@novorb/mcp-core 2.1.1 → 3.0.0

package/README.md

@@ -4,195 +4,116 @@
 
 [![CI](https://github.com/Novorb/mcp-core/actions/workflows/ci.yml/badge.svg)](https://github.com/Novorb/mcp-core/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@novorb/mcp-core)](https://www.npmjs.com/package/@novorb/mcp-core)
-[![Node](https://img.shields.io/badge/Node-22%2B-green)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/Tests-122-purple)]()
+[![Node](https://img.shields.io/badge/Node-20%2B-green)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/Tests-1186-purple)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 
-Shared TypeScript utilities for building MCP (Model Context Protocol) servers — logging, HTTP clients, retry logic, pagination, and transport — so every MCP server gets a consistent, tested foundation without reimplementing common patterns.
+#### Quality Assurance
 
-## Features
-
-- **Structured logging** — file output with rotation, stderr output, text or JSON format, secret redaction
-- **HTTP client** — axios wrapper with automatic retry on 429/5xx, request logging, pagination
-- **Retry with backoff** — exponential backoff with jitter, configurable retries and delays
-- **Pagination helpers** — normalize params, compute metadata, paginate arrays in memory
-- **Unified transport** — stdio and stateless streamable-HTTP with built-in auth and DNS-rebinding protection
-- **Server builder** — `McpServer` factory, annotation presets, and SDK re-exports from one import point
-- **ESM native** — built as ES modules with full TypeScript declarations
-
-## Documentation
+[![Coverage](https://img.shields.io/badge/coverage-98%25%20lines-brightgreen)]()
+[![Audit](https://img.shields.io/badge/audit-1_moderate-yellow)](docs/sdk.md#known-advisories)
+[![Fallow](https://img.shields.io/badge/fallow_health-86.6_(A)-brightgreen)](https://fallow.tools)
+[![Maintainability](https://img.shields.io/badge/maintainability-94-brightgreen)](https://fallow.tools)
 
-- **[CLAUDE.md](CLAUDE.md)** — agent/contributor context and working conventions
-- **[docs/TESTING.md](docs/TESTING.md)** — test runner commands, conventions, and guidelines
+Shared TypeScript foundation for building MCP (Model Context Protocol) servers: bootstrap, transport, tools, logging, HTTP clients, credentials and testing, so every server gets the same tested behaviour without reimplementing it. Version 3 is built on the MCP SDK v2 packages.
 
-## Installation
-
-```bash
-pnpm add @novorb/mcp-core
-```
+## Features
 
-## Modules
+- **Bootstrap** (`runMcpServer`): one entry point for every server, from env loading to clean shutdown
+- **Transport**: stdio and stateless streamable HTTP with bearer auth, plus an adapter for existing Express apps
+- **Tools** (`registerTools`): central logging, safe error mapping, result caps and tamper-checked cursors
+- **Protocol features**: logging, elicitation, sampling, roots, progress and cancellation across both protocol eras
+- **Resources, prompts and notifications**: registration helpers, runtime toggles and change events on every transport
+- **Tasks and requestState**: long-running tools with file or in-memory stores, and sealed multi-step state
+- **HTTP client, retry and pagination**: one hardened client per upstream, one retry policy, page walkers for common API shapes
+- **Guarded outbound URLs**: safe fetches of caller-supplied URLs and safe encoding of path segments
+- **Credential health**: startup checks, key pools with rotation, and a report on every result
+- **Env and data store**: one env loader with typed validation, and traversal-safe, atomic disk writes
+- **Logger**: console and rotating file sinks with secret redaction and PII masking
+- **Testing harness**: unit and integration helpers for your own server, and a cross-platform jest runner
+- **The SDK through mcp-core**: a curated entry plus full re-exports, so servers depend on one package
 
-### Logger
+## Documentation
 
-Unified logger supporting file output (with rotation) and stderr output, in text or structured JSON format. MCP servers use stdio for protocol communication, so logging to stdout/stderr directly isn't always possible — file-based logging solves this. Sensitive-keyed fields in `meta` are redacted before serialisation.
+**Getting started**
 
-```typescript
-import { initLogger, LogLevel } from '@novorb/mcp-core';
+- [Building a server](docs/building-a-server.md): a minimal server and what `runMcpServer` does
+- [Features](docs/features.md): the full feature list in detail
+- [API reference](docs/api-reference.md): every import path and what it exports
+- [The MCP SDK](docs/sdk.md): importing the SDK through mcp-core, and what SDK v2 changes
+- [Migrating to 3.0](docs/migrating-to-v3.md): breaking changes and moving a low-level `Server` consumer
 
-// File-based (writes to logs/mcp.log with rotation)
-const logger = initLogger({
-  output: 'file',
-  logDir: './logs',
-  level: LogLevel.INFO,
-});
+**Serving**
 
-// Stderr with structured JSON
-const logger = initLogger({
-  output: 'stderr',
-  format: 'json',
-});
+- [Server](docs/server.md): the server builder, annotation presets, list pagination
+- [Transport and Express adapter](docs/transport.md): stdio, HTTP, auth and guards
+- [Tools](docs/tools.md): definitions, response limits, cursors
+- [Protocol features](docs/protocol-features.md): logging, elicitation, sampling, roots, progress, cancellation
+- [Resources, prompts, notifications, tasks, requestState](docs/resources-prompts-tasks.md)
 
-logger.info('Server started', 'Server');
-logger.error('Request failed', 'HttpClient', { status: 500, path: '/api/items' });
-```
+**Upstreams and configuration**
 
-### HTTP Client
+- [HTTP client and retry](docs/http-client.md)
+- [Pagination](docs/pagination.md)
+- [Outbound URLs](docs/outbound-urls.md): `guardedFetch` and URL path segments
+- [Env](docs/env.md)
+- [Credential health](docs/credentials.md)
+- [Data store](docs/data-store.md)
+- [Logger](docs/logger.md)
 
-Pre-configured axios wrapper with automatic retry on transient failures (429, 5xx, network errors) for idempotent methods, request/response logging, and pagination support via `X-Total-Count` headers.
+**Testing and contributing**
 
-```typescript
-import { createHttpClient } from '@novorb/mcp-core';
+- [Testing your server](docs/testing-harness.md): the `./testing` harness and `mcp-core-jest`
+- [Testing mcp-core](docs/testing.md): this repo's test commands and conventions
+- [CLAUDE.md](CLAUDE.md): agent and contributor context
 
-const client = createHttpClient({
-  baseURL: 'https://api.example.com',
-  headers: { 'Authorization': 'Bearer token' },
-  retries: 3,
-  logContext: 'MyApiClient',
-});
+## Quick Start
 
-const item = await client.get('/items/1');
-const { data, totalCount } = await client.getPaginated('/items', { page: 1, per_page: 50 });
-await client.post('/items', { name: 'new item' });
+```bash
+pnpm add @novorb/mcp-core zod
 ```
 
-### Retry
-
-Exponential backoff with jitter for retrying failed operations. Used internally by the HTTP client, but also available standalone.
-
 ```typescript
-import { retryWithBackoff, isRetryableError } from '@novorb/mcp-core';
-
-const result = await retryWithBackoff(async (ctx) => {
-  console.log(`Attempt ${ctx.attempt + 1}/${ctx.maxRetries + 1}`);
-  return await someUnreliableOperation();
-}, {
-  maxRetries: 3,
-  initialDelayMs: 1000,
-  backoffMultiplier: 2,
+import { z } from 'zod';
+import { runMcpServer } from '@novorb/mcp-core/bootstrap';
+import { packageRootFrom } from '@novorb/mcp-core/logger';
+import { TOOL_ANNOTATIONS } from '@novorb/mcp-core/server';
+import { defineTool, registerTools, toolResult } from '@novorb/mcp-core/tools';
+
+await runMcpServer({
+  rootDir: packageRootFrom(import.meta.url),
+  env: [],
+  create: (_shared, _req, { env, info, createServer }) => {
+    const server = createServer();
+    registerTools(
+      server,
+      [
+        defineTool({
+          name: 'hello',
+          description: 'Say hello',
+          inputSchema: z.object({ name: z.string() }),
+          annotations: TOOL_ANNOTATIONS.readOnly,
+          handler: async ({ name }) => toolResult(`Hello ${name}`),
+        }),
+      ],
+      { env, serverName: info.name },
+    );
+    return server;
+  },
 });
 ```
 
-### Pagination
-
-Normalize pagination parameters, compute metadata, and paginate arrays in memory.
-
-```typescript
-import { normalizePagination, createPaginationMetadata, paginateArray } from '@novorb/mcp-core';
-
-const params = normalizePagination({ page: 3, per_page: 200 });
-// { page: 3, per_page: 100 }  (capped at max)
-
-const metadata = createPaginationMetadata(500, params);
-// { totalCount: 500, page: 3, perPage: 100, totalPages: 5 }
-
-const { data, metadata } = paginateArray(allItems, { page: 2, per_page: 20 });
-```
-
-### Transport
-
-Unified transport that selects between stdio and stateless streamable HTTP based on the `MCP_TRANSPORT` environment variable. HTTP mode is fail-closed (refuses to start without auth unless explicitly disabled) and supports Bearer-token auth, body-size caps, and opt-in DNS-rebinding protection.
-
-```typescript
-import { startMcpServer } from '@novorb/mcp-core/transport';
-
-// Factory (recommended for HTTP — fresh server instance per request):
-await startMcpServer(() => createServer(services));
-
-// Server instance (fine for stdio):
-await startMcpServer(server);
-```
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
-| `PORT` | `8080` | HTTP listen port |
-| `MCP_HTTP_HOST` | `0.0.0.0` | Bind address (`127.0.0.1` for local-only) |
-| `MCP_API_KEY` | none | Bearer token for HTTP auth (required in HTTP mode unless disabled) |
-| `MCP_AUTH_DISABLED` | `false` | Set `true` to run HTTP without auth (only behind a fronting gateway) |
-| `MCP_MAX_BODY_BYTES` | 4 MiB | Max accepted POST body size |
-| `MCP_ALLOWED_HOSTS` | none | Comma-separated Host allowlist (enables DNS-rebinding protection) |
-| `MCP_ALLOWED_ORIGINS` | none | Comma-separated Origin allowlist (enables DNS-rebinding protection) |
-
-### Server
-
-Import MCP server-building primitives from here instead of the SDK directly, to centralise the MCP dependency.
-
-```typescript
-import { createMcpServer, TOOL_ANNOTATIONS, completable } from '@novorb/mcp-core/server';
-import type { McpToolAnnotations, McpCallToolResult } from '@novorb/mcp-core/server';
-
-const server = createMcpServer('my-mcp', '1.0.0');
-
-server.registerTool('lookup', {
-  description: 'Look up a value',
-  inputSchema: { key: z.string() },
-  outputSchema: { value: z.string(), found: z.boolean() },
-  annotations: TOOL_ANNOTATIONS.readOnly,
-}, async ({ key }) => ({
-  content: [{ type: 'text', text: value }],
-  structuredContent: { value, found: true },
-}));
-```
-
-**`TOOL_ANNOTATIONS` presets:** `readOnly` (lookups/searches), `idempotentWrite` (upserts), `mutableWrite` (non-idempotent writes), `destructive` (deletes/overwrites).
-
-## Testing
-
-```bash
-pnpm test            # 122 tests
-pnpm run test:watch  # watch mode
-pnpm run test:coverage
-```
-
-> **Windows note:** the test scripts set `NODE_OPTIONS=` inline, which is Unix shell syntax. On Windows, invoke jest directly via a bash shell. See [docs/TESTING.md](docs/TESTING.md).
-
-## Building
-
-```bash
-pnpm run build   # tsc → dist/
-```
-
-This is an ESM package (`"type": "module"`). `tsconfig.json` is self-contained so it builds standalone.
-
-## CI / Releasing
-
-GitHub Actions (`.github/workflows/`):
-
-- **CI** (`ci.yml`) — runs build + test on every push to `main` and on pull requests.
-- **Publish** (`publish.yml`) — on a pushed version tag `v*`, runs build + test, verifies the
-  tag matches `package.json` `version`, then publishes to the public npm registry (with provenance).
+The server runs on stdio by default; set `MCP_TRANSPORT=http` for HTTP. Continue with [Building a server](docs/building-a-server.md).
 
-Release flow:
+## Development
 
 ```bash
-# 1. bump "version" in package.json (e.g. 2.1.1), commit
-# 2. tag and push — the tag triggers the publish workflow
-git tag v2.1.1 && git push origin v2.1.1
+pnpm run build       # tsc to dist/
+pnpm test            # all suites
+pnpm run qa:all      # full QA matrix
 ```
 
-Requires the repo secret **`NPM_TOKEN`** (an npm automation/granular token with publish rights for
-the `@novorb` scope) under *Settings → Secrets and variables → Actions*.
+This is an ESM package (`"type": "module"`). See [Testing mcp-core](docs/testing.md).
 
 ## License
 

package/bin/mcp-core-jest.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * mcp-core-jest: a cross-platform jest launcher for ESM MCP servers (and for mcp-core itself).
+ *
+ * ESM jest suites (`"type": "module"` + ts-jest useESM) need the node binary started with
+ * `--experimental-vm-modules`. The usual `NODE_OPTIONS=--experimental-vm-modules jest` script is POSIX
+ * inline-env syntax and does not run under PowerShell or cmd. This launcher starts node with the flag
+ * and runs the CALLER's jest: jest is resolved from the current working directory (the consumer's
+ * package), so it stays the consumer's devDependency and mcp-core never depends on it at runtime.
+ *
+ *   "test:unit": "mcp-core-jest tests/unit",
+ *   "test:integration": "mcp-core-jest tests/integration --runInBand --coverage=false"
+ *
+ * Every argument is passed through to jest unchanged. The exit code is jest's; a signal that ends jest
+ * ends this process with the same signal; SIGTERM/SIGHUP are forwarded on POSIX and SIGINT (which reaches jest
+ * from the terminal) is waited out, never doubled.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+
+/** The directory of the `jest` package that owns `entry` (the nearest package.json named jest). */
+function jestPackageRoot(entry) {
+  let dir = dirname(entry);
+  for (;;) {
+    const manifest = join(dir, 'package.json');
+    if (existsSync(manifest)) {
+      try {
+        if (JSON.parse(readFileSync(manifest, 'utf8')).name === 'jest') return dir;
+      } catch {
+        /* keep walking */
+      }
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** `jest/bin/jest.js` as resolved from `cwd` (its `exports` map hides the bin subpath, so derive it). */
+function findJestBin(cwd) {
+  try {
+    const entry = createRequire(join(resolve(cwd), 'noop.js')).resolve('jest');
+    const root = jestPackageRoot(entry);
+    if (root) {
+      const bin = join(root, 'bin', 'jest.js');
+      if (existsSync(bin)) return bin;
+    }
+  } catch {
+    /* fall through to the walk */
+  }
+  let dir = resolve(cwd);
+  for (;;) {
+    const bin = join(dir, 'node_modules', 'jest', 'bin', 'jest.js');
+    if (existsSync(bin)) return bin;
+    const parent = resolve(dir, '..');
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Signal handling, as npm and cross-spawn do it:
+ * - SIGINT is never forwarded: a Ctrl+C reaches jest from the terminal itself (the console process group
+ *   on POSIX, CTRL_C_EVENT on Windows), so forwarding would deliver it twice. The launcher only ignores
+ *   it and waits for jest to finish its own shutdown.
+ * - SIGTERM and SIGHUP are forwarded on POSIX (a supervisor signals the launcher, not the group).
+ * - On Windows nothing is forwarded: `child.kill(signal)` there is TerminateProcess, which would cut
+ *   jest's own cleanup short.
+ */
+const IGNORED_SIGNALS = ['SIGINT'];
+const FORWARDED_SIGNALS = process.platform === 'win32' ? [] : ['SIGTERM', 'SIGHUP'];
+
+function main() {
+  const jestBin = findJestBin(process.cwd());
+  if (!jestBin) {
+    process.stderr.write(
+      `mcp-core-jest: could not locate jest from ${process.cwd()}. Add jest as a devDependency of this package and install it.\n`,
+    );
+    process.exit(1);
+  }
+  const child = spawn(process.execPath, ['--experimental-vm-modules', jestBin, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    shell: false,
+  });
+  const forwarders = [
+    ...IGNORED_SIGNALS.map((signal) => [signal, () => undefined]),
+    ...FORWARDED_SIGNALS.map((signal) => [
+      signal,
+      () => {
+        if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+      },
+    ]),
+  ];
+  for (const [signal, handler] of forwarders) process.on(signal, handler);
+  child.on('error', (err) => {
+    process.stderr.write(`mcp-core-jest: could not start jest: ${err.message}\n`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    for (const [name, forward] of forwarders) process.off(name, forward);
+    if (signal) {
+      process.exitCode = 1;
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+main();

package/dist/auth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @novorb/mcp-core - HTTP auth
+ *
+ * mcp-core's HTTP auth runs on the SDK's resource-server gate: `verifyBearerToken` parses the
+ * `Authorization` header, calls an `OAuthTokenVerifier`, checks `expectedResource`, `requiredScopes` and
+ * the expiry, and `bearerAuthChallengeResponse` maps a failure to the 401 / 403 OAuth error with its
+ * `WWW-Authenticate` challenge. The verified `AuthInfo` is set as `req.auth`, which the SDK forwards to
+ * the server factory (`RequestContext.authInfo`) and to handlers (`ctx.http.authInfo`), so per-tool
+ * `scopeChallenge` / `requireScopes(...)` gates work.
+ *
+ * The static `MCP_API_KEY` is one verifier (`apiKeyVerifier`): a constant-time comparison (SHA-256 of
+ * both sides, `timingSafeEqual`) that answers an `AuthInfo` whose `token` is a placeholder, never the
+ * key. A host can pass its own verifier (for example one checking OAuth JWTs) instead.
+ */
+import type { ServerResponse } from 'node:http';
+import { type AuthInfo, type OAuthTokenVerifier, type VerifyBearerTokenOptions } from '@modelcontextprotocol/server';
+/** The `AuthInfo.token` the API-key verifier reports: never the real key. */
+export declare const API_KEY_TOKEN_PLACEHOLDER = "[api-key]";
+/** How long an API-key `AuthInfo` is valid (the SDK refuses tokens without `expiresAt`). */
+export declare const API_KEY_TTL_SECONDS = 3600;
+export interface ApiKeyVerifierOptions {
+    /** `AuthInfo.clientId` (default `api-key`). */
+    clientId?: string;
+    /** `AuthInfo.scopes` granted by the key (default none). */
+    scopes?: string[];
+    /** `AuthInfo.expiresAt` = now + this (default 3600 s). */
+    ttlSeconds?: number;
+}
+/** Options for the HTTP auth gate (transport and Express adapter). */
+export interface HttpAuthOptions {
+    /** A token verifier (for example a JWT verifier). When set it replaces the static API key. */
+    verifier?: OAuthTokenVerifier;
+    /** Scopes every request must carry (403 `insufficient_scope` otherwise). */
+    requiredScopes?: string[];
+    /** RFC 9728 Protected Resource Metadata URL advertised in challenges. */
+    resourceMetadataUrl?: string;
+    /** Accept only tokens issued for this resource (audience). */
+    expectedResource?: URL;
+    /** `AuthInfo` fields for the static API key. */
+    apiKey?: ApiKeyVerifierOptions;
+}
+/** A verifier for one static key, compared in constant time. The returned `AuthInfo` never holds the key. */
+export declare function apiKeyVerifier(apiKey: string, options?: ApiKeyVerifierOptions): OAuthTokenVerifier;
+/** The SDK bearer options for a gate: the explicit verifier, else the API key, else none (open). */
+export declare function bearerOptions(auth: HttpAuthOptions | undefined, apiKey: string | undefined): VerifyBearerTokenOptions | undefined;
+export type AuthOutcome = {
+    ok: true;
+    authInfo: AuthInfo;
+} | {
+    ok: false;
+    response: Response;
+};
+/** Verify an `Authorization` header value; a failure carries the SDK's ready-made challenge response. */
+export declare function authenticate(header: string | undefined, options: VerifyBearerTokenOptions): Promise<AuthOutcome>;
+/** Write a web `Response` (status, headers, body) to a Node response. */
+export declare function writeWebResponse(res: ServerResponse, response: Response): Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,KAAK,QAAQ,EAIb,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAE9B,MAAM,8BAA8B,CAAC;AAEtC,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,GAAG,CAAC;IACvB,gDAAgD;IAChD,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAMD,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,kBAAkB,CAgBtG;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAC3B,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,wBAAwB,GAAG,SAAS,CAStC;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE/F,yGAAyG;AACzG,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAMtB;AAED,yEAAyE;AACzE,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7F"}

package/dist/auth.js

@@ -0,0 +1,74 @@
+/**
+ * @novorb/mcp-core - HTTP auth
+ *
+ * mcp-core's HTTP auth runs on the SDK's resource-server gate: `verifyBearerToken` parses the
+ * `Authorization` header, calls an `OAuthTokenVerifier`, checks `expectedResource`, `requiredScopes` and
+ * the expiry, and `bearerAuthChallengeResponse` maps a failure to the 401 / 403 OAuth error with its
+ * `WWW-Authenticate` challenge. The verified `AuthInfo` is set as `req.auth`, which the SDK forwards to
+ * the server factory (`RequestContext.authInfo`) and to handlers (`ctx.http.authInfo`), so per-tool
+ * `scopeChallenge` / `requireScopes(...)` gates work.
+ *
+ * The static `MCP_API_KEY` is one verifier (`apiKeyVerifier`): a constant-time comparison (SHA-256 of
+ * both sides, `timingSafeEqual`) that answers an `AuthInfo` whose `token` is a placeholder, never the
+ * key. A host can pass its own verifier (for example one checking OAuth JWTs) instead.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { bearerAuthChallengeResponse, OAuthError, OAuthErrorCode, verifyBearerToken, } from '@modelcontextprotocol/server';
+/** The `AuthInfo.token` the API-key verifier reports: never the real key. */
+export const API_KEY_TOKEN_PLACEHOLDER = '[api-key]';
+/** How long an API-key `AuthInfo` is valid (the SDK refuses tokens without `expiresAt`). */
+export const API_KEY_TTL_SECONDS = 3600;
+function digest(value) {
+    return createHash('sha256').update(value).digest();
+}
+/** A verifier for one static key, compared in constant time. The returned `AuthInfo` never holds the key. */
+export function apiKeyVerifier(apiKey, options = {}) {
+    if (apiKey.length === 0)
+        throw new Error('apiKeyVerifier: the API key must not be empty');
+    const expected = digest(apiKey);
+    return {
+        async verifyAccessToken(token) {
+            if (!timingSafeEqual(digest(token), expected)) {
+                throw new OAuthError(OAuthErrorCode.InvalidToken, 'Invalid token');
+            }
+            return {
+                token: API_KEY_TOKEN_PLACEHOLDER,
+                clientId: options.clientId ?? 'api-key',
+                scopes: [...(options.scopes ?? [])],
+                expiresAt: Math.floor(Date.now() / 1000) + (options.ttlSeconds ?? API_KEY_TTL_SECONDS),
+            };
+        },
+    };
+}
+/** The SDK bearer options for a gate: the explicit verifier, else the API key, else none (open). */
+export function bearerOptions(auth, apiKey) {
+    const verifier = auth?.verifier ?? (apiKey ? apiKeyVerifier(apiKey, auth?.apiKey) : undefined);
+    if (!verifier)
+        return undefined;
+    return {
+        verifier,
+        ...(auth?.requiredScopes ? { requiredScopes: auth.requiredScopes } : {}),
+        ...(auth?.resourceMetadataUrl ? { resourceMetadataUrl: auth.resourceMetadataUrl } : {}),
+        ...(auth?.expectedResource ? { expectedResource: auth.expectedResource } : {}),
+    };
+}
+/** Verify an `Authorization` header value; a failure carries the SDK's ready-made challenge response. */
+export async function authenticate(header, options) {
+    try {
+        return { ok: true, authInfo: await verifyBearerToken(header, options) };
+    }
+    catch (error) {
+        return { ok: false, response: bearerAuthChallengeResponse(error, options) };
+    }
+}
+/** Write a web `Response` (status, headers, body) to a Node response. */
+export async function writeWebResponse(res, response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    const body = await response.text();
+    res.writeHead(response.status, headers);
+    res.end(body);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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