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

package/dist/selfUpdate/bootstrapReadiness.d.ts

@@ -0,0 +1,9 @@
+import { util } from '@evomap/evolver-core';
+export declare function publishLifecycleBootstrapReadiness(input: {
+    env: NodeJS.ProcessEnv;
+    pid?: number;
+    supervisorPid?: number;
+    readProcessStartIdentity?: typeof util.readFileLockProcessStartIdentity;
+    startedAt: string;
+    ipcUrl: string;
+}): void;

package/dist/selfUpdate/bootstrapReadiness.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { bootstrap as coreBootstrap, util } from '@evomap/evolver-core';
+import { resolveBootstrapStateDir } from './bootstrap.js';
+const MAX_READINESS_BYTES = 16 * 1024;
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function syncDirectory(path) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY);
+        fsyncSync(descriptor);
+    }
+    catch (error) {
+        if (isErrno(error, 'EINVAL'))
+            return;
+        if (process.platform === 'win32' && (isErrno(error, 'EPERM') || isErrno(error, 'EACCES')))
+            return;
+        throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function readExistingReadiness(path) {
+    try {
+        const before = lstatSync(path, { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(MAX_READINESS_BYTES)
+            || before.dev <= 0n || before.ino <= 0n) {
+            throw new Error('bootstrap readiness path is not a bounded regular file');
+        }
+        const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const opened = fstatSync(descriptor, { bigint: true });
+            if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) {
+                throw new Error('bootstrap readiness path changed while opening');
+            }
+            const bytes = Buffer.alloc(MAX_READINESS_BYTES + 1);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const count = readSync(descriptor, bytes, offset, bytes.length - offset, null);
+                if (count === 0)
+                    break;
+                offset += count;
+            }
+            if (offset > MAX_READINESS_BYTES) {
+                throw new Error('bootstrap readiness path is not a bounded regular file');
+            }
+            const raw = bytes.subarray(0, offset).toString('utf8');
+            const after = fstatSync(descriptor, { bigint: true });
+            if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size
+                || after.mtimeNs !== opened.mtimeNs || after.ctimeNs !== opened.ctimeNs) {
+                throw new Error('bootstrap readiness path changed while reading');
+            }
+            const parsed = coreBootstrap.parseLifecycleBootstrapReadinessJson(raw);
+            if (!parsed)
+                throw new Error('bootstrap readiness receipt is corrupt');
+            return parsed;
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+export function publishLifecycleBootstrapReadiness(input) {
+    const transactionId = input.env[coreBootstrap.LIFECYCLE_BOOTSTRAP_TRANSACTION_ENV]?.trim();
+    if (!transactionId)
+        return;
+    const pid = input.pid ?? process.pid;
+    const supervisorPid = input.supervisorPid ?? process.ppid;
+    const readProcessStartIdentity = input.readProcessStartIdentity
+        ?? util.readFileLockProcessStartIdentity;
+    const pidProcessStartIdentity = readProcessStartIdentity(pid);
+    const supervisorProcessStartIdentity = readProcessStartIdentity(supervisorPid);
+    if (!pidProcessStartIdentity || !supervisorProcessStartIdentity) {
+        throw new Error('lifecycle bootstrap readiness process identity is unavailable');
+    }
+    const readiness = {
+        schema: coreBootstrap.LIFECYCLE_BOOTSTRAP_READINESS_SCHEMA,
+        transactionId,
+        pid,
+        pidProcessStartIdentity,
+        supervisorPid,
+        supervisorProcessStartIdentity,
+        startedAt: input.startedAt,
+        ipcUrl: input.ipcUrl,
+    };
+    if (!coreBootstrap.parseLifecycleBootstrapReadiness(readiness)) {
+        throw new Error('invalid lifecycle bootstrap readiness receipt');
+    }
+    const stateDir = resolveBootstrapStateDir(input.env);
+    const state = lstatSync(stateDir);
+    if (!state.isDirectory() || state.isSymbolicLink()) {
+        throw new Error('lifecycle bootstrap state directory is not trusted');
+    }
+    if (process.platform !== 'win32') {
+        const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+        if ((uid !== undefined && state.uid !== uid) || (state.mode & 0o077) !== 0) {
+            throw new Error('lifecycle bootstrap state directory is not owner-only');
+        }
+    }
+    const path = join(stateDir, coreBootstrap.LIFECYCLE_BOOTSTRAP_READINESS_FILE);
+    const lockPath = join(stateDir, coreBootstrap.LIFECYCLE_BOOTSTRAP_READINESS_LOCK_FILE);
+    util.acquireLock(lockPath, { maxTries: 500, waitMs: 10 });
+    let publicationError;
+    let publicationFailed = false;
+    try {
+        const existing = readExistingReadiness(path);
+        if (existing && existing.transactionId !== transactionId) {
+            throw new Error('lifecycle bootstrap readiness is owned by another transaction');
+        }
+        const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+        let descriptor;
+        try {
+            descriptor = openSync(temporary, 'wx', 0o600);
+            writeFileSync(descriptor, `${JSON.stringify(readiness)}\n`, { encoding: 'utf8' });
+            fchmodSync(descriptor, 0o600);
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporary, path);
+            syncDirectory(stateDir);
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            rmSync(temporary, { force: true });
+        }
+    }
+    catch (error) {
+        publicationError = error;
+        publicationFailed = true;
+    }
+    const released = util.releaseLock(lockPath);
+    if (!released.released
+        || (released.reason !== 'released' && released.reason !== 'released_with_cleanup_error')) {
+        throw new Error(`lifecycle bootstrap readiness lock release failed: ${released.reason}`, {
+            cause: publicationFailed
+                ? new AggregateError([publicationError, new Error(released.reason)])
+                : undefined,
+        });
+    }
+    if (publicationFailed)
+        throw publicationError;
+}

package/dist/selfUpdate/builtinKey.d.ts

@@ -0,0 +1,4 @@
+/** Ed25519 SPKI public key (base64 DER) matching the v2-beta release environment signing key. */
+export declare const BUILTIN_SELF_UPDATE_PUBLIC_KEY = "MCowBQYDK2VwAyEAAgoV6aWwJd5zlxOcPqWuxkDB+isQnKydFStV8X3DxMk=";
+/** Resolve the self-update verification public key: env override wins, else the built-in key. */
+export declare function resolveSelfUpdatePublicKey(env?: NodeJS.ProcessEnv): string;

package/dist/selfUpdate/builtinKey.js

@@ -0,0 +1,16 @@
+// Built-in Ed25519 verification public key for the official v2-beta self-update channel.
+//
+// A public key is not secret: embedding it lets nodes installed through a trusted
+// distribution channel (npm tarball or prebuilt release binary) verify signed update
+// manifests with zero per-node configuration. Trust bootstraps from the install
+// channel itself (npm registry integrity / release artifact provenance), and every
+// later self-update stays signature-gated.
+//
+// EVOLVER_SELF_UPDATE_PUBLIC_KEY overrides this when set (rotation / private fleets).
+/** Ed25519 SPKI public key (base64 DER) matching the v2-beta release environment signing key. */
+export const BUILTIN_SELF_UPDATE_PUBLIC_KEY = 'MCowBQYDK2VwAyEAAgoV6aWwJd5zlxOcPqWuxkDB+isQnKydFStV8X3DxMk=';
+/** Resolve the self-update verification public key: env override wins, else the built-in key. */
+export function resolveSelfUpdatePublicKey(env = process.env) {
+    const configured = env['EVOLVER_SELF_UPDATE_PUBLIC_KEY']?.trim();
+    return configured || BUILTIN_SELF_UPDATE_PUBLIC_KEY;
+}

package/dist/selfUpdate/controllerLifecycleAuthority.d.ts

@@ -0,0 +1,45 @@
+import type { util } from '@evomap/evolver-core';
+import { type PreparedRecoveryChildStartGate, type RecoveryChildStartGateRole } from './recoveryChildStartGate.js';
+interface RecoveryControllerLifecycleLease {
+    readonly owner: util.FileLockOwnerRecord;
+    assertOwned(): void;
+    armProcess(pid: number): util.FileLockOwnerRecord;
+    disarmProcess(): void;
+    retainProcess(): void;
+    transferToProcess(pid: number): util.FileLockOwnerRecord;
+    release(): void;
+}
+type RecoveryControllerLifecycleLeaseAcquirer = (env: NodeJS.ProcessEnv, options: {
+    maxTries: number;
+    waitMs: number;
+}) => RecoveryControllerLifecycleLease;
+type SupervisedActivationDelegationAssertion = (env: NodeJS.ProcessEnv) => void;
+interface RecoveryControllerPreparedOwnerCapability {
+    env: NodeJS.ProcessEnv;
+    startupAckToken: string;
+}
+interface RecoveryControllerPreparedChild {
+    env: NodeJS.ProcessEnv;
+    startupAckToken?: string;
+    startupGateToken: string;
+}
+type RecoveryControllerChildCapabilityFactory = (env: NodeJS.ProcessEnv, owner: util.FileLockOwnerRecord) => RecoveryControllerPreparedOwnerCapability;
+type RecoveryControllerStartGateFactory = (env: NodeJS.ProcessEnv, role: RecoveryChildStartGateRole, expectedParent?: Pick<util.FileLockOwnerRecord, 'pid' | 'processStartIdentity'>) => PreparedRecoveryChildStartGate;
+export interface RecoveryControllerAuthorityDependencies {
+    acquireOwnerLease?: RecoveryControllerLifecycleLeaseAcquirer;
+    assertActivationDelegation?: SupervisedActivationDelegationAssertion;
+    prepareOwnerCapability?: RecoveryControllerChildCapabilityFactory;
+    prepareStartGate?: RecoveryControllerStartGateFactory;
+}
+export interface RecoveryControllerAuthority {
+    readonly kind: 'owned' | 'delegated';
+    assertAuthorized(): void;
+    prepareTarget(env: NodeJS.ProcessEnv): RecoveryControllerPreparedChild;
+    prepareWorker(env: NodeJS.ProcessEnv): PreparedRecoveryChildStartGate;
+    armProcess(pid: number): void;
+    disarmProcess(): void;
+    retainProcess(): void;
+    release(): void;
+}
+export declare function resolveRecoveryControllerAuthority(env: NodeJS.ProcessEnv, dependencies?: RecoveryControllerAuthorityDependencies): Promise<RecoveryControllerAuthority>;
+export {};

package/dist/selfUpdate/controllerLifecycleAuthority.js

@@ -0,0 +1,61 @@
+import { prepareRecoveryChildStartGate, } from './recoveryChildStartGate.js';
+export async function resolveRecoveryControllerAuthority(env, dependencies = {}) {
+    const bootstrap = dependencies.acquireOwnerLease
+        && dependencies.assertActivationDelegation
+        && dependencies.prepareOwnerCapability
+        ? undefined
+        : await import('./bootstrap.js');
+    const acquireOwnerLease = dependencies.acquireOwnerLease
+        ?? bootstrap.acquireLifecycleBootstrapOwnerLease;
+    const assertActivationDelegation = dependencies.assertActivationDelegation
+        ?? bootstrap.assertActiveSupervisedLifecycleBootstrapDelegation;
+    const prepareOwnerCapability = dependencies.prepareOwnerCapability
+        ?? bootstrap.prepareRecoveryControllerLifecycleOwnerCapability;
+    const prepareStartGate = dependencies.prepareStartGate ?? prepareRecoveryChildStartGate;
+    try {
+        const lease = acquireOwnerLease(env, { maxTries: 2, waitMs: 0 });
+        return {
+            kind: 'owned',
+            assertAuthorized: () => { lease.assertOwned(); },
+            prepareTarget: (childEnv) => {
+                lease.assertOwned();
+                const ownerCapability = prepareOwnerCapability(childEnv, lease.owner);
+                const startGate = prepareStartGate(ownerCapability.env, 'proxy-target', lease.owner);
+                return { ...ownerCapability, ...startGate };
+            },
+            prepareWorker: (childEnv) => {
+                lease.assertOwned();
+                return prepareStartGate(childEnv, 'windows-updater', lease.owner);
+            },
+            armProcess: (pid) => { lease.armProcess(pid); },
+            disarmProcess: () => { lease.disarmProcess(); },
+            retainProcess: () => { lease.retainProcess(); },
+            release: () => { lease.release(); },
+        };
+    }
+    catch (leaseError) {
+        try {
+            assertActivationDelegation(env);
+        }
+        catch (delegationError) {
+            throw new AggregateError([leaseError, delegationError], 'self_update_recovery_controller_authority_unavailable');
+        }
+        return {
+            kind: 'delegated',
+            assertAuthorized: () => { assertActivationDelegation(env); },
+            prepareTarget: (childEnv) => {
+                assertActivationDelegation(env);
+                return prepareStartGate(childEnv, 'proxy-target');
+            },
+            prepareWorker: () => {
+                throw new Error('self_update_recovery_controller_owner_lease_required');
+            },
+            armProcess: () => {
+                throw new Error('self_update_recovery_controller_delegated_guardian_unavailable');
+            },
+            disarmProcess: () => { },
+            retainProcess: () => { },
+            release: () => { },
+        };
+    }
+}

package/dist/selfUpdate/executor.d.ts

@@ -1,8 +1,9 @@
 import { ops } from '@evomap/evolver-core';
 import { type SelfUpdateFailureCode } from './failureCodes.js';
+import type { DurableSelfUpdateSession } from './transaction.js';
 type DownloadedArtifact = ops.DownloadedArtifact;
 /** Structured outcome codes — reported to telemetry; the hub sees WHY an update did/didn't apply. */
-export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'already_in_progress' | 'disabled';
+export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'restart_failed' | 'rollback_failed' | 'already_in_progress' | 'disabled';
 export interface SelfUpdateResult {
     outcome: SelfUpdateOutcome;
     reason: string;
@@ -13,13 +14,17 @@ export interface SelfUpdateResult {
     /**
      * Which download path produced the staged binary: `'binary'` is the normal
      * precompiled-asset happy path, `'tarball'` means the binary download failed
-     * and Channel 1b (release `.tar.gz`) fallback was used. The verifyManifest
+     * and Channel 1b (release `.tar.gz`) fallback was used. The selected-artifact
      * gate ran in BOTH cases, so apply-semantics are identical, but "tarball
      * used in production" is a useful CDN/rate-limit signal for the hub.
      * Persisted into `last_update.json` (lastUpdate.LastUpdatePayload.applied_via)
      * on success so the hub can observe the channel directly.
      */
     appliedVia?: 'binary' | 'tarball';
+    /** Durable installs are not successful until the relaunched daemon completes startup health checks. */
+    confirmationPending?: true;
+    /** A bounded integrity warning from cleanup that did not change the primary update outcome. */
+    cleanupWarning?: string;
 }
 /** The hub's force_update directive (inbound message payload). */
 export interface ForceUpdateDirective {
@@ -36,7 +41,7 @@ export interface ForceUpdateDirective {
 export interface DownloadResult {
     /** Where the new version was staged (e.g. a tmp dir). Passed to atomicReplace on success. */
     stagedPath: string;
-    /** The downloaded artifacts (bytes or precomputed sha256) for verifyManifest. */
+    /** Exactly one selected artifact (bytes or precomputed sha256) for verification. */
     artifacts: readonly DownloadedArtifact[];
     /**
      * Which channel actually produced the staged bytes — defaults to `'binary'`
@@ -57,31 +62,42 @@ export interface SelfUpdateDeps {
     policy: 'off' | 'prompt' | 'auto';
     /** Current installed version (read from package.json by the caller). */
     currentVersion: string;
+    /** Lazy cross-process lease that serializes self-update with lifecycle mutations. */
+    acquireLifecycleLease?: () => Promise<SelfUpdateLifecycleLease> | SelfUpdateLifecycleLease;
     /** Resolve a trusted manifest when the hub directive does not carry one. */
     resolveManifest?: (directive: ForceUpdateDirective, currentVersion: string) => Promise<unknown> | unknown;
     /** Download the staged release for the target version. Throws/rejects on failure. */
     download: (targetVersion: string, directive: ForceUpdateDirective) => Promise<DownloadResult>;
     /** Atomically replace the install tree with the staged path (preserving node_modules/.env/etc). Throws on fail. */
     atomicReplace: (stagedPath: string) => Promise<void>;
+    /** Optional durable transaction: cross-process lock + journal + backup + recovery-aware install. */
+    beginTransaction?: (targetVersion: string) => Promise<DurableSelfUpdateSession>;
     /** Signal a restart so the supervisor relaunches the new version. v1 convention: process.exit(78). */
-    restart: () => void;
+    restart: () => void | Promise<void>;
     /** Optional Ed25519 public key (PEM / raw base64). When set, an unsigned/badly-signed manifest is REJECTED. */
     publicKey?: string;
     /** Best-effort telemetry sink for the structured outcome (never throws into the update path). */
     onTelemetry?: (result: SelfUpdateResult) => void;
+    /** One-shot operator warning sink for a lifecycle lease cleanup integrity failure. */
+    onCleanupWarning?: (warning: string, result: SelfUpdateResult) => void;
+}
+export interface SelfUpdateLifecycleLease {
+    assertOwned(): Promise<void> | void;
+    release(): Promise<void> | void;
 }
 /** Test-only: reset the mutex between cases. Not part of the public update path. */
 export declare function _resetSelfUpdateMutex(): void;
 /**
- * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
+ * Execute a force_update directive end to end: fast exits → lease → resolve/decide → download → VERIFY → replace → restart.
  *
  * Order is load-bearing:
- *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
- *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
- *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
- *  4. download the staged release.
- *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
- *  6. atomicReplace, then restart(). Only reached after verification passed.
+ *  1. policy off → do nothing (explicit opt-out; auto is hard-gated upstream by supervisor + public key).
+ *  2. reject malformed/already-satisfied required versions without acquiring the lifecycle owner lease.
+ *  3. mutex + lifecycle owner lease: exactly one executor may resolve or mutate release state.
+ *  4. resolve and decideUpdate (pure): reject bad manifests or NOOP under the held lease.
+ *  5. download the staged release.
+ *  6. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
+ *  7. atomicReplace, then restart(). Only reached after verification passed.
  *
  * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
  * on the old (intact) version.