@oracle-agent/oracle 0.2.4 → 0.3.1

package/README.md

@@ -226,7 +226,7 @@ owner-local source lane.** The short version:
 - Reads and quotes need **no keys**.
 - The public package exposes no signer, key vault, or broadcast path.
 - User wallets authorize prepared actions outside the public data plane.
-- The source-only operator signer is not a public API and is not shipped to npm.
+- Owner-local signing is shipped separately as `@oracle-agent/operator`; its agent-facing daemon supports only policy-bounded Hyperliquid and Polymarket execution.
 
 Run the read-only data plane:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
   "license": "Apache-2.0",
   "type": "module",

package/src/index.mjs

@@ -7,7 +7,15 @@
 // public package entrypoint, so importing the package cannot hand a caller a
 // signer.
 
-export { stampPrepared, assertPreparedEnvelope, computePrepareHash } from "./prepare-envelope.mjs";
+export {
+  stampPrepared,
+  assertPreparedEnvelope,
+  computePrepareHash,
+  resolvePrepareMaxAgeMs,
+  PREPARE_VERSION,
+  PREPARE_MAX_AGE_MS,
+  PREPARE_HARD_MAX_AGE_MS,
+} from "./prepare-envelope.mjs";
 export { data, dataCall, dataHealth, dataCatalog } from "./data/desk-data.mjs";
 export { registerProvider, getProvider, listProviders } from "./data/catalog.mjs";
 

package/src/prepare-envelope.mjs

@@ -1,12 +1,23 @@
-// Canonical prepare envelope — stamped by @oracle-agent/oracle prepare helpers,
-// verified by @oracle-agent/operator before any local sign/submit.
-// Keeps agentic UX identical: prepare() → exec(prepared). Blocks handcrafted actions.
+// 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.
 
 import { createHash } from "node:crypto";
 
-export const PREPARE_VERSION = 1;
+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). */
+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;
+})();
+
+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);
@@ -20,10 +31,7 @@ export function prepareBodyForHash(prepared) {
   const {
     oraclePrepared,
     prepareHash,
-    preparedAt,
-    prepareVersion,
     note,
-    // strip volatile display-only
     ...body
   } = prepared || {};
   return body;
@@ -52,8 +60,9 @@ export function stampPrepared(payload, { provider, kind } = {}) {
   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, prepareVersion };
+  const withMeta = { ...base, preparedAt, expiresAt, prepareVersion };
   const prepareHash = computePrepareHash(withMeta);
   return {
     ...withMeta,
@@ -78,20 +87,33 @@ export function assertPreparedEnvelope(prepared, {
   }
   if (prepared.oraclePrepared !== true) {
     throw new Error(
-      `${label}: refused handcrafted action — pass a stamped prepare result from @oracle-agent/oracle (oraclePrepared missing)`
+      `${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 age = nowMs - Number(prepared.preparedAt || 0);
-  if (!Number.isFinite(age) || age < 0 || age > maxAgeMs) {
-    throw new Error(`${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${maxAgeMs})`);
-  }
   const expected = computePrepareHash(prepared);
   if (String(prepared.prepareHash || "") !== expected) {
     throw new Error(`${label}: prepareHash mismatch — payload was altered after prepare`);
   }
+  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)) {