@casys/mcp-server 0.15.0 → 0.16.0

package/package.json

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

package/src/auth/config.ts

@@ -29,6 +29,16 @@ 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 157-168)
+ * to the type level, matching what 0.16.0 did for `JwtAuthProviderOptions`.
+ * See `CHANGELOG.md` [Unreleased] section and
+ * `memory/project_mcp_server_016_deferred.md` for the deferred-work anchor.
  */
 export interface AuthConfig {
   provider: AuthProviderName;
@@ -47,9 +57,9 @@ export interface AuthConfig {
    * metadata document is served publicly (RFC 9728 § 3).
    *
    * Required when `resource` is an opaque URI (e.g., an OIDC project ID used
-   * as JWT audience per RFC 9728 § 2) — otherwise `JwtAuthProvider` will
+   * as JWT audience per RFC 9728 § 2) — otherwise preset factories will
    * throw at construction. When `resource` is itself an HTTP(S) URL, this
-   * field is optional and auto-derived by the factory. Mirrors
+   * field is optional and auto-derived by the preset bridge layer. Mirrors
    * `JwtAuthProviderOptions.resourceMetadataUrl`.
    */
   resourceMetadataUrl?: string;

package/src/auth/jwt-provider.ts

@@ -9,57 +9,99 @@
 
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { AuthProvider } from "./provider.js";
-import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
+import {
+  type AuthInfo,
+  type HttpsUrl,
+  httpsUrl,
+  type ProtectedResourceMetadata,
+} from "./types.js";
 import { isOtelEnabled, recordAuthEvent } from "../observability/otel.js";
 
+// ============================================================================
+// JwtAuthProviderOptions — discriminated union (0.16.0)
+// ============================================================================
+
 /**
- * Configuration for JwtAuthProvider.
+ * Fields shared by both branches of {@link JwtAuthProviderOptions}.
  */
-export interface JwtAuthProviderOptions {
+interface JwtAuthProviderOptionsBase {
   /** JWT issuer (iss claim) */
   issuer: string;
   /** JWT audience (aud claim) */
   audience: string;
-  /** JWKS URI for signature validation. Defaults to {issuer}/.well-known/jwks.json */
+  /**
+   * JWKS URI for signature validation. Defaults to
+   * `{issuer}/.well-known/jwks.json` when omitted.
+   */
   jwksUri?: string;
-  /** Resource identifier for RFC 9728 */
-  resource: string;
-  /** Authorization servers that issue valid tokens */
-  authorizationServers: string[];
+  /**
+   * Authorization servers that issue valid tokens. Each entry is a branded
+   * {@link HttpsUrl} — raw strings are rejected at compile time. Construct
+   * via {@link httpsUrl}.
+   */
+  authorizationServers: HttpsUrl[];
   /** Scopes supported by this server */
   scopesSupported?: string[];
+}
+
+/**
+ * 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`.
+ */
+export interface JwtAuthProviderOptionsUrlResource
+  extends JwtAuthProviderOptionsBase {
+  /** RFC 9728 § 2 resource identifier, pre-validated as HTTP(S) URL. */
+  resource: HttpsUrl;
   /**
-   * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
-   * metadata document is served publicly. Used to populate the
-   * `resource_metadata` parameter of the WWW-Authenticate challenge
-   * (RFC 9728 § 5) and the `resource_metadata_url` field of
-   * `ProtectedResourceMetadata`.
-   *
-   * - When omitted AND `resource` is an HTTP(S) URL, the factory
-   *   auto-derives `${resource}/.well-known/oauth-protected-resource`.
-   * - When omitted AND `resource` is an opaque URI (e.g., an OIDC project
-   *   ID used as JWT audience — valid per RFC 9728 § 2), the factory
-   *   throws at construction. Set this option explicitly in that case
-   *   (fail-fast, no silent broken header).
-   *
-   * @example "https://my-mcp.example.com/.well-known/oauth-protected-resource"
+   * Metadata URL, optional — auto-derived from `resource` when omitted.
    */
-  resourceMetadataUrl?: string;
+  resourceMetadataUrl?: HttpsUrl;
 }
 
 /**
- * JWT Auth Provider with JWKS validation.
+ * 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.
+ */
+export interface JwtAuthProviderOptionsOpaqueResource
+  extends JwtAuthProviderOptionsBase {
+  /** RFC 9728 § 2 opaque resource identifier (NOT an URL). */
+  resource: string;
+  /**
+   * Metadata URL, REQUIRED — cannot be derived from opaque `resource`.
+   * Construct via {@link httpsUrl}.
+   */
+  resourceMetadataUrl: HttpsUrl;
+}
+
+/**
+ * Configuration for JwtAuthProvider.
  *
- * @example
- * ```typescript
- * const provider = new JwtAuthProvider({
- *   issuer: "https://accounts.google.com",
- *   audience: "https://my-mcp.example.com",
- *   resource: "https://my-mcp.example.com",
- *   authorizationServers: ["https://accounts.google.com"],
- * });
- * ```
+ * 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:
+ *
+ * - `resource: HttpsUrl` (via {@link httpsUrl}) → {@link
+ *   JwtAuthProviderOptionsUrlResource} branch, `resourceMetadataUrl`
+ *   optional (auto-derived from `resource`).
+ * - `resource: string` (raw) → {@link JwtAuthProviderOptionsOpaqueResource}
+ *   branch, `resourceMetadataUrl: HttpsUrl` REQUIRED.
+ *
+ * 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).
  */
+export type JwtAuthProviderOptions =
+  | JwtAuthProviderOptionsUrlResource
+  | JwtAuthProviderOptionsOpaqueResource;
+
+// ============================================================================
+// JwtAuthProvider
+// ============================================================================
+
 /**
  * Cached auth result with expiration
  */
@@ -68,10 +110,25 @@ interface CachedAuth {
   expiresAt: number; // ms timestamp
 }
 
+/**
+ * JWT Auth Provider with JWKS validation.
+ *
+ * @example
+ * ```typescript
+ * import { httpsUrl, JwtAuthProvider } from "@casys/mcp-server";
+ *
+ * const provider = new JwtAuthProvider({
+ *   issuer: "https://accounts.google.com",
+ *   audience: "https://my-mcp.example.com",
+ *   resource: httpsUrl("https://my-mcp.example.com"),
+ *   authorizationServers: [httpsUrl("https://accounts.google.com")],
+ * });
+ * ```
+ */
 export class JwtAuthProvider extends AuthProvider {
   private jwks: ReturnType<typeof createRemoteJWKSet>;
   private options: JwtAuthProviderOptions;
-  private readonly resourceMetadataUrl: string;
+  private readonly resourceMetadataUrl: HttpsUrl;
 
   // Token verification cache: hash(token) → AuthInfo with TTL
   // Prevents redundant JWKS fetches (network round-trip per tool call)
@@ -97,30 +154,44 @@ export class JwtAuthProvider extends AuthProvider {
       );
     }
 
-    // Resolve resource_metadata_url: explicit > auto-derive (if URL) > throw.
-    // Per RFC 9728 § 2, `resource` is an URI identifier and MAY be opaque
-    // (e.g., an OIDC project ID used as JWT audience). The metadata document
-    // URL is a separate concept — always an HTTP(S) URL. We used to derive
-    // it from `resource` by string concatenation, which produced a broken
-    // URL when `resource` was not itself an HTTP(S) URL. 0.15.0+ requires
-    // the caller to provide the URL explicitly whenever `resource` is opaque.
-    if (options.resourceMetadataUrl) {
+    // 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.
+    //
+    // 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:
+    //
+    //   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) {
       this.resourceMetadataUrl = options.resourceMetadataUrl;
     } else {
-      const isUrl = /^https?:\/\//.test(options.resource);
-      if (!isUrl) {
-        throw new Error(
-          `[JwtAuthProvider] resourceMetadataUrl is required when 'resource' ` +
-            `is not an HTTP(S) URL (got resource="${options.resource}"). ` +
-            `Per RFC 9728 § 2, 'resource' is an URI identifier that can be ` +
-            `opaque (e.g., an OIDC project ID used as JWT audience). The ` +
-            `metadata document URL is a separate concept. Set 'resourceMetadataUrl' ` +
-            `to the HTTPS URL where your /.well-known/oauth-protected-resource ` +
-            `endpoint is served publicly (e.g., "https://my-mcp.example.com/.well-known/oauth-protected-resource").`,
-        );
-      }
-      const base = options.resource.replace(/\/$/, "");
-      this.resourceMetadataUrl = `${base}/.well-known/oauth-protected-resource`;
+      const parsed = new URL(options.resource);
+      const pathPart = parsed.pathname === "/" ? "" : parsed.pathname;
+      this.resourceMetadataUrl = httpsUrl(
+        `${parsed.origin}/.well-known/oauth-protected-resource${pathPart}${parsed.search}`,
+      );
     }
 
     this.options = options;

package/src/auth/mod.ts

@@ -8,8 +8,13 @@
 export type {
   AuthInfo,
   AuthOptions,
+  HttpsUrl,
   ProtectedResourceMetadata,
 } from "./types.js";
+// HttpsUrl brand factories (0.16.0) — construct branded URL values for
+// `JwtAuthProviderOptions`, `ProtectedResourceMetadata`, and anywhere else
+// that requires a validated absolute HTTP(S) URL.
+export { httpsUrl, tryHttpsUrl } from "./types.js";
 
 // Provider base class
 export { AuthProvider } from "./provider.js";
@@ -36,7 +41,14 @@ export type {
 
 // JWT Provider
 export { JwtAuthProvider } from "./jwt-provider.js";
-export type { JwtAuthProviderOptions } from "./jwt-provider.js";
+// JwtAuthProviderOptions is a discriminated union in 0.16.0 — both branch
+// types are exported so advanced callers can type-annotate variables
+// explicitly.
+export type {
+  JwtAuthProviderOptions,
+  JwtAuthProviderOptionsOpaqueResource,
+  JwtAuthProviderOptionsUrlResource,
+} from "./jwt-provider.js";
 
 // OIDC Presets
 export {
@@ -45,7 +57,7 @@ export {
   createGoogleAuthProvider,
   createOIDCAuthProvider,
 } from "./presets.js";
-export type { PresetOptions } from "./presets.js";
+export type { OIDCPresetOptions, PresetOptions } from "./presets.js";
 
 // Config loader (YAML + env)
 export { createAuthProviderFromConfig, loadAuthConfig } from "./config.js";

package/src/auth/presets.ts

@@ -1,17 +1,21 @@
 /**
  * OIDC auth provider presets.
  *
- * Factory functions for common OIDC providers.
- * Each preset pre-configures the issuer, JWKS URI, and
- * authorization server for the provider.
+ * Factory functions for common OIDC providers. Each preset pre-configures
+ * the issuer, JWKS URI, and authorization server for the provider.
+ *
+ * Bridge layer (0.16.0): presets accept raw `string` fields for `resource`,
+ * `resourceMetadataUrl`, and `authorizationServers`, then wrap them through
+ * {@link httpsUrl} before passing to the branded {@link JwtAuthProviderOptions}
+ * constructor. This keeps the YAML/env config pipeline (`createAuthProviderFromConfig`)
+ * working with raw strings while the core `JwtAuthProvider` API enforces the
+ * `HttpsUrl` brand at the type level.
  *
  * @module lib/server/auth/presets
  */
 
-import {
-  JwtAuthProvider,
-  type JwtAuthProviderOptions,
-} from "./jwt-provider.js";
+import { JwtAuthProvider } from "./jwt-provider.js";
+import { type HttpsUrl, httpsUrl, tryHttpsUrl } from "./types.js";
 
 /**
  * Base options shared by all presets.
@@ -19,18 +23,52 @@ import {
 export interface PresetOptions {
   /** JWT audience (aud claim) */
   audience: string;
-  /** Resource identifier for RFC 9728 */
+  /**
+   * RFC 9728 § 2 resource identifier, as a raw string. Presets detect
+   * whether this is an HTTP(S) URL or an opaque URI and pick the correct
+   * {@link JwtAuthProviderOptions} branch internally. When opaque, you
+   * MUST also supply {@link resourceMetadataUrl}.
+   */
   resource: string;
   /** Scopes supported by this server */
   scopesSupported?: 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. See `JwtAuthProviderOptions.resourceMetadataUrl`.
+   * `resource` is an opaque URI; optional when `resource` is itself an
+   * HTTP(S) URL (in which case the preset auto-derives). Empty and
+   * whitespace-only values are treated as absent.
    */
   resourceMetadataUrl?: string;
 }
 
+/**
+ * Options for {@link createOIDCAuthProvider}. Unlike 0.15.x where this
+ * function accepted `JwtAuthProviderOptions` directly, 0.16.0 exposes a
+ * preset-style interface with raw string fields — the preset wraps them
+ * through {@link httpsUrl} internally.
+ *
+ * BREAKING: callers that previously passed a pre-built
+ * `JwtAuthProviderOptions` to `createOIDCAuthProvider` must now pass
+ * raw strings. Migration: just drop the `httpsUrl()` wrappers you'd
+ * otherwise need at the call site.
+ */
+export interface OIDCPresetOptions extends PresetOptions {
+  /** OIDC issuer (typically an HTTPS URL) */
+  issuer: string;
+  /**
+   * JWKS URI for signature validation. Defaults to
+   * `{issuer}/.well-known/jwks.json`.
+   */
+  jwksUri?: string;
+  /**
+   * Authorization servers, as raw strings. Defaults to `[issuer]` when
+   * omitted. Each entry must be a valid absolute HTTP(S) URL — the preset
+   * validates via {@link httpsUrl}.
+   */
+  authorizationServers?: string[];
+}
+
 /**
  * GitHub Actions OIDC provider.
  *
@@ -48,14 +86,14 @@ export interface PresetOptions {
 export function createGitHubAuthProvider(
   options: PresetOptions,
 ): JwtAuthProvider {
-  return new JwtAuthProvider({
+  return buildJwtProvider({
     issuer: "https://token.actions.githubusercontent.com",
     audience: options.audience,
-    resource: options.resource,
     authorizationServers: ["https://token.actions.githubusercontent.com"],
     scopesSupported: options.scopesSupported,
+    resource: options.resource,
     resourceMetadataUrl: options.resourceMetadataUrl,
-  });
+  }, "createGitHubAuthProvider");
 }
 
 /**
@@ -75,15 +113,15 @@ export function createGitHubAuthProvider(
 export function createGoogleAuthProvider(
   options: PresetOptions,
 ): JwtAuthProvider {
-  return new JwtAuthProvider({
+  return buildJwtProvider({
     issuer: "https://accounts.google.com",
     audience: options.audience,
-    resource: options.resource,
     authorizationServers: ["https://accounts.google.com"],
     jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
     scopesSupported: options.scopesSupported,
+    resource: options.resource,
     resourceMetadataUrl: options.resourceMetadataUrl,
-  });
+  }, "createGoogleAuthProvider");
 }
 
 /**
@@ -105,15 +143,15 @@ export function createAuth0AuthProvider(
   options: PresetOptions & { domain: string },
 ): JwtAuthProvider {
   const issuer = `https://${options.domain}/`;
-  return new JwtAuthProvider({
+  return buildJwtProvider({
     issuer,
     audience: options.audience,
-    resource: options.resource,
     authorizationServers: [issuer],
     jwksUri: `${issuer}.well-known/jwks.json`,
     scopesSupported: options.scopesSupported,
+    resource: options.resource,
     resourceMetadataUrl: options.resourceMetadataUrl,
-  });
+  }, "createAuth0AuthProvider");
 }
 
 /**
@@ -132,7 +170,109 @@ export function createAuth0AuthProvider(
  * ```
  */
 export function createOIDCAuthProvider(
-  options: JwtAuthProviderOptions,
+  options: OIDCPresetOptions,
+): JwtAuthProvider {
+  return buildJwtProvider({
+    issuer: options.issuer,
+    audience: options.audience,
+    jwksUri: options.jwksUri,
+    authorizationServers: options.authorizationServers ?? [options.issuer],
+    scopesSupported: options.scopesSupported,
+    resource: options.resource,
+    resourceMetadataUrl: options.resourceMetadataUrl,
+  }, "createOIDCAuthProvider");
+}
+
+// ============================================================================
+// Internal bridge: raw strings → branded JwtAuthProviderOptions
+// ============================================================================
+
+/**
+ * Internal options for the bridge helper.
+ */
+interface BuildJwtProviderOptions {
+  issuer: string;
+  audience: string;
+  jwksUri?: string;
+  authorizationServers: string[];
+  scopesSupported?: string[];
+  resource: string;
+  resourceMetadataUrl?: string;
+}
+
+/**
+ * Bridge raw-string preset options to the branded {@link JwtAuthProviderOptions}
+ * discriminated union used by the core `JwtAuthProvider` constructor.
+ *
+ * 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.
+ *
+ * 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`.
+ * - `resourceMetadataUrl`: empty or whitespace-only strings are treated as
+ *   absent (matches YAML-key-with-no-value semantics from 0.15.1).
+ */
+function buildJwtProvider(
+  opts: BuildJwtProviderOptions,
+  presetName: string,
 ): JwtAuthProvider {
-  return new JwtAuthProvider(options);
+  const wrappedAuthServers: HttpsUrl[] = opts.authorizationServers.map(
+    (raw, i) => {
+      try {
+        return httpsUrl(raw);
+      } catch (err) {
+        throw new Error(
+          `[${presetName}] authorizationServers[${i}] is not a valid ` +
+            `HTTP(S) URL: ${(err as Error).message}`,
+        );
+      }
+    },
+  );
+
+  const explicitMetadata: HttpsUrl | undefined = opts.resourceMetadataUrl &&
+      opts.resourceMetadataUrl.trim().length > 0
+    ? httpsUrl(opts.resourceMetadataUrl)
+    : undefined;
+
+  const base = {
+    issuer: opts.issuer,
+    audience: opts.audience,
+    jwksUri: opts.jwksUri,
+    authorizationServers: wrappedAuthServers,
+    scopesSupported: opts.scopesSupported,
+  };
+
+  const resourceUrl = tryHttpsUrl(opts.resource);
+  if (resourceUrl !== null) {
+    // URL resource branch — metadata URL optional (derivable)
+    return new JwtAuthProvider({
+      ...base,
+      resource: resourceUrl,
+      resourceMetadataUrl: explicitMetadata,
+    });
+  }
+
+  // Opaque resource branch — metadata URL required
+  if (!explicitMetadata) {
+    throw new Error(
+      `[${presetName}] 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 ` +
+        `document URL is a separate concept and must be provided explicitly. ` +
+        `Set 'resourceMetadataUrl' to the HTTPS URL where your ` +
+        `/.well-known/oauth-protected-resource endpoint is served publicly.`,
+    );
+  }
+  return new JwtAuthProvider({
+    ...base,
+    resource: opts.resource,
+    resourceMetadataUrl: explicitMetadata,
+  });
 }

package/src/auth/types.ts

@@ -7,6 +7,95 @@
  * @module lib/server/auth/types
  */
 
+// ============================================================================
+// HttpsUrl brand — 0.16.0
+// ============================================================================
+
+declare const httpsUrlBrand: unique symbol;
+
+/**
+ * A string that has been validated as a syntactically valid absolute HTTP(S)
+ * URL. Cannot be constructed by type assertion — callers MUST go through
+ * {@link httpsUrl} (which parses, normalizes, and throws on invalid input) so
+ * the invariant is enforced at both the type level and runtime.
+ *
+ * Added in 0.16.0 to lift `resource_metadata_url`, `authorization_servers`,
+ * and the URL-resource branch of {@link JwtAuthProviderOptions} from raw
+ * `string` into a type that structurally encodes the invariant. The motivating
+ * incident was 0.14.x silently producing `"://host/.well-known/..."` in
+ * `WWW-Authenticate` headers when callers mis-set `resource` — a class of bug
+ * that 0.15.x closed with runtime guards and 0.16.0 closes at the type level.
+ */
+export type HttpsUrl = string & { readonly [httpsUrlBrand]: never };
+
+/**
+ * Parse, validate, and normalize a string as an absolute HTTP(S) URL.
+ *
+ * Trims leading/trailing whitespace before parsing so YAML keys with trailing
+ * spaces don't produce unparseable URLs. Delegates parsing to `new URL()`,
+ * which lowercases the scheme — so `HTTPS://foo.com` is accepted and returned
+ * as `https://foo.com/`.
+ *
+ * @throws if the string is empty/whitespace-only, unparseable as a URL, or
+ *         uses a non-HTTP(S) scheme (RFC 9728 § 3 requires HTTPS for metadata
+ *         documents; http is permitted here for local dev only).
+ *
+ * @example
+ * ```typescript
+ * const url = httpsUrl("https://my-mcp.example.com");
+ * // url is of type HttpsUrl and can be passed wherever HttpsUrl is required.
+ * ```
+ */
+export function httpsUrl(raw: string): HttpsUrl {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new Error(
+      `[httpsUrl] empty or whitespace-only string is not a valid URL. ` +
+        `Expected an absolute HTTP(S) URL like ` +
+        `"https://my-mcp.example.com/.well-known/oauth-protected-resource".`,
+    );
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(
+      `[httpsUrl] not a parseable URL: ${JSON.stringify(raw)}. ` +
+        `Expected an absolute HTTP(S) URL like ` +
+        `"https://my-mcp.example.com/.well-known/oauth-protected-resource".`,
+    );
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(
+      `[httpsUrl] must use http:// or https:// scheme, got ${
+        JSON.stringify(parsed.protocol)
+      } in ${JSON.stringify(raw)}. Per RFC 9728 § 3, the protected resource ` +
+        `metadata document must be served over HTTP(S).`,
+    );
+  }
+  return parsed.toString() as HttpsUrl;
+}
+
+/**
+ * Non-throwing variant of {@link httpsUrl}. Returns the normalized `HttpsUrl`
+ * on success, `null` on any validation failure. Use this when you need to
+ * branch on validity without catching exceptions — typically to detect whether
+ * an RFC 9728 § 2 `resource` identifier is an HTTP(S) URL (the URL-resource
+ * branch) or an opaque URI (the opaque-resource branch that requires an
+ * explicit metadata URL).
+ */
+export function tryHttpsUrl(raw: string): HttpsUrl | null {
+  try {
+    return httpsUrl(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Runtime auth types
+// ============================================================================
+
 /**
  * Information extracted from a validated token.
  * Frozen (Object.freeze) before being passed to tool handlers.
@@ -69,7 +158,9 @@ export interface ProtectedResourceMetadata {
   /**
    * RFC 9728 § 2 resource identifier. URI that identifies the protected
    * resource — used as the JWT `aud` claim. Can be an HTTP(S) URL OR an
-   * opaque URI (e.g., an OIDC project ID). Do NOT assume it's an URL.
+   * opaque URI (e.g., an OIDC project ID). Stays `string` because RFC 9728
+   * explicitly allows opaque URIs; callers must NOT assume it parses as
+   * an URL.
    */
   resource: string;
 
@@ -79,17 +170,23 @@ export interface ProtectedResourceMetadata {
    * WWW-Authenticate challenge. Always an HTTP(S) URL, regardless of
    * whether `resource` itself is an URL or an opaque URI.
    *
-   * REQUIRED as of 0.15.0 — previously derived at the middleware level
-   * from `resource`, which produced a broken URL when `resource` was not
-   * itself an HTTP(S) URL. Callers using the `createOIDCAuthProvider`
-   * factory or `JwtAuthProvider` can omit the explicit value when their
-   * `resource` IS an HTTP(S) URL (the factory auto-derives). Custom
-   * `AuthProvider` subclasses must always set it explicitly.
+   * 0.16.0: typed as {@link HttpsUrl} (branded). The invariant is now
+   * structurally enforced — producers must construct the value via
+   * {@link httpsUrl}, which validates at runtime AND returns the brand.
+   * Prior to 0.16.0 this was a raw `string` guarded only by a runtime
+   * validator in the `JwtAuthProvider` constructor (0.15.1).
    */
-  resource_metadata_url: string;
+  resource_metadata_url: HttpsUrl;
 
-  /** Authorization servers that can issue valid tokens */
-  authorization_servers: string[];
+  /**
+   * Authorization servers that can issue valid tokens.
+   *
+   * 0.16.0: each element is branded as {@link HttpsUrl} so downstream
+   * consumers (e.g., MCP clients building discovery URLs) can rely on
+   * them being parseable absolute URLs without re-validation. Construct
+   * via {@link httpsUrl}.
+   */
+  authorization_servers: HttpsUrl[];
 
   /** Scopes this resource supports */
   scopes_supported?: string[];