skybridge 0.0.0-dev.edc0ede → 0.0.0-dev.eddca63

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

@@ -0,0 +1,128 @@
+// @vitest-environment node
+import http from "node:http";
+import { afterEach, describe, expect, it } from "vitest";
+import { customProvider } from "./custom.js";
+let server;
+afterEach(() => server?.close());
+function doc(origin, extra = {}) {
+    return {
+        issuer: origin,
+        authorization_endpoint: `${origin}/authorize`,
+        token_endpoint: `${origin}/token`,
+        registration_endpoint: `${origin}/register`,
+        response_types_supported: ["code"],
+        scopes_supported: ["openid", "email", "profile"],
+        jwks_uri: `${origin}/jwks`,
+        ...extra,
+    };
+}
+// Serves the discovery doc (built from the live origin) at the OIDC well-known path.
+async function serveDiscovery(extra = {}) {
+    let origin = "";
+    const srv = http.createServer((req, res) => {
+        if (req.url !== "/.well-known/openid-configuration") {
+            res.writeHead(404).end();
+            return;
+        }
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(doc(origin, extra)));
+    });
+    await new Promise((resolve) => srv.listen(0, resolve));
+    server = srv;
+    origin = `http://localhost:${srv.address().port}`;
+    return origin;
+}
+describe("customProvider", () => {
+    it("builds an OAuthConfig from discovery", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "my-api",
+            baseUrl: "https://app.example.test",
+            scopes: ["openid"],
+        });
+        expect(config.baseUrl).toBe("https://app.example.test");
+        expect(config.verify).toEqual({
+            issuer: base,
+            audience: "my-api",
+            jwksUri: `${base}/jwks`,
+        });
+        expect(config.scopesSupported).toEqual(["openid"]);
+        expect(config.oauthMetadata.registration_endpoint).toBe(`${base}/register`);
+    });
+    it("ignores a runtime issuer override (keeps the discovered trust anchor)", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            metadataOverrides: { issuer: "https://evil.test" },
+        });
+        expect(config.verify.issuer).toBe(base);
+        expect(config.oauthMetadata.issuer).toBe(base);
+    });
+    it("ignores a runtime jwks_uri override (keeps the discovered signing keys)", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            metadataOverrides: { jwks_uri: "https://evil.test/keys" },
+        });
+        expect(config.verify.jwksUri).toBe(`${base}/jwks`);
+    });
+    it("serves metadata without a registration_endpoint when the IdP has no DCR", async () => {
+        const base = await serveDiscovery({ registration_endpoint: undefined });
+        const config = await customProvider({ issuer: base, audience: "a" });
+        expect(config.oauthMetadata.registration_endpoint).toBeUndefined();
+        expect(config.verify.issuer).toBe(base);
+    });
+    it("throws when discovery has no jwks_uri (token verification needs it)", async () => {
+        const base = await serveDiscovery({ jwks_uri: undefined });
+        await expect(customProvider({ issuer: base, audience: "a" })).rejects.toThrow(/jwks_uri/);
+    });
+    it("serverUrl advertises this server as the AS, keeping the IdP as the token issuer", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            serverUrl: "https://app.example.test/",
+            scopes: ["openid"],
+        });
+        // AS metadata + advertised scopes reflect this server.
+        expect(config.oauthMetadata.issuer).toBe("https://app.example.test");
+        expect(config.oauthMetadata.scopes_supported).toEqual(["openid"]);
+        // but the token's issuer is still verified against the IdP.
+        expect(config.verify.issuer).toBe(base);
+    });
+    it("authorizationServer advertises a distinct AS, keeping the discovered issuer for verification", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            authorizationServer: "https://as.example.test/agentic/P1/MS1/",
+        });
+        expect(config.oauthMetadata.issuer).toBe("https://as.example.test/agentic/P1/MS1");
+        expect(config.verify.issuer).toBe(base);
+    });
+    it("serverUrl takes precedence over authorizationServer", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            serverUrl: "https://app.example.test/",
+            authorizationServer: "https://as.example.test/agentic/P1/MS1",
+        });
+        expect(config.oauthMetadata.issuer).toBe("https://app.example.test");
+        expect(config.verify.issuer).toBe(base);
+    });
+    it("applies metadataOverrides over discovered values", async () => {
+        const base = await serveDiscovery();
+        const config = await customProvider({
+            issuer: base,
+            audience: "a",
+            baseUrl: "https://app.example.test",
+            metadataOverrides: { token_endpoint: "https://override/token" },
+        });
+        expect(config.oauthMetadata.token_endpoint).toBe("https://override/token");
+    });
+});
+//# sourceMappingURL=custom.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"custom.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/custom.test.ts"],"names":[],"mappings":"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","sourcesContent":["// @vitest-environment node\nimport http from \"node:http\";\nimport { afterEach, describe, expect, it } from \"vitest\";\nimport { customProvider } from \"./custom.js\";\n\nlet server: http.Server | undefined;\nafterEach(() => server?.close());\n\nfunction doc(origin: string, extra: Record<string, unknown> = {}) {\n  return {\n    issuer: origin,\n    authorization_endpoint: `${origin}/authorize`,\n    token_endpoint: `${origin}/token`,\n    registration_endpoint: `${origin}/register`,\n    response_types_supported: [\"code\"],\n    scopes_supported: [\"openid\", \"email\", \"profile\"],\n    jwks_uri: `${origin}/jwks`,\n    ...extra,\n  };\n}\n\n// Serves the discovery doc (built from the live origin) at the OIDC well-known path.\nasync function serveDiscovery(extra: Record<string, unknown> = {}) {\n  let origin = \"\";\n  const srv = http.createServer((req, res) => {\n    if (req.url !== \"/.well-known/openid-configuration\") {\n      res.writeHead(404).end();\n      return;\n    }\n    res.setHeader(\"content-type\", \"application/json\");\n    res.end(JSON.stringify(doc(origin, extra)));\n  });\n  await new Promise<void>((resolve) => srv.listen(0, resolve));\n  server = srv;\n  origin = `http://localhost:${(srv.address() as { port: number }).port}`;\n  return origin;\n}\n\ndescribe(\"customProvider\", () => {\n  it(\"builds an OAuthConfig from discovery\", async () => {\n    const base = await serveDiscovery();\n\n    const config = await customProvider({\n      issuer: base,\n      audience: \"my-api\",\n      baseUrl: \"https://app.example.test\",\n      scopes: [\"openid\"],\n    });\n\n    expect(config.baseUrl).toBe(\"https://app.example.test\");\n    expect(config.verify).toEqual({\n      issuer: base,\n      audience: \"my-api\",\n      jwksUri: `${base}/jwks`,\n    });\n    expect(config.scopesSupported).toEqual([\"openid\"]);\n    expect(config.oauthMetadata.registration_endpoint).toBe(`${base}/register`);\n  });\n\n  it(\"ignores a runtime issuer override (keeps the discovered trust anchor)\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      metadataOverrides: { issuer: \"https://evil.test\" } as never,\n    });\n    expect(config.verify.issuer).toBe(base);\n    expect(config.oauthMetadata.issuer).toBe(base);\n  });\n\n  it(\"ignores a runtime jwks_uri override (keeps the discovered signing keys)\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      metadataOverrides: { jwks_uri: \"https://evil.test/keys\" } as never,\n    });\n    expect(config.verify.jwksUri).toBe(`${base}/jwks`);\n  });\n\n  it(\"serves metadata without a registration_endpoint when the IdP has no DCR\", async () => {\n    const base = await serveDiscovery({ registration_endpoint: undefined });\n    const config = await customProvider({ issuer: base, audience: \"a\" });\n    expect(config.oauthMetadata.registration_endpoint).toBeUndefined();\n    expect(config.verify.issuer).toBe(base);\n  });\n\n  it(\"throws when discovery has no jwks_uri (token verification needs it)\", async () => {\n    const base = await serveDiscovery({ jwks_uri: undefined });\n    await expect(\n      customProvider({ issuer: base, audience: \"a\" }),\n    ).rejects.toThrow(/jwks_uri/);\n  });\n\n  it(\"serverUrl advertises this server as the AS, keeping the IdP as the token issuer\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      serverUrl: \"https://app.example.test/\",\n      scopes: [\"openid\"],\n    });\n    // AS metadata + advertised scopes reflect this server.\n    expect(config.oauthMetadata.issuer).toBe(\"https://app.example.test\");\n    expect(config.oauthMetadata.scopes_supported).toEqual([\"openid\"]);\n    // but the token's issuer is still verified against the IdP.\n    expect(config.verify.issuer).toBe(base);\n  });\n\n  it(\"authorizationServer advertises a distinct AS, keeping the discovered issuer for verification\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      authorizationServer: \"https://as.example.test/agentic/P1/MS1/\",\n    });\n    expect(config.oauthMetadata.issuer).toBe(\n      \"https://as.example.test/agentic/P1/MS1\",\n    );\n    expect(config.verify.issuer).toBe(base);\n  });\n\n  it(\"serverUrl takes precedence over authorizationServer\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      serverUrl: \"https://app.example.test/\",\n      authorizationServer: \"https://as.example.test/agentic/P1/MS1\",\n    });\n    expect(config.oauthMetadata.issuer).toBe(\"https://app.example.test\");\n    expect(config.verify.issuer).toBe(base);\n  });\n\n  it(\"applies metadataOverrides over discovered values\", async () => {\n    const base = await serveDiscovery();\n    const config = await customProvider({\n      issuer: base,\n      audience: \"a\",\n      baseUrl: \"https://app.example.test\",\n      metadataOverrides: { token_endpoint: \"https://override/token\" },\n    });\n    expect(config.oauthMetadata.token_endpoint).toBe(\"https://override/token\");\n  });\n});\n"]}

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

@@ -0,0 +1,15 @@
+import type { OAuthConfig } from "../index.js";
+import { type CustomProviderOptions } from "./custom.js";
+/**
+ * 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. 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: {
+    url: string;
+} & Omit<CustomProviderOptions, "issuer">): Promise<OAuthConfig>;

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

@@ -0,0 +1,35 @@
+import { customProvider } from "./custom.js";
+/**
+ * Derives the Descope Project ID from an MCP Server URL
+ * (`…/agentic/<projectId>/<mcpServerId>`). Descope binds the token `aud` to the
+ * project id, so it doubles as the audience.
+ */
+function projectIdFromUrl(url) {
+    const projectId = url.match(/\/agentic\/([^/]+)\/[^/]+/)?.[1];
+    if (!projectId) {
+        throw new Error(`Could not derive the Descope project id from "${url}"; pass an explicit \`audience\`.`);
+    }
+    return projectId;
+}
+/**
+ * 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. 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 projectId = projectIdFromUrl(url);
+    const issuer = `${url.slice(0, url.indexOf("/agentic/"))}/${projectId}`;
+    return customProvider({
+        issuer,
+        audience: audience ?? projectId,
+        authorizationServer: url,
+        ...rest,
+    });
+}
+//# sourceMappingURL=descope.js.map

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

@@ -0,0 +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;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA6D;IAE7D,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC;IACxE,OAAO,cAAc,CAAC;QACpB,MAAM;QACN,QAAQ,EAAE,QAAQ,IAAI,SAAS;QAC/B,mBAAmB,EAAE,GAAG;QACxB,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. 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  opts: { url: string } & Omit<CustomProviderOptions, \"issuer\">,\n): Promise<OAuthConfig> {\n  const { url, audience, ...rest } = opts;\n  const projectId = projectIdFromUrl(url);\n  const issuer = `${url.slice(0, url.indexOf(\"/agentic/\"))}/${projectId}`;\n  return customProvider({\n    issuer,\n    audience: audience ?? projectId,\n    authorizationServer: url,\n    ...rest,\n  });\n}\n"]}

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

@@ -0,0 +1,39 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { descopeProvider } from "./descope.js";
+afterEach(() => vi.restoreAllMocks());
+function discoveryDoc(issuer) {
+    return {
+        issuer,
+        authorization_endpoint: `${issuer}/authorize`,
+        token_endpoint: `${issuer}/token`,
+        registration_endpoint: `${issuer}/register`,
+        response_types_supported: ["code"],
+        scopes_supported: ["openid"],
+        jwks_uri: `${issuer}/.well-known/jwks.json`,
+    };
+}
+function mockDiscovery(issuer) {
+    return vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response(JSON.stringify(discoveryDoc(issuer)), {
+        headers: { "content-type": "application/json" },
+    }));
+}
+describe("descopeProvider", () => {
+    it("builds the base-project issuer and audience (project id) from the MCP Server URL", async () => {
+        const url = "https://api.descope.com/v1/apps/agentic/P123/MS456";
+        const base = "https://api.descope.com/v1/apps/P123";
+        const fetchSpy = mockDiscovery(base);
+        const config = await descopeProvider({ url });
+        expect(fetchSpy).toHaveBeenCalledWith(`${base}/.well-known/openid-configuration`, expect.anything());
+        expect(config.verify.issuer).toBe(base);
+        expect(config.verify.audience).toBe("P123");
+        expect(config.oauthMetadata.issuer).toBe(url);
+    });
+    it("lets an explicit audience override the derived project id", async () => {
+        const url = "https://api.descope.com/v1/apps/agentic/P123/MS456";
+        mockDiscovery("https://api.descope.com/v1/apps/P123");
+        const config = await descopeProvider({ url, audience: "custom" });
+        expect(config.verify.audience).toBe("custom");
+    });
+});
+//# sourceMappingURL=descope.test.js.map

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

@@ -0,0 +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,kBAAkB,CACrD,KAAK,IAAI,EAAE,CACT,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE;QACjD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;KAChD,CAAC,CACL,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;QAChG,MAAM,GAAG,GAAG,oDAAoD,CAAC;QACjE,MAAM,IAAI,GAAG,sCAAsC,CAAC;QACpD,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAErC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;QAE9C,MAAM,CAAC,QAAQ,CAAC,CAAC,oBAAoB,CACnC,GAAG,IAAI,mCAAmC,EAC1C,MAAM,CAAC,QAAQ,EAAE,CAClB,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,GAAG,GAAG,oDAAoD,CAAC;QACjE,aAAa,CAAC,sCAAsC,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAElE,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\").mockImplementation(\n    async () =>\n      new Response(JSON.stringify(discoveryDoc(issuer)), {\n        headers: { \"content-type\": \"application/json\" },\n      }),\n  );\n}\n\ndescribe(\"descopeProvider\", () => {\n  it(\"builds the base-project issuer and audience (project id) from the MCP Server URL\", async () => {\n    const url = \"https://api.descope.com/v1/apps/agentic/P123/MS456\";\n    const base = \"https://api.descope.com/v1/apps/P123\";\n    const fetchSpy = mockDiscovery(base);\n\n    const config = await descopeProvider({ url });\n\n    expect(fetchSpy).toHaveBeenCalledWith(\n      `${base}/.well-known/openid-configuration`,\n      expect.anything(),\n    );\n    expect(config.verify.issuer).toBe(base);\n    expect(config.verify.audience).toBe(\"P123\");\n    expect(config.oauthMetadata.issuer).toBe(url);\n  });\n\n  it(\"lets an explicit audience override the derived project id\", async () => {\n    const url = \"https://api.descope.com/v1/apps/agentic/P123/MS456\";\n    mockDiscovery(\"https://api.descope.com/v1/apps/P123\");\n\n    const config = await descopeProvider({ url, audience: \"custom\" });\n\n    expect(config.verify.audience).toBe(\"custom\");\n  });\n});\n"]}

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

@@ -0,0 +1,2 @@
+/** Normalises a bare host to an https issuer URL and strips a trailing slash. */
+export declare function toIssuerUrl(domain: string): string;

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

@@ -0,0 +1,6 @@
+/** Normalises a bare host to an https issuer URL and strips a trailing slash. */
+export function toIssuerUrl(domain) {
+    const withScheme = /^https?:\/\//.test(domain) ? domain : `https://${domain}`;
+    return withScheme.replace(/\/$/, "");
+}
+//# sourceMappingURL=shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/shared.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,EAAE,CAAC;IAC9E,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC","sourcesContent":["/** Normalises a bare host to an https issuer URL and strips a trailing slash. */\nexport function toIssuerUrl(domain: string): string {\n  const withScheme = /^https?:\\/\\//.test(domain) ? domain : `https://${domain}`;\n  return withScheme.replace(/\\/$/, \"\");\n}\n"]}

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

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { toIssuerUrl } from "./shared.js";
+describe("toIssuerUrl", () => {
+    it("adds https to a bare host, preserves an explicit scheme, strips a trailing slash", () => {
+        expect(toIssuerUrl("acme.authkit.app")).toBe("https://acme.authkit.app");
+        expect(toIssuerUrl("https://acme.authkit.app/")).toBe("https://acme.authkit.app");
+        expect(toIssuerUrl("http://localhost:3000")).toBe("http://localhost:3000");
+    });
+});
+//# sourceMappingURL=shared.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/shared.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,kFAAkF,EAAE,GAAG,EAAE;QAC1F,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACzE,MAAM,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,IAAI,CACnD,0BAA0B,CAC3B,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { toIssuerUrl } from \"./shared.js\";\n\ndescribe(\"toIssuerUrl\", () => {\n  it(\"adds https to a bare host, preserves an explicit scheme, strips a trailing slash\", () => {\n    expect(toIssuerUrl(\"acme.authkit.app\")).toBe(\"https://acme.authkit.app\");\n    expect(toIssuerUrl(\"https://acme.authkit.app/\")).toBe(\n      \"https://acme.authkit.app\",\n    );\n    expect(toIssuerUrl(\"http://localhost:3000\")).toBe(\"http://localhost:3000\");\n  });\n});\n"]}

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

@@ -0,0 +1,12 @@
+import type { OAuthConfig } from "../index.js";
+import { type CustomProviderOptions } from "./custom.js";
+/**
+ * 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: {
+    domain: string;
+    audience: string;
+} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig>;

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

@@ -0,0 +1,13 @@
+import { customProvider } from "./custom.js";
+import { toIssuerUrl } from "./shared.js";
+/**
+ * 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 function stytchProvider(opts) {
+    const { domain, ...rest } = opts;
+    return customProvider({ issuer: toIssuerUrl(domain), ...rest });
+}
+//# sourceMappingURL=stytch.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,11 @@
+import type { OAuthConfig } from "../index.js";
+import { type CustomProviderOptions } from "./custom.js";
+/**
+ * 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: {
+    domain: string;
+    audience: string;
+} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig>;

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

@@ -0,0 +1,12 @@
+import { customProvider } from "./custom.js";
+import { toIssuerUrl } from "./shared.js";
+/**
+ * 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 function workosProvider(opts) {
+    const { domain, ...rest } = opts;
+    return customProvider({ issuer: toIssuerUrl(domain), ...rest });
+}
+//# sourceMappingURL=workos.js.map

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

@@ -0,0 +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"]}

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.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

@@ -0,0 +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, schemesByTool: Map<string, SecurityScheme[] | undefined>): ResourceMetadataUrlResolver;