@orangecheck/agent-core 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "2.5.0",
+  "version": "2.6.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/delegation-window.test.ts

@@ -0,0 +1,82 @@
+// SPEC §4.4: expires_at > issued_at and expires_at - issued_at ≤ 365 days, checked at
+// §8.1 step 2 (E_MALFORMED) whatever the clock says. Every envelope here has an honest
+// id, so without the window check each one would verify.
+
+import { describe, expect, it } from 'vitest';
+
+import { canonicalizeScopes, computeDelegationId } from './canonical.js';
+import type { DelegationEnvelope } from './types.js';
+import { verifyDelegation } from './verify.js';
+
+const ISSUED = '2026-04-22T12:00:00Z';
+const DAY = 86_400_000;
+const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+function delegation(issued_at: string, expires_at: string): DelegationEnvelope {
+    const principal = 'bc1qprincipal000000000000000000000000000000';
+    const agent = 'bc1qagent0000000000000000000000000000000000';
+    const scopes = canonicalizeScopes(['ln:send(max_sats<=1000)']);
+    const nonce = '0123456789abcdef0123456789abcdef';
+    const id = computeDelegationId({
+        principal,
+        agent,
+        scopes,
+        bond_sats: 0,
+        bond_attestation: 'none',
+        issued_at,
+        expires_at,
+        nonce,
+    });
+    return {
+        v: 1,
+        kind: 'agent-delegation',
+        id,
+        principal: { address: principal, alg: 'bip322' },
+        agent: { address: agent, alg: 'bip322' },
+        scopes,
+        bond: null,
+        issued_at,
+        expires_at,
+        nonce,
+        revocation: { holders: ['principal'], ref: null },
+        sig: { alg: 'bip322', pubkey: principal, value: 'AAAA' },
+    };
+}
+
+const verify = (env: DelegationEnvelope, now?: Date) =>
+    verifyDelegation({
+        envelope: env,
+        skipSignatureVerification: true,
+        skipRevocationCheck: true,
+        ...(now ? { now } : { skipTemporalCheck: true }),
+    });
+
+describe('delegation window (SPEC §4.4)', () => {
+    const issuedMs = Date.parse(ISSUED);
+
+    it('accepts exactly 365 days', async () => {
+        expect((await verify(delegation(ISSUED, iso(issuedMs + 365 * DAY)))).ok).toBe(true);
+    });
+
+    it('rejects 365 days and one second with E_MALFORMED', async () => {
+        const r = await verify(delegation(ISSUED, iso(issuedMs + 365 * DAY + 1000)));
+        expect(r).toMatchObject({ ok: false, code: 'E_MALFORMED' });
+        if (!r.ok) expect(r.message).toBe('expires_at is more than 365 days after issued_at (SPEC §4.4)');
+    });
+
+    it('rejects 366 days even inside the window, so the clock cannot rescue it', async () => {
+        const r = await verify(delegation(ISSUED, iso(issuedMs + 366 * DAY)), new Date(issuedMs + DAY));
+        expect(r).toMatchObject({ ok: false, code: 'E_MALFORMED' });
+    });
+
+    it('rejects expires_at equal to issued_at with temporal checks skipped', async () => {
+        const r = await verify(delegation(ISSUED, ISSUED));
+        expect(r).toMatchObject({ ok: false, code: 'E_MALFORMED' });
+        if (!r.ok) expect(r.message).toBe('expires_at must be after issued_at');
+    });
+
+    it('rejects a timestamp that is shaped right but is no real time', async () => {
+        const r = await verify(delegation(ISSUED, '2026-13-01T00:00:00Z'));
+        expect(r).toMatchObject({ ok: false, code: 'E_MALFORMED' });
+    });
+});

package/src/federation.test.ts

@@ -16,7 +16,7 @@ import {
     type FederationDelegationEnvelope,
     type FederationRevocationEnvelope,
 } from './federation.js';
-import { computeRevocationId } from './canonical.js';
+import { computeDelegationId, computeRevocationId } from './canonical.js';
 import { verifyDelegation } from './verify.js';
 import type { DelegationEnvelope } from './types.js';
 
@@ -168,9 +168,29 @@ d('federation reject reasons (each invalid case fails for its named reason)', ()
         expect(r.ok).toBe(false);
         if (!r.ok) expect(r.code).toBe('E_THRESHOLD_MISMATCH');
     });
+    it('366-day window → E_MALFORMED (FEDERATION.md §5 bounds it as SPEC §4.4 does)', async () => {
+        const v = await load('v19-federation-delegation-3of5-valid.json');
+        const env = { ...v.expected.envelope } as FederationDelegationEnvelope;
+        env.expires_at = new Date(Date.parse(env.issued_at) + 366 * 86_400_000)
+            .toISOString()
+            .replace(/\.\d{3}Z$/, 'Z');
+        // Honest id for the longer window, so the window is the only fault.
+        env.id = computeDelegationId({
+            principal: `federation:${env.principal.descriptor_id}`,
+            agent: env.agent.address,
+            scopes: env.scopes,
+            bond_sats: env.bond?.sats ?? 0,
+            bond_attestation: env.bond?.attestation_id ?? 'none',
+            issued_at: env.issued_at,
+            expires_at: env.expires_at,
+            nonce: env.nonce,
+        });
+        const r = await verifyFederationDelegation({ envelope: env, ...opts });
+        expect(r).toMatchObject({ ok: false, code: 'E_MALFORMED' });
+    });
 });
 
-// FEDERATION.md §4 / SECURITY §7 item 7: a revoked federation delegation must
+// FEDERATION.md §4 / SECURITY §5 item 7: a revoked federation delegation must
 // not verify, and skipping the revocation check has to be stated.
 d('federation delegation revocation check', () => {
     const base = { skipSignatureVerification: true, skipTemporalCheck: true } as const;
@@ -180,6 +200,8 @@ d('federation delegation revocation check', () => {
         const r = await verifyFederationDelegation({ envelope: dv.expected.envelope, ...base });
         expect(r.ok).toBe(false);
         expect(r.ok === false && r.message).toMatch(/requires `revocations`/);
+        expect(r.ok === false && r.message).toMatch(/"#t": \[delegation id\]/);
+        expect(r.ok === false && r.message).not.toMatch(/#delegation/);
     });
 
     it('verifies with an empty revocation list', async () => {

package/src/federation.ts

@@ -32,6 +32,7 @@ import type {
     DelegationRevocationRef,
     RevocationEnvelope,
 } from './types.js';
+import { delegationWindowError } from './verify.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (FEDERATION.md §2 / §3.2)
@@ -228,7 +229,7 @@ async function checkFederationQuorum(
 export interface VerifyFederationDelegationInput extends VerifyFederationBase {
     envelope: FederationDelegationEnvelope;
     /**
-     * Revocations to check (kind-30085 by `#delegation`): federation revocations,
+     * Revocations to check (kind-30085 by `#t` with the delegation id, SPEC §9.4): federation revocations,
      * and agent self-revocations when `revocation.holders` includes "agent".
      * Required unless `skipRevocationCheck` states that revocation is not checked.
      */
@@ -251,6 +252,8 @@ export async function verifyFederationDelegation(
     if (!ISO_UTC.test(env.issued_at) || !ISO_UTC.test(env.expires_at)) {
         return fail('E_MALFORMED', 'issued_at / expires_at must be ISO 8601 UTC');
     }
+    const windowError = delegationWindowError(env.issued_at, env.expires_at);
+    if (windowError) return fail('E_MALFORMED', windowError);
     if (!/^[0-9a-f]{32}$/.test(env.nonce)) return fail('E_MALFORMED', 'nonce must be 32 hex chars');
 
     // Canonical scopes (identical rules to v1) must be sorted on the envelope.
@@ -290,7 +293,7 @@ export async function verifyFederationDelegation(
     if (!input.skipRevocationCheck && !input.revocations) {
         return fail(
             'E_MALFORMED',
-            'verifyFederationDelegation requires `revocations` (fetch kind-30085 by #delegation) ' +
+            'verifyFederationDelegation requires `revocations` (query kind 30085 with "#t": [delegation id], SPEC §9.4) ' +
                 'or an explicit skipRevocationCheck:true to state that revocation is not being checked'
         );
     }
@@ -305,7 +308,6 @@ export async function verifyFederationDelegation(
         const now = input.now ?? new Date();
         const issued = new Date(env.issued_at);
         const expires = new Date(env.expires_at);
-        if (expires <= issued) return fail('E_MALFORMED', 'expires_at <= issued_at');
         if (now < issued) return fail('E_NOT_YET_VALID', `delegation not valid until ${env.issued_at}`);
         if (now >= expires) return fail('E_EXPIRED', `delegation expired at ${env.expires_at}`);
     }

package/src/private-scope.test.ts

@@ -189,8 +189,10 @@ async function buildPrivateEnvelopeWithKey(
         ],
     });
 
-    const issued_at = '2026-04-22T12:00:00Z';
-    const expires_at = '2099-04-22T12:00:00Z';
+    // Current window, inside SPEC §4.4's 365-day limit, so the temporal check passes.
+    const isoSeconds = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const issued_at = isoSeconds(Date.now() - 86_400_000);
+    const expires_at = isoSeconds(Date.now() + 30 * 86_400_000);
     const nonce = hexEncode(randomBytesN(16));
 
     const canonInput = {

package/src/revocation-failclosed.test.ts

@@ -1,6 +1,6 @@
-// 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."
+// SECURITY §5 item 7: "Query revocation feeds (Nostr kind-30085 by `#t` with
+// 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
@@ -12,8 +12,9 @@
 // changed is that declining to is now a decision they have to state.
 import { describe, expect, it } from 'vitest';
 
-import { verifyDelegation } from './verify.js';
-import type { DelegationEnvelope } from './types.js';
+import { computeActionId } from './canonical.js';
+import { verifyAction, verifyDelegation } from './verify.js';
+import type { ActionEnvelope, DelegationEnvelope } from './types.js';
 
 // 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
@@ -68,11 +69,46 @@ describe('verifyDelegation fails closed on revocation', () => {
         });
         expect(r.ok).toBe(true);
     });
+});
+
+// The refusal tells the caller how to fetch revocations. SPEC §9.4: relays index
+// single-letter tags only and reject a `#delegation` filter (SPEC §10.4), so the
+// message must name the `#t` query.
+describe('the refusal names a query relays answer', () => {
+    const action: ActionEnvelope = (() => {
+        const canon = {
+            address: delegation.agent.address,
+            content_hash: 'sha256:' + '00'.repeat(32),
+            content_length: 0,
+            content_mime: 'text/plain',
+            signed_at: '2026-04-23T12:00:00Z',
+            delegation_id: delegation.id,
+            scope_exercised: delegation.scopes![0]!,
+        };
+        return {
+            v: 1,
+            kind: 'agent-action',
+            id: computeActionId(canon),
+            content: { hash: canon.content_hash, length: 0, mime: 'text/plain', ref: null },
+            signer: { address: canon.address, alg: 'bip322' },
+            signed_at: canon.signed_at,
+            delegation_id: delegation.id,
+            scope_exercised: canon.scope_exercised,
+            ots: null,
+            sig: { alg: 'bip322', pubkey: canon.address, value: 'AAAA' },
+        } as ActionEnvelope;
+    })();
 
-    // 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');
+    it('verifyDelegation', async () => {
+        const r = await verifyDelegation({ envelope: delegation, skipSignatureVerification: true, now: AT });
+        expect(r.ok === false && r.message).toMatch(/"#t": \[delegation id\]/);
+        expect(r.ok === false && r.message).not.toMatch(/#delegation/);
+    });
+
+    it('verifyAction', async () => {
+        const r = await verifyAction({ action, delegation, skipSignatureVerification: true });
+        expect(r.ok === false && r.code).toBe('E_MALFORMED');
+        expect(r.ok === false && r.message).toMatch(/"#t": \[id of every link in the chain\]/);
+        expect(r.ok === false && r.message).not.toMatch(/#delegation/);
     });
 });

package/src/scope.test.ts

@@ -257,3 +257,23 @@ describe('the adapter scopes are registered', () => {
         expect(isSubScope(parseScope('anthropic:tool(name=getWeather)'), granted)).toBe(false);
     });
 });
+
+// SPEC §7.2 rule 2 (errata 1.6.2): values keep their case on every key, not only the
+// four marked case-sensitive. Folding would break base58 addresses and widen grants.
+describe('scope values keep their case (SPEC §7.2)', () => {
+    for (const s of [
+        'lock:seal(recipient=1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2)',
+        'mcp:invoke(server=https://mcp.example.com/Tools,tool=getWeather)',
+        'http:request(method=GET,origin=https://api.example.com)',
+    ]) {
+        it(`canonical form of ${s} is unchanged`, () => {
+            expect(canonicalizeScopeString(s)).toBe(s);
+        });
+    }
+
+    it('a grant on a key not marked case-sensitive still matches case exactly', () => {
+        const granted = parseScope('mcp:invoke(tool=getWeather)');
+        expect(isSubScope(parseScope('mcp:invoke(tool=getWeather)'), granted)).toBe(true);
+        expect(isSubScope(parseScope('mcp:invoke(tool=GetWeather)'), granted)).toBe(false);
+    });
+});

package/src/test-vectors.test.ts

@@ -155,6 +155,12 @@ interface NegativeDelegationVector extends NegativeVectorBase {
         scope: string;
         why: string;
     }[];
+    // Present when the fault is in a well-formed, honestly-id'd envelope (v27).
+    expected: NegativeVectorBase['expected'] & {
+        canonical_message?: string;
+        id?: string;
+        envelope?: DelegationEnvelope;
+    };
 }
 
 interface NegativeSubdelegationVector extends NegativeVectorBase {
@@ -507,6 +513,21 @@ describe('oc-agent-protocol negative test vectors', () => {
                 });
                 expect(r.ok).toBe(false);
                 if (!r.ok) expect(r.code).toBe(v.expected.error_code);
+            } else if (data.kind === 'delegation' && (data as NegativeDelegationVector).expected.envelope) {
+                // The envelope is honest (its id reconstructs from inputs), so the
+                // verifier's rejection is the declared fault and nothing else.
+                const v = data as NegativeDelegationVector;
+                const asPositive = { kind: 'delegation', inputs: v.inputs } as unknown as PositiveVector;
+                expect(reconstructCanonical(asPositive)).toBe(v.expected.canonical_message);
+                expect(reconstructId(asPositive)).toBe(v.expected.id);
+                const r = await verifyDelegation({
+                    envelope: v.expected.envelope!,
+                    skipSignatureVerification: true,
+                    skipRevocationCheck: true,
+                    skipTemporalCheck: true,
+                });
+                expect(r.ok).toBe(false);
+                if (!r.ok) expect(r.code).toBe(v.expected.error_code);
             } else if (data.kind === 'delegation') {
                 // Delegation negative vectors target the §7.1 grammar parser
                 // directly — that's where E_BAD_SCOPE_GRAMMAR fires per

package/src/verify.ts

@@ -51,9 +51,9 @@ export interface VerifyBase {
     /**
      * 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
+     * SECURITY §5 item 7: "Query revocation feeds (Nostr kind-30085 by `#t`
+     * with 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".
      *
@@ -63,7 +63,9 @@ export interface VerifyBase {
     skipRevocationCheck?: boolean;
     /**
      * Revocations to evaluate against the delegation (or, for an action, every
-     * link in its chain). Fetch these from kind-30085 by `#delegation`.
+     * link in its chain). Fetch kind-30085 events with `"#t": [<delegation id>]`
+     * (SPEC §9.4); relays do not index the multi-letter `delegation` tag. Pass
+     * `[]` only when a relay answered with EOSE and none matched (SPEC §10.4).
      */
     revocations?: RevocationEnvelope[];
 }
@@ -222,15 +224,15 @@ 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.
+    // Revocation. SECURITY §5 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',
+            'verifyDelegation requires `revocations` (query kind 30085 with "#t": [delegation id], ' +
+                'SPEC §9.4) or an explicit skipRevocationCheck:true to state that revocation is not being checked',
         );
     }
     if (input.revocations) {
@@ -252,7 +254,6 @@ export async function verifyDelegation(input: VerifyDelegationInput): Promise<Ve
         const now = input.now ?? new Date();
         const issued = new Date(env.issued_at);
         const expires = new Date(env.expires_at);
-        if (expires <= issued) return err('E_MALFORMED', 'expires_at <= issued_at');
         if (now < issued) return err('E_NOT_YET_VALID', `delegation not valid until ${env.issued_at}`);
         if (now >= expires) return err('E_EXPIRED', `delegation expired at ${env.expires_at}`);
     }
@@ -452,8 +453,8 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
     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',
+            'verifyAction requires `revocations` (query kind 30085 with "#t": [id of every link ' +
+                'in the chain], SPEC §9.4) or an explicit skipRevocationCheck:true',
         );
     }
     // Anchor heights only count once the proof is verified against the
@@ -670,12 +671,26 @@ function checkDelegationShape(env: DelegationEnvelope): VerifyDelegationResult |
     }
     if (!isIsoUtc(env.issued_at)) return err('E_MALFORMED', 'issued_at must be ISO 8601 UTC');
     if (!isIsoUtc(env.expires_at)) return err('E_MALFORMED', 'expires_at must be ISO 8601 UTC');
+    const windowError = delegationWindowError(env.issued_at, env.expires_at);
+    if (windowError) return err('E_MALFORMED', windowError);
     if (!/^[0-9a-f]{32}$/.test(env.nonce)) return err('E_MALFORMED', 'nonce must be 32 lowercase hex chars');
     if (env.sig?.alg !== 'bip322' || typeof env.sig.value !== 'string') return err('E_MALFORMED', 'sig invalid');
     if (env.sig.pubkey !== env.principal.address) return err('E_MALFORMED', 'sig.pubkey must equal principal.address');
     return null;
 }
 
+const MAX_DELEGATION_MS = 365 * 86_400_000;
+
+/** SPEC §4.4 window, checked at §8.1 step 2 whatever the clock says: issued < expires, at most 365 days. */
+export function delegationWindowError(issuedAt: string, expiresAt: string): string | null {
+    const issued = Date.parse(issuedAt);
+    const expires = Date.parse(expiresAt);
+    if (Number.isNaN(issued) || Number.isNaN(expires)) return 'issued_at / expires_at must be real UTC times';
+    if (expires <= issued) return 'expires_at must be after issued_at';
+    if (expires - issued > MAX_DELEGATION_MS) return 'expires_at is more than 365 days after issued_at (SPEC §4.4)';
+    return null;
+}
+
 function checkActionShape(a: ActionEnvelope): VerifyActionResult | null {
     if (a.kind !== 'agent-action') return err('E_MALFORMED', 'kind must be "agent-action"');
     if (!isHex64(a.id)) return err('E_MALFORMED', 'id must be 64 lowercase hex chars');