@nocoo/base-mcp 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,194 @@
+# @nocoo/base-mcp
+
+MCP Server development framework with OAuth 2.1, Entity-Driven CRUD, and Streamable HTTP transport support.
+
+## Features
+
+- **Entity-Driven CRUD Framework**: Declarative entity definitions → automatic MCP tool generation
+- **OAuth 2.1 Support**: PKCE, Dynamic Client Registration, token management
+- **DNS Rebinding Protection**: Origin validation for HTTP transport
+- **Testing Utilities**: Mock context, result parsing, token store mocking
+
+## Installation
+
+```bash
+pnpm add @nocoo/base-mcp
+```
+
+Peer dependencies:
+```bash
+pnpm add @modelcontextprotocol/sdk zod
+```
+
+## Quick Start
+
+```typescript
+import { createMcpServer, registerEntityTools, ok, error } from "@nocoo/base-mcp";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod";
+
+// 1. Create MCP Server
+const server = createMcpServer({
+  name: "my-app",
+  version: "1.0.0",
+});
+
+// 2. Define an Entity
+const productEntity = {
+  name: "product",
+  display: "Product",
+  plural: "products",
+  dataLayer: {
+    list: async (ctx, opts) => ctx.repos.products.list(opts),
+    getById: async (ctx, id) => ctx.repos.products.getById(id),
+    create: async (ctx, input) => ctx.repos.products.create(input),
+    update: async (ctx, id, input) => ctx.repos.products.update(id, input),
+    delete: async (ctx, id) => ctx.repos.products.delete(id),
+  },
+  schemas: {
+    list: { category: z.string().optional() },
+    create: { name: z.string(), price: z.number() },
+    update: { name: z.string().optional(), price: z.number().optional() },
+  },
+};
+
+// 3. Register Entity Tools
+const ctx = { repos: createRepos(db) };
+registerEntityTools(server, productEntity, ctx);
+
+// 4. Handle HTTP requests (Hono/Cloudflare Worker example)
+app.post("/mcp", async (c) => {
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined, // Stateless
+    enableJsonResponse: true,
+  });
+  await server.connect(transport);
+  return transport.handleRequest(c.req.raw);
+});
+```
+
+## API Reference
+
+### Server
+
+```typescript
+import { createMcpServer } from "@nocoo/base-mcp";
+
+const server = createMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  capabilities: { tools: true, resources: false },
+});
+```
+
+### Framework
+
+```typescript
+import {
+  // Entity registration
+  registerEntityTools,
+  registerCustomTool,
+  createCrudHandlers,
+  
+  // Response builders
+  ok,
+  error,
+  
+  // Field projection
+  projectFields,
+  
+  // ID/Slug resolution
+  validateIdOrSlug,
+  resolveEntity,
+  isResolveError,
+} from "@nocoo/base-mcp";
+```
+
+### Auth
+
+```typescript
+import {
+  // PKCE
+  verifyPkceS256,
+  generateCodeVerifier,
+  generateCodeChallenge,
+  isLoopbackRedirectUri,
+  
+  // OAuth Metadata
+  getOAuthMetadata,
+  
+  // Origin Validation
+  validateOrigin,
+  isLoopbackHost,
+  
+  // Token Management
+  generateToken,
+  hashToken,
+  tokenPreview,
+  extractBearerToken,
+  validateMcpToken,
+} from "@nocoo/base-mcp/auth";
+```
+
+### Testing
+
+```typescript
+import {
+  createMockContext,
+  parseToolResult,
+  isToolError,
+  getToolErrorMessage,
+  createMockTokenStore,
+} from "@nocoo/base-mcp/testing";
+```
+
+## Entity Configuration
+
+```typescript
+interface EntityConfig<T, TRepos> {
+  name: string;           // Singular name (e.g., "product")
+  display: string;        // Human-readable name
+  plural: string;         // Plural name for list tool
+  
+  dataLayer: {
+    list: (ctx, opts) => Promise<T[]>;
+    getById: (ctx, id) => Promise<T | null>;
+    getBySlug?: (ctx, slug) => Promise<T | null>;
+    create?: (ctx, input) => Promise<T>;
+    update?: (ctx, id, input) => Promise<T | null>;
+    delete?: (ctx, id) => Promise<boolean>;
+  };
+  
+  schemas?: {
+    list?: Record<string, ZodType>;
+    create?: Record<string, ZodType>;
+    update?: Record<string, ZodType>;
+  };
+  
+  descriptions?: {
+    list?: string;
+    get?: string;
+    create?: string;
+    update?: string;
+    delete?: string;
+  };
+  
+  projection?: {
+    omit: string[];
+    groups: Record<string, string[]>;
+  };
+  
+  hooks?: {
+    beforeCreate?: (ctx, input) => Promise<Record<string, unknown>>;
+    afterCreate?: (ctx, entity) => Promise<void>;
+    beforeUpdate?: (ctx, id, input, existing) => Promise<Record<string, unknown>>;
+    afterUpdate?: (ctx, id, input, result) => Promise<void>;
+    beforeDelete?: (ctx, id, existing) => Promise<void>;
+    afterDelete?: (ctx, id) => Promise<void>;
+  };
+}
+```
+
+## License
+
+MIT

package/dist/auth/index.d.ts

@@ -0,0 +1,5 @@
+export { verifyPkceS256, generateCodeVerifier, generateCodeChallenge, isLoopbackRedirectUri, } from "./pkce.js";
+export { getOAuthMetadata, type OAuthMetadata, type OAuthMetadataOptions, } from "./oauth-metadata.js";
+export { validateOrigin, isLoopbackHost, type OriginValidationResult, } from "./origin.js";
+export { generateToken, hashToken, tokenPreview, extractBearerToken, validateMcpToken, type TokenStore, type TokenValidationResult, type TokenValidationSuccess, type TokenValidationError, } from "./token.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+// Auth exports
+export { verifyPkceS256, generateCodeVerifier, generateCodeChallenge, isLoopbackRedirectUri, } from "./pkce.js";
+export { getOAuthMetadata, } from "./oauth-metadata.js";
+export { validateOrigin, isLoopbackHost, } from "./origin.js";
+export { generateToken, hashToken, tokenPreview, extractBearerToken, validateMcpToken, } from "./token.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,eAAe;AACf,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,GAGjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,cAAc,GAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GAKjB,MAAM,YAAY,CAAC"}

package/dist/auth/oauth-metadata.d.ts

@@ -0,0 +1,31 @@
+export interface OAuthMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    scopes_supported?: string[];
+}
+export interface OAuthMetadataOptions {
+    /** Base path for OAuth endpoints (default: "/api/mcp") */
+    basePath?: string;
+    /** Supported scopes (default: ["mcp:full"]) */
+    scopes?: string[];
+    /** Enable dynamic client registration endpoint */
+    enableRegistration?: boolean;
+}
+/**
+ * Generate OAuth 2.1 Authorization Server Metadata.
+ *
+ * This metadata is served at `/.well-known/oauth-authorization-server`
+ * and allows MCP clients to discover OAuth endpoints.
+ *
+ * @param issuer - The base URL of the authorization server (e.g., "https://example.com")
+ * @param options - Optional configuration
+ * @returns OAuth metadata object
+ */
+export declare function getOAuthMetadata(issuer: string, options?: OAuthMetadataOptions): OAuthMetadata;
+//# sourceMappingURL=oauth-metadata.d.ts.map

package/dist/auth/oauth-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-metadata.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-metadata.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,gCAAgC,EAAE,MAAM,EAAE,CAAC;IAC3C,qCAAqC,EAAE,MAAM,EAAE,CAAC;IAChD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,aAAa,CA0Bf"}

package/dist/auth/oauth-metadata.js

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// OAuth 2.1 Authorization Server Metadata
+// ---------------------------------------------------------------------------
+/**
+ * Generate OAuth 2.1 Authorization Server Metadata.
+ *
+ * This metadata is served at `/.well-known/oauth-authorization-server`
+ * and allows MCP clients to discover OAuth endpoints.
+ *
+ * @param issuer - The base URL of the authorization server (e.g., "https://example.com")
+ * @param options - Optional configuration
+ * @returns OAuth metadata object
+ */
+export function getOAuthMetadata(issuer, options = {}) {
+    const { basePath = "/api/mcp", scopes = ["mcp:full"], enableRegistration = true, } = options;
+    // Remove trailing slash from issuer
+    const base = issuer.replace(/\/$/, "");
+    const metadata = {
+        issuer: base,
+        authorization_endpoint: `${base}${basePath}/authorize`,
+        token_endpoint: `${base}${basePath}/token`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        scopes_supported: scopes,
+    };
+    if (enableRegistration) {
+        metadata.registration_endpoint = `${base}${basePath}/register`;
+    }
+    return metadata;
+}
+//# sourceMappingURL=oauth-metadata.js.map

package/dist/auth/oauth-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-metadata.js","sourceRoot":"","sources":["../../src/auth/oauth-metadata.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAuB9E;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAAgC,EAAE;IAElC,MAAM,EACJ,QAAQ,GAAG,UAAU,EACrB,MAAM,GAAG,CAAC,UAAU,CAAC,EACrB,kBAAkB,GAAG,IAAI,GAC1B,GAAG,OAAO,CAAC;IAEZ,oCAAoC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEvC,MAAM,QAAQ,GAAkB;QAC9B,MAAM,EAAE,IAAI;QACZ,sBAAsB,EAAE,GAAG,IAAI,GAAG,QAAQ,YAAY;QACtD,cAAc,EAAE,GAAG,IAAI,GAAG,QAAQ,QAAQ;QAC1C,wBAAwB,EAAE,CAAC,MAAM,CAAC;QAClC,qBAAqB,EAAE,CAAC,oBAAoB,EAAE,eAAe,CAAC;QAC9D,gCAAgC,EAAE,CAAC,MAAM,CAAC;QAC1C,qCAAqC,EAAE,CAAC,MAAM,CAAC;QAC/C,gBAAgB,EAAE,MAAM;KACzB,CAAC;IAEF,IAAI,kBAAkB,EAAE,CAAC;QACvB,QAAQ,CAAC,qBAAqB,GAAG,GAAG,IAAI,GAAG,QAAQ,WAAW,CAAC;IACjE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/auth/origin.d.ts

@@ -0,0 +1,32 @@
+export type OriginValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+    status: number;
+};
+/**
+ * Validate the Origin header for DNS rebinding protection.
+ *
+ * MCP servers using HTTP transport need to protect against DNS rebinding attacks.
+ * This function validates that the request origin is allowed.
+ *
+ * Allowed origins:
+ * - null (CLI clients, curl, etc.)
+ * - Same site (matches siteUrl)
+ * - Loopback addresses (localhost, 127.0.0.1, [::1])
+ * - Non-web protocols (vscode-file://, electron://, tauri://)
+ *
+ * @param origin - The Origin header value (may be null)
+ * @param siteUrl - The allowed site URL (e.g., "https://example.com")
+ * @returns Validation result with error details if invalid
+ */
+export declare function validateOrigin(origin: string | null, siteUrl: string): OriginValidationResult;
+/**
+ * Check if a hostname is a loopback address.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if loopback
+ */
+export declare function isLoopbackHost(hostname: string): boolean;
+//# sourceMappingURL=origin.d.ts.map

package/dist/auth/origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../src/auth/origin.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,sBAAsB,GAC9B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,MAAM,GACd,sBAAsB,CAkCxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMxD"}

package/dist/auth/origin.js

@@ -0,0 +1,66 @@
+// ---------------------------------------------------------------------------
+// Origin Validation for DNS Rebinding Protection
+// ---------------------------------------------------------------------------
+/**
+ * Validate the Origin header for DNS rebinding protection.
+ *
+ * MCP servers using HTTP transport need to protect against DNS rebinding attacks.
+ * This function validates that the request origin is allowed.
+ *
+ * Allowed origins:
+ * - null (CLI clients, curl, etc.)
+ * - Same site (matches siteUrl)
+ * - Loopback addresses (localhost, 127.0.0.1, [::1])
+ * - Non-web protocols (vscode-file://, electron://, tauri://)
+ *
+ * @param origin - The Origin header value (may be null)
+ * @param siteUrl - The allowed site URL (e.g., "https://example.com")
+ * @returns Validation result with error details if invalid
+ */
+export function validateOrigin(origin, siteUrl) {
+    // Null origin is allowed (CLI clients, curl, etc.)
+    if (!origin)
+        return { valid: true };
+    // Same site is allowed
+    try {
+        const siteOrigin = new URL(siteUrl).origin;
+        if (origin === siteOrigin)
+            return { valid: true };
+    }
+    catch {
+        // Invalid siteUrl - continue with other checks
+    }
+    // Non-web protocols are allowed (desktop apps)
+    if (!origin.startsWith("http://") && !origin.startsWith("https://")) {
+        return { valid: true };
+    }
+    // Check for loopback addresses
+    try {
+        const url = new URL(origin);
+        const host = url.hostname;
+        if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") {
+            return { valid: true };
+        }
+    }
+    catch {
+        // Invalid origin URL
+    }
+    // All other origins are rejected
+    return {
+        valid: false,
+        error: "Origin not allowed",
+        status: 403,
+    };
+}
+/**
+ * Check if a hostname is a loopback address.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if loopback
+ */
+export function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "[::1]");
+}
+//# sourceMappingURL=origin.js.map

package/dist/auth/origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.js","sourceRoot":"","sources":["../../src/auth/origin.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iDAAiD;AACjD,8EAA8E;AAM9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAqB,EACrB,OAAe;IAEf,mDAAmD;IACnD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAEpC,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC3C,IAAI,MAAM,KAAK,UAAU;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;IAED,+CAA+C;IAC/C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC1B,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;IAED,iCAAiC;IACjC,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,oBAAoB;QAC3B,MAAM,EAAE,GAAG;KACZ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,CACL,QAAQ,KAAK,WAAW;QACxB,QAAQ,KAAK,WAAW;QACxB,QAAQ,KAAK,OAAO,CACrB,CAAC;AACJ,CAAC"}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Verify a PKCE S256 code_challenge against a code_verifier.
+ *
+ * The code_challenge is created by: base64url(sha256(code_verifier))
+ * We recompute this from the verifier and compare.
+ *
+ * @param codeVerifier - The original random string (43-128 chars)
+ * @param codeChallenge - The base64url-encoded SHA-256 hash
+ * @returns True if the verifier matches the challenge
+ */
+export declare function verifyPkceS256(codeVerifier: string, codeChallenge: string): Promise<boolean>;
+/**
+ * Generate a PKCE code_verifier (for testing purposes).
+ *
+ * In production, this is typically done client-side.
+ *
+ * @param length - Length of the verifier (43-128 chars, default 64)
+ * @returns A random code_verifier string
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Generate a PKCE code_challenge from a code_verifier (for testing purposes).
+ *
+ * @param codeVerifier - The code_verifier to hash
+ * @returns The base64url-encoded SHA-256 hash
+ */
+export declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
+/**
+ * Check if a redirect URI is a loopback address (allowed for native apps).
+ *
+ * Per RFC 8252, native apps can use http:// with loopback addresses:
+ * - localhost
+ * - 127.0.0.1
+ * - [::1]
+ *
+ * @param uri - The redirect_uri to check
+ * @returns True if it's a valid loopback URI
+ */
+export declare function isLoopbackRedirectUri(uri: string): boolean;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,SAAK,GAAG,MAAM,CAQxD;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAS1D"}

package/dist/auth/pkce.js

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// OAuth 2.1 PKCE (Proof Key for Code Exchange) Verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify a PKCE S256 code_challenge against a code_verifier.
+ *
+ * The code_challenge is created by: base64url(sha256(code_verifier))
+ * We recompute this from the verifier and compare.
+ *
+ * @param codeVerifier - The original random string (43-128 chars)
+ * @param codeChallenge - The base64url-encoded SHA-256 hash
+ * @returns True if the verifier matches the challenge
+ */
+export async function verifyPkceS256(codeVerifier, codeChallenge) {
+    if (!codeVerifier || !codeChallenge)
+        return false;
+    const encoded = new TextEncoder().encode(codeVerifier);
+    const buffer = await crypto.subtle.digest("SHA-256", encoded);
+    const base64url = btoa(String.fromCharCode(...new Uint8Array(buffer)))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+    return base64url === codeChallenge;
+}
+/**
+ * Generate a PKCE code_verifier (for testing purposes).
+ *
+ * In production, this is typically done client-side.
+ *
+ * @param length - Length of the verifier (43-128 chars, default 64)
+ * @returns A random code_verifier string
+ */
+export function generateCodeVerifier(length = 64) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    return Array.from(array)
+        .map((b) => chars[b % chars.length])
+        .join("");
+}
+/**
+ * Generate a PKCE code_challenge from a code_verifier (for testing purposes).
+ *
+ * @param codeVerifier - The code_verifier to hash
+ * @returns The base64url-encoded SHA-256 hash
+ */
+export async function generateCodeChallenge(codeVerifier) {
+    const encoded = new TextEncoder().encode(codeVerifier);
+    const buffer = await crypto.subtle.digest("SHA-256", encoded);
+    return btoa(String.fromCharCode(...new Uint8Array(buffer)))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * Check if a redirect URI is a loopback address (allowed for native apps).
+ *
+ * Per RFC 8252, native apps can use http:// with loopback addresses:
+ * - localhost
+ * - 127.0.0.1
+ * - [::1]
+ *
+ * @param uri - The redirect_uri to check
+ * @returns True if it's a valid loopback URI
+ */
+export function isLoopbackRedirectUri(uri) {
+    try {
+        const url = new URL(uri);
+        if (url.protocol !== "http:")
+            return false;
+        const host = url.hostname;
+        return host === "localhost" || host === "127.0.0.1" || host === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=pkce.js.map

package/dist/auth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,YAAoB,EACpB,aAAqB;IAErB,IAAI,CAAC,YAAY,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IAElD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;SACnE,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,SAAS,KAAK,aAAa,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAM,GAAG,EAAE;IAC9C,MAAM,KAAK,GACT,oEAAoE,CAAC;IACvE,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;SACnC,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,YAAoB;IAEpB,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;SACxD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC1B,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,OAAO,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/auth/token.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Generate a secure random token.
+ *
+ * @param length - Number of random bytes (default 32, produces 64 hex chars)
+ * @returns Hex-encoded random token
+ */
+export declare function generateToken(length?: number): string;
+/**
+ * Hash a token using SHA-256.
+ *
+ * Tokens should be stored as hashes, never in plaintext.
+ *
+ * @param token - The plaintext token
+ * @returns SHA-256 hash as hex string
+ */
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Generate a token preview (first 8 characters).
+ *
+ * Used for logging and display without exposing the full token.
+ *
+ * @param token - The plaintext token
+ * @returns First 8 characters
+ */
+export declare function tokenPreview(token: string): string;
+/**
+ * Extract bearer token from Authorization header.
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The token, or null if invalid
+ */
+export declare function extractBearerToken(authHeader: string | null): string | null;
+export interface TokenValidationSuccess {
+    valid: true;
+    token: {
+        id: string;
+        user_id: string;
+        client_id: string;
+        scope: string;
+    };
+}
+export interface TokenValidationError {
+    valid: false;
+    error: string;
+    status: number;
+}
+export type TokenValidationResult = TokenValidationSuccess | TokenValidationError;
+/**
+ * Token store interface for validation.
+ *
+ * Implement this interface to connect to your token storage.
+ */
+export interface TokenStore {
+    /**
+     * Find a token by its hash.
+     * @returns Token record or null if not found
+     */
+    findByHash(hash: string): Promise<{
+        id: string;
+        user_id: string;
+        client_id: string;
+        scope: string;
+        revoked: boolean;
+        expires_at: string | null;
+    } | null>;
+    /**
+     * Update last_used_at timestamp.
+     */
+    updateLastUsed(id: string): Promise<void>;
+}
+/**
+ * Validate an MCP bearer token.
+ *
+ * @param store - Token storage implementation
+ * @param authHeader - The Authorization header value
+ * @returns Validation result
+ */
+export declare function validateMcpToken(store: TokenStore, authHeader: string | null): Promise<TokenValidationResult>;
+//# sourceMappingURL=token.d.ts.map

package/dist/auth/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/auth/token.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAK,GAAG,MAAM,CAMjD;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAI3E;AAMD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,GAAG,IAAI,CAAC,CAAC;IAEV;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAmDhC"}