sliccy 4.23.0 → 4.25.0

package/dist/node-server/bridge-security.d.ts

@@ -23,6 +23,12 @@
  * origins (parallel to chrome-extension's `BRIDGE_DEV_ORIGINS`). Add a new
  * origin here and in the extension allowlist together — they MUST stay in
  * sync, otherwise extension and standalone disagree on what's a leader.
+ *
+ * Dev-only extra origins can be added at process start via the
+ * `BRIDGE_DEV_ALLOWED_ORIGINS` env var (comma-separated). Used by the
+ * local two-service harness (wrangler dev UI on :8787 + node-server
+ * bridge); see Wave 5c. When the env var is unset, the effective
+ * allowlist is byte-identical to this frozen base — prod is unaffected.
  */
 export declare const BRIDGE_ALLOWED_ORIGINS: readonly string[];
 /** Subprotocol prefix advertised by the leader; the per-process token is appended. */
@@ -31,8 +37,40 @@ export declare const BRIDGE_SUBPROTOCOL_PREFIX = "slicc.bridge.v1.";
 export declare const BRIDGE_TOKEN_QUERY_PARAM = "bridgeToken";
 /** Query-param name the launch URL uses to forward the local /cdp WebSocket URL. */
 export declare const BRIDGE_WS_QUERY_PARAM = "bridge";
-/** True iff `origin` is in the bridge allowlist. Case-sensitive (origins are normalized lowercase). */
+/**
+ * Request header carrying the per-process bridge token on cross-origin
+ * /api/* calls from a remote allowlisted leader (e.g. sliccy.ai). The
+ * webapp's `proxied-fetch.ts` attaches it whenever a local API base
+ * origin is set; the thin-bridge CORS middleware validates it. Header
+ * is included in `CORS_BASE_ALLOW_HEADERS` so browsers don't strip it
+ * on the preflight.
+ */
+export declare const BRIDGE_TOKEN_HEADER = "X-Bridge-Token";
+/**
+ * True iff `origin` is in the bridge allowlist. The frozen prod base
+ * (`BRIDGE_ALLOWED_ORIGINS`) is matched case-sensitively against the
+ * raw origin; the dev-only env-supplied extras (normalized lowercase
+ * + trailing-slash-stripped at load) are matched against a normalized
+ * copy of the input, so a leader sending `Origin: HTTP://Localhost:8787`
+ * (or with a stray trailing slash) still resolves correctly.
+ */
 export declare function isAllowedBridgeOrigin(origin: string | undefined | null): boolean;
+/**
+ * True iff `origin` is a loopback host (localhost / 127.0.0.1 / ::1).
+ * Loopback allowlisted origins (e.g. the locally-served OAuth callback
+ * page at `http://localhost:5710/auth/callback` posting to
+ * `/api/oauth-result`) are exempt from the bridge-token requirement —
+ * the token's threat model is "remote allowlisted origin (sliccy.ai)
+ * with a hostile script", not "local server talking to itself".
+ */
+export declare function isLoopbackBridgeOrigin(origin: string | undefined | null): boolean;
+/**
+ * Constant-time compare for the bridge token. `presented` may be missing
+ * or shaped wrong (Express delivers headers as `string | string[] |
+ * undefined`). Returns `false` for any non-string, length mismatch, or
+ * empty expected — never throws.
+ */
+export declare function validateBridgeToken(presented: string | string[] | undefined, expected: string | null): boolean;
 /**
  * Mint a per-process bridge token. Embedded in the leader launch URL and
  * required as the WebSocket subprotocol on /cdp. Use `crypto.randomUUID()`
@@ -77,6 +115,18 @@ export declare function validateBridgeUpgrade(input: {
     subprotocolHeader: string | string[] | undefined;
     expectedToken: string;
 }): BridgeUpgradeGateResult;
+/**
+ * Resolve the `Access-Control-Allow-Headers` value for a request. Starts
+ * from `CORS_BASE_ALLOW_HEADERS` (the static set covering the documented
+ * /api endpoints + the `/api/fetch-proxy` transport headers) and unions
+ * in any header names from the request's `Access-Control-Request-Headers`
+ * that aren't already listed. This is the reflect-headers pattern: the
+ * agent's `bash curl -H X-Custom: …` can route through `/api/fetch-proxy`
+ * cross-origin without us having to enumerate every possible upstream
+ * header in advance. Comparison is case-insensitive; the static set's
+ * canonical casing wins on duplicates.
+ */
+export declare function resolveCorsAllowHeaders(requestHeadersHeader: string | undefined | null): string;
 /**
  * CORS headers for an allowlisted `Origin`. Returns `null` when the origin
  * is not in the allowlist (caller should NOT set CORS headers).
@@ -84,8 +134,12 @@ export declare function validateBridgeUpgrade(input: {
  * `Access-Control-Allow-Credentials: true` is included so the hosted leader
  * can carry cookies to /api/* (e.g. auth) when that's added later. Today
  * the bridge token is the auth factor, not cookies.
+ *
+ * `requestHeadersHeader` should be the request's `Access-Control-Request-Headers`
+ * value (preflight only); on a non-preflight request pass `null` and the
+ * caller can omit it.
  */
-export declare function buildCorsHeaders(origin: string | undefined | null): Record<string, string> | null;
+export declare function buildCorsHeaders(origin: string | undefined | null, requestHeadersHeader?: string | string[] | null): Record<string, string> | null;
 /**
  * PNA preflight extras. Added on OPTIONS responses for allowlisted origins
  * when the request carries `Access-Control-Request-Private-Network: true`

package/dist/node-server/bridge-security.js

@@ -18,12 +18,18 @@
  * Pure module (no node-only imports) so the WS gate is trivially unit
  * testable from `tests/bridge-security.test.ts`.
  */
-import { randomUUID } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 /**
  * Origin allowlist. Production + staging worker plus the dev-mode loopback
  * origins (parallel to chrome-extension's `BRIDGE_DEV_ORIGINS`). Add a new
  * origin here and in the extension allowlist together — they MUST stay in
  * sync, otherwise extension and standalone disagree on what's a leader.
+ *
+ * Dev-only extra origins can be added at process start via the
+ * `BRIDGE_DEV_ALLOWED_ORIGINS` env var (comma-separated). Used by the
+ * local two-service harness (wrangler dev UI on :8787 + node-server
+ * bridge); see Wave 5c. When the env var is unset, the effective
+ * allowlist is byte-identical to this frozen base — prod is unaffected.
  */
 export const BRIDGE_ALLOWED_ORIGINS = Object.freeze([
     'https://www.sliccy.ai',
@@ -31,21 +37,155 @@ export const BRIDGE_ALLOWED_ORIGINS = Object.freeze([
     'http://localhost:5710',
     'http://127.0.0.1:5710',
 ]);
+/**
+ * Normalize a single env-supplied origin: trim, lowercase, drop trailing
+ * slash. Returns `null` for blank/whitespace entries or anything that
+ * `URL` can't parse. Never throws.
+ */
+function normalizeDevOrigin(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    let candidate = trimmed.toLowerCase();
+    while (candidate.endsWith('/')) {
+        candidate = candidate.slice(0, -1);
+    }
+    if (!candidate)
+        return null;
+    try {
+        // Sanity check: must parse as an absolute URL with scheme + host.
+        const parsed = new URL(candidate);
+        if (!parsed.protocol || !parsed.hostname)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return candidate;
+}
+/**
+ * Dev-only extra origins parsed once from `BRIDGE_DEV_ALLOWED_ORIGINS` at
+ * module load. Comma-separated; blank entries ignored; malformed entries
+ * dropped. Frozen prod base above is left intact; `isAllowedBridgeOrigin`
+ * consults the union.
+ */
+const BRIDGE_DEV_ALLOWED_ORIGINS = (() => {
+    const raw = process.env.BRIDGE_DEV_ALLOWED_ORIGINS;
+    if (!raw)
+        return new Set();
+    const set = new Set();
+    for (const entry of raw.split(',')) {
+        const normalized = normalizeDevOrigin(entry);
+        if (normalized)
+            set.add(normalized);
+    }
+    return set;
+})();
 /** Subprotocol prefix advertised by the leader; the per-process token is appended. */
 export const BRIDGE_SUBPROTOCOL_PREFIX = 'slicc.bridge.v1.';
 /** Query-param name the launch URL uses to forward the subprotocol token to the leader. */
 export const BRIDGE_TOKEN_QUERY_PARAM = 'bridgeToken';
 /** Query-param name the launch URL uses to forward the local /cdp WebSocket URL. */
 export const BRIDGE_WS_QUERY_PARAM = 'bridge';
-/** Headers we allow on cross-origin /api requests from the hosted leader. */
-const CORS_ALLOW_HEADERS = 'Content-Type, X-Slicc-Raw-Body, X-Session-Id, X-Bridge-Token, Authorization';
+/**
+ * Request header carrying the per-process bridge token on cross-origin
+ * /api/* calls from a remote allowlisted leader (e.g. sliccy.ai). The
+ * webapp's `proxied-fetch.ts` attaches it whenever a local API base
+ * origin is set; the thin-bridge CORS middleware validates it. Header
+ * is included in `CORS_BASE_ALLOW_HEADERS` so browsers don't strip it
+ * on the preflight.
+ */
+export const BRIDGE_TOKEN_HEADER = 'X-Bridge-Token';
+/**
+ * Headers we allow on cross-origin /api requests from the hosted leader.
+ * Includes the `/api/fetch-proxy` transport headers (`X-Target-URL`, the
+ * forbidden-header `X-Proxy-*` bridges, `X-Slicc-Raw-Body`) so the
+ * webapp's `createProxiedFetch` can route through the local node-server
+ * cross-origin in thin-bridge mode. Custom upstream headers (any header
+ * the agent's `curl -H …` would pass through) are reflected via
+ * `Access-Control-Request-Headers` in `buildCorsHeaders` below.
+ */
+const CORS_BASE_ALLOW_HEADERS = [
+    'Content-Type',
+    'X-Slicc-Raw-Body',
+    'X-Session-Id',
+    'X-Bridge-Token',
+    'Authorization',
+    'X-Target-URL',
+    'X-Proxy-Cookie',
+    'X-Proxy-Origin',
+    'X-Proxy-Referer',
+];
+/**
+ * Response headers the browser is allowed to read after a cross-origin
+ * /api call — must include the proxy's infrastructure-error marker
+ * (`isProxyError` reads `X-Proxy-Error`) and the forbidden-response
+ * bridge (`decodeForbiddenResponseHeaders` reads `X-Proxy-Set-Cookie`).
+ */
+const CORS_EXPOSE_HEADERS = 'Link, X-Proxy-Error, X-Proxy-Set-Cookie';
 /** Methods exposed to the hosted leader. */
 const CORS_ALLOW_METHODS = 'GET, POST, PUT, DELETE, OPTIONS';
-/** True iff `origin` is in the bridge allowlist. Case-sensitive (origins are normalized lowercase). */
+/**
+ * True iff `origin` is in the bridge allowlist. The frozen prod base
+ * (`BRIDGE_ALLOWED_ORIGINS`) is matched case-sensitively against the
+ * raw origin; the dev-only env-supplied extras (normalized lowercase
+ * + trailing-slash-stripped at load) are matched against a normalized
+ * copy of the input, so a leader sending `Origin: HTTP://Localhost:8787`
+ * (or with a stray trailing slash) still resolves correctly.
+ */
 export function isAllowedBridgeOrigin(origin) {
     if (!origin)
         return false;
-    return BRIDGE_ALLOWED_ORIGINS.includes(origin);
+    if (BRIDGE_ALLOWED_ORIGINS.includes(origin))
+        return true;
+    if (BRIDGE_DEV_ALLOWED_ORIGINS.size === 0)
+        return false;
+    const normalized = normalizeDevOrigin(origin);
+    if (!normalized)
+        return false;
+    return BRIDGE_DEV_ALLOWED_ORIGINS.has(normalized);
+}
+/**
+ * True iff `origin` is a loopback host (localhost / 127.0.0.1 / ::1).
+ * Loopback allowlisted origins (e.g. the locally-served OAuth callback
+ * page at `http://localhost:5710/auth/callback` posting to
+ * `/api/oauth-result`) are exempt from the bridge-token requirement —
+ * the token's threat model is "remote allowlisted origin (sliccy.ai)
+ * with a hostile script", not "local server talking to itself".
+ */
+export function isLoopbackBridgeOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const url = new URL(origin);
+        // Node's WHATWG URL parser keeps the brackets on IPv6 hostnames
+        // (`http://[::1]:5710` → `[::1]`); accept both bracketed and bare.
+        return (url.hostname === 'localhost' ||
+            url.hostname === '127.0.0.1' ||
+            url.hostname === '::1' ||
+            url.hostname === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Constant-time compare for the bridge token. `presented` may be missing
+ * or shaped wrong (Express delivers headers as `string | string[] |
+ * undefined`). Returns `false` for any non-string, length mismatch, or
+ * empty expected — never throws.
+ */
+export function validateBridgeToken(presented, expected) {
+    if (!expected)
+        return false;
+    const value = Array.isArray(presented) ? presented[0] : presented;
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    const a = Buffer.from(value);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
 }
 /**
  * Mint a per-process bridge token. Embedded in the leader launch URL and
@@ -102,6 +242,36 @@ export function validateBridgeUpgrade(input) {
     }
     return { ok: true, acceptedSubprotocol: accepted };
 }
+/**
+ * Resolve the `Access-Control-Allow-Headers` value for a request. Starts
+ * from `CORS_BASE_ALLOW_HEADERS` (the static set covering the documented
+ * /api endpoints + the `/api/fetch-proxy` transport headers) and unions
+ * in any header names from the request's `Access-Control-Request-Headers`
+ * that aren't already listed. This is the reflect-headers pattern: the
+ * agent's `bash curl -H X-Custom: …` can route through `/api/fetch-proxy`
+ * cross-origin without us having to enumerate every possible upstream
+ * header in advance. Comparison is case-insensitive; the static set's
+ * canonical casing wins on duplicates.
+ */
+export function resolveCorsAllowHeaders(requestHeadersHeader) {
+    if (!requestHeadersHeader)
+        return CORS_BASE_ALLOW_HEADERS.join(', ');
+    const seen = new Set(CORS_BASE_ALLOW_HEADERS.map((h) => h.toLowerCase()));
+    const extras = [];
+    for (const raw of requestHeadersHeader.split(',')) {
+        const name = raw.trim();
+        if (!name)
+            continue;
+        const lower = name.toLowerCase();
+        if (seen.has(lower))
+            continue;
+        seen.add(lower);
+        extras.push(name);
+    }
+    if (extras.length === 0)
+        return CORS_BASE_ALLOW_HEADERS.join(', ');
+    return [...CORS_BASE_ALLOW_HEADERS, ...extras].join(', ');
+}
 /**
  * CORS headers for an allowlisted `Origin`. Returns `null` when the origin
  * is not in the allowlist (caller should NOT set CORS headers).
@@ -109,17 +279,24 @@ export function validateBridgeUpgrade(input) {
  * `Access-Control-Allow-Credentials: true` is included so the hosted leader
  * can carry cookies to /api/* (e.g. auth) when that's added later. Today
  * the bridge token is the auth factor, not cookies.
+ *
+ * `requestHeadersHeader` should be the request's `Access-Control-Request-Headers`
+ * value (preflight only); on a non-preflight request pass `null` and the
+ * caller can omit it.
  */
-export function buildCorsHeaders(origin) {
+export function buildCorsHeaders(origin, requestHeadersHeader) {
     if (!isAllowedBridgeOrigin(origin))
         return null;
+    const reqHeaders = Array.isArray(requestHeadersHeader)
+        ? requestHeadersHeader.join(', ')
+        : (requestHeadersHeader ?? null);
     return {
         'Access-Control-Allow-Origin': origin,
         'Access-Control-Allow-Credentials': 'true',
         'Access-Control-Allow-Methods': CORS_ALLOW_METHODS,
-        'Access-Control-Allow-Headers': CORS_ALLOW_HEADERS,
-        'Access-Control-Expose-Headers': 'Link',
-        Vary: 'Origin',
+        'Access-Control-Allow-Headers': resolveCorsAllowHeaders(reqHeaders),
+        'Access-Control-Expose-Headers': CORS_EXPOSE_HEADERS,
+        Vary: 'Origin, Access-Control-Request-Headers',
     };
 }
 /**

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

@@ -3,9 +3,15 @@
  *
  * Includes hop-by-hop headers (`host`, `connection`, `transfer-encoding`,
  * `content-length`), proxy-internal markers (`x-target-url`,
- * `x-slicc-raw-body`), and forbidden-header transports the client uses
+ * `x-slicc-raw-body`), forbidden-header transports the client uses
  * to smuggle reserved names through `fetch()` (`x-proxy-cookie`,
- * `x-proxy-origin`, `x-proxy-referer`).
+ * `x-proxy-origin`, `x-proxy-referer`), and the thin-bridge auth header
+ * (`x-bridge-token`) which authenticates the browser->local hop only
+ * and must not leak onward to `targetUrl`. The bridge-token middleware
+ * (`createThinBridgeCorsMiddleware` in `index.ts`) is mounted ahead of
+ * this route and reads `req.headers` directly, so token validation
+ * still sees the header - this Set only filters what gets COPIED into
+ * the forwarded request.
  *
  * Lives in its own module (rather than `index.ts`) so tests can import
  * it without triggering the server bootstrap that runs at `index.ts`

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

@@ -3,9 +3,15 @@
  *
  * Includes hop-by-hop headers (`host`, `connection`, `transfer-encoding`,
  * `content-length`), proxy-internal markers (`x-target-url`,
- * `x-slicc-raw-body`), and forbidden-header transports the client uses
+ * `x-slicc-raw-body`), forbidden-header transports the client uses
  * to smuggle reserved names through `fetch()` (`x-proxy-cookie`,
- * `x-proxy-origin`, `x-proxy-referer`).
+ * `x-proxy-origin`, `x-proxy-referer`), and the thin-bridge auth header
+ * (`x-bridge-token`) which authenticates the browser->local hop only
+ * and must not leak onward to `targetUrl`. The bridge-token middleware
+ * (`createThinBridgeCorsMiddleware` in `index.ts`) is mounted ahead of
+ * this route and reads `req.headers` directly, so token validation
+ * still sees the header - this Set only filters what gets COPIED into
+ * the forwarded request.
  *
  * Lives in its own module (rather than `index.ts`) so tests can import
  * it without triggering the server bootstrap that runs at `index.ts`
@@ -21,4 +27,5 @@ export const FETCH_PROXY_SKIP_HEADERS = new Set([
     'x-proxy-cookie',
     'x-proxy-origin',
     'x-proxy-referer',
+    'x-bridge-token',
 ]);