@oracle-agent/oracle 0.1.0

package/src/public-api/http.mjs

@@ -0,0 +1,374 @@
+// 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 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export function resolvePublicBind({ host, port } = {}) {
+  const h = 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;
+}