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

package/dist/pairing-transport.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pairing transport — HTTP routes that complete a viewer↔server pairing
+ * handshake, mint codes on admin trigger, and revoke active pairings.
+ *
+ * Three routes (all opt-in via `createGguiServer({ pairing })`):
+ *
+ *   POST /pair                      — public. Body `{code, deviceName}`.
+ *                                     Returns `{pairingId, token, serverName,
+ *                                     deviceName}`. No auth — pairing IS
+ *                                     the bootstrap for future auth.
+ *
+ *   POST /admin/pair/init           — admin. Bearer auth → builder only.
+ *                                     Returns `{code, codeExpiresAt,
+ *                                     serverName}`.
+ *
+ *   POST /admin/pair/:pairingId/revoke
+ *                                   — admin. Bearer auth → builder only.
+ *                                     Immediate revocation of a minted
+ *                                     pairing. Idempotent — revoking
+ *                                     a pairingId that does not exist
+ *                                     returns the same `{ok: true}`
+ *                                     envelope. Delegates to
+ *                                     {@link PairingService.revokePairing};
+ *                                     `onTokenRevoked` unregisters the
+ *                                     token from the active adapter so
+ *                                     subsequent `/mcp` calls fail with
+ *                                     401 via the canonical
+ *                                     `No valid credentials` envelope.
+ *
+ * The transport is thin by construction — it delegates every stateful
+ * decision to the supplied {@link PairingService}. Error mapping is the
+ * only transport-level concern:
+ *
+ *   - Body validation failure → 400 with `{code: 'bad_request', ...}`.
+ *   - Service throws on mismatched / expired / missing code → 401 with
+ *     `{code: 'pairing_rejected', ...}`.
+ *   - Any other service failure → 500 with `{code: 'internal', ...}`.
+ *
+ * Routes are mounted on the existing Express app the server already
+ * owns — no sub-router, no second server surface.
+ */
+import type { Express } from 'express';
+import type { AuthAdapter, PairingService } from '@ggui-ai/mcp-server-core';
+import type { Logger } from './logger.js';
+/** Default URL path the pairing-completion route is mounted at. */
+export declare const DEFAULT_PAIRING_PATH = "/pair";
+/**
+ * Default URL path the admin-init route is mounted at. Keep prefixed
+ * with `/admin/` so operators can firewall the whole family with one
+ * rule when fronting the server behind a reverse proxy.
+ */
+export declare const DEFAULT_PAIRING_ADMIN_INIT_PATH = "/admin/pair/init";
+/**
+ * Default URL-template the admin-revoke route is mounted at. `:pairingId`
+ * is the Express route parameter consumed by the handler; operators
+ * firewalling behind a reverse proxy should match on the prefix
+ * `/admin/pair/` — this template sits under that same umbrella as
+ * {@link DEFAULT_PAIRING_ADMIN_INIT_PATH}.
+ */
+export declare const DEFAULT_PAIRING_ADMIN_REVOKE_PATH = "/admin/pair/:pairingId/revoke";
+export interface PairingTransportOptions {
+    /** Required. The pairing service the routes delegate to. */
+    readonly pairing: PairingService;
+    /**
+     * Required. The same AuthAdapter the `/mcp` and live-channel endpoints
+     * use. Gates the admin-init route; MUST resolve to a `builder`
+     * identity for init to succeed.
+     */
+    readonly auth: AuthAdapter;
+    /** Structured logger. Child loggers are derived per-route. */
+    readonly logger: Logger;
+    /**
+     * URL path for the public completion route. Defaults to `/pair`.
+     */
+    readonly path?: string;
+    /**
+     * URL path for the admin init route. Defaults to
+     * `/admin/pair/init`. Pass `null` to disable the route entirely —
+     * embedded hosts that trigger `initPairing()` programmatically via
+     * `GguiServer.pairingService` may not want an HTTP surface.
+     */
+    readonly adminInitPath?: string | null;
+    /**
+     * URL-template for the admin revoke route. Defaults to
+     * `/admin/pair/:pairingId/revoke`. Pass `null` to disable the route
+     * entirely — embedded hosts that trigger `revokePairing()`
+     * programmatically may not want an HTTP surface. Mount symmetry
+     * with `adminInitPath`: if a caller disables one, they frequently
+     * disable both.
+     */
+    readonly adminRevokePath?: string | null;
+}
+/**
+ * Mount the pairing routes onto an existing Express app. Idempotent is
+ * NOT a goal here — call once per server; mounting twice registers the
+ * routes twice.
+ */
+export declare function mountPairingTransport(app: Express, opts: PairingTransportOptions): void;
+//# sourceMappingURL=pairing-transport.d.ts.map

package/dist/pairing-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-transport.d.ts","sourceRoot":"","sources":["../src/pairing-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,qBAAqB,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,kCACb,CAAC;AAElC,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAmNN"}

package/dist/pairing-transport.js

@@ -0,0 +1,223 @@
+import { resolveIdentity, UnauthenticatedError } from './auth.js';
+/** Default URL path the pairing-completion route is mounted at. */
+export const DEFAULT_PAIRING_PATH = '/pair';
+/**
+ * Default URL path the admin-init route is mounted at. Keep prefixed
+ * with `/admin/` so operators can firewall the whole family with one
+ * rule when fronting the server behind a reverse proxy.
+ */
+export const DEFAULT_PAIRING_ADMIN_INIT_PATH = '/admin/pair/init';
+/**
+ * Default URL-template the admin-revoke route is mounted at. `:pairingId`
+ * is the Express route parameter consumed by the handler; operators
+ * firewalling behind a reverse proxy should match on the prefix
+ * `/admin/pair/` — this template sits under that same umbrella as
+ * {@link DEFAULT_PAIRING_ADMIN_INIT_PATH}.
+ */
+export const DEFAULT_PAIRING_ADMIN_REVOKE_PATH = '/admin/pair/:pairingId/revoke';
+/**
+ * Mount the pairing routes onto an existing Express app. Idempotent is
+ * NOT a goal here — call once per server; mounting twice registers the
+ * routes twice.
+ */
+export function mountPairingTransport(app, opts) {
+    const path = opts.path ?? DEFAULT_PAIRING_PATH;
+    const adminInitPath = opts.adminInitPath === undefined
+        ? DEFAULT_PAIRING_ADMIN_INIT_PATH
+        : opts.adminInitPath;
+    const adminRevokePath = opts.adminRevokePath === undefined
+        ? DEFAULT_PAIRING_ADMIN_REVOKE_PATH
+        : opts.adminRevokePath;
+    // --- POST /pair ---
+    //
+    // No auth. Expects JSON `{code, deviceName}`. Either field missing or
+    // non-string → 400. Service rejection (bad/expired/consumed code) →
+    // 401. Success → 200 with the `PairingCompletion` shape the viewer
+    // stores verbatim.
+    app.post(path, async (req, res) => {
+        const reqLogger = opts.logger.child({ route: 'POST ' + path });
+        const body = (req.body ?? {});
+        const code = typeof body['code'] === 'string' ? body['code'] : undefined;
+        const deviceName = typeof body['deviceName'] === 'string' ? body['deviceName'] : undefined;
+        const remoteAddress = req.socket.remoteAddress ?? undefined;
+        if (!code || !deviceName) {
+            reqLogger.debug?.('pair_bad_request', {
+                hasCode: code !== undefined,
+                hasDeviceName: deviceName !== undefined,
+            });
+            res.status(400).json({
+                error: {
+                    code: 'bad_request',
+                    message: 'POST /pair requires a JSON body with string `code` and `deviceName`.',
+                },
+            });
+            return;
+        }
+        try {
+            const completion = await opts.pairing.completePairing({
+                code,
+                deviceName,
+                ...(remoteAddress ? { remoteAddress } : {}),
+            });
+            reqLogger.info('pair_completed', {
+                pairingId: completion.pairingId,
+                deviceName: completion.deviceName,
+            });
+            res.status(200).json(completion);
+        }
+        catch (err) {
+            // The service's thrown Error messages describe the mismatch
+            // precisely but aren't safe to surface verbatim (code values
+            // would leak into logs). Collapse to one code + one message.
+            reqLogger.warn('pair_rejected', { error: String(err) });
+            res.status(401).json({
+                error: {
+                    code: 'pairing_rejected',
+                    message: 'Pairing code is invalid, expired, or has already been consumed.',
+                },
+            });
+        }
+    });
+    // --- POST /admin/pair/init ---
+    //
+    // Bearer-authenticated. Only builder identities may mint codes — the
+    // operator triggering a code mint is by definition the server owner.
+    // User identities (if any ever land on the OSS tier) are rejected.
+    if (adminInitPath) {
+        app.post(adminInitPath, async (req, res) => {
+            const reqLogger = opts.logger.child({ route: 'POST ' + adminInitPath });
+            try {
+                const identity = await resolveIdentity(opts.auth, req);
+                if (identity.identity.kind !== 'builder') {
+                    reqLogger.warn('admin_init_forbidden', {
+                        identityKind: identity.identity.kind,
+                    });
+                    res.status(403).json({
+                        error: {
+                            code: 'forbidden',
+                            message: 'POST /admin/pair/init requires a builder identity.',
+                        },
+                    });
+                    return;
+                }
+            }
+            catch (err) {
+                if (err instanceof UnauthenticatedError) {
+                    reqLogger.warn('admin_init_unauthenticated', {
+                        reason: err.message,
+                    });
+                    res.status(401).json({
+                        error: {
+                            code: 'unauthenticated',
+                            message: err.message,
+                        },
+                    });
+                    return;
+                }
+                reqLogger.error('admin_init_unexpected_error', {
+                    error: String(err),
+                });
+                res.status(500).json({
+                    error: { code: 'internal', message: 'Internal server error' },
+                });
+                return;
+            }
+            try {
+                const init = await opts.pairing.initPairing();
+                reqLogger.info('admin_init_minted', {
+                    codeExpiresAt: init.codeExpiresAt,
+                });
+                res.status(200).json(init);
+            }
+            catch (err) {
+                reqLogger.error('admin_init_failed', { error: String(err) });
+                res.status(500).json({
+                    error: { code: 'internal', message: 'Internal server error' },
+                });
+            }
+        });
+    }
+    // --- POST /admin/pair/:pairingId/revoke ---
+    //
+    // Bearer-authenticated builder-only — mirrors `/admin/pair/init`'s
+    // identity gate. Delegates to `PairingService.revokePairing`, which
+    // the in-memory reference is idempotent about (revoking a missing
+    // pairingId is a no-op, NOT a 404 — the HTTP surface preserves that
+    // so an admin cleanup loop is safe to re-run). The service's
+    // `onTokenRevoked` callback is the load-bearing side-effect: it
+    // unregisters the bearer from the active AuthAdapter, so a
+    // subsequent `/mcp` call with the revoked token fails at
+    // `resolveIdentity` with the canonical JSON-RPC 401 envelope.
+    //
+    // Response envelope on success: `{ok: true, pairingId}`. Thin by
+    // design — the service returns void, so the route asserts the
+    // operation completed without surfacing internal state.
+    if (adminRevokePath) {
+        app.post(adminRevokePath, async (req, res) => {
+            const reqLogger = opts.logger.child({
+                route: 'POST ' + adminRevokePath,
+            });
+            const pairingId = req.params['pairingId'];
+            if (typeof pairingId !== 'string' || pairingId.length === 0) {
+                reqLogger.debug?.('pair_revoke_bad_request', {});
+                res.status(400).json({
+                    error: {
+                        code: 'bad_request',
+                        message: 'POST /admin/pair/:pairingId/revoke requires a non-empty `pairingId` path parameter.',
+                    },
+                });
+                return;
+            }
+            try {
+                const identity = await resolveIdentity(opts.auth, req);
+                if (identity.identity.kind !== 'builder') {
+                    reqLogger.warn('admin_revoke_forbidden', {
+                        identityKind: identity.identity.kind,
+                        pairingId,
+                    });
+                    res.status(403).json({
+                        error: {
+                            code: 'forbidden',
+                            message: 'POST /admin/pair/:pairingId/revoke requires a builder identity.',
+                        },
+                    });
+                    return;
+                }
+            }
+            catch (err) {
+                if (err instanceof UnauthenticatedError) {
+                    reqLogger.warn('admin_revoke_unauthenticated', {
+                        reason: err.message,
+                        pairingId,
+                    });
+                    res.status(401).json({
+                        error: { code: 'unauthenticated', message: err.message },
+                    });
+                    return;
+                }
+                reqLogger.error('admin_revoke_unexpected_error', {
+                    error: String(err),
+                    pairingId,
+                });
+                res.status(500).json({
+                    error: { code: 'internal', message: 'Internal server error' },
+                });
+                return;
+            }
+            try {
+                await opts.pairing.revokePairing(pairingId);
+                reqLogger.info('admin_revoke_completed', { pairingId });
+                res.status(200).json({ ok: true, pairingId });
+            }
+            catch (err) {
+                reqLogger.error('admin_revoke_failed', {
+                    error: String(err),
+                    pairingId,
+                });
+                res.status(500).json({
+                    error: { code: 'internal', message: 'Internal server error' },
+                });
+            }
+        });
+    }
+}

package/dist/rate-limit-middleware.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-IP rate-limit middleware for `/pair`.
+ *
+ * Wraps an already-constructed {@link RateLimiter} (policy lives there —
+ * limit + window are baked into the adapter at construction time, so
+ * swapping a hosted Redis-backed limiter in for the OSS in-memory
+ * `FixedWindowRateLimiter` does not change this middleware).
+ *
+ * Behavior:
+ *   - Composes the bucket key as `${quotaKey}:${ip}`. `quotaKey` is
+ *     caller-tagged so additional pre-auth surfaces can share the
+ *     middleware with isolated quotas.
+ *   - Per-IP source: `X-Forwarded-For` (first non-empty hop) when
+ *     `trustProxy=true`, else `req.socket.remoteAddress`. Falls back to
+ *     `'unknown'` and treats every unidentified peer as a single bucket.
+ *   - On denial: 429 + `Retry-After` (seconds, ceiling) + JSON
+ *     `{error: {code: 'rate_limited', message, retryAfter}}`.
+ *   - On limiter throw: log + `next()` (fail-open). A limiter outage MUST
+ *     NOT take down auth endpoints — same posture documented on the
+ *     `RateLimiter` seam itself.
+ */
+import type { Request, RequestHandler } from 'express';
+import type { RateLimiter } from '@ggui-ai/mcp-server-core';
+import type { Logger } from './logger.js';
+export interface PairLoginRateLimitOptions {
+    readonly limiter: RateLimiter;
+    readonly logger: Logger;
+    /** Tag prefix on the bucket key. */
+    readonly quotaKey: string;
+    /** When true, prefer the first `X-Forwarded-For` hop. Default false. */
+    readonly trustProxy?: boolean;
+}
+/** Extracted so tests can target the IP-resolution path directly if needed. */
+export declare function resolveClientIp(req: Pick<Request, 'headers' | 'socket'>, trustProxy: boolean): string;
+export declare function createPairLoginRateLimitMiddleware(opts: PairLoginRateLimitOptions): RequestHandler;
+//# sourceMappingURL=rate-limit-middleware.d.ts.map

package/dist/rate-limit-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-middleware.d.ts","sourceRoot":"","sources":["../src/rate-limit-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAC7B,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAC,EACxC,UAAU,EAAE,OAAO,GAClB,MAAM,CAaR;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,yBAAyB,GAC9B,cAAc,CA2ChB"}

package/dist/rate-limit-middleware.js

@@ -0,0 +1,57 @@
+/** Extracted so tests can target the IP-resolution path directly if needed. */
+export function resolveClientIp(req, trustProxy) {
+    if (trustProxy) {
+        const raw = req.headers['x-forwarded-for'];
+        const header = Array.isArray(raw) ? raw[0] : raw;
+        if (typeof header === 'string') {
+            for (const segment of header.split(',')) {
+                const trimmed = segment.trim();
+                if (trimmed.length > 0)
+                    return trimmed;
+            }
+        }
+    }
+    const sock = req.socket.remoteAddress;
+    return sock && sock.length > 0 ? sock : 'unknown';
+}
+export function createPairLoginRateLimitMiddleware(opts) {
+    const { limiter, logger, quotaKey, trustProxy = false } = opts;
+    return (req, res, next) => {
+        const ip = resolveClientIp(req, trustProxy);
+        const key = `${quotaKey}:${ip}`;
+        limiter
+            .check({ key })
+            .then((decision) => {
+            if (decision.allowed) {
+                next();
+                return;
+            }
+            const retryAfterSec = Math.max(1, Math.ceil((decision.retryAfterMs ?? 0) / 1000));
+            logger.info('rate_limit_hit', {
+                quotaKey,
+                ip,
+                remaining: decision.remaining,
+                retryAfterSec,
+            });
+            res
+                .status(429)
+                .setHeader('Retry-After', String(retryAfterSec))
+                .json({
+                error: {
+                    code: 'rate_limited',
+                    message: `Too many attempts. Try again in ${retryAfterSec} seconds.`,
+                    retryAfter: retryAfterSec,
+                },
+            });
+        })
+            .catch((err) => {
+            // Fail-open: limiter outages must not block auth endpoints.
+            logger.error('rate_limit_check_failed', {
+                quotaKey,
+                ip,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            next();
+        });
+    };
+}

package/dist/render-gate.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `gateShortCode` — the single chokepoint for capability-URL routes.
+ *
+ * `/r/<code>` and `/api/bootstrap/<code>` are sibling surfaces that
+ * expose the same render state via different content types (HTML
+ * shell vs JSON bootstrap envelope). Before this gate, each route
+ * implemented its own lookup + session resolve + 404 mapping, which
+ * meant: hardening one route (revoke checks, sig verify, rate limit,
+ * audit log) silently left the other unhardened. Capability URLs are
+ * the credential — drift across the two routes is a defense gap.
+ *
+ * This module centralizes the gate logic. Routes ask the gate for
+ * an outcome; content-type rendering stays on the route.
+ *
+ * Outcomes today:
+ *   - `ok` — binding lookup + session resolve both succeeded
+ *   - `not_found` — shortCode unknown OR revoked (lookup returned null)
+ *   - `session_missing` — binding present but session record absent
+ *
+ * Outcomes reserved for future slices (sig verify, rate limit, etc.):
+ *   - `invalid_signature` (HMAC slice)
+ *   - `expired` (TTL slice)
+ *   - `rate_limited` (per-code throttle slice)
+ *
+ * Each future slice extends the union; routes can map new codes to
+ * appropriate status codes (403, 410, 429) without re-implementing
+ * the lookup.
+ */
+import type { Session } from '@ggui-ai/protocol';
+import type { ShortCodeIndex } from '@ggui-ai/mcp-server-core';
+import type { RenderSigner } from './render-signing.js';
+/** Minimal SessionStore surface the gate uses — narrower than the
+ *  full interface so test fakes stay tiny. */
+interface GateSessionStore {
+    get(id: string): Promise<Session | null>;
+}
+/** The single failure surface the gate emits. New codes added here
+ *  grow the discriminated union; consumers exhaustively match. */
+export type RenderGateFailureCode = 'not_found' | 'session_missing' | 'invalid_signature' | 'expired' | 'malformed_signature';
+export type RenderGateOutcome = {
+    readonly ok: true;
+    readonly binding: NonNullable<Awaited<ReturnType<ShortCodeIndex['lookup']>>>;
+    readonly session: Session;
+} | {
+    readonly ok: false;
+    readonly code: RenderGateFailureCode;
+    /** Optional context that's safe to pass to a structured logger
+     *  but MUST NOT leak to the wire — error responses stay generic
+     *  ("shortCode not recognised") to avoid info-leak amplification
+     *  on brute-force attempts. */
+    readonly logContext?: Record<string, unknown>;
+};
+export interface GateShortCodeInput {
+    readonly shortCode: string;
+    readonly shortCodeIndex: ShortCodeIndex;
+    readonly sessionStore: GateSessionStore;
+    /**
+     * Optional render-URL signer. When wired, the gate verifies the
+     * incoming `sig`+`exp` query pair BEFORE lookup; an invalid or
+     * expired signature short-circuits with a tagged failure code so
+     * the route can map to an appropriate status (403/410). Absent =
+     * signing disabled (legacy or `--no-render-signing` boot).
+     */
+    readonly signer?: RenderSigner;
+    /**
+     * Raw `sig`+`exp` from the request query string. When `signer` is
+     * wired but these are missing, the gate fails with
+     * `malformed_signature`. When `signer` is absent, both fields are
+     * ignored.
+     */
+    readonly signedQuery?: {
+        readonly sig?: string | undefined;
+        readonly exp?: string | undefined;
+    };
+}
+/**
+ * Look up a shortCode + resolve its session. Idempotent + side-
+ * effect-free; safe to call from any HTTP handler. Returns a tagged
+ * outcome the caller maps to its content-type-appropriate response.
+ *
+ * Empty input MUST be caught upstream (path-param validation) — the
+ * gate assumes a non-empty shortCode arrives because the route
+ * pattern requires it.
+ */
+export declare function gateShortCode(input: GateShortCodeInput): Promise<RenderGateOutcome>;
+export {};
+//# sourceMappingURL=render-gate.d.ts.map

package/dist/render-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-gate.d.ts","sourceRoot":"","sources":["../src/render-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;8CAC8C;AAC9C,UAAU,gBAAgB;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC1C;AAED;kEACkE;AAClE,MAAM,MAAM,qBAAqB,GAC7B,WAAW,GACX,iBAAiB,GACjB,mBAAmB,GACnB,SAAS,GACT,qBAAqB,CAAC;AAE1B,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAC3B,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC9C,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC;;;mCAG+B;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C,CAAC;AAEN,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACnC,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAwC5B"}

package/dist/render-gate.js

@@ -0,0 +1,77 @@
+/**
+ * `gateShortCode` — the single chokepoint for capability-URL routes.
+ *
+ * `/r/<code>` and `/api/bootstrap/<code>` are sibling surfaces that
+ * expose the same render state via different content types (HTML
+ * shell vs JSON bootstrap envelope). Before this gate, each route
+ * implemented its own lookup + session resolve + 404 mapping, which
+ * meant: hardening one route (revoke checks, sig verify, rate limit,
+ * audit log) silently left the other unhardened. Capability URLs are
+ * the credential — drift across the two routes is a defense gap.
+ *
+ * This module centralizes the gate logic. Routes ask the gate for
+ * an outcome; content-type rendering stays on the route.
+ *
+ * Outcomes today:
+ *   - `ok` — binding lookup + session resolve both succeeded
+ *   - `not_found` — shortCode unknown OR revoked (lookup returned null)
+ *   - `session_missing` — binding present but session record absent
+ *
+ * Outcomes reserved for future slices (sig verify, rate limit, etc.):
+ *   - `invalid_signature` (HMAC slice)
+ *   - `expired` (TTL slice)
+ *   - `rate_limited` (per-code throttle slice)
+ *
+ * Each future slice extends the union; routes can map new codes to
+ * appropriate status codes (403, 410, 429) without re-implementing
+ * the lookup.
+ */
+/**
+ * Look up a shortCode + resolve its session. Idempotent + side-
+ * effect-free; safe to call from any HTTP handler. Returns a tagged
+ * outcome the caller maps to its content-type-appropriate response.
+ *
+ * Empty input MUST be caught upstream (path-param validation) — the
+ * gate assumes a non-empty shortCode arrives because the route
+ * pattern requires it.
+ */
+export async function gateShortCode(input) {
+    // Signature verification runs BEFORE the lookup so a flood of
+    // requests with garbage shortCodes can be rejected without hitting
+    // the index. The signer also gates information-leak: revealing
+    // "this code doesn't exist" vs "your sig is wrong" lets an
+    // attacker probe shortCodes via timing differences. Rejecting on
+    // signature first keeps the response timing uniform for any code
+    // an attacker hasn't seen a valid sig for.
+    if (input.signer) {
+        const verify = input.signer.verify({
+            shortCode: input.shortCode,
+            sig: input.signedQuery?.sig,
+            exp: input.signedQuery?.exp,
+        });
+        if (!verify.ok) {
+            return {
+                ok: false,
+                code: verify.code === 'malformed'
+                    ? 'malformed_signature'
+                    : verify.code,
+            };
+        }
+    }
+    const binding = await input.shortCodeIndex.lookup(input.shortCode);
+    if (!binding) {
+        return { ok: false, code: 'not_found' };
+    }
+    const session = await input.sessionStore.get(binding.sessionId);
+    if (!session) {
+        return {
+            ok: false,
+            code: 'session_missing',
+            logContext: {
+                shortCode: input.shortCode,
+                sessionId: binding.sessionId,
+            },
+        };
+    }
+    return { ok: true, binding, session };
+}

package/dist/render-rate-limit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-shortCode rate limiter.
+ *
+ * Brute-force attempts on `/r/<code>` or `/api/bootstrap/<code>` are
+ * trivially detected at the wire by per-shortCode call counts. Even
+ * with high-entropy shortCodes and HMAC-signed render URLs, the gate
+ * still hits a real backend on every request — so DoS resistance +
+ * abuse-signal logging matter independently of entropy.
+ *
+ * **Design choice — rate-limit by shortCode, not by peer.**
+ * Cross-origin iframes (claude.ai) NAT every user through the host's
+ * outbound proxy, so per-peer limits would either rate-limit the whole
+ * host (false-positive flood) or accept every peer (no signal). Per-
+ * shortCode is the right granularity: 30 hits/minute on a single
+ * code is abuse no matter who sent them; 30 hits/minute spread across
+ * 30 unique codes is normal traffic.
+ *
+ * In-memory + per-process by default. Operator-grade deployments
+ * back this with a shared store (Redis bucket counter) — wire via the
+ * {@link RenderRateLimiter} interface; the OSS reference uses a
+ * `Map<shortCode, {windowStart, count}>` with periodic cleanup.
+ */
+/** Configuration knobs. Operators tune via boot options. */
+export interface RenderRateLimiterConfig {
+    /** Window size in seconds. Each shortCode gets `limit` hits per
+     *  rolling window. Default 60s. */
+    readonly windowSeconds?: number;
+    /** Per-shortCode hit cap inside the window. Default 30. */
+    readonly limit?: number;
+    /** Clock seam for tests. */
+    readonly now?: () => number;
+}
+export type RenderRateLimitResult = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly retryAfterSeconds: number;
+};
+export interface RenderRateLimiter {
+    /** Record a hit on `shortCode`. Returns the gate decision + (when
+     *  rejected) a Retry-After hint in seconds. */
+    check(shortCode: string): RenderRateLimitResult;
+}
+/**
+ * In-memory reference implementation. Cleanup runs lazily on each
+ * call — entries past their window-end are reaped before the count is
+ * read. Worst-case heap: bounded by the number of distinct shortCodes
+ * hit within the last `windowSeconds`; pre-launch OSS workloads stay
+ * tiny enough that the periodic pass is sufficient.
+ */
+export declare function createInMemoryRenderRateLimiter(cfg?: RenderRateLimiterConfig): RenderRateLimiter;
+/**
+ * Mask a shortCode for log output. The full code is the credential —
+ * log it verbatim and a leaked log line becomes a leaked URL. Show
+ * just enough (first 3 chars) to correlate within a session without
+ * giving the credential away.
+ */
+export declare function maskShortCode(shortCode: string): string;
+//# sourceMappingURL=render-rate-limit.d.ts.map

package/dist/render-rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-rate-limit.d.ts","sourceRoot":"","sources":["../src/render-rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC;uCACmC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC;mDAC+C;IAC/C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,GAAE,uBAA4B,GAChC,iBAAiB,CAmCnB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIvD"}