@casys/mcp-server 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casys/mcp-server",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
   "type": "module",
   "main": "mod.ts",

package/src/auth/config.ts

@@ -28,33 +28,14 @@ const VALID_PROVIDERS: AuthProviderName[] = [
 ];
 
 /**
- * Parsed auth configuration (after YAML + env merge).
- *
- * TODO(0.17.0): convert to a discriminated union on `provider`. Each variant
- * should encode which provider-specific fields are required:
- *   - `"github"` / `"google"`: base only
- *   - `"auth0"`: base + required `domain`
- *   - `"oidc"`: base + required `issuer`, optional `jwksUri`
- * This lifts the current runtime checks in `loadAuthConfig()` (lines ~167-178)
- * to the type level, matching what 0.16.0 did for `JwtAuthProviderOptions`.
- *
- * Tracked in:
- *   - GitHub issue: https://github.com/Casys-AI/mcp-server/issues/11 (primary)
- *   - `CHANGELOG.md` [Unreleased] section
- * Hard trigger: do this refactor the next time a new provider preset is added
- * (per 0.16.0 type-design review recommendation — don't let it slip past 0.17.0).
+ * Fields shared by all {@link AuthConfig} variants.
  */
-export interface AuthConfig {
-  provider: AuthProviderName;
+interface AuthConfigBase {
+  /** JWT audience (aud claim) */
   audience: string;
+  /** RFC 9728 § 2 resource identifier (HTTP(S) URL or opaque URI) */
   resource: string;
-  /** Auth0 tenant domain */
-  domain?: string;
-  /** OIDC issuer */
-  issuer?: string;
-  /** OIDC JWKS URI (optional, derived from issuer if absent) */
-  jwksUri?: string;
-  /** Supported scopes */
+  /** Scopes supported by this server */
   scopesSupported?: string[];
   /**
    * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
@@ -69,6 +50,62 @@ export interface AuthConfig {
   resourceMetadataUrl?: string;
 }
 
+/** Auth config for GitHub Actions OIDC (no provider-specific fields). */
+export interface GitHubAuthConfig extends AuthConfigBase {
+  provider: "github";
+}
+
+/** Auth config for Google OIDC (no provider-specific fields). */
+export interface GoogleAuthConfig extends AuthConfigBase {
+  provider: "google";
+}
+
+/** Auth config for Auth0 — `domain` is REQUIRED at the type level. */
+export interface Auth0AuthConfig extends AuthConfigBase {
+  provider: "auth0";
+  /** Auth0 tenant domain (e.g., `"my-tenant.auth0.com"`). */
+  domain: string;
+}
+
+/** Auth config for generic OIDC — `issuer` is REQUIRED at the type level. */
+export interface OIDCAuthConfig extends AuthConfigBase {
+  provider: "oidc";
+  /** OIDC issuer URL (used as both JWT `iss` and JWKS discovery root). */
+  issuer: string;
+  /** JWKS URI, optional — derived from `issuer` if absent. */
+  jwksUri?: string;
+}
+
+/**
+ * Parsed auth configuration (after YAML + env merge).
+ *
+ * 0.17.0: discriminated union on `provider` tag. Each variant encodes
+ * its provider-specific required fields at the type level:
+ *   - `"github"` / `"google"`: base only
+ *   - `"auth0"`: base + required `domain`
+ *   - `"oidc"`: base + required `issuer`, optional `jwksUri`
+ *
+ * TypeScript narrows on `config.provider`, so `createAuthProviderFromConfig`
+ * no longer needs non-null assertions (`config.domain!`) — the required
+ * fields are typed correctly in each branch.
+ *
+ * The runtime checks in `loadAuthConfig()` stay as defense-in-depth for
+ * YAML/env input (untyped), but TS callers constructing `AuthConfig` literals
+ * directly now get compile-time safety.
+ *
+ * BREAKING from 0.16.x: callers who constructed `AuthConfig` literals with
+ * optional `domain`/`issuer` and relied on runtime validation now get a
+ * compile error if they don't match a variant's required fields. Migration:
+ * ensure the literal satisfies the discriminated variant (e.g.,
+ * `provider: "auth0"` requires `domain`). See
+ * `Casys-AI/mcp-server#11`.
+ */
+export type AuthConfig =
+  | GitHubAuthConfig
+  | GoogleAuthConfig
+  | Auth0AuthConfig
+  | OIDCAuthConfig;
+
 /**
  * YAML file schema (top-level has `auth` key).
  */
@@ -124,18 +161,20 @@ export async function loadAuthConfig(
   const envResourceMetadataUrl = env("MCP_AUTH_RESOURCE_METADATA_URL");
 
   // 3. Merge: env overrides YAML
-  const provider = envProvider ?? yamlAuth?.provider;
+  const providerRaw = envProvider ?? yamlAuth?.provider;
 
   // No provider configured anywhere → no auth
-  if (!provider) return null;
+  if (!providerRaw) return null;
 
-  // Validate provider name
-  if (!VALID_PROVIDERS.includes(provider as AuthProviderName)) {
+  // Validate provider name — untyped YAML/env input requires a runtime check
+  // even after 0.17.0's compile-time DU. This is the defense-in-depth layer.
+  if (!VALID_PROVIDERS.includes(providerRaw as AuthProviderName)) {
     throw new Error(
-      `[AuthConfig] Unknown auth provider: "${provider}". ` +
+      `[AuthConfig] Unknown auth provider: "${providerRaw}". ` +
         `Valid values: ${VALID_PROVIDERS.join(", ")}`,
     );
   }
+  const provider = providerRaw as AuthProviderName;
 
   const audience = envAudience ?? yamlAuth?.audience;
   const resource = envResource ?? yamlAuth?.resource;
@@ -153,13 +192,9 @@ export async function loadAuthConfig(
     );
   }
 
-  const config: AuthConfig = {
-    provider: provider as AuthProviderName,
+  const base: AuthConfigBase = {
     audience,
     resource,
-    domain: envDomain ?? yamlAuth?.domain,
-    issuer: envIssuer ?? yamlAuth?.issuer,
-    jwksUri: envJwksUri ?? yamlAuth?.jwksUri,
     scopesSupported: envScopes
       ? envScopes.split(" ").filter(Boolean)
       : yamlAuth?.scopesSupported,
@@ -167,26 +202,87 @@ export async function loadAuthConfig(
       yamlAuth?.resourceMetadataUrl,
   };
 
-  // Provider-specific validation (fail-fast)
-  if (config.provider === "auth0" && !config.domain) {
-    throw new Error(
-      '[AuthConfig] "domain" is required for auth0 provider. ' +
-        "Set auth.domain in YAML or MCP_AUTH_DOMAIN env var.",
-    );
-  }
-  if (config.provider === "oidc" && !config.issuer) {
-    throw new Error(
-      '[AuthConfig] "issuer" is required for oidc provider. ' +
-        "Set auth.issuer in YAML or MCP_AUTH_ISSUER env var.",
-    );
+  // 4. Construct the correct DU variant, enforcing provider-specific
+  // required fields at runtime. The runtime checks mirror the type-level
+  // constraints in the DU variants (Auth0AuthConfig.domain, OIDCAuthConfig.issuer).
+  //
+  // The `issuer` / `domain` fields are URL-shaped at runtime even though the
+  // DU variants type them as `string`. 0.17.0 runs them through `new URL()`
+  // here (at the YAML/env boundary) to catch typos like
+  // `MCP_AUTH_ISSUER=not-a-url` with a clear error naming the offending field,
+  // instead of surfacing a confusing `authorizationServers[0]` error deep
+  // inside the preset bridge later (pre-existing issue caught during 0.17.0
+  // review, code-reviewer finding).
+  switch (provider) {
+    case "github":
+      return { provider: "github", ...base };
+    case "google":
+      return { provider: "google", ...base };
+    case "auth0": {
+      const domain = envDomain ?? yamlAuth?.domain;
+      if (!domain) {
+        throw new Error(
+          '[AuthConfig] "domain" is required for auth0 provider. ' +
+            "Set auth.domain in YAML or MCP_AUTH_DOMAIN env var.",
+        );
+      }
+      return { provider: "auth0", ...base, domain };
+    }
+    case "oidc": {
+      const issuer = envIssuer ?? yamlAuth?.issuer;
+      if (!issuer) {
+        throw new Error(
+          '[AuthConfig] "issuer" is required for oidc provider. ' +
+            "Set auth.issuer in YAML or MCP_AUTH_ISSUER env var.",
+        );
+      }
+      try {
+        const parsed = new URL(issuer);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+          throw new Error(
+            `[AuthConfig] "issuer" for oidc provider must use http(s):// ` +
+              `scheme, got ${JSON.stringify(parsed.protocol)} in ` +
+              `${JSON.stringify(issuer)}.`,
+          );
+        }
+      } catch (err) {
+        // If new URL() threw, re-wrap with AuthConfig-labelled error.
+        // If our explicit scheme check threw, re-throw as-is (already labelled).
+        if (err instanceof Error && err.message.startsWith("[AuthConfig]")) {
+          throw err;
+        }
+        throw new Error(
+          `[AuthConfig] "issuer" for oidc provider is not a valid URL: ` +
+            `${JSON.stringify(issuer)}. Set auth.issuer in YAML or ` +
+            `MCP_AUTH_ISSUER env var to an absolute http(s)://... URL.`,
+        );
+      }
+      const jwksUri = envJwksUri ?? yamlAuth?.jwksUri;
+      return { provider: "oidc", ...base, issuer, jwksUri };
+    }
+    default: {
+      // Exhaustiveness guard: future provider additions land here as a TS
+      // error at this function. Runtime throw is belt-and-suspenders — the
+      // earlier `VALID_PROVIDERS.includes` check at line ~130 already
+      // eliminates unknown provider strings.
+      const _exhaustive: never = provider;
+      throw new Error(
+        `[AuthConfig] Unreachable — unhandled provider ${
+          JSON.stringify(_exhaustive)
+        }`,
+      );
+    }
   }
-
-  return config;
 }
 
 /**
  * Create an AuthProvider from a loaded AuthConfig.
  *
+ * 0.17.0: `config` is a discriminated union on `provider`, so TypeScript
+ * narrows `config.domain`/`config.issuer` as required (non-optional) in
+ * their respective branches. No more non-null assertions (`config.domain!`)
+ * or defensive runtime checks here — the type system guarantees them.
+ *
  * @param config - Validated auth config
  * @returns AuthProvider instance
  */
@@ -204,16 +300,25 @@ export function createAuthProviderFromConfig(config: AuthConfig): AuthProvider {
     case "google":
       return createGoogleAuthProvider(base);
     case "auth0":
-      return createAuth0AuthProvider({ ...base, domain: config.domain! });
+      return createAuth0AuthProvider({ ...base, domain: config.domain });
     case "oidc":
       return createOIDCAuthProvider({
         ...base,
-        issuer: config.issuer!,
+        issuer: config.issuer,
         jwksUri: config.jwksUri,
-        authorizationServers: [config.issuer!],
+        authorizationServers: [config.issuer],
       });
-    default:
-      throw new Error(`[AuthConfig] Unsupported provider: ${config.provider}`);
+    default: {
+      // Exhaustiveness guard matching the one in loadAuthConfig — when a
+      // 5th variant is added to AuthConfig, TS flags this function as
+      // incomplete before any caller is affected.
+      const _exhaustive: never = config;
+      throw new Error(
+        `[AuthConfig] Unreachable — unhandled variant ${
+          JSON.stringify(_exhaustive)
+        }`,
+      );
+    }
   }
 }
 

package/src/auth/jwt-provider.ts

@@ -18,7 +18,7 @@ import {
 import { isOtelEnabled, recordAuthEvent } from "../observability/otel.js";
 
 // ============================================================================
-// JwtAuthProviderOptions — discriminated union (0.16.0)
+// JwtAuthProviderOptions — tagged discriminated union (0.17.0)
 // ============================================================================
 
 /**
@@ -46,11 +46,18 @@ interface JwtAuthProviderOptionsBase {
 
 /**
  * Options where `resource` is a verified HTTP(S) URL. The metadata URL is
- * auto-derived when `resourceMetadataUrl` is omitted, by appending
- * `/.well-known/oauth-protected-resource` to `resource`.
+ * auto-derived when `resourceMetadataUrl` is omitted, by applying RFC 9728
+ * § 3.1 insertion to `resource`.
+ *
+ * Tagged with `kind: "url"` so TypeScript narrowing is sound at the function
+ * body level (see 0.17.0 CHANGELOG — this fixes finding C1 from the 0.16.0
+ * review where narrowing on `resourceMetadataUrl === undefined` failed to
+ * propagate because `HttpsUrl extends string` collapsed the union).
  */
 export interface JwtAuthProviderOptionsUrlResource
   extends JwtAuthProviderOptionsBase {
+  /** Discriminant tag — MUST be `"url"` for this branch. */
+  kind: "url";
   /** RFC 9728 § 2 resource identifier, pre-validated as HTTP(S) URL. */
   resource: HttpsUrl;
   /**
@@ -63,9 +70,16 @@ export interface JwtAuthProviderOptionsUrlResource
  * Options where `resource` is an opaque URI (per RFC 9728 § 2 — e.g., an
  * OIDC project ID used as JWT audience). The metadata URL is MANDATORY
  * because it cannot be derived from an opaque identifier.
+ *
+ * Tagged with `kind: "opaque"` to make the DU structurally disjoint (see
+ * finding C2 from the 0.16.0 review — without the tag, `UrlResource` was
+ * a structural subtype of `OpaqueResource` because `HttpsUrl extends
+ * string`).
  */
 export interface JwtAuthProviderOptionsOpaqueResource
   extends JwtAuthProviderOptionsBase {
+  /** Discriminant tag — MUST be `"opaque"` for this branch. */
+  kind: "opaque";
   /** RFC 9728 § 2 opaque resource identifier (NOT an URL). */
   resource: string;
   /**
@@ -78,21 +92,30 @@ export interface JwtAuthProviderOptionsOpaqueResource
 /**
  * Configuration for JwtAuthProvider.
  *
- * 0.16.0: discriminated union enforcing at compile time that callers with an
- * opaque `resource` MUST supply `resourceMetadataUrl` explicitly. TypeScript
- * narrows based on which branch accepts the given fields:
+ * 0.17.0: tagged discriminated union on `kind: "url" | "opaque"`. TypeScript
+ * narrowing is now structurally sound — `if (options.kind === "url")` truly
+ * narrows `options.resource` to `HttpsUrl` at the constructor body level.
+ * The tag also makes the branches strictly disjoint: a caller cannot
+ * accidentally satisfy `OpaqueResource` with an `HttpsUrl`-branded `resource`
+ * (as was possible in 0.16.x — finding C2 from the type-design review).
+ *
+ * - `kind: "url"` → {@link JwtAuthProviderOptionsUrlResource},
+ *   `resource: HttpsUrl` (wrap with {@link httpsUrl}),
+ *   `resourceMetadataUrl` optional (auto-derived).
+ * - `kind: "opaque"` → {@link JwtAuthProviderOptionsOpaqueResource},
+ *   `resource: string` (raw opaque identifier),
+ *   `resourceMetadataUrl: HttpsUrl` REQUIRED.
  *
- * - `resource: HttpsUrl` (via {@link httpsUrl}) → {@link
- *   JwtAuthProviderOptionsUrlResource} branch, `resourceMetadataUrl`
- *   optional (auto-derived from `resource`).
- * - `resource: string` (raw) → {@link JwtAuthProviderOptionsOpaqueResource}
- *   branch, `resourceMetadataUrl: HttpsUrl` REQUIRED.
+ * The preset factories and the public `buildJwtAuthProvider` bridge accept
+ * raw string `resource` and set the `kind` tag automatically via detection
+ * — only callers that construct `JwtAuthProvider` directly (not through the
+ * bridge) need to supply `kind` themselves. Custom OIDC providers written
+ * on top of `buildJwtAuthProvider` are unaffected.
  *
- * A caller forgetting to wrap an HTTP(S) URL in `httpsUrl()` gets a compile
- * error telling them to either wrap the resource or supply an explicit
- * metadata URL — structurally closing the bug class that 0.15.x fixed with
- * runtime guards (see `postmortems/phase8-deployment.md` § 7 and
- * `CHANGELOG.md` 0.15.0 / 0.15.1 for the motivating history).
+ * BREAKING from 0.16.x: every direct `new JwtAuthProvider(...)` site must
+ * add `kind: "url"` or `kind: "opaque"`. Preset users are unaffected.
+ * See `postmortems/phase8-deployment.md` § 7 and `CHANGELOG.md` 0.15.0 /
+ * 0.15.1 / 0.16.0 for the bug-class history this refactor closes.
  */
 export type JwtAuthProviderOptions =
   | JwtAuthProviderOptionsUrlResource
@@ -113,17 +136,35 @@ interface CachedAuth {
 /**
  * JWT Auth Provider with JWKS validation.
  *
- * @example
+ * @example URL resource (auto-derives metadata URL)
  * ```typescript
  * import { httpsUrl, JwtAuthProvider } from "@casys/mcp-server";
  *
  * const provider = new JwtAuthProvider({
+ *   kind: "url",
  *   issuer: "https://accounts.google.com",
  *   audience: "https://my-mcp.example.com",
  *   resource: httpsUrl("https://my-mcp.example.com"),
  *   authorizationServers: [httpsUrl("https://accounts.google.com")],
  * });
  * ```
+ *
+ * @example Opaque resource (explicit metadata URL required)
+ * ```typescript
+ * import { httpsUrl, JwtAuthProvider } from "@casys/mcp-server";
+ *
+ * // RFC 9728 § 2 Option B: OIDC project ID as JWT audience
+ * const provider = new JwtAuthProvider({
+ *   kind: "opaque",
+ *   issuer: "https://my-tenant.zitadel.cloud",
+ *   audience: "367545125829670172",
+ *   resource: "367545125829670172",
+ *   resourceMetadataUrl: httpsUrl(
+ *     "https://my-mcp.example.com/.well-known/oauth-protected-resource",
+ *   ),
+ *   authorizationServers: [httpsUrl("https://my-tenant.zitadel.cloud")],
+ * });
+ * ```
  */
 export class JwtAuthProvider extends AuthProvider {
   private jwks: ReturnType<typeof createRemoteJWKSet>;
@@ -154,37 +195,28 @@ export class JwtAuthProvider extends AuthProvider {
       );
     }
 
-    // DU invariant: the `OpaqueResource` branch requires `resourceMetadataUrl`,
-    // so at runtime the `else` branch below can only be reached when the
-    // caller constructed via the `UrlResource` branch — meaning
-    // `options.resource` is, by construction at input time, a valid
-    // `HttpsUrl`. TypeScript does NOT narrow this at the function-body level
-    // (because `HttpsUrl extends string`, the union `HttpsUrl | string`
-    // collapses to `string`, and there is no tag field to discriminate on),
-    // so the type-checker sees `options.resource: string` here — but the
-    // runtime value is guaranteed parseable because it came through
-    // `httpsUrl()` at the call site. The `new URL()` call below is therefore
-    // sound, and the `httpsUrl()` wrapper on the derived value acts as
-    // defense-in-depth.
+    // 0.17.0: narrow on the `kind` discriminant tag. TypeScript structurally
+    // narrows the DU here — after `if (options.kind === "opaque")`, `options`
+    // is `JwtAuthProviderOptionsOpaqueResource` and `resourceMetadataUrl` is
+    // guaranteed non-undefined; after `else`, `options` is
+    // `JwtAuthProviderOptionsUrlResource` and `options.resource` is
+    // `HttpsUrl` (no widening, no runtime guess). This fixes finding C1 from
+    // the 0.16.0 review — the previous narrowing on `resourceMetadataUrl !==
+    // undefined` was unsound because `HttpsUrl extends string` collapsed the
+    // union back to `string`. Tagging makes the branches strictly disjoint.
     //
-    // Derivation follows RFC 9728 § 3.1 exactly: when the resource has a
-    // path or query component, the well-known path suffix is inserted
-    // BETWEEN the host and the path, not appended after it:
+    // URL branch derivation follows RFC 9728 § 3.1: when `resource` has a
+    // path or query component, the well-known suffix is INSERTED between
+    // the host and the path, not appended after it:
     //
     //   resource  = https://api.example.com/v1/mcp
     //   metadata  = https://api.example.com/.well-known/oauth-protected-resource/v1/mcp
     //
-    // Prior to 0.16.0 the derivation was a naive `${resource}/.well-known/...`
-    // concat which produced `.../v1/mcp/.well-known/oauth-protected-resource`
-    // — a 404 for RFC 9728-compliant discovery clients. Root-path resources
-    // (`pathname === "/"`) are the only case the old code happened to get
-    // right; everything else was silently broken. All current tests exercise
-    // root-path resources which is why the bug survived until the 0.16.0
-    // review (see `code-reviewer` findings).
-    //
     // Fragments (`#...`) are intentionally dropped — they're client-side-only
     // per RFC 3986 § 3.5 and never part of a server-side metadata endpoint.
-    if (options.resourceMetadataUrl !== undefined) {
+    if (options.kind === "opaque") {
+      this.resourceMetadataUrl = options.resourceMetadataUrl;
+    } else if (options.resourceMetadataUrl !== undefined) {
       this.resourceMetadataUrl = options.resourceMetadataUrl;
     } else {
       const parsed = new URL(options.resource);

package/src/auth/mod.ts

@@ -52,13 +52,27 @@ export type {
 
 // OIDC Presets
 export {
+  buildJwtAuthProvider,
   createAuth0AuthProvider,
   createGitHubAuthProvider,
   createGoogleAuthProvider,
   createOIDCAuthProvider,
 } from "./presets.js";
-export type { OIDCPresetOptions, PresetOptions } from "./presets.js";
+export type {
+  BuildJwtAuthProviderOptions,
+  OIDCPresetOptions,
+  PresetOptions,
+} from "./presets.js";
 
 // Config loader (YAML + env)
 export { createAuthProviderFromConfig, loadAuthConfig } from "./config.js";
-export type { AuthConfig, AuthProviderName } from "./config.js";
+// `AuthConfig` is a discriminated union in 0.17.0 — each variant is also
+// exported for callers that want to annotate variables explicitly.
+export type {
+  Auth0AuthConfig,
+  AuthConfig,
+  AuthProviderName,
+  GitHubAuthConfig,
+  GoogleAuthConfig,
+  OIDCAuthConfig,
+} from "./config.js";

package/src/auth/presets.ts

@@ -86,7 +86,7 @@ export interface OIDCPresetOptions extends PresetOptions {
 export function createGitHubAuthProvider(
   options: PresetOptions,
 ): JwtAuthProvider {
-  return buildJwtProvider({
+  return buildJwtAuthProvider({
     issuer: "https://token.actions.githubusercontent.com",
     audience: options.audience,
     authorizationServers: ["https://token.actions.githubusercontent.com"],
@@ -113,7 +113,7 @@ export function createGitHubAuthProvider(
 export function createGoogleAuthProvider(
   options: PresetOptions,
 ): JwtAuthProvider {
-  return buildJwtProvider({
+  return buildJwtAuthProvider({
     issuer: "https://accounts.google.com",
     audience: options.audience,
     authorizationServers: ["https://accounts.google.com"],
@@ -143,7 +143,7 @@ export function createAuth0AuthProvider(
   options: PresetOptions & { domain: string },
 ): JwtAuthProvider {
   const issuer = `https://${options.domain}/`;
-  return buildJwtProvider({
+  return buildJwtAuthProvider({
     issuer,
     audience: options.audience,
     authorizationServers: [issuer],
@@ -172,7 +172,7 @@ export function createAuth0AuthProvider(
 export function createOIDCAuthProvider(
   options: OIDCPresetOptions,
 ): JwtAuthProvider {
-  return buildJwtProvider({
+  return buildJwtAuthProvider({
     issuer: options.issuer,
     audience: options.audience,
     jwksUri: options.jwksUri,
@@ -184,43 +184,112 @@ export function createOIDCAuthProvider(
 }
 
 // ============================================================================
-// Internal bridge: raw strings → branded JwtAuthProviderOptions
+// Public bridge: raw strings → branded JwtAuthProviderOptions
 // ============================================================================
 
 /**
- * Internal options for the bridge helper.
+ * Raw-string options accepted by {@link buildJwtAuthProvider}. Mirrors
+ * {@link JwtAuthProviderOptions} but with all URL fields as plain `string`
+ * instead of {@link HttpsUrl}, and without the `kind` discriminant tag
+ * (the bridge auto-detects).
+ *
+ * Exported for 3rd-party OIDC provider implementations that want to accept
+ * YAML/env-style raw string config and delegate URL validation to the
+ * bridge instead of reimplementing it. See `createGitHubAuthProvider`,
+ * `createGoogleAuthProvider`, `createAuth0AuthProvider`, and
+ * `createOIDCAuthProvider` for built-in consumers.
  */
-interface BuildJwtProviderOptions {
+export interface BuildJwtAuthProviderOptions {
+  /** JWT issuer (iss claim) */
   issuer: string;
+  /** JWT audience (aud claim) */
   audience: string;
+  /**
+   * JWKS URI for signature validation. Defaults to
+   * `{issuer}/.well-known/jwks.json` when omitted.
+   */
   jwksUri?: string;
+  /**
+   * Authorization servers that issue valid tokens, as raw strings. Each
+   * entry must be a valid absolute HTTP(S) URL — the bridge validates
+   * via {@link httpsUrl} and throws with a preset-named error if invalid.
+   */
   authorizationServers: string[];
+  /** Scopes supported by this server */
   scopesSupported?: string[];
+  /**
+   * RFC 9728 § 2 resource identifier, as a raw string. The bridge detects
+   * whether this is an HTTP(S) URL or an opaque URI and picks the correct
+   * {@link JwtAuthProviderOptions} branch internally. When opaque, you
+   * MUST also supply {@link resourceMetadataUrl}.
+   */
   resource: string;
+  /**
+   * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
+   * metadata document is served publicly (RFC 9728 § 3). Required when
+   * `resource` is an opaque URI; optional when `resource` is itself an
+   * HTTP(S) URL. Empty and whitespace-only values are treated as absent.
+   */
   resourceMetadataUrl?: string;
 }
 
 /**
- * Bridge raw-string preset options to the branded {@link JwtAuthProviderOptions}
- * discriminated union used by the core `JwtAuthProvider` constructor.
+ * Bridge raw-string options to a fully-constructed `JwtAuthProvider`.
  *
- * This helper centralizes the preset → constructor translation so:
- *   1. All four presets share one validation pathway.
- *   2. Error messages name the preset that failed (via `presetName`).
- *   3. The DU branch choice (URL resource vs opaque) happens in exactly
- *      one place.
+ * This is the shared validation + DU-branch-selection pathway used by all
+ * four built-in preset factories (`createGitHubAuthProvider` et al). 0.17.0
+ * exports it as public API so 3rd-party OIDC provider implementations
+ * (Keycloak, Zitadel custom, Okta, ...) can reuse the same pathway instead
+ * of reimplementing URL-vs-opaque detection, `HttpsUrl` wrapping, and
+ * empty-metadata fall-through.
  *
  * Rules:
- * - `authorizationServers[]`: every entry must be a valid HTTP(S) URL.
- * - `resource`: if parseable as HTTP(S) URL → UrlResource branch (metadata
- *   URL derivable). Otherwise → OpaqueResource branch requiring explicit
- *   `resourceMetadataUrl`.
+ * - `authorizationServers[]`: every entry must be a valid absolute HTTP(S)
+ *   URL. Invalid entries throw with a `[${label}] authorizationServers[i]`
+ *   prefix for pinpointing.
+ * - `resource`: if parseable as HTTP(S) URL → `UrlResource` branch (metadata
+ *   URL derivable per RFC 9728 § 3.1). Otherwise → `OpaqueResource` branch
+ *   requiring explicit `resourceMetadataUrl`.
  * - `resourceMetadataUrl`: empty or whitespace-only strings are treated as
  *   absent (matches YAML-key-with-no-value semantics from 0.15.1).
+ *
+ * @param opts Raw-string options, as from YAML/env config.
+ * @param label Identifier used in error messages — REQUIRED. Pass your
+ *   factory name so error prefixes point at the actual caller rather than
+ *   the anonymous bridge layer. E.g., `"createKeycloakAuthProvider"`.
+ *   (0.17.0: required, was optional with a misleading default in the
+ *   draft — type-design review recommendation Q4.)
+ *
+ * @example Custom OIDC provider factory
+ * ```typescript
+ * import { buildJwtAuthProvider, type JwtAuthProvider } from "@casys/mcp-server";
+ *
+ * export interface KeycloakPresetOptions {
+ *   keycloakHost: string;
+ *   realm: string;
+ *   audience: string;
+ *   resource: string;
+ *   resourceMetadataUrl?: string;
+ * }
+ *
+ * export function createKeycloakAuthProvider(
+ *   options: KeycloakPresetOptions,
+ * ): JwtAuthProvider {
+ *   const issuer = `https://${options.keycloakHost}/realms/${options.realm}`;
+ *   return buildJwtAuthProvider({
+ *     issuer,
+ *     audience: options.audience,
+ *     authorizationServers: [issuer],
+ *     jwksUri: `${issuer}/protocol/openid-connect/certs`,
+ *     resource: options.resource,
+ *     resourceMetadataUrl: options.resourceMetadataUrl,
+ *   }, "createKeycloakAuthProvider");
+ * }
+ * ```
  */
-function buildJwtProvider(
-  opts: BuildJwtProviderOptions,
-  presetName: string,
+export function buildJwtAuthProvider(
+  opts: BuildJwtAuthProviderOptions,
+  label: string,
 ): JwtAuthProvider {
   const wrappedAuthServers: HttpsUrl[] = opts.authorizationServers.map(
     (raw, i) => {
@@ -228,7 +297,7 @@ function buildJwtProvider(
         return httpsUrl(raw);
       } catch (err) {
         throw new Error(
-          `[${presetName}] authorizationServers[${i}] is not a valid ` +
+          `[${label}] authorizationServers[${i}] is not a valid ` +
             `HTTP(S) URL: ${(err as Error).message}`,
         );
       }
@@ -250,9 +319,12 @@ function buildJwtProvider(
 
   const resourceUrl = tryHttpsUrl(opts.resource);
   if (resourceUrl !== null) {
-    // URL resource branch — metadata URL optional (derivable)
+    // URL resource branch — metadata URL optional (derivable). 0.17.0 sets
+    // the explicit `kind: "url"` tag so the DU narrowing in the constructor
+    // body is structurally sound.
     return new JwtAuthProvider({
       ...base,
+      kind: "url",
       resource: resourceUrl,
       resourceMetadataUrl: explicitMetadata,
     });
@@ -261,7 +333,7 @@ function buildJwtProvider(
   // Opaque resource branch — metadata URL required
   if (!explicitMetadata) {
     throw new Error(
-      `[${presetName}] resourceMetadataUrl is required when 'resource' is ` +
+      `[${label}] resourceMetadataUrl is required when 'resource' is ` +
         `not an HTTP(S) URL (got resource=${JSON.stringify(opts.resource)}). ` +
         `Per RFC 9728 § 2, 'resource' can be an opaque URI (e.g., an OIDC ` +
         `project ID used as JWT audience); in that case the metadata ` +
@@ -272,6 +344,7 @@ function buildJwtProvider(
   }
   return new JwtAuthProvider({
     ...base,
+    kind: "opaque",
     resource: opts.resource,
     resourceMetadataUrl: explicitMetadata,
   });

package/src/auth/types.ts

@@ -129,19 +129,30 @@ export interface AuthInfo {
 }
 
 /**
- * Auth configuration for the server.
+ * Auth configuration slot for {@link McpAppOptions.auth}.
+ *
+ * 0.17.0: slimmed to a single `provider` field. Previously exposed
+ * `authorizationServers`, `resource`, and `scopesSupported` fields that
+ * were NEVER read by `McpApp` at runtime (only `provider` was consumed at
+ * `mcp-app.ts:1061`). Those fields were vestigial from a pre-0.15 design
+ * where `McpApp` could auto-construct a `JwtAuthProvider` from its own
+ * `auth:` option; that auto-construction path was removed when
+ * `createAuthProviderFromConfig` took over YAML/env provider construction,
+ * but the dead fields stayed in the interface. 0.17.0 deletes them as part
+ * of the auth-module cleanup (Casys-AI/mcp-server#13).
+ *
+ * The interface is kept (rather than reducing `McpAppOptions.auth` to a
+ * bare `AuthProvider`) so that future additions like pipeline-level auth
+ * hooks have a named extension point without another BC break.
  */
 export interface AuthOptions {
-  /** Authorization servers that issue valid tokens */
-  authorizationServers: string[];
-
-  /** Resource identifier for this MCP server (used in WWW-Authenticate header) */
-  resource: string;
-
-  /** Scopes supported by this server */
-  scopesSupported?: string[];
-
-  /** Custom auth provider (overrides default JWT validation) */
+  /**
+   * The `AuthProvider` that validates bearer tokens and produces RFC 9728
+   * metadata. Construct via {@link JwtAuthProvider}, any of the preset
+   * factories (`createGitHubAuthProvider`, `createGoogleAuthProvider`,
+   * `createAuth0AuthProvider`, `createOIDCAuthProvider`), or a custom
+   * `AuthProvider` subclass for non-JWT token schemes.
+   */
   provider: AuthProvider;
 }