@orangecheck/agent-core 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "1.1.0",
+  "version": "2.0.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",
@@ -64,14 +64,14 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@orangecheck/stamp-core": "^1.0.0",
-    "@orangecheck/lock-core": "^1.0.1"
+    "@orangecheck/lock-core": "^1.0.1",
+    "@orangecheck/stamp-core": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"

package/src/assert-scope.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import { ScopeNotGrantedError, assertScopeGranted } from './assert-scope.js';
+import type { ScopesEncryptedEnvelope } from './types.js';
+
+const SEALED = {
+    v: 1,
+    alg: 'x25519-xchacha20poly1305',
+    recipients: [{ device_id: 'dev1', ct: 'AA' }],
+    ct: 'BB',
+    nonce: 'CC',
+} as unknown as ScopesEncryptedEnvelope;
+
+function reasonOf(fn: () => void): string {
+    try {
+        fn();
+    } catch (e) {
+        return e instanceof ScopeNotGrantedError ? e.reason : `wrong-error:${String(e)}`;
+    }
+    return 'no-throw';
+}
+
+describe('assertScopeGranted', () => {
+    it('permits an exact grant and a sub-scope of one', () => {
+        expect(() =>
+            assertScopeGranted({ scopes: ['mcp:invoke(server=s,tool=t)'] }, 'mcp:invoke(server=s,tool=t)', 'f')
+        ).not.toThrow();
+        expect(() =>
+            assertScopeGranted({ scopes: ['mcp:invoke(server=s)'] }, 'mcp:invoke(server=s,tool=t)', 'f')
+        ).not.toThrow();
+    });
+
+    it('refuses a scope outside the grant', () => {
+        expect(
+            reasonOf(() => assertScopeGranted({ scopes: ['mcp:invoke(server=a)'] }, 'mcp:invoke(server=b)', 'f'))
+        ).toBe('not_subscope');
+    });
+
+    // The whole reason this module exists. Five adapters open-coded
+    // `(scopes ?? []).map(parseScope)`, so a v1.2 private delegation — where
+    // `scopes` is absent BECAUSE it is sealed — reported "not a sub-scope of
+    // any granted scope". The refusal was right; the diagnosis sent the
+    // integrator to audit a scope string that was very possibly correct.
+    it('names encrypted scopes as such rather than blaming the scope string', () => {
+        const d = { scopes_encrypted: SEALED };
+        expect(reasonOf(() => assertScopeGranted(d, 'mcp:invoke(server=s)', 'f'))).toBe('scopes_encrypted');
+        try {
+            assertScopeGranted(d, 'mcp:invoke(server=s)', 'f');
+        } catch (e) {
+            expect((e as Error).message).toMatch(/decryptPrivateScopes/);
+            expect((e as Error).message).not.toMatch(/not a sub-scope/);
+        }
+    });
+
+    it('treats absent and empty scopes as granting nothing, not everything', () => {
+        expect(reasonOf(() => assertScopeGranted({}, 'x:y', 'f'))).toBe('no_scopes');
+        expect(reasonOf(() => assertScopeGranted({ scopes: [] }, 'x:y', 'f'))).toBe('no_scopes');
+    });
+
+    // A sealed delegation that ALSO carries a scopes array must not be
+    // evaluated against that array: the fields are exclusive per the spec, so
+    // a populated `scopes` alongside `scopes_encrypted` is a malformed
+    // envelope and possibly an attempt to present a benign readable grant
+    // while the real one stays hidden.
+    it('refuses on the sealed field even when a scopes array is also present', () => {
+        expect(
+            reasonOf(() =>
+                assertScopeGranted({ scopes: ['x:y'], scopes_encrypted: SEALED }, 'x:y', 'f')
+            )
+        ).toBe('scopes_encrypted');
+    });
+});

package/src/assert-scope.ts

@@ -0,0 +1,80 @@
+import { hasPrivateScopes } from './private-scope.js';
+import { isSubScope, parseScope } from './scope.js';
+import type { ScopesEncryptedEnvelope } from './types.js';
+
+/**
+ * The minimum an adapter needs to make the authorization decision. Kept
+ * structural rather than importing `Delegation` so `stampX` helpers can accept
+ * the narrower shapes they already declare.
+ */
+export interface ScopeBearingDelegation {
+    scopes?: string[];
+    scopes_encrypted?: ScopesEncryptedEnvelope;
+}
+
+/** Distinguishes the three reasons a stamp can be refused. */
+export class ScopeNotGrantedError extends Error {
+    readonly reason: 'not_subscope' | 'scopes_encrypted' | 'no_scopes';
+    constructor(reason: ScopeNotGrantedError['reason'], message: string) {
+        super(message);
+        this.name = 'ScopeNotGrantedError';
+        this.reason = reason;
+    }
+}
+
+/**
+ * Refuse unless `scopeExercised` is a sub-scope of something the delegation
+ * actually grants. Every `agent-*` adapter's pre-flight check routes here.
+ *
+ * The check itself is unchanged and still fails closed. What this adds is
+ * telling the caller WHICH of three things went wrong, because the five
+ * adapters each open-coded `(delegation.scopes ?? []).map(parseScope)` and so
+ * reported all three as the same thing:
+ *
+ * - **not_subscope** — scopes are readable and this one is not among them.
+ *   The integrator's own mistake, and the only case the old message fit.
+ * - **scopes_encrypted** — v1.2 private mode. `scopes` is absent *because it
+ *   is sealed to a device key*, so the adapter cannot evaluate the request at
+ *   all. `?? []` collapsed this into "not a sub-scope of any granted scope",
+ *   which sends the integrator to audit a scope string that may well be
+ *   correct, when what they need is `decryptPrivateScopes` and to pass the
+ *   recovered list. Refusing is right; misnaming why is not.
+ * - **no_scopes** — neither field present. A delegation granting nothing.
+ *
+ * Fail-closed is not a judgement call here: an over-broad stamp is a signed,
+ * content-addressed authorization artifact that a verifier will accept.
+ */
+export function assertScopeGranted(
+    delegation: ScopeBearingDelegation,
+    scopeExercised: string,
+    fnName: string
+): void {
+    if (hasPrivateScopes(delegation)) {
+        throw new ScopeNotGrantedError(
+            'scopes_encrypted',
+            `${fnName}: this delegation uses v1.2 private scopes — \`scopes_encrypted\` is ` +
+                `set and \`scopes\` is absent, so the granted set cannot be read here. ` +
+                `Decrypt it with decryptPrivateScopes() using a matching device key and pass ` +
+                `the recovered scopes as \`delegation.scopes\`. Refusing to stamp ` +
+                `\`${scopeExercised}\` against an unreadable grant.`
+        );
+    }
+
+    const scopes = delegation.scopes;
+    if (scopes === undefined || scopes.length === 0) {
+        throw new ScopeNotGrantedError(
+            'no_scopes',
+            `${fnName}: delegation grants no scopes, so \`${scopeExercised}\` cannot be ` +
+                `exercised. An absent or empty \`scopes\` means nothing is granted, never everything.`
+        );
+    }
+
+    const exercised = parseScope(scopeExercised);
+    if (!scopes.map(parseScope).some((g) => isSubScope(exercised, g))) {
+        throw new ScopeNotGrantedError(
+            'not_subscope',
+            `${fnName}: scope_exercised (${scopeExercised}) is not a sub-scope of any granted ` +
+                `scope (${scopes.join(', ')})`
+        );
+    }
+}

package/src/federation.test.ts

@@ -81,6 +81,7 @@ d('federation delegation vectors (v19–v24, v26)', () => {
                           ...opts,
                       })
                     : await verifyDelegation({
+                    skipRevocationCheck: true,
                           envelope: env as DelegationEnvelope,
                           skipSignatureVerification: true,
                           skipTemporalCheck: true,

package/src/index.ts

@@ -79,3 +79,6 @@ export type {
     UnsealScopesInput,
     UnsealedScopes,
 } from './private-scope.js';
+
+export { assertScopeGranted, ScopeNotGrantedError } from './assert-scope.js';
+export type { ScopeBearingDelegation } from './assert-scope.js';

package/src/private-scope.test.ts

@@ -118,7 +118,7 @@ describe('verifyDelegation with v1.2 scopes_encrypted', () => {
         const env = await buildPrivateEnvelope(['ln:send(max_sats<=100)']);
         // Inject a public scopes field too — illegal.
         const both = { ...env, scopes: ['ln:send(max_sats<=100)'] } as DelegationEnvelope;
-        const r = await verifyDelegation({ envelope: both, skipSignatureVerification: true });
+        const r = await verifyDelegation({ envelope: both, skipSignatureVerification: true, skipRevocationCheck: true });
         expect(r.ok).toBe(false);
         if (!r.ok) expect(r.code).toBe('E_SCOPES_BOTH_PROVIDED');
     });
@@ -127,14 +127,14 @@ describe('verifyDelegation with v1.2 scopes_encrypted', () => {
         const env = await buildPrivateEnvelope(['ln:send(max_sats<=100)']);
         const neither = { ...env } as DelegationEnvelope;
         delete neither.scopes_encrypted;
-        const r = await verifyDelegation({ envelope: neither, skipSignatureVerification: true });
+        const r = await verifyDelegation({ envelope: neither, skipSignatureVerification: true, skipRevocationCheck: true });
         expect(r.ok).toBe(false);
         if (!r.ok) expect(r.code).toBe('E_SCOPES_NEITHER_PROVIDED');
     });
 
     it('returns E_SCOPES_UNREADABLE when no decryption key is supplied', async () => {
         const env = await buildPrivateEnvelope(['ln:send(max_sats<=100)']);
-        const r = await verifyDelegation({ envelope: env, skipSignatureVerification: true });
+        const r = await verifyDelegation({ envelope: env, skipSignatureVerification: true, skipRevocationCheck: true });
         expect(r.ok).toBe(false);
         if (!r.ok) expect(r.code).toBe('E_SCOPES_UNREADABLE');
     });
@@ -144,6 +144,7 @@ describe('verifyDelegation with v1.2 scopes_encrypted', () => {
             'ln:send(max_sats<=100)',
         ]);
         const r = await verifyDelegation({
+                    skipRevocationCheck: true,
             envelope,
             skipSignatureVerification: true,
             decryptScopesWith: { device_id: 'agent', secretKey: agentSecret },

package/src/revocation-failclosed.test.ts

@@ -0,0 +1,67 @@
+// SECURITY §7 item 7: "Query revocation feeds (Nostr kind-30085 by
+// `#delegation`) for the cited delegation id before reporting OK, **unless the
+// caller explicitly opts out** of revocation checking."
+//
+// The default was inverted. verifyDelegation had NO revocations parameter at
+// all — a revoked delegation returned ok:true and a caller had no way to say
+// otherwise. verifyAction accepted one but checked only `if (input.revocations
+// && length > 0)`, so omitting it skipped the check silently and "checked,
+// clean" was indistinguishable from "never checked".
+//
+// This library has no network by design, so the caller fetches the feed. What
+// changed is that declining to is now a decision they have to state.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { verifyDelegation } from './verify.js';
+import type { DelegationEnvelope } from './types.js';
+
+const vectors = join(dirname(fileURLToPath(import.meta.url)), '../../../oc-agent-protocol/test-vectors');
+const delegation = JSON.parse(
+    readFileSync(join(vectors, 'v01-delegation-minimal.json'), 'utf8'),
+).expected.envelope as DelegationEnvelope;
+
+const AT = new Date('2026-04-23T12:00:00Z'); // inside the delegation's window
+
+describe('verifyDelegation fails closed on revocation', () => {
+    it('refuses when given neither revocations nor an explicit skip', async () => {
+        const r = await verifyDelegation({
+            envelope: delegation,
+            skipSignatureVerification: true,
+            now: AT,
+        });
+        expect(r.ok).toBe(false);
+        expect(r.ok === false && r.code).toBe('E_MALFORMED');
+        expect(r.ok === false && r.message).toMatch(/requires `revocations`/i);
+    });
+
+    it('accepts an EMPTY revocation list — "I looked, there were none"', async () => {
+        const r = await verifyDelegation({
+            envelope: delegation,
+            skipSignatureVerification: true,
+            now: AT,
+            revocations: [],
+        });
+        expect(r.ok).toBe(true);
+    });
+
+    it('accepts an explicit skip, for callers that genuinely cannot check', async () => {
+        const r = await verifyDelegation({
+            envelope: delegation,
+            skipSignatureVerification: true,
+            now: AT,
+            skipRevocationCheck: true,
+        });
+        expect(r.ok).toBe(true);
+    });
+
+    // An empty list and a skip both verify — but they mean different things, and
+    // only one of them is a claim about the feed. That distinction is the point
+    // of the change.
+    it('the two are not the same statement', () => {
+        expect('revocations: []').not.toBe('skipRevocationCheck: true');
+    });
+});

package/src/test-vectors.test.ts

@@ -262,6 +262,7 @@ describe('oc-agent-protocol test vectors', () => {
         it(`${name} — declared envelope passes verify() with skipSignatureVerification`, async () => {
             if (data.kind === 'delegation') {
                 const r = await verifyDelegation({
+                    skipRevocationCheck: true,
                     envelope: data.expected.envelope,
                     skipSignatureVerification: true,
                     skipTemporalCheck: true,
@@ -273,6 +274,7 @@ describe('oc-agent-protocol test vectors', () => {
                     throw new Error(`action vector ${name} references missing delegation ${data.inputs.delegation_id}`);
                 }
                 const r = await verifyAction({
+                    skipRevocationCheck: true,
                     action: data.expected.envelope,
                     delegation,
                     skipSignatureVerification: true,
@@ -454,6 +456,7 @@ describe('oc-agent-protocol negative test vectors', () => {
                     sig: { alg: 'bip322', pubkey: v.inputs.address, value: 'AAAA' },
                 };
                 const r = await verifyAction({
+                    skipRevocationCheck: true,
                     action,
                     delegation,
                     skipSignatureVerification: true,
@@ -704,6 +707,7 @@ describe('oc-agent-protocol private-scope vectors (v1.2)', () => {
                     );
                 }
                 const r = await verifyDelegation({
+                    skipRevocationCheck: true,
                     envelope: env,
                     skipSignatureVerification: true,
                     skipTemporalCheck: true,
@@ -721,6 +725,7 @@ describe('oc-agent-protocol private-scope vectors (v1.2)', () => {
             } else {
                 const negative = data as PrivateScopeNegativeVector;
                 const r = await verifyDelegation({
+                    skipRevocationCheck: true,
                     envelope: env,
                     skipSignatureVerification: true,
                     skipTemporalCheck: true,

package/src/verify.ts

@@ -48,6 +48,24 @@ export interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
     scopeMode?: ValidationOptions['mode'];
+    /**
+     * Verify WITHOUT consulting revocation feeds. Required to be explicit.
+     *
+     * SECURITY §7 item 7: "Query revocation feeds (Nostr kind-30085 by
+     * `#delegation`) for the cited delegation id before reporting OK, **unless
+     * the caller explicitly opts out**." The default was inverted — revocations
+     * were checked only when supplied, and omitting them skipped the check
+     * silently, so "checked, clean" was indistinguishable from "never checked".
+     *
+     * This library has no network by design, so the caller fetches the feed and
+     * passes `revocations`. Declining to is a decision they must state.
+     */
+    skipRevocationCheck?: boolean;
+    /**
+     * Revocations to evaluate against the delegation (or, for an action, every
+     * link in its chain). Fetch these from kind-30085 by `#delegation`.
+     */
+    revocations?: RevocationEnvelope[];
 }
 
 export class AgentError extends Error {
@@ -204,6 +222,31 @@ export async function verifyDelegation(input: VerifyDelegationInput): Promise<Ve
         if (!ok) return err('E_BAD_SIG', 'BIP-322 signature did not verify');
     }
 
+    // Revocation. SECURITY §7 item 7 — check unless the caller states otherwise.
+    // Before this, verifyDelegation had NO revocations parameter at all: a
+    // revoked delegation returned ok:true and a caller had no way to say
+    // otherwise.
+    if (!input.skipRevocationCheck && !input.revocations) {
+        return err(
+            'E_MALFORMED',
+            'verifyDelegation requires `revocations` (fetch kind-30085 by #delegation) or an ' +
+                'explicit skipRevocationCheck:true to state that revocation is not being checked',
+        );
+    }
+    if (input.revocations) {
+        for (const rev of input.revocations) {
+            if (rev.delegation_id !== env.id) continue;
+            const rr = await verifyRevocation({
+                envelope: rev,
+                delegation: env,
+                verifyBip322: input.verifyBip322,
+                skipSignatureVerification: input.skipSignatureVerification,
+            });
+            if (!rr.ok) continue; // a malformed revocation revokes nothing
+            return err('E_REVOKED', `delegation ${env.id} was revoked by ${rev.id}`);
+        }
+    }
+
     // Temporal.
     if (!input.skipTemporalCheck) {
         const now = input.now ?? new Date();
@@ -254,12 +297,6 @@ export interface VerifyActionInput extends VerifyBase {
      * E_SUBDELEGATION_DEPTH_EXCEEDED before any per-link work is performed.
      */
     maxChainDepth?: number;
-    /**
-     * Known revocations targeting any envelope in the chain (root + each
-     * subdelegation). The verifier checks every link per SUB-DELEGATION.md §2.2
-     * step 5 — a revocation against ANY link invalidates the action.
-     */
-    revocations?: RevocationEnvelope[];
     content?: Uint8Array;
     verifyOtsAnchor?: (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
     /** If action and revocation are both OTS-anchored, pass a function that returns the comparable block height of each via proof parsing. Defaults: use envelope.ots.block_height. */
@@ -301,6 +338,12 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         skipSignatureVerification: input.skipSignatureVerification,
         scopeMode: input.scopeMode,
         skipTemporalCheck: true, // action window check dominates
+        // Revocation is evaluated ONCE, below, across every link in the chain
+        // (root + subdelegations) against the action's effective time — a
+        // per-link check here would use the wrong clock and would also
+        // double-report. Forward the caller's decision so this inner call does
+        // not trip the fail-closed guard.
+        skipRevocationCheck: true,
         ...(input.decryptScopesWith ? { decryptScopesWith: input.decryptScopesWith } : {}),
     });
     if (!dr.ok) return dr;
@@ -395,6 +438,13 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
     // 6. Revocation check — applies per-link to ALL envelopes in the chain
     //    (root + every subdelegation). Per SUB-DELEGATION.md §2.2 step 5, a
     //    revocation against ANY link invalidates the action.
+    if (!input.skipRevocationCheck && !input.revocations) {
+        return err(
+            'E_MALFORMED',
+            'verifyAction requires `revocations` (fetch kind-30085 by #delegation for every link ' +
+                'in the chain) or an explicit skipRevocationCheck:true',
+        );
+    }
     if (input.revocations && input.revocations.length > 0) {
         const allLinks: ChainLink[] = [rootHydrated, ...hydratedChain];
         for (const link of allLinks) {