@verax-ai/body 0.3.0 → 0.4.0

package/dist/desktop.d.ts

@@ -1,3 +1,13 @@
+import { type ChildProcess } from "node:child_process";
+import { type Server } from "node:net";
+/** One stderr line when this state has no enrolled operator. */
+export declare const DESKTOP_PASSKEY_HINT = "the panel reads the ledger after a passkey sign-in; run verax operator enroll\n";
+/**
+ * The credentials file is written only when an operator enrolls. Its presence
+ * is the whole answer; a missing file means the panel's audit doors will
+ * refuse the session that has no passkey.
+ */
+export declare function desktopPasskeyHint(stateDir: string): string | null;
 export declare function resolveRepoRoot(): string;
 export declare const DESKTOP_CLONE_ONLY = "verax desktop runs from a clone of github.com/verax-ai/verax; it is not in the npm package\n";
 export declare function desktopCloneError(root: string): string | null;
@@ -16,10 +26,48 @@ export type DesktopOpts = {
  * and reopening it showed the previous app, with no sign that it was stale.
  */
 export declare function panelBuildNeeded(distIndex: string, sourceRoots: readonly string[]): boolean;
-export declare function parseDesktopArgs(argv: string[]): DesktopOpts | {
+/** UNC share or a Win32 device path (`\\?\`, `\\.\`, `\\?\UNC\`, `//host`): all start with two separators. */
+export declare function desktopStateUncOrDevice(stateDir: string): boolean;
+export declare function parseDesktopArgs(argv: string[], platform?: NodeJS.Platform): DesktopOpts | {
     error: string;
 };
 export declare function portOpen(port: number, host?: string): Promise<boolean>;
+/**
+ * Bind 127.0.0.1 and [::1], then close both. True only when this process held
+ * 127.0.0.1 and [::1] was free or this host has no IPv6 loopback. A connect
+ * probe is not this: whoever is already listening would answer it.
+ */
+export declare function desktopPortFree(port: number): Promise<boolean>;
+/** True when a socket can bind [::1]. False when the host has no IPv6 loopback. */
+export declare function ipv6LoopbackAvailable(): Promise<boolean>;
+/**
+ * Hold `[::1]:port` and pipe each accepted socket to `127.0.0.1:port`.
+ * `unsupported` means this host cannot bind the IPv6 loopback.
+ */
+export declare function forwardIpv6Loopback(port: number): Promise<{
+    ok: true;
+    server: Server;
+} | {
+    ok: false;
+    reason: "busy" | "unsupported";
+}>;
+export declare function desktopPortBusyLine(name: DesktopChildName, port: number, ipv6?: boolean): string;
+/** JWKS document the dev issuer rewrites under the state directory on every start. */
+export declare function issuerJwksPinPath(stateDir: string): string;
+/** Drop a file left by an earlier run. A missing file is the state we want. */
+export declare function discardStaleFile(file: string): void;
+/**
+ * The pin is the file the issuer just wrote. Compact JSON, or a throw when
+ * it is not a key set. Nothing is fetched.
+ */
+export declare function readIssuerJwksPin(stateDir: string): string;
+export declare function issuerReadyLine(port: number): string;
+export declare function bodyReadyLine(port: number): string;
+export declare function panelReadyLine(port: number): string;
+export declare function childStillAlive(child: {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+}): boolean;
 /** GET /healthz on the loopback port; true only for a 200. */
 export declare function healthzUp(port: number): Promise<boolean>;
 export type DesktopMode = {
@@ -30,26 +78,107 @@ export type DesktopMode = {
 } | {
     error: "desktop-body-locked";
     pid: number;
+    lockPort: number | null;
 };
+/** Pid listening on 127.0.0.1:`port`, or null when the tool names nobody or more than one pid. */
+export declare function loopbackListenPid(port: number, platform?: NodeJS.Platform): number | null;
 /**
  * One ledger, one body. The desktop used to build its own issuer and body on
  * every open, which on a machine whose body starts at logon put the window on
  * a second, empty ledger: the panel looked broken while the real decisions sat
- * in the directory the lock names. So the lock is read first. Held by a live
- * process that answers /healthz where this run was told to look, the panel
- * joins that body. Held by a live process that does not answer there, the
- * desktop stops: someone owns the ledger and is not where we were pointed, and
- * a second body would be refused by the lock anyway. A dead or unreadable lock
- * is the body's own to clear (`verax unlock`); the desktop builds as before.
- */
-export declare function desktopMode(stateDir: string, bodyPort: number, probe?: (port: number) => Promise<boolean>): Promise<DesktopMode>;
+ * in the directory the lock names. So the lock is read first. A live lock that
+ * records this port, whose pid is the listener on 127.0.0.1 there, is
+ * `attach`. 0.4.0 does not join that body: `runDesktop` stops before it
+ * claims a port or starts a child. A later release may join again, once that
+ * body is supervised. A 200 from /healthz is not the check. Any other live
+ * lock stops the desktop: `desktop-body-locked:<pid>:<port or unknown>`. A
+ * lock with no port is that stop until the body is started again. A dead or
+ * unreadable lock is left for `verax unlock`, which is only for a dead lock.
+ */
+export declare function desktopMode(stateDir: string, bodyPort: number, listenerPid?: (port: number) => number | null): Promise<DesktopMode>;
+export type DesktopChildName = "issuer" | "body" | "panel";
+export type SupervisedChild = {
+    name: DesktopChildName;
+    /** Registers the listener invoked when this child exits. May run it immediately if it already has. */
+    onExit: (listener: () => void) => void;
+};
+/**
+ * The first of the issuer, the body or the panel to exit stops the rest.
+ * A later exit does not stop again. `stillWatching` is false once this run
+ * is shutting down on purpose, so those exits are not a child failure.
+ */
+export declare function superviseDesktopChildren(children: readonly SupervisedChild[], stopAll: () => void, stillWatching?: () => boolean): Promise<DesktopChildName>;
+export declare function desktopChildExitedLine(name: DesktopChildName): string;
+export type DesktopSpawnName = DesktopChildName | "browser";
+/**
+ * Stand-in for `process` so a test can emit SIGHUP, SIGBREAK, an uncaught
+ * exception, or `exit` without signalling this process. `platform` chooses
+ * SIGHUP (anything but win32) or SIGBREAK (win32).
+ */
+export type DesktopSignalHost = {
+    once: (event: string, listener: () => void) => void;
+    on: (event: string, listener: () => void) => void;
+    removeListener: (event: string, listener: () => void) => void;
+    exit: (code: number) => void;
+    platform?: NodeJS.Platform;
+};
+/** Test seam. Production leaves this unset and spawns the real children. */
+export type DesktopHooks = {
+    spawn?: (name: DesktopSpawnName, cmd: string, args: string[], env: NodeJS.ProcessEnv, cwd: string) => ChildProcess;
+    /** Caps issuer, body, and panel readiness waits. The CLI uses the built-in budgets. */
+    readyMs?: number;
+    /** Replaces the listener-pid lookup. */
+    listenerPid?: (port: number) => number | null;
+    /** Replaces the Windows owner ACL call on the state directory and the browser profile. */
+    restrictOwner?: (dir: string) => void;
+    /** Replaces `process.platform` for the directory owner check. */
+    platform?: NodeJS.Platform;
+    /** Replaces the Windows owner-SID and invoking-SID lookup. */
+    windowsDirectoryOwner?: (dir: string) => {
+        ownerSid?: string;
+        invokingSid?: string;
+    };
+    /** Replaces the Windows DACL read. The text is the SDDL `windowsUserCanWrite` already judges. */
+    windowsDirectoryDacl?: (dir: string) => string;
+    /**
+     * Replaces the ancestor DACL read. When set, each ancestor is judged with
+     * `windowsUserCanWrite(..., { ancestor: true })`. When a leaf owner or leaf
+     * DACL hook is set and this is not, ancestors are not read from the machine.
+     */
+    windowsAncestorDacl?: (dir: string) => string;
+    /** Replaces `killTree` for the children this run started. */
+    kill?: (pid: number | undefined) => void;
+    /** Called with the capped stdout/stderr kept for one child. */
+    childOutput?: (name: DesktopSpawnName, stored: string) => void;
+    /** Replaces `process` for stop handlers. Production uses this process. */
+    signals?: DesktopSignalHost;
+};
+/**
+ * The account SIDs in place of the `LA` / `LG` aliases, so the built-in
+ * Administrator's own entry compares equal to its SID (a GitHub Windows
+ * runner runs as that account). An alias with no SID given is left, and the
+ * judge treats it as someone else.
+ */
+export declare function expandLocalAccountAliases(sddl: string, sids: {
+    LA?: string;
+    LG?: string;
+}): string;
+/** Last bytes kept from a child so a long log cannot grow without a bound. */
+export declare const DESKTOP_CHILD_OUTPUT_CAP: number;
+/** Keep the tail. A ready line at the end of a large chunk stays inside the cap. */
+export declare function rememberChildOutput(current: string, chunk: string, cap?: number): string;
+/** Synchronous: `spawnSync` on Windows, `process.kill` elsewhere. An `exit` handler can call it. */
 export declare function killTree(pid: number | undefined): void;
+/** Comma-separated origins. An origin already listed is not added again. */
+export declare function mergeAllowedOrigin(existing: string | undefined, origin: string): string;
 /** The panel's redirect is its own origin, so the issuer has to be told which port
- *  this run put it on: the allow-list default only holds 5173 and 4173. */
+ *  this run put it on: the allow-list default only holds 5173 and 4173.
+ *  The passkey ceremony runs on the issuer (`/authorize` and `/enroll`), so the
+ *  RP ID and RP origins name that origin unless the operator already set them. */
 export declare function issuerEnv(base: NodeJS.ProcessEnv, opts: {
     stateDir: string;
     issuerPort: number;
     panelPort: number;
 }, audience: string, issuerUrl: string): NodeJS.ProcessEnv;
-export declare function runDesktop(opts: DesktopOpts, writeErr?: (s: string) => void): Promise<number>;
+export declare function runDesktop(opts: DesktopOpts, writeErr?: (s: string) => void, hooks?: DesktopHooks): Promise<number>;
 export declare function desktopMain(argv: string[]): Promise<number>;