@finchip.ai/foga 0.6.0-alpha.6 → 0.6.0

package/dist/demo/quickstart.js

@@ -1,12 +1,15 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { formatEther, parseEther } from "ethers";
 import { anvilKeys } from "../genesis/roles.js";
 import { Kernel } from "../kernel/kernel.js";
 import { newApiKey } from "../http/server.js";
 import { loadCellConfig, saveCellConfig } from "../node/config.js";
+import { Node } from "../node/node.js";
+import { defaultCatalog, OPERATOR_CALLER } from "../tools/index.js";
+import { ensureWallet, ensuredKey, walletDir } from "../node/wallet.js";
 import { repoRoot } from "../util/fs.js";
 import { deployWorld } from "../world/deploy.js";
 import { ANVIL_INSTALL_HINT, anvilBinary, anvilVersion, launchAnvil, portInUse, portProblem, stopChild } from "./anvil.js";
@@ -14,7 +17,8 @@ import { birthCell } from "./birth.js";
 import { mintCases } from "./demander.js";
 import { cleanEnv, ownCli, waitForHttp } from "./loop-d.js";
 export const MARKER = "quickstart.json";
-export const PACKAGE_NAME = "@finchip.ai/foga";
+export { PACKAGE_NAME } from "../util/version.js";
+import { PACKAGE_NAME } from "../util/version.js";
 /** How a client should start this very CLI: the published package through npx, or this checkout's compiled launcher. */
 export function clientLauncher() {
     const root = repoRoot();
@@ -49,6 +53,12 @@ export async function runQuickstart(o = {}) {
     const listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
     const name = o.name ?? "quick";
     const rpc = `http://127.0.0.1:${port}`;
+    const walletPath = resolve(o.wallet ?? walletDir());
+    const nodeUrlPlanned = listen ? (() => {
+        const i = listen.lastIndexOf(":");
+        const host = listen.slice(0, i) || "127.0.0.1";
+        return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
+    })() : null;
     // --- say what is wrong before touching anything
     const anvilBin = anvilBinary();
     const version = anvilVersion(anvilBin.path);
@@ -62,6 +72,8 @@ export async function runQuickstart(o = {}) {
         if (await portInUse(lp))
             throw new Error(`port ${lp} is in use; pass --listen <host:port> for the node (or --no-serve to run no node)`);
     }
+    if (walletPath === dir || walletPath.startsWith(dir + sep))
+        throw new Error(`the wallet (${walletPath}) must live outside the quickstart directory (${dir}), which is cleared on every run`);
     if (existsSync(dir)) {
         const entries = readdirSync(dir);
         if (entries.length && !entries.includes(MARKER))
@@ -74,18 +86,34 @@ export async function runQuickstart(o = {}) {
     mkdirSync(dir, { recursive: true });
     const keysDir = join(dir, "keys");
     mkdirSync(keysDir, { recursive: true, mode: 0o700 });
+    // --- the wallet: the first step; made now when there is none, reused when there is; never a reason to stop
+    const wallet = ensureWallet(walletPath, { name: "default" });
+    const singleKey = wallet.wallet.roles.length === 1 && wallet.wallet.roles[0] === "signer";
+    const walletAddrs = singleKey ? `identity ${wallet.wallet.addresses.signer}` : `owner ${wallet.wallet.addresses.owner}, operator ${wallet.wallet.addresses.operator}, guardian ${wallet.wallet.addresses.guardian}`;
+    if (wallet.ephemeral)
+        log(`quickstart: wallet: could not write ${walletPath} (${wallet.reason}); using keys made in memory for this run — they are not kept`);
+    else
+        log(`quickstart: wallet: ${wallet.created ? "made" : "using"} ${wallet.wallet.dir} — ${walletAddrs}`);
     // --- the chain and the world
     log(`quickstart: starting ${version} on ${rpc} (log ${join(dir, "anvil.log")})`);
     const anvil = await launchAnvil({ port, logPath: join(dir, "anvil.log") });
     let node = null;
     let endedWith = null;
     const ended = new Promise((r) => (endedWith = r));
-    anvil.on("exit", (code, signal) => endedWith?.(`anvil stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+    // a stop asked for (Ctrl-C, --exit, SIGTERM) ends the children in order; their exits are then expected and do not end the run
+    // early — otherwise the node's exit would resolve `ended` while anvil is still being stopped and leave the chain running
+    let stopping = false;
+    anvil.on("exit", (code, signal) => {
+        if (!stopping)
+            endedWith?.(`anvil stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`);
+    });
     const stop = async () => {
+        stopping = true;
         if (node)
             await stopChild(node);
         node = null;
         await stopChild(anvil);
+        endedWith?.("stopped");
     };
     try {
         const worldPath = join(dir, "world.json");
@@ -106,6 +134,7 @@ export async function runQuickstart(o = {}) {
                 configPath: join(dir, "cell.config.json"),
                 storePath: join(dir, "cell.ops.sqlite"),
                 description: `Cell ${name}: born by foga quickstart on a local anvil chain`,
+                keys: { owner: ensuredKey(wallet, "owner"), operator: ensuredKey(wallet, "operator"), guardian: ensuredKey(wallet, "guardian") },
                 log: (line) => log(`quickstart: ${line}`),
                 configure: (cfg) => {
                     cfg.policy.budget = { dailyValueWei: parseEther("0.002").toString(), perOperationValueWei: parseEther("0.001").toString(), dailyGasWei: parseEther("0.05").toString(), maxConcurrentCommitments: 2 };
@@ -113,6 +142,8 @@ export async function runQuickstart(o = {}) {
                     cfg.runtime.pollSeconds = 2;
                     cfg.runtime.http.listen = listen ?? "127.0.0.1:8787";
                     cfg.runtime.http.rateLimitPerMinute = 600;
+                    if (nodeUrlPlanned)
+                        cfg.runtime.http.publicUrl = nodeUrlPlanned;
                 },
             });
         }
@@ -121,13 +152,16 @@ export async function runQuickstart(o = {}) {
             k.world.provider.destroy();
         }
         const configPath = cell.configPath;
-        // --- the keys, each in its own 0600 file (anvil money; nothing of value), and an act-level API key for the HTTP entrance
+        // --- the key files the configurations name: the wallet's own; an in-memory wallet is written beside the cell so the run still works
         const keyFile = (file, value) => {
             const path = join(keysDir, file);
             writeFileSync(path, value + "\n", { mode: 0o600 });
             return path;
         };
-        const keyPaths = { owner: keyFile("owner.key", cell.owner.privateKey), operator: keyFile("operator.key", cell.operator.privateKey), guardian: keyFile("guardian.key", cell.guardian.privateKey) };
+        const keyPaths = wallet.ephemeral
+            ? { owner: keyFile("owner.key", cell.owner.privateKey), operator: keyFile("operator.key", cell.operator.privateKey), guardian: keyFile("guardian.key", cell.guardian.privateKey) }
+            : { owner: wallet.wallet.files.owner, operator: wallet.wallet.files.operator, guardian: wallet.wallet.files.guardian };
+        // an act-level API key for the HTTP entrance
         const api = newApiKey("agent");
         {
             const loaded = loadCellConfig(configPath);
@@ -135,6 +169,23 @@ export async function runQuickstart(o = {}) {
             saveCellConfig(configPath, loaded.config);
         }
         const agentKeyPath = keyFile("agent.api-key", api.key);
+        // --- the cell says what it is: both skills offered, the documents built and committed on chain (the operator's act, in this process)
+        {
+            const loaded = loadCellConfig(configPath);
+            loaded.config.skills.offered = Object.keys(loaded.config.skills.held);
+            saveCellConfig(configPath, loaded.config);
+            const publisher = await Node.open({ configPath, rpc, keys: { operator: ensuredKey(wallet, "operator") }, log: () => { } });
+            try {
+                const r = await defaultCatalog().invoke(publisher, "docs_publish", {}, OPERATOR_CALLER, { mode: "act" });
+                if (!r.ok)
+                    throw new Error(`docs_publish: ${r.gate}: ${r.reason}`);
+                const out = r.output;
+                log(`quickstart: documents v${out.version} built in ${out.dir} and committed on chain (${out.committed.join(", ")})`);
+            }
+            finally {
+                publisher.close();
+            }
+        }
         // --- two tenders for the cell to find: a probe of the cell itself and an extraction over the fixture
         let minted = [];
         if (o.tenders ?? true) {
@@ -149,12 +200,17 @@ export async function runQuickstart(o = {}) {
             const host = listen.slice(0, i) || "127.0.0.1";
             nodeUrl = `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
             node = spawn(cli.command, [...cli.args, "node", "serve", "--config", configPath, "--rpc", rpc, "--listen", listen], { env: cleanEnv({ FOGA_OPERATOR_KEY_FILE: keyPaths.operator }), stdio: ["ignore", "ignore", "pipe"] });
+            // the node's lines are relayed, except a watcher tick in which nothing happened (every two seconds, forever)
+            const idleTick = /: anchor ACTIVE, heartbeat not sent \([^)]*\); 0 new tender\(s\); 0 settled, 0 withdrawn; safety Satisfied$/;
             node.stderr.on("data", (d) => {
                 for (const line of String(d).split("\n"))
-                    if (line.trim())
+                    if (line.trim() && !idleTick.test(line.trim()))
                         log(`  node| ${line}`);
             });
-            node.on("exit", (code, signal) => endedWith?.(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+            node.on("exit", (code, signal) => {
+                if (!stopping)
+                    endedWith?.(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`);
+            });
             await waitForHttp(`${nodeUrl}/healthz`);
             // --- the entrance answers: health, a public read, the agent key's pre-check of the first tender, the MCP handshake and tool list
             const health = (await (await fetch(`${nodeUrl}/healthz`)).json());
@@ -177,7 +233,15 @@ export async function runQuickstart(o = {}) {
             const toolCount = (toolsText.match(/"name":"/g) ?? []).length;
             if (toolCount < 20)
                 throw new Error(`the MCP entrance listed ${toolCount} tool(s) for the agent key; expected the act-level set`);
-            log(`quickstart: the entrance answers — /healthz ok, cell_status names ${cell.account}, tender ${minted[0]?.tokenId ?? "-"} eligible for the agent key, MCP initialize ok, ${toolCount} tools`);
+            const cardRes = await fetch(`${nodeUrl}/.well-known/agent-card.json`);
+            const cardDoc = (await cardRes.json());
+            if (!cardRes.ok || cardDoc.supportedInterfaces?.[0]?.url !== `${nodeUrl}/a2a`)
+                throw new Error(`the agent card at /.well-known/agent-card.json does not name ${nodeUrl}/a2a`);
+            const quoteRes = await fetch(`${nodeUrl}/a2a`, { method: "POST", headers: { "content-type": "application/json", "a2a-version": "1.0" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "SendMessage", params: { message: { messageId: "quickstart-quote", role: "ROLE_USER", parts: [{ text: "What can you do?" }] } } }) });
+            const quoteBody = (await quoteRes.json());
+            if (quoteBody.result?.task?.status?.state !== "TASK_STATE_COMPLETED")
+                throw new Error(`the A2A entrance did not answer a quote: ${JSON.stringify(quoteBody).slice(0, 200)}`);
+            log(`quickstart: the entrance answers — /healthz ok, cell_status names ${cell.account}, tender ${minted[0]?.tokenId ?? "-"} eligible for the agent key, MCP initialize ok, ${toolCount} tools; the agent card names ${nodeUrl}/a2a and a quote came back`);
         }
         // --- the stdio server the client configurations name, started as a client would start it: the operator's tool set over stdio
         const stdioTools = await stdioToolCount(cli, configPath, rpc, cleanEnv({ FOGA_OPERATOR_KEY_FILE: keyPaths.operator }));
@@ -197,12 +261,15 @@ export async function runQuickstart(o = {}) {
         lines.push(`foga quickstart: a FOGA cell is live on a local chain`);
         lines.push("");
         lines.push(`  chain     anvil on ${rpc} (chain ${world.chainId}), world ${world.worldId} — the chain lives as long as this process`);
-        lines.push(`  cell      ${name} = ${cell.account}${cell.agentId ? ` (ERC-8004 agent ${cell.agentId})` : ""}; owner, operator and guardian keys in ${keysDir} (anvil money, no value)`);
+        lines.push(`  cell      ${name} = ${cell.account}${cell.agentId ? ` (ERC-8004 agent ${cell.agentId})` : ""}`);
+        const walletRoles = singleKey ? `identity ${cell.owner.address} (one key, every role)` : `owner ${cell.owner.address}, operator ${cell.operator.address}, guardian ${cell.guardian.address}`;
+        lines.push(`  wallet    ${wallet.ephemeral ? `keys made in memory for this run, written to ${keysDir} (${walletPath} was not writable)` : `${wallet.wallet.dir} (${wallet.created ? "made now" : "reused"}) — ${walletRoles}; the same wallet on every run`}`);
         lines.push(`  skills    ${Object.keys(cell.held).join(", ")} (held and offered)`);
         if (minted.length)
             lines.push(`  tenders   ${minted.map((c) => `#${c.tokenId} ${c.skill} (${formatEther(c.rewardWei)} ETH)`).join(", ")} — open, waiting for the cell to take them`);
         if (nodeUrl)
-            lines.push(`  node      ${nodeUrl} — /mcp (Streamable HTTP), /api/<capability>, /healthz; its watchers settle and withdraw what the cell commits to`);
+            lines.push(`  node      ${nodeUrl} — /mcp (Streamable HTTP), /api/<capability>, /a2a (A2A 1.0, JSON-RPC), /.well-known/agent-card.json, /documents/*, /healthz; its watchers settle and withdraw`);
+        lines.push(`  documents ${join(dir, "documents")} — registration, AID document, ARD descriptor, AUF unit, agent card, server.json; committed on chain${nodeUrl ? ` as URLs under ${nodeUrl}` : ""}`);
         lines.push(`  files     ${configPath} (the cell), ${join(dir, "connect.md")} (this text), ${mcpDir}${process.platform === "win32" ? "\\" : "/"}*.json (the client configurations)`);
         lines.push("");
         lines.push("Connect an MCP client over stdio (the client starts the server on this machine; with the operator key it acts for the cell):");
@@ -217,6 +284,8 @@ export async function runQuickstart(o = {}) {
             lines.push("Or over HTTP (a client on another machine, or any agent runtime that speaks HTTP):");
             lines.push(`  MCP      ${nodeUrl}/mcp   with the header   Authorization: Bearer ${api.key}   (${join(mcpDir, "http-mcp.json")})`);
             lines.push(`  API      ${nodeUrl}/api/<capability>, POST a JSON body (reads also GET); the same header for acts. GET ${nodeUrl}/api/capabilities lists them.`);
+            lines.push(`  A2A      POST ${nodeUrl}/a2a with A2A-Version: 1.0 — SendMessage for a quote (anyone) or a tender ({"foga":{"mode":"tender","tokenId":"…"}}, the header above); the card is at ${nodeUrl}/.well-known/agent-card.json`);
+            lines.push(`  wallet   a credential of your own instead of the key: Authorization: FOGA-EIP712 <envelope> signed by any wallet (foga wallet sign --url ${nodeUrl} prints one; docs/wallet.md)`);
             lines.push(`           curl -s ${nodeUrl}/api/cell_status`);
             if (minted.length)
                 lines.push(`           curl -s -X POST ${nodeUrl}/api/tender_precheck -H "content-type: application/json" -H "authorization: Bearer ${api.key}" -d "{\\"tokenId\\":\\"${minted[0].tokenId}\\"}"`);
@@ -227,11 +296,27 @@ export async function runQuickstart(o = {}) {
         lines.push(`  FOGA_DEMANDER_KEY=<a funded key, anvil's first account by default> ${demanderCmd}`);
         if (launcher.fromCheckout)
             lines.push(`(This is a checkout: the configurations start ${launcher.command} ${launcher.args.join(" ")}; a published install would start npx -y ${PACKAGE_NAME}.)`);
+        // Next: what a cell should do once it runs — advice, kept out of the first run on purpose (docs/node.md, "Advice").
+        try {
+            const { adviseCell, formatAdvice } = await import("../node/advise.js");
+            const reader = await Node.open({ configPath, rpc, keys: {}, allowUnborn: true, log: () => { } });
+            try {
+                const next = formatAdvice(adviseCell(reader), { brief: true, config: configPath });
+                if (next)
+                    lines.push("", next);
+            }
+            finally {
+                reader.close();
+            }
+        }
+        catch {
+            // advice is never a reason for a quickstart to fail
+        }
         lines.push("");
         lines.push(o.exit ? "Started with --exit: stopping the node and the chain." : "Ctrl-C stops the node and the chain; the next quickstart starts over in the same directory.");
         const summary = lines.join("\n");
         writeFileSync(join(dir, "connect.md"), `# foga quickstart\n\n\`\`\`\n${summary}\n\`\`\`\n`);
-        writeFileSync(join(dir, MARKER), JSON.stringify({ schema: "foga.quickstart/1", createdAt: new Date().toISOString(), rpc, chainId: world.chainId, worldId: world.worldId, cell: name, account: cell.account, agentId: cell.agentId, nodeUrl, tenders: minted.map((c) => c.tokenId), anvil: version }, null, 2) + "\n");
+        writeFileSync(join(dir, MARKER), JSON.stringify({ schema: "foga.quickstart/1", createdAt: new Date().toISOString(), rpc, chainId: world.chainId, worldId: world.worldId, cell: name, account: cell.account, agentId: cell.agentId, wallet: wallet.ephemeral ? null : wallet.wallet.dir, nodeUrl, tenders: minted.map((c) => c.tokenId), anvil: version }, null, 2) + "\n");
         out(summary);
         return {
             dir,
@@ -242,6 +327,7 @@ export async function runQuickstart(o = {}) {
             configPath,
             account: cell.account,
             agentId: cell.agentId,
+            wallet: { dir: wallet.wallet.dir, created: wallet.created, ephemeral: wallet.ephemeral, addresses: wallet.wallet.addresses },
             keys: { ...keyPaths, agentApiKey: agentKeyPath },
             apiKey: api.key,
             nodeUrl,

package/dist/genesis/operator-scope.js

@@ -12,6 +12,7 @@ export const SCOPE_GROUPS = {
         { contract: "8444/ARDOnchainRegistry", fn: "register(bytes32,address,uint256,bytes32,string,string)" },
         { contract: "8444/ARDOnchainRegistry", fn: "updateDescriptor(bytes32,bytes32,string,string)" },
         { contract: "8454/AUFUnitRegistry", fn: "registerUnit(address,bytes32,string,(uint256,uint32)[])" },
+        { contract: "8454/AUFUnitRegistry", fn: "publishVersion(uint256,bytes32,string,(uint256,uint32)[])" },
         { contract: "8447/ERC8004Eligibility", fn: "declareAgent(uint256)" },
     ],
     standing: [{ contract: "8419/KYARegistry", fn: "attestWithProof((bytes32,bytes),bytes32,bytes,bytes,string)" }],

package/dist/genesis/probe.js

@@ -18,6 +18,22 @@ export async function runProbe(world, input) {
         throw new Error(`block ${input.block} not found`);
     const at = { blockTag: tag };
     const fromBlock = input.lookback === undefined ? 0 : Math.max(0, input.block - input.lookback);
+    // A bounded scan is asked in windows of 2000 blocks, the windows in parallel and their logs concatenated in block
+    // order — the same logs a single query returns, in the same order (the answer hash is over them, so this must not
+    // change), but each request small enough for a public endpoint, which caps the range of `eth_getLogs` and answers
+    // a 9000-block scan slowly or not at all: a skill run on Sepolia overran its worker's budget on exactly this. An
+    // unbounded scan (no lookback: a local chain) stays one query.
+    const WINDOW = 2000;
+    const logsOf = async (c, filter) => {
+        const to = input.block;
+        if (input.lookback === undefined || to - fromBlock < WINDOW)
+            return c.queryFilter(filter, fromBlock, to);
+        const windows = [];
+        for (let a = fromBlock; a <= to; a += WINDOW)
+            windows.push([a, Math.min(a + WINDOW - 1, to)]);
+        const parts = await Promise.all(windows.map(([a, b]) => c.queryFilter(filter, a, b)));
+        return parts.flat();
+    };
     const section = async (fn) => {
         try {
             return await fn();
@@ -95,13 +111,13 @@ export async function runProbe(world, input) {
     });
     checks.erc8454 = await section(async () => {
         const units = world.contract("8454/AUFUnitRegistry");
-        const logs = await units.queryFilter(units.filters.UnitRegistered(null, subject), fromBlock, input.block);
+        const logs = await logsOf(units, units.filters.UnitRegistered(null, subject));
         return { unitsControlled: logs.map((l) => String(l.args.unitId)) };
     });
     checks.erc8338 = await section(async () => {
         const skills = world.contract("8338/SkillToken");
         const held = String(await skills.balanceOf(subject, at));
-        const received = await skills.queryFilter(skills.filters.Transfer(null, subject), fromBlock, input.block);
+        const received = await logsOf(skills, skills.filters.Transfer(null, subject));
         const ids = new Set();
         for (const l of received)
             ids.add(String(l.args.tokenId));
@@ -122,13 +138,13 @@ export async function runProbe(world, input) {
     checks.erc8414 = await section(async () => {
         const tasks = world.contract("8414/TaskToken");
         const held = String(await tasks.balanceOf(subject, at));
-        const submitted = await tasks.queryFilter(tasks.filters.FulfillmentSubmitted(null, null, subject), fromBlock, input.block);
-        const accepted = await tasks.queryFilter(tasks.filters.FulfillmentAccepted(null, null, subject), fromBlock, input.block);
+        const submitted = await logsOf(tasks, tasks.filters.FulfillmentSubmitted(null, null, subject));
+        const accepted = await logsOf(tasks, tasks.filters.FulfillmentAccepted(null, null, subject));
         return { held, submissions: String(submitted.length), accepted: String(accepted.length) };
     });
     checks.erc8447 = await section(async () => {
         const swarms = world.contract("8447/SwarmRegistry");
-        const activated = await swarms.queryFilter(swarms.filters.MemberActivated(null, subject), fromBlock, input.block);
+        const activated = await logsOf(swarms, swarms.filters.MemberActivated(null, subject));
         const ids = [...new Set(activated.map((l) => String(l.args.swarmId)))].sort();
         const memberships = [];
         for (const swarmId of ids)
@@ -137,12 +153,12 @@ export async function runProbe(world, input) {
     });
     checks.erc8436 = await section(async () => {
         const acdf = world.contract("8436/ACDFRegistry");
-        const filed = await acdf.queryFilter(acdf.filters.IssueFiled(null, null, null, subject), fromBlock, input.block);
+        const filed = await logsOf(acdf, acdf.filters.IssueFiled(null, null, null, subject));
         return { issuesFiled: String(filed.length) };
     });
     checks.erc8471 = await section(async () => {
         const adrf = world.contract("8471/ADRFDisputeRegistry");
-        const filed = await adrf.queryFilter(adrf.filters.CaseFiled(), fromBlock, input.block);
+        const filed = await logsOf(adrf, adrf.filters.CaseFiled());
         let asParty = 0;
         for (const l of filed) {
             if (String(l.args.claimant).toLowerCase() === low || String(l.args.respondent).toLowerCase() === low)

package/dist/http/access.js

@@ -0,0 +1,105 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { getAddress } from "ethers";
+import { accountSubject } from "../core/kya.js";
+import { ACTION_RANK, PUBLIC_CALLER } from "../tools/index.js";
+import { SIGNED_SCHEME, verifyAuthorization } from "./signed.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 };
+}
+export async function resolveCaller(i) {
+    const { node } = i;
+    const cfg = node.config;
+    const header = i.authorization?.trim();
+    if (!header)
+        return { caller: { ...PUBLIC_CALLER, entrance: "http" }, via: "anonymous" };
+    if (/^bearer\s/i.test(header)) {
+        const caller = callerFromAuthorization(cfg, header);
+        if (!caller)
+            return { caller: null, status: 401, reason: "the Authorization header carries no key this node knows" };
+        return { caller, via: "key" };
+    }
+    if (new RegExp(`^${SIGNED_SCHEME}\\s`, "i").test(header)) {
+        if (!node.cell)
+            return { caller: null, status: 403, reason: "this node has no cell to sign for yet" };
+        const v = verifyAuthorization(header, { chainId: node.chainId, cell: node.cell.address, method: i.method, path: i.path, body: i.body, now: i.now, nonces: i.nonces });
+        if (!v.ok)
+            return { caller: null, status: 401, reason: `signature refused: ${v.reason}` };
+        const grant = await grantFor(node, v.envelope);
+        if (!grant)
+            return { caller: null, status: 403, reason: "this node does not accept signatures (access.signers.default is none)" };
+        let level = grant.level;
+        if (!v.bound && cfg.access.signers.actsNeedRequestBinding && ACTION_RANK[level] >= ACTION_RANK.act)
+            level = "build";
+        return { caller: { id: v.envelope.signer, entrance: "http", level, visibility: grant.visibility }, via: "signature", signer: v.envelope };
+    }
+    return { caller: null, status: 401, reason: `the Authorization scheme is not one this node accepts (Bearer <key> or ${SIGNED_SCHEME} <envelope>)` };
+}
+/** The grant a verified signer gets, from the cell's roles, the configuration's grants, its standing, or the default. */
+export async function grantFor(node, e) {
+    const cfg = node.config;
+    const signer = getAddress(e.signer);
+    const roles = [
+        ["operator", cfg.identity.operator],
+        ["owner", cfg.identity.owner],
+    ];
+    for (const [name, address] of roles)
+        if (getAddress(address) === signer)
+            return { level: "act", visibility: "operator", why: `the cell's ${name}` };
+    const s = cfg.access.signers;
+    const byAddress = s.allow.find((g) => g.address && getAddress(g.address) === signer);
+    if (byAddress)
+        return { level: byAddress.level, visibility: byAddress.visibility, why: `granted by address${byAddress.note ? ` (${byAddress.note})` : ""}` };
+    if (e.agentId) {
+        const byAgent = s.allow.find((g) => g.agentId && g.agentId === e.agentId);
+        if (byAgent && (await actsForAgent(node, signer, e.agentId)))
+            return { level: byAgent.level, visibility: byAgent.visibility, why: `granted as ERC-8004 agent ${e.agentId}` };
+    }
+    if (s.standing && cfg.identity.standing) {
+        try {
+            const subject = accountSubject(node.chainId, signer);
+            const meets = await node.kernel.kya.check(subject, cfg.identity.standing.schemeId, s.standing.minLevel, cfg.identity.standing.issuers);
+            if (meets)
+                return { level: s.standing.level, visibility: s.standing.visibility, why: `KYA standing at level ${s.standing.minLevel} or above` };
+        }
+        catch {
+            /* no standing readable: the default applies */
+        }
+    }
+    if (s.default === "none")
+        return null;
+    return { level: s.default, visibility: "caller", why: "any valid signer" };
+}
+/** Whether `signer` is the owner or the agent wallet of ERC-8004 agent `agentId` on this world's registry. */
+export async function actsForAgent(node, signer, agentId) {
+    try {
+        const id = BigInt(agentId);
+        const [owner, wallet] = await Promise.all([node.kernel.identity.ownerOf(id).catch(() => null), node.kernel.identity.agentWallet(id).catch(() => null)]);
+        return [owner, wallet].some((a) => a && getAddress(a) === getAddress(signer));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/http/server.js

@@ -1,34 +1,16 @@
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { createMcpHandler } from "@modelcontextprotocol/server";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { A2AServer } from "../a2a/server.js";
+import { A2A_ERRORS, A2A_WELL_KNOWN } from "../a2a/types.js";
 import { buildMcpServer } from "../mcp/server.js";
+import { DOCUMENT_FILES, documentsDir, readManifest } from "../node/documents.js";
+import { buildPropagationManifest, servicesCatalogOf } from "../node/propagation.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 };
-}
+import { resolveCaller } from "./access.js";
+import { NonceCache } from "./signed.js";
+export { callerFromAuthorization, newApiKey } from "./access.js";
 /** A token bucket per client address: `limit` requests per minute, refilled continuously. */
 class RateLimiter {
     perMinute;
@@ -98,6 +80,8 @@ export function createHttpServer(o) {
     const http = cfg.runtime.http;
     const log = o.log ?? node.log;
     const limiter = new RateLimiter(http.rateLimitPerMinute);
+    const nonces = new NonceCache();
+    const a2a = new A2AServer(node, catalog, log);
     let loopback = false;
     const mcp = createMcpHandler((ctx) => {
         const caller = ctx.authInfo?.extra?.caller ?? { ...PUBLIC_CALLER, entrance: "http" };
@@ -120,19 +104,21 @@ export function createHttpServer(o) {
             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" });
+        // the body first (a signature may be bound to it), then who is calling
+        const bodyless = method === "GET" || method === "HEAD" || method === "DELETE";
+        const body = bodyless ? null : await readBody(req, http.maxBodyBytes);
+        if (body === null && !bodyless)
+            return json(res, 413, { ok: false, gate: "input", reason: `request body over ${http.maxBodyBytes} bytes` });
+        const resolved = await resolveCaller({ node, authorization: req.headers.authorization, method, path: url.pathname + url.search, body: body ? new Uint8Array(body) : null, nonces });
+        if (!resolved.caller)
+            return json(res, resolved.status, { ok: false, gate: "permission", reason: resolved.reason });
+        const caller = resolved.caller;
         if (url.pathname === "/mcp") {
-            // the SDK reads and bounds the body itself; headers pass through, the caller rides in authInfo
+            // 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 });
@@ -146,6 +132,24 @@ export function createHttpServer(o) {
             res.end();
             return;
         }
+        // A2A 1.0, the JSON-RPC binding: the version as a header (or the A2A-Version query parameter), JSON in and out
+        if (url.pathname === "/a2a") {
+            if (method !== "POST")
+                return json(res, 405, { jsonrpc: "2.0", id: null, error: { code: A2A_ERRORS.InvalidRequestError, message: "POST a JSON-RPC 2.0 request" } });
+            if (!/^application\/json\b/i.test(req.headers["content-type"] ?? ""))
+                return json(res, 415, { jsonrpc: "2.0", id: null, error: { code: A2A_ERRORS.InvalidRequestError, message: "Content-Type must be application/json" } });
+            let rpc;
+            try {
+                rpc = body && body.length ? JSON.parse(body.toString("utf8")) : null;
+            }
+            catch {
+                return json(res, 200, { jsonrpc: "2.0", id: null, error: { code: A2A_ERRORS.JSONParseError, message: "Invalid JSON payload" } });
+            }
+            const versionHeader = req.headers["a2a-version"];
+            const version = (Array.isArray(versionHeader) ? versionHeader[0] : versionHeader) ?? url.searchParams.get("A2A-Version") ?? undefined;
+            // A2A-Extensions a client declares are ignored: this agent requires none and offers none
+            return json(res, 200, await a2a.handle(rpc, caller, version));
+        }
         if (method === "GET" && url.pathname === "/healthz") {
             let block = null;
             try {
@@ -159,10 +163,10 @@ export function createHttpServer(o) {
         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" } });
+            return json(res, 200, { foga: o.version, cell: cfg.name, status: r.ok ? r.output : null, decisions, endpoints: { mcp: "/mcp", api: "/api/<capability>", a2a: "/a2a", agentCard: A2A_WELL_KNOWN, manifest: "/.well-known/foga-cell.json", documents: "/documents/<file>", 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) });
+            return json(res, 200, { caller: { id: caller.id, level: caller.level, visibility: caller.visibility, via: resolved.via }, 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));
@@ -183,11 +187,8 @@ export function createHttpServer(o) {
             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")) : {};
+                    input = body && body.length ? JSON.parse(body.toString("utf8")) : {};
                 }
                 catch {
                     return json(res, 400, { ok: false, gate: "input", reason: "the body is not JSON" });
@@ -200,8 +201,48 @@ export function createHttpServer(o) {
                 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" });
+        // the propagation manifest: free, built live from the configuration, answered even before any document is published
+        if (method === "GET" && url.pathname === "/.well-known/foga-cell.json") {
+            const text = Buffer.from(JSON.stringify(buildPropagationManifest(node, { version: o.version }), null, 2) + "\n");
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "public, max-age=300", "content-length": text.length });
+            res.end(text);
+            return;
+        }
+        // the services catalog, when the one this cell's manifest points at is its own (the reference cell: the maintainer's list);
+        // a static file at this path on the host, answered by the proxy before the node, is how the list changes without a release
+        if (method === "GET" && url.pathname === "/services.json") {
+            const doc = servicesCatalogOf(node, { version: o.version });
+            if (!doc)
+                return json(res, 404, { ok: false, reason: "this cell's services pointer names another catalog; read it from the manifest at /.well-known/foga-cell.json" });
+            const text = Buffer.from(JSON.stringify(doc, null, 2) + "\n");
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "public, max-age=300", "content-length": text.length });
+            res.end(text);
+            return;
+        }
+        // the published documents (foga cell docs build): served as built, by their file names, and at the well-known paths
+        if (method === "GET" && (url.pathname.startsWith("/.well-known/") || url.pathname.startsWith("/documents/"))) {
+            const dir = documentsDir(node);
+            const manifest = readManifest(dir);
+            if (!manifest)
+                return json(res, 404, { ok: false, reason: "not published yet" });
+            let file = null;
+            if (url.pathname === A2A_WELL_KNOWN)
+                file = DOCUMENT_FILES.agentCard;
+            else if (url.pathname === "/.well-known/agent-registration.json")
+                file = DOCUMENT_FILES.registration;
+            else if (url.pathname.startsWith("/documents/")) {
+                const name = basename(decodeURIComponent(url.pathname.slice("/documents/".length)));
+                if (name === "manifest.json" || Object.values(DOCUMENT_FILES).includes(name))
+                    file = name;
+            }
+            const path = file ? join(dir, file) : null;
+            if (!path || !existsSync(path))
+                return json(res, 404, { ok: false, reason: "no such document" });
+            const text = readFileSync(path);
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "public, max-age=300", "content-length": text.length });
+            res.end(text);
+            return;
+        }
         json(res, 404, { ok: false, reason: "no such path" });
     }
     function answer(res, r) {