@orangecheck/agent-core 0.1.0

package/package.json

@@ -0,0 +1,75 @@
+{
+    "name": "@orangecheck/agent-core",
+    "version": "0.1.0",
+    "description": "OC Agent canonical messages, envelope formats (delegation/action/revocation), scope grammar, and verification. See https://github.com/orangecheck/oc-agent-protocol.",
+    "keywords": [
+        "bitcoin",
+        "agent",
+        "authority",
+        "delegation",
+        "bip322",
+        "oc-agent",
+        "orangecheck"
+    ],
+    "author": "OrangeCheck",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/orangecheck/oc-packages.git",
+        "directory": "agent-core"
+    },
+    "homepage": "https://github.com/orangecheck/oc-agent-protocol",
+    "bugs": {
+        "url": "https://github.com/orangecheck/oc-agent-protocol/issues"
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./canonical": {
+            "types": "./dist/canonical.d.ts",
+            "import": "./dist/canonical.mjs",
+            "require": "./dist/canonical.js"
+        },
+        "./scope": {
+            "types": "./dist/scope.d.ts",
+            "import": "./dist/scope.mjs",
+            "require": "./dist/scope.js"
+        },
+        "./types": {
+            "types": "./dist/types.d.ts",
+            "import": "./dist/types.mjs",
+            "require": "./dist/types.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "dependencies": {
+        "@noble/hashes": "^1.5.0",
+        "@orangecheck/stamp-core": "^0.1.1"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vitest": "^3.2.4"
+    }
+}

package/src/canonical.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    actionCanonicalMessage,
+    canonicalizeScopes,
+    computeActionId,
+    computeDelegationId,
+    computeRevocationId,
+    delegationCanonicalMessage,
+    revocationCanonicalMessage,
+} from './canonical.js';
+
+describe('delegation canonical message', () => {
+    it('sorts scopes lexicographically and serializes fields LF-terminated', () => {
+        const msg = delegationCanonicalMessage({
+            principal: 'bc1qprincipal',
+            agent: 'bc1qagent',
+            scopes: canonicalizeScopes(['stamp:sign(mime=text/markdown)', 'lock:seal(recipient=bc1qalice)']),
+            bond_sats: 0,
+            bond_attestation: 'none',
+            issued_at: '2026-04-22T12:00:00Z',
+            expires_at: '2026-04-29T12:00:00Z',
+            nonce: '0123456789abcdef0123456789abcdef',
+        });
+        expect(msg.startsWith('oc-agent:delegation:v1\n')).toBe(true);
+        expect(msg).toContain('scopes: lock:seal(recipient=bc1qalice),stamp:sign(mime=text/markdown)');
+        expect(msg.endsWith('\n')).toBe(false);
+    });
+
+    it('produces a deterministic id across identical inputs', () => {
+        const input = {
+            principal: 'bc1qprincipal000000000000000000000000000000',
+            agent: 'bc1qagent0000000000000000000000000000000000',
+            scopes: ['lock:seal(recipient=bc1qalice000000000000000000000000000000000)'],
+            bond_sats: 0,
+            bond_attestation: 'none',
+            issued_at: '2026-04-22T12:00:00Z',
+            expires_at: '2026-04-29T12:00:00Z',
+            nonce: '0123456789abcdef0123456789abcdef',
+        };
+        const id1 = computeDelegationId(input);
+        const id2 = computeDelegationId(input);
+        expect(id1).toBe(id2);
+        expect(id1).toMatch(/^[0-9a-f]{64}$/);
+    });
+});
+
+describe('action canonical message', () => {
+    it('includes delegation_id and scope_exercised on extra lines', () => {
+        const msg = actionCanonicalMessage({
+            address: 'bc1qagent',
+            content_hash: 'sha256:' + '3'.repeat(64),
+            content_length: 1024,
+            content_mime: 'application/vnd.oc-lock+json',
+            signed_at: '2026-04-22T12:05:00Z',
+            delegation_id: 'a'.repeat(64),
+            scope_exercised: 'lock:seal(recipient=bc1qalice)',
+        });
+        expect(msg.startsWith('oc-agent:action:v1\n')).toBe(true);
+        expect(msg).toContain('delegation_id: ' + 'a'.repeat(64));
+        expect(msg).toContain('scope_exercised: lock:seal(recipient=bc1qalice)');
+    });
+
+    it('id is computable', () => {
+        const id = computeActionId({
+            address: 'bc1qagent',
+            content_hash: 'sha256:' + '3'.repeat(64),
+            content_length: 1,
+            content_mime: 'text/plain',
+            signed_at: '2026-04-22T12:05:00Z',
+            delegation_id: 'a'.repeat(64),
+            scope_exercised: 'lock:seal(recipient=bc1qalice)',
+        });
+        expect(id).toMatch(/^[0-9a-f]{64}$/);
+    });
+});
+
+describe('revocation canonical message', () => {
+    it('serializes empty reason as a blank line value', () => {
+        const msg = revocationCanonicalMessage({
+            address: 'bc1qprincipal',
+            delegation_id: 'a'.repeat(64),
+            reason: '',
+            signed_at: '2026-04-22T14:00:00Z',
+        });
+        expect(msg).toContain('\nreason: \n');
+        const id = computeRevocationId({
+            address: 'bc1qprincipal',
+            delegation_id: 'a'.repeat(64),
+            reason: '',
+            signed_at: '2026-04-22T14:00:00Z',
+        });
+        expect(id).toMatch(/^[0-9a-f]{64}$/);
+    });
+});

package/src/canonical.ts

@@ -0,0 +1,155 @@
+// Canonical messages + envelope canonicalization for OC Agent. SPEC §4.1, §5.1, §9.1.
+//
+// Three canonical-message builders live here — one per envelope kind. Each one
+// produces the exact byte sequence a signer signs via BIP-322 and the hash
+// input for the envelope id.
+//
+// The RFC 8785 JSON canonicalizer and hex utilities are re-exported from
+// @orangecheck/stamp-core so OC Agent and OC Stamp are guaranteed to produce
+// identical bytes for identical structural inputs.
+
+import { sha256 } from '@noble/hashes/sha256';
+import { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
+
+import { canonicalizeScope, parseScope, type Scope } from './scope.js';
+import type {
+    ActionCanonicalInput,
+    ActionEnvelope,
+    DelegationCanonicalInput,
+    DelegationEnvelope,
+    RevocationCanonicalInput,
+    RevocationEnvelope,
+} from './types.js';
+
+export { canonicalize, hexEncode };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scope sorting + serialization
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonicalize and sort a list of scope strings for the delegation canonical
+ * message. Each scope is first parsed, then re-emitted in canonical form
+ * (constraints sorted by key), and the whole list is sorted lexicographically.
+ */
+export function canonicalizeScopes(scopes: string[]): string[] {
+    const canonical = scopes.map((s) => canonicalizeScope(parseScope(s)));
+    return [...canonical].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * Same as `canonicalizeScopes` but returns `Scope` objects too, for callers
+ * that need them.
+ */
+export function parseAndCanonicalizeScopes(scopes: string[]): { canonical: string[]; parsed: Scope[] } {
+    const parsed = scopes.map(parseScope);
+    const canonicalStrings = parsed.map(canonicalizeScope);
+    const indexed = canonicalStrings.map((s, i) => ({ s, p: parsed[i]! }));
+    indexed.sort((a, b) => (a.s < b.s ? -1 : a.s > b.s ? 1 : 0));
+    return {
+        canonical: indexed.map((x) => x.s),
+        parsed: indexed.map((x) => x.p),
+    };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Canonical messages (SPEC §4.1, §5.1, §9.1)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function delegationCanonicalMessage(input: DelegationCanonicalInput): string {
+    const scopeField = input.scopes.join(',');
+    return [
+        'oc-agent:delegation:v1',
+        `principal: ${input.principal}`,
+        `agent: ${input.agent}`,
+        `scopes: ${scopeField}`,
+        `bond_sats: ${input.bond_sats}`,
+        `bond_attestation: ${input.bond_attestation}`,
+        `issued_at: ${input.issued_at}`,
+        `expires_at: ${input.expires_at}`,
+        `nonce: ${input.nonce}`,
+    ].join('\n');
+}
+
+export function actionCanonicalMessage(input: ActionCanonicalInput): string {
+    return [
+        'oc-agent:action:v1',
+        `address: ${input.address}`,
+        `content_hash: ${input.content_hash}`,
+        `content_length: ${input.content_length}`,
+        `content_mime: ${input.content_mime}`,
+        `signed_at: ${input.signed_at}`,
+        `delegation_id: ${input.delegation_id}`,
+        `scope_exercised: ${input.scope_exercised}`,
+    ].join('\n');
+}
+
+export function revocationCanonicalMessage(input: RevocationCanonicalInput): string {
+    return [
+        'oc-agent:revocation:v1',
+        `address: ${input.address}`,
+        `delegation_id: ${input.delegation_id}`,
+        `reason: ${input.reason}`,
+        `signed_at: ${input.signed_at}`,
+    ].join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bytes + ids
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function delegationCanonicalBytes(input: DelegationCanonicalInput): Uint8Array {
+    return new TextEncoder().encode(delegationCanonicalMessage(input));
+}
+
+export function actionCanonicalBytes(input: ActionCanonicalInput): Uint8Array {
+    return new TextEncoder().encode(actionCanonicalMessage(input));
+}
+
+export function revocationCanonicalBytes(input: RevocationCanonicalInput): Uint8Array {
+    return new TextEncoder().encode(revocationCanonicalMessage(input));
+}
+
+export function computeDelegationId(input: DelegationCanonicalInput): string {
+    return hexEncode(sha256(delegationCanonicalBytes(input)));
+}
+
+export function computeActionId(input: ActionCanonicalInput): string {
+    return hexEncode(sha256(actionCanonicalBytes(input)));
+}
+
+export function computeRevocationId(input: RevocationCanonicalInput): string {
+    return hexEncode(sha256(revocationCanonicalBytes(input)));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Envelope canonicalization (SPEC §6; RFC 8785 + scope-sorting)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function canonicalizeDelegation(env: DelegationEnvelope): string {
+    return canonicalize(env as unknown as Parameters<typeof canonicalize>[0]);
+}
+
+export function canonicalizeAction(env: ActionEnvelope): string {
+    return canonicalize(env as unknown as Parameters<typeof canonicalize>[0]);
+}
+
+export function canonicalizeRevocation(env: RevocationEnvelope): string {
+    return canonicalize(env as unknown as Parameters<typeof canonicalize>[0]);
+}
+
+export function canonicalDelegationBytes(env: DelegationEnvelope): Uint8Array {
+    return new TextEncoder().encode(canonicalizeDelegation(env) + '\n');
+}
+
+export function canonicalActionBytes(env: ActionEnvelope): Uint8Array {
+    return new TextEncoder().encode(canonicalizeAction(env) + '\n');
+}
+
+export function canonicalRevocationBytes(env: RevocationEnvelope): Uint8Array {
+    return new TextEncoder().encode(canonicalizeRevocation(env) + '\n');
+}
+
+export function sha256Hex(bytes: Uint8Array): string {
+    return hexEncode(sha256(bytes));
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export * from './types.js';
+export {
+    canonicalize,
+    hexEncode,
+    sha256Hex,
+    canonicalizeScopes,
+    parseAndCanonicalizeScopes,
+    delegationCanonicalMessage,
+    actionCanonicalMessage,
+    revocationCanonicalMessage,
+    delegationCanonicalBytes,
+    actionCanonicalBytes,
+    revocationCanonicalBytes,
+    computeDelegationId,
+    computeActionId,
+    computeRevocationId,
+    canonicalizeDelegation,
+    canonicalizeAction,
+    canonicalizeRevocation,
+    canonicalDelegationBytes,
+    canonicalActionBytes,
+    canonicalRevocationBytes,
+} from './canonical.js';
+export {
+    parseScope,
+    canonicalizeScope,
+    canonicalizeScopeString,
+    validateScope,
+    isSubScope,
+    ScopeParseError,
+    REGISTERED_SCOPES,
+} from './scope.js';
+export type { Scope, ScopeConstraint, ScopeOp, ValidationOptions } from './scope.js';
+export {
+    verifyDelegation,
+    verifyAction,
+    verifyRevocation,
+    AgentError,
+} from './verify.js';
+export type {
+    VerifyBase,
+    VerifyDelegationInput,
+    VerifyActionInput,
+    VerifyRevocationInput,
+} from './verify.js';

package/src/scope.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    canonicalizeScope,
+    canonicalizeScopeString,
+    isSubScope,
+    parseScope,
+    ScopeParseError,
+    validateScope,
+} from './scope.js';
+
+describe('parseScope', () => {
+    it('parses a bare product:verb scope', () => {
+        const s = parseScope('nostr:publish');
+        expect(s.product).toBe('nostr');
+        expect(s.verb).toBe('publish');
+        expect(s.constraints).toHaveLength(0);
+    });
+
+    it('parses constraints with =, !=, <=, >=', () => {
+        const s = parseScope('ln:send(max_sats<=1000,node=03abc,max_fee_sats<=10)');
+        expect(s.constraints).toHaveLength(3);
+        expect(s.constraints.find((c) => c.key === 'max_sats')?.op).toBe('<=');
+        expect(s.constraints.find((c) => c.key === 'node')?.op).toBe('=');
+    });
+
+    it('accepts a wildcard constraint', () => {
+        const s = parseScope('http:request(origin=*)');
+        expect(s.constraints[0]?.op).toBe('*');
+    });
+
+    it('rejects whitespace', () => {
+        expect(() => parseScope('lock:seal (recipient=bc)')).toThrow(ScopeParseError);
+    });
+
+    it('rejects duplicate keys', () => {
+        expect(() => parseScope('ln:send(max_sats=1,max_sats=2)')).toThrow(ScopeParseError);
+    });
+
+    it('parses quoted values', () => {
+        const s = parseScope('http:request(origin="https://a.example,b")');
+        expect(s.constraints[0]?.value).toBe('https://a.example,b');
+        expect(s.constraints[0]?.quoted).toBe(true);
+    });
+});
+
+describe('canonicalize', () => {
+    it('sorts constraints by key', () => {
+        expect(canonicalizeScopeString('ln:send(node=03abc,max_sats<=1000)')).toBe(
+            'ln:send(max_sats<=1000,node=03abc)'
+        );
+    });
+
+    it('canonicalizes a no-constraint scope', () => {
+        expect(canonicalizeScopeString('stamp:sign')).toBe('stamp:sign');
+    });
+
+    it('round-trips quoted values', () => {
+        expect(canonicalizeScopeString('http:request(origin="a,b")')).toBe(
+            'http:request(origin="a,b")'
+        );
+    });
+});
+
+describe('validateScope', () => {
+    it('strict mode rejects unregistered product', () => {
+        expect(() => validateScope(parseScope('xxx:yyy'))).toThrow(ScopeParseError);
+    });
+
+    it('strict mode rejects unregistered constraint key', () => {
+        expect(() => validateScope(parseScope('lock:seal(zzz=1)'))).toThrow(ScopeParseError);
+    });
+
+    it('permissive mode accepts unregistered product/key', () => {
+        expect(() =>
+            validateScope(parseScope('xxx:yyy(foo=1)'), { mode: 'permissive' })
+        ).not.toThrow();
+    });
+});
+
+describe('isSubScope (SPEC §7.4)', () => {
+    const cs = (s: string) => canonicalizeScope(parseScope(s));
+    void cs;
+
+    it('accepts exact match', () => {
+        expect(
+            isSubScope(
+                parseScope('lock:seal(recipient=bc1qalice)'),
+                parseScope('lock:seal(recipient=bc1qalice)')
+            )
+        ).toBe(true);
+    });
+
+    it('rejects different value under =', () => {
+        expect(
+            isSubScope(
+                parseScope('stamp:sign(mime=application/pdf)'),
+                parseScope('stamp:sign(mime=text/markdown)')
+            )
+        ).toBe(false);
+    });
+
+    it('accepts tighter numeric range', () => {
+        expect(
+            isSubScope(
+                parseScope('ln:send(max_sats=500,node=03abc,max_fee_sats=5)'),
+                parseScope('ln:send(max_sats<=1000,node=03abc,max_fee_sats<=10)')
+            )
+        ).toBe(true);
+    });
+
+    it('rejects wider numeric range', () => {
+        expect(
+            isSubScope(
+                parseScope('ln:send(max_sats=5000)'),
+                parseScope('ln:send(max_sats<=1000)')
+            )
+        ).toBe(false);
+    });
+
+    it('wildcard grants admit anything', () => {
+        expect(
+            isSubScope(
+                parseScope('http:request(origin=https://evil.com)'),
+                parseScope('http:request(origin=*)')
+            )
+        ).toBe(true);
+    });
+
+    it('exercised may add keys not in granted', () => {
+        expect(
+            isSubScope(
+                parseScope('ln:send(max_sats=500,node=03abc,max_fee_sats=5)'),
+                parseScope('ln:send(max_sats<=1000)')
+            )
+        ).toBe(true);
+    });
+
+    it('rejects mismatched product or verb', () => {
+        expect(
+            isSubScope(parseScope('lock:chat'), parseScope('lock:seal'))
+        ).toBe(false);
+    });
+
+    it('accepts != with admissible value', () => {
+        expect(
+            isSubScope(
+                parseScope('http:request(method=GET)'),
+                parseScope('http:request(method!=POST)')
+            )
+        ).toBe(true);
+    });
+
+    it('rejects != with disallowed value', () => {
+        expect(
+            isSubScope(
+                parseScope('http:request(method=POST)'),
+                parseScope('http:request(method!=POST)')
+            )
+        ).toBe(false);
+    });
+});