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

package/dist/private/nodeCredentialStore.d.ts

@@ -0,0 +1,23 @@
+export interface WindowsSecretProtector {
+    protect(secret: string): string;
+    unprotect(protectedValue: string): string;
+    preflight?(): void;
+}
+export interface PrivateNodeCredentialStoreOptions {
+    platform?: NodeJS.Platform;
+    windowsProtector?: WindowsSecretProtector;
+}
+export declare class PrivateNodeCredentialReadError extends Error {
+    constructor();
+}
+export declare class PrivateNodeCredentialStore {
+    private readonly directory;
+    private readonly path;
+    private readonly platform;
+    private readonly windowsProtector;
+    constructor(proxyStorePath: string, options?: PrivateNodeCredentialStoreOptions);
+    read(): string | undefined;
+    write(nodeSecret: string): void;
+    private prepareDirectory;
+    private assertRegularFile;
+}

package/dist/private/nodeCredentialStore.js

@@ -0,0 +1,210 @@
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const NODE_SECRET_RE = /^[a-f0-9]{64}$/i;
+const WINDOWS_PROTECTED_VALUE_RE = /^[a-z0-9+/]+={0,2}$/i;
+const MAX_PROTECTED_VALUE_LENGTH = 16_384;
+export class PrivateNodeCredentialReadError extends Error {
+    constructor() {
+        super('stored private node credential is unreadable');
+        this.name = 'PrivateNodeCredentialReadError';
+    }
+}
+export class PrivateNodeCredentialStore {
+    directory;
+    path;
+    platform;
+    windowsProtector;
+    constructor(proxyStorePath, options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.windowsProtector = this.platform === 'win32'
+            ? options.windowsProtector ?? createWindowsDpapiProtector()
+            : undefined;
+        if (this.windowsProtector)
+            verifyWindowsProtector(this.windowsProtector);
+        this.directory = join(dirname(resolve(proxyStorePath)), '.private-credentials');
+        this.path = join(this.directory, this.platform === 'win32' ? 'node-secret.dpapi' : 'node-secret');
+        this.prepareDirectory();
+    }
+    read() {
+        if (!existsSync(this.path))
+            return undefined;
+        this.assertRegularFile(this.path);
+        if (this.platform !== 'win32')
+            chmodSync(this.path, FILE_MODE);
+        const storedValue = readFileSync(this.path, 'utf8').trim();
+        try {
+            const value = this.windowsProtector
+                ? this.windowsProtector.unprotect(assertWindowsProtectedValue(storedValue))
+                : storedValue;
+            if (!NODE_SECRET_RE.test(value))
+                throw new PrivateNodeCredentialReadError();
+            return value;
+        }
+        catch {
+            throw new PrivateNodeCredentialReadError();
+        }
+    }
+    write(nodeSecret) {
+        if (!NODE_SECRET_RE.test(nodeSecret))
+            throw new Error('private node credential is invalid');
+        const storedValue = this.windowsProtector
+            ? assertWindowsProtectedValue(this.windowsProtector.protect(nodeSecret))
+            : nodeSecret;
+        this.prepareDirectory();
+        if (existsSync(this.path))
+            this.assertRegularFile(this.path);
+        const temporaryPath = join(this.directory, `.node-secret.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+        let descriptor;
+        try {
+            descriptor = openSync(temporaryPath, 'wx', FILE_MODE);
+            writeFileSync(descriptor, storedValue, 'utf8');
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporaryPath, this.path);
+            if (this.platform !== 'win32')
+                chmodSync(this.path, FILE_MODE);
+            if (this.platform !== 'win32')
+                syncDirectory(this.directory);
+        }
+        catch (error) {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            if (existsSync(temporaryPath))
+                unlinkSync(temporaryPath);
+            throw error;
+        }
+    }
+    prepareDirectory() {
+        const parent = dirname(this.directory);
+        const parentStat = lstatSync(parent);
+        if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) {
+            throw new Error(`private credential parent must be a real directory: ${parent}`);
+        }
+        if (this.platform !== 'win32' && (parentStat.mode & 0o022) !== 0) {
+            throw new Error(`private credential parent must not be group/world-writable: ${parent}`);
+        }
+        const directoryExisted = existsSync(this.directory);
+        mkdirSync(this.directory, { recursive: true, mode: DIRECTORY_MODE });
+        const stat = lstatSync(this.directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`private credential path must be a real directory: ${this.directory}`);
+        }
+        if (this.platform !== 'win32')
+            chmodSync(this.directory, DIRECTORY_MODE);
+        if (!directoryExisted && this.platform !== 'win32')
+            syncDirectory(parent);
+    }
+    assertRegularFile(path) {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`private credential must be a regular file: ${path}`);
+        }
+    }
+}
+function assertWindowsProtectedValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > MAX_PROTECTED_VALUE_LENGTH || !WINDOWS_PROTECTED_VALUE_RE.test(trimmed)) {
+        throw new Error('stored private node credential ciphertext is invalid');
+    }
+    return trimmed;
+}
+function createWindowsDpapiProtector() {
+    const systemRoot = process.env['SystemRoot']?.trim();
+    if (!systemRoot || !isAbsolute(systemRoot)) {
+        throw new Error('Windows private credential persistence requires an absolute SystemRoot');
+    }
+    const executable = join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    let executableIsSafe = false;
+    try {
+        const executableStat = lstatSync(executable);
+        executableIsSafe = executableStat.isFile() && !executableStat.isSymbolicLink();
+    }
+    catch {
+        // Normalize filesystem errors so local paths are not included in startup logs.
+    }
+    if (!executableIsSafe) {
+        throw new Error('Windows private credential persistence requires Windows PowerShell');
+    }
+    return {
+        preflight: () => {
+            const canary = randomBytes(32).toString('hex');
+            if (runWindowsPowerShell(executable, WINDOWS_DPAPI_PREFLIGHT_SCRIPT, canary) !== canary) {
+                throw new Error('Windows private credential protection preflight failed');
+            }
+        },
+        protect: (secret) => runWindowsPowerShell(executable, WINDOWS_DPAPI_PROTECT_SCRIPT, secret),
+        unprotect: (protectedValue) => runWindowsPowerShell(executable, WINDOWS_DPAPI_UNPROTECT_SCRIPT, protectedValue),
+    };
+}
+function verifyWindowsProtector(protector) {
+    try {
+        if (protector.preflight) {
+            protector.preflight();
+            return;
+        }
+        const canary = randomBytes(32).toString('hex');
+        const protectedCanary = assertWindowsProtectedValue(protector.protect(canary));
+        if (protector.unprotect(protectedCanary) !== canary) {
+            throw new Error('round trip mismatch');
+        }
+    }
+    catch {
+        throw new Error('Windows private credential protection preflight failed');
+    }
+}
+function runWindowsPowerShell(executable, script, input) {
+    try {
+        return execFileSync(executable, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf8',
+            input,
+            maxBuffer: 64 * 1024,
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 15_000,
+            windowsHide: true,
+        }).trim();
+    }
+    catch {
+        throw new Error('Windows private credential protection failed');
+    }
+}
+const WINDOWS_DPAPI_PREFLIGHT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$plain = [Console]::In.ReadToEnd()',
+    '$bytes = [Text.Encoding]::UTF8.GetBytes($plain)',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$protected = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, $scope)',
+    '$restored = [Security.Cryptography.ProtectedData]::Unprotect($protected, $null, $scope)',
+    '[Console]::Out.Write([Text.Encoding]::UTF8.GetString($restored))',
+].join('; ');
+const WINDOWS_DPAPI_PROTECT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$plain = [Console]::In.ReadToEnd()',
+    '$bytes = [Text.Encoding]::UTF8.GetBytes($plain)',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$protected = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, $scope)',
+    '[Console]::Out.Write([Convert]::ToBase64String($protected))',
+].join('; ');
+const WINDOWS_DPAPI_UNPROTECT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$protected = [Convert]::FromBase64String([Console]::In.ReadToEnd())',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$bytes = [Security.Cryptography.ProtectedData]::Unprotect($protected, $null, $scope)',
+    '[Console]::Out.Write([Text.Encoding]::UTF8.GetString($bytes))',
+].join('; ');
+function syncDirectory(path) {
+    const descriptor = openSync(path, 'r');
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/router/messagesRoute.js

@@ -235,9 +235,15 @@ function sessionIdFromUserField(value) {
         }
     }
     if (parsed && typeof parsed === 'object') {
-        const sid = parsed['session_id'];
-        if (typeof sid === 'string' && sid.length > 0)
-            return safePlainSessionId(sid);
+        // Accept both spellings. The archive-side session key (agentic-trace-pipeline
+        // derive_session_key) reads `session_id ?? sessionId` from this same field, so a
+        // camelCase producer yields a `cc::<sid>` key upstream while we recorded null —
+        // the two datasets then silently fail to join. Both spellings still pass through
+        // safePlainSessionId; this widens the accepted key name, never the value guard.
+        const raw = parsed['session_id']
+            ?? parsed['sessionId'];
+        if (typeof raw === 'string' && raw.length > 0)
+            return safePlainSessionId(raw);
     }
     return '';
 }

package/dist/router/providerRoutes.js

@@ -998,9 +998,13 @@ function sessionIdFromUserField(value) {
         }
     }
     if (parsed && typeof parsed === 'object') {
-        const sid = parsed['session_id'];
-        if (typeof sid === 'string' && sid.length > 0)
-            return safePlainSessionId(sid);
+        // Accept both spellings — see the matching note in messagesRoute.ts. The
+        // archive-side session key reads `session_id ?? sessionId` from this field, so
+        // dropping camelCase here costs a join, not just a field.
+        const raw = parsed['session_id']
+            ?? parsed['sessionId'];
+        if (typeof raw === 'string' && raw.length > 0)
+            return safePlainSessionId(raw);
     }
     return '';
 }

package/dist/selfUpdate/bootstrap.d.ts

@@ -0,0 +1,162 @@
+import { spawn } from 'node:child_process';
+import { util } from '@evomap/evolver-core';
+import { type MigrationOptions } from './migration.js';
+export declare const RECOVERY_CONTROLLER_LIFECYCLE_OWNER_CAPABILITY_ENV = "EVOLVER_INTERNAL_RECOVERY_CONTROLLER_LIFECYCLE_OWNER";
+type BootstrapProcessKill = (pid: number, signal: NodeJS.Signals | 0) => boolean;
+type BootstrapSkipReason = 'already_supervised' | 'already_bootstrapped' | 'unsupported_install_shape' | 'policy_not_auto' | 'bootstrap_disabled' | 'ci_environment' | 'container_environment' | 'recent_failure' | 'migration_ambiguous' | 'bootstrap_attempt_invalid' | 'bootstrap_intent_pending' | 'bootstrap_attempt_pending';
+export interface BootstrapDecision {
+    proceed: boolean;
+    reason?: BootstrapSkipReason;
+}
+export interface BootstrapOutcome {
+    ok: boolean;
+    /**
+     * 'bootstrapped' / 'bootstrapped_lock_release_unconfirmed' / 'migrated' on success;
+     * failure/skip reason otherwise. Migration failures record 'migration_failed' /
+     * 'migration_timeout' (both cooldown-worthy).
+     */
+    reason: string;
+    detail?: string;
+    /** The child may own manager or IPC state, so the foreground proxy must exit. */
+    requiresForegroundExit?: true;
+}
+export interface BootstrapRunOptions {
+    env: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    argv1?: string;
+    /** Parent force-timeout; it must exceed the child's transaction budget. */
+    timeoutMs?: number;
+    /** Absolute child deadline offset. Production uses the complete transaction budget. */
+    transactionBudgetMs?: number;
+    /** Bounded wait for OS confirmation after force-terminating the process tree. */
+    terminationGraceMs?: number;
+    now?: number;
+    exists?: (path: string) => boolean;
+    readFile?: (path: string) => string;
+    writeFile?: (path: string, content: string) => void;
+    spawnFn?: typeof spawn;
+    treeKillSpawnFn?: typeof spawn;
+    processKill?: BootstrapProcessKill;
+    /** Test-only failure seam; production publication always uses the strict exclusive writer. */
+    beforeIntentPublish?: () => void;
+    /** Test-only crash seam for each durable initial-publication boundary. */
+    afterIntentPublicationStep?: (step: 'create' | 'partial_write' | 'file_fsync' | 'link' | 'directory_fsync', path: string) => void;
+    /** Test-only crash seams around the atomic terminal/clear state transitions. */
+    beforeIntentTerminalFsync?: (path: string) => void;
+    afterIntentTerminalPublish?: () => void;
+    afterIntentClearRename?: () => void;
+    /** Test-only trust seams. Production always uses native owner/DACL validation. */
+    assertIntentDirectoryTrust?: (directory: string) => void;
+    assertIntentFileTrust?: (path: string) => void;
+    assertLegacyProofDirectoryTrust?: (directory: string) => void;
+    assertLegacyProofFileTrust?: (path: string) => void;
+    afterLegacyProofRead?: (path: string) => void;
+    /** Test-only process identity seams; production uses fresh native core observations. */
+    readRegistrationProcessStartIdentity?: (pid: number) => util.FileLockProcessStartIdentity | null;
+    registrationOwnerProcessStatus?: (owner: Pick<util.FileLockOwnerRecord, 'pid' | 'processStartIdentity'>) => util.FileLockOwnerProcessStatus;
+    registrationPublisherProcessStatus?: (publisher: Readonly<{
+        pid: number;
+        token: string;
+        processIdentityDigest: string;
+    }>) => util.FileLockOwnerProcessStatus;
+    /**
+     * Extra seams forwarded to the one-time npm/JS → standalone migration (migration.ts).
+     * Bootstrap-level seams (exists/readFile/writeFile/spawnFn/now/execPath) win when both
+     * are supplied, so the decision and the migration observe the same injected world.
+     */
+    migration?: MigrationOptions;
+}
+/** Lifecycle state dir mirror of evolver-cli lifecyclePaths (kept dependency-free across packages). */
+export declare function resolveBootstrapStateDir(env: NodeJS.ProcessEnv): string;
+export declare function withRecoveryControllerLifecycleOwnerCapability(env: NodeJS.ProcessEnv, owner: util.FileLockOwnerRecord): NodeJS.ProcessEnv;
+export interface PreparedRecoveryControllerLifecycleOwnerCapability {
+    env: NodeJS.ProcessEnv;
+    startupAckToken: string;
+}
+export declare function prepareRecoveryControllerLifecycleOwnerCapability(env: NodeJS.ProcessEnv, owner: util.FileLockOwnerRecord): PreparedRecoveryControllerLifecycleOwnerCapability;
+export declare function clearRecoveryControllerLifecycleOwnerCapability(env: NodeJS.ProcessEnv): void;
+export declare function publishRecoveryControllerLifecycleStartupAttestation(env: NodeJS.ProcessEnv, descriptor?: number): boolean;
+export declare function lifecycleBootstrapStatePresent(env: NodeJS.ProcessEnv, exists?: (path: string) => boolean): boolean;
+export type BootstrapDurableStateOptions = Pick<BootstrapRunOptions, 'exists' | 'readFile' | 'assertIntentFileTrust' | 'assertLegacyProofDirectoryTrust' | 'assertLegacyProofFileTrust' | 'afterLegacyProofRead' | 'registrationOwnerProcessStatus' | 'now'> & {
+    /** Exact owner currently holding the shared lifecycle mutation lock. */
+    expectedRecoveryOwner?: util.FileLockOwnerRecord;
+};
+export interface LifecycleBootstrapOwnerLease {
+    readonly path: string;
+    readonly owner: util.FileLockOwnerRecord;
+    assertOwned(): void;
+    armProcess(pid: number): util.FileLockOwnerRecord;
+    disarmProcess(): void;
+    retainProcess(): void;
+    transferToProcess(pid: number): util.FileLockOwnerRecord;
+    release(): void;
+}
+export declare function assertSupervisedLifecycleBootstrapState(env: NodeJS.ProcessEnv, options?: BootstrapDurableStateOptions & {
+    requireLifecycleState?: boolean;
+    /** Test-only parent identity seam; production always binds to process.ppid. */
+    recoveryControllerParentPid?: number;
+}): void;
+/**
+ * Revalidate the narrow parent-owned activation window used by a newly launched recovery
+ * controller. This deliberately rejects committed supervision: callers use it only as delegated
+ * authority while the lifecycle parent still owns the mutation lock and is waiting for readiness.
+ */
+export declare function assertActiveSupervisedLifecycleBootstrapDelegation(env: NodeJS.ProcessEnv, options?: BootstrapDurableStateOptions): void;
+/**
+ * Revalidate a transaction-bound launcher before any self-update operation. Unlike the startup
+ * assertion above, this never accepts the narrow activating window used to publish readiness.
+ */
+export declare function assertCommittedLifecycleBootstrapState(env: NodeJS.ProcessEnv, options?: BootstrapDurableStateOptions): void;
+/**
+ * Serialize self-update with every lifecycle bootstrap, recovery, and manual-transition writer.
+ * Acquisition is deliberately fail-fast: a heartbeat must not block the daemon while another
+ * lifecycle owner is active. Transaction-bound launchers revalidate the committed receipt under
+ * the exact acquired generation; legacy launchers still hold and recheck the shared owner lock.
+ */
+export declare function acquireLifecycleBootstrapOwnerLease(env: NodeJS.ProcessEnv, lockOptions?: {
+    maxTries?: number;
+    waitMs?: number;
+}): LifecycleBootstrapOwnerLease;
+export declare function looksLikeContainer(exists: (path: string) => boolean, readFile: (path: string) => string): boolean;
+/** True when a recent bootstrap/migration attempt failed within the cooldown window. */
+export declare function recentBootstrapFailure(env: NodeJS.ProcessEnv, optionsOrReadFile: Pick<BootstrapRunOptions, 'exists' | 'readFile' | 'assertIntentFileTrust'> | ((path: string) => string), now: number): boolean;
+/**
+ * Decide whether an unsupervised (degraded) startup should attempt first-run bootstrap.
+ * Pure — filesystem access is injectable for tests.
+ */
+export declare function shouldBootstrap(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: Pick<BootstrapRunOptions, 'exists' | 'readFile' | 'now' | 'execPath' | 'assertIntentFileTrust'>): BootstrapDecision;
+/**
+ * Resolve the `lifecycle bootstrap` invocation for the current install shape: standalone binary,
+ * CLI entry through node, or the npm-installed @evomap/evolver-cli sibling. Returns undefined when
+ * no CLI can be located. The caller may continue only after confirming durable state is clean.
+ */
+export declare function resolveBootstrapCliInvocation(options?: Pick<BootstrapRunOptions, 'execPath' | 'argv1' | 'exists'>): {
+    command: string;
+    args: string[];
+} | undefined;
+/** Best-effort attempt marker; never throws — bootstrap bookkeeping must not break startup. */
+export declare function recordBootstrapAttempt(env: NodeJS.ProcessEnv, outcome: BootstrapOutcome, options?: Pick<BootstrapRunOptions, 'writeFile' | 'now'>): void;
+/** Spawn `evolver lifecycle bootstrap` and await its result within a bounded timeout. */
+export declare function runBootstrap(options: BootstrapRunOptions): Promise<BootstrapOutcome>;
+export type DegradedStartupBootstrapResult = {
+    disposition: 'continue';
+    handedOver: false;
+    message: string;
+} | {
+    disposition: 'handoff';
+    handedOver: true;
+    exitCode: 0;
+    message: string;
+} | {
+    disposition: 'fail_closed';
+    handedOver: false;
+    exitCode: 1;
+    message: string;
+};
+/**
+ * Orchestrate bootstrap for a degraded (default-auto, unsupervised) startup: decide, attempt,
+ * record, and produce the operator message. Never throws.
+ */
+export declare function bootstrapDegradedSelfUpdateStartup(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: Omit<BootstrapRunOptions, 'env' | 'platform'>): Promise<DegradedStartupBootstrapResult>;
+export {};