skybridge 0.0.0-dev.d2cb8f6 → 0.0.0-dev.d33e6f5

package/dist/server/app.test.js

@@ -0,0 +1,178 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { describe, expect, it } from "vitest";
+import { Skybridge } from "./app.js";
+const oauthConfig = {
+    oauthMetadata: {
+        issuer: "https://issuer.example.com",
+        authorization_endpoint: "https://issuer.example.com/authorize",
+        token_endpoint: "https://issuer.example.com/token",
+        response_types_supported: ["code"],
+    },
+    verifier: {
+        verifyAccessToken: async () => ({
+            token: "t",
+            clientId: "c",
+            scopes: [],
+            extra: {},
+        }),
+    },
+};
+describe("Skybridge setup and handler", () => {
+    it("resolves setup once and passes the context to the per-request handler", async () => {
+        let loads = 0;
+        const app = new Skybridge({
+            name: "test",
+            version: "1.0.0",
+            setup: async () => {
+                loads++;
+                return { greeting: await Promise.resolve("hello") };
+            },
+            handler: (server, { greeting }) => server.registerTool({ name: "greet", description: "greet" }, async () => ({ content: [{ type: "text", text: greeting }] })),
+        });
+        expect(loads).toBe(0);
+        const call = async () => {
+            const client = new Client({ name: "client", version: "1.0.0" });
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+            await app.connect(serverTransport);
+            await client.connect(clientTransport);
+            const result = await client.callTool({ name: "greet" });
+            await client.close();
+            return result;
+        };
+        expect(await call()).toMatchObject({
+            content: [{ type: "text", text: "hello" }],
+        });
+        expect(await call()).toMatchObject({
+            content: [{ type: "text", text: "hello" }],
+        });
+        expect(loads).toBe(1);
+    });
+    it("retries setup after a failed first resolution", async () => {
+        let attempts = 0;
+        const app = new Skybridge({
+            name: "test",
+            version: "1.0.0",
+            setup: async () => {
+                attempts++;
+                if (attempts === 1) {
+                    throw new Error("transient");
+                }
+            },
+            handler: (server) => server,
+        });
+        const [, first] = InMemoryTransport.createLinkedPair();
+        await expect(app.connect(first)).rejects.toThrow("transient");
+        const [, second] = InMemoryTransport.createLinkedPair();
+        await expect(app.connect(second)).resolves.toBeUndefined();
+        expect(attempts).toBe(2);
+    });
+    it("rejects a handler that returns a promise", async () => {
+        const app = new Skybridge({
+            name: "test",
+            version: "1.0.0",
+            // @ts-expect-error the handler runs per request and must stay synchronous
+            handler: async (server) => server,
+        });
+        const [, serverTransport] = InMemoryTransport.createLinkedPair();
+        await expect(app.connect(serverTransport)).rejects.toThrow(/must be synchronous/);
+    });
+    it("resolves an oauth function with the setup config before wiring the routes", async () => {
+        let seen;
+        const app = new Skybridge({
+            name: "test",
+            version: "1.0.0",
+            setup: () => ({ issuer: "https://issuer.example.com" }),
+            oauth: (config) => {
+                seen = config;
+                return oauthConfig;
+            },
+            handler: (server) => server,
+        });
+        expect(seen).toBeUndefined();
+        const [, serverTransport] = InMemoryTransport.createLinkedPair();
+        await app.connect(serverTransport);
+        expect(seen).toEqual({ issuer: "https://issuer.example.com" });
+    });
+});
+it("registers outer middleware on the app while preserving its setup lifecycle", async () => {
+    let loads = 0;
+    const events = [];
+    const app = new Skybridge({
+        name: "outer-middleware",
+        version: "1",
+        setup: () => ++loads,
+        handler: (server) => server
+            .registerTool({ name: "echo" }, () => ({ content: "live" }))
+            .mcpMiddleware("tools/call", async (_request, _extra, next) => {
+            events.push("app:before");
+            const result = await next();
+            events.push("app:after");
+            return result;
+        }),
+    });
+    const configured = app
+        .withMcpMiddleware({
+        filter: "tools/call",
+        handler: async (_request, _extra, next) => {
+            events.push("outer:before");
+            const result = await next();
+            events.push("outer:after");
+            return result;
+        },
+    })
+        .withMcpMiddleware({
+        filter: "tools/list",
+        handler: (_request, _extra, next) => {
+            events.push("list");
+            return next();
+        },
+    });
+    const [outer, ordinary, conversation] = await Promise.all([
+        configured.createServerInstance(),
+        app.createServerInstance(),
+        app.createServerInstance([
+            {
+                filter: "tools/call",
+                handler: async (_request, _extra, next) => {
+                    events.push("conversation:before");
+                    const result = await next();
+                    events.push("conversation:after");
+                    return result;
+                },
+            },
+        ]),
+    ]);
+    expect(configured).toBe(app);
+    expect(outer).not.toBe(ordinary);
+    expect(loads).toBe(1);
+    for (const [server, expected] of [
+        [
+            conversation,
+            [
+                "conversation:before",
+                "outer:before",
+                "app:before",
+                "app:after",
+                "outer:after",
+                "conversation:after",
+            ],
+        ],
+        [outer, ["outer:before", "app:before", "app:after", "outer:after"]],
+        [ordinary, ["outer:before", "app:before", "app:after", "outer:after"]],
+    ]) {
+        const client = new Client({ name: "test", version: "1" });
+        const [a, b] = InMemoryTransport.createLinkedPair();
+        try {
+            await server.connect(b);
+            await client.connect(a);
+            events.length = 0;
+            await client.callTool({ name: "echo" });
+            expect(events).toEqual(expected);
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    }
+});
+//# sourceMappingURL=app.test.js.map

package/dist/server/app.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.test.js","sourceRoot":"","sources":["../../src/server/app.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { Client, InMemoryTransport } from \"@modelcontextprotocol/client\";\nimport { describe, expect, it } from \"vitest\";\nimport { Skybridge } from \"./app.js\";\n\nconst oauthConfig = {\n  oauthMetadata: {\n    issuer: \"https://issuer.example.com\",\n    authorization_endpoint: \"https://issuer.example.com/authorize\",\n    token_endpoint: \"https://issuer.example.com/token\",\n    response_types_supported: [\"code\"],\n  },\n  verifier: {\n    verifyAccessToken: async () => ({\n      token: \"t\",\n      clientId: \"c\",\n      scopes: [],\n      extra: {},\n    }),\n  },\n};\n\ndescribe(\"Skybridge setup and handler\", () => {\n  it(\"resolves setup once and passes the context to the per-request handler\", async () => {\n    let loads = 0;\n    const app = new Skybridge({\n      name: \"test\",\n      version: \"1.0.0\",\n      setup: async () => {\n        loads++;\n        return { greeting: await Promise.resolve(\"hello\") };\n      },\n      handler: (server, { greeting }) =>\n        server.registerTool(\n          { name: \"greet\", description: \"greet\" },\n          async () => ({ content: [{ type: \"text\", text: greeting }] }),\n        ),\n    });\n\n    expect(loads).toBe(0);\n\n    const call = async () => {\n      const client = new Client({ name: \"client\", version: \"1.0.0\" });\n      const [clientTransport, serverTransport] =\n        InMemoryTransport.createLinkedPair();\n      await app.connect(serverTransport);\n      await client.connect(clientTransport);\n      const result = await client.callTool({ name: \"greet\" });\n      await client.close();\n      return result;\n    };\n\n    expect(await call()).toMatchObject({\n      content: [{ type: \"text\", text: \"hello\" }],\n    });\n    expect(await call()).toMatchObject({\n      content: [{ type: \"text\", text: \"hello\" }],\n    });\n    expect(loads).toBe(1);\n  });\n\n  it(\"retries setup after a failed first resolution\", async () => {\n    let attempts = 0;\n    const app = new Skybridge({\n      name: \"test\",\n      version: \"1.0.0\",\n      setup: async () => {\n        attempts++;\n        if (attempts === 1) {\n          throw new Error(\"transient\");\n        }\n      },\n      handler: (server) => server,\n    });\n\n    const [, first] = InMemoryTransport.createLinkedPair();\n    await expect(app.connect(first)).rejects.toThrow(\"transient\");\n\n    const [, second] = InMemoryTransport.createLinkedPair();\n    await expect(app.connect(second)).resolves.toBeUndefined();\n    expect(attempts).toBe(2);\n  });\n\n  it(\"rejects a handler that returns a promise\", async () => {\n    const app = new Skybridge({\n      name: \"test\",\n      version: \"1.0.0\",\n      // @ts-expect-error the handler runs per request and must stay synchronous\n      handler: async (server) => server,\n    });\n    const [, serverTransport] = InMemoryTransport.createLinkedPair();\n    await expect(app.connect(serverTransport)).rejects.toThrow(\n      /must be synchronous/,\n    );\n  });\n\n  it(\"resolves an oauth function with the setup config before wiring the routes\", async () => {\n    let seen: unknown;\n    const app = new Skybridge({\n      name: \"test\",\n      version: \"1.0.0\",\n      setup: () => ({ issuer: \"https://issuer.example.com\" }),\n      oauth: (config) => {\n        seen = config;\n        return oauthConfig;\n      },\n      handler: (server) => server,\n    });\n\n    expect(seen).toBeUndefined();\n    const [, serverTransport] = InMemoryTransport.createLinkedPair();\n    await app.connect(serverTransport);\n    expect(seen).toEqual({ issuer: \"https://issuer.example.com\" });\n  });\n});\n\nit(\"registers outer middleware on the app while preserving its setup lifecycle\", async () => {\n  let loads = 0;\n  const events: string[] = [];\n  const app = new Skybridge({\n    name: \"outer-middleware\",\n    version: \"1\",\n    setup: () => ++loads,\n    handler: (server) =>\n      server\n        .registerTool({ name: \"echo\" }, () => ({ content: \"live\" }))\n        .mcpMiddleware(\"tools/call\", async (_request, _extra, next) => {\n          events.push(\"app:before\");\n          const result = await next();\n          events.push(\"app:after\");\n          return result;\n        }),\n  });\n  const configured = app\n    .withMcpMiddleware({\n      filter: \"tools/call\",\n      handler: async (_request, _extra, next) => {\n        events.push(\"outer:before\");\n        const result = await next();\n        events.push(\"outer:after\");\n        return result;\n      },\n    })\n    .withMcpMiddleware({\n      filter: \"tools/list\",\n      handler: (_request, _extra, next) => {\n        events.push(\"list\");\n        return next();\n      },\n    });\n  const [outer, ordinary, conversation] = await Promise.all([\n    configured.createServerInstance(),\n    app.createServerInstance(),\n    app.createServerInstance([\n      {\n        filter: \"tools/call\",\n        handler: async (_request, _extra, next) => {\n          events.push(\"conversation:before\");\n          const result = await next();\n          events.push(\"conversation:after\");\n          return result;\n        },\n      },\n    ]),\n  ]);\n  expect(configured).toBe(app);\n  expect(outer).not.toBe(ordinary);\n  expect(loads).toBe(1);\n  for (const [server, expected] of [\n    [\n      conversation,\n      [\n        \"conversation:before\",\n        \"outer:before\",\n        \"app:before\",\n        \"app:after\",\n        \"outer:after\",\n        \"conversation:after\",\n      ],\n    ],\n    [outer, [\"outer:before\", \"app:before\", \"app:after\", \"outer:after\"]],\n    [ordinary, [\"outer:before\", \"app:before\", \"app:after\", \"outer:after\"]],\n  ] as const) {\n    const client = new Client({ name: \"test\", version: \"1\" });\n    const [a, b] = InMemoryTransport.createLinkedPair();\n    try {\n      await server.connect(b);\n      await client.connect(a);\n      events.length = 0;\n      await client.callTool({ name: \"echo\" });\n      expect(events).toEqual(expected);\n    } finally {\n      await client.close();\n      await server.close();\n    }\n  }\n});\n"]}

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 /**
  * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's
  * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but
@@ -24,6 +24,7 @@ declare const DiscoverySchema: z.ZodObject<{
     introspection_endpoint_auth_signing_alg_values_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
     code_challenge_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
     client_id_metadata_document_supported: z.ZodOptional<z.ZodBoolean>;
+    authorization_response_iss_parameter_supported: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
     jwks_uri: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type DiscoveredMetadata = z.infer<typeof DiscoverySchema>;

package/dist/server/auth/discovery.js

@@ -1,5 +1,5 @@
-import { OAuthMetadataSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
-import { z } from "zod";
+import { OAuthMetadataSchema } from "@modelcontextprotocol/core";
+import { z } from "zod/v4";
 /**
  * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's
  * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but

package/dist/server/auth/discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/server/auth/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAC/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,eAAe,GAAG,mBAAmB,CAAC,MAAM,CAAC;IACjD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAGH,MAAM,UAAU,GAAG;IACjB,mCAAmC;IACnC,yCAAyC;CAC1C,CAAC;AAEF,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAc;IAEd,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,QAAwC,CAAC;IAE7C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;QAC7B,4EAA4E;QAC5E,yEAAyE;QACzE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,oBAAoB,CAAC;aAClD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACxC,CAAC;YACD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACrD,yEAAyE;YACzE,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACrD,CAAC;YACD,0EAA0E;YAC1E,wEAAwE;YACxE,2EAA2E;YAC3E,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;gBAC/B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,QAAQ,KAAK,IAAI,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CACT,GAAG,GAAG,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC","sourcesContent":["import { OAuthMetadataSchema } from \"@modelcontextprotocol/sdk/shared/auth.js\";\nimport { z } from \"zod\";\n\n/**\n * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's\n * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but\n * we need it for JWKS token verification, so we extend the schema to keep it.\n */\nconst DiscoverySchema = OAuthMetadataSchema.extend({\n  jwks_uri: z.string().optional(),\n});\nexport type DiscoveredMetadata = z.infer<typeof DiscoverySchema>;\n\nconst WELL_KNOWN = [\n  \"/.well-known/openid-configuration\",\n  \"/.well-known/oauth-authorization-server\",\n];\n\nconst DISCOVERY_TIMEOUT_MS = 5000;\n\n/** Fetches and validates an authorization server's discovery document. */\nexport async function discoverAuthorizationServer(\n  issuer: string,\n): Promise<DiscoveredMetadata> {\n  const base = issuer.replace(/\\/$/, \"\");\n  const errors: string[] = [];\n  // First valid doc lacking a registration_endpoint, kept as a fallback so a\n  // genuinely non-DCR IdP still resolves (and is rejected later by the caller).\n  let fallback: DiscoveredMetadata | undefined;\n\n  for (const path of WELL_KNOWN) {\n    const url = `${base}${path}`;\n    // Any failure (network/timeout, non-2xx, non-JSON, invalid metadata, issuer\n    // mismatch) records a per-URL reason and falls through to the next path.\n    try {\n      const res = await fetch(url, {\n        signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),\n      });\n      if (!res.ok) {\n        throw new Error(`HTTP ${res.status}`);\n      }\n      const meta = DiscoverySchema.parse(await res.json());\n      // RFC 8414 §3.3: issuer must match the fetch origin (slash-insensitive).\n      if (meta.issuer.replace(/\\/$/, \"\") !== base) {\n        throw new Error(`issuer mismatch: ${meta.issuer}`);\n      }\n      // Prefer the document that advertises DCR: some IdPs (e.g. Clerk) serve a\n      // valid openid-configuration without `registration_endpoint` yet expose\n      // it at oauth-authorization-server. Keep looking past a doc that omits it.\n      if (meta.registration_endpoint) {\n        return meta;\n      }\n      fallback ??= meta;\n    } catch (err) {\n      errors.push(\n        `${url}: ${err instanceof Error ? err.message : String(err)}`,\n      );\n    }\n  }\n\n  if (fallback) {\n    return fallback;\n  }\n  throw new Error(`OAuth discovery failed for ${issuer}: ${errors.join(\"; \")}`);\n}\n"]}
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/server/auth/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;GAIG;AACH,MAAM,eAAe,GAAG,mBAAmB,CAAC,MAAM,CAAC;IACjD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAGH,MAAM,UAAU,GAAG;IACjB,mCAAmC;IACnC,yCAAyC;CAC1C,CAAC;AAEF,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAc;IAEd,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,QAAwC,CAAC;IAE7C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;QAC7B,4EAA4E;QAC5E,yEAAyE;QACzE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,oBAAoB,CAAC;aAClD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACxC,CAAC;YACD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACrD,yEAAyE;YACzE,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACrD,CAAC;YACD,0EAA0E;YAC1E,wEAAwE;YACxE,2EAA2E;YAC3E,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;gBAC/B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,QAAQ,KAAK,IAAI,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CACT,GAAG,GAAG,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC","sourcesContent":["import { OAuthMetadataSchema } from \"@modelcontextprotocol/core\";\nimport { z } from \"zod/v4\";\n\n/**\n * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's\n * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but\n * we need it for JWKS token verification, so we extend the schema to keep it.\n */\nconst DiscoverySchema = OAuthMetadataSchema.extend({\n  jwks_uri: z.string().optional(),\n});\nexport type DiscoveredMetadata = z.infer<typeof DiscoverySchema>;\n\nconst WELL_KNOWN = [\n  \"/.well-known/openid-configuration\",\n  \"/.well-known/oauth-authorization-server\",\n];\n\nconst DISCOVERY_TIMEOUT_MS = 5000;\n\n/** Fetches and validates an authorization server's discovery document. */\nexport async function discoverAuthorizationServer(\n  issuer: string,\n): Promise<DiscoveredMetadata> {\n  const base = issuer.replace(/\\/$/, \"\");\n  const errors: string[] = [];\n  // First valid doc lacking a registration_endpoint, kept as a fallback so a\n  // genuinely non-DCR IdP still resolves (and is rejected later by the caller).\n  let fallback: DiscoveredMetadata | undefined;\n\n  for (const path of WELL_KNOWN) {\n    const url = `${base}${path}`;\n    // Any failure (network/timeout, non-2xx, non-JSON, invalid metadata, issuer\n    // mismatch) records a per-URL reason and falls through to the next path.\n    try {\n      const res = await fetch(url, {\n        signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),\n      });\n      if (!res.ok) {\n        throw new Error(`HTTP ${res.status}`);\n      }\n      const meta = DiscoverySchema.parse(await res.json());\n      // RFC 8414 §3.3: issuer must match the fetch origin (slash-insensitive).\n      if (meta.issuer.replace(/\\/$/, \"\") !== base) {\n        throw new Error(`issuer mismatch: ${meta.issuer}`);\n      }\n      // Prefer the document that advertises DCR: some IdPs (e.g. Clerk) serve a\n      // valid openid-configuration without `registration_endpoint` yet expose\n      // it at oauth-authorization-server. Keep looking past a doc that omits it.\n      if (meta.registration_endpoint) {\n        return meta;\n      }\n      fallback ??= meta;\n    } catch (err) {\n      errors.push(\n        `${url}: ${err instanceof Error ? err.message : String(err)}`,\n      );\n    }\n  }\n\n  if (fallback) {\n    return fallback;\n  }\n  throw new Error(`OAuth discovery failed for ${issuer}: ${errors.join(\"; \")}`);\n}\n"]}

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

@@ -1,7 +1,15 @@
-import type { OAuthMetadata } from "@modelcontextprotocol/sdk/shared/auth.js";
-import type { JwksVerifyConfig } from "./verify.js";
-/** Resource-server OAuth config for `SkybridgeServerOptions.oauth`. */
-export type OAuthConfig = {
+import type { OAuthMetadata } from "@modelcontextprotocol/server";
+import type { ExtraClaims, TokenVerifier } from "../auth.js";
+/**
+ * Resource-server OAuth config for the `oauth` field of `SkybridgeConfig`.
+ *
+ * `TExtra` comes from the `verifier` and flows on to tool handlers and
+ * `mcpMiddleware`, so the claim shape is declared once by whoever checks the
+ * token. The branded providers set it from the claims their IdP documents.
+ *
+ * @typeParam TExtra - Claims the verifier populates in `AuthInfo["extra"]`.
+ */
+export type OAuthConfig<TExtra extends ExtraClaims = ExtraClaims> = {
     /**
      * Public URL of this server; sets `resourceServerUrl` and the
      * `resource_metadata` URL. When omitted, it is inferred per request from
@@ -10,9 +18,31 @@ export type OAuthConfig = {
     baseUrl?: string;
     /** AS metadata served at `/.well-known/oauth-authorization-server`. */
     oauthMetadata: OAuthMetadata;
-    verify: JwksVerifyConfig;
     /** Scopes advertised in protected-resource metadata. */
     scopesSupported?: string[];
     /** Server-wide required-scope floor. */
     requiredScopes?: string[];
+    /**
+     * Checks each bearer token. Build one with `createJwksVerifier` for a
+     * JWT-issuing IdP, or supply your own for opaque tokens.
+     */
+    verifier: TokenVerifier<TExtra>;
+};
+/**
+ * What the branded providers return: a deferred {@link OAuthConfig}. Discovery
+ * runs in `resolve`, so `oauth: auth0Provider(...)` at module scope performs
+ * no network access until `Skybridge.run`. Call `resolve` yourself
+ * (`await customProvider(...).resolve()`) when wiring the middleware by hand.
+ *
+ * This is an object rather than a bare `() => Promise<OAuthConfig>` on
+ * purpose. TypeScript defers, during the first inference pass, any argument
+ * that is a call to a generic function returning a function type. The
+ * providers are generic (`workosProvider<TCustom>`), so a function-shaped
+ * return written inline in `new Skybridge({ oauth: workosProvider(...) })`
+ * would be skipped and `TAuthExtra` would fall back to `ExtraClaims`, losing
+ * the claims typing in tool handlers. A non-function shape is inferred
+ * eagerly.
+ */
+export type OAuthProvider<TExtra extends ExtraClaims = ExtraClaims> = {
+    resolve: () => Promise<OAuthConfig<TExtra>>;
 };

package/dist/server/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/auth/index.ts"],"names":[],"mappings":"","sourcesContent":["import type { OAuthMetadata } from \"@modelcontextprotocol/sdk/shared/auth.js\";\nimport type { JwksVerifyConfig } from \"./verify.js\";\n\n/** Resource-server OAuth config for `SkybridgeServerOptions.oauth`. */\nexport type OAuthConfig = {\n  /**\n   * Public URL of this server; sets `resourceServerUrl` and the\n   * `resource_metadata` URL. When omitted, it is inferred per request from\n   * `x-forwarded-host`/`origin`/`host` headers.\n   */\n  baseUrl?: string;\n  /** AS metadata served at `/.well-known/oauth-authorization-server`. */\n  oauthMetadata: OAuthMetadata;\n  verify: JwksVerifyConfig;\n  /** Scopes advertised in protected-resource metadata. */\n  scopesSupported?: string[];\n  /** Server-wide required-scope floor. */\n  requiredScopes?: string[];\n};\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/auth/index.ts"],"names":[],"mappings":"","sourcesContent":["import type { OAuthMetadata } from \"@modelcontextprotocol/server\";\nimport type { ExtraClaims, TokenVerifier } from \"../auth.js\";\n\n/**\n * Resource-server OAuth config for the `oauth` field of `SkybridgeConfig`.\n *\n * `TExtra` comes from the `verifier` and flows on to tool handlers and\n * `mcpMiddleware`, so the claim shape is declared once by whoever checks the\n * token. The branded providers set it from the claims their IdP documents.\n *\n * @typeParam TExtra - Claims the verifier populates in `AuthInfo[\"extra\"]`.\n */\nexport type OAuthConfig<TExtra extends ExtraClaims = ExtraClaims> = {\n  /**\n   * Public URL of this server; sets `resourceServerUrl` and the\n   * `resource_metadata` URL. When omitted, it is inferred per request from\n   * `x-forwarded-host`/`origin`/`host` headers.\n   */\n  baseUrl?: string;\n  /** AS metadata served at `/.well-known/oauth-authorization-server`. */\n  oauthMetadata: OAuthMetadata;\n  /** Scopes advertised in protected-resource metadata. */\n  scopesSupported?: string[];\n  /** Server-wide required-scope floor. */\n  requiredScopes?: string[];\n  /**\n   * Checks each bearer token. Build one with `createJwksVerifier` for a\n   * JWT-issuing IdP, or supply your own for opaque tokens.\n   */\n  verifier: TokenVerifier<TExtra>;\n};\n\n/**\n * What the branded providers return: a deferred {@link OAuthConfig}. Discovery\n * runs in `resolve`, so `oauth: auth0Provider(...)` at module scope performs\n * no network access until `Skybridge.run`. Call `resolve` yourself\n * (`await customProvider(...).resolve()`) when wiring the middleware by hand.\n *\n * This is an object rather than a bare `() => Promise<OAuthConfig>` on\n * purpose. TypeScript defers, during the first inference pass, any argument\n * that is a call to a generic function returning a function type. The\n * providers are generic (`workosProvider<TCustom>`), so a function-shaped\n * return written inline in `new Skybridge({ oauth: workosProvider(...) })`\n * would be skipped and `TAuthExtra` would fall back to `ExtraClaims`, losing\n * the claims typing in tool handlers. A non-function shape is inferred\n * eagerly.\n */\nexport type OAuthProvider<TExtra extends ExtraClaims = ExtraClaims> = {\n  resolve: () => Promise<OAuthConfig<TExtra>>;\n};\n"]}

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

@@ -1,5 +1,27 @@
-import type { OAuthConfig } from "../index.js";
+import type { ExtraClaims } from "../../auth.js";
+import type { OAuthProvider } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
+/**
+ * Claims an Auth0 access token carries for a custom API audience. Auth0 puts no
+ * user attributes beyond the id in the token, so there is no `email`: call
+ * `/userinfo` for the profile. Custom claims must be namespaced (a bare `email`
+ * key is silently dropped), so add them through the type parameter under their
+ * full URI.
+ *
+ * @see https://auth0.com/docs/secure/tokens/access-tokens
+ * @see https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims
+ */
+export type Auth0Claims = {
+    /** Authorized party: the client id the token was issued to. */
+    azp?: string;
+    /** Only when the API has RBAC and "Add Permissions in the Access Token" on. */
+    permissions?: string[];
+    /** Organization id, when the tenant uses Organizations. */
+    org_id?: string;
+    /** Organization name, when the tenant uses Organizations. */
+    org_name?: string;
+};
 /**
  * OAuth provider for Auth0. `domain` is the tenant domain (e.g.
  * `acme.us.auth0.com`); `audience` is the API Identifier; `serverUrl` is this
@@ -11,8 +33,8 @@ import { type CustomProviderOptions } from "./custom.js";
  * `authorization_endpoint`. The token's `aud` is the API; `verify.issuer` stays
  * Auth0 (the token's real `iss`).
  */
-export declare function auth0Provider(opts: {
+export declare function auth0Provider<TCustom extends ExtraClaims = Record<never, never>>(opts: {
     domain: string;
     audience: string;
     serverUrl: string;
-} & Omit<CustomProviderOptions, "issuer" | "audience" | "baseUrl" | "serverUrl">): Promise<OAuthConfig>;
+} & Omit<CustomProviderOptions, "issuer" | "audience" | "baseUrl" | "serverUrl">): OAuthProvider<Auth0Claims & TCustom & RegisteredClaims>;

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

@@ -11,20 +11,25 @@ import { toIssuerUrl } from "./shared.js";
  * `authorization_endpoint`. The token's `aud` is the API; `verify.issuer` stays
  * Auth0 (the token's real `iss`).
  */
-export async function auth0Provider(opts) {
+export function auth0Provider(opts) {
     const { domain, audience, ...rest } = opts;
-    const config = await customProvider({
+    const provider = customProvider({
         issuer: toIssuerUrl(domain),
         audience,
         ...rest,
     });
-    const authUrl = new URL(config.oauthMetadata.authorization_endpoint);
-    authUrl.searchParams.set("audience", audience);
     return {
-        ...config,
-        oauthMetadata: {
-            ...config.oauthMetadata,
-            authorization_endpoint: authUrl.href,
+        resolve: async () => {
+            const config = await provider.resolve();
+            const authUrl = new URL(config.oauthMetadata.authorization_endpoint);
+            authUrl.searchParams.set("audience", audience);
+            return {
+                ...config,
+                oauthMetadata: {
+                    ...config.oauthMetadata,
+                    authorization_endpoint: authUrl.href,
+                },
+            };
         },
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"auth0.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/auth0.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;QAClC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QAC3B,QAAQ;QACR,GAAG,IAAI;KACR,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACrE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC/C,OAAO;QACL,GAAG,MAAM;QACT,aAAa,EAAE;YACb,GAAG,MAAM,CAAC,aAAa;YACvB,sBAAsB,EAAE,OAAO,CAAC,IAAI;SACrC;KACF,CAAC;AACJ,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 Auth0. `domain` is the tenant domain (e.g.\n * `acme.us.auth0.com`); `audience` is the API Identifier; `serverUrl` is this\n * server's public URL. Requires DCR enabled on the tenant.\n *\n * Auth0 can't use the client's resource indicator — `audience` must be *in* the\n * authorize request. So it runs as skybridge-as-AS (`serverUrl`, see\n * {@link customProvider}) and bakes `?audience=<id>` into the advertised\n * `authorization_endpoint`. The token's `aud` is the API; `verify.issuer` stays\n * Auth0 (the token's real `iss`).\n */\nexport async function auth0Provider(\n  opts: { domain: string; audience: string; serverUrl: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\" | \"baseUrl\" | \"serverUrl\"\n  >,\n): Promise<OAuthConfig> {\n  const { domain, audience, ...rest } = opts;\n  const config = await customProvider({\n    issuer: toIssuerUrl(domain),\n    audience,\n    ...rest,\n  });\n  const authUrl = new URL(config.oauthMetadata.authorization_endpoint);\n  authUrl.searchParams.set(\"audience\", audience);\n  return {\n    ...config,\n    oauthMetadata: {\n      ...config.oauthMetadata,\n      authorization_endpoint: authUrl.href,\n    },\n  };\n}\n"]}
+{"version":3,"file":"auth0.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/auth0.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuB1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAG3B,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,QAAQ,GAAG,cAAc,CAAwB;QACrD,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QAC3B,QAAQ;QACR,GAAG,IAAI;KACR,CAAC,CAAC;IACH,OAAO;QACL,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;YACrE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC/C,OAAO;gBACL,GAAG,MAAM;gBACT,aAAa,EAAE;oBACb,GAAG,MAAM,CAAC,aAAa;oBACvB,sBAAsB,EAAE,OAAO,CAAC,IAAI;iBACrC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthProvider } 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 an Auth0 access token carries for a custom API audience. Auth0 puts no\n * user attributes beyond the id in the token, so there is no `email`: call\n * `/userinfo` for the profile. Custom claims must be namespaced (a bare `email`\n * key is silently dropped), so add them through the type parameter under their\n * full URI.\n *\n * @see https://auth0.com/docs/secure/tokens/access-tokens\n * @see https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims\n */\nexport type Auth0Claims = {\n  /** Authorized party: the client id the token was issued to. */\n  azp?: string;\n  /** Only when the API has RBAC and \"Add Permissions in the Access Token\" on. */\n  permissions?: string[];\n  /** Organization id, when the tenant uses Organizations. */\n  org_id?: string;\n  /** Organization name, when the tenant uses Organizations. */\n  org_name?: string;\n};\n\n/**\n * OAuth provider for Auth0. `domain` is the tenant domain (e.g.\n * `acme.us.auth0.com`); `audience` is the API Identifier; `serverUrl` is this\n * server's public URL. Requires DCR enabled on the tenant.\n *\n * Auth0 can't use the client's resource indicator — `audience` must be *in* the\n * authorize request. So it runs as skybridge-as-AS (`serverUrl`, see\n * {@link customProvider}) and bakes `?audience=<id>` into the advertised\n * `authorization_endpoint`. The token's `aud` is the API; `verify.issuer` stays\n * Auth0 (the token's real `iss`).\n */\nexport function auth0Provider<\n  TCustom extends ExtraClaims = Record<never, never>,\n>(\n  opts: { domain: string; audience: string; serverUrl: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\" | \"baseUrl\" | \"serverUrl\"\n  >,\n): OAuthProvider<Auth0Claims & TCustom & RegisteredClaims> {\n  const { domain, audience, ...rest } = opts;\n  const provider = customProvider<Auth0Claims & TCustom>({\n    issuer: toIssuerUrl(domain),\n    audience,\n    ...rest,\n  });\n  return {\n    resolve: async () => {\n      const config = await provider.resolve();\n      const authUrl = new URL(config.oauthMetadata.authorization_endpoint);\n      authUrl.searchParams.set(\"audience\", audience);\n      return {\n        ...config,\n        oauthMetadata: {\n          ...config.oauthMetadata,\n          authorization_endpoint: authUrl.href,\n        },\n      };\n    },\n  };\n}\n"]}

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

@@ -1,6 +1,8 @@
 // @vitest-environment node
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { auth0Provider } from "./auth0.js";
+import { lastJwksConfig as jwks } from "./verify-spy.js";
+vi.mock("../verify.js", () => import("./verify-spy.js"));
 afterEach(() => vi.restoreAllMocks());
 function doc(issuer) {
     return {
@@ -24,7 +26,7 @@ describe("auth0Provider", () => {
             audience: "https://api.example.com/",
             serverUrl: "https://app.example.com/",
             scopes: ["openid", "profile", "email"],
-        });
+        }).resolve();
         // skybridge is the advertised AS: static issuer = serverUrl (trailing slash stripped).
         expect(config.oauthMetadata.issuer).toBe("https://app.example.com");
         // AS metadata scopes match the advertised set (clients read scopes from here).
@@ -41,8 +43,8 @@ describe("auth0Provider", () => {
         // baseUrl left unset so the PRM resource resolves per request (Alpic-safe).
         expect(config.baseUrl).toBeUndefined();
         // token verification still uses Auth0 as issuer + the API audience.
-        expect(config.verify.issuer).toBe(issuer);
-        expect(config.verify.audience).toBe("https://api.example.com/");
+        expect(jwks().issuer).toBe(issuer);
+        expect(jwks().audience).toBe("https://api.example.com/");
     });
 });
 //# sourceMappingURL=auth0.test.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth0.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/auth0.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,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;AAEtC,SAAS,GAAG,CAAC,MAAc;IACzB,OAAO;QACL,MAAM;QACN,sBAAsB,EAAE,GAAG,MAAM,YAAY;QAC7C,cAAc,EAAE,GAAG,MAAM,cAAc;QACvC,qBAAqB,EAAE,GAAG,MAAM,gBAAgB;QAChD,wBAAwB,EAAE,CAAC,MAAM,CAAC;QAClC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC;QAChD,QAAQ,EAAE,GAAG,MAAM,wBAAwB;KAC5C,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,2FAA2F,EAAE,KAAK,IAAI,EAAE;QACzG,MAAM,MAAM,GAAG,2BAA2B,CAAC;QAC3C,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE;YACxC,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC;YACjC,MAAM,EAAE,mBAAmB;YAC3B,QAAQ,EAAE,0BAA0B;YACpC,SAAS,EAAE,0BAA0B;YACrC,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC;SACvC,CAAC,CAAC;QAEH,uFAAuF;QACvF,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACpE,+EAA+E;QAC/E,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC;YACpD,QAAQ;YACR,SAAS;YACT,OAAO;SACR,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACvE,mFAAmF;QACnF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,YAAY,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QAC1E,4EAA4E;QAC5E,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,CAAC;QACvC,oEAAoE;QACpE,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,0BAA0B,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["// @vitest-environment node\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { auth0Provider } from \"./auth0.js\";\n\nafterEach(() => vi.restoreAllMocks());\n\nfunction doc(issuer: string) {\n  return {\n    issuer,\n    authorization_endpoint: `${issuer}/authorize`,\n    token_endpoint: `${issuer}/oauth/token`,\n    registration_endpoint: `${issuer}/oidc/register`,\n    response_types_supported: [\"code\"],\n    scopes_supported: [\"openid\", \"profile\", \"email\"],\n    jwks_uri: `${issuer}/.well-known/jwks.json`,\n  };\n}\n\ndescribe(\"auth0Provider\", () => {\n  it(\"advertises skybridge as the AS (static issuer) and bakes audience; verifies against Auth0\", async () => {\n    const issuer = \"https://acme.us.auth0.com\";\n    vi.spyOn(globalThis, \"fetch\").mockResolvedValue(\n      new Response(JSON.stringify(doc(issuer)), {\n        headers: { \"content-type\": \"application/json\" },\n      }),\n    );\n\n    const config = await auth0Provider({\n      domain: \"acme.us.auth0.com\",\n      audience: \"https://api.example.com/\",\n      serverUrl: \"https://app.example.com/\",\n      scopes: [\"openid\", \"profile\", \"email\"],\n    });\n\n    // skybridge is the advertised AS: static issuer = serverUrl (trailing slash stripped).\n    expect(config.oauthMetadata.issuer).toBe(\"https://app.example.com\");\n    // AS metadata scopes match the advertised set (clients read scopes from here).\n    expect(config.oauthMetadata.scopes_supported).toEqual([\n      \"openid\",\n      \"profile\",\n      \"email\",\n    ]);\n    expect(config.scopesSupported).toEqual([\"openid\", \"profile\", \"email\"]);\n    // audience baked into the advertised authorize endpoint (still pointing at Auth0).\n    const url = new URL(config.oauthMetadata.authorization_endpoint);\n    expect(url.origin + url.pathname).toBe(`${issuer}/authorize`);\n    expect(url.searchParams.get(\"audience\")).toBe(\"https://api.example.com/\");\n    // baseUrl left unset so the PRM resource resolves per request (Alpic-safe).\n    expect(config.baseUrl).toBeUndefined();\n    // token verification still uses Auth0 as issuer + the API audience.\n    expect(config.verify.issuer).toBe(issuer);\n    expect(config.verify.audience).toBe(\"https://api.example.com/\");\n  });\n});\n"]}
+{"version":3,"file":"auth0.test.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/auth0.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,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEzD,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEzD,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;AAEtC,SAAS,GAAG,CAAC,MAAc;IACzB,OAAO;QACL,MAAM;QACN,sBAAsB,EAAE,GAAG,MAAM,YAAY;QAC7C,cAAc,EAAE,GAAG,MAAM,cAAc;QACvC,qBAAqB,EAAE,GAAG,MAAM,gBAAgB;QAChD,wBAAwB,EAAE,CAAC,MAAM,CAAC;QAClC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC;QAChD,QAAQ,EAAE,GAAG,MAAM,wBAAwB;KAC5C,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,2FAA2F,EAAE,KAAK,IAAI,EAAE;QACzG,MAAM,MAAM,GAAG,2BAA2B,CAAC;QAC3C,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE;YACxC,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC;YACjC,MAAM,EAAE,mBAAmB;YAC3B,QAAQ,EAAE,0BAA0B;YACpC,SAAS,EAAE,0BAA0B;YACrC,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC;SACvC,CAAC,CAAC,OAAO,EAAE,CAAC;QAEb,uFAAuF;QACvF,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACpE,+EAA+E;QAC/E,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC;YACpD,QAAQ;YACR,SAAS;YACT,OAAO;SACR,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACvE,mFAAmF;QACnF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,YAAY,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QAC1E,4EAA4E;QAC5E,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,CAAC;QACvC,oEAAoE;QACpE,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["// @vitest-environment node\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { auth0Provider } from \"./auth0.js\";\nimport { lastJwksConfig as jwks } from \"./verify-spy.js\";\n\nvi.mock(\"../verify.js\", () => import(\"./verify-spy.js\"));\n\nafterEach(() => vi.restoreAllMocks());\n\nfunction doc(issuer: string) {\n  return {\n    issuer,\n    authorization_endpoint: `${issuer}/authorize`,\n    token_endpoint: `${issuer}/oauth/token`,\n    registration_endpoint: `${issuer}/oidc/register`,\n    response_types_supported: [\"code\"],\n    scopes_supported: [\"openid\", \"profile\", \"email\"],\n    jwks_uri: `${issuer}/.well-known/jwks.json`,\n  };\n}\n\ndescribe(\"auth0Provider\", () => {\n  it(\"advertises skybridge as the AS (static issuer) and bakes audience; verifies against Auth0\", async () => {\n    const issuer = \"https://acme.us.auth0.com\";\n    vi.spyOn(globalThis, \"fetch\").mockResolvedValue(\n      new Response(JSON.stringify(doc(issuer)), {\n        headers: { \"content-type\": \"application/json\" },\n      }),\n    );\n\n    const config = await auth0Provider({\n      domain: \"acme.us.auth0.com\",\n      audience: \"https://api.example.com/\",\n      serverUrl: \"https://app.example.com/\",\n      scopes: [\"openid\", \"profile\", \"email\"],\n    }).resolve();\n\n    // skybridge is the advertised AS: static issuer = serverUrl (trailing slash stripped).\n    expect(config.oauthMetadata.issuer).toBe(\"https://app.example.com\");\n    // AS metadata scopes match the advertised set (clients read scopes from here).\n    expect(config.oauthMetadata.scopes_supported).toEqual([\n      \"openid\",\n      \"profile\",\n      \"email\",\n    ]);\n    expect(config.scopesSupported).toEqual([\"openid\", \"profile\", \"email\"]);\n    // audience baked into the advertised authorize endpoint (still pointing at Auth0).\n    const url = new URL(config.oauthMetadata.authorization_endpoint);\n    expect(url.origin + url.pathname).toBe(`${issuer}/authorize`);\n    expect(url.searchParams.get(\"audience\")).toBe(\"https://api.example.com/\");\n    // baseUrl left unset so the PRM resource resolves per request (Alpic-safe).\n    expect(config.baseUrl).toBeUndefined();\n    // token verification still uses Auth0 as issuer + the API audience.\n    expect(jwks().issuer).toBe(issuer);\n    expect(jwks().audience).toBe(\"https://api.example.com/\");\n  });\n});\n"]}

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

@@ -1,4 +1,6 @@
-import type { OAuthConfig } from "../index.js";
+import type { ExtraClaims } from "../../auth.js";
+import type { OAuthProvider } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
 /** Options accepted by {@link authplaneProvider}. */
 export type AuthplaneProviderOptions = {
@@ -44,4 +46,4 @@ export type AuthplaneProviderOptions = {
  * of the authorization path. Pass `serverUrl` to advertise this server as the
  * authorization server instead (see {@link customProvider}).
  */
-export declare function authplaneProvider(opts: AuthplaneProviderOptions): Promise<OAuthConfig>;
+export declare function authplaneProvider<TCustom extends ExtraClaims = Record<never, never>>(opts: AuthplaneProviderOptions): OAuthProvider<TCustom & RegisteredClaims>;

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

@@ -1 +1 @@
-{"version":3,"file":"authplane.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/authplane.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AAqCzE;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAa,EAAE,MAAc;IACpD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,mCAAmC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,6CAA6C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACnG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,uCAAuC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA8B;IAE9B,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAErD,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAClC,MAAM,cAAc,GAAG,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAE7D,0EAA0E;IAC1E,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,cAAc,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI;YACvF,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,6GAA6G,CAC1J,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC;QACpB,MAAM;QACN,QAAQ,EAAE,QAAQ,IAAI,QAAQ;QAC9B,OAAO,EAAE,QAAQ;QACjB,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { OAuthConfig } from \"../index.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\n\n/** Options accepted by {@link authplaneProvider}. */\nexport type AuthplaneProviderOptions = {\n  /**\n   * The authorization server's issuer identifier (RFC 8414 §2) — your\n   * Authplane deployment, e.g. `https://auth.acme.com` (or\n   * `http://localhost:9000` in local development).\n   */\n  issuer: string;\n  /**\n   * This server's resource identifier (RFC 9728 §1.2): the public URL clients\n   * reach, advertised as the `resource` field of its protected-resource\n   * metadata. Required, unlike the other providers.\n   *\n   * Authplane binds the access token's `aud` to the RFC 8707 `resource`\n   * parameter the client sends, and the client takes that value from the\n   * advertised metadata. Setting it explicitly gives the deployment one fixed\n   * identifier, which is what the audience is checked against.\n   *\n   * Resource identifiers are compared by exact string match, so give it in the\n   * form it will be advertised and register that same string in Authplane. RFC\n   * 8707 §2 asks for the most specific URI available, e.g.\n   * `https://acme.example.com/mcp`.\n   */\n  resource: string;\n  /**\n   * Expected token `aud`. Defaults to `resource`.\n   *\n   * RFC 8707 §2 lets an authorization server use the resource identifier\n   * verbatim as the audience or map it to another value; set this only for a\n   * resource configured in Authplane with such an override, and pass that\n   * value verbatim.\n   */\n  audience?: string;\n} & Omit<CustomProviderOptions, \"issuer\" | \"audience\" | \"baseUrl\">;\n\n/**\n * Rejects anything that cannot serve as an OAuth identifier: RFC 8707 §2\n * requires an absolute URI and forbids a fragment, and the discovery and\n * protected-resource metadata URLs are both built from the scheme and host.\n */\nfunction parseIdentifier(value: string, option: string): URL {\n  let parsed: URL;\n  try {\n    parsed = new URL(value);\n  } catch {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must be an absolute URL, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (parsed.protocol !== \"https:\" && parsed.protocol !== \"http:\") {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must use the http or https scheme, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (!parsed.host) {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must include a host, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (parsed.hash) {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must not include a fragment, got ${JSON.stringify(value)}`,\n    );\n  }\n  return parsed;\n}\n\n/**\n * OAuth provider for Authplane. `issuer` is the authorization server's issuer\n * identifier and `resource` is this server's resource identifier, which also\n * supplies the expected token audience.\n *\n * Dynamic Client Registration is supported natively, so no registration proxy\n * is needed: clients register with Authplane directly and this server stays out\n * of the authorization path. Pass `serverUrl` to advertise this server as the\n * authorization server instead (see {@link customProvider}).\n */\nexport function authplaneProvider(\n  opts: AuthplaneProviderOptions,\n): Promise<OAuthConfig> {\n  const { issuer, resource, audience, ...rest } = opts;\n\n  parseIdentifier(issuer, \"issuer\");\n  const parsedResource = parseIdentifier(resource, \"resource\");\n\n  // The advertised resource is the URL-normalised form of this value. Where\n  // normalisation would change the string — a bare origin gaining a root path,\n  // an uppercase host, an explicit default port — the configured and advertised\n  // identifiers would differ, and the audience check compares them exactly.\n  // Require the advertised form up front so the two always match.\n  if (parsedResource.href !== resource) {\n    throw new Error(\n      `authplaneProvider: \\`resource\\` must be given in the form it will be advertised. ` +\n        `${JSON.stringify(resource)} is advertised as ${JSON.stringify(parsedResource.href)}. ` +\n        `Use ${JSON.stringify(parsedResource.href)}, or a path-qualified URL such as \"https://acme.example.com/mcp\", and register the same value in Authplane.`,\n    );\n  }\n\n  return customProvider({\n    issuer,\n    audience: audience ?? resource,\n    baseUrl: resource,\n    ...rest,\n  });\n}\n"]}
+{"version":3,"file":"authplane.js","sourceRoot":"","sources":["../../../../src/server/auth/providers/authplane.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,cAAc,EAAE,MAAM,aAAa,CAAC;AAqCzE;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAa,EAAE,MAAc;IACpD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,mCAAmC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,6CAA6C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACnG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,uCAAuC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAE/B,IAA8B;IAC9B,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAErD,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAClC,MAAM,cAAc,GAAG,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAE7D,0EAA0E;IAC1E,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,cAAc,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI;YACvF,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,6GAA6G,CAC1J,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAU;QAC7B,MAAM;QACN,QAAQ,EAAE,QAAQ,IAAI,QAAQ;QAC9B,OAAO,EAAE,QAAQ;QACjB,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthProvider } from \"../index.js\";\nimport type { RegisteredClaims } from \"../verify.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\n\n/** Options accepted by {@link authplaneProvider}. */\nexport type AuthplaneProviderOptions = {\n  /**\n   * The authorization server's issuer identifier (RFC 8414 §2) — your\n   * Authplane deployment, e.g. `https://auth.acme.com` (or\n   * `http://localhost:9000` in local development).\n   */\n  issuer: string;\n  /**\n   * This server's resource identifier (RFC 9728 §1.2): the public URL clients\n   * reach, advertised as the `resource` field of its protected-resource\n   * metadata. Required, unlike the other providers.\n   *\n   * Authplane binds the access token's `aud` to the RFC 8707 `resource`\n   * parameter the client sends, and the client takes that value from the\n   * advertised metadata. Setting it explicitly gives the deployment one fixed\n   * identifier, which is what the audience is checked against.\n   *\n   * Resource identifiers are compared by exact string match, so give it in the\n   * form it will be advertised and register that same string in Authplane. RFC\n   * 8707 §2 asks for the most specific URI available, e.g.\n   * `https://acme.example.com/mcp`.\n   */\n  resource: string;\n  /**\n   * Expected token `aud`. Defaults to `resource`.\n   *\n   * RFC 8707 §2 lets an authorization server use the resource identifier\n   * verbatim as the audience or map it to another value; set this only for a\n   * resource configured in Authplane with such an override, and pass that\n   * value verbatim.\n   */\n  audience?: string;\n} & Omit<CustomProviderOptions, \"issuer\" | \"audience\" | \"baseUrl\">;\n\n/**\n * Rejects anything that cannot serve as an OAuth identifier: RFC 8707 §2\n * requires an absolute URI and forbids a fragment, and the discovery and\n * protected-resource metadata URLs are both built from the scheme and host.\n */\nfunction parseIdentifier(value: string, option: string): URL {\n  let parsed: URL;\n  try {\n    parsed = new URL(value);\n  } catch {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must be an absolute URL, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (parsed.protocol !== \"https:\" && parsed.protocol !== \"http:\") {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must use the http or https scheme, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (!parsed.host) {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must include a host, got ${JSON.stringify(value)}`,\n    );\n  }\n  if (parsed.hash) {\n    throw new Error(\n      `authplaneProvider: \\`${option}\\` must not include a fragment, got ${JSON.stringify(value)}`,\n    );\n  }\n  return parsed;\n}\n\n/**\n * OAuth provider for Authplane. `issuer` is the authorization server's issuer\n * identifier and `resource` is this server's resource identifier, which also\n * supplies the expected token audience.\n *\n * Dynamic Client Registration is supported natively, so no registration proxy\n * is needed: clients register with Authplane directly and this server stays out\n * of the authorization path. Pass `serverUrl` to advertise this server as the\n * authorization server instead (see {@link customProvider}).\n */\nexport function authplaneProvider<\n  TCustom extends ExtraClaims = Record<never, never>,\n>(opts: AuthplaneProviderOptions): OAuthProvider<TCustom & RegisteredClaims> {\n  const { issuer, resource, audience, ...rest } = opts;\n\n  parseIdentifier(issuer, \"issuer\");\n  const parsedResource = parseIdentifier(resource, \"resource\");\n\n  // The advertised resource is the URL-normalised form of this value. Where\n  // normalisation would change the string — a bare origin gaining a root path,\n  // an uppercase host, an explicit default port — the configured and advertised\n  // identifiers would differ, and the audience check compares them exactly.\n  // Require the advertised form up front so the two always match.\n  if (parsedResource.href !== resource) {\n    throw new Error(\n      `authplaneProvider: \\`resource\\` must be given in the form it will be advertised. ` +\n        `${JSON.stringify(resource)} is advertised as ${JSON.stringify(parsedResource.href)}. ` +\n        `Use ${JSON.stringify(parsedResource.href)}, or a path-qualified URL such as \"https://acme.example.com/mcp\", and register the same value in Authplane.`,\n    );\n  }\n\n  return customProvider<TCustom>({\n    issuer,\n    audience: audience ?? resource,\n    baseUrl: resource,\n    ...rest,\n  });\n}\n"]}

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

@@ -1,6 +1,8 @@
 // @vitest-environment node
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { authplaneProvider } from "./authplane.js";
+import { lastJwksConfig as jwks } from "./verify-spy.js";
+vi.mock("../verify.js", () => import("./verify-spy.js"));
 afterEach(() => vi.restoreAllMocks());
 const ISSUER = "https://auth.acme.com";
 function discoveryDoc(issuer, scopes) {
@@ -34,10 +36,10 @@ describe("authplaneProvider", () => {
         const config = await authplaneProvider({
             issuer: ISSUER,
             resource: "https://coffee.example.com/mcp",
-        });
-        expect(config.verify.audience).toBe("https://coffee.example.com/mcp");
-        expect(config.verify.issuer).toBe(ISSUER);
-        expect(config.verify.jwksUri).toBe(`${ISSUER}/.well-known/jwks.json`);
+        }).resolve();
+        expect(jwks().audience).toBe("https://coffee.example.com/mcp");
+        expect(jwks().issuer).toBe(ISSUER);
+        expect(jwks().jwksUri).toBe(`${ISSUER}/.well-known/jwks.json`);
         expect(config.baseUrl).toBe("https://coffee.example.com/mcp");
     });
     it.each([
@@ -48,9 +50,12 @@ describe("authplaneProvider", () => {
         "https://coffee.example.com:8443/mcp",
     ])("passes %s through as both resource and audience", async (resource) => {
         mockDiscovery({ [ISSUER]: ["checkout"] });
-        const config = await authplaneProvider({ issuer: ISSUER, resource });
+        const config = await authplaneProvider({
+            issuer: ISSUER,
+            resource,
+        }).resolve();
         expect(config.baseUrl).toBe(resource);
-        expect(config.verify.audience).toBe(resource);
+        expect(jwks().audience).toBe(resource);
     });
     // The metadata router serialises the resource identifier through `URL` before
     // advertising it. Anything that serialisation would rewrite is refused here,
@@ -70,12 +75,12 @@ describe("authplaneProvider", () => {
     });
     it("lets an explicit audience override the default", async () => {
         mockDiscovery({ [ISSUER]: ["checkout"] });
-        const config = await authplaneProvider({
+        await authplaneProvider({
             issuer: ISSUER,
             resource: "https://coffee.example.com/mcp",
             audience: "urn:acme:coffee",
-        });
-        expect(config.verify.audience).toBe("urn:acme:coffee");
+        }).resolve();
+        expect(jwks().audience).toBe("urn:acme:coffee");
     });
     it.each([
         ["coffee.example.com/mcp", /must be an absolute URL/],
@@ -98,21 +103,21 @@ describe("authplaneProvider", () => {
         // Discovery resolves the issuer itself; the provider passes it through
         // rather than rewriting the operator's value.
         mockDiscovery({ [ISSUER]: ["checkout"] });
-        const config = await authplaneProvider({
+        await authplaneProvider({
             issuer: `${ISSUER}/`,
             resource: "https://coffee.example.com/mcp",
-        });
-        expect(config.verify.issuer).toBe(ISSUER);
+        }).resolve();
+        expect(jwks().issuer).toBe(ISSUER);
     });
     it("accepts a local http issuer for development", async () => {
         const local = "http://localhost:9000";
         mockDiscovery({ [local]: ["checkout"] });
-        const config = await authplaneProvider({
+        await authplaneProvider({
             issuer: local,
             resource: "http://localhost:3000/mcp",
-        });
-        expect(config.verify.issuer).toBe(local);
-        expect(config.verify.audience).toBe("http://localhost:3000/mcp");
+        }).resolve();
+        expect(jwks().issuer).toBe(local);
+        expect(jwks().audience).toBe("http://localhost:3000/mcp");
     });
     it("forwards scopes and the required-scope floor", async () => {
         mockDiscovery({ [ISSUER]: ["checkout", "profile"] });
@@ -121,7 +126,7 @@ describe("authplaneProvider", () => {
             resource: "https://coffee.example.com/mcp",
             scopes: ["checkout"],
             requiredScopes: ["checkout"],
-        });
+        }).resolve();
         expect(config.scopesSupported).toEqual(["checkout"]);
         expect(config.requiredScopes).toEqual(["checkout"]);
     });
@@ -130,7 +135,7 @@ describe("authplaneProvider", () => {
         const config = await authplaneProvider({
             issuer: ISSUER,
             resource: "https://coffee.example.com/mcp",
-        });
+        }).resolve();
         expect(config.oauthMetadata.issuer).toBe(ISSUER);
         expect(config.oauthMetadata.registration_endpoint).toBe(`${ISSUER}/register`);
     });