@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/http/server.js

@@ -0,0 +1,276 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { buildMcpServer } from "../mcp/server.js";
+import { PUBLIC_CALLER } from "../tools/index.js";
+const KEY_PREFIX = "foga";
+/** Make an API key for a grant: shown once, stored only as its hash. */
+export function newApiKey(id) {
+    const key = `${KEY_PREFIX}.${id}.${randomBytes(24).toString("base64url")}`;
+    return { key, sha256: "0x" + createHash("sha256").update(key).digest("hex") };
+}
+/** The caller an Authorization header establishes: the public without one, the grant of a valid key, or null for an invalid key. */
+export function callerFromAuthorization(cfg, header) {
+    if (!header)
+        return { ...PUBLIC_CALLER, entrance: "http" };
+    const m = /^Bearer\s+(\S+)$/i.exec(header.trim());
+    if (!m)
+        return null;
+    const key = m[1];
+    const parts = key.split(".");
+    if (parts.length !== 3 || parts[0] !== KEY_PREFIX)
+        return null;
+    const grant = cfg.access.keys.find((k) => k.id === parts[1]);
+    if (!grant)
+        return null;
+    const given = Buffer.from(createHash("sha256").update(key).digest("hex"), "hex");
+    const stored = Buffer.from(grant.sha256.slice(2), "hex");
+    if (given.length !== stored.length || !timingSafeEqual(given, stored))
+        return null;
+    return { id: grant.id, entrance: "http", level: grant.level, visibility: grant.visibility };
+}
+/** A token bucket per client address: `limit` requests per minute, refilled continuously. */
+class RateLimiter {
+    perMinute;
+    buckets = new Map();
+    constructor(perMinute) {
+        this.perMinute = perMinute;
+    }
+    take(key) {
+        const now = Date.now();
+        const b = this.buckets.get(key) ?? { tokens: this.perMinute, at: now };
+        b.tokens = Math.min(this.perMinute, b.tokens + ((now - b.at) / 60_000) * this.perMinute);
+        b.at = now;
+        if (b.tokens < 1) {
+            this.buckets.set(key, b);
+            return false;
+        }
+        b.tokens -= 1;
+        this.buckets.set(key, b);
+        if (this.buckets.size > 10_000)
+            for (const [k, v] of this.buckets)
+                if (now - v.at > 120_000)
+                    this.buckets.delete(k);
+        return true;
+    }
+}
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function hostnameOf(value) {
+    if (!value)
+        return null;
+    try {
+        return new URL(`http://${value}`).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+function json(res, status, body) {
+    const text = JSON.stringify(body, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "content-length": Buffer.byteLength(text) });
+    res.end(text);
+}
+async function readBody(req, max) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > max)
+            return null;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/** The client address: the socket's, or the first X-Forwarded-For entry when the socket is the loopback (a reverse proxy on this host). */
+function clientAddress(req) {
+    const remote = req.socket.remoteAddress ?? "unknown";
+    const forwarded = req.headers["x-forwarded-for"];
+    if (forwarded && (remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1")) {
+        const first = (Array.isArray(forwarded) ? forwarded[0] : forwarded).split(",")[0].trim();
+        if (first)
+            return first;
+    }
+    return remote;
+}
+export function createHttpServer(o) {
+    const { node, catalog } = o;
+    const cfg = node.config;
+    const http = cfg.runtime.http;
+    const log = o.log ?? node.log;
+    const limiter = new RateLimiter(http.rateLimitPerMinute);
+    let loopback = false;
+    const mcp = createMcpHandler((ctx) => {
+        const caller = ctx.authInfo?.extra?.caller ?? { ...PUBLIC_CALLER, entrance: "http" };
+        return buildMcpServer({ node, catalog, caller, version: o.version });
+    }, { legacy: "stateless", maxRequestBodySize: http.maxBodyBytes, onerror: (e) => log(`mcp: ${e.message}`) });
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        const method = req.method ?? "GET";
+        // the edge: budget per address, the Host this server answers for, the Origin a browser sends
+        if (!limiter.take(clientAddress(req)))
+            return json(res, 429, { ok: false, gate: "rate", reason: `more than ${http.rateLimitPerMinute} requests a minute from this address` });
+        const host = hostnameOf(req.headers.host);
+        const allowedHosts = http.allowedHosts.length ? http.allowedHosts : loopback ? [...LOCAL_HOSTS] : null;
+        if (allowedHosts && (!host || !allowedHosts.includes(host)))
+            return json(res, 403, { ok: false, gate: "host", reason: "this server does not answer for that Host" });
+        const origin = req.headers.origin;
+        if (origin) {
+            const originHost = hostnameOf(origin.replace(/^https?:\/\//, ""));
+            const allowedOrigins = [...http.allowedOrigins, ...(loopback ? LOCAL_HOSTS : [])];
+            if (!originHost || !allowedOrigins.includes(originHost))
+                return json(res, 403, { ok: false, gate: "origin", reason: "Origin not allowed" });
+        }
+        // who is calling
+        const caller = callerFromAuthorization(cfg, req.headers.authorization);
+        if (!caller)
+            return json(res, 401, { ok: false, gate: "permission", reason: "the Authorization header carries no key this node knows" });
+        if (url.pathname === "/mcp") {
+            // the SDK reads and bounds the body itself; headers pass through, the caller rides in authInfo
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers))
+                if (v !== undefined && k !== "authorization")
+                    headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+            const body = method === "GET" || method === "HEAD" || method === "DELETE" ? undefined : await readBody(req, http.maxBodyBytes);
+            if (body === null)
+                return json(res, 413, { ok: false, gate: "input", reason: `request body over ${http.maxBodyBytes} bytes` });
+            const request = new Request(url, { method, headers, body: body ? new Uint8Array(body) : undefined });
+            const authInfo = { token: caller.id, clientId: caller.id, scopes: [caller.level], extra: { caller } };
+            const response = await mcp.fetch(request, { authInfo });
+            const out = {};
+            response.headers.forEach((v, k) => (out[k] = v));
+            out["cache-control"] = "no-store";
+            res.writeHead(response.status, out);
+            if (response.body)
+                for await (const chunk of response.body)
+                    res.write(chunk);
+            res.end();
+            return;
+        }
+        if (method === "GET" && url.pathname === "/healthz") {
+            let block = null;
+            try {
+                block = await node.kernel.blockNumber();
+            }
+            catch {
+                block = null;
+            }
+            return json(res, block === null ? 503 : 200, { ok: block !== null, cell: cfg.name, account: node.cell?.address ?? null, worldId: node.world.file.worldId, chainId: node.chainId, block, version: o.version });
+        }
+        if (method === "GET" && url.pathname === "/") {
+            const r = await catalog.invoke(node, "cell_status", {}, caller);
+            const decisions = node.store.summary().decisions;
+            return json(res, 200, { foga: o.version, cell: cfg.name, status: r.ok ? r.output : null, decisions, endpoints: { mcp: "/mcp", api: "/api/<capability>", health: "/healthz" } });
+        }
+        if (method === "GET" && url.pathname === "/api/capabilities")
+            return json(res, 200, { caller: { id: caller.id, level: caller.level, visibility: caller.visibility }, capabilities: catalog.list(caller) });
+        const jobMatch = /^\/api\/jobs\/([^/]+)$/.exec(url.pathname);
+        if (method === "GET" && jobMatch)
+            return answer(res, await catalog.invoke(node, "job_status", { jobId: decodeURIComponent(jobMatch[1]) }, caller));
+        const opMatch = /^\/api\/operations\/([^/]+)$/.exec(url.pathname);
+        if (method === "GET" && opMatch)
+            return answer(res, await catalog.invoke(node, "operation_status", { operationId: decodeURIComponent(opMatch[1]) }, caller));
+        if (method === "GET" && url.pathname === "/api/decisions")
+            return answer(res, await catalog.invoke(node, "decision_list", Object.fromEntries(url.searchParams), caller));
+        const capMatch = /^\/api\/([a-z][a-z0-9_]*)$/.exec(url.pathname);
+        if (capMatch) {
+            const name = capMatch[1];
+            const cap = catalog.get(name);
+            if (!cap)
+                return json(res, 404, { ok: false, gate: "input", reason: `unknown capability ${name}` });
+            if (method !== "POST" && !(method === "GET" && cap.action === "read"))
+                return json(res, 405, { ok: false, gate: "input", reason: "POST the input as JSON (GET for a read with query parameters)" });
+            let input = {};
+            if (method === "POST") {
+                if (!/^application\/json\b/i.test(req.headers["content-type"] ?? ""))
+                    return json(res, 415, { ok: false, gate: "input", reason: "Content-Type must be application/json" });
+                const body = await readBody(req, http.maxBodyBytes);
+                if (body === null)
+                    return json(res, 413, { ok: false, gate: "input", reason: `request body over ${http.maxBodyBytes} bytes` });
+                try {
+                    input = body.length ? JSON.parse(body.toString("utf8")) : {};
+                }
+                catch {
+                    return json(res, 400, { ok: false, gate: "input", reason: "the body is not JSON" });
+                }
+            }
+            else
+                input = Object.fromEntries(url.searchParams);
+            const mode = (url.searchParams.get("mode") ?? "act");
+            if (!["simulate", "build", "act"].includes(mode))
+                return json(res, 400, { ok: false, gate: "input", reason: "mode must be simulate, build or act" });
+            return answer(res, await catalog.invoke(node, name, input, caller, { mode }));
+        }
+        if (url.pathname.startsWith("/.well-known/") || url.pathname.startsWith("/documents/"))
+            return json(res, 404, { ok: false, reason: "not published yet" });
+        json(res, 404, { ok: false, reason: "no such path" });
+    }
+    function answer(res, r) {
+        if (r.ok)
+            return json(res, 200, r);
+        // credentials and permission are HTTP's business; a business refusal is an ordinary answer with ok: false
+        if (r.gate === "permission")
+            return json(res, 403, r);
+        if (r.gate === "input")
+            return json(res, 400, r);
+        json(res, 200, r);
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            log(`http: ${req.method} ${req.url}: ${e.message}`);
+            if (!res.headersSent)
+                json(res, 500, { ok: false, reason: "internal error" });
+            else
+                res.end();
+        });
+    });
+    server.requestTimeout = 60_000;
+    server.headersTimeout = 15_000;
+    return {
+        server,
+        listen(hostPort) {
+            const [hostRaw, portRaw] = splitHostPort(hostPort);
+            loopback = LOCAL_HOSTS.has(hostRaw);
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(Number(portRaw), hostRaw === "[::1]" ? "::1" : hostRaw, () => {
+                    const addr = server.address();
+                    const port = typeof addr === "object" && addr ? addr.port : Number(portRaw);
+                    const url = `http://${hostRaw.includes(":") && !hostRaw.startsWith("[") ? `[${hostRaw}]` : hostRaw}:${port}`;
+                    resolve({ server, url, close: () => new Promise((r) => { server.closeAllConnections(); server.close(() => r()); }) });
+                });
+            });
+        },
+    };
+}
+function splitHostPort(hostPort) {
+    const i = hostPort.lastIndexOf(":");
+    if (i < 0)
+        return ["127.0.0.1", hostPort];
+    return [hostPort.slice(0, i) || "127.0.0.1", hostPort.slice(i + 1)];
+}
+/** Run the watchers on the poll interval beside the server; returns a stop function. */
+export function startWatchLoop(watchers, intervalMs, log) {
+    let running = false;
+    let stopped = false;
+    const tick = async () => {
+        if (running || stopped)
+            return;
+        running = true;
+        try {
+            const r = await watchers.tick();
+            log(`${r.at} block ${r.block}: anchor ${r.anchor}, heartbeat ${r.heartbeat.sent ? "sent" : "not sent"} (${r.heartbeat.reason}); ${r.discovered.length} new tender(s); ${r.settled.length} settled, ${r.withdrawn.length} withdrawn; safety ${r.safety.verdict}${r.safety.changed ? " (changed)" : ""}`);
+        }
+        catch (e) {
+            log(`watch: ${e.message}`);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), intervalMs);
+    void tick();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}

package/dist/kernel/cell.js

@@ -0,0 +1,104 @@
+import { Contract } from "ethers";
+import { ReasonName, VerdictName } from "../core/asf.js";
+/**
+ * A cell as the kernel drives it: one FogaCellAccount, the owner key for administration and the operator key for
+ * acting. Every act of the cell is an `execute` through the account, keyed for the operation store.
+ */
+export class Cell {
+    kernel;
+    name;
+    address;
+    roles;
+    iface;
+    constructor(kernel, name, address, roles) {
+        this.kernel = kernel;
+        this.name = name;
+        this.address = address;
+        this.roles = roles;
+        this.iface = kernel.world.ifaceOf("foga:FogaCellAccount");
+    }
+    /**
+     * Deploy the account from the owner key. The requirement may name the account itself (as adopter / subject),
+     * so it is built from the address predicted for the deployment nonce and checked against the receipt.
+     */
+    static async deploy(kernel, p) {
+        const safety = kernel.asf.bindingRegistryAddress;
+        const owner = kernel.address(p.roles.owner);
+        const operator = kernel.address(p.roles.operator);
+        const recovery = p.roles.recovery ?? owner;
+        let predictedFor = null;
+        const { address } = await kernel.deploy(p.key, p.roles.owner, "foga:FogaCellAccount", [], (predicted) => {
+            predictedFor = predicted;
+            return [safety, owner, operator, p.roles.guardian, recovery, p.requirement(predicted)];
+        });
+        if (predictedFor && predictedFor.toLowerCase() !== address.toLowerCase()) {
+            throw new Error(`cell ${p.name}: deployed at ${address} but the requirement was built for ${predictedFor}; the deployer's nonce moved between prediction and inclusion`);
+        }
+        return new Cell(kernel, p.name, address, p.roles);
+    }
+    contract(runner) {
+        return new Contract(this.address, this.iface, runner ?? this.kernel.world.provider);
+    }
+    // ---------------------------------------------------------------------------- acting
+    /** The calldata of `execute(target, value, data)` on this account. */
+    encodeExecute(target, value, data) {
+        return this.iface.encodeFunctionData("execute", [target, value, data]);
+    }
+    /** Act as the cell: `execute(target, value, data)` signed by the operator (default) or the owner; `binding` ties the operation to the request that asked for it (the node). */
+    async execute(key, target, data, opts = {}) {
+        const signer = opts.by === "owner" ? this.roles.owner : this.roles.operator;
+        return this.kernel.tx.send({
+            key,
+            signer,
+            kind: "execute",
+            binding: opts.binding,
+            build: () => ({ to: this.address, data: this.encodeExecute(target, opts.value ?? 0n, data) }),
+        });
+    }
+    /** Owner administration (setOperator, setAIDRegistry, setCommitmentClass, setDeriskAllowed, ...). */
+    async admin(key, fn, args, binding) {
+        return this.kernel.tx.send({
+            key,
+            signer: this.roles.owner,
+            kind: "admin",
+            binding,
+            build: () => ({ to: this.address, data: this.iface.encodeFunctionData(fn, args) }),
+        });
+    }
+    /** Adopt a safety binding as the account and present it for a clause (owner-level bootstrap). */
+    async adoptBinding(key, input, clauseIndex = 0) {
+        const confirmed = await this.admin(key, "adoptBinding", [input, clauseIndex]);
+        const bindingId = this.kernel.event(confirmed.receipt, this.iface, "BindingAdopted", this.address).bindingId;
+        return { bindingId, confirmed };
+    }
+    // ---------------------------------------------------------------------------- views
+    async status() {
+        const r = await this.contract().status();
+        const reasons = Array.from(r[1], (x) => Number(x));
+        return {
+            verdict: Number(r[0]),
+            verdictName: VerdictName[Number(r[0])] ?? String(r[0]),
+            reasons,
+            reasonNames: reasons.map((x) => ReasonName[x] ?? String(x)),
+            restrictions: Array.from(r[2], (x) => Number(x)),
+        };
+    }
+    async presentedBindings() {
+        return Array.from(await this.contract().presentedBindings(), String);
+    }
+    async owner() {
+        return this.contract().owner();
+    }
+    async operator() {
+        return this.contract().operator();
+    }
+    async balance() {
+        return this.kernel.balance(this.address);
+    }
+    get operatorAddress() {
+        return this.kernel.address(this.roles.operator);
+    }
+    get ownerAddress() {
+        return this.kernel.address(this.roles.owner);
+    }
+}

package/dist/kernel/errors.js

@@ -0,0 +1,78 @@
+import { Interface } from "ethers";
+/**
+ * Revert decoding across every interface the kernel knows (world contracts, the cell account, the ERC-8004
+ * surface). A revert that bubbles out of FogaCellAccount.execute arrives as CallFailed(bytes) with the inner
+ * revert data inside; it is unwrapped so the message names the real cause.
+ */
+export class RevertDecoder {
+    ifaces = [];
+    seen = new Set();
+    add(iface, name) {
+        const key = name ?? iface.fragments.map((f) => f.format("sighash")).join("|");
+        if (this.seen.has(key))
+            return;
+        this.seen.add(key);
+        this.ifaces.push(iface);
+    }
+    /** Human-readable description of revert data, or null when nothing matches. */
+    describe(data) {
+        if (!data || data === "0x")
+            return null;
+        const selector = data.slice(0, 10);
+        if (selector === "0x08c379a0") {
+            try {
+                const [msg] = new Interface(["error Error(string)"]).decodeErrorResult("Error", data);
+                return `Error(${JSON.stringify(msg)})`;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        if (selector === "0x4e487b71") {
+            try {
+                const [code] = new Interface(["error Panic(uint256)"]).decodeErrorResult("Panic", data);
+                return `Panic(${code})`;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        for (const iface of this.ifaces) {
+            let parsed = null;
+            try {
+                parsed = iface.parseError(data);
+            }
+            catch {
+                parsed = null;
+            }
+            if (!parsed)
+                continue;
+            if (parsed.name === "CallFailed" && parsed.args.length === 1) {
+                const inner = this.describe(String(parsed.args[0]));
+                return `CallFailed(${inner ?? String(parsed.args[0])})`;
+            }
+            const args = parsed.args.map((a) => (typeof a === "bigint" ? a.toString() : Array.isArray(a) ? JSON.stringify(a.map(String)) : String(a)));
+            return `${parsed.name}(${args.join(", ")})`;
+        }
+        return null;
+    }
+    /** Extract revert data from an ethers error (CallException, or a JSON-RPC error with data). */
+    static revertData(err) {
+        if (!err)
+            return null;
+        if (typeof err.data === "string")
+            return err.data;
+        if (err.info?.error?.data && typeof err.info.error.data === "string")
+            return err.info.error.data;
+        if (err.error?.data && typeof err.error.data === "string")
+            return err.error.data;
+        const m = /0x[0-9a-fA-F]{8,}/.exec(err.info?.error?.message ?? err.shortMessage ?? err.message ?? "");
+        return m ? m[0] : null;
+    }
+    explain(err) {
+        const data = RevertDecoder.revertData(err);
+        const described = this.describe(data);
+        const base = err?.shortMessage ?? err?.message ?? String(err);
+        return described ? `${described} [${base}]` : base;
+    }
+}