@oracle-agent/oracle 0.11.0 → 0.12.0

package/src/public-api/grants.mjs

@@ -1,142 +0,0 @@
-// Oracle Public API — grant reads (Slice D).
-//
-// Pure, deterministic read functions over an INJECTED grant store. No DB, no
-// chain, no clock fallback: callers pass an array/Map of grant records plus an
-// explicit `now` (unix seconds). Same inputs always produce the same output.
-//
-// Imports ONLY from the assigned public peers (policy-schema.mjs) and the
-// sibling connect-agent.mjs for the shared no-secret invariant. Never from the
-// private executor stack.
-//
-// Store shape (injected, caller-owned):
-//   - an Array or Map whose entries are either
-//       a) a raw grant object (policy-schema shape), or
-//       b) a wrapper record { grant, revoked?, revokedAt? }.
-//   - revocation may also be supplied out-of-band via opts.revoked: a Set /
-//     array / Map-like of grant ids and/or revocation keys, or a function
-//     (id, grant) => boolean.
-//
-// Fail-closed rules:
-//   - records that do not validate against the public policy schema are
-//     EXCLUDED from active listings (a grant that cannot validate cannot
-//     authorize anything).
-//   - `now` is required for listActiveGrants; without a reference time we
-//     cannot prove liveness, so we refuse rather than guess.
-//   - every returned object passes the no-secret invariant scan.
-
-import { validateGrant, grantId, isExpired } from "../public-control/policy-schema.mjs";
-import { assertNoSecretMaterial } from "./connect-agent.mjs";
-
-export const GRANT_STATUS = Object.freeze({
-  ACTIVE: "active",
-  EXPIRED: "expired",
-  REVOKED: "revoked",
-  INVALID: "invalid",
-});
-
-function toRecords(store) {
-  if (store == null) return [];
-  if (Array.isArray(store)) return store;
-  if (store instanceof Map) return [...store.values()];
-  if (typeof store[Symbol.iterator] === "function") return [...store];
-  throw new TypeError("grant store must be an array, Map, or iterable of grant records");
-}
-
-function unwrap(record) {
-  if (record && typeof record === "object" && !Array.isArray(record) && record.grant != null) {
-    return {
-      grant: record.grant,
-      revoked: record.revoked === true || record.revokedAt != null,
-    };
-  }
-  return { grant: record, revoked: false };
-}
-
-function toSafeNow(now) {
-  const n = typeof now === "string" ? Number(now.trim()) : Number(now);
-  if (!Number.isSafeInteger(n) || n < 0) {
-    throw new TypeError("an explicit unix-seconds `now` is required (deterministic liveness, no wall-clock fallback)");
-  }
-  return n;
-}
-
-function isRevokedBy(revoked, id, grant) {
-  if (revoked == null) return false;
-  if (typeof revoked === "function") return revoked(id, grant) === true;
-  const keys = [id, grant.revocationKey];
-  if (revoked instanceof Set) return keys.some((k) => revoked.has(k));
-  if (Array.isArray(revoked)) return keys.some((k) => revoked.includes(k));
-  if (typeof revoked.has === "function") return keys.some((k) => revoked.has(k));
-  return false;
-}
-
-/**
- * Classify a single store record. Returns { status, id, grant } where grant
- * is the normalized public grant (null when invalid). Pure + deterministic.
- */
-export function classifyGrant(record, { now, revoked } = {}) {
-  const nowSec = toSafeNow(now);
-  const { grant: raw, revoked: recordRevoked } = unwrap(record);
-  const { ok, grant } = validateGrant(raw);
-  if (!ok) return { status: GRANT_STATUS.INVALID, id: null, grant: null };
-  const id = grantId(grant);
-  // Revocation takes precedence over expiry (matches session-key-model
-  // semantics: a revoked-then-expired grant still reports "revoked").
-  if (recordRevoked || isRevokedBy(revoked, id, grant)) {
-    return { status: GRANT_STATUS.REVOKED, id, grant };
-  }
-  if (isExpired(grant, nowSec)) return { status: GRANT_STATUS.EXPIRED, id, grant };
-  return { status: GRANT_STATUS.ACTIVE, id, grant };
-}
-
-/**
- * List grants that are currently ACTIVE: valid under the public policy
- * schema, not expired at `now`, and not revoked (per record flag or the
- * injected `revoked` source). Invalid records are silently excluded
- * (fail closed — they cannot authorize anything).
- *
- * Optional filters: { agentAddress, accountAddress, chainId }.
- *
- * @returns frozen array of { id, grant } sorted by id (deterministic order).
- */
-export function listActiveGrants(store, { now, revoked, agentAddress, accountAddress, chainId } = {}) {
-  const nowSec = toSafeNow(now);
-  const wantAgent = agentAddress != null ? String(agentAddress).trim().toLowerCase() : null;
-  const wantAccount = accountAddress != null ? String(accountAddress).trim().toLowerCase() : null;
-  const wantChain = chainId != null ? Number(chainId) : null;
-
-  const out = [];
-  for (const record of toRecords(store)) {
-    const { status, id, grant } = classifyGrant(record, { now: nowSec, revoked });
-    if (status !== GRANT_STATUS.ACTIVE) continue;
-    if (wantAgent != null && grant.agentAddress !== wantAgent) continue;
-    if (wantAccount != null && grant.accountAddress !== wantAccount) continue;
-    if (wantChain != null && grant.chainId !== wantChain) continue;
-    out.push(Object.freeze({ id, grant }));
-  }
-  out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  return assertNoSecretMaterial(Object.freeze(out));
-}
-
-/**
- * Look up a single grant by its public grant id. Returns
- * { id, status, grant } or null when no record in the store matches.
- * Unlike listActiveGrants this also surfaces expired/revoked grants (with
- * their status) so a UI can explain WHY a grant is not active — but invalid
- * records never match (they have no trustworthy id).
- */
-export function getGrant(store, id, { now, revoked } = {}) {
-  const nowSec = toSafeNow(now);
-  const wanted = String(id ?? "").trim().toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(wanted)) return null;
-  for (const record of toRecords(store)) {
-    const res = classifyGrant(record, { now: nowSec, revoked });
-    if (res.status === GRANT_STATUS.INVALID) continue;
-    if (res.id === wanted) {
-      return assertNoSecretMaterial(
-        Object.freeze({ id: res.id, status: res.status, grant: res.grant })
-      );
-    }
-  }
-  return null;
-}

package/src/public-api/http.mjs

@@ -1,389 +0,0 @@
-// Oracle Public HTTP surface (Slice G) — secret-free BFF over the public
-// read/assemble contract.
-//
-// Hard boundaries for this file:
-//   - Imports ONLY the public API/peer modules (connect-agent, grants,
-//     policy-schema, oracle-env). NEVER the private executor stack
-//     (get-signer, keystore, exec-policy, local-signer/*, adapters/*,
-//     exec-server, mint-capability).
-//   - NEVER signs anything and NEVER holds key material. Every payload this
-//     server emits is unsigned public data; the user signs client-side.
-//   - Fail-closed no-secret invariant: EVERY response body is recursively
-//     scanned with assertNoSecretMaterial() before it is written to the
-//     socket. If the scan throws, the body is dropped and the client gets
-//     500 { error: "secret-leak-blocked" } instead. The model proposes,
-//     the owner authorizes.
-//   - No auth secrets in code: this plane serves public reads/assembly only,
-//     binds to loopback by default, and carries no bearer/token logic.
-
-import { createServer } from "node:http";
-import { readFileSync, existsSync } from "node:fs";
-import { dirname, join, normalize, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import {
-  buildConnectRequest,
-  assembleUnsignedGrant,
-  assertNoSecretMaterial,
-  assertSerializedNoSecrets,
-  SecretLeakError,
-} from "./connect-agent.mjs";
-import { listActiveGrants, getGrant } from "./grants.mjs";
-import { GrantValidationError } from "../public-control/policy-schema.mjs";
-import { env } from "../oracle-env.mjs";
-
-const pkg = JSON.parse(
-  readFileSync(new URL("../../package.json", import.meta.url), "utf8")
-);
-
-export const PUBLIC_PLANE = "public";
-export const DEFAULT_HOST = "127.0.0.1";
-export const DEFAULT_PORT = 8799;
-export const VERSION = pkg.version;
-
-const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
-
-const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), "../..");
-const CONSOLE_DIR = join(ROOT_DIR, "public", "oracle-console");
-
-/** Allowlisted console static files only — no directory listing / traversal. */
-const STATIC_FILES = Object.freeze({
-  "/": { file: "index.html", type: "text/html; charset=utf-8" },
-  "/index.html": { file: "index.html", type: "text/html; charset=utf-8" },
-  "/app.js": { file: "app.js", type: "application/javascript; charset=utf-8" },
-  "/styles.css": { file: "styles.css", type: "text/css; charset=utf-8" },
-  "/oracle-console": { file: "index.html", type: "text/html; charset=utf-8" },
-  "/oracle-console/": { file: "index.html", type: "text/html; charset=utf-8" },
-  "/oracle-console/index.html": { file: "index.html", type: "text/html; charset=utf-8" },
-  "/oracle-console/app.js": { file: "app.js", type: "application/javascript; charset=utf-8" },
-  "/oracle-console/styles.css": { file: "styles.css", type: "text/css; charset=utf-8" },
-});
-
-/** Refuse absurd bodies before parsing (fail closed, cheap DoS guard). */
-const MAX_BODY_BYTES = 1_000_000;
-
-class HttpError extends Error {
-  constructor(status, code, message) {
-    super(message || code);
-    this.status = status;
-    this.code = code;
-  }
-}
-
-/**
- * Write a JSON response. The no-secret invariant runs HERE, on every body,
- * immediately before the bytes hit the socket.
- *
- * Two layers, in order:
- *   1. assertNoSecretMaterial() walks the object graph (precise path in the
- *      error, catches forbidden key names on real properties).
- *   2. assertSerializedNoSecrets() scans the ACTUAL JSON bytes we are about to
- *      write. This is the authoritative check: toJSON(), getters, symbol keys
- *      and non-enumerable properties can all put a value on the wire that the
- *      graph walk never visited.
- *
- * If either throws, the original body is never serialized to the client; a
- * fixed 500 secret-leak-blocked envelope is sent instead.
- */
-function send(res, status, body) {
-  let payloadStatus = status;
-  let json;
-  try {
-    assertNoSecretMaterial(body);
-    json = assertSerializedNoSecrets(body);
-  } catch {
-    payloadStatus = 500;
-    json = JSON.stringify({ error: "secret-leak-blocked" });
-  }
-  res.writeHead(payloadStatus, {
-    "content-type": "application/json; charset=utf-8",
-    "cache-control": "no-store",
-    "x-oracle-plane": PUBLIC_PLANE,
-    "x-oracle-unsigned": "true",
-  });
-  res.end(json);
-}
-
-function readJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let size = 0;
-    req.on("data", (chunk) => {
-      size += chunk.length;
-      if (size > MAX_BODY_BYTES) {
-        reject(new HttpError(413, "payload-too-large", "request body too large"));
-        req.destroy();
-        return;
-      }
-      chunks.push(chunk);
-    });
-    req.on("end", () => {
-      const raw = Buffer.concat(chunks).toString("utf8").trim();
-      if (raw === "") return resolve({});
-      try {
-        resolve(JSON.parse(raw));
-      } catch {
-        reject(new HttpError(400, "invalid-json", "request body must be valid JSON"));
-      }
-    });
-    req.on("error", () => reject(new HttpError(400, "bad-request", "request stream error")));
-  });
-}
-
-function asPlainObject(v, code) {
-  if (v == null) return {};
-  if (typeof v !== "object" || Array.isArray(v)) {
-    throw new HttpError(400, code, `${code} must be a JSON object`);
-  }
-  return v;
-}
-
-function normalizeHost(host) {
-  return String(host || "").trim().toLowerCase().replace(/^\[|\]$/g, "");
-}
-
-function assertLoopbackBindHost(host) {
-  const normalized = normalizeHost(host);
-  if (!LOOPBACK_HOSTS.has(normalized)) {
-    throw new TypeError(`oracle-public only binds loopback hosts; got ${String(host)}`);
-  }
-  return normalized === "::1" ? "::1" : String(host).trim();
-}
-
-// ---------------------------------------------------------------------------
-// Route handlers — each returns { status, body }; errors are thrown.
-// ---------------------------------------------------------------------------
-
-function handleHealth() {
-  return { status: 200, body: { ok: true, plane: PUBLIC_PLANE, version: VERSION } };
-}
-
-function handleConnectRequest(body) {
-  const b = asPlainObject(body, "body");
-  // Accept either { input, opts } or the raw grant fields as the body itself.
-  const input = b.input !== undefined ? asPlainObject(b.input, "input") : b;
-  const opts = asPlainObject(b.opts, "opts");
-  const rawInput = input === b ? (({ opts: _drop, ...rest }) => rest)(b) : input;
-  return { status: 200, body: buildConnectRequest(rawInput, opts) };
-}
-
-function handleConnectAssemble(body) {
-  const b = asPlainObject(body, "body");
-  const input =
-    b.request !== undefined
-      ? asPlainObject(b.request, "request")
-      : b.input !== undefined
-        ? asPlainObject(b.input, "input")
-        : b;
-  const opts = asPlainObject(b.opts, "opts");
-  const rawInput = input === b ? (({ opts: _drop, ...rest }) => rest)(b) : input;
-  return { status: 200, body: assembleUnsignedGrant(rawInput, opts) };
-}
-
-function handleGrantsActive(body) {
-  const b = asPlainObject(body, "body");
-  const opts = asPlainObject(b.opts, "opts");
-  const grants = listActiveGrants(b.store ?? [], opts);
-  return { status: 200, body: { ok: true, count: grants.length, grants } };
-}
-
-function handleGrantsGet(body) {
-  const b = asPlainObject(body, "body");
-  const opts = asPlainObject(b.opts, "opts");
-  const found = getGrant(b.store ?? [], b.id, opts);
-  if (found == null) {
-    return { status: 404, body: { error: "grant-not-found" } };
-  }
-  return { status: 200, body: found };
-}
-
-/**
- * Public runtime config for the browser console.
- *
- * Advertises which wallet-connection modes this deployment supports so the frontend
- * does not have to guess or hardcode. Two modes, both self-custodial:
- *
- *   injected  EIP-1193 / EIP-6963 browser wallet (MetaMask, Rabby, ...)
- *   privy     embedded/social login, still user-held keys
- *
- * A Privy APP ID is a PUBLIC client identifier -- it is designed to ship in
- * frontend bundles. The app SECRET is server-side and must never appear here, which
- * is why only the id is read and the send() path runs a secret scan over every
- * response body regardless.
- *
- * Absent env means the mode is simply unavailable. Reporting it as disabled is
- * honest; inventing a default app id would produce a broken login flow.
- */
-function handleConfig() {
-  const privyAppId = (process.env.ORACLE_PRIVY_APP_ID || process.env.PRIVY_APP_ID || "").trim();
-  const privyEnabled = privyAppId.length > 0;
-  // Injected wallets need no server config, so this deployment can always offer it.
-  const injectedEnabled = true;
-
-  const modes = [];
-  if (privyEnabled) modes.push("privy");
-  if (injectedEnabled) modes.push("injected");
-
-  return {
-    status: 200,
-    body: {
-      ok: true,
-      plane: PUBLIC_PLANE,
-      version: VERSION,
-      custody: {
-        // Stated explicitly: no deployment of the public plane ever holds keys.
-        selfCustodial: true,
-        signer: "user-wallet",
-        privyEnabled,
-        injectedEnabled,
-        modes,
-      },
-      privy: {
-        // Public client id only. Never the app secret.
-        appId: privyAppId || null,
-      },
-    },
-  };
-}
-
-const ROUTES = Object.freeze({
-  "GET /public/health": handleHealth,
-  "GET /public/config": handleConfig,
-  "POST /public/connect/request": handleConnectRequest,
-  "POST /public/connect/assemble": handleConnectAssemble,
-  "POST /public/grants/active": handleGrantsActive,
-  "POST /public/grants/get": handleGrantsGet,
-});
-
-function publicHeaders(extra = {}) {
-  return {
-    "cache-control": "no-store",
-    "x-oracle-plane": PUBLIC_PLANE,
-    "x-oracle-unsigned": "true",
-    ...extra,
-  };
-}
-
-function sendStatic(res, status, contentType, body) {
-  res.writeHead(status, publicHeaders({ "content-type": contentType }));
-  res.end(body);
-}
-
-/**
- * Serve allowlisted Oracle console assets only.
- * Returns true if the request was handled (including 404 for missing file).
- */
-function tryServeStatic(req, res, pathname) {
-  if (req.method !== "GET" && req.method !== "HEAD") return false;
-  // Keep trailing slash variants resolvable via STATIC_FILES keys.
-  const rawPath = pathname === "" ? "/" : pathname;
-  const meta = STATIC_FILES[rawPath] || STATIC_FILES[rawPath.replace(/\/+$/, "") || "/"];
-  if (!meta) return false;
-
-  const abs = normalize(join(CONSOLE_DIR, meta.file));
-  if (!abs.startsWith(CONSOLE_DIR + sep) && abs !== CONSOLE_DIR) {
-    send(res, 404, { error: "not-found", message: "unknown static path" });
-    return true;
-  }
-  if (!existsSync(abs)) {
-    send(res, 404, { error: "not-found", message: `missing static file ${meta.file}` });
-    return true;
-  }
-  const body = readFileSync(abs);
-  // Static HTML/JS/CSS are not JSON secret-scanned the same way as API bodies;
-  // content is repo-authored allowlisted files only.
-  if (req.method === "HEAD") {
-    res.writeHead(200, publicHeaders({
-      "content-type": meta.type,
-      "content-length": String(body.length),
-    }));
-    res.end();
-    return true;
-  }
-  sendStatic(res, 200, meta.type, body);
-  return true;
-}
-
-async function handleRequest(req, res) {
-  const url = new URL(req.url, "http://localhost");
-  // Preserve a single trailing slash only for static console aliases.
-  let pathname = url.pathname || "/";
-  if (pathname.length > 1 && pathname.endsWith("/") && pathname !== "/oracle-console/") {
-    pathname = pathname.replace(/\/+$/, "");
-  }
-  if (pathname === "") pathname = "/";
-  const routePath = pathname.replace(/\/+$/, "") || "/";
-  const key = `${req.method} ${routePath}`;
-  const handler = ROUTES[key];
-
-  try {
-    if (!handler) {
-      if (tryServeStatic(req, res, pathname)) return;
-      const pathKnown = Object.keys(ROUTES).some((k) => k.endsWith(` ${routePath}`));
-      if (pathKnown) throw new HttpError(405, "method-not-allowed", `unsupported method for ${routePath}`);
-      throw new HttpError(404, "not-found", `unknown route ${routePath}`);
-    }
-    const body = req.method === "GET" || req.method === "HEAD" ? undefined : await readJsonBody(req);
-    const out = handler(body);
-    send(res, out.status, out.body);
-  } catch (err) {
-    if (err instanceof SecretLeakError) {
-      // Never echo the leak path/rule detail either — fixed envelope only.
-      send(res, 500, { error: "secret-leak-blocked" });
-      return;
-    }
-    if (err instanceof GrantValidationError) {
-      send(res, 400, {
-        error: "invalid-grant",
-        errors: err.errors.map((e) => ({ field: e.field, message: e.message })),
-      });
-      return;
-    }
-    if (err instanceof HttpError) {
-      send(res, err.status, { error: err.code, message: err.message });
-      return;
-    }
-    if (err instanceof TypeError) {
-      send(res, 400, { error: "bad-request", message: err.message });
-      return;
-    }
-    // Unknown failure: fixed envelope, no internal detail leaves the server.
-    send(res, 500, { error: "internal-error" });
-  }
-}
-
-/** Build (but do not bind) the public HTTP server. */
-export function createPublicServer() {
-  return createServer((req, res) => {
-    handleRequest(req, res).catch(() => {
-      try {
-        send(res, 500, { error: "internal-error" });
-      } catch {
-        /* socket already gone */
-      }
-    });
-  });
-}
-
-/**
- * Resolve host/port: explicit args > ORACLE_PUBLIC_HOST/PORT env (via
- * oracle-env's env() helper) > loopback 127.0.0.1:8799 default.
- * Non-loopback binds fail closed; this plane has no remote peer/origin guard.
- */
-export function resolvePublicBind({ host, port } = {}) {
-  const h = assertLoopbackBindHost(host ?? env("ORACLE_PUBLIC_HOST", "MAD_PUBLIC_HOST", DEFAULT_HOST));
-  const rawPort = port ?? env("ORACLE_PUBLIC_PORT", "MAD_PUBLIC_PORT", String(DEFAULT_PORT));
-  const p = Number(rawPort);
-  if (!Number.isInteger(p) || p < 0 || p > 65535) {
-    throw new TypeError(`invalid public port: ${String(rawPort)}`);
-  }
-  return { host: h, port: p };
-}
-
-/** Create + bind the public server. Returns the node:http server instance. */
-export function startPublicServer(bind = {}) {
-  const { host, port } = resolvePublicBind(bind);
-  const server = createPublicServer();
-  server.listen(port, host);
-  return server;
-}