@venturekit/mcp 0.0.0-dev.20260608102211

package/dist/migrations/vk_mcp_0001_tokens.sql

@@ -0,0 +1,63 @@
+-- @venturekit/mcp — initial schema: mcp_tokens.
+--
+-- Storage for the bearer tokens an MCP server issues to agents
+-- (Cascade/Windsurf workflows, CI bots, scripts). Ships WITH the
+-- package so any app that depends on `@venturekit/mcp` gets token
+-- management out of the box — `vk migrate` auto-discovers this file via
+-- the package's `vk.migrations` field (mirrors @venturekit-pro/audit's
+-- `audit_events`).
+--
+-- # Generic by construction
+--
+-- The package owns the MCP protocol, not any host's tenancy model, so
+-- the owner key is a free-form `scope` (text) — NOT a foreign key into
+-- some `tenants` table that only the CMS has. A host maps `scope` to
+-- whatever it owns: the VentureKit CMS uses the tenant slug (which is
+-- also the token's `vk_<scope>_…` segment, letting the verifier resolve
+-- the owner before hashing). `created_by` is likewise a bare text audit
+-- field (a Cognito sub, a user id, a CI run id — the host decides), with
+-- no FK.
+--
+-- # Security
+--
+-- Only a hash of the plaintext + a short lookup `prefix` are stored; the
+-- plaintext is shown once at issuance and is unrecoverable. The hash is
+-- scrypt (see `store.ts:hashTokenSecret`) — self-describing
+-- (`scrypt$N$r$p$salt$dk`) so params can evolve without a column change.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS mcp_tokens (
+  id            uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- Owner key. Host-defined; the CMS uses the tenant slug. Also the
+  -- `vk_<scope>_…` segment of the plaintext, so the verifier can narrow
+  -- to one owner before hashing.
+  scope         text         NOT NULL,
+  -- Human label shown in the issuing UI ("Cascade workflow", "CI bot").
+  label         text         NOT NULL,
+  -- First chars of the plaintext (`vk_<scope>_…`) — the lookup key the
+  -- verifier narrows on before hash-comparing candidates.
+  prefix        varchar(24)  NOT NULL,
+  -- scrypt hash of the full plaintext (`scrypt$N$r$p$salt$dk`).
+  token_hash    text         NOT NULL,
+  -- Comma-separated MCP tool whitelist; NULL = every registered tool.
+  allowed_tools text,
+  last_used_at  timestamptz,
+  revoked_at    timestamptz,
+  created_at    timestamptz  NOT NULL DEFAULT now(),
+  -- Free-form audit field (no FK): a user id / Cognito sub / CI id.
+  created_by    text
+);
+
+-- Label is unique per scope: stops accidental dupes in the UI and
+-- bounds the verifier's prefix-collision hash loop.
+CREATE UNIQUE INDEX IF NOT EXISTS mcp_tokens_scope_label_unique
+  ON mcp_tokens (scope, lower(label));
+
+-- Verifier hot path: WHERE scope = $1 AND prefix = $2 AND revoked_at IS NULL.
+CREATE INDEX IF NOT EXISTS mcp_tokens_lookup_idx
+  ON mcp_tokens (scope, prefix) WHERE revoked_at IS NULL;
+
+-- Owner list: WHERE scope = $1 ORDER BY created_at DESC.
+CREATE INDEX IF NOT EXISTS mcp_tokens_scope_created_idx
+  ON mcp_tokens (scope, created_at DESC);

package/dist/path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Migrations-dir helper.
+ *
+ * `vk migrate` auto-discovers a package's migrations via its
+ * `vk.migrations` field, so most apps need nothing here. This export is
+ * the explicit escape hatch: a host that disables auto-discovery can
+ * wire it into `vk.config.ts:extraMigrationsDirs`:
+ *
+ * ```ts
+ * import { getMcpMigrationsDir } from '@venturekit/mcp';
+ * export default defineVenture({ extraMigrationsDirs: [getMcpMigrationsDir()] });
+ * ```
+ *
+ * The directory is bundled into the build (via `files: ["src/migrations/*.sql"]`
+ * in package.json, mirrored into `dist/migrations/` by the build script).
+ * Apps consuming the source via a workspace symlink read from
+ * `src/migrations/`. Both layouts resolve to a `migrations/` dir next to
+ * this module, so a single path works for both.
+ */
+/** Absolute path to the `mcp_tokens` migration files (`vk_mcp_*.sql`). */
+export declare function getMcpMigrationsDir(): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,0EAA0E;AAC1E,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C"}

package/dist/path.js

@@ -0,0 +1,27 @@
+/**
+ * Migrations-dir helper.
+ *
+ * `vk migrate` auto-discovers a package's migrations via its
+ * `vk.migrations` field, so most apps need nothing here. This export is
+ * the explicit escape hatch: a host that disables auto-discovery can
+ * wire it into `vk.config.ts:extraMigrationsDirs`:
+ *
+ * ```ts
+ * import { getMcpMigrationsDir } from '@venturekit/mcp';
+ * export default defineVenture({ extraMigrationsDirs: [getMcpMigrationsDir()] });
+ * ```
+ *
+ * The directory is bundled into the build (via `files: ["src/migrations/*.sql"]`
+ * in package.json, mirrored into `dist/migrations/` by the build script).
+ * Apps consuming the source via a workspace symlink read from
+ * `src/migrations/`. Both layouts resolve to a `migrations/` dir next to
+ * this module, so a single path works for both.
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Absolute path to the `mcp_tokens` migration files (`vk_mcp_*.sql`). */
+export function getMcpMigrationsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(here, 'migrations');
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Transport-agnostic MCP JSON-RPC dispatcher.
+ *
+ * Implements the slice of the MCP wire protocol an HTTP/JSON-RPC client
+ * (e.g. Windsurf/Cascade's built-in HTTP MCP transport) needs:
+ * `initialize`, `notifications/initialized`, `ping`, `tools/list`,
+ * `tools/call`. It is deliberately stateless (one request -> one
+ * response), which suits a Lambda or any request/response transport.
+ *
+ * Everything app-specific — authentication, rate limiting, audit
+ * wrapping, per-call context assembly — is injected via
+ * {@link McpServerConfig} hooks, so this loop carries no host concern.
+ */
+import type { McpHandlerInput, McpHandlerOutput, McpServerConfig } from './types.js';
+/**
+ * Handle a single MCP JSON-RPC request against `config`. Never throws for
+ * an expected client/auth/rate-limit failure — those become a structured
+ * `{ statusCode, response }` pair. A tool that throws is reported per the
+ * MCP spec as a *successful* response with `isError: true`.
+ */
+export declare function handleMcpRequest<TContext, TPrincipal>(config: McpServerConfig<TContext, TPrincipal>, input: McpHandlerInput): Promise<McpHandlerOutput>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,gBAAgB,EAChB,eAAe,EAEhB,MAAM,YAAY,CAAC;AA+DpB;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EACzD,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC7C,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAwI3B"}

package/dist/server.js

@@ -0,0 +1,177 @@
+/**
+ * Transport-agnostic MCP JSON-RPC dispatcher.
+ *
+ * Implements the slice of the MCP wire protocol an HTTP/JSON-RPC client
+ * (e.g. Windsurf/Cascade's built-in HTTP MCP transport) needs:
+ * `initialize`, `notifications/initialized`, `ping`, `tools/list`,
+ * `tools/call`. It is deliberately stateless (one request -> one
+ * response), which suits a Lambda or any request/response transport.
+ *
+ * Everything app-specific — authentication, rate limiting, audit
+ * wrapping, per-call context assembly — is injected via
+ * {@link McpServerConfig} hooks, so this loop carries no host concern.
+ */
+import { zodToJsonSchema } from './json-schema.js';
+const DEFAULT_PROTOCOL_VERSION = '2025-03-26';
+function rpcError(id, code, message, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code, message, ...(data === undefined ? {} : { data }) },
+    };
+}
+/**
+ * Translate an arbitrary thrown value into JSON-RPC error fields. Honors
+ * a numeric `statusCode` / `rpcCode` and a structured `data` when the
+ * error carries them (so a host's bespoke error classes need not extend
+ * {@link McpError}); also lifts a bare `retryAfterSec` into `data`.
+ */
+function mapError(err, fallbackStatus, fallbackRpc) {
+    const e = (typeof err === 'object' && err !== null ? err : {});
+    const statusCode = typeof e.statusCode === 'number' ? e.statusCode : fallbackStatus;
+    const rpcCode = typeof e.rpcCode === 'number' ? e.rpcCode : fallbackRpc;
+    const message = err instanceof Error ? err.message : String(err);
+    let data = e.data;
+    if (data === undefined && typeof e.retryAfterSec === 'number') {
+        data = { retryAfterSec: e.retryAfterSec };
+    }
+    return { statusCode, rpcCode, message, data };
+}
+function toToolDescriptor(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: zodToJsonSchema(tool.inputSchema),
+    };
+}
+function normalizeId(value) {
+    return typeof value === 'number' || typeof value === 'string' ? value : null;
+}
+/**
+ * Handle a single MCP JSON-RPC request against `config`. Never throws for
+ * an expected client/auth/rate-limit failure — those become a structured
+ * `{ statusCode, response }` pair. A tool that throws is reported per the
+ * MCP spec as a *successful* response with `isError: true`.
+ */
+export async function handleMcpRequest(config, input) {
+    const body = input.body;
+    if (!body || body.jsonrpc !== '2.0' || typeof body.method !== 'string') {
+        return {
+            statusCode: 400,
+            response: rpcError(normalizeId(body?.id), -32600, 'Invalid JSON-RPC request'),
+        };
+    }
+    const id = normalizeId(body.id);
+    const method = body.method;
+    const params = (body.params ?? {});
+    // Authenticate up-front for every method (incl. `initialize`) so the
+    // principal is validated before any work and a single auth decision
+    // governs the whole request.
+    let auth;
+    try {
+        auth = await config.authenticate(input.authHeader);
+    }
+    catch (err) {
+        const f = mapError(err, 401, -32001);
+        return { statusCode: f.statusCode, response: rpcError(id, f.rpcCode, f.message, f.data) };
+    }
+    const protocolVersion = config.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+    switch (method) {
+        case 'initialize':
+            return {
+                statusCode: 200,
+                response: {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion,
+                        capabilities: { tools: {} },
+                        serverInfo: config.serverInfo,
+                    },
+                },
+            };
+        case 'notifications/initialized':
+            return { statusCode: 204, response: { jsonrpc: '2.0', id, result: {} } };
+        case 'ping':
+            return { statusCode: 200, response: { jsonrpc: '2.0', id, result: {} } };
+        case 'tools/list': {
+            const tools = Object.values(config.tools)
+                .filter((t) => !auth.allowedTools || auth.allowedTools.has(t.name))
+                .map(toToolDescriptor);
+            return { statusCode: 200, response: { jsonrpc: '2.0', id, result: { tools } } };
+        }
+        case 'tools/call': {
+            const callParams = params;
+            const toolName = String(callParams.name ?? '');
+            const tool = config.tools[toolName];
+            if (!tool) {
+                return { statusCode: 404, response: rpcError(id, -32601, `Unknown tool '${toolName}'`) };
+            }
+            if (auth.allowedTools && !auth.allowedTools.has(toolName)) {
+                return {
+                    statusCode: 403,
+                    response: rpcError(id, -32603, `Token not allowed to call '${toolName}'`),
+                };
+            }
+            // Rate-limit BEFORE schema validation + dispatch so a flooded
+            // principal can't burn quota by sending malformed args.
+            if (config.rateLimit) {
+                try {
+                    await config.rateLimit(auth.principal, toolName);
+                }
+                catch (err) {
+                    const f = mapError(err, 429, -32029);
+                    return { statusCode: f.statusCode, response: rpcError(id, f.rpcCode, f.message, f.data) };
+                }
+            }
+            const parsed = tool.inputSchema.safeParse(callParams.arguments ?? {});
+            if (!parsed.success) {
+                return {
+                    statusCode: 422,
+                    response: rpcError(id, -32602, 'Invalid tool arguments', {
+                        issues: parsed.error.issues,
+                    }),
+                };
+            }
+            try {
+                const ctx = await config.createContext(auth.principal, toolName);
+                const invoke = () => tool.run(parsed.data, ctx);
+                const result = config.wrapToolCall
+                    ? await config.wrapToolCall({ toolName, input: parsed.data, principal: auth.principal }, invoke)
+                    : await invoke();
+                return {
+                    statusCode: 200,
+                    response: {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: JSON.stringify(result) }],
+                            structuredContent: result,
+                            isError: false,
+                        },
+                    },
+                };
+            }
+            catch (err) {
+                // Per the MCP spec, tool execution failures are wrapped in a
+                // *successful* response with `isError: true` rather than a
+                // JSON-RPC error — the agent reads the message and recovers.
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    statusCode: 200,
+                    response: {
+                        jsonrpc: '2.0',
+                        id,
+                        result: { content: [{ type: 'text', text: message }], isError: true },
+                    },
+                };
+            }
+        }
+        default:
+            return {
+                statusCode: 404,
+                response: rpcError(id, -32601, `Method '${method}' not implemented`),
+            };
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Postgres-backed token store for MCP bearer credentials.
+ *
+ * Ships with the package so a host gets MCP token management out of the
+ * box: a single `mcp_tokens` table (migration
+ * `migrations/vk_mcp_0001_tokens.sql`, auto-discovered by `vk migrate`)
+ * plus the CRUD + verify functions here. The host supplies a
+ * {@link Querier} (e.g. `@venturekit/data`'s `query`) and maps `scope`
+ * to whatever it owns — a tenant slug, a user id, a project id.
+ *
+ * # Security
+ *   - Only a scrypt hash + the lookup `prefix` are persisted. The
+ *     plaintext is returned once from {@link createMcpToken} and never
+ *     stored.
+ *   - {@link verifyMcpToken} narrows by `(scope, prefix)` then runs a
+ *     constant-time scrypt compare over the (normally single) candidate.
+ *   - Hashing is `node:crypto` scrypt — no third-party dependency.
+ */
+/**
+ * Minimal querier shape — a function that runs a parameterized SQL
+ * statement and returns rows. Matches `@venturekit/data`'s `Querier`
+ * so a consumer can pass `query` directly, while staying structural so
+ * any Postgres driver can be adapted.
+ */
+export type Querier = <T = Record<string, unknown>[]>(sql: string, params?: unknown[]) => Promise<T>;
+/**
+ * Persisted token row (snake_case columns mapped to camelCase, which is
+ * what `@venturekit/data` returns). The plaintext is NEVER a column.
+ */
+export interface McpTokenRow {
+    id: string;
+    /** Host-defined owner key (the CMS uses the tenant slug). */
+    scope: string;
+    label: string;
+    /** Non-secret lookup prefix (first chars of the plaintext). */
+    prefix: string;
+    /** scrypt hash (`scrypt$N$r$p$salt$dk`). */
+    tokenHash: string;
+    /** Comma-separated tool whitelist; `null` = every tool. */
+    allowedTools: string | null;
+    lastUsedAt: Date | null;
+    revokedAt: Date | null;
+    createdAt: Date;
+    createdBy: string | null;
+}
+export interface CreateMcpTokenInput {
+    /** Owner key — becomes the token's `vk_<scope>_…` segment. */
+    scope: string;
+    label: string;
+    /** Tool whitelist; empty/omitted → token may call every tool. */
+    allowedTools?: string[] | null;
+    /** Free-form audit id (user id / Cognito sub / CI id). */
+    createdBy?: string | null;
+}
+export interface CreatedMcpToken {
+    row: McpTokenRow;
+    /** The full plaintext token. Surface it once; it is unrecoverable after. */
+    token: string;
+}
+/** scrypt-hash a token plaintext into a self-describing `scrypt$…` string. */
+export declare function hashTokenSecret(plaintext: string): Promise<string>;
+/** Constant-time verify a plaintext against a stored `scrypt$…` hash. */
+export declare function verifyTokenSecret(plaintext: string, stored: string): Promise<boolean>;
+/** List every token for an owner, newest-first (incl. revoked). */
+export declare function listMcpTokens(q: Querier, scope: string): Promise<McpTokenRow[]>;
+/** Mint a token for `scope`. Returns the persisted row + the plaintext (once). */
+export declare function createMcpToken(q: Querier, input: CreateMcpTokenInput): Promise<CreatedMcpToken>;
+/**
+ * Revoke a token (idempotent — re-revoking preserves the original
+ * `revoked_at`). Returns `null` when the id doesn't exist for `scope`.
+ */
+export declare function revokeMcpToken(q: Querier, scope: string, id: string): Promise<McpTokenRow | null>;
+/**
+ * Resolve a plaintext bearer token to its active row, or `null` if the
+ * token is malformed, unknown, or revoked. Parses the scope from the
+ * token, narrows by `(scope, prefix)`, scrypt-verifies each candidate,
+ * and stamps `last_used_at` on a match (best-effort; failures don't
+ * block auth). The host is responsible for any further checks (e.g.
+ * mapping `scope` to a tenant and rejecting suspended ones).
+ */
+export declare function verifyMcpToken(q: Querier, plaintext: string): Promise<McpTokenRow | null>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAsBH;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClD,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC/B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,WAAW,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf;AAID,8EAA8E;AAC9E,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQxE;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY3F;AAID,mEAAmE;AACnE,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAKrF;AAID,kFAAkF;AAClF,wBAAsB,cAAc,CAClC,CAAC,EAAE,OAAO,EACV,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,eAAe,CAAC,CAe1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,CAAC,EAAE,OAAO,EACV,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAS7B;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB/F"}

package/dist/store.js

@@ -0,0 +1,111 @@
+/**
+ * Postgres-backed token store for MCP bearer credentials.
+ *
+ * Ships with the package so a host gets MCP token management out of the
+ * box: a single `mcp_tokens` table (migration
+ * `migrations/vk_mcp_0001_tokens.sql`, auto-discovered by `vk migrate`)
+ * plus the CRUD + verify functions here. The host supplies a
+ * {@link Querier} (e.g. `@venturekit/data`'s `query`) and maps `scope`
+ * to whatever it owns — a tenant slug, a user id, a project id.
+ *
+ * # Security
+ *   - Only a scrypt hash + the lookup `prefix` are persisted. The
+ *     plaintext is returned once from {@link createMcpToken} and never
+ *     stored.
+ *   - {@link verifyMcpToken} narrows by `(scope, prefix)` then runs a
+ *     constant-time scrypt compare over the (normally single) candidate.
+ *   - Hashing is `node:crypto` scrypt — no third-party dependency.
+ */
+import { randomBytes, scrypt as scryptCb, timingSafeEqual, } from 'node:crypto';
+import { promisify } from 'node:util';
+import { generateBearerToken, bearerTokenPrefix, parseScopedToken } from './tokens.js';
+const scrypt = promisify(scryptCb);
+// scrypt cost parameters. N=16384 keeps a single hash ~50-80ms (on par
+// with bcrypt cost 12) while staying under Node's default 32MB maxmem
+// (128 * N * r = 16MB).
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_KEYLEN = 32;
+// ─── Hashing ────────────────────────────────────────────────────────
+/** scrypt-hash a token plaintext into a self-describing `scrypt$…` string. */
+export async function hashTokenSecret(plaintext) {
+    const salt = randomBytes(16);
+    const dk = (await scrypt(plaintext, salt, SCRYPT_KEYLEN, {
+        N: SCRYPT_N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+    }));
+    return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt.toString('base64')}$${dk.toString('base64')}`;
+}
+/** Constant-time verify a plaintext against a stored `scrypt$…` hash. */
+export async function verifyTokenSecret(plaintext, stored) {
+    const parts = stored.split('$');
+    if (parts.length !== 6 || parts[0] !== 'scrypt')
+        return false;
+    const n = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    if (!Number.isInteger(n) || !Number.isInteger(r) || !Number.isInteger(p))
+        return false;
+    const salt = Buffer.from(parts[4], 'base64');
+    const expected = Buffer.from(parts[5], 'base64');
+    if (expected.length === 0)
+        return false;
+    const dk = (await scrypt(plaintext, salt, expected.length, { N: n, r, p }));
+    return dk.length === expected.length && timingSafeEqual(dk, expected);
+}
+// ─── Read ───────────────────────────────────────────────────────────
+/** List every token for an owner, newest-first (incl. revoked). */
+export async function listMcpTokens(q, scope) {
+    return q(`SELECT * FROM mcp_tokens WHERE scope = $1 ORDER BY created_at DESC`, [scope]);
+}
+// ─── Write ──────────────────────────────────────────────────────────
+/** Mint a token for `scope`. Returns the persisted row + the plaintext (once). */
+export async function createMcpToken(q, input) {
+    const { token, prefix } = generateBearerToken({ scope: input.scope });
+    const tokenHash = await hashTokenSecret(token);
+    const allowedTools = input.allowedTools && input.allowedTools.length > 0 ? input.allowedTools.join(',') : null;
+    const rows = await q(`INSERT INTO mcp_tokens (scope, label, prefix, token_hash, allowed_tools, created_by)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     RETURNING *`, [input.scope, input.label, prefix, tokenHash, allowedTools, input.createdBy ?? null]);
+    const row = rows[0];
+    if (!row)
+        throw new Error('[mcp/createMcpToken] INSERT ... RETURNING returned no rows');
+    return { row, token };
+}
+/**
+ * Revoke a token (idempotent — re-revoking preserves the original
+ * `revoked_at`). Returns `null` when the id doesn't exist for `scope`.
+ */
+export async function revokeMcpToken(q, scope, id) {
+    const rows = await q(`UPDATE mcp_tokens
+        SET revoked_at = COALESCE(revoked_at, NOW())
+      WHERE scope = $1 AND id = $2
+      RETURNING *`, [scope, id]);
+    return rows[0] ?? null;
+}
+/**
+ * Resolve a plaintext bearer token to its active row, or `null` if the
+ * token is malformed, unknown, or revoked. Parses the scope from the
+ * token, narrows by `(scope, prefix)`, scrypt-verifies each candidate,
+ * and stamps `last_used_at` on a match (best-effort; failures don't
+ * block auth). The host is responsible for any further checks (e.g.
+ * mapping `scope` to a tenant and rejecting suspended ones).
+ */
+export async function verifyMcpToken(q, plaintext) {
+    const parsed = parseScopedToken(plaintext);
+    if (!parsed)
+        return null;
+    const prefix = bearerTokenPrefix(plaintext);
+    const candidates = await q(`SELECT * FROM mcp_tokens WHERE scope = $1 AND prefix = $2 AND revoked_at IS NULL`, [parsed.scope, prefix]);
+    for (const row of candidates) {
+        if (await verifyTokenSecret(plaintext, row.tokenHash)) {
+            // Best-effort touch — never block a valid auth on a stats write.
+            Promise.resolve(q(`UPDATE mcp_tokens SET last_used_at = NOW() WHERE id = $1`, [row.id])).catch(() => { });
+            return row;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/tokens.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Opaque bearer-token primitives for MCP servers.
+ *
+ * An MCP server authenticates agents with a long-lived bearer token. A
+ * host issues one, stores only a hash + a short lookup prefix, and shows
+ * the plaintext exactly once. These helpers own the parts that are
+ * identical across every host — the token format, secure generation,
+ * and the prefix/parse helpers — while leaving hashing and storage to
+ * the host, which knows its own DB and crypto policy.
+ *
+ * Token shape: `<scheme>_<scope>_<secret>`, e.g. `vk_acme_Xy3…`.
+ *   - `scheme` namespaces the token (default `vk`).
+ *   - `scope` is an opaque routing hint (e.g. a tenant slug) the host can
+ *     read *before* hashing, to narrow a DB lookup to one tenant. It is
+ *     optional; without it the token is `<scheme>_<secret>`.
+ *   - `secret` is URL-safe base64 (`A-Za-z0-9_-`) random entropy.
+ *
+ * `node:crypto` is the only import (a Node builtin), so the package keeps
+ * its no-third-party-runtime-dependency property.
+ */
+export interface GenerateBearerTokenOptions {
+    /** Token namespace, e.g. `vk`. Default `vk`. Must be lowercase alnum/dash. */
+    scheme?: string;
+    /**
+     * Opaque routing hint (e.g. a tenant slug) embedded before the secret
+     * so the host can resolve the owner before hashing. Lowercase
+     * alnum/dash. Omit for an unscoped `<scheme>_<secret>` token.
+     */
+    scope?: string;
+    /**
+     * Random entropy in bytes, base64url-encoded into the secret. Default
+     * 24 bytes (192 bits → 32 chars). Minimum 16.
+     */
+    byteLength?: number;
+}
+export interface GeneratedBearerToken {
+    /** The full plaintext token. Show it once; never store it. */
+    token: string;
+    /** Stable lookup prefix (see {@link bearerTokenPrefix}); safe to store/display. */
+    prefix: string;
+}
+/** Chars kept from the front of a token as its (non-secret) lookup key. */
+export declare const DEFAULT_PREFIX_LENGTH = 10;
+/**
+ * Mint a new bearer token + its lookup prefix. The secret is drawn from
+ * a CSPRNG (`node:crypto`); the host should hash {@link GeneratedBearerToken.token}
+ * (bcrypt/argon2/SHA-256 — its choice) and persist only the hash + prefix.
+ */
+export declare function generateBearerToken(opts?: GenerateBearerTokenOptions): GeneratedBearerToken;
+/**
+ * The first `length` characters of a token. Stored alongside the hash so
+ * a lookup is `WHERE prefix = ?` (one indexed read) rather than a scan +
+ * hash-compare over every row. NOT a secret — safe to show in a UI.
+ */
+export declare function bearerTokenPrefix(token: string, length?: number): string;
+export interface ParsedScopedToken {
+    scheme: string;
+    scope: string;
+    secret: string;
+}
+/**
+ * Parse a `<scheme>_<scope>_<secret>` token into its parts, or `null` if
+ * the shape doesn't match (callers should fail closed on `null`). The
+ * secret must be at least 16 URL-safe chars, which rejects obviously
+ * truncated or malformed tokens before any DB / hash work.
+ */
+export declare function parseScopedToken(token: string): ParsedScopedToken | null;
+/**
+ * Extract the token from an `Authorization` header value, stripping a
+ * leading `Bearer ` (case-insensitive). Returns the raw value when no
+ * scheme prefix is present, or `null` for an empty/missing header.
+ */
+export declare function parseBearer(header: string | null | undefined): string | null;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAKxC;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,0BAA+B,GACpC,oBAAoB,CAgBtB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAwB,GAAG,MAAM,CAEvF;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CASxE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAW5E"}