@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/thread-transport.js

@@ -0,0 +1,478 @@
+import { randomUUID } from 'node:crypto';
+import { appendMessage, applyThreadAction, createThread, getThread, InvalidThreadActionError, InvalidThreadRequestError, listMessages, listThreads, observeMessages, ThreadActionInvalidStateError, ThreadNotFoundError, } from '@ggui-ai/mcp-server-handlers/threads';
+import { resolveIdentity, UnauthenticatedError } from './auth.js';
+/** Default URL prefix the thread routes are mounted at. */
+export const DEFAULT_THREADS_PATH = '/threads';
+export const DEFAULT_BUILDER_OWNER_ID = 'builder';
+/**
+ * Default identity → ownerId mapping for the OSS server.
+ *
+ * Preserves the protocol's "self-hosted → typically `paired_<pairingId>`"
+ * convention whenever the token was minted by pairing: the bridge in
+ * `createGguiServer` passes `metadata: { pairingId }` on `onTokenIssued`,
+ * which surfaces here via `AuthResult.metadata.pairingId`. Fallbacks:
+ *
+ *   - `source: 'cognito'` with a `sub` metadata field → `cognito_<sub>`
+ *     (parallel adapters in any closed cloud runtime; not a shape the
+ *     OSS server ships today but the mapping is stable so custom
+ *     adapters are uniform).
+ *   - `kind: 'user'` → `user_<workspaceId ?? userId>` — same partition
+ *     rule `defaultAppIdFromIdentity` uses.
+ *   - `kind: 'builder'` with no pairing metadata (dev mode / manual
+ *     token) → {@link DEFAULT_BUILDER_OWNER_ID}.
+ *
+ * Keeping every OSS-reachable identity collapsed to ONE owner by
+ * default is correct: OSS is a single-operator tier. Operators who
+ * split owners across multiple tokens pass a custom resolver.
+ */
+export function defaultThreadOwnerFromIdentity(result) {
+    const pairingId = result.metadata?.['pairingId'];
+    if (typeof pairingId === 'string' && pairingId.length > 0) {
+        return `paired_${pairingId}`;
+    }
+    if (result.source === 'cognito') {
+        const sub = result.metadata?.['sub'];
+        if (typeof sub === 'string' && sub.length > 0)
+            return `cognito_${sub}`;
+    }
+    if (result.identity.kind === 'user') {
+        return `user_${result.identity.workspaceId ?? result.identity.userId}`;
+    }
+    // `kind: 'app'` is a per-app machine caller (e.g. an agent-builder
+    // API key hitting a hosted multi-tenant deployment). Threads owned
+    // by an app should be scoped to that app, NOT pooled into the
+    // default builder bucket — the latter would let two apps see each
+    // other's threads.
+    if (result.identity.kind === 'app') {
+        return `app_${result.identity.appId}`;
+    }
+    return DEFAULT_BUILDER_OWNER_ID;
+}
+/**
+ * Mount the six thread routes onto an existing Express app.
+ *
+ * Idempotent is NOT a goal — call once per server. `createGguiServer`
+ * owns the single call site via `opts.threads`.
+ */
+export function mountThreadTransport(app, opts) {
+    const prefix = opts.path ?? DEFAULT_THREADS_PATH;
+    const ownerFromIdentity = opts.ownerFromIdentity ?? defaultThreadOwnerFromIdentity;
+    const deps = { threads: opts.store };
+    // Resolve identity + ownerId in one place. Every route calls this
+    // first; on failure it writes the response and returns null so the
+    // route handler short-circuits. Returning null via a shared helper
+    // means no route accidentally proceeds without identity.
+    async function requireOwnerContext(req, res, routeLogger) {
+        const requestId = typeof req.headers['x-request-id'] === 'string'
+            ? req.headers['x-request-id']
+            : randomUUID();
+        try {
+            const identity = await resolveIdentity(opts.auth, req);
+            const ownerId = ownerFromIdentity(identity);
+            return { ownerId, requestId };
+        }
+        catch (err) {
+            if (err instanceof UnauthenticatedError) {
+                routeLogger.warn('thread_auth_failed', { reason: err.message });
+                res.status(401).json({
+                    error: { code: 'unauthenticated', message: err.message },
+                });
+                return null;
+            }
+            routeLogger.error('thread_auth_unexpected_error', {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+            return null;
+        }
+    }
+    /**
+     * Map a thrown handler / store error to the stable HTTP envelope.
+     * Central for two reasons: (1) every route has the same mapping
+     * rules, so DRY; (2) adding a new error class is a one-liner here
+     * instead of six places.
+     */
+    function handleError(err, res, routeLogger, routeLabel) {
+        if (err instanceof InvalidThreadRequestError) {
+            routeLogger.debug?.('thread_bad_request', {
+                route: routeLabel,
+                message: err.message,
+            });
+            res.status(400).json({
+                error: {
+                    code: 'bad_request',
+                    message: err.message,
+                    details: { issues: err.issues },
+                },
+            });
+            return;
+        }
+        if (err instanceof InvalidThreadActionError) {
+            // Handler-schema parsing rejects unknown actions first (→
+            // InvalidThreadRequestError). This branch covers direct-call
+            // paths where the store validates. 400 matches the "malformed
+            // action value" semantics.
+            routeLogger.debug?.('thread_invalid_action', {
+                route: routeLabel,
+                message: err.message,
+            });
+            res.status(400).json({
+                error: { code: 'bad_request', message: err.message },
+            });
+            return;
+        }
+        if (err instanceof ThreadActionInvalidStateError) {
+            routeLogger.debug?.('thread_action_invalid_state', {
+                route: routeLabel,
+                message: err.message,
+            });
+            res.status(409).json({
+                error: { code: 'conflict', message: err.message },
+            });
+            return;
+        }
+        if (err instanceof ThreadNotFoundError) {
+            routeLogger.debug?.('thread_not_found', {
+                route: routeLabel,
+                message: err.message,
+            });
+            res.status(404).json({
+                error: { code: 'not_found', message: err.message },
+            });
+            return;
+        }
+        routeLogger.error('thread_route_unexpected_error', {
+            route: routeLabel,
+            error: String(err),
+        });
+        if (!res.headersSent) {
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+        }
+    }
+    // --- POST /threads ---
+    app.post(prefix, async (req, res) => {
+        const routeLogger = opts.logger.child({ route: 'POST ' + prefix });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const thread = await createThread(deps, req.body ?? {}, ctx);
+            res.status(201).json(thread);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'POST ' + prefix);
+        }
+    });
+    // --- GET /threads ---
+    //
+    // Filter comes from the query string. `limit` arrives as a string
+    // from Express; coerce before handing to the handler (the
+    // handler's zod schema would otherwise reject `"50"` as not a
+    // number). Everything else is already a string or absent.
+    app.get(prefix, async (req, res) => {
+        const routeLogger = opts.logger.child({ route: 'GET ' + prefix });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const filter = coerceQueryToFilter(req.query);
+            const result = await listThreads(deps, filter, ctx);
+            res.json(result);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'GET ' + prefix);
+        }
+    });
+    // --- GET /threads/:id ---
+    app.get(`${prefix}/:id`, async (req, res) => {
+        const routeLogger = opts.logger.child({ route: 'GET ' + prefix + '/:id' });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const thread = await getThread(deps, { threadId: req.params.id }, ctx);
+            res.json(thread);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'GET ' + prefix + '/:id');
+        }
+    });
+    // --- PATCH /threads/:id ---
+    //
+    // Body: `{ action: ThreadStateAction }`. PATCH picked (over POST
+    // on `/:id/actions`) because the action is a state transition on
+    // the resource, not a new sub-resource, and that matches how the
+    // cloud adapter frames it (`updateThreadState` mutation).
+    app.patch(`${prefix}/:id`, async (req, res) => {
+        const routeLogger = opts.logger.child({
+            route: 'PATCH ' + prefix + '/:id',
+        });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const thread = await applyThreadAction(deps, { threadId: req.params.id, body: req.body ?? {} }, ctx);
+            res.json(thread);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'PATCH ' + prefix + '/:id');
+        }
+    });
+    // --- GET /threads/:id/messages ---
+    app.get(`${prefix}/:id/messages`, async (req, res) => {
+        const routeLogger = opts.logger.child({
+            route: 'GET ' + prefix + '/:id/messages',
+        });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const result = await listMessages(deps, {
+                threadId: req.params.id,
+                options: coerceQueryToMessageOptions(req.query),
+            }, ctx);
+            res.json(result);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'GET ' + prefix + '/:id/messages');
+        }
+    });
+    // --- POST /threads/:id/messages ---
+    //
+    // The body carries every field except `threadId` (which comes from
+    // the URL). The handler requires `threadId` on its input envelope,
+    // so we fold it in here — caller-supplied `threadId` in the body
+    // (if any) is intentionally overwritten by the URL segment, which
+    // is the canonical truth for a RESTful path-scoped write.
+    app.post(`${prefix}/:id/messages`, async (req, res) => {
+        const routeLogger = opts.logger.child({
+            route: 'POST ' + prefix + '/:id/messages',
+        });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        try {
+            const body = typeof req.body === 'object' && req.body !== null ? req.body : {};
+            const input = { ...body, threadId: req.params.id };
+            const message = await appendMessage(deps, input, ctx);
+            res.status(201).json(message);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'POST ' + prefix + '/:id/messages');
+        }
+    });
+    // --- GET /threads/:id/stream (SSE) ---
+    //
+    // Serializes frames from the Step 3 `observeMessages` handler's
+    // AsyncIterable. Pre-header error handling is the interesting bit:
+    //
+    //   1. Resolve auth + ownerId (JSON-error channel).
+    //   2. Parse query options (JSON-error channel on shape failures).
+    //   3. Construct the iterator and call `.next()`.
+    //   4. Race that first `.next()` against `setImmediate`:
+    //        - If it rejects synchronously → ThreadNotFoundError /
+    //          InvalidThreadRequestError → write JSON error response
+    //          with the right status code, NEVER write SSE headers.
+    //        - If it resolves synchronously (backlog available or
+    //          tail:false+empty backlog) → headers committed + that
+    //          first result is sent as the initial SSE frame.
+    //        - If it's still pending after one macrotask → ownership
+    //          has passed (the store's wrong-owner check is
+    //          synchronous), so headers can safely commit. The
+    //          already-queued `firstNext` becomes the first frame
+    //          whenever the first append lands.
+    //
+    // This keeps wrong-owner and missing-thread both 404'd BEFORE SSE
+    // headers are flushed — clients see the same error envelope they
+    // see on the JSON routes. The alternative (flush 200 then write a
+    // terminal error event) would silently convert a 404 into a 200,
+    // breaking the partition-indistinguishability rule.
+    app.get(`${prefix}/:id/stream`, async (req, res) => {
+        const routeLogger = opts.logger.child({
+            route: 'GET ' + prefix + '/:id/stream',
+        });
+        const ctx = await requireOwnerContext(req, res, routeLogger);
+        if (!ctx)
+            return;
+        // Parse fromSeq from query. Tail is always true for SSE — the
+        // whole point of the endpoint is a live subscription. If a
+        // future caller wants a one-shot snapshot they'd use
+        // `GET /messages`, not stream.
+        let iterable;
+        try {
+            iterable = observeMessages(deps, {
+                threadId: req.params.id,
+                options: coerceQueryToObserveOptions(req.query),
+            }, ctx);
+        }
+        catch (err) {
+            handleError(err, res, routeLogger, 'GET ' + prefix + '/:id/stream');
+            return;
+        }
+        const iter = iterable[Symbol.asyncIterator]();
+        // Client-disconnect cleanup — set up BEFORE the race so that a
+        // disconnect during the ownership-probe window still disposes
+        // the iterator.
+        let clientClosed = false;
+        res.on('close', () => {
+            clientClosed = true;
+            if (iter.return) {
+                iter.return(undefined).catch(() => undefined);
+            }
+        });
+        // --- Ownership probe ---
+        // The store's observeMessages rejects the first `.next()`
+        // synchronously for wrong-owner / missing. On an empty thread
+        // with tail:true, the first `.next()` stays pending indefinitely.
+        // We distinguish by racing one macrotask.
+        const firstNext = iter.next();
+        const probe = await Promise.race([
+            firstNext.then((r) => ({ kind: 'settled', result: r }), (err) => ({ kind: 'rejected', error: err })),
+            new Promise((resolve) => setImmediate(() => resolve({ kind: 'pending' }))),
+        ]);
+        if (probe.kind === 'rejected') {
+            handleError(probe.error, res, routeLogger, 'GET ' + prefix + '/:id/stream');
+            return;
+        }
+        if (clientClosed) {
+            // Client gave up before we even committed headers. Nothing to
+            // send; iterator has already been disposed by the close hook.
+            return;
+        }
+        // Commit SSE headers.
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        res.flushHeaders?.();
+        // Consume the first result + continue the loop. The try/catch
+        // here covers post-header failures (e.g. a deferred store error
+        // surfacing through the pending firstNext). On that path we can't
+        // return 4xx — just log and close cleanly.
+        try {
+            if (probe.kind === 'settled') {
+                if (!probe.result.done) {
+                    writeEventFrame(res, probe.result.value);
+                }
+                else {
+                    res.end();
+                    return;
+                }
+            }
+            else {
+                // Probe ended as pending. firstNext still resolves in the
+                // normal path; await it like any subsequent iteration.
+                const first = await firstNext;
+                if (first.done) {
+                    res.end();
+                    return;
+                }
+                writeEventFrame(res, first.value);
+            }
+            while (!clientClosed) {
+                const result = await iter.next();
+                if (result.done)
+                    break;
+                writeEventFrame(res, result.value);
+            }
+            res.end();
+        }
+        catch (err) {
+            // Deferred error after headers are committed. Best-effort
+            // terminal-event shape (clients can still dedupe on seq), then
+            // close. NEVER reset the status code — headers are out.
+            routeLogger.warn('thread_stream_deferred_error', {
+                error: String(err),
+            });
+            if (!res.writableEnded) {
+                try {
+                    res.write(`event: error\ndata: ${JSON.stringify({ message: String(err) })}\n\n`);
+                }
+                catch {
+                    // Socket may be gone — swallow.
+                }
+                res.end();
+            }
+        }
+    });
+}
+/**
+ * Emit one ThreadMessage as an SSE frame. Frame shape:
+ *
+ *   id: <seq>
+ *   event: thread-message
+ *   data: <JSON-encoded ThreadStreamEvent>
+ *   \n
+ *
+ * The `id` field carries the `seq` so clients automatically get the
+ * Last-Event-ID reconnect hint (the browser's EventSource sends the
+ * last-seen id back on `?fromSeq=<last+1>`-aware reconnects; CLI
+ * consumers honor it manually). Event type is the shipped
+ * `ThreadStreamEvent` discriminant — v1 is `'thread-message'`;
+ * future additions stay forward-compatible because clients dedupe
+ * on seq + ignore unknown event types.
+ */
+function writeEventFrame(res, message) {
+    const event = { type: 'thread-message', message };
+    res.write(`id: ${message.seq}\nevent: thread-message\ndata: ${JSON.stringify(event)}\n\n`);
+}
+/**
+ * Coerce Express's query object (`string | string[] | ParsedQs | ...`)
+ * into the shape {@link listThreadsFilterSchema} expects. We only
+ * coerce fields the filter knows about; extras pass through untouched
+ * and the handler's strict schema rejects them (so a typo like
+ * `?stats=archived` returns 400 instead of silently ignoring the
+ * filter — catches client bugs fast).
+ */
+function coerceQueryToFilter(query) {
+    const out = {};
+    if (typeof query['status'] === 'string')
+        out['status'] = query['status'];
+    if (typeof query['appId'] === 'string')
+        out['appId'] = query['appId'];
+    if (typeof query['cursor'] === 'string')
+        out['cursor'] = query['cursor'];
+    if (typeof query['limit'] === 'string') {
+        const n = Number(query['limit']);
+        out['limit'] = Number.isFinite(n) ? n : query['limit'];
+    }
+    return out;
+}
+function coerceQueryToMessageOptions(query) {
+    const out = {};
+    if (typeof query['cursor'] === 'string')
+        out['cursor'] = query['cursor'];
+    if (typeof query['fromSeq'] === 'string') {
+        const n = Number(query['fromSeq']);
+        out['fromSeq'] = Number.isFinite(n) ? n : query['fromSeq'];
+    }
+    if (typeof query['limit'] === 'string') {
+        const n = Number(query['limit']);
+        out['limit'] = Number.isFinite(n) ? n : query['limit'];
+    }
+    return out;
+}
+/**
+ * Coerce SSE stream query params.
+ *
+ * `?fromSeq=<n>` is the only knob the stream endpoint honors — tail
+ * is always on (the endpoint IS a subscription). Limit is not
+ * meaningful for a stream and cursor is a paginated-read concept;
+ * both are omitted here and the handler's strict schema rejects
+ * them if passed (so a misdirected client query gets 400 instead of
+ * silently ignoring the knob).
+ */
+function coerceQueryToObserveOptions(query) {
+    const out = {};
+    if (typeof query['fromSeq'] === 'string') {
+        const n = Number(query['fromSeq']);
+        out['fromSeq'] = Number.isFinite(n) ? n : query['fromSeq'];
+    }
+    return out;
+}

package/dist/user-session-auth.d.ts

@@ -0,0 +1,167 @@
+/**
+ * End-user browser session cookie auth plane.
+ *
+ * This is the FOURTH cookie kind the OSS server tracks. Distinct from
+ * the existing console session cookie (`ggui_console_session`,
+ * `console-auth.ts`) — that one's an HMAC token bound to
+ * `{sessionId, appId}` for narrow live-channel upgrade auth.
+ *
+ * The user-session cookie carries something different: **the raw
+ * pairing-minted bearer**, opaque to this module, validated downstream
+ * by the configured `AuthAdapter`. Architecture rationale:
+ *
+ *   - One bearer per end-user, two transports.
+ *
+ *     The pair-code consume flow (`POST /pair`) mints a bearer the
+ *     MCP host (claude.ai's connector) sends as `Authorization: Bearer
+ *     ...` on `/mcp` calls. The same bearer can also live in a
+ *     same-origin HTTP-only cookie so the end-user's BROWSER (visiting
+ *     the operator's `/settings` page) authenticates as the SAME
+ *     identity. The AuthAdapter resolves both transports identically.
+ *
+ *   - `/login` mints the cookie atomically with a fresh pair-code
+ *     consume.
+ *
+ *     Bearer paste at `/login` was rejected during the audit (session
+ *     fixation: attacker tricks user into pasting attacker's bearer
+ *     → user's actions land under attacker's identity). Only pair-code
+ *     consume sets the cookie. The bearer never crosses an untrusted
+ *     boundary.
+ *
+ *   - Cookie value === bearer string verbatim.
+ *
+ *     No HMAC-wrapping needed because the bearer is already a
+ *     cryptographic credential the AuthAdapter validates. Wrapping
+ *     would just add friction to the `Authorization: Bearer ...` ↔
+ *     cookie symmetry. (The console session cookie HMACs because its
+ *     payload is plain `{sessionId, appId}` claims, not a bearer.)
+ *
+ * Cookie attributes locked in the plan doc:
+ *   - `HttpOnly` — JS can't read; XSS exfil blocked
+ *   - `SameSite=Lax` — Strict breaks the Connect-Claude card
+ *     cross-origin click flow (claude.ai iframe → ggui /settings)
+ *   - `Secure` — TLS-only. Disabled for `secure: false` opt-out under
+ *     localhost-only dev
+ *   - `Path=/`
+ *   - `Max-Age` — bound to bearer's pairing TTL
+ *
+ * What this module does NOT do:
+ *   - Mint or verify HMAC tokens (that's bearer territory; AuthAdapter
+ *     owns it).
+ *   - Decide which routes require the cookie (composition-time;
+ *     consumers wire `cookieAuthMiddleware` where they want
+ *     cookie-or-header auth).
+ *   - Rate-limiting, CSRF, audit hooks (handled by separate
+ *     middleware).
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+import type { Request, RequestHandler } from 'express';
+/**
+ * Cookie name. Distinct from `ggui_console_session` so cross-kind
+ * confusion is impossible — a cookie value never gets misinterpreted
+ * as a different auth artifact. Change carries a compat concern (the
+ * `/login` mint endpoint, `cookieAuthMiddleware`, and `/logout` clear
+ * read this exact name); keep this export as the single source of
+ * truth.
+ */
+export declare const USER_SESSION_COOKIE_NAME = "ggui_user_session";
+/**
+ * Default cookie TTL (seconds). 8 hours mirrors the console session
+ * cookie default — operators leaving a tab open for a workday don't
+ * get re-prompted, but a stale cookie on a forgotten device expires
+ * before it ages further. Operators wanting longer sessions pass
+ * `ttlSec` at mount time.
+ */
+export declare const DEFAULT_USER_SESSION_TTL_SEC: number;
+export interface FormatUserSessionCookieInput {
+    /** The pairing-minted bearer to embed as the cookie value. */
+    readonly bearer: string;
+    /** Cookie TTL in seconds. Defaults to {@link DEFAULT_USER_SESSION_TTL_SEC}. */
+    readonly ttlSec?: number;
+    /**
+     * Adds `Secure` when truthy — cookie only sent over HTTPS. Operators
+     * fronting the server with TLS pass `true`; localhost-only dev paths
+     * leave it falsy. No auto-detect — explicit is safer here than
+     * sniffing `req.protocol` (which lies behind reverse proxies).
+     */
+    readonly secure?: boolean;
+    /** Cookie path. Defaults to `/`. */
+    readonly path?: string;
+    /**
+     * SameSite policy. Defaults to `'Lax'` per the audit decision —
+     * Strict would break the Connect-Claude card flow where the user
+     * clicks an `<a target="_blank">` from claude.ai's iframe to
+     * ggui's `/settings`. Lax permits top-level GET navigations to
+     * carry the cookie, which is what we need; CSRF on POSTs is
+     * defended via the CSRF-token middleware, not by cookie SameSite
+     * alone.
+     */
+    readonly sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Format the `Set-Cookie` header value. Caller does
+ * `res.setHeader('Set-Cookie', formatUserSessionCookieHeader(...))`.
+ *
+ * The bearer is URL-encoded so values containing `;` / `,` / `=`
+ * survive the cookie wire format. `extractUserSessionCookie` decodes
+ * symmetrically.
+ */
+export declare function formatUserSessionCookieHeader(input: FormatUserSessionCookieInput): string;
+/**
+ * Format a `Set-Cookie` header that immediately invalidates the
+ * user-session cookie. Used by `/logout` and `/revoke-bearer` so the
+ * browser drops it without waiting for `Max-Age`.
+ *
+ * `Max-Age=0` is the canonical clear pattern; matching attrs (Path,
+ * Secure) are required so the browser pairs this with the original
+ * mint and replaces it.
+ */
+export declare function formatClearUserSessionCookieHeader(input: {
+    readonly secure?: boolean;
+    readonly path?: string;
+    readonly sameSite?: 'Strict' | 'Lax' | 'None';
+}): string;
+/**
+ * Read the user-session cookie value from a `Cookie` header string.
+ * Returns the URL-decoded bearer, or `null` when the cookie is absent
+ * / malformed.
+ *
+ * Manual parser — same shape as `extractDevtoolCookie`. Tolerant of
+ * multi-cookie headers (`a=1; ggui_user_session=xyz; b=2`); rejects
+ * empty values rather than treating them as an authenticated bearer.
+ */
+export declare function extractUserSessionCookie(cookieHeader: string | undefined): string | null;
+/**
+ * Read the cookie off Node `IncomingHttpHeaders` directly. Thin
+ * wrapper for callers operating below Express (raw `IncomingMessage`,
+ * WebSocket upgrade).
+ */
+export declare function readUserSessionCookieFromHeaders(headers: IncomingHttpHeaders): string | null;
+/**
+ * Express middleware that bridges the cookie → header path.
+ *
+ * When a request arrives WITHOUT an `Authorization` header but WITH a
+ * valid user-session cookie, the middleware synthesizes
+ * `Authorization: Bearer <cookie>` so every existing
+ * `resolveIdentity(auth, req)` call works transparently. No new auth
+ * codepath, no new gate logic.
+ *
+ * When the request already has an `Authorization` header, the cookie
+ * is ignored — the explicit header wins. This preserves the existing
+ * `/mcp` ingress posture (claude.ai's connector sends Authorization;
+ * the cookie does not interfere with it).
+ *
+ * Composition-time: mount BEFORE any gate that reads
+ * `req.headers['authorization']` (the `/ggui/console/llm-keys` gate,
+ * the `/mcp` ingress, etc.). Order matters — middleware runs
+ * top-to-bottom in the Express chain.
+ */
+export declare function cookieAuthMiddleware(): RequestHandler;
+/**
+ * Read the user-session cookie off an Express request. Used by
+ * `/logout` to know whether there's anything to clear, by
+ * `/revoke-bearer` to identify the pairing to revoke, and by tests
+ * that need to inspect the cookie without going through middleware.
+ */
+export declare function readUserSessionCookie(req: Request): string | null;
+//# sourceMappingURL=user-session-auth.d.ts.map

package/dist/user-session-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-session-auth.d.ts","sourceRoot":"","sources":["../src/user-session-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAAc,CAAC;AAExD,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,4BAA4B,GAClC,MAAM,CAWR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C,GAAG,MAAM,CAUT;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAqBf;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAYrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEjE"}