@varnir/agent-server 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License (MIT)
+Copyright (c) 2026 Adam Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# @varnir/agent-server
+
+A self-hosted server that lets your own AI assistant (Claude, Gemini, ChatGPT,
+or anything else that speaks MCP or plain HTTP) trade and move funds on
+Varnir, bounded by an on-ledger spending policy attached to the key you give
+it. Varnir never holds the key - it lives in your environment, on your host,
+under your control.
+
+It exposes thirteen tools over MCP - seven reads (identity, balances, tokens,
+the order book, transaction history, a transfer's settlement receipt, the
+key's own spend policy) and six writes (post an order, fill an order, place a
+market order, cancel an order, send to an L1 address, transfer to another
+Varnir identity on L2). The same
+operations are also reachable over a plain REST API, off by default - see
+"The REST SecureAPI" below. Writes are refused outright unless the key this
+server signs with actually carries a spend policy; see "Before you start".
+
+## Before you start
+
+**Mint a policy-scoped agent key in the scanner's keys card, with the spend
+policy you want the assistant bound by, before you put anything in
+`VARNIR_PRIVATE_KEY`.**
+
+Do not hand this server your identity's owner key. It will not do what you
+expect: at boot, the server reads its own key back off the ledger and checks
+what it actually is before allowing any write. If that key turns out to be
+
+- the identity's **owner** key (no spend policy exists to bound it),
+- a key with **no spend policy** attached, or
+- a key with the **`readonly`** or **`offledger`** role (the money contracts
+  refuse these write access regardless of any policy attached to them),
+
+the server starts anyway, but **read-only**: every write tool and every write
+REST method is refused before it ever reaches the ledger, with a message
+explaining why. This is deliberate - the entire security argument for this
+server is that the on-ledger policy is the hard bound on what a connected
+assistant can spend, and that argument only holds when the key actually
+carries one. There is an escape hatch (`VARNIR_ALLOW_UNSCOPED_KEY=i-understand`
+in `.env.example`) for operators who understand they are removing that bound;
+do not reach for it to make an error message go away.
+
+Once you have the key, set `VARNIR_PRIVATE_KEY`, `VARNIR_IDENTITY`, and
+`VARNIR_NETWORK` (e.g. `testnet`).
+
+## Install and run
+
+Run these from the repo root:
+
+```bash
+pnpm install
+pnpm --filter @varnir/agent-server build
+```
+
+Then, with the environment set (see `.env.example`), still from the repo root:
+
+```bash
+node apps/agent-server/dist/index.js
+```
+
+The server logs which mode it started in (`writes`, `read-only`, or it exits
+with `refuse` if the key isn't even attached to `VARNIR_IDENTITY`) before it
+starts serving anything.
+
+## Deploying to your own cloud account
+
+You can also run this server in your own Google Cloud, Azure, or AWS
+account instead of on a local machine - it is still your account and your
+key either way; Varnir runs none of this infrastructure and never sees the
+key. See `deploy/README.md` for one-click deploy buttons, the ARM/
+CloudFormation templates, and `Dockerfile` for the container image (built
+from the published npm package, not this repo's source).
+
+## Connecting a client
+
+By default the server speaks MCP over stdio (`VARNIR_MCP_STDIO=on`), which is
+how a client that can launch a local process connects. Copy the block for
+your client and fill in the real values - `VARNIR_PRIVATE_KEY` and
+`VARNIR_IDENTITY` particularly should come from wherever you actually keep
+them, not pasted in plaintext if you can avoid it. Replace
+`/absolute/path/to/apps/agent-server/dist/index.js` with the real absolute
+path to the built entry point on your machine (the package's `bin` name is
+`varnir-agent-server` if you install it globally instead of pointing at
+`dist/index.js` directly).
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio varnir \
+  --env VARNIR_PRIVATE_KEY=... --env VARNIR_IDENTITY=... --env VARNIR_NETWORK=testnet \
+  -- node /absolute/path/to/apps/agent-server/dist/index.js
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "varnir": {
+      "command": "node",
+      "args": ["/absolute/path/to/apps/agent-server/dist/index.js"],
+      "env": {
+        "VARNIR_PRIVATE_KEY": "...",
+        "VARNIR_IDENTITY": "...",
+        "VARNIR_NETWORK": "testnet"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+This recipe substitutes `$VARNIR_PRIVATE_KEY` and `$VARNIR_IDENTITY` from the
+shell environment, so `export` both in the shell you launch `gemini` from
+first - an unset variable resolves to an empty string here rather than
+erroring, which just pushes the failure to server boot instead of catching it
+here.
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "varnir": {
+      "command": "node",
+      "args": ["/absolute/path/to/apps/agent-server/dist/index.js"],
+      "env": {
+        "VARNIR_PRIVATE_KEY": "$VARNIR_PRIVATE_KEY",
+        "VARNIR_IDENTITY": "$VARNIR_IDENTITY",
+        "VARNIR_NETWORK": "testnet"
+      },
+      "timeout": 30000
+    }
+  }
+}
+```
+
+### ChatGPT (Streamable HTTP, over a tunnel)
+
+ChatGPT cannot launch a local process - it needs a publicly reachable HTTPS
+URL, so this recipe uses the MCP HTTP transport (`POST /mcp`) behind a tunnel
+instead of stdio. `VARNIR_MCP_HTTP_TOKEN` (at least 32 characters) is now
+**mandatory whenever `VARNIR_MCP_HTTP=on`, even on loopback** - without it,
+any other local user or process on the same host could reach the full write
+set with no authentication at all. A remote bind additionally requires
+`VARNIR_MCP_HTTP_ALLOW_REMOTE=i-understand` - `cloudflared` puts you on a
+public hostname even though the process itself still listens on loopback, so
+in practice you need the token either way. Without the token set, the server
+refuses to start with `VARNIR_MCP_HTTP=on` at all.
+
+Run this from the repo root, same as "Install and run" above:
+
+```bash
+VARNIR_PRIVATE_KEY=... VARNIR_IDENTITY=... VARNIR_NETWORK=testnet \
+VARNIR_MCP_HTTP=on VARNIR_MCP_HTTP_TOKEN=<a-random-string-32-chars-or-longer> \
+VARNIR_MCP_HTTP_ALLOW_REMOTE=i-understand \
+node apps/agent-server/dist/index.js
+```
+
+Expose it:
+
+```bash
+cloudflared tunnel --url http://localhost:8787
+```
+
+Then in ChatGPT: Settings -> Connectors -> Advanced -> Developer mode -> Add
+custom connector, URL `<tunnel-url>/mcp`, bearer token
+`<the token you set above>`.
+
+## The REST SecureAPI
+
+The SDK's methods are also reachable over plain HTTP, for integrating
+software that can only call HTTP endpoints rather than speak MCP. It is off
+by default (`VARNIR_HTTP_API=off`) and every gate below is enforced in
+`src/config.ts` before the process will even start with it on.
+
+| Variable | Default | Required | Notes |
+|---|---|---|---|
+| `VARNIR_HTTP_API` | off | No | Enable with `on`/`true`/`1` |
+| `VARNIR_HTTP_API_TOKEN` | - | Yes, when enabled | No default, minimum 32 characters |
+| `VARNIR_HTTP_API_HOST` | `127.0.0.1` | No | Loopback by default |
+| `VARNIR_HTTP_API_PORT` | 8788 | No | Integer [1, 65535] |
+| `VARNIR_HTTP_API_WRITES` | off | No | Reads only until set `on` |
+| `VARNIR_HTTP_API_ALLOW_REMOTE` | - | Conditional | Exactly `i-understand`; required for a non-loopback host |
+
+**Turning this on with writes enabled and a non-loopback bind puts a
+money-moving endpoint on the network.** Anyone who can reach that host and
+port and holds the bearer token can move funds within whatever the signing
+key's on-ledger policy allows - the policy still bounds them, but the network
+exposure itself is real and irreversible the moment someone finds the port.
+Keep it on loopback with writes off unless you have a specific, considered
+reason to do otherwise, and prefer a tunnel with its own auth in front of it
+over binding a public interface directly.
+
+Every write method is also refused if the server's own key came up
+read-only at boot (see "Before you start"), on top of the `VARNIR_HTTP_API_WRITES`
+gate - two independent checks, not one.
+
+One method needs calling out specifically: **`getWallet` is classified as a
+write**, even though the name and its use elsewhere as a read look
+innocuous. When this identity has no wallet yet on a given chain, `getWallet`
+falls through to claiming a pregenerated L1 wallet from the pool and signing
+a `Varnir.AssignOwner` transaction to establish ownership - a real
+ledger-mutating write, on its first call for that chain. `send` calls
+`getWallet` internally for the same reason. Both are refused with
+`VARNIR_HTTP_API_WRITES=off` or in read-only mode, exactly like any other
+write.
+
+Example, once you have `VARNIR_HTTP_API=on` and a token set:
+
+```bash
+curl -s -X POST http://127.0.0.1:8788/v1/getBalances \
+  -H "Authorization: Bearer $VARNIR_HTTP_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+`GET /v1/methods` (also bearer-authenticated) lists every method the server
+will accept and whether it is a write. `GET /v1/health` is unauthenticated and
+carries no identity or key data - just whether the process is up and whether
+it is running read-only.
+
+## Security
+
+The signing key lives in your environment - your host is the trust boundary,
+not Varnir. Whoever can read that environment (or the process's memory) can
+sign whatever the key's on-ledger policy allows. The on-ledger spending
+policy - per-transaction ceiling, rolling-period cap, recipient allowlist,
+co-sign threshold - is the real bound on a connected assistant, not this
+server; this server is defence in depth around that bound (see `src/guard.ts`
+for exactly what it checks and why). To revoke access, remove the key from
+the identity in the scanner - that is the authoritative shutoff, independent
+of whether this process is still running.
+
+Reads are ungated by design: `get_balances`, `list_transactions`,
+`get_identity`, and the equivalent REST methods, do not check the guard mode
+and are always answerable once the server is running at all. Anything that
+can talk to this server - over stdio, MCP HTTP, or the REST API - can see
+your balances and transaction history, whether or not it can move anything.
+Do not treat "read-only mode" as "safe to expose"; treat it as "cannot sign."
+
+## What it will not do
+
+- **No key management on any surface.** There is no tool and no REST method
+  to add a key, remove a key, change an approval threshold, or register or
+  revoke an API key - `addKey`, `removeKey`, `setApprovalThreshold`,
+  `registerApiKey` and `revokeApiKey` are absent from `REST_METHODS` on
+  purpose and must stay absent.
+- **One deliberate, narrower exception:** a `verifier` or `dual` key (both
+  stake 80) that has NOT itself raised a transfer proposal can still hit the
+  ledger's co-sign band on that proposal - the contract treats that as a
+  genuine co-sign confirmation and releases it without re-checking that
+  key's own spend policy, because the policy was already checked when the
+  proposal was raised. `confirmTransfer` and `listPendingApprovals` would let
+  a connected assistant enumerate and release someone else's held proposal at
+  the proposal's amount, ignoring its own per-tx ceiling, period cap and
+  allowlist - the one way this server's design lets a key widen its own
+  effective authority. Both are absent from `REST_METHODS` for exactly this
+  reason and must stay absent; neither has an MCP tool, so nothing regresses.
+  Aside from this, nothing reachable from a connected assistant can widen
+  that assistant's own authority.
+- **No remaining-allowance figure.** `get_spend_policy` reports the
+  *configured limits* on this key - per-transaction ceiling, rolling-period
+  cap, allowlist, co-sign threshold - not how much of the period's cap is
+  left. Remaining allowance against a rolling-period cap is not readable
+  through the SDK yet.
+- **`get_transfer` cannot tell "still settling" apart from "held for a
+  co-sign that will never settle on its own"**, given only a umid. That
+  distinction genuinely exists only in `send`'s/`transfer_on_ledger`'s own
+  return at submission time (`awaiting_cosign` plus the `proposal`) - looking
+  the umid up afterwards, which is all `get_transfer` does, cannot recover it.
+  Telling them apart from a umid alone would need reading this identity's
+  pending-approvals list, which is deliberately not wired into any MCP tool
+  (see the point above) - so `get_transfer` says so plainly rather than
+  guessing, and a `not_settled` result should be read as "no receipt yet,"
+  not "still settling."
+- **No writes behind an owner, policy-less, `readonly` or `offledger` key.**
+  The server starts read-only in all four cases rather than silently running
+  with unbounded or contract-refused authority; see "Before you start" for
+  what each one means and how to fix it.

package/dist/bearer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Timing-safe bearer token comparison to prevent timing-based token guessing attacks.
+ */
+export declare function tokenMatches(presented: string, expected: string): boolean;
+//# sourceMappingURL=bearer.d.ts.map

package/dist/bearer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKzE"}

package/dist/bearer.js

@@ -0,0 +1,12 @@
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Timing-safe bearer token comparison to prevent timing-based token guessing attacks.
+ */
+export function tokenMatches(presented, expected) {
+    const a = Buffer.from(presented);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+//# sourceMappingURL=bearer.js.map

package/dist/bearer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAE5C;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,QAAgB;IAC9D,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import { redact } from './log.js';
+export { redact };
+/** A configuration problem that must stop the process before it serves anything. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export interface ServerConfig {
+    privateKeyHex: string;
+    identity: string;
+    network: string;
+    /** True only for the exact phrase `i-understand`. See the guard in guard.ts. */
+    allowUnscopedKey: boolean;
+    mcpStdio: boolean;
+    mcpHttp: {
+        enabled: false;
+    } | {
+        enabled: true;
+        port: number;
+        host: string;
+        token: string;
+        remote: boolean;
+    };
+    restApi: {
+        enabled: false;
+    } | {
+        enabled: true;
+        host: string;
+        port: number;
+        token: string;
+        writes: boolean;
+        remote: boolean;
+    };
+}
+type Env = Record<string, string | undefined>;
+export declare function loadConfig(env: Env): ServerConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAC,MAAM,EAAC,CAAC;AAEhB,oFAAoF;AACpF,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAK5B;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE;QAAC,OAAO,EAAE,KAAK,CAAA;KAAC,GAAG;QAAC,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC;IACxG,OAAO,EACH;QAAC,OAAO,EAAE,KAAK,CAAA;KAAC,GAChB;QAAC,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC;CAClG;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AA8D9C,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,YAAY,CAkGjD"}

package/dist/config.js

@@ -0,0 +1,151 @@
+import { keyTypeOf } from '@varnir/chain-client';
+import { redact } from './log.js';
+export { redact };
+/** A configuration problem that must stop the process before it serves anything. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'ConfigError';
+    }
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+const MIN_TOKEN_LEN = 32;
+function required(env, name) {
+    const v = env[name]?.trim();
+    if (!v) {
+        throw new ConfigError(`${name} is required. Set it in the environment (a secret manager should supply it) and start again.`);
+    }
+    return v;
+}
+/** `on`/`true`/`1` are on; anything else (including unset) is off. */
+function flag(env, name, fallback = false) {
+    const v = env[name]?.trim().toLowerCase();
+    if (v === undefined || v === '')
+        return fallback;
+    return v === 'on' || v === 'true' || v === '1';
+}
+function port(env, name, fallback) {
+    const v = env[name]?.trim();
+    if (!v)
+        return fallback;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new ConfigError(`${name} must be an integer port in [1, 65535]; got ${JSON.stringify(v)}.`);
+    }
+    return n;
+}
+/**
+ * Precedence: VARNIR_MCP_HTTP_PORT -> PORT -> 8787.
+ *
+ * Google Cloud Run and Azure Container Apps both inject a `PORT` environment
+ * variable at container start and require the process to listen on exactly
+ * that port - a container bound elsewhere is health-checked as down and
+ * killed, regardless of what it's actually doing. This server's own knob is
+ * VARNIR_MCP_HTTP_PORT (default 8787), which predates any cloud deployment
+ * target and must keep working unchanged for stdio/local/self-hosted users
+ * who set it deliberately. Falling back to PORT only when
+ * VARNIR_MCP_HTTP_PORT is unset lets the same image boot correctly on either
+ * platform without extra configuration, while an operator who explicitly
+ * sets VARNIR_MCP_HTTP_PORT (e.g. to run two instances behind one host)
+ * still gets exactly that value.
+ *
+ * The REST API's port (VARNIR_HTTP_API_PORT, default 8788) deliberately does
+ * NOT get this same PORT fallback: a container only has one port that is
+ * "the platform's" port (the one Cloud Run/ACA route traffic to and health
+ * check), and the MCP HTTP server is that surface for a cloud deployment -
+ * the REST API is off by default and, when enabled at all, is a secondary,
+ * self-hosted-oriented surface that isn't part of the one-click cloud path.
+ * Wiring PORT to REST's port too would silently break MCP whenever only one
+ * of the two servers is meant to claim the platform's assigned port.
+ */
+function mcpHttpPort(env) {
+    if (env.VARNIR_MCP_HTTP_PORT?.trim())
+        return port(env, 'VARNIR_MCP_HTTP_PORT', 8787);
+    if (env.PORT?.trim())
+        return port(env, 'PORT', 8787);
+    return 8787;
+}
+export function loadConfig(env) {
+    const privateKeyHex = required(env, 'VARNIR_PRIVATE_KEY');
+    // Validate key format based on key type
+    const keyType = keyTypeOf(privateKeyHex);
+    if (keyType === 'secp256k1') {
+        // secp256k1: must be hex
+        if (!/^(0x)?[0-9a-fA-F]+$/.test(privateKeyHex)) {
+            // Deliberately does not echo the value.
+            throw new ConfigError('VARNIR_PRIVATE_KEY must be a hex string.');
+        }
+    }
+    else {
+        // Post-quantum: must be <type>:<secretKey>:<publicKey>
+        const parts = privateKeyHex.split(':');
+        // Two-part format is a public key (<type>:<publicKey>), not a private
+        // key - but only when that second part is actually present. `<type>:`
+        // alone (parts[1] === '') isn't a public key either; it's simply a
+        // malformed private key, and must fall through to the generic format
+        // error below rather than be misdiagnosed as "here is a public key."
+        if (parts.length === 2 && parts[1]) {
+            throw new ConfigError(`VARNIR_PRIVATE_KEY appears to be a public key (${keyType}). A private key is required.`);
+        }
+        if (parts.length !== 3 || !parts[1] || !parts[2]) {
+            // Deliberately does not echo the value.
+            throw new ConfigError(`VARNIR_PRIVATE_KEY must be a valid ${keyType} private key in the format <type>:<secretKey>:<publicKey>.`);
+        }
+    }
+    const identity = required(env, 'VARNIR_IDENTITY');
+    const network = required(env, 'VARNIR_NETWORK');
+    const allowUnscopedKey = env.VARNIR_ALLOW_UNSCOPED_KEY?.trim() === 'i-understand';
+    const mcpStdio = flag(env, 'VARNIR_MCP_STDIO', true);
+    let mcpHttp = { enabled: false };
+    if (flag(env, 'VARNIR_MCP_HTTP')) {
+        const host = env.VARNIR_MCP_HTTP_HOST?.trim() || '127.0.0.1';
+        const remote = !LOOPBACK.has(host);
+        if (remote && env.VARNIR_MCP_HTTP_ALLOW_REMOTE?.trim() !== 'i-understand') {
+            throw new ConfigError(`VARNIR_MCP_HTTP_HOST is ${host}, which is not loopback. Binding the MCP HTTP server to a reachable address exposes a money-moving endpoint to the network. Set VARNIR_MCP_HTTP_ALLOW_REMOTE=i-understand if that is genuinely what you want.`);
+        }
+        // I4: mandatory even on loopback. VARNIR_MCP_HTTP=on alone used to put the
+        // full write set on 127.0.0.1 with NO authentication - any other local
+        // user or process on a shared host could move funds. REST already
+        // requires a token unconditionally; MCP HTTP now matches it.
+        const token = env.VARNIR_MCP_HTTP_TOKEN?.trim();
+        if (!token) {
+            throw new ConfigError('VARNIR_MCP_HTTP is on but VARNIR_MCP_HTTP_TOKEN is not set. The MCP HTTP server moves money; it will not start without a token, even on loopback - anything else on the host could otherwise reach it unauthenticated.');
+        }
+        if (token.length < MIN_TOKEN_LEN) {
+            throw new ConfigError(`VARNIR_MCP_HTTP_TOKEN must be at least ${MIN_TOKEN_LEN} characters. A weak token on a money-moving endpoint is a misconfiguration, not a preference.`);
+        }
+        mcpHttp = {
+            enabled: true,
+            port: mcpHttpPort(env),
+            host,
+            token,
+            remote,
+        };
+    }
+    let restApi = { enabled: false };
+    if (flag(env, 'VARNIR_HTTP_API')) {
+        const token = env.VARNIR_HTTP_API_TOKEN?.trim();
+        if (!token) {
+            throw new ConfigError('VARNIR_HTTP_API is on but VARNIR_HTTP_API_TOKEN is not set. The REST API moves money; it will not start without a token. There is no default and none is generated for you.');
+        }
+        if (token.length < MIN_TOKEN_LEN) {
+            throw new ConfigError(`VARNIR_HTTP_API_TOKEN must be at least ${MIN_TOKEN_LEN} characters. A weak token on a money-moving endpoint is a misconfiguration, not a preference.`);
+        }
+        const host = env.VARNIR_HTTP_API_HOST?.trim() || '127.0.0.1';
+        const remote = !LOOPBACK.has(host);
+        if (remote && env.VARNIR_HTTP_API_ALLOW_REMOTE?.trim() !== 'i-understand') {
+            throw new ConfigError(`VARNIR_HTTP_API_HOST is ${host}, which is not loopback. Binding the REST API to a reachable address exposes a money-moving endpoint to the network. Set VARNIR_HTTP_API_ALLOW_REMOTE=i-understand if that is genuinely what you want.`);
+        }
+        restApi = {
+            enabled: true,
+            host,
+            port: port(env, 'VARNIR_HTTP_API_PORT', 8788),
+            token,
+            writes: flag(env, 'VARNIR_HTTP_API_WRITES'),
+            remote,
+        };
+    }
+    return { privateKeyHex, identity, network, allowUnscopedKey, mcpStdio, mcpHttp, restApi };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/guard.d.ts

@@ -0,0 +1,28 @@
+import type { VarnirLedgerKey } from '@varnir/chain-client';
+/**
+ * The whole security argument for this server is that the on-ledger spending
+ * policy is the hard bound on what a connected assistant can do. That argument
+ * holds ONLY if the key in VARNIR_PRIVATE_KEY is a policy-scoped agent key.
+ *
+ * Nothing stops an operator pasting their owner key into the environment, and
+ * the result would appear to work perfectly while having unbounded authority
+ * over the identity. So at boot we read our own key off the ledger and check
+ * what it actually is.
+ *
+ * This is defence in depth, not the bound itself - the contracts remain the
+ * real enforcement. Its value is catching the single most likely operator
+ * mistake before it can cost money.
+ */
+export type GuardMode = 'writes' | 'read-only' | 'refuse';
+export interface KeyClassification {
+    mode: GuardMode;
+    reason: string;
+}
+/**
+ * `onWirePublicKey` MUST be the UNTAGGED on-wire value - i.e.
+ * `onWirePublicKey(privateKeyHex).publicKey`, NOT `publicKeyForPrivateKey()`,
+ * which tags PQ keys as `falcon-512:<pk>` and would never match what
+ * `listLedgerKeys()` reports. See key-match.ts.
+ */
+export declare function classifyKey(keys: VarnirLedgerKey[], onWirePublicKey: string, allowUnscoped: boolean): KeyClassification;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,sBAAsB,CAAC;AAG1D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,eAAe,EAAE,EACvB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,OAAO,GACrB,iBAAiB,CA4DnB"}

package/dist/guard.js

@@ -0,0 +1,56 @@
+import { samePublicKey } from './key-match.js';
+/**
+ * `onWirePublicKey` MUST be the UNTAGGED on-wire value - i.e.
+ * `onWirePublicKey(privateKeyHex).publicKey`, NOT `publicKeyForPrivateKey()`,
+ * which tags PQ keys as `falcon-512:<pk>` and would never match what
+ * `listLedgerKeys()` reports. See key-match.ts.
+ */
+export function classifyKey(keys, onWirePublicKey, allowUnscoped) {
+    const mine = keys.find(k => samePublicKey(k.publicKey, onWirePublicKey));
+    if (!mine) {
+        // Not a degradation: this key could not sign anything on this identity at
+        // all, so every write would fail later anyway. Fail loudly and early.
+        return {
+            mode: 'refuse',
+            reason: 'This key is not attached to VARNIR_IDENTITY on the ledger. Check that VARNIR_PRIVATE_KEY and VARNIR_IDENTITY belong together, and that the key has not been revoked.',
+        };
+    }
+    if (mine.isOwner || mine.role === 'owner') {
+        if (allowUnscoped) {
+            return { mode: 'writes', reason: 'Running with the identity OWNER key because VARNIR_ALLOW_UNSCOPED_KEY is set.' };
+        }
+        return {
+            mode: 'read-only',
+            reason: 'This is the identity OWNER key, which carries no spending policy - an assistant holding it would have unbounded authority over your funds. Starting read-only. Mint a policy-scoped agent key in the scanner and use that instead, or set VARNIR_ALLOW_UNSCOPED_KEY=i-understand.',
+        };
+    }
+    if (mine.role === 'readonly') {
+        return {
+            mode: 'read-only',
+            reason: 'This key is a read-only key by ledger design - it carries a 9000 stake that gates read-only access, and the money contracts refuse it write access regardless of any spend policy. A spend policy on this key cannot grant write ability. Mint a proposer or dual key carrying a spend policy in the scanner instead.',
+        };
+    }
+    if (mine.role === 'offledger') {
+        return {
+            mode: 'read-only',
+            reason: 'This is an off-ledger key - the money contracts refuse it any fund movement regardless of any spend policy. A spend policy on this key is inert and will not grant write ability. Mint a proposer or dual key carrying a spend policy in the scanner instead.',
+        };
+    }
+    if (mine.role === 'verifier') {
+        return {
+            mode: 'read-only',
+            reason: 'This is a verifier key - the money contracts refuse it outright ("A verifier key cannot raise transfers") regardless of any spend policy. A spend policy on this key cannot grant write ability. Mint a proposer or dual key carrying a spend policy in the scanner instead.',
+        };
+    }
+    if (!mine.policy) {
+        if (allowUnscoped) {
+            return { mode: 'writes', reason: 'Running with a key that carries no spend policy because VARNIR_ALLOW_UNSCOPED_KEY is set.' };
+        }
+        return {
+            mode: 'read-only',
+            reason: 'This key carries no on-ledger spend policy, so nothing would bound what a connected assistant could spend. Starting read-only. Add a spend policy to the key in the scanner, or set VARNIR_ALLOW_UNSCOPED_KEY=i-understand.',
+        };
+    }
+    return { mode: 'writes', reason: 'Scoped agent key with an on-ledger spend policy.' };
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,aAAa,EAAC,MAAM,gBAAgB,CAAC;AAuB7C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,IAAuB,EACvB,eAAuB,EACvB,aAAsB;IAEtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC;IAEzE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,0EAA0E;QAC1E,sEAAsE;QACtE,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,MAAM,EACJ,sKAAsK;SACzK,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1C,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,EAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,+EAA+E,EAAC,CAAC;QACnH,CAAC;QACD,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EACJ,mRAAmR;SACtR,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EACJ,uTAAuT;SAC1T,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EACJ,+PAA+P;SAClQ,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EACJ,8QAA8Q;SACjR,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACjB,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,EAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,2FAA2F,EAAC,CAAC;QAC/H,CAAC;QACD,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EACJ,6NAA6N;SAChO,CAAC;IACJ,CAAC;IAED,OAAO,EAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,kDAAkD,EAAC,CAAC;AACtF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}