@oracle-agent/oracle 0.1.0

package/src/public-control/bundler-client.mjs

@@ -0,0 +1,372 @@
+// Oracle Control — ERC-4337 bundler/paymaster runtime submit path (Slice H).
+//
+// Takes a USER-SIGNED UserOperation (produced off this infrastructure — the
+// user's own wallet signs it, never Oracle) and submits it to an ERC-4337
+// bundler via an INJECTED client. This module never talks to a real network
+// itself: every RPC call goes through a caller-supplied `bundlerClient` /
+// `paymasterClient`, duck-typed to the viem/permissionless BundlerClient
+// action shape ({ sendUserOperation, waitForUserOperationReceipt,
+// estimateUserOperationGas }) or a thin equivalent. Tests inject a fully
+// offline mock; production code injects a real viem/permissionless client.
+//
+// Hard boundaries (same posture as aa-adapter.mjs / connect-agent.mjs):
+//   - This module holds no keys and requests no signature. It only forwards
+//     an ALREADY-SIGNED userOp (or, for estimateAndFill/applyPaymaster, an
+//     unsigned userOp being prepared BEFORE the user signs it) to an
+//     injected client's methods.
+//   - submitUserOperation refuses an unsigned userOp outright — a missing or
+//     placeholder ("0x") signature must never reach a bundler.
+//   - submitUserOperation/estimateAndFill/applyPaymaster all refuse an
+//     entryPoint that does not match ENTRYPOINT_V07 (imported from
+//     aa-adapter.mjs, the single source of truth for the deployed EntryPoint
+//     address this codebase targets) unless the caller explicitly overrides
+//     it, and even then the value must still be a valid checksummed address
+//     — this stops an accidental/mismatched EntryPoint submit.
+//   - Before any payload is handed to an injected client, it is rebuilt from
+//     an explicit field allowlist (canonicalizeUserOpForSubmit) and then
+//     recursively scanned by assertNoSecretPayload() for anything shaped
+//     like a private key, mnemonic, bearer token, keystore path, or signer
+//     URL. Fail closed: throws before the call is ever made.
+//   - Imports ONLY from ./aa-adapter.mjs (ENTRYPOINT_V07, buildUserOperation)
+//     and viem/node builtins. NEVER from the private executor stack
+//     (get-signer.mjs, keystore.mjs, exec-policy.mjs, local-signer/*,
+//     adapters/*, mint-capability.mjs) — this module must never be wired to
+//     private operator wallet, and never makes a live network call of its own.
+
+import { isAddress, isHex, getAddress } from "viem";
+
+import { ENTRYPOINT_V07, buildUserOperation } from "./aa-adapter.mjs";
+
+// Re-exported for convenience so callers of this module don't need a second
+// import from aa-adapter just to read the default EntryPoint constant.
+export { ENTRYPOINT_V07 };
+
+function fail(message) {
+  throw new Error(`bundler-client: ${message}`);
+}
+
+// ---------------------------------------------------------------------------
+// No-secret invariant (fail closed) — scoped to what a bundler/paymaster
+// payload could plausibly carry. Mirrors the posture of
+// public-api/connect-agent.mjs's assertNoSecretMaterial without importing
+// across slices.
+// ---------------------------------------------------------------------------
+
+export class SecretLeakError extends Error {
+  constructor(path, rule) {
+    super(`secret material must never appear in a bundler/paymaster payload (at ${path}, rule: ${rule})`);
+    this.name = "SecretLeakError";
+    this.path = path;
+    this.rule = rule;
+  }
+}
+
+const FORBIDDEN_KEY_RE =
+  /(private[_-]?key|secret|bearer|keystore|mnemonic|seed[_-]?phrase|passphrase|password|api[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|signer[_-]?url)/i;
+
+const FORBIDDEN_VALUE_RULES = Object.freeze([
+  // 32-byte hex — the shape of a raw EVM private key / session secret.
+  { rule: "raw-32-byte-hex-key", re: /^0x[0-9a-fA-F]{64}$/ },
+  { rule: "bearer-token", re: /bearer\s+[A-Za-z0-9._~+/=-]+/i },
+  { rule: "pem-private-key", re: /-----BEGIN[A-Z ]*PRIVATE KEY-----/ },
+  { rule: "keystore-path", re: /keystore/i },
+  { rule: "signer-url", re: /https?:\/\/\S*sign/i },
+  { rule: "authorization-header", re: /authorization\s*:/i },
+]);
+
+/**
+ * Recursively scan a value for anything shaped like secret material. Throws
+ * SecretLeakError on the first hit — fail closed. Note: this intentionally
+ * does NOT flag `signature` as a forbidden key (unlike connect-agent's
+ * variant) — a signed userOp's `signature` field is a public, submittable
+ * ECDSA/contract signature, not a secret, and this module's whole job is to
+ * submit it.
+ */
+export function assertNoSecretPayload(value, path = "$", seen = new Set()) {
+  if (value == null) return value;
+  if (typeof value === "string") {
+    for (const { rule, re } of FORBIDDEN_VALUE_RULES) {
+      if (re.test(value)) throw new SecretLeakError(path, rule);
+    }
+    return value;
+  }
+  if (typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertNoSecretPayload(v, `${path}[${i}]`, seen));
+    return value;
+  }
+  for (const [k, v] of Object.entries(value)) {
+    if (FORBIDDEN_KEY_RE.test(k)) {
+      throw new SecretLeakError(`${path}.${k}`, "forbidden-key-name");
+    }
+    assertNoSecretPayload(v, `${path}.${k}`, seen);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Explicit field allowlist for an ERC-4337 v0.7 UserOperation, matching the
+ *  exact shape aa-adapter.buildUserOperation() returns. Rebuilding from this
+ *  allowlist (rather than spreading the caller's object) means any stray
+ *  extra property on a hand-built/tampered userOp — however it got there —
+ *  is dropped before it can ever reach an injected client. */
+const USEROP_FIELDS = [
+  "sender",
+  "nonce",
+  "factory",
+  "factoryData",
+  "callData",
+  "callGasLimit",
+  "verificationGasLimit",
+  "preVerificationGas",
+  "maxFeePerGas",
+  "maxPriorityFeePerGas",
+  "paymaster",
+  "paymasterVerificationGasLimit",
+  "paymasterPostOpGasLimit",
+  "paymasterData",
+  "signature",
+];
+
+function canonicalizeUserOpForSubmit(userOp) {
+  if (!userOp || typeof userOp !== "object") {
+    fail("userOp must be an object (typically the output of aa-adapter.buildUserOperation)");
+  }
+  const out = {};
+  for (const field of USEROP_FIELDS) out[field] = userOp[field] ?? null;
+  if (typeof out.sender !== "string" || !isAddress(out.sender)) {
+    fail("userOp.sender must be a valid 0x address");
+  }
+  if (typeof out.callData !== "string" || !isHex(out.callData)) {
+    fail("userOp.callData must be 0x-prefixed hex");
+  }
+  return Object.freeze(out);
+}
+
+function requireSignedUserOp(userOp) {
+  const sig = userOp && userOp.signature;
+  if (sig == null || sig === "" || sig === "0x") {
+    fail("refusing to submit a userOp with a missing/placeholder signature — sign it in the user's own wallet first");
+  }
+  if (typeof sig !== "string" || !isHex(sig)) {
+    fail("userOp.signature must be 0x-prefixed hex when present");
+  }
+}
+
+function resolveEntryPoint(entryPoint) {
+  const value = entryPoint ?? ENTRYPOINT_V07;
+  if (typeof value !== "string" || !isAddress(value)) {
+    fail("entryPoint must be a valid 0x address");
+  }
+  const normalized = getAddress(value);
+  if (normalized !== getAddress(ENTRYPOINT_V07)) {
+    fail(
+      `entryPoint ${normalized} does not match the expected EntryPoint ${getAddress(ENTRYPOINT_V07)} ` +
+        "(ENTRYPOINT_V07 from aa-adapter.mjs) — refusing to submit to an unexpected EntryPoint"
+    );
+  }
+  return normalized;
+}
+
+function requireClientMethod(client, methodName, clientLabel) {
+  if (!client || typeof client[methodName] !== "function") {
+    fail(
+      `${clientLabel} must expose an async ${methodName}(...) method (viem/permissionless BundlerClient shape, ` +
+        "or a thin { sendUserOperation, waitForUserOperationReceipt, estimateUserOperationGas } interface) — " +
+        "this module never makes a network call of its own"
+    );
+  }
+}
+
+function toHexIfBigIntLike(value) {
+  if (value == null) return value;
+  if (typeof value === "string") return value;
+  if (typeof value === "bigint") return `0x${value.toString(16)}`;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return `0x${BigInt(value).toString(16)}`;
+  fail("gas/fee field returned by client must be a 0x-hex string, bigint, or safe integer");
+}
+
+// ---------------------------------------------------------------------------
+// Public contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit an already user-signed UserOperation to an ERC-4337 bundler via an
+ * injected client. This is the only function in this module that is allowed
+ * to move a userOp onto a bundler's mempool, and it refuses to do so unless
+ * the userOp actually carries a real signature.
+ *
+ * @param {object} params
+ * @param {object} params.userOp  a signed UserOperation (signature != "0x")
+ * @param {object} params.bundlerClient  injected client exposing async
+ *   sendUserOperation({ userOperation, entryPoint }) -> userOpHash
+ * @param {string} [params.entryPoint]  defaults to ENTRYPOINT_V07; refused
+ *   if it does not resolve to ENTRYPOINT_V07
+ * @returns {Promise<string>} userOpHash returned by the bundler client
+ */
+export async function submitUserOperation(params = {}) {
+  const { userOp, bundlerClient, entryPoint } = params;
+  requireSignedUserOp(userOp);
+  const resolvedEntryPoint = resolveEntryPoint(entryPoint);
+  requireClientMethod(bundlerClient, "sendUserOperation", "bundlerClient");
+
+  const payload = canonicalizeUserOpForSubmit(userOp);
+  assertNoSecretPayload(payload);
+
+  const userOpHash = await bundlerClient.sendUserOperation({
+    userOperation: payload,
+    entryPoint: resolvedEntryPoint,
+  });
+
+  if (typeof userOpHash !== "string" || !isHex(userOpHash)) {
+    fail("bundlerClient.sendUserOperation must resolve to a 0x-hex userOpHash");
+  }
+  return userOpHash;
+}
+
+/**
+ * Fill gas fields on an UNSIGNED (pre-signature) UserOperation via an
+ * injected bundler client's estimateUserOperationGas. Never submits
+ * anything and never requires a signature — this runs BEFORE the user
+ * signs, so it can supply real gas numbers to sign over. Returns a new
+ * frozen userOp; the input is never mutated.
+ *
+ * @param {object} params
+ * @param {object} params.userOp  unsigned or placeholder-gas UserOperation
+ *   (typically straight out of aa-adapter.buildUserOperation)
+ * @param {object} params.bundlerClient  injected client exposing async
+ *   estimateUserOperationGas({ userOperation, entryPoint }) -> gas fields
+ * @param {string} [params.entryPoint]  defaults to ENTRYPOINT_V07
+ * @returns {Promise<object>} frozen userOp with gas fields filled from the
+ *   client's estimate (falls back to the input's own values for any field
+ *   the client did not return)
+ */
+export async function estimateAndFill(params = {}) {
+  const { userOp, bundlerClient, entryPoint } = params;
+  const payload = canonicalizeUserOpForSubmit(userOp);
+  const resolvedEntryPoint = resolveEntryPoint(entryPoint);
+  requireClientMethod(bundlerClient, "estimateUserOperationGas", "bundlerClient");
+
+  assertNoSecretPayload(payload);
+  const estimate = await bundlerClient.estimateUserOperationGas({
+    userOperation: payload,
+    entryPoint: resolvedEntryPoint,
+  });
+  if (!estimate || typeof estimate !== "object") {
+    fail("bundlerClient.estimateUserOperationGas must resolve to a gas-fields object");
+  }
+
+  const filled = {
+    ...payload,
+    callGasLimit: toHexIfBigIntLike(estimate.callGasLimit ?? payload.callGasLimit),
+    verificationGasLimit: toHexIfBigIntLike(estimate.verificationGasLimit ?? payload.verificationGasLimit),
+    preVerificationGas: toHexIfBigIntLike(estimate.preVerificationGas ?? payload.preVerificationGas),
+  };
+  if (payload.paymaster != null) {
+    if (estimate.paymasterVerificationGasLimit != null) {
+      filled.paymasterVerificationGasLimit = toHexIfBigIntLike(estimate.paymasterVerificationGasLimit);
+    }
+    if (estimate.paymasterPostOpGasLimit != null) {
+      filled.paymasterPostOpGasLimit = toHexIfBigIntLike(estimate.paymasterPostOpGasLimit);
+    }
+  }
+
+  return Object.freeze(assertNoSecretPayload(filled));
+}
+
+/**
+ * Attach (or explicitly omit) paymaster sponsorship on an UNSIGNED
+ * UserOperation via an injected paymasterClient. If `paymasterClient` is
+ * absent/null, this is a no-op that returns the self-funded path — the
+ * userOp is returned with its paymaster fields explicitly nulled out, never
+ * left ambiguous. This module never holds paymaster credentials; whatever
+ * auth the paymaster needs lives inside the injected client, off this file.
+ *
+ * @param {object} params
+ * @param {object} params.userOp  unsigned UserOperation
+ * @param {object} [params.paymasterClient]  injected client exposing async
+ *   getPaymasterData({ userOperation, entryPoint }) -> paymaster fields.
+ *   Omit for the self-funded path (no paymaster).
+ * @param {string} [params.entryPoint]  defaults to ENTRYPOINT_V07
+ * @returns {Promise<object>} frozen userOp with paymaster fields set
+ */
+export async function applyPaymaster(params = {}) {
+  const { userOp, paymasterClient, entryPoint } = params;
+  const payload = canonicalizeUserOpForSubmit(userOp);
+  const resolvedEntryPoint = resolveEntryPoint(entryPoint);
+
+  if (paymasterClient == null) {
+    // Self-funded path: no paymaster involved, fields explicitly nulled.
+    return Object.freeze({
+      ...payload,
+      paymaster: null,
+      paymasterData: null,
+      paymasterVerificationGasLimit: null,
+      paymasterPostOpGasLimit: null,
+    });
+  }
+
+  requireClientMethod(paymasterClient, "getPaymasterData", "paymasterClient");
+  assertNoSecretPayload(payload);
+  const sponsorship = await paymasterClient.getPaymasterData({
+    userOperation: payload,
+    entryPoint: resolvedEntryPoint,
+  });
+  if (!sponsorship || typeof sponsorship.paymaster !== "string" || !isAddress(sponsorship.paymaster)) {
+    fail("paymasterClient.getPaymasterData must resolve to an object with a valid paymaster address");
+  }
+
+  const filled = {
+    ...payload,
+    paymaster: getAddress(sponsorship.paymaster),
+    paymasterData: sponsorship.paymasterData ?? "0x",
+    paymasterVerificationGasLimit: toHexIfBigIntLike(sponsorship.paymasterVerificationGasLimit ?? 0n),
+    paymasterPostOpGasLimit: toHexIfBigIntLike(sponsorship.paymasterPostOpGasLimit ?? 0n),
+  };
+
+  return Object.freeze(assertNoSecretPayload(filled));
+}
+
+/**
+ * Passthrough to an injected bundler client's receipt-polling method. This
+ * module adds no retry/timeout logic of its own — that belongs to the
+ * injected client (viem/permissionless already implement polling with
+ * backoff); this is a thin, testable seam.
+ *
+ * @param {object} params
+ * @param {string} params.hash  userOpHash returned by submitUserOperation
+ * @param {object} params.bundlerClient  injected client exposing async
+ *   waitForUserOperationReceipt({ hash, ...rest }) -> receipt
+ * @param {object} [params.opts]  extra options forwarded verbatim (e.g.
+ *   pollingInterval, timeout) — passed through untouched, never inspected
+ *   for secrets since this module trusts caller-supplied polling knobs are
+ *   not where key material would ever live
+ * @returns {Promise<object>} whatever the injected client resolves to
+ */
+export async function waitForReceipt(params = {}) {
+  const { hash, bundlerClient, opts = {} } = params;
+  if (typeof hash !== "string" || !isHex(hash)) {
+    fail("hash is required and must be 0x-prefixed hex (the userOpHash from submitUserOperation)");
+  }
+  requireClientMethod(bundlerClient, "waitForUserOperationReceipt", "bundlerClient");
+  return bundlerClient.waitForUserOperationReceipt({ hash, ...opts });
+}
+
+export const _internal = {
+  canonicalizeUserOpForSubmit,
+  requireSignedUserOp,
+  resolveEntryPoint,
+  requireClientMethod,
+  toHexIfBigIntLike,
+};
+
+// Re-exported so callers building a fresh userOp before submit don't need a
+// second import from aa-adapter for the common "build then submit" flow.
+export { buildUserOperation };

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;
+}