@veertu/anka-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veertu Inc.
+
+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,324 @@
+# anka-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Anka](https://veertu.com/) macOS virtualization. It runs as a **streamable HTTP server** with bearer-token auth and exposes two curated, purpose-built tool sets that auto-enable based on configuration:
+
+- **Controller backend** - talks to the [Anka Build Cloud Controller](https://docs.veertu.com/anka/anka-build-cloud/working-with-controller-and-api/) REST API to request a VM from a fleet and hand back SSH connection details. No `anka` CLI is used.
+- **Local backend** - drives the local `anka` CLI with a small, safe set of lifecycle commands, guarded by a running-VM limit.
+
+There is intentionally no generic "run any anka command" tool.
+
+## Backends and when they enable
+
+| Backend    | Enabled when                                              | Tools |
+| ---------- | --------------------------------------------------------- | ----- |
+| Controller | `ANKA_CONTROLLER_URL` is set                              | `controller_list_templates`, `controller_request_vm`, `controller_get_vm`, `controller_terminate_vm` |
+| Local      | `ANKA_LOCAL=on`, or `auto` when no controller is configured (detects the `anka` CLI) | `local_list_templates`, `local_start_vm`, `local_show_vm`, `local_ssh_access`, `local_delete_vm` |
+
+When `ANKA_CONTROLLER_URL` is set, the local backend defaults to **off** so only controller tools are exposed. Set `ANKA_LOCAL=on` or `ANKA_LOCAL=auto` to enable both. The server refuses to start if neither backend is enabled.
+
+## Requirements
+
+- Node.js >= 18
+- For the local backend: the `anka` CLI installed and on `PATH` (or point `ANKA_BIN` at it)
+- For the controller backend: network access to an Anka Build Cloud Controller
+
+## Install and run
+
+### From npm
+
+Requires Node.js >= 18.
+
+```bash
+# run without a global install
+npx @veertu/anka-mcp
+
+# or install globally
+npm install -g @veertu/anka-mcp
+anka-mcp
+```
+
+Set auth and backend env vars before starting (see [Configuration](#configuration)). Example:
+
+```bash
+export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
+echo "MCP_AUTH_TOKEN=$MCP_AUTH_TOKEN"
+anka-mcp
+```
+
+### From source (contributors)
+
+```bash
+npm install
+npm run build
+export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
+echo "MCP_AUTH_TOKEN=$MCP_AUTH_TOKEN"
+npm start
+```
+
+For **multi-client** deployments, use the admin API instead of a single shared token:
+
+```bash
+export MCP_ADMIN_TOKEN="$(openssl rand -hex 32)"
+export ANKA_CONTROLLER_URL="http://your-controller:8090"
+npm start
+
+# Create a per-client MCP token (plaintext shown once):
+curl -s -X POST "http://localhost:9111/admin/tokens" \
+  -H "Authorization: Bearer $MCP_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"label":"team-a"}'
+```
+
+The endpoint is served at `http://<host>:<port>/mcp`. For local dev without auth (never expose beyond localhost):
+
+```bash
+MCP_ALLOW_NO_AUTH=1 npm run dev
+```
+
+## Use-case 1: Controller fleet
+
+The agent asks the MCP server for a VM; the server generates a temporary SSH key, passes it to the VM via the controller `startup_script` (with `startup_script_condition: 1` so the script runs immediately, before networking), waits until the controller reports the instance started and an SSH auth probe with that key succeeds over the forwarded port, then returns the host IP, forwarded SSH port, private key path, and a ready-to-use `ssh` command. The agent then SSHes in itself.
+
+```mermaid
+flowchart LR
+  agent["AI agent"] -->|"controller_request_vm {vmid}"| mcp["anka-mcp"]
+  mcp -->|"POST /api/v1/vm"| ctl["Controller API"]
+  mcp -->|"poll GET /api/v1/vm?id="| ctl
+  mcp -->|"{host, port, username, private_key_path, command}"| agent
+  agent -->|"ssh -p port username@host"| vm["macOS VM"]
+```
+
+The VM template must expose port forwarding for the SSH guest port (default `22`, e.g. a `port-forward-22` tag), or pass `addSshPortForward: true` to `controller_request_vm` to add a rule at start time.
+
+## Use-case 2: Local laptop
+
+The agent manages VMs on the developer's own machine through a limited command set: list templates, start (which always clones the chosen template into a fresh VM so the original is never touched), show, prepare SSH access, delete. A running-VM limit (default 2) prevents exceeding the local Anka concurrency limit. The delete tool always requires a specific VM name and can never delete all VMs.
+
+For SSH, `local_ssh_access` generates a throwaway ed25519 keypair on the host, copies the public key into the running VM with `anka cp`, installs it into the VM's `~/.ssh/authorized_keys` (via `anka run`), and returns the private key path plus a ready-to-use `ssh` command. The agent (on the same machine) then connects directly to the VM's shared-network IP. The VM template must have Remote Login (sshd) enabled.
+
+## Configuration
+
+All configuration is via environment variables.
+
+### HTTP transport + auth
+
+| Variable              | Default   | Description                                                            |
+| --------------------- | --------- | --------------------------------------------------------------------- |
+| `MCP_HTTP_PORT`       | `9111`    | Port the HTTP server listens on.                                      |
+| `MCP_HTTP_HOST`       | `127.0.0.1` | Interface to bind to. Defaults to localhost; set `0.0.0.0` for remote access behind TLS. |
+| `MCP_AUTH_TOKEN`      | (none)    | Legacy single bearer token for all MCP clients. Still supported.      |
+| `MCP_ADMIN_TOKEN`     | (none)    | Admin bearer token for `/admin/*` routes. Enables token management.   |
+| `MCP_DB_PATH`         | `./anka-mcp.db` | SQLite database for client tokens and instance ownership.       |
+| `MCP_REVOKE_CLEANUP`  | `on`      | When a token is revoked, terminate its controller VMs (set `off` to skip). |
+| `MCP_ALLOW_NO_AUTH`   | `false`   | Set to `1` to run unauthenticated (local dev only).                   |
+| `MCP_ALLOWED_ORIGINS` | (none)    | Comma-separated Origin allow-list for DNS-rebinding protection.       |
+| `MCP_LOG`             | `on`      | Request logging to stderr. Set to `off` (or `0`/`false`/`no`) to disable. |
+| `MCP_AUDIT_LOG`       | (none)    | Optional append-only audit log file (duplicates stderr log lines).    |
+| `MCP_MAX_BODY_BYTES`  | `1048576` | Max JSON request body size (1 MiB).                                   |
+| `MCP_RATE_LIMIT_RPM`  | `120`     | Max requests per client IP per minute (`0` = disabled).               |
+| `MCP_SESSION_IDLE_MS` | `3600000` | Idle MCP session eviction threshold (1 hour).                         |
+| `MCP_MAX_SESSIONS`    | `50`      | Max concurrent MCP sessions.                                          |
+| `MCP_MAX_RESPONSE_CHARS` | `32768` | Max serialized tool response size (32 KiB).                         |
+
+When logging is enabled, each MCP request is written to stderr with the client source (IP and user-agent), JSON-RPC method, tool name and arguments, tool response (with passwords and private keys redacted), and any underlying `anka` or controller API calls. Example:
+
+```
+anka-mcp: 2026-06-22T16:52:15.021Z [127.0.0.1 (Cursor/1.x)] mcp tools/call {"tool":"local_list_templates","args":{}}
+anka-mcp: 2026-06-22T16:52:15.059Z [127.0.0.1 (Cursor/1.x)] anka anka -j list -> ok
+anka-mcp: 2026-06-22T16:52:15.059Z [127.0.0.1 (Cursor/1.x)] tool local_list_templates args={} -> {"vms":[...]}
+```
+
+### Controller backend
+
+| Variable                          | Default  | Description                                                        |
+| --------------------------------- | -------- | ------------------------------------------------------------------ |
+| `ANKA_CONTROLLER_URL`             | (none)   | Base URL, e.g. `http://anka.controller:8090`. Enables the backend. |
+| `ANKA_CONTROLLER_AUTH`            | (none)   | Raw `Authorization` header value (root token / UAK / Basic).       |
+| `ANKA_CONTROLLER_TLS_INSECURE`    | `false`  | Set to `1` to skip TLS certificate verification.                   |
+| `ANKA_CONTROLLER_POLL_INTERVAL_MS`| `3000`   | Interval between instance-status polls.                            |
+| `ANKA_CONTROLLER_START_TIMEOUT_MS`| `180000` | Max time to wait for a VM to become SSH-ready.                     |
+| `ANKA_CONTROLLER_SSH_PROBE`       | `on`     | When enabled, `controller_request_vm` runs an SSH auth probe with the generated key before returning (set to `0` to skip). |
+
+### Local backend
+
+| Variable             | Default | Description                                                  |
+| -------------------- | ------- | ------------------------------------------------------------ |
+| `ANKA_LOCAL`         | `auto`* | `auto` (detect the binary), `on`, or `off`. \*Defaults to `off` when `ANKA_CONTROLLER_URL` is set. |
+| `ANKA_BIN`           | `anka`  | Path to (or name of) the anka binary.                        |
+| `ANKA_TIMEOUT_MS`    | `300000`| Max time a single anka invocation may run.                   |
+| `ANKA_LOCAL_MAX_VMS` | `2`     | Max running VMs allowed before start is refused.            |
+| `ANKA_LOCAL_POLL_INTERVAL_MS` | `2000` | Interval between status polls while waiting for a VM's IP. |
+| `ANKA_LOCAL_IP_TIMEOUT_MS` | `120000` | Max time `local_start_vm`/`local_ssh_access` wait for an IP. |
+
+### SSH connection details (returned to the agent)
+
+| Variable              | Default | Description                                          |
+| --------------------- | ------- | ---------------------------------------------------- |
+| `ANKA_VM_SSH_USER`    | `anka`  | Username returned for SSHing into a VM.              |
+| `ANKA_VM_SSH_PASSWORD`| `admin` | Password returned for SSHing into a VM.              |
+| `ANKA_VM_SSH_GUEST_PORT` | `22` | Guest port that maps to SSH (matched in port forwarding). |
+
+Returned `ssh` commands include `-o IdentitiesOnly=yes` so a local ssh-agent does not offer other keys and cause auth failures. If you build your own command, use that flag or prefix with `SSH_AUTH_SOCK=` to disable the agent.
+
+For production, terminate TLS in front of this server so the bearer token and any returned credentials are not sent in cleartext.
+
+See [SECURITY.md](SECURITY.md) for the full operator security guide.
+
+### Remote deployment
+
+By default the server binds to **localhost only** (`127.0.0.1`). To expose it on a network:
+
+1. Set `MCP_HTTP_HOST=0.0.0.0` (or a specific interface).
+2. Terminate **TLS** in a reverse proxy in front of anka-mcp.
+3. Firewall to trusted clients only.
+4. Issue **per-client tokens** via the admin API — avoid sharing `MCP_AUTH_TOKEN`.
+5. Never use `MCP_ALLOW_NO_AUTH` on non-localhost hosts.
+
+The server prints a warning at startup when bound to a non-loopback address.
+
+### Multi-client tokens and VM isolation
+
+When `MCP_ADMIN_TOKEN` is set, the server exposes an admin API to create and revoke per-client MCP bearer tokens. Tokens are stored in SQLite (`MCP_DB_PATH`); only hashed secrets are persisted.
+
+| Method   | Path                 | Auth                    | Purpose                          |
+| -------- | -------------------- | ----------------------- | -------------------------------- |
+| `POST`   | `/admin/tokens`      | `Bearer MCP_ADMIN_TOKEN` | Create a client token            |
+| `GET`    | `/admin/tokens`      | admin bearer            | List tokens (no secrets)         |
+| `DELETE` | `/admin/tokens/:id`  | admin bearer            | Revoke token and clean up VMs    |
+
+Admin and MCP tokens are separate: the admin token never works on `/mcp`, and client tokens never work on `/admin/*`.
+
+**Controller VM isolation:** each client token can only `controller_get_vm` / `controller_terminate_vm` instances it created via `controller_request_vm`. Revoking a token blocks MCP access immediately and, by default (`MCP_REVOKE_CLEANUP=on`), best-effort terminates all controller instances owned by that token. The revoke response includes `cleanup.terminated` and `cleanup.failed` arrays.
+
+The legacy `MCP_AUTH_TOKEN` still works as a single shared client identity (`legacy`); all controller VMs created under it share one ownership bucket.
+
+Back up `anka-mcp.db` for disaster recovery; it is created automatically on first start.
+
+## Tools
+
+### Controller
+
+- `controller_list_templates` - list registry templates (`id`, `name`, `arch`) to find a `vmid`.
+- `controller_request_vm` `{ vmid, tag?, name?, externalId?, addSshPortForward? }` - start one VM, install a temporary SSH key via the controller `startup_script`, wait until SSH auth succeeds over the forwarded port, return `{ instance_id, ssh: { host, port, username, private_key_path, command } }`. The controller `external_id` is auto-filled with MCP client, IP, user-agent, session, and credential id; pass `externalId` to append a custom `ref`.
+- `controller_get_vm` `{ instance_id }` - current state and SSH details for an existing instance (must be owned by the caller's token).
+- `controller_terminate_vm` `{ instance_id }` - terminate an instance (must be owned by the caller's token).
+
+### Local
+
+- `local_list_templates` - list the local VM library to find a template to clone from.
+- `local_start_vm` `{ template, name?, wait?, timeoutSeconds? }` - clone the given template into a fresh, disposable VM and start it. The original template is never started or modified. `name` defaults to an auto-generated name (`mcp-<id>`). Subject to the running-VM limit. By default waits for the new VM to boot and obtain an IP, then returns `{ ok, name, source, ip }`; pass `wait: false` to return immediately. Delete with `local_delete_vm` when done.
+- `local_show_vm` `{ name }` - get a VM's IP address.
+- `local_ssh_access` `{ name }` - install a temporary SSH key into a running VM (waiting for a pending IP if needed); returns `{ ip, port, user, private_key_path, command }`.
+- `local_delete_vm` `{ name }` - delete one specific VM.
+
+VM/template names that start with `-` are rejected so a name can never be reinterpreted as a CLI flag.
+
+## Connecting a client
+
+Point any MCP client that supports streamable HTTP at `http://<host>:<port>/mcp` with the bearer token. For example, Cursor's `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "anka": {
+      "url": "http://your-host:9111/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+## Publishing (maintainers)
+
+Releases are published to npm by the [Publish](.github/workflows/publish.yml) workflow when a `v*` tag is pushed. Auth uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no long-lived npm tokens in GitHub secrets.
+
+### First release (bootstrap)
+
+Trusted publishing only works once `@veertu/anka-mcp` **already exists** on npm. The first version must be published once with token or interactive auth that satisfies the `@veertu` org's 2FA policy.
+
+**Option A — interactive login (simplest):**
+
+```bash
+npm login   # use an account with publish access to @veertu; complete 2FA when prompted
+npm ci
+npm run build
+npm test
+npm publish --access public
+```
+
+**Option B — granular access token (for CI-style bootstrap):**
+
+1. On [npmjs.com](https://www.npmjs.com) → **Access Tokens** → **Generate New Token** → **Granular Access Token**
+2. Permissions: **Read and write** for the `@veertu` scope (or this package)
+3. Enable **Bypass two-factor authentication for automation** (required when the org mandates 2FA for publish)
+4. Publish:
+
+```bash
+export NODE_AUTH_TOKEN="npm_..."
+npm ci && npm run build && npm test
+npm publish --access public
+```
+
+If you see `403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required`, your current login/token does not meet the org policy — use one of the options above.
+
+Then on [npmjs.com](https://www.npmjs.com/package/@veertu/anka-mcp) → **Settings** → **Trusted publishing**, add a GitHub Actions publisher:
+
+| Field | Value |
+| ----- | ----- |
+| Organization or user | `veertuinc` |
+| Repository | `anka-mcp` |
+| Workflow filename | `publish.yml` |
+| Allowed actions | `npm publish` |
+
+After the package exists and the trusted publisher is configured, push tags (e.g. `v0.1.1`) and CI publishes via OIDC. Provenance is generated automatically.
+
+If publish fails with `404 Not Found` on PUT, check: (1) package bootstrapped on npm, (2) trusted publisher fields match exactly, (3) workflow uses Node 24+ (npm 11.5.1+).
+
+## Testing
+
+```bash
+npm test           # run the suite once
+npm run test:watch # watch mode
+```
+
+The suite (Vitest) is hermetic - it needs neither a real Anka install nor a controller:
+
+- Unit tests cover config parsing, token store, the controller client + `extractSsh`/`isSshReady` (against an in-process mock controller), and input validation / output shaping.
+- End-to-end tests spawn the real server over HTTP and exercise tools through the MCP protocol, using a fake `anka` binary ([test/fixtures/fake-anka.mjs](test/fixtures/fake-anka.mjs)) and a mock controller ([test/helpers/controllerMock.ts](test/helpers/controllerMock.ts)). They verify auth, admin token API, per-token controller VM isolation, revoke cleanup, backend gating, per-backend tool exposure, the controller request->SSH flow, the local 2-VM guard, flag-injection rejection, and the SSH key-injection flow.
+
+## Adding new tools
+
+1. Create a file under `src/tools/controller/` or `src/tools/local/` exporting a tool via `defineTool({ name, config, handler })`.
+2. Add it to the array in that backend's `index.ts` (`controllerTools` or `localTools`). It is then auto-registered whenever that backend is enabled.
+
+## Project layout
+
+```
+src/
+  index.ts                 # entry: starts the HTTP server
+  auth.ts                  # MCP bearer token resolution
+  config.ts                # env-driven config + backend detection
+  anka.ts                  # runAnka(): execFile wrapper + JSON-envelope parsing
+  controller.ts            # Anka Build Cloud Controller API client
+  server.ts                # createServer(): McpServer + registerTools
+  tokens/
+    store.ts               # SQLite token + instance ownership store
+    schema.ts              # DB migrations
+    ownership.ts           # controller instance access helpers
+    cleanup.ts             # revoke-time controller VM termination
+  tools/
+    define-tool.ts         # defineTool helper + jsonResult
+    index.ts               # registers enabled backends' tools
+    controller/            # controller_* tools
+    local/                 # local_* tools (+ vms.ts: list/count/guard/name schema)
+  transports/
+    http.ts                # streamable HTTP transport + auth/origin middleware
+    admin.ts               # /admin/tokens routes
+test/
+  fixtures/fake-anka.mjs   # fake anka CLI for hermetic local-backend tests
+  helpers/                 # mock controller + MCP-over-HTTP client
+  unit/                    # config, controller client, validation/shaping
+  e2e/                     # full server over HTTP (auth, controller, local)
+```

package/dist/anka.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The JSON envelope every `anka -j <command>` call returns, e.g.
+ * `{"status":"OK","body":[...]}` or `{"status":"ERROR","message":"..."}`.
+ */
+export interface AnkaEnvelope {
+    status: "OK" | "ERROR" | string;
+    body?: unknown;
+    message?: string;
+    code?: number;
+    exception_type?: string;
+}
+export interface RunAnkaOptions {
+    /** Prepend `-j` so anka emits its JSON envelope and we parse it. Default true. */
+    machineReadable?: boolean;
+    /** Override the per-call timeout in ms. */
+    timeoutMs?: number;
+}
+/** Normalized result returned by {@link runAnka}. */
+export interface AnkaResult {
+    /** True when the process exited 0 and (if parsed) the envelope status was OK. */
+    ok: boolean;
+    /** Parsed envelope status, when machine-readable output was parsed. */
+    status?: string;
+    /** Parsed `body` field from the envelope, when present. */
+    body?: unknown;
+    /** Parsed `message` field from the envelope, when present. */
+    message?: string;
+    /** Process exit code (0 on success). */
+    exitCode: number;
+    /** The exact argument vector passed to the anka binary. */
+    args: string[];
+    /** Raw stdout. */
+    stdout: string;
+    /** Raw stderr. */
+    stderr: string;
+}
+/**
+ * Run the anka CLI with the given argument vector. Uses execFile (no shell) so
+ * arguments are passed verbatim and are not subject to shell injection.
+ */
+export declare function runAnka(args: string[], options?: RunAnkaOptions): Promise<AnkaResult>;

package/dist/anka.js

@@ -0,0 +1,65 @@
+import { execFile } from "node:child_process";
+import { config } from "./config.js";
+import { logAnkaCommand } from "./log.js";
+function isExecFailure(error) {
+    return typeof error === "object" && error !== null && "message" in error;
+}
+function tryParseEnvelope(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        // Not JSON (e.g. a non machine-readable command); leave undefined.
+    }
+    return undefined;
+}
+/**
+ * Run the anka CLI with the given argument vector. Uses execFile (no shell) so
+ * arguments are passed verbatim and are not subject to shell injection.
+ */
+export function runAnka(args, options = {}) {
+    const { machineReadable = true, timeoutMs = config.ankaTimeoutMs } = options;
+    const finalArgs = machineReadable ? ["-j", ...args] : [...args];
+    return new Promise((resolve) => {
+        execFile(config.ankaBin, finalArgs, { timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+            const envelope = machineReadable ? tryParseEnvelope(stdout) : undefined;
+            if (error) {
+                const failure = isExecFailure(error)
+                    ? error
+                    : { message: String(error) };
+                const result = {
+                    ok: false,
+                    status: envelope?.status,
+                    body: envelope?.body,
+                    message: envelope?.message ?? failure.message,
+                    exitCode: typeof failure.code === "number" ? failure.code : 1,
+                    args: finalArgs,
+                    stdout,
+                    stderr
+                };
+                logAnkaCommand(finalArgs, { ok: false, message: result.message });
+                resolve(result);
+                return;
+            }
+            const status = envelope?.status;
+            const ok = status ? status === "OK" : true;
+            logAnkaCommand(finalArgs, { ok, message: envelope?.message });
+            resolve({
+                ok,
+                status,
+                body: envelope?.body,
+                message: envelope?.message,
+                exitCode: 0,
+                args: finalArgs,
+                stdout,
+                stderr
+            });
+        });
+    });
+}
+//# sourceMappingURL=anka.js.map

package/dist/anka.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anka.js","sourceRoot":"","sources":["../src/anka.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAkD1C,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,CAAC;AAC3E,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAsB,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,UAA0B,EAAE;IAClE,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,aAAa,EAAE,GAAG,OAAO,CAAC;IAC7E,MAAM,SAAS,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEhE,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,EAAE;QACzC,QAAQ,CACN,MAAM,CAAC,OAAO,EACd,SAAS,EACT,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,EACnD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAExE,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,OAAO,GAAgB,aAAa,CAAC,KAAK,CAAC;oBAC/C,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG;oBACb,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,QAAQ,EAAE,MAAM;oBACxB,IAAI,EAAE,QAAQ,EAAE,IAAI;oBACpB,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,OAAO,CAAC,OAAO;oBAC7C,QAAQ,EAAE,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;oBAC7D,IAAI,EAAE,SAAS;oBACf,MAAM;oBACN,MAAM;iBACP,CAAC;gBACF,cAAc,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClE,OAAO,CAAC,MAAM,CAAC,CAAC;gBAChB,OAAO;YACT,CAAC;YAED,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAC;YAChC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3C,cAAc,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9D,OAAO,CAAC;gBACN,EAAE;gBACF,MAAM;gBACN,IAAI,EAAE,QAAQ,EAAE,IAAI;gBACpB,OAAO,EAAE,QAAQ,EAAE,OAAO;gBAC1B,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,SAAS;gBACf,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,10 @@
+export interface ResolvedMcpCredential {
+    credentialId: string;
+    credentialLabel?: string;
+}
+/** Constant-time string comparison that tolerates differing lengths. */
+export declare function safeEqual(a: string, b: string): boolean;
+/** Resolve a bearer token to an MCP client credential identity, or null when invalid. */
+export declare function resolveMcpCredential(bearerToken: string): ResolvedMcpCredential | null;
+/** Whether the server has any configured MCP client authentication path. */
+export declare function isMcpAuthConfigured(): boolean;

package/dist/auth.js

@@ -0,0 +1,43 @@
+import { timingSafeEqual } from "node:crypto";
+import { config } from "./config.js";
+import { getTokenStore, LEGACY_CREDENTIAL_ID } from "./tokens/store.js";
+/** Constant-time string comparison that tolerates differing lengths. */
+export function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/** Resolve a bearer token to an MCP client credential identity, or null when invalid. */
+export function resolveMcpCredential(bearerToken) {
+    if (config.allowNoAuth) {
+        return { credentialId: "anonymous" };
+    }
+    if (!bearerToken)
+        return null;
+    if (config.authToken && safeEqual(bearerToken, config.authToken)) {
+        return { credentialId: LEGACY_CREDENTIAL_ID, credentialLabel: "legacy" };
+    }
+    const validated = getTokenStore().validateToken(bearerToken);
+    if (validated) {
+        return { credentialId: validated.id, credentialLabel: validated.label || undefined };
+    }
+    return null;
+}
+/** Whether the server has any configured MCP client authentication path. */
+export function isMcpAuthConfigured() {
+    if (config.allowNoAuth)
+        return true;
+    if (config.authToken)
+        return true;
+    if (config.adminToken)
+        return true;
+    try {
+        return getTokenStore().hasActiveTokens();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAOxE,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,IAAI,MAAM,CAAC,SAAS,IAAI,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC3E,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7D,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,SAAS,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC;IACvF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,mBAAmB;IACjC,IAAI,MAAM,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,MAAM,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,aAAa,EAAE,CAAC,eAAe,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,69 @@
+export interface AnkaMcpConfig {
+    /** Port the HTTP server listens on. */
+    httpPort: number;
+    /** Host/interface the HTTP server binds to. */
+    httpHost: string;
+    /** Bearer token clients must present. Empty only when auth is explicitly disabled. */
+    authToken: string;
+    /** Admin bearer token for /admin/* routes. Empty disables the admin API. */
+    adminToken: string;
+    /** SQLite database path for client tokens and instance ownership. */
+    dbPath: string;
+    /** When true, revoking a token terminates its owned controller instances. */
+    revokeCleanupEnabled: boolean;
+    /** When true, the server runs without authentication (local dev only). */
+    allowNoAuth: boolean;
+    /** Allowed Origin header values for DNS-rebinding protection. Empty = unrestricted. */
+    allowedOrigins: string[];
+    /** When false, request/tool/backend logging to stderr is suppressed. */
+    logEnabled: boolean;
+    /** Optional append-only audit log file path. Empty = stderr only. */
+    auditLogPath: string;
+    /** Max JSON request body size in bytes. */
+    maxBodyBytes: number;
+    /** Max requests per client IP per minute (0 = disabled). */
+    rateLimitRpm: number;
+    /** Idle MCP session eviction threshold in ms. */
+    sessionIdleMs: number;
+    /** Max concurrent MCP sessions. */
+    maxSessions: number;
+    /** Max serialized tool response size in characters. */
+    maxResponseChars: number;
+    /** True when the local anka CLI tool set should be exposed. */
+    localEnabled: boolean;
+    /** Path to (or name of) the anka CLI binary. */
+    ankaBin: string;
+    /** Max time in ms a single anka invocation may run before being killed. */
+    ankaTimeoutMs: number;
+    /** Max number of running VMs the local backend will allow. */
+    localMaxVms: number;
+    /** Interval between local VM status polls (waiting for an IP), in ms. */
+    localPollIntervalMs: number;
+    /** Max time to wait for a local VM to obtain an IP after starting, in ms. */
+    localIpTimeoutMs: number;
+    /** True when the controller tool set should be exposed. */
+    controllerEnabled: boolean;
+    /** Base URL of the Anka Build Cloud Controller (e.g. http://anka.controller:8090). */
+    controllerUrl: string;
+    /** Raw value for the Authorization header sent to the controller (optional). */
+    controllerAuth: string;
+    /** When true, TLS certificate verification against the controller is skipped. */
+    controllerTlsInsecure: boolean;
+    /** Interval between instance-status polls, in ms. */
+    controllerPollIntervalMs: number;
+    /** Max time to wait for a requested VM to become SSH-ready, in ms. */
+    controllerStartTimeoutMs: number;
+    /** When true, controller_request_vm verifies SSH key auth before returning. */
+    controllerSshProbeEnabled: boolean;
+    /** Username the agent should use to SSH into a VM. */
+    vmSshUser: string;
+    /** Password the agent should use to SSH into a VM. */
+    vmSshPassword: string;
+    /** Guest port that maps to SSH inside the VM (forwarded on the host). */
+    vmSshGuestPort: number;
+    serverName: string;
+    serverVersion: string;
+}
+/** Build the runtime config from environment variables (read once at startup). */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AnkaMcpConfig;
+export declare const config: AnkaMcpConfig;