@orangecheck/agent-core 2.6.0 → 2.7.1

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 }[];
     };
 }
 
@@ -279,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,
@@ -461,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

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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -324,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;
 
@@ -427,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
@@ -489,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));
@@ -529,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;
+        },
     };
 }
 
@@ -617,13 +717,14 @@ export async function verifyRevocation(input: VerifyRevocationInput): Promise<Ve
         return err('E_DELEGATION_MISMATCH', `revocation.delegation_id (${env.delegation_id}) != delegation.id (${d.id})`);
     }
 
-    // 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>([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`);
+    // The principal and the agent may always revoke (SPEC §9.5). Revoking only
+    // removes authority, and `revocation.holders` is outside the delegation's
+    // signature, so no copy of it decides who may.
+    if (env.signer.address !== d.principal.address && env.signer.address !== d.agent.address) {
+        return err(
+            'E_REVOKER_UNAUTHORIZED',
+            `revocation signer ${env.signer.address} is neither the principal nor the agent`
+        );
     }
 
     const canonInput = {