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

package/lib/types/host/services/remote-access/index.js

@@ -0,0 +1,47 @@
+/**
+ * Remote-access service domain: the two pieces every reverse-proxied
+ * deployment needs regardless of whether the optional server-mode gateway is
+ * mounted.
+ *
+ * - the per-request Host-ownership boot script and the authority posture
+ *   readout (`./routes.ts`);
+ * - the index boot rows every entry shares: the parser-blocking ownership
+ *   script, the `crypto.randomUUID` polyfill and the `navigator.clipboard`
+ *   shim (`./boot-scripts.ts`).
+ *
+ * The ownership decision is the shared host access fence, so this domain can
+ * never claim more than the privileged panels already allow. Fail-closed: when
+ * the fence service is missing, `accessTrustOf` falls back to the strict
+ * loopback rule and only a loopback page (which already owns the Host) is
+ * admitted.
+ * @module dsh-web-all/host/services/remote-access
+ */
+import { accessTrustOf, browserSessionPredicateOf, trustedAuthoritiesOf } from "../access-trust/index.js";
+import { CLIPBOARD_SHIM_SCRIPT, HOST_ACCESS_BOOT_PATH, UUID_POLYFILL_SCRIPT } from "./boot-scripts.js";
+import { makeRemoteAccessRoutes } from "./routes.js";
+import { registerResources } from "../resources.js";
+export { CLIPBOARD_SHIM_SCRIPT, HOST_ACCESS_BOOT_PATH, HOST_ACCESS_MARKER_COOKIE, HOST_ACCESS_MARKER_MAX_AGE_SECONDS, HOST_ACCESS_MARKER_VALUE, HOST_ACCESS_SESSION_PATH, UUID_POLYFILL_SCRIPT, hostAccessBootScript, } from "./boot-scripts.js";
+export { makeRemoteAccessRoutes } from "./routes.js";
+/**
+ * Mount the service domain.
+ * @param ctx - host plugin context.
+ * @returns the disposer releasing the routes and the injection rows.
+ */
+export function register(ctx) {
+    const deps = {
+        isTrusted: (request) => accessTrustOf(ctx).isTrusted(request),
+        trustedAuthorities: () => trustedAuthoritiesOf(ctx),
+        isAuthenticated: (request) => browserSessionPredicateOf(ctx)?.(request) === true,
+    };
+    return registerResources(own => {
+        for (const route of makeRemoteAccessRoutes(deps))
+            own(ctx.webServer.register(route));
+        // Row order is execution order: the parser-blocking ownership script runs
+        // first, then the two inline shims the plain-HTTP origin needs.
+        own(ctx.on('webserver/index-inject', (table) => {
+            table.push({ kind: 'script-src', placement: 'head', src: HOST_ACCESS_BOOT_PATH });
+            table.push({ kind: 'script', placement: 'head', text: UUID_POLYFILL_SCRIPT });
+            table.push({ kind: 'script', placement: 'head', text: CLIPBOARD_SHIM_SCRIPT });
+        }));
+    });
+}

package/lib/types/host/services/remote-access/routes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * HTTP boundary of the remote-access domain: the per-request Host-ownership
+ * boot script and the credential-free authority posture readout.
+ *
+ * Both routes exist for the documented reverse-proxy topology
+ * (browser -> `http://dsh.<machine>/` -> nginx -> `127.0.0.1:3080`), where the
+ * optional server-mode gateway is not in the request path:
+ *
+ * - `GET /web-all/remote-access/boot.js` is referenced by a parser-blocking
+ *   `<script src>` row in every served index document. The handler runs the
+ *   same shared host access fence the privileged panels use and answers with
+ *   either a script that claims Host ownership or a no-op, so a remote page
+ *   keeps a host-backed settings plane without granting that claim to an
+ *   undeclared Host.
+ * - `GET /api/dsh-access/session` reports whether this deployment declares the
+ *   requesting Host (`authority.declared`), whether a browser session is
+ *   present (`session`), and the full fence decision (`owners`). It needs no
+ *   session, which is what lets the fleet audit detect a machine whose running
+ *   process carries no `--trusted-host` for its canonical authority
+ *   (docs/remote-access.md invariant 6); `authority` is therefore public and
+ *   carries no canonical list or token, while the `session` bit is only
+ *   computed for a caller the fence already admits.
+ * @module dsh-web-all/host/services/remote-access/routes
+ */
+import type { IncomingMessage } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+/** Admission inputs the remote-access routes read per request. */
+export interface RemoteAccessDeps {
+    /** The shared host access fence decision for one request. */
+    isTrusted(request: IncomingMessage): boolean;
+    /** Authorities this deployment declares as its browser entries. */
+    trustedAuthorities(): readonly string[];
+    /** Whether the request carries an authenticated browser session. */
+    isAuthenticated(request: IncomingMessage): boolean;
+}
+/**
+ * Build the remote-access routes.
+ * @param deps - admission inputs, read live on every request.
+ * @returns the routes to register on the web server.
+ */
+export declare function makeRemoteAccessRoutes(deps: RemoteAccessDeps): WebRoute[];
+//# sourceMappingURL=routes.d.ts.map

package/lib/types/host/services/remote-access/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/remote-access/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAW/D,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAC5C,mEAAmE;IACnE,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAAA;IACvC,oEAAoE;IACpE,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;CACnD;AA4CD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,QAAQ,EAAE,CAyCzE"}

package/lib/types/host/services/remote-access/routes.js

@@ -0,0 +1,119 @@
+/**
+ * HTTP boundary of the remote-access domain: the per-request Host-ownership
+ * boot script and the credential-free authority posture readout.
+ *
+ * Both routes exist for the documented reverse-proxy topology
+ * (browser -> `http://dsh.<machine>/` -> nginx -> `127.0.0.1:3080`), where the
+ * optional server-mode gateway is not in the request path:
+ *
+ * - `GET /web-all/remote-access/boot.js` is referenced by a parser-blocking
+ *   `<script src>` row in every served index document. The handler runs the
+ *   same shared host access fence the privileged panels use and answers with
+ *   either a script that claims Host ownership or a no-op, so a remote page
+ *   keeps a host-backed settings plane without granting that claim to an
+ *   undeclared Host.
+ * - `GET /api/dsh-access/session` reports whether this deployment declares the
+ *   requesting Host (`authority.declared`), whether a browser session is
+ *   present (`session`), and the full fence decision (`owners`). It needs no
+ *   session, which is what lets the fleet audit detect a machine whose running
+ *   process carries no `--trusted-host` for its canonical authority
+ *   (docs/remote-access.md invariant 6); `authority` is therefore public and
+ *   carries no canonical list or token, while the `session` bit is only
+ *   computed for a caller the fence already admits.
+ * @module dsh-web-all/host/services/remote-access/routes
+ */
+import { hostUrlOf, isLoopbackHostname, matchesTrustedAuthority } from "../access-trust/trust.js";
+import { HOST_ACCESS_BOOT_PATH, HOST_ACCESS_MARKER_COOKIE, HOST_ACCESS_MARKER_MAX_AGE_SECONDS, HOST_ACCESS_MARKER_VALUE, HOST_ACCESS_SESSION_PATH, hostAccessBootScript, } from "./boot-scripts.js";
+/** Whether the request reached the plugin over TLS, directly or through a proxy. */
+function requestIsSecure(request) {
+    const forwarded = request.headers['x-forwarded-proto'];
+    const value = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    if (typeof value === 'string' && value.split(',')[0]?.trim().toLowerCase() === 'https')
+        return true;
+    return request.socket?.encrypted === true;
+}
+/**
+ * Host-only provenance marker; `Secure` is appended only when the request
+ * arrived over TLS, so a plain-HTTP entry can still read it back.
+ */
+function markerCookie(request) {
+    const secure = requestIsSecure(request) ? '; Secure' : '';
+    return `${HOST_ACCESS_MARKER_COOKIE}=${HOST_ACCESS_MARKER_VALUE}; Path=/; SameSite=Lax; Max-Age=${String(HOST_ACCESS_MARKER_MAX_AGE_SECONDS)}${secure}`;
+}
+function writeScript(response, body, cookies = []) {
+    const headers = {
+        'content-type': 'application/javascript; charset=utf-8',
+        'cache-control': 'no-store',
+    };
+    if (cookies.length > 0)
+        headers['set-cookie'] = [...cookies];
+    response.writeHead(200, headers);
+    response.end(body);
+}
+function writeJson(response, status, body, cookies = []) {
+    const headers = {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    };
+    if (cookies.length > 0)
+        headers['set-cookie'] = [...cookies];
+    response.writeHead(status, headers);
+    response.end(JSON.stringify(body));
+}
+function methodNotAllowed(response) {
+    response.writeHead(405, { allow: 'GET', 'cache-control': 'no-store' });
+    response.end();
+}
+/**
+ * Build the remote-access routes.
+ * @param deps - admission inputs, read live on every request.
+ * @returns the routes to register on the web server.
+ */
+export function makeRemoteAccessRoutes(deps) {
+    return [
+        {
+            kind: 'exact',
+            path: HOST_ACCESS_BOOT_PATH,
+            handler: (request, response) => {
+                if (request.method !== 'GET') {
+                    methodNotAllowed(response);
+                    return;
+                }
+                const hostUrl = hostUrlOf(request);
+                const loopback = hostUrl !== undefined && isLoopbackHostname(hostUrl.hostname);
+                const admitted = deps.isTrusted(request);
+                const cookies = admitted && !loopback ? [markerCookie(request)] : [];
+                writeScript(response, hostAccessBootScript(admitted), cookies);
+            },
+        },
+        {
+            kind: 'exact',
+            path: HOST_ACCESS_SESSION_PATH,
+            handler: (request, response) => {
+                if (request.method !== 'GET') {
+                    methodNotAllowed(response);
+                    return;
+                }
+                const hostUrl = hostUrlOf(request);
+                const loopback = hostUrl !== undefined && isLoopbackHostname(hostUrl.hostname);
+                const declared = loopback
+                    || (hostUrl !== undefined && matchesTrustedAuthority(hostUrl, deps.trustedAuthorities()));
+                const owners = deps.isTrusted(request);
+                const cookies = owners && !loopback ? [markerCookie(request)] : [];
+                writeJson(response, 200, {
+                    authority: {
+                        host: hostUrl?.host ?? '',
+                        loopback,
+                        declared,
+                    },
+                    // The browser-session predicate is only consulted for a caller the
+                    // fence already admits: an unadmitted caller must not be able to
+                    // spend the host's session lookup, and its session bit is false by
+                    // construction anyway.
+                    session: owners ? deps.isAuthenticated(request) : false,
+                    owners,
+                }, cookies);
+            },
+        },
+    ];
+}

package/lib/types/host/services/remote-web-ui/index.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import { PairTokenStore, type PairTokenStoreOptions } from '../../../core/remote-web-ui/security.ts';
+export declare const PAIR_API_PREFIX = "/api/pair";
+export declare const GATEWAY_API_PREFIX = "/api/gateway";
+export interface RemoteDeps extends PairTokenStoreOptions {
+    logger: {
+        warn(error: unknown): void;
+    };
+    fetch?: typeof fetch;
+    targetOrigin?: string;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    timeoutMs?: number;
+    tokenStore?: PairTokenStore;
+}
+export declare function makeRemoteRoutes(deps: RemoteDeps): WebRoute[];
+export declare function register(ctx: Context): () => void;
+export { PairTokenStore } from '../../../core/remote-web-ui/security.ts';
+export type { PairTokenSummary } from '../../../core/remote-web-ui/security.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/host/services/remote-web-ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/remote-web-ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAK/D,OAAO,EAIL,cAAc,EAId,KAAK,qBAAqB,EAC3B,MAAM,yCAAyC,CAAA;AAEhD,eAAO,MAAM,eAAe,cAAc,CAAA;AAC1C,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAgBhD,MAAM,WAAW,UAAW,SAAQ,qBAAqB;IACvD,MAAM,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;IACtC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,cAAc,CAAA;CAC5B;AA6ID,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,EAAE,CA8I7D;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,IAAI,CAajD;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAA;AACxE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAA"}

package/lib/types/host/services/remote-web-ui/index.js

@@ -0,0 +1,325 @@
+import { registerServerMode } from "./server.js";
+import { registerResources } from "../resources.js";
+import { isLoopbackRequest } from "../access-trust/trust.js";
+import { DEFAULT_GATEWAY_MAX_BODY_BYTES, DEFAULT_GATEWAY_TARGET_ORIGIN, DEFAULT_GATEWAY_TIMEOUT_MS, PairTokenStore, bearerToken, isAllowedGatewayMethod, resolveGatewayTarget, } from "../../../core/remote-web-ui/security.js";
+export const PAIR_API_PREFIX = '/api/pair';
+export const GATEWAY_API_PREFIX = '/api/gateway';
+const MAX_PAIR_BODY_BYTES = 64 * 1024;
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const REQUEST_CREDENTIAL_HEADERS = new Set(['authorization', 'cookie', 'host', 'origin', 'referer']);
+const RESPONSE_CREDENTIAL_HEADERS = new Set(['set-cookie', 'set-cookie2']);
+class PayloadTooLargeError extends Error {
+}
+/**
+ * Loopback privilege rule for the pairing control surface: a loopback socket
+ * AND a loopback Host AND same-origin browser markers. The socket alone is not
+ * enough behind the documented same-host reverse proxy (nginx connects to
+ * 127.0.0.1), where every remote browser request would otherwise look local and
+ * could mint, list or revoke pair tokens.
+ */
+function isLoopback(req) {
+    return isLoopbackRequest(req);
+}
+function writeJson(res, status, body) {
+    const encoded = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(encoded),
+    });
+    res.end(encoded);
+}
+async function readBody(req, maxBytes) {
+    const contentLength = Number(req.headers['content-length']);
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        req.resume();
+        throw new PayloadTooLargeError('request body too large');
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > maxBytes) {
+            req.resume();
+            throw new PayloadTooLargeError('request body too large');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+async function readJsonBody(req, maxBytes) {
+    const raw = await readBody(req, maxBytes);
+    try {
+        const parsed = JSON.parse(raw.toString('utf8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // Return one uniform bad-request response below.
+    }
+    throw new SyntaxError('invalid JSON body');
+}
+async function readFetchBody(body, maxBytes) {
+    if (body === null)
+        return Buffer.alloc(0);
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const buffer = Buffer.from(value);
+            total += buffer.length;
+            if (total > maxBytes)
+                throw new PayloadTooLargeError('upstream response too large');
+            chunks.push(buffer);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return Buffer.concat(chunks);
+}
+function loopbackGuard(req, res, method) {
+    if (!isLoopback(req)) {
+        req.resume();
+        writeJson(res, 403, { error: 'forbidden: loopback-only' });
+        return false;
+    }
+    if (req.method !== method) {
+        req.resume();
+        res.setHeader('allow', method);
+        writeJson(res, 405, { error: `method not allowed: ${req.method ?? 'GET'}` });
+        return false;
+    }
+    return true;
+}
+function sanitizedRequestHeaders(headers, target) {
+    const forwarded = new Headers();
+    const connectionTokens = connectionHeaderTokens(headers.connection);
+    connectionTokens.add('proxy-connection');
+    for (const [name, value] of Object.entries(headers)) {
+        const lowerName = name.toLowerCase();
+        if (value === undefined || HOP_BY_HOP_HEADERS.has(lowerName) || REQUEST_CREDENTIAL_HEADERS.has(lowerName) || connectionTokens.has(lowerName))
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                forwarded.append(name, item);
+        }
+        else {
+            forwarded.set(name, value);
+        }
+    }
+    forwarded.set('host', target.host);
+    return forwarded;
+}
+function sanitizedResponseHeaders(headers) {
+    const forwarded = {};
+    const connectionTokens = connectionHeaderTokens(headers.get('connection'));
+    connectionTokens.add('proxy-connection');
+    for (const [name, value] of headers) {
+        const lowerName = name.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(lowerName) || RESPONSE_CREDENTIAL_HEADERS.has(lowerName) || connectionTokens.has(lowerName))
+            continue;
+        forwarded[name] = value;
+    }
+    return forwarded;
+}
+function connectionHeaderTokens(value) {
+    const source = Array.isArray(value) ? value.join(',') : value ?? '';
+    return new Set(source.split(',').map(item => item.trim().toLowerCase()).filter(Boolean));
+}
+function normalizeLabel(value) {
+    if (typeof value !== 'string')
+        return 'mobile';
+    const normalized = value.trim().slice(0, 120);
+    return normalized === '' ? 'mobile' : normalized;
+}
+function normalizeTokenId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return /^[a-f\d]{24}$/i.test(normalized) ? normalized : undefined;
+}
+function gatewayError(res, status, error) {
+    writeJson(res, status, { ok: false, error });
+}
+export function makeRemoteRoutes(deps) {
+    const store = deps.tokenStore ?? new PairTokenStore(deps);
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const targetOrigin = deps.targetOrigin ?? DEFAULT_GATEWAY_TARGET_ORIGIN;
+    const maxRequestBytes = deps.maxRequestBytes ?? DEFAULT_GATEWAY_MAX_BODY_BYTES;
+    const maxResponseBytes = deps.maxResponseBytes ?? DEFAULT_GATEWAY_MAX_BODY_BYTES;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_GATEWAY_TIMEOUT_MS;
+    const gatewayHandler = async (req, res) => {
+        const token = bearerToken(req.headers.authorization);
+        if (token === undefined || store.authenticate(token) === undefined) {
+            req.resume();
+            gatewayError(res, 401, 'unauthorized');
+            return;
+        }
+        if (!isAllowedGatewayMethod(req.method)) {
+            req.resume();
+            gatewayError(res, 405, 'method not allowed');
+            return;
+        }
+        const target = resolveGatewayTarget(req.url, targetOrigin);
+        if (target === undefined) {
+            req.resume();
+            gatewayError(res, 403, 'forbidden gateway target');
+            return;
+        }
+        const method = req.method ?? 'GET';
+        let body;
+        try {
+            if (method !== 'GET' && method !== 'HEAD')
+                body = await readBody(req, maxRequestBytes);
+            else
+                req.resume();
+        }
+        catch (error) {
+            if (error instanceof PayloadTooLargeError) {
+                gatewayError(res, 413, error.message);
+                return;
+            }
+            throw error;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref?.();
+        try {
+            const upstream = await fetchImpl(target, {
+                method,
+                headers: sanitizedRequestHeaders(req.headers, target),
+                body: body !== undefined && body.byteLength > 0 ? body : undefined,
+                redirect: 'manual',
+                signal: controller.signal,
+            });
+            const contentLength = upstream.headers.get('content-length');
+            const declaredLength = contentLength === null ? undefined : Number(contentLength);
+            if (declaredLength !== undefined && Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
+                await upstream.body?.cancel().catch(() => { });
+                gatewayError(res, 502, 'upstream response too large');
+                return;
+            }
+            const responseBody = await readFetchBody(upstream.body, maxResponseBytes);
+            const headers = sanitizedResponseHeaders(upstream.headers);
+            headers['content-length'] = String(responseBody.byteLength);
+            res.writeHead(upstream.status, headers);
+            res.end(responseBody);
+        }
+        catch (error) {
+            if (error instanceof PayloadTooLargeError) {
+                gatewayError(res, 502, error.message);
+                return;
+            }
+            if (controller.signal.aborted) {
+                gatewayError(res, 504, 'gateway timeout');
+                return;
+            }
+            deps.logger.warn(error);
+            gatewayError(res, 502, 'gateway upstream failed');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return [
+        {
+            kind: 'exact',
+            path: `${PAIR_API_PREFIX}/pair`,
+            handler: async (req, res) => {
+                if (!loopbackGuard(req, res, 'POST'))
+                    return;
+                try {
+                    const body = await readJsonBody(req, MAX_PAIR_BODY_BYTES);
+                    const issued = store.issue(normalizeLabel(body.label));
+                    writeJson(res, 201, { ok: true, ...issued });
+                }
+                catch (error) {
+                    if (error instanceof PayloadTooLargeError)
+                        writeJson(res, 413, { error: error.message });
+                    else if (error instanceof SyntaxError)
+                        writeJson(res, 400, { error: error.message });
+                    else {
+                        deps.logger.warn(error);
+                        writeJson(res, 500, { error: 'failed to create pair token' });
+                    }
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: `${PAIR_API_PREFIX}/status`,
+            handler: async (req, res) => {
+                if (!loopbackGuard(req, res, 'GET'))
+                    return;
+                const tokens = store.list();
+                writeJson(res, 200, { ok: true, paired: tokens.length > 0, tokens });
+            },
+        },
+        {
+            kind: 'exact',
+            path: `${PAIR_API_PREFIX}/revoke`,
+            handler: async (req, res) => {
+                if (!loopbackGuard(req, res, 'POST'))
+                    return;
+                try {
+                    const body = await readJsonBody(req, MAX_PAIR_BODY_BYTES);
+                    const id = normalizeTokenId(body.id);
+                    if (id === undefined) {
+                        writeJson(res, 400, { error: 'invalid token id' });
+                        return;
+                    }
+                    if (!store.revoke(id)) {
+                        writeJson(res, 404, { error: 'pair token not found' });
+                        return;
+                    }
+                    writeJson(res, 200, { ok: true, id });
+                }
+                catch (error) {
+                    if (error instanceof PayloadTooLargeError)
+                        writeJson(res, 413, { error: error.message });
+                    else if (error instanceof SyntaxError)
+                        writeJson(res, 400, { error: error.message });
+                    else {
+                        deps.logger.warn(error);
+                        writeJson(res, 500, { error: 'failed to revoke pair token' });
+                    }
+                }
+            },
+        },
+        {
+            kind: 'prefix',
+            path: GATEWAY_API_PREFIX,
+            handler: gatewayHandler,
+        },
+    ];
+}
+export function register(ctx) {
+    // The full authenticated server-mode surface owns /api/gateway, /login,
+    // authentication callbacks and its public listener. Pairing remains as a compatibility
+    // control surface only; the secure pair-token gateway proxy is deliberately
+    // omitted here to avoid a second owner for /api/gateway.
+    return registerResources(own => {
+        own(registerServerMode(ctx));
+        const routes = makeRemoteRoutes({
+            logger: { warn: (error) => { console.warn('[web-all:remote-web-ui]', error); } },
+        }).filter(route => route.path.startsWith(PAIR_API_PREFIX));
+        const webServer = ctx.webServer;
+        for (const route of routes)
+            own(webServer.register(route));
+    });
+}
+export { PairTokenStore } from "../../../core/remote-web-ui/security.js";

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

@@ -0,0 +1,115 @@
+/**
+ * Account store for the server-mode gateway: username, scrypt password hash,
+ * role, and enabled flag, persisted to a 0600 JSON file with atomic writes.
+ *
+ * Security invariants:
+ * - Passwords are never stored in plaintext; only the scrypt verifier string
+ *   (`scrypt$N$r$p$saltHex$hashHex`) is persisted.
+ * - Verification uses `timingSafeEqual` over the derived key.
+ * - The store file is created 0600 (owner read/write only) and rewritten via
+ *   a temp file + rename so a crash cannot leave a half-written store.
+ * - No record exposes the password hash through the snapshot surface.
+ */
+/** Role set of the server-mode gateway (decided: admin + user). */
+export type AccountRole = 'admin' | 'user';
+/** One persisted account record. */
+export interface AccountRecord {
+    username: string;
+    /** scrypt verifier string; never surfaced by snapshots. */
+    passwordHash: string;
+    role: AccountRole;
+    enabled: boolean;
+    /** Account creation time (ms epoch). */
+    createdAt: number;
+    authVersion: string;
+}
+/** Redacted account row safe for the admin surface (no hash, no secrets). */
+export interface AccountSnapshot {
+    username: string;
+    role: AccountRole;
+    enabled: boolean;
+    createdAt: number;
+}
+/** Stable conflict codes for account-domain invariants. */
+export type AccountConflictCode = 'username-exists' | 'last-enabled-admin' | 'external-bootstrap-forbidden';
+/** Typed mutation conflict surfaced as HTTP 409 by the gateway routes. */
+export declare class AccountConflictError extends Error {
+    readonly code: AccountConflictCode;
+    constructor(code: AccountConflictCode, message: string);
+}
+/** Clock/randomness seams so the whole security semantics are unit-testable. */
+export interface AccountStoreDeps {
+    now: () => number;
+    /** 16-byte random salt per password set. */
+    randomSalt: () => Buffer;
+}
+/** Hash a password into the persisted verifier string. */
+export declare function hashPassword(password: string, salt: Buffer): string;
+/** Constant-time password verification against a stored verifier string. */
+export declare function verifyPassword(password: string, verifier: string): boolean;
+/**
+ * The account store. Loads the file at construction and persists every
+ * mutation through an atomic 0600 write.
+ */
+export declare class AccountStore {
+    private readonly accounts;
+    private readonly file;
+    private readonly deps;
+    private readonly generations;
+    private healthy;
+    private pristine;
+    private readonly listeners;
+    subscribe(listener: () => void): () => void;
+    private changed;
+    private requireHealthy;
+    canBootstrap(): boolean;
+    /** Live authorization identity, independent of a persisted session's role snapshot. */
+    authorization(username: string): {
+        role: AccountRole;
+        version: string;
+    } | undefined;
+    private invalidate;
+    constructor(file: string, deps: AccountStoreDeps);
+    /** Read the persisted file, if any, into memory. */
+    private load;
+    /** Atomic 0600 persistence of the current account set. */
+    private persist;
+    /** Whether the store has any account (gateway fails closed on empty). */
+    isEmpty(): boolean;
+    /** Whether this mutation would remove the store's final enabled admin. */
+    private isLastEnabledAdmin;
+    /** Refuse a mutation that would leave no enabled administrator. */
+    private requireAdminSurvivor;
+    /**
+     * Create one account. Refuses an existing username. The first account is
+     * always an administrator, regardless of the caller-supplied role.
+     */
+    create(username: string, password: string, role: AccountRole): AccountSnapshot;
+    /** Verify a username/password pair. Never reveals whether the user exists. */
+    verify(username: string, password: string): boolean;
+    /** Look up the role of an existing account, or undefined. */
+    roleOf(username: string): AccountRole | undefined;
+    /**
+     * Create a passwordless external-identity binding. External login may not
+     * bootstrap the store: an operator must create the first local administrator
+     * explicitly, otherwise unrestricted provider JIT binding could claim it.
+     */
+    ensureExternal(username: string, role: AccountRole): AccountSnapshot;
+    /** Whether an account exists and is enabled. */
+    isEnabled(username: string): boolean;
+    /** Replace a password (does not touch other fields). */
+    setPassword(username: string, password: string): boolean;
+    /** Change a role without allowing the last enabled admin to be demoted. */
+    setRole(username: string, role: AccountRole): boolean;
+    /** Enable or disable an account (disabled accounts cannot log in). */
+    setEnabled(username: string, enabled: boolean): boolean;
+    /** Remove an account without deleting the last enabled admin. */
+    remove(username: string): boolean;
+    private commitChange;
+    /** All accounts as redacted snapshots. */
+    list(): AccountSnapshot[];
+    private snapshotOf;
+}
+/** A 16-byte cryptographically random salt (the live seam implementation). */
+export declare function randomSalt(): Buffer;
+//# sourceMappingURL=accounts.d.ts.map