skybridge 0.0.0-dev.815d058 → 0.0.0-dev.8164d23

package/dist/server/app.js

@@ -0,0 +1,261 @@
+import http from "node:http";
+import { createMcpHandler, } from "@modelcontextprotocol/server";
+import express, {} from "express";
+import { setupOAuth } from "./auth/setup.js";
+import { createApp } from "./express.js";
+import { createMiddlewareEntry } from "./metric.js";
+import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
+import { McpServer, } from "./server.js";
+/**
+ * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`
+ * route) plus a factory that builds the MCP server for each request.
+ *
+ * The factory runs once per request, so tools, resources, prompts and views
+ * are always registered on the instance that serves the request. It also runs
+ * once at construction time, which surfaces registration errors at boot and
+ * gives the OAuth layer the set of per-tool security schemes.
+ *
+ * @typeParam TTools - Accumulated tool registry, inferred from the server the
+ * factory returns. You almost never set this manually.
+ *
+ * @example
+ * ```ts
+ * export const app = new Skybridge(
+ *   { name: "my-app", version: "1.0.0", capabilities: {} },
+ *   (server) =>
+ *     server.registerTool(
+ *       {
+ *         name: "search",
+ *         inputSchema: { query: z.string() },
+ *         view: { component: "search" },
+ *       },
+ *       async ({ query }) => ({ content: `Results for ${query}` }),
+ *     ),
+ * );
+ *
+ * export type AppType = typeof app;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
+export class Skybridge {
+    serverInfo;
+    serverOptions;
+    skybridgeOptions;
+    setup;
+    expressApp;
+    errorMiddleware = [];
+    mcpMiddlewareEntries = [];
+    middlewareLocked = false;
+    monitoringEntry = null;
+    resolveResourceMetadataUrl;
+    cachedFetchHandler;
+    constructor(config, setup) {
+        const { name, title, version, description, icons, websiteUrl, json, oauth, skills, ...serverOptions } = config;
+        this.serverInfo = { name, title, version, description, icons, websiteUrl };
+        this.serverOptions = serverOptions;
+        this.skybridgeOptions = { json, oauth, skills };
+        this.setup = setup;
+        const sample = this.buildServer();
+        this.expressApp = express();
+        this.expressApp.use(express.json(json));
+        if (oauth) {
+            this.resolveResourceMetadataUrl = setupOAuth(this.expressApp, oauth, sample.securitySchemesByTool);
+        }
+    }
+    /**
+     * The underlying Express app. Use this to extend the HTTP server with
+     * custom routes, middleware, or settings — e.g.
+     * `app.express.get("/health", ...)`.
+     *
+     * `express.json()` is pre-applied — tune it via the `json` config field,
+     * e.g. `new Skybridge({ name, version, json: { limit: "10mb" } }, setup)`.
+     * Register your handlers before `run()`; after `run()`, dev-mode middleware,
+     * the `/mcp` route, and the default error handler are appended in that order.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
+     * locally and on self-hosted deployments.
+     */
+    get express() {
+        return this.expressApp;
+    }
+    /**
+     * The app's fetch handler for `/mcp`: a `Request` → `Response` function that
+     * builds a fresh MCP server per request. Memoized, so the same handler is
+     * reused across requests.
+     */
+    get fetchHandler() {
+        this.cachedFetchHandler ??= createMcpHandler(() => this.createServerInstance(), {
+            onerror: (error) => {
+                console.error("Error handling MCP request:", error);
+            },
+        });
+        return this.cachedFetchHandler;
+    }
+    /**
+     * Build a fresh server for one stateless HTTP request, as
+     * `createMcpHandler`'s factory contract requires: the factory runs again so
+     * the SDK's handler closures belong to the instance whose protocol era it
+     * stamps. Sharing one instance's handler maps instead would bind them to an
+     * instance that is never marked, pinning every request to the 2025 codec and
+     * letting concurrent callers overwrite each other's negotiated version.
+     */
+    createServerInstance() {
+        const server = this.buildServer();
+        this.instrumentHandlers(server);
+        return server.server;
+    }
+    /**
+     * Connect a Skybridge app to an MCP transport. Use this when you're
+     * embedding Skybridge in a host that already manages its own transport
+     * (e.g. stdio for desktop apps); for HTTP, prefer {@link Skybridge.run}
+     * which sets the transport up for you. Locks in any middleware registered
+     * via {@link Skybridge.mcpMiddleware} — further calls to that method will
+     * throw afterwards.
+     */
+    async connect(transport) {
+        await this.createServerInstance().connect(transport);
+    }
+    use(pathOrHandler, ...handlers) {
+        // Branching is load-bearing: Express's `app.use` overloads can't be
+        // resolved against a `string | RequestHandler` union, so we narrow.
+        if (typeof pathOrHandler === "string") {
+            this.expressApp.use(pathOrHandler, ...handlers);
+        }
+        else {
+            this.expressApp.use(pathOrHandler, ...handlers);
+        }
+        return this;
+    }
+    useOnError(pathOrHandler, ...handlers) {
+        if (typeof pathOrHandler === "string") {
+            this.errorMiddleware.push({ path: pathOrHandler, handlers });
+        }
+        else {
+            this.errorMiddleware.push({ handlers: [pathOrHandler, ...handlers] });
+        }
+        return this;
+    }
+    mcpMiddleware(filterOrHandler, 
+    // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants
+    maybeHandler) {
+        if (this.middlewareLocked) {
+            throw new Error("Cannot register MCP middleware after run() or connect() has been called");
+        }
+        const handler = maybeHandler;
+        if (typeof filterOrHandler === "function") {
+            this.mcpMiddlewareEntries.push({
+                filter: null,
+                handler: filterOrHandler,
+            });
+        }
+        else if (handler) {
+            this.mcpMiddlewareEntries.push({
+                filter: filterOrHandler,
+                handler,
+            });
+        }
+        else {
+            throw new Error("mcpMiddleware requires a handler function when a filter is provided");
+        }
+        return this;
+    }
+    /**
+     * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
+     * mounts the `/mcp` route, applies any custom Express middleware registered
+     * via {@link Skybridge.use} / {@link Skybridge.useOnError}, and locks in
+     * any MCP middleware registered via {@link Skybridge.mcpMiddleware}.
+     *
+     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
+     * the runtime can bridge incoming requests to the Node HTTP server. On
+     * Vercel (`VERCEL === "1"`), returns the Express app directly so the
+     * serverless function entry can call it as a `(req, res)` handler. On
+     * Node, returns `undefined` once listening.
+     */
+    async run() {
+        this.middlewareLocked = true;
+        if (process.env.VERCEL === "1") {
+            // createApp only reads httpServer inside its dev-only branch
+            // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a
+            // bare object passed to satisfy the required parameter.
+            const httpServer = http.createServer();
+            await createApp({
+                app: this,
+                httpServer,
+                errorMiddleware: this.errorMiddleware,
+            });
+            return this.expressApp;
+        }
+        const httpServer = http.createServer();
+        await createApp({
+            app: this,
+            httpServer,
+            errorMiddleware: this.errorMiddleware,
+        });
+        httpServer.on("request", this.expressApp);
+        const port = parseInt(process.env.__PORT ?? "3000", 10);
+        await new Promise((resolve, reject) => {
+            httpServer.on("error", (error) => {
+                console.error("Failed to start server:", error);
+                reject(error);
+            });
+            httpServer.listen(port, () => {
+                resolve();
+            });
+        });
+        // On workerd, bridge the Node http server to a Workers fetch handler.
+        // The specifier is held in a variable to sidestep tsc's module resolution
+        // (`cloudflare:node` only exists under wrangler/workerd).
+        if (typeof navigator !== "undefined" &&
+            navigator.userAgent === "Cloudflare-Workers") {
+            const cloudflareNode = "cloudflare:node";
+            const { httpServerHandler } = await import(cloudflareNode);
+            return httpServerHandler({ port });
+        }
+        const shutdown = () => {
+            // Drop both handlers so a second signal falls through to Node's default
+            // (force-quit on a second Ctrl+C while drain is hanging).
+            process.off("SIGTERM", shutdown);
+            process.off("SIGINT", shutdown);
+            httpServer.close(() => process.exit(0));
+            // Force exit if connections don't drain in time so the port is still
+            // released promptly (e.g. for nodemon restarts).
+            setTimeout(() => process.exit(0), 3000).unref();
+        };
+        process.on("SIGTERM", shutdown);
+        process.on("SIGINT", shutdown);
+        return undefined;
+    }
+    buildServer() {
+        const server = new McpServer(this.serverInfo, this.serverOptions, this.skybridgeOptions);
+        if (this.resolveResourceMetadataUrl) {
+            server.setResourceMetadataUrlResolver(this.resolveResourceMetadataUrl);
+        }
+        return this.setup(server);
+    }
+    middlewareEntries(server) {
+        if (!this.middlewareLocked) {
+            this.middlewareLocked = true;
+            this.monitoringEntry = createMiddlewareEntry();
+        }
+        return [
+            ...(this.monitoringEntry ? [this.monitoringEntry] : []),
+            ...server.protocolMiddlewareEntries(),
+            ...this.mcpMiddlewareEntries,
+        ];
+    }
+    instrumentHandlers(server) {
+        const entries = this.middlewareEntries(server);
+        const { requestHandlers, notificationHandlers } = getHandlerMaps(server.server);
+        const instrumentMap = (map, isNotification) => {
+            for (const [method, handler] of map) {
+                map.set(method, buildMiddlewareChain(method, isNotification, handler, entries));
+            }
+            const originalSet = map.set.bind(map);
+            map.set = (method, handler) => originalSet(method, buildMiddlewareChain(method, isNotification, handler, entries));
+        };
+        instrumentMap(requestHandlers, false);
+        instrumentMap(notificationHandlers, true);
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/server/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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","sourcesContent":["import http from \"node:http\";\nimport {\n  createMcpHandler,\n  type Implementation,\n  type McpHttpHandler,\n  type Server as SdkServer,\n  type ServerOptions,\n  type ServerResult,\n} from \"@modelcontextprotocol/server\";\nimport express, {\n  type ErrorRequestHandler,\n  type Express,\n  type RequestHandler,\n} from \"express\";\nimport { type ResourceMetadataUrlResolver, setupOAuth } from \"./auth/setup.js\";\nimport type { ExtraClaims } from \"./auth.js\";\nimport { createApp } from \"./express.js\";\nimport { createMiddlewareEntry } from \"./metric.js\";\nimport type {\n  McpExtra,\n  McpExtraFor,\n  McpMethodString,\n  McpMiddlewareEntry,\n  McpMiddlewareFilter,\n  McpMiddlewareFn,\n  McpResultFor,\n  McpTypedMiddlewareFn,\n  McpWildcard,\n} from \"./middleware.js\";\nimport { buildMiddlewareChain, getHandlerMaps } from \"./middleware.js\";\nimport {\n  McpServer,\n  type McpServerTypes,\n  type SkybridgeServerOptions,\n  type ToolDef,\n} from \"./server.js\";\n\ntype ErrorMiddlewareConfig = {\n  path?: string;\n  handlers: ErrorRequestHandler[];\n};\n\n/**\n * Everything a Skybridge app needs in one bag: the MCP implementation info\n * (`name`, `version`, …), the SDK's {@link ServerOptions} (`capabilities`,\n * `instructions`, …), and the Skybridge-specific options (`oauth`, `json`,\n * `skills`).\n */\nexport type SkybridgeConfig<TAuthExtra extends ExtraClaims = ExtraClaims> =\n  Implementation & ServerOptions & SkybridgeServerOptions<TAuthExtra>;\n\n/**\n * The factory that declares an app's MCP surface. Called with a fresh\n * {@link McpServer} for every request, it must **return** the chained server so\n * `typeof app` carries the registered tool types.\n */\nexport type SkybridgeSetup<\n  TTools extends Record<string, ToolDef>,\n  TAuthExtra extends ExtraClaims,\n> = (\n  server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n) => McpServer<TTools, TAuthExtra>;\n\n/**\n * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`\n * route) plus a factory that builds the MCP server for each request.\n *\n * The factory runs once per request, so tools, resources, prompts and views\n * are always registered on the instance that serves the request. It also runs\n * once at construction time, which surfaces registration errors at boot and\n * gives the OAuth layer the set of per-tool security schemes.\n *\n * @typeParam TTools - Accumulated tool registry, inferred from the server the\n * factory returns. You almost never set this manually.\n *\n * @example\n * ```ts\n * export const app = new Skybridge(\n *   { name: \"my-app\", version: \"1.0.0\", capabilities: {} },\n *   (server) =>\n *     server.registerTool(\n *       {\n *         name: \"search\",\n *         inputSchema: { query: z.string() },\n *         view: { component: \"search\" },\n *       },\n *       async ({ query }) => ({ content: `Results for ${query}` }),\n *     ),\n * );\n *\n * export type AppType = typeof app;\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/mcp-server\n */\nexport class Skybridge<\n  TTools extends Record<string, ToolDef> = Record<never, ToolDef>,\n  TAuthExtra extends ExtraClaims = ExtraClaims,\n> {\n  declare readonly $types: McpServerTypes<TTools>;\n  private readonly serverInfo: Implementation;\n  private readonly serverOptions: ServerOptions;\n  private readonly skybridgeOptions: SkybridgeServerOptions<TAuthExtra>;\n  private readonly setup: SkybridgeSetup<TTools, TAuthExtra>;\n  private readonly expressApp: Express;\n  private readonly errorMiddleware: ErrorMiddlewareConfig[] = [];\n  private readonly mcpMiddlewareEntries: McpMiddlewareEntry[] = [];\n  private middlewareLocked = false;\n  private monitoringEntry: McpMiddlewareEntry | null = null;\n  private resolveResourceMetadataUrl?: ResourceMetadataUrlResolver;\n  private cachedFetchHandler?: McpHttpHandler;\n\n  constructor(\n    config: SkybridgeConfig<TAuthExtra>,\n    setup: SkybridgeSetup<TTools, TAuthExtra>,\n  ) {\n    const {\n      name,\n      title,\n      version,\n      description,\n      icons,\n      websiteUrl,\n      json,\n      oauth,\n      skills,\n      ...serverOptions\n    } = config;\n\n    this.serverInfo = { name, title, version, description, icons, websiteUrl };\n    this.serverOptions = serverOptions;\n    this.skybridgeOptions = { json, oauth, skills };\n    this.setup = setup;\n\n    const sample = this.buildServer();\n\n    this.expressApp = express();\n    this.expressApp.use(express.json(json));\n    if (oauth) {\n      this.resolveResourceMetadataUrl = setupOAuth(\n        this.expressApp,\n        oauth,\n        sample.securitySchemesByTool,\n      );\n    }\n  }\n\n  /**\n   * The underlying Express app. Use this to extend the HTTP server with\n   * custom routes, middleware, or settings — e.g.\n   * `app.express.get(\"/health\", ...)`.\n   *\n   * `express.json()` is pre-applied — tune it via the `json` config field,\n   * e.g. `new Skybridge({ name, version, json: { limit: \"10mb\" } }, setup)`.\n   * Register your handlers before `run()`; after `run()`, dev-mode middleware,\n   * the `/mcp` route, and the default error handler are appended in that order.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work\n   * locally and on self-hosted deployments.\n   */\n  get express(): Express {\n    return this.expressApp;\n  }\n\n  /**\n   * The app's fetch handler for `/mcp`: a `Request` → `Response` function that\n   * builds a fresh MCP server per request. Memoized, so the same handler is\n   * reused across requests.\n   */\n  get fetchHandler(): McpHttpHandler {\n    this.cachedFetchHandler ??= createMcpHandler(\n      () => this.createServerInstance(),\n      {\n        onerror: (error) => {\n          console.error(\"Error handling MCP request:\", error);\n        },\n      },\n    );\n    return this.cachedFetchHandler;\n  }\n\n  /**\n   * Build a fresh server for one stateless HTTP request, as\n   * `createMcpHandler`'s factory contract requires: the factory runs again so\n   * the SDK's handler closures belong to the instance whose protocol era it\n   * stamps. Sharing one instance's handler maps instead would bind them to an\n   * instance that is never marked, pinning every request to the 2025 codec and\n   * letting concurrent callers overwrite each other's negotiated version.\n   */\n  createServerInstance(): SdkServer {\n    const server = this.buildServer();\n    this.instrumentHandlers(server);\n    return server.server;\n  }\n\n  /**\n   * Connect a Skybridge app to an MCP transport. Use this when you're\n   * embedding Skybridge in a host that already manages its own transport\n   * (e.g. stdio for desktop apps); for HTTP, prefer {@link Skybridge.run}\n   * which sets the transport up for you. Locks in any middleware registered\n   * via {@link Skybridge.mcpMiddleware} — further calls to that method will\n   * throw afterwards.\n   */\n  async connect(transport: Parameters<SdkServer[\"connect\"]>[0]): Promise<void> {\n    await this.createServerInstance().connect(transport);\n  }\n\n  /**\n   * Register Express middleware on the underlying app. Mirrors `app.use` —\n   * pass handlers directly or a path-prefixed handler list. Register before\n   * {@link Skybridge.run}; ordering matches Express.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work\n   * locally and on self-hosted deployments.\n   */\n  use(...handlers: RequestHandler[]): this;\n  use(path: string, ...handlers: RequestHandler[]): this;\n  use(\n    pathOrHandler: string | RequestHandler,\n    ...handlers: RequestHandler[]\n  ): this {\n    // Branching is load-bearing: Express's `app.use` overloads can't be\n    // resolved against a `string | RequestHandler` union, so we narrow.\n    if (typeof pathOrHandler === \"string\") {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    } else {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    }\n    return this;\n  }\n\n  /**\n   * Register Express error-handling middleware to run after the built-in\n   * `/mcp` route (or your custom route). Use this to log or transform errors\n   * thrown by tool handlers before the default error handler responds.\n   *\n   * @example\n   * ```ts\n   * app.useOnError((err, _req, _res, next) => {\n   *   logger.error(err);\n   *   next(err);\n   * });\n   * ```\n   */\n  useOnError(...handlers: ErrorRequestHandler[]): this;\n  useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;\n  useOnError(\n    pathOrHandler: string | ErrorRequestHandler,\n    ...handlers: ErrorRequestHandler[]\n  ): this {\n    if (typeof pathOrHandler === \"string\") {\n      this.errorMiddleware.push({ path: pathOrHandler, handlers });\n    } else {\n      this.errorMiddleware.push({ handlers: [pathOrHandler, ...handlers] });\n    }\n    return this;\n  }\n\n  /** Register MCP protocol-level middleware (catch-all). */\n  mcpMiddleware(handler: McpMiddlewareFn<TAuthExtra>): this;\n  /** Register MCP protocol-level middleware for all requests (`extra` is `McpExtra`). */\n  mcpMiddleware(\n    filter: \"request\",\n    handler: (\n      request: { method: string; params: Record<string, unknown> },\n      extra: McpExtra<TAuthExtra>,\n      next: () => Promise<ServerResult>,\n    ) => Promise<unknown> | unknown,\n  ): this;\n  /** Register MCP protocol-level middleware for all notifications (`extra` is `undefined`). */\n  mcpMiddleware(\n    filter: \"notification\",\n    handler: (\n      request: { method: string; params: Record<string, unknown> },\n      extra: undefined,\n      next: () => Promise<undefined>,\n    ) => Promise<unknown> | unknown,\n  ): this;\n  /**\n   * Register MCP protocol-level middleware for an exact method.\n   * Narrows `params`, `extra`, and `next()` result based on the method string.\n   */\n  mcpMiddleware<M extends McpMethodString>(\n    filter: M,\n    handler: McpTypedMiddlewareFn<M, TAuthExtra>,\n  ): this;\n  /**\n   * Register MCP protocol-level middleware for a wildcard pattern (e.g. `\"tools/*\"`).\n   * `next()` returns the union of result types for matching methods.\n   */\n  mcpMiddleware<W extends McpWildcard>(\n    filter: W,\n    handler: (\n      request: { method: string; params: Record<string, unknown> },\n      extra: McpExtraFor<W, TAuthExtra>,\n      next: () => Promise<McpResultFor<W>>,\n    ) => Promise<unknown> | unknown,\n  ): this;\n  /**\n   * Register MCP protocol-level middleware with a method filter.\n   * Filter can be an exact method (`\"tools/call\"`), wildcard (`\"tools/*\"`),\n   * category (`\"request\"` | `\"notification\"`), or an array of those.\n   */\n  mcpMiddleware(\n    filter: McpMiddlewareFilter,\n    handler: McpMiddlewareFn<TAuthExtra>,\n  ): this;\n  mcpMiddleware(\n    filterOrHandler: McpMiddlewareFilter | McpMiddlewareFn<TAuthExtra>,\n    // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants\n    maybeHandler?: any,\n  ): this {\n    if (this.middlewareLocked) {\n      throw new Error(\n        \"Cannot register MCP middleware after run() or connect() has been called\",\n      );\n    }\n\n    const handler = maybeHandler as McpMiddlewareFn | undefined;\n\n    if (typeof filterOrHandler === \"function\") {\n      this.mcpMiddlewareEntries.push({\n        filter: null,\n        handler: filterOrHandler as McpMiddlewareFn,\n      });\n    } else if (handler) {\n      this.mcpMiddlewareEntries.push({\n        filter: filterOrHandler,\n        handler,\n      });\n    } else {\n      throw new Error(\n        \"mcpMiddleware requires a handler function when a filter is provided\",\n      );\n    }\n\n    return this;\n  }\n\n  /**\n   * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),\n   * mounts the `/mcp` route, applies any custom Express middleware registered\n   * via {@link Skybridge.use} / {@link Skybridge.useOnError}, and locks in\n   * any MCP middleware registered via {@link Skybridge.mcpMiddleware}.\n   *\n   * On Cloudflare Workers / workerd, returns an object exposing `fetch` so\n   * the runtime can bridge incoming requests to the Node HTTP server. On\n   * Vercel (`VERCEL === \"1\"`), returns the Express app directly so the\n   * serverless function entry can call it as a `(req, res)` handler. On\n   * Node, returns `undefined` once listening.\n   */\n  async run(): Promise<\n    { fetch: (...args: unknown[]) => unknown } | Express | undefined\n  > {\n    this.middlewareLocked = true;\n    if (process.env.VERCEL === \"1\") {\n      // createApp only reads httpServer inside its dev-only branch\n      // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a\n      // bare object passed to satisfy the required parameter.\n      const httpServer = http.createServer();\n      await createApp({\n        app: this,\n        httpServer,\n        errorMiddleware: this.errorMiddleware,\n      });\n      return this.expressApp;\n    }\n\n    const httpServer = http.createServer();\n\n    await createApp({\n      app: this,\n      httpServer,\n      errorMiddleware: this.errorMiddleware,\n    });\n\n    httpServer.on(\"request\", this.expressApp);\n    const port = parseInt(process.env.__PORT ?? \"3000\", 10);\n    await new Promise<void>((resolve, reject) => {\n      httpServer.on(\"error\", (error: Error) => {\n        console.error(\"Failed to start server:\", error);\n        reject(error);\n      });\n      httpServer.listen(port, () => {\n        resolve();\n      });\n    });\n\n    // On workerd, bridge the Node http server to a Workers fetch handler.\n    // The specifier is held in a variable to sidestep tsc's module resolution\n    // (`cloudflare:node` only exists under wrangler/workerd).\n    if (\n      typeof navigator !== \"undefined\" &&\n      navigator.userAgent === \"Cloudflare-Workers\"\n    ) {\n      const cloudflareNode = \"cloudflare:node\";\n      const { httpServerHandler } = await import(cloudflareNode);\n      return httpServerHandler({ port });\n    }\n\n    const shutdown = () => {\n      // Drop both handlers so a second signal falls through to Node's default\n      // (force-quit on a second Ctrl+C while drain is hanging).\n      process.off(\"SIGTERM\", shutdown);\n      process.off(\"SIGINT\", shutdown);\n      httpServer.close(() => process.exit(0));\n      // Force exit if connections don't drain in time so the port is still\n      // released promptly (e.g. for nodemon restarts).\n      setTimeout(() => process.exit(0), 3000).unref();\n    };\n    process.on(\"SIGTERM\", shutdown);\n    process.on(\"SIGINT\", shutdown);\n    return undefined;\n  }\n\n  private buildServer(): McpServer<TTools, TAuthExtra> {\n    const server = new McpServer<Record<never, ToolDef>, TAuthExtra>(\n      this.serverInfo,\n      this.serverOptions,\n      this.skybridgeOptions,\n    );\n    if (this.resolveResourceMetadataUrl) {\n      server.setResourceMetadataUrlResolver(this.resolveResourceMetadataUrl);\n    }\n    return this.setup(server);\n  }\n\n  private middlewareEntries(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): McpMiddlewareEntry[] {\n    if (!this.middlewareLocked) {\n      this.middlewareLocked = true;\n      this.monitoringEntry = createMiddlewareEntry();\n    }\n    return [\n      ...(this.monitoringEntry ? [this.monitoringEntry] : []),\n      ...server.protocolMiddlewareEntries(),\n      ...this.mcpMiddlewareEntries,\n    ];\n  }\n\n  private instrumentHandlers(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): void {\n    const entries = this.middlewareEntries(server);\n    const { requestHandlers, notificationHandlers } = getHandlerMaps(\n      server.server,\n    );\n\n    const instrumentMap = (\n      map: Map<string, (...args: unknown[]) => Promise<unknown>>,\n      isNotification: boolean,\n    ) => {\n      for (const [method, handler] of map) {\n        map.set(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n      }\n      const originalSet = map.set.bind(map);\n      map.set = (\n        method: string,\n        handler: (...args: unknown[]) => Promise<unknown>,\n      ) =>\n        originalSet(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n    };\n\n    instrumentMap(requestHandlers, false);\n    instrumentMap(notificationHandlers, true);\n  }\n}\n"]}

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

@@ -1,11 +1,33 @@
-import { type OAuthMetadata } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { z } from "zod";
 /**
- * Discovered AS metadata + `jwks_uri` — the SDK's `OAuthMetadata` omits it (its
- * OAuth client never verifies tokens), but we need it to verify token signatures
- * via JWKS, so we re-type the field for typed access.
+ * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's
+ * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but
+ * we need it for JWKS token verification, so we extend the schema to keep it.
  */
-export type DiscoveredMetadata = OAuthMetadata & {
-    jwks_uri?: string;
-};
+declare const DiscoverySchema: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodURL;
+    token_endpoint: z.ZodURL;
+    registration_endpoint: z.ZodOptional<z.ZodURL>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    response_types_supported: z.ZodArray<z.ZodString>;
+    response_modes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    grant_types_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    token_endpoint_auth_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    token_endpoint_auth_signing_alg_values_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    service_documentation: z.ZodOptional<z.ZodURL>;
+    revocation_endpoint: z.ZodOptional<z.ZodURL>;
+    revocation_endpoint_auth_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    revocation_endpoint_auth_signing_alg_values_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    introspection_endpoint: z.ZodOptional<z.ZodString>;
+    introspection_endpoint_auth_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    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>;
 /** Fetches and validates an authorization server's discovery document. */
 export declare function discoverAuthorizationServer(issuer: string): Promise<DiscoveredMetadata>;
+export {};

package/dist/server/auth/discovery.js

@@ -1,4 +1,13 @@
-import { OAuthMetadataSchema, } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { OAuthMetadataSchema } from "@modelcontextprotocol/core";
+import { z } from "zod";
+/**
+ * Discovery doc validated as OAuth AS metadata + `jwks_uri`. The SDK's
+ * `OAuthMetadataSchema` omits `jwks_uri` (its client never verifies tokens), but
+ * we need it for JWKS token verification, so we extend the schema to keep it.
+ */
+const DiscoverySchema = OAuthMetadataSchema.extend({
+    jwks_uri: z.string().optional(),
+});
 const WELL_KNOWN = [
     "/.well-known/openid-configuration",
     "/.well-known/oauth-authorization-server",
@@ -22,22 +31,18 @@ export async function discoverAuthorizationServer(issuer) {
             if (!res.ok) {
                 throw new Error(`HTTP ${res.status}`);
             }
-            const parsed = OAuthMetadataSchema.safeParse(await res.json());
-            if (!parsed.success) {
-                throw new Error(`invalid metadata (${parsed.error.message})`);
-            }
+            const meta = DiscoverySchema.parse(await res.json());
             // RFC 8414 §3.3: issuer must match the fetch origin (slash-insensitive).
-            if (parsed.data.issuer.replace(/\/$/, "") !== base) {
-                throw new Error(`issuer mismatch: ${parsed.data.issuer}`);
+            if (meta.issuer.replace(/\/$/, "") !== base) {
+                throw new Error(`issuer mismatch: ${meta.issuer}`);
             }
-            const metadata = parsed.data;
             // Prefer the document that advertises DCR: some IdPs (e.g. Clerk) serve a
             // valid openid-configuration without `registration_endpoint` yet expose
             // it at oauth-authorization-server. Keep looking past a doc that omits it.
-            if (metadata.registration_endpoint) {
-                return metadata;
+            if (meta.registration_endpoint) {
+                return meta;
             }
-            fallback ??= metadata;
+            fallback ??= meta;
         }
         catch (err) {
             errors.push(`${url}: ${err instanceof Error ? err.message : String(err)}`);

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,EAEL,mBAAmB,GACpB,MAAM,0CAA0C,CAAC;AASlD,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,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;YAChE,CAAC;YACD,yEAAyE;YACzE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;gBACnD,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAA0B,CAAC;YACnD,0EAA0E;YAC1E,wEAAwE;YACxE,2EAA2E;YAC3E,IAAI,QAAQ,CAAC,qBAAqB,EAAE,CAAC;gBACnC,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,QAAQ,KAAK,QAAQ,CAAC;QACxB,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 {\n  type OAuthMetadata,\n  OAuthMetadataSchema,\n} from \"@modelcontextprotocol/sdk/shared/auth.js\";\n\n/**\n * Discovered AS metadata + `jwks_uri` — the SDK's `OAuthMetadata` omits it (its\n * OAuth client never verifies tokens), but we need it to verify token signatures\n * via JWKS, so we re-type the field for typed access.\n */\nexport type DiscoveredMetadata = OAuthMetadata & { jwks_uri?: string };\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 parsed = OAuthMetadataSchema.safeParse(await res.json());\n      if (!parsed.success) {\n        throw new Error(`invalid metadata (${parsed.error.message})`);\n      }\n      // RFC 8414 §3.3: issuer must match the fetch origin (slash-insensitive).\n      if (parsed.data.issuer.replace(/\\/$/, \"\") !== base) {\n        throw new Error(`issuer mismatch: ${parsed.data.issuer}`);\n      }\n      const metadata = parsed.data as DiscoveredMetadata;\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 (metadata.registration_endpoint) {\n        return metadata;\n      }\n      fallback ??= metadata;\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,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/core\";\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"]}

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 `SkybridgeServerOptions.oauth`.
+ *
+ * `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,13 @@ 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>;
 };

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 `SkybridgeServerOptions.oauth`.\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"]}

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

@@ -1,13 +1,40 @@
+import type { ExtraClaims } from "../../auth.js";
 import type { OAuthConfig } from "../index.js";
+import type { RegisteredClaims } from "../verify.js";
 import { type CustomProviderOptions } from "./custom.js";
+/**
+ * Claims 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`) or a custom domain. Requires Dynamic Client
- * Registration enabled on the tenant (`enable_dynamic_client_registration`).
- * `audience` is the registered API Identifier — Auth0 only issues a verifiable
- * JWT (rather than an opaque token) when the request targets that audience.
+ * `acme.us.auth0.com`); `audience` is the API Identifier; `serverUrl` is this
+ * server's public URL. Requires DCR enabled on the tenant.
+ *
+ * Auth0 can't use the client's resource indicator — `audience` must be *in* the
+ * authorize request. So it runs as skybridge-as-AS (`serverUrl`, see
+ * {@link customProvider}) and bakes `?audience=<id>` into the advertised
+ * `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;
-} & Omit<CustomProviderOptions, "issuer" | "audience">): Promise<OAuthConfig>;
+    serverUrl: string;
+} & Omit<CustomProviderOptions, "issuer" | "audience" | "baseUrl" | "serverUrl">): Promise<OAuthConfig<Auth0Claims & TCustom & RegisteredClaims>>;

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

@@ -1,18 +1,31 @@
 import { customProvider } from "./custom.js";
-/** Normalises a bare host to an https issuer URL and strips a trailing slash. */
-function toIssuerUrl(domain) {
-    const withScheme = /^https?:\/\//.test(domain) ? domain : `https://${domain}`;
-    return withScheme.replace(/\/$/, "");
-}
+import { toIssuerUrl } from "./shared.js";
 /**
  * OAuth provider for Auth0. `domain` is the tenant domain (e.g.
- * `acme.us.auth0.com`) or a custom domain. Requires Dynamic Client
- * Registration enabled on the tenant (`enable_dynamic_client_registration`).
- * `audience` is the registered API Identifier — Auth0 only issues a verifiable
- * JWT (rather than an opaque token) when the request targets that audience.
+ * `acme.us.auth0.com`); `audience` is the API Identifier; `serverUrl` is this
+ * server's public URL. Requires DCR enabled on the tenant.
+ *
+ * Auth0 can't use the client's resource indicator — `audience` must be *in* the
+ * authorize request. So it runs as skybridge-as-AS (`serverUrl`, see
+ * {@link customProvider}) and bakes `?audience=<id>` into the advertised
+ * `authorization_endpoint`. The token's `aud` is the API; `verify.issuer` stays
+ * Auth0 (the token's real `iss`).
  */
-export function auth0Provider(opts) {
-    const { domain, ...rest } = opts;
-    return customProvider({ issuer: toIssuerUrl(domain), ...rest });
+export async function auth0Provider(opts) {
+    const { domain, audience, ...rest } = opts;
+    const config = await 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,
+        },
+    };
 }
 //# sourceMappingURL=auth0.js.map

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;AAEzE,iFAAiF;AACjF,SAAS,WAAW,CAAC,MAAc;IACjC,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;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,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\";\n\n/** Normalises a bare host to an https issuer URL and strips a trailing slash. */\nfunction toIssuerUrl(domain: string): string {\n  const withScheme = /^https?:\\/\\//.test(domain) ? domain : `https://${domain}`;\n  return withScheme.replace(/\\/$/, \"\");\n}\n\n/**\n * OAuth provider for Auth0. `domain` is the tenant domain (e.g.\n * `acme.us.auth0.com`) or a custom domain. Requires Dynamic Client\n * Registration enabled on the tenant (`enable_dynamic_client_registration`).\n * `audience` is the registered API Identifier — Auth0 only issues a verifiable\n * JWT (rather than an opaque token) when the request targets that audience.\n */\nexport function auth0Provider(\n  opts: { domain: string; audience: string } & Omit<\n    CustomProviderOptions,\n    \"issuer\" | \"audience\"\n  >,\n): Promise<OAuthConfig> {\n  const { domain, ...rest } = opts;\n  return customProvider({ issuer: toIssuerUrl(domain), ...rest });\n}\n"]}
+{"version":3,"file":"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,CAAC,KAAK,UAAU,aAAa,CAGjC,IAGC;IAED,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,cAAc,CAAwB;QACzD,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 { ExtraClaims } from \"../../auth.js\";\nimport type { OAuthConfig } from \"../index.js\";\nimport type { RegisteredClaims } from \"../verify.js\";\nimport { type CustomProviderOptions, customProvider } from \"./custom.js\";\nimport { toIssuerUrl } from \"./shared.js\";\n\n/**\n * Claims 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 async 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): Promise<OAuthConfig<Auth0Claims & TCustom & RegisteredClaims>> {\n  const { domain, audience, ...rest } = opts;\n  const config = await customProvider<Auth0Claims & TCustom>({\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"]}