@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/lib/types/host/services/remote-web-ui/server-mode/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, and each family's route
+ * module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-shared/host/http
+ */
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http';
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export declare function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown>;
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export declare function readJsonBody(req: IncomingMessage, opts?: {
+    maxBytes?: number;
+    objectOnly?: boolean;
+}): Promise<unknown | null>;
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown, headers?: OutgoingHttpHeaders): void;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/http.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAWrF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9F;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBzB;AAOD,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAIN"}

package/lib/types/host/services/remote-web-ui/server-mode/http.js

@@ -0,0 +1,92 @@
+// Generated by scripts/sync-shared.mjs from shared/host/http.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, and each family's route
+ * module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-shared/host/http
+ */
+/** Default body cap for readJsonBody: 64 KiB. */
+const DEFAULT_JSON_BODY_MAX_BYTES = 64 * 1024;
+/** Family-default JSON response headers; callers may append or override. */
+const JSON_HEADERS = {
+    'content-type': 'application/json; charset=utf-8',
+    'referrer-policy': 'no-referrer',
+};
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export async function readBoundedJson(req, maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > maxBytes)
+            throw new Error('body too large');
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export async function readJsonBody(req, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_JSON_BODY_MAX_BYTES;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > maxBytes) {
+            req.destroy();
+            return null;
+        }
+        chunks.push(buffer);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text === '')
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        if (opts.objectOnly && !isJsonObject(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a value is a JSON object: typeof object, not null, not an array. */
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export function asJsonObject(value) {
+    return isJsonObject(value) ? value : undefined;
+}
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export function writeJson(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { ...JSON_HEADERS, ...headers });
+    res.end(payload);
+}

package/lib/types/host/services/remote-web-ui/server-mode/integrated-auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Integrate the remote-web-ui account session with DSH's own BrowserAuth.
+ *
+ * DSH 0.2 does not yet publish a replaceable Web authentication provider.
+ * The connection service nevertheless owns one BrowserAuth object used by all
+ * native admission paths: frontend index, `/api`, and `/api/remote.mux`.
+ * This adapter composes (never disables) that object with the account session:
+ * a valid native launch-token cookie OR a valid remote-web-ui session is
+ * accepted. The original methods are restored exactly on disposal.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Private DSH BrowserAuth shape required by the compatibility adapter. */
+export interface BrowserAuthLike {
+    isAuthenticated(request: IncomingMessage): boolean;
+    authorizeIndex(request: IncomingMessage, response: ServerResponse): boolean;
+    authenticatedUrl(baseUrl: string): string;
+}
+/** Private subset of the DSH connection service. */
+export interface BrowserConnectionLike {
+    browserAuth?: BrowserAuthLike;
+}
+export interface IntegratedAuthOptions {
+    /** Live feature flag so settings changes do not require re-patching methods. */
+    enabled(): boolean;
+    /** Validate and touch the account session carried by this request. */
+    hasSession(request: IncomingMessage): boolean;
+    /** Login route on the same DSH origin. */
+    loginPath?: string;
+}
+/** Only same-origin absolute paths may be retained across a login redirect. */
+export declare function safeLoginTarget(rawUrl: string | undefined): string;
+/** Locate the private BrowserAuth object and fail closed on SDK shape drift. */
+export declare function browserAuthOf(connection: BrowserConnectionLike): BrowserAuthLike;
+/**
+ * Compose account sessions into DSH BrowserAuth.
+ *
+ * The Host/Origin fence remains owned by Connection and still runs before API
+ * admission. This adapter changes authentication only; it never marks an
+ * untrusted Host as trusted.
+ */
+export declare function installIntegratedBrowserAuth(connection: BrowserConnectionLike, options: IntegratedAuthOptions): () => void;
+//# sourceMappingURL=integrated-auth.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/integrated-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrated-auth.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/integrated-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAClD,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAA;IAC3E,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAC1C;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,eAAe,CAAA;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,OAAO,IAAI,OAAO,CAAA;IAClB,sEAAsE;IACtE,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAC7C,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAWlE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CAWhF;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,qBAAqB,GAC7B,MAAM,IAAI,CA8CZ"}

package/lib/types/host/services/remote-web-ui/server-mode/integrated-auth.js

@@ -0,0 +1,73 @@
+/** Only same-origin absolute paths may be retained across a login redirect. */
+export function safeLoginTarget(rawUrl) {
+    try {
+        const candidate = rawUrl ?? '/';
+        if (!candidate.startsWith('/') || candidate.startsWith('//'))
+            return '/';
+        const url = new URL(candidate, 'http://dsh.invalid');
+        if (!url.pathname.startsWith('/') || url.pathname.startsWith('//'))
+            return '/';
+        if (url.pathname === '/login' || url.pathname.startsWith('/api/gateway/'))
+            return '/';
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    catch {
+        return '/';
+    }
+}
+/** Locate the private BrowserAuth object and fail closed on SDK shape drift. */
+export function browserAuthOf(connection) {
+    const auth = connection.browserAuth;
+    if (auth === undefined
+        || typeof auth.isAuthenticated !== 'function'
+        || typeof auth.authorizeIndex !== 'function'
+        || typeof auth.authenticatedUrl !== 'function') {
+        throw new Error('remote-web-ui: connection.browserAuth shape changed; integrated WebAuth refuses to mount');
+    }
+    return auth;
+}
+/**
+ * Compose account sessions into DSH BrowserAuth.
+ *
+ * The Host/Origin fence remains owned by Connection and still runs before API
+ * admission. This adapter changes authentication only; it never marks an
+ * untrusted Host as trusted.
+ */
+export function installIntegratedBrowserAuth(connection, options) {
+    const auth = browserAuthOf(connection);
+    const originalIsAuthenticated = auth.isAuthenticated;
+    const originalAuthorizeIndex = auth.authorizeIndex;
+    const originalAuthenticatedUrl = auth.authenticatedUrl;
+    const loginPath = options.loginPath ?? '/login';
+    const nativeAuthenticated = (request) => originalIsAuthenticated.call(auth, request);
+    const accountAuthenticated = (request) => options.enabled() && options.hasSession(request);
+    auth.isAuthenticated = (request) => nativeAuthenticated(request) || accountAuthenticated(request);
+    auth.authorizeIndex = (request, response) => {
+        if (!options.enabled())
+            return originalAuthorizeIndex.call(auth, request, response);
+        // Preserve the native launch-token exchange and its clean redirect. An
+        // invalid token deliberately keeps the native 401 rather than being treated
+        // as an account-login attempt.
+        const url = new URL(request.url ?? '/', 'http://dsh.invalid');
+        if (url.searchParams.has('token') || nativeAuthenticated(request)) {
+            return originalAuthorizeIndex.call(auth, request, response);
+        }
+        if (accountAuthenticated(request))
+            return true;
+        const target = safeLoginTarget(request.url);
+        response.writeHead(302, {
+            'cache-control': 'no-store',
+            'location': `${loginPath}?next=${encodeURIComponent(target)}`,
+            'referrer-policy': 'no-referrer',
+        });
+        response.end();
+        return false;
+    };
+    // The CLI's printed launch-token URL remains the local break-glass path.
+    auth.authenticatedUrl = (baseUrl) => originalAuthenticatedUrl.call(auth, baseUrl);
+    return () => {
+        auth.isAuthenticated = originalIsAuthenticated;
+        auth.authorizeIndex = originalAuthorizeIndex;
+        auth.authenticatedUrl = originalAuthenticatedUrl;
+    };
+}

package/lib/types/host/services/remote-web-ui/server-mode/lan.d.ts

@@ -0,0 +1,13 @@
+/**
+ * LAN address derivation for the advertised gateway URL. Mirrors the dsh
+ * CLI's boot-time sampling (apps/cli/src/app-cli-entry.ts `resolveLanTrust`):
+ * the same non-internal IPv4 derivation applies here so the plugin never
+ * advertises an address the deployment cannot actually serve.
+ */
+/**
+ * Non-internal IPv4 interface addresses of this machine — the IP-literal
+ * authorities an all-interfaces bind is reachable by on the LAN.
+ * @returns the addresses in interface order (possibly empty).
+ */
+export declare function lanIPv4Addresses(): string[];
+//# sourceMappingURL=lan.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/lan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/lan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAI3C"}

package/lib/types/host/services/remote-web-ui/server-mode/lan.js

@@ -0,0 +1,17 @@
+/**
+ * LAN address derivation for the advertised gateway URL. Mirrors the dsh
+ * CLI's boot-time sampling (apps/cli/src/app-cli-entry.ts `resolveLanTrust`):
+ * the same non-internal IPv4 derivation applies here so the plugin never
+ * advertises an address the deployment cannot actually serve.
+ */
+import { networkInterfaces } from 'node:os';
+/**
+ * Non-internal IPv4 interface addresses of this machine — the IP-literal
+ * authorities an all-interfaces bind is reachable by on the LAN.
+ * @returns the addresses in interface order (possibly empty).
+ */
+export function lanIPv4Addresses() {
+    return Object.values(networkInterfaces()).flat()
+        .filter((iface) => { return iface !== undefined && iface.family === 'IPv4' && !iface.internal; })
+        .map(iface => iface.address);
+}

package/lib/types/host/services/remote-web-ui/server-mode/loopback.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-shared/host/loopback
+ */
+import type { IncomingMessage } from 'node:http';
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export declare function isIPv4Loopback(v4: string): boolean;
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;
+//# sourceMappingURL=loopback.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/loopback.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMtE;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAmBnE"}

package/lib/types/host/services/remote-web-ui/server-mode/loopback.js

@@ -0,0 +1,68 @@
+// Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-shared/host/loopback
+ */
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export function isIPv4Loopback(v4) {
+    const parts = v4.split('.');
+    return parts.length === 4
+        && parts[0] === '127'
+        && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export function isLoopbackAddress(address) {
+    if (address === undefined)
+        return false;
+    const normalized = address.toLowerCase();
+    if (normalized === '::1')
+        return true;
+    if (normalized.startsWith('::ffff:'))
+        return isIPv4Loopback(normalized.slice('::ffff:'.length));
+    return isIPv4Loopback(normalized);
+}
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '[::1]')
+        return true;
+    return isIPv4Loopback(hostname);
+}
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export function isLoopbackRequest(request) {
+    if (!isLoopbackAddress(request.socket.remoteAddress))
+        return false;
+    const host = request.headers.host;
+    if (typeof host !== 'string')
+        return false;
+    let hostUrl;
+    try {
+        hostUrl = new URL('http://' + host);
+    }
+    catch {
+        return false;
+    }
+    if (!isLoopbackHostname(hostUrl.hostname))
+        return false;
+    if (request.headers['sec-fetch-site'] === 'cross-site')
+        return false;
+    const origin = request.headers.origin;
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === hostUrl.host;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/types/host/services/remote-web-ui/server-mode/posture.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Deployment posture probe: verify that the connection plugin's `/api` fence
+ * actually refuses non-loopback requests for every origin this deployment
+ * advertises (the public tunnel host, the LAN bases). The fence is the SDK's
+ * own Host check — the one seam a plugin cannot mount a gate into — so this
+ * probe is the guardrail that makes a re-opened `/api` (for example a
+ * re-added `--trusted-host`, or the SDK's LAN-literal auto-trust under
+ * `--host 0.0.0.0`) visible instead of silent.
+ *
+ * The probe issues loopback requests with a forged Host header — the exact
+ * shape a tunnel or LAN client produces — and treats anything other than a
+ * 403 as exposed: the fence is documented to refuse with 403, so any other
+ * status means the request reached the RPC bridge.
+ */
+import type { ClientRequest, ClientRequestArgs } from 'node:http';
+/** One probed origin. */
+export interface PostureHost {
+    /** The forged Host header value that was probed. */
+    host: string;
+    /** True when the probe reached past the fence (anything but 403). */
+    exposed: boolean;
+}
+/** One probe round. */
+export interface PostureSnapshot {
+    /** When the round completed (epoch ms). */
+    checkedAt: number;
+    /** Every probed origin and its verdict. */
+    hosts: PostureHost[];
+}
+/** Whether any probed origin is currently exposed. */
+export declare function anyExposed(snapshot: PostureSnapshot): boolean;
+/**
+ * Build the forged Host values to probe: the public base authority (host or
+ * host:port as written in the URL) plus every LAN base literal.
+ * @param publicBaseUrl - the configured public base URL (or undefined).
+ * @param lanAddresses - the LAN interface addresses the QR advertises.
+ * @param port - the local webServer port (LAN hosts are probed as host:port).
+ * @returns Host header values, de-duplicated.
+ */
+export declare function postureTargets(publicBaseUrl: string | undefined, lanAddresses: string[], port: number): string[];
+/** Injectable transport seam (defaults to node:http). */
+export type ProbeRequest = (options: ClientRequestArgs, onStatus: (status: number) => void) => ClientRequest;
+/** Probe options. */
+export interface ProbePostureOptions {
+    /** The local webServer port. */
+    port: number;
+    /** Forged Host header values (see {@link postureTargets}). */
+    targets: string[];
+    /** Transport seam (defaults to node:http). */
+    request?: ProbeRequest;
+    /** Per-host timeout (default 3000 ms). */
+    timeoutMs?: number;
+    /** Clock seam (default Date.now). */
+    now?: () => number;
+}
+/**
+ * Run one posture probe round.
+ * @returns the snapshot for this round.
+ */
+export declare function probePosture(options: ProbePostureOptions): Promise<PostureSnapshot>;
+/**
+ * Reserve an advertised-target key so a second trigger with the same set
+ * does not overlap an in-flight round. Pair with {@link releasePostureKey}
+ * on failure — otherwise that key never retries.
+ */
+export declare function claimPostureKey(current: string | undefined, key: string): {
+    run: boolean;
+    next: string;
+};
+/**
+ * Drop a failed in-flight key so the next trigger re-probes the same targets.
+ * A newer key that started meanwhile is left alone.
+ */
+export declare function releasePostureKey(current: string | undefined, attempted: string): string | undefined;
+//# sourceMappingURL=posture.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/posture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posture.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/posture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGjE,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,uBAAuB;AACvB,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,2CAA2C;IAC3C,KAAK,EAAE,WAAW,EAAE,CAAA;CACrB;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAehH;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KAAK,aAAa,CAAA;AAyC5G,qBAAqB;AACrB,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CAWzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAGxG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpG"}

package/lib/types/host/services/remote-web-ui/server-mode/posture.js

@@ -0,0 +1,116 @@
+/**
+ * Deployment posture probe: verify that the connection plugin's `/api` fence
+ * actually refuses non-loopback requests for every origin this deployment
+ * advertises (the public tunnel host, the LAN bases). The fence is the SDK's
+ * own Host check — the one seam a plugin cannot mount a gate into — so this
+ * probe is the guardrail that makes a re-opened `/api` (for example a
+ * re-added `--trusted-host`, or the SDK's LAN-literal auto-trust under
+ * `--host 0.0.0.0`) visible instead of silent.
+ *
+ * The probe issues loopback requests with a forged Host header — the exact
+ * shape a tunnel or LAN client produces — and treats anything other than a
+ * 403 as exposed: the fence is documented to refuse with 403, so any other
+ * status means the request reached the RPC bridge.
+ */
+import http from 'node:http';
+/** Whether any probed origin is currently exposed. */
+export function anyExposed(snapshot) {
+    return snapshot.hosts.some(host => host.exposed);
+}
+/**
+ * Build the forged Host values to probe: the public base authority (host or
+ * host:port as written in the URL) plus every LAN base literal.
+ * @param publicBaseUrl - the configured public base URL (or undefined).
+ * @param lanAddresses - the LAN interface addresses the QR advertises.
+ * @param port - the local webServer port (LAN hosts are probed as host:port).
+ * @returns Host header values, de-duplicated.
+ */
+export function postureTargets(publicBaseUrl, lanAddresses, port) {
+    const targets = [];
+    if (publicBaseUrl !== undefined) {
+        try {
+            const url = new URL(publicBaseUrl);
+            const authority = url.port === '' ? url.hostname : `${url.hostname}:${url.port}`;
+            if (authority !== '')
+                targets.push(authority);
+        }
+        catch {
+            // A malformed base is ignored elsewhere with a warning; nothing to probe.
+        }
+    }
+    for (const address of lanAddresses) {
+        targets.push(`${address}:${String(port)}`);
+    }
+    return [...new Set(targets)];
+}
+const defaultRequest = (options, onStatus) => {
+    const request = http.request(options, response => { onStatus(response.statusCode ?? 0); });
+    request.on('error', () => { onStatus(0); });
+    return request;
+};
+/**
+ * Probe one forged Host against the local `/api` fence.
+ * @param port - the local webServer port.
+ * @param hostHeader - the Host header to forge.
+ * @param request - transport seam.
+ * @param timeoutMs - give up after this long (counts as not exposed; the
+ * fence being unreachable is not evidence it is open).
+ * @returns true when the probe got past the fence.
+ */
+async function probeHost(port, hostHeader, request, timeoutMs) {
+    return await new Promise(resolve => {
+        let settled = false;
+        const finish = (exposed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            handle.destroy();
+            resolve(exposed);
+        };
+        const handle = request({
+            host: '127.0.0.1',
+            port,
+            method: 'POST',
+            path: '/api/session.list',
+            headers: { host: hostHeader, 'content-type': 'application/json' },
+            timeout: timeoutMs,
+        }, status => { finish(status !== 403); });
+        const timer = setTimeout(() => { finish(false); }, timeoutMs + 1_000);
+        handle.on('error', () => { finish(false); });
+        handle.end('{}');
+    });
+}
+/**
+ * Run one posture probe round.
+ * @returns the snapshot for this round.
+ */
+export async function probePosture(options) {
+    const { port, targets } = options;
+    const request = options.request ?? defaultRequest;
+    const timeoutMs = options.timeoutMs ?? 3_000;
+    const now = options.now ?? (() => Date.now());
+    const hosts = [];
+    for (const target of targets) {
+        // Sequential on purpose: one slow host must not multiply the round's latency.
+        hosts.push({ host: target, exposed: await probeHost(port, target, request, timeoutMs) });
+    }
+    return { checkedAt: now(), hosts };
+}
+/**
+ * Reserve an advertised-target key so a second trigger with the same set
+ * does not overlap an in-flight round. Pair with {@link releasePostureKey}
+ * on failure — otherwise that key never retries.
+ */
+export function claimPostureKey(current, key) {
+    if (current === key)
+        return { run: false, next: current };
+    return { run: true, next: key };
+}
+/**
+ * Drop a failed in-flight key so the next trigger re-probes the same targets.
+ * A newer key that started meanwhile is left alone.
+ */
+export function releasePostureKey(current, attempted) {
+    return current === attempted ? undefined : current;
+}

package/lib/types/host/services/remote-web-ui/server-mode/roles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Role policy of the server-mode gateway (decided: admin + user).
+ *
+ * The gateway is the authentication + loopback-shaping front door: once a
+ * session crosses the wall, every request is re-issued to 127.0.0.1 with the
+ * client's cookies/Origin stripped and Host rewritten, so the upstream's own
+ * loopback fence can no longer tell roles apart. This table is therefore the
+ * only place a role is narrowed.
+ *
+ * Decided surface — both roles use the whole product:
+ * - the native DSH API, addressed as `/api/<namespace>/<method>` in 0.2
+ *   (`/api/settings/describe`, `/api/pluginManager/setPluginEnabled`,
+ *   `/api/llm/listProviders`, `/api/credentials/describe`, ...);
+ * - the family's own feature routes (`/worktree/*`, `/git/*`,
+ *   `/api/workbench/*`).
+ * Remote access exists so the same web UI runs on another device. Walling the
+ * settings plane or the plugin manager away from the `user` role produced
+ * exactly the "the page renders but the switch will not flip / the models tab
+ * stays empty" failures on the owner's own devices — and the 0.1-era dotted
+ * method names this table used to carry (`settings.describe`,
+ * `/api/plugin-manager`) silently matched nothing in 0.2 anyway.
+ *
+ * Admin-only is the family's machine-control surface: pairing and token
+ * administration under `/api/pair` (that route is also loopback-guarded
+ * upstream). `/api/gateway/*` never reaches this table — the gateway answers it
+ * before the wall.
+ */
+/**
+ * Family control prefixes that stay out of the user surface. These are real 0.2
+ * paths: the family mounts them literally, unlike the SDK's method names, which
+ * are `/api/<namespace>/<method>` (camelCase namespace).
+ */
+export declare const CONTROL_PREFIXES: readonly ["/api/pair"];
+/** Gateway self-served prefix (never proxied; handled before the wall logic). */
+export declare const GATEWAY_API_PREFIX = "/api/gateway";
+/** Whether an /api pathname falls under a control prefix. */
+export declare function isControlPath(pathname: string): boolean;
+/**
+ * Whether a user-role session may pass this request upstream.
+ * @param pathname - the request pathname (without query).
+ * @returns true to proxy, false to refuse with 403.
+ */
+export declare function userRoleAllows(pathname: string): boolean;
+//# sourceMappingURL=roles.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wBAAyB,CAAA;AAEtD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAEhD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}