@tenkicloud/mcp 0.2.0 → 0.3.0

package/README.md

@@ -22,10 +22,30 @@ 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`:
@@ -106,6 +126,12 @@ Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` comman
 | `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
 
@@ -146,7 +172,7 @@ 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]
 ```
 
-**Security — this endpoint is a capability.** In HTTP mode the process holds one shared `TENKI_API_KEY` and exposes every tool, including arbitrary code execution and credit spend. So by default it:
+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.
@@ -158,7 +184,9 @@ 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`. v2.0-beta uses one shared `TENKI_API_KEY` for all sessions; per-request auth (multi-tenant hosting) is not yet implemented. Verified end-to-end (`test/http-transport.test.mjs`: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).
+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
 

package/SECURITY.md

@@ -1,14 +1,14 @@
 # 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 the API key it holds — accordingly. This document is the threat model and the controls, mapped to the [CSA MCP Server Top 10](https://modelcontextprotocol-security.io/top10/server/).
+`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)
-- **The API key is a capability.** In every mode the process authenticates to Tenki with one `TENKI_API_KEY` and can create sandboxes, run arbitrary code, and spend credits. Anyone who can invoke the server can do those things. Scope the key if your Tenki plan allows it; never commit it (`.env` is gitignored).
+- **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 HTTP mode the `/mcp` endpoint is equivalent to handing out the key — protect it (below).
+- **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
 
@@ -28,7 +28,7 @@ Grant the smallest set that the use case needs.
 - **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)
-- The key is read from env and sent only as an auth header — never logged, never in error responses.
+- 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
@@ -36,9 +36,9 @@ Grant the smallest set that the use case needs.
 | # | 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 | single shared key; HTTP endpoint requires its own bearer token; `READONLY`/denylist bound the blast radius; per-request auth is not yet implemented |
+| 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 | key via env only; never logged/committed/echoed; audit logs keys not values |
+| 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` |

package/dist/client.d.ts

@@ -37,6 +37,10 @@ export interface TenkiClientOptions {
     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;
@@ -47,7 +51,10 @@ export declare class TenkiClient {
     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.

package/dist/client.js

@@ -128,6 +128,8 @@ export class TenkiClient {
     execTimeoutMs;
     slowTimeoutMs;
     credTtlMs;
+    workspaceId;
+    bearerTokenProvider;
     constructor(token, baseUrl = DEFAULT_BASE_URL, opts = {}) {
         this.token = token;
         this.baseUrl = baseUrl.replace(/\/+$/, "");
@@ -135,6 +137,13 @@ export class TenkiClient {
         this.execTimeoutMs = opts.execTimeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
         this.slowTimeoutMs = opts.slowTimeoutMs ?? DEFAULT_SLOW_TIMEOUT_MS;
         this.credTtlMs = opts.credTtlMs ?? DEFAULT_CRED_TTL_MS;
+        this.workspaceId = opts.workspaceId?.trim() || undefined;
+        this.bearerTokenProvider = opts.bearerTokenProvider;
+    }
+    controlAuthHeaders() {
+        if (this.bearerTokenProvider)
+            return { Authorization: `Bearer ${this.bearerTokenProvider()}` };
+        return authHeaders(this.token);
     }
     /**
      * ExecuteCommand blocks until the command finishes, so its timeout follows
@@ -207,7 +216,7 @@ export class TenkiClient {
             try {
                 res = await this.fetchTextWithTimeout(url, {
                     method: "POST",
-                    headers: { "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...authHeaders(this.token) },
+                    headers: { "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...this.controlAuthHeaders() },
                     body: JSON.stringify(body ?? {}),
                 }, deadline - Date.now(), method);
             }
@@ -360,7 +369,9 @@ export class TenkiClient {
     async resolveOwner() {
         const resp = await this.control("WhoAmI", {});
         const workspaces = Array.isArray(resp.workspaces) ? resp.workspaces : [];
-        const ws = workspaces[0];
+        const ws = this.workspaceId
+            ? workspaces.find((candidate) => (candidate?.workspaceId ?? candidate?.id) === this.workspaceId)
+            : workspaces[0];
         let ownerType = resp.ownerType;
         let ownerId = resp.ownerId;
         // Substitute the placeholder only when WhoAmI returned a type CreateSession
@@ -373,7 +384,7 @@ export class TenkiClient {
         return {
             ownerType,
             ownerId,
-            workspaceId: ws?.workspaceId ?? ws?.id,
+            workspaceId: this.workspaceId ?? ws?.workspaceId ?? ws?.id,
         };
     }
     /** Poll GetSession until it reaches (or passes into) the target state. */

package/dist/http.d.ts

@@ -8,12 +8,10 @@
  *   TENKI_MCP_HTTP_HOST    — bind host (default 127.0.0.1, loopback-only)
  *   TENKI_MCP_HTTP_TOKEN   — required Bearer token for the /mcp endpoint
  *
- * Security posture (the process holds one shared TENKI_API_KEY and exposes all
- * tools, incl. arbitrary code execution + credit spend, so the endpoint is a
- * capability): loopback-only by default; DNS-rebinding protection on (Host
- * allowlist); optional bearer auth; and it REFUSES to bind to a non-loopback
- * host without a token set. Per-session/global DoS caps are applied.
+ * Security posture: loopback-only by default; DNS-rebinding protection on
+ * (Host allowlist); static bearer auth or OAuth required for non-loopback
+ * binds; and per-session/global DoS caps are applied.
  */
 import http from "node:http";
-import type { TenkiClient } from "./client.js";
+import { TenkiClient } from "./client.js";
 export declare function startHttp(client: TenkiClient | null, port: number): http.Server;

package/dist/http.js

@@ -8,16 +8,16 @@
  *   TENKI_MCP_HTTP_HOST    — bind host (default 127.0.0.1, loopback-only)
  *   TENKI_MCP_HTTP_TOKEN   — required Bearer token for the /mcp endpoint
  *
- * Security posture (the process holds one shared TENKI_API_KEY and exposes all
- * tools, incl. arbitrary code execution + credit spend, so the endpoint is a
- * capability): loopback-only by default; DNS-rebinding protection on (Host
- * allowlist); optional bearer auth; and it REFUSES to bind to a non-loopback
- * host without a token set. Per-session/global DoS caps are applied.
+ * Security posture: loopback-only by default; DNS-rebinding protection on
+ * (Host allowlist); static bearer auth or OAuth required for non-loopback
+ * binds; and per-session/global DoS caps are applied.
  */
 import http from "node:http";
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { TenkiClient } from "./client.js";
+import { OAuthResourceRoutes, OAuthTokenVerifier, authorizationBinding, bearerToken, loadOAuthConfig, } from "./oauth.js";
 import { createServer } from "./server.js";
 const MAX_BODY_BYTES = 1 << 20; // 1 MiB — reject larger POST bodies (memory-DoS guard)
 const MAX_SESSIONS = 256; // cap concurrent sessions (init-flood DoS guard)
@@ -109,22 +109,41 @@ function authOk(header, expected) {
  * an ephemeral `port: 0` bind still accepts its own address). Anything else —
  * e.g. a rebound attacker domain — is rejected by the transport.
  */
-function allowedHostsFor(server, host, port) {
+function allowedHostsFor(server, host, port, publicUrl) {
     const addr = server.address();
     const bound = addr && typeof addr === "object" ? addr.port : port;
     const ports = Array.from(new Set([port, bound]));
     const hosts = Array.from(new Set([host, "127.0.0.1", "localhost", "[::1]", "::1"]));
-    return hosts.flatMap((h) => ports.map((p) => `${h}:${p}`));
+    const configured = (process.env.TENKI_MCP_ALLOWED_HOSTS || "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (publicUrl) {
+        const url = new URL(publicUrl);
+        configured.push(url.host, url.hostname);
+    }
+    return Array.from(new Set([...hosts.flatMap((h) => ports.map((p) => `${h}:${p}`)), ...configured]));
+}
+function oauthUnauthorized(res, metadataUrl, scope) {
+    res
+        .writeHead(401, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        "WWW-Authenticate": `Bearer resource_metadata="${metadataUrl}", scope="${scope}"`,
+    })
+        .end(JSON.stringify({ error: "unauthorized" }));
 }
 export function startHttp(client, port) {
     const host = process.env.TENKI_MCP_HTTP_HOST || "127.0.0.1";
     const httpToken = process.env.TENKI_MCP_HTTP_TOKEN || "";
     const isLoopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
+    const oauthConfig = loadOAuthConfig();
+    const oauthVerifier = oauthConfig ? new OAuthTokenVerifier(oauthConfig) : null;
+    const oauthRoutes = oauthConfig ? new OAuthResourceRoutes(oauthConfig) : null;
     // Refuse to expose an unauthenticated capability to the network.
-    if (!isLoopback && !httpToken) {
+    if (!isLoopback && !httpToken && !oauthConfig) {
         console.error("tenki-mcp: refusing to bind HTTP to a non-loopback host without TENKI_MCP_HTTP_TOKEN " +
-            "(the /mcp endpoint would be unauthenticated and can spend credits / run code). " +
-            "Set TENKI_MCP_HTTP_TOKEN, or bind to 127.0.0.1.");
+            "or OAuth configuration (the /mcp endpoint would be unauthenticated and can spend credits / run code).");
         process.exit(1);
     }
     const sessions = new Map();
@@ -145,16 +164,37 @@ export function startHttp(client, port) {
     sweep.unref?.();
     const httpServer = http.createServer(async (req, res) => {
         try {
-            if (!authOk(req.headers["authorization"], httpToken)) {
-                res.writeHead(401, { "Content-Type": "text/plain" }).end("unauthorized");
-                return;
-            }
             const url = new URL(req.url || "/", `http://${host}`);
+            if (oauthRoutes && (await oauthRoutes.handle(req, res, url)))
+                return;
             if (url.pathname !== "/mcp") {
                 res.writeHead(404, { "Content-Type": "text/plain" }).end("not found — MCP endpoint is /mcp");
                 return;
             }
+            let delegated;
+            if (oauthConfig && oauthVerifier) {
+                const token = bearerToken(req.headers["authorization"]);
+                delegated = token ? await oauthVerifier.verify(token) : null;
+                if (!delegated) {
+                    oauthUnauthorized(res, oauthConfig.metadataUrl, oauthConfig.scope);
+                    return;
+                }
+            }
+            else if (!authOk(req.headers["authorization"], httpToken)) {
+                res.writeHead(401, { "Content-Type": "text/plain" }).end("unauthorized");
+                return;
+            }
             const sid = req.headers["mcp-session-id"];
+            const existingEntry = sid ? sessions.get(sid) : undefined;
+            if (existingEntry?.authorization &&
+                delegated &&
+                existingEntry.authorization.binding !== authorizationBinding(delegated)) {
+                oauthUnauthorized(res, oauthConfig.metadataUrl, oauthConfig.scope);
+                return;
+            }
+            if (existingEntry?.authorization && delegated) {
+                existingEntry.authorization.apiDelegationToken = delegated.apiDelegationToken;
+            }
             if (req.method === "POST") {
                 let body;
                 try {
@@ -172,20 +212,30 @@ export function startHttp(client, port) {
                         .end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }));
                     return;
                 }
-                let entry = sid ? sessions.get(sid) : undefined;
+                let entry = existingEntry;
                 if (!entry && isInitializeRequest(body)) {
                     if (sessions.size >= MAX_SESSIONS) {
                         res.writeHead(503, { "Content-Type": "text/plain" }).end("too many sessions");
                         return;
                     }
+                    const sessionAuthorization = delegated
+                        ? {
+                            binding: authorizationBinding(delegated),
+                            apiDelegationToken: delegated.apiDelegationToken,
+                        }
+                        : undefined;
                     const transport = new StreamableHTTPServerTransport({
                         sessionIdGenerator: () => randomUUID(),
                         // DNS-rebinding defense: only accept these Host headers, so a rebound
                         // attacker-domain request from a browser is rejected.
                         enableDnsRebindingProtection: true,
-                        allowedHosts: allowedHostsFor(httpServer, host, port),
+                        allowedHosts: allowedHostsFor(httpServer, host, port, oauthConfig?.publicUrl),
                         onsessioninitialized: (id) => {
-                            sessions.set(id, { transport, lastSeen: Date.now() });
+                            sessions.set(id, {
+                                transport,
+                                lastSeen: Date.now(),
+                                ...(sessionAuthorization ? { authorization: sessionAuthorization } : {}),
+                            });
                         },
                     });
                     transport.onclose = () => {
@@ -193,8 +243,18 @@ export function startHttp(client, port) {
                         if (id)
                             sessions.delete(id);
                     };
-                    await createServer(client).connect(transport);
-                    entry = { transport, lastSeen: Date.now() };
+                    const sessionClient = delegated
+                        ? new TenkiClient("", process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || undefined, {
+                            workspaceId: delegated.workspaceId,
+                            bearerTokenProvider: () => sessionAuthorization.apiDelegationToken,
+                        })
+                        : client;
+                    await createServer(sessionClient).connect(transport);
+                    entry = {
+                        transport,
+                        lastSeen: Date.now(),
+                        ...(sessionAuthorization ? { authorization: sessionAuthorization } : {}),
+                    };
                 }
                 if (!entry) {
                     res.writeHead(400, { "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "No valid session; send an initialize request first." }, id: null }));
@@ -228,7 +288,7 @@ export function startHttp(client, port) {
     httpServer.on("close", () => clearInterval(sweep));
     httpServer.listen(port, host, () => {
         console.error(`tenki-mcp running on http://${host}:${port}/mcp (Streamable HTTP)` +
-            (httpToken ? " [bearer auth required]" : " [loopback only, no auth]"));
+            (oauthConfig ? " [OAuth required]" : httpToken ? " [bearer auth required]" : " [loopback only, no auth]"));
     });
     return httpServer;
 }

package/dist/index.js

@@ -23,7 +23,8 @@ import { startHttp } from "./http.js";
 // tenki_auth_status registered (see createServer), so an agent can ask what is
 // wrong and relay the fix.
 const token = process.env.TENKI_AUTH_TOKEN || process.env.TENKI_API_KEY;
-if (!token) {
+const oauthHttp = Boolean(process.env.TENKI_MCP_OAUTH_ISSUER);
+if (!token && !oauthHttp) {
     console.error("tenki-mcp: no credential — starting in unauthenticated mode (only tenki_auth_status is available). " +
         "Set TENKI_API_KEY (tk_…) or TENKI_AUTH_TOKEN (ory_st_…) in the server's env and restart, " +
         "e.g. claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y @tenkicloud/mcp");

package/dist/oauth.d.ts

@@ -0,0 +1,33 @@
+import type http from "node:http";
+export interface OAuthConfig {
+    issuer: string;
+    resource: string;
+    publicUrl: string;
+    metadataUrl: string;
+    identityUrl: string;
+    identityServiceToken: string;
+    scope: string;
+}
+export interface DelegatedAuthorization {
+    tokenDigest: string;
+    subject: string;
+    workspaceId: string;
+    clientId: string;
+    scope: string[];
+    expiresAt?: number;
+    apiDelegationToken: string;
+}
+export declare function loadOAuthConfig(): OAuthConfig | null;
+export declare class OAuthTokenVerifier {
+    private readonly config;
+    private readonly cache;
+    constructor(config: OAuthConfig);
+    verify(token: string): Promise<DelegatedAuthorization | null>;
+}
+export declare class OAuthResourceRoutes {
+    private readonly config;
+    constructor(config: OAuthConfig);
+    handle(_req: http.IncomingMessage, res: http.ServerResponse, url: URL): Promise<boolean>;
+}
+export declare function bearerToken(header: string | undefined): string | null;
+export declare function authorizationBinding(authorization: DelegatedAuthorization): string;

package/dist/oauth.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+const DEFAULT_SCOPE = "mcp";
+const FETCH_TIMEOUT_MS = 8_000;
+const TOKEN_CACHE_MS = 15_000;
+const EXCHANGE_PROCEDURE = "/tenki.cloud.identity.private.v1beta1.IdentityPrivateService/ExchangeMcpOAuthToken";
+function trimUrl(value) {
+    return value.trim().replace(/\/+$/, "");
+}
+export function loadOAuthConfig() {
+    const issuer = trimUrl(process.env.TENKI_MCP_OAUTH_ISSUER || "");
+    const identityUrl = trimUrl(process.env.TENKI_MCP_IDENTITY_URL || "");
+    const identityServiceToken = (process.env.TENKI_MCP_IDENTITY_SERVICE_TOKEN || "").trim();
+    const publicUrl = trimUrl(process.env.TENKI_MCP_PUBLIC_URL || "");
+    if (!issuer && !identityUrl && !identityServiceToken && !publicUrl)
+        return null;
+    if (!issuer || !identityUrl || !identityServiceToken || !publicUrl) {
+        throw new Error("TENKI_MCP_OAUTH_ISSUER, TENKI_MCP_IDENTITY_URL, TENKI_MCP_IDENTITY_SERVICE_TOKEN, and TENKI_MCP_PUBLIC_URL must be set together.");
+    }
+    const resource = trimUrl(process.env.TENKI_MCP_OAUTH_RESOURCE || `${publicUrl}/mcp`);
+    return {
+        issuer,
+        resource,
+        publicUrl,
+        metadataUrl: `${publicUrl}/.well-known/oauth-protected-resource/mcp`,
+        identityUrl,
+        identityServiceToken,
+        scope: (process.env.TENKI_MCP_OAUTH_SCOPE || DEFAULT_SCOPE).trim(),
+    };
+}
+function tokenDigest(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+async function fetchJson(url, init = {}) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    const text = await response.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`upstream returned non-JSON HTTP ${response.status}`);
+    }
+    if (!response.ok)
+        throw new Error(`upstream returned HTTP ${response.status}`);
+    return body;
+}
+export class OAuthTokenVerifier {
+    config;
+    cache = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    async verify(token) {
+        const digest = tokenDigest(token);
+        const cached = this.cache.get(digest);
+        if (cached && cached.cachedUntil > Date.now())
+            return cached.authorization;
+        let body;
+        try {
+            body = await fetchJson(`${this.config.identityUrl}${EXCHANGE_PROCEDURE}`, {
+                method: "POST",
+                headers: {
+                    "X-Service-Token": this.config.identityServiceToken,
+                    "Content-Type": "application/json",
+                    "Connect-Protocol-Version": "1",
+                },
+                body: JSON.stringify({ accessToken: token }),
+            });
+        }
+        catch {
+            return null;
+        }
+        const subject = typeof body.subject === "string" ? body.subject.trim() : "";
+        const workspaceId = typeof body.workspaceId === "string" ? body.workspaceId.trim() : "";
+        const clientId = typeof body.clientId === "string" ? body.clientId.trim() : "";
+        const apiDelegationToken = typeof body.apiDelegationToken === "string" ? body.apiDelegationToken.trim() : "";
+        const scope = stringArray(body.scopes);
+        const expiresAtUnix = Number(body.expiresAtUnix);
+        const expiresAt = Number.isFinite(expiresAtUnix) ? expiresAtUnix * 1000 : undefined;
+        if (!subject ||
+            !workspaceId ||
+            !clientId ||
+            !apiDelegationToken ||
+            !scope.includes(this.config.scope) ||
+            (expiresAt !== undefined && expiresAt <= Date.now())) {
+            return null;
+        }
+        const authorization = {
+            tokenDigest: digest,
+            subject,
+            workspaceId,
+            clientId,
+            scope,
+            ...(expiresAt !== undefined ? { expiresAt } : {}),
+            apiDelegationToken,
+        };
+        this.cache.set(digest, {
+            authorization,
+            cachedUntil: Math.min(Date.now() + TOKEN_CACHE_MS, expiresAt ?? Number.POSITIVE_INFINITY),
+        });
+        return authorization;
+    }
+}
+function json(res, status, body) {
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        Pragma: "no-cache",
+    });
+    res.end(JSON.stringify(body));
+}
+export class OAuthResourceRoutes {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async handle(_req, res, url) {
+        if (url.pathname === "/.well-known/oauth-protected-resource/mcp" || url.pathname === "/.well-known/oauth-protected-resource") {
+            json(res, 200, {
+                resource: this.config.resource,
+                authorization_servers: [this.config.issuer],
+                scopes_supported: [this.config.scope, "offline_access"],
+                bearer_methods_supported: ["header"],
+                resource_name: "Tenki MCP",
+            });
+            return true;
+        }
+        if (url.pathname === "/healthz") {
+            json(res, 200, { status: "ok" });
+            return true;
+        }
+        return false;
+    }
+}
+export function bearerToken(header) {
+    const match = /^Bearer (.+)$/.exec(header ?? "");
+    return match?.[1]?.trim() || null;
+}
+export function authorizationBinding(authorization) {
+    return createHash("sha256")
+        .update(JSON.stringify([authorization.subject, authorization.workspaceId, authorization.clientId]))
+        .digest("hex");
+}

package/dist/server.d.ts

@@ -14,7 +14,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "./client.js";
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";
 type Cls = "read" | "write" | "destructive";
 export declare function classifyTool(name: string): Cls;
 /**

package/dist/server.js

@@ -30,7 +30,7 @@ import { registerWorkspace } from "./tools/workspace.js";
 import { registerArtifacts } from "./tools/artifacts.js";
 import { registerSsh } from "./tools/ssh.js";
 import { registerAuthStatus } from "./tools/auth_status.js";
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.0";
 const modules = [
     registerIdentity,
     registerRun,

package/dist/tools/auth_status.d.ts

@@ -13,8 +13,8 @@
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";
-/** How a credential was supplied, derived from the token's prefix. */
-export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "session_cookie";
+/** How the server authenticates API calls. */
+export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "session_cookie" | "hosted_oauth";
 export interface CredentialInfo {
     kind: CredentialKind;
     /** Env var the token came from, or undefined when there is none. */

package/dist/tools/auth_status.js

@@ -9,6 +9,8 @@ export function describeCredential(env = process.env) {
     const fromToken = env.TENKI_AUTH_TOKEN?.trim();
     const fromKey = env.TENKI_API_KEY?.trim();
     const raw = fromToken || fromKey;
+    if (!raw && env.TENKI_MCP_OAUTH_ISSUER?.trim())
+        return { kind: "hosted_oauth" };
     if (!raw)
         return { kind: "none" };
     const source = fromToken ? "TENKI_AUTH_TOKEN" : "TENKI_API_KEY";
@@ -23,12 +25,13 @@ const CREDENTIAL_HELP = {
     api_key: "Authenticated with a tk_… API key (Authorization: Bearer).",
     oauth_session_token: "Authenticated with an ory_st_… session token (X-Session-Token). Session tokens expire; an API key is the stabler choice for a long-running server.",
     session_cookie: "Authenticated with a session cookie (the token matched neither the tk_ nor ory_st_ prefix, so it is sent as a tenki_session cookie). If that is not what you intended, check the value.",
+    hosted_oauth: "Authenticated through the hosted OAuth session for this MCP connection.",
 };
 const authOutputSchema = {
     authenticated: z.boolean().describe("True only when a credential is present AND a live identity probe succeeded."),
     credential: z
-        .enum(["none", "api_key", "oauth_session_token", "session_cookie"])
-        .describe("Kind of credential the server is running with, derived from its prefix. Never includes the token itself."),
+        .enum(["none", "api_key", "oauth_session_token", "session_cookie", "hosted_oauth"])
+        .describe("Kind of credential the server is running with. Never includes the token itself."),
     source: z
         .string()
         .optional()
@@ -96,7 +99,9 @@ export function registerAuthStatus(server, client, toolsRegistered) {
                 ...base,
                 authenticated: false,
                 error: e.message,
-                detail: `A ${cred.kind === "api_key" ? "tk_… API key" : "credential"} is set (from ${cred.source}) but the identity probe failed — it may be expired, revoked, or the endpoint may be wrong. ${CREDENTIAL_HELP.none}`,
+                detail: cred.kind === "hosted_oauth"
+                    ? "The hosted OAuth session is present, but the identity probe failed. Run MCP login again."
+                    : `A ${cred.kind === "api_key" ? "tk_… API key" : "credential"} is set (from ${cred.source}) but the identity probe failed — it may be expired, revoked, or the endpoint may be wrong. ${CREDENTIAL_HELP.none}`,
             };
             return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenkicloud/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "io.github.LuxorLabs/tenki-mcp",
   "description": "Model Context Protocol server for Tenki Cloud — disposable microVM sandboxes for AI agents. Create sandboxes, run code, read/write files, run git, expose preview URLs — from any MCP client.",
   "type": "module",
@@ -21,7 +21,7 @@
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
-    "test": "node test/offline.test.mjs && node test/public-shapes.test.mjs && node test/exec-output.test.mjs && node test/http-input.test.mjs && node test/security.test.mjs && node test/client-net.test.mjs",
+    "test": "node test/offline.test.mjs && node test/public-shapes.test.mjs && node test/exec-output.test.mjs && node test/http-input.test.mjs && node test/oauth-http.test.mjs && node test/security.test.mjs && node test/client-net.test.mjs",
     "test:all": "npm run build && node test/run.mjs",
     "test:offline": "npm run build && node test/offline.test.mjs"
   },