sealkeep 0.9.0 → 0.11.0

package/dist/src/ui-server.d.ts

@@ -1,3 +1,28 @@
+/**
+ * The GUI, reachable without typing a command.
+ *
+ * PRODUCT_ARCHITECTURE.md §5: the terminal is the free tier's interface, not
+ * the product's. `src/local-api.ts` already serves the settings surface and
+ * `web/` already draws it — what was missing was a way to get a browser
+ * pointed at it, authenticated, without a person copying a token by hand.
+ *
+ * This module is the plumbing for that and nothing else. It starts (or finds)
+ * the loopback server, mints a short-lived one-use browser ticket, and launches
+ * a browser. Every line printed to a terminal lives in cli.ts, so this stays
+ * usable by any surface that is not a terminal — the native shell in §5 v2
+ * being the obvious one.
+ */
+declare const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * `taskpolicy -B` is PID-only on macOS. Its supported command form is `-a`,
+ * which gives the child application scheduling/resource policy instead of
+ * inheriting an old service definition's background policy. Keep both paths
+ * argument-vector based: no shell parses a PID or command.
+ */
+export declare function uiPsIdentityCommand(pid: number, targetPlatform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+};
 /**
  * The name to show a person, as opposed to the address to bind.
  *
@@ -24,8 +49,6 @@ export declare const DISPLAY_HOST = "localhost";
  * window on an odd port beats a correct error.
  */
 export declare const DEFAULT_UI_PORT = 7477;
-/** The hostnames this service answers to, mirrored by ALLOWED_HOSTS in local-api.ts. */
-export declare const UI_HOSTNAMES: readonly ["localhost", "127.0.0.1", "vault.line", "vault.localhost"];
 /**
  * Where a running server announces itself, so a second `sealkeep ui` finds it.
  *
@@ -35,31 +58,50 @@ export declare const UI_HOSTNAMES: readonly ["localhost", "127.0.0.1", "vault.li
  * else in there rather than being the one loose file.
  */
 export declare const uiRecordPath: (dataDir: string) => string;
+export type UiOwner = "interactive" | "autopilot";
 export type UiRecord = {
     port: number;
     pid: number;
     startedAt: string;
+    /** Who owns the listener lifecycle. Absent means an older interactive build. */
+    owner?: UiOwner;
+    /** The stable port this listener attempted before any collision fallback. */
+    requestedPort?: number;
+    /** Per-listener generation. Required for authenticated adoption and exact cleanup. */
+    instanceId?: string;
+    /** Kernel process generation; unlike pid, this is not reused after a crash. */
+    processIdentity?: string;
 };
 /** Anything unreadable, truncated, or not describing a usable port reads as "no server", never as an error. */
 export declare function readUiRecord(dataDir: string): Promise<UiRecord | null>;
 /**
- * Written in place rather than through a temp file and a rename: a half-written
- * record fails to parse, and failing to parse already means "start a fresh
- * server", which is the safe answer. Atomicity would buy nothing.
+ * Atomically published: a reader sees either the preceding complete owner or
+ * the next complete owner, never a truncated file that could start a second
+ * mutating API server.
  */
 export declare function writeUiRecord(dataDir: string, record: UiRecord): Promise<void>;
 /**
- * Removes the record only when it still names this server's port. Two servers
- * can exist at once (a second one starts whenever the first is unreachable),
- * and the first to shut down must not delete the survivor's announcement.
+ * Removes the record only when it still names this exact listener generation.
+ * A closing old process must not delete a replacement's announcement.
  */
-export declare function clearUiRecord(dataDir: string, port?: number): Promise<void>;
+export declare function clearUiRecord(dataDir: string, port?: number, instanceId?: string): Promise<void>;
+export type ProcessIdentityLookupResult = {
+    state: "identified";
+    identity: string;
+} | {
+    state: "dead";
+} | {
+    state: "unknown";
+};
+export type ProcessIdentityLookup = (pid: number) => Promise<ProcessIdentityLookupResult>;
+export declare const uiProcessIdentity: ProcessIdentityLookup;
 /** Where a person goes. Bound on loopback, named so it can be read and typed. */
 export declare const uiOrigin: (port: number, host?: string) => string;
 /** Where this process talks to itself. Always the address, never a name that has to resolve. */
 export declare const uiProbeOrigin: (port: number) => string;
 /**
- * How the browser gets authenticated: the token rides in the URL fragment.
+ * How the browser gets authenticated: a short-lived one-use ticket rides in
+ * the URL fragment; the permanent bearer never enters opener argv.
  *
  * A fragment is the only part of a URL a browser never transmits. It is not in
  * the request line, so it cannot reach an access log, a proxy, or a Referer
@@ -72,14 +114,10 @@ export declare const uiProbeOrigin: (port: number) => string;
  * is the terminal step this whole command exists to remove, and it puts the
  * secret in scrollback, in `script` logs, and in any pasted transcript.
  *
- * What this does cost: the URL is an argv of the opener process, so it is
- * visible to `ps` for the few milliseconds that process lives. That is
- * accepted rather than overlooked — the token grants nothing that a local
- * process running as this user does not already have, since it can read
- * <data-dir>/local-api-token directly. Scrollback is the leak that outlives
- * the session; argv is not.
+ * The ticket is visible briefly in opener argv, but it expires after seconds,
+ * is redeemable once, and can only be minted through the owner-only proof key.
  */
-export declare const uiUrl: (port: number, token: string) => string;
+export declare const uiUrl: (port: number, ticket: string) => string;
 export type BrowserResult = {
     opened: boolean;
     /** The opener that ran, for a message that names what failed rather than "something went wrong". */
@@ -128,17 +166,18 @@ export declare function openInBrowser(url: string, options?: {
     graceMs?: number;
 }): Promise<BrowserResult>;
 /**
- * Is a Sealkeep local API still listening on `port`, and is it *this* vault's?
- *
- * Two questions, because a recorded port answers neither. A port is reused by
- * whatever process grabs it next, so `/health` first establishes that the
- * listener is one of ours at all. Then a `/v1/status` call carrying this
- * vault's token establishes that it reads the same token file — that is, that
- * it serves this data dir and not a second vault's. 401 is the only answer
- * that means "not this vault": every other status got past the token check,
- * including the 404 a data dir with no vault yet would return.
+ * Is this exact listener generation serving this vault?
+ *
+ * The request contains only a fresh nonce. The listener signs that nonce plus
+ * its server-observed port and generation with an owner-only key. A stale or
+ * hostile process can neither learn the API bearer nor relay a genuine
+ * listener's answer from another port.
  */
-export declare function servesThisVault(port: number, token: string, fetchImpl?: typeof fetch): Promise<boolean>;
+export type UiProbeCredentials = {
+    proofKey: string;
+    instanceId: string;
+};
+export declare function servesThisVault(port: number, credentials: UiProbeCredentials, fetchImpl?: typeof fetch): Promise<boolean>;
 export type UiHandle = {
     port: number;
     origin: string;
@@ -149,17 +188,27 @@ export type UiHandle = {
      * the URL happens to be spelled.
      */
     address: string;
-    /** The full URL including the token fragment. Print it only when no browser could be opened. */
+    /** The full URL including the one-use ticket. Print it only when no browser could be opened. */
     url: string;
     /** True when an already-running server was reused; nothing new was started and close() is a no-op. */
     reused: boolean;
     /** Set when reused, so a caller can say who owns the server it just pointed at. */
     running: UiRecord | null;
+    /** Exact listener generation; cleanup and supervisor status never match on port alone. */
+    instanceId: string;
+    /**
+     * Authoritative only for a listener created by this handle. A supervisor
+     * must not tear down its own healthy server merely because a large vault
+     * request kept the event loop busy longer than the loopback probe timeout.
+     * Reused handles deliberately return false: their owner still has to be
+     * verified over the authenticated health endpoint.
+     */
+    isListening: () => boolean;
     browser: BrowserResult;
     close: () => Promise<void>;
 };
 export type UiOptions = {
-    /** 0 — the default — asks the OS for an ephemeral port, so two vaults never fight over one. */
+    /** Defaults to stable 7477; 0 explicitly asks the OS for an ephemeral port. */
     port?: number;
     /** False for a headless surface that serves the API but has no window to open. */
     openBrowser?: boolean;
@@ -167,13 +216,14 @@ export type UiOptions = {
     open?: (url: string) => Promise<BrowserResult>;
     /** Injected by tests that need to control what the reuse probe sees. */
     fetchImpl?: typeof fetch;
-    /**
-     * False for `sealkeep api`, whose port is a stable address other tools are
-     * pointed at — handing it back an ephemeral one because a window happened to
-     * be open would break the thing that makes it useful. It still announces
-     * itself, so a later `sealkeep ui` finds it rather than starting a second.
-     */
+    /** Legacy compatibility only; false no longer bypasses singleton ownership. */
     reuse?: boolean;
+    /** Recorded lifecycle owner; it never changes the loopback or auth policy. */
+    owner?: UiOwner;
+    /** True means a daemon is waiting to take queue/worker ownership after unlock. */
+    onRecoveryPhraseAvailable?: () => boolean;
+    /** Test seam for process-generation lookup failures. */
+    processIdentityLookup?: ProcessIdentityLookup;
 };
 /**
  * Starts the local UI, or points at the one already running for this vault.
@@ -185,3 +235,81 @@ export type UiOptions = {
  * what someone typing the command twice actually meant.
  */
 export declare function startUi(dataDir: string, options?: UiOptions): Promise<UiHandle>;
+/**
+ * Runtime evidence for the background service's UI lane.
+ *
+ * This is deliberately state, not preference: `daemon --serve-ui` in the
+ * native service definition is the preference. This owner-only record merely
+ * says which process is supervising the listener now, where it actually
+ * landed after a port collision, and why it is retrying if it could not bind.
+ */
+export declare const uiSupervisorPath: (dataDir: string) => string;
+export type UiSupervisorRecord = {
+    version: 1;
+    instanceId: string;
+    pid: number;
+    processIdentity: string;
+    state: "starting" | "running" | "retrying" | "off";
+    requestedPort: number;
+    port: number | null;
+    listenerPid: number | null;
+    listenerOwner: UiOwner | null;
+    listenerInstanceId: string | null;
+    ownsListener: boolean;
+    startedAt: string;
+    checkedAt: string;
+    nextRetryAt: string | null;
+    lastError: string | null;
+};
+export type UiRuntimeStatus = {
+    supervised: boolean;
+    available: boolean;
+    state: "off" | "running" | "retrying";
+    requestedPort: number;
+    port: number | null;
+    /** Actual reachable loopback URL. It never contains the local bearer token. */
+    origin: string | null;
+    address: typeof LOOPBACK_HOST | null;
+    fallback: boolean;
+    supervisorPid: number | null;
+    listenerPid: number | null;
+    listenerOwner: UiOwner | null;
+    checkedAt: string | null;
+    nextRetryAt: string | null;
+    lastError: string | null;
+};
+/** Live truth for CLI/setup status; stale pid/record files never count as available. */
+export declare function uiRuntimeStatus(dataDir: string, options?: {
+    fetchImpl?: typeof fetch;
+    processIdentityLookup?: ProcessIdentityLookup;
+}): Promise<UiRuntimeStatus>;
+export type UiSupervisor = {
+    /** True only for the generation holding the per-vault supervisor lease. */
+    owned: boolean;
+    /** Ask the supervisor to verify or repair its listener immediately. */
+    refresh(): Promise<UiRuntimeStatus>;
+    status(): Promise<UiRuntimeStatus>;
+    /** Stops only a listener this supervisor created; a reused interactive UI remains open. */
+    close(): Promise<void>;
+};
+export type UiSupervisorOptions = {
+    port?: number;
+    retryMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Test seam; production always reuses startUi. */
+    start?: typeof startUi;
+    /** True means this service will own the worker once the phrase becomes available. */
+    onRecoveryPhraseAvailable?: () => boolean;
+    /** Test seam for process-generation lookup failures. */
+    processIdentityLookup?: ProcessIdentityLookup;
+};
+/**
+ * Keeps one authenticated loopback UI available beside Autopilot.
+ *
+ * It opens no window. A live UI already serving this vault is reused and
+ * watched; if that owner later exits, the next bounded check replaces it. An
+ * unrelated process on 7477 is never adopted: startUi falls back to a free
+ * loopback port and the exact port is written to both runtime records.
+ */
+export declare function startUiSupervisor(dataDir: string, options?: UiSupervisorOptions): Promise<UiSupervisor>;
+export {};