@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/oauth-as-routes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OAuth 2.1 + PKCE + DCR route family (per MCP spec 2025-06-18+).
+ *
+ *   GET  /.well-known/oauth-protected-resource           — RFC 9728 metadata
+ *   GET  <pathPrefix>/:appId/.well-known/oauth-protected-resource
+ *        — per-app metadata (mounted only with `perAppRouting`)
+ *   GET  /.well-known/oauth-authorization-server         — RFC 8414 metadata
+ *   POST /oauth/register                                 — RFC 7591 DCR
+ *   GET  /oauth/authorize                                — consent page
+ *   POST /oauth/authorize                                — consent submit
+ *   POST /oauth/token                                    — token exchange
+ *
+ * The handlers themselves live in `./oauth.ts`; this module owns the
+ * Express mounting only. Mounted when the composer enables OAuth —
+ * without it, pure-bearer clients still work but OAuth-discovery
+ * clients (Claude Desktop, claude.ai, Goose, etc.) bail with
+ * "couldn't reach".
+ */
+import type { AuthAdapter, PairingService } from "@ggui-ai/mcp-server-core";
+import type { Express } from "express";
+import { type OAuthConfig, type OAuthStorage } from "./oauth.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Resolved OAuth config (issuer override, validateResource, …). */
+    readonly oauthConfig: OAuthConfig;
+    /** Client / code / token storage the handlers persist into. */
+    readonly oauthStorage: OAuthStorage;
+    /** Universal MCP endpoint path — the default RFC 9728 resource. */
+    readonly universalMcpPath: string;
+    /**
+     * Per-tenant URL routing shape. When configured, a second
+     * well-known endpoint mounts under the same path prefix the
+     * per-app `/mcp` handler lives on.
+     */
+    readonly perAppRouting?: {
+        readonly paramName: string;
+        readonly pathPrefix?: string;
+    };
+    /** Auth adapter the consent-submit handler resolves bearers against. */
+    readonly auth: AuthAdapter;
+    /**
+     * Late-bound pairing-service reference. The pairing service is
+     * constructed AFTER these routes mount (declaration-order in the
+     * composer), so the consent-submit handler reads through a getter
+     * on every request. Safe because requests only arrive after
+     * `listen()`, which is strictly after composition completes.
+     */
+    readonly getPairingService: () => PairingService | null;
+}
+/**
+ * Mount the OAuth discovery + auth + token endpoints onto the express
+ * app. Also flips `trust proxy` on — nginx-ingress + ALB both
+ * terminate TLS upstream; without trust-proxy the metadata advertises
+ * `http://` instead of `https://` which breaks PKCE (browsers refuse
+ * insecure flows). Returns nothing — the routes self-register.
+ */
+export declare function mountOAuthAuthorizationServerRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=oauth-as-routes.d.ts.map

package/dist/oauth-as-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-as-routes.d.ts","sourceRoot":"","sources":["../src/oauth-as-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAwE5E"}

package/dist/oauth-as-routes.js

@@ -0,0 +1,82 @@
+/**
+ * OAuth 2.1 + PKCE + DCR route family (per MCP spec 2025-06-18+).
+ *
+ *   GET  /.well-known/oauth-protected-resource           — RFC 9728 metadata
+ *   GET  <pathPrefix>/:appId/.well-known/oauth-protected-resource
+ *        — per-app metadata (mounted only with `perAppRouting`)
+ *   GET  /.well-known/oauth-authorization-server         — RFC 8414 metadata
+ *   POST /oauth/register                                 — RFC 7591 DCR
+ *   GET  /oauth/authorize                                — consent page
+ *   POST /oauth/authorize                                — consent submit
+ *   POST /oauth/token                                    — token exchange
+ *
+ * The handlers themselves live in `./oauth.ts`; this module owns the
+ * Express mounting only. Mounted when the composer enables OAuth —
+ * without it, pure-bearer clients still work but OAuth-discovery
+ * clients (Claude Desktop, claude.ai, Goose, etc.) bail with
+ * "couldn't reach".
+ */
+import { handleAuthorizationServerMetadata, handleAuthorizeGet, handleAuthorizePost, handleProtectedResourceMetadata, handleRegister, handleToken, } from "./oauth.js";
+/**
+ * Mount the OAuth discovery + auth + token endpoints onto the express
+ * app. Also flips `trust proxy` on — nginx-ingress + ALB both
+ * terminate TLS upstream; without trust-proxy the metadata advertises
+ * `http://` instead of `https://` which breaks PKCE (browsers refuse
+ * insecure flows). Returns nothing — the routes self-register.
+ */
+export function mountOAuthAuthorizationServerRoutes(opts) {
+    const { app, oauthConfig, oauthStorage, universalMcpPath, perAppRouting, auth, getPairingService, } = opts;
+    // `trust proxy` so req.protocol + req.host honor X-Forwarded-Proto +
+    // X-Forwarded-Host.
+    app.set("trust proxy", true);
+    app.get("/.well-known/oauth-protected-resource", (req, res) => handleProtectedResourceMetadata(req, res, oauthConfig, universalMcpPath));
+    // Per-app protected-resource metadata (RFC 9728 per-resource
+    // discovery). When `perAppRouting` is configured,
+    // mount a second well-known endpoint under the same path prefix
+    // the per-app `/mcp` handler lives on. Each `appId` gets its own
+    // metadata document with `resource: ${issuer}${pathPrefix}/${appId}`
+    // so claude.ai's discovery flow against `mcp.ggui.ai/apps/<appId>`
+    // sees a per-app resource rather than the universal one. The
+    // shared `authorization_servers: [issuer]` lets the auth server
+    // (also us) issue tokens bound to either resource via RFC 8707
+    // resource indicators.
+    if (perAppRouting !== undefined) {
+        const { paramName, pathPrefix = "" } = perAppRouting;
+        // `path-to-regexp` v8 (express@5) removed the `:param(pattern)`
+        // inline-regex route syntax — registering one throws at startup.
+        // Per-app routes now mount with a PLAIN named param; `paramPattern`
+        // is enforced by a single `app.param` validator (registered with
+        // the per-app MCP route in the MCP-endpoint family) that 404s any
+        // value failing a full-anchored match. Express resolves `app.param`
+        // callbacks at dispatch time for any route declaring the param,
+        // regardless of registration order, so this well-known route
+        // inherits the check even though the validator is wired elsewhere.
+        //
+        // `req.params` can't be indexed by the runtime `paramName` under
+        // the v8 param-key inference, so pin the params type to the plain
+        // string dictionary (`ParamsDictionary`) — the legitimate
+        // single-value param shape — so the `paramName` lookup resolves
+        // to `string`.
+        app.get(`${pathPrefix}/:${paramName}/.well-known/oauth-protected-resource`, (req, res) => {
+            const appId = req.params[paramName];
+            if (typeof appId !== "string" || appId.length === 0) {
+                res.status(404).json({ error: "not_found" });
+                return;
+            }
+            handleProtectedResourceMetadata(req, res, oauthConfig, `${pathPrefix}/${appId}`);
+        });
+    }
+    app.get("/.well-known/oauth-authorization-server", (req, res) => handleAuthorizationServerMetadata(req, res, oauthConfig));
+    app.post("/oauth/register", (req, res) => {
+        void handleRegister(req, res, oauthConfig, oauthStorage);
+    });
+    app.get("/oauth/authorize", (req, res) => {
+        void handleAuthorizeGet(req, res, oauthConfig, oauthStorage);
+    });
+    app.post("/oauth/authorize", (req, res) => {
+        void handleAuthorizePost(req, res, oauthConfig, oauthStorage, auth, getPairingService());
+    });
+    app.post("/oauth/token", (req, res) => {
+        void handleToken(req, res, oauthStorage);
+    });
+}

package/dist/oauth-clients-routes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Console OAuth-client management routes (the "Connected Apps"
+ * surface). Phase 1 of the Connected Apps slice — list + revoke, no
+ * manual create yet.
+ *
+ *   GET    /ggui/console/oauth-clients       — list (oldest-first by createdAt)
+ *   DELETE /ggui/console/oauth-clients/:id   — revoke (idempotent)
+ *
+ * Mounted only when both console + OAuth are enabled — there's
+ * nothing to manage if OAuth is off, and the management surface
+ * belongs to the operator-facing console plane (not the public
+ * OAuth metadata endpoints). Same-origin posture: no bearer auth,
+ * matches sibling console routes (`/ggui/console/registry`,
+ * `/ggui/console/blueprints/cached/...`).
+ *
+ * Revoke caveat — see OAuthStorage.deleteClient JSDoc: revoke
+ * deletes the registration but doesn't invalidate in-flight
+ * access tokens (the current paste-key flow has access_token ===
+ * paired bearer).
+ */
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+import type { OAuthStorage } from "./oauth.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** OAuth storage the management surface lists/revokes against. */
+    readonly oauthStorage: OAuthStorage;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /ggui/console/oauth-clients` +
+ * `DELETE /ggui/console/oauth-clients/:clientId` onto the express
+ * app. Returns nothing — the routes self-register.
+ */
+export declare function mountOAuthClientsRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=oauth-clients-routes.d.ts.map

package/dist/oauth-clients-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-clients-routes.d.ts","sourceRoot":"","sources":["../src/oauth-clients-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA+DhE"}

package/dist/oauth-clients-routes.js

@@ -0,0 +1,87 @@
+/**
+ * Console OAuth-client management routes (the "Connected Apps"
+ * surface). Phase 1 of the Connected Apps slice — list + revoke, no
+ * manual create yet.
+ *
+ *   GET    /ggui/console/oauth-clients       — list (oldest-first by createdAt)
+ *   DELETE /ggui/console/oauth-clients/:id   — revoke (idempotent)
+ *
+ * Mounted only when both console + OAuth are enabled — there's
+ * nothing to manage if OAuth is off, and the management surface
+ * belongs to the operator-facing console plane (not the public
+ * OAuth metadata endpoints). Same-origin posture: no bearer auth,
+ * matches sibling console routes (`/ggui/console/registry`,
+ * `/ggui/console/blueprints/cached/...`).
+ *
+ * Revoke caveat — see OAuthStorage.deleteClient JSDoc: revoke
+ * deletes the registration but doesn't invalidate in-flight
+ * access tokens (the current paste-key flow has access_token ===
+ * paired bearer).
+ */
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount `GET /ggui/console/oauth-clients` +
+ * `DELETE /ggui/console/oauth-clients/:clientId` onto the express
+ * app. Returns nothing — the routes self-register.
+ */
+export function mountOAuthClientsRoutes(opts) {
+    const { app, oauthStorage, logger } = opts;
+    app.get("/ggui/console/oauth-clients", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        try {
+            const clients = await oauthStorage.listClients();
+            // Project to a wire shape: explicitly list every field we
+            // intend to expose so an unrelated `ClientRecord` field
+            // addition doesn't accidentally leak through this endpoint.
+            res.json({
+                clients: clients.map((c) => ({
+                    clientId: c.clientId,
+                    clientName: c.clientName ?? null,
+                    redirectUris: c.redirectUris,
+                    createdAt: c.createdAt,
+                })),
+            });
+        }
+        catch (err) {
+            logger.warn("console_oauth_clients_list_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "list_failed",
+                message: err instanceof Error
+                    ? `Client list failed — ${err.message}`
+                    : `Client list failed — ${String(err)}`,
+            });
+        }
+    });
+    app.delete("/ggui/console/oauth-clients/:clientId", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const clientId = req.params["clientId"];
+        if (typeof clientId !== "string" || clientId.length === 0) {
+            res.status(400).json({
+                error: "missing_client_id",
+                message: "clientId required in path segment (e.g. DELETE /ggui/console/oauth-clients/abc123).",
+            });
+            return;
+        }
+        try {
+            await oauthStorage.deleteClient(clientId);
+            // 204 whether the id was present or not — `deleteClient`
+            // is idempotent at the storage layer (matches DELETE
+            // /blueprints/cached/:id semantics).
+            res.status(204).end();
+        }
+        catch (err) {
+            logger.warn("console_oauth_clients_delete_failed", {
+                error: String(err),
+                clientId,
+            });
+            res.status(500).json({
+                error: "delete_failed",
+                message: err instanceof Error
+                    ? `Client delete failed — ${err.message}`
+                    : `Client delete failed — ${String(err)}`,
+            });
+        }
+    });
+}

package/dist/oauth-login-types.d.ts

@@ -27,7 +27,6 @@
  * Provider-subject is the strongest cross-provider primary key the
  * OAuth spec gives us. Future "link account" flows are explicit.
  */
-import type { AuthResult } from '@ggui-ai/mcp-server-core';
 /**
  * The runtime contract every concrete OAuth provider implements.
  *
@@ -138,23 +137,5 @@ export interface OAuthProviderConfigRecord {
      */
     readonly enabled: boolean;
 }
-/**
- * The minimal AuthAdapter call shape OAuth callbacks use to mint a
- * bearer. `source: 'oauth'` is the canonical provenance string —
- * audit hooks branch on this to distinguish OAuth identity from
- * pairing-issued bearers.
- */
-export type OAuthAuthResult = AuthResult & {
-    source: 'oauth';
-};
-/**
- * Compose the canonical user-id namespace for an OAuth identity.
- * `userId = '${providerId}:${providerSubject}'`. Pure helper —
- * exported here so every consumer (routes, storage, audit hooks)
- * computes the same thing.
- */
-export declare function composeOAuthUserId(input: {
-    readonly providerId: string;
-    readonly providerSubject: string;
-}): string;
+export { composeOAuthUserId } from "@ggui-ai/protocol";
 //# sourceMappingURL=oauth-login-types.d.ts.map

package/dist/oauth-login-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-login-types.d.ts","sourceRoot":"","sources":["../src/oauth-login-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC/C;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GAAG,MAAM,CAET"}
+{"version":3,"file":"oauth-login-types.d.ts","sourceRoot":"","sources":["../src/oauth-login-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC/C;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAID,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/oauth-login-types.js

@@ -1,9 +1,32 @@
 /**
- * Compose the canonical user-id namespace for an OAuth identity.
- * `userId = '${providerId}:${providerSubject}'`. Pure helper —
- * exported here so every consumer (routes, storage, audit hooks)
- * computes the same thing.
+ * OAuth login provider seam.
+ *
+ * Locks the contract every OAuth-login consumer composes against:
+ *
+ *   - Provider implementations (`oauth-providers/{google,github}.ts`)
+ *     return one of these per configured provider.
+ *   - Storage (`oauth-providers-store.ts`) serializes config records
+ *     and hydrates concrete providers via the registered factory.
+ *   - Routes (`oauth-login.ts`) iterate the bound providers and call
+ *     `authorizeUrl` / `exchangeCode` per request.
+ *   - Console UI (`AdminOAuthProviders.tsx`) lists `providerId` /
+ *     `displayName` per record so the operator can paste secrets
+ *     into the right slot.
+ *
+ * Identity model: a successful OAuth callback mints a bearer for an
+ * `Identity` of `{ kind: 'user', userId: '${providerId}:${providerSubject}', roles: [] }`.
+ * Email is informational only — providers MAY return it (display in
+ * the operator's audit log + the user's `/settings` page), but the
+ * identity is always provider-namespaced. No email-based account
+ * linking — different providers ⇒ different identities, period.
+ *
+ * **Why no email-based linking?** A user's OAuth-provider email can
+ * change (they switch jobs, providers verify slowly). Linking by
+ * email would let an attacker who briefly controls an email at
+ * provider X impersonate the same user's account at provider Y.
+ * Provider-subject is the strongest cross-provider primary key the
+ * OAuth spec gives us. Future "link account" flows are explicit.
  */
-export function composeOAuthUserId(input) {
-    return `${input.providerId}:${input.providerSubject}`;
-}
+// composeOAuthUserId now lives in @ggui-ai/protocol (shared with the
+// OIDC verify adapter, which can't import upward from mcp-server).
+export { composeOAuthUserId } from "@ggui-ai/protocol";

package/dist/oauth-login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-login.d.ts","sourceRoot":"","sources":["../src/oauth-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAO1D,OAAO,KAAK,EAEV,SAAS,EACT,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAO,MAAM,wBAAwB,wCAAwC,CAAC;AAC9E,eAAO,MAAM,2BAA2B,2CACE,CAAC;AAC3C;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,gCACf,CAAC;AAChC,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAKxD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EACd,aAAa,CAAC,kBAAkB,CAAC,GACjC,CAAC,MAAM,aAAa,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC3F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAwWN"}
+{"version":3,"file":"oauth-login.d.ts","sourceRoot":"","sources":["../src/oauth-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAO1D,OAAO,KAAK,EAEV,SAAS,EACT,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,eAAO,MAAM,wBAAwB,wCAAwC,CAAC;AAC9E,eAAO,MAAM,2BAA2B,2CACE,CAAC;AAC3C;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,gCACf,CAAC;AAChC,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAKxD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EACd,aAAa,CAAC,kBAAkB,CAAC,GACjC,CAAC,MAAM,aAAa,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC3F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAwWN"}

package/dist/oauth-login.js

@@ -1,6 +1,7 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual, } from 'node:crypto';
 import { formatUserSessionCookieHeader } from './user-session-auth.js';
 import { composeOAuthUserId, } from './oauth-login-types.js';
+import { singleParam } from './route-param.js';
 export const DEFAULT_OAUTH_START_PATH = '/ggui/oauth-login/:providerId/start';
 export const DEFAULT_OAUTH_CALLBACK_PATH = '/ggui/oauth-login/:providerId/callback';
 /**
@@ -81,7 +82,7 @@ export function mountOAuthLoginRoutes(app, opts) {
     });
     // --- GET /ggui/oauth-login/:providerId/start ---
     app.get(startPath, async (req, res) => {
-        const providerId = req.params['providerId'];
+        const providerId = singleParam(req.params['providerId']);
         const reqLogger = opts.logger.child({
             route: 'GET ' + startPath,
             providerId: providerId ?? '<missing>',
@@ -131,7 +132,7 @@ export function mountOAuthLoginRoutes(app, opts) {
     });
     // --- GET /ggui/oauth-login/:providerId/callback ---
     app.get(callbackPath, async (req, res) => {
-        const providerId = req.params['providerId'];
+        const providerId = singleParam(req.params['providerId']);
         const reqLogger = opts.logger.child({
             route: 'GET ' + callbackPath,
             providerId: providerId ?? '<missing>',

package/dist/oauth-providers-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-providers-store.d.ts","sourceRoot":"","sources":["../src/oauth-providers-store.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C,MAAM,WAAW,0BAA0B;IACzC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,yBAAyB,CAAC,CAAC,CAAC;IAC1D,qEAAqE;IACrE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IACnE;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACzD,uDAAuD;IACvD,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,mEAAmE;IACnE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAuLD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,mBAAmB,CA+HrB"}
+{"version":3,"file":"oauth-providers-store.d.ts","sourceRoot":"","sources":["../src/oauth-providers-store.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C,MAAM,WAAW,0BAA0B;IACzC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,yBAAyB,CAAC,CAAC,CAAC;IAC1D,qEAAqE;IACrE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IACnE;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACzD,uDAAuD;IACvD,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,mEAAmE;IACnE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAsLD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,mBAAmB,CA+HrB"}

package/dist/oauth-providers-store.js

@@ -15,6 +15,7 @@
 import { promises as fs } from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { isRecord } from '@ggui-ai/protocol';
 const PROVIDER_ID_RE = /^[a-z][a-z0-9-]*$/;
 const ENV_KEY_RE = /^GGUI_OAUTH_([A-Z0-9_]+)_CLIENT_ID$/;
 const FILE_VERSION = '1';
@@ -112,15 +113,14 @@ async function readFileShape(filePath, logger) {
         });
         return { version: FILE_VERSION, providers: [] };
     }
-    if (!parsed || typeof parsed !== 'object') {
+    if (!isRecord(parsed)) {
         logger.warn('oauth_providers_file_corrupt', {
             filePath,
             reason: 'root_not_object',
         });
         return { version: FILE_VERSION, providers: [] };
     }
-    const obj = parsed;
-    if (!Array.isArray(obj.providers)) {
+    if (!Array.isArray(parsed['providers'])) {
         logger.warn('oauth_providers_file_corrupt', {
             filePath,
             reason: 'providers_not_array',
@@ -128,8 +128,8 @@ async function readFileShape(filePath, logger) {
         return { version: FILE_VERSION, providers: [] };
     }
     const providers = [];
-    for (const row of obj.providers) {
-        if (!row || typeof row !== 'object')
+    for (const row of parsed['providers']) {
+        if (!isRecord(row))
             continue;
         const r = row;
         if (typeof r['providerId'] !== 'string' ||

package/dist/oauth.d.ts

@@ -49,8 +49,8 @@
  * ## Storage
  *
  * Auth codes + DCR clients live in-memory ({@link InMemoryOAuthStorage}).
- * For multi-replica deployments (e.g. `mcp.ggui.ai` with 2+ pods),
- * either:
+ * For multi-replica deployments (2+ processes behind one load
+ * balancer), either:
  *   - Use nginx-ingress sticky sessions so the same pod handles both
  *     `/oauth/authorize` and `/oauth/token` (current sandbox posture).
  *   - Plug a Redis-backed {@link OAuthStorage} via the
@@ -64,7 +64,7 @@ import type { Request, Response } from 'express';
 import type { AuthAdapter, PairingService } from '@ggui-ai/mcp-server-core';
 export interface OAuthConfig {
     /**
-     * Public origin of this server (e.g. `https://mcp.ggui.ai`). Used in
+     * Public origin of this server (e.g. `https://mcp.example.com`). Used in
      * discovery metadata, `WWW-Authenticate` headers, and OAuth redirects.
      * Should NOT have a trailing slash. When absent, the server derives
      * it from the request's `Host` header — fine for most deployments,
@@ -80,7 +80,7 @@ export interface OAuthConfig {
     readonly storage?: OAuthStorage;
     /**
      * External consent UI to delegate the user-facing approval step to
-     * (e.g. `https://console.ggui.ai/oauth/consent`). When set,
+     * (e.g. `https://console.example.com/oauth/consent`). When set,
      * `GET /oauth/authorize` returns a 302 to this URL with every OAuth
      * query param forwarded verbatim — the consent UI then constructs an
      * HTML form that POSTs back to `<issuer>/oauth/authorize` with the
@@ -104,8 +104,8 @@ export interface OAuthConfig {
      * MCP endpoint on this deployment, `false` otherwise.
      *
      * For ggui this gates two shapes:
-     *   - Universal: `${issuer}` (cloud bare root) or
-     *     `${issuer}${universalMcpPath}` (OSS `/mcp`).
+     *   - Universal: `${issuer}` (bare-root mount) or
+     *     `${issuer}${universalMcpPath}` (the conventional `/mcp`).
      *   - Per-app:   `${issuer}${perAppRouting.pathPrefix}/<appId>`
      *     where `<appId>` matches `perAppRouting.paramPattern`.
      *
@@ -269,8 +269,9 @@ export declare function buildWwwAuthenticate(issuerUrl: string, resourcePath?: s
  * in our case (we host both the resource AND the auth server).
  *
  * `mcpPath` (default `/mcp`) is the deployment's universal MCP route.
- * Cloud `mcp.ggui.ai` mounts at the bare root `/` so URLs are short
- * (the domain already says "mcp"); OSS keeps the conventional `/mcp`.
+ * A deployment on a dedicated MCP domain may mount at the bare root
+ * `/` so URLs stay short (the domain already says "mcp"); the
+ * conventional default is `/mcp`.
  * The trailing slash is normalized off when the path is `/` so the
  * resource URL is `${issuer}` (no trailing slash) rather than
  * `${issuer}/`.

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/oauth.js

@@ -49,8 +49,8 @@
  * ## Storage
  *
  * Auth codes + DCR clients live in-memory ({@link InMemoryOAuthStorage}).
- * For multi-replica deployments (e.g. `mcp.ggui.ai` with 2+ pods),
- * either:
+ * For multi-replica deployments (2+ processes behind one load
+ * balancer), either:
  *   - Use nginx-ingress sticky sessions so the same pod handles both
  *     `/oauth/authorize` and `/oauth/token` (current sandbox posture).
  *   - Plug a Redis-backed {@link OAuthStorage} via the
@@ -61,7 +61,8 @@
  * registrations; clients re-register transparently on next failure.
  */
 import { createHash, randomBytes } from 'node:crypto';
-import { resolveIdentity, UnauthenticatedError } from './auth.js';
+import { isRecord } from '@ggui-ai/protocol';
+import { resolveIdentityFromHeaders, UnauthenticatedError } from './auth.js';
 export class InMemoryOAuthStorage {
     codes = new Map();
     clients = new Map();
@@ -148,6 +149,27 @@ export function buildWwwAuthenticate(issuerUrl, resourcePath = '') {
 // =============================================================================
 // PKCE
 // =============================================================================
+/**
+ * Narrow an untrusted params source (express `req.query`, parsed
+ * request body) to the string-valued record the OAuth handlers
+ * consume. Express query values can be `string | string[] | ParsedQs
+ * | ParsedQs[]` (duplicate keys yield arrays under both query
+ * parsers) and JSON bodies can carry arbitrary shapes — only single
+ * string values are meaningful OAuth params, so anything else is
+ * DROPPED at this trust boundary. The downstream required-param
+ * validation then rejects the request with a clean 400 instead of
+ * flowing a non-string through string-typed code.
+ */
+function toStringParams(source) {
+    const out = {};
+    if (!isRecord(source))
+        return out;
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value === 'string')
+            out[key] = value;
+    }
+    return out;
+}
 function sha256Base64Url(input) {
     return createHash('sha256').update(input).digest('base64url');
 }
@@ -164,8 +186,9 @@ function verifyPkce(verifier, challenge) {
  * in our case (we host both the resource AND the auth server).
  *
  * `mcpPath` (default `/mcp`) is the deployment's universal MCP route.
- * Cloud `mcp.ggui.ai` mounts at the bare root `/` so URLs are short
- * (the domain already says "mcp"); OSS keeps the conventional `/mcp`.
+ * A deployment on a dedicated MCP domain may mount at the bare root
+ * `/` so URLs stay short (the domain already says "mcp"); the
+ * conventional default is `/mcp`.
  * The trailing slash is normalized off when the path is `/` so the
  * resource URL is `${issuer}` (no trailing slash) rather than
  * `${issuer}/`.
@@ -206,8 +229,8 @@ export function handleAuthorizationServerMetadata(req, res, config) {
  * to do PKCE + paste-key gets registered.
  */
 export async function handleRegister(req, res, config, storage) {
-    const body = (req.body ?? {});
-    const redirectUrisRaw = body.redirect_uris;
+    const body = isRecord(req.body) ? req.body : {};
+    const redirectUrisRaw = body['redirect_uris'];
     if (!Array.isArray(redirectUrisRaw) || redirectUrisRaw.length === 0) {
         res.status(400).json({
             error: 'invalid_redirect_uri',
@@ -224,7 +247,7 @@ export async function handleRegister(req, res, config, storage) {
         return;
     }
     const clientId = `mcp_client_${randomBytes(16).toString('base64url')}`;
-    const clientName = typeof body.client_name === 'string' ? body.client_name : undefined;
+    const clientName = typeof body['client_name'] === 'string' ? body['client_name'] : undefined;
     await storage.putClient({
         clientId,
         redirectUris,
@@ -256,7 +279,7 @@ export async function handleRegister(req, res, config, storage) {
  * with the user's pasted key.
  */
 export async function handleAuthorizeGet(req, res, config, storage) {
-    const params = req.query;
+    const params = toStringParams(req.query);
     const issuer = resolveIssuerUrl(req, config.issuerUrl);
     const v = await validateAuthorizeParams(params, storage, config, issuer);
     if ('error' in v) {
@@ -301,7 +324,7 @@ export async function handleAuthorizeGet(req, res, config, storage) {
  *      OAuth params).
  */
 export async function handleAuthorizePost(req, res, config, storage, auth, pairingService) {
-    const params = (req.body ?? {});
+    const params = toStringParams(req.body);
     const issuer = resolveIssuerUrl(req, config.issuerUrl);
     const validation = await validateAuthorizeParams(params, storage, config, issuer);
     if ('error' in validation) {
@@ -338,15 +361,14 @@ export async function handleAuthorizePost(req, res, config, storage, auth, pairi
         res.status(400).type('html').send(renderAuthorizePage(params, 'Pair code or API key required'));
         return;
     }
-    // Validate the key by running the adapter's auth path. We synthesize a
-    // minimal Request shape — the adapter only reads `headers` for bearer
-    // extraction. Using the real `resolveIdentity()` keeps the validation
-    // semantics byte-identical to /mcp's auth gate.
-    const fakeReq = {
-        headers: { authorization: `Bearer ${apiKey}` },
-    };
+    // Validate the key by running the adapter's auth path. Using the
+    // same `resolveIdentityFromHeaders()` the `/mcp` and `/ws` ingress
+    // points funnel through keeps the validation semantics
+    // byte-identical to /mcp's auth gate — no synthetic Request needed.
     try {
-        await resolveIdentity(auth, fakeReq);
+        await resolveIdentityFromHeaders(auth, {
+            authorization: `Bearer ${apiKey}`,
+        });
     }
     catch (err) {
         if (err instanceof UnauthenticatedError) {
@@ -430,7 +452,7 @@ export async function handleAuthorizePost(req, res, config, storage, auth, pairi
  * 400 status code.
  */
 export async function handleToken(req, res, storage) {
-    const body = (req.body ?? {});
+    const body = toStringParams(req.body);
     if (body['grant_type'] !== 'authorization_code') {
         res.status(400).json({
             error: 'unsupported_grant_type',