@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/lib/types/pair-grant.js

@@ -0,0 +1,95 @@
+/**
+ * One-time pairing grants for the /pair-app landing.
+ *
+ * The QR entry (`/pair-accept?pair=<token>`) used to hand the freshly minted
+ * device id to the app landing in its own URL (`/pair-app?device=<id>`). A
+ * device id is a live session credential: the channel gate authorizes every
+ * gated request by it and the cookie it mirrors lives a year, so a URL carrying
+ * it leaks that credential into browser history, the address bar, and every log
+ * on the path. The landing is reached with a one-time grant instead — 256 bits
+ * of entropy, a short TTL, and single-consume semantics — and the device id
+ * reaches the client only inside the server-rendered shell (the capture script
+ * the landing patches in).
+ *
+ * Consume semantics follow the reference implementation's one-time host
+ * capability (zcode `packages/server/src/hostCapability.ts`): the record is
+ * deleted on EVERY consume attempt — success, expiry, or replay — so a captured
+ * grant is worthless after its first use and a replayed one can never resolve,
+ * and only a first use inside the TTL yields a device.
+ *
+ * @module @linxin666/dsh-remote-web-ui/pair-grant
+ */
+import { randomBytes } from 'node:crypto';
+/**
+ * Default grant lifetime. The grant only has to survive one redirect chain
+ * from the accept page to the app landing, tunnel round trips included, so it
+ * is far shorter than the device session it stands in for.
+ */
+export const DEFAULT_PAIR_GRANT_TTL_MS = 60_000;
+/**
+ * Cap on live grants. The accept page is rate-limited per source, but the
+ * table is still caller-driven, so it stays bounded (oldest evicted first)
+ * exactly like the device table.
+ */
+export const MAX_LIVE_GRANTS = 256;
+/**
+ * Build the grant table. Pure TypeScript with injected clock/randomness so the
+ * whole one-time semantics are unit-testable without a server.
+ */
+export function createPairGrantStore(options = {}) {
+    const ttlMs = options.ttlMs ?? DEFAULT_PAIR_GRANT_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const createGrant = options.createGrant ?? (() => randomBytes(32).toString('base64url'));
+    const entries = new Map();
+    const purgeExpired = (at) => {
+        for (const [grant, entry] of entries) {
+            if (entry.expiresAt <= at)
+                entries.delete(grant);
+        }
+    };
+    return {
+        issue(deviceId) {
+            const issuedAt = now();
+            purgeExpired(issuedAt);
+            while (entries.size >= MAX_LIVE_GRANTS) {
+                const oldest = entries.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                entries.delete(oldest);
+            }
+            const grant = createGrant();
+            const expiresAt = issuedAt + ttlMs;
+            entries.set(grant, { deviceId, expiresAt });
+            return { grant, expiresAt };
+        },
+        consume(grant) {
+            if (grant === undefined || grant === '')
+                return undefined;
+            const consumedAt = now();
+            const entry = entries.get(grant);
+            // Delete before validating: a replayed grant must never resolve, and an
+            // expired one must not linger in the table.
+            entries.delete(grant);
+            purgeExpired(consumedAt);
+            if (entry === undefined || entry.expiresAt <= consumedAt)
+                return undefined;
+            return entry.deviceId;
+        },
+        peek(grant) {
+            if (grant === undefined || grant === '')
+                return undefined;
+            const at = now();
+            const entry = entries.get(grant);
+            if (entry === undefined)
+                return undefined;
+            if (entry.expiresAt <= at) {
+                entries.delete(grant);
+                return undefined;
+            }
+            return entry.deviceId;
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/lib/types/pairing.d.ts

@@ -7,9 +7,9 @@
  * Security invariants:
  * - One active token at a time; `issue()` replaces it, so a refreshed QR
  *   immediately invalidates the previous link.
- * - A token stays re-usable until it expires or is replaced: the first
- *   successful `accept()` marks it consumed, but the same link may pair
- *   again within the window (each re-accept mints a fresh device session).
+ * - A token is a bearer credential for its whole window: it is refused only
+ *   when unknown, expired, or after `stop()`, and the same link may pair
+ *   repeatedly within that window (each accept mints a fresh device session).
  *   Mobile flows routinely split across cookie contexts (camera preview to
  *   in-app browser to the system browser), and the later context must be
  *   able to complete its own pairing from the same link.
@@ -39,8 +39,6 @@ export interface TokenRecord {
     issuedAt: number;
     /** Absolute expiry (ms epoch); accept() past this is refused. */
     expiresAt: number;
-    /** Consumed by the first successful accept(). */
-    consumed: boolean;
     /** Opaque, non-secret identifier surfaced in snapshots (never the pairing secret). */
     id: string;
     /** Workspace the QR link should land the phone in (optional). */
@@ -150,13 +148,17 @@ export interface PairingConfig {
      */
     devicesFile?: string;
 }
-/** Result of one accept() attempt. */
+/**
+ * Result of one accept() attempt. A token is a bearer credential for its whole
+ * window (see the module doc), so the only refusal is `invalid`: unknown,
+ * expired, or after stop(). There is no "already used" outcome.
+ */
 export type AcceptResult = {
     ok: true;
     deviceId: string;
 } | {
     ok: false;
-    code: 'invalid' | 'used';
+    code: 'invalid';
 };
 /** Thrown by issue() for an address outside the sampled LAN literals. */
 export declare class UnknownLanAddressError extends Error {
@@ -170,6 +172,11 @@ export interface PairingClock {
     now(): number;
     randomToken(): string;
 }
+/** File-operation seam for the revocation-durability step (tests). */
+export interface PairingFsSeams {
+    /** Remove the stale device store (defaults to fs.rmSync with force). */
+    removeFile?(path: string): void;
+}
 /** Real clock/entropy: 32 random hex chars per token. */
 export declare const defaultClock: PairingClock;
 /**
@@ -184,6 +191,7 @@ export declare const defaultClock: PairingClock;
 export declare class PairingService {
     config: PairingConfig;
     private readonly clock;
+    private readonly fs;
     private readonly tokens;
     private readonly devices;
     private readonly listeners;
@@ -206,7 +214,7 @@ export declare class PairingService {
      * the current one.
      * @param clock - clock/entropy source (injectable for tests).
      */
-    constructor(config: PairingConfig, clock?: PairingClock);
+    constructor(config: PairingConfig, clock?: PairingClock, fs?: PairingFsSeams);
     /**
      * Restore device sessions persisted by a previous process run. A corrupt
      * or missing file is tolerated (an empty device table, never a throw) —
@@ -228,6 +236,16 @@ export declare class PairingService {
      * atomic rename; a crash mid-write can never leave a half-written store.
      */
     private persist;
+    /**
+     * Persist a table change that REVOKES access (stop, per-device revoke, idle
+     * eviction). A failed write would leave the revoked session on disk, and
+     * {@link loadPersisted} restores that file verbatim on the next start — the
+     * device's still-valid cookie would authorize again after an explicit
+     * revocation. When the write cannot be made durable, the stale store is
+     * removed instead (a missing file already loads as an empty table), so the
+     * failure costs a re-pair rather than silently undoing the revocation.
+     */
+    private persistRevocation;
     /** The default LAN base URL (the first interface; undefined when not LAN-reachable). */
     get lanBaseUrl(): string | undefined;
     /** The LAN base URL for one specific literal (undefined when not constructible). */
@@ -241,7 +259,12 @@ export declare class PairingService {
     }[]): void;
     /** The configured public (tunneled) base URL, when present. */
     get publicBaseUrl(): string | undefined;
-    /** Set or clear the public base URL (a tunnel in front of this server). */
+    /**
+     * Set or clear the public base URL (a tunnel in front of this server). The
+     * value is canonicalized to its origin: a trailing slash (what a browser
+     * address-bar copy produces) or a path would mint a dead `//pair-accept`
+     * link, which WHATWG resolves as an authority rather than a path.
+     */
     setPublicBaseUrl(url: string | undefined): void;
     /** Set or clear the auto-tunnel status frame (undefined when the feature is off). */
     setTunnelStatus(status: TunnelStatus | undefined): void;
@@ -266,9 +289,11 @@ export declare class PairingService {
         expiresAt: number;
     };
     /**
-     * Consume a token and bind a device session. One-time: the second
-     * successful call for the same token is impossible because the first
-     * consumes it.
+     * Redeem a token and bind a device session. The token is a bearer
+     * credential for its whole window, not a single-use nonce: it is refused
+     * only when unknown, past its expiry, or after stop(), and every successful
+     * call — including a repeat within the same window — mints a fresh device
+     * session (see the module doc for the mobile cookie-context rationale).
      * @param token - the token secret from the QR link.
      * @param userAgent - optional User-Agent header captured at accept.
      * @returns the new device id, or a refusal code.
@@ -327,6 +352,13 @@ export declare class PairingService {
     private isOnlineAt;
     private notify;
 }
+/**
+ * Canonical origin of a public base URL. An unparsable value is returned
+ * verbatim so the caller's malformed-base warning stays the single owner of
+ * that case.
+ * @param url - the configured public base.
+ */
+export declare function canonicalBaseUrl(url: string): string;
 /** Strip control characters and cap the User-Agent stored with a session. */
 export declare function sanitizeUserAgent(raw: string | undefined): string | undefined;
 //# sourceMappingURL=pairing.d.ts.map

package/lib/types/pairing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"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"}

package/lib/types/pairing.js

@@ -7,9 +7,9 @@
  * Security invariants:
  * - One active token at a time; `issue()` replaces it, so a refreshed QR
  *   immediately invalidates the previous link.
- * - A token stays re-usable until it expires or is replaced: the first
- *   successful `accept()` marks it consumed, but the same link may pair
- *   again within the window (each re-accept mints a fresh device session).
+ * - A token is a bearer credential for its whole window: it is refused only
+ *   when unknown, expired, or after `stop()`, and the same link may pair
+ *   repeatedly within that window (each accept mints a fresh device session).
  *   Mobile flows routinely split across cookie contexts (camera preview to
  *   in-app browser to the system browser), and the later context must be
  *   able to complete its own pairing from the same link.
@@ -21,7 +21,7 @@
  *   `idleExpireMs` are deleted on sweep, load, and the next gated request.
  */
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 /**
  * Default idle-expiry window: 30 days without a heartbeat or a gated
@@ -62,6 +62,7 @@ export const defaultClock = {
 export class PairingService {
     config;
     clock;
+    fs;
     tokens = new Map();
     devices = new Map();
     listeners = new Set();
@@ -84,9 +85,10 @@ export class PairingService {
      * the current one.
      * @param clock - clock/entropy source (injectable for tests).
      */
-    constructor(config, clock = defaultClock) {
+    constructor(config, clock = defaultClock, fs = {}) {
         this.config = config;
         this.clock = clock;
+        this.fs = fs;
         this.loadPersisted();
     }
     /**
@@ -119,7 +121,7 @@ export class PairingService {
             }
             this.clampToMaxDevices();
             if (this.evictIdle())
-                this.persist();
+                this.persistRevocation();
         }
         catch {
             // Unreadable/corrupt: start empty rather than refusing to boot.
@@ -160,7 +162,7 @@ export class PairingService {
     persist() {
         const file = this.config.devicesFile;
         if (file === undefined)
-            return;
+            return true;
         try {
             mkdirSync(dirname(file), { recursive: true });
             const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
@@ -170,9 +172,37 @@ export class PairingService {
             writeFileSync(temp, JSON.stringify(payload), { mode: 0o600 });
             renameSync(temp, file);
             this.dirty = false;
+            return true;
         }
         catch (error) {
             console.error('remote-web-ui: failed to persist paired devices', error);
+            return false;
+        }
+    }
+    /**
+     * Persist a table change that REVOKES access (stop, per-device revoke, idle
+     * eviction). A failed write would leave the revoked session on disk, and
+     * {@link loadPersisted} restores that file verbatim on the next start — the
+     * device's still-valid cookie would authorize again after an explicit
+     * revocation. When the write cannot be made durable, the stale store is
+     * removed instead (a missing file already loads as an empty table), so the
+     * failure costs a re-pair rather than silently undoing the revocation.
+     */
+    persistRevocation() {
+        if (this.persist())
+            return;
+        const file = this.config.devicesFile;
+        if (file === undefined)
+            return;
+        try {
+            if (this.fs.removeFile !== undefined)
+                this.fs.removeFile(file);
+            else
+                rmSync(file, { force: true });
+            console.error('remote-web-ui: the device revocation could not be persisted; removed the stale device store so a restart cannot restore it');
+        }
+        catch (error) {
+            console.error('remote-web-ui: the device revocation could not be persisted and the stale device store could not be removed', error);
         }
     }
     /** The default LAN base URL (the first interface; undefined when not LAN-reachable). */
@@ -196,9 +226,14 @@ export class PairingService {
     get publicBaseUrl() {
         return this.publicBase;
     }
-    /** Set or clear the public base URL (a tunnel in front of this server). */
+    /**
+     * Set or clear the public base URL (a tunnel in front of this server). The
+     * value is canonicalized to its origin: a trailing slash (what a browser
+     * address-bar copy produces) or a path would mint a dead `//pair-accept`
+     * link, which WHATWG resolves as an authority rather than a path.
+     */
     setPublicBaseUrl(url) {
-        this.publicBase = url;
+        this.publicBase = url === undefined ? undefined : canonicalBaseUrl(url);
         this.notify();
     }
     /** Set or clear the auto-tunnel status frame (undefined when the feature is off). */
@@ -244,7 +279,6 @@ export class PairingService {
             id: `t${this.tokenSerial}`,
             issuedAt: now,
             expiresAt: now + this.config.tokenTtlMs,
-            consumed: false,
             ...(workspaceId !== undefined ? { workspaceId } : {}),
             ...(address !== undefined ? { address } : {}),
         });
@@ -252,21 +286,20 @@ export class PairingService {
         return { token, expiresAt: now + this.config.tokenTtlMs };
     }
     /**
-     * Consume a token and bind a device session. One-time: the second
-     * successful call for the same token is impossible because the first
-     * consumes it.
+     * Redeem a token and bind a device session. The token is a bearer
+     * credential for its whole window, not a single-use nonce: it is refused
+     * only when unknown, past its expiry, or after stop(), and every successful
+     * call — including a repeat within the same window — mints a fresh device
+     * session (see the module doc for the mobile cookie-context rationale).
      * @param token - the token secret from the QR link.
      * @param userAgent - optional User-Agent header captured at accept.
      * @returns the new device id, or a refusal code.
      */
     accept(token, userAgent) {
         const record = this.tokens.get(token);
-        // A consumed token stays a valid bearer credential until expiry or
-        // replacement (see the module doc): re-accept mints a fresh device.
         if (record === undefined || this.stopped || this.clock.now() > record.expiresAt) {
             return { ok: false, code: 'invalid' };
         }
-        record.consumed = true;
         const deviceId = this.clock.randomToken();
         const now = this.clock.now();
         if (this.devices.size >= this.config.maxDevices) {
@@ -297,7 +330,7 @@ export class PairingService {
     stop() {
         this.tokens.clear();
         this.devices.clear();
-        this.persist();
+        this.persistRevocation();
         this.stopped = true;
         this.notify();
     }
@@ -312,7 +345,7 @@ export class PairingService {
             return false;
         if (!this.devices.delete(deviceId))
             return false;
-        this.persist();
+        this.persistRevocation();
         this.notify();
         return true;
     }
@@ -349,7 +382,9 @@ export class PairingService {
      */
     sweep() {
         const evicted = this.evictIdle();
-        if (evicted || this.dirty)
+        if (evicted)
+            this.persistRevocation();
+        else if (this.dirty)
             this.persist();
         this.notify();
     }
@@ -407,7 +442,7 @@ export class PairingService {
         const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS;
         if (this.clock.now() - session.lastSeenAt > limit) {
             this.devices.delete(deviceId);
-            this.persist();
+            this.persistRevocation();
             this.notify();
             return undefined;
         }
@@ -494,6 +529,20 @@ function relayEqual(a, b) {
 function sameStrings(a, b) {
     return a.length === b.length && a.every((value, index) => value === b[index]);
 }
+/**
+ * Canonical origin of a public base URL. An unparsable value is returned
+ * verbatim so the caller's malformed-base warning stays the single owner of
+ * that case.
+ * @param url - the configured public base.
+ */
+export function canonicalBaseUrl(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
 /** Strip control characters and cap the User-Agent stored with a session. */
 export function sanitizeUserAgent(raw) {
     if (raw === undefined)

package/lib/types/pairing.persist.test.js

@@ -180,4 +180,30 @@ describe('PairingService device persistence', () => {
         const deviceId = result.ok ? result.deviceId : '';
         expect(saved[deviceId]?.userAgent).toBe('Mozilla/5.0 TestPhone');
     });
+    it('operator is not left with a revocation that a restart silently undoes', () => {
+        // Given a device store that cannot be written (its parent path is a file)
+        // while a stale, readable store sits beside it.
+        const blocker = join(dir, 'blocker');
+        writeFileSync(blocker, 'not a directory');
+        const file = join(blocker, 'devices.json');
+        const removed = [];
+        const service = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock(), { removeFile: (path) => { removed.push(path); } });
+        // When the operator stops remote access and the write cannot be made durable.
+        service.stop();
+        // Then the stale store is handed to the removal step, so a restart cannot
+        // restore the revoked sessions from disk.
+        expect(removed).toEqual([file]);
+    });
+    it('operator keeps the device store when a revocation persist succeeds', () => {
+        // Given a writable device store with one paired device.
+        const file = join(dir, 'devices.json');
+        const removed = [];
+        const service = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock(), { removeFile: (path) => { removed.push(path); } });
+        const deviceId = pairDevice(service);
+        // When the device is revoked and the write lands.
+        expect(service.revoke(deviceId)).toBe(true);
+        // Then the store stays (with the row gone) and nothing is removed.
+        expect(removed).toEqual([]);
+        expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({});
+    });
 });

package/lib/types/posture.d.ts

@@ -9,15 +9,23 @@
  *
  * 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.
+ * 403 or a 401 as exposed. The fence is documented to refuse with 403; the
+ * harness answers 401 when the Host fence PASSED but the browser-auth cookie
+ * is missing (the connection plugin checks the fence first and the cookie
+ * second). A 401 therefore means the /api surface is still gated — reporting
+ * it as open produced a false CRITICAL on exactly the supported LAN
+ * deployment (0.0.0.0 bind auto-trusts the LAN literals) and desensitized the
+ * one alarm that should mean a real exposure.
  */
 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). */
+    /**
+     * True when the probe reached the RPC bridge without any gate refusing it
+     * (a status that is neither the fence's 403 nor the browser-auth 401).
+     */
     exposed: boolean;
 }
 /** One probe round. */

package/lib/types/posture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posture.d.ts","sourceRoot":"","sources":["../../src/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"}
+{"version":3,"file":"posture.d.ts","sourceRoot":"","sources":["../../src/posture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;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;;;OAGG;IACH,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/posture.js

@@ -9,8 +9,13 @@
  *
  * 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.
+ * 403 or a 401 as exposed. The fence is documented to refuse with 403; the
+ * harness answers 401 when the Host fence PASSED but the browser-auth cookie
+ * is missing (the connection plugin checks the fence first and the cookie
+ * second). A 401 therefore means the /api surface is still gated — reporting
+ * it as open produced a false CRITICAL on exactly the supported LAN
+ * deployment (0.0.0.0 bind auto-trusts the LAN literals) and desensitized the
+ * one alarm that should mean a real exposure.
  */
 import http from 'node:http';
 /** Whether any probed origin is currently exposed. */
@@ -75,7 +80,7 @@ async function probeHost(port, hostHeader, request, timeoutMs) {
             path: '/api/session.list',
             headers: { host: hostHeader, 'content-type': 'application/json' },
             timeout: timeoutMs,
-        }, status => { finish(status !== 403); });
+        }, status => { finish(status !== 403 && status !== 401); });
         const timer = setTimeout(() => { finish(false); }, timeoutMs + 1_000);
         handle.on('error', () => { finish(false); });
         handle.end('{}');

package/lib/types/remote-api.d.ts

@@ -7,10 +7,14 @@
  * consult.
  *
  * Security model:
- * - While `requirePairingForLan` is on (default), every request must carry a
- *   live paired-device cookie, enforced before any bytes are forwarded and
- *   before any host call. With the policy off, the cookie gate is skipped
- *   (the local-only denials below still apply).
+ * - Every request must carry a live paired-device credential, enforced before
+ *   any bytes are forwarded and before any host call. This gate is
+ *   unconditional and does NOT follow `requirePairingForLan`: the channel
+ *   re-issues traffic with the process's own browser-auth credential, so it is
+ *   an authentication amplifier — an unpaired caller admitted here would reach
+ *   the full host API without ever holding that credential. The LAN policy
+ *   governs the plain `/api` surface only (whether the harness fence's LAN
+ *   auto-trust stands on its own); it can never widen this channel.
  * - A paired remote desktop is a full-control credential: the browser half
  *   flips the official UI into host mode (the transport ownsHost hook), so
  *   the configuration plane (settings, credentials, presets, deliverables)
@@ -31,15 +35,8 @@ export { REMOTE_API_PREFIX } from './remote-methods.ts';
 export interface RemoteApiDeps {
     /** The pairing service (device gate + cookie name). */
     service: PairingService;
-    /** The local webServer port the loopback proxy connects to. */
+    /** Local webServer port the loopback proxy connects to. */
     port: number;
-    /**
-     * Live policy: whether the paired-device cookie gates the /remote channel.
-     * When false, requests are proxied without a cookie (the loopback-only
-     * denials still apply). A function is re-read per request, so a settings
-     * edit takes effect without a restart. Defaults to true.
-     */
-    requirePairingForLan?: boolean | (() => boolean);
     /**
      * The process's inner browser-auth credential attached to re-issued
      * requests (the connection plugin's /api route enforces that cookie and
@@ -68,7 +65,7 @@ export declare function loopbackOnlyDenial(innerPath: string): string | undefine
 export declare function pairedDeviceIdOf(req: IncomingMessage, service: PairingService): string | undefined;
 /**
  * Build the remote desktop channel HTTP routes.
- * @param deps - pairing service + local port + live pairing policy.
+ * @param deps - pairing service + local port + inner credential.
  * @returns the routes to register on webServer.
  */
 export declare function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[];

package/lib/types/remote-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;IAChD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CA0CnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CA2CjF"}
+{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CAwCnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CAyCjF"}