toolroll 0.9.62 → 0.9.63

package/dist/tool-broker.d.ts

@@ -0,0 +1,37 @@
+import type { ToolSpec } from "./contracts/integration-metadata.js";
+/** One tool a launch may use: its values (never leaving this process) and, for research, the only actions it offers. */
+export type BrokeredTool = {
+    spec: ToolSpec;
+    values: Record<string, string>;
+    actions?: readonly string[];
+};
+export type BrokerOptions = {
+    /** Where a local server's environment comes from (the launch's): only SERVER_ENV's names are taken from it. */
+    env?: NodeJS.ProcessEnv;
+    omitEnv?: readonly string[];
+    /** Toolroll's own settings for a local server (the run's isolated database), passed as they are. */
+    pass?: Readonly<Record<string, string>>;
+    cwd?: string;
+    /** How a local server is started inside its run's fence, read when it starts (the fence is fixed after the tools). */
+    wrap?: () => ((file: string, args: readonly string[]) => {
+        file: string;
+        args: string[];
+    }) | null;
+};
+export type ToolBroker = {
+    /** The launch's token: the agent's only key to its tools. */
+    token: string;
+    url: (name: string) => string;
+    /** The local servers running now (the fence tests read them). */
+    pids: () => number[];
+    /** Revoke the token, stop every server, close the port. */
+    close: () => void;
+};
+/** What a local server inherits from the launch: enough to run and find its tools, and nothing that could be
+ * another tool's or a provider's secret. Its own configured values are added after. */
+export declare const SERVER_ENV: readonly string[];
+/** A local server's environment: the allowlisted names from `base` (and its LC_* locale), less `omit`, then `pass`,
+ * then the tool's own values. */
+export declare function serverEnv(base: NodeJS.ProcessEnv, omit: readonly string[], pass: Readonly<Record<string, string>>, values: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
+/** Start one launch's broker on a loopback port. */
+export declare function startToolBroker(tools: readonly BrokeredTool[], options?: BrokerOptions): Promise<ToolBroker>;

package/dist/tool-broker.js

@@ -0,0 +1,369 @@
+/**
+ * The tool broker: where a build's project tools keep their secrets.
+ *
+ * Anything a fenced agent can read, its shell can read too, so no tool secret
+ * may sit in its MCP config, its environment, an inherited descriptor or a
+ * process it can inspect. The broker runs in Toolroll's own process, outside
+ * the fence, for one launch: it holds each tool's resolved values in memory,
+ * starts a local server itself (with the values as that server's environment,
+ * inside the run's fence when it has one) or relays to a web server (adding
+ * the sign-in headers), and serves each tool as streamable HTTP on a loopback
+ * port. The agent's config names only that address and a token minted for
+ * this launch: valid for exactly its opted-in tools (a research step's only
+ * for their read-only actions), and revoked when the launch ends. A resumed
+ * build is a new launch with its own broker and token.
+ *
+ * What it relays is plain JSON-RPC: a request gets its answer as JSON, a
+ * notification is accepted, and a server's own requests (sampling, roots) are
+ * answered "not supported" — a build has nobody to ask.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+const BODY_LIMIT = 4 * 1024 * 1024;
+const ANSWER_LIMIT = 32 * 1024 * 1024;
+const STOP_GRACE_MS = 2_000;
+const rpcError = (id, message, code = -32000) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+const isRequest = (message) => typeof message.method === "string" && message.id !== undefined && message.id !== null;
+/** A research step's server lists and calls only its read-only actions. */
+function limitList(message, actions) {
+    if (actions === undefined || message === null || typeof message !== "object" || message.result === null || typeof message.result !== "object")
+        return message;
+    const result = message.result;
+    return { ...message, result: { ...result,
+            ...(Array.isArray(result["tools"]) ? { tools: result["tools"].filter(one => one !== null && typeof one === "object" && actions.includes(String(one.name))) } : {}),
+            // The research grant names tool actions only; it grants no resources or prompts.
+            ...Object.fromEntries(["resources", "resourceTemplates", "prompts"].filter(key => Array.isArray(result[key])).map(key => [key, []])), } };
+}
+const RESEARCH_METHODS = new Set(["initialize", "ping", "notifications/initialized", "notifications/cancelled", "tools/list", "resources/list", "resources/templates/list", "prompts/list"]);
+function refused(message, actions) {
+    if (actions === undefined || RESEARCH_METHODS.has(String(message.method)))
+        return null;
+    const name = message.params?.name;
+    if (message.method === "tools/call" && typeof name === "string" && actions.includes(name))
+        return null;
+    return rpcError(message.id, "This step may only read: that action is not available.", -32601);
+}
+/** What a local server inherits from the launch: enough to run and find its tools, and nothing that could be
+ * another tool's or a provider's secret. Its own configured values are added after. */
+export const SERVER_ENV = ["PATH", "HOME", "USER", "LANG", "TMPDIR", "SHELL", "TERM", "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR",
+    ...["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY"].flatMap(name => [name, name.toLowerCase()])];
+/** A local server's environment: the allowlisted names from `base` (and its LC_* locale), less `omit`, then `pass`,
+ * then the tool's own values. */
+export function serverEnv(base, omit, pass, values) {
+    const env = {};
+    for (const [name, value] of Object.entries(base))
+        if (value !== undefined && (SERVER_ENV.includes(name) || name.startsWith("LC_")))
+            env[name] = value;
+    for (const name of omit)
+        delete env[name];
+    return Object.assign(env, pass, values);
+}
+/** A local server, started on first use and spoken to over its stdin and stdout. */
+class LocalServer {
+    tool;
+    options;
+    child = null;
+    initialized = false;
+    buffer = "";
+    next = 1;
+    pending = new Map();
+    constructor(tool, options) {
+        this.tool = tool;
+        this.options = options;
+    }
+    pid() { return this.child?.pid ?? null; }
+    start() {
+        const env = serverEnv(this.options.env ?? process.env, this.options.omitEnv ?? [], this.options.pass ?? {}, this.tool.values);
+        const wrap = this.options.wrap?.() ?? null;
+        const { file, args } = wrap === null ? { file: this.tool.spec.command, args: [...this.tool.spec.args] } : wrap(this.tool.spec.command, this.tool.spec.args);
+        const child = spawn(file, args, { env, ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }), stdio: ["pipe", "pipe", "ignore"], detached: process.platform !== "win32" });
+        this.child = child;
+        this.initialized = false;
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => this.read(chunk));
+        const gone = (why) => {
+            if (this.child !== child)
+                return;
+            this.child = null;
+            for (const [, waiting] of this.pending)
+                waiting.done(rpcError(waiting.id, why));
+            this.pending.clear();
+        };
+        child.on("error", error => gone(`The tool could not start: ${error.message}.`));
+        child.on("exit", code => gone(`The tool stopped (exit ${code ?? "signal"}).`));
+        child.stdin?.on("error", () => undefined);
+        return child;
+    }
+    read(chunk) {
+        this.buffer += chunk;
+        for (let end = this.buffer.indexOf("\n"); end >= 0; end = this.buffer.indexOf("\n")) {
+            const line = this.buffer.slice(0, end).trim();
+            this.buffer = this.buffer.slice(end + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (message === null || typeof message !== "object")
+                continue;
+            if (isRequest(message)) {
+                this.write(rpcError(message.id, "Not supported in an unattended build.", -32601));
+                continue;
+            }
+            const waiting = typeof message.id === "number" ? this.pending.get(message.id) : undefined;
+            if (waiting === undefined)
+                continue;
+            this.pending.delete(message.id);
+            waiting.done({ ...message, id: waiting.id });
+        }
+    }
+    write(message) {
+        try {
+            this.child?.stdin?.write(`${JSON.stringify(message)}\n`);
+        }
+        catch { /* its exit answers whoever waits */ }
+    }
+    /** One message from the agent: a request's answer, or null for a notification. */
+    send(message) {
+        // A new session (a reconnect) starts a fresh server: a server answers initialize once.
+        if (message.method === "initialize" && this.initialized)
+            this.stop();
+        if (this.child === null)
+            this.start();
+        if (message.method === "initialize")
+            this.initialized = true;
+        if (!isRequest(message)) {
+            if (typeof message.method === "string")
+                this.write(message);
+            return Promise.resolve(null);
+        }
+        const id = this.next++;
+        return new Promise(resolve => {
+            this.pending.set(id, { id: message.id, done: resolve });
+            this.write({ ...message, id });
+        });
+    }
+    stop() {
+        const child = this.child;
+        if (child === null)
+            return;
+        this.child = null;
+        for (const [, waiting] of this.pending)
+            waiting.done(rpcError(waiting.id, "The tool was stopped."));
+        this.pending.clear();
+        const signal = (name) => {
+            try {
+                if (child.pid !== undefined && process.platform !== "win32")
+                    process.kill(-child.pid, name);
+                else
+                    child.kill(name);
+            }
+            catch { /* gone */ }
+        };
+        signal("SIGTERM");
+        if (child.exitCode === null && child.signalCode === null)
+            setTimeout(() => signal("SIGKILL"), STOP_GRACE_MS).unref();
+    }
+}
+/** A web server, relayed with its sign-in headers added here and nowhere else. */
+async function relayWeb(tool, request, body) {
+    const spec = tool.spec;
+    const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+    for (const name of ["mcp-session-id", "mcp-protocol-version", "last-event-id"]) {
+        const value = request.headers[name];
+        if (typeof value === "string")
+            headers[name] = value;
+    }
+    if (spec.bearer !== null && tool.values[spec.bearer])
+        headers["authorization"] = `Bearer ${tool.values[spec.bearer]}`;
+    for (const [header, secret] of Object.entries(spec.headerSecrets))
+        if (tool.values[secret])
+            headers[header] = tool.values[secret];
+    try {
+        // Never followed: a redirect would carry the sign-in headers to wherever it points.
+        const response = await fetch(spec.url, { method: request.method ?? "POST", headers, redirect: "error", ...(request.method === "POST" ? { body } : {}) });
+        const text = (await response.text()).slice(0, ANSWER_LIMIT);
+        return { status: response.status, type: response.headers.get("content-type") ?? "application/json", body: text, session: response.headers.get("mcp-session-id") };
+    }
+    catch {
+        let id = null;
+        try {
+            id = JSON.parse(body).id ?? null;
+        }
+        catch {
+            id = null;
+        }
+        return { status: 200, type: "application/json", body: JSON.stringify(rpcError(id, "The tool's server could not be reached.")) };
+    }
+}
+/** A relayed answer with a research step's list limited, JSON or event stream alike. An answer that isn't JSON (an
+ * accepted notification's empty 202) carries no list and passes as it is. */
+function limitAnswer(answer, actions) {
+    if (actions === undefined)
+        return answer;
+    if (!answer.type.includes("text/event-stream") && jsonOf(answer.body) === undefined)
+        return answer;
+    const limit = (text) => {
+        try {
+            const parsed = JSON.parse(text);
+            return JSON.stringify(Array.isArray(parsed) ? parsed.map(one => limitList(one, actions)) : limitList(parsed, actions));
+        }
+        catch {
+            return JSON.stringify(rpcError(null, "The tool returned an invalid response."));
+        }
+    };
+    const body = answer.type.includes("text/event-stream")
+        ? answer.body.split(/\r?\n\r?\n/).map(event => {
+            const lines = event.split(/\r?\n/);
+            const data = lines.filter(line => line.startsWith("data:")).map(line => line.slice(5).replace(/^ /, ""));
+            if (data.length === 0)
+                return event;
+            return [...lines.filter(line => !line.startsWith("data:")), `data: ${limit(data.join("\n"))}`].join("\n");
+        }).join("\n\n")
+        : limit(answer.body);
+    return { ...answer, body };
+}
+/** A body's JSON, or undefined when it is empty or not JSON. */
+function jsonOf(body) {
+    if (body.trim() === "")
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A research batch's relayed answer with the broker's refusals added: always something the agent can read. An event
+ * stream gets them as further events; anything else becomes one JSON 200 holding the server's answers, when it gave
+ * some as JSON, and the refusals. An empty or non-JSON answer (an accepted notification's 202) is never passed on
+ * alone, which would drop the refusals; a request the server left unanswered gets an error instead.
+ */
+function withRefusals(answer, allowed, refusals) {
+    if (answer.type.includes("text/event-stream")) {
+        return { ...answer, body: answer.body + refusals.map(one => `\nevent: message\ndata: ${JSON.stringify(one)}\n\n`).join("") };
+    }
+    const parsed = answer.status >= 200 && answer.status < 300 ? jsonOf(answer.body) : undefined;
+    const upstream = parsed === undefined ? [] : Array.isArray(parsed) ? parsed : [parsed];
+    const why = answer.status >= 200 && answer.status < 300 ? "The tool returned an invalid response." : `The tool's server answered HTTP ${answer.status}.`;
+    const unanswered = allowed.filter(one => isRequest(one) && !upstream.some(reply => reply !== null && typeof reply === "object" && reply.id === one.id)).map(one => rpcError(one.id, why));
+    return { ...answer, status: 200, type: "application/json", body: JSON.stringify([...upstream, ...unanswered, ...refusals]) };
+}
+function readBody(request) {
+    return new Promise(resolve => {
+        let size = 0;
+        const chunks = [];
+        request.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > BODY_LIMIT) {
+                resolve(null);
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        request.on("error", () => resolve(null));
+    });
+}
+/** Start one launch's broker on a loopback port. */
+export async function startToolBroker(tools, options = {}) {
+    const token = randomBytes(32).toString("base64url");
+    const expected = Buffer.from(`Bearer ${token}`);
+    let revoked = false;
+    const byName = new Map(tools.map(tool => [tool.spec.name, tool]));
+    const local = new Map(tools.filter(tool => tool.spec.transport !== "http").map(tool => [tool.spec.name, new LocalServer(tool, options)]));
+    const authorized = (request) => {
+        const given = Buffer.from(String(request.headers["authorization"] ?? ""));
+        return !revoked && given.length === expected.length && timingSafeEqual(given, expected);
+    };
+    const reply = (response, answer) => {
+        response.writeHead(answer.status, { "content-type": answer.type, ...(answer.session == null ? {} : { "mcp-session-id": answer.session }) });
+        response.end(answer.body);
+    };
+    const json = (status, value) => ({ status, type: "application/json", body: JSON.stringify(value) });
+    const handle = async (request, response) => {
+        const name = /^\/mcp\/([a-z0-9][a-z0-9_-]*)$/.exec(request.url ?? "")?.[1];
+        const tool = name === undefined ? undefined : byName.get(name);
+        if (!authorized(request))
+            return reply(response, json(401, { error: "This launch's tools are closed to that key." }));
+        if (tool === undefined)
+            return reply(response, json(404, { error: "No such tool in this launch." }));
+        if (request.method === "GET")
+            return reply(response, { status: 405, type: "text/plain", body: "" });
+        const server = local.get(tool.spec.name);
+        if (request.method === "DELETE") {
+            if (server !== undefined) {
+                server.stop();
+                return reply(response, { status: 200, type: "text/plain", body: "" });
+            }
+            return reply(response, await relayWeb(tool, request, ""));
+        }
+        if (request.method !== "POST")
+            return reply(response, { status: 405, type: "text/plain", body: "" });
+        const body = await readBody(request);
+        if (body === null)
+            return reply(response, json(413, rpcError(null, "The message is too large.")));
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return reply(response, json(400, rpcError(null, "Parse error", -32700)));
+        }
+        const messages = Array.isArray(parsed) ? parsed : [parsed];
+        if (messages.length === 0 || messages.some(one => one === null || typeof one !== "object" || Array.isArray(one) || typeof one.method !== "string"))
+            return reply(response, json(400, rpcError(null, "Invalid request", -32600)));
+        // A refused action is answered here and never reaches the tool.
+        const refusals = messages.map(one => refused(one, tool.actions));
+        const deniedAnswers = refusals.filter((one, index) => one !== null && isRequest(messages[index]));
+        if (refusals.every(one => one !== null))
+            return reply(response, deniedAnswers.length === 0
+                ? { status: 202, type: "text/plain", body: "" }
+                : json(200, Array.isArray(parsed) ? deniedAnswers : deniedAnswers[0]));
+        if (server === undefined) {
+            const allowed = messages.filter((_, index) => refusals[index] === null);
+            // Relay exactly what was parsed and authorized, never ambiguous raw JSON.
+            const answer = limitAnswer(await relayWeb(tool, request, JSON.stringify(Array.isArray(parsed) ? allowed : allowed[0])), tool.actions);
+            return reply(response, deniedAnswers.length === 0 ? answer : withRefusals(answer, allowed, deniedAnswers));
+        }
+        const answers = [];
+        for (const [index, message] of messages.entries()) {
+            const answer = refusals[index] ?? await server.send(message);
+            if (answer !== null && isRequest(message))
+                answers.push(limitList(answer, tool.actions));
+        }
+        if (answers.length === 0)
+            return reply(response, { status: 202, type: "text/plain", body: "" });
+        return reply(response, json(200, Array.isArray(parsed) ? answers : answers[0]));
+    };
+    const server = createServer((request, response) => {
+        handle(request, response).catch(() => {
+            if (!response.headersSent)
+                reply(response, json(500, rpcError(null, "The tool broker failed.")));
+            else
+                response.end();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+    const port = server.address().port;
+    return {
+        token,
+        url: name => `http://127.0.0.1:${port}/mcp/${name}`,
+        pids: () => [...local.values()].map(one => one.pid()).filter((pid) => pid !== null),
+        close: () => {
+            revoked = true;
+            for (const one of local.values())
+                one.stop();
+            server.close();
+            server.closeAllConnections();
+        },
+    };
+}

package/dist/tool-launcher.js

@@ -2,10 +2,11 @@
  * The launcher a Codex build starts each project tool through (v80):
  * `node tool-launcher.js <config.json>`. Codex hands its own environment
  * to the agent's shell whatever `shell_environment_policy` says (checked
- * against codex-cli 0.156), so a tool's secrets never ride Codex's
- * environment: they sit in the run's private 0600 file, and this process
- * gives them to exactly one server — as its environment for a local
- * program, or as sign-in headers for a web server it relays to over stdio.
+ * against codex-cli 0.156), so nothing rides Codex's environment. A build's
+ * launch file names its run's tool broker (tool-broker.ts) and that launch's
+ * token, and this process relays stdio to it over HTTP; the tool's own
+ * secrets stay in the broker. A launch file naming a local program or a web
+ * server with its values is still run as before.
  */
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";

package/dist/tool-secret-store.d.ts

@@ -0,0 +1,170 @@
+export type SecretStoreKind = "macos-keychain" | "secret-service" | "files";
+/** One item's address: what the store lists, never a secret (a folder's or project's hash, a tool's name). */
+export type SecretItem = {
+    service: string;
+    account: string;
+};
+export type SecretBackend = {
+    kind: Exclude<SecretStoreKind, "files">;
+    /** Values are [A-Za-z0-9._-] only, at most `limit` characters. */
+    limit: number;
+    get(item: SecretItem): string | null;
+    /** `create`: only when no item is there yet ("exists" when one is). */
+    set(item: SecretItem, value: string, options?: {
+        create?: boolean;
+    }): "ok" | "exists";
+    remove(item: SecretItem): void;
+};
+export declare class SecretStoreError extends Error {
+}
+/** The words Settings and `toolroll integrations` use for where secrets rest. */
+export declare const STORE_WORDS: Readonly<Record<SecretStoreKind, string>>;
+/** Said instead when a keyring is installed but doesn't answer, so files are all there is. */
+export declare const UNANSWERED_WORDS = "Secrets are protected by owner-only files on this computer: its keyring isn't answering.";
+/** The macOS Keychain, through `security -i` (`keychain`: a keychain file instead of the user's own, for tests). */
+export declare function macosKeychain(options?: {
+    keychain?: string;
+    binary?: string;
+}): SecretBackend;
+/** The Secret Service (GNOME Keyring, KWallet), through `secret-tool` at `binary`, an absolute path; the value goes on its stdin. */
+export declare function secretService(options: {
+    binary: string;
+}): SecretBackend;
+/**
+ * `path` when it is a program only the system (or, for a test's stand-in, one of `owners`) can have put there: a real
+ * executable file nobody else can change, in folders nobody else can either. Null otherwise.
+ */
+export declare function trustedProgram(path: string, owners?: readonly number[]): string | null;
+/** Where `secret-tool` may be: the system's own folders, never the PATH a process was given. */
+export declare const SECRET_TOOL_PATHS: readonly string[];
+/** This computer's store as found: a backend, or none, and when none, whether one is installed but not answering. */
+export type DetectedStore = {
+    backend: SecretBackend | null;
+    unanswered: boolean;
+};
+/**
+ * Find this computer's store: the macOS Keychain where the system's `security` is; a Secret Service where the system's
+ * `secret-tool` is and answers; else none (files). A `secret-tool` that is there but can't reach a keyring (no session
+ * bus) is none too, and says so.
+ */
+export declare function detectSecretStore(options?: {
+    platform?: NodeJS.Platform;
+    secretTools?: readonly string[];
+    owners?: readonly number[];
+}): DetectedStore;
+/** Tests choose the store (a keychain file of their own, files, or what detection found); null goes back to this computer's. */
+export declare function chooseSecretStore(store: SecretBackend | "files" | DetectedStore | null): void;
+/** This computer's store (found once), or null for owner-only files. */
+export declare function secretBackend(env?: NodeJS.ProcessEnv): SecretBackend | null;
+export declare const secretStoreKind: () => SecretStoreKind;
+/** Where secrets rest, in the words Settings and `toolroll integrations` share; `problem` when Toolroll's folder can't be used. */
+export declare function secretStorage(): {
+    kind: SecretStoreKind;
+    words: string;
+    filesOnly: boolean;
+    problem?: string;
+};
+/** The text stored at `item`, or null when nothing is. A head read while a writer replaces it is read again. */
+export declare function readValue(backend: SecretBackend, item: SecretItem): string | null;
+/**
+ * Store `text` at `item`: the chunks of a new generation first, then the head that names them, then the old
+ * generation's chunks are removed. `create`: only when nothing is stored there yet.
+ */
+export declare function writeValue(backend: SecretBackend, item: SecretItem, text: string, options?: {
+    create?: boolean;
+}): "ok" | "exists";
+/** Remove what is stored at `item`, every chunk with it. */
+export declare function removeValue(backend: SecretBackend, item: SecretItem): void;
+/** The folder's name, beside the database. */
+export declare const SECRET_FOLDER = "tool-secrets";
+/** Where Toolroll records which sealing key it made: the database, which no build can write. */
+export type KeyAnchor = {
+    read(): string | null;
+    swap(expected: string | null, next: string): boolean;
+};
+/** An anchor kept in this process alone: a test's own folder. */
+export declare function memoryAnchor(): KeyAnchor;
+/** Toolroll's folder for secrets, checked: its key in hand, and where the files kept before it are (`legacy`). */
+export type SecretFolder = {
+    readonly root: string;
+    readonly dir: string;
+    readonly legacy: string | null;
+    dev: number;
+    ino: number;
+    key: Buffer;
+    digest: string;
+    anchor: KeyAnchor;
+};
+/**
+ * Prepare Toolroll's folder for secrets beside `stateDir` (the folder holding the database), checked against what
+ * `anchor` recorded: made with its sealing key when it isn't there yet (`create`), refused when something else put a
+ * folder, key or link there. `standing`: the folder this process uses by default (Toolroll's own start).
+ */
+export declare function prepareSecretFolder(stateDir: string, anchor: KeyAnchor, options?: {
+    create?: boolean;
+    legacy?: string | null;
+    standing?: boolean;
+}): {
+    ok: true;
+    dir: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Name Toolroll's folder for secrets (beside `stateDir`, the database's folder) and the record to check it against,
+ * without touching it yet: it is prepared the first time a secret is used. `standing`: this process's default.
+ */
+export declare function registerSecretFolder(stateDir: string, anchor: KeyAnchor, options?: {
+    legacy?: string | null;
+}): void;
+/**
+ * Toolroll's folder for secrets, checked again now: the one prepared at start when `state` is absent, else the one
+ * beside `state` (a test's own folder is prepared the first time it is used, against an anchor in this process).
+ */
+export declare function secretFolder(state?: string): SecretFolder;
+/** Forget every prepared folder (tests). */
+export declare function forgetSecretFolders(): void;
+/** The keychain service for everything kept for this folder's Toolroll: its folder, hashed. Never a secret. */
+export declare const serviceOf: (folder: SecretFolder) => string;
+/**
+ * A path inside `base` (the folder, or Toolroll's own folder above it), each folder on the way checked: a real folder
+ * of this user's that nobody else can write, never a link. Made owner-only when `make` (else a missing one ends the
+ * walk: nothing is there).
+ */
+export declare function pathIn(base: string, parts: readonly string[], options?: {
+    make?: boolean;
+}): string;
+/** A file's text, read without following a link; null when there is none. Anything not plainly Toolroll's is refused. */
+export declare function readOwnFile(path: string): string | null;
+/** Write a file whole and owner-only: a new file beside it, then renamed over it, so a link or second name planted there is replaced, never written through. */
+export declare function writeOwnFile(path: string, text: string): void;
+/** A file's bytes overwritten, then the file removed (a link is only removed, never followed). */
+export declare function destroyOwnFile(path: string): void;
+/** One change at a time to what `name` keeps, across Toolroll's processes (a lock file in the folder), re-entrant within one. */
+export declare function withSecretLock<T>(folder: SecretFolder, name: string, work: () => T): T;
+/** The same, for work that waits on the network (renewing a sign-in): other processes wait for it, up to `waitMs`. */
+export declare function withSecretLockAsync<T>(folder: SecretFolder, name: string, work: () => Promise<T>, options?: {
+    staleMs?: number;
+    waitMs?: number;
+}): Promise<T>;
+/** `text` sealed for `item` with the folder's key. */
+export declare function seal(text: string, item: SecretItem, folder: SecretFolder): string;
+/** What `seal` sealed for `item`; refused when it was sealed for another item, with another key, or changed. */
+export declare function unseal(sealed: string, item: SecretItem, folder: SecretFolder): string;
+/** The sealed text kept at `item`, opened; null when nothing is. */
+export declare function readSealed(backend: SecretBackend, folder: SecretFolder, item: SecretItem): string | null;
+/** Keep `text` at `item`, sealed. */
+export declare function writeSealed(backend: SecretBackend, folder: SecretFolder, item: SecretItem, text: string, options?: {
+    create?: boolean;
+}): "ok" | "exists";
+/**
+ * A secret Toolroll holds for an integration, by `name` ("linear-key", "google-mail", "flow-hook.12"), for the
+ * Toolroll whose folder is `state`. `file` (inside `state`) is where it was kept before, and still is where there's no
+ * keychain. The first read or write with a keychain moves the file in.
+ */
+export declare function readHeldSecret(state: string, name: string, file: readonly string[]): string | null;
+/** Keep (or, with null, remove) a held secret: see readHeldSecret. */
+export declare function writeHeldSecret(state: string, name: string, file: readonly string[], value: string | null): void;
+/** Whether a held secret has a value, without reading it where that can be helped. */
+export declare function heldSecretSet(state: string, name: string, file: readonly string[]): boolean;