@wrongstack/cli 1.0.3 → 1.0.6

package/dist/{hq-IG3YRGCO.js → hq-V4PHEETW.js}

@@ -2,8 +2,15 @@ import {
   parseTokenTtlValue
 } from "./chunk-UZ2TMHNH.js";
 import {
+  resolveHqPasswordInput
+} from "./chunk-AUQDGU5D.js";
+import {
+  normalizeHqPublicOrigin,
   resolveAuditActor
-} from "./chunk-Q5GTM25S.js";
+} from "./chunk-5EA6OTLJ.js";
+import {
+  parseHqIpAllowlist
+} from "./chunk-Q7E3BPDU.js";
 
 // src/subcommands/handlers/hq.ts
 import * as fs from "node:fs/promises";
@@ -14,6 +21,7 @@ import {
   hqAuthAuditPath,
   hqAuthContentHash,
   hqAuthFilePath,
+  isLoopbackHost,
   logHqAuthAudit,
   mintHqToken,
   mutateHqAuthFile,
@@ -40,6 +48,10 @@ var hqCmd = async (args, deps) => {
   if (sub === "audit") {
     return hqAuditCmd(args.slice(1), deps);
   }
+  if (sub === "service") {
+    const { hqServiceCmd } = await import("./hq-service-L5INQFM4.js");
+    return hqServiceCmd(args.slice(1), deps);
+  }
   if (sub === "help" || sub === "--help") {
     printHelp(deps);
     return 0;
@@ -50,15 +62,53 @@ var hqCmd = async (args, deps) => {
   return 1;
 };
 async function startServer(deps) {
-  const { startHqServer } = await import("./hq-server-OILU3NPI.js");
+  const { startHqServer } = await import("./hq-server-MZ7DV6X7.js");
   const dataDir = resolveDataDir(deps);
   const flags = deps.flags ?? {};
-  const host = typeof flags["host"] === "string" ? flags["host"] : HQ_CLI_DEFAULT_HOST;
+  const rawPublicUrl = typeof flags["hq-public-url"] === "string" ? flags["hq-public-url"] : process.env.WRONGSTACK_HQ_PUBLIC_URL;
+  let publicOrigin;
+  if (rawPublicUrl !== void 0 && rawPublicUrl.trim() !== "") {
+    try {
+      publicOrigin = normalizeHqPublicOrigin(rawPublicUrl);
+    } catch (cause) {
+      deps.renderer.writeError(`${cause instanceof Error ? cause.message : String(cause)}
+`);
+      return 1;
+    }
+  }
+  const host = typeof flags["host"] === "string" ? flags["host"] : publicOrigin !== void 0 ? "127.0.0.1" : HQ_CLI_DEFAULT_HOST;
   const port = typeof flags["port"] === "string" ? Number.parseInt(flags["port"], 10) : 3499;
+  if (publicOrigin !== void 0 && !isLoopbackHost(host)) {
+    deps.renderer.writeError(
+      "Persistent public HQ requires a loopback bind. Remove --host or use --host 127.0.0.1.\n"
+    );
+    return 1;
+  }
   const strictPort = flags["strict-port"] === true;
   const open = flags["open"] === true;
-  const password = typeof flags["password"] === "string" ? flags["password"] : process.env.WRONGSTACK_HQ_PASSWORD;
+  let password;
+  try {
+    password = await resolveHqPasswordInput({
+      ...typeof flags["password"] === "string" ? { explicitPassword: flags["password"] } : {}
+    });
+  } catch (cause) {
+    deps.renderer.writeError(`${cause instanceof Error ? cause.message : String(cause)}
+`);
+    return 1;
+  }
+  const bootstrapPasswordOnly = /^(?:1|true)$/i.test(
+    process.env.WRONGSTACK_HQ_BOOTSTRAP_PASSWORD_ONLY?.trim() ?? ""
+  );
   const allowInsecureOpen = flags["insecure-open"] === true;
+  const rawAllowlist = typeof flags["hq-allowlist"] === "string" ? flags["hq-allowlist"] : process.env.WRONGSTACK_HQ_ALLOWLIST;
+  let ipAllowlist;
+  try {
+    ipAllowlist = parseHqIpAllowlist(rawAllowlist);
+  } catch (cause) {
+    deps.renderer.writeError(`${cause instanceof Error ? cause.message : String(cause)}
+`);
+    return 1;
+  }
   const rawTtl = typeof flags["hq-token-ttl"] === "string" ? flags["hq-token-ttl"] : void 0;
   let tokenTtlMs;
   if (rawTtl !== void 0 && rawTtl.length > 0) {
@@ -94,9 +144,13 @@ async function startServer(deps) {
       strictPort,
       dataDir,
       allowInsecureOpen,
+      secureCookies: publicOrigin !== void 0,
+      requireBrowserAuth: publicOrigin !== void 0,
       ...password !== void 0 ? { password } : {},
+      ...bootstrapPasswordOnly ? { bootstrapPasswordOnly: true } : {},
       ...tokenTtlMs !== void 0 ? { tokenTtlMs } : {},
-      ...trustedProxyHops !== void 0 ? { trustedProxyHops } : {}
+      ...trustedProxyHops !== void 0 ? { trustedProxyHops } : {},
+      ...ipAllowlist !== void 0 ? { ipAllowlist } : {}
     });
   } catch (err) {
     if (err instanceof HqInsecureExposureError) {
@@ -106,14 +160,34 @@ async function startServer(deps) {
     }
     throw err;
   }
+  if (publicOrigin !== void 0) {
+    if (handle.firstRunSetup?.passwordMode !== true) {
+      await handle.close();
+      deps.renderer.writeError(
+        "Persistent public HQ requires password mode. Set WRONGSTACK_HQ_PASSWORD and retry.\n"
+      );
+      return 1;
+    }
+    handle.trustPublicOrigin(publicOrigin);
+    deps.renderer.write(`Public endpoint:  ${publicOrigin}/
+`);
+    deps.renderer.write(`Public mobile:    ${publicOrigin}/mobile
+`);
+  }
   if (open) {
     try {
       const { openBrowser } = await import("@wrongstack/webui-server");
-      openBrowser(handle.firstRunSetup?.browserUrl ?? `http://${handle.host}:${handle.port}`);
+      openBrowser(
+        publicOrigin ?? handle.firstRunSetup?.browserUrl ?? `http://${handle.host}:${handle.port}`
+      );
     } catch {
     }
   }
   writeStartupInfo(deps, handle);
+  deps.renderer.write(
+    ipAllowlist === void 0 ? "Network allowlist: disabled (authentication remains required when configured).\n" : `Network allowlist: active (${ipAllowlist.length} configured rule${ipAllowlist.length === 1 ? "" : "s"} + loopback).
+`
+  );
   await new Promise((resolve) => {
     const shutdown = async () => {
       try {
@@ -137,9 +211,34 @@ function writeStartupInfo(deps, handle) {
 `);
     deps.renderer.write(`Browser endpoint: http://${handle.host}:${handle.port}
 `);
+    deps.renderer.write(
+      `Mobile endpoint:  http://${handle.host}:${handle.port}/mobile (password required)
+`
+    );
+    return;
+  }
+  if (process.env.WRONGSTACK_HQ_SUPPRESS_STARTUP_SECRETS === "1") {
+    deps.renderer.write(`Browser endpoint: http://${handle.host}:${handle.port}
+`);
+    deps.renderer.write(
+      `Mobile endpoint:  http://${handle.host}:${handle.port}/mobile (password required)
+`
+    );
+    deps.renderer.write(`Client endpoint:  ws://${handle.host}:${handle.port}/ws/client
+`);
+    deps.renderer.write(
+      `Startup credentials suppressed; auth state is stored in ${handle.firstRunSetup.dataDir}.
+`
+    );
     return;
   }
+  const mobileUrl = new URL(handle.firstRunSetup.browserUrl);
+  mobileUrl.pathname = "/mobile";
+  mobileUrl.search = "";
+  mobileUrl.hash = "";
   deps.renderer.write(`Browser endpoint: ${handle.firstRunSetup.browserUrl}
+`);
+  deps.renderer.write(`Mobile endpoint:  ${mobileUrl.toString()} (password required)
 `);
   deps.renderer.write(`Client endpoint:  ${handle.firstRunSetup.clientUrl}
 `);
@@ -537,7 +636,7 @@ async function tokenRevoke(args, deps) {
   return 0;
 }
 function printHelp(deps) {
-  deps.renderer.write(`Usage: wstack hq <serve | token | audit>
+  deps.renderer.write(`Usage: wstack hq <serve | token | audit | service>
 `);
   deps.renderer.write("\n");
   deps.renderer.write(`  wstack hq                      Start the HQ command center server.
@@ -564,6 +663,18 @@ function printHelp(deps) {
 `);
   deps.renderer.write(
     `  wstack hq audit verify         Re-derive auth.json contentHash for forensic comparison.
+`
+  );
+  deps.renderer.write(
+    `  wstack hq service install      Install persistent Ubuntu/systemd service + updater timer.
+`
+  );
+  deps.renderer.write(`  wstack hq service status       Show service and updater status.
+`);
+  deps.renderer.write(`  wstack hq service update       Run the guarded update job now.
+`);
+  deps.renderer.write(
+    `  wstack hq service uninstall    Remove units but preserve HQ data and secret file.
 `
   );
   deps.renderer.write("\n");
@@ -579,6 +690,10 @@ function printHelp(deps) {
   );
   deps.renderer.write(
     `  --tunnel            Publish a temporary *.trycloudflare.com URL (requires cloudflared).
+`
+  );
+  deps.renderer.write(
+    `  --hq-public-url <https-origin>  Trust a persistent TLS reverse-proxy origin; binds loopback and requires password mode.
 `
   );
   deps.renderer.write(`  --password <value>  Set or rotate the browser login password.
@@ -599,6 +714,10 @@ function printHelp(deps) {
     `  --hq-trusted-proxy-hops <n>  Trust the rightmost n X-Forwarded-For entries when rate-limiting logins.
                         Default 0 (ignore the header). Set to the real hop count behind a tunnel,
                         otherwise every user shares one backoff bucket. Never guess high.
+`
+  );
+  deps.renderer.write(
+    `  --hq-allowlist <csv>  Optional source IP/CIDR allowlist (for example 203.0.113.4,10.0.0.0/8).
 `
   );
   deps.renderer.write(`  --open              Open the dashboard in the default browser.
@@ -708,4 +827,4 @@ export {
   hqCmd,
   resolveAuditActor
 };
-//# sourceMappingURL=hq-IG3YRGCO.js.map
+//# sourceMappingURL=hq-V4PHEETW.js.map

package/dist/hq-command-controller.d.ts

@@ -6,8 +6,9 @@
  * (`director`, the rebound `interruptLeader`) are not yet defined at HQ-connect
  * time.
  *
- * The five command types route through the agent's own decision loop or the
- * project mailbox, so they inherit existing guardrails. `run-command` (raw
+ * Conversational commands route through the agent's own decision loop or the
+ * project mailbox; Kanban commands route through its project IPC owner, so
+ * both inherit existing guardrails. `run-command` (raw
  * shell) is deliberately NOT wired here — it requires a separately-audited
  * escalation policy (operator flag + per-token `control.execute` + allowlist)
  * and is left as a stub that rejects until that policy exists.
@@ -67,7 +68,35 @@ export interface HqCommandController {
     ownsSession?: ((sessionId: string) => boolean) | undefined;
     /** Whether raw shell execution is explicitly opted-in by the operator. */
     allowRunCommand: () => boolean;
+    /** Apply a lifecycle transition through the project's Kanban IPC client. */
+    kanbanTransition?: ((input: {
+        boardId: string;
+        taskId: string;
+        to: 'backlog' | 'todo' | 'running' | 'review' | 'done';
+        comment: string;
+        sessionId?: string | undefined;
+    }) => Promise<string>) | undefined;
+    /** Assign a card through the project owner while preserving active leases. */
+    kanbanAssign?: ((input: {
+        boardId: string;
+        taskId: string;
+        agentId: string;
+        assignee: string;
+        comment: string;
+        sessionId?: string | undefined;
+    }) => Promise<string>) | undefined;
+    /** Claim and dispatch one ready card through this host's canonical Director path. */
+    kanbanDispatch?: ((input: {
+        boardId: string;
+        taskId: string;
+        comment: string;
+        sessionId?: string | undefined;
+    }) => Promise<string>) | undefined;
 }
+/** Bind HQ transitions to the same project-scoped IPC path every other client uses. */
+export declare function createProjectKanbanTransitionHandler(projectRoot: string): NonNullable<HqCommandController['kanbanTransition']>;
+/** Bind guarded HQ assignment to the canonical project-scoped Kanban owner. */
+export declare function createProjectKanbanAssignHandler(projectRoot: string): NonNullable<HqCommandController['kanbanAssign']>;
 /**
  * Build the `onCommand` handler for an HQ publisher. The handler validates
  * the command, dispatches through the controller, and returns an ack result

package/dist/hq-server/auth-state.d.ts

@@ -6,6 +6,12 @@ export interface HqAuthState {
     tokenStats(): NonNullable<HqSnapshot['totals']['tokenStats']>;
 }
 interface HqAuthStateOptions {
+    /**
+     * The server's `requireBrowserAuth` option, stamped onto the state so every
+     * `hqAuthRequired(mutableAuth)` gate observes it without having to be handed
+     * it separately. See the field's doc on `HqRouterMutableAuth`.
+     */
+    requireBrowserAuth?: boolean | undefined;
     /**
      * Invoked after every {@link HqAuthState.apply}, with the freshly projected
      * `mutableAuth`. The server wires this to the WS-010 exposure re-assessment

package/dist/hq-server/auth.d.ts

@@ -38,7 +38,16 @@ export type HqBrowserAuthResult = HqBrowserAuthContext | HqCookieAuthContext | u
  * inline style is not script execution.
  */
 export declare function setHqSecurityHeaders(res: http.ServerResponse): void;
-export declare function hasTrustedBrowserOrigin(req: http.IncomingMessage, boundHost?: string, boundPort?: number, trustedPublicOrigins?: ReadonlySet<string>, allowFileOrigin?: boolean): boolean;
+export declare function hasTrustedBrowserOrigin(req: http.IncomingMessage, boundHost?: string, boundPort?: number, trustedPublicOrigins?: ReadonlySet<string>, allowFileOrigin?: boolean, 
+/**
+ * Whether this surface has any credential configured — pass
+ * `hqAuthRequired(mutableAuth, requireBrowserAuth)`.
+ *
+ * Defaults to `false`, the STRICT side, deliberately: a caller that forgets
+ * to wire it gets the tighter rule rather than the looser one. That is the
+ * opposite of how the WS-077 gates drifted.
+ */
+credentialedSurface?: boolean): boolean;
 export declare function serializeHqSessionCookie(sessionId: string, secret: string): string;
 export declare function parseHqSessionCookie(value: string, secret: string): string | undefined;
 export declare function parseCookieHeader(cookieHeader: string | undefined): Record<string, string>;

package/dist/hq-server/client-address.d.ts

@@ -35,6 +35,8 @@
  * @module hq-server/client-address
  */
 import type * as http from 'node:http';
+/** The actual TCP peer, with IPv4-mapped IPv6 normalized. Never reads headers. */
+export declare function resolveSocketAddress(req: http.IncomingMessage): string | undefined;
 /**
  * Parse one `X-Forwarded-For` element into a bare address, or `undefined` when
  * it is not one. Handles `1.2.3.4`, `1.2.3.4:5678`, `[::1]`, and `[::1]:5678`.

package/dist/hq-server/ip-allowlist.d.ts

@@ -0,0 +1,16 @@
+export interface HqIpAllowlist {
+    readonly entries: readonly string[];
+    allows(address: string | undefined): boolean;
+}
+/**
+ * Build the optional HQ admission allowlist.
+ *
+ * Matching is intentionally performed against the TCP peer, never a forwarded
+ * header. When HQ is directly reachable on 0.0.0.0, trusting a client-supplied
+ * X-Forwarded-For value here would turn the allowlist into a bypass. Loopback
+ * remains implicit so local administration and health checks cannot be locked
+ * out by a remote-only list.
+ */
+export declare function createHqIpAllowlist(rules: readonly string[] | undefined): HqIpAllowlist | undefined;
+export declare function parseHqIpAllowlist(value: string | undefined): string[] | undefined;
+//# sourceMappingURL=ip-allowlist.d.ts.map

package/dist/hq-server/preflight.d.ts

@@ -4,6 +4,7 @@ interface HqPreflightOptions {
     port?: number;
     dataDir?: string;
     password?: string;
+    bootstrapPasswordOnly?: boolean;
     tokenTtlMs?: number;
     requireBrowserAuth?: boolean;
     allowInsecureOpen?: boolean;

package/dist/hq-server/routes/auth/common.d.ts

@@ -1,7 +1,41 @@
 import type * as http from 'node:http';
 import { type HqAuthFile } from '@wrongstack/core/hq';
 import { type HqBrowserAuthResult } from '../../auth.js';
+import type { LoginAttemptStore } from '../../login-attempt-store.js';
 import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+/**
+ * Record a failed second-factor confirmation and return the new failure count.
+ *
+ * Shared by every route that verifies a factor outside `/api/login`
+ * (totp/disable, password change). Kept here rather than copied per route: the
+ * whole point is that each of those routes feeds the SAME per-IP counter, so a
+ * attacker cannot get a fresh budget by switching endpoints.
+ */
+export declare function recordVerifyFailure(loginAttempts: LoginAttemptStore, clientIp: string): number;
+/** Outcome of {@link consumeTotpCode}. */
+export type TotpConsumeResult = 'ok' | 'invalid' | 'replayed';
+/**
+ * Verify a TOTP code AND burn it, so it cannot be presented a second time.
+ *
+ * A TOTP code stays valid for its whole time step plus the verification
+ * window — roughly 90 seconds. Without a single-use record, one observed code
+ * can be replayed at a *different* endpoint for as long as that window lasts.
+ * That is not theoretical here: `/api/login/verify` advanced
+ * `totpLastUsedCounter` and the other two verification sites
+ * (`totp/disable`, `auth/password`) called the counter-less `verifyTotp`, so a
+ * code already spent on a login replayed into removing 2FA outright or
+ * rotating the password and cookie secret.
+ *
+ * Kept in this module for the same reason as {@link recordVerifyFailure}: the
+ * property only holds if EVERY site that verifies a code shares one counter.
+ * A route that verifies a TOTP code by any other means is a bug —
+ * `hq-totp-single-use.test.ts` enumerates the call sites to keep it that way.
+ *
+ * The counter is advanced in memory first and persisted best-effort, matching
+ * the pre-existing behaviour at `/api/login/verify`: a failed write must not
+ * turn a consumed code back into an unconsumed one for this process.
+ */
+export declare function consumeTotpCode(code: string, mutableAuth: HqRouterMutableAuth, dataDir: string, applyAuthFile: ApplyHqAuthFile): Promise<TotpConsumeResult>;
 export declare function isLoopbackRequest(req: http.IncomingMessage): boolean;
 export declare const HQ_AUTH_ADMIN_CAPABILITY = "auth.admin";
 export declare function callerCanAdministerAuth(auth: HqBrowserAuthResult): boolean;

package/dist/hq-server/routes/auth/password-routes.d.ts

@@ -3,7 +3,9 @@ import type { LoginAttemptStore } from '../../login-attempt-store.js';
 import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
 import { type ApplyHqAuthFile } from './common.js';
 export declare function handleApiAuthStatus(req: http.IncomingMessage, res: http.ServerResponse, url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, requireBrowserAuth: boolean | undefined, trustedPublicOrigins: Set<string>, secureCookies: boolean | undefined): Promise<void>;
-export declare function handleApiLogin(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, secureCookies: boolean | undefined, trustedProxyHops: number): Promise<void>;
+export declare function handleApiLogin(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, secureCookies: boolean | undefined, trustedProxyHops: number, 
+/** Where `auth.json` lives — needed to persist a transparent KDF upgrade. */
+dataDir: string, sessionCapabilities?: string[]): Promise<void>;
 export declare function handleApiLogout(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, secureCookies: boolean | undefined): Promise<void>;
-export declare function handleApiPassword(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, secureCookies: boolean | undefined, requireBrowserAuth: boolean | undefined, applyAuthFile: ApplyHqAuthFile): Promise<void>;
+export declare function handleApiPassword(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, secureCookies: boolean | undefined, requireBrowserAuth: boolean | undefined, applyAuthFile: ApplyHqAuthFile, loginAttempts: LoginAttemptStore, trustedProxyHops: number): Promise<void>;
 //# sourceMappingURL=password-routes.d.ts.map

package/dist/hq-server/routes.d.ts

@@ -8,10 +8,8 @@
  * @module hq-server/routes
  */
 import type * as http from 'node:http';
-import type { createMailboxHttpRouter } from '@wrongstack/core/coordination';
-import type { Mailbox, MailboxHttpAccessDecision, MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
-import type { HqAlertEngine, HqCommandAuditLog, HqEventEnvelope, HqSnapshot, HqTranscriptEntry } from '@wrongstack/core/hq';
-import type { createHqPersistence } from '@wrongstack/core/hq';
+import type { createMailboxHttpRouter, Mailbox, MailboxHttpAccessDecision, MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
+import type { createHqPersistence, HqAlertEngine, HqCommandAuditLog, HqEventEnvelope, HqSnapshot, HqTranscriptEntry } from '@wrongstack/core/hq';
 import type { TrustBoundary } from '@wrongstack/core/security';
 import type { WebSocket } from 'ws';
 import * as HqServerAuth from './auth.js';
@@ -41,6 +39,7 @@ export declare const agentMessageToEntry: typeof HqServerUtils.agentMessageToEnt
 export declare const readLocalSubagentTranscript: typeof HqServerUtils.readLocalSubagentTranscript;
 export declare const lanIPv4Addresses: typeof HqServerUtils.lanIPv4Addresses;
 export declare const hqRuntimeMarkerPath: typeof HqServerUtils.hqRuntimeMarkerPath;
+import type { HqIpAllowlist } from './ip-allowlist.js';
 import type { LoginAttemptStore } from './login-attempt-store.js';
 import type { ConnectedClient, HqRouterMutableAuth, HqSessionEntry, HqSnapshotBroadcaster, ProjectDetail, TranscriptRing } from './types.js';
 export type { ConnectedClient, HqSnapshotBroadcaster, ProjectDetail, TranscriptRing };
@@ -99,6 +98,8 @@ export interface HqRouterDeps {
      * Defaults to 0, which ignores `X-Forwarded-For` entirely.
      */
     trustedProxyHops?: number | undefined;
+    /** TCP-peer allowlist shared by HTTP and WebSocket admission. */
+    ipAllowlist?: HqIpAllowlist | undefined;
 }
 /**
  * Create the HTTP request listener that handles all `/api/*` routes as well

package/dist/hq-server/secret-input.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveHqPasswordOptions {
+    explicitPassword?: string | undefined;
+    environment?: NodeJS.ProcessEnv | undefined;
+}
+/** Resolve HQ password input without putting Docker/Kubernetes secrets in argv or env values. */
+export declare function resolveHqPasswordInput(options?: ResolveHqPasswordOptions): Promise<string | undefined>;
+//# sourceMappingURL=secret-input.d.ts.map

package/dist/hq-server/types.d.ts

@@ -103,11 +103,30 @@ export interface HqRouterMutableAuth {
      * the surface fails closed instead of opening up.
      */
     requireAuthFloor?: boolean | undefined;
+    /**
+     * The server's `requireBrowserAuth` option, carried on the state rather than
+     * passed to every gate.
+     *
+     * `hqAuthRequired` takes it as an optional second argument, and five gates
+     * called it with one — `command-handlers`, three in `mailbox-handlers`, and
+     * `mailbox-gateway-manager` — so a public relay did not raise the auth
+     * requirement on those routes. That is the WS-077 drift class the helper's
+     * own docstring warns about, recurring on the same routes. Holding the value
+     * on the state makes the one-argument call correct instead of incomplete.
+     *
+     * Required, not optional, and deliberately so. Optional would mean a second
+     * construction site could omit it and every one-argument gate would silently
+     * read `undefined` — the same drift this field exists to end, one level down.
+     * With `exactOptionalPropertyTypes` the compiler now makes every builder say
+     * what it means, including `undefined`.
+     */
+    requireBrowserAuth: boolean | undefined;
 }
 /**
  * Session record stored in the server-side `sessions` Map.
  *
- * - `kind: 'password'` — created by `/api/login`; full browser access.
+ * - `kind: 'password'` — created by `/api/login`; full browser access unless
+ *   the dedicated mobile endpoint stamped a least-privilege capability set.
  * - `kind: 'token'` — created by `/api/auth/bootstrap`; scoped to the
  *   originating browser token's ID and capabilities so revocation/expiry
  *   of that token invalidates the session too.
@@ -117,7 +136,7 @@ export interface HqSessionEntry {
     readonly kind: 'password' | 'token';
     /** For token sessions: the browser-token ID this session was minted from. */
     readonly tokenId?: string | undefined;
-    /** For token sessions: capabilities inherited from the source token. */
+    /** Token capabilities, or a server-stamped scope for a mobile password session. */
     readonly capabilities?: string[] | undefined;
     /**
      * Set when a password login passed but 2FA verification is still pending.

package/dist/hq-server/upgrade-handler.d.ts

@@ -8,6 +8,7 @@ import type { Duplex } from 'node:stream';
 import { type HqToken } from '@wrongstack/core/hq';
 import type { WebSocket, WebSocketServer } from 'ws';
 import type { HqAuthState } from './auth-state.js';
+import type { HqIpAllowlist } from './ip-allowlist.js';
 import type { ConnectedClient, HqSessionEntry, TranscriptRing } from './types.js';
 interface HqUpgradeHandlerDeps {
     host: string;
@@ -28,6 +29,7 @@ interface HqUpgradeHandlerDeps {
     auditLog: import('@wrongstack/core/hq').HqCommandAuditLog;
     snapshotBroadcaster: ReturnType<typeof import('./snapshot.js').createSnapshotBroadcaster>;
     wss: WebSocketServer;
+    ipAllowlist?: HqIpAllowlist | undefined;
 }
 export declare function handleHqUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, deps: HqUpgradeHandlerDeps): void;
 export declare function handleHqConnection(ws: WebSocket, req: IncomingMessage, pathname: string, deps: HqUpgradeHandlerDeps): void;

package/dist/hq-server/utils.d.ts

@@ -95,6 +95,12 @@ export declare function buildHttpUrl(host: string, port: number, token?: string)
  */
 export declare function buildBootstrapHttpUrl(host: string, port: number, bootstrapCode: string): string;
 export declare function buildClientWsUrl(host: string, port: number, token?: string): string;
+/**
+ * Validate and normalize a browser-facing HQ origin supplied for a persistent
+ * HTTPS reverse proxy. Paths, credentials, query strings and fragments are
+ * refused because the value becomes a Host/Origin trust-boundary entry.
+ */
+export declare function normalizeHqPublicOrigin(value: string): string;
 export declare function hqRuntimeMarkerPath(dataDir: string): string;
 /** Non-internal IPv4 addresses, so we can print URLs reachable from other machines. */
 export declare function lanIPv4Addresses(): string[];

package/dist/{hq-server-OILU3NPI.js → hq-server-MZ7DV6X7.js}

@@ -10,9 +10,10 @@ import {
   readLocalSubagentTranscript,
   sanitizeApiError,
   startHqServer
-} from "./chunk-C2E24IXZ.js";
+} from "./chunk-PQZPHGGD.js";
 import "./chunk-HXJYHAR4.js";
-import "./chunk-Q5GTM25S.js";
+import "./chunk-5EA6OTLJ.js";
+import "./chunk-Q7E3BPDU.js";
 export {
   DEFAULT_HOST,
   DEFAULT_PORT,
@@ -26,4 +27,4 @@ export {
   sanitizeApiError,
   startHqServer
 };
-//# sourceMappingURL=hq-server-OILU3NPI.js.map
+//# sourceMappingURL=hq-server-MZ7DV6X7.js.map

package/dist/hq-server.d.ts

@@ -30,12 +30,16 @@ interface HqServerOptions {
     clientCleanupIntervalMs?: number;
     sessionSnapshotTtlMs?: number;
     password?: string;
+    /** Keep an existing Settings-managed password instead of reapplying the startup secret. */
+    bootstrapPasswordOnly?: boolean;
     allowInsecureOpen?: boolean;
     secureCookies?: boolean;
     requireBrowserAuth?: boolean;
     allowFileOrigin?: boolean;
     tokenTtlMs?: number;
     trustedProxyHops?: number;
+    /** Optional exact-IP/CIDR admission list. Empty/absent means unrestricted. */
+    ipAllowlist?: readonly string[];
 }
 import type { HqServerHandle } from './hq-server/handle-types.js';
 export type { HqFirstRunSetup, HqServerHandle, HqStartupConnectionInfo, } from './hq-server/handle-types.js';