@orangecheck/agent-core 2.0.0 → 2.2.0

package/src/revocation-failclosed.test.ts

@@ -10,19 +10,30 @@
 //
 // 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;
+// Inlined rather than read from oc-agent-protocol/test-vectors: this test is
+// about the revocation guard, not vector conformance, and a relative path into
+// a sibling repo resolves locally but not in CI, where the spec repo is not
+// checked out beside this one. test-vectors.test.ts is the place that depends
+// on the real vectors, and CI checks them out for it.
+const delegation: DelegationEnvelope = {
+    v: 1,
+    kind: 'agent-delegation',
+    id: '36d79600191db871baa3fc9aa3b5e77750a5c423b1f620ec26cf16bd122e19a7',
+    principal: { address: 'bc1qprincipal000000000000000000000000000000', alg: 'bip322' },
+    agent: { address: 'bc1qagent0000000000000000000000000000000000', alg: 'bip322' },
+    scopes: ['lock:seal(recipient=bc1qalice000000000000000000000000000000000)'],
+    bond: null,
+    issued_at: '2026-04-22T12:00:00Z',
+    expires_at: '2026-04-29T12:00:00Z',
+    nonce: '0123456789abcdef0123456789abcdef',
+    revocation: { holders: ['principal'], ref: null },
+    sig: { alg: 'bip322', pubkey: 'bc1qprincipal000000000000000000000000000000', value: 'AAAA' },
+} as DelegationEnvelope;
 
 const AT = new Date('2026-04-23T12:00:00Z'); // inside the delegation's window
 

package/src/scope.test.ts

@@ -160,3 +160,47 @@ describe('isSubScope (SPEC §7.4)', () => {
         ).toBe(false);
     });
 });
+
+// SPEC §7.4: "values MUST be decimal integers for ordered ops". `Number()` is
+// much looser and accepted 1e3, 0x3e8, +1000, " 1000 " and 1.5 — plus "", which
+// becomes 0 and turns an empty constraint into a silent zero bound. A verifier
+// with a strict decimal parser rejects all of them, so identical bytes produced
+// different accept/reject answers across implementations, which SECURITY §5
+// rules out.
+describe('ordered-op values must be decimal integers (SPEC §7.4)', () => {
+    const granted = parseScope('ln:send(max_sats<=1000)');
+
+    it('still admits a plain decimal integer', () => {
+        expect(isSubScope(parseScope('ln:send(max_sats<=500)'), granted)).toBe(true);
+        expect(isSubScope(parseScope('ln:send(max_sats<=1000)'), granted)).toBe(true);
+    });
+
+    it('still rejects a decimal integer outside the granted range', () => {
+        expect(isSubScope(parseScope('ln:send(max_sats<=1001)'), granted)).toBe(false);
+    });
+
+    // Each of these previously compared numerically and could be ADMITTED.
+    for (const v of ['1e3', '0x3e8', '+1000', '1.5']) {
+        it(`rejects ${JSON.stringify(v)} rather than coercing it`, () => {
+            let exercised;
+            try {
+                exercised = parseScope(`ln:send(max_sats<=${v})`);
+            } catch {
+                return; // rejected at parse time is also a rejection
+            }
+            expect(isSubScope(exercised, granted)).toBe(false);
+        });
+    }
+
+    // The sharpest case: Number('') === 0, so an empty constraint became
+    // max_sats<=0 — a real bound nobody wrote.
+    it('does not silently read an empty value as zero', () => {
+        let exercised;
+        try {
+            exercised = parseScope('ln:send(max_sats<=)');
+        } catch {
+            return;
+        }
+        expect(isSubScope(exercised, parseScope('ln:send(max_sats<=0)'))).toBe(false);
+    });
+});

package/src/scope.ts

@@ -309,10 +309,25 @@ function rangeSubset(ex: ScopeConstraint, g: ScopeConstraint): boolean {
     return gRange.lo <= exRange.lo && exRange.hi <= gRange.hi;
 }
 
+/**
+ * SPEC §7.4: "values MUST be decimal integers for ordered ops".
+ *
+ * `Number()` is far more permissive than that and accepts `1e3`, `0x3e8`,
+ * `+1000`, `" 1000 "`, `1.5` — and `""`, which becomes 0, turning an empty
+ * constraint into a silent zero bound. A verifier using a strict decimal parser
+ * rejects every one of those, so the same bytes produced different accept/reject
+ * answers on different implementations. SECURITY §5 requires they not.
+ */
+function parseDecimalInteger(value: string): number | null {
+    if (!/^-?\d+$/.test(value)) return null;
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : null;
+}
+
 function opToRange(c: ScopeConstraint): { lo: number; hi: number } | null {
     if (c.value === undefined) return null;
-    const n = Number(c.value);
-    if (!Number.isFinite(n)) return null;
+    const n = parseDecimalInteger(c.value);
+    if (n === null) return null;
     switch (c.op) {
         case '=':
             return { lo: n, hi: n };

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();
 }
 
 // ─────────────────────────────────────────────────────────────────────────────