sliccy 4.3.1 → 4.4.0

package/dist/node-server/routes/fetch-proxy.d.ts

@@ -0,0 +1,12 @@
+import type { Express } from 'express';
+import type { SecretProxyManager } from '../secrets/proxy-manager.js';
+export interface FetchProxyDeps {
+    secretProxy: SecretProxyManager;
+}
+/**
+ * Fetch proxy — forwards cross-origin requests from the browser to bypass
+ * CORS (used by just-bash's curl, which calls the browser's fetch() API).
+ * Note: express.json() may already have parsed the body, so collectRawBody
+ * checks req.body first.
+ */
+export declare function registerFetchProxyRoute(app: Express, deps: FetchProxyDeps): void;

package/dist/node-server/routes/fetch-proxy.js

@@ -0,0 +1,316 @@
+import { Readable, Transform } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+import { FETCH_PROXY_SKIP_HEADERS } from '../fetch-proxy-headers.js';
+/** Pick the first value of a possibly-multi-valued request header. */
+function firstHeaderValue(value) {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/** True when an origin/referer value points at localhost (any family). */
+function isLocalhostOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const url = new URL(origin);
+        return (url.hostname === 'localhost' ||
+            url.hostname === '127.0.0.1' ||
+            url.hostname === '::1' ||
+            url.hostname === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+/** Get the body — either from express.json()'s parsed body or raw chunks. */
+async function collectRawBody(req) {
+    if (req.body && typeof req.body === 'object' && Object.keys(req.body).length > 0) {
+        // Body was already parsed by express.json() — re-serialize it.
+        return Buffer.from(JSON.stringify(req.body), 'utf-8');
+    }
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Build the forwarded header set: copy non-hop-by-hop headers, then restore
+ * the forbidden-header transports (Cookie/Origin/Referer/Proxy-*) the browser
+ * could not send via fetch(), and force an identity encoding.
+ */
+function buildForwardHeaders(req, targetUrl) {
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (!FETCH_PROXY_SKIP_HEADERS.has(key) && typeof value === 'string') {
+            headers[key] = value;
+        }
+    }
+    // Forbidden-header transport: browser cannot send Cookie via fetch(),
+    // so the client encodes it as X-Proxy-Cookie. Restore it here.
+    const proxyCookie = firstHeaderValue(req.headers['x-proxy-cookie']);
+    if (proxyCookie)
+        headers.cookie = proxyCookie;
+    // Forbidden-header transport: restore X-Proxy-Origin → Origin
+    const proxyOrigin = firstHeaderValue(req.headers['x-proxy-origin']);
+    if (proxyOrigin) {
+        headers.origin = proxyOrigin;
+    }
+    else if (isLocalhostOrigin(headers.origin)) {
+        // Only strip the browser's auto-added localhost origin; preserve legitimate origins.
+        delete headers.origin;
+    }
+    // Default-Origin fallback: synthesize one from the target URL so upstream
+    // CORS-protected APIs see a real Origin instead of nothing.
+    if (!headers.origin) {
+        try {
+            headers.origin = new URL(targetUrl).origin;
+        }
+        catch {
+            // Malformed targetUrl — leave origin unset; the upstream fetch fails anyway.
+        }
+    }
+    // Forbidden-header transport: restore X-Proxy-Referer → Referer
+    const proxyReferer = firstHeaderValue(req.headers['x-proxy-referer']);
+    if (proxyReferer) {
+        headers.referer = proxyReferer;
+    }
+    else if (isLocalhostOrigin(headers.referer)) {
+        delete headers.referer;
+    }
+    // Restore any X-Proxy-Proxy-* transport headers as Proxy-* headers
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (key.startsWith('x-proxy-proxy-') && typeof value === 'string') {
+            headers[key.replace(/^x-proxy-/, '')] = value;
+            delete headers[key];
+        }
+    }
+    // Always request uncompressed responses — the proxy doesn't decompress and
+    // the browser→proxy hop is localhost, so compression has no benefit and
+    // would arrive as garbage once Content-Encoding is stripped below.
+    headers['accept-encoding'] = 'identity';
+    return headers;
+}
+/**
+ * Apply request-side secret injection: unmask headers and URL-embedded
+ * credentials. Mutates `headers` to attach a synthetic Authorization when the
+ * URL carried credentials. Returns the forbidden descriptor when a masked
+ * secret is used against a domain it is not scoped to, else the cleaned URL.
+ */
+function injectRequestSecrets(secretProxy, headers, targetUrl, targetHostname) {
+    if (!secretProxy.hasSecrets())
+        return { cleanedUrl: targetUrl };
+    const headerResult = secretProxy.unmaskHeaders(headers, targetHostname);
+    if (headerResult.forbidden)
+        return { forbidden: headerResult.forbidden };
+    const credsResult = secretProxy.extractAndUnmaskUrlCredentials(targetUrl);
+    if (credsResult.forbidden)
+        return { forbidden: credsResult.forbidden };
+    // Attach synthetic Authorization if the URL had credentials and the header isn't already set.
+    if (credsResult.syntheticAuthorization && !('authorization' in headers)) {
+        headers.authorization = credsResult.syntheticAuthorization;
+    }
+    return { cleanedUrl: credsResult.url };
+}
+/**
+ * Unmask masked secrets in a text request body. Non-text bodies (git
+ * packfiles, octet-stream, images, …) are left untouched — `toString('utf-8')`
+ * on arbitrary bytes corrupts them, and masked values never appear in binary.
+ */
+function unmaskRequestBody(secretProxy, headers, rawBody, targetHostname) {
+    const reqCt = (headers['content-type'] ?? headers['Content-Type'] ?? '').toLowerCase();
+    const reqIsText = !reqCt ||
+        reqCt.startsWith('text/') ||
+        reqCt.includes('json') ||
+        reqCt.includes('xml') ||
+        reqCt.includes('javascript') ||
+        reqCt.includes('ecmascript') ||
+        reqCt.includes('html') ||
+        reqCt.includes('css') ||
+        reqCt.includes('svg');
+    if (reqIsText && secretProxy.hasSecrets()) {
+        const bodyResult = secretProxy.unmaskBody(rawBody.toString('utf-8'), targetHostname);
+        return Buffer.from(bodyResult.text, 'utf-8');
+    }
+    return rawBody;
+}
+/**
+ * Forward the upstream status + response headers, stripping hop-by-hop and
+ * www-authenticate (so the browser shows no native Basic Auth dialog) and
+ * relaying Set-Cookie out-of-band as X-Proxy-Set-Cookie. All header values are
+ * secret-scrubbed.
+ */
+function forwardUpstreamHeaders(res, upstream, secretProxy) {
+    res.status(upstream.status);
+    res.setHeader('Cache-Control', 'no-store, no-cache');
+    const setCookieValues = upstream.headers.getSetCookie();
+    upstream.headers.forEach((v, k) => {
+        const lower = k.toLowerCase();
+        if (lower !== 'transfer-encoding' &&
+            lower !== 'content-encoding' &&
+            lower !== 'content-length' &&
+            lower !== 'www-authenticate' &&
+            lower !== 'set-cookie' &&
+            !lower.startsWith('x-proxy-')) {
+            // Headers are small — one-shot scrub, no per-chunk semantics.
+            res.setHeader(k, secretProxy.scrubResponse(v));
+        }
+    });
+    if (setCookieValues.length > 0) {
+        res.setHeader('X-Proxy-Set-Cookie', secretProxy.scrubResponse(JSON.stringify(setCookieValues)));
+    }
+}
+/**
+ * Buffer-aware UTF-8 secret scrubber. A `StringDecoder` keeps trailing partial
+ * multi-byte sequences out of the scrub so codepoints straddling a chunk
+ * boundary aren't corrupted (fatal for CJK/emoji model output). Pass-through
+ * when the body is non-text or no secrets are configured.
+ */
+function createScrubStream(secretProxy, isText) {
+    const utf8Decoder = new StringDecoder('utf8');
+    return new Transform({
+        transform(chunk, _enc, cb) {
+            if (!isText || !secretProxy.hasSecrets()) {
+                cb(null, chunk);
+                return;
+            }
+            try {
+                const decoded = utf8Decoder.write(chunk);
+                if (decoded.length === 0) {
+                    // All bytes buffered as a partial codepoint — no output yet.
+                    cb(null, Buffer.alloc(0));
+                    return;
+                }
+                cb(null, Buffer.from(secretProxy.scrubResponse(decoded), 'utf-8'));
+            }
+            catch (err) {
+                cb(err);
+            }
+        },
+        flush(cb) {
+            if (!isText || !secretProxy.hasSecrets()) {
+                cb();
+                return;
+            }
+            try {
+                const tail = utf8Decoder.end();
+                if (tail.length === 0) {
+                    cb();
+                    return;
+                }
+                cb(null, Buffer.from(secretProxy.scrubResponse(tail), 'utf-8'));
+            }
+            catch (err) {
+                cb(err);
+            }
+        },
+    });
+}
+/** Stream the upstream body to the client through the secret-scrub transform. */
+function streamUpstreamBody(res, upstream, secretProxy, detachClientClose) {
+    const ct = (upstream.headers.get('content-type') ?? '').toLowerCase();
+    const isText = ct.startsWith('text/') ||
+        ct.startsWith('application/json') ||
+        ct.includes('charset=') ||
+        ct.includes('event-stream');
+    const upstreamStream = Readable.fromWeb(upstream.body);
+    const scrubChunk = createScrubStream(secretProxy, isText);
+    upstreamStream.on('error', (err) => {
+        detachClientClose();
+        if (!res.headersSent) {
+            res.setHeader('X-Proxy-Error', '1');
+            res
+                .status(502)
+                .json({ error: `Proxy stream failed: ${err instanceof Error ? err.message : err}` });
+        }
+        else {
+            res.destroy(err);
+        }
+    });
+    // Belt-and-braces cleanup: 'finish' fires once the response is fully flushed;
+    // 'close' fires regardless of how the response ended. Either way the abort
+    // listener should be gone.
+    res.on('finish', detachClientClose);
+    res.on('close', detachClientClose);
+    upstreamStream.pipe(scrubChunk).pipe(res);
+}
+/**
+ * Fetch proxy — forwards cross-origin requests from the browser to bypass
+ * CORS (used by just-bash's curl, which calls the browser's fetch() API).
+ * Note: express.json() may already have parsed the body, so collectRawBody
+ * checks req.body first.
+ */
+export function registerFetchProxyRoute(app, deps) {
+    const { secretProxy } = deps;
+    app.all('/api/fetch-proxy', async (req, res) => {
+        const rawBody = await collectRawBody(req);
+        const targetUrl = req.headers['x-target-url'];
+        if (!targetUrl) {
+            res.setHeader('X-Proxy-Error', '1');
+            res.status(400).json({ error: 'Missing X-Target-URL header' });
+            return;
+        }
+        // Hoisted so the catch handler can detach it on early failures (e.g. fetch
+        // threw before the success-path detach could run).
+        let onClientClose = null;
+        const detachClientClose = () => {
+            if (onClientClose) {
+                res.off('close', onClientClose);
+                onClientClose = null;
+            }
+        };
+        try {
+            const fetchInit = { method: req.method, redirect: 'follow' };
+            const headers = buildForwardHeaders(req, targetUrl);
+            let targetHostname;
+            try {
+                targetHostname = new URL(targetUrl).hostname;
+            }
+            catch {
+                targetHostname = '';
+            }
+            const injection = injectRequestSecrets(secretProxy, headers, targetUrl, targetHostname);
+            if ('forbidden' in injection) {
+                res.setHeader('X-Proxy-Error', '1');
+                res.status(403).json({
+                    error: `Secret "${injection.forbidden.secretName}" is not allowed for domain "${injection.forbidden.hostname}"`,
+                });
+                return;
+            }
+            if (Object.keys(headers).length > 0)
+                fetchInit.headers = headers;
+            if (rawBody.length > 0 && !['GET', 'HEAD'].includes(req.method)) {
+                const body = unmaskRequestBody(secretProxy, headers, rawBody, targetHostname);
+                // Buffer extends Uint8Array which is a valid fetch body at runtime.
+                fetchInit.body = body;
+            }
+            // Propagate client disconnect to the upstream request so long-lived
+            // streams (LLM SSE completions) are torn down promptly. Listen on
+            // `res.on('close')`, not `req.on('close')` — Node fires req close as soon
+            // as the request body is consumed, which would abort before fetch starts.
+            const abortController = new AbortController();
+            onClientClose = () => {
+                if (!res.writableEnded)
+                    abortController.abort();
+            };
+            res.on('close', onClientClose);
+            fetchInit.signal = abortController.signal;
+            const upstream = await fetch(injection.cleanedUrl, fetchInit);
+            forwardUpstreamHeaders(res, upstream, secretProxy);
+            if (!upstream.body) {
+                res.end();
+                detachClientClose();
+                return;
+            }
+            streamUpstreamBody(res, upstream, secretProxy, detachClientClose);
+        }
+        catch (err) {
+            // Best-effort cleanup so an early failure doesn't leave the close
+            // listener attached to the response object.
+            detachClientClose();
+            const message = err instanceof Error ? err.message : String(err);
+            res.setHeader('X-Proxy-Error', '1');
+            res.status(502).json({ error: `Proxy fetch failed: ${message}` });
+        }
+    });
+}

package/dist/node-server/routes/handoff.d.ts

@@ -0,0 +1,48 @@
+import type { Express } from 'express';
+/**
+ * Profile-independent handoff injection.
+ *
+ * The CDP navigation-watcher only sees tabs inside the Chrome instance
+ * SLICC launched (isolated profile keyed by port); similarly the
+ * extension's webRequest observer only fires inside the profile where it
+ * is installed. External tools (e.g. the slicc-handoff helper) post here
+ * so a handoff reaches the cone regardless of which browser profile the
+ * user is currently driving.
+ *
+ * The payload mirrors the parsed RFC 8288 `Link` form used by the
+ * observers: `verb` ∈ {handoff, upskill}, `target` is the resolved URL,
+ * `instruction` is optional free-form prose (handoff verb).
+ */
+export interface HandoffPayload {
+    verb?: unknown;
+    target?: unknown;
+    instruction?: unknown;
+    url?: unknown;
+    title?: unknown;
+    branch?: unknown;
+    path?: unknown;
+    sliccHeader?: unknown;
+}
+export interface NavigateEvent {
+    type: 'navigate_event';
+    verb: 'handoff' | 'upskill';
+    target: string;
+    instruction?: string;
+    url: string;
+    title?: string;
+    branch?: string;
+    path?: string;
+    timestamp: string;
+}
+export interface HandoffRouteDeps {
+    broadcastLickEvent(event: unknown): void;
+}
+/**
+ * Validate an inbound handoff payload. Returns an error message when the
+ * payload is malformed, or `null` when it is well-formed and ready to be
+ * turned into a navigate event. Pure — no I/O.
+ */
+export declare function validateHandoffPayload(payload: HandoffPayload): string | null;
+/** Build the navigate event broadcast to the browser. Assumes a valid payload. */
+export declare function buildNavigateEvent(payload: HandoffPayload): NavigateEvent;
+export declare function registerHandoffRoute(app: Express, deps: HandoffRouteDeps): void;

package/dist/node-server/routes/handoff.js

@@ -0,0 +1,60 @@
+/**
+ * Validate an inbound handoff payload. Returns an error message when the
+ * payload is malformed, or `null` when it is well-formed and ready to be
+ * turned into a navigate event. Pure — no I/O.
+ */
+export function validateHandoffPayload(payload) {
+    if (typeof payload?.sliccHeader === 'string') {
+        return 'The legacy `sliccHeader` payload was removed; post `{ verb, target, instruction? }` instead. See docs/slicc-handoff.md.';
+    }
+    if (payload?.verb !== 'handoff' && payload?.verb !== 'upskill') {
+        return 'verb must be "handoff" or "upskill"';
+    }
+    if (typeof payload.target !== 'string' || payload.target.length === 0) {
+        return 'target is required (non-empty string)';
+    }
+    if (payload.instruction != null && typeof payload.instruction !== 'string') {
+        return 'instruction must be a string when provided';
+    }
+    // `branch` / `path` mirror the upskill rel's Link params and are
+    // ignored on the handoff verb (its target is the page itself, not a
+    // repo). Reject the wrong-shape combo loudly so emitters notice
+    // rather than silently dropping the scope.
+    if (payload.branch != null && typeof payload.branch !== 'string') {
+        return 'branch must be a string when provided';
+    }
+    if (payload.path != null && typeof payload.path !== 'string') {
+        return 'path must be a string when provided';
+    }
+    if (payload.verb === 'handoff' && (payload.branch != null || payload.path != null)) {
+        return 'branch and path are only valid with verb="upskill"';
+    }
+    return null;
+}
+/** Build the navigate event broadcast to the browser. Assumes a valid payload. */
+export function buildNavigateEvent(payload) {
+    const optionalString = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+    return {
+        type: 'navigate_event',
+        verb: payload.verb,
+        target: payload.target,
+        instruction: typeof payload.instruction === 'string' ? payload.instruction : undefined,
+        url: optionalString(payload.url) ?? 'about:handoff',
+        title: typeof payload.title === 'string' ? payload.title : undefined,
+        branch: optionalString(payload.branch),
+        path: optionalString(payload.path),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function registerHandoffRoute(app, deps) {
+    app.post('/api/handoff', (req, res) => {
+        const payload = req.body;
+        const error = validateHandoffPayload(payload);
+        if (error) {
+            res.status(400).json({ error });
+            return;
+        }
+        deps.broadcastLickEvent(buildNavigateEvent(payload));
+        res.json({ ok: true });
+    });
+}

package/dist/node-server/routes/lick-api.d.ts

@@ -0,0 +1,7 @@
+import type { Express } from 'express';
+import type { LickBridge } from './lick-bridge.js';
+/**
+ * Routes that forward to the connected browser over the lick bridge:
+ * tray status, webhook management + receiver, and cron task management.
+ */
+export declare function registerLickApiRoutes(app: Express, bridge: LickBridge): void;

package/dist/node-server/routes/lick-api.js

@@ -0,0 +1,129 @@
+/** 503 with the underlying message, or the standard "Browser not connected". */
+function respondBrowserUnavailable(res, err) {
+    res.status(503).json({ error: err instanceof Error ? err.message : 'Browser not connected' });
+}
+/**
+ * Routes that forward to the connected browser over the lick bridge:
+ * tray status, webhook management + receiver, and cron task management.
+ */
+export function registerLickApiRoutes(app, bridge) {
+    const { sendLickRequest, broadcastLickEvent } = bridge;
+    // Tray status API — forwards to browser to get leader tray join info
+    app.get('/api/tray-status', async (_req, res) => {
+        try {
+            const data = await sendLickRequest('tray_status', {});
+            res.json(data);
+        }
+        catch (err) {
+            respondBrowserUnavailable(res, err);
+        }
+    });
+    // Webhook management API — forwards to browser
+    app.get('/api/webhooks', async (_req, res) => {
+        try {
+            const data = await sendLickRequest('list_webhooks', {});
+            res.json(data);
+        }
+        catch (err) {
+            respondBrowserUnavailable(res, err);
+        }
+    });
+    app.post('/api/webhooks', async (req, res) => {
+        try {
+            const data = await sendLickRequest('create_webhook', req.body);
+            res.json(data);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res.status(msg.includes('Invalid') ? 400 : 503).json({ error: msg });
+        }
+    });
+    app.delete('/api/webhooks/:id', async (req, res) => {
+        try {
+            const data = (await sendLickRequest('delete_webhook', { id: req.params.id }));
+            if (data.error) {
+                res.status(404).json({ error: data.error });
+            }
+            else {
+                res.json(data);
+            }
+        }
+        catch (err) {
+            respondBrowserUnavailable(res, err);
+        }
+    });
+    // Webhook receiver — handle CORS preflight
+    app.options('/webhooks/:id', (_req, res) => {
+        res.set({
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'POST, OPTIONS',
+            'Access-Control-Allow-Headers': 'Content-Type',
+        });
+        res.sendStatus(204);
+    });
+    // Webhook receiver — forwards POST to browser for processing
+    app.post('/webhooks/:id', async (req, res) => {
+        res.set({ 'Access-Control-Allow-Origin': '*' });
+        const { id } = req.params;
+        // Collect body
+        let body = req.body;
+        if (!body || Object.keys(body).length === 0) {
+            const chunks = [];
+            for await (const chunk of req) {
+                chunks.push(Buffer.from(chunk));
+            }
+            const raw = Buffer.concat(chunks).toString('utf-8');
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                body = { raw };
+            }
+        }
+        // Forward to browser for processing
+        broadcastLickEvent({
+            type: 'webhook_event',
+            webhookId: id,
+            timestamp: new Date().toISOString(),
+            headers: req.headers,
+            body,
+        });
+        res.json({ ok: true, received: true });
+    });
+    // Cron task management API — forwards to browser
+    app.get('/api/crontasks', async (_req, res) => {
+        try {
+            const data = await sendLickRequest('list_crontasks', {});
+            res.json(data);
+        }
+        catch (err) {
+            respondBrowserUnavailable(res, err);
+        }
+    });
+    app.post('/api/crontasks', async (req, res) => {
+        try {
+            const data = await sendLickRequest('create_crontask', req.body);
+            res.json(data);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res
+                .status(msg.includes('Invalid') || msg.includes('required') ? 400 : 503)
+                .json({ error: msg });
+        }
+    });
+    app.delete('/api/crontasks/:id', async (req, res) => {
+        try {
+            const data = (await sendLickRequest('delete_crontask', { id: req.params.id }));
+            if (data.error) {
+                res.status(404).json({ error: data.error });
+            }
+            else {
+                res.json(data);
+            }
+        }
+        catch (err) {
+            respondBrowserUnavailable(res, err);
+        }
+    });
+}

package/dist/node-server/routes/lick-bridge.d.ts

@@ -0,0 +1,16 @@
+import { WebSocketServer } from 'ws';
+/**
+ * Lick system — WebSocket bridge for webhooks/crontasks. All the actual
+ * logic lives in the browser; this bridge is the request/response and
+ * broadcast transport between the CLI's HTTP routes and the connected
+ * browser client(s).
+ */
+export interface LickBridge {
+    /** noServer WebSocketServer — the caller wires `/licks-ws` upgrades to it. */
+    lickWss: WebSocketServer;
+    /** Send a request to the browser and wait for its response. */
+    sendLickRequest(type: string, data: unknown, timeout?: number): Promise<unknown>;
+    /** Broadcast an event to all connected browsers (no response expected). */
+    broadcastLickEvent(event: unknown): void;
+}
+export declare function createLickBridge(): LickBridge;

package/dist/node-server/routes/lick-bridge.js

@@ -0,0 +1,73 @@
+import { WebSocket, WebSocketServer } from 'ws';
+export function createLickBridge() {
+    const lickWss = new WebSocketServer({ noServer: true });
+    const lickClients = new Set();
+    const pendingRequests = new Map();
+    let requestIdCounter = 0;
+    lickWss.on('connection', (ws) => {
+        lickClients.add(ws);
+        console.log('[licks] Browser client connected');
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                // Handle responses to pending requests
+                if (msg.type === 'response' && msg.requestId) {
+                    const pending = pendingRequests.get(msg.requestId);
+                    if (pending) {
+                        pendingRequests.delete(msg.requestId);
+                        if (msg.error) {
+                            pending.reject(new Error(msg.error));
+                        }
+                        else {
+                            pending.resolve(msg.data);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore invalid messages
+            }
+        });
+        ws.on('close', () => {
+            lickClients.delete(ws);
+            console.log('[licks] Browser client disconnected');
+        });
+    });
+    function sendLickRequest(type, data, timeout = 5000) {
+        return new Promise((resolve, reject) => {
+            const requestId = `req_${++requestIdCounter}`;
+            const msg = JSON.stringify({ type, requestId, ...data });
+            // Find a connected client
+            const client = Array.from(lickClients).find((c) => c.readyState === WebSocket.OPEN);
+            if (!client) {
+                reject(new Error('No browser connected'));
+                return;
+            }
+            // Set up timeout
+            const timer = setTimeout(() => {
+                pendingRequests.delete(requestId);
+                reject(new Error('Request timeout'));
+            }, timeout);
+            pendingRequests.set(requestId, {
+                resolve: (data) => {
+                    clearTimeout(timer);
+                    resolve(data);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            client.send(msg);
+        });
+    }
+    function broadcastLickEvent(event) {
+        const msg = JSON.stringify(event);
+        for (const client of lickClients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(msg);
+            }
+        }
+    }
+    return { lickWss, sendLickRequest, broadcastLickEvent };
+}

package/dist/node-server/routes/oauth-callback.d.ts

@@ -0,0 +1,11 @@
+import { type Express } from 'express';
+/**
+ * Generic OAuth redirect target for OAuth providers (implicit + PKCE).
+ *
+ * The callback page tries `window.opener.postMessage` first (works in the
+ * CLI popup flow). When `window.opener` is null (Electron overlay opens the
+ * system browser), it falls back to POSTing the result to
+ * `/api/oauth-result`, which the UI polls via the GET counterpart — the
+ * server holds the single pending result in memory between the two calls.
+ */
+export declare function registerOAuthCallbackRoutes(app: Express): void;