@ttoss/http-server-mcp 0.14.0 → 0.15.0

package/README.md

@@ -315,6 +315,75 @@ app.use(createMcpRouter(mcpServer).routes());
 
 The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients bootstrap OAuth discovery after their first unauthorized request.
 
+## OAuth 2.1 Authorization Server
+
+The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). When you want your own first-party server to _issue_ the tokens, `createMcpAuthServer` provides the **authorization-server** half: the `/authorize`, `/token`, `/register`, and discovery endpoints an MCP client (Claude, Cursor, VS Code) auto-discovers and runs the full OAuth 2.1 flow against.
+
+ttoss owns only the protocol mechanics (PKCE, discovery metadata, code exchange, dynamic client registration). Your app keeps its own user model, token signing, and login/consent UI through pluggable hooks — the user model never leaves your app.
+
+```typescript
+import { App, bodyParser } from '@ttoss/http-server';
+import { createMcpAuthServer } from '@ttoss/http-server-mcp';
+
+const authServer = createMcpAuthServer({
+  issuer: 'https://api.example.com',
+  clientStore, // register/lookup dynamic clients
+  authCodeStore, // persist short-lived codes + PKCE challenge
+  // App-owned token minting — ttoss never sees your signing keys
+  issueTokens: async ({ subject, scopes }) => ({
+    accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
+    refreshToken: createRefreshToken(subject),
+    expiresIn: 3600,
+  }),
+  // App-owned login/consent — show your own UI, then approve
+  onAuthorize: async ({ ctx, request }) => {
+    const session = await getSession(ctx);
+    if (!session) {
+      ctx.redirect(`/login?return_to=${encodeURIComponent(ctx.url)}`);
+      return { approved: false };
+    }
+    return { approved: true, subject: session.userId, scopes: request.scopes };
+  },
+  // App-owned refresh validation — required to enable the refresh_token grant
+  onRefreshToken: async ({ refreshToken }) => {
+    const claims = await verifyRefreshToken(refreshToken);
+    return claims ? { subject: claims.sub, scopes: claims.scopes } : undefined;
+  },
+  scopesSupported: ['mcp:access'],
+});
+
+const app = new App();
+app.use(bodyParser());
+app.use(authServer.routes());
+```
+
+This mounts:
+
+| Endpoint                                  | Spec      | Purpose                                              |
+| ----------------------------------------- | --------- | ---------------------------------------------------- |
+| `/.well-known/oauth-authorization-server` | RFC 8414  | Authorization server metadata discovery              |
+| `/.well-known/oauth-protected-resource`   | RFC 9728  | Protected-resource metadata (when `resource` is set) |
+| `/authorize`                              | OAuth 2.1 | Authorization endpoint — **PKCE (S256) required**    |
+| `/token`                                  | OAuth 2.1 | `authorization_code` + `refresh_token` grants        |
+| `/register`                               | RFC 7591  | Dynamic Client Registration                          |
+
+The full flow an MCP client runs: it fetches the discovery document, self-registers at `/register`, opens `/authorize` (your `onAuthorize` handles login/consent), exchanges the returned code at `/token` with its PKCE verifier, and uses the access token against your `createMcpRouter` endpoint. Pair this with `createMcpRouter({ auth: { verifyToken } })` so the same server both issues and verifies tokens.
+
+The pluggable stores let you keep persistence in your own datastore:
+
+```typescript
+const clientStore: ClientStore = {
+  get: (clientId) => db.clients.findById(clientId),
+  register: (client) => db.clients.put(client),
+};
+
+const authCodeStore: AuthCodeStore = {
+  save: (code) => db.codes.put(code), // set a TTL matching authorizationCodeTtl
+  get: (code) => db.codes.findById(code),
+  delete: (code) => db.codes.remove(code),
+};
+```
+
 ## API Reference
 
 ### `createMcpRouter(server, options?)`
@@ -337,6 +406,25 @@ Creates a Koa router configured to handle MCP protocol requests.
 
 **Returns:** `Router` — Koa router instance
 
+### `createMcpAuthServer(options)`
+
+Creates an OAuth 2.1 Authorization Server (`/authorize`, `/token`, `/register`, and discovery metadata) for MCP clients. See [OAuth 2.1 Authorization Server](#oauth-21-authorization-server).
+
+**Parameters (`McpAuthServerOptions`):**
+
+- `issuer` (`string`) — The authorization server's issuer identifier (its base URL); used to build absolute endpoint URLs in the discovery document
+- `clientStore` (`ClientStore`) — `{ get(clientId), register(client) }` for dynamic clients
+- `authCodeStore` (`AuthCodeStore`) — `{ save(code), get(code), delete(code) }` for short-lived authorization codes (codes are single-use)
+- `issueTokens` (`({ subject, scopes, client }) => IssuedTokens`) — App-owned token minting; returns `{ accessToken, refreshToken?, expiresIn?, scope? }`
+- `onAuthorize` (`({ ctx, client, request }) => OnAuthorizeResult`) — App-owned login/consent; return `{ approved: true, subject, scopes? }` to issue a code, or take over the response and return `{ approved: false }`
+- `onRefreshToken` (`({ refreshToken, client, scopes }) => { subject, scopes } | undefined`, optional) — App-owned refresh-token validation; required to enable the `refresh_token` grant
+- `scopesSupported` (`string[]`, optional) — Advertised in discovery metadata as `scopes_supported`
+- `resource` (`string`, optional) — When set, also serves `/.well-known/oauth-protected-resource`
+- `authorizationCodeTtl` (`number`, optional) — Authorization code lifetime in seconds (default: `600`)
+- `endpoints` (`{ authorize?, token?, register? }`, optional) — Override the default endpoint paths
+
+**Returns:** `Router` — Koa router instance exposing `routes()` / `allowedMethods()`
+
 ### `apiCall(method, url, options?)`
 
 Generic HTTP helper for use inside MCP tool handlers.

package/dist/index.cjs

@@ -7,8 +7,379 @@ let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextp
 let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let _ttoss_http_server = require("@ttoss/http-server");
 let zod = require("zod");
+let node_crypto = require("node:crypto");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 
+//#region src/authServerHandlers.ts
+var base64UrlEncode = buffer => {
+  return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+/** Generates a URL-safe random token of the given byte length. */
+var generateToken = (bytes = 32) => {
+  return base64UrlEncode((0, node_crypto.randomBytes)(bytes));
+};
+var sha256Base64Url = input => {
+  return base64UrlEncode((0, node_crypto.createHash)("sha256").update(input).digest());
+};
+/** Verifies a PKCE `code_verifier` against a stored S256 `code_challenge`. */
+var verifyPkce = (codeVerifier, codeChallenge) => {
+  return sha256Base64Url(codeVerifier) === codeChallenge;
+};
+/** Joins an issuer base URL with a path, collapsing any duplicate slash. */
+var joinUrl = (issuer, path) => {
+  return `${issuer.replace(/\/$/, "")}${path}`;
+};
+/** Returns the value if it is a string, otherwise `undefined`. */
+var asString = value => {
+  return typeof value === "string" ? value : void 0;
+};
+var parseScopes = scope => {
+  const value = asString(scope);
+  return value ? value.split(" ").filter(Boolean) : [];
+};
+/** Writes a spec-compliant OAuth error response (RFC 6749 §5.2). */
+var sendOAuthError = (ctx, status, error, description) => {
+  ctx.status = status;
+  ctx.body = {
+    error,
+    error_description: description
+  };
+};
+var buildTokenResponse = (tokens, scopes) => {
+  return {
+    access_token: tokens.accessToken,
+    token_type: "Bearer",
+    ...(tokens.expiresIn !== void 0 ? {
+      expires_in: tokens.expiresIn
+    } : {}),
+    ...(tokens.refreshToken !== void 0 ? {
+      refresh_token: tokens.refreshToken
+    } : {}),
+    scope: tokens.scope ?? scopes.join(" ")
+  };
+};
+/**
+* Authenticates the client at the token endpoint via `client_secret_basic`
+* (Authorization header), `client_secret_post` (body), or `none` (public,
+* PKCE-only). Returns the client, or `undefined` when authentication fails.
+*/
+var authenticateClient = async (ctx, body, clientStore) => {
+  let clientId = asString(body.client_id);
+  let clientSecret = asString(body.client_secret);
+  const authHeader = ctx.headers.authorization;
+  if (authHeader?.startsWith("Basic ")) {
+    const decoded = Buffer.from(authHeader.slice(6), "base64").toString();
+    const separatorIndex = decoded.indexOf(":");
+    if (separatorIndex !== -1) {
+      clientId = decodeURIComponent(decoded.slice(0, separatorIndex));
+      clientSecret = decodeURIComponent(decoded.slice(separatorIndex + 1));
+    }
+  }
+  if (!clientId) return;
+  const client = await clientStore.get(clientId);
+  if (!client) return;
+  if (client.client_secret && client.client_secret !== clientSecret) return;
+  return client;
+};
+/** Handles `grant_type=authorization_code` token requests (with PKCE verify). */
+var handleAuthorizationCodeGrant = async (ctx, body, options) => {
+  const {
+    clientStore,
+    authCodeStore,
+    issueTokens
+  } = options;
+  const client = await authenticateClient(ctx, body, clientStore);
+  if (!client) {
+    sendOAuthError(ctx, 401, "invalid_client", "client authentication failed");
+    return;
+  }
+  const code = asString(body.code);
+  if (!code) {
+    sendOAuthError(ctx, 400, "invalid_request", "code is required");
+    return;
+  }
+  const stored = await authCodeStore.get(code);
+  await authCodeStore.delete(code);
+  if (!stored) {
+    sendOAuthError(ctx, 400, "invalid_grant", "invalid or expired authorization code");
+    return;
+  }
+  if (stored.expiresAt < Date.now()) {
+    sendOAuthError(ctx, 400, "invalid_grant", "authorization code expired");
+    return;
+  }
+  if (stored.clientId !== client.client_id) {
+    sendOAuthError(ctx, 400, "invalid_grant", "authorization code was not issued to this client");
+    return;
+  }
+  if (stored.redirectUri !== asString(body.redirect_uri)) {
+    sendOAuthError(ctx, 400, "invalid_grant", "redirect_uri mismatch");
+    return;
+  }
+  const codeVerifier = asString(body.code_verifier);
+  if (!codeVerifier) {
+    sendOAuthError(ctx, 400, "invalid_request", "code_verifier is required");
+    return;
+  }
+  if (!verifyPkce(codeVerifier, stored.codeChallenge)) {
+    sendOAuthError(ctx, 400, "invalid_grant", "PKCE verification failed");
+    return;
+  }
+  ctx.body = buildTokenResponse(await issueTokens({
+    subject: stored.subject,
+    scopes: stored.scopes,
+    client
+  }), stored.scopes);
+};
+/** Handles `grant_type=refresh_token` token requests. */
+var handleRefreshTokenGrant = async (ctx, body, options) => {
+  const {
+    clientStore,
+    issueTokens,
+    onRefreshToken
+  } = options;
+  const client = await authenticateClient(ctx, body, clientStore);
+  if (!client) {
+    sendOAuthError(ctx, 401, "invalid_client", "client authentication failed");
+    return;
+  }
+  if (!onRefreshToken) {
+    sendOAuthError(ctx, 400, "unsupported_grant_type", "refresh_token grant is not supported");
+    return;
+  }
+  const refreshToken = asString(body.refresh_token);
+  if (!refreshToken) {
+    sendOAuthError(ctx, 400, "invalid_request", "refresh_token is required");
+    return;
+  }
+  const result = await onRefreshToken({
+    refreshToken,
+    client,
+    scopes: parseScopes(body.scope)
+  });
+  if (!result) {
+    sendOAuthError(ctx, 400, "invalid_grant", "invalid refresh token");
+    return;
+  }
+  ctx.body = buildTokenResponse(await issueTokens({
+    subject: result.subject,
+    scopes: result.scopes,
+    client
+  }), result.scopes);
+};
+/**
+* Handles the authorization request after `client_id` and `redirect_uri` have
+* been validated: enforces PKCE, runs the consent hook, and issues a code.
+*/
+var handleAuthorize = async (ctx, options, redirectUri) => {
+  const {
+    clientStore,
+    authCodeStore,
+    onAuthorize
+  } = options;
+  const ttl = options.authorizationCodeTtl ?? 600;
+  const clientId = asString(ctx.query.client_id);
+  const client = await clientStore.get(clientId);
+  const state = asString(ctx.query.state);
+  const redirectError = (error, description) => {
+    const url = new URL(redirectUri);
+    url.searchParams.set("error", error);
+    url.searchParams.set("error_description", description);
+    if (state) url.searchParams.set("state", state);
+    ctx.redirect(url.toString());
+  };
+  if (asString(ctx.query.response_type) !== "code") {
+    redirectError("unsupported_response_type", "response_type must be code");
+    return;
+  }
+  const codeChallenge = asString(ctx.query.code_challenge);
+  if (!codeChallenge) {
+    redirectError("invalid_request", "code_challenge is required (PKCE)");
+    return;
+  }
+  const codeChallengeMethod = asString(ctx.query.code_challenge_method) ?? "plain";
+  if (codeChallengeMethod !== "S256") {
+    redirectError("invalid_request", "code_challenge_method must be S256");
+    return;
+  }
+  const scopes = parseScopes(ctx.query.scope);
+  const result = await onAuthorize({
+    ctx,
+    client,
+    request: {
+      clientId,
+      redirectUri,
+      scopes,
+      state,
+      codeChallenge,
+      codeChallengeMethod
+    }
+  });
+  if (!result.approved) return;
+  const grantedScopes = result.scopes ?? scopes;
+  const code = generateToken();
+  await authCodeStore.save({
+    code,
+    clientId,
+    redirectUri,
+    codeChallenge,
+    scopes: grantedScopes,
+    subject: result.subject,
+    expiresAt: Date.now() + ttl * 1e3
+  });
+  const url = new URL(redirectUri);
+  url.searchParams.set("code", code);
+  if (state) url.searchParams.set("state", state);
+  ctx.redirect(url.toString());
+};
+/** Handles Dynamic Client Registration (RFC 7591) requests. */
+var handleRegister = async (ctx, clientStore) => {
+  const metadata = ctx.request.body ?? {};
+  const redirectUris = metadata.redirect_uris;
+  if (!Array.isArray(redirectUris) || redirectUris.length === 0 || !redirectUris.every(uri => {
+    return typeof uri === "string";
+  })) {
+    sendOAuthError(ctx, 400, "invalid_redirect_uri", "redirect_uris is required and must be an array of strings");
+    return;
+  }
+  const tokenAuthMethod = asString(metadata.token_endpoint_auth_method) ?? "client_secret_basic";
+  const isPublic = tokenAuthMethod === "none";
+  const client = {
+    ...metadata,
+    client_id: generateToken(16),
+    redirect_uris: redirectUris,
+    token_endpoint_auth_method: tokenAuthMethod,
+    grant_types: metadata.grant_types ?? ["authorization_code", "refresh_token"],
+    response_types: metadata.response_types ?? ["code"],
+    client_id_issued_at: Math.floor(Date.now() / 1e3)
+  };
+  if (!isPublic) {
+    client.client_secret = generateToken(32);
+    client.client_secret_expires_at = 0;
+  }
+  await clientStore.register(client);
+  ctx.status = 201;
+  ctx.body = client;
+};
+
+//#endregion
+//#region src/authServer.ts
+/**
+* Creates transport-agnostic OAuth 2.1 Authorization Server primitives for MCP.
+*
+* Mounts the authorization endpoint (`/authorize`, PKCE S256 required), token
+* endpoint (`/token`, `authorization_code` + `refresh_token` grants), Dynamic
+* Client Registration (`/register`, RFC 7591), and AS metadata discovery
+* (`/.well-known/oauth-authorization-server`, RFC 8414). When `resource` is
+* set, it also serves the protected-resource metadata (RFC 9728).
+*
+* ttoss owns only the protocol mechanics — the app supplies its own stores,
+* token signing/verification, and login/consent UI through the option hooks, so
+* the user model, JWT/IAM, and authentication never leave the consuming app.
+*
+* @param options - Authorization server configuration and pluggable hooks.
+* @returns A Koa `Router` exposing `routes()` / `allowedMethods()`.
+*
+* @example
+* ```typescript
+* import { App, bodyParser } from '@ttoss/http-server';
+* import { createMcpAuthServer } from '@ttoss/http-server-mcp';
+*
+* const authServer = createMcpAuthServer({
+*   issuer: 'https://api.soat.dev',
+*   clientStore,
+*   authCodeStore,
+*   issueTokens: async ({ subject, scopes }) => ({
+*     accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
+*     refreshToken: createRefreshToken(subject),
+*     expiresIn: 3600,
+*   }),
+*   onAuthorize: async ({ ctx }) => {
+*     const session = await getSession(ctx);
+*     if (!session) {
+*       ctx.redirect('/login');
+*       return { approved: false };
+*     }
+*     return { approved: true, subject: session.userId };
+*   },
+*   scopesSupported: ['mcp:access'],
+* });
+*
+* const app = new App();
+* app.use(bodyParser());
+* app.use(authServer.routes());
+* ```
+*/
+var createMcpAuthServer = options => {
+  const {
+    issuer,
+    clientStore,
+    scopesSupported,
+    resource
+  } = options;
+  const authorizePath = options.endpoints?.authorize ?? "/authorize";
+  const tokenPath = options.endpoints?.token ?? "/token";
+  const registerPath = options.endpoints?.register ?? "/register";
+  const router = new _ttoss_http_server.Router();
+  router.get("/.well-known/oauth-authorization-server", ctx => {
+    ctx.body = {
+      issuer,
+      authorization_endpoint: joinUrl(issuer, authorizePath),
+      token_endpoint: joinUrl(issuer, tokenPath),
+      registration_endpoint: joinUrl(issuer, registerPath),
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      code_challenge_methods_supported: ["S256"],
+      token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post", "none"],
+      ...(scopesSupported ? {
+        scopes_supported: scopesSupported
+      } : {})
+    };
+  });
+  if (resource) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource,
+      authorization_servers: [issuer]
+    };
+  });
+  router.get(authorizePath, async ctx => {
+    const clientId = asString(ctx.query.client_id);
+    if (!clientId) {
+      sendOAuthError(ctx, 400, "invalid_request", "client_id is required");
+      return;
+    }
+    const client = await clientStore.get(clientId);
+    if (!client) {
+      sendOAuthError(ctx, 400, "invalid_client", "unknown client_id");
+      return;
+    }
+    const redirectUri = asString(ctx.query.redirect_uri);
+    if (!redirectUri || !client.redirect_uris.includes(redirectUri)) {
+      sendOAuthError(ctx, 400, "invalid_request", "redirect_uri is missing or not registered for this client");
+      return;
+    }
+    await handleAuthorize(ctx, options, redirectUri);
+  });
+  router.post(tokenPath, async ctx => {
+    const body = ctx.request.body ?? {};
+    const grantType = asString(body.grant_type);
+    if (grantType === "authorization_code") {
+      await handleAuthorizationCodeGrant(ctx, body, options);
+      return;
+    }
+    if (grantType === "refresh_token") {
+      await handleRefreshTokenGrant(ctx, body, options);
+      return;
+    }
+    sendOAuthError(ctx, 400, "unsupported_grant_type", "grant_type must be authorization_code or refresh_token");
+  });
+  router.post(registerPath, async ctx => {
+    await handleRegister(ctx, clientStore);
+  });
+  return router;
+};
+
+//#endregion
 //#region src/index.ts
 var requestContextStore = new node_async_hooks.AsyncLocalStorage();
 /**
@@ -446,6 +817,7 @@ Object.defineProperty(exports, 'McpServer', {
 });
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
+exports.createMcpAuthServer = createMcpAuthServer;
 exports.createMcpRouter = createMcpRouter;
 exports.createProtectedResourceMetadataMiddleware = createProtectedResourceMetadataMiddleware;
 exports.getIdentity = getIdentity;