@venturekit/mcp 0.0.0-dev.20260608102211

package/dist/tokens.js

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+import { randomBytes } from 'node:crypto';
+const DEFAULT_SCHEME = 'vk';
+const DEFAULT_BYTES = 24;
+const MIN_BYTES = 16;
+/** Chars kept from the front of a token as its (non-secret) lookup key. */
+export const DEFAULT_PREFIX_LENGTH = 10;
+/** A `scheme` / `scope` segment: lowercase alnum, dashes allowed inside. */
+const SEGMENT_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/**
+ * 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 function generateBearerToken(opts = {}) {
+    const scheme = opts.scheme ?? DEFAULT_SCHEME;
+    if (!SEGMENT_RE.test(scheme)) {
+        throw new Error(`Invalid token scheme '${scheme}' (must be lowercase alnum/dash)`);
+    }
+    if (opts.scope !== undefined && !SEGMENT_RE.test(opts.scope)) {
+        throw new Error(`Invalid token scope '${opts.scope}' (must be lowercase alnum/dash)`);
+    }
+    const bytes = opts.byteLength ?? DEFAULT_BYTES;
+    if (!Number.isInteger(bytes) || bytes < MIN_BYTES) {
+        throw new Error(`byteLength must be an integer >= ${MIN_BYTES} for adequate entropy`);
+    }
+    const secret = randomBytes(bytes).toString('base64url');
+    const token = opts.scope ? `${scheme}_${opts.scope}_${secret}` : `${scheme}_${secret}`;
+    return { token, prefix: bearerTokenPrefix(token) };
+}
+/**
+ * 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 function bearerTokenPrefix(token, length = DEFAULT_PREFIX_LENGTH) {
+    return token.slice(0, length);
+}
+/**
+ * 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 function parseScopedToken(token) {
+    const m = /^(?<scheme>[a-z0-9-]+)_(?<scope>[a-z0-9-]+)_(?<secret>[A-Za-z0-9_-]{16,})$/.exec(token);
+    if (!m?.groups)
+        return null;
+    return {
+        scheme: m.groups['scheme'],
+        scope: m.groups['scope'],
+        secret: m.groups['secret'],
+    };
+}
+/**
+ * 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 function parseBearer(header) {
+    if (!header)
+        return null;
+    const trimmed = header.trim();
+    if (!trimmed)
+        return null;
+    const lower = trimmed.toLowerCase();
+    // A bare `Bearer` scheme with no token (e.g. `Bearer   `) carries no credential.
+    if (lower === 'bearer')
+        return null;
+    if (lower.startsWith('bearer ')) {
+        return trimmed.slice(7).trim() || null;
+    }
+    return trimmed;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Core types for the transport-agnostic MCP server.
+ *
+ * The package is intentionally dependency-light: `zod` is a *type-only*
+ * peer dependency (the dispatcher only ever calls `.safeParse` on a
+ * schema the host supplies, and the JSON-Schema serializer reads
+ * `._def` structurally), so nothing here pulls zod in at runtime.
+ *
+ * The two generic parameters thread two host-owned shapes through the
+ * dispatcher:
+ *   - `TContext`   — the per-call value handed to every `McpTool.run`.
+ *                    The CMS uses `{ tenant, actorTokenPrefix, ... }`.
+ *   - `TPrincipal` — the opaque authenticated identity returned by
+ *                    `authenticate` and forwarded to `rateLimit` /
+ *                    `wrapToolCall` / `createContext`. The CMS uses the
+ *                    `{ token, tenant }` pair from its bearer-token check.
+ */
+import type { ZodType, ZodTypeDef } from 'zod';
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+/**
+ * A single callable tool. `inputSchema` is any Zod schema; the `unknown`
+ * Input variance lets schemas using `.default()` (where Zod splits the
+ * Input/Output types so Input becomes optional) satisfy this type.
+ */
+export interface McpTool<TInput = unknown, TContext = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: ZodType<TInput, ZodTypeDef, unknown>;
+    run(args: TInput, ctx: TContext): Promise<TOutput>;
+}
+/** A keyed bag of tools sharing one `TContext`. */
+export type McpToolRegistry<TContext = unknown> = Record<string, McpTool<any, TContext, any>>;
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+/** Outcome of {@link McpServerConfig.authenticate}. */
+export interface McpAuthResult<TPrincipal> {
+    /**
+     * Tool allow-list for this principal. `null` = every registered tool
+     * is callable. A populated set restricts both `tools/list` and
+     * `tools/call`.
+     */
+    allowedTools: ReadonlySet<string> | null;
+    /** Opaque identity forwarded to the other hooks. */
+    principal: TPrincipal;
+}
+/** Metadata handed to {@link McpServerConfig.wrapToolCall}. */
+export interface McpToolCallInfo<TPrincipal> {
+    toolName: string;
+    /** The validated, schema-coerced tool arguments. */
+    input: unknown;
+    principal: TPrincipal;
+}
+/**
+ * Everything the dispatcher needs that is *host-specific*. Authentication,
+ * rate limiting, audit logging, and context assembly are all hooks so the
+ * protocol loop itself stays free of any app concern.
+ */
+export interface McpServerConfig<TContext, TPrincipal> {
+    serverInfo: McpServerInfo;
+    tools: McpToolRegistry<TContext>;
+    /** Defaults to `'2025-03-26'`. */
+    protocolVersion?: string;
+    /**
+     * Resolve + authorize the caller. Throw to reject — errors carrying a
+     * numeric `statusCode` (and optional `rpcCode` / `data` / `retryAfterSec`)
+     * are mapped to the JSON-RPC error response; otherwise a 401 is assumed.
+     */
+    authenticate(authHeader: string | null): Promise<McpAuthResult<TPrincipal>>;
+    /** Build the per-call context passed to the tool's `run`. May be async. */
+    createContext(principal: TPrincipal, toolName: string): TContext | Promise<TContext>;
+    /** Optional pre-dispatch throttle. Throw (ideally an {@link McpError}) to reject. */
+    rateLimit?(principal: TPrincipal, toolName: string): Promise<void>;
+    /** Optional wrapper around each tool invocation (e.g. an audit-log bracket). */
+    wrapToolCall?<T>(info: McpToolCallInfo<TPrincipal>, run: () => Promise<T>): Promise<T>;
+}
+export interface McpHandlerInput {
+    /** The raw `Authorization` header value, or null. */
+    authHeader: string | null;
+    /** The parsed JSON-RPC request body. */
+    body: unknown;
+}
+export interface McpHandlerOutput {
+    /** HTTP status the transport should respond with. */
+    statusCode: number;
+    /** The JSON-RPC envelope to serialize back to the client. */
+    response: JsonRpcResponse;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Core types for the transport-agnostic MCP server.
+ *
+ * The package is intentionally dependency-light: `zod` is a *type-only*
+ * peer dependency (the dispatcher only ever calls `.safeParse` on a
+ * schema the host supplies, and the JSON-Schema serializer reads
+ * `._def` structurally), so nothing here pulls zod in at runtime.
+ *
+ * The two generic parameters thread two host-owned shapes through the
+ * dispatcher:
+ *   - `TContext`   — the per-call value handed to every `McpTool.run`.
+ *                    The CMS uses `{ tenant, actorTokenPrefix, ... }`.
+ *   - `TPrincipal` — the opaque authenticated identity returned by
+ *                    `authenticate` and forwarded to `rateLimit` /
+ *                    `wrapToolCall` / `createContext`. The CMS uses the
+ *                    `{ token, tenant }` pair from its bearer-token check.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@venturekit/mcp",
+  "version": "0.0.0-dev.20260608102211",
+  "description": "Transport-agnostic Model Context Protocol (MCP) server primitives for VentureKit: JSON-RPC dispatch, a typed tool registry, and a Zod→JSON-Schema serializer.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/migrations/*.sql"
+  ],
+  "vk": {
+    "migrations": "src/migrations"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/venturekit-dev/venturekit.private.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "venturekit",
+    "mcp",
+    "model-context-protocol",
+    "json-rpc",
+    "tools",
+    "agents"
+  ],
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.3.0",
+    "zod": "^3.22.0"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').cpSync('src/migrations','dist/migrations',{recursive:true})\"",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  }
+}

package/src/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);