@casys/mcp-server 0.14.0 → 0.15.1

package/README.md

@@ -41,13 +41,35 @@ stack.
 ## Install
 
 ```bash
-# npm
-npm install @casys/mcp-server
-
-# Deno
+# Deno (primary target — JSR)
 deno add jsr:@casys/mcp-server
+
+# Node (secondary — npm, via build-node compilation)
+npm install @casys/mcp-server
 ```
 
+## Runtime targets
+
+`@casys/mcp-server` is **Deno-first**. The canonical deployment path is Deno 2.x
+running on [Deno Deploy](https://deno.com/deploy) or self-hosted Deno, with a
+Node 20+ distribution as a secondary target via `scripts/build-node.sh` (which
+swaps the HTTP runtime adapter and remaps `@std/*` imports to their npm
+equivalents).
+
+| Runtime                                       |      Status      |
+| --------------------------------------------- | :--------------: |
+| **Deno 2.x** (Deno Deploy, self-hosted)       |    ✅ Primary    |
+| **Node.js 20+** (Express, Hono-on-Node, bare) |   ✅ Secondary   |
+| **Cloudflare Workers / workerd**              | ❌ Not supported |
+| **Browser / WebContainer**                    | ❌ Not supported |
+
+If you need to target Cloudflare Workers or the browser, use
+[`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+directly with its workerd / browser shims — that package focuses on the protocol
+and runtime portability, while `@casys/mcp-server` focuses on the production
+stack (auth, middleware, observability, multi-tenant, MCP Apps helpers) for Deno
+deployments.
+
 ---
 
 ## Quick Start

package/package.json

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

package/src/auth/config.ts

@@ -42,6 +42,17 @@ export interface AuthConfig {
   jwksUri?: string;
   /** Supported scopes */
   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 (e.g., an OIDC project ID used
+   * as JWT audience per RFC 9728 § 2) — otherwise `JwtAuthProvider` will
+   * throw at construction. When `resource` is itself an HTTP(S) URL, this
+   * field is optional and auto-derived by the factory. Mirrors
+   * `JwtAuthProviderOptions.resourceMetadataUrl`.
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -56,6 +67,7 @@ interface ConfigFile {
     issuer?: string;
     jwksUri?: string;
     scopesSupported?: string[];
+    resourceMetadataUrl?: string;
   };
 }
 
@@ -75,6 +87,7 @@ interface ConfigFile {
  * - MCP_AUTH_ISSUER → auth.issuer
  * - MCP_AUTH_JWKS_URI → auth.jwksUri
  * - MCP_AUTH_SCOPES → auth.scopesSupported (space-separated)
+ * - MCP_AUTH_RESOURCE_METADATA_URL → auth.resourceMetadataUrl
  *
  * @param configPath - Path to YAML config file. Defaults to "mcp-server.yaml" in cwd.
  * @returns AuthConfig or null if no auth configured
@@ -94,6 +107,7 @@ export async function loadAuthConfig(
   const envIssuer = env("MCP_AUTH_ISSUER");
   const envJwksUri = env("MCP_AUTH_JWKS_URI");
   const envScopes = env("MCP_AUTH_SCOPES");
+  const envResourceMetadataUrl = env("MCP_AUTH_RESOURCE_METADATA_URL");
 
   // 3. Merge: env overrides YAML
   const provider = envProvider ?? yamlAuth?.provider;
@@ -135,6 +149,8 @@ export async function loadAuthConfig(
     scopesSupported: envScopes
       ? envScopes.split(" ").filter(Boolean)
       : yamlAuth?.scopesSupported,
+    resourceMetadataUrl: envResourceMetadataUrl ??
+      yamlAuth?.resourceMetadataUrl,
   };
 
   // Provider-specific validation (fail-fast)
@@ -165,6 +181,7 @@ export function createAuthProviderFromConfig(config: AuthConfig): AuthProvider {
     audience: config.audience,
     resource: config.resource,
     scopesSupported: config.scopesSupported,
+    resourceMetadataUrl: config.resourceMetadataUrl,
   };
 
   switch (config.provider) {
@@ -225,5 +242,8 @@ async function loadYamlAuth(
         typeof s === "string"
       )
       : undefined,
+    resourceMetadataUrl: typeof auth.resourceMetadataUrl === "string"
+      ? auth.resourceMetadataUrl
+      : undefined,
   };
 }

package/src/auth/jwt-provider.ts

@@ -28,6 +28,23 @@ export interface JwtAuthProviderOptions {
   authorizationServers: string[];
   /** Scopes supported by this server */
   scopesSupported?: string[];
+  /**
+   * 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"
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -51,9 +68,54 @@ interface CachedAuth {
   expiresAt: number; // ms timestamp
 }
 
+/**
+ * Validate that a string is a parseable absolute HTTP(S) URL. Used by
+ * `JwtAuthProvider`'s constructor to enforce the RFC 9728 § 3 invariant
+ * at construction time: the `resource_metadata_url` placed in the
+ * `WWW-Authenticate` challenge MUST be a URL clients can fetch. Before
+ * 0.15.1 the constructor stored whatever string the caller passed and
+ * trusted the type system, which silently produced broken headers when
+ * the value was empty / a relative path / unparseable / contained
+ * trailing whitespace — the exact class of bug that 0.15.0 was meant to
+ * eliminate (see postmortem phase8-deployment.md § 7 and F.1).
+ *
+ * Throws with a clear error message pointing at the offending value
+ * (`JSON.stringify`-ed so quotes/newlines/specials don't break log
+ * parsing) and suggesting a concrete fix. The `source` parameter names
+ * which input produced the bad value so operators reading the error know
+ * which config key to correct.
+ *
+ * Returns the normalized URL string (via `URL.toString()`), which
+ * lowercases the scheme and applies minor canonicalization — so a
+ * caller passing `HTTPS://foo.com/` receives `https://foo.com/` back.
+ */
+function validateAbsoluteHttpUrl(raw: string, source: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(
+      `[JwtAuthProvider] ${source} is 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(
+      `[JwtAuthProvider] ${source} 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();
+}
+
 export class JwtAuthProvider extends AuthProvider {
   private jwks: ReturnType<typeof createRemoteJWKSet>;
   private options: JwtAuthProviderOptions;
+  private readonly resourceMetadataUrl: string;
 
   // Token verification cache: hash(token) → AuthInfo with TTL
   // Prevents redundant JWKS fetches (network round-trip per tool call)
@@ -79,7 +141,63 @@ export class JwtAuthProvider extends AuthProvider {
       );
     }
 
-    this.options = options;
+    // 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.
+    //
+    // 0.15.1 hardening: both branches now run through `validateAbsoluteHttpUrl`
+    // which `new URL()`-parses the result and rejects non-HTTP(S) schemes.
+    // Empty / whitespace-only `resourceMetadataUrl` is treated as absent
+    // (so a YAML key with no value falls through to the derivation branch
+    // instead of silently producing `"://host"`). The scheme regex is now
+    // case-insensitive — `HTTPS://foo.com` is a valid URL per RFC 3986
+    // and we accept it (normalization happens in validateAbsoluteHttpUrl).
+    // `options.resource` is `.trim()`-ed before derivation so trailing
+    // whitespace doesn't produce an unparseable URL.
+    const explicitUrl = options.resourceMetadataUrl?.trim();
+    if (explicitUrl) {
+      this.resourceMetadataUrl = validateAbsoluteHttpUrl(
+        explicitUrl,
+        "options.resourceMetadataUrl",
+      );
+    } else {
+      const isUrl = /^https?:\/\//i.test(options.resource);
+      if (!isUrl) {
+        throw new Error(
+          `[JwtAuthProvider] resourceMetadataUrl is required when 'resource' ` +
+            `is not an HTTP(S) URL (got resource=${
+              JSON.stringify(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.trim().replace(/\/$/, "");
+      const derived = `${base}/.well-known/oauth-protected-resource`;
+      this.resourceMetadataUrl = validateAbsoluteHttpUrl(
+        derived,
+        "derived from options.resource",
+      );
+    }
+
+    // Normalize `resource` at store time so `getResourceMetadata()` returns
+    // the trimmed value in the RFC 9728 Protected Resource Metadata JSON
+    // payload. Prior to 0.15.1 the derivation branch trimmed `resource` for
+    // URL construction BUT `this.options` kept the raw value, so clients
+    // fetching `/.well-known/oauth-protected-resource` would see
+    // `"resource": "https://api.example.com   "` with trailing whitespace
+    // in the JSON body. The WWW-Authenticate header was always clean
+    // (middleware only reads `resource_metadata_url` which went through
+    // `validateAbsoluteHttpUrl` + `new URL().toString()` normalization),
+    // so runtime was never broken — just the PRM doc body was polluted.
+    this.options = { ...options, resource: options.resource.trim() };
     const jwksUri = options.jwksUri ??
       `${options.issuer}/.well-known/jwks.json`;
     this.jwks = createRemoteJWKSet(new URL(jwksUri));
@@ -153,6 +271,7 @@ export class JwtAuthProvider extends AuthProvider {
   getResourceMetadata(): ProtectedResourceMetadata {
     return {
       resource: this.options.resource,
+      resource_metadata_url: this.resourceMetadataUrl,
       authorization_servers: this.options.authorizationServers,
       scopes_supported: this.options.scopesSupported,
       bearer_methods_supported: ["header"],

package/src/auth/middleware.ts

@@ -123,10 +123,10 @@ export function createAuthMiddleware(provider: AuthProvider): Middleware {
       return next();
     }
 
-    const metadata = provider.getResourceMetadata();
-    const resource = metadata.resource;
-    const base = resource.endsWith("/") ? resource.slice(0, -1) : resource;
-    const metadataUrl = `${base}/.well-known/oauth-protected-resource`;
+    // 0.15.0+: provider's getResourceMetadata() always returns a valid
+    // absolute URL in resource_metadata_url (type system guarantees it).
+    // No derivation needed at the middleware level anymore.
+    const metadataUrl = provider.getResourceMetadata().resource_metadata_url;
 
     const token = extractBearerToken(ctx.request);
     if (!token) {

package/src/auth/presets.ts

@@ -23,6 +23,12 @@ export interface PresetOptions {
   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`.
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -48,6 +54,7 @@ export function createGitHubAuthProvider(
     resource: options.resource,
     authorizationServers: ["https://token.actions.githubusercontent.com"],
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 
@@ -75,6 +82,7 @@ export function createGoogleAuthProvider(
     authorizationServers: ["https://accounts.google.com"],
     jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 
@@ -104,6 +112,7 @@ export function createAuth0AuthProvider(
     authorizationServers: [issuer],
     jwksUri: `${issuer}.well-known/jwks.json`,
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 

package/src/auth/provider.ts

@@ -24,6 +24,8 @@ import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
  *   getResourceMetadata(): ProtectedResourceMetadata {
  *     return {
  *       resource: "https://my-mcp.example.com",
+ *       resource_metadata_url:
+ *         "https://my-mcp.example.com/.well-known/oauth-protected-resource",
  *       authorization_servers: ["https://auth.example.com"],
  *       bearer_methods_supported: ["header"],
  *     };

package/src/auth/types.ts

@@ -66,9 +66,28 @@ import type { AuthProvider } from "./provider.js";
  * @see https://datatracker.ietf.org/doc/html/rfc9728
  */
 export interface ProtectedResourceMetadata {
-  /** Resource identifier (URL of this MCP server) */
+  /**
+   * 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.
+   */
   resource: string;
 
+  /**
+   * Absolute HTTP(S) URL where this metadata document is served publicly.
+   * Per RFC 9728 § 3, this is the URL a client discovers via the
+   * 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.
+   */
+  resource_metadata_url: string;
+
   /** Authorization servers that can issue valid tokens */
   authorization_servers: string[];
 

package/src/mcp-app.ts

@@ -1159,15 +1159,16 @@ export class McpApp {
       return c.json(this.authProvider.getResourceMetadata());
     });
 
-    // Helper: build resource metadata URL safely (avoid double slash)
-    const buildMetadataUrl = (resource: string): string => {
-      const base = resource.endsWith("/") ? resource.slice(0, -1) : resource;
-      return `${base}/.well-known/oauth-protected-resource`;
-    };
-
     // Auth verification helper for HTTP endpoints.
     // Returns an error Response if auth is required but token is missing/invalid.
     // Returns null if auth passes or is not configured.
+    //
+    // 0.15.0+: provider's getResourceMetadata() always returns a valid
+    // absolute URL in resource_metadata_url (type-enforced). We used to
+    // derive this URL from `metadata.resource` by string concatenation
+    // (see `buildMetadataUrl` helper, removed 0.15.0), which produced a
+    // broken URL when `resource` was an opaque URI per RFC 9728 § 2
+    // (e.g., an OIDC project ID used as JWT audience).
     const verifyHttpAuth = async (
       request: Request,
     ): Promise<Response | null> => {
@@ -1177,7 +1178,7 @@ export class McpApp {
       if (!token) {
         const metadata = this.authProvider.getResourceMetadata();
         return createUnauthorizedResponse(
-          buildMetadataUrl(metadata.resource),
+          metadata.resource_metadata_url,
           "missing_token",
           "Authorization header with Bearer token required",
         );
@@ -1187,7 +1188,7 @@ export class McpApp {
       if (!authInfo) {
         const metadata = this.authProvider.getResourceMetadata();
         return createUnauthorizedResponse(
-          buildMetadataUrl(metadata.resource),
+          metadata.resource_metadata_url,
           "invalid_token",
           "Invalid or expired token",
         );
@@ -1779,8 +1780,17 @@ export class McpApp {
   /**
    * Build the HTTP middleware stack and return its fetch handler without
    * binding a port. Use this when you want to mount the MCP HTTP layer
-   * inside another HTTP framework (Fresh, Hono, Express, Cloudflare Workers,
-   * etc.) instead of giving up port ownership to {@link startHttp}.
+   * inside another HTTP framework on Deno (Fresh, Hono, `Deno.serve`) or
+   * Node (Express, Hono-on-Node) instead of giving up port ownership to
+   * {@link startHttp}.
+   *
+   * **Runtime targets:** `@casys/mcp-server` is Deno-first — the canonical
+   * deployment path is Deno 2.x on Deno Deploy or self-hosted Deno, with
+   * a Node 20+ distribution via `scripts/build-node.sh` as a secondary
+   * target. Cloudflare Workers, workerd, and browser runtimes are not
+   * supported — if you target those, use
+   * [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+   * directly instead.
    *
    * The returned handler accepts a Web Standard {@link Request} and returns
    * a Web Standard {@link Response}. It exposes the same routes as