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

package/dist/console-config-routes.js

@@ -0,0 +1,91 @@
+/**
+ * Console manifest-read route.
+ *
+ *   GET /ggui/console/config — VSCode-settings-style read of the
+ *   resolved `ggui.json`. Returns the parsed manifest, the raw
+ *   file contents for display, and the introspected v1 JSON Schema
+ *   (which carries field descriptions via the `.describe()` calls
+ *   on `GguiJsonV1`).
+ *
+ * Source resolution: walks up from `process.cwd()` to find the
+ * nearest `ggui.json`. Honest about three states:
+ *   - found + valid → `{source: {found:true, path}, manifest, raw, schema}`
+ *   - found + invalid → `{source: {found:true, path, error: {message}},
+ *     raw, schema}` (no manifest field — the operator inspects the raw
+ *     bytes + sees the validation error so they can fix the file)
+ *   - not found → `{source: {found:false, searchedFrom}, schema}`
+ *     (the schema still ships so operators can browse what would be
+ *     configurable IF a manifest existed)
+ *
+ * Read-only. Form controls on the same payload and a PATCH
+ * endpoint with atomic write + conflict detection layer on top.
+ */
+import { GguiJsonV1 } from "@ggui-ai/project-config";
+import { findGguiJson, safeLoadGguiJson } from "@ggui-ai/project-config/node";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount `GET /ggui/console/config` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export function mountConsoleConfigRoutes(opts) {
+    const { app, logger } = opts;
+    app.get("/ggui/console/config", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const searchedFrom = process.cwd();
+        const safeSchema = (() => {
+            try {
+                // `unrepresentable: 'any'` keeps fields backed by `.transform()`
+                // (e.g. `generation.model`, parsed at the schema boundary into
+                // a typed `LlmRoute`) in the JSON Schema as `{}` instead of
+                // throwing. Transforms are runtime-only; the JSON-Schema view
+                // serves the console SPA as documentation, so a permissive
+                // shape is the honest projection.
+                return z.toJSONSchema(GguiJsonV1, { unrepresentable: "any" });
+            }
+            catch (err) {
+                logger.warn("console_config_schema_conversion_failed", {
+                    error: String(err),
+                });
+                return {};
+            }
+        })();
+        const path = findGguiJson(searchedFrom);
+        if (path === null) {
+            res.json({
+                source: { found: false, searchedFrom },
+                schema: safeSchema,
+            });
+            return;
+        }
+        let raw = null;
+        try {
+            raw = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            logger.warn("console_config_read_failed", { path, error: String(err) });
+        }
+        const result = safeLoadGguiJson(path);
+        if (!result.success) {
+            const cause = result.error.cause;
+            const errorMessage = cause instanceof Error ? cause.message : result.error.message;
+            res.json({
+                source: {
+                    found: true,
+                    path,
+                    error: { message: errorMessage },
+                },
+                ...(raw !== null ? { raw } : {}),
+                schema: safeSchema,
+            });
+            return;
+        }
+        res.json({
+            source: { found: true, path },
+            manifest: result.data,
+            ...(raw !== null ? { raw } : {}),
+            schema: safeSchema,
+        });
+    });
+}

package/dist/console-headers.d.ts

@@ -55,7 +55,7 @@
  *     door to inline `<script>` or `<style>` blocks (different CSP
  *     directive). Scoped, not dangerous.
  *   - `connect-src 'self'` — covers both same-origin `fetch()` to
- *     `/ggui/console/render-cookie` and the `new WebSocket('/ws')`
+ *     `/ggui/console/session-cookie` and the `new WebSocket('/ws')`
  *     upgrade. CSP Level 3 treats `'self'` as matching the document's
  *     origin across http/https/ws/wss, which is exactly the scope.
  *   - `img-src 'self' data:` — no images in the minimal viewer today,

package/dist/console-info-routes.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Console server-info route.
+ *
+ *   GET /ggui/console/info — JSON describing this server (name +
+ *   version + mode + pairing block + capabilities + storage). Stable
+ *   shape so the SPA client in `@ggui-ai/console` can fetch once on
+ *   load.
+ *
+ * Pairing block: `enabled` reflects whether the server was composed
+ * with `pairing: true|{...}`. `pending` is the current `activeInit()`
+ * read — null when no code is pending OR when pairing is disabled.
+ * The landing page renders three distinct copy paths against this
+ * shape (disabled / enabled-but-idle / enabled-with-pending) so the
+ * client never has to compose state from multiple optional fields.
+ *
+ * Capabilities block (console status dashboard):
+ *   - `toolCount`: the number of MCP tool handlers this server
+ *     registered. Same value `server.toolCount` exposes and the
+ *     banner prints.
+ *   - `blueprintCount`: operator-scoped blueprint count from the
+ *     wired `uiRegistry.list()` — 0 when no registry is bound.
+ *     Best-effort on read (same contract as `/ggui/console/registry`).
+ *   - `primitiveCount`: sum across `primitiveCatalogs`.
+ *   - `agentWired`: whether the render-channel + mcpApps path is
+ *     live (the server can accept `ggui_render` + live-channel joins).
+ *   - `generation.wired`: whether generation deps were bound — the
+ *     `ggui_render` LLM path is active. Absent = render returns
+ *     `codeReady: false` honest placeholders.
+ *   - `generation.hasCredentials`: actually resolves BYOK credentials
+ *     via the same seam the render handler uses, so the
+ *     operator-facing pill can distinguish three honest states:
+ *     off / needs-key / ready.
+ *
+ * Storage block: 'memory' when the server fell back to the in-memory
+ * default, 'custom' when the operator passed one. Keeps the label
+ * taxonomy narrow — two states the operator can act on (swap to
+ * SQLite, swap to Postgres). Implementation-name leakage (e.g.
+ * "InMemoryGguiSessionStore") would couple the wire to class names
+ * that are not part of the public contract.
+ */
+import type { PairingService } from "@ggui-ai/mcp-server-core";
+import type { GenerationDeps } from "@ggui-ai/mcp-server-handlers/renders";
+import type { DiscoveredPrimitiveCatalog } from "@ggui-ai/project-config/node";
+import type { UiRegistry } from "@ggui-ai/ui-registry";
+import type { Express } from "express";
+import type { ServerInfo } from "./build-mcp.js";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Server identity (name / version / description). */
+    readonly info: ServerInfo;
+    /** Operator mode surfaced so the SPA shows/hides `/devtools`. */
+    readonly mode: "dev" | "prod";
+    /** Whether pairing was enabled at composition. */
+    readonly pairingEnabled: boolean;
+    /** Pairing service (null = pairing disabled / `pending` is null). */
+    readonly pairingService: PairingService | null;
+    /** Registered tool count. */
+    readonly toolCount: number;
+    /** Declared-blueprint registry for the blueprintCount probe. */
+    readonly uiRegistry?: UiRegistry;
+    /** Discovered primitive catalogs for the primitiveCount sum. */
+    readonly primitiveCatalogs?: ReadonlyArray<DiscoveredPrimitiveCatalog>;
+    /** Whether the mcpApps render path is live (`agentWired`). */
+    readonly mcpAppsEnabled: boolean;
+    /** Generation deps — presence drives `wired`; resolveLlm drives the
+     * `hasCredentials` probe. */
+    readonly generation?: GenerationDeps;
+    /** Pre-resolved storage labels (option plumbing in the composer). */
+    readonly storage: {
+        readonly renderStore: "memory" | "custom";
+        readonly vectorStore: "memory" | "custom";
+    };
+    /** Structured logger for best-effort probe warnings. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /ggui/console/info` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export declare function mountConsoleInfoRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-info-routes.d.ts.map

package/dist/console-info-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-info-routes.d.ts","sourceRoot":"","sources":["../src/console-info-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/C,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAAC;IACvE,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;iCAC6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC;QAC1C,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC;KAC3C,CAAC;IACF,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAwG/D"}

package/dist/console-info-routes.js

@@ -0,0 +1,135 @@
+/**
+ * Console server-info route.
+ *
+ *   GET /ggui/console/info — JSON describing this server (name +
+ *   version + mode + pairing block + capabilities + storage). Stable
+ *   shape so the SPA client in `@ggui-ai/console` can fetch once on
+ *   load.
+ *
+ * Pairing block: `enabled` reflects whether the server was composed
+ * with `pairing: true|{...}`. `pending` is the current `activeInit()`
+ * read — null when no code is pending OR when pairing is disabled.
+ * The landing page renders three distinct copy paths against this
+ * shape (disabled / enabled-but-idle / enabled-with-pending) so the
+ * client never has to compose state from multiple optional fields.
+ *
+ * Capabilities block (console status dashboard):
+ *   - `toolCount`: the number of MCP tool handlers this server
+ *     registered. Same value `server.toolCount` exposes and the
+ *     banner prints.
+ *   - `blueprintCount`: operator-scoped blueprint count from the
+ *     wired `uiRegistry.list()` — 0 when no registry is bound.
+ *     Best-effort on read (same contract as `/ggui/console/registry`).
+ *   - `primitiveCount`: sum across `primitiveCatalogs`.
+ *   - `agentWired`: whether the render-channel + mcpApps path is
+ *     live (the server can accept `ggui_render` + live-channel joins).
+ *   - `generation.wired`: whether generation deps were bound — the
+ *     `ggui_render` LLM path is active. Absent = render returns
+ *     `codeReady: false` honest placeholders.
+ *   - `generation.hasCredentials`: actually resolves BYOK credentials
+ *     via the same seam the render handler uses, so the
+ *     operator-facing pill can distinguish three honest states:
+ *     off / needs-key / ready.
+ *
+ * Storage block: 'memory' when the server fell back to the in-memory
+ * default, 'custom' when the operator passed one. Keeps the label
+ * taxonomy narrow — two states the operator can act on (swap to
+ * SQLite, swap to Postgres). Implementation-name leakage (e.g.
+ * "InMemoryGguiSessionStore") would couple the wire to class names
+ * that are not part of the public contract.
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount `GET /ggui/console/info` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export function mountConsoleInfoRoutes(opts) {
+    const { app, info, mode, pairingEnabled, pairingService, toolCount, uiRegistry, primitiveCatalogs, mcpAppsEnabled, generation, storage, logger, } = opts;
+    app.get("/ggui/console/info", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        let pending = null;
+        if (pairingService) {
+            try {
+                pending = await pairingService.activeInit();
+            }
+            catch (err) {
+                // `activeInit` is a read — failure here shouldn't 500 the
+                // landing page. Log + return null; operator sees "no pending
+                // pair code" which matches reality (we couldn't read one).
+                logger.warn("console_active_init_failed", {
+                    error: String(err),
+                });
+                pending = null;
+            }
+        }
+        // Provider/model specifics (`generation: { provider, model }`)
+        // are intentionally NOT surfaced yet — the `UiGenerator` contract
+        // doesn't expose a read-only identity on the handle. Adding that
+        // is a generator-package change; the dashboard card lands on the
+        // simpler `generation.wired` boolean until then.
+        let blueprintCount = 0;
+        if (uiRegistry) {
+            try {
+                const list = await uiRegistry.list();
+                blueprintCount = list.length;
+            }
+            catch (err) {
+                logger.warn("console_info_blueprint_count_failed", {
+                    error: String(err),
+                });
+            }
+        }
+        const primitiveCount = (primitiveCatalogs ?? []).reduce((sum, c) => sum + c.manifest.primitives.length, 0);
+        // Generation probe — `wired` reports dep binding; `hasCredentials`
+        // actually resolves BYOK credentials via the same seam the render
+        // handler uses, so the operator-facing pill can distinguish
+        // three honest states: off / needs-key / ready. The split avoids
+        // a green "wired" pill next to a "text-only" meta misleading
+        // operators when creds are missing.
+        //
+        // Probe is best-effort: resolveLlm failure (filesystem hiccup,
+        // malformed `~/.ggui/credentials.json`) reports
+        // `hasCredentials: false`, matching operator expectation
+        // "whatever is on disk, this won't fire right now." Absence of
+        // creds is a non-error path per the GenerationDeps contract.
+        let generationHasCredentials = false;
+        if (generation) {
+            try {
+                const probeResult = await generation.resolveLlm({
+                    appId: DEFAULT_BUILDER_APP_ID,
+                    requestId: `console-info-probe-${randomUUID()}`,
+                });
+                generationHasCredentials = probeResult !== null;
+            }
+            catch (err) {
+                logger.warn("console_info_credential_probe_failed", {
+                    error: String(err),
+                });
+            }
+        }
+        const capabilities = {
+            toolCount,
+            blueprintCount,
+            primitiveCount,
+            agentWired: mcpAppsEnabled,
+            generation: {
+                wired: generation !== undefined,
+                hasCredentials: generationHasCredentials,
+            },
+        };
+        res.json({
+            server: info.name,
+            version: info.version,
+            ...(info.description !== undefined ? { description: info.description } : {}),
+            mode,
+            pairing: {
+                enabled: pairingEnabled,
+                pending,
+            },
+            capabilities,
+            storage,
+        });
+    });
+}

package/dist/console-keys-routes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Admin-gated keys plane.
+ *
+ *   POST /ggui/console/admin-login    — bearer → cookie exchange.
+ *   GET  /ggui/console/keys           — list pairings + plaintext token.
+ *   POST /ggui/console/keys           — mint a new pairing programmatically.
+ *   DELETE /ggui/console/keys/:id     — revoke a pairing (idempotent).
+ *
+ * Why the gate exists: the keys plane renders plaintext bearer
+ * tokens minted by the pairing service. The persistence file
+ * (`~/.ggui/keys.json` typically) already stores them in plaintext
+ * — single-operator local-host threat model — so showing them in
+ * a same-origin admin page is a UX, not a posture, change. BUT
+ * operators expose `ggui serve` over Cloudflare tunnels for
+ * claude.ai connector use, which removes "URL is unreachable from
+ * the open internet" from the threat model. The admin token gates
+ * the keys plane against random URL discovery.
+ *
+ * Scope discipline: the gate covers `/ggui/console/keys*` +
+ * `/ggui/console/admin-login` ONLY. Other console routes
+ * (registry, renders, cached blueprints, oauth-clients) are not
+ * re-gated here — that's a separate audit slice. Adding a single-
+ * path-prefix middleware avoids re-litigating the whole console
+ * posture in one go.
+ *
+ * Auth shape: `Authorization: Bearer <admin-token>` header OR the
+ * `ggui_console_admin` cookie (HttpOnly, sameSite=Lax, Secure when
+ * the request arrived over TLS). Cookie is minted by
+ * POST /ggui/console/admin-login on a successful token paste.
+ */
+import type { PairingService } from "@ggui-ai/mcp-server-core";
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Resolved admin token gating the plane. */
+    readonly adminToken: string;
+    /** Pairing service the keys CRUD operates on. */
+    readonly pairing: PairingService;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount the admin-login + keys routes onto the express app. Returns
+ * nothing — the routes self-register.
+ */
+export declare function mountConsoleKeysRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-keys-routes.d.ts.map

package/dist/console-keys-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-keys-routes.d.ts","sourceRoot":"","sources":["../src/console-keys-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAW,MAAM,SAAS,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA0L/D"}

package/dist/console-keys-routes.js

@@ -0,0 +1,222 @@
+/**
+ * Admin-gated keys plane.
+ *
+ *   POST /ggui/console/admin-login    — bearer → cookie exchange.
+ *   GET  /ggui/console/keys           — list pairings + plaintext token.
+ *   POST /ggui/console/keys           — mint a new pairing programmatically.
+ *   DELETE /ggui/console/keys/:id     — revoke a pairing (idempotent).
+ *
+ * Why the gate exists: the keys plane renders plaintext bearer
+ * tokens minted by the pairing service. The persistence file
+ * (`~/.ggui/keys.json` typically) already stores them in plaintext
+ * — single-operator local-host threat model — so showing them in
+ * a same-origin admin page is a UX, not a posture, change. BUT
+ * operators expose `ggui serve` over Cloudflare tunnels for
+ * claude.ai connector use, which removes "URL is unreachable from
+ * the open internet" from the threat model. The admin token gates
+ * the keys plane against random URL discovery.
+ *
+ * Scope discipline: the gate covers `/ggui/console/keys*` +
+ * `/ggui/console/admin-login` ONLY. Other console routes
+ * (registry, renders, cached blueprints, oauth-clients) are not
+ * re-gated here — that's a separate audit slice. Adding a single-
+ * path-prefix middleware avoids re-litigating the whole console
+ * posture in one go.
+ *
+ * Auth shape: `Authorization: Bearer <admin-token>` header OR the
+ * `ggui_console_admin` cookie (HttpOnly, sameSite=Lax, Secure when
+ * the request arrived over TLS). Cookie is minted by
+ * POST /ggui/console/admin-login on a successful token paste.
+ */
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+const ADMIN_COOKIE_NAME = "ggui_console_admin";
+/**
+ * Mount the admin-login + keys routes onto the express app. Returns
+ * nothing — the routes self-register.
+ */
+export function mountConsoleKeysRoutes(opts) {
+    const { app, adminToken, pairing, logger } = opts;
+    const requestHasAdminAuth = (req) => {
+        // Header path — `Authorization: Bearer <token>`. Constant-time
+        // compare not needed: this is single-tenant local-host with a
+        // local network attacker model; the token also has 72 bits of
+        // entropy, so a timing-side-channel attack would still need
+        // ~2^36 attempts on average to materialize. Skip the cost.
+        const authHeader = req.headers["authorization"];
+        if (typeof authHeader === "string") {
+            const match = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+            if (match && match[1] === adminToken)
+                return true;
+        }
+        // Cookie path — same name the admin-login route sets.
+        const cookieHeader = req.headers["cookie"];
+        if (typeof cookieHeader === "string") {
+            for (const raw of cookieHeader.split(";")) {
+                const trimmed = raw.trim();
+                const eq = trimmed.indexOf("=");
+                if (eq <= 0)
+                    continue;
+                const name = trimmed.slice(0, eq);
+                if (name !== ADMIN_COOKIE_NAME)
+                    continue;
+                const value = decodeURIComponent(trimmed.slice(eq + 1));
+                if (value === adminToken)
+                    return true;
+            }
+        }
+        return false;
+    };
+    // Same-origin posture for cookie minting: req.secure is true when
+    // the connecting socket is TLS, OR when an upstream proxy set
+    // `X-Forwarded-Proto: https` AND express trust-proxy is enabled.
+    // For zero-config local-host, trust-proxy is OFF and req.secure
+    // reflects the literal socket. Operators behind a tunnel with
+    // TLS termination at the edge get the cookie WITHOUT Secure
+    // (intended — the in-pod request is plaintext HTTP). Browsers
+    // still scope it to the origin via SameSite, which is the
+    // primary CSRF protection here; Secure is a defense-in-depth
+    // attribute, not load-bearing for this token.
+    const buildAdminCookie = (req, value) => {
+        const attrs = [
+            `${ADMIN_COOKIE_NAME}=${encodeURIComponent(value)}`,
+            "Path=/",
+            // 8-hour TTL — same posture as the console session cookie.
+            // Operators staying in the keys page longer than that just
+            // re-paste the admin token (printed on the boot banner).
+            "Max-Age=28800",
+            "SameSite=Lax",
+            "HttpOnly",
+        ];
+        if (req.secure)
+            attrs.push("Secure");
+        return attrs.join("; ");
+    };
+    // POST /ggui/console/admin-login — bearer-paste → cookie exchange.
+    // No auth gate: the request body IS the credential. On match,
+    // we set the cookie and 204; on mismatch we 401. Pre-launch no-
+    // backcompat: there's no rate-limiter wired in — this is a
+    // local-host route, lock-out via wider posture (tunnel access
+    // control, Cloudflare WAF) belongs to the operator.
+    app.post("/ggui/console/admin-login", (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const body = req.body;
+        const candidate = typeof body?.token === "string" ? body.token : "";
+        if (candidate.length === 0 || candidate !== adminToken) {
+            res.status(401).json({ error: "invalid_token" });
+            return;
+        }
+        res.setHeader("Set-Cookie", buildAdminCookie(req, adminToken));
+        res.status(204).end();
+    });
+    // Path-prefix gate. `app.use(path, mw)` runs `mw` for every
+    // request whose path starts with `path` — express normalizes
+    // trailing slashes / sub-paths so `/keys/abc` + `/keys` both
+    // hit. We only mount the keys routes BELOW this so the gate is
+    // genuinely the only ingress.
+    app.use("/ggui/console/keys", (req, res, next) => {
+        if (requestHasAdminAuth(req))
+            return next();
+        applyDevtoolSecurityHeaders(res);
+        res.status(401).json({ error: "admin_auth_required" });
+    });
+    // GET /ggui/console/keys — list pairings + plaintext bearer.
+    // Wire shape: `{ keys: [{pairingId, deviceName, createdAt,
+    // lastUsedAt?, token}] }`. Plaintext exposure is intentional;
+    // see PairingWithToken JSDoc for the threat model.
+    app.get("/ggui/console/keys", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        try {
+            const rows = await pairing.listPairingsWithTokens();
+            res.json({
+                keys: rows.map((row) => ({
+                    pairingId: row.pairingId,
+                    deviceName: row.deviceName,
+                    createdAt: row.createdAt,
+                    ...(row.lastUsedAt !== undefined ? { lastUsedAt: row.lastUsedAt } : {}),
+                    token: row.token,
+                })),
+            });
+        }
+        catch (err) {
+            logger.warn("console_keys_list_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "list_failed",
+                message: err instanceof Error
+                    ? `Keys list failed — ${err.message}`
+                    : `Keys list failed — ${String(err)}`,
+            });
+        }
+    });
+    // POST /ggui/console/keys — mint a fresh pairing without
+    // round-tripping `initPairing` + `completePairing` from the SPA.
+    // We do both server-side here: (1) initPairing to get a code,
+    // (2) completePairing to consume it. Idiomatic for an admin-only
+    // surface — the operator doesn't need a 6-digit-code typed in,
+    // they're already authenticated by the admin token. Returns the
+    // full `PairingCompletion` so the SPA can show the plaintext
+    // bearer in a one-time copy callout.
+    app.post("/ggui/console/keys", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const body = req.body;
+        const deviceName = typeof body?.deviceName === "string" ? body.deviceName.trim() : "";
+        if (deviceName.length === 0 || deviceName.length > 256) {
+            res.status(400).json({
+                error: "invalid_device_name",
+                message: "`deviceName` is required (non-empty string, ≤256 chars).",
+            });
+            return;
+        }
+        try {
+            const init = await pairing.initPairing();
+            const completion = await pairing.completePairing({
+                code: init.code,
+                deviceName,
+            });
+            res.json({
+                pairingId: completion.pairingId,
+                token: completion.token,
+                serverName: completion.serverName,
+                deviceName: completion.deviceName,
+            });
+        }
+        catch (err) {
+            logger.warn("console_keys_mint_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "mint_failed",
+                message: err instanceof Error ? `Mint failed — ${err.message}` : `Mint failed — ${String(err)}`,
+            });
+        }
+    });
+    // DELETE /ggui/console/keys/:pairingId — revoke (idempotent).
+    app.delete("/ggui/console/keys/:pairingId", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const pairingId = req.params["pairingId"];
+        if (typeof pairingId !== "string" || pairingId.length === 0) {
+            res.status(400).json({
+                error: "missing_pairing_id",
+                message: "pairingId required in path segment (e.g. DELETE /ggui/console/keys/pair-1).",
+            });
+            return;
+        }
+        try {
+            await pairing.revokePairing(pairingId);
+            res.status(204).end();
+        }
+        catch (err) {
+            logger.warn("console_keys_revoke_failed", {
+                error: String(err),
+                pairingId,
+            });
+            res.status(500).json({
+                error: "revoke_failed",
+                message: err instanceof Error
+                    ? `Revoke failed — ${err.message}`
+                    : `Revoke failed — ${String(err)}`,
+            });
+        }
+    });
+}

package/dist/console-llm-keys-routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BYOK LLM-keys plane — gated /ggui/console/llm-keys. Two postures:
+ *
+ *   - `gateMode: 'admin-token'` (default — OSS-personal):
+ *     gate accepts the admin bearer. Single global keyset; the
+ *     /settings UI lets the operator paste keys for everyone.
+ *   - `gateMode: 'auth-adapter'` (multi-tenant): gate
+ *     calls the server's `AuthAdapter`. Each user's keys are
+ *     scoped by `scopeFromRequest` (default: `userId`/`appId`).
+ *
+ * Wire shape (same in both gates):
+ *   GET    /ggui/console/llm-keys                 — list providers + presence
+ *   POST   /ggui/console/llm-keys                 — set { provider, key }
+ *   DELETE /ggui/console/llm-keys/:provider       — clear (idempotent)
+ *   POST   /ggui/console/llm-keys/:provider/probe — auth-validation probe
+ *
+ * Plaintext is NEVER returned on GET — unlike pairing tokens, an LLM
+ * key is a one-way paste (operator already has the key elsewhere; the
+ * server is just persisting it). The presence + source signal is
+ * enough for the /settings UI.
+ */
+import type { AuthAdapter, AuthResult, ProviderKeyStore } from "@ggui-ai/mcp-server-core";
+import type { Express, Request } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** BYOK provider-key store backing list/set/delete/probe. */
+    readonly providerKeys: ProviderKeyStore;
+    /** Which gate guards the plane. */
+    readonly gateMode: "admin-token" | "auth-adapter";
+    /** Admin token for `admin-token` gate mode (null = gate never passes). */
+    readonly adminToken: string | null;
+    /** Auth adapter for `auth-adapter` gate mode. */
+    readonly auth: AuthAdapter;
+    /** Per-request scope resolver override (default: userId/appId/global). */
+    readonly scopeFromRequest?: (req: Request, identity: AuthResult | null) => string;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount the LLM-keys routes onto the express app. Returns nothing —
+ * the routes self-register.
+ */
+export declare function mountConsoleLlmKeysRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-llm-keys-routes.d.ts.map

package/dist/console-llm-keys-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-llm-keys-routes.d.ts","sourceRoot":"","sources":["../src/console-llm-keys-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAEV,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA+B1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAAC;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI,KAAK,MAAM,CAAC;IAClF,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAgZlE"}