@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/public-control/session-orchestrator.mjs

@@ -0,0 +1,418 @@
+// Oracle Control — end-to-end session orchestrator (Slice J).
+//
+// Pure GLUE. This module composes the already-tested public lanes into one
+// plan -> activate -> revoke -> describe lifecycle and adds NO new custody,
+// NO new crypto, NO new policy. Every capability below is an import:
+//
+//   plan      — policy-schema.validateGrant + connect-agent.assembleUnsignedGrant
+//   activate  — session-key-model.createSessionGrant + aa-adapter
+//               (encodeSessionKeyInstall / buildUserOperation)
+//   revoke    — aa-adapter.revokeSessionKey + session-key-model's
+//               createRevocationRegistry entry shape
+//   describe  — grant-indexer.reconstructGrantIndex
+//
+// Hard boundaries (same posture as every other public-control module):
+//   - NEVER signs. There is no signer here. activateSession() verifies the
+//     owner's grant signature before assembly but never stores or returns it.
+//     Every userOp leaving this module has signature: "0x".
+//   - NEVER imports the private executor stack (get-signer.mjs, keystore.mjs,
+//     exec-policy.mjs, local-signer/*, adapters/*, mint-capability.mjs).
+//   - Fail-closed no-secret invariant: every object returned from this module
+//     is scanned with connect-agent's assertNoSecretMaterial (see
+//     scanPublicReturn below for the two documented, narrow redactions).
+//
+// CRITICAL UNIT RULE (control lane vs AA lane):
+//   - policy-schema / grant-indexer / connect-agent speak UNIX SECONDS
+//     (`expiresAt`, `now`).
+//   - session-key-model / aa-adapter speak MILLISECONDS (`expiresAtMs`,
+//     `issuedAtMs`, `nowMs`).
+//   Every crossing in this file converts EXPLICITLY:
+//     seconds -> ms:  seconds * 1000
+//     ms -> seconds:  Math.floor(ms / 1000)
+//   and is marked with a "UNIT BOUNDARY" comment.
+
+import {
+  assembleUnsignedGrant,
+  assertNoSecretMaterial,
+  SIGNING_SCHEME,
+} from "../public-api/connect-agent.mjs";
+import { validateGrant, grantId as computeControlGrantId, GrantValidationError } from "./policy-schema.mjs";
+import { reconstructGrantIndex } from "./grant-indexer.mjs";
+import {
+  createSessionGrant,
+  createRevocationRegistry,
+  PROVIDERS,
+} from "./session-key-model.mjs";
+import {
+  encodeSessionKeyInstall,
+  revokeSessionKey,
+  buildUserOperation,
+} from "./aa-adapter.mjs";
+import { getBytes, verifyMessage } from "ethers";
+
+export const ORCHESTRATOR_KINDS = Object.freeze({
+  PLAN: "oracle-session-plan",
+  ACTIVATION: "oracle-session-activation",
+  REVOCATION: "oracle-session-revocation",
+  DESCRIPTION: "oracle-session-description",
+});
+
+export { SIGNING_SCHEME };
+
+function fail(message) {
+  throw new Error(`session-orchestrator: ${message}`);
+}
+
+// ---------------------------------------------------------------------------
+// No-secret scan for orchestrator returns
+// ---------------------------------------------------------------------------
+//
+// connect-agent's assertNoSecretMaterial is intentionally stricter than this
+// lane's data: it forbids ANY `signature` key and ANY 0x+64-hex string value
+// (the shape of a raw EVM private key). Two values in the AA lane are public
+// by design yet share those shapes:
+//
+//   1. userOp.signature — ALWAYS the empty placeholder "0x" here (unsigned).
+//      We PROVE it is exactly "0x" and then strip the key from the scan
+//      clone. A signature key holding anything else fails closed.
+//   2. session ids — sha256-derived 0x+64-hex PUBLIC identifiers produced by
+//      session-key-model.computeSessionId. They are redacted in the scan
+//      clone ONLY when sitting at the known id keys below. A 0x+64-hex
+//      value at ANY other key (i.e. anything that could be a smuggled raw
+//      private key) still fails closed.
+//
+// The ORIGINAL object is returned untouched; only the scan clone is redacted.
+
+const SESSION_ID_KEYS = Object.freeze(["id", "sessionId"]);
+const SESSION_ID_RE = /^0x[0-9a-fA-F]{64}$/;
+
+function redactForScan(value, keyName) {
+  if (value == null || typeof value !== "object") {
+    if (
+      typeof value === "string" &&
+      SESSION_ID_KEYS.includes(keyName) &&
+      SESSION_ID_RE.test(value)
+    ) {
+      // Public sha256 session id (see header note 2): scan the bare hex so
+      // the raw-32-byte-hex-key value rule doesn't misfire, while keeping
+      // the content itself scannable.
+      return `session-id:${value.slice(2)}`;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((v) => redactForScan(v, null));
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (k === "signature") {
+      // See header note 1: unsigned invariant is PROVEN, then the key is
+      // dropped from the scan clone only.
+      if (v !== "0x") {
+        fail(
+          `refusing to return a userOp whose signature is not the empty "0x" placeholder (this module never signs)`
+        );
+      }
+      continue;
+    }
+    out[k] = redactForScan(v, k);
+  }
+  return out;
+}
+
+/** Fail-closed scan of an orchestrator return value. Throws SecretLeakError /
+ *  Error on anything secret-shaped; returns the ORIGINAL value unchanged. */
+export function scanPublicReturn(value) {
+  assertNoSecretMaterial(redactForScan(value, null));
+  return value;
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const v of Object.values(value)) deepFreeze(v);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// 1. planConnection
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a raw control-lane grant and assemble the UNSIGNED payload the
+ * owner reviews and signs in their own wallet.
+ *
+ * Out-of-policy input is refused HERE, before anything downstream sees it:
+ * validateGrant() fails closed (unknown fields, wildcard actions, empty
+ * targets for state-changing scopes, expired grants when opts.now is given)
+ * and this function throws its GrantValidationError verbatim.
+ *
+ * @param {object} input   raw grant fields (policy-schema REQUIRED_FIELDS;
+ *                         `expiresAt` is UNIX SECONDS)
+ * @param {object} opts
+ * @param {number} opts.now  required unix SECONDS reference time for liveness and TTL checks
+ * @returns frozen { kind, grantId, grant, unsignedGrant, signingBytes, render }
+ */
+export function planConnection(input, opts = {}) {
+  // Control lane: validateGrant speaks UNIX SECONDS (expiresAt, opts.now).
+  const verdict = validateGrant(input, { now: opts.now });
+  if (!verdict.ok) {
+    // Refused at the door — out-of-policy grants never reach assembly.
+    throw new GrantValidationError(verdict.errors);
+  }
+
+  const unsignedGrant = assembleUnsignedGrant(verdict.grant, { now: opts.now });
+
+  const result = deepFreeze({
+    kind: ORCHESTRATOR_KINDS.PLAN,
+    unsigned: true,
+    grantId: unsignedGrant.payload.grantId,
+    grant: verdict.grant,
+    unsignedGrant,
+    signingBytes: unsignedGrant.signing,
+    render: unsignedGrant.render,
+  });
+  return scanPublicReturn(result);
+}
+
+// ---------------------------------------------------------------------------
+// 2. activateSession
+// ---------------------------------------------------------------------------
+
+function normalizeOwnerSignature(ownerSignature) {
+  if (typeof ownerSignature !== "string" || ownerSignature.trim() === "") {
+    fail("ownerSignature is required (the owner must have signed the grant in their own wallet)");
+  }
+  const sig = ownerSignature.trim();
+  if (!/^0x[0-9a-fA-F]+$/.test(sig) || sig === "0x") {
+    fail("ownerSignature must be non-empty 0x-prefixed hex");
+  }
+  return sig;
+}
+
+async function verifyOwnerApproval({ grant, ownerSignature, verifyOwnerSignature, nowSeconds }) {
+  const signature = normalizeOwnerSignature(ownerSignature);
+  const unsignedGrant = assembleUnsignedGrant(grant, { now: nowSeconds });
+  if (typeof verifyOwnerSignature === "function") {
+    const approved = await verifyOwnerSignature({
+      grant,
+      ownerSignature: signature,
+      signingBytes: unsignedGrant.signing,
+    });
+    if (approved !== true) fail("ownerSignature verification failed");
+    return;
+  }
+  try {
+    const recovered = verifyMessage(getBytes(unsignedGrant.signing.bytesHex), signature);
+    if (recovered.toLowerCase() !== grant.accountAddress.toLowerCase()) {
+      fail("ownerSignature signer does not match grant accountAddress");
+    }
+  } catch (error) {
+    if (String(error?.message || "").startsWith("session-orchestrator:")) throw error;
+    fail("ownerSignature could not be verified; smart accounts must provide verifyOwnerSignature");
+  }
+}
+
+/**
+ * Bridge an owner-approved control-lane grant (UNIX SECONDS) into the AA
+ * lane (MILLISECONDS): create the session-key-model grant, encode install
+ * calldata, and assemble the UNSIGNED ERC-4337 userOp that carries it.
+ *
+ * NEVER signs. The returned userOp always has signature "0x", and the
+ * ownerSignature the caller proved possession of is not part of the return.
+ *
+ * @param {object} params
+ * @param {object} params.grant  control-lane grant (policy-schema shape,
+ *                               `expiresAt` in UNIX SECONDS). Re-validated.
+ * @param {string} params.ownerSignature  owner's grant signature, verified
+ *                               against accountAddress for EOAs.
+ * @param {object} params.sessionKeyModel AA-lane parameters:
+ *   provider       one of session-key-model PROVIDERS (default permissionless-viem)
+ *   moduleAddress  REQUIRED deployed session-key module address
+ *   issuedAtMs     REQUIRED epoch MILLISECONDS issuance instant (explicit for
+ *                  determinism; also used as the active-check nowMs)
+ *   abi            optional module ABI override
+ *   userOp         REQUIRED buildUserOperation params minus sender/callData:
+ *                  { nonce | client, callGasLimit, verificationGasLimit,
+ *                    preVerificationGas, maxFeePerGas, maxPriorityFeePerGas, ... }
+ * @returns frozen { kind, unsigned, grantId, sessionId, sessionGrant,
+ *                   install, userOp, units }
+ */
+async function activateSessionWithVerifier(
+  { grant, ownerSignature, sessionKeyModel } = {},
+  verifyOwnerSignature,
+) {
+  if (sessionKeyModel == null || typeof sessionKeyModel !== "object") {
+    fail("sessionKeyModel is required ({ provider?, moduleAddress, issuedAtMs, userOp })");
+  }
+  const {
+    provider = PROVIDERS.PERMISSIONLESS_VIEM,
+    moduleAddress,
+    issuedAtMs,
+    abi,
+    userOp: userOpParams,
+  } = sessionKeyModel;
+
+  if (!Number.isFinite(Number(issuedAtMs))) {
+    fail("sessionKeyModel.issuedAtMs (epoch MILLISECONDS) is required for a deterministic session grant");
+  }
+  if (userOpParams == null || typeof userOpParams !== "object") {
+    fail("sessionKeyModel.userOp (gas/fee/nonce params for buildUserOperation) is required");
+  }
+
+  // Control lane: re-validate the grant (expiresAt in UNIX SECONDS).
+  // UNIT BOUNDARY (SECONDS -> for the liveness check we pass the AA-lane
+  // instant down-converted): now = Math.floor(issuedAtMs / 1000).
+  const nowSeconds = Math.floor(Number(issuedAtMs) / 1000);
+  const verdict = validateGrant(grant, { now: nowSeconds });
+  if (!verdict.ok) throw new GrantValidationError(verdict.errors);
+  const controlGrant = verdict.grant;
+  await verifyOwnerApproval({
+    grant: controlGrant,
+    ownerSignature,
+    verifyOwnerSignature,
+    nowSeconds,
+  });
+
+  // UNIT BOUNDARY (SECONDS -> MILLISECONDS): the control lane's expiresAt is
+  // UNIX SECONDS; session-key-model requires expiresAtMs in MILLISECONDS.
+  const expiresAtMs = controlGrant.expiresAt * 1000;
+
+  const sessionGrant = createSessionGrant({
+    provider,
+    owner: controlGrant.accountAddress, // owner smart account
+    agent: controlGrant.agentAddress, // session key address
+    chainId: controlGrant.chainId,
+    actions: controlGrant.actions,
+    targets: controlGrant.targets,
+    maxValueWei: controlGrant.maxValueWei,
+    maxGasWei: controlGrant.maxGasWei,
+    expiresAtMs, // MILLISECONDS (converted above)
+    nonce: controlGrant.nonce,
+    issuedAtMs: Number(issuedAtMs), // MILLISECONDS
+  });
+
+  // AA lane: encodeSessionKeyInstall / sessionStatus speak MILLISECONDS.
+  const install = encodeSessionKeyInstall(sessionGrant, {
+    moduleAddress,
+    abi,
+    nowMs: Number(issuedAtMs),
+  });
+
+  // UNSIGNED ERC-4337 envelope. buildUserOperation always emits
+  // signature: "0x" — scanPublicReturn additionally proves it below.
+  const userOp = await buildUserOperation({
+    ...userOpParams,
+    sender: controlGrant.accountAddress,
+    callData: install.data,
+  });
+
+  const result = deepFreeze({
+    kind: ORCHESTRATOR_KINDS.ACTIVATION,
+    unsigned: true,
+    grantId: computeControlGrantId(controlGrant), // control-lane public id (bare sha256 hex)
+    sessionId: sessionGrant.id,
+    sessionGrant,
+    install,
+    userOp,
+    units: {
+      // Both representations surfaced so callers/tests can audit the
+      // SECONDS<->MILLISECONDS conversion explicitly.
+      expiresAtSeconds: controlGrant.expiresAt,
+      expiresAtMs: sessionGrant.expiresAtMs,
+    },
+  });
+  return scanPublicReturn(result);
+}
+
+export async function activateSession(params = {}) {
+  return activateSessionWithVerifier(params, undefined);
+}
+
+export function createSessionOrchestrator({ verifyOwnerSignature } = {}) {
+  if (typeof verifyOwnerSignature !== "function") {
+    fail("createSessionOrchestrator requires a trusted verifyOwnerSignature function");
+  }
+  const trustedVerifier = verifyOwnerSignature;
+  return Object.freeze({
+    activateSession(params = {}) {
+      return activateSessionWithVerifier(params, trustedVerifier);
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 3. revokeSession
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke a session: deterministic revoke calldata for the on-chain module
+ * plus the off-chain revocation-registry entry Oracle Control's policy
+ * checks consume.
+ *
+ * @param {object|string} grantOrSessionId  session-key-model grant or raw id
+ * @param {object} opts
+ * @param {string} opts.moduleAddress  REQUIRED session-key module address
+ * @param {object} [opts.registry]     createRevocationRegistry() instance to
+ *                                     record into (a fresh one is created —
+ *                                     and returned — when omitted)
+ * @param {number} [opts.nowMs]        epoch MILLISECONDS revocation instant
+ * @param {string} [opts.reason]
+ * @returns frozen { kind, sessionId, revoke, revocation:{revokedAtMs,reason}, registry }
+ */
+export function revokeSession(grantOrSessionId, opts = {}) {
+  const revoke = revokeSessionKey(grantOrSessionId, {
+    moduleAddress: opts.moduleAddress,
+    abi: opts.abi,
+  });
+
+  const sessionId =
+    typeof grantOrSessionId === "string" ? grantOrSessionId : grantOrSessionId.id;
+
+  // AA lane registry speaks MILLISECONDS (revokedAtMs).
+  const registry = opts.registry ?? createRevocationRegistry();
+  const entry = registry.revoke(sessionId, {
+    nowMs: opts.nowMs ?? Date.now(), // MILLISECONDS
+    reason: opts.reason ?? null,
+  });
+
+  const result = {
+    kind: ORCHESTRATOR_KINDS.REVOCATION,
+    sessionId,
+    revoke,
+    revocation: Object.freeze({ revokedAtMs: entry.revokedAtMs, reason: entry.reason }),
+    // The live registry is handed back for the caller's subsequent
+    // sessionStatus / checkSessionAuthorized calls; not frozen on purpose.
+    registry,
+  };
+  Object.freeze(result);
+  deepFreeze(result.revoke);
+  return scanPublicReturn(result);
+}
+
+// ---------------------------------------------------------------------------
+// 4. describeActive
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconstruct the control-lane grant index from an event log and return the
+ * currently-active grants.
+ *
+ * @param {object[]} events  grant-indexer event log
+ * @param {number} now       UNIX SECONDS reference instant (control lane)
+ * @returns frozen { kind, now, active, count, index }
+ */
+export function describeActive(events, now) {
+  // Control lane: reconstructGrantIndex speaks UNIX SECONDS (`now`,
+  // record.expiresAt). No conversion happens here — callers holding a
+  // MILLISECONDS clock must pass Math.floor(ms / 1000) themselves.
+  const index = reconstructGrantIndex(events, { now });
+
+  const result = deepFreeze({
+    kind: ORCHESTRATOR_KINDS.DESCRIPTION,
+    now,
+    active: index.active,
+    count: index.active.length,
+    index,
+  });
+  return scanPublicReturn(result);
+}

package/src/rfq/intent.mjs

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { getAddress, isAddress } from "ethers";
+
+export const NATIVE_TOKEN = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+export const DEFAULT_SAME_CHAIN_SOURCES = Object.freeze(["lifi", "paraswap", "0x", "cow", "uniswap-v3"]);
+export const DEFAULT_CROSS_CHAIN_SOURCES = Object.freeze(["lifi"]);
+const HEX32 = /^0x[0-9a-fA-F]{64}$/;
+const INT = /^\d+$/;
+
+function fail(label, message = "invalid") {
+  throw new Error(`rfq: ${label} ${message}`);
+}
+
+function chainId(value, label) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) fail(label, "must be a positive chainId");
+  return n;
+}
+
+function amount(value, label) {
+  const s = String(value ?? "").trim();
+  if (!INT.test(s) || BigInt(s) <= 0n) fail(label, "must be a positive integer string");
+  return s;
+}
+
+function optionalAmount(value, label) {
+  if (value == null || value === "") return null;
+  return amount(value, label);
+}
+
+function token(value, label) {
+  const s = String(value ?? "").trim();
+  if (s.toLowerCase() === NATIVE_TOKEN.toLowerCase()) return NATIVE_TOKEN;
+  if (!isAddress(s)) fail(label, "must be an EVM address or native token sentinel");
+  return getAddress(s);
+}
+
+function address(value, label) {
+  const s = String(value ?? "").trim();
+  if (!isAddress(s)) fail(label, "must be an EVM address");
+  return getAddress(s);
+}
+
+function optionalAddress(value, label) {
+  if (value == null || value === "") return null;
+  return address(value, label);
+}
+
+function stringList(value, label, defaults) {
+  if (value === undefined) return [...defaults];
+  if (!Array.isArray(value)) fail(label, "must be an array");
+  return value.map((x) => String(x).trim()).filter(Boolean);
+}
+
+function deadline(value, { nowMs, maxDeadlineMs }, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) fail(label, "must be a finite millisecond timestamp");
+  if (n <= nowMs) fail(label, "expired");
+  if (n > nowMs + maxDeadlineMs) fail(label, "exceeds maxDeadlineMs");
+  return Math.floor(n);
+}
+
+function plain(value) {
+  if (Array.isArray(value)) return value.map(plain);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      if (value[key] !== undefined) out[key] = plain(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(plain(value));
+}
+
+export function sha256Hex(value) {
+  return `0x${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+function withoutHash(value, keys) {
+  const out = { ...value };
+  for (const key of keys) delete out[key];
+  return out;
+}
+
+export function hashRfqIntent(intent) {
+  return sha256Hex(withoutHash(intent, ["intentHash"]));
+}
+
+export function hashFirmQuote(quote) {
+  return sha256Hex(withoutHash(quote, ["firmQuoteHash"]));
+}
+
+export function normalizeRfqIntent(input = {}, opts = {}) {
+  const nowMs = Number(opts.nowMs ?? Date.now());
+  const maxDeadlineMs = Number(opts.maxDeadlineMs ?? 30 * 60 * 1000);
+  if (!Number.isFinite(nowMs) || !Number.isFinite(maxDeadlineMs) || maxDeadlineMs <= 0) fail("time", "is invalid");
+  const fromChainId = chainId(input.fromChainId ?? input.fromChain, "fromChainId");
+  const toChainId = chainId(input.toChainId ?? input.toChain, "toChainId");
+  const sameChain = fromChainId === toChainId;
+  const defaults = sameChain ? DEFAULT_SAME_CHAIN_SOURCES : DEFAULT_CROSS_CHAIN_SOURCES;
+  const intent = {
+    kind: "rfq-intent",
+    version: 1,
+    fromChainId,
+    toChainId,
+    sellToken: token(input.sellToken ?? input.tokenIn ?? input.fromToken, "sellToken"),
+    buyToken: token(input.buyToken ?? input.tokenOut ?? input.toToken, "buyToken"),
+    sellAmount: amount(input.sellAmount ?? input.amountIn ?? input.fromAmount, "sellAmount"),
+    receiver: address(input.receiver ?? input.recipient ?? input.to, "receiver"),
+    deadlineMs: deadline(input.deadlineMs ?? input.deadline ?? input.expiresAtMs, { nowMs, maxDeadlineMs }, "deadline"),
+    minBuyAmount: optionalAmount(input.minBuyAmount ?? input.minOut ?? input.amountOutMin, "minBuyAmount"),
+    allowedSources: stringList(input.allowedSources, "allowedSources", defaults),
+    allowedRouters: stringList(input.allowedRouters, "allowedRouters", []),
+    slippageBps: Number.isFinite(Number(input.slippageBps)) ? Number(input.slippageBps) : null,
+    partialFill: input.partialFill === true,
+    metadata: input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata) ? plain(input.metadata) : {},
+  };
+  if (intent.slippageBps != null && (!Number.isInteger(intent.slippageBps) || intent.slippageBps < 0 || intent.slippageBps > 10_000)) fail("slippageBps", "must be 0 to 10000");
+  intent.intentId = input.intentId ? String(input.intentId) : sha256Hex({ seed: "rfq-intent", intent }).slice(0, 34);
+  intent.intentHash = hashRfqIntent(intent);
+  return Object.freeze(intent);
+}
+
+function artifact(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("artifact", "required");
+  if (value.typedDataHash != null && !HEX32.test(String(value.typedDataHash))) fail("artifact.typedDataHash", "must be bytes32");
+  if (value.calldataHash != null && !HEX32.test(String(value.calldataHash))) fail("artifact.calldataHash", "must be bytes32");
+  if (value.to != null && !isAddress(String(value.to))) fail("artifact.to", "must be an address");
+  if (value.data != null && !/^0x(?:[0-9a-fA-F]{2})*$/.test(String(value.data))) fail("artifact.data", "must be hex");
+  return plain(value);
+}
+
+export function normalizeFirmQuote(intent, quote = {}, opts = {}) {
+  if (!intent || intent.kind !== "rfq-intent") fail("intent", "required");
+  const nowMs = Number(opts.nowMs ?? Date.now());
+  const expiryMs = Number(quote.expiryMs ?? quote.expiresAtMs ?? quote.validUntilMs);
+  if (!Number.isFinite(expiryMs)) fail("quote expiry", "required");
+  if (expiryMs <= nowMs) fail("quote", "expired");
+  if (expiryMs > intent.deadlineMs) fail("quote expiry", "exceeds intent deadline");
+  const source = String(quote.source ?? quote.provider ?? "").trim();
+  if (!source) fail("source", "required");
+  if (!intent.allowedSources.includes(source)) fail("source", "not allowed by intent");
+  const amountOut = amount(quote.amountOut ?? quote.buyAmount, "amountOut");
+  const minBuyAmount = amount(quote.minBuyAmount ?? quote.minOut ?? amountOut, "minBuyAmount");
+  if (BigInt(minBuyAmount) > BigInt(amountOut)) fail("minBuyAmount", "exceeds amountOut");
+  const artifactValue = artifact(quote.artifact ?? quote.executableArtifact ?? quote.transaction ?? quote.typedData);
+  const quotedAtMs = Number(quote.quotedAtMs ?? quote.timestampMs ?? opts.nowMs ?? Date.now());
+  if (!Number.isFinite(quotedAtMs)) fail("quotedAtMs", "must be finite");
+  const router = optionalAddress(quote.router ?? quote.settlementRouter ?? artifactValue.to, "router");
+  const out = {
+    kind: "rfq-firm-quote",
+    provider: "rfq",
+    surface: "rfq",
+    version: 1,
+    quoteId: String(quote.quoteId ?? quote.id ?? "").trim(),
+    source,
+    intentHash: intent.intentHash,
+    fromChainId: intent.fromChainId,
+    toChainId: intent.toChainId,
+    sellToken: intent.sellToken,
+    buyToken: intent.buyToken,
+    sellAmount: intent.sellAmount,
+    receiver: intent.receiver,
+    router,
+    amountOut,
+    minBuyAmount,
+    quotedAtMs: Math.floor(quotedAtMs),
+    expiryMs: Math.floor(expiryMs),
+    artifact: artifactValue,
+    maker: quote.maker ? String(quote.maker) : null,
+    metadata: quote.metadata && typeof quote.metadata === "object" && !Array.isArray(quote.metadata) ? plain(quote.metadata) : {},
+  };
+  if (!out.quoteId) out.quoteId = sha256Hex({ seed: "rfq-quote", out }).slice(0, 34);
+  out.firmQuoteHash = hashFirmQuote(out);
+  return Object.freeze(out);
+}