@evomap/evolver-proxy 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/selfUpdate/policy.d.ts

@@ -1,3 +1,20 @@
 export type SelfUpdatePolicy = 'off' | 'prompt' | 'auto';
-/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset/unrecognized → 'off' (fail-closed). */
-export declare function resolveSelfUpdatePolicy(env?: NodeJS.ProcessEnv): SelfUpdatePolicy;
+/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset → 'auto' (still gated by supervisor + public key). Unrecognized → 'off' (fail-closed). */
+export declare function resolveSelfUpdatePolicy(env?: NodeJS.ProcessEnv): SelfUpdatePolicy;
+/** True when the operator set EVOLVER_SELF_UPDATE to any non-blank value. */
+export declare function isSelfUpdateExplicit(env?: NodeJS.ProcessEnv): boolean;
+/** Attested only by the generated durable launchers; env files and operators cannot forge the marker. */
+export declare function selfUpdateSupervisorAttested(env: NodeJS.ProcessEnv): boolean;
+export interface EffectiveSelfUpdatePolicy {
+    policy: SelfUpdatePolicy;
+    /** True when a DEFAULT auto was degraded to 'off' because the supervisor attestation is missing. */
+    degraded: boolean;
+}
+/**
+ * Resolve the policy that startup should actually run with. A default (unset) 'auto' without durable
+ * supervisor attestation OR without any available public key OR without a bindable self-update target
+ * (npm/JS install shape) degrades to 'off' so direct/foreground runs — and residual launchers from a
+ * bad bootstrap on a JS install — keep working; an explicit 'auto' passes through untouched and fails
+ * closed at assembly time. `execPath` overrides process.execPath for the target-bindability check.
+ */
+export declare function resolveEffectiveSelfUpdatePolicy(env?: NodeJS.ProcessEnv, execPath?: string): EffectiveSelfUpdatePolicy;

package/dist/selfUpdate/policy.js

@@ -1,9 +1,83 @@
-/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset/unrecognized → 'off' (fail-closed). */
+// Self-update policy resolution from the EVOLVER_SELF_UPDATE env var.
+//
+// Default is AUTO. An auto-applying self-update channel is the single highest-value attack surface
+// in the fleet, so the auto default stays hard-gated: production auto requires supervisor attestation
+// (a generated durable launcher owns relaunch) plus an Ed25519 public key for signed-manifest
+// verification, and anything missing fails closed before any update is applied.
+//
+// The DEFAULT auto is an install-convenience, not an operator assertion: when no durable supervisor
+// attestation is present OR no verification public key is available (configured env value or the
+// built-in distribution key) OR no self-update target is bindable (npm/JS install shape without a
+// standalone binary), resolveEffectiveSelfUpdatePolicy
+// degrades it to 'off' (with a warning at startup) so unsupervised foreground runs still start —
+// keeping 'auto' would just make createSelfUpdateDeps throw at assembly and crash startup. The
+// target-bindability check also rescues residual bad launchers left behind by older bootstraps:
+// an attested supervisor running through node degrades to 'off' instead of crash-looping.
+// An EXPLICIT EVOLVER_SELF_UPDATE=auto keeps failing closed at assembly (createSelfUpdateDeps throws)
+// — the operator asked for auto, silence would hide a misconfiguration.
+// Operators can still narrow it explicitly:
+//   off    : never apply.
+//   prompt : recognized but not auto-applied until an approval store/UI exists.
+//   auto   : apply automatically after verification (default).
+// Enterprise/air-gap deployments should pin 'off' explicitly in their env file (decided by the
+// private adapter, not core).
+import { resolveSelfUpdatePublicKey } from './builtinKey.js';
+import { selfUpdateProcessTargetBindable } from './releaseBinary.js';
+/** Resolve EVOLVER_SELF_UPDATE to a policy. Unset → 'auto' (still gated by supervisor + public key). Unrecognized → 'off' (fail-closed). */
 export function resolveSelfUpdatePolicy(env = process.env) {
     const raw = (env['EVOLVER_SELF_UPDATE'] ?? '').trim().toLowerCase();
+    if (raw === 'off')
+        return 'off';
     if (raw === 'prompt')
         return 'prompt';
-    if (raw === 'auto')
+    if (raw === 'auto' || raw === '')
         return 'auto';
     return 'off';
+}
+/** True when the operator set EVOLVER_SELF_UPDATE to any non-blank value. */
+export function isSelfUpdateExplicit(env = process.env) {
+    return (env['EVOLVER_SELF_UPDATE'] ?? '').trim() !== '';
+}
+/** Attested only by the generated durable launchers; env files and operators cannot forge the marker. */
+export function selfUpdateSupervisorAttested(env) {
+    const supervisor = env['EVOLVER_SELF_UPDATE_SUPERVISOR']?.trim();
+    return supervisor === 'systemd'
+        || supervisor === 'launchd'
+        || supervisor === 'windows-scheduled-task';
+}
+/**
+ * True when a verification public key will be available at assembly time: a configured
+ * EVOLVER_SELF_UPDATE_PUBLIC_KEY or the built-in distribution key. Must stay aligned with
+ * the resolver used by createSelfUpdateDeps so policy never degrades for a key that
+ * assembly would accept.
+ */
+function selfUpdatePublicKeyAvailable(env) {
+    return Boolean(resolveSelfUpdatePublicKey(env).trim());
+}
+/**
+ * True when a self-update target can be bound at assembly time: an explicit
+ * EVOLVER_SELF_UPDATE_TARGET_PATH or a standalone release binary execPath. Must stay aligned
+ * with resolveSelfUpdateTarget as used by createSelfUpdateDeps so policy never keeps 'auto'
+ * for a target that assembly would reject.
+ */
+function selfUpdateTargetBindable(env, execPath) {
+    return selfUpdateProcessTargetBindable({ env, processExecPath: execPath });
+}
+/**
+ * Resolve the policy that startup should actually run with. A default (unset) 'auto' without durable
+ * supervisor attestation OR without any available public key OR without a bindable self-update target
+ * (npm/JS install shape) degrades to 'off' so direct/foreground runs — and residual launchers from a
+ * bad bootstrap on a JS install — keep working; an explicit 'auto' passes through untouched and fails
+ * closed at assembly time. `execPath` overrides process.execPath for the target-bindability check.
+ */
+export function resolveEffectiveSelfUpdatePolicy(env = process.env, execPath) {
+    const policy = resolveSelfUpdatePolicy(env);
+    if (policy === 'auto'
+        && !isSelfUpdateExplicit(env)
+        && (!selfUpdateSupervisorAttested(env)
+            || !selfUpdatePublicKeyAvailable(env)
+            || !selfUpdateTargetBindable(env, execPath))) {
+        return { policy: 'off', degraded: true };
+    }
+    return { policy, degraded: false };
 }

package/dist/selfUpdate/recoveryChildStartGate.d.ts

@@ -0,0 +1,29 @@
+import type { ChildProcess } from 'node:child_process';
+import { util } from '@evomap/evolver-core';
+export declare const RECOVERY_CHILD_START_GATE_ENV = "EVOLVER_INTERNAL_RECOVERY_CHILD_START_GATE";
+export declare const DEFAULT_RECOVERY_CHILD_START_GATE_TIMEOUT_MS = 120000;
+export type RecoveryChildStartGateRole = 'proxy-target' | 'windows-updater';
+export interface PreparedRecoveryChildStartGate {
+    env: NodeJS.ProcessEnv;
+    startupGateToken: string;
+}
+export interface ConsumeRecoveryChildStartGateOptions {
+    descriptor?: number;
+    timeoutMs?: number;
+    parentPid?: number;
+    inspectParentProcess?: (parent: Pick<util.FileLockOwnerRecord, 'pid' | 'processStartIdentity'>) => util.FileLockOwnerProcessStatus;
+}
+/**
+ * Bind a one-shot child start gate to this exact parent PID generation.
+ * The token travels in both the environment capability and a private fd4 pipe;
+ * neither input is sufficient on its own.
+ */
+export declare function prepareRecoveryChildStartGate(env: NodeJS.ProcessEnv, role: RecoveryChildStartGateRole, expectedParent?: Pick<util.FileLockOwnerRecord, 'pid' | 'processStartIdentity'>): PreparedRecoveryChildStartGate;
+/**
+ * Consume the gate before controller/worker dispatch or durable recovery.
+ * Invalid capability, wrong role/parent generation, EOF, malformed input and
+ * timeout all fail closed. The inherited capability is scrubbed on every path.
+ */
+export declare function consumeRecoveryChildStartGate(env: NodeJS.ProcessEnv, expectedRole: RecoveryChildStartGateRole | undefined, options?: ConsumeRecoveryChildStartGateOptions): Promise<boolean>;
+/** Deliver fd4 only after the caller establishes its owned guardian or delegated authority. */
+export declare function deliverRecoveryChildStartGate(child: ChildProcess, token: string, timeoutMs?: number): Promise<boolean>;

package/dist/selfUpdate/recoveryChildStartGate.js

@@ -0,0 +1,319 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, createReadStream } from 'node:fs';
+import { Socket } from 'node:net';
+import { util } from '@evomap/evolver-core';
+export const RECOVERY_CHILD_START_GATE_ENV = 'EVOLVER_INTERNAL_RECOVERY_CHILD_START_GATE';
+const RECOVERY_CHILD_START_GATE_DESCRIPTOR = 4;
+export const DEFAULT_RECOVERY_CHILD_START_GATE_TIMEOUT_MS = 120_000;
+const MAX_RECOVERY_CHILD_START_GATE_CAPABILITY_BYTES = 1024;
+const MAX_RECOVERY_CHILD_START_GATE_SIGNAL_BYTES = 128;
+const BUN_READER_CANCEL_TIMEOUT_MS = 1_000;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Bind a one-shot child start gate to this exact parent PID generation.
+ * The token travels in both the environment capability and a private fd4 pipe;
+ * neither input is sufficient on its own.
+ */
+export function prepareRecoveryChildStartGate(env, role, expectedParent) {
+    if (expectedParent?.pid !== undefined && expectedParent.pid !== process.pid) {
+        throw new Error('self_update_recovery_child_start_gate_parent_invalid');
+    }
+    const processStartIdentity = util.readFileLockProcessStartIdentity(process.pid);
+    if (!processStartIdentity
+        || (expectedParent
+            && !util.sameFileLockProcessStartIdentity(expectedParent.processStartIdentity, processStartIdentity))) {
+        throw new Error('self_update_recovery_child_start_gate_parent_invalid');
+    }
+    const startupGateToken = randomUUID();
+    const capability = {
+        v: 1,
+        role,
+        pid: process.pid,
+        processStartIdentity,
+        token: startupGateToken,
+    };
+    return {
+        env: {
+            ...env,
+            [RECOVERY_CHILD_START_GATE_ENV]: JSON.stringify(capability),
+        },
+        startupGateToken,
+    };
+}
+function clearRecoveryChildStartGate(env) {
+    delete env[RECOVERY_CHILD_START_GATE_ENV];
+}
+/**
+ * Consume the gate before controller/worker dispatch or durable recovery.
+ * Invalid capability, wrong role/parent generation, EOF, malformed input and
+ * timeout all fail closed. The inherited capability is scrubbed on every path.
+ */
+export async function consumeRecoveryChildStartGate(env, expectedRole, options = {}) {
+    const raw = env[RECOVERY_CHILD_START_GATE_ENV];
+    if (raw === undefined)
+        return false;
+    const descriptor = options.descriptor ?? RECOVERY_CHILD_START_GATE_DESCRIPTOR;
+    try {
+        const capability = parseRecoveryChildStartGateCapability(raw, expectedRole, options.parentPid ?? process.ppid, options.inspectParentProcess ?? util.inspectFileLockOwnerProcess);
+        if (!capability) {
+            await closeDescriptorBestEffort(descriptor);
+            throw new Error('self_update_recovery_child_start_gate_invalid');
+        }
+        const accepted = await readExactGateToken(descriptor, capability.token, positiveTimeout(options.timeoutMs));
+        if (!accepted) {
+            throw new Error('self_update_recovery_child_start_gate_rejected');
+        }
+        return true;
+    }
+    finally {
+        clearRecoveryChildStartGate(env);
+    }
+}
+/** Deliver fd4 only after the caller establishes its owned guardian or delegated authority. */
+export function deliverRecoveryChildStartGate(child, token, timeoutMs = DEFAULT_RECOVERY_CHILD_START_GATE_TIMEOUT_MS) {
+    if (!UUID_PATTERN.test(token))
+        return Promise.resolve(false);
+    const stream = child.stdio[RECOVERY_CHILD_START_GATE_DESCRIPTOR];
+    const writable = stream;
+    if (!writable
+        || typeof writable.on !== 'function'
+        || typeof writable.once !== 'function'
+        || typeof writable.off !== 'function'
+        || typeof writable.end !== 'function'
+        || typeof writable.destroy !== 'function') {
+        return Promise.resolve(false);
+    }
+    const gate = writable;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (accepted) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            gate.off('finish', onFinish);
+            gate.off('error', onError);
+            gate.off('close', onClose);
+            resolve(accepted);
+        };
+        const onFinish = () => { finish(true); };
+        const onError = () => { finish(false); };
+        const onClose = () => { finish(false); };
+        const timer = setTimeout(() => {
+            try {
+                gate.destroy();
+            }
+            catch {
+                // The bounded false result remains authoritative.
+            }
+            finish(false);
+        }, positiveTimeout(timeoutMs));
+        gate.once('finish', onFinish);
+        gate.once('error', onError);
+        gate.once('close', onClose);
+        gate.end(`${token}\n`);
+    });
+}
+function parseRecoveryChildStartGateCapability(raw, expectedRole, parentPid, inspectParentProcess) {
+    if (!raw || Buffer.byteLength(raw, 'utf8') > MAX_RECOVERY_CHILD_START_GATE_CAPABILITY_BYTES) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        const record = parsed;
+        const keys = Object.keys(record).sort();
+        if (keys.length !== 5
+            || keys[0] !== 'pid'
+            || keys[1] !== 'processStartIdentity'
+            || keys[2] !== 'role'
+            || keys[3] !== 'token'
+            || keys[4] !== 'v'
+            || record['v'] !== 1
+            || (record['role'] !== 'proxy-target' && record['role'] !== 'windows-updater')
+            || record['role'] !== expectedRole
+            || !Number.isSafeInteger(record['pid'])
+            || record['pid'] !== parentPid
+            || typeof record['token'] !== 'string'
+            || !UUID_PATTERN.test(record['token'])) {
+            return undefined;
+        }
+        const processStartIdentity = util.parseFileLockProcessStartIdentity(record['processStartIdentity']);
+        if (!processStartIdentity)
+            return undefined;
+        const capability = {
+            v: 1,
+            role: record['role'],
+            pid: record['pid'],
+            processStartIdentity,
+            token: record['token'],
+        };
+        if (inspectParentProcess(capability) !== 'current')
+            return undefined;
+        return capability;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readExactGateToken(descriptor, token, timeoutMs) {
+    if (typeof process.versions['bun'] === 'string') {
+        const bun = activeBunFileRuntime();
+        if (!bun)
+            return Promise.resolve(false);
+        return readExactGateTokenFromBunFile(bun, descriptor, token, timeoutMs);
+    }
+    const expected = Buffer.from(`${token}\n`, 'utf8');
+    return new Promise((resolve) => {
+        let raw = Buffer.alloc(0);
+        let settled = false;
+        let stream;
+        try {
+            // Node's libuv pipe socket can cancel an outstanding silent read on
+            // destroy; fs.ReadStream leaves that read live on Windows after timeout.
+            stream = new Socket({ fd: descriptor, readable: true, writable: false });
+        }
+        catch {
+            // Regular-file descriptors are useful for deterministic parser tests;
+            // Node production fd4 is always the cancellable pipe path above.
+            stream = createReadStream('', { fd: descriptor, autoClose: true });
+        }
+        const finish = (accepted) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            stream.off('data', onData);
+            stream.off('end', onEnd);
+            stream.off('error', onError);
+            stream.off('close', onClose);
+            if (!stream.destroyed)
+                stream.destroy();
+            resolve(accepted);
+        };
+        const onData = (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+            if (bytes.byteLength > MAX_RECOVERY_CHILD_START_GATE_SIGNAL_BYTES - raw.byteLength) {
+                finish(false);
+                return;
+            }
+            raw = Buffer.concat([raw, bytes], raw.byteLength + bytes.byteLength);
+            if (!raw.equals(expected.subarray(0, raw.byteLength))) {
+                finish(false);
+            }
+        };
+        const onEnd = () => { finish(raw.equals(expected)); };
+        const onError = () => { finish(false); };
+        const onClose = () => { finish(false); };
+        const timer = setTimeout(() => { finish(false); }, timeoutMs);
+        stream.on('data', onData);
+        stream.once('end', onEnd);
+        stream.once('error', onError);
+        stream.once('close', onClose);
+    });
+}
+async function readExactGateTokenFromBunFile(bun, descriptor, token, timeoutMs) {
+    const expected = Buffer.from(`${token}\n`, 'utf8');
+    let reader;
+    try {
+        // Bun's net.Socket accepts an inherited Windows pipe descriptor but never
+        // observes its data or EOF. Bun.file(fd).stream() owns that pipe correctly
+        // and its reader cancellation also releases a silent outstanding read.
+        reader = bun.file(descriptor).stream().getReader();
+    }
+    catch {
+        return false;
+    }
+    const timedOut = Symbol('recovery-child-start-gate-timeout');
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => { resolve(timedOut); }, timeoutMs);
+    });
+    let raw = Buffer.alloc(0);
+    let completed = false;
+    try {
+        for (;;) {
+            const result = await Promise.race([
+                reader.read().catch(() => undefined),
+                timeout,
+            ]);
+            if (result === timedOut || result === undefined)
+                return false;
+            if (result.done) {
+                completed = true;
+                return raw.equals(expected);
+            }
+            const bytes = Buffer.from(result.value);
+            if (bytes.byteLength > MAX_RECOVERY_CHILD_START_GATE_SIGNAL_BYTES - raw.byteLength) {
+                return false;
+            }
+            raw = Buffer.concat([raw, bytes], raw.byteLength + bytes.byteLength);
+            if (!raw.equals(expected.subarray(0, raw.byteLength)))
+                return false;
+        }
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (!completed) {
+            try {
+                await cancelBunReaderBestEffort(reader);
+            }
+            catch {
+                // Rejection remains authoritative after cancellation was attempted.
+            }
+        }
+    }
+}
+function activeBunFileRuntime() {
+    const bun = globalThis.Bun;
+    return bun && typeof bun.file === 'function'
+        ? bun
+        : undefined;
+}
+async function cancelBunReaderBestEffort(reader) {
+    await new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(finish, BUN_READER_CANCEL_TIMEOUT_MS);
+        try {
+            void reader.cancel('self_update_recovery_child_start_gate_closed').then(finish, finish);
+        }
+        catch {
+            finish();
+        }
+    });
+}
+async function closeDescriptorBestEffort(descriptor) {
+    if (typeof process.versions['bun'] === 'string') {
+        const bun = activeBunFileRuntime();
+        if (!bun)
+            return;
+        try {
+            const reader = bun.file(descriptor).stream().getReader();
+            await cancelBunReaderBestEffort(reader);
+        }
+        catch {
+            // The invalid capability remains authoritative.
+        }
+        return;
+    }
+    try {
+        closeSync(descriptor);
+    }
+    catch {
+        // The capability rejection remains authoritative.
+    }
+}
+function positiveTimeout(value) {
+    return Number.isFinite(value) && (value ?? 0) > 0
+        ? Math.floor(value)
+        : DEFAULT_RECOVERY_CHILD_START_GATE_TIMEOUT_MS;
+}

package/dist/selfUpdate/releaseBinary.d.ts

@@ -11,8 +11,18 @@ export interface ReleaseBinaryOptions {
     targetPath?: string;
     processExecPath?: string;
     requireSignedManifest?: boolean;
+    maxPrimaryBinaryBytes?: number;
     maxExtractedTarballBytes?: number;
 }
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export declare const MAX_PRIMARY_BINARY_BYTES: number;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export declare const MAX_RELEASE_METADATA_BYTES: number;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered
@@ -26,6 +36,7 @@ export declare const MAX_TARBALL_BYTES: number;
  * bombs fail before the extractor accumulates unbounded output in memory.
  */
 export declare const MAX_EXTRACTED_TARBALL_BYTES: number;
+export declare function isStandaloneReleaseBinaryName(name: string): boolean;
 export declare function requiredVersionForRelease(raw: unknown): string;
 export declare function releaseAssetName(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): string;
 export declare function resolveGithubReleaseManifest(directive: ForceUpdateDirective, opts?: ReleaseBinaryOptions): Promise<UpdateManifest>;
@@ -53,4 +64,6 @@ export declare function resolveSelfUpdateTarget(opts?: ReleaseBinaryOptions): {
     path: string;
     explicit: boolean;
 };
+export declare function assertSelfUpdateProcessTargetBound(options: ReleaseBinaryOptions, allowUnresolvedTarget?: boolean): void;
+export declare function selfUpdateProcessTargetBindable(options: ReleaseBinaryOptions): boolean;
 export {};