@cpajs/cpa 0.0.1-alpha-3 → 0.1.0-rc.2

package/src/server/management.ts

@@ -0,0 +1,89 @@
+import { compare, hash } from 'bcryptjs';
+import { CpaStartError } from './errors.ts';
+import type { ManagementOptions } from './types.ts';
+
+/** bcrypt cost; matches upstream's `bcrypt.DefaultCost` (about 50-100 ms per hash). */
+export const BCRYPT_COST = 10;
+
+// bcrypt only uses the first 72 bytes and upstream's Go implementation rejects
+// longer passwords, so a hash of a longer key could never authenticate.
+const MAX_BCRYPT_BYTES = 72;
+
+export interface ResolvedManagement {
+  /** The plaintext key, when the caller supplied one. */
+  key: string | undefined;
+  /** True when the key travels through `MANAGEMENT_PASSWORD`. */
+  viaEnvironment: boolean;
+  /** Value for `management.allow-remote` in a managed config. */
+  allowRemote: boolean;
+  /** bcrypt hash for `management.secret-key` (default mode only). */
+  secretKeyHash: string | undefined;
+}
+
+/**
+ * Normalises the management options and hashes the key for the default mode.
+ * The deprecated `managementKey` alias maps to the same safe default, not to
+ * the old `MANAGEMENT_PASSWORD` behaviour.
+ */
+export async function resolveManagement(options: {
+  management?: ManagementOptions;
+  managementKey?: string;
+}): Promise<ResolvedManagement> {
+  if (options.management !== undefined && options.managementKey !== undefined) {
+    throw new CpaStartError(
+      'invalid-options',
+      'management and managementKey are mutually exclusive; managementKey is the deprecated alias for management.key.',
+    );
+  }
+  const management =
+    options.management ?? (options.managementKey === undefined ? undefined : { key: options.managementKey });
+  if (management === undefined) {
+    return {
+      key: undefined,
+      viaEnvironment: false,
+      allowRemote: false,
+      secretKeyHash: undefined,
+    };
+  }
+  const key = management.key;
+  if (typeof key !== 'string' || key.trim() === '') {
+    throw new CpaStartError('invalid-options', 'management.key must not be empty.');
+  }
+  if (management.viaEnvironment === true) {
+    // Upstream trims MANAGEMENT_PASSWORD, so a key with surrounding whitespace
+    // would not match what the caller sends from its own client.
+    if (key !== key.trim()) {
+      throw new CpaStartError('invalid-options', 'management.key must not start or end with whitespace when viaEnvironment is true.');
+    }
+    return {
+      key,
+      viaEnvironment: true,
+      allowRemote: management.allowRemote === true,
+      secretKeyHash: undefined,
+    };
+  }
+  if (Buffer.byteLength(key, 'utf8') > MAX_BCRYPT_BYTES) {
+    throw new CpaStartError(
+      'invalid-options',
+      `management.key is longer than ${MAX_BCRYPT_BYTES} bytes, which bcrypt cannot represent. Use management.viaEnvironment: true for a longer key.`,
+    );
+  }
+  return {
+    key,
+    viaEnvironment: false,
+    allowRemote: management.allowRemote === true,
+    secretKeyHash: await hash(key, BCRYPT_COST),
+  };
+}
+
+const BCRYPT_HASH = /^\$2[aby]\$/;
+
+/**
+ * True when `stored` (a `management.secret-key` value) authenticates `key` the
+ * way upstream checks it: bcrypt hashes are compared, a plaintext value is
+ * hashed by CPA on load and so must equal the key.
+ */
+export async function keyMatches(key: string, stored: string | undefined): Promise<boolean> {
+  if (stored === undefined) return false;
+  return BCRYPT_HASH.test(stored) ? compare(key, stored) : stored === key;
+}

package/src/server/process.ts

@@ -3,16 +3,23 @@ import type { Readable } from 'node:stream';
 import type { ExitResult, LogLine } from './types.ts';
 
 const MAX_RECENT_LINES = 200;
+/** Longest line kept, in UTF-16 code units; longer output is truncated with a marker. */
+export const MAX_LINE_LENGTH = 64 * 1024;
 
-// Children still running when the parent exits are killed so they never outlive it.
-const live = new Set<ChildProcess>();
+// Children still running when this process exits normally (or calls
+// process.exit()) are killed. A fatal signal with no listener, e.g. a default
+// SIGTERM or SIGKILL, ends Node without emitting 'exit'; there the launcher
+// (cpa-launcher, see binary.ts) stops CPA instead. This library does not
+// install signal handlers, because doing so would change how the host process
+// reacts to them.
+const live = new Set<ManagedProcess>();
 let exitHookInstalled = false;
-function trackChild(child: ChildProcess): void {
-  live.add(child);
+function track(proc: ManagedProcess): void {
+  live.add(proc);
   if (exitHookInstalled) return;
   exitHookInstalled = true;
   process.once('exit', () => {
-    for (const c of live) c.kill('SIGKILL');
+    for (const p of live) p.kill('SIGKILL');
   });
 }
 
@@ -21,6 +28,12 @@ export interface SpawnOptions {
   env: NodeJS.ProcessEnv;
   redact: (text: string) => string;
   onLog?: ((log: LogLine) => void) | undefined;
+  /**
+   * Supervise mode of cpa-launcher: start it in its own process group, signal
+   * the whole group (launcher and CPA), and keep a stdin pipe open whose EOF
+   * tells the launcher that this process has died.
+   */
+  supervised?: boolean;
 }
 
 /** A spawned CPA process with line-buffered, redacted output and idempotent stop. */
@@ -35,18 +48,26 @@ export class ManagedProcess {
   readonly #redact: (text: string) => string;
   readonly #onLog: ((log: LogLine) => void) | undefined;
   readonly #lineListeners = new Set<(log: LogLine) => void>();
+  readonly #supervised: boolean;
   #stopping: Promise<ExitResult> | undefined;
 
   constructor(binaryPath: string, args: readonly string[], options: SpawnOptions) {
     this.#redact = options.redact;
     this.#onLog = options.onLog;
+    this.#supervised = options.supervised === true;
     this.child = spawn(binaryPath, [...args], {
       cwd: options.cwd,
       env: options.env,
-      stdio: ['ignore', 'pipe', 'pipe'],
+      // The supervised launcher's stdin is a liveness pipe: never written, closed by
+      // the OS when this process dies.
+      stdio: [this.#supervised ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      // Its own process group, so stop() can signal the launcher and CPA together.
+      detached: this.#supervised,
       windowsHide: true,
     });
-    trackChild(this.child);
+    // A liveness pipe with nobody reading it is expected after the launcher exits.
+    this.child.stdin?.on('error', () => {});
+    track(this);
 
     this.exited = new Promise<ExitResult>((resolve) => {
       this.child.once('error', (error) => {
@@ -64,7 +85,7 @@ export class ManagedProcess {
   #finish(resolve: (result: ExitResult) => void, result: ExitResult): void {
     if (this.exitResult) return;
     this.exitResult = result;
-    live.delete(this.child);
+    live.delete(this);
     resolve(result);
   }
 
@@ -72,8 +93,14 @@ export class ManagedProcess {
     if (!stream) return;
     stream.setEncoding('utf8');
     let pending = '';
+    // Characters dropped from the line currently being received; bounds memory
+    // when the child writes very long or never-terminated lines.
+    let dropped = 0;
     const emit = (raw: string): void => {
-      const log: LogLine = { stream: name, line: this.#redact(raw.replace(/\r$/, '')) };
+      const text = raw.replace(/\r$/, '');
+      const line = dropped > 0 ? `${text} …[truncated ${dropped} chars]` : text;
+      dropped = 0;
+      const log: LogLine = { stream: name, line: this.#redact(line) };
       this.recentLogs.push(log);
       if (this.recentLogs.length > MAX_RECENT_LINES) this.recentLogs.shift();
       for (const listener of this.#lineListeners) listener(log);
@@ -83,9 +110,14 @@ export class ManagedProcess {
       pending += chunk;
       let index: number;
       while ((index = pending.indexOf('\n')) !== -1) {
-        emit(pending.slice(0, index));
+        if (index > MAX_LINE_LENGTH) dropped += index - MAX_LINE_LENGTH;
+        emit(pending.slice(0, Math.min(index, MAX_LINE_LENGTH)));
         pending = pending.slice(index + 1);
       }
+      if (pending.length > MAX_LINE_LENGTH) {
+        dropped += pending.length - MAX_LINE_LENGTH;
+        pending = pending.slice(0, MAX_LINE_LENGTH);
+      }
     });
     stream.on('end', () => {
       if (pending) emit(pending);
@@ -93,6 +125,20 @@ export class ManagedProcess {
     });
   }
 
+  /** Signals the process, or the launcher's whole process group in supervise mode. */
+  kill(signal: NodeJS.Signals): void {
+    const pid = this.child.pid;
+    if (this.#supervised && pid !== undefined) {
+      try {
+        process.kill(-pid, signal);
+        return;
+      } catch {
+        // The group is already gone; fall back to the direct child.
+      }
+    }
+    this.child.kill(signal);
+  }
+
   onLine(listener: (log: LogLine) => void): () => void {
     this.#lineListeners.add(listener);
     return () => this.#lineListeners.delete(listener);
@@ -104,19 +150,20 @@ export class ManagedProcess {
 
   /**
    * Sends SIGTERM and waits up to `timeoutMs` before SIGKILL. On Windows Node
-   * can only terminate the process forcefully, so both steps are immediate.
+   * cannot deliver SIGTERM: both steps terminate the process forcefully, so
+   * there is no grace period and the timeout is irrelevant.
    */
   stop(timeoutMs: number): Promise<ExitResult> {
     if (this.exitResult) return Promise.resolve(this.exitResult);
     this.#stopping ??= (async () => {
-      this.child.kill('SIGTERM');
+      this.kill('SIGTERM');
       let timer: NodeJS.Timeout | undefined;
       const timedOut = new Promise<'timeout'>((resolve) => {
         timer = setTimeout(() => resolve('timeout'), timeoutMs);
       });
       const first = await Promise.race([this.exited, timedOut]);
       clearTimeout(timer);
-      if (first === 'timeout') this.child.kill('SIGKILL');
+      if (first === 'timeout') this.kill('SIGKILL');
       return this.exited;
     })();
     return this.#stopping;

package/src/server/readiness.ts

@@ -9,6 +9,15 @@ export function connectHost(bindHost: string): string {
   return bindHost;
 }
 
+/** True when a bind host only accepts loopback connections. */
+export function isLoopbackHost(host: string): boolean {
+  const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
+  if (normalized === '' || normalized === '0.0.0.0' || normalized === '::') return false;
+  if (normalized === 'localhost' || normalized === '::1') return true;
+  if (normalized.startsWith('::ffff:127.')) return true;
+  return /^127(?:\.\d{1,3}){3}$/.test(normalized);
+}
+
 export function formatOrigin(protocol: 'http' | 'https', host: string, port: number): string {
   const h = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
   return `${protocol}://${h}:${port}`;
@@ -32,8 +41,21 @@ export function probeHealth(origin: string, timeoutMs: number): Promise<boolean>
   });
 }
 
-/** Asks the OS for a currently free TCP port on `host`. */
-export function findFreePort(host: string): Promise<number> {
+/** A free port whose probing listener stays open until `release()` is called. */
+export interface PortReservation {
+  port: number;
+  /** Closes the probing listener so a child process can bind the port. */
+  release(): Promise<void>;
+}
+
+/**
+ * Reserves a currently free TCP port on `host`.
+ *
+ * The listening socket is left open until `release()` so another process cannot
+ * take the port while the caller finishes preparing the child. The window
+ * between `release()` and the child's own bind cannot be removed entirely.
+ */
+export function findFreePort(host: string): Promise<PortReservation> {
   return new Promise((resolve, reject) => {
     const server = createServer();
     server.unref();
@@ -41,7 +63,20 @@ export function findFreePort(host: string): Promise<number> {
     server.listen({ host: connectHost(host), port: 0, exclusive: true }, () => {
       const address = server.address();
       const port = typeof address === 'object' && address ? address.port : 0;
-      server.close(() => (port ? resolve(port) : reject(new Error('Could not allocate a free port.'))));
+      if (!port) {
+        server.close(() => reject(new Error('Could not allocate a free port.')));
+        return;
+      }
+      let released: Promise<void> | undefined;
+      resolve({
+        port,
+        release() {
+          released ??= new Promise<void>((resolveClose) => {
+            server.close(() => resolveClose());
+          });
+          return released;
+        },
+      });
     });
   });
 }

package/src/server/targets.ts

@@ -131,3 +131,11 @@ export function packageName(target: Target): string {
 export function binaryName(target: Pick<Target, 'os'>): string {
   return target.os === 'win32' ? 'cli-proxy-api.exe' : 'cli-proxy-api';
 }
+
+/** Name of the launcher shipped next to the CPA binary. Windows needs none (see binary.ts). */
+export const LAUNCHER_NAME = 'cpa-launcher';
+
+/** True for targets whose platform package ships `cpa-launcher`. */
+export function hasLauncher(target: Pick<Target, 'os'>): boolean {
+  return target.os !== 'win32';
+}

package/src/server/types.ts

@@ -18,6 +18,23 @@ export interface HomeOptions {
   disableClusterDiscovery?: boolean;
 }
 
+export interface ManagementOptions {
+  /** Management API key. Empty keys are rejected. */
+  key: string;
+  /**
+   * Write `management.allow-remote`, which lets non-loopback clients use the
+   * management API. Default `false`; ignored by `viaEnvironment`, which always
+   * enables remote access upstream.
+   */
+  allowRemote?: boolean;
+  /**
+   * Pass the key to CPA through `MANAGEMENT_PASSWORD` instead of writing a
+   * bcrypt hash into the managed config. Upstream treats that variable as
+   * enabling remote management and compares the key in plaintext.
+   */
+  viaEnvironment?: boolean;
+}
+
 interface CommonServerOptions {
   /** Use this executable instead of the bundled platform package. */
   binaryPath?: string;
@@ -26,10 +43,15 @@ interface CommonServerOptions {
    * directory. When omitted, a temporary directory is created and removed on stop.
    */
   stateDir?: string;
+  /** Management API key and how it reaches CPA. */
+  management?: ManagementOptions;
   /**
-   * Management key passed to CPA through the `MANAGEMENT_PASSWORD` environment
-   * variable, so it never touches disk. Note that upstream treats this variable
-   * as allowing remote management access regardless of `management.allow-remote`.
+   * Deprecated alias for `management: { key }`. It uses the safe default
+   * (bcrypt hash in the config, remote management disabled) and will be removed
+   * in a future release. Use `management.viaEnvironment` for the old
+   * `MANAGEMENT_PASSWORD` behaviour.
+   *
+   * @deprecated Use `management` instead.
    */
   managementKey?: string;
   /**
@@ -37,6 +59,22 @@ interface CommonServerOptions {
    * (`-local-model`). Explicit `models.*` config sources still win.
    */
   localModel?: boolean;
+  /**
+   * Start CPA through `cpa-launcher` so it cannot outlive this process, even
+   * when this process is killed with SIGKILL or crashes. Default `true`.
+   *
+   * - Linux: the launcher sets PR_SET_PDEATHSIG and execs CPA (no extra process).
+   * - macOS / BSD: the launcher stays as CPA's parent and stops it when this
+   *   process dies; `pid` is then the launcher's pid, and signals sent to it are
+   *   forwarded to CPA.
+   * - Windows: not needed; Node already kills child processes with their parent.
+   *
+   * The launcher ships next to the CPA binary in every platform package. With a
+   * custom `binaryPath` it is looked up next to that binary and then in an
+   * installed platform package; if none is found CPA is started directly and a
+   * notice is logged through `onLog`.
+   */
+  launcher?: boolean;
   /** Run as a node of a CPA Home control plane. Home mode disables the local management API. */
   home?: HomeOptions;
   /**
@@ -55,25 +93,41 @@ interface CommonServerOptions {
   onLog?: (log: LogLine) => void;
   /** Additional strings to redact from logs and errors. */
   redact?: readonly string[];
-  /** Default grace period for `stop()` before the process is killed. Default 10 000 ms. */
+  /** Default grace period for `stop()` before the process is killed. Ignored on Windows, where `stop()` terminates forcefully. Default 10 000 ms. */
   stopTimeoutMs?: number;
 }
 
 export interface StartWithConfigOptions extends CommonServerOptions {
   /**
-   * Native CPA configuration. It is written to `<stateDir>/config.yaml` on
-   * every start, replacing whatever CPA persisted there during the last run.
+   * Native CPA configuration.
+   *
+   * Written as YAML to `<stateDir>/config.yaml` only when that file does not
+   * exist. On later starts the existing file is reused, so changes made through
+   * the management API (or by CPA itself) survive a `stop()` / `startServer()`
+   * cycle. Set `overwriteConfig: true` to replace it with this object.
    */
   config?: CpaConfig;
   configPath?: never;
-  /** Bind host. Overrides `config.server.host`. Default `127.0.0.1`. */
+  /**
+   * Replace `<stateDir>/config.yaml` even when it already exists. Default
+   * `false`. When the existing file is kept, `config`, `host` and `port` are not
+   * applied and a message is emitted through `onLog`.
+   */
+  overwriteConfig?: boolean;
+  /** Bind host, when cpajs writes the managed file. Default `config.server.host`, else `127.0.0.1`. */
   host?: string;
-  /** Bind port. Overrides `config.server.port`. Default `0`, meaning a free port is picked. */
+  /** Bind port, when cpajs writes the managed file. Default `config.server.port`, else `0` (a free port is picked). */
   port?: number;
 }
 
 export interface StartWithConfigPathOptions extends CommonServerOptions {
-  /** Existing CPA config file, handed to CPA as-is. CPA may rewrite it (e.g. to hash `secret-key`). */
+  /**
+   * Existing CPA config file, handed to CPA as-is. CPA may rewrite it on
+   * startup: it hashes a plaintext `management.secret-key`, removes legacy
+   * keys that conflict with their v8 equivalents, and normalizes the layout.
+   * The file must set a fixed positive port; a missing or non-positive port
+   * makes CPA bind a random port it does not report.
+   */
   configPath: string;
   config?: never;
   host?: never;
@@ -88,10 +142,20 @@ export interface ExitResult {
 }
 
 export interface StopOptions {
-  /** Grace period after the termination signal before the process is killed. */
+  /** Grace period after the termination signal before the process is killed. Ignored on Windows, where the process is terminated forcefully right away. */
   timeoutMs?: number;
 }
 
+export interface RestartOptions {
+  /**
+   * Grace period after the termination signal before the old process is killed.
+   * Defaults to `stopTimeoutMs`.
+   */
+  timeoutMs?: number;
+  /** Cancels the restart. The server is left stopped, like any other failed restart. */
+  signal?: AbortSignal;
+}
+
 export interface CpaServer {
   /** e.g. `http://127.0.0.1:8317`. Use as the client `baseUrl`. */
   readonly origin: string;
@@ -103,13 +167,25 @@ export interface CpaServer {
   readonly binaryPath: string;
   readonly configPath: string;
   readonly stateDir: string;
-  /** The management key given in the options, if any. */
-  readonly managementKey: string | undefined;
   readonly process: ChildProcess;
   /** Recent output lines (redacted), oldest first. */
   readonly recentLogs: readonly LogLine[];
-  /** Settles when the process exits, whether or not `stop()` was called. */
+  /**
+   * Settles when the process exits for good: on `stop()` or an unexpected exit.
+   * A restart stops one process and starts another, so it does not settle this.
+   */
   readonly exited: Promise<ExitResult>;
-  /** Terminates CPA gracefully, killing it after the grace period. Idempotent. */
+  /**
+   * Stops CPA. On POSIX it sends SIGTERM and then SIGKILL after the grace
+   * period. On Windows Node cannot deliver a graceful signal, so the process is
+   * terminated forcefully (there is no grace period and CPA is not asked to
+   * flush state or update auth files). Idempotent.
+   */
   stop(options?: StopOptions): Promise<ExitResult>;
+  /**
+   * Restarts CPA with the original options, reusing `origin`, `baseUrl`, `host`,
+   * `port`, `stateDir` and the existing config file. Concurrent calls share one
+   * operation. A failed or cancelled restart leaves the server stopped.
+   */
+  restart(options?: RestartOptions): Promise<void>;
 }