@luxorai/mcp 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `@tenkicloud/mcp`. This project follows semantic versioning.
+
+## [0.2.0] — 2026-08-21
+
+- Remove standalone image management tools. Template images remain available through template builds and sandbox creation.
+- Use `image` when creating a sandbox from a template image; removed image-reference arguments are now rejected.
+- Cap `tenki_exec` / `tenki_run_code` inline output at 64 KB per stream (override with `max_output_bytes` on `tenki_exec`). Larger output returns a head+tail preview with `stdoutTruncated`/`stderrTruncated` set, and the full capture file is kept in the sandbox at the reported `stdoutPath`/`stderrPath`.
+- Remove the project-scoped surface — the `tenki_list_project_sandboxes`/`_templates`/`_volumes`/`_snapshots` tools (their API methods no longer exist) and the `project_id` arguments (ignored by the API). Use the workspace-scoped equivalents.
+- Document the template-image path end to end: `image_name` builds require a typed template (`builder_spec`), and `tenki_create_sandbox`'s `image` takes the ready build's `imageDigestRef`.
+
+## [0.1.0] — 2026-08-03 — Initial release
+
+Model Context Protocol server for Tenki Cloud — disposable microVM sandboxes for AI agents. Published as **`@tenkicloud/mcp`**, matching the `@tenkicloud/sandbox` SDK. Install with `npx -y @tenkicloud/mcp`; the command it provides is `tenki-mcp`.
+
+### Tools
+
+- **85 tools covering the full Tenki unary API**, enforced by a CI parity audit (`scripts/parity-audit.mjs` fails the build if any SandboxService / DataPlane / SSHGateway method lacks a tool): sandbox lifecycle, code execution (`tenki_exec`, `tenki_run_code`), files, git, ports and preview URLs, snapshots, volumes, templates, SSH, artifacts, and workspace administration.
+- **`tenki_git`** validates `operation` as an enum of what the API actually supports (`clone`, `checkout`, `diff`, `log`) with per-operation arg keys documented; other git commands go through `tenki_exec`.
+- **`tenki_exec` returns structured output**: it declares an `outputSchema` and returns `structuredContent` (`stdout`/`stderr`/`exitCode`/`ok`) alongside a human-readable rendering in which control characters, bidi overrides, and zero-width marks are escaped to visible `\xNN`/`\uNNNN` — sandbox output is untrusted.
+- **`tenki_auth_status`** reports whether a usable credential is configured, which kind (`api_key`, `oauth_session_token`, or `session_cookie`), which env var it came from, the endpoint targeted, and whether a live identity probe succeeded — without ever returning the token. The server boots without a credential with this as the only registered tool, so a misconfigured client can ask what is wrong instead of seeing an opaque "server failed to start".
+- Shared, described input schemas across modules: session ids (trimmed, non-empty), ports (1–65535), preview slugs (matching the server's own validation), and file paths (blank rejected client-side, otherwise sent verbatim — no silent trimming of legal POSIX filenames).
+
+### Transports
+
+- **stdio** (default) and **Streamable HTTP** (`TENKI_MCP_TRANSPORT=http PORT=3000`), built from a shared `createServer()` factory.
+- The HTTP transport is hardened: loopback-only by default (`TENKI_MCP_HTTP_HOST` to expose), bearer auth via `TENKI_MCP_HTTP_TOKEN` (constant-time checked; required to bind a non-loopback host), DNS-rebinding protection via a Host-header allowlist, a 1 MiB request-body cap enforced on both the header and the streamed byte count, session count cap with idle reaping, and SIGTERM/SIGINT graceful shutdown.
+
+### Security posture
+
+- **Tool annotations on every tool** (`readOnlyHint`, `destructiveHint`, `openWorldHint`) so clients can surface or gate dangerous tools.
+- **Least-privilege env controls:** `TENKI_MCP_READONLY=1` registers only read tools (plus `tenki_auth_status`); `TENKI_MCP_DISABLED_TOOLS=a,b` drops named tools; `TENKI_MCP_AUDIT=1` logs each tool call's name and arg keys — never values, content, or tokens — to stderr. Applied centrally via a registration guard covering both SDK registration APIs.
+- **SECURITY.md** documents the threat model, trust boundaries (the key and endpoint are capabilities; sandbox output is untrusted), and a CSA MCP Server Top-10 mapping.
+- Importing the package cannot execute the server or exit the host process: the package is bin-only.
+
+### Network layer
+
+- **Every request carries a timeout** with one shared deadline per call (retries and backoff draw from it): 30s for unary calls (`TENKI_MCP_TIMEOUT_MS`), 600s for RPCs that block on storage work — snapshot creation and pause (`TENKI_MCP_SLOW_TIMEOUT_MS`) — and command execution follows the command's own timeout plus a 30s margin.
+- **Retry policy shaped by double-apply risk:** methods that must never run twice (creates, builds, publishes, resumes, extends, exec) never retry transient failures; reads and idempotent teardown retry `unavailable`, gateway-shaped 502/503/504, and transport-level failures, with rate limits retried for every method under jittered backoff honoring `Retry-After`. Read-shaped data-plane methods retry under the same rules.
+- **Session-credential cache** with expiry-aware refresh, single-flight minting, and invalidate-and-retry-once on a stale certificate (`permission_denied` deliberately does not re-mint).
+
+### Client
+
+- Dependency-free ConnectRPC client for the control and data planes; runtime dependencies are only `@modelcontextprotocol/sdk` and `zod`. Node ≥ 22.
+- Offline regression suites (security, transport input handling, exec output, network behavior — local stubs, zero external network) run in CI via `npm test`; live end-to-end suites in `test/run.mjs`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tenki Cloud
+
+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

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# tenki-mcp — `@tenkicloud/mcp`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A [Model Context Protocol](https://modelcontextprotocol.io) server for [Tenki Cloud](https://tenki.cloud).** Give any agent — Claude, Codex, Cursor — a disposable microVM it can create, run code in, read and write files, run git, and expose to the web. Sandboxes boot in ~2 seconds and are billed per second.
+
+Part of making Tenki the execution layer coding agents reach for: the agent writes code and Tenki runs it in isolation. (Tenki's **Code Reviewer** and **Runners** — AI PR review and managed CI — are separate products; this server currently exposes the Sandbox.)
+
+```
+"Run this Python in a fresh sandbox and tell me what it prints."
+        │
+        ▼   tenki_run_code
+   boots a microVM → runs it → returns stdout → tears it down
+```
+
+## Quickstart
+
+```bash
+export TENKI_API_KEY=tk_your_key_here
+npx -y @tenkicloud/mcp     # speaks MCP over stdio
+```
+
+Nothing to clone or build. The package installs one command, `tenki-mcp`.
+
+### Use it in Claude Code
+
+Connect to Tenki's hosted MCP service and sign in with your Tenki account:
+
+```bash
+claude mcp add --transport http tenki https://mcp.tenki.cloud/mcp
+claude mcp login tenki
+```
+
+Claude Code's `mcp add` command stores the server configuration; `mcp login` performs the one-time browser authorization and workspace selection.
+
+Alternatively, run the MCP server locally with an API key:
+
+```bash
+claude mcp add tenki --env TENKI_API_KEY=tk_your_key_here -- npx -y @tenkicloud/mcp
+```
+
+### Or install it as a Claude Code plugin
+
+The repo doubles as a plugin marketplace. This prompts for your API key on install and stores it in your OS keychain — no env var to manage:
+
+```
+/plugin marketplace add LuxorLabs/tenki-mcp
+/plugin install tenki@tenki
+```
+
+### Use it in Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tenki": {
+      "command": "npx",
+      "args": ["-y", "@tenkicloud/mcp"],
+      "env": { "TENKI_API_KEY": "tk_your_key_here" }
+    }
+  }
+}
+```
+
+### Use it in Cursor
+
+Add the same block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "tenki": {
+      "command": "npx",
+      "args": ["-y", "@tenkicloud/mcp"],
+      "env": { "TENKI_API_KEY": "tk_your_key_here" }
+    }
+  }
+}
+```
+
+### Use it in Codex
+
+The OpenAI Codex CLI reads MCP servers from `~/.codex/config.toml`. Add:
+
+```toml
+[mcp_servers.tenki]
+command = "npx"
+args = ["-y", "@tenkicloud/mcp"]
+env = { TENKI_API_KEY = "tk_your_key_here" }
+```
+
+### Confirm it's working
+
+After adding the server, **start a fresh session** so the client loads it, then ask your agent one of:
+
+- *"Check tenki auth status."* — confirms your credential was picked up.
+- *"Run `print(2+2)` in a fresh Tenki sandbox."* — a full boot → run → teardown round-trip.
+
+If the `tenki_*` tools don't show up, restart the client so it re-reads its config.
+
+No key yet? Start the server without one and ask the agent to check `tenki_auth_status` — it reports what to set and where. See [Auth](#auth).
+
+### Run it from a clone instead
+
+For development, or to run an unreleased change:
+
+```bash
+git clone https://github.com/LuxorLabs/tenki-mcp.git && cd tenki-mcp
+npm install && npm run build
+TENKI_API_KEY=tk_your_key_here node dist/index.js
+```
+
+Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` command in any of the configs above. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development loop.
+
+### Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TENKI_API_KEY` | — | API key (`tk_…`). One of this or `TENKI_AUTH_TOKEN` is required. |
+| `TENKI_AUTH_TOKEN` | — | Session token (`ory_st_…` or cookie value). **Takes precedence over `TENKI_API_KEY`** when both are set. |
+| `TENKI_API_ENDPOINT` | `https://api.tenki.cloud` | Control-plane base URL (`TENKI_API_URL` is an alias). |
+| `TENKI_MCP_READONLY` | off | `1` registers only read tools (no create/run/delete/spend). |
+| `TENKI_MCP_DISABLED_TOOLS` | — | Comma-separated tool names to skip registering. |
+| `TENKI_MCP_AUDIT` | off | `1` logs each tool call name + arg keys to stderr. |
+| `TENKI_MCP_TRANSPORT` | `stdio` | `http` serves Streamable HTTP instead (see below). |
+| `PORT` | `3000` | HTTP transport port. |
+| `TENKI_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host; non-loopback requires `TENKI_MCP_HTTP_TOKEN`. |
+| `TENKI_MCP_HTTP_TOKEN` | — | Bearer token for the HTTP endpoint; optional on loopback, required on a non-loopback host. |
+| `TENKI_MCP_PUBLIC_URL` | — | Public base URL for an OAuth-protected hosted server. |
+| `TENKI_MCP_OAUTH_ISSUER` | — | OAuth authorization-server issuer. Enables delegated OAuth HTTP mode. |
+| `TENKI_MCP_OAUTH_RESOURCE` | `<public URL>/mcp` | RFC 8707 resource identifier accepted in access-token audiences. |
+| `TENKI_MCP_OAUTH_SCOPE` | `mcp` | Required delegated scope. |
+| `TENKI_MCP_IDENTITY_URL` | — | Internal Tenki Identity service endpoint used to exchange OAuth access tokens. |
+| `TENKI_MCP_IDENTITY_SERVICE_TOKEN` | — | Service credential for the private Identity token-exchange RPC. |
+
+## Tools
+
+**71 tools** — all 68 public unary API methods (enforced by a CI [parity audit](scripts/parity-audit.mjs)), two workflow helpers, and `tenki_auth_status`. Implementation-only control-plane methods are intentionally excluded. Grouped by domain:
+
+| Domain | Tools |
+|---|---|
+| **Auth** | `tenki_auth_status` (which credential is configured, and does it work — the only tool available when none is) |
+| **Identity** | `tenki_whoami` |
+| **Run** | `tenki_run_code` (one-shot: boot → run shell/python/js → tear down) |
+| **Sandboxes** | `tenki_create_sandbox` · `tenki_get_sandbox` · `tenki_list_sandboxes` · `tenki_terminate_sandbox` · `tenki_pause_sandbox` · `tenki_resume_sandbox` |
+| **Session admin** | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes` |
+| **Exec** | `tenki_exec` (stdout/stderr/exit inline) |
+| **Files** | `tenki_read_file` · `tenki_write_file` · `tenki_list_files` · `tenki_stat_path` · `tenki_make_dir` · `tenki_remove_path` · `tenki_move_path` |
+| **Git** | `tenki_git` (clone/checkout/diff/log — the API supports exactly these four; run other git commands via `tenki_exec`) |
+| **Ports & previews** | expose · list-exposed · unexpose · create-preview-url · open-preview · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token |
+| **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET) |
+| **SSH** | `tenki_update_ssh_keys` · `tenki_issue_ssh_cert` · `tenki_list_ssh_gateways` |
+| **Snapshots** | create · get · list · list-session · list-workspace · list-dangling · update · delete · get-download-url |
+| **Volumes** | create · get · list · update · delete · resize · attach · detach |
+| **Templates** | create · get · list · update · delete · build · cancel-build · get-build · list-active-builds |
+| **Workspace** | `tenki_get_workspace_usage` · `tenki_get_workspace_settings` · `tenki_update_workspace_settings` · `tenki_get_snapshot_retention_settings` · `tenki_update_snapshot_retention_settings` |
+
+Full per-release breakdown in [CHANGELOG.md](CHANGELOG.md).
+
+## Auth
+
+Set one of `TENKI_API_KEY` or `TENKI_AUTH_TOKEN` — when both are set, `TENKI_AUTH_TOKEN` wins. The header is chosen by token prefix: `tk_…` → `Authorization: Bearer`, `ory_st_…` → `X-Session-Token`, otherwise a session cookie. Override the endpoint with `TENKI_API_ENDPOINT` (default `https://api.tenki.cloud`).
+
+**Without a credential the server still starts**, registering only `tenki_auth_status` — so instead of an MCP client reporting an opaque "server failed to start", the agent can call that tool and get told what to set. Ask it "check tenki auth status" any time other tools return auth errors: it reports the credential kind (API key vs session token), the endpoint, and whether a live identity probe succeeded — never the token itself. It reports status only; get a credential with `tenki login` or from the dashboard.
+
+## Host it over HTTP (v2.0-beta)
+
+Besides stdio, the server speaks **Streamable HTTP** so it can be hosted for remote MCP clients:
+
+```bash
+TENKI_MCP_TRANSPORT=http PORT=3000 TENKI_API_KEY=… npx -y @tenkicloud/mcp
+# → tenki-mcp running on http://127.0.0.1:3000/mcp (Streamable HTTP) [loopback only, no auth]
+```
+
+For a single-user deployment, HTTP mode can hold one shared `TENKI_API_KEY` and therefore exposes a powerful capability. By default it:
+
+- **binds to loopback (`127.0.0.1`) only** — set `TENKI_MCP_HTTP_HOST=0.0.0.0` to expose it, but then
+- it **requires a bearer token**: set `TENKI_MCP_HTTP_TOKEN` and send `Authorization: Bearer <token>`. It **refuses to start** on a non-loopback host without one.
+- **DNS-rebinding protection** is on (Host-header allowlist), so a malicious web page can't drive your local server.
+
+```bash
+# expose to a network safely:
+TENKI_MCP_TRANSPORT=http TENKI_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
+  TENKI_MCP_HTTP_TOKEN=$(openssl rand -hex 32) TENKI_API_KEY=… npx -y @tenkicloud/mcp
+```
+
+Point an HTTP-capable MCP client at `/mcp`. Static-key mode uses one shared `TENKI_API_KEY` for all sessions. Verified end-to-end (`test/http-transport.test.mjs`: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).
+
+Hosted multi-tenant deployments instead use Tenki Identity's OAuth facade. The MCP server publishes RFC 9728 protected-resource metadata and exchanges each caller's access token through the private Identity service. Identity owns Hydra, validates the requested audience and scope, and issues a short-lived API delegation bound to the user, client, and workspace selected on the Tenki consent page. `tenki-mcp` has no Hydra Admin access and does not hold the delegation-signing secret.
+
+## How it works
+
+Tenki's API is **ConnectRPC** — JSON over HTTP/1.1, not REST. Every control-plane call is `POST https://api.tenki.cloud/tenki.sandbox.v1.SandboxService/{Method}` with a lowerCamelCase JSON body. Per-session file I/O runs on a **separate data-plane endpoint** returned at create time, authenticated with a short-lived session certificate. This server owns both transports so the tools stay one-liners.
+
+Command output: `tenki_exec` and `tenki_run_code` capture `stdout`/`stderr` by redirecting to files (`sh -c '… > out 2> err'`) and reading them back over the data plane, so you get the output inline through a plain HTTP client.
+
+The wire details are ported from the live-verified [n8n community node](https://github.com/opencolin/n8n-nodes-tenki).
+
+## Security
+
+This server holds a Tenki API key and can run code + spend credits, so treat it as a capability. Full model + [CSA MCP Server Top-10](https://modelcontextprotocol-security.io/top10/server/) mapping in **[SECURITY.md](SECURITY.md)**. Quick controls:
+
+- **Least privilege:** every tool carries MCP annotations (`readOnlyHint` / `destructiveHint`). Run `TENKI_MCP_READONLY=1` for an inspection-only server (read tools only), or `TENKI_MCP_DISABLED_TOOLS=tenki_run_code,…` to drop specific tools.
+- **HTTP transport** is loopback-only by default and requires a bearer token to expose to a network (see [Host it over HTTP](#host-it-over-http-v20-beta)).
+- **Audit:** `TENKI_MCP_AUDIT=1` logs each tool call's name to stderr.
+- **Untrusted output:** `tenki_run_code`/`tenki_exec`/`tenki_read_file` return output from untrusted code — clients should treat tool results as data, not instructions.
+
+Report vulnerabilities via a private [security advisory](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), not a public issue.
+
+## Related
+
+- **Tenki Sandbox** — the platform: https://tenki.cloud
+- **n8n-nodes-tenki** — Tenki as an n8n node: https://github.com/opencolin/n8n-nodes-tenki
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security
+
+`tenki-mcp` gives an AI agent a capability: a disposable microVM it can create, run code in, and spend Tenki credits with. Treat the server and its credentials accordingly. This document is the threat model and the controls, mapped to the [CSA MCP Server Top 10](https://modelcontextprotocol-security.io/top10/server/).
+
+## Reporting a vulnerability
+Please **do not** open a public issue for security reports. Open a private [GitHub security advisory](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), or email **hello@luxor.tech**. We'll acknowledge within a few business days.
+
+## Trust boundaries (read this first)
+- **Credentials are capabilities.** Local and single-user modes authenticate with a `TENKI_API_KEY` or session token. Hosted OAuth mode exchanges each caller's token through Tenki Identity and receives only a short-lived, workspace-bound internal delegation to the Tenki API. Never commit credentials (`.env` is gitignored).
+- **Sandbox output is untrusted.** `tenki_run_code` / `tenki_exec` / `tenki_read_file` return output produced by *untrusted, AI-generated code running in the sandbox*. That output flows back to the calling model as a tool result — a classic **indirect / output prompt-injection** vector. The microVM is the isolation boundary; the model should treat tool results as **data, not instructions**. (MCP clients are responsible for not executing instructions found in tool output.)
+- **The HTTP endpoint is a capability.** In static-key HTTP mode, access to `/mcp` is equivalent to access to the configured key. Hosted mode requires a valid OAuth bearer on every request and binds the MCP session to its user, client, and workspace.
+
+## Controls this server provides
+
+### Least privilege (MCP-07 — the main lever)
+Every tool is tagged with MCP **annotations** so clients can surface/gate danger:
+`readOnlyHint` on inspection tools, `destructiveHint` on the 13 that delete/terminate/revoke, `openWorldHint` on all (they call an external API). Plus two env controls:
+
+| Env | Effect |
+|---|---|
+| `TENKI_MCP_READONLY=1` | Register **only read-only tools** — no create, run, spend, or delete. For inspection-only deployments. |
+| `TENKI_MCP_DISABLED_TOOLS=a,b,c` | Skip the named tools (e.g. disable `tenki_run_code` where code execution isn't wanted). |
+
+Grant the smallest set that the use case needs.
+
+### Transport security (MCP-05, MCP-10)
+- **stdio** (default) has no network surface.
+- **HTTP** (`TENKI_MCP_TRANSPORT=http`) binds **loopback-only** by default, **requires a bearer token** to bind to a non-loopback host, has **DNS-rebinding protection**, and caps sessions + body size. For network exposure put it behind a **TLS-terminating proxy**. (Hardening details in the transport module, `src/http.ts`.)
+
+### Secrets & audit (MCP-04, Observability)
+- Static credentials are read from env and sent only as auth headers. Hosted OAuth tokens are sent only to the private Tenki Identity exchange endpoint and are never forwarded to the Tenki API; the API receives a short-lived signed delegation instead.
+- `TENKI_MCP_AUDIT=1` logs each tool call's **name + argument keys** to stderr (never values, content, or the token) for an operator audit trail.
+
+## CSA MCP Server Top-10 mapping
+
+| # | Risk | tenki-mcp posture |
+|---|---|---|
+| MCP-01 | Prompt Injection | zod-validates every tool arg pre-network; **sandbox output is untrusted** (treat tool results as data) |
+| MCP-02 | Confused Deputy | static mode requires its own HTTP bearer; hosted mode authenticates every request and binds the session and API delegation to the authorized user, client, and workspace; `READONLY`/denylist further bound the blast radius |
+| MCP-03 | Tool Poisoning | tool descriptions are static and authored (no dynamic/remote descriptions); verify the package via its npm provenance attestation (published from GitHub Actions, linking each release to its source commit) + MCP-registry namespace ownership |
+| MCP-04 | Credential/Token Exposure | credentials are never logged/committed/echoed; hosted OAuth tokens go only to Tenki Identity and only short-lived internal delegations reach the API; audit logs keys not values |
+| MCP-05 | Insecure Configuration | HTTP transport is loopback + token + DNS-rebinding-protected + DoS-capped by default |
+| MCP-06 | Supply Chain | 2 direct runtime deps (`@modelcontextprotocol/sdk`, `zod`) — ~91 transitive, nearly all via the MCP SDK; lockfile committed; released only from CI with npm provenance, Actions pinned to commit SHAs |
+| MCP-07 | Excessive Permissions | tool annotations + `TENKI_MCP_READONLY` + `TENKI_MCP_DISABLED_TOOLS` |
+| MCP-08 | Data Exfiltration | microVM isolation; sandbox **outbound networking is off unless `allow_outbound` is set**; the server itself stores/forwards nothing |
+| MCP-09 | Context Spoofing | tool results are raw API/sandbox output surfaced as data, not merged into instructions |
+| MCP-10 | Insecure Communication | control plane is HTTPS; run the HTTP transport behind TLS for any non-loopback use |
+
+## Cost / resource notes
+`tenki_run_code` is cost-guarded (1 vCPU, 1 GB, 10-min cap, 5-min idle) and self-terminates. `tenki_create_sandbox` and other create tools **spend real credits** — bound them with your **Tenki workspace limits**, `TENKI_MCP_READONLY`/denylist, and `TENKI_MCP_AUDIT` for visibility.

package/dist/client.d.ts

@@ -0,0 +1,177 @@
+/**
+ * TenkiClient — a dependency-free client for the Tenki Cloud API.
+ *
+ * Tenki's API is ConnectRPC (JSON over HTTP/1.1), not REST. Every control-plane
+ * call is `POST {baseUrl}/tenki.sandbox.v1.SandboxService/{Method}` with a
+ * lowerCamelCase JSON body and a JSON response. Per-session file I/O runs on a
+ * separate data-plane endpoint returned at session-create time, authenticated
+ * with a short-lived session certificate.
+ *
+ * The wire details here (headers, the control/data-plane split, and capturing
+ * command stdout/stderr via an `sh -c` redirect + data-plane ReadFile) are
+ * ported from the live-verified n8n community node
+ * (github.com/opencolin/n8n-nodes-tenki).
+ */
+export type Language = "shell" | "python" | "javascript";
+export interface ExecResult {
+    command: string;
+    args: string[];
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    ok: boolean;
+    captureError?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    /** Sandbox path holding the FULL stdout, present only when stdout was truncated. */
+    stdoutPath?: string;
+    /** Sandbox path holding the FULL stderr, present only when stderr was truncated. */
+    stderrPath?: string;
+}
+export interface TenkiClientOptions {
+    /** Timeout for unary control/data-plane calls (default 30s). */
+    timeoutMs?: number;
+    /** Timeout for ExecuteCommand when the command itself has no timeout (default 630s). */
+    execTimeoutMs?: number;
+    /** Timeout for long storage/VM operations — see SLOW_METHOD (default 600s). */
+    slowTimeoutMs?: number;
+    /** Assumed session-credential lifetime when the API returns no parseable expiry (default 5min). */
+    credTtlMs?: number;
+    /** Workspace selected by an upstream delegated authorization grant. */
+    workspaceId?: string;
+    /** Supplies a short-lived Bearer credential for hosted delegated calls. */
+    bearerTokenProvider?: () => string;
+}
+export declare class TenkiClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly credCache;
+    private readonly credInflight;
+    private readonly timeoutMs;
+    private readonly execTimeoutMs;
+    private readonly slowTimeoutMs;
+    private readonly credTtlMs;
+    private readonly workspaceId?;
+    private readonly bearerTokenProvider?;
+    constructor(token: string, baseUrl?: string, opts?: TenkiClientOptions);
+    private controlAuthHeaders;
+    /**
+     * ExecuteCommand blocks until the command finishes, so its timeout follows
+     * the command's own timeout (plus margin) instead of the unary default.
+     */
+    private timeoutFor;
+    /**
+     * fetch + full body read under ONE timeout, with a readable error instead of
+     * a bare AbortError. Reading the body inside the guarded section matters: a
+     * response whose headers arrive but whose body stalls must fail with the
+     * same friendly, retryable timeout as a connection that never responds.
+     */
+    private fetchTextWithTimeout;
+    /**
+     * Retry policy: rate limits always; `unavailable` and gateway-shaped
+     * 502/503/504 (load balancers and CDNs return these with an HTML or empty
+     * body, no ConnectRPC code) for every method that cannot double-apply.
+     */
+    private shouldRetry;
+    /** Exponential backoff with half-jitter; a Retry-After header (seconds) wins, capped. */
+    private backoffMs;
+    /**
+     * Unary control-plane call. The WHOLE call — every attempt plus every
+     * backoff sleep — draws from one shared deadline (the method's timeout), so
+     * retries can never stack past it: an MCP client's own 60s default would
+     * otherwise give up before our per-attempt timeouts did. Rate-limit
+     * rejections retry with jittered backoff (honoring Retry-After); transient
+     * `unavailable`/gateway errors AND transport-level failures (timeout,
+     * connection reset, DNS) retry for every method that cannot double-apply.
+     * `service` defaults to SandboxService; pass another fully-qualified ConnectRPC
+     * service (e.g. the SSH gateway service) for methods hosted elsewhere.
+     */
+    control(method: string, body?: Record<string, unknown>, service?: string): Promise<Record<string, any>>;
+    /**
+     * Mint (and cache per session) the data-plane endpoint + session certificate.
+     * A credential with no parseable expiry is cached for credTtlMs — never
+     * forever — and a known expiry is shortened by a skew so an in-flight call
+     * can't straddle the real expiry. Minting is single-flight: concurrent data
+     * calls on a cold cache share one mint instead of each paying a
+     * control-plane round trip for its own certificate.
+     */
+    private credentialFor;
+    private mintCredential;
+    /**
+     * Unary data-plane call. The inner request is wrapped as
+     * `{ request: { sessionId, ...request } }`. This is the path behind every
+     * file tool AND how tenki_exec reads back its own output, so it gets the
+     * same treatment as the control plane: one shared deadline, rate limits
+     * retried for every method, transient/gateway/transport failures retried
+     * for read-shaped methods. A stale-certificate failure (401/unauthenticated
+     * — the cert may have expired server-side regardless of its stated expiry)
+     * invalidates the cache and re-mints once; permission_denied is NOT an auth
+     * failure — a denied path is a normal user error a fresh cert can never
+     * fix, so re-minting would waste a control-plane round trip per denied call.
+     */
+    data(sessionId: string, method: string, request?: Record<string, unknown>): Promise<Record<string, any>>;
+    /**
+     * Resolve the calling identity + a default workspace for CreateSession and
+     * other workspace-scoped calls. (Projects were removed from the API — the
+     * proto reserves every project_id field and WhoAmI no longer lists projects —
+     * so there is nothing narrower than a workspace to resolve.)
+     *
+     * CreateSession validates owner_type ∈ {SERVICE, USER} and requires a
+     * non-empty owner_id, but derives the real owner from the authenticated
+     * identity server-side. WhoAmI can return other owner types (e.g. WORKSPACE
+     * for workspace-scoped keys), which the validator rejects — so for those we
+     * send the same placeholder the first-party SDKs hardcode ("SERVICE"/"self").
+     */
+    resolveOwner(): Promise<{
+        ownerType?: string;
+        ownerId?: string;
+        workspaceId?: string;
+    }>;
+    /** Poll GetSession until it reaches (or passes into) the target state. */
+    waitForState(sessionId: string, target?: string, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Record<string, any>>;
+    readTextFile(sessionId: string, path: string): Promise<string>;
+    writeTextFile(sessionId: string, path: string, text: string): Promise<Record<string, any>>;
+    /**
+     * Read a capture file back, capping what crosses the wire. Stat first: a
+     * file at or under the cap is read whole; a larger one gets a server-side
+     * head+tail preview (assembled by `sh` in the sandbox, so the full body
+     * never leaves it — ReadFile has no range support). The preview file is the
+     * caller's to clean up (returned as previewPath); the ORIGINAL is theirs to
+     * keep, so the user can page through the full output afterwards.
+     */
+    private readCaptureFile;
+    /**
+     * Run a command in a session and return stdout/stderr inline.
+     *
+     * We wrap the command in `sh -c '<cmd> > out 2> err'`, then read the capture
+     * files back over the data plane, so output is available through a plain-HTTP
+     * client. Capture-read failures degrade gracefully into `captureError` rather
+     * than losing the run — but the result is marked NOT ok, because empty
+     * stdout/stderr next to a zero exit code would otherwise read as a clean,
+     * silent success. Streams over maxOutputBytes come back truncated
+     * (head+tail) with the full capture file retained in the sandbox — see
+     * readCaptureFile; truncation does not affect `ok`.
+     */
+    execCaptured(sessionId: string, command: string, opts?: {
+        args?: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutSeconds?: number;
+        maxOutputBytes?: number;
+    }): Promise<ExecResult>;
+    /**
+     * One-shot: boot a throwaway sandbox, run code (shell / python / javascript),
+     * return its output, and terminate the sandbox. Cost-guarded (1 vCPU, 1 GB,
+     * 10-min cap, 5-min idle) so an ephemeral run can never leak a billing session.
+     */
+    runCode(language: Language, code: string, opts?: {
+        env?: Record<string, string>;
+        timeoutSeconds?: number;
+    }): Promise<ExecResult & {
+        sessionId: string;
+        language: Language;
+    }>;
+}