@ttoss/http-server-mcp 0.13.8 → 0.15.0

package/README.md

@@ -169,7 +169,7 @@ const mcpRouter = createMcpRouter(mcpServer, {
 
 ### Custom verifier
 
-Pass an async `verifyToken` function for any other provider (Auth0, Keycloak, etc.):
+Pass an async `verifyToken` function for any provider — JWT-based or opaque. The contract is simply: resolve with an identity payload on success, or throw on failure.
 
 ```typescript
 import { createMcpRouter } from '@ttoss/http-server-mcp';
@@ -189,6 +189,25 @@ const mcpRouter = createMcpRouter(mcpServer, {
 });
 ```
 
+**Opaque token (database lookup):** `verifyToken` does not have to be JWT-based — a plain API-key lookup works equally well:
+
+```typescript
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    verifyToken: async (token) => {
+      // Look up the hashed token in your database
+      const record = await db.apiKeys.findByHash(sha256(token));
+      if (!record || record.revokedAt) {
+        throw new Error('Invalid API key');
+      }
+      return { sub: record.userId, scope: record.scopes.join(' ') };
+    },
+  },
+});
+```
+
+The router emits `401 Unauthorized` whenever `verifyToken` throws, regardless of whether you are using JWTs or opaque tokens.
+
 ### Accessing the verified identity
 
 Inside any tool handler, call `getIdentity()` to retrieve the verified JWT payload:
@@ -245,7 +264,9 @@ Cognito encodes scopes as a space-separated string in `payload.scope` (e.g. `"op
 
 ### OAuth Protected Resource Metadata
 
-For MCP clients that support OAuth auto-discovery, add `resourceServerUrl` and `authorizationServerUrl` to expose the `/.well-known/oauth-protected-resource` endpoint (RFC 9728):
+MCP clients (Claude, Cursor, etc.) fetch `/.well-known/oauth-protected-resource` to discover which authorization server issues tokens for your MCP server. The endpoint must be **unauthenticated** — MCP clients call it before they have a token.
+
+**With the built-in `auth` option** — add `resourceServerUrl` and `authorizationServerUrl`:
 
 ```typescript
 createMcpRouter(mcpServer, {
@@ -258,6 +279,111 @@ createMcpRouter(mcpServer, {
 });
 ```
 
+**With your own auth middleware** — use `createProtectedResourceMetadataMiddleware` as a standalone middleware, mounted _before_ your auth layer so discovery stays unauthenticated:
+
+```typescript
+import {
+  createProtectedResourceMetadataMiddleware,
+  getWwwAuthenticateHeader,
+} from '@ttoss/http-server-mcp';
+
+// Mount the discovery endpoint before your own auth middleware
+app.use(
+  createProtectedResourceMetadataMiddleware({
+    resource: 'https://mcp.example.com',
+    authorizationServers: ['https://api.example.com'],
+  })
+);
+
+// Your own auth middleware — emit the spec-compliant WWW-Authenticate header on 401s
+app.use(async (ctx, next) => {
+  const token = ctx.headers.authorization?.replace('Bearer ', '');
+  if (!token || !(await myVerify(token))) {
+    ctx.status = 401;
+    ctx.set(
+      'WWW-Authenticate',
+      getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' })
+    );
+    ctx.body = 'Unauthorized';
+    return;
+  }
+  await next();
+});
+
+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?)`
@@ -280,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.
@@ -307,6 +452,27 @@ Asserts that the current request token contains all required scopes. Throws `Err
 
 - `required` (`string[]`) — Scope strings that must all be present in `payload.scope`
 
+### `createProtectedResourceMetadataMiddleware(args)`
+
+Creates a standalone Koa middleware that serves `GET /.well-known/oauth-protected-resource` (RFC 9728). Use this when you have your own auth middleware and don't want to tie the discovery endpoint to the built-in `auth` option.
+
+**Parameters:**
+
+- `args.resource` (`string`) — The protected resource's identifier URI (your MCP server URL)
+- `args.authorizationServers` (`string[]`) — Issuer URIs of the authorization servers that protect this resource
+
+**Returns:** `Koa.Middleware`
+
+### `getWwwAuthenticateHeader(args)`
+
+Returns the `WWW-Authenticate` header value for a 401 response, formatted per the MCP auth spec: `Bearer resource_metadata="<resource>/.well-known/oauth-protected-resource"`.
+
+**Parameters:**
+
+- `args.resource` (`string`) — The protected resource URL (trailing slash is stripped automatically)
+
+**Returns:** `string` — The full `WWW-Authenticate` header value
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.

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();
 /**
@@ -380,6 +751,62 @@ var registerToolFromSchema = (server, params) => {
     });
   }
 };
+/**
+* Returns the `WWW-Authenticate` header value for a 401 response on a
+* protected resource, following the MCP auth spec requirement that
+* unauthorized responses advertise the resource metadata URL so MCP
+* clients can bootstrap OAuth discovery.
+*
+* Use this in your own auth middleware when you are not using the built-in
+* `auth` option on `createMcpRouter`.
+*
+* @example
+* ```typescript
+* import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
+*
+* // Inside a Koa middleware
+* ctx.status = 401;
+* ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
+* ```
+*/
+var getWwwAuthenticateHeader = args => {
+  return `Bearer resource_metadata="${`${args.resource.replace(/\/$/, "")}/.well-known/oauth-protected-resource`}"`;
+};
+/**
+* Creates a standalone Koa middleware that serves
+* `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
+* the built-in `auth` option on `createMcpRouter`.
+*
+* Mount this **before** your own auth middleware so the discovery endpoint
+* remains unauthenticated (MCP clients fetch it before they have a token).
+*
+* @example
+* ```typescript
+* import Koa from 'koa';
+* import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
+*
+* const app = new Koa();
+* app.use(
+*   createProtectedResourceMetadataMiddleware({
+*     resource: 'https://mcp.example.com',
+*     authorizationServers: ['https://api.example.com'],
+*   })
+* );
+* app.use(myOwnAuthMiddleware);
+* ```
+*/
+var createProtectedResourceMetadataMiddleware = args => {
+  return async (ctx, next) => {
+    if (ctx.method === "GET" && ctx.path === "/.well-known/oauth-protected-resource") {
+      ctx.body = {
+        resource: args.resource,
+        authorization_servers: args.authorizationServers
+      };
+      return;
+    }
+    await next();
+  };
+};
 
 //#endregion
 Object.defineProperty(exports, 'McpServer', {
@@ -390,8 +817,11 @@ Object.defineProperty(exports, 'McpServer', {
 });
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
+exports.createMcpAuthServer = createMcpAuthServer;
 exports.createMcpRouter = createMcpRouter;
+exports.createProtectedResourceMetadataMiddleware = createProtectedResourceMetadataMiddleware;
 exports.getIdentity = getIdentity;
+exports.getWwwAuthenticateHeader = getWwwAuthenticateHeader;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {
   enumerable: true,