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

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/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,15 @@
-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 { 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 +79,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 +103,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 +131,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 +162,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, 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 +186,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 +200,30 @@ 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 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) {

package/dist/http/signed.js

@@ -0,0 +1,136 @@
+import { getAddress, isHexString, keccak256, randomBytes, toUtf8Bytes, verifyTypedData } from "ethers";
+/**
+ * Signed calls (design memo, Phase 3, sections 3 and 6, v0.2): a caller's credential is its own wallet's signature,
+ * not a secret the node issued. The envelope is EIP-712 typed data over this cell — the domain's verifyingContract
+ * is the cell's account, so a signature made for one cell means nothing to another — in one of two shapes:
+ *
+ *   Request  bound to one HTTP request (method, path, the hash of the body), valid for at most two minutes:
+ *            the shape for an act, since whoever holds the header can replay nothing else with it;
+ *   Session  not bound to a request, valid for at most ten minutes: the shape a client with static headers
+ *            (an MCP client given `Authorization` once) can use; the policy decides how far it reaches.
+ *
+ * A request-bound envelope carries a nonce the node remembers until it expires, so a captured header is good once;
+ * a session envelope is presented as many times as the session lasts (a captured one is a Bearer token's risk for
+ * ten minutes at most, which is why it reaches build unless the configuration says otherwise). The node recovers
+ * the address, and the address — with what the chain says about it (an ERC-8004 agent, a KYA standing) — is what
+ * the access policy grants a level to. Bearer keys and anonymous reads are untouched: a signature is one more way
+ * in, never a requirement.
+ */
+export const SIGNED_SCHEME = "FOGA-EIP712";
+export const REQUEST_MAX_SECONDS = 120;
+export const SESSION_MAX_SECONDS = 600;
+export const SIGNED_TYPES = {
+    Request: [
+        { name: "method", type: "string" },
+        { name: "path", type: "string" },
+        { name: "bodyHash", type: "bytes32" },
+        { name: "issuedAt", type: "uint256" },
+        { name: "expiresAt", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+    Session: [
+        { name: "issuedAt", type: "uint256" },
+        { name: "expiresAt", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+export function signedDomain(chainId, cell) {
+    return { name: "FOGA", version: "1", chainId, verifyingContract: getAddress(cell) };
+}
+/** keccak256 of the request body (the empty body for a GET). */
+export function bodyHashOf(body) {
+    if (body === null || body === undefined)
+        return keccak256(new Uint8Array());
+    return keccak256(typeof body === "string" ? toUtf8Bytes(body) : body);
+}
+function message(e) {
+    if (e.request)
+        return { primaryType: "Request", types: { Request: SIGNED_TYPES.Request }, value: { method: e.request.method, path: e.request.path, bodyHash: e.request.bodyHash, issuedAt: e.issuedAt, expiresAt: e.expiresAt, nonce: e.nonce } };
+    return { primaryType: "Session", types: { Session: SIGNED_TYPES.Session }, value: { issuedAt: e.issuedAt, expiresAt: e.expiresAt, nonce: e.nonce } };
+}
+/** Sign an envelope with a wallet (ethers Signer with signTypedData) and return the Authorization header value. */
+export async function signAuthorization(signer, o) {
+    const now = o.now ?? Math.floor(Date.now() / 1000);
+    const max = o.request ? REQUEST_MAX_SECONDS : SESSION_MAX_SECONDS;
+    const ttl = Math.min(o.ttlSeconds ?? max, max);
+    const base = { issuedAt: now, expiresAt: now + ttl, nonce: keccak256(randomBytes(32)), request: o.request ? { method: o.request.method.toUpperCase(), path: o.request.path, bodyHash: bodyHashOf(o.request.body) } : undefined };
+    const m = message(base);
+    const signature = await signer.signTypedData(signedDomain(o.chainId, o.cell), m.types, m.value);
+    const envelope = { v: 1, signer: getAddress(await signer.getAddress()), ...(o.agentId ? { agentId: o.agentId } : {}), issuedAt: base.issuedAt, expiresAt: base.expiresAt, nonce: base.nonce, ...(base.request ? { request: base.request } : {}), signature };
+    return `${SIGNED_SCHEME} ${Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url")}`;
+}
+/** Remembers the nonces of request-bound envelopes until they expire: a captured one is good once. */
+export class NonceCache {
+    seen = new Map();
+    lastSweep = 0;
+    take(signer, nonce, expiresAt, now) {
+        if (now - this.lastSweep > 30) {
+            for (const [k, exp] of this.seen)
+                if (exp < now)
+                    this.seen.delete(k);
+            this.lastSweep = now;
+        }
+        const key = `${signer.toLowerCase()}:${nonce.toLowerCase()}`;
+        if (this.seen.has(key))
+            return false;
+        this.seen.set(key, expiresAt);
+        if (this.seen.size > 100_000)
+            this.seen.delete(this.seen.keys().next().value);
+        return true;
+    }
+}
+/** Parse and verify an Authorization header of the FOGA-EIP712 scheme against this cell and this request. */
+export function verifyAuthorization(header, o) {
+    const m = new RegExp(`^${SIGNED_SCHEME}\\s+(\\S+)$`, "i").exec(header.trim());
+    if (!m)
+        return { ok: false, reason: "not a FOGA-EIP712 envelope" };
+    let e;
+    try {
+        e = JSON.parse(Buffer.from(m[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "the envelope is not base64url JSON" };
+    }
+    if (e?.v !== 1 || typeof e.signer !== "string" || typeof e.issuedAt !== "number" || typeof e.expiresAt !== "number" || !isHexString(e.nonce, 32) || typeof e.signature !== "string")
+        return { ok: false, reason: "the envelope lacks a field (v, signer, issuedAt, expiresAt, nonce, signature)" };
+    const now = o.now ?? Math.floor(Date.now() / 1000);
+    const bound = Boolean(e.request);
+    const max = bound ? REQUEST_MAX_SECONDS : SESSION_MAX_SECONDS;
+    if (e.expiresAt <= e.issuedAt || e.expiresAt - e.issuedAt > max)
+        return { ok: false, reason: `the envelope's validity must be 1 to ${max} seconds (${bound ? "request" : "session"})` };
+    if (e.issuedAt > now + 60)
+        return { ok: false, reason: "the envelope is issued in the future" };
+    if (e.expiresAt < now)
+        return { ok: false, reason: "the envelope has expired" };
+    if (bound) {
+        const r = e.request;
+        if (typeof r.method !== "string" || typeof r.path !== "string" || !isHexString(r.bodyHash, 32))
+            return { ok: false, reason: "the request binding lacks method, path or bodyHash" };
+        if (r.method.toUpperCase() !== o.method.toUpperCase())
+            return { ok: false, reason: `the envelope is bound to ${r.method}, this request is ${o.method}` };
+        if (r.path !== o.path)
+            return { ok: false, reason: `the envelope is bound to ${r.path}, this request is ${o.path}` };
+        if (r.bodyHash.toLowerCase() !== bodyHashOf(o.body).toLowerCase())
+            return { ok: false, reason: "the envelope is bound to another body" };
+    }
+    let recovered;
+    try {
+        const msg = message({ issuedAt: e.issuedAt, expiresAt: e.expiresAt, nonce: e.nonce, request: e.request });
+        recovered = verifyTypedData(signedDomain(o.chainId, o.cell), msg.types, msg.value, e.signature);
+    }
+    catch {
+        return { ok: false, reason: "the signature does not verify" };
+    }
+    let claimed;
+    try {
+        claimed = getAddress(e.signer);
+    }
+    catch {
+        return { ok: false, reason: "signer is not an address" };
+    }
+    if (recovered !== claimed)
+        return { ok: false, reason: "the signature was not made by the signer it names" };
+    if (bound && o.nonces && !o.nonces.take(claimed, e.nonce, e.expiresAt, now))
+        return { ok: false, reason: "the envelope was presented before (nonce reused)" };
+    return { ok: true, envelope: { ...e, signer: claimed }, bound };
+}

package/dist/mcp/server.js

@@ -142,7 +142,33 @@ export function buildMcpServer(o) {
     if (existsSync(matrix)) {
         server.registerResource("compatibility-matrix", "foga://docs/compatibility-matrix", { title: "Compatibility matrix", description: "The ten standards, what the kernel exercises of each, and the evidence.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(matrix, "utf8") }] }));
     }
-    // the one prompt: take a tender as the node's operator would
+    // how to become a cell: every cell carries the genome's instructions, so an agent that meets one can make itself one
+    const quickstartDoc = join(repoRoot(), "docs", "quickstart.md");
+    if (existsSync(quickstartDoc)) {
+        server.registerResource("quickstart", "foga://docs/quickstart", { title: "Become a cell", description: "How any agent makes itself a FOGA cell: one command, its own wallet, the same program this node runs.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(quickstartDoc, "utf8") }] }));
+    }
+    server.registerPrompt("become-a-cell", { title: "Become a cell", description: "Replicate: make yourself a FOGA cell on your own machine, with your own wallet — the same program as this node, your own identity.", argsSchema: z.object({}) }, () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `You are talking to cell ${node.config.name}${cell ? ` (account ${cell.address})` : ""} through the Finch OG Agent node software, version ${o.version}. You can become a cell yourself: the program is public, the identity you make is your own, and nothing of this cell's identity is copied.`,
+                        "On a machine where you can run commands (Node 22.13 or newer, and Foundry's anvil for a local chain):",
+                        "1. The wallet, first and once:  npx -y @finchip.ai/foga wallet new          (owner, operator and guardian keys in ~/.foga/wallet; never overwritten; a failure here never blocks the next step)",
+                        "2. A living cell on a local chain:  npx -y @finchip.ai/foga quickstart         (anvil, the world, a cell born with your wallet's keys, two tenders, the node served; it prints the MCP client configuration to connect a model to the cell)",
+                        "3. Connect your model: paste the printed configuration into your MCP client (Claude Desktop, Claude Code, Cursor, or any client with the HTTP form); the stdio form acts with your operator key, the HTTP form with the printed Bearer key.",
+                        "4. On a public chain, when you are ready: fund the wallet's owner and operator, then  foga cell new --wallet ~/.foga/wallet --world <world.json> …  and  foga cell init --config <cell.config.json> --wallet ~/.foga/wallet.",
+                        `5. With the wallet alone you can also call this cell as yourself:  npx -y @finchip.ai/foga wallet sign --url ${node.config.runtime.http.publicUrl ?? "<this node's URL>"}  prints an Authorization header (FOGA-EIP712) for its /api, /mcp and /a2a; what it is granted is this cell's policy.`,
+                        "The guide is the resource foga://docs/quickstart. In PowerShell, quote the package name: npx -y '@finchip.ai/foga' quickstart.",
+                        "What you get is a complete body: the ten standards, the catalog that decides, the acceptance (foga doctor, foga demo --loop-d). The mind driving it stays yours.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // the one prompt about work: take a tender as the node's operator would
     server.registerPrompt("take-tender", { title: "Take a tender", description: "Work one ERC-8414 tender the way the node's operator would: inspect, pre-check, run the skill, submit, settle.", argsSchema: z.object({ tokenId: z.string().describe("the tender's token id") }) }, ({ tokenId }) => ({
         messages: [
             {

package/dist/node/config.js

@@ -7,7 +7,8 @@ import { ensureDir } from "../util/fs.js";
  * Six blocks: identity (the world, the account and its roles, what `foga cell init` writes back), presence (how the
  * cell describes itself to the world), skills (what it holds and offers), policy (the business authorization the
  * policy engine applies to every act), runtime (how the node runs, the HTTP server among it) and access (the API
- * keys the HTTP entrance accepts, as their hashes). Amounts in wei are decimal strings so the file stays plain JSON.
+ * keys the HTTP entrance accepts, as their hashes, and what a signer proving itself with its wallet is granted).
+ * Amounts in wei are decimal strings so the file stays plain JSON.
  */
 const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/, "an address (0x + 40 hex digits)");
 const bytes32 = z.string().regex(/^0x[0-9a-fA-F]{64}$/, "a 32-byte hex value");
@@ -45,6 +46,9 @@ export const PresenceSchema = z.object({
     description: z.string().max(2000).default(""),
     image: z.string().url().optional(),
     homepage: z.string().url().optional(),
+    /** The organization behind the cell, for the A2A agent card. */
+    provider: z.object({ organization: z.string().min(1).max(120), url: z.string().url() }).optional(),
+    /** The public endpoints; when absent they are derived from runtime.http.publicUrl (/mcp, /a2a, the URL itself). */
     endpoints: z
         .object({
         mcp: z.string().url().optional(),
@@ -104,6 +108,8 @@ export const HttpSchema = z.object({
     allowedHosts: z.array(z.string()).default([]),
     /** The URL the public reaches the node at (for its documents and card). */
     publicUrl: z.string().url().optional(),
+    /** Where `foga cell docs build` writes and the node serves the documents from (relative to the config's directory). */
+    documentsDir: z.string().default("documents"),
     rateLimitPerMinute: z.number().int().min(1).default(60),
     maxBodyBytes: z.number().int().min(1024).default(256 * 1024),
 });
@@ -133,8 +139,35 @@ export const AccessKeySchema = z.object({
     visibility: z.enum(["public", "caller", "operator"]).default("caller"),
     note: z.string().max(200).optional(),
 });
+/** What a signer (an address proving itself with an EIP-712 envelope) is granted: by address, or by the ERC-8004 agent id it acts for. */
+export const SignerGrantSchema = z
+    .object({
+    address: address.optional(),
+    agentId: uint.optional(),
+    level: z.enum(["read", "build", "act"]).default("act"),
+    visibility: z.enum(["public", "caller", "operator"]).default("caller"),
+    note: z.string().max(200).optional(),
+})
+    .refine((g) => g.address || g.agentId, { message: "a signer grant names an address or an agentId" });
+export const SignersSchema = z.object({
+    /** What any valid signature is granted without a grant of its own: the public's level (build) by default; none refuses signatures outright. */
+    default: z.enum(["none", "read", "build"]).default("build"),
+    allow: z.array(SignerGrantSchema).default([]),
+    /** A signer whose KYA standing under the cell's scheme reaches minLevel is granted this level. */
+    standing: z
+        .object({
+        minLevel: z.number().int().min(1),
+        level: z.enum(["read", "build", "act"]).default("act"),
+        visibility: z.enum(["public", "caller", "operator"]).default("caller"),
+    })
+        .optional(),
+    /** An act by signature needs an envelope bound to its request (a session envelope reaches build at most). */
+    actsNeedRequestBinding: z.boolean().default(true),
+});
 export const AccessSchema = z.object({
     keys: z.array(AccessKeySchema).default([]),
+    /** Signed calls (FOGA-EIP712): what an address proving itself with its wallet is granted. */
+    signers: SignersSchema.prefault({}),
 });
 export const CellConfigSchema = z.object({
     schema: z.literal("foga.cell-config/1"),