@ttoss/http-server-mcp 0.14.0 → 0.16.0

package/dist/index.mjs

@@ -1,11 +1,452 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { z, z as z$1 } from "zod";
+import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
+import { createHash, randomBytes } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+//#region src/auth.ts
+/** MCP lifecycle/discovery methods reachable before a client authenticates. */
+var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* Builds the token verifier from the auth options, preferring an explicit
+* `verifyToken` and otherwise creating a `CognitoJwtVerifier`.
+*/
+var buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+/** Returns true when the identity carries every required scope (or none are required). */
+var hasRequiredScopes = (requiredScopes, identity) => {
+  if (!requiredScopes?.length) return true;
+  const tokenScopes = (identity?.scope ?? "").split(" ");
+  return requiredScopes.every(s => {
+    return tokenScopes.includes(s);
+  });
+};
+/**
+* Registers the token-verification middleware (with public-method bypass and
+* RFC 9728 discovery) and, when configured, the OAuth protected-resource
+* metadata endpoint on the given router.
+*/
+var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
+  const unauthorizedHeader = auth.resourceMetadataUrl ? `Bearer resource_metadata="${auth.resourceMetadataUrl}"` : "Bearer";
+  router.use(path, async (ctx, next) => {
+    const method = ctx.request.body?.method;
+    if (publicMethods.has(method ?? "")) {
+      await next();
+      return;
+    }
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", unauthorizedHeader);
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (!hasRequiredScopes(auth.requiredScopes, identity)) {
+      ctx.status = 403;
+      ctx.body = "Forbidden";
+      return;
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+
+//#endregion
+//#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(randomBytes(bytes));
+};
+var sha256Base64Url = input => {
+  return base64UrlEncode(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 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 AsyncLocalStorage();
 /**
@@ -122,52 +563,6 @@ var checkScopes = required => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
 };
-var buildTokenVerifier = auth => {
-  if (auth.cognitoUserPool) {
-    const v = CognitoJwtVerifier.create({
-      tokenUse: "access",
-      ...auth.cognitoUserPool
-    });
-    return t => {
-      return v.verify(t);
-    };
-  }
-  if (auth.verifyToken) return auth.verifyToken;
-  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
-};
-var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
-  router.use(path, async (ctx, next) => {
-    const authHeader = ctx.headers.authorization;
-    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
-    let identity;
-    try {
-      identity = await tokenVerifier(token);
-    } catch {
-      ctx.status = 401;
-      ctx.set("WWW-Authenticate", "Bearer");
-      ctx.body = "Unauthorized";
-      return;
-    }
-    if (auth.requiredScopes?.length) {
-      const tokenScopes = (identity?.scope ?? "").split(" ");
-      if (auth.requiredScopes.filter(s => {
-        return !tokenScopes.includes(s);
-      }).length > 0) {
-        ctx.status = 403;
-        ctx.body = "Forbidden";
-        return;
-      }
-    }
-    ctx.state.identity = identity;
-    await next();
-  });
-  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
-    ctx.body = {
-      resource: auth.resourceServerUrl,
-      authorization_servers: [auth.authorizationServerUrl]
-    };
-  });
-};
 /**
 * Creates a Koa router configured to handle MCP protocol requests
 *
@@ -435,4 +830,4 @@ var createProtectedResourceMetadataMiddleware = args => {
 };
 
 //#endregion
-export { McpServer, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { McpServer, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,8 +35,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@ttoss/http-server": "^0.6.1",
-    "@ttoss/auth-core": "^0.6.0"
+    "@ttoss/auth-core": "^0.6.0",
+    "@ttoss/http-server": "^0.6.1"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",