@orangecheck/agent-core 2.5.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "2.5.1",
+  "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,6 +168,26 @@ 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 §5 item 7: a revoked federation delegation must

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)
@@ -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.
@@ -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/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

@@ -254,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}`);
     }
@@ -672,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');