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

package/dist/node/config.js

@@ -0,0 +1,195 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+import { ensureDir } from "../util/fs.js";
+/**
+ * `cell.config.json` (schema `foga.cell-config/1`): the one file a node maintains (design memo, Phase 3, section 7).
+ * 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.
+ */
+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");
+const wei = z.string().regex(/^\d+$/, "a decimal amount in wei");
+const uint = z.string().regex(/^\d+$/, "a decimal integer");
+export const SafetySchema = z.object({
+    /** The ASF specification the cell adopts; `foga cell init` publishes FOGA-Cell-v1 and fills this in when absent. */
+    specId: bytes32.optional(),
+    version: z.number().int().positive().default(1),
+    contentHash: bytes32.optional(),
+});
+export const StandingSchema = z.object({
+    /** The attested KYA scheme and issuers the cell cites for its own standing and requires of counterparties. */
+    schemeId: bytes32,
+    issuers: z.array(address).min(1),
+});
+export const IdentitySchema = z.object({
+    account: address.optional(),
+    agentId: uint.optional(),
+    owner: address,
+    operator: address,
+    guardian: address,
+    recovery: address.optional(),
+    bindingId: bytes32.optional(),
+    recordId: bytes32.optional(),
+    unitId: uint.optional(),
+    documentDigest: bytes32.optional(),
+    safety: SafetySchema.prefault({}),
+    standing: StandingSchema.optional(),
+    /** The ERC-8434 liveness window the account keeps (seconds); the registry's default when absent. */
+    livenessWindow: z.number().int().positive().optional(),
+});
+export const PresenceSchema = z.object({
+    name: z.string().min(1).max(120),
+    description: z.string().max(2000).default(""),
+    image: z.string().url().optional(),
+    homepage: z.string().url().optional(),
+    endpoints: z
+        .object({
+        mcp: z.string().url().optional(),
+        a2a: z.string().url().optional(),
+        web: z.string().url().optional(),
+    })
+        .prefault({}),
+});
+export const HeldSkillSchema = z.object({
+    tokenId: uint,
+    recordId: bytes32.optional(),
+    unitId: uint.optional(),
+    packageHash: bytes32.optional(),
+});
+export const SkillsSchema = z.object({
+    /** Directory holding the skill packages (one subdirectory per skill name). */
+    dir: z.string().default("scenarios/skills"),
+    /** The only directory a skill run may read documents from (a task's document is written here when it arrives inline). */
+    inputDir: z.string().default("scenarios/fixtures"),
+    /** Skills the cell holds on chain, by name (written by `skill_mint`). */
+    held: z.record(z.string(), HeldSkillSchema).default({}),
+    /** Skills the cell offers to run for others; a tender for a skill not listed here is refused (gate: skill). */
+    offered: z.array(z.string()).default([]),
+});
+export const BudgetSchema = z.object({
+    /** Native value the cell may move out per day (settlements paid in count as income, not spend). */
+    dailyValueWei: wei.default("2000000000000000"),
+    /** The most one operation may move. */
+    perOperationValueWei: wei.default("1000000000000000"),
+    /** Fees the operator key may pay per day (gas), replacements included. */
+    dailyGasWei: wei.default("5000000000000000"),
+    /** Tenders taken and not yet settled at the same time. */
+    maxConcurrentCommitments: z.number().int().min(1).default(2),
+});
+export const TenderPolicySchema = z.object({
+    minRewardWei: wei.default("100000000000000"),
+    /** A tender whose submitBy is closer than this is refused (gate: policy). */
+    minSubmitWindowSeconds: z.number().int().min(0).default(600),
+    minSettleWindowSeconds: z.number().int().min(0).default(600),
+    /** Acceptance authorities the cell works under: "hashlock" (the world's HashlockVerifier) or an address. */
+    acceptance: z.array(z.string()).default(["hashlock"]),
+    /** What the cell requires of a demander: a KYA level under the standing scheme, 0 = nothing. */
+    counterpartyMinLevel: z.number().int().min(0).default(0),
+    /** How far back tender discovery scans (blocks). */
+    lookbackBlocks: z.number().int().min(1).default(9000),
+});
+export const PolicySchema = z.object({
+    budget: BudgetSchema.prefault({}),
+    tenders: TenderPolicySchema.prefault({}),
+});
+export const HttpSchema = z.object({
+    /** host:port the HTTP server binds (loopback by default; a reverse proxy terminates TLS in front of it). */
+    listen: z.string().default("127.0.0.1:8787"),
+    /** Origins (hostnames) a browser-sent request may carry; a request with another Origin is refused. Requests without an Origin pass. */
+    allowedOrigins: z.array(z.string()).default([]),
+    /** Host names this server answers for (the reverse proxy's and the loopback ones). Empty: any Host. */
+    allowedHosts: z.array(z.string()).default([]),
+    /** The URL the public reaches the node at (for its documents and card). */
+    publicUrl: z.string().url().optional(),
+    rateLimitPerMinute: z.number().int().min(1).default(60),
+    maxBodyBytes: z.number().int().min(1024).default(256 * 1024),
+});
+export const RuntimeSchema = z.object({
+    heartbeatEverySeconds: z.number().int().positive().default(3600),
+    pollSeconds: z.number().int().positive().default(12),
+    http: HttpSchema.prefault({}),
+    /** The runner's model (3c): the provider, the model name (required for anthropic), and the limits the runner holds it to. */
+    model: z
+        .object({
+        provider: z.enum(["stub", "anthropic"]).default("stub"),
+        model: z.string().optional(),
+        /** Model calls per UTC day; a tick that would exceed it is skipped and journaled. */
+        dailyCalls: z.number().int().min(0).default(20),
+        /** Tool calls the runner carries out in one tick. */
+        maxToolCallsPerTick: z.number().int().min(1).max(100).default(12),
+        /** Acts (pre-checks not counted) the runner carries out in one tick. */
+        maxActsPerTick: z.number().int().min(0).max(20).default(2),
+    })
+        .prefault({}),
+});
+/** An API key the HTTP entrance accepts: only its hash is kept; the key itself is shown once by `foga node key new`. */
+export const AccessKeySchema = z.object({
+    id: z.string().min(1).max(64).regex(/^[A-Za-z0-9_.-]+$/, "a key id: letters, digits, _ . -"),
+    sha256: bytes32,
+    level: z.enum(["read", "build", "act"]).default("act"),
+    visibility: z.enum(["public", "caller", "operator"]).default("caller"),
+    note: z.string().max(200).optional(),
+});
+export const AccessSchema = z.object({
+    keys: z.array(AccessKeySchema).default([]),
+});
+export const CellConfigSchema = z.object({
+    schema: z.literal("foga.cell-config/1"),
+    name: z.string().min(1).max(64),
+    world: z.string().min(1),
+    rpc: z.string().url().optional(),
+    bundle: z.string().optional(),
+    /** The operation store of this cell (operations, jobs, decisions, facts). */
+    store: z.string().min(1),
+    identity: IdentitySchema,
+    presence: PresenceSchema,
+    skills: SkillsSchema.prefault({}),
+    policy: PolicySchema.prefault({}),
+    runtime: RuntimeSchema.prefault({}),
+    access: AccessSchema.prefault({}),
+});
+export function loadCellConfig(path) {
+    const abs = resolve(path);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(abs, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`cannot read cell config ${abs}: ${e.message}`);
+    }
+    const parsed = CellConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+        throw new Error(`cell config ${abs} is not a valid foga.cell-config/1 document:\n${issues}`);
+    }
+    return { path: abs, dir: dirname(abs), config: parsed.data };
+}
+/** Write the config back (after `init`, `migrate` or `skill_mint` filled in what the chain decided). */
+export function saveCellConfig(path, config) {
+    const abs = resolve(path);
+    ensureDir(dirname(abs));
+    writeFileSync(abs, JSON.stringify(config, null, 2) + "\n");
+}
+/** Resolve a path in the config against the config's directory, unless absolute. */
+export function configPath(loaded, p) {
+    return resolve(loaded.dir, p);
+}
+/** A starting config for a new cell: the roles and the world, nothing the chain has decided yet. */
+export function newCellConfig(p) {
+    return CellConfigSchema.parse({
+        schema: "foga.cell-config/1",
+        name: p.name,
+        world: p.world,
+        rpc: p.rpc,
+        store: p.store,
+        identity: { owner: p.owner, operator: p.operator, guardian: p.guardian, safety: { version: 1 } },
+        presence: { name: `FOGA cell ${p.name}`, description: p.description ?? `Cell ${p.name}: an address acting under the ten-ERC stack`, endpoints: {} },
+        skills: { dir: p.skillsDir ?? "scenarios/skills", inputDir: p.inputDir ?? "scenarios/fixtures", held: {}, offered: [] },
+        policy: {},
+        runtime: {},
+        access: {},
+    });
+}

package/dist/node/init.js

@@ -0,0 +1,200 @@
+import { getAddress, parseEther } from "ethers";
+import { AID } from "../core/aid.js";
+import { agentDescriptor, kindId } from "../core/ard.js";
+import { Enforcement, Rights, accountSubjectKey, fogaCellSpecification, oneClause, scopeKeyOf, specIdOf } from "../core/asf.js";
+import { accountRef, dataUri, keccakJcs } from "../core/canonical.js";
+import { cellUnitDefinition } from "../core/units.js";
+import { operatorScope } from "../genesis/operator-scope.js";
+import { Cell } from "../kernel/cell.js";
+import { ROLE } from "./node.js";
+/** The operator scope a standalone cell starts with: identity, standing, skills, labour on both sides, services as provider. */
+export const NODE_SCOPE_GROUPS = ["identity", "standing", "skills-provider", "labour", "demander", "service-provider"];
+/**
+ * The birth of one cell from its configuration (T1 of the genesis for a single cell, design memo Phase 3 section 5):
+ * the owner deploys a revision-2 account naming the operator and guardian, funds it, opens the operator's scope,
+ * sets the commitment and de-risk classes, adopts the FOGA-Cell-v1 binding, and — through the account, as owner —
+ * registers the ERC-8004 identity, binds and heartbeats the anchor, publishes the AID document, the ARD agent record
+ * and the AUF unit. Every step is a keyed operation in the cell's own store, so a stopped init resumes. Standing
+ * (KYA) is not the cell's to give itself: an issuer attests it afterwards. The config is written back with what
+ * the chain decided.
+ */
+export async function cellInit(node, opts = {}) {
+    const k = node.kernel;
+    const cfg = node.config;
+    const log = opts.log ?? node.log;
+    if (!node.hasKey("owner"))
+        throw new Error("cell init is the owner's act: load the owner key (FOGA_OWNER_KEY or FOGA_OWNER_KEY_FILE)");
+    if (cfg.identity.account && k.store.get("init.deploy")?.status !== "confirmed")
+        throw new Error(`${node.loaded.path} already names account ${cfg.identity.account}; init runs on a config without one`);
+    const chainId = node.chainId;
+    const owner = cfg.identity.owner;
+    const operator = cfg.identity.operator;
+    const guardian = cfg.identity.guardian;
+    const ownerSigner = ROLE.owner;
+    const operations = [];
+    const done = (key) => operations.push(key);
+    // 0. the specification the cell adopts: published by the owner when the config names none. The registry derives
+    // the id from the publisher and the salt, so an owner who has published FOGA-Cell-v1 before (an earlier cell of
+    // theirs on this chain) adopts that specification rather than registering it again.
+    let spec = cfg.identity.safety;
+    if (!spec.specId || !spec.contentHash) {
+        const document = fogaCellSpecification();
+        const salt = keccakJcs({ spec: "FOGA-Cell-v1", publisher: owner.toLowerCase() });
+        const commitment = k.asf.specificationCommitment(document);
+        const expected = specIdOf(chainId, k.asf.specRegistryAddress, owner, salt);
+        const published = await k.asf.versionOf(expected, 1).catch(() => null);
+        if (published) {
+            if (published.contentHash.toLowerCase() !== commitment.contentHash.toLowerCase())
+                throw new Error(`the owner published specification ${expected} before with contentHash ${published.contentHash}; this build's FOGA-Cell-v1 hashes to ${commitment.contentHash}. Name the specification to adopt in identity.safety.`);
+            spec = { specId: expected, version: 1, contentHash: commitment.contentHash };
+            log(`  spec: FOGA-Cell-v1 already published by the owner as ${expected}; adopted`);
+        }
+        else {
+            const reg = await k.call("init.spec.register", ownerSigner, k.asf.specRegistryAddress, k.asf.specs().interface, "registerSpecification", [salt, commitment.contentHash, commitment.locator, []]);
+            done("init.spec.register");
+            const specId = k.asf.specIdFromReceipt(reg.receipt);
+            if (specId.toLowerCase() !== expected.toLowerCase())
+                throw new Error(`the registry assigned ${specId}; expected ${expected}`);
+            spec = { specId, version: 1, contentHash: commitment.contentHash };
+            log(`  spec: FOGA-Cell-v1 published by the owner as ${specId}`);
+        }
+        cfg.identity.safety = spec;
+        node.saveConfig();
+    }
+    else {
+        const v = await k.asf.versionOf(spec.specId, spec.version);
+        if (v.contentHash.toLowerCase() !== spec.contentHash.toLowerCase())
+            throw new Error(`specification ${spec.specId} v${spec.version} on chain has contentHash ${v.contentHash}, the config says ${spec.contentHash}`);
+    }
+    const specId = spec.specId;
+    const contentHash = spec.contentHash;
+    // 1. the body: deployed by the owner; the requirement names the account itself
+    const safety = k.asf.bindingRegistryAddress;
+    const recovery = cfg.identity.recovery ?? owner;
+    const requirement = (predicted) => oneClause({ specRegistry: k.asf.specRegistryAddress, specId, versions: [spec.version], adopter: predicted, subjectKey: accountSubjectKey(chainId, predicted), scopeKey: scopeKeyOf({ ref: accountRef(chainId, predicted) }), enforcement: Enforcement.account | Enforcement.contract, interveners: [{ account: guardian, rights: Rights.suspend | Rights.resume }] });
+    let predictedFor = null;
+    const { address } = await k.deploy("init.deploy", ownerSigner, "foga:FogaCellAccount", [], (predicted) => {
+        predictedFor = predicted;
+        return [safety, owner, operator, guardian, recovery, requirement(predicted)];
+    });
+    done("init.deploy");
+    if (predictedFor && predictedFor.toLowerCase() !== address.toLowerCase())
+        throw new Error(`deployed at ${address} but the requirement was built for ${predictedFor}; the owner's nonce moved between prediction and inclusion`);
+    const cell = new Cell(k, cfg.name, address, { owner: ROLE.owner, operator: ROLE.operator, guardian, recovery });
+    cfg.identity.account = getAddress(address);
+    node.saveConfig();
+    k.store.setMeta("cellAccount", address);
+    log(`  account: ${address} (owner ${owner}, operator ${operator}, guardian ${guardian})`);
+    // 2. working capital from the owner
+    const capital = opts.capitalWei ?? (k.isLocalChain ? parseEther("0.05") : parseEther("0.005"));
+    if (capital > 0n) {
+        await k.transfer("init.fund", ownerSigner, address, capital);
+        done("init.fund");
+    }
+    // 3. owner administration: the operator's key, scope and daily cap, the AID registry, the selector classes
+    await cell.admin("init.setOperator", "setOperator", [operator, 0, BigInt(cfg.policy.budget.dailyValueWei)]);
+    done("init.setOperator");
+    const scope = operatorScope(k, NODE_SCOPE_GROUPS);
+    await cell.admin("init.scope", "setOperatorAllowedBatch", [scope.targets, scope.selectors, true]);
+    done("init.scope");
+    k.setFact("init.scope", { groups: NODE_SCOPE_GROUPS, entries: scope.names });
+    await cell.admin("init.setAIDRegistry", "setAIDRegistry", [k.aid.address]);
+    done("init.setAIDRegistry");
+    const sel = (id, fn) => node.world.iface(id).getFunction(fn).selector;
+    const commitment = [
+        ["8414.submitFulfillment", k.tenders.address, sel("8414/TaskToken", "submitFulfillment")],
+        ["8447.join", node.world.address("8447/SwarmRegistry"), sel("8447/SwarmRegistry", "join")],
+        ["8447.applyToJoin", node.world.address("8447/SwarmRegistry"), sel("8447/SwarmRegistry", "applyToJoin")],
+        ["8454.assertStatement", node.world.address("8454/AUFAssertionRegistry"), sel("8454/AUFAssertionRegistry", "assertStatement")],
+        ["8436.castBallot", k.acdf.registryAddress, sel("8436/ACDFRegistry", "castBallot")],
+    ];
+    for (const [name, target, selector] of commitment) {
+        await cell.admin(`init.class.${name}`, "setCommitmentClass", [target, selector, true]);
+        done(`init.class.${name}`);
+    }
+    const derisk = [
+        ["8414.withdrawCredit", k.tenders.address, sel("8414/TaskToken", "withdrawCredit")],
+        ["8414.reclaimEscrow", k.tenders.address, sel("8414/TaskToken", "reclaimEscrow")],
+        ["8447.leave", node.world.address("8447/SwarmRegistry"), sel("8447/SwarmRegistry", "leave")],
+        ["8471.withdrawBalance", k.adrf.escrowAddress, sel("8471/ADRFServiceEscrow", "withdrawBalance")],
+    ];
+    for (const [name, target, selector] of derisk) {
+        await cell.admin(`init.derisk.${name}`, "setDeriskAllowed", [target, selector, true]);
+        done(`init.derisk.${name}`);
+    }
+    // 4. the safety binding, adopted by the account and presented for clause 0
+    const params = { profile: "foga-cell/1", cell: cfg.name, operatorScope: NODE_SCOPE_GROUPS, deriskActions: derisk.map((d) => d[0]), commitmentActions: commitment.map((c) => c[0]) };
+    const authority = { kind: "owner", owner: accountRef(chainId, owner), guardian: accountRef(chainId, guardian) };
+    const input = k.asf.cellBindingInput({ chainId, cell: address, specId, version: spec.version, contentHash, guardian, params, authority });
+    const { bindingId } = await cell.adoptBinding("init.adopt", input, 0);
+    done("init.adopt");
+    cfg.identity.bindingId = bindingId;
+    node.saveConfig();
+    // 5. identity: the ERC-8004 registration, made by the account (the owner executes; the operator's scope is for later)
+    const registration = {
+        type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
+        name: cfg.presence.name,
+        description: cfg.presence.description,
+        image: cfg.presence.image,
+        services: [
+            ...(cfg.presence.endpoints.mcp ? [{ name: "MCP", endpoint: cfg.presence.endpoints.mcp, version: "2026-07-28" }] : []),
+            ...(cfg.presence.endpoints.a2a ? [{ name: "A2A", endpoint: cfg.presence.endpoints.a2a, version: "1.0" }] : []),
+            ...(cfg.presence.endpoints.web ? [{ name: "web", endpoint: cfg.presence.endpoints.web }] : []),
+        ],
+        x402Support: false,
+        active: true,
+        supportedTrust: ["reputation"],
+        "x-foga": { cell: cfg.name, anchor: accountRef(chainId, address), binding: bindingId },
+    };
+    const reg = await cell.execute("init.8004.register", k.identity.address, k.identity.encodeRegister(dataUri(registration)), { by: "owner" });
+    done("init.8004.register");
+    const agentId = k.identity.agentIdFromReceipt(reg.receipt);
+    cfg.identity.agentId = agentId.toString();
+    node.saveConfig();
+    // 6. the anchor: bind and heartbeat in the reference registry, bind in the backing registry where there is one
+    await cell.execute("init.aid.bind", k.aid.address, k.aid.encodeBind(k.identity.address, agentId), { by: "owner" });
+    done("init.aid.bind");
+    await cell.execute("init.aid.heartbeat", k.aid.address, k.aid.encodeHeartbeat(), { by: "owner" });
+    done("init.aid.heartbeat");
+    if (k.aid.backing) {
+        await cell.execute("init.aid.backing.bind", k.aid.backing.address, k.aid.encodeBind(k.identity.address, agentId), { by: "owner" });
+        done("init.aid.backing.bind");
+    }
+    if (cfg.identity.livenessWindow) {
+        await cell.execute("init.aid.window", k.aid.address, k.aid.encodeSetLivenessWindow(cfg.identity.livenessWindow), { by: "owner" });
+        done("init.aid.window");
+    }
+    // 7. the AID document: the identity facet (SELF); standing and skills facets follow when they exist
+    const doc = {
+        version: "aid-document/v1",
+        aid: accountRef(chainId, address),
+        did: `did:aid:${accountRef(chainId, address)}`,
+        binding: { registry: k.identity.address, agentId: Number(agentId) },
+        livenessWindow: cfg.identity.livenessWindow ?? Number(node.world.file.params.aid.defaultLivenessWindow),
+        facets: [{ facetType: "aid:core/identity/v1", provenance: "SELF", issuer: accountRef(chainId, address), validUntil: 0, digest: keccakJcs(registration), access: { mode: "PUBLIC" }, resolver: { kind: "erc8004-identity", chainId, registry: k.identity.address, agentId: Number(agentId) } }],
+    };
+    const commitment2 = AID.documentCommitment(doc);
+    await cell.execute("init.aid.document", k.aid.address, k.aid.encodeSetDocumentURI(commitment2.uri, commitment2.digest), { by: "owner" });
+    done("init.aid.document");
+    cfg.identity.documentDigest = commitment2.digest;
+    // 8. discovery: the ARD agent record, controlled by the anchor itself
+    const descriptor = agentDescriptor({ chainId, anchor: address, slug: `cell-${cfg.name.toLowerCase()}`, name: cfg.presence.name, description: cfg.presence.description, url: cfg.presence.homepage, capabilities: ["erc8414:fulfiller", "erc8338:holder"], registration: { registry: `eip155:${chainId}:${k.identity.address.toLowerCase()}`, agentId: agentId.toString() } });
+    const ard = await cell.execute("init.ard.register", k.ard.address, k.ard.encodeRegister(kindId("agent"), address, 0n, descriptor), { by: "owner" });
+    done("init.ard.register");
+    const recordId = k.ard.recordIdFromReceipt(ard.receipt);
+    cfg.identity.recordId = recordId;
+    // 9. the economic boundary: the cell's unit
+    const unitDef = cellUnitDefinition({ chainId, cell: address, name: cfg.presence.name });
+    const unit = await cell.execute("init.auf.unit", k.units.registryAddress, k.units.encodeRegisterUnit(address, unitDef, []), { by: "owner" });
+    done("init.auf.unit");
+    const unitId = k.units.unitIdFromReceipt(unit.receipt);
+    cfg.identity.unitId = unitId.toString();
+    node.saveConfig();
+    k.evidence("init", cfg.name, { account: address, owner, operator, guardian, specId, bindingId, agentId: agentId.toString(), recordId, unitId: unitId.toString(), documentDigest: commitment2.digest, scope: scope.names, capital: capital.toString() });
+    const state = await k.aid.stateName(address);
+    const status = await cell.status();
+    log(`  born: agent ${agentId}, anchor ${state}, binding ${status.verdictName}, record ${recordId.slice(0, 10)}…, unit ${unitId}`);
+    if (state !== "ACTIVE" || status.verdictName !== "Satisfied")
+        throw new Error(`the cell was born but is not ready: anchor ${state}, binding ${status.verdictName} [${status.reasonNames.join(",")}]`);
+    return { account: address, agentId: agentId.toString(), bindingId, recordId, unitId: unitId.toString(), documentDigest: commitment2.digest, specId, operations };
+}

package/dist/node/keys.js

@@ -0,0 +1,95 @@
+import { readFileSync, statSync } from "node:fs";
+import { Wallet, isHexString } from "ethers";
+/**
+ * The one key a running node holds: its cell's operator key, and nothing else (design memo, Phase 3, key
+ * isolation). The genesis derives twelve roles from one phrase because it plays every part; a node plays one, and
+ * the process that signs for the public must not be able to derive the owner, the guardian or the treasury. So
+ * the node reads its key from FOGA_OPERATOR_KEY (the hex key) or FOGA_OPERATOR_KEY_FILE (a file holding it, readable
+ * by its user alone) and refuses to start when its environment also carries a phrase, a deployer key or any
+ * FOGA_KEY_<ROLE>: those belong to the operator's shell, never to the node's user. `foga keys export` writes the
+ * file for the node from the operator's phrase.
+ */
+export const OPERATOR_KEY_ENV = "FOGA_OPERATOR_KEY";
+export const OPERATOR_KEY_FILE_ENV = "FOGA_OPERATOR_KEY_FILE";
+/** Variables whose presence means the process could sign as more than the operator. */
+export const FORBIDDEN_IN_NODE_ENV = ["FOGA_MNEMONIC", "FOGA_MNEMONIC_FILE", "FOGA_DEPLOYER_PK", "FOGA_OWNER_KEY", "FOGA_OWNER_KEY_FILE", "FOGA_GUARDIAN_KEY", "FOGA_GUARDIAN_KEY_FILE"];
+/** The variables a role's key is read from: FOGA_<ROLE>_KEY or FOGA_<ROLE>_KEY_FILE. */
+export function roleKeyEnv(role) {
+    const up = role.toUpperCase();
+    return { inline: `FOGA_${up}_KEY`, file: `FOGA_${up}_KEY_FILE` };
+}
+export class KeyIsolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KeyIsolationError";
+    }
+}
+/** The variables of `env` a node must not see, with their names (never their values). */
+export function forbiddenVariables(env = process.env) {
+    const out = [];
+    for (const name of Object.keys(env)) {
+        if (env[name] === undefined || env[name] === "")
+            continue;
+        if (FORBIDDEN_IN_NODE_ENV.includes(name) || name.startsWith("FOGA_KEY_"))
+            out.push(name);
+    }
+    return out.sort();
+}
+function parseKey(text, where) {
+    const key = text.trim();
+    if (!isHexString(key, 32))
+        throw new KeyIsolationError(`${where} does not hold a private key (expected 0x followed by 64 hex digits)`);
+    return key;
+}
+/**
+ * Load the operator key from the environment. Exactly one of FOGA_OPERATOR_KEY and FOGA_OPERATOR_KEY_FILE must be
+ * set; the file must be a regular file owned by the current user and readable by nobody else (mode 0600 or
+ * tighter; the ownership and mode checks are POSIX-only).
+ */
+export function loadOperatorKey(env = process.env) {
+    const forbidden = forbiddenVariables(env);
+    if (forbidden.length) {
+        throw new KeyIsolationError(`the node's environment holds ${forbidden.join(", ")}: a node runs with its operator key alone (${OPERATOR_KEY_ENV} or ${OPERATOR_KEY_FILE_ENV}). Unset these for the node's user; they belong to the operator's shell.`);
+    }
+    return loadRoleKey("operator", env);
+}
+/**
+ * Read one role's key from the environment without the isolation check: for the CLI's one-shot commands in the
+ * operator's own shell (an owner's or guardian's act, a cell's birth), never for a running node. The file rules
+ * are the same as the node's.
+ */
+export function loadRoleKey(role, env = process.env) {
+    const names = roleKeyEnv(role);
+    const inline = env[names.inline]?.trim();
+    const file = env[names.file]?.trim();
+    if (inline && file)
+        throw new KeyIsolationError(`both ${names.inline} and ${names.file} are set; set one`);
+    if (!inline && !file) {
+        if (role === "operator")
+            throw new KeyIsolationError(`no operator key: set ${names.file} to a file written by 'foga keys export --role operator.<X>' (or ${names.inline} to the key itself)`);
+        throw new KeyIsolationError(`no ${role} key: set ${names.file} (a 0600 file holding the key) or ${names.inline} for this one command`);
+    }
+    if (inline) {
+        const privateKey = parseKey(inline, names.inline);
+        return { privateKey, address: new Wallet(privateKey).address, source: { kind: "env", name: names.inline } };
+    }
+    const path = file;
+    let st;
+    try {
+        st = statSync(path);
+    }
+    catch {
+        throw new KeyIsolationError(`${names.file}=${path}: no such file`);
+    }
+    if (!st.isFile())
+        throw new KeyIsolationError(`${names.file}=${path} is not a regular file`);
+    if (process.platform !== "win32") {
+        if (st.mode & 0o077)
+            throw new KeyIsolationError(`${path} is readable by other users (mode ${(st.mode & 0o777).toString(8)}); make it 0600 (chmod 600)`);
+        const uid = process.getuid?.();
+        if (uid !== undefined && st.uid !== uid)
+            throw new KeyIsolationError(`${path} is owned by uid ${st.uid}, not by the node's user (uid ${uid}); the node's user must own its key file`);
+    }
+    const privateKey = parseKey(readFileSync(path, "utf8"), path);
+    return { privateKey, address: new Wallet(privateKey).address, source: { kind: "file", path } };
+}