@evomap/evolver-proxy 2.0.2 → 2.0.12

package/dist/selfUpdate/policy.js

@@ -22,7 +22,7 @@
 // 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 { resolveSelfUpdateTarget } from './releaseBinary.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();
@@ -61,13 +61,7 @@ function selfUpdatePublicKeyAvailable(env) {
  * for a target that assembly would reject.
  */
 function selfUpdateTargetBindable(env, execPath) {
-    try {
-        resolveSelfUpdateTarget({ env, processExecPath: execPath });
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return selfUpdateProcessTargetBindable({ env, processExecPath: execPath });
 }
 /**
  * Resolve the policy that startup should actually run with. A default (unset) 'auto' without durable

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

@@ -36,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>;
@@ -63,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 {};

package/dist/selfUpdate/releaseBinary.js

@@ -1,7 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { chmod, copyFile, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, resolve, win32 } from 'node:path';
 import { createGunzip } from 'node:zlib';
 import { ops } from '@evomap/evolver-core';
 import { SELF_UPDATE_FAILURE_CODES, SelfUpdateFailureError, selfUpdateFailure } from './failureCodes.js';
@@ -30,6 +31,10 @@ export const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
  * bombs fail before the extractor accumulates unbounded output in memory.
  */
 export const MAX_EXTRACTED_TARBALL_BYTES = 128 * 1024 * 1024;
+const SELF_UPDATE_RELEASE_BINARY_RE = /^evolver(?:\.exe|-(?:darwin-(?:arm64|x64)|linux-(?:arm64|x64)|windows-x64\.exe))?$/;
+export function isStandaloneReleaseBinaryName(name) {
+    return SELF_UPDATE_RELEASE_BINARY_RE.test(name.toLowerCase());
+}
 export function requiredVersionForRelease(raw) {
     try {
         return ops.requireSelfUpdateVersion(raw, 'required_version');
@@ -209,10 +214,48 @@ export function resolveSelfUpdateTarget(opts = {}) {
     // correctly even when this check runs on a POSIX host (shape probes, tests).
     const segments = execPath.split(/[/\\]+/).filter(Boolean);
     const name = (segments.length > 0 ? segments[segments.length - 1] : basename(execPath)).toLowerCase();
-    if (name.startsWith('evolver'))
+    if (isStandaloneReleaseBinaryName(name))
         return { path: execPath, explicit: false };
     throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.INSTALL_GUARD_UNREADABLE, `self_update_target_required:${execPath}`);
 }
+export function assertSelfUpdateProcessTargetBound(options, allowUnresolvedTarget = false) {
+    let targetPath;
+    try {
+        targetPath = resolveSelfUpdateTarget(options).path;
+    }
+    catch {
+        if (allowUnresolvedTarget)
+            return;
+        throw new Error('self_update_process_target_mismatch');
+    }
+    const processExecPath = options.processExecPath ?? process.execPath;
+    try {
+        if (canonicalExecutablePath(processExecPath) !== canonicalExecutablePath(targetPath)) {
+            throw new Error('self_update_process_target_mismatch');
+        }
+    }
+    catch {
+        throw new Error('self_update_process_target_mismatch');
+    }
+}
+export function selfUpdateProcessTargetBindable(options) {
+    try {
+        assertSelfUpdateProcessTargetBound(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function canonicalExecutablePath(path) {
+    const canonical = realpathSync.native(path);
+    if (process.platform !== 'win32')
+        return resolve(canonical);
+    const withoutNamespace = canonical
+        .replace(/^\\\\\?\\UNC\\/i, '\\\\')
+        .replace(/^\\\\\?\\/i, '');
+    return win32.normalize(withoutNamespace).toLowerCase();
+}
 function releaseDownloadUrl(releaseUrl, version, assetName) {
     let base;
     try {
@@ -391,7 +434,7 @@ function shaForAsset(sums, assetName) {
 }
 function assertSafeExecutableTarget(targetPath, explicitTarget) {
     const name = basename(targetPath).toLowerCase();
-    if ((name === 'node' || name === 'node.exe' || !name.startsWith('evolver')) && !explicitTarget) {
+    if (!isStandaloneReleaseBinaryName(name) && !explicitTarget) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.INSTALL_GUARD_NAME_MISMATCH, `unsafe_self_update_target:${targetPath}`);
     }
 }

package/dist/selfUpdate/transaction.d.ts

@@ -71,9 +71,17 @@ export type SelfUpdateRecoveryOptions = Omit<DurableSelfUpdateOptions, 'currentV
 };
 export interface StableUnixRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
     platform?: NodeJS.Platform;
+    /** Bootstrap uses create-only ownership; explicit install-service keeps replacement semantics. */
+    replaceExisting?: boolean;
+    artifactClaimPath?: string;
+    onArtifactPublished?: (path: string, claimPath: string) => void | Promise<void>;
 }
 export interface StableWindowsRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
     platform?: NodeJS.Platform;
+    /** Bootstrap uses create-only ownership; explicit install-service keeps replacement semantics. */
+    replaceExisting?: boolean;
+    artifactClaimPath?: string;
+    onArtifactPublished?: (path: string, claimPath: string) => void | Promise<void>;
 }
 export declare function inspectDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
 export declare function resolveStableUnixRecoveryControllerPath(options: StableUnixRecoveryControllerOptions): Promise<string>;