@orangecheck/agent-core 2.6.0 → 2.7.0

package/README.md

@@ -114,7 +114,9 @@ if (!result.ok) throw new Error(result.code + ': ' + result.message);
 ### Verification (§SPEC 8)
 
 - `verifyDelegation({ envelope, revocations | skipRevocationCheck, verifyBip322, now?, skipTemporalCheck?, scopeMode? })`
-- `verifyAction({ action, delegation, revocations | skipRevocationCheck, verifyBip322, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })`
+- `verifyAction({ action, delegation, revocations | skipRevocationCheck, verifyBip322, now?, maxSkewMs?, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })` — the live check, as of `now` (default: the current time). Every link of the chain must be in force at `now`, a revocation in effect at or before `now` refuses the action (`E_REVOKED`), and `signed_at` must lie within `maxSkewMs` of `now` (default 120 s; else `E_STALE`). The result's `asOf` is `{ basis: 'now', now }`.
+- `verifyActionAsOfSignedAt({ … })` — an audit of a past action, as of its own `signed_at`. The agent chooses that time, so `asOf.anchored` says whether a verified OTS anchor fixes it. Never use it to decide whether to act now.
+- `createReplayGuard(maxSkewMs?)` — `firstUse(action, now?)` is true once per action id. It keeps each id until `signed_at + maxSkewMs`, as long as the action could pass `verifyAction`. One process only; across instances keep the same record in a shared store. Replay is the caller's to stop: `verifyAction` keeps no state.
 - `verifyRevocation({ envelope, delegation, verifyBip322 })` — the principal may always revoke; `revocation.holders` can only add the agent
 - `verifyOtsAnchor(proofB64, blockHeight, blockHash, envelopeId)` — an anchor orders an action against a revocation only when this returns true
 - `verifyFederationRevocation({ envelope, delegation, verifyBip322 })`

package/dist/index.d.mts

@@ -7,6 +7,7 @@ import { SealInput, DeviceRecord, UnsealInput } from '@orangecheck/lock-core';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
 
 declare const DEFAULT_MAX_CHAIN_DEPTH = 5;
+declare const DEFAULT_MAX_SKEW_MS = 120000;
 interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
@@ -40,8 +41,15 @@ interface VerifyActionInput extends VerifyBase {
         device_id: string;
         secretKey: Uint8Array;
     };
+    now?: Date;
+    maxSkewMs?: number;
 }
+type VerifyActionAsOfSignedAtInput = Omit<VerifyActionInput, 'now' | 'maxSkewMs'>;
 declare function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult>;
+declare function verifyActionAsOfSignedAt(input: VerifyActionAsOfSignedAtInput): Promise<VerifyActionResult>;
+declare function createReplayGuard(maxSkewMs?: number): {
+    firstUse(action: Pick<ActionEnvelope, 'id' | 'signed_at'>, now?: Date): boolean;
+};
 interface VerifyRevocationInput extends VerifyBase {
     envelope: RevocationEnvelope;
     delegation: ChainLink;
@@ -179,4 +187,4 @@ declare class ScopeNotGrantedError extends Error {
 }
 declare function assertScopeGranted(delegation: ScopeBearingDelegation, scopeExercised: string, fnName: string): void;
 
-export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DEFAULT_MAX_SKEW_MS, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionAsOfSignedAtInput, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, createReplayGuard, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyActionAsOfSignedAt, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { SealInput, DeviceRecord, UnsealInput } from '@orangecheck/lock-core';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
 
 declare const DEFAULT_MAX_CHAIN_DEPTH = 5;
+declare const DEFAULT_MAX_SKEW_MS = 120000;
 interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
@@ -40,8 +41,15 @@ interface VerifyActionInput extends VerifyBase {
         device_id: string;
         secretKey: Uint8Array;
     };
+    now?: Date;
+    maxSkewMs?: number;
 }
+type VerifyActionAsOfSignedAtInput = Omit<VerifyActionInput, 'now' | 'maxSkewMs'>;
 declare function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult>;
+declare function verifyActionAsOfSignedAt(input: VerifyActionAsOfSignedAtInput): Promise<VerifyActionResult>;
+declare function createReplayGuard(maxSkewMs?: number): {
+    firstUse(action: Pick<ActionEnvelope, 'id' | 'signed_at'>, now?: Date): boolean;
+};
 interface VerifyRevocationInput extends VerifyBase {
     envelope: RevocationEnvelope;
     delegation: ChainLink;
@@ -179,4 +187,4 @@ declare class ScopeNotGrantedError extends Error {
 }
 declare function assertScopeGranted(delegation: ScopeBearingDelegation, scopeExercised: string, fnName: string): void;
 
-export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DEFAULT_MAX_SKEW_MS, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionAsOfSignedAtInput, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, createReplayGuard, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyActionAsOfSignedAt, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };

package/dist/index.js

@@ -411,6 +411,7 @@ function hasPrivateScopes(envelope) {
 
 // src/verify.ts
 var DEFAULT_MAX_CHAIN_DEPTH = 5;
+var DEFAULT_MAX_SKEW_MS = 12e4;
 var AgentError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -545,6 +546,12 @@ async function verifyDelegation(input) {
   };
 }
 async function verifyAction(input) {
+  return verifyActionAt(input, input.now ?? /* @__PURE__ */ new Date());
+}
+async function verifyActionAsOfSignedAt(input) {
+  return verifyActionAt(input, null);
+}
+async function verifyActionAt(input, now) {
   const a = input.action;
   const d = input.delegation;
   const chain = input.subdelegationChain ?? [];
@@ -622,6 +629,17 @@ async function verifyAction(input) {
   if (signed < issued || signed >= expires) {
     return err("E_OUT_OF_WINDOW", `action.signed_at ${a.signed_at} is outside leaf window [${leaf.issued_at}, ${leaf.expires_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}`);
+      }
+    }
+  }
   if (!leaf.scopes) {
     return err("E_SCOPES_NEITHER_PROVIDED", "leaf has no plaintext scopes after hydration");
   }
@@ -670,9 +688,21 @@ async function verifyAction(input) {
         if (revocationPrecedes(rev, revAnchor, a, actionAnchor)) {
           return err("E_REVOKED", `chain link ${link.id} was revoked by ${rev.id} before action was signed`);
         }
+        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}`);
+        }
       }
     }
   }
+  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()}`
+      );
+    }
+  }
   if (input.content) {
     const actualHash = "sha256:" + canonical.hexEncode(sha256.sha256(input.content));
     if (actualHash !== a.content.hash) {
@@ -700,7 +730,20 @@ async function verifyAction(input) {
     delegation: rootHydrated,
     chain: hydratedChain,
     scopeExercised: exercised,
-    anchor
+    anchor,
+    asOf: now ? { basis: "now", now: now.toISOString() } : { basis: "signed_at", signedAt: a.signed_at, anchored: actionAnchor !== null }
+  };
+}
+function createReplayGuard(maxSkewMs = DEFAULT_MAX_SKEW_MS) {
+  const keepUntil = /* @__PURE__ */ new Map();
+  return {
+    firstUse(action, now = /* @__PURE__ */ 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;
+    }
   };
 }
 async function hydrateSubdelegationScopes(sub, input) {
@@ -1250,6 +1293,7 @@ Object.defineProperty(exports, "hexEncode", {
 });
 exports.AgentError = AgentError;
 exports.DEFAULT_MAX_CHAIN_DEPTH = DEFAULT_MAX_CHAIN_DEPTH;
+exports.DEFAULT_MAX_SKEW_MS = DEFAULT_MAX_SKEW_MS;
 exports.ENVELOPE_VERSION = ENVELOPE_VERSION;
 exports.REGISTERED_SCOPES = REGISTERED_SCOPES;
 exports.ScopeNotGrantedError = ScopeNotGrantedError;
@@ -1271,6 +1315,7 @@ exports.computeDelegationId = computeDelegationId;
 exports.computeFederationDescriptorId = computeFederationDescriptorId;
 exports.computeRevocationId = computeRevocationId;
 exports.computeSubdelegationId = computeSubdelegationId;
+exports.createReplayGuard = createReplayGuard;
 exports.decodeScopesPayload = decodeScopesPayload;
 exports.delegationCanonicalBytes = delegationCanonicalBytes;
 exports.delegationCanonicalMessage = delegationCanonicalMessage;
@@ -1289,6 +1334,7 @@ exports.subdelegationCanonicalMessage = subdelegationCanonicalMessage;
 exports.unsealScopes = unsealScopes;
 exports.validateScope = validateScope;
 exports.verifyAction = verifyAction;
+exports.verifyActionAsOfSignedAt = verifyActionAsOfSignedAt;
 exports.verifyDelegation = verifyDelegation;
 exports.verifyFederationDelegation = verifyFederationDelegation;
 exports.verifyFederationRevocation = verifyFederationRevocation;