botanary-mcp 0.1.0

package/README.md

@@ -0,0 +1,235 @@
+# botanary-mcp
+
+Botanary's **agent connector**: a local MCP server that lets an outside coding agent - Claude Code,
+Codex, Cursor, or something you wrote yourself - hold its own signing key, prove who it is, pair with a
+Botanary account, read its balance, and spend under whatever grant its owner gave it - all without
+Botanary ever holding, seeing, or backing up that key.
+
+The tools this server exposes:
+
+| Tool | What it does |
+|---|---|
+| `get_identity` | Reports this agent's address/public key/fingerprint. Generates the key on first call. No network call. |
+| `get_pairing_code` / `regenerate_pairing_code` | Shows (or rotates) the short code the owner types into "Connected agents". No network call. |
+| `pair` | Signs the pairing code and submits the proof to `POST /agents/pair`. |
+| `whoami` | Calls `GET /agents/me` - this agent's own identity, account, and live grant (or an honest `grant: null`). |
+| `get_balance` | Calls `GET /balance` under this agent's session. |
+| `propose_payment` | Reads the grant's bounds first; refuses honestly (citing the backend's own numbers) when there is none or the amount is out of bounds; otherwise builds against THIS agent's own grant id (`POST /delegations/{delegationId}/actions` - the session-key-validatable lane, never the owner-lane `/money/send/build`) and relays (`POST /userops`) signed with the grant's own session key. |
+| `request_approval` | Raises a request for an action outside the grant (`POST /agents/requests`) - the "ask" half of Flow 7d. |
+| `what_may_i_do` | Renders the grant in plain terms, or an honest "nothing yet" - a convenience read, never the check. |
+
+`forget` (delete the key from this machine) is a **CLI command only**, not a tool - see "Why `forget` has
+no MCP tool" below.
+
+## Add it to your agent
+
+One-time setup (from this directory):
+
+```bash
+pnpm install   # also builds dist/ automatically (see "prepare" in package.json)
+```
+
+Then, the one command per client:
+
+```bash
+# Claude Code
+claude mcp add --transport stdio botanary -- node "$(pwd)/dist/bin/botanary-mcp.js"
+
+# Codex
+codex mcp add botanary -- node "$(pwd)/dist/bin/botanary-mcp.js"
+```
+
+The server talks to `https://api.app.botanary.xyz` by default. Point it somewhere else with
+`BOTANARY_API_URL`:
+
+```bash
+claude mcp add --transport stdio botanary \
+  -e BOTANARY_API_URL=http://localhost:3000 \
+  -- node "$(pwd)/dist/bin/botanary-mcp.js"
+```
+
+Cursor has no CLI equivalent - add this block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json`
+(global) instead:
+
+```json
+{
+  "mcpServers": {
+    "botanary": {
+      "command": "node",
+      "args": ["/absolute/path/to/tools/botanary-mcp/dist/bin/botanary-mcp.js"]
+    }
+  }
+}
+```
+
+Restart the client so it picks up the new server. Once connected, ask the agent for its Botanary
+identity or pairing code - it will call `get_identity` / `get_pairing_code` and read the key
+straight out of wherever this machine's OS keeps secrets. The first call generates the key; nothing
+before that point touches disk or asks any question.
+
+## What a freshly-connected agent can and cannot do
+
+This is the product's own promise (Flow 7c/7d), and every tool in this package exists to make it true:
+
+- **Connecting is harmless by itself.** A newly connected, ungranted agent can read balances
+  (`get_balance`) and read its own bounds (`whoami`/`what_may_i_do`) - `propose_payment` refuses
+  honestly, citing the backend's own "you have no grant" answer, rather than pretending. It cannot move
+  a cent.
+- **What it's granted, it can spend - unattended, signed with its own key.** `propose_payment` builds
+  and relays a payment under the grant when the amount is within its bounds. Nothing outside that grant
+  works; `request_approval` turns it into a request the owner approves as themselves, or it doesn't
+  happen.
+- **What it can never do, no matter what it was granted:** sign in as the owner, add or remove a
+  signer, write or change a policy, grant access to another agent, or unfreeze the account. A grant is
+  permission to spend inside a fence, never permission to move the fence. None of these tools exist in
+  this package - there is nothing here that could call them even if a prompt tried to talk it into it.
+- **The bound it reads is a convenience, not the check.** `whoami`/`what_may_i_do`/`propose_payment`'s
+  own pre-check all read the grant's bounds from the backend, but the actual enforcement happens
+  on-chain. A bug or a lie in what any of them reports changes nothing about what this agent can
+  actually get away with.
+
+## Why intercepting the pairing code alone grants nothing
+
+The short code this server shows (`get_pairing_code`) is built from two parts, and **neither one is a
+secret**:
+
+1. A **fingerprint** - a few characters derived from the agent's *public* key. It exists so a human can
+   visually confirm "yes, this is the code my agent just showed me," the same role an SSH host-key
+   fingerprint plays. It is only ever a function of information that's already public (the address
+   itself is shared openly by `get_identity`), so there is nothing about it worth hiding to begin with.
+2. A **nonce** - fresh randomness, generated new each time a pairing attempt starts, with a short
+   (10-minute default) expiry. This is what makes the code single-use and short-lived: once it expires,
+   or once a fresh one is requested, the old code stops being the one anything checks against.
+
+Neither piece is derived *from* the private key, and there's no computation that gets you from
+"fingerprint + nonce" back to the 32 bytes that would let something sign as this agent. The code isn't
+an obfuscated secret - it was never built out of one.
+
+That's what makes the rest of the claim hold: **the code identifies, the signature authenticates.**
+Completing a connection is designed to require the agent to sign a server-issued challenge with the key
+that never left this machine - proof of possession, not proof of having seen a string. Someone who only
+intercepted the code cannot produce that signature, because they don't have the key. The worst they can
+do is type the code into their *own* Botanary account's "Connected agents" box - which, per the product
+rule above, gets *them* nothing: a connection with no grant can do nothing, and it takes nothing away
+from the real owner, whose agent still holds the only key that can ever complete a real pairing for that
+identity. There is no password, token, or secret anywhere in this exchange for anyone to steal.
+
+(The `pair` tool is what actually submits the signed challenge - `POST /agents/pair` - to complete this
+half of a pairing. The cryptographic property above does not depend on that call existing: the code is
+derived only from public information, so intercepting it is intercepting nothing, whether or not
+anything has submitted a proof yet.)
+
+## The key: generated here, stored here, never sent anywhere
+
+**This is a property to preserve, not an implementation detail.** There is no code path in this package
+that sends the private key anywhere - no telemetry, no crash reporting, no "just in case" backup, no
+cloud sync. `test/no-leak.spec.ts` exists specifically to keep that true: it drives every tool, the real
+MCP protocol, the CLI, and a deliberately misbehaving backend that tries to leak the key through an
+error message, then greps everything that came out for it. If you're extending this package, that test
+is the one to think hardest about before touching.
+
+The key is generated locally on first use (secp256k1, the same curve/derivation as every other signer in
+this system - see `src/identity/keypair.ts`) and handed to the best available OS secret store:
+
+| Platform | Backend | Mechanism |
+|---|---|---|
+| macOS | Keychain | the `security` CLI (`add-generic-password` / `find-generic-password` / `delete-generic-password`) |
+| Linux | Secret Service (GNOME Keyring, KWallet's libsecret shim, ...) | the `secret-tool` CLI, secret piped over **stdin** |
+| Windows | DPAPI, current-user scope | a short PowerShell call to `ProtectedData.Protect`/`Unprotect`, secret piped over **stdin**; only the ciphertext touches disk |
+| any platform, if none of the above is available | a local file, mode `0600`, parent dir `0700` | plain file, last resort only |
+
+No native addon is linked for any of this - every backend shells out to a platform CLI that's already
+there, which is also why `npm install` never needs a compiler. The trade-off is documented rather than
+hidden: macOS's `security` CLI has no way to pass the password except as an argument, so it's briefly
+visible in this process's own argv (to anything else on the same machine that can list processes) for
+the moment that one command runs - `secret-tool` and the Windows path both avoid this by using stdin.
+See the comments in `src/identity/backends/*.ts` for the full reasoning per backend.
+
+Two more things worth knowing:
+
+- **Exactly one copy, always.** A new key is written to the *first* available backend and stops there -
+  never a redundant "backup" copy in a second place. `src/identity/store.ts` and its tests
+  (`test/identity/store.spec.ts`) pin this down explicitly.
+- **The key is read fresh for every signing operation and never cached in memory.** Only `store.sign()`
+  (EIP-191 personal-message signing) and `store.signHash()` (raw ECDSA over an exact 32-byte hash - what
+  `pair`/session-minting/`propose_payment`'s spend all actually use, since the backend recovers over the
+  raw hash with no prefix) ever touch it, and only for the duration of that one call. Identity lookups
+  (`get_identity`, `get_pairing_code`) never touch the keychain at all - they read a small, non-secret
+  metadata file (address / public key / fingerprint / when it was created / which backend holds the key)
+  that's written once alongside the real key and never contains it.
+
+### Deleting the key on its own machine
+
+```bash
+node dist/bin/botanary-mcp.js forget
+```
+
+This deletes the private key from wherever it's stored (every backend candidate is swept, not just the
+one currently in use, so this also cleans up after a platform change or a partial past failure) and
+clears the local identity. **It does not touch any grant a Botanary account still has on file for that
+address** - this machine never had the authority to revoke that, only the key. That's the whole point:
+after this command, nothing on this machine can produce a signature for the old address, which is the
+part anyone can verify for themselves without trusting Botanary's word for it. `test/identity/store.spec.ts`
+and `test/no-leak.spec.ts` both exercise this directly: after `forget()`, signing fails, and the *next*
+identity created is a different address - proof the old key is really gone, not just hidden.
+
+#### Why `forget` has no MCP tool
+
+Every other capability in this package is an MCP tool because an agent legitimately needs to invoke it
+itself. Deleting its own key is different: an agent that can erase its own identity ON REQUEST is one an
+injected instruction (a poisoned webpage, a malicious dependency's README, anything the agent reads as
+part of its normal work) can silence - "forget your Botanary identity" is exactly the kind of one-line
+instruction a prompt injection would try, and a tool that honored it would hand an attacker a free,
+untraceable way to sever a working connection. There is no legitimate reason an AGENT (as opposed to the
+human running it) would ever need to delete its own key mid-session, so `forget` stays a command the
+human runs directly (`node dist/bin/botanary-mcp.js forget`), never something `tools.ts` exposes -
+`test/tools.spec.ts` and `test/server.spec.ts` both assert no tool named `forget` exists.
+
+## Development
+
+```bash
+pnpm install       # installs deps and builds dist/ (the "prepare" script)
+pnpm build         # rebuild dist/ by hand
+pnpm dev           # run bin/botanary-mcp.ts directly, watching for changes (no MCP client attached)
+pnpm typecheck     # tsc --noEmit, strict (matches the backend repo's compiler settings)
+pnpm test          # vitest - no network, no real keychain (every OS call is mocked; see
+                    # test/fixtures/fake-exec.ts and test/fixtures/fake-backend.ts)
+```
+
+`BOTANARY_MCP_HOME` overrides where the non-secret metadata file (and the file-fallback secret, if it's
+ever in use) live - defaults to `~/.botanary-mcp`. It exists mainly for tests and for running this
+server inside a container with an isolated home; a normal install never needs to set it.
+
+## What's deliberately not here
+
+Everything the original design called out as "later work" is now built: the pairing HTTP exchange
+(`pair`), reading balances (`get_balance`), building and relaying under a grant (`propose_payment`), and
+the out-of-grant request lane (`request_approval`, Flow 7d step 5 - "ask, when it needs more").
+
+What stays out on purpose:
+
+- **`forget` as a tool** - see "Why `forget` has no MCP tool" above. It remains a human-run CLI command.
+- **Owner-lane authority.** Nothing in this package can add or remove a signer, write or change a
+  policy, grant another agent access, or unfreeze the account - not because those endpoints are hard to
+  call, but because an agent's grant is authority to spend inside a fence, never authority to move the
+  fence. There is no tool here that could be talked into trying.
+- **A cached or session-spanning bounds check as the real gate.** `propose_payment`'s pre-check (and
+  `what_may_i_do`'s rendering) reads `GET /agents/me` fresh via `AgentRuntime.me()` and refuses using
+  whatever the backend reports at that moment - it never assumes a bound it read earlier still holds.
+  The chain is still the only real enforcement either way (see "The bound it reads is a convenience, not
+  the check" above).
+
+`src/runtime.ts`'s `AgentRuntime` is the seam every tool in `src/tools.ts` is built on: it owns identity,
+signing (`store.sign()`/`store.signHash()`), a cached-with-retry agent session, and one method per
+backend call a tool needs (`me`, `getBalance`, `buildDelegatedAction`, `raiseRequest`, `spendUnderGrant`) -
+a future tool extends this class rather than reaching for `fetch` directly.
+
+`buildDelegatedAction` (`POST /delegations/{delegationId}/actions`), not `/money/send/build`, is the
+build call `propose_payment` uses, and deliberately so: `/money/send/build` builds an owner-lane op in
+the Kernel account's ROOT nonce lane, which a session-key signature can never validate (it routes
+validation to the root ECDSA validator, which cannot parse the USE-mode `(bytes1, bytes32, bytes)`
+envelope `spendUnderGrant` wraps every signature in as anything resembling a valid 65-byte ECDSA
+signature). `/delegations/{delegationId}/actions` builds in the delegation's own Smart Sessions nonce
+lane with fixed native gas instead - the one lane this package's session key can actually sign for. The
+backend additionally scopes this route to the caller's OWN grant: an agent session naming a *different*
+agent's delegation id is refused (403, named reason) before any build happens at all.

package/dist/bin/botanary-mcp.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { runCli } from '../src/cli.js';
+import { createDefaultRuntime } from '../src/runtime.js';
+import { createServer } from '../src/server.js';
+// Deliberately the only file in this package that is not unit tested directly - it does nothing but
+// wire the real runtime/server/transport into runCli (src/cli.ts), which is where all the actual
+// logic and tests live. Trust this file by reading it, the same way tools/agent-harness/mcp/server.mjs
+// keeps its own main() to a couple of lines around attachShutdown.
+const exitCode = await runCli(process.argv.slice(2), {
+    runtime: createDefaultRuntime(),
+    createServer,
+    createTransport: () => new StdioServerTransport(),
+});
+// The `serve` (no-args) path resolves once the stdio transport is connected, then the process stays
+// alive on its own (stdin is being read) until the client closes the pipe or the process is signaled -
+// there is nothing to await further and nothing here should force an exit while a session is live.
+if (process.argv.slice(2).length > 0) {
+    process.exit(exitCode);
+}
+//# sourceMappingURL=botanary-mcp.js.map

package/dist/bin/botanary-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"botanary-mcp.js","sourceRoot":"","sources":["../../bin/botanary-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,oGAAoG;AACpG,iGAAiG;AACjG,uGAAuG;AACvG,mEAAmE;AACnE,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACnD,OAAO,EAAE,oBAAoB,EAAE;IAC/B,YAAY;IACZ,eAAe,EAAE,GAAG,EAAE,CAAC,IAAI,oBAAoB,EAAE;CAClD,CAAC,CAAC;AAEH,oGAAoG;AACpG,uGAAuG;AACvG,mGAAmG;AACnG,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC"}

package/dist/src/api-client.js

@@ -0,0 +1,42 @@
+/** Thrown for any non-2xx response, carrying the HTTP status alongside the SERVER's own message (never a
+ *  generic one - whoever built this agent needs the reason, §6-40 one layer up from the chain). The
+ *  status is what lets `AgentRuntime` tell "this session token is stale, re-mint and retry" (401) apart
+ *  from every other failure, which it should surface as-is. */
+export class BotanaryApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'BotanaryApiError';
+    }
+}
+/** JSON in and out, throwing the SERVER's own message rather than a generic one - whoever built this
+ *  agent needs the reason, not "request failed" (§6-40, one layer up from the chain). */
+export class BotanaryApiClient {
+    baseUrl;
+    fetchImpl;
+    constructor(baseUrl, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.fetchImpl = fetchImpl;
+    }
+    async post(path, body, token) {
+        return this.#request('POST', path, body, token);
+    }
+    /** GET has no body - a query string, when one is needed, belongs in `path` itself (callers below never
+     *  put a token or anything secret there; see test/no-leak.spec.ts). */
+    async get(path, token) {
+        return this.#request('GET', path, undefined, token);
+    }
+    async #request(method, path, body, token) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const json = (await res.json());
+        if (!res.ok)
+            throw new BotanaryApiError(json?.error?.message ?? `${path} failed with ${res.status}`, res.status);
+        return json;
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/src/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AAAA;;;+DAG+D;AAC/D,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAG9B;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;yFACyF;AACzF,MAAM,OAAO,iBAAiB;IAET;IACA;IAFnB,YACmB,OAAe,EACf,YAA0B,KAAK;QAD/B,YAAO,GAAP,OAAO,CAAQ;QACf,cAAS,GAAT,SAAS,CAAsB;IAC/C,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAa,EAAE,KAAc;QACvD,OAAO,IAAI,CAAC,QAAQ,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IAED;2EACuE;IACvE,KAAK,CAAC,GAAG,CAAI,IAAY,EAAE,KAAc;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAI,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAI,MAAsB,EAAE,IAAY,EAAE,IAAa,EAAE,KAAc;QACnF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACzD,MAAM;YACN,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YACvG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqC,CAAC;QACpE,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,IAAI,GAAG,IAAI,gBAAgB,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACjH,OAAO,IAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/src/cli.js

@@ -0,0 +1,79 @@
+const HELP_TEXT = `botanary-mcp - Botanary's agent connector (local MCP server)
+
+Usage:
+  botanary-mcp                 Start the MCP server (stdio transport). This is what an MCP client
+                                (Claude Code, Codex, Cursor, ...) runs - see the README for the exact
+                                one-line command per client.
+  botanary-mcp whoami           Print this agent's identity (address, public key, fingerprint) without
+                                starting a server. Never prints the private key.
+  botanary-mcp forget           Delete the agent's private key from this machine (OS keychain or file
+                                fallback). Any grant a Botanary account still has on file for this
+                                agent's address is UNCHANGED - revoke that separately, in Botanary. See
+                                the README ("what deleting the key does and doesn't do").
+  botanary-mcp --help           Show this message.
+`;
+/** Runs one CLI invocation and returns the process exit code. Kept free of `process.exit`/signal
+ *  handling so it's directly testable with fake deps - see test/cli.spec.ts. bin/botanary-mcp.ts is
+ *  the (deliberately tiny, untested-by-inspection) shim that wires real deps and process lifecycle. */
+export async function runCli(argv, deps) {
+    const stdout = deps.stdout ?? ((line) => process.stdout.write(`${line}\n`));
+    const stderr = deps.stderr ?? ((line) => process.stderr.write(`${line}\n`));
+    const [command] = argv;
+    try {
+        switch (command) {
+            case undefined:
+                return await serve(deps, stderr);
+            case 'whoami':
+                return await whoami(deps, stdout);
+            case 'forget':
+                return await forget(deps, stdout);
+            case '--help':
+            case '-h':
+            case 'help':
+                stdout(HELP_TEXT);
+                return 0;
+            default:
+                stderr(`Unknown command "${command}". Run "botanary-mcp --help" for usage.`);
+                return 1;
+        }
+    }
+    catch (e) {
+        stderr(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+}
+async function serve(deps, stderr) {
+    // The server must not die mid-session over a stray async error - mirrors
+    // tools/agent-harness/mcp/server.mjs's own top-level handlers, for the same reason: the failing
+    // call already gets an error result through the normal tool-call try/catch (see server.ts); this is
+    // only a last-resort net so an unrelated stray rejection can't take the whole stdio session down.
+    process.on('unhandledRejection', (e) => stderr(`unhandledRejection: ${e instanceof Error ? e.message : String(e)}`));
+    process.on('uncaughtException', (e) => stderr(`uncaughtException: ${e.message}`));
+    const server = deps.createServer(deps.runtime);
+    await server.connect(deps.createTransport());
+    return 0;
+}
+async function whoami(deps, stdout) {
+    const identity = await deps.runtime.identity();
+    stdout(JSON.stringify({
+        address: identity.address,
+        publicKey: identity.publicKey,
+        fingerprint: identity.fingerprint,
+        createdAt: identity.createdAt,
+        keyStorage: identity.backend,
+    }, null, 2));
+    return 0;
+}
+async function forget(deps, stdout) {
+    const hadIdentity = await deps.runtime.store.hasIdentity();
+    await deps.runtime.store.forget();
+    deps.runtime.reset();
+    stdout(hadIdentity
+        ? 'Deleted the agent key from this machine. It can no longer sign anything - including for any ' +
+            'grant a Botanary account still has on file for its old address. That grant itself still ' +
+            'exists until its owner revokes it in Botanary; this command only removes the key, which is ' +
+            'the only thing this machine ever held.'
+        : 'No agent identity was stored on this machine - nothing to delete.');
+    return 0;
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/identity/backends/exec.js

@@ -0,0 +1,34 @@
+// A tiny, injectable process-runner. Every real key-storage backend (macOS Keychain, libsecret,
+// Windows DPAPI) shells out to a platform CLI rather than linking a native addon - see the package
+// README for why. Routing every backend through this one seam is what makes the backend tests real
+// unit tests: they inject a fake `Exec` and never touch an actual keychain, `security`, `secret-tool`,
+// or `powershell` process (the harness this package's tests must run without, per the task brief).
+/** The real implementation: spawn a child process (no shell - argv is passed directly, so there is no
+ *  shell-quoting/injection surface), capture stdout/stderr, resolve with the exit code. `spawn` (not
+ *  `execFile`) because we need to write to stdin ourselves and close it explicitly. */
+export const nodeExec = async (command, args, options) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            // ENOENT (binary not installed) and similar - the caller treats this as "backend unavailable".
+            reject(err);
+        });
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code: code ?? -1 });
+        });
+        if (options?.input !== undefined) {
+            child.stdin.write(options.input, 'utf8');
+        }
+        child.stdin.end();
+    });
+};
+//# sourceMappingURL=exec.js.map

package/dist/src/identity/backends/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../../src/identity/backends/exec.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,mGAAmG;AACnG,mGAAmG;AACnG,uGAAuG;AACvG,mGAAmG;AAkBnG;;uFAEuF;AACvF,MAAM,CAAC,MAAM,QAAQ,GAAS,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IAC7D,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACrD,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxE,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,+FAA+F;YAC/F,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;YACjC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/src/identity/backends/file-fallback.js

@@ -0,0 +1,58 @@
+import { dirname } from 'node:path';
+import { chmod, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { KeyBackendError } from './types.js';
+import { fileFallbackSecretPath } from '../../paths.js';
+// The last-resort backend, used only when no platform keychain is available (Linux with no Secret
+// Service running, a locked-down/headless box, or an unsupported platform). A plain file, permissions
+// locked down as tightly as this process can manage:
+//   - parent dir created 0700 (owner rwx only) and the mode reasserted after mkdir in case an umask
+//     loosened it, or the directory already existed with wider permissions from a previous run;
+//   - the file itself written 0600 (owner rw only) and reasserted after write for the same reason -
+//     `writeFile`'s `mode` option is only honored when the file doesn't already exist yet, so an
+//     overwrite of an existing file (key rotation) would silently keep whatever mode it already had
+//     without the explicit chmod below.
+// This is real protection against another local user reading the file, but it is not what "the key
+// never leaves the machine" is about - a keychain backend is preferred on every platform this package
+// knows how to detect one on. See README for when this path is actually taken.
+export function createFileFallbackBackend(filePath = fileFallbackSecretPath()) {
+    return {
+        id: 'file-fallback',
+        label: `Local file (${filePath}, mode 0600)`,
+        async isAvailable() {
+            // Always available by design - it's the backend nothing else falls back to.
+            return true;
+        },
+        async save(secret) {
+            const dir = dirname(filePath);
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            await chmod(dir, 0o700).catch(() => {
+                // Best-effort: some platforms (notably Windows) don't honor POSIX mode bits via chmod at all.
+                // DPAPI, not file permissions, is the real protection there (windows-dpapi.ts) - this fallback
+                // is a last resort on Windows too, but only reached if even PowerShell is unavailable.
+            });
+            await writeFile(filePath, secret, { encoding: 'utf8', mode: 0o600 });
+            await chmod(filePath, 0o600).catch(() => { });
+        },
+        async load() {
+            try {
+                const content = await readFile(filePath, 'utf8');
+                return content.length > 0 ? content : null;
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return null;
+                throw new KeyBackendError('file-fallback', 'load', e.message);
+            }
+        },
+        async delete() {
+            await rm(filePath, { force: true });
+        },
+    };
+}
+/** Exposed for tests: true only if the file exists and (on POSIX) is exactly owner-rw. Windows mode
+ *  bits are not meaningful via fs.stat, so callers should skip the assertion there. */
+export async function isPrivateFileMode(filePath) {
+    const s = await stat(filePath);
+    return (s.mode & 0o777) === 0o600;
+}
+//# sourceMappingURL=file-fallback.js.map

package/dist/src/identity/backends/file-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-fallback.js","sourceRoot":"","sources":["../../../../src/identity/backends/file-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAmB,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,kGAAkG;AAClG,sGAAsG;AACtG,qDAAqD;AACrD,oGAAoG;AACpG,gGAAgG;AAChG,oGAAoG;AACpG,iGAAiG;AACjG,oGAAoG;AACpG,wCAAwC;AACxC,mGAAmG;AACnG,sGAAsG;AACtG,+EAA+E;AAC/E,MAAM,UAAU,yBAAyB,CAAC,WAAmB,sBAAsB,EAAE;IACnF,OAAO;QACL,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,eAAe,QAAQ,cAAc;QAE5C,KAAK,CAAC,WAAW;YACf,4EAA4E;YAC5E,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,MAAc;YACvB,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC9B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACnD,MAAM,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACjC,8FAA8F;gBAC9F,+FAA+F;gBAC/F,uFAAuF;YACzF,CAAC,CAAC,CAAC;YACH,MAAM,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACrE,MAAM,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC/C,CAAC;QAED,KAAK,CAAC,IAAI;YACR,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBACjD,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;YAC7C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,IAAI,CAAC;gBAChE,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,MAAM,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,KAAK,CAAC,MAAM;YACV,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;uFACuF;AACvF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,KAAK,CAAC;AACpC,CAAC"}

package/dist/src/identity/backends/libsecret.js

@@ -0,0 +1,57 @@
+import { nodeExec } from './exec.js';
+import { ACCOUNT_NAME, KeyBackendError, SERVICE_NAME } from './types.js';
+import { redactSecret } from '../redact.js';
+// Linux Secret Service (GNOME Keyring, KWallet's libsecret shim, ...) via the `secret-tool` CLI
+// (package `libsecret-tools` / `libsecret` depending on distro). Unlike macOS's `security`,
+// `secret-tool store` reads the secret from STDIN, so it never touches argv or `ps` output.
+//
+// `secret-tool` needs a running Secret Service (a D-Bus session + an unlocked keyring). Headless boxes,
+// bare containers and plenty of real dev machines don't have one - isAvailable() below treats that as
+// "unavailable" so store.ts falls through to the file fallback, rather than failing outright.
+const NOT_FOUND_CODES = new Set([1]); // secret-tool lookup exits 1 (empty stdout) when there's no match.
+export function createLibsecretBackend(exec = nodeExec) {
+    return {
+        id: 'libsecret',
+        label: 'Linux Secret Service (libsecret)',
+        async isAvailable() {
+            if (process.platform !== 'linux')
+                return false;
+            try {
+                // A lookup for a name that (almost certainly) doesn't exist. We only care that the process
+                // spawned and a Secret Service answered - "no such item" (exit 1, empty stdout) still proves
+                // the backend is usable; a spawn failure (ENOENT: no secret-tool installed) throws instead.
+                const r = await exec('secret-tool', ['lookup', 'service', '__botanary-mcp-availability-probe__']);
+                return r.code === 0 || NOT_FOUND_CODES.has(r.code);
+            }
+            catch {
+                return false;
+            }
+        },
+        async save(secret) {
+            const r = await exec('secret-tool', ['store', '--label=Botanary agent identity', 'service', SERVICE_NAME, 'account', ACCOUNT_NAME], { input: secret });
+            if (r.code !== 0) {
+                // secret-tool doesn't echo stdin back on error, but redact defensively anyway - this backend
+                // should never be the one place that skips it.
+                throw new KeyBackendError('libsecret', 'save', redactSecret(r.stderr || `exit ${r.code}`, secret));
+            }
+        },
+        async load() {
+            const r = await exec('secret-tool', ['lookup', 'service', SERVICE_NAME, 'account', ACCOUNT_NAME]);
+            if (r.code !== 0) {
+                if (NOT_FOUND_CODES.has(r.code) && !r.stderr.trim())
+                    return null;
+                throw new KeyBackendError('libsecret', 'load', r.stderr || `exit ${r.code}`);
+            }
+            const value = r.stdout.replace(/\n$/, '');
+            return value.length > 0 ? value : null;
+        },
+        async delete() {
+            const r = await exec('secret-tool', ['clear', 'service', SERVICE_NAME, 'account', ACCOUNT_NAME]);
+            // secret-tool clear exits 0 whether or not anything was there - nothing to tolerate specially.
+            if (r.code !== 0) {
+                throw new KeyBackendError('libsecret', 'delete', r.stderr || `exit ${r.code}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=libsecret.js.map

package/dist/src/identity/backends/libsecret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libsecret.js","sourceRoot":"","sources":["../../../../src/identity/backends/libsecret.ts"],"names":[],"mappings":"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"}

package/dist/src/identity/backends/macos-keychain.js

@@ -0,0 +1,63 @@
+import { nodeExec } from './exec.js';
+import { ACCOUNT_NAME, KeyBackendError, SERVICE_NAME } from './types.js';
+import { redactSecret } from '../redact.js';
+// macOS Keychain via the `security` CLI - no native addon (see README: this package is a plain `npm
+// install`, and a native keychain binding would need a compiled addon per Node ABI/arch, which is
+// exactly the kind of install friction that keeps an agent from getting connected).
+//
+// KNOWN LIMITATION, stated plainly rather than glossed over: `security add-generic-password` has no
+// way to read the password from stdin - it only accepts it via the `-w` argument. That means the
+// secret is briefly present in this process's argv, visible to anything else on the same machine that
+// can list processes (e.g. another local user running `ps`) for the moment the command runs. This is
+// a limitation of the macOS CLI, not of this package; the only way around it is a native Keychain
+// binding, which we deliberately don't ship. `find-generic-password`/`delete-generic-password` take no
+// secret argument, so they don't have this issue.
+const NOT_FOUND_RE = /could not be found|item.*could not be found|specified item could not be found/i;
+export function createMacosKeychainBackend(exec = nodeExec) {
+    return {
+        id: 'macos-keychain',
+        label: 'macOS Keychain',
+        async isAvailable() {
+            if (process.platform !== 'darwin')
+                return false;
+            try {
+                // `security help` always exits non-zero (it's not a real subcommand) - a successful SPAWN
+                // (no ENOENT) is all we're checking: does this binary exist and run at all.
+                await exec('security', ['help']);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async save(secret) {
+            // -U: update in place if an entry already exists, instead of erroring "already exists".
+            const r = await exec('security', [
+                'add-generic-password',
+                '-a', ACCOUNT_NAME,
+                '-s', SERVICE_NAME,
+                '-w', secret,
+                '-U',
+            ]);
+            if (r.code !== 0) {
+                throw new KeyBackendError('macos-keychain', 'save', redactSecret(r.stderr || `exit ${r.code}`, secret));
+            }
+        },
+        async load() {
+            const r = await exec('security', ['find-generic-password', '-a', ACCOUNT_NAME, '-s', SERVICE_NAME, '-w']);
+            if (r.code !== 0) {
+                if (NOT_FOUND_RE.test(r.stderr))
+                    return null;
+                throw new KeyBackendError('macos-keychain', 'load', r.stderr || `exit ${r.code}`);
+            }
+            return r.stdout.trim();
+        },
+        async delete() {
+            const r = await exec('security', ['delete-generic-password', '-a', ACCOUNT_NAME, '-s', SERVICE_NAME]);
+            if (r.code !== 0 && !NOT_FOUND_RE.test(r.stderr)) {
+                throw new KeyBackendError('macos-keychain', 'delete', r.stderr || `exit ${r.code}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=macos-keychain.js.map

package/dist/src/identity/backends/macos-keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"macos-keychain.js","sourceRoot":"","sources":["../../../../src/identity/backends/macos-keychain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,YAAY,EAAmB,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,oGAAoG;AACpG,kGAAkG;AAClG,oFAAoF;AACpF,EAAE;AACF,oGAAoG;AACpG,iGAAiG;AACjG,sGAAsG;AACtG,qGAAqG;AACrG,kGAAkG;AAClG,uGAAuG;AACvG,kDAAkD;AAClD,MAAM,YAAY,GAAG,gFAAgF,CAAC;AAEtG,MAAM,UAAU,0BAA0B,CAAC,OAAa,QAAQ;IAC9D,OAAO;QACL,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gBAAgB;QAEvB,KAAK,CAAC,WAAW;YACf,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAChD,IAAI,CAAC;gBACH,0FAA0F;gBAC1F,4EAA4E;gBAC5E,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;gBACjC,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,MAAc;YACvB,wFAAwF;YACxF,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE;gBAC/B,sBAAsB;gBACtB,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,MAAM;gBACZ,IAAI;aACL,CAAC,CAAC;YACH,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACjB,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;YAC1G,CAAC;QACH,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,uBAAuB,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1G,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACjB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;oBAAE,OAAO,IAAI,CAAC;gBAC7C,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC;QAED,KAAK,CAAC,MAAM;YACV,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,yBAAyB,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;YACtG,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}