@orangecheck/agent-core 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "2.1.0",
+  "version": "2.2.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",

package/src/federation.test.ts

@@ -97,13 +97,39 @@ d('federation delegation vectors (v19–v24, v26)', () => {
 d('federation revocation (v25)', () => {
     it('3-of-5 threshold met → valid', async () => {
         const v = await load('v25-federation-revocation-3of5-valid.json');
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
         const result = await verifyFederationRevocation({
             envelope: v.expected.envelope as FederationRevocationEnvelope,
+            delegation: dv.expected.envelope as FederationDelegationEnvelope,
             skipSignatureVerification: true,
         });
         expect(result.ok).toBe(true);
         if (result.ok) expect(result.id).toBe(v.expected.envelope.id);
     });
+
+    it('is bound to the delegation it revokes and to that delegation\'s federation', async () => {
+        const v = await load('v25-federation-revocation-3of5-valid.json');
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const rev = v.expected.envelope as FederationRevocationEnvelope;
+        const del = dv.expected.envelope as FederationDelegationEnvelope;
+        const otherDelegation = await verifyFederationRevocation({
+            envelope: rev,
+            delegation: { ...del, id: 'f'.repeat(64) },
+            skipSignatureVerification: true,
+        });
+        expect(otherDelegation.ok === false && otherDelegation.code).toBe('E_DELEGATION_MISMATCH');
+        const otherFederation = await verifyFederationRevocation({
+            envelope: rev,
+            delegation: { ...del, principal: { ...del.principal, descriptor_id: 'e'.repeat(64) } },
+            skipSignatureVerification: true,
+        });
+        expect(otherFederation.ok === false && otherFederation.code).toBe('E_REVOKER_UNAUTHORIZED');
+        const missing = await verifyFederationRevocation({
+            envelope: rev,
+            skipSignatureVerification: true,
+        } as Parameters<typeof verifyFederationRevocation>[0]);
+        expect(missing.ok).toBe(false);
+    });
 });
 
 d('federation reject reasons (each invalid case fails for its named reason)', () => {

package/src/federation.ts

@@ -291,6 +291,8 @@ export async function verifyFederationDelegation(
 
 export interface VerifyFederationRevocationInput extends VerifyFederationBase {
     envelope: FederationRevocationEnvelope;
+    /** The delegation being revoked. Its federation is the one that may revoke it. */
+    delegation: FederationDelegationEnvelope;
 }
 
 export async function verifyFederationRevocation(
@@ -305,6 +307,18 @@ export async function verifyFederationRevocation(
     }
     if (!ISO_UTC.test(env.signed_at)) return fail('E_MALFORMED', 'signed_at must be ISO 8601 UTC');
 
+    const d = input.delegation;
+    if (!d || !HEX64.test(d.id ?? '')) return fail('E_MALFORMED', 'the revoked delegation is required');
+    if (env.delegation_id !== d.id) {
+        return fail('E_DELEGATION_MISMATCH', `revocation.delegation_id (${env.delegation_id}) != delegation.id (${d.id})`);
+    }
+    if (d.principal?.alg !== 'federation' || env.signer?.descriptor_id !== d.principal.descriptor_id) {
+        return fail(
+            'E_REVOKER_UNAUTHORIZED',
+            `revoking federation (${env.signer?.descriptor_id}) is not the delegation's principal`
+        );
+    }
+
     // §4 — the `address:` line carries the `federation:<descriptor_id>`
     // substitution; everything else is the v1 revocation canonical message.
     const canonInput = {

package/src/revocation-authority.test.ts

@@ -0,0 +1,258 @@
+// SPEC §9.5 / §9.3: who may revoke a delegation, and when a revocation takes
+// effect against an action. `revocation.holders` and `ots` are both outside the
+// signatures they sit next to, so neither may narrow what a signed revocation
+// does.
+import { describe, expect, it } from 'vitest';
+
+import { computeActionId, computeDelegationId, computeRevocationId } from './canonical.js';
+import { verifyAction, verifyDelegation, verifyRevocation } from './verify.js';
+import type { ActionEnvelope, ActionOts, DelegationEnvelope, RevocationEnvelope } from './types.js';
+
+const PRINCIPAL = 'bc1qprincipal000000000000000000000000000000';
+const AGENT = 'bc1qagent0000000000000000000000000000000000';
+const SCOPE = 'lock:seal(recipient=bc1qalice000000000000000000000000000000000)';
+
+function delegation(holders: unknown): DelegationEnvelope {
+    const canon = {
+        principal: PRINCIPAL,
+        agent: AGENT,
+        scopes: [SCOPE],
+        bond_sats: 0,
+        bond_attestation: 'none',
+        issued_at: '2026-04-22T12:00:00Z',
+        expires_at: '2026-04-29T12:00:00Z',
+        nonce: '0123456789abcdef0123456789abcdef',
+    };
+    return {
+        v: 1,
+        kind: 'agent-delegation',
+        id: computeDelegationId(canon),
+        principal: { address: PRINCIPAL, alg: 'bip322' },
+        agent: { address: AGENT, alg: 'bip322' },
+        scopes: [SCOPE],
+        bond: null,
+        issued_at: canon.issued_at,
+        expires_at: canon.expires_at,
+        nonce: canon.nonce,
+        revocation: { holders, ref: null },
+        sig: { alg: 'bip322', pubkey: PRINCIPAL, value: 'AAAA' },
+    } as DelegationEnvelope;
+}
+
+function revocation(d: DelegationEnvelope, signer: string, signedAt: string, ots: ActionOts | null = null): RevocationEnvelope {
+    const id = computeRevocationId({ address: signer, delegation_id: d.id, reason: '', signed_at: signedAt });
+    return {
+        v: 1,
+        kind: 'agent-revocation',
+        id,
+        delegation_id: d.id,
+        signer: { address: signer, alg: 'bip322' },
+        reason: '',
+        signed_at: signedAt,
+        ots,
+        sig: { alg: 'bip322', pubkey: signer, value: 'AAAA' },
+    };
+}
+
+function action(d: DelegationEnvelope, signedAt: string, ots: ActionOts | null = null): ActionEnvelope {
+    const canon = {
+        address: AGENT,
+        content_hash: 'sha256:' + '00'.repeat(32),
+        content_length: 0,
+        content_mime: 'text/plain',
+        signed_at: signedAt,
+        delegation_id: d.id,
+        scope_exercised: SCOPE,
+    };
+    return {
+        v: 1,
+        kind: 'agent-action',
+        id: computeActionId(canon),
+        content: { hash: canon.content_hash, length: 0, mime: 'text/plain', ref: null },
+        signer: { address: AGENT, alg: 'bip322' },
+        signed_at: signedAt,
+        delegation_id: d.id,
+        scope_exercised: SCOPE,
+        ots,
+        sig: { alg: 'bip322', pubkey: AGENT, value: 'AAAA' },
+    } as ActionEnvelope;
+}
+
+function confirmed(height: number): ActionOts {
+    return {
+        status: 'confirmed',
+        proof: 'AAAA',
+        calendars: [],
+        block_height: height,
+        block_hash: 'ab'.repeat(32),
+        upgraded_at: null,
+    };
+}
+
+const AT = new Date('2026-04-23T12:00:00Z');
+
+describe('revocation authority always includes the principal', () => {
+    for (const holders of [['agent'], [], ['principal'], undefined, 'agent']) {
+        it(`principal revocation is honoured with holders=${JSON.stringify(holders)}`, async () => {
+            const d = delegation(holders);
+            const rev = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z');
+            const rr = await verifyRevocation({ envelope: rev, delegation: d, skipSignatureVerification: true });
+            expect(rr.ok).toBe(true);
+            const dr = await verifyDelegation({
+                envelope: d,
+                revocations: [rev],
+                skipSignatureVerification: true,
+                now: AT,
+            });
+            expect(dr.ok === false && dr.code).toBe('E_REVOKED');
+            const ar = await verifyAction({
+                action: action(d, '2026-04-23T06:00:00Z'),
+                delegation: d,
+                revocations: [rev],
+                skipSignatureVerification: true,
+            });
+            expect(ar.ok === false && ar.code).toBe('E_REVOKED');
+        });
+    }
+
+    it('the agent may revoke only when holders lists it', async () => {
+        const open = delegation(['principal', 'agent']);
+        const closed = delegation(['principal']);
+        const okR = await verifyRevocation({
+            envelope: revocation(open, AGENT, '2026-04-23T00:00:00Z'),
+            delegation: open,
+            skipSignatureVerification: true,
+        });
+        expect(okR.ok).toBe(true);
+        const noR = await verifyRevocation({
+            envelope: revocation(closed, AGENT, '2026-04-23T00:00:00Z'),
+            delegation: closed,
+            skipSignatureVerification: true,
+        });
+        expect(noR.ok === false && noR.code).toBe('E_REVOKER_UNAUTHORIZED');
+    });
+
+    it('a third party is never an authorised revoker', async () => {
+        const d = delegation(['principal', 'agent']);
+        const r = await verifyRevocation({
+            envelope: revocation(d, 'bc1qother0000000000000000000000000000000000', '2026-04-23T00:00:00Z'),
+            delegation: d,
+            skipSignatureVerification: true,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKER_UNAUTHORIZED');
+    });
+});
+
+describe('revocation priority uses only verified anchors', () => {
+    const d = delegation(['principal']);
+    // Revocation signed before the action: revoked unless the action proves priority.
+    const rev = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z');
+    const later = '2026-04-23T06:00:00Z';
+
+    it('an action anchor with no anchor verifier does not outrank a revocation', async () => {
+        const r = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [rev],
+            skipSignatureVerification: true,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+    });
+
+    it('an action anchor the verifier rejects does not outrank a revocation', async () => {
+        const r = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [rev],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => false,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+        const clean = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => false,
+        });
+        expect(clean.ok && clean.anchor).toEqual({
+            status: 'confirmed',
+            blockHeight: 1,
+            blockHash: 'ab'.repeat(32),
+            verified: false,
+        });
+    });
+
+    it('the anchor verifier is asked about the envelope it belongs to', async () => {
+        const a = action(d, later, confirmed(100));
+        const revAnchored = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(200));
+        const seen: string[] = [];
+        const r = await verifyAction({
+            action: a,
+            delegation: d,
+            revocations: [revAnchored],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async (_p, _h, _b, id) => {
+                seen.push(id);
+                return true;
+            },
+        });
+        expect(seen).toEqual([a.id, revAnchored.id]);
+        // Both verified: action at 100 precedes revocation at 200 (§9.3).
+        expect(r.ok).toBe(true);
+    });
+
+    it('a verified action anchor against an unanchored revocation falls back to signed times', async () => {
+        const r = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [rev],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => true,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+        const before = await verifyAction({
+            action: action(d, '2026-04-22T18:00:00Z', confirmed(1)),
+            delegation: d,
+            revocations: [rev],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => true,
+        });
+        expect(before.ok).toBe(true);
+    });
+
+    it('a revocation anchor that does not verify cannot move the revocation later', async () => {
+        const revFarFuture = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(10_000_000));
+        const a = action(d, later, confirmed(100));
+        const r = await verifyAction({
+            action: a,
+            delegation: d,
+            revocations: [revFarFuture],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async (_p, _h, _b, id) => id === a.id,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+    });
+
+    it('both anchors verified: the later block does not revoke the earlier action', async () => {
+        const a = action(d, later, confirmed(300));
+        const revAt = (h: number) => revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(h));
+        const verifyOtsAnchor = async () => true;
+        const earlierRev = await verifyAction({
+            action: a,
+            delegation: d,
+            revocations: [revAt(300)],
+            skipSignatureVerification: true,
+            verifyOtsAnchor,
+        });
+        expect(earlierRev.ok === false && earlierRev.code).toBe('E_REVOKED');
+        const laterRev = await verifyAction({
+            action: a,
+            delegation: d,
+            revocations: [revAt(301)],
+            skipSignatureVerification: true,
+            verifyOtsAnchor,
+        });
+        expect(laterRev.ok).toBe(true);
+    });
+});

package/src/verify.ts

@@ -298,8 +298,19 @@ export interface VerifyActionInput extends VerifyBase {
      */
     maxChainDepth?: number;
     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. */
+    /**
+     * Verify an OTS proof commits `envelopeId` into the block at `blockHeight`.
+     * Same shape as @orangecheck/stamp-core. An anchor is used for revocation
+     * priority (SPEC §9.3) only when this returns true; without it every
+     * anchor is treated as absent.
+     */
+    verifyOtsAnchor?: (
+        proofB64: string,
+        blockHeight: number,
+        blockHash: string,
+        envelopeId: 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. The height is still checked by verifyOtsAnchor. */
     resolveAnchorBlockHeight?: (env: ActionEnvelope | RevocationEnvelope) => number | null;
     /**
      * v1.2 private-scope decryption key. Applied to the root delegation AND
@@ -445,6 +456,14 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
                 'in the chain) or an explicit skipRevocationCheck:true',
         );
     }
+    // Anchor heights only count once the proof is verified against the
+    // envelope's own id; `ots` is outside the signature.
+    let actionAnchor: number | null;
+    try {
+        actionAnchor = await verifiedAnchorHeight(a, input);
+    } catch (e) {
+        return err('E_MALFORMED', `anchor verifier threw: ${(e as Error).message}`);
+    }
     if (input.revocations && input.revocations.length > 0) {
         const allLinks: ChainLink[] = [rootHydrated, ...hydratedChain];
         for (const link of allLinks) {
@@ -460,9 +479,13 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
                     skipSignatureVerification: input.skipSignatureVerification,
                 });
                 if (!rr.ok) continue; // malformed revocations don't affect the action
-                const effective = effectiveRevocationTime(rev, input.resolveAnchorBlockHeight);
-                const actionTime = actionEffectiveTime(a, input.resolveAnchorBlockHeight);
-                if (compareTimes(effective, actionTime) <= 0) {
+                let revAnchor: number | null;
+                try {
+                    revAnchor = await verifiedAnchorHeight(rev, input);
+                } catch (e) {
+                    return err('E_MALFORMED', `anchor verifier threw: ${(e as Error).message}`);
+                }
+                if (revocationPrecedes(rev, revAnchor, a, actionAnchor)) {
                     return err('E_REVOKED', `chain link ${link.id} was revoked by ${rev.id} before action was signed`);
                 }
             }
@@ -489,14 +512,7 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         if (h === null || hash === null) {
             return err('E_MALFORMED', 'confirmed OTS proof missing block_height or block_hash');
         }
-        let verified = false;
-        if (input.verifyOtsAnchor) {
-            try {
-                verified = await input.verifyOtsAnchor(a.ots.proof, h, hash);
-            } catch (e) {
-                return err('E_MALFORMED', `anchor verifier threw: ${(e as Error).message}`);
-            }
-        }
+        const verified = actionAnchor !== null;
         anchor = { status: 'confirmed', blockHeight: h, blockHash: hash, verified } as typeof anchor;
     }
 
@@ -597,11 +613,11 @@ export async function verifyRevocation(input: VerifyRevocationInput): Promise<Ve
         return err('E_DELEGATION_MISMATCH', `revocation.delegation_id (${env.delegation_id}) != delegation.id (${d.id})`);
     }
 
-    // Signer must be authorized per delegation.revocation.holders.
+    // The principal may always revoke (SPEC §9.5). `revocation.holders` is not
+    // covered by the delegation signature, so it may only add the agent.
     const holders = d.revocation?.holders ?? ['principal'];
-    const holderAddrs = new Set<string>();
-    if (holders.includes('principal')) holderAddrs.add(d.principal.address);
-    if (holders.includes('agent')) holderAddrs.add(d.agent.address);
+    const holderAddrs = new Set<string>([d.principal.address]);
+    if (Array.isArray(holders) && holders.includes('agent')) holderAddrs.add(d.agent.address);
     if (!holderAddrs.has(env.signer.address)) {
         return err('E_REVOKER_UNAUTHORIZED', `revocation signer ${env.signer.address} not in delegation holders`);
     }
@@ -901,40 +917,36 @@ export async function verifySubdelegation(
 // Time comparison for revocation vs action (SPEC §9.3)
 // ─────────────────────────────────────────────────────────────────────────────
 
-type EffectiveTime =
-    | { kind: 'anchor'; blockHeight: number }
-    | { kind: 'signed'; ms: number };
-
-function actionEffectiveTime(
-    a: ActionEnvelope,
-    resolve?: (env: ActionEnvelope | RevocationEnvelope) => number | null
-): EffectiveTime {
-    if (a.ots?.status === 'confirmed') {
-        const h = resolve ? resolve(a) : a.ots.block_height;
-        if (h !== null && h !== undefined) return { kind: 'anchor', blockHeight: h };
-    }
-    return { kind: 'signed', ms: new Date(a.signed_at).getTime() };
-}
-
-function effectiveRevocationTime(
-    r: RevocationEnvelope,
-    resolve?: (env: ActionEnvelope | RevocationEnvelope) => number | null
-): EffectiveTime {
-    if (r.ots?.status === 'confirmed') {
-        const h = resolve ? resolve(r) : r.ots.block_height;
-        if (h !== null && h !== undefined) return { kind: 'anchor', blockHeight: h };
-    }
-    return { kind: 'signed', ms: new Date(r.signed_at).getTime() };
+/**
+ * The block height of an envelope's OTS anchor, or null unless the proof has
+ * been verified to commit this envelope's id at that height.
+ */
+async function verifiedAnchorHeight(
+    env: ActionEnvelope | RevocationEnvelope,
+    input: Pick<VerifyActionInput, 'verifyOtsAnchor' | 'resolveAnchorBlockHeight'>
+): Promise<number | null> {
+    if (env.ots?.status !== 'confirmed' || !input.verifyOtsAnchor) return null;
+    const h = input.resolveAnchorBlockHeight ? input.resolveAnchorBlockHeight(env) : env.ots.block_height;
+    const hash = env.ots.block_hash;
+    if (h === null || h === undefined || !Number.isInteger(h) || !hash) return null;
+    return (await input.verifyOtsAnchor(env.ots.proof, h, hash, env.id)) ? h : null;
 }
 
-/** Returns <0 if a < b, 0 if equal, >0 if a > b. Anchored always beats signed-only. */
-function compareTimes(a: EffectiveTime, b: EffectiveTime): number {
-    if (a.kind === 'anchor' && b.kind === 'anchor') return a.blockHeight - b.blockHeight;
-    // If only one anchored, the anchored one is authoritative: an unanchored action cannot
-    // prove priority against an anchored revocation, so the anchored side is treated as "earlier".
-    if (a.kind === 'anchor') return -1;
-    if (b.kind === 'anchor') return 1;
-    return a.ms - b.ms;
+/**
+ * True when the revocation takes effect at or before the action (SPEC §9.3).
+ * Only verified anchors count for priority. An action without one cannot prove
+ * priority over a revocation that claims an anchor; an anchored action against
+ * an unanchored revocation falls back to the signed times.
+ */
+function revocationPrecedes(
+    rev: RevocationEnvelope,
+    revAnchor: number | null,
+    action: ActionEnvelope,
+    actionAnchor: number | null
+): boolean {
+    if (revAnchor !== null && actionAnchor !== null) return revAnchor <= actionAnchor;
+    if (actionAnchor === null && rev.ots?.status === 'confirmed') return true;
+    return new Date(rev.signed_at).getTime() <= new Date(action.signed_at).getTime();
 }
 
 // ─────────────────────────────────────────────────────────────────────────────