@oracle-agent/oracle 0.3.1 → 0.3.3

package/src/prepare-envelope.mjs

@@ -1,20 +1,28 @@
 // Canonical prepare envelope shared by Oracle prepare helpers and the local operator.
-// The versioned checksum binds payload and freshness metadata. It detects mutation;
-// signer-owned policy, not this public checksum, authorizes execution.
+// 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 } from "node:crypto";
+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 authenticated envelope lifetime (ms). */
+/**
+ * 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;
+  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);
+  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);
 }
@@ -26,11 +34,21 @@ function stableStringify(value) {
   return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
 }
 
+function stampSecret(env = process.env) {
+  const s = String(env.ORACLE_STAMP_HMAC_SECRET || "").trim();
+  return s.length >= 16 ? s : "";
+}
+
+function requireMac(env = process.env) {
+  return 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 || {};
@@ -42,11 +60,27 @@ export function computePrepareHash(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 } = {}) {
+export function stampPrepared(payload, { provider, kind, env = process.env } = {}) {
   if (!payload || typeof payload !== "object") throw new Error("stampPrepared: payload object required");
   const base = {
     ...payload,
@@ -64,11 +98,15 @@ export function stampPrepared(payload, { provider, kind } = {}) {
   const prepareVersion = PREPARE_VERSION;
   const withMeta = { ...base, preparedAt, expiresAt, prepareVersion };
   const prepareHash = computePrepareHash(withMeta);
-  return {
+  const secret = stampSecret(env);
+  const prepareMac = secret ? computePrepareMac(prepareHash, secret) : undefined;
+  const out = {
     ...withMeta,
     oraclePrepared: true,
     prepareHash,
   };
+  if (prepareMac) out.prepareMac = prepareMac;
+  return out;
 }
 
 /**
@@ -81,13 +119,14 @@ export function assertPreparedEnvelope(prepared, {
   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`
+      `${label}: prepared integrity envelope missing — use an @oracle-agent/oracle prepare result`,
     );
   }
   if (Number(prepared.prepareVersion) !== PREPARE_VERSION) {
@@ -97,6 +136,21 @@ export function assertPreparedEnvelope(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 || "");
+  if (requireMac(env) || mac) {
+    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);
@@ -112,7 +166,9 @@ export function assertPreparedEnvelope(prepared, {
     age > effectiveMax ||
     nowMs > expiresAt
   ) {
-    throw new Error(`${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${effectiveMax})`);
+    throw new Error(
+      `${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${effectiveMax})`,
+    );
   }
   if (providers) {
     const allow = new Set(providers);

package/src/vault-attestation.mjs

@@ -129,6 +129,7 @@ export function assertVaultAttestation(attestation, tx = {}, { chainId, nowMs =
 export function assertVaultApprovalAttestation(attestation, tx = {}, guard = {}, { chainId, nowMs = Date.now(), secret } = {}) {
   if (!attestation || attestation.mode !== "vault-attestation") throw new Error("vault attestation required");
   if (String(attestation.action) !== "deposit") throw new Error("vault approval requires deposit attestation");
+  assertFreshWindow(attestation, nowMs, "vault approval attestation");
   if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("vault attestation expired");
   const expected = hmac(attestationSecret(secret), canonicalJson(unsigned(attestation)));
   if (!sameSignature(attestation.signature, expected)) throw new Error("vault attestation signature mismatch");