@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/public-control/grant-indexer.mjs

@@ -0,0 +1,296 @@
+// Oracle Control — grant audit + active-permission indexer (Slice F).
+//
+// Deterministic, storage-agnostic reconstruction of grant state from an
+// append-only event log. Oracle Control is DETERMINISTIC AUTHORIZATION: this
+// module never guesses, never consults Oracle Router (advisory), and never
+// keeps its own mutable state. The chain (or whatever emits the event log)
+// is the sole source of truth; this file is a pure projection of that log
+// plus an explicit reference `now`.
+//
+// Hard boundaries for this file:
+//   - No imports outside src/public-control/policy-schema.mjs (grant identity
+//     + expiry helpers are reused from there, never duplicated).
+//   - No import from the private executor stack, no RPC/chain calls, no I/O.
+//   - Pure functions only: reconstructGrantIndex(events, opts) always returns
+//     the same result for the same (events, opts.now) — same events replayed
+//     after a "restart" (fresh process, no cache, no prior in-memory state)
+//     reconstruct the identical active set. Input array order never matters.
+//   - Audit/output records are built from an explicit field whitelist only.
+//     Unknown/extra properties on raw events (or on a rejected grant payload)
+//     are NEVER copied into output, so a poisoned event can't smuggle a
+//     secret (API key, session key, keystore path, ...) into the index.
+//
+// Event log shape (each entry is a plain object; unknown extra fields are
+// ignored, never echoed):
+//   { type: "grantCreated",   at: <unix seconds>, grant: <raw grant>, grantId?: <string> }
+//   { type: "grantActivated", at: <unix seconds>, grantId: <string> }
+//   { type: "grantRevoked",   at: <unix seconds>, grantId: <string>, reason?: <string> }
+//   { type: "grantExpired",   at: <unix seconds>, grantId: <string> }
+//
+// `grantId` on a grantCreated event is optional: when omitted it is derived
+// from the grant payload itself via policy-schema's grantId() (content
+// addressed identity). When supplied it is cross-checked against the derived
+// id and the event is rejected on mismatch (fail closed, no id spoofing).
+//
+// Status precedence (revocation beats expiry beats activity — mirrors the
+// same precedence used by session-key-model.mjs's sessionStatus): a grant
+// that was revoked and later would also have expired still reports revoked.
+//   REVOKED > EXPIRED > ACTIVE > PENDING > UNKNOWN
+// Only ACTIVE grants are ever included in the `active` set.
+
+import { normalizeGrant, grantId as computeGrantId, isExpired, GrantValidationError } from "./policy-schema.mjs";
+
+export const GRANT_EVENT_TYPES = Object.freeze([
+  "grantCreated",
+  "grantActivated",
+  "grantRevoked",
+  "grantExpired",
+]);
+
+export const GRANT_STATUS = Object.freeze({
+  ACTIVE: "active",
+  PENDING: "pending",
+  REVOKED: "revoked",
+  EXPIRED: "expired",
+  UNKNOWN: "unknown",
+  INVALID: "invalid",
+});
+
+/** Fields ever allowed into an audit/output record. Nothing outside this
+ *  whitelist can reach the returned index, no matter what a raw event or
+ *  grant payload carries. All of these are public-by-design fields already
+ *  enforced by policy-schema.mjs's REQUIRED_FIELDS. */
+const GRANT_SUMMARY_FIELDS = Object.freeze([
+  "chainId",
+  "agentAddress",
+  "accountAddress",
+  "actions",
+  "targets",
+  "maxValueWei",
+  "maxGasWei",
+  "maxSlippageBps",
+  "expiresAt",
+  "nonce",
+  "revocationKey",
+]);
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+function toUnixSeconds(v) {
+  if (typeof v === "bigint") return Number(v);
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v.trim()))) {
+    return Number(v.trim());
+  }
+  return null;
+}
+
+function toSafeString(v, maxLen = 512) {
+  if (typeof v !== "string") return null;
+  const s = v.trim();
+  if (!s) return null;
+  return s.length > maxLen ? s.slice(0, maxLen) : s;
+}
+
+function grantSummary(normalizedGrant) {
+  const out = {};
+  for (const field of GRANT_SUMMARY_FIELDS) out[field] = normalizedGrant[field];
+  return out;
+}
+
+/**
+ * Parse one raw event into a strictly-whitelisted internal shape. Never
+ * throws. Extra/unknown properties on `raw` are silently dropped (this is
+ * the point — it's the no-secret-leak boundary for whatever noise a chain
+ * indexer/relay might attach to an event object).
+ *
+ * Returns { ok: true, event } or { ok: false, error: { type, at, grantId, message } }.
+ */
+function parseEvent(raw, opts) {
+  if (!isPlainObject(raw)) {
+    return { ok: false, error: { type: null, at: null, grantId: null, message: "event must be a plain object" } };
+  }
+
+  const type = typeof raw.type === "string" ? raw.type : null;
+  const at = toUnixSeconds(raw.at);
+  const grantIdHint = typeof raw.grantId === "string" && raw.grantId.trim() ? raw.grantId.trim() : null;
+
+  if (!GRANT_EVENT_TYPES.includes(type)) {
+    return { ok: false, error: { type, at, grantId: grantIdHint, message: `unknown event type "${String(type)}"` } };
+  }
+  if (at == null) {
+    return { ok: false, error: { type, at: null, grantId: grantIdHint, message: "event.at must be a unix-seconds number" } };
+  }
+
+  if (type === "grantCreated") {
+    if (!isPlainObject(raw.grant)) {
+      return { ok: false, error: { type, at, grantId: grantIdHint, message: "grantCreated requires a grant payload" } };
+    }
+    let normalized;
+    try {
+      // Identity + shape validation only — deliberately WITHOUT opts.now, so
+      // a grant that has since expired can still be identified/reconstructed
+      // (liveness is evaluated separately against the caller's `now`).
+      normalized = normalizeGrant(raw.grant, { allowWildcardActions: opts.allowWildcardActions });
+    } catch (e) {
+      const message = e instanceof GrantValidationError ? e.message : String(e?.message || e);
+      return { ok: false, error: { type, at, grantId: grantIdHint, message } };
+    }
+    const derivedId = computeGrantId(raw.grant, { allowWildcardActions: opts.allowWildcardActions });
+    if (grantIdHint && grantIdHint !== derivedId) {
+      return {
+        ok: false,
+        error: { type, at, grantId: grantIdHint, message: "grantId does not match content-derived grant identity (fail closed)" },
+      };
+    }
+    return { ok: true, event: { type, at, grantId: derivedId, grant: normalized } };
+  }
+
+  // grantActivated / grantRevoked / grantExpired all reference an existing
+  // grant purely by id — they never carry grant material.
+  if (!grantIdHint) {
+    return { ok: false, error: { type, at, grantId: null, message: `${type} requires a grantId` } };
+  }
+  const reason = type === "grantRevoked" ? toSafeString(raw.reason) : null;
+  return { ok: true, event: { type, at, grantId: grantIdHint, reason } };
+}
+
+function minOf(list) {
+  return list.length ? list.reduce((a, b) => Math.min(a, b)) : null;
+}
+
+/**
+ * Reconstruct the deterministic grant index from a raw event log.
+ *
+ * @param {object[]} events        raw event log (any order, any origin)
+ * @param {object} opts
+ * @param {number} opts.now        REQUIRED unix-seconds reference time. All
+ *                                 reconstruction is relative to this instant;
+ *                                 pass the same `now` to get the same result.
+ * @param {boolean} [opts.allowWildcardActions] forwarded to policy-schema.
+ *
+ * @returns {{
+ *   active: object[],       grants currently ACTIVE, sorted by grantId
+ *   historical: object[],   everything else (pending/revoked/expired/unknown/invalid), sorted by grantId
+ *   all: object[],          active + historical, sorted by grantId
+ *   invalidEvents: object[] malformed/rejected raw events (whitelisted fields only)
+ * }}
+ */
+export function reconstructGrantIndex(events, opts = {}) {
+  const now = toUnixSeconds(opts.now);
+  if (now == null) throw new Error("grant-indexer: opts.now (unix seconds) is required");
+  if (!Array.isArray(events)) throw new Error("grant-indexer: events must be an array");
+
+  const invalidEvents = [];
+  /** grantId -> { created: [], activated: [], revoked: [], expired: [] } */
+  const byId = new Map();
+
+  function bucket(id) {
+    if (!byId.has(id)) {
+      byId.set(id, { created: [], activated: [], revoked: [], expired: [] });
+    }
+    return byId.get(id);
+  }
+
+  for (const raw of events) {
+    const parsed = parseEvent(raw, opts);
+    if (!parsed.ok) {
+      invalidEvents.push(parsed.error);
+      continue;
+    }
+    const ev = parsed.event;
+    // Chain is source of truth for what has already happened: an event dated
+    // after the reconstruction instant hasn't occurred *yet* from this
+    // vantage point, so it is excluded rather than applied early.
+    if (ev.at > now) continue;
+
+    const b = bucket(ev.grantId);
+    if (ev.type === "grantCreated") {
+      // Same content-derived id => identical normalized grant; duplicate
+      // creations are idempotent. Keep the earliest-by-time occurrence so
+      // createdAt is stable and order-independent.
+      const existing = b.created[0];
+      if (!existing || ev.at < existing.at) b.created = [ev];
+    } else if (ev.type === "grantActivated") {
+      b.activated.push(ev);
+    } else if (ev.type === "grantRevoked") {
+      b.revoked.push(ev);
+    } else if (ev.type === "grantExpired") {
+      b.expired.push(ev);
+    }
+  }
+
+  const records = [];
+  for (const [id, b] of byId.entries()) {
+    const createdEvent = b.created[0] || null;
+    const createdAt = createdEvent ? createdEvent.at : null;
+    const activatedAt = minOf(b.activated.map((e) => e.at));
+    const revokedAt = minOf(b.revoked.map((e) => e.at));
+    const explicitExpiredAt = minOf(b.expired.map((e) => e.at));
+
+    const grant = createdEvent ? createdEvent.grant : null;
+    const schemaExpired = grant ? isExpired(grant, now) : false;
+    const expiredAt = explicitExpiredAt != null ? explicitExpiredAt : schemaExpired ? grant.expiresAt : null;
+
+    let status;
+    if (!createdEvent) {
+      // Lifecycle events (activated/revoked/expired) referencing a grantId
+      // we never saw a valid grantCreated for. Never active — there is no
+      // grant content to authorize against.
+      status = GRANT_STATUS.UNKNOWN;
+    } else if (b.revoked.length > 0) {
+      status = GRANT_STATUS.REVOKED;
+    } else if (explicitExpiredAt != null || schemaExpired) {
+      status = GRANT_STATUS.EXPIRED;
+    } else if (b.activated.length > 0) {
+      status = GRANT_STATUS.ACTIVE;
+    } else {
+      status = GRANT_STATUS.PENDING;
+    }
+
+    const record = {
+      grantId: id,
+      status,
+      createdAt,
+      activatedAt,
+      revokedAt,
+      expiredAt,
+      reason: b.revoked.length > 0 ? toSafeString(b.revoked.map((e) => e.reason).find(Boolean) || null) : null,
+      grant: grant ? grantSummary(grant) : null,
+    };
+    records.push(record);
+  }
+
+  records.sort((a, b) => (a.grantId < b.grantId ? -1 : a.grantId > b.grantId ? 1 : 0));
+  invalidEvents.sort((a, b) => {
+    const at = (a.at ?? -Infinity) - (b.at ?? -Infinity);
+    if (at !== 0) return at;
+    const ai = a.grantId || "";
+    const bi = b.grantId || "";
+    return ai < bi ? -1 : ai > bi ? 1 : 0;
+  });
+
+  const active = records.filter((r) => r.status === GRANT_STATUS.ACTIVE);
+  const historical = records.filter((r) => r.status !== GRANT_STATUS.ACTIVE);
+
+  return Object.freeze({
+    active: Object.freeze(active),
+    historical: Object.freeze(historical),
+    all: Object.freeze(records),
+    invalidEvents: Object.freeze(invalidEvents),
+  });
+}
+
+/** Convenience: is a single grant id active right now, per the given log? */
+export function isGrantActive(events, grantId, opts = {}) {
+  const { active } = reconstructGrantIndex(events, opts);
+  return active.some((r) => r.grantId === grantId);
+}
+
+/** Convenience: look up one grant's reconstructed record (or null). */
+export function getGrantRecord(events, grantId, opts = {}) {
+  const { all } = reconstructGrantIndex(events, opts);
+  return all.find((r) => r.grantId === grantId) || null;
+}

package/src/public-control/policy-render.mjs

@@ -0,0 +1,69 @@
+// Oracle Control — human-readable grant renderer (Slice A).
+//
+// Renders a validated public grant into deterministic plain text a user can
+// review before approving. Rendering is a PRESENTATION of the deterministic
+// policy only — it never adds, removes, or reinterprets authority, and it only
+// ever surfaces public grant material (no keys, tokens, paths, or secrets).
+//
+// Output is byte-for-byte deterministic for a given grant: fixed field order,
+// fixed labels, UTC timestamps derived purely from expiresAt, and the sha256
+// grant id from the canonical form. Tests assert exact output.
+
+import { normalizeGrant, grantId, isReadonlyAction, GRANT_VERSION } from "./policy-schema.mjs";
+
+const LABEL_WIDTH = 14;
+
+function row(label, value) {
+  return `${(label + ":").padEnd(LABEL_WIDTH)}${value}`;
+}
+
+/** Deterministic UTC ISO string from unix seconds. */
+function isoUtc(unixSeconds) {
+  return new Date(unixSeconds * 1000).toISOString();
+}
+
+/** "50 bps (0.50%)" — deterministic fixed-2 percentage. */
+export function formatBps(bps) {
+  return `${bps} bps (${(bps / 100).toFixed(2)}%)`;
+}
+
+/** Group wei digits for readability: 1000000 -> "1,000,000". Deterministic. */
+export function formatWei(weiString) {
+  const s = String(weiString);
+  return `${s.replace(/\B(?=(\d{3})+(?!\d))/g, ",")} wei`;
+}
+
+/**
+ * Render a grant as deterministic human-readable text.
+ * Validates/normalizes first (throws GrantValidationError on bad input), so a
+ * grant that cannot be rendered is a grant that cannot be authorized.
+ */
+export function renderGrant(input, opts = {}) {
+  const g = normalizeGrant(input, opts);
+  const id = grantId(g);
+  const readonlyOnly = g.actions.every((a) => isReadonlyAction(a));
+
+  const lines = [
+    "ORACLE CONTROL GRANT (deterministic authorization)",
+    "==================================================",
+    row("Grant ID", id),
+    row("Version", String(GRANT_VERSION)),
+    row("Chain", String(g.chainId)),
+    row("Agent", g.agentAddress),
+    row("Account", g.accountAddress),
+    row("Actions", g.actions.join(", ")),
+    row("Targets", g.targets.length ? g.targets.join(", ") : "(none — read/simulate only)"),
+    row("Max value", formatWei(g.maxValueWei)),
+    row("Max gas", formatWei(g.maxGasWei)),
+    row("Max slippage", formatBps(g.maxSlippageBps)),
+    row("Expires", `${isoUtc(g.expiresAt)} (unix ${g.expiresAt})`),
+    row("Nonce", g.nonce),
+    row("Revocation", g.revocationKey),
+    "--------------------------------------------------",
+    readonlyOnly
+      ? "Scope: read/simulate only — this grant cannot move funds."
+      : "Scope: includes state-changing actions bounded by the caps above.",
+    "Self-custodial: this grant contains public data only and can be revoked at any time via the revocation key.",
+  ];
+  return lines.join("\n");
+}

package/src/public-control/policy-schema.mjs

@@ -0,0 +1,322 @@
+// Oracle Control — public grant policy schema (Slice A).
+//
+// Oracle Control is DETERMINISTIC AUTHORIZATION: a grant either validates or it
+// does not, with no advisory judgement involved (that is Oracle Router's job,
+// and Router output must never gate anything here).
+//
+// This module is dependency-free (node builtins only, no npm packages) and
+// fully deterministic: same input object => same normalized grant => same
+// canonical string => same grant id, regardless of key order, address casing,
+// array ordering, or numeric representation (number / bigint / decimal string).
+//
+// Self-custody boundary: a grant only ever references PUBLIC material —
+// chain id, the agent's public address, the user's own account address,
+// action scopes, target contracts, spend/gas/slippage ceilings, expiry,
+// nonce, and a public revocation key identifier. Nothing here may carry or
+// derive private keys, bearer tokens, keystore paths, or session secrets.
+//
+// Fail-closed rules enforced by validateGrant / normalizeGrant:
+//   - every required field must be present (expiry, chain, agent, account, ...)
+//   - unknown fields are rejected (no smuggling extra authority)
+//   - broad wildcard actions are rejected by default ("*", "*:*", "verb:*")
+//   - empty targets are only allowed when EVERY action is read/simulate scoped
+//   - expiresAt is required and, when a reference `now` is supplied, must be
+//     strictly in the future
+
+import { createHash } from "node:crypto";
+
+export const GRANT_VERSION = 1;
+
+/** Every field is required. Order here is documentation only; canonical form
+ *  always sorts keys alphabetically. */
+export const REQUIRED_FIELDS = Object.freeze([
+  "chainId",
+  "agentAddress",
+  "accountAddress",
+  "actions",
+  "targets",
+  "maxValueWei",
+  "maxGasWei",
+  "maxSlippageBps",
+  "expiresAt",
+  "nonce",
+  "revocationKey",
+]);
+
+/** Action verbs that never touch state; only these may have empty targets. */
+export const READONLY_ACTION_VERBS = Object.freeze(["read", "simulate"]);
+
+export const MAX_SLIPPAGE_BPS = 10_000;
+export const MAX_GRANT_TTL_SECONDS = 24 * 60 * 60;
+export const MAX_NONCE_LENGTH = 128;
+export const MAX_REVOCATION_KEY_LENGTH = 256;
+export const MAX_ACTIONS = 64;
+export const MAX_TARGETS = 256;
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+// verb:resource — lowercase verb, resource may carry dots/dashes/underscores.
+const ACTION_RE = /^[a-z][a-z0-9_-]*:[a-z0-9._-]+$/;
+// wildcard-bearing action (only accepted when explicitly opted in, and never
+// with a wildcard verb).
+const ACTION_WILDCARD_RE = /^[a-z][a-z0-9_-]*:\*$/;
+const NONCE_RE = /^[A-Za-z0-9._:-]+$/;
+const REVOCATION_KEY_RE = /^[A-Za-z0-9._:-]+$/;
+const DECIMAL_RE = /^(0|[1-9][0-9]*)$/;
+
+export class GrantValidationError extends Error {
+  constructor(errors) {
+    const lines = errors.map((e) => `${e.field}: ${e.message}`);
+    super(`invalid grant (${errors.length} error${errors.length === 1 ? "" : "s"}): ${lines.join("; ")}`);
+    this.name = "GrantValidationError";
+    this.errors = errors;
+  }
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Parse a non-negative integer amount (number | bigint | decimal string)
+ *  into a canonical decimal string. Returns null when unparseable. */
+function toAmountString(v) {
+  if (typeof v === "bigint") {
+    return v >= 0n ? v.toString(10) : null;
+  }
+  if (typeof v === "number") {
+    if (!Number.isSafeInteger(v) || v < 0) return null;
+    return String(v);
+  }
+  if (typeof v === "string") {
+    const s = v.trim();
+    if (!DECIMAL_RE.test(s)) return null;
+    return s;
+  }
+  return null;
+}
+
+function toSafeInt(v) {
+  if (typeof v === "bigint") {
+    if (v < 0n || v > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+    return Number(v);
+  }
+  if (typeof v === "number") {
+    if (!Number.isSafeInteger(v) || v < 0) return null;
+    return v;
+  }
+  if (typeof v === "string") {
+    const s = v.trim();
+    if (!DECIMAL_RE.test(s)) return null;
+    const n = Number(s);
+    return Number.isSafeInteger(n) ? n : null;
+  }
+  return null;
+}
+
+/** True when the action verb is read-only (read/simulate). */
+export function isReadonlyAction(action) {
+  const verb = String(action).split(":")[0];
+  return READONLY_ACTION_VERBS.includes(verb);
+}
+
+/**
+ * Validate a grant. Never throws; returns { ok, errors, grant } where `grant`
+ * is the normalized form when ok, else null.
+ *
+ * Options:
+ *   allowWildcardActions  (default false) — permit "verb:*" actions. Broad
+ *                         wildcards ("*", "*:*", wildcard verbs) are ALWAYS
+ *                         rejected regardless of this flag.
+ *   now                   (unix seconds) — when provided, expiresAt must be
+ *                         strictly greater than it. Pass explicitly for
+ *                         deterministic validation; omitted means no liveness
+ *                         check (pure shape validation).
+ */
+export function validateGrant(input, opts = {}) {
+  const errors = [];
+  const push = (field, message) => errors.push({ field, message });
+
+  if (!isPlainObject(input)) {
+    push("grant", "grant must be a plain object");
+    return { ok: false, errors, grant: null };
+  }
+
+  // Fail closed on unknown fields.
+  for (const key of Object.keys(input)) {
+    if (!REQUIRED_FIELDS.includes(key)) push(key, "unknown field is not allowed");
+  }
+  for (const key of REQUIRED_FIELDS) {
+    if (!(key in input) || input[key] == null) push(key, "required field is missing");
+  }
+  if (errors.length) return { ok: false, errors, grant: null };
+
+  const out = {};
+
+  // chainId
+  const chainId = toSafeInt(input.chainId);
+  if (chainId == null || chainId <= 0) push("chainId", "must be a positive integer chain id");
+  else out.chainId = chainId;
+
+  // addresses
+  for (const field of ["agentAddress", "accountAddress"]) {
+    const v = input[field];
+    if (typeof v !== "string" || !ADDRESS_RE.test(v.trim())) {
+      push(field, "must be a 0x-prefixed 20-byte hex address");
+    } else {
+      out[field] = v.trim().toLowerCase();
+    }
+  }
+
+  // actions
+  if (!Array.isArray(input.actions) || input.actions.length === 0) {
+    push("actions", "must be a non-empty array of action scopes");
+  } else if (input.actions.length > MAX_ACTIONS) {
+    push("actions", `too many actions (max ${MAX_ACTIONS})`);
+  } else {
+    const actions = [];
+    for (const raw of input.actions) {
+      const a = typeof raw === "string" ? raw.trim() : null;
+      if (!a) {
+        push("actions", "action entries must be non-empty strings");
+        continue;
+      }
+      if (a.includes("*")) {
+        if (opts.allowWildcardActions === true && ACTION_WILDCARD_RE.test(a)) {
+          actions.push(a);
+        } else {
+          push("actions", `broad wildcard action "${a}" is rejected (fail closed)`);
+        }
+        continue;
+      }
+      if (!ACTION_RE.test(a)) {
+        push("actions", `malformed action "${a}" (expected verb:resource)`);
+        continue;
+      }
+      actions.push(a);
+    }
+    out.actions = [...new Set(actions)].sort();
+  }
+
+  // targets
+  if (!Array.isArray(input.targets)) {
+    push("targets", "must be an array of contract addresses");
+  } else if (input.targets.length > MAX_TARGETS) {
+    push("targets", `too many targets (max ${MAX_TARGETS})`);
+  } else {
+    const targets = [];
+    for (const raw of input.targets) {
+      const t = typeof raw === "string" ? raw.trim() : null;
+      if (!t || !ADDRESS_RE.test(t)) {
+        push("targets", `target "${raw}" must be a 0x-prefixed 20-byte hex address (wildcards not allowed)`);
+        continue;
+      }
+      targets.push(t.toLowerCase());
+    }
+    out.targets = [...new Set(targets)].sort();
+    if (out.targets.length === 0 && Array.isArray(out.actions)) {
+      const nonReadonly = out.actions.filter((a) => !isReadonlyAction(a));
+      if (nonReadonly.length > 0 || out.actions.length === 0) {
+        push(
+          "targets",
+          `empty targets are only allowed for read/simulate scopes (blocked by: ${nonReadonly.join(", ") || "no valid actions"})`
+        );
+      }
+    }
+  }
+
+  // amounts
+  for (const field of ["maxValueWei", "maxGasWei"]) {
+    const amt = toAmountString(input[field]);
+    if (amt == null) push(field, "must be a non-negative integer wei amount");
+    else out[field] = amt;
+  }
+
+  // slippage
+  const bps = toSafeInt(input.maxSlippageBps);
+  if (bps == null || bps > MAX_SLIPPAGE_BPS) {
+    push("maxSlippageBps", `must be an integer between 0 and ${MAX_SLIPPAGE_BPS}`);
+  } else {
+    out.maxSlippageBps = bps;
+  }
+
+  // expiry — required (checked above); must be a positive unix-seconds int and,
+  // when `now` is supplied, strictly in the future.
+  // Date-renderable ceiling in unix seconds. JS Date maxes at 8.64e15 ms, so a
+  // seconds value above 8.64e12 overflows the renderer (isoUtc does *1000).
+  // Also well within the AA lane's uint48 bound, so a schema-valid expiry always
+  // fits both the on-chain validUntil field and the human render. Reject rather
+  // than render a bogus far-future date (fail closed on the seconds-vs-ms mistake).
+  const MAX_UNIX_SECONDS = 8_640_000_000_000;
+  const expiresAt = toSafeInt(input.expiresAt);
+  if (expiresAt == null || expiresAt <= 0) {
+    push("expiresAt", "must be a positive unix-seconds timestamp");
+  } else if (expiresAt > MAX_UNIX_SECONDS) {
+    push("expiresAt", "exceeds the max unix-seconds timestamp (pass seconds, not milliseconds)");
+  } else {
+    out.expiresAt = expiresAt;
+    if (opts.now != null) {
+      const now = toSafeInt(opts.now);
+      if (now == null) push("expiresAt", "opts.now must be a unix-seconds integer");
+      else if (expiresAt <= now) push("expiresAt", `grant is expired (expiresAt ${expiresAt} <= now ${now})`);
+      else if (expiresAt - now > MAX_GRANT_TTL_SECONDS) {
+        push("expiresAt", `grant exceeds the hard 24-hour TTL (${MAX_GRANT_TTL_SECONDS} seconds)`);
+      }
+    }
+  }
+
+  // nonce
+  const nonce =
+    typeof input.nonce === "string"
+      ? input.nonce.trim()
+      : toSafeInt(input.nonce) != null
+        ? String(toSafeInt(input.nonce))
+        : null;
+  if (!nonce || nonce.length > MAX_NONCE_LENGTH || !NONCE_RE.test(nonce)) {
+    push("nonce", `must be a non-empty string (max ${MAX_NONCE_LENGTH} chars, [A-Za-z0-9._:-])`);
+  } else {
+    out.nonce = nonce;
+  }
+
+  // revocationKey — a PUBLIC identifier used to revoke this grant; never a secret.
+  const rk = typeof input.revocationKey === "string" ? input.revocationKey.trim() : null;
+  if (!rk || rk.length > MAX_REVOCATION_KEY_LENGTH || !REVOCATION_KEY_RE.test(rk)) {
+    push("revocationKey", `must be a non-empty public identifier (max ${MAX_REVOCATION_KEY_LENGTH} chars, [A-Za-z0-9._:-])`);
+  } else {
+    out.revocationKey = rk;
+  }
+
+  if (errors.length) return { ok: false, errors, grant: null };
+  return { ok: true, errors: [], grant: out };
+}
+
+/** Validate + normalize; throws GrantValidationError on any failure. */
+export function normalizeGrant(input, opts = {}) {
+  const { ok, errors, grant } = validateGrant(input, opts);
+  if (!ok) throw new GrantValidationError(errors);
+  return grant;
+}
+
+/**
+ * Deterministic canonical JSON for a grant: validates/normalizes first, then
+ * serializes with alphabetically sorted keys (arrays already sorted + deduped
+ * by normalization). Identical grants — regardless of input key order, address
+ * casing, or numeric representation — always produce the identical string.
+ */
+export function canonicalizeGrant(input, opts = {}) {
+  const g = normalizeGrant(input, opts);
+  const keys = Object.keys(g).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${JSON.stringify(g[k])}`);
+  return `{"version":${GRANT_VERSION},${parts.join(",")}}`;
+}
+
+/** sha256 hex of the canonical form — stable public identifier for a grant. */
+export function grantId(input, opts = {}) {
+  return createHash("sha256").update(canonicalizeGrant(input, opts), "utf8").digest("hex");
+}
+
+/** Deterministic expiry check against an explicit unix-seconds `now`. */
+export function isExpired(grant, nowSeconds) {
+  const now = toSafeInt(nowSeconds);
+  const exp = toSafeInt(isPlainObject(grant) ? grant.expiresAt : null);
+  if (now == null || exp == null) return true; // fail closed
+  return exp <= now;
+}