@webpieces/mcp-server 0.4.990 → 0.4.991

package/src/McpAuth.d.ts

@@ -1,5 +1,5 @@
-import { McpToolProfiles } from '@webpieces/core-util';
-import { AuthenticatedCaller, AuthorizationService } from '@webpieces/http-routing';
+import { AuthMethod } from '@webpieces/core-util';
+import { AuthenticatedCaller, CredentialVerifiers } from '@webpieces/http-routing';
 import { Icon } from '@modelcontextprotocol/server';
 import { McpIcon } from './McpIcon';
 export declare const MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS: number;
@@ -41,8 +41,8 @@ export declare class VerifiedMcpCredential {
     get principalRoles(): readonly string[];
 }
 /**
- * Application-owned paired mint/verify authority for resource-bound MCP access tokens.
- * `verifyAccessToken` must throw `ApiUnauthorizedError` for a token it rejects (the bind boundary
+ * Application-owned paired mint/verify authority for resource-bound MCP access tokens, handed to
+ * `mcpOAuth(...)`. `verifyAccessToken` must throw `ApiUnauthorizedError` for a token it rejects (the bind boundary
  * answers 401 + `WWW-Authenticate`); any other throw is treated as an implementation failure (500).
  */
 export interface McpAccessTokenAuthority<TGrant> {
@@ -58,41 +58,51 @@ export declare class McpProtectedResourceMetadata {
     constructor(resource: string, authorizationServers: readonly string[], scopesSupported?: readonly string[]);
 }
 /**
- * Node MCP server configuration, built with fluent setters: every name sits next to its own value, so
- * no two settings can be swapped, and a future setting is an additive setter rather than a breaking
- * signature change. The access-token authority verifies MCP credentials; the authorization service
- * is shared with receiving endpoints and document projection.
+ * One member of a server's `setAuth([...])` set: an `@WpAuth` builder (`oidcSameProject()`,
+ * `oidcSvcs([...])`, `jwt()`, `apiKey(...)`, `sharedSecret(...)`) or `mcpOAuth(...)`.
+ */
+export type McpHttpAuth = AuthMethod | McpOAuthMode;
+/** A server's `setAuth([...])` set: at least one mode. */
+export type McpHttpAuths = readonly [McpHttpAuth, ...McpHttpAuth[]];
+/**
+ * Node MCP HTTP server configuration, built with fluent setters: every name sits next to its own
+ * value, so no two settings can be swapped, and a future setting is an additive setter rather than a
+ * breaking signature change.
  *
- * SINGLE CANONICAL ORIGIN: one server serves exactly one protected resource. {@link setResource} is
- * fixed for the lifetime of the process, is the audience of every access token, and is never derived
- * from the request `Host` — see that setter for why a host-derived audience is a confused deputy.
+ * WHICH tools the server serves is not here: that is the `McpToolset` handed to
+ * `new WpMcpServer(config, toolset)`. This config says only who the server is and HOW A CALLER GETS
+ * IN — {@link setAuth}, an OR-set of the same `@WpAuth` builders an endpoint uses plus `mcpOAuth(...)`.
+ *
+ * SINGLE CANONICAL ORIGIN: one server serves exactly one resource. {@link setResource} is fixed for
+ * the lifetime of the process, is the audience of every `mcpOAuth(...)` access token, and is never
+ * derived from the request `Host` — see that setter for why a host-derived audience is a confused
+ * deputy.
  *
  * Each setter validates its own value immediately and names itself in the failure. Setters cannot
  * make a field impossible to forget the way a positional constructor could, so
  * {@link WpMcpServerConfig.validate} runs from `WpMcpServer.bind(...)` and fails at startup listing
  * EVERY missing required setter at once. A misconfiguration is therefore a boot failure naming the
- * setter, instead of a first-request 401 + `WWW-Authenticate` — which is the OAuth discovery signal,
- * so the client's correct response is to re-authenticate and fail again, forever.
+ * setter, instead of a first-request 401 — which, with `mcpOAuth(...)`, is the OAuth discovery
+ * signal, so the client's correct response is to re-authenticate and fail again, forever.
  *
  * ```ts
- * const config = new WpMcpServerConfig<MyGrant>()
+ * const config = new WpMcpServerConfig()
  *     .setName('my-server')
  *     .setTitle('My Product')
  *     .setDescription('Search and manage My Product accounts from any MCP client.')
  *     .setWebsiteUrl('https://www.example.com/my-product')
  *     .setVersion('1.0.0')
- *     .setResource('https://api.example.com/mcp')
- *     .setAccessTokenAuthority(authority)
- *     .setAuthorizationService(router.authorizationService())
- *     .setAuthorizationServers(['https://login.example.com'])
- *     .setRequiredScopes(['tools']);
+ *     .setResource('https://api.example.com/mcp/user')
+ *     .setAuth([oidcSameProject()])                       // internal svc-to-svc MCP
+ *     .setCredentialVerifiers(router.credentialVerifiers());
+ * //  .setAuth([oidcSameProject(), jwt(), apiKey('partner', creds),
+ * //            mcpOAuth(authority, ['https://login.example.com'], ['tools'], McpAccessTokenFormat.opaquePrefix('wpmcp_'))])
  *
  * // the tools/call error translator is a PROCESS-GLOBAL, not a member of this config:
  * McpRegistry.setErrorTranslator(new MyMcpErrorTranslator());
  * ```
  */
-export declare class WpMcpServerConfig<TGrant> {
-    private toolProfilesValue;
+export declare class WpMcpServerConfig {
     private nameValue?;
     private titleValue?;
     private descriptionValue?;
@@ -100,14 +110,8 @@ export declare class WpMcpServerConfig<TGrant> {
     private versionValue?;
     private iconsValue?;
     private resourceValue?;
-    private accessTokenAuthorityValue?;
-    private authorizationServiceValue?;
-    private authorizationServersValue?;
-    private requiredScopesValue?;
-    private maxAccountValidationAgeSecondsValue;
-    /** OPTIONAL. Union of groups exposed by this instance; defaults to [Mcp.DEFAULT]. */
-    setToolProfiles(profiles: McpToolProfiles): this;
-    get toolProfiles(): readonly string[];
+    private authValue?;
+    private credentialVerifiersValue?;
     /** REQUIRED. The MCP server name reported by `initialize`. */
     setName(name: string): this;
     /**
@@ -140,9 +144,9 @@ export declare class WpMcpServerConfig<TGrant> {
     /** Immutable snapshot; omitted icons remain absent from SDK implementation metadata. */
     get icons(): readonly McpIcon[] | undefined;
     /**
-     * REQUIRED. The ONE canonical protected-resource URI, which must be an absolute URL: it is the
-     * exact audience every access token is checked against, and {@link resourceMetadataUrl} is
-     * derived from it for the 401 challenge, so a non-URL here is always a mistake — including a
+     * REQUIRED. The ONE canonical resource URI, which must be an absolute URL: it is the exact
+     * audience every `mcpOAuth(...)` access token is checked against, and {@link resourceMetadataUrl}
+     * is derived from it for the 401 challenge, so a non-URL here is always a mistake — including a
      * name or version landed on it.
      *
      * It is fixed for the lifetime of the process and must NEVER be derived from the request `Host`
@@ -153,23 +157,23 @@ export declare class WpMcpServerConfig<TGrant> {
      * audience.
      */
     setResource(resource: string): this;
-    /** REQUIRED. Application-owned paired mint/verify authority for MCP access tokens. */
-    setAccessTokenAuthority(authority: McpAccessTokenAuthority<TGrant>): this;
-    /** REQUIRED. The common authorization service for tool projection and invocation. */
-    setAuthorizationService(authority: AuthorizationService): this;
     /**
-     * REQUIRED. The trusted token issuers. Every entry must be an absolute URL, because each is
-     * compared against a token's `issuer` claim and published as an `authorization_servers` entry —
-     * which is what makes a scope list landed here fail at boot rather than on the first request.
+     * REQUIRED. HOW a caller gets in: an OR-set of the `@WpAuth` builders endpoints already use —
+     * `oidcSameProject()`, `oidcSvcs([...])`, `jwt()`, `apiKey(regime, creds)`, `sharedSecret(key)` —
+     * plus `mcpOAuth(...)` for off-the-shelf connectors. Each request is CLASSIFIED from unverified
+     * surface facts (which header; a JWT's unverified `iss`) and handed to exactly ONE verifier, whose
+     * rejection is the answer — it never falls through to another mode.
+     *
+     * `vendorAuth(...)` and `@WpAuthPublic` identify no caller to authorize tools against, so they are
+     * refused at bind; so is a set whose modes could both claim one request.
      */
-    setAuthorizationServers(authorizationServers: readonly string[]): this;
+    setAuth(auth: McpHttpAuths): this;
     /**
-     * REQUIRED, and empty only by saying so explicitly. Scopes every access token must carry before
-     * any tool is dispatched.
+     * REQUIRED when {@link setAuth} holds any `@WpAuth` mode (everything but `mcpOAuth(...)`): the
+     * verifiers this app bound, from `router.credentialVerifiers()` — the SAME JwtHook, OidcHook /
+     * DefaultOidcVerifier, AuthConfig and ApiKeyHook the endpoint `AuthFilter` uses.
      */
-    setRequiredScopes(requiredScopes: readonly string[]): this;
-    /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */
-    setMaxAccountValidationAgeSeconds(seconds: number): this;
+    setCredentialVerifiers(verifiers: CredentialVerifiers): this;
     /**
      * Called by `WpMcpServer.bind(...)`. Throws naming EVERY missing required setter at once, so a
      * half-built config is repaired in one pass rather than one boot failure at a time.
@@ -181,29 +185,84 @@ export declare class WpMcpServerConfig<TGrant> {
     get websiteUrl(): string;
     get version(): string;
     get resource(): string;
-    get accessTokenAuthority(): McpAccessTokenAuthority<TGrant>;
-    get authorizationService(): AuthorizationService;
-    get authorizationServers(): readonly string[];
-    get requiredScopes(): readonly string[];
-    get maxAccountValidationAgeSeconds(): number;
+    get auth(): McpHttpAuths;
+    /** The bound verifiers, or `undefined` for an `mcpOAuth(...)`-only server, which needs none. */
+    get credentialVerifiers(): CredentialVerifiers | undefined;
     /**
      * RFC 9728 §3.1: the URL of this resource's protected-resource METADATA DOCUMENT, derived from
      * {@link resource} by inserting `/.well-known/oauth-protected-resource` between origin and path
      * (`https://host/mcp` → `https://host/.well-known/oauth-protected-resource/mcp`).
      *
      * This — never the resource identifier itself — is what RFC 9728 §5.1 defines `resource_metadata`
-     * to be, so it is the value webpieces puts in the 401 `WWW-Authenticate` challenge. webpieces
-     * mounts no `.well-known` route; publish {@link protectedResourceMetadata} at this URL.
+     * to be, so it is the value webpieces puts in the `mcpOAuth(...)` 401 `WWW-Authenticate`
+     * challenge. webpieces mounts no `.well-known` route; publish
+     * `WpMcpServer.protectedResourceMetadata()` at this URL.
      */
     get resourceMetadataUrl(): string;
-    protectedResourceMetadata(): McpProtectedResourceMetadata;
     /** Copies caller-owned descriptors and nested size arrays before freezing the snapshot. */
     private snapshotIcons;
     private requireText;
     private requireUrl;
     private requireMaxLength;
-    private requireArray;
-    private requireSeconds;
-    private requirePresent;
     private read;
 }
+/** Google's OIDC issuers. An `mcpOAuth(...)` issuer may never be one: it would claim Google tokens. */
+export declare const GOOGLE_OIDC_ISSUERS: readonly string[];
+/** The unsigned off-GCP OIDC token prefix `@webpieces/gcp-identity` mints and verifies. */
+export declare const DEV_OIDC_TOKEN_PREFIX = "dev-oidc.";
+/** Every JWT starts with the base64url of `{"`. An opaque prefix starting so would claim JWTs. */
+export declare const JWT_PREFIX = "eyJ";
+export type McpAccessTokenFormatKind = 'opaque-prefix' | 'jwt-issuer' | 'every-bearer';
+/** The trusted token issuers of an `mcpOAuth(...)` mode: at least one absolute URL. */
+export type McpAuthorizationServers = readonly [string, ...string[]];
+/**
+ * How an `mcpOAuth(...)` access token LOOKS, decided by the authority that mints it. The MCP door
+ * classifies every request from unverified surface facts before handing it to exactly ONE verifier, so
+ * the OAuth mode must say which bearers are its kind without any crypto or I/O:
+ *
+ * - {@link opaquePrefix} — the authority mints opaque tokens that all start with `prefix`
+ *   (e.g. `'wpmcp_'`). Disjoint from every JWT and from off-GCP OIDC tokens by construction.
+ * - {@link jwtIssuer} — the authority mints JWTs whose `iss` is one of the mode's
+ *   `authorizationServers`. A JWT with any other issuer is not this mode's.
+ * - {@link everyBearer} — every `Authorization: Bearer` credential is this mode's. Legal ONLY when no
+ *   other bearer mode (`oidcSameProject()`, `oidcSvcs(...)`, `jwt()`, a bearer `apiKey(...)`) is in the
+ *   same `setAuth([...])`; startup refuses the combination, because two modes claiming one token is
+ *   exactly the overlap classify-then-verify forbids.
+ */
+export declare class McpAccessTokenFormat {
+    readonly kind: McpAccessTokenFormatKind;
+    readonly prefix: string;
+    private constructor();
+    static opaquePrefix(prefix: string): McpAccessTokenFormat;
+    static jwtIssuer(): McpAccessTokenFormat;
+    static everyBearer(): McpAccessTokenFormat;
+}
+/**
+ * The MCP OAuth mode: today's connector behavior (Claude / ChatGPT) as ONE member of a server's
+ * `setAuth([...])` set. It is the only mode that publishes RFC 9728 protected-resource metadata and
+ * answers a request carrying no credential with the `401 WWW-Authenticate` discovery challenge, and
+ * its access tokens are audience-bound to the server's canonical resource. Build it with
+ * {@link mcpOAuth}.
+ */
+export declare class McpOAuthMode {
+    readonly authority: McpAccessTokenAuthority<never>;
+    readonly authorizationServers: McpAuthorizationServers;
+    readonly requiredScopes: readonly string[];
+    readonly tokenFormat: McpAccessTokenFormat;
+    readonly maxAccountValidationAgeSeconds: number;
+    readonly kind = "mcp-oauth";
+    constructor(authority: McpAccessTokenAuthority<never>, authorizationServers: McpAuthorizationServers, requiredScopes: readonly string[], tokenFormat: McpAccessTokenFormat, maxAccountValidationAgeSeconds: number);
+    /** RFC 9728 metadata for `resource`, published by the app at the server's `resourceMetadataUrl`. */
+    protectedResourceMetadata(resource: string): McpProtectedResourceMetadata;
+}
+/**
+ * The MCP OAuth door mode, for off-the-shelf connectors. Everything OAuth-only lives here and is
+ * required only when this mode is in the server's `setAuth([...])`:
+ *
+ * @param authority            the application-owned paired mint/verify authority
+ * @param authorizationServers the trusted token issuers, published as `authorization_servers`
+ * @param requiredScopes       scopes every access token must carry before any tool is dispatched
+ * @param tokenFormat          how the authority's tokens look, so the door can classify them
+ * @param maxAccountValidationAgeSeconds how fresh the account facts must be, 1 second to 1 hour
+ */
+export declare function mcpOAuth<TGrant>(authority: McpAccessTokenAuthority<TGrant>, authorizationServers: McpAuthorizationServers, requiredScopes: readonly string[], tokenFormat: McpAccessTokenFormat, maxAccountValidationAgeSeconds?: number): McpOAuthMode;