@openvtc/trust-tasks 0.12.17 → 0.13.0

package/src/_runtime/consume.ts

@@ -1,12 +1,20 @@
 /**
- * Inbound-document orchestration for SPEC.md §7.2 item 2 and items 4–8.
+ * Inbound-document orchestration for SPEC.md §7.2 item 2, items 4–8, and the
+ * two stateful checks — the freshness bound of item 4 and the
+ * duplicate-execution record of item 11.
  *
  * Hand-written. Mirrors `consume.rs` in trust-tasks-rs, deliberately closely:
  * a TypeScript consumer and a Rust one must reach the same verdict on the same
  * document, or the two reference implementations disagree about what conforms.
  *
  * ```ts
- * import { consumeInbound, StaticTransport, AclGrant_v0_1 } from "@openvtc/trust-tasks";
+ * import {
+ *   consequentialChecks, consumeInbound, InMemoryReplayGuard,
+ *   StaticTransport, AclGrant_v0_1,
+ * } from "@openvtc/trust-tasks";
+ *
+ * // One guard per consumer, not one per document: it *is* the record.
+ * const guard = new InMemoryReplayGuard();
  *
  * const outcome = await consumeInbound({
  *   transport,
@@ -14,6 +22,8 @@
  *   proofPolicy: { kind: "verify", verify: myVerifier },
  *   // ajv, or whatever validator you already run — see PayloadPolicy.
  *   payloadPolicy: { kind: "validate", validate: myValidator },
+ *   // acl/grant is consequential: a replayed envelope must not grant twice.
+ *   checks: consequentialChecks(guard),
  *   doc,
  *   myVid: "did:web:maintainer.example",
  *   now: Date.now(),
@@ -27,6 +37,11 @@
  *   case "rejected":   emit(outcome.error); break;
  *   case "suppressed": logSuppressed(); break;
  *   case "accepted":   break; // fire-and-forget: nothing to emit
+ *   // §7.2 item 11: already executed. Not an error — return the prior result
+ *   // if there is one, otherwise emit nothing.
+ *   case "duplicate":
+ *     if (outcome.priorResponse !== undefined) emit(outcome.priorResponse);
+ *     break;
  * }
  * ```
  *
@@ -55,6 +70,19 @@ import {
   type SpecPolicy,
   type TrustTaskDocument,
 } from "./document.js";
+import {
+  CONSEQUENTIAL_FRESHNESS,
+  DEFAULT_FRESHNESS,
+  STALE_WIRE_MESSAGE,
+  recordExpiry,
+  validateFreshness,
+  type FreshnessPolicy,
+} from "./freshness.js";
+import {
+  documentDigest,
+  type ReplayGuard,
+  type ReplayPolicy,
+} from "./replay.js";
 import {
   identityMismatchReason,
   reject,
@@ -63,6 +91,53 @@ import {
   type TransportHandler,
 } from "./transport.js";
 
+/**
+ * The two stateful §7.2 checks: the freshness bound over `issuedAt` /
+ * `expiresAt`, and the duplicate-execution record of item 11.
+ *
+ * They travel together because the spec ties them together. §7.2 (*Bounding
+ * the record*) makes the acceptance window and the record's retention **the
+ * same bound**. Passing them as one option is what stops a deployment
+ * configuring a five-minute record and an unbounded acceptance window, which
+ * reads as a working replay defence and is not one.
+ *
+ * Like {@link PayloadPolicy}, this is a *required* option. Whether the task a
+ * consumer implements is *consequential* (§2) is a decision only that consumer
+ * can make, and the failure mode of getting it wrong silently — an ACL grant
+ * applied twice by a mediator retry — is not one to discover after the fact.
+ */
+export interface ConsumeChecks {
+  /** Bounds the document in time (SPEC §4.2, §7.2 item 4). */
+  readonly freshness: FreshnessPolicy;
+  /** Applies (or knowingly disapplies) SPEC §7.2 item 11. */
+  readonly replay: ReplayPolicy;
+}
+
+/**
+ * The posture for a *consequential Trust Task* (§2): item 11 enforced against
+ * `guard`, and the bounded acceptance window that makes the record droppable.
+ *
+ * The right choice for any task whose execution grants access, moves value,
+ * discloses a secret, or otherwise cannot be undone by ignoring the next
+ * document.
+ */
+export function consequentialChecks(guard: ReplayGuard): ConsumeChecks {
+  return { freshness: CONSEQUENTIAL_FRESHNESS, replay: { kind: "guard", guard } };
+}
+
+/**
+ * The posture for a task that is **not** consequential, or whose specification
+ * "explicitly declares repeated execution safe and intended" — the narrow
+ * disapplication item 11 permits.
+ *
+ * Keeps no record. Still applies the default freshness policy, because a
+ * future-dated document and one with an empty validity interval are malformed
+ * whatever the task does.
+ */
+export function notConsequentialChecks(): ConsumeChecks {
+  return { freshness: DEFAULT_FRESHNESS, replay: { kind: "notConsequential" } };
+}
+
 /** Verifies a document's Data Integrity proof (SPEC §4.7). */
 export interface ProofVerifier {
   /** Resolve to `true` when the proof verifies against the in-band `issuer`. */
@@ -173,7 +248,32 @@ export type ConsumeOutcome<R> =
    * return type demanded a document or an error, and returning neither threw a
    * bare `TypeError` out of the pipeline. Emit nothing.
    */
-  | { kind: "accepted" };
+  | { kind: "accepted" }
+  /**
+   * SPEC §7.2 item 11: a document with this `id` and this content was already
+   * accepted for execution. **The handler was not called**, and the
+   * consequential effect did not happen a second time. This is the §8.4 retry
+   * being absorbed, which is what makes retrying safe.
+   *
+   * **Not an error.** §7.2 (*Disposition of a duplicate*): "In no case is a
+   * duplicate reported as `taskFailed`; the task did not fail, it already
+   * happened." Folding this into `rejected` would report a failure that did
+   * not occur.
+   *
+   * What to emit:
+   *
+   * - `priorResponse` present — emit it. It is the response document the first
+   *   execution produced (a success response, or a non-retryable error
+   *   response; tell them apart by its `type`), which §7.2 says the consumer
+   *   SHOULD return.
+   * - `priorResponse` absent, `inFlight === false` — the specification defines
+   *   no success response (§4.4.1 fire-and-forget), or the guard retains none.
+   *   Emit nothing: that silence is the correct disposition, not an error.
+   * - `inFlight === true` — the first execution has not finished. §7.2: the
+   *   consumer SHOULD "return or expose the existing execution state rather
+   *   than begin another".
+   */
+  | { kind: "duplicate"; priorResponse?: unknown; inFlight: boolean };
 
 /** Wire-safe message for the `rejectIfPresent` path. */
 export const PROOF_NOT_ACCEPTED_BY_POLICY =
@@ -186,6 +286,12 @@ export interface ConsumeOptions<P, R> {
   proofPolicy: ProofPolicy;
   /** §7.2 item 2. Required — see {@link PayloadPolicy} for why. */
   payloadPolicy: PayloadPolicy;
+  /**
+   * §7.2 item 4 (freshness) and item 11 (duplicate execution). Required — see
+   * {@link ConsumeChecks}. Use {@link consequentialChecks} or
+   * {@link notConsequentialChecks}.
+   */
+  checks: ConsumeChecks;
   doc: TrustTaskDocument<P>;
   /** This consumer's own VID, for the §7.2 item 5 recipient check. */
   myVid: string;
@@ -225,8 +331,19 @@ export interface ConsumeOptions<P, R> {
 export async function consumeInbound<P, R>(
   opts: ConsumeOptions<P, R>,
 ): Promise<ConsumeOutcome<R>> {
-  const { transport, spec, proofPolicy, payloadPolicy, doc, myVid, now, newErrorId, handler, clock } =
-    opts;
+  const {
+    transport,
+    spec,
+    proofPolicy,
+    payloadPolicy,
+    checks,
+    doc,
+    myVid,
+    now,
+    newErrorId,
+    handler,
+    clock,
+  } = opts;
 
   const route = (reason: RejectReason): ConsumeOutcome<R> => {
     const error = reject(transport, doc, newErrorId(), reason, clock);
@@ -246,6 +363,19 @@ export async function consumeInbound<P, R>(
     );
   }
 
+  // Same reasoning, for the check that decides whether a replayed envelope
+  // executes a second time. A JavaScript caller gets no compile-time check,
+  // and defaulting to "keep no record" would silently reproduce the defect
+  // this option exists to remove.
+  if (checks === undefined) {
+    throw new TypeError(
+      "consumeInbound: `checks` is required as of 0.12.18 (SPEC §7.2 items 4 and 11). " +
+        "Pass consequentialChecks(guard) for a task whose execution grants access, " +
+        "moves value or is otherwise irreversible, or notConsequentialChecks() to " +
+        "state that repeated execution of this task is safe and intended.",
+    );
+  }
+
   // §7.2 item 2 — payload schema. Runs first, in the spec's own order, and
   // before anything that reasons about what the payload means: a payload that
   // is not the shape the specification declares should be refused as malformed
@@ -278,6 +408,15 @@ export async function consumeInbound<P, R>(
   const basic = validateBasic(doc, now, myVid);
   if (basic !== null) return route(basic);
 
+  // §7.2 item 4, the other half — the freshness bound over `issuedAt`.
+  // `validateBasic` honours `expiresAt`, which is optional and which a
+  // producer sets for its own reasons; on its own it leaves a document stamped
+  // years ago, or years hence, indefinitely acceptable. It is also what bounds
+  // the replay record below: §7.2 makes the acceptance window and the record's
+  // retention one bound.
+  const fresh = validateFreshness(doc, now, checks.freshness);
+  if (fresh !== null) return route(fresh);
+
   // §7.2 item 6 — in-band vs transport-derived identity cross-check.
   const resolved = resolveParties(transport, doc);
   if ("error" in resolved) return route(identityMismatchReason(resolved.error));
@@ -293,9 +432,15 @@ export async function consumeInbound<P, R>(
           ok = false;
         }
         if (!ok) {
+          // A constant, never the verifier's own error text. SPEC §10.4
+          // extends the §8.1 identity rule to every code, and a verifier's
+          // vocabulary names DIDs it tried to resolve, whether a resolver
+          // answered, and what a fetched DID document contained — a
+          // resolver-reachability oracle for a sender who is, by construction,
+          // unauthenticated. Log the detail; do not send it.
           return route({
             code: "proofInvalid",
-            message: "proof verification failed",
+            message: PROOF_INVALID_WIRE_MESSAGE,
             retryable: false,
           });
         }
@@ -317,13 +462,125 @@ export async function consumeInbound<P, R>(
   const policy = enforceSpecPolicy(doc, spec);
   if (policy !== null) return route(policy);
 
+  // §7.2 item 11 — the duplicate-execution record. Deliberately **last**:
+  // claiming the `id` marks the document as accepted for execution, and a
+  // document some earlier check refuses was never accepted. Claiming first
+  // would burn the `id` on every malformed or unauthorised arrival, so a
+  // corrected resend under the same `id` would come back `idConflict` forever
+  // — and an attacker could pre-burn an `id` it had merely observed.
+  let claim: { guard: ReplayGuard; digest: string } | undefined;
+  if (checks.replay.kind === "guard") {
+    const { guard } = checks.replay;
+    const digest = documentDigest(doc);
+
+    // §7.2 (*Bounding the record*): "A consumer that can establish neither an
+    // `expiresAt` nor an age for a document has no window in which to place
+    // it, and MUST NOT execute a consequential Trust Task on it." A guard
+    // asked to retain a record forever is not a guard, so refuse rather than
+    // pretend.
+    const retainUntil = recordExpiry(doc, checks.freshness, now);
+    if (retainUntil === undefined) {
+      return route({ code: "expired", message: STALE_WIRE_MESSAGE, retryable: false });
+    }
+
+    let verdict;
+    try {
+      verdict = await guard.claim(doc.id, digest, retainUntil, now);
+    } catch {
+      // Fail closed. A consumer that cannot consult its record has not
+      // satisfied item 11, and executing anyway is exactly the double
+      // execution the rule forbids. `unavailable` is retryable, which is the
+      // honest answer: the producer's bit-for-bit resend will be absorbed
+      // correctly once the store is back. The thrown detail — a hostname, a
+      // connection string — stays out of the message, per §10.4.
+      return route({
+        code: "unavailable",
+        message: REPLAY_RECORD_UNAVAILABLE,
+        retryable: true,
+      });
+    }
+
+    switch (verdict.kind) {
+      case "duplicate":
+        return verdict.priorResponse === undefined
+          ? { kind: "duplicate", inFlight: verdict.inFlight }
+          : { kind: "duplicate", priorResponse: verdict.priorResponse, inFlight: verdict.inFlight };
+      case "conflict":
+        return route({
+          code: "idConflict",
+          message: ID_CONFLICT_WIRE_MESSAGE,
+          retryable: false,
+        });
+      case "fresh":
+        claim = { guard, digest };
+        break;
+    }
+  }
+
   const result = await handler(doc, resolved.parties);
-  if (result === undefined || result === null) return { kind: "accepted" };
-  return isErrorResponse(result)
-    ? { kind: "rejected", error: result }
-    : { kind: "handled", response: result as TrustTaskDocument<R> };
+
+  if (result === undefined || result === null) {
+    // Fire-and-forget: nothing to cache, but the claim stands — the effect
+    // happened, and item 11 is about the effect, not about the response.
+    await settle(claim, doc.id, undefined);
+    return { kind: "accepted" };
+  }
+  if (isErrorResponse(result)) {
+    // §8.4: a retryable refusal has just invited the producer to re-send this
+    // document bit-for-bit. Holding the claim would answer that invited retry
+    // with the cached failure forever. A non-retryable refusal is final, so
+    // the record stands and a replay is answered with the same determination.
+    if (result.payload.retryable === true) {
+      await claim?.guard.release?.(doc.id, claim.digest);
+    } else {
+      await settle(claim, doc.id, result);
+    }
+    return { kind: "rejected", error: result };
+  }
+  await settle(claim, doc.id, result);
+  return { kind: "handled", response: result as TrustTaskDocument<R> };
+}
+
+/**
+ * Record the response for a completed execution, best-effort.
+ *
+ * The effect has already happened, so a guard that cannot cache the response
+ * cannot un-happen it. The record of the *claim* is what item 11 needs and it
+ * is already written; all that is lost is the ability to hand the same
+ * response back, and the duplicate is still absorbed. Guards should log their
+ * own failures — there is nowhere to report this from here.
+ */
+async function settle(
+  claim: { guard: ReplayGuard; digest: string } | undefined,
+  id: string,
+  response: unknown,
+): Promise<void> {
+  if (claim === undefined) return;
+  try {
+    await claim.guard.recordResponse?.(id, response);
+  } catch {
+    /* see above */
+  }
 }
 
+/**
+ * Wire message for `proofInvalid`.
+ *
+ * Constant by design — see the §10.4 note at the rejection site. The Rust
+ * counterpart is `PROOF_INVALID_WIRE_MESSAGE` in `trust-tasks-rs`, kept equal.
+ */
+export const PROOF_INVALID_WIRE_MESSAGE = "proof verification failed";
+
+/** Wire message for `idConflict` (SPEC §7.2 item 11, §8.3). */
+export const ID_CONFLICT_WIRE_MESSAGE =
+  "a different document has already been accepted under this id (SPEC §7.2 item 11)";
+
+/**
+ * Wire message for a replay-record outage. A constant, so a store's hostname
+ * or connection string never reaches the wire (SPEC §10.4).
+ */
+export const REPLAY_RECORD_UNAVAILABLE = "temporarily unavailable";
+
 /**
  * Whether a handler returned an error response rather than a success response.
  *

package/src/_runtime/document.ts

@@ -195,10 +195,23 @@ export interface RejectReason {
 /**
  * The Type URI a consumer emits error responses under.
  *
- * `0.3`, because this runtime populates the `inResponseTo` member of §8.2 and
- * `0.2`'s payload schema is `additionalProperties: false` — a document carrying
- * it would not validate as `0.2`. Per §5.2 forward-minor compatibility a `0.2`
- * consumer SHOULD accept it.
+ * **The single source of truth for the emitted `trust-task-error` version on
+ * this side.** Three different answers were in circulation — this runtime and
+ * `trust-tasks-rs` emitted `0.5`, the HTTPS server emitted `0.2`, and the
+ * READMEs described `0.1` — so a producer could not tell from the
+ * documentation which schema an error response would validate against. Build
+ * error responses with `rejectWith` / `rejectWithRecipient`, or read the URI
+ * from here; do not spell it out again.
+ *
+ * The Rust counterpart is `trust_task_error_type_uri()` in `trust-tasks-rs`,
+ * kept equal to this value.
+ *
+ * `0.5` because this runtime populates the `inResponseTo` member of §8.2 and
+ * can emit `idConflict` (§8.3), which is absent from `0.3`'s code enum and does
+ * not match its extended-code pattern — a document carrying it would not
+ * validate as `0.3`. Per §5.2 forward-minor compatibility a `0.3` consumer
+ * SHOULD accept it. (This comment said `0.3` while the value said `0.5`: the
+ * value moved and the prose did not.)
  */
 export const TRUST_TASK_ERROR_TYPE_URI = "https://trusttasks.org/spec/trust-task-error/0.5";
 

package/src/_runtime/freshness.ts

@@ -0,0 +1,183 @@
+/**
+ * Freshness bounds over `issuedAt` / `expiresAt` (SPEC §4.2, §7.2).
+ *
+ * Mirrors `freshness.rs` in trust-tasks-rs, deliberately closely: a TypeScript
+ * consumer and a Rust one must reach the same verdict on the same document.
+ *
+ * Until this module, the only temporal check either runtime made was §7.2
+ * item 4 — `expiresAt`, and only where the producer chose to set it.
+ * `issuedAt` was carried on the type and looked at by nobody. That accepted a
+ * document stamped a year in the future (for the whole of that year), and one
+ * whose `expiresAt` sat at or before its own `issuedAt` — a validity interval
+ * that never contained a valid instant.
+ *
+ * It is also what makes {@link ReplayGuard} implementable. SPEC §7.2
+ * (*Bounding the record*) ties the duplicate-execution record to the
+ * acceptance window and says the two bounds are the same bound: a consumer
+ * "**MUST NOT** accept for execution a document older than the window over
+ * which it retains records". Without {@link FreshnessPolicy.maxAgeMs} there is
+ * no window, so a record for a document carrying no `expiresAt` would have to
+ * be kept forever.
+ */
+
+import type { RejectReason, TrustTaskDocument } from "./document.js";
+
+/** The clock-skew tolerance SPEC §4.2 sanctions ("typically ≤ 60s"), in ms. */
+export const DEFAULT_SKEW_MS = 60_000;
+
+/**
+ * The acceptance window {@link consequentialFreshness} applies, in ms.
+ *
+ * Five minutes survives a mediator queue, a retry with backoff and a modest
+ * clock disagreement, and keeps the record it bounds small. A deployment whose
+ * transport buffers for longer must widen it *and* widen its guard's retention
+ * to match — §7.2 makes them one bound.
+ */
+export const DEFAULT_MAX_AGE_MS = 5 * 60_000;
+
+/** How a consumer bounds a document in time before acting on it. */
+export interface FreshnessPolicy {
+  /**
+   * Tolerance applied to the document's timestamps against this consumer's
+   * clock, per SPEC §4.2. Applied to the future-dating check and to
+   * {@link maxAgeMs}; **not** to `expiresAt`, which `validateBasic` compares
+   * against the raw `now` it is given.
+   */
+  readonly skewMs: number;
+  /**
+   * Oldest `issuedAt` this consumer accepts, measured back from `now`.
+   * `undefined` means unbounded — the pre-existing behaviour, and the only
+   * setting under which a document carrying neither timestamp is acceptable.
+   */
+  readonly maxAgeMs?: number;
+  /** Reject a document carrying no `issuedAt`, with `malformedRequest`. */
+  readonly requireIssuedAt?: boolean;
+}
+
+/**
+ * The minimum every consumer should apply: reject a future-dated document and
+ * one whose stated validity interval is empty. No conforming producer emits
+ * either, so this costs a correct deployment nothing.
+ *
+ * Deliberately sets no `maxAgeMs` — an acceptance window depends on how long
+ * the transport may hold a message, which is a deployment fact, and a library
+ * that guessed one would start refusing documents that had arrived for years.
+ */
+export const DEFAULT_FRESHNESS: FreshnessPolicy = { skewMs: DEFAULT_SKEW_MS };
+
+/**
+ * The posture SPEC §7.2 (*Bounding the record*) describes for a *consequential
+ * Trust Task*: `issuedAt` REQUIRED and a bounded acceptance window, so every
+ * accepted document sits inside a window a {@link ReplayGuard} can retain a
+ * record for.
+ */
+export const CONSEQUENTIAL_FRESHNESS: FreshnessPolicy = {
+  skewMs: DEFAULT_SKEW_MS,
+  maxAgeMs: DEFAULT_MAX_AGE_MS,
+  requireIssuedAt: true,
+};
+
+/** Wire-safe reason for a `malformedRequest` from a future-dated `issuedAt`. */
+export const FUTURE_ISSUED_AT =
+  "issuedAt is in the future beyond the consumer's skew tolerance (SPEC §4.2)";
+
+/** Wire-safe reason for a `malformedRequest` from `expiresAt <= issuedAt`. */
+export const EXPIRY_NOT_AFTER_ISSUANCE =
+  "expiresAt is not after issuedAt: the document states an empty validity interval (SPEC §4.2)";
+
+/** Wire-safe reason for a `malformedRequest` from a missing `issuedAt`. */
+export const ISSUED_AT_REQUIRED =
+  "issuedAt is required by consumer policy (SPEC §7.2, bounding the duplicate-execution record)";
+
+/**
+ * Wire message for a document outside the consumer's acceptance window.
+ *
+ * A constant, not a rendering of the window or the consumer's clock: §10.4
+ * keeps consumer-side state off the wire, and echoing the delta would turn
+ * every rejection into a remote `ntpdate` — and a probe for the window's exact
+ * boundary — for an unauthenticated sender.
+ */
+export const STALE_WIRE_MESSAGE = "document is outside the consumer's acceptance window (SPEC §7.2)";
+
+/**
+ * Apply `policy` to this document's `issuedAt` / `expiresAt`. Returns `null`
+ * when the document is acceptable.
+ *
+ * This is the freshness half of SPEC §7.2 item 4 that `validateBasic` does not
+ * cover. {@link consumeInbound} calls it for you.
+ *
+ * @param now Milliseconds since the epoch, as from `Date.now()`.
+ */
+export function validateFreshness<P>(
+  doc: TrustTaskDocument<P>,
+  now: number,
+  policy: FreshnessPolicy,
+): RejectReason | null {
+  const malformed = (message: string): RejectReason => ({
+    code: "malformedRequest",
+    message,
+    retryable: false,
+  });
+  const stale = (): RejectReason => ({
+    code: "expired",
+    message: STALE_WIRE_MESSAGE,
+    retryable: false,
+  });
+
+  if (doc.issuedAt !== undefined) {
+    const issuedAt = Date.parse(doc.issuedAt);
+    if (Number.isNaN(issuedAt)) {
+      return malformed("issuedAt is not a valid RFC 3339 timestamp");
+    }
+    if (issuedAt > now + policy.skewMs) return malformed(FUTURE_ISSUED_AT);
+
+    if (doc.expiresAt !== undefined) {
+      const expiresAt = Date.parse(doc.expiresAt);
+      // A malformed `expiresAt` is `validateBasic`'s to report; skip it here
+      // rather than raise a second, differently-worded rejection for it.
+      if (!Number.isNaN(expiresAt) && expiresAt <= issuedAt) {
+        return malformed(EXPIRY_NOT_AFTER_ISSUANCE);
+      }
+    }
+
+    if (policy.maxAgeMs !== undefined && issuedAt + policy.maxAgeMs + policy.skewMs < now) {
+      return stale();
+    }
+    return null;
+  }
+
+  if (policy.requireIssuedAt === true) return malformed(ISSUED_AT_REQUIRED);
+
+  // No `issuedAt`. A policy with a window cannot place the document in it
+  // unless the producer supplied an `expiresAt` instead (SPEC §7.2, *Bounding
+  // the record*).
+  if (policy.maxAgeMs !== undefined && doc.expiresAt === undefined) return stale();
+  return null;
+}
+
+/**
+ * The instant past which a replay record for `doc` may be dropped — the end of
+ * this consumer's willingness to execute it, which SPEC §7.2 makes the same
+ * instant as the end of the record's required retention.
+ *
+ * `expiresAt` fixes it where present; otherwise `issuedAt + maxAgeMs`.
+ * `undefined` means this policy places no bound on the document, in which case
+ * a consumer **MUST NOT** execute a consequential task on it — there is no
+ * window in which to keep the record.
+ */
+export function recordExpiry<P>(
+  doc: TrustTaskDocument<P>,
+  policy: FreshnessPolicy,
+  now: number,
+): number | undefined {
+  if (doc.expiresAt !== undefined) {
+    const expiresAt = Date.parse(doc.expiresAt);
+    if (!Number.isNaN(expiresAt)) return expiresAt;
+  }
+  if (policy.maxAgeMs === undefined) return undefined;
+  const issuedAt = doc.issuedAt === undefined ? NaN : Date.parse(doc.issuedAt);
+  // Fall back to `now` when the producer stamped no usable `issuedAt`: the
+  // record then lives a full window from first sight, which is the longest the
+  // document could still be arriving from a queue.
+  return (Number.isNaN(issuedAt) ? now : issuedAt) + policy.maxAgeMs;
+}

package/src/_runtime/index.ts

@@ -51,9 +51,15 @@ export {
 } from "./transport.js";
 
 export {
+  ID_CONFLICT_WIRE_MESSAGE,
+  PROOF_INVALID_WIRE_MESSAGE,
   PROOF_NOT_ACCEPTED_BY_POLICY,
+  REPLAY_RECORD_UNAVAILABLE,
+  consequentialChecks,
   consumeInbound,
+  notConsequentialChecks,
   refuse,
+  type ConsumeChecks,
   type ConsumeOptions,
   type ConsumeOutcome,
   type PayloadPolicy,
@@ -61,3 +67,27 @@ export {
   type ProofPolicy,
   type ProofVerifier,
 } from "./consume.js";
+
+export { canonicalJson, sha256Hex } from "./canonical.js";
+
+export {
+  CONSEQUENTIAL_FRESHNESS,
+  DEFAULT_FRESHNESS,
+  DEFAULT_MAX_AGE_MS,
+  DEFAULT_SKEW_MS,
+  EXPIRY_NOT_AFTER_ISSUANCE,
+  FUTURE_ISSUED_AT,
+  ISSUED_AT_REQUIRED,
+  STALE_WIRE_MESSAGE,
+  recordExpiry,
+  validateFreshness,
+  type FreshnessPolicy,
+} from "./freshness.js";
+
+export {
+  InMemoryReplayGuard,
+  documentDigest,
+  type ReplayGuard,
+  type ReplayPolicy,
+  type ReplayVerdict,
+} from "./replay.js";