skybridge 0.0.0-dev.ecfdeac → 0.0.0-dev.ed29eee

package/dist/server/auth/providers/descope.d.ts

@@ -1,13 +1,44 @@
+import type { ExtraClaims } from "../../auth.js";
 import type { OAuthConfig } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
+/**
+ * Claims a Descope session JWT carries. Roles and permissions are nested per
+ * tenant when the project uses tenants, and flat otherwise. `email` arrives only
+ * through a Custom Claims flow action or a JWT template.
+ *
+ * @see https://docs.descope.com/authorization/session-management
+ * @see https://docs.descope.com/management/token/jwt-templates
+ */
+export type DescopeClaims = {
+    /** Authentication methods used, e.g. `["otp"]`. */
+    amr?: string[];
+    /** Descope Resource Name: where the token is stored. */
+    drn?: string;
+    /** The user's active tenant. */
+    dct?: string;
+    /** Associated tenants, keyed by tenant id. */
+    tenants?: Record<string, {
+        roles?: string[];
+        permissions?: string[];
+    }>;
+    /** Roles, when the project has no tenants. */
+    roles?: string[];
+    /** Permissions, when the project has no tenants. */
+    permissions?: string[];
+    /** Only via a Custom Claims action or JWT template; not a default claim. */
+    email?: string;
+};
 /**
  * OAuth provider for a Descope MCP Server. `url` is the MCP Server's **Discovery
  * URL** (a.k.a. Issuer) from the console's Connection Information, e.g.
  * `https://api.descope.com/v1/apps/agentic/<projectId>/<mcpServerId>` (or your
- * custom domain). Requires DCR enabled on the MCP Server. The token `audience`
- * defaults to the **Project ID** derived from the URL — Descope binds `aud` to
- * [DCR client id, project id], not the server URL; pass `audience` to override.
+ * custom domain). Requires DCR enabled on the MCP Server. For Descope with DCR
+ * disabled and Alpic's DCR proxy, use {@link customProvider} with `serverUrl`
+ * instead (see `examples/auth-descope-alpic`). The token `audience` defaults to
+ * the **Project ID** derived from the URL — Descope binds `aud` to [DCR client
+ * id, project id], not the server URL; pass `audience` to override.
  */
-export declare function descopeProvider(opts: {
+export declare function descopeProvider<TCustom extends ExtraClaims = Record<never, never>>(opts: {
     url: string;
-} & Omit<CustomProviderOptions, "issuer">): Promise<OAuthConfig>;
+} & Omit<CustomProviderOptions, "issuer">): Promise<OAuthConfig<DescopeClaims & TCustom & RegisteredClaims>>;

package/dist/server/auth/providers/descope.js

@@ -1,4 +1,12 @@
 import { customProvider } from "./custom.js";
+/**
+ * Turns the console's Discovery URL into the authorization server's base URL:
+ * drops a `/.well-known/openid-configuration` (or `oauth-authorization-server`)
+ * suffix, since discovery appends that path itself, and any trailing slash.
+ */
+function toAuthorizationServerUrl(discoveryUrl) {
+    return discoveryUrl.replace(/\/\.well-known\/[^?#]*$/, "").replace(/\/$/, "");
+}
 /**
  * Derives the Descope Project ID from an MCP Server URL
  * (`…/agentic/<projectId>/<mcpServerId>`). Descope binds the token `aud` to the
@@ -15,16 +23,21 @@ function projectIdFromUrl(url) {
  * OAuth provider for a Descope MCP Server. `url` is the MCP Server's **Discovery
  * URL** (a.k.a. Issuer) from the console's Connection Information, e.g.
  * `https://api.descope.com/v1/apps/agentic/<projectId>/<mcpServerId>` (or your
- * custom domain). Requires DCR enabled on the MCP Server. The token `audience`
- * defaults to the **Project ID** derived from the URL — Descope binds `aud` to
- * [DCR client id, project id], not the server URL; pass `audience` to override.
+ * custom domain). Requires DCR enabled on the MCP Server. For Descope with DCR
+ * disabled and Alpic's DCR proxy, use {@link customProvider} with `serverUrl`
+ * instead (see `examples/auth-descope-alpic`). The token `audience` defaults to
+ * the **Project ID** derived from the URL — Descope binds `aud` to [DCR client
+ * id, project id], not the server URL; pass `audience` to override.
  */
 export function descopeProvider(opts) {
     const { url, audience, ...rest } = opts;
-    const issuer = url.replace(/\/\.well-known\/[^?#]*$/, "").replace(/\/$/, "");
+    const asUrl = toAuthorizationServerUrl(url);
+    const projectId = projectIdFromUrl(asUrl);
+    const issuer = `${asUrl.slice(0, asUrl.indexOf("/agentic/"))}/${projectId}`;
     return customProvider({
         issuer,
-        audience: audience ?? projectIdFromUrl(issuer),
+        audience: audience ?? projectId,
+        authorizationServer: asUrl,
         ...rest,
     });
 }

package/dist/server/auth/providers/descope.js.map

@@ -1 +1 @@
-{"version":3,"file":"descope.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/descope.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzE;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,iDAAiD,GAAG,mCAAmC,CACxF,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA6D;IAE7D,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7E,OAAO,cAAc,CAAC;QACpB,MAAM;QACN,QAAQ,EAAE,QAAQ,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAC9C,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { OAuthConfig } from \"../index.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\n\n/**\n * Derives the Descope Project ID from an MCP Server URL\n * (`…/agentic/<projectId>/<mcpServerId>`). Descope binds the token `aud` to the\n * project id, so it doubles as the audience.\n */\nfunction projectIdFromUrl(url: string): string {\n  const projectId = url.match(/\\/agentic\\/([^/]+)\\/[^/]+/)?.[1];\n  if (!projectId) {\n    throw new Error(\n      `Could not derive the Descope project id from \"${url}\"; pass an explicit \\`audience\\`.`,\n    );\n  }\n  return projectId;\n}\n\n/**\n * OAuth provider for a Descope MCP Server. `url` is the MCP Server's **Discovery\n * URL** (a.k.a. Issuer) from the console's Connection Information, e.g.\n * `https://api.descope.com/v1/apps/agentic/<projectId>/<mcpServerId>` (or your\n * custom domain). Requires DCR enabled on the MCP Server. The token `audience`\n * defaults to the **Project ID** derived from the URL — Descope binds `aud` to\n * [DCR client id, project id], not the server URL; pass `audience` to override.\n */\nexport function descopeProvider(\n  opts: { url: string } & Omit<CustomProviderOptions, \"issuer\">,\n): Promise<OAuthConfig> {\n  const { url, audience, ...rest } = opts;\n  const issuer = url.replace(/\\/\\.well-known\\/[^?#]*$/, \"\").replace(/\\/$/, \"\");\n  return customProvider({\n    issuer,\n    audience: audience ?? projectIdFromUrl(issuer),\n    ...rest,\n  });\n}\n"]}
+{"version":3,"file":"descope.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/descope.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AA2BzE;;;;GAIG;AACH,SAAS,wBAAwB,CAAC,YAAoB;IACpD,OAAO,YAAY,CAAC,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,iDAAiD,GAAG,mCAAmC,CACxF,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAG7B,IAA6D;IAE7D,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,KAAK,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC;IAC5E,OAAO,cAAc,CAA0B;QAC7C,MAAM;QACN,QAAQ,EAAE,QAAQ,IAAI,SAAS;QAC/B,mBAAmB,EAAE,KAAK;QAC1B,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthConfig } from \"../index.js\";\nimport type { RegisteredClaims } from \"../verify.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\n\n/**\n * Claims a Descope session JWT carries. Roles and permissions are nested per\n * tenant when the project uses tenants, and flat otherwise. `email` arrives only\n * through a Custom Claims flow action or a JWT template.\n *\n * @see https://docs.descope.com/authorization/session-management\n * @see https://docs.descope.com/management/token/jwt-templates\n */\nexport type DescopeClaims = {\n  /** Authentication methods used, e.g. `[\"otp\"]`. */\n  amr?: string[];\n  /** Descope Resource Name: where the token is stored. */\n  drn?: string;\n  /** The user's active tenant. */\n  dct?: string;\n  /** Associated tenants, keyed by tenant id. */\n  tenants?: Record<string, { roles?: string[]; permissions?: string[] }>;\n  /** Roles, when the project has no tenants. */\n  roles?: string[];\n  /** Permissions, when the project has no tenants. */\n  permissions?: string[];\n  /** Only via a Custom Claims action or JWT template; not a default claim. */\n  email?: string;\n};\n\n/**\n * Turns the console's Discovery URL into the authorization server's base URL:\n * drops a `/.well-known/openid-configuration` (or `oauth-authorization-server`)\n * suffix, since discovery appends that path itself, and any trailing slash.\n */\nfunction toAuthorizationServerUrl(discoveryUrl: string): string {\n  return discoveryUrl.replace(/\\/\\.well-known\\/[^?#]*$/, \"\").replace(/\\/$/, \"\");\n}\n\n/**\n * Derives the Descope Project ID from an MCP Server URL\n * (`…/agentic/<projectId>/<mcpServerId>`). Descope binds the token `aud` to the\n * project id, so it doubles as the audience.\n */\nfunction projectIdFromUrl(url: string): string {\n  const projectId = url.match(/\\/agentic\\/([^/]+)\\/[^/]+/)?.[1];\n  if (!projectId) {\n    throw new Error(\n      `Could not derive the Descope project id from \"${url}\"; pass an explicit \\`audience\\`.`,\n    );\n  }\n  return projectId;\n}\n\n/**\n * OAuth provider for a Descope MCP Server. `url` is the MCP Server's **Discovery\n * URL** (a.k.a. Issuer) from the console's Connection Information, e.g.\n * `https://api.descope.com/v1/apps/agentic/<projectId>/<mcpServerId>` (or your\n * custom domain). Requires DCR enabled on the MCP Server. For Descope with DCR\n * disabled and Alpic's DCR proxy, use {@link customProvider} with `serverUrl`\n * instead (see `examples/auth-descope-alpic`). The token `audience` defaults to\n * the **Project ID** derived from the URL — Descope binds `aud` to [DCR client\n * id, project id], not the server URL; pass `audience` to override.\n */\nexport function descopeProvider<\n  TCustom extends ExtraClaims = Record<never, never>,\n>(\n  opts: { url: string } & Omit<CustomProviderOptions, \"issuer\">,\n): Promise<OAuthConfig<DescopeClaims & TCustom & RegisteredClaims>> {\n  const { url, audience, ...rest } = opts;\n  const asUrl = toAuthorizationServerUrl(url);\n  const projectId = projectIdFromUrl(asUrl);\n  const issuer = `${asUrl.slice(0, asUrl.indexOf(\"/agentic/\"))}/${projectId}`;\n  return customProvider<DescopeClaims & TCustom>({\n    issuer,\n    audience: audience ?? projectId,\n    authorizationServer: asUrl,\n    ...rest,\n  });\n}\n"]}

package/dist/server/auth/providers/descope.test.js

@@ -1,37 +1,62 @@
 // @vitest-environment node
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { descopeProvider } from "./descope.js";
+import { lastJwksConfig as jwks } from "./verify-spy.js";
+vi.mock("../verify.js", () => import("./verify-spy.js"));
 afterEach(() => vi.restoreAllMocks());
-function discoveryDoc(issuer) {
+function discoveryDoc(issuer, scopes) {
     return {
         issuer,
         authorization_endpoint: `${issuer}/authorize`,
         token_endpoint: `${issuer}/token`,
         registration_endpoint: `${issuer}/register`,
         response_types_supported: ["code"],
-        scopes_supported: ["openid"],
+        scopes_supported: scopes,
         jwks_uri: `${issuer}/.well-known/jwks.json`,
     };
 }
-function mockDiscovery(issuer) {
-    return vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(JSON.stringify(discoveryDoc(issuer)), {
-        headers: { "content-type": "application/json" },
-    }));
+const PROJECT = "https://api.descope.com/v1/apps/P123";
+const AGENTIC = "https://api.descope.com/v1/apps/agentic/P123/MS456";
+function mockDiscovery(docs) {
+    return vi
+        .spyOn(globalThis, "fetch")
+        .mockImplementation(async (input) => {
+        const url = String(input);
+        const entry = Object.entries(docs).find(([issuer]) => url === `${issuer}/.well-known/openid-configuration`);
+        if (entry === undefined) {
+            return new Response(null, { status: 404 });
+        }
+        return new Response(JSON.stringify(discoveryDoc(...entry)), {
+            headers: { "content-type": "application/json" },
+        });
+    });
 }
 describe("descopeProvider", () => {
-    it("derives issuer and audience (project id) from the MCP Server URL", async () => {
-        const issuer = "https://api.descope.com/v1/apps/agentic/P123/MS456";
-        const fetchSpy = mockDiscovery(issuer);
-        const config = await descopeProvider({ url: issuer });
-        expect(fetchSpy).toHaveBeenCalledWith(`${issuer}/.well-known/openid-configuration`, expect.anything());
-        expect(config.verify.issuer).toBe(issuer);
-        expect(config.verify.audience).toBe("P123");
+    it("verifies against the agentic issuer it advertises", async () => {
+        const fetchSpy = mockDiscovery({
+            [PROJECT]: ["openid", "profile", "email", "phone"],
+            [AGENTIC]: ["checkout"],
+        });
+        const config = await descopeProvider({ url: AGENTIC });
+        expect(fetchSpy).toHaveBeenCalledWith(`${PROJECT}/.well-known/openid-configuration`, expect.anything());
+        expect(jwks().issuer).toBe(AGENTIC);
+        expect(jwks().audience).toBe("P123");
+        expect(config.oauthMetadata.issuer).toBe(AGENTIC);
+        expect(config.oauthMetadata.registration_endpoint).toBe(`${AGENTIC}/register`);
+        expect(config.scopesSupported).toEqual(["checkout"]);
+    });
+    it("accepts a URL carrying the well-known suffix", async () => {
+        mockDiscovery({ [PROJECT]: ["openid"], [AGENTIC]: ["checkout"] });
+        const config = await descopeProvider({
+            url: `${AGENTIC}/.well-known/openid-configuration`,
+        });
+        expect(config.oauthMetadata.issuer).toBe(AGENTIC);
+        expect(config.scopesSupported).toEqual(["checkout"]);
     });
     it("lets an explicit audience override the derived project id", async () => {
-        const issuer = "https://api.descope.com/v1/apps/agentic/P123/MS456";
-        mockDiscovery(issuer);
-        const config = await descopeProvider({ url: issuer, audience: "custom" });
-        expect(config.verify.audience).toBe("custom");
+        mockDiscovery({ [PROJECT]: ["openid"], [AGENTIC]: ["checkout"] });
+        await descopeProvider({ url: AGENTIC, audience: "custom" });
+        expect(jwks().audience).toBe("custom");
     });
 });
 //# sourceMappingURL=descope.test.js.map

package/dist/server/auth/providers/descope.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"descope.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/descope.test.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO;QACL,MAAM;QACN,sBAAsB,EAAE,GAAG,MAAM,YAAY;QAC7C,cAAc,EAAE,GAAG,MAAM,QAAQ;QACjC,qBAAqB,EAAE,GAAG,MAAM,WAAW;QAC3C,wBAAwB,EAAE,CAAC,MAAM,CAAC;QAClC,gBAAgB,EAAE,CAAC,QAAQ,CAAC;QAC5B,QAAQ,EAAE,GAAG,MAAM,wBAAwB;KAC5C,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CACpD,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE;QACjD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;KAChD,CAAC,CACH,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;QAChF,MAAM,MAAM,GAAG,oDAAoD,CAAC;QACpE,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAEvC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAEtD,MAAM,CAAC,QAAQ,CAAC,CAAC,oBAAoB,CACnC,GAAG,MAAM,mCAAmC,EAC5C,MAAM,CAAC,QAAQ,EAAE,CAClB,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,MAAM,GAAG,oDAAoD,CAAC;QACpE,aAAa,CAAC,MAAM,CAAC,CAAC;QAEtB,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE1E,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["// @vitest-environment node\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { descopeProvider } from \"./descope.js\";\n\nafterEach(() => vi.restoreAllMocks());\n\nfunction discoveryDoc(issuer: string) {\n  return {\n    issuer,\n    authorization_endpoint: `${issuer}/authorize`,\n    token_endpoint: `${issuer}/token`,\n    registration_endpoint: `${issuer}/register`,\n    response_types_supported: [\"code\"],\n    scopes_supported: [\"openid\"],\n    jwks_uri: `${issuer}/.well-known/jwks.json`,\n  };\n}\n\nfunction mockDiscovery(issuer: string) {\n  return vi.spyOn(globalThis, \"fetch\").mockResolvedValue(\n    new Response(JSON.stringify(discoveryDoc(issuer)), {\n      headers: { \"content-type\": \"application/json\" },\n    }),\n  );\n}\n\ndescribe(\"descopeProvider\", () => {\n  it(\"derives issuer and audience (project id) from the MCP Server URL\", async () => {\n    const issuer = \"https://api.descope.com/v1/apps/agentic/P123/MS456\";\n    const fetchSpy = mockDiscovery(issuer);\n\n    const config = await descopeProvider({ url: issuer });\n\n    expect(fetchSpy).toHaveBeenCalledWith(\n      `${issuer}/.well-known/openid-configuration`,\n      expect.anything(),\n    );\n    expect(config.verify.issuer).toBe(issuer);\n    expect(config.verify.audience).toBe(\"P123\");\n  });\n\n  it(\"lets an explicit audience override the derived project id\", async () => {\n    const issuer = \"https://api.descope.com/v1/apps/agentic/P123/MS456\";\n    mockDiscovery(issuer);\n\n    const config = await descopeProvider({ url: issuer, audience: \"custom\" });\n\n    expect(config.verify.audience).toBe(\"custom\");\n  });\n});\n"]}
+{"version":3,"file":"descope.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/descope.test.ts"],"names":[],"mappings":"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","sourcesContent":["// @vitest-environment node\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { descopeProvider } from \"./descope.js\";\nimport { lastJwksConfig as jwks } from \"./verify-spy.js\";\n\nvi.mock(\"../verify.js\", () => import(\"./verify-spy.js\"));\n\nafterEach(() => vi.restoreAllMocks());\n\nfunction discoveryDoc(issuer: string, scopes: string[]) {\n  return {\n    issuer,\n    authorization_endpoint: `${issuer}/authorize`,\n    token_endpoint: `${issuer}/token`,\n    registration_endpoint: `${issuer}/register`,\n    response_types_supported: [\"code\"],\n    scopes_supported: scopes,\n    jwks_uri: `${issuer}/.well-known/jwks.json`,\n  };\n}\n\nconst PROJECT = \"https://api.descope.com/v1/apps/P123\";\nconst AGENTIC = \"https://api.descope.com/v1/apps/agentic/P123/MS456\";\n\nfunction mockDiscovery(docs: Record<string, string[]>) {\n  return vi\n    .spyOn(globalThis, \"fetch\")\n    .mockImplementation(async (input: RequestInfo | URL) => {\n      const url = String(input);\n      const entry = Object.entries(docs).find(\n        ([issuer]) => url === `${issuer}/.well-known/openid-configuration`,\n      );\n      if (entry === undefined) {\n        return new Response(null, { status: 404 });\n      }\n      return new Response(JSON.stringify(discoveryDoc(...entry)), {\n        headers: { \"content-type\": \"application/json\" },\n      });\n    });\n}\n\ndescribe(\"descopeProvider\", () => {\n  it(\"verifies against the agentic issuer it advertises\", async () => {\n    const fetchSpy = mockDiscovery({\n      [PROJECT]: [\"openid\", \"profile\", \"email\", \"phone\"],\n      [AGENTIC]: [\"checkout\"],\n    });\n\n    const config = await descopeProvider({ url: AGENTIC });\n\n    expect(fetchSpy).toHaveBeenCalledWith(\n      `${PROJECT}/.well-known/openid-configuration`,\n      expect.anything(),\n    );\n    expect(jwks().issuer).toBe(AGENTIC);\n    expect(jwks().audience).toBe(\"P123\");\n    expect(config.oauthMetadata.issuer).toBe(AGENTIC);\n    expect(config.oauthMetadata.registration_endpoint).toBe(\n      `${AGENTIC}/register`,\n    );\n    expect(config.scopesSupported).toEqual([\"checkout\"]);\n  });\n\n  it(\"accepts a URL carrying the well-known suffix\", async () => {\n    mockDiscovery({ [PROJECT]: [\"openid\"], [AGENTIC]: [\"checkout\"] });\n\n    const config = await descopeProvider({\n      url: `${AGENTIC}/.well-known/openid-configuration`,\n    });\n\n    expect(config.oauthMetadata.issuer).toBe(AGENTIC);\n    expect(config.scopesSupported).toEqual([\"checkout\"]);\n  });\n\n  it(\"lets an explicit audience override the derived project id\", async () => {\n    mockDiscovery({ [PROJECT]: [\"openid\"], [AGENTIC]: [\"checkout\"] });\n\n    await descopeProvider({ url: AGENTIC, audience: \"custom\" });\n\n    expect(jwks().audience).toBe(\"custom\");\n  });\n});\n"]}

package/dist/server/auth/providers/stytch.d.ts

@@ -1,12 +1,25 @@
+import type { ExtraClaims } from "../../auth.js";
 import type { OAuthConfig } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
+/**
+ * Claims a Stytch Connected Apps access token carries. Beyond the subject,
+ * everything is project-configured through the client's access-token template.
+ *
+ * @see https://stytch.com/docs/api-reference/consumer/api/connected-apps/tokens/connected-app-access-token-object
+ * @see https://stytch.com/docs/api/connected-apps-create
+ */
+export type StytchClaims = {
+    /** Only when the client's access-token template adds it. */
+    email?: string;
+};
 /**
  * OAuth provider for Stytch Connected Apps. `domain` is the project domain,
  * e.g. `acme.customers.stytch.dev`, or a configured custom domain. Requires
  * DCR enabled in the Stytch dashboard. `audience` is the Stytch Project ID
  * (the default token audience).
  */
-export declare function stytchProvider(opts: {
+export declare function stytchProvider<TCustom extends ExtraClaims = Record<never, never>>(opts: {
     domain: string;
     audience: string;
-} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig>;
+} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig<StytchClaims & TCustom & RegisteredClaims>>;

package/dist/server/auth/providers/stytch.js

@@ -8,6 +8,9 @@ import { toIssuerUrl } from "./shared.js";
  */
 export function stytchProvider(opts) {
     const { domain, ...rest } = opts;
-    return customProvider({ issuer: toIssuerUrl(domain), ...rest });
+    return customProvider({
+        issuer: toIssuerUrl(domain),
+        ...rest,
+    });
 }
 //# sourceMappingURL=stytch.js.map

package/dist/server/auth/providers/stytch.js.map

@@ -1 +1 @@
-{"version":3,"file":"stytch.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/stytch.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACjC,OAAO,cAAc,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC","sourcesContent":["import type { OAuthConfig } from \"../index.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\nimport { toIssuerUrl } from \"./shared.js\";\n\n/**\n * OAuth provider for Stytch Connected Apps. `domain` is the project domain,\n * e.g. `acme.customers.stytch.dev`, or a configured custom domain. Requires\n * DCR enabled in the Stytch dashboard. `audience` is the Stytch Project ID\n * (the default token audience).\n */\nexport function stytchProvider(\n  opts: { domain: string; audience: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\"\n  >,\n): Promise<OAuthConfig> {\n  const { domain, ...rest } = opts;\n  return customProvider({ issuer: toIssuerUrl(domain), ...rest });\n}\n"]}
+{"version":3,"file":"stytch.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/stytch.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc1C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAG5B,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACjC,OAAO,cAAc,CAAyB;QAC5C,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QAC3B,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthConfig } from \"../index.js\";\nimport type { RegisteredClaims } from \"../verify.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\nimport { toIssuerUrl } from \"./shared.js\";\n\n/**\n * Claims a Stytch Connected Apps access token carries. Beyond the subject,\n * everything is project-configured through the client's access-token template.\n *\n * @see https://stytch.com/docs/api-reference/consumer/api/connected-apps/tokens/connected-app-access-token-object\n * @see https://stytch.com/docs/api/connected-apps-create\n */\nexport type StytchClaims = {\n  /** Only when the client's access-token template adds it. */\n  email?: string;\n};\n\n/**\n * OAuth provider for Stytch Connected Apps. `domain` is the project domain,\n * e.g. `acme.customers.stytch.dev`, or a configured custom domain. Requires\n * DCR enabled in the Stytch dashboard. `audience` is the Stytch Project ID\n * (the default token audience).\n */\nexport function stytchProvider<\n  TCustom extends ExtraClaims = Record<never, never>,\n>(\n  opts: { domain: string; audience: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\"\n  >,\n): Promise<OAuthConfig<StytchClaims & TCustom & RegisteredClaims>> {\n  const { domain, ...rest } = opts;\n  return customProvider<StytchClaims & TCustom>({\n    issuer: toIssuerUrl(domain),\n    ...rest,\n  });\n}\n"]}

package/dist/server/auth/providers/verify-spy.d.ts

@@ -0,0 +1,12 @@
+export declare const createJwksVerifier: import("vitest").Mock<typeof import("../verify.js").createJwksVerifier>;
+/**
+ * The JWKS parameters a provider handed to `createJwksVerifier`: the issuer and
+ * JWKS URL it derived from discovery, and the audience it expects. Substitute
+ * this module for `../verify.js` to assert on them:
+ *
+ * ```ts
+ * vi.mock("../verify.js", () => import("./verify-spy.js"));
+ * import { lastJwksConfig as jwks } from "./verify-spy.js";
+ * ```
+ */
+export declare const lastJwksConfig: () => import("../verify.js").JwksVerifyConfig;

package/dist/server/auth/providers/verify-spy.js

@@ -0,0 +1,21 @@
+import { vi } from "vitest";
+const actual = await vi.importActual("../verify.js");
+export const createJwksVerifier = vi.fn(actual.createJwksVerifier);
+/**
+ * The JWKS parameters a provider handed to `createJwksVerifier`: the issuer and
+ * JWKS URL it derived from discovery, and the audience it expects. Substitute
+ * this module for `../verify.js` to assert on them:
+ *
+ * ```ts
+ * vi.mock("../verify.js", () => import("./verify-spy.js"));
+ * import { lastJwksConfig as jwks } from "./verify-spy.js";
+ * ```
+ */
+export const lastJwksConfig = () => {
+    const call = createJwksVerifier.mock.lastCall;
+    if (!call) {
+        throw new Error("createJwksVerifier was not called");
+    }
+    return call[0];
+};
+//# sourceMappingURL=verify-spy.js.map

package/dist/server/auth/providers/verify-spy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-spy.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/verify-spy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE5B,MAAM,MAAM,GACV,MAAM,EAAE,CAAC,YAAY,CAAgC,cAAc,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CAAC","sourcesContent":["import { vi } from \"vitest\";\n\nconst actual =\n  await vi.importActual<typeof import(\"../verify.js\")>(\"../verify.js\");\n\nexport const createJwksVerifier = vi.fn(actual.createJwksVerifier);\n\n/**\n * The JWKS parameters a provider handed to `createJwksVerifier`: the issuer and\n * JWKS URL it derived from discovery, and the audience it expects. Substitute\n * this module for `../verify.js` to assert on them:\n *\n * ```ts\n * vi.mock(\"../verify.js\", () => import(\"./verify-spy.js\"));\n * import { lastJwksConfig as jwks } from \"./verify-spy.js\";\n * ```\n */\nexport const lastJwksConfig = () => {\n  const call = createJwksVerifier.mock.lastCall;\n  if (!call) {\n    throw new Error(\"createJwksVerifier was not called\");\n  }\n  return call[0];\n};\n"]}

package/dist/server/auth/providers/workos.d.ts

@@ -1,11 +1,33 @@
+import type { ExtraClaims } from "../../auth.js";
 import type { OAuthConfig } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
+/**
+ * Claims a WorkOS AuthKit access token carries. All optional: `org_id`, `role`
+ * and `permissions` appear only when an organization is selected at sign-in, and
+ * `email` only when a JWT template adds it.
+ *
+ * @see https://workos.com/docs/authkit/sessions/integrating-sessions/access-token
+ * @see https://workos.com/docs/authkit/jwt-templates
+ */
+export type WorkosClaims = {
+    /** Session id, used for signing out. */
+    sid?: string;
+    /** Organization selected at sign-in. */
+    org_id?: string;
+    /** Role of the selected organization membership. */
+    role?: string;
+    /** Permissions assigned to the role. */
+    permissions?: string[];
+    /** Only when a JWT template adds it; not a default AuthKit claim. */
+    email?: string;
+};
 /**
  * OAuth provider for WorkOS AuthKit. `domain` is the AuthKit domain, e.g.
  * `acme.authkit.app`. Requires DCR enabled in the WorkOS dashboard
  * (Connect → Configuration). `audience` is the MCP server's Resource Indicator.
  */
-export declare function workosProvider(opts: {
+export declare function workosProvider<TCustom extends ExtraClaims = Record<never, never>>(opts: {
     domain: string;
     audience: string;
-} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig>;
+} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig<WorkosClaims & TCustom & RegisteredClaims>>;

package/dist/server/auth/providers/workos.js

@@ -7,6 +7,9 @@ import { toIssuerUrl } from "./shared.js";
  */
 export function workosProvider(opts) {
     const { domain, ...rest } = opts;
-    return customProvider({ issuer: toIssuerUrl(domain), ...rest });
+    return customProvider({
+        issuer: toIssuerUrl(domain),
+        ...rest,
+    });
 }
 //# sourceMappingURL=workos.js.map

package/dist/server/auth/providers/workos.js.map

@@ -1 +1 @@
-{"version":3,"file":"workos.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/workos.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACjC,OAAO,cAAc,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC","sourcesContent":["import type { OAuthConfig } from \"../index.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\nimport { toIssuerUrl } from \"./shared.js\";\n\n/**\n * OAuth provider for WorkOS AuthKit. `domain` is the AuthKit domain, e.g.\n * `acme.authkit.app`. Requires DCR enabled in the WorkOS dashboard\n * (Connect → Configuration). `audience` is the MCP server's Resource Indicator.\n */\nexport function workosProvider(\n  opts: { domain: string; audience: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\"\n  >,\n): Promise<OAuthConfig> {\n  const { domain, ...rest } = opts;\n  return customProvider({ issuer: toIssuerUrl(domain), ...rest });\n}\n"]}
+{"version":3,"file":"workos.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/workos.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuB1C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAG5B,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACjC,OAAO,cAAc,CAAyB;QAC5C,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QAC3B,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthConfig } from \"../index.js\";\nimport type { RegisteredClaims } from \"../verify.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\nimport { toIssuerUrl } from \"./shared.js\";\n\n/**\n * Claims a WorkOS AuthKit access token carries. All optional: `org_id`, `role`\n * and `permissions` appear only when an organization is selected at sign-in, and\n * `email` only when a JWT template adds it.\n *\n * @see https://workos.com/docs/authkit/sessions/integrating-sessions/access-token\n * @see https://workos.com/docs/authkit/jwt-templates\n */\nexport type WorkosClaims = {\n  /** Session id, used for signing out. */\n  sid?: string;\n  /** Organization selected at sign-in. */\n  org_id?: string;\n  /** Role of the selected organization membership. */\n  role?: string;\n  /** Permissions assigned to the role. */\n  permissions?: string[];\n  /** Only when a JWT template adds it; not a default AuthKit claim. */\n  email?: string;\n};\n\n/**\n * OAuth provider for WorkOS AuthKit. `domain` is the AuthKit domain, e.g.\n * `acme.authkit.app`. Requires DCR enabled in the WorkOS dashboard\n * (Connect → Configuration). `audience` is the MCP server's Resource Indicator.\n */\nexport function workosProvider<\n  TCustom extends ExtraClaims = Record<never, never>,\n>(\n  opts: { domain: string; audience: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\"\n  >,\n): Promise<OAuthConfig<WorkosClaims & TCustom & RegisteredClaims>> {\n  const { domain, ...rest } = opts;\n  return customProvider<WorkosClaims & TCustom>({\n    issuer: toIssuerUrl(domain),\n    ...rest,\n  });\n}\n"]}

package/dist/server/auth/security-schemes.d.ts

@@ -0,0 +1,23 @@
+import type { AuthInfo } from "../auth.js";
+import type { SecurityScheme, ToolAuth } from "../server.js";
+export declare function authToSecuritySchemes(auth: ToolAuth): SecurityScheme[];
+export declare function securitySchemesAllowAnonymous(schemes: SecurityScheme[] | undefined): boolean;
+export type SchemeFailure = {
+    error: "invalid_token" | "insufficient_scope";
+    description: string;
+    scopes: string[];
+};
+export declare function evaluateSecuritySchemes(schemes: SecurityScheme[] | undefined, authInfo: AuthInfo | undefined): SchemeFailure | undefined;
+export declare function httpStatusForFailure(failure: SchemeFailure): 401 | 403;
+export declare function clientPrefersInBandChallenge(userAgent: string | undefined): boolean;
+export declare function wwwAuthenticateHeader(failure: SchemeFailure, resourceMetadataUrl?: string): string;
+export declare function inBandChallengeResult(failure: SchemeFailure, resourceMetadataUrl?: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        "mcp/www_authenticate": string[];
+    };
+};

package/dist/server/auth/security-schemes.js

@@ -0,0 +1,64 @@
+import { hostFromUserAgent } from "../host.js";
+export function authToSecuritySchemes(auth) {
+    const oauth2 = {
+        type: "oauth2",
+        ...(auth.scopes?.length ? { scopes: auth.scopes } : {}),
+    };
+    return auth.allowsAnonymous ? [{ type: "noauth" }, oauth2] : [oauth2];
+}
+export function securitySchemesAllowAnonymous(schemes) {
+    return !!schemes?.some((scheme) => scheme.type === "noauth");
+}
+export function evaluateSecuritySchemes(schemes, authInfo) {
+    if (securitySchemesAllowAnonymous(schemes) && !authInfo) {
+        return undefined;
+    }
+    const oauth2 = (schemes ?? []).filter((scheme) => scheme.type === "oauth2");
+    const required = oauth2.length ? oauth2 : [{ type: "oauth2" }];
+    const scopes = [
+        ...new Set(required.flatMap((scheme) => scheme.scopes ?? [])),
+    ];
+    if (!authInfo) {
+        return {
+            error: "invalid_token",
+            description: "Sign in to use this tool.",
+            scopes,
+        };
+    }
+    const satisfied = required.some((scheme) => (scheme.scopes ?? []).every((scope) => authInfo.scopes.includes(scope)));
+    return satisfied
+        ? undefined
+        : {
+            error: "insufficient_scope",
+            description: "Missing required scope for this tool.",
+            scopes,
+        };
+}
+export function httpStatusForFailure(failure) {
+    return failure.error === "insufficient_scope" ? 403 : 401;
+}
+export function clientPrefersInBandChallenge(userAgent) {
+    return hostFromUserAgent(userAgent) === "openai";
+}
+export function wwwAuthenticateHeader(failure, resourceMetadataUrl) {
+    let header = `Bearer error="${failure.error}", error_description="${failure.description}"`;
+    if (failure.scopes.length) {
+        header += `, scope="${failure.scopes.join(" ")}"`;
+    }
+    if (resourceMetadataUrl) {
+        header += `, resource_metadata="${resourceMetadataUrl}"`;
+    }
+    return header;
+}
+export function inBandChallengeResult(failure, resourceMetadataUrl) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: failure.description }],
+        _meta: {
+            "mcp/www_authenticate": [
+                wwwAuthenticateHeader(failure, resourceMetadataUrl),
+            ],
+        },
+    };
+}
+//# sourceMappingURL=security-schemes.js.map

package/dist/server/auth/security-schemes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-schemes.js","sourceRoot":"","sources":["../../../src/server/auth/security-schemes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG/C,MAAM,UAAU,qBAAqB,CAAC,IAAc;IAClD,MAAM,MAAM,GAAmB;QAC7B,IAAI,EAAE,QAAQ;QACd,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;IACF,OAAO,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,OAAqC;IAErC,OAAO,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAQD,MAAM,UAAU,uBAAuB,CACrC,OAAqC,EACrC,QAA8B;IAE9B,IAAI,6BAA6B,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG;QACb,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;KAC9D,CAAC;IACF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,KAAK,EAAE,eAAe;YACtB,WAAW,EAAE,2BAA2B;YACxC,MAAM;SACP,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CACzC,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CACxE,CAAC;IACF,OAAO,SAAS;QACd,CAAC,CAAC,SAAS;QACX,CAAC,CAAC;YACE,KAAK,EAAE,oBAAoB;YAC3B,WAAW,EAAE,uCAAuC;YACpD,MAAM;SACP,CAAC;AACR,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAsB;IACzD,OAAO,OAAO,CAAC,KAAK,KAAK,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,SAA6B;IAE7B,OAAO,iBAAiB,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,mBAA4B;IAE5B,IAAI,MAAM,GAAG,iBAAiB,OAAO,CAAC,KAAK,yBAAyB,OAAO,CAAC,WAAW,GAAG,CAAC;IAC3F,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,YAAY,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACpD,CAAC;IACD,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,wBAAwB,mBAAmB,GAAG,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,mBAA4B;IAE5B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAC/D,KAAK,EAAE;YACL,sBAAsB,EAAE;gBACtB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,CAAC;aACpD;SACF;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { AuthInfo } from \"../auth.js\";\nimport { hostFromUserAgent } from \"../host.js\";\nimport type { SecurityScheme, ToolAuth } from \"../server.js\";\n\nexport function authToSecuritySchemes(auth: ToolAuth): SecurityScheme[] {\n  const oauth2: SecurityScheme = {\n    type: \"oauth2\",\n    ...(auth.scopes?.length ? { scopes: auth.scopes } : {}),\n  };\n  return auth.allowsAnonymous ? [{ type: \"noauth\" }, oauth2] : [oauth2];\n}\n\nexport function securitySchemesAllowAnonymous(\n  schemes: SecurityScheme[] | undefined,\n): boolean {\n  return !!schemes?.some((scheme) => scheme.type === \"noauth\");\n}\n\nexport type SchemeFailure = {\n  error: \"invalid_token\" | \"insufficient_scope\";\n  description: string;\n  scopes: string[];\n};\n\nexport function evaluateSecuritySchemes(\n  schemes: SecurityScheme[] | undefined,\n  authInfo: AuthInfo | undefined,\n): SchemeFailure | undefined {\n  if (securitySchemesAllowAnonymous(schemes) && !authInfo) {\n    return undefined;\n  }\n  const oauth2 = (schemes ?? []).filter((scheme) => scheme.type === \"oauth2\");\n  const required = oauth2.length ? oauth2 : [{ type: \"oauth2\" as const }];\n  const scopes = [\n    ...new Set(required.flatMap((scheme) => scheme.scopes ?? [])),\n  ];\n  if (!authInfo) {\n    return {\n      error: \"invalid_token\",\n      description: \"Sign in to use this tool.\",\n      scopes,\n    };\n  }\n  const satisfied = required.some((scheme) =>\n    (scheme.scopes ?? []).every((scope) => authInfo.scopes.includes(scope)),\n  );\n  return satisfied\n    ? undefined\n    : {\n        error: \"insufficient_scope\",\n        description: \"Missing required scope for this tool.\",\n        scopes,\n      };\n}\n\nexport function httpStatusForFailure(failure: SchemeFailure): 401 | 403 {\n  return failure.error === \"insufficient_scope\" ? 403 : 401;\n}\n\nexport function clientPrefersInBandChallenge(\n  userAgent: string | undefined,\n): boolean {\n  return hostFromUserAgent(userAgent) === \"openai\";\n}\n\nexport function wwwAuthenticateHeader(\n  failure: SchemeFailure,\n  resourceMetadataUrl?: string,\n): string {\n  let header = `Bearer error=\"${failure.error}\", error_description=\"${failure.description}\"`;\n  if (failure.scopes.length) {\n    header += `, scope=\"${failure.scopes.join(\" \")}\"`;\n  }\n  if (resourceMetadataUrl) {\n    header += `, resource_metadata=\"${resourceMetadataUrl}\"`;\n  }\n  return header;\n}\n\nexport function inBandChallengeResult(\n  failure: SchemeFailure,\n  resourceMetadataUrl?: string,\n) {\n  return {\n    isError: true,\n    content: [{ type: \"text\" as const, text: failure.description }],\n    _meta: {\n      \"mcp/www_authenticate\": [\n        wwwAuthenticateHeader(failure, resourceMetadataUrl),\n      ],\n    },\n  };\n}\n"]}

package/dist/server/auth/security-schemes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/auth/security-schemes.test.js

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { authToSecuritySchemes, clientPrefersInBandChallenge, evaluateSecuritySchemes, securitySchemesAllowAnonymous, wwwAuthenticateHeader, } from "./security-schemes.js";
+describe("clientPrefersInBandChallenge", () => {
+    it("detects ChatGPT / OpenAI user agents", () => {
+        expect(clientPrefersInBandChallenge("openai-mcp/1.0")).toBe(true);
+        expect(clientPrefersInBandChallenge("ChatGPT")).toBe(true);
+        expect(clientPrefersInBandChallenge("Claude-User/1.0")).toBe(false);
+        expect(clientPrefersInBandChallenge(undefined)).toBe(false);
+    });
+});
+describe("authToSecuritySchemes", () => {
+    it("maps the auth shorthand", () => {
+        expect(authToSecuritySchemes({ allowsAnonymous: true })).toEqual([
+            { type: "noauth" },
+            { type: "oauth2" },
+        ]);
+        expect(authToSecuritySchemes({})).toEqual([{ type: "oauth2" }]);
+        expect(authToSecuritySchemes({ scopes: ["checkout"] })).toEqual([
+            { type: "oauth2", scopes: ["checkout"] },
+        ]);
+        expect(authToSecuritySchemes({ allowsAnonymous: true, scopes: ["checkout"] })).toEqual([{ type: "noauth" }, { type: "oauth2", scopes: ["checkout"] }]);
+    });
+});
+const authInfo = (scopes) => ({
+    token: "t",
+    clientId: "c",
+    scopes,
+});
+describe("securitySchemesAllowAnonymous", () => {
+    it("is true only when a noauth scheme is present", () => {
+        expect(securitySchemesAllowAnonymous([{ type: "noauth" }])).toBe(true);
+        expect(securitySchemesAllowAnonymous([{ type: "noauth" }, { type: "oauth2" }])).toBe(true);
+        expect(securitySchemesAllowAnonymous([{ type: "oauth2" }])).toBe(false);
+        expect(securitySchemesAllowAnonymous(undefined)).toBe(false);
+    });
+});
+describe("evaluateSecuritySchemes", () => {
+    it("lets anonymous callers through a noauth tool", () => {
+        const schemes = [{ type: "noauth" }, { type: "oauth2" }];
+        expect(evaluateSecuritySchemes(schemes, undefined)).toBeUndefined();
+    });
+    it("enforces oauth2 scopes on a public tool once a token is present", () => {
+        const schemes = [
+            { type: "noauth" },
+            { type: "oauth2", scopes: ["checkout"] },
+        ];
+        expect(evaluateSecuritySchemes(schemes, undefined)).toBeUndefined();
+        expect(evaluateSecuritySchemes(schemes, authInfo(["openid"]))?.error).toBe("insufficient_scope");
+        expect(evaluateSecuritySchemes(schemes, authInfo(["checkout"]))).toBeUndefined();
+    });
+    it("fails an oauth2-only tool with no token (invalid_token / 401)", () => {
+        expect(evaluateSecuritySchemes([{ type: "oauth2" }], undefined)?.error).toBe("invalid_token");
+    });
+    it("fails when the token is missing a required scope (insufficient_scope / 403)", () => {
+        const schemes = [
+            { type: "oauth2", scopes: ["checkout"] },
+        ];
+        expect(evaluateSecuritySchemes(schemes, authInfo(["openid"]))?.error).toBe("insufficient_scope");
+    });
+    it("passes when the token carries every required scope", () => {
+        const schemes = [
+            { type: "oauth2", scopes: ["checkout"] },
+        ];
+        expect(evaluateSecuritySchemes(schemes, authInfo(["openid", "checkout"]))).toBeUndefined();
+    });
+    it("treats an undeclared tool as auth-required, satisfied by any valid token", () => {
+        expect(evaluateSecuritySchemes(undefined, undefined)?.error).toBe("invalid_token");
+        expect(evaluateSecuritySchemes(undefined, authInfo([]))).toBeUndefined();
+    });
+    it("carries the tool's required scopes on the failure", () => {
+        const schemes = [
+            { type: "oauth2", scopes: ["checkout"] },
+        ];
+        expect(evaluateSecuritySchemes(schemes, undefined)?.scopes).toEqual([
+            "checkout",
+        ]);
+        expect(evaluateSecuritySchemes(schemes, authInfo(["openid"]))?.scopes).toEqual(["checkout"]);
+    });
+});
+describe("wwwAuthenticateHeader", () => {
+    it("names the required scopes so the client can step up", () => {
+        const header = wwwAuthenticateHeader({
+            error: "insufficient_scope",
+            description: "Missing required scope for this tool.",
+            scopes: ["checkout"],
+        });
+        expect(header).toContain('error="insufficient_scope"');
+        expect(header).toContain('scope="checkout"');
+    });
+    it("omits the scope parameter when there are none", () => {
+        const header = wwwAuthenticateHeader({
+            error: "invalid_token",
+            description: "Sign in to use this tool.",
+            scopes: [],
+        });
+        expect(header).not.toContain("scope=");
+    });
+});
+//# sourceMappingURL=security-schemes.test.js.map

package/dist/server/auth/security-schemes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-schemes.test.js","sourceRoot":"","sources":["../../../src/server/auth/security-schemes.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport type { AuthInfo } from \"../auth.js\";\nimport type { SecurityScheme } from \"../server.js\";\nimport {\n  authToSecuritySchemes,\n  clientPrefersInBandChallenge,\n  evaluateSecuritySchemes,\n  securitySchemesAllowAnonymous,\n  wwwAuthenticateHeader,\n} from \"./security-schemes.js\";\n\ndescribe(\"clientPrefersInBandChallenge\", () => {\n  it(\"detects ChatGPT / OpenAI user agents\", () => {\n    expect(clientPrefersInBandChallenge(\"openai-mcp/1.0\")).toBe(true);\n    expect(clientPrefersInBandChallenge(\"ChatGPT\")).toBe(true);\n    expect(clientPrefersInBandChallenge(\"Claude-User/1.0\")).toBe(false);\n    expect(clientPrefersInBandChallenge(undefined)).toBe(false);\n  });\n});\n\ndescribe(\"authToSecuritySchemes\", () => {\n  it(\"maps the auth shorthand\", () => {\n    expect(authToSecuritySchemes({ allowsAnonymous: true })).toEqual([\n      { type: \"noauth\" },\n      { type: \"oauth2\" },\n    ]);\n    expect(authToSecuritySchemes({})).toEqual([{ type: \"oauth2\" }]);\n    expect(authToSecuritySchemes({ scopes: [\"checkout\"] })).toEqual([\n      { type: \"oauth2\", scopes: [\"checkout\"] },\n    ]);\n    expect(\n      authToSecuritySchemes({ allowsAnonymous: true, scopes: [\"checkout\"] }),\n    ).toEqual([{ type: \"noauth\" }, { type: \"oauth2\", scopes: [\"checkout\"] }]);\n  });\n});\n\nconst authInfo = (scopes: string[]): AuthInfo => ({\n  token: \"t\",\n  clientId: \"c\",\n  scopes,\n});\n\ndescribe(\"securitySchemesAllowAnonymous\", () => {\n  it(\"is true only when a noauth scheme is present\", () => {\n    expect(securitySchemesAllowAnonymous([{ type: \"noauth\" }])).toBe(true);\n    expect(\n      securitySchemesAllowAnonymous([{ type: \"noauth\" }, { type: \"oauth2\" }]),\n    ).toBe(true);\n    expect(securitySchemesAllowAnonymous([{ type: \"oauth2\" }])).toBe(false);\n    expect(securitySchemesAllowAnonymous(undefined)).toBe(false);\n  });\n});\n\ndescribe(\"evaluateSecuritySchemes\", () => {\n  it(\"lets anonymous callers through a noauth tool\", () => {\n    const schemes: SecurityScheme[] = [{ type: \"noauth\" }, { type: \"oauth2\" }];\n    expect(evaluateSecuritySchemes(schemes, undefined)).toBeUndefined();\n  });\n\n  it(\"enforces oauth2 scopes on a public tool once a token is present\", () => {\n    const schemes: SecurityScheme[] = [\n      { type: \"noauth\" },\n      { type: \"oauth2\", scopes: [\"checkout\"] },\n    ];\n    expect(evaluateSecuritySchemes(schemes, undefined)).toBeUndefined();\n    expect(evaluateSecuritySchemes(schemes, authInfo([\"openid\"]))?.error).toBe(\n      \"insufficient_scope\",\n    );\n    expect(\n      evaluateSecuritySchemes(schemes, authInfo([\"checkout\"])),\n    ).toBeUndefined();\n  });\n\n  it(\"fails an oauth2-only tool with no token (invalid_token / 401)\", () => {\n    expect(\n      evaluateSecuritySchemes([{ type: \"oauth2\" }], undefined)?.error,\n    ).toBe(\"invalid_token\");\n  });\n\n  it(\"fails when the token is missing a required scope (insufficient_scope / 403)\", () => {\n    const schemes: SecurityScheme[] = [\n      { type: \"oauth2\", scopes: [\"checkout\"] },\n    ];\n    expect(evaluateSecuritySchemes(schemes, authInfo([\"openid\"]))?.error).toBe(\n      \"insufficient_scope\",\n    );\n  });\n\n  it(\"passes when the token carries every required scope\", () => {\n    const schemes: SecurityScheme[] = [\n      { type: \"oauth2\", scopes: [\"checkout\"] },\n    ];\n    expect(\n      evaluateSecuritySchemes(schemes, authInfo([\"openid\", \"checkout\"])),\n    ).toBeUndefined();\n  });\n\n  it(\"treats an undeclared tool as auth-required, satisfied by any valid token\", () => {\n    expect(evaluateSecuritySchemes(undefined, undefined)?.error).toBe(\n      \"invalid_token\",\n    );\n    expect(evaluateSecuritySchemes(undefined, authInfo([]))).toBeUndefined();\n  });\n\n  it(\"carries the tool's required scopes on the failure\", () => {\n    const schemes: SecurityScheme[] = [\n      { type: \"oauth2\", scopes: [\"checkout\"] },\n    ];\n    expect(evaluateSecuritySchemes(schemes, undefined)?.scopes).toEqual([\n      \"checkout\",\n    ]);\n    expect(\n      evaluateSecuritySchemes(schemes, authInfo([\"openid\"]))?.scopes,\n    ).toEqual([\"checkout\"]);\n  });\n});\n\ndescribe(\"wwwAuthenticateHeader\", () => {\n  it(\"names the required scopes so the client can step up\", () => {\n    const header = wwwAuthenticateHeader({\n      error: \"insufficient_scope\",\n      description: \"Missing required scope for this tool.\",\n      scopes: [\"checkout\"],\n    });\n    expect(header).toContain('error=\"insufficient_scope\"');\n    expect(header).toContain('scope=\"checkout\"');\n  });\n\n  it(\"omits the scope parameter when there are none\", () => {\n    const header = wwwAuthenticateHeader({\n      error: \"invalid_token\",\n      description: \"Sign in to use this tool.\",\n      scopes: [],\n    });\n    expect(header).not.toContain(\"scope=\");\n  });\n});\n"]}

package/dist/server/auth/setup.d.ts

@@ -1,4 +1,6 @@
 import type { Express } from "express";
+import type { SecurityScheme } from "../server.js";
 import type { OAuthConfig } from "./index.js";
+export type ResourceMetadataUrlResolver = (getHeader: (key: string) => string | undefined) => string;
 /** Mounts the well-known OAuth metadata and bearer auth on `/mcp`. */
-export declare function setupOAuth(app: Express, config: OAuthConfig): void;
+export declare function setupOAuth(app: Express, config: OAuthConfig<Record<string, unknown>>, schemesByTool: Map<string, SecurityScheme[] | undefined>): ResourceMetadataUrlResolver;