@oracle-agent/oracle 0.11.0 → 0.12.0

package/src/onboarding/tiers.mjs

@@ -1,139 +0,0 @@
-// Product onboarding tiers — multi-user, non-custodial.
-// Tier chooses default scopes. Higher tiers never put user private keys on our box.
-
-import { DEFAULT_SCOPES, EXECUTE_SCOPE } from "../scopes.mjs";
-import { createAgentKey, listAgentKeys, revokeAgentKey, authenticateAgentKey } from "./agent-keys.mjs";
-
-/**
- * Tier catalog (product story):
- * - observer:   read-only market/position data
- * - preparer:   can prepare trades/mints (unsigned / advisory)
- * - shadow:     paper/shadow agent loops
- * - executor:   live agent:execute — ONLY if owner is on controller allowlist
- * - local_signer: no API key needed for signing; user signs off-infra (docs only)
- */
-export const TIERS = {
-  observer: {
-    id: "observer",
-    label: "Observer",
-    description: "Read markets, NFTs, positions. No prepare/execute.",
-    scopes: ["read:markets", "read:nfts", "read:positions"],
-    custody: "none",
-    canExecute: false,
-  },
-  preparer: {
-    id: "preparer",
-    label: "Preparer",
-    description: "Prepare trades/mints; user or operator co-signs. No live execute scope.",
-    scopes: [...DEFAULT_SCOPES].filter((s) => s !== "agent:shadow"),
-    custody: "none",
-    canExecute: false,
-  },
-  shadow: {
-    id: "shadow",
-    label: "Shadow agent",
-    description: "Full prepare + agent:shadow paper loops. Still no live execute.",
-    scopes: [...DEFAULT_SCOPES],
-    custody: "none",
-    canExecute: false,
-  },
-  executor: {
-    id: "executor",
-    label: "Executor (controller)",
-    description:
-      "Live agent:execute on the owner's own wallet only. Owner must be an executor controller. Key is NOT a wallet key.",
-    scopes: [...DEFAULT_SCOPES, EXECUTE_SCOPE],
-    custody: "none — scoped API key only; user wallet key never stored",
-    canExecute: true,
-  },
-  local_signer: {
-    id: "local_signer",
-    label: "Local signer",
-    description:
-      "User keeps keys on their device. Desk issues prepare-only key; signing happens off our infra.",
-    scopes: ["read:markets", "read:positions", "prepare:trade", "prepare:mint"],
-    custody: "none — signing off-box",
-    canExecute: false,
-    mintKey: true,
-  },
-};
-
-export function listTiers() {
-  return Object.values(TIERS).map((t) => ({
-    id: t.id,
-    label: t.label,
-    description: t.description,
-    scopes: t.scopes,
-    custody: t.custody,
-    canExecute: t.canExecute,
-  }));
-}
-
-export function getTier(id) {
-  const t = TIERS[id];
-  if (!t) throw new Error(`Unknown tier: ${id}`);
-  return t;
-}
-
-/**
- * Onboard a user wallet onto a tier. Returns one-time raw API key (except pure docs).
- * NEVER accepts or stores a private key.
- */
-export function onboardUser({
-  owner,
-  tier = "observer",
-  name,
-  controllerAllowlist = [],
-  storePath,
-  scopes, // optional override
-} = {}) {
-  if (owner && typeof owner === "object" && owner.privateKey) {
-    throw new Error("Refusing privateKey — non-custodial onboarding accepts owner address only");
-  }
-  const t = getTier(tier);
-  const finalScopes = scopes || t.scopes;
-  const result = createAgentKey({
-    owner,
-    name: name || `${t.label} key`,
-    scopes: finalScopes,
-    tier: t.id,
-    controllerAllowlist,
-    storePath,
-  });
-  return {
-    tier: t.id,
-    custody: t.custody,
-    canExecute: t.canExecute && finalScopes.includes(EXECUTE_SCOPE),
-    key: result.key, // show once
-    record: result.record,
-    nextSteps:
-      t.id === "local_signer"
-        ? [
-            "Store the API key for prepare/read calls only",
-            "Keep your wallet key on your device / hardware signer",
-            "Submit prepared payloads to your local signer — never upload the key here",
-          ]
-        : t.canExecute
-          ? [
-              "Store the API key securely",
-              "Live execute still requires MAD_EXECUTE_ENABLED=1 on the operator side",
-              "This key can only act on YOUR owner wallet (custody firewall)",
-            ]
-          : [
-              "Store the API key securely",
-              "Use with getSigner({ identity: auth.identity, venue }) after authenticateAgentKey",
-            ],
-  };
-}
-
-export function onboardAuthenticate(rawKey, opts) {
-  return authenticateAgentKey(rawKey, opts);
-}
-
-export function onboardListKeys(owner, opts) {
-  return listAgentKeys(owner, opts);
-}
-
-export function onboardRevoke(opts) {
-  return revokeAgentKey(opts);
-}

package/src/oracle-env.mjs

@@ -1,47 +0,0 @@
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export const ORACLE_CONFIG_DIR = join(homedir(), ".config", "oracle");
-// Legacy config dir from before the rename. Kept so existing installs keep
-// working; new installs only ever see ~/.config/oracle.
-export const LEGACY_CONFIG_DIR = join(homedir(), ".config", "mad-desk");
-
-export function env(primary, legacy, fallback = "") {
-  const pv = process.env[primary];
-  if (pv != null && String(pv).trim() !== "") return pv;
-  const lv = legacy ? process.env[legacy] : undefined;
-  if (lv != null && String(lv).trim() !== "") return lv;
-  return fallback;
-}
-
-export function envFlag(primary, legacy, defaultValue = false) {
-  const fallback = defaultValue ? "1" : "";
-  return String(env(primary, legacy, fallback)).trim() === "1";
-}
-
-const DISABLE_WORDS = ["0", "false", "off", "no"];
-
-// Reading a flag that may default ON. Only an explicit disable word turns it
-// off, and an unset value keeps `defaultValue`.
-//
-// The old shape (`!== "0"`) inverted with a false default: ORACLE_ONBOARD_HTTP
-// defaults off, so a user writing `false` to keep it off actually ENABLED it,
-// because "false" is not "0". A disable word must never enable a surface.
-export function envEnabled(primary, legacy, defaultValue = true) {
-  const raw = String(env(primary, legacy, "")).trim().toLowerCase();
-  if (raw === "") return defaultValue;
-  return !DISABLE_WORDS.includes(raw);
-}
-
-export function csvEnv(primary, legacy) {
-  return String(env(primary, legacy, ""));
-}
-
-export function configPath(file, primary, legacy) {
-  const explicit = env(primary, legacy, "");
-  if (explicit) return explicit;
-  const oraclePath = join(ORACLE_CONFIG_DIR, file);
-  if (existsSync(oraclePath)) return oraclePath;
-  return join(LEGACY_CONFIG_DIR, file);
-}

package/src/portfolio-risk.mjs

@@ -1,170 +0,0 @@
-// Pure portfolio exposure and coverage summary. This module performs no I/O.
-
-export const DEFAULT_RISK_THRESHOLDS = Object.freeze({
-  assetHighPct: 50,
-  assetMediumPct: 25,
-  chainHighPct: 75,
-  venueHighPct: 60,
-  stablecoinHighPct: 70,
-});
-
-const STABLECOINS = new Set(["USDC", "USDT", "USDT0", "DAI", "FRAX", "LUSD", "TUSD", "USDP", "GUSD", "PYUSD", "USDE"]);
-
-function finite(value) {
-  if (value === null || value === "" || value === undefined) return null;
-  const number = Number(value);
-  return Number.isFinite(number) && number >= 0 ? number : null;
-}
-
-function rounded(value) {
-  return Math.round((value + Number.EPSILON) * 1e8) / 1e8;
-}
-
-function pct(value, total) {
-  return total > 0 ? rounded((value / total) * 100) : null;
-}
-
-function addressOf(snapshot) {
-  return snapshot.address || snapshot.owner || snapshot.walletAddress || snapshot.wallet?.address || null;
-}
-
-function labelIndex(labels) {
-  const entries = Array.isArray(labels) ? labels : Array.isArray(labels?.entries) ? labels.entries : [];
-  const index = new Map();
-  for (const entry of entries) {
-    if (!entry?.address) continue;
-    const key = String(entry.address).toLowerCase();
-    if (!index.has(key)) index.set(key, entry);
-  }
-  return index;
-}
-
-function addAsset(output, raw, context = {}) {
-  if (!raw || typeof raw !== "object") return;
-  const symbol = String(raw.symbol ?? raw.coin ?? raw.name ?? raw.collection ?? raw.tokenId ?? "unknown");
-  const value = finite(raw.usdValue ?? raw.valueUsd ?? raw.knownUsd ?? raw.estimatedValueUsd ?? raw.floorValueUsd);
-  const kind = raw.kind === "nft" || raw.type === "nft" || raw.collection || raw.tokenId != null ? "nft" : "fungible";
-  output.push({
-    symbol,
-    usdValue: value,
-    chain: String(raw.chain ?? raw.chainName ?? context.chain ?? "unknown"),
-    venue: String(raw.venue ?? raw.protocol ?? raw.platform ?? context.venue ?? "wallet"),
-    address: raw.address ?? context.address ?? null,
-    kind,
-    stablecoin: raw.stablecoin === true || STABLECOINS.has(symbol.toUpperCase()),
-  });
-}
-
-function assetsFromSnapshot(snapshot) {
-  const output = [];
-  const rootAddress = addressOf(snapshot);
-  for (const asset of snapshot.assets || snapshot.holdings || []) addAsset(output, asset, { address: rootAddress, chain: snapshot.chain, venue: snapshot.venue });
-  for (const chain of snapshot.chains || []) {
-    const chainName = chain.chain ?? chain.name ?? chain.slug ?? (chain.chainId != null ? String(chain.chainId) : chain.family) ?? "unknown";
-    const context = { address: chain.address ?? rootAddress, chain: chainName, venue: chain.venue };
-    if (chain.native && (chain.native.amount == null || Number(chain.native.amount) !== 0)) {
-      addAsset(output, { ...chain.native, symbol: chain.native.symbol ?? chain.symbol ?? chainName }, context);
-    }
-    for (const asset of chain.assets || chain.fungibleTokens?.assets || []) addAsset(output, asset, context);
-    for (const asset of chain.collectibles?.assets || chain.nfts || []) addAsset(output, { ...asset, kind: "nft" }, context);
-    for (const asset of chain.spot?.balances || []) addAsset(output, asset, { ...context, venue: "Hyperliquid spot" });
-    const accountValue = finite(chain.perps?.accountValueUsd);
-    if (accountValue != null) addAsset(output, { symbol: "perps account", usdValue: accountValue }, { ...context, venue: "Hyperliquid perps" });
-  }
-  for (const item of snapshot.inventory?.items || snapshot.nfts?.items || []) addAsset(output, { ...item, kind: "nft" }, { address: rootAddress, chain: item.chain ?? snapshot.chain, venue: item.marketplace ?? snapshot.venue });
-  return output;
-}
-
-function snapshotKey(snapshot, index) {
-  const address = addressOf(snapshot);
-  const chain = snapshot.chain ?? snapshot.chainId ?? snapshot.family ?? "*";
-  return address ? `${String(address).toLowerCase()}|${String(chain).toLowerCase()}` : `snapshot:${index}`;
-}
-
-function buckets(assets, property, total) {
-  const map = new Map();
-  for (const asset of assets) {
-    if (asset.usdValue == null) continue;
-    const name = asset[property];
-    map.set(name, (map.get(name) || 0) + asset.usdValue);
-  }
-  return [...map].map(([name, knownUsd]) => ({ name, knownUsd: rounded(knownUsd), percentOfKnown: pct(knownUsd, total) }))
-    .sort((a, b) => b.knownUsd - a.knownUsd || a.name.localeCompare(b.name));
-}
-
-/**
- * Summarize already-fetched portfolio snapshots. Accepts either
- * `{ snapshots, labels, thresholds }` or an array plus an options object.
- */
-export function summarizePortfolioRisk(input = {}, options = {}) {
-  const snapshots = Array.isArray(input) ? input : Array.isArray(input.snapshots) ? input.snapshots : input.snapshot ? [input.snapshot] : [];
-  const labels = labelIndex(options.labels ?? options.addressBook ?? input.labels ?? input.addressBook);
-  const thresholds = { ...DEFAULT_RISK_THRESHOLDS, ...(input.thresholds || {}), ...(options.thresholds || {}) };
-  const unique = [];
-  const seen = new Set();
-  let duplicatesIgnored = 0;
-  snapshots.forEach((snapshot, index) => {
-    if (!snapshot || typeof snapshot !== "object") return;
-    const key = snapshotKey(snapshot, index);
-    if (seen.has(key)) duplicatesIgnored += 1;
-    else { seen.add(key); unique.push(snapshot); }
-  });
-
-  const assets = unique.flatMap(assetsFromSnapshot);
-  const priced = assets.filter((asset) => asset.usdValue != null);
-  const unknown = assets.filter((asset) => asset.usdValue == null);
-  const explicitUnknown = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.unpricedNonzeroItems || snapshot.unpricedNonzeroItems || 0), 0);
-  const totalKnownUsd = rounded(priced.reduce((sum, asset) => sum + asset.usdValue, 0));
-  const unknownItemCount = unknown.length + explicitUnknown;
-  const chainExposures = buckets(priced, "chain", totalKnownUsd);
-  const venueExposures = buckets(priced, "venue", totalKnownUsd);
-  const groupedAssets = buckets(priced, "symbol", totalKnownUsd);
-  for (const row of chainExposures) row.chain = row.name;
-  for (const row of venueExposures) row.venue = row.name;
-  for (const row of groupedAssets) {
-    row.asset = row.name;
-    row.symbol = row.name;
-  }
-  const stablecoinKnownUsd = rounded(priced.filter((asset) => asset.stablecoin).reduce((sum, asset) => sum + asset.usdValue, 0));
-  const nftAssets = assets.filter((asset) => asset.kind === "nft");
-  const snapshotNftUnvalued = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.nftUnvaluedItems || 0), 0);
-  const nftUnvaluedItems = nftAssets.filter((asset) => asset.usdValue == null).length + snapshotNftUnvalued;
-  const nftValuedItems = nftAssets.filter((asset) => asset.usdValue != null).length;
-  const top = groupedAssets[0] || null;
-  const concentrationLevel = !top ? "unknown" : top.percentOfKnown >= thresholds.assetHighPct ? "high" : top.percentOfKnown >= thresholds.assetMediumPct ? "medium" : "low";
-  const warnings = [];
-  if (unknownItemCount) warnings.push(`${unknownItemCount} nonzero holding(s) have unknown USD value; they are excluded from totals and percentages.`);
-  if (nftUnvaluedItems) warnings.push("NFT valuation coverage is partial; estimates are not executable bids and unvalued NFTs are not treated as zero.");
-  if (duplicatesIgnored) warnings.push(`${duplicatesIgnored} duplicate address/chain snapshot(s) were ignored.`);
-  if (top && concentrationLevel !== "low") warnings.push(`Asset concentration is ${concentrationLevel}: ${top.name} is ${top.percentOfKnown}% of known value.`);
-  if (chainExposures[0]?.percentOfKnown >= thresholds.chainHighPct) warnings.push(`Chain concentration is high: ${chainExposures[0].name} is ${chainExposures[0].percentOfKnown}% of known value.`);
-  if (venueExposures[0]?.percentOfKnown >= thresholds.venueHighPct) warnings.push(`Venue concentration is high: ${venueExposures[0].name} is ${venueExposures[0].percentOfKnown}% of known value.`);
-
-  const addresses = unique.map(addressOf).filter(Boolean).map((address) => {
-    const entry = labels.get(String(address).toLowerCase());
-    return { address, label: entry?.label ?? null, who: entry?.who ?? null, role: entry?.role ?? null };
-  });
-  return {
-    totalKnownUsd,
-    coverage: {
-      complete: unique.length > 0 && unknownItemCount === 0 && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false),
-      label: unknownItemCount === 0 && unique.length && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false)
-        ? "complete for the supplied snapshots" : "known priced value only; portfolio coverage is partial or unverified",
-      unknownUsd: unknownItemCount ? null : 0,
-      pricedItemCount: priced.length,
-      unknownItemCount,
-      snapshotCount: unique.length,
-      duplicatesIgnored,
-    },
-    chainExposures,
-    venueExposures,
-    topAssets: groupedAssets.slice(0, Math.max(1, Number(options.topAssets ?? input.topAssets ?? 10))),
-    concentrationRisk: { level: concentrationLevel, topAsset: top?.name ?? null, topAssetPercent: top?.percentOfKnown ?? null, thresholds: { mediumPct: thresholds.assetMediumPct, highPct: thresholds.assetHighPct } },
-    stablecoinExposure: { knownUsd: stablecoinKnownUsd, percentOfKnown: pct(stablecoinKnownUsd, totalKnownUsd), high: totalKnownUsd > 0 && pct(stablecoinKnownUsd, totalKnownUsd) >= thresholds.stablecoinHighPct },
-    nftCoverage: { status: nftAssets.length || snapshotNftUnvalued ? (nftUnvaluedItems ? "partial" : "valued") : "not-observed", valuedItems: nftValuedItems, unvaluedItems: nftUnvaluedItems, knownUsd: rounded(nftAssets.filter((asset) => asset.usdValue != null).reduce((sum, asset) => sum + asset.usdValue, 0)) },
-    addresses,
-    warnings: [...new Set(warnings)],
-  };
-}
-
-export const portfolioRiskSummary = summarizePortfolioRisk;

package/src/prepare-envelope.mjs

@@ -1,204 +0,0 @@
-// Canonical prepare envelope shared by Oracle prepare helpers and the local operator.
-// The versioned checksum binds payload and freshness metadata. It detects mutation.
-// Optional HMAC (ORACLE_STAMP_HMAC_SECRET) adds keyed integrity when configured.
-// Signer-owned policy, not this public checksum alone, authorizes execution.
-
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-
-export const PREPARE_VERSION = 2;
-/** Default max age for a prepared envelope at sign time (ms). */
-export const PREPARE_MAX_AGE_MS = 5 * 60 * 1000;
-/**
- * Hard ceiling for maxAgeMs. Caller/agent cannot widen past this.
- * Override upward only via signer-process env ORACLE_PREPARE_HARD_MAX_AGE_MS.
- */
-export const PREPARE_HARD_MAX_AGE_MS = (() => {
-  const n = Number(process.env.ORACLE_PREPARE_HARD_MAX_AGE_MS);
-  return Number.isFinite(n) && n > 0 ? n : 30 * 60 * 1000; // 30 minutes
-})();
-
-/** Resolve max age: default 5m, never above hard max (even if caller passes MAX_SAFE_INTEGER). */
-export function resolvePrepareMaxAgeMs(requested) {
-  const base =
-    requested == null || requested === ""
-      ? PREPARE_MAX_AGE_MS
-      : Number(requested);
-  if (!Number.isFinite(base) || base < 0) return PREPARE_MAX_AGE_MS;
-  return Math.min(base, PREPARE_HARD_MAX_AGE_MS);
-}
-
-function stableStringify(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-  const keys = Object.keys(value).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
-}
-
-function secretFrom(env) {
-  const s = String(env?.ORACLE_STAMP_HMAC_SECRET || "").trim();
-  return s.length >= 16 ? s : "";
-}
-
-function stampSecret(env = process.env) {
-  // The signer process owns its policy. An options env is useful for isolated
-  // tests and unkeyed clients, but cannot shadow a real process secret.
-  return secretFrom(process.env) || secretFrom(env);
-}
-
-function requireMac(env = process.env) {
-  return String(process.env.ORACLE_STAMP_REQUIRE_MAC || "").trim() === "1" ||
-    String(env?.ORACLE_STAMP_REQUIRE_MAC || "").trim() === "1";
-}
-
-/** Fields that bind the envelope (must not include the stamp fields themselves). */
-export function prepareBodyForHash(prepared) {
-  const {
-    oraclePrepared,
-    prepareHash,
-    prepareMac,
-    note,
-    ...body
-  } = prepared || {};
-  return body;
-}
-
-export function computePrepareHash(prepared) {
-  const body = prepareBodyForHash(prepared);
-  return createHash("sha256").update(stableStringify(body)).digest("hex");
-}
-
-export function computePrepareMac(prepareHash, secret = stampSecret()) {
-  if (!secret) return "";
-  return createHmac("sha256", secret).update(String(prepareHash)).digest("hex");
-}
-
-function safeEqualHex(a, b) {
-  try {
-    const ba = Buffer.from(String(a), "hex");
-    const bb = Buffer.from(String(b), "hex");
-    if (ba.length === 0 || ba.length !== bb.length) return false;
-    return timingSafeEqual(ba, bb);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Stamp a prepare result. Call at the end of every prepare helper.
- * @param {object} payload  provider-specific prepare fields (action/tx/psbt/...)
- */
-export function stampPrepared(payload, { provider, kind, env = process.env } = {}) {
-  if (!payload || typeof payload !== "object") throw new Error("stampPrepared: payload object required");
-  const base = {
-    ...payload,
-    provider: payload.provider || provider,
-    kind: payload.kind || kind,
-    requiresUserSignature: payload.requiresUserSignature !== false,
-    signingReady: false,
-    broadcastReady: false,
-    executionReady: false,
-  };
-  if (!base.provider) throw new Error("stampPrepared: provider required");
-  if (!base.kind) throw new Error("stampPrepared: kind required");
-  const preparedAt = Date.now();
-  const expiresAt = preparedAt + PREPARE_MAX_AGE_MS;
-  const prepareVersion = PREPARE_VERSION;
-  const withMeta = { ...base, preparedAt, expiresAt, prepareVersion };
-  const prepareHash = computePrepareHash(withMeta);
-  const secret = stampSecret(env);
-  const prepareMac = secret ? computePrepareMac(prepareHash, secret) : undefined;
-  const out = {
-    ...withMeta,
-    oraclePrepared: true,
-    prepareHash,
-  };
-  if (prepareMac) out.prepareMac = prepareMac;
-  return out;
-}
-
-/**
- * Verify a prepared envelope before operator sign.
- * @throws on mismatch / expiry / missing stamp
- */
-export function assertPreparedEnvelope(prepared, {
-  maxAgeMs = PREPARE_MAX_AGE_MS,
-  nowMs = Date.now(),
-  providers = null,
-  kinds = null,
-  label = "operator",
-  env = process.env,
-} = {}) {
-  if (!prepared || typeof prepared !== "object") {
-    throw new Error(`${label}: prepared envelope object required`);
-  }
-  if (prepared.oraclePrepared !== true) {
-    throw new Error(
-      `${label}: prepared integrity envelope missing — use an @oracle-agent/oracle prepare result`,
-    );
-  }
-  if (Number(prepared.prepareVersion) !== PREPARE_VERSION) {
-    throw new Error(`${label}: unsupported prepareVersion ${prepared.prepareVersion}`);
-  }
-  const expected = computePrepareHash(prepared);
-  if (String(prepared.prepareHash || "") !== expected) {
-    throw new Error(`${label}: prepareHash mismatch — payload was altered after prepare`);
-  }
-
-  const secret = stampSecret(env);
-  const mac = String(prepared.prepareMac || "");
-  // The MAC used to be enforced only when it was PRESENT or when
-  // ORACLE_STAMP_REQUIRE_MAC=1. That is the classic optional-MAC downgrade:
-  // prepareHash is an unkeyed sha256 an attacker can recompute via the
-  // exported computePrepareHash, so stripping prepareMac and recomputing the
-  // hash let a mutated payload pass a default-posture verifier.
-  //
-  // A verifier that HOLDS the stamp secret is by definition in keyed mode, so
-  // it now requires the MAC rather than treating its absence as opt-out. An
-  // attacker can still strip the field, but they cannot forge it, and a
-  // verifier with no secret configured is unchanged (checksum-only, exactly as
-  // documented — the signer's own policy remains the authoritative wall).
-  if (requireMac(env) || mac || secret) {
-    if (!secret) {
-      throw new Error(
-        `${label}: prepareMac present or ORACLE_STAMP_REQUIRE_MAC=1 but ORACLE_STAMP_HMAC_SECRET missing in signer`,
-      );
-    }
-    const expectedMac = computePrepareMac(expected, secret);
-    if (!mac || !safeEqualHex(mac, expectedMac)) {
-      throw new Error(`${label}: prepareMac mismatch — stamp not from trusted preparer`);
-    }
-  }
-
-  const preparedAt = Number(prepared.preparedAt);
-  const expiresAt = Number(prepared.expiresAt);
-  const effectiveMax = resolvePrepareMaxAgeMs(maxAgeMs);
-  const age = nowMs - preparedAt;
-  const lifetime = expiresAt - preparedAt;
-  if (
-    !Number.isFinite(age) ||
-    !Number.isFinite(expiresAt) ||
-    !Number.isFinite(lifetime) ||
-    age < 0 ||
-    lifetime <= 0 ||
-    lifetime > PREPARE_HARD_MAX_AGE_MS ||
-    age > effectiveMax ||
-    nowMs > expiresAt
-  ) {
-    throw new Error(
-      `${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${effectiveMax})`,
-    );
-  }
-  if (providers) {
-    const allow = new Set(providers);
-    if (!allow.has(prepared.provider)) {
-      throw new Error(`${label}: provider ${prepared.provider} not allowed here`);
-    }
-  }
-  if (kinds) {
-    const allow = new Set(kinds);
-    if (!allow.has(prepared.kind)) {
-      throw new Error(`${label}: kind ${prepared.kind} not allowed here`);
-    }
-  }
-  return true;
-}