@orangecheck/agent-core 2.5.1 → 2.7.0

package/src/revocation-failclosed.test.ts

@@ -106,7 +106,7 @@ describe('the refusal names a query relays answer', () => {
     });
 
     it('verifyAction', async () => {
-        const r = await verifyAction({ action, delegation, skipSignatureVerification: true });
+        const r = await verifyAction({ action, delegation, skipSignatureVerification: true, now: AT });
         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

@@ -18,7 +18,13 @@ import {
     subdelegationCanonicalMessage,
 } from './canonical.js';
 import { parseScope, ScopeParseError } from './scope.js';
-import { verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation } from './verify.js';
+import {
+    verifyAction,
+    verifyActionAsOfSignedAt,
+    verifyDelegation,
+    verifyRevocation,
+    verifySubdelegation,
+} from './verify.js';
 import type {
     ActionEnvelope,
     AgentErrorCode,
@@ -127,6 +133,12 @@ interface NegativeActionVector extends NegativeVectorBase {
         scope_exercised: string;
         content_ref?: string | null;
         ots?: unknown;
+        /** Present on a live vector (§8.1 steps 6–7, §8.3 step 11a): the time of verification. */
+        verified_at?: string;
+        /** The freshness bound a live vector assumes, in seconds. */
+        max_skew_seconds?: number;
+        /** Revocations of the cited delegation, as the inputs of each envelope. */
+        revocations?: { address: string; reason: string; signed_at: string }[];
     };
 }
 
@@ -155,6 +167,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 {
@@ -273,7 +291,8 @@ describe('oc-agent-protocol test vectors', () => {
                 if (!delegation) {
                     throw new Error(`action vector ${name} references missing delegation ${data.inputs.delegation_id}`);
                 }
-                const r = await verifyAction({
+                // A positive vector is the envelope as of its own signed_at.
+                const r = await verifyActionAsOfSignedAt({
                     skipRevocationCheck: true,
                     action: data.expected.envelope,
                     delegation,
@@ -455,12 +474,34 @@ describe('oc-agent-protocol negative test vectors', () => {
                     ots: null,
                     sig: { alg: 'bip322', pubkey: v.inputs.address, value: 'AAAA' },
                 };
-                const r = await verifyAction({
-                    skipRevocationCheck: true,
-                    action,
-                    delegation,
-                    skipSignatureVerification: true,
-                });
+                const revocations: RevocationEnvelope[] = (v.inputs.revocations ?? []).map((rv) => ({
+                    v: 1,
+                    kind: 'agent-revocation',
+                    id: computeRevocationId({ ...rv, delegation_id: v.inputs.delegation_id }),
+                    delegation_id: v.inputs.delegation_id,
+                    signer: { address: rv.address, alg: 'bip322' },
+                    reason: rv.reason,
+                    signed_at: rv.signed_at,
+                    ots: null,
+                    sig: { alg: 'bip322', pubkey: rv.address, value: 'AAAA' },
+                }));
+                // A vector with verified_at is checked live at that time; one
+                // without is an audit of the envelope as of its signed_at.
+                const r = v.inputs.verified_at
+                    ? await verifyAction({
+                          action,
+                          delegation,
+                          skipSignatureVerification: true,
+                          revocations,
+                          now: new Date(v.inputs.verified_at),
+                          maxSkewMs: (v.inputs.max_skew_seconds ?? 120) * 1000,
+                      })
+                    : await verifyActionAsOfSignedAt({
+                          skipRevocationCheck: true,
+                          action,
+                          delegation,
+                          skipSignatureVerification: true,
+                      });
                 expect(r.ok).toBe(false);
                 if (!r.ok) {
                     // v07 specifically allows either E_OUT_OF_WINDOW or E_EXPIRED
@@ -507,6 +548,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/types.ts

@@ -237,6 +237,7 @@ export type AgentErrorCode =
     | 'E_NOT_YET_VALID'
     | 'E_EXPIRED'
     | 'E_REVOKED'
+    | 'E_STALE'
     | 'E_DELEGATION_MISMATCH'
     | 'E_AGENT_MISMATCH'
     | 'E_OUT_OF_WINDOW'
@@ -298,6 +299,14 @@ export interface VerifyActionOkExtra {
         | { status: 'pending' }
         | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }
         | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };
+    /**
+     * The time the verdict holds for. `now`: verifyAction, checked live.
+     * `signed_at`: verifyActionAsOfSignedAt, checked as of the time the agent
+     * claims; `anchored` is false when only the agent says so.
+     */
+    asOf:
+        | { basis: 'now'; now: string }
+        | { basis: 'signed_at'; signedAt: string; anchored: boolean };
 }
 
 export type VerifyActionResult =

package/src/verify.ts

@@ -40,6 +40,9 @@ import {
 /** Default maximum chain depth, per SUB-DELEGATION.md §2.1. */
 export const DEFAULT_MAX_CHAIN_DEPTH = 5;
 
+/** How far a live action's `signed_at` may lie from the verifier's clock, either way (SPEC §8.3 step 11a). */
+export const DEFAULT_MAX_SKEW_MS = 120_000;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared options
 // ─────────────────────────────────────────────────────────────────────────────
@@ -254,7 +257,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}`);
     }
@@ -325,9 +327,51 @@ export interface VerifyActionInput extends VerifyBase {
         device_id: string;
         secretKey: Uint8Array;
     };
+    /**
+     * The time of verification; defaults to new Date(). Every link of the
+     * chain must be in force at `now`, and a revocation in effect at or
+     * before `now` refuses the action, whatever `signed_at` it claims
+     * (SPEC §8.1 steps 6–7).
+     */
+    now?: Date;
+    /**
+     * How far `signed_at` may lie from `now`, either way, before the action
+     * is refused with E_STALE. Default DEFAULT_MAX_SKEW_MS (120 s). The agent
+     * chooses `signed_at`, so this bound is what makes it mean "just now".
+     */
+    maxSkewMs?: number;
 }
 
+/** An audit of a past action: no `now`, no freshness bound. See verifyActionAsOfSignedAt. */
+export type VerifyActionAsOfSignedAtInput = Omit<VerifyActionInput, 'now' | 'maxSkewMs'>;
+
+/**
+ * Verify an action live, as of `now` (SPEC §8). This is the check for a
+ * server deciding whether to act on it. Replay is the caller's to stop: keep
+ * the ids of accepted actions (createReplayGuard) for as long as they could
+ * pass the freshness bound.
+ */
 export async function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult> {
+    return verifyActionAt(input, input.now ?? new Date());
+}
+
+/**
+ * Verify a past action as of its own `signed_at`, for an audit (SPEC §8.6).
+ * The agent chose that time, so the verdict holds only if the claim is true:
+ * `asOf.anchored` is false unless a verified OTS anchor fixes it. Never use
+ * this to decide whether to act on an action now.
+ */
+export async function verifyActionAsOfSignedAt(
+    input: VerifyActionAsOfSignedAtInput
+): Promise<VerifyActionResult> {
+    return verifyActionAt(input, null);
+}
+
+/** `now` null: the audit form, checked as of the action's own signed_at. */
+async function verifyActionAt(
+    input: VerifyActionInput,
+    now: Date | null
+): Promise<VerifyActionResult> {
     const a = input.action;
     const d = input.delegation;
 
@@ -428,6 +472,19 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         return err('E_OUT_OF_WINDOW', `action.signed_at ${a.signed_at} is outside leaf window [${leaf.issued_at}, ${leaf.expires_at})`);
     }
 
+    // 4b. Live: every link is in force now, not only at the claimed signed_at.
+    if (now) {
+        const t = now.getTime();
+        for (const link of [rootHydrated, ...hydratedChain]) {
+            if (t < new Date(link.issued_at).getTime()) {
+                return err('E_NOT_YET_VALID', `${link.id} is not valid until ${link.issued_at}`);
+            }
+            if (t >= new Date(link.expires_at).getTime()) {
+                return err('E_EXPIRED', `${link.id} expired at ${link.expires_at}`);
+            }
+        }
+    }
+
     // 5. Scope containment — against the leaf's granted set.
     //    Leaf is post-hydration, so `scopes` is guaranteed populated. The
     //    runtime guard satisfies the type checker and would only fire if a
@@ -490,10 +547,27 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
                 if (revocationPrecedes(rev, revAnchor, a, actionAnchor)) {
                     return err('E_REVOKED', `chain link ${link.id} was revoked by ${rev.id} before action was signed`);
                 }
+                // Live: a revocation already in effect refuses the action, however
+                // early its signed_at claims to be.
+                if (now && (revAnchor !== null || new Date(rev.signed_at).getTime() <= now.getTime())) {
+                    return err('E_REVOKED', `chain link ${link.id} was revoked by ${rev.id}`);
+                }
             }
         }
     }
 
+    // 6b. Live: signed_at is the agent's claim; only a bound on it makes the
+    //     action recent.
+    if (now) {
+        const maxSkew = input.maxSkewMs ?? DEFAULT_MAX_SKEW_MS;
+        if (Math.abs(now.getTime() - signed) > maxSkew) {
+            return err(
+                'E_STALE',
+                `action.signed_at ${a.signed_at} is more than ${maxSkew} ms from the time of verification ${now.toISOString()}`
+            );
+        }
+    }
+
     // 7. Content check.
     if (input.content) {
         const actualHash = 'sha256:' + hexEncode(sha256(input.content));
@@ -530,6 +604,31 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         chain: hydratedChain,
         scopeExercised: exercised,
         anchor,
+        asOf: now
+            ? { basis: 'now', now: now.toISOString() }
+            : { basis: 'signed_at', signedAt: a.signed_at, anchored: actionAnchor !== null },
+    };
+}
+
+/**
+ * Remembers the ids of accepted actions, so one signed action is acted on
+ * once. An action passes the freshness bound for `maxSkewMs` either side of
+ * its signed_at, so its id is kept until signed_at + maxSkewMs. In-memory and
+ * per process: a server on several instances keeps the same record in a
+ * shared store. Two identical calls signed in the same second share an id.
+ */
+export function createReplayGuard(maxSkewMs: number = DEFAULT_MAX_SKEW_MS): {
+    firstUse(action: Pick<ActionEnvelope, 'id' | 'signed_at'>, now?: Date): boolean;
+} {
+    const keepUntil = new Map<string, number>();
+    return {
+        firstUse(action, now = new Date()) {
+            const t = now.getTime();
+            for (const [id, until] of keepUntil) if (until <= t) keepUntil.delete(id);
+            if (keepUntil.has(action.id)) return false;
+            keepUntil.set(action.id, new Date(action.signed_at).getTime() + maxSkewMs);
+            return true;
+        },
     };
 }
 
@@ -672,12 +771,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');