@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,539 lines • 64 kB
text/typescript
import { publishCredentialAsync, publishCredentialSync } from "../local-credentials/generation";
import { randomUUID } from "node:crypto";
import { Database } from "bun:sqlite";
import {
chmodSync,
closeSync,
constants as fsConstants,
existsSync,
fstatSync,
ftruncateSync,
lstatSync,
mkdirSync,
openSync,
readFileSync,
readdirSync,
realpathSync,
renameSync,
rmSync,
statSync,
unlinkSync,
writeFileSync,
} from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
import { atomicWriteFileAsync } from "../config";
import { hardenSecretDirAsync, hardenSecretPathAsync } from "../lib/windows-secret-acl";
import { applyConfirmedMainCodexAccountTransition } from "./account-lifecycle";
import {
assertStableLockFile,
openStableLockFile,
StableLockPathUnsafeError,
type StableLockFile,
} from "./native-main-lock-file";
import { decideNativeProfileRecovery } from "./native-profile-recovery";
import { probeNativeCodexProcesses, type NativeCodexProcessProbe } from "./native-profile-processes";
import {
assertUniqueNativeProfileLabel,
assertNativeProfileLockPath,
assertNativeProfileMetadataLayout,
assertNoLegacyNativeProfileState,
decryptNativeEnvelope,
encryptNativeEnvelope,
inspectNativeProfileJournal,
MAX_NATIVE_PROFILES,
nativeIdentityHash,
nativeIdentityHint,
nativeProfileSelectorKey,
OsNativeProfileKeyProvider,
publicNativeProfile,
readNativeEnvelope,
readNativeEnvelopeResult,
readNativeProfileVault,
probeNativeProfileRecoveryState,
requireFileCredentialStore,
resolveNativeCredentialStoreMode,
resolveNativeProfileContext,
serializeNativeProfileJournal,
serializeNativeProfileMetadata,
validateNativeProfileLabel,
type NativeEnvelopeSnapshot,
type NativeProfileContext,
} from "./native-profile-store";
import {
NativeProfileError,
type NativeMainProfileRecordV1,
type NativeMainProfileVaultV1,
type NativeProfileKey,
type NativeProfileKeyProvider,
type NativeProfilePublic,
type NativeProfileSwitchJournalV1,
} from "./native-profile-types";
import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
import {
NATIVE_STAGE_HEARTBEAT_INTERVAL_MS,
NativeProfileStageStore,
type NativeStageProof,
type NativeStageTerminalOutcome,
} from "./native-profile-stage-store";
import { writeNativeMainAuthFileAsync } from "./native-main-auth-file";
const LOCK_WAIT_MS = 5_000;
const LEGACY_STAGE_MAX_AGE_MS = 30 * 60_000;
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
interface PathIdentity {
dev: bigint;
ino: bigint;
}
type AtomicWriter = (path: string, content: string) => Promise<void>;
type TransitionApplier = (fromAccountId: string, toAccountId: string) => void;
type EnvelopeReader = (path: string) => NativeEnvelopeSnapshot;
type VaultReader = () => NativeMainProfileVaultV1 | null;
type EnvelopeResultReader = (path: string) => ReturnType<typeof readNativeEnvelopeResult>;
type StableLockOpener = (path: string) => StableLockFile;
type StableLockAsserter = (path: string, file: StableLockFile) => void;
export type NativeProfileSwitchBoundary =
| "journal-prepared"
| "auth-replaced"
| "vault-committed"
| "runtime-transition-published"
| "journal-deleted";
export interface NativeProfileManagerOptions {
codexHome?: string;
configDir?: string;
keyProvider?: NativeProfileKeyProvider;
atomicWrite?: AtomicWriter;
hardenPath?: (path: string) => Promise<void>;
processProbe?: () => Promise<NativeCodexProcessProbe>;
applyTransition?: TransitionApplier;
now?: () => number;
randomUUID?: () => string;
sleep?: (ms: number) => Promise<void>;
lockWaitMs?: number;
onLockAcquired?: () => void | Promise<void>;
removeStageTree?: (path: string) => void;
stageLeaseMs?: number;
/** Test-only crash seam; production never supplies this callback. */
onSwitchBoundary?: (boundary: NativeProfileSwitchBoundary) => void | Promise<void>;
/** Test-only reader seams; production uses the native profile store directly. */
readEnvelope?: EnvelopeReader;
readVault?: VaultReader;
readEnvelopeResult?: EnvelopeResultReader;
/** Test-only stable-path seams; production uses the native stable-lock helpers directly. */
stableLockOpen?: StableLockOpener;
stableLockAssert?: StableLockAsserter;
}
export interface NativeProfileListResult {
effectiveCodexHome: string;
activeProfileId: string | null;
profiles: NativeProfilePublic[];
}
export interface NativeStageCleanupResult {
removed: boolean;
plaintextMayRemain: boolean;
}
export interface NativeStageSweepResult {
removed: number;
live: number;
cleanupFailed: number;
plaintextMayRemain: boolean;
}
async function hardenNativeProfilePath(path: string): Promise<void> {
const entry = lstatSync(path);
if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", "A native-profile path is not a private file or directory.", 409);
}
const directory = entry.isDirectory();
const mode = directory ? 0o700 : 0o600;
try { chmodSync(path, mode); } catch { /* Windows ACL below is authoritative there. */ }
if (process.platform === "win32") {
if (directory) await hardenSecretDirAsync(path, { required: true, timeoutMemoKey: path });
else await hardenSecretPathAsync(path, { required: true, timeoutMemoKey: path });
}
}
function samePath(left: string, right: string): boolean {
return resolve(left) === resolve(right);
}
function pathIdentity(path: string): PathIdentity {
const entry = lstatSync(path, { bigint: true });
return { dev: entry.dev, ino: entry.ino };
}
function sameIdentity(left: PathIdentity, right: PathIdentity): boolean {
return left.dev === right.dev && left.ino === right.ino;
}
function assertPathIdentity(path: string, expected: PathIdentity, label: string): void {
try {
if (!sameIdentity(pathIdentity(path), expected)) throw new Error("identity changed");
} catch {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", `${label} was replaced during the native-profile operation.`, 409);
}
}
function assertSafeDirectory(path: string, label: string): string {
try {
const entry = lstatSync(path);
if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error("entry type");
const canonical = realpathSync.native(path);
if (!samePath(canonical, path)) throw new Error("path substitution");
return canonical;
} catch {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", `${label} is not a private canonical directory.`, 409);
}
}
function errorCode(error: unknown): string | undefined {
return error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : undefined;
}
export class NativeProfileManager {
readonly context: NativeProfileContext;
private readonly keyProvider: NativeProfileKeyProvider;
private readonly atomicWrite: AtomicWriter;
private readonly hardenPath: (path: string) => Promise<void>;
private readonly processProbe: () => Promise<NativeCodexProcessProbe>;
private readonly applyTransition: TransitionApplier;
private readonly now: () => number;
private readonly uuid: () => string;
private readonly sleep: (ms: number) => Promise<void>;
private readonly lockWaitMs: number;
private readonly onLockAcquired: () => void | Promise<void>;
private readonly removeStageTree: (path: string) => void;
private readonly onSwitchBoundary: (boundary: NativeProfileSwitchBoundary) => void | Promise<void>;
private readonly readEnvelope: EnvelopeReader;
private readonly readVault: VaultReader;
private readonly readEnvelopeResult: EnvelopeResultReader;
private readonly stableLockOpen: StableLockOpener;
private readonly stableLockAssert: StableLockAsserter;
private readonly stageStore: NativeProfileStageStore;
private activeRootIdentity: PathIdentity | null = null;
private activeLockFile: StableLockFile | null = null;
constructor(options: NativeProfileManagerOptions = {}) {
this.context = resolveNativeProfileContext(options);
this.keyProvider = options.keyProvider ?? new OsNativeProfileKeyProvider();
const write = options.atomicWrite ?? atomicWriteFileAsync;
this.atomicWrite = (path, content) => publishCredentialAsync(() => write(path, content));
this.hardenPath = options.hardenPath ?? hardenNativeProfilePath;
this.processProbe = options.processProbe ?? probeNativeCodexProcesses;
this.applyTransition = options.applyTransition ?? ((from, to) => { applyConfirmedMainCodexAccountTransition(from, to); });
this.now = options.now ?? Date.now;
this.uuid = options.randomUUID ?? randomUUID;
this.sleep = options.sleep ?? (ms => Bun.sleep(ms));
this.lockWaitMs = options.lockWaitMs ?? LOCK_WAIT_MS;
this.onLockAcquired = options.onLockAcquired ?? (() => {});
this.removeStageTree = options.removeStageTree ?? (path => rmSync(path, { recursive: true, force: false }));
this.onSwitchBoundary = options.onSwitchBoundary ?? (() => {});
this.readEnvelope = options.readEnvelope ?? readNativeEnvelope;
this.readVault = options.readVault ?? (() => readNativeProfileVault(this.context));
this.readEnvelopeResult = options.readEnvelopeResult ?? readNativeEnvelopeResult;
this.stableLockOpen = options.stableLockOpen ?? openStableLockFile;
this.stableLockAssert = options.stableLockAssert ?? assertStableLockFile;
this.stageStore = new NativeProfileStageStore({
context: this.context,
now: this.now,
randomUUID: this.uuid,
atomicWrite: this.atomicWrite,
hardenPath: this.hardenPath,
leaseMs: options.stageLeaseMs,
});
}
private async ensureRoot(): Promise<PathIdentity> {
assertNativeProfileMetadataLayout(this.context);
if (!existsSync(this.context.rootDir)) {
try { mkdirSync(this.context.rootDir, { mode: 0o700 }); }
catch (error) { if (errorCode(error) !== "EEXIST") throw error; }
}
const identity = pathIdentity(this.context.rootDir);
assertPathIdentity(this.context.rootDir, identity, "The native-profile metadata root");
await this.hardenPath(this.context.rootDir);
assertPathIdentity(this.context.rootDir, identity, "The native-profile metadata root");
assertNativeProfileMetadataLayout(this.context);
for (const name of readdirSync(this.context.rootDir)) {
assertPathIdentity(this.context.rootDir, identity, "The native-profile metadata root");
await this.hardenPath(join(this.context.rootDir, name));
assertPathIdentity(this.context.rootDir, identity, "The native-profile metadata root");
}
assertNativeProfileMetadataLayout(this.context);
assertPathIdentity(this.context.rootDir, identity, "The native-profile metadata root");
return identity;
}
private isLockBusy(error: unknown): boolean {
const code = errorCode(error);
const message = error instanceof Error ? error.message : String(error);
return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || /database (?:is|table is) locked/i.test(message);
}
private profileLockStorageUnsafe(): NativeProfileError {
return new NativeProfileError("PROFILE_STORAGE_UNSAFE", "The native-profile transaction lock was replaced.", 409);
}
private profileLockUnavailable(): NativeProfileError {
return new NativeProfileError("PROFILE_LOCK_UNAVAILABLE", "The native-profile lock is unavailable.", 503, true);
}
private isExplicitProfileLockStorageUnsafe(error: unknown): boolean {
const code = errorCode(error);
const message = error instanceof Error ? error.message : String(error);
return error instanceof StableLockPathUnsafeError
|| code === "ELOOP"
|| code === "EISDIR"
|| code === "ENOTDIR"
|| message.startsWith("unsafe SQLite lock path:")
|| message.startsWith("SQLite lock path identity changed:");
}
private openStableProfileLockFile(): StableLockFile {
try {
return this.stableLockOpen(this.context.lockPath);
} catch (error) {
if (this.isExplicitProfileLockStorageUnsafe(error)) throw this.profileLockStorageUnsafe();
throw this.profileLockUnavailable();
}
}
private assertStableProfileLockFile(file: StableLockFile): void {
try {
this.stableLockAssert(this.context.lockPath, file);
} catch (error) {
if (errorCode(error) === "ENOENT" || this.isExplicitProfileLockStorageUnsafe(error)) {
throw this.profileLockStorageUnsafe();
}
throw this.profileLockUnavailable();
}
}
private async withLock<T>(operation: () => Promise<T>): Promise<T> {
assertNoLegacyNativeProfileState(this.context);
assertNativeProfileLockPath(this.context);
const deadline = this.now() + this.lockWaitMs;
let database: Database | undefined;
let lockFile: StableLockFile | undefined;
while (!database) {
let candidate: Database | undefined;
let candidateFile: StableLockFile | undefined;
try {
candidateFile = this.openStableProfileLockFile();
this.assertStableProfileLockFile(candidateFile);
candidate = new Database(this.context.lockPath, { create: true });
const claim = this.uuid();
candidate.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
candidate.exec("CREATE TABLE IF NOT EXISTS ocx_native_profile_lock (singleton INTEGER PRIMARY KEY CHECK (singleton = 1), claim TEXT NOT NULL)");
candidate.query("INSERT INTO ocx_native_profile_lock (singleton, claim) VALUES (1, ?) ON CONFLICT(singleton) DO UPDATE SET claim = excluded.claim").run(claim);
candidate.exec("COMMIT");
candidate.exec("BEGIN IMMEDIATE");
const candidateClaim = candidate.query("SELECT claim FROM ocx_native_profile_lock WHERE singleton = 1").get() as { claim?: unknown } | null;
let verifier: Database | undefined;
let pathClaim: { claim?: unknown } | null = null;
try {
this.assertStableProfileLockFile(candidateFile);
verifier = new Database(this.context.lockPath, { readonly: true });
pathClaim = verifier.query("SELECT claim FROM ocx_native_profile_lock WHERE singleton = 1").get() as { claim?: unknown } | null;
} finally {
try { verifier?.close(); } catch { /* mismatch below is authoritative */ }
}
this.assertStableProfileLockFile(candidateFile);
if (candidateClaim?.claim !== claim || pathClaim?.claim !== claim) {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", "The native-profile transaction lock changed during acquisition.", 409);
}
try { chmodSync(this.context.lockPath, 0o600); } catch { /* Windows ACL below is authoritative there. */ }
await this.hardenPath(this.context.lockPath);
assertNativeProfileLockPath(this.context);
this.assertStableProfileLockFile(candidateFile);
database = candidate;
candidate = undefined;
lockFile = candidateFile;
candidateFile = undefined;
} catch (error) {
let mappedError = error;
if (!(mappedError instanceof NativeProfileError) && candidateFile) {
try { this.assertStableProfileLockFile(candidateFile); }
catch (storageError) { mappedError = storageError; }
}
try { candidate?.exec("ROLLBACK"); } catch { /* acquisition already failed */ }
try { candidate?.close(); } catch { /* acquisition already failed */ }
try { candidateFile?.close(); } catch { /* acquisition already failed */ }
if (mappedError instanceof NativeProfileError) throw mappedError;
if (!this.isLockBusy(mappedError)) {
throw this.profileLockUnavailable();
}
if (this.now() >= deadline) {
throw new NativeProfileError("NATIVE_PROFILE_BUSY", "Another native-profile operation is still running.", 503, true);
}
await this.sleep(50);
}
}
try {
this.activeLockFile = lockFile ?? null;
this.activeRootIdentity = await this.ensureRoot();
await this.onLockAcquired();
this.assertOperationStorageStable();
const result = await operation();
this.assertOperationStorageStable();
return result;
} finally {
try { database.exec("ROLLBACK"); } catch { /* close still releases the OS-backed lock */ }
try { database.close(); } catch { /* transaction is already ending */ }
try { lockFile?.close(); } catch { /* SQLite handle already released the transaction */ }
this.activeRootIdentity = null;
this.activeLockFile = null;
}
}
private assertOperationStorageStable(): void {
if (!this.activeRootIdentity || !this.activeLockFile) {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", "Native-profile storage ownership is not active.", 409);
}
this.assertStableProfileLockFile(this.activeLockFile);
assertPathIdentity(this.context.rootDir, this.activeRootIdentity, "The native-profile metadata root");
assertNativeProfileMetadataLayout(this.context);
}
private async assertNativeCodexStopped(confirmedStopped: boolean): Promise<void> {
const processState = await this.processProbe();
if (processState.status === "busy") {
throw new NativeProfileError("CODEX_BUSY", `Close the ${processState.count} detected native Codex process(es) before switching.`, 409);
}
if (processState.status === "unknown" && !confirmedStopped) {
throw new NativeProfileError("CODEX_PROCESS_CHECK_UNAVAILABLE", "Codex process state could not be confirmed; close Codex and retry with explicit confirmation.", 409);
}
}
private async keyForVault(vault: NativeMainProfileVaultV1 | null): Promise<NativeProfileKey> {
const existing = await this.keyProvider.get(this.context.homeId);
if (existing) return existing;
if (vault) {
throw new NativeProfileError("KEYRING_KEY_MISSING", "The OS credential-store key for this vault is missing.", 409);
}
return this.keyProvider.create(this.context.homeId);
}
private async writeVault(vault: NativeMainProfileVaultV1): Promise<void> {
this.assertOperationStorageStable();
await this.atomicWrite(this.context.vaultPath, serializeNativeProfileMetadata(vault));
this.assertOperationStorageStable();
}
private async writeJournal(journal: NativeProfileSwitchJournalV1): Promise<void> {
this.assertOperationStorageStable();
await this.atomicWrite(this.context.journalPath, serializeNativeProfileJournal(journal));
this.assertOperationStorageStable();
}
private removeJournal(): void {
this.assertOperationStorageStable();
try { publishCredentialSync(() => unlinkSync(this.context.journalPath)); } catch (error) { if (errorCode(error) !== "ENOENT") throw error; }
}
private removeRecoveryBlock(): void {
this.assertOperationStorageStable();
try { publishCredentialSync(() => unlinkSync(this.context.recoveryBlockPath)); } catch (error) { if (errorCode(error) !== "ENOENT") throw error; }
}
private async currentOwnershipConfirmed(): Promise<boolean> {
let key: NativeProfileKey | null = null;
let current: NativeEnvelopeSnapshot | null = null;
try {
const vault = this.readVault();
if (!vault) return false;
key = await this.keyForVault(vault);
current = this.readEnvelope(this.context.authPath);
this.assertCurrentIdentity(vault, current, key);
return true;
} catch {
return false;
} finally {
current?.raw.fill(0);
key?.key.fill(0);
}
}
private async clearRecoveryBlockLocked(): Promise<Record<string, unknown>> {
if (!(await this.currentOwnershipConfirmed())) {
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"The quarantined recovery state remains blocked until auth.json matches the active encrypted profile.",
409,
);
}
this.removeRecoveryBlock();
return {
ok: true,
recovered: true,
action: "confirm-current-owner",
externallyRefreshed: false,
effectiveCodexHome: this.context.codexHome,
restartRequired: false,
};
}
private async quarantineInvalidJournalLocked(): Promise<Record<string, unknown>> {
const quarantineFile = this.context.homeId + ".journal.quarantine-" + this.uuid() + ".json";
const quarantinePath = join(this.context.rootDir, quarantineFile);
this.assertOperationStorageStable();
await this.atomicWrite(this.context.recoveryBlockPath, serializeNativeProfileMetadata({
version: 1,
homeId: this.context.homeId,
reason: "malformed-journal",
quarantineFile,
createdAt: new Date(this.now()).toISOString(),
}));
this.assertOperationStorageStable();
try {
publishCredentialSync(() => renameSync(this.context.journalPath, quarantinePath));
await this.hardenPath(quarantinePath);
this.assertOperationStorageStable();
} catch {
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"The invalid recovery journal could not be quarantined; the fail-closed recovery marker remains active.",
409,
);
}
if (!(await this.currentOwnershipConfirmed())) {
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"The invalid recovery journal was quarantined as " + quarantineFile + ", but current credential ownership is not confirmed.",
409,
);
}
this.removeRecoveryBlock();
return {
ok: true,
recovered: true,
action: "quarantine-invalid-journal",
quarantineFile,
externallyRefreshed: false,
effectiveCodexHome: this.context.codexHome,
restartRequired: false,
};
}
private assertNoPendingRecovery(): void {
if (probeNativeProfileRecoveryState(this.context) === "none") return;
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"A native-profile recovery journal is pending. Run `ocx account main recover` or `ocx account main recover --rollback --yes` before registering or adding profiles.",
409,
);
}
private requireVault(): NativeMainProfileVaultV1 {
const vault = this.readVault();
if (!vault) throw new NativeProfileError("PROFILE_NOT_FOUND", "Register the current native login before adding or switching profiles.", 404);
return vault;
}
private currentProfile(vault: NativeMainProfileVaultV1): NativeMainProfileRecordV1 {
const profile = vault.profiles.find(item => item.id === vault.activeProfileId && item.state === "active");
if (!profile) throw new NativeProfileError("VAULT_INVALID", "The native-profile vault has no active owner.", 409);
return profile;
}
private assertCurrentIdentity(vault: NativeMainProfileVaultV1, envelope: NativeEnvelopeSnapshot, key: NativeProfileKey): NativeMainProfileRecordV1 {
const active = this.currentProfile(vault);
if (nativeIdentityHash(key.key, envelope.accountId) !== active.identityHash) {
throw new NativeProfileError(
"ACTIVE_PROFILE_MISMATCH",
"The physical native login changed outside OpenCodex; recover or register the expected login before continuing.",
409,
);
}
return active;
}
async register(labelInput: string): Promise<{ effectiveCodexHome: string; profile: NativeProfilePublic }> {
return this.withLock(async () => {
this.assertNoPendingRecovery();
requireFileCredentialStore(this.context);
const label = validateNativeProfileLabel(labelInput);
let envelope: NativeEnvelopeSnapshot | null = null;
let key: NativeProfileKey | null = null;
try {
envelope = this.readEnvelope(this.context.authPath);
let vault = this.readVault();
key = await this.keyForVault(vault);
const identityHash = nativeIdentityHash(key.key, envelope.accountId);
const timestamp = new Date(this.now()).toISOString();
if (!vault) {
const id = this.uuid();
assertUniqueNativeProfileLabel({ profiles: [] }, label, undefined, [id]);
vault = {
version: 1,
revision: 1,
homeId: this.context.homeId,
activeProfileId: id,
profiles: [{
id,
label,
identityHash,
identityHint: nativeIdentityHint(identityHash),
state: "active",
payload: null,
createdAt: timestamp,
updatedAt: timestamp,
}],
};
} else {
const active = this.assertCurrentIdentity(vault, envelope, key);
assertUniqueNativeProfileLabel(vault, label, active.id);
active.label = label;
active.updatedAt = timestamp;
vault.revision += 1;
}
await this.writeVault(vault);
return { effectiveCodexHome: this.context.codexHome, profile: publicNativeProfile(this.currentProfile(vault)) };
} finally {
envelope?.raw.fill(0);
key?.key.fill(0);
}
});
}
async list(): Promise<NativeProfileListResult> {
const vault = readNativeProfileVault(this.context);
return {
effectiveCodexHome: this.context.codexHome,
activeProfileId: vault?.activeProfileId ?? null,
profiles: vault?.profiles.map(publicNativeProfile) ?? [],
};
}
async doctor(): Promise<Record<string, unknown>> {
return this.withLock(async () => {
let stagingSweep: "ok" | "cleanup-required" | "unreadable" = "ok";
try {
const sweep = await this.sweepStagesLocked();
if (sweep.cleanupFailed > 0) stagingSweep = "cleanup-required";
} catch (error) {
stagingSweep = error instanceof NativeProfileError && error.code === "STAGING_CLEANUP_REQUIRED"
? "cleanup-required"
: "unreadable";
}
const mode = (() => {
try { return resolveNativeCredentialStoreMode(this.context); } catch { return "unknown"; }
})();
const auth = this.readEnvelopeResult(this.context.authPath);
try {
let vault: NativeMainProfileVaultV1 | null = null;
let vaultStatus: "ok" | "missing" | "invalid" = "missing";
try {
vault = this.readVault();
vaultStatus = vault ? "ok" : "missing";
} catch {
vaultStatus = "invalid";
}
let keyStore: "available" | "missing-key" | "unavailable" = "available";
try {
const key = await this.keyProvider.get(this.context.homeId);
if (vaultStatus !== "missing" && !key) keyStore = "missing-key";
if (key) key.key.fill(0);
} catch {
keyStore = "unavailable";
}
let stagingCount: number | null = 0;
try {
stagingCount = this.stageStore.records().length;
if (existsSync(this.context.stagingRoot)) stagingCount += Array.from(new Bun.Glob("*").scanSync({ cwd: this.context.stagingRoot, onlyFiles: false })).filter(name => !UUID_RE.test(name) || !this.stageStore.recordForStage(name)).length;
} catch {
stagingSweep = "unreadable";
stagingCount = null;
}
return {
effectiveCodexHome: this.context.codexHome,
credentialStoreMode: mode,
supported: mode === "file",
authStatus: auth.status,
keyStore,
vaultStatus,
profileCount: vaultStatus === "invalid" ? null : vault?.profiles.length ?? 0,
activeProfileId: vault?.activeProfileId ?? null,
recoveryPending: probeNativeProfileRecoveryState(this.context) !== "none",
recoveryState: probeNativeProfileRecoveryState(this.context),
stagingSweep,
stagingCount,
};
} finally {
if (auth.status === "ok") auth.envelope.raw.fill(0);
}
});
}
private stagePath(stageId: string): string {
if (!UUID_RE.test(stageId)) throw new NativeProfileError("INVALID_REQUEST", "The staging identifier is invalid.", 400);
return join(this.context.stagingRoot, stageId);
}
private assertStagingLayout(requireRoot = false): void {
if (!existsSync(this.context.configDir)) {
if (requireRoot) throw new NativeProfileError("STAGING_NOT_FOUND", "The native-login staging root is missing.", 404);
return;
}
const configDir = assertSafeDirectory(this.context.configDir, "The OpenCodex configuration root");
const stagingBase = dirname(this.context.stagingRoot);
if (!samePath(stagingBase, join(configDir, "native-main-profile-staging"))) {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", "The native-login staging root escaped OPENCODEX_HOME.", 409);
}
if (!existsSync(stagingBase)) {
if (requireRoot) throw new NativeProfileError("STAGING_NOT_FOUND", "The native-login staging root is missing.", 404);
return;
}
const canonicalBase = assertSafeDirectory(stagingBase, "The native-login staging namespace");
if (!samePath(dirname(this.context.stagingRoot), canonicalBase)) {
throw new NativeProfileError("PROFILE_STORAGE_UNSAFE", "The native-login staging root is not contained by OPENCODEX_HOME.", 409);
}
if (!existsSync(this.context.stagingRoot)) {
if (requireRoot) throw new NativeProfileError("STAGING_NOT_FOUND", "The native-login staging root is missing.", 404);
return;
}
assertSafeDirectory(this.context.stagingRoot, "The native-login staging root");
}
private async ensureStagingRoot(): Promise<void> {
if (!existsSync(this.context.configDir)) mkdirSync(this.context.configDir, { recursive: true, mode: 0o700 });
this.assertStagingLayout(false);
const stagingBase = dirname(this.context.stagingRoot);
if (!existsSync(stagingBase)) mkdirSync(stagingBase, { mode: 0o700 });
assertSafeDirectory(stagingBase, "The native-login staging namespace");
await this.hardenPath(stagingBase);
if (!existsSync(this.context.stagingRoot)) mkdirSync(this.context.stagingRoot, { mode: 0o700 });
assertSafeDirectory(this.context.stagingRoot, "The native-login staging root");
await this.hardenPath(this.context.stagingRoot);
this.assertStagingLayout(true);
}
private deleteStage(path: string, identity?: PathIdentity): void {
if (identity) assertPathIdentity(path, identity, "The native-login staging directory");
const authPath = join(path, "auth.json");
let authFd: number | undefined;
try {
const flags = process.platform === "win32"
? fsConstants.O_RDWR
: fsConstants.O_RDWR | fsConstants.O_NOFOLLOW;
authFd = openSync(authPath, flags);
const opened = fstatSync(authFd, { bigint: true });
const pathEntry = lstatSync(authPath, { bigint: true });
if (
!opened.isFile()
|| !pathEntry.isFile()
|| pathEntry.isSymbolicLink()
|| opened.dev !== pathEntry.dev
|| opened.ino !== pathEntry.ino
|| opened.nlink !== 1n
) throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"The staged credential file is not privately owned; plaintext may remain and requires manual cleanup.",
500,
false,
true,
true,
);
publishCredentialSync(() => unlinkSync(authPath));
const unlinked = fstatSync(authFd, { bigint: true });
if (unlinked.dev !== opened.dev || unlinked.ino !== opened.ino || unlinked.nlink !== 0n) {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"The staged credential file could not be exclusively unlinked; plaintext may remain and requires manual cleanup.",
500,
false,
true,
true,
);
}
ftruncateSync(authFd, 0);
} catch (error) {
if (error instanceof NativeProfileError) throw error;
if (errorCode(error) !== "ENOENT") {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"The staged credential file could not be securely scrubbed; plaintext may remain and requires manual cleanup.",
500,
false,
true,
true,
);
}
} finally {
try { if (authFd !== undefined) closeSync(authFd); } catch { /* removal below remains required */ }
}
if (identity) assertPathIdentity(path, identity, "The native-login staging directory");
publishCredentialSync(() => this.removeStageTree(path));
}
private deleteLegacyStageById(stageId: string, requirePresent = false): void {
this.assertStagingLayout(true);
const expected = resolve(this.stagePath(stageId));
let stageStat: ReturnType<typeof lstatSync>;
try { stageStat = lstatSync(expected); } catch (error) {
if (errorCode(error) === "ENOENT") {
if (requirePresent) throw new NativeProfileError("STAGING_NOT_FOUND", "The native-login staging session is missing.", 404);
return;
}
throw error;
}
if (stageStat.isSymbolicLink() || !stageStat.isDirectory()) {
throw new NativeProfileError(
"PROFILE_STORAGE_UNSAFE",
"The native-login staging path is not a private directory.",
409,
false,
true,
true,
);
}
const canonicalRoot = resolve(realpathSync.native(this.context.stagingRoot));
const canonicalExpected = resolve(realpathSync.native(expected));
const rel = relative(canonicalRoot, canonicalExpected);
if (!rel || rel.startsWith("..") || rel.includes(sep)) {
throw new NativeProfileError("STAGING_CLEANUP_REQUIRED", "The staging path could not be safely removed.", 500, false, true, true);
}
this.deleteStage(canonicalExpected, pathIdentity(canonicalExpected));
}
private async cleanupRegisteredStage(
proof: NativeStageProof,
outcome: Exclude<NativeStageTerminalOutcome, null>,
): Promise<NativeStageCleanupResult> {
let stageRemoved = false;
let plaintextMayRemain = true;
try {
this.deleteStage(proof.path, proof.identity);
stageRemoved = true;
plaintextMayRemain = false;
} catch (error) {
plaintextMayRemain = error instanceof NativeProfileError
? error.plaintextMayRemain !== false
: false;
}
if (stageRemoved) {
try {
await this.stageStore.remove(proof);
return { removed: true, plaintextMayRemain: false };
} catch {
try { await this.stageStore.markCleanupRequired(proof, outcome); } catch { /* the cleanup result remains authoritative */ }
return { removed: false, plaintextMayRemain: false };
}
}
try { await this.stageStore.markCleanupRequired(proof, outcome); } catch { /* preserve the plaintext signal */ }
return { removed: false, plaintextMayRemain };
}
private async sweepStagesLocked(): Promise<NativeStageSweepResult> {
let removed = 0;
let live = 0;
let cleanupFailed = 0;
let plaintextMayRemain = false;
const records = this.stageStore.records();
const registeredHere = new Set(
records
.filter(record => samePath(record.stagingRoot, this.context.stagingRoot))
.map(record => record.stageId),
);
for (const record of records) {
if (record.state === "open" && this.now() <= record.leaseExpiresAt) {
live += 1;
continue;
}
const outcome = record.terminalOutcome
?? (record.state === "creating" ? "cancelled" : "expired");
let proof: NativeStageProof | null;
try {
proof = this.stageStore.proofForRecord(record, record.state === "creating");
} catch {
cleanupFailed += 1;
plaintextMayRemain = true;
try {
await this.stageStore.markCleanupRequired({ record }, outcome);
} catch { /* fail closed and report the unresolved plaintext boundary */ }
continue;
}
if (!proof) {
try {
await this.stageStore.remove({ record });
removed += 1;
} catch {
cleanupFailed += 1;
}
continue;
}
const cleanup = await this.cleanupRegisteredStage(proof, outcome);
if (cleanup.removed) removed += 1;
else cleanupFailed += 1;
plaintextMayRemain ||= cleanup.plaintextMayRemain;
}
if (existsSync(this.context.stagingRoot)) {
this.assertStagingLayout(true);
for (const name of readdirSync(this.context.stagingRoot)) {
if (!UUID_RE.test(name) || registeredHere.has(name)) continue;
const path = this.stagePath(name);
let createdAt: number;
try {
const entry = lstatSync(path);
if (!entry.isDirectory() || entry.isSymbolicLink()) {
cleanupFailed += 1;
plaintextMayRemain = true;
continue;
}
createdAt = entry.mtimeMs;
try {
const metadata = JSON.parse(readFileSync(join(path, "stage.json"), "utf8")) as Record<string, unknown>;
if (typeof metadata.createdAt === "number") createdAt = metadata.createdAt;
} catch { /* mtime bounds legacy crash residue */ }
} catch (error) {
if (errorCode(error) === "ENOENT") continue;
cleanupFailed += 1;
plaintextMayRemain = true;
continue;
}
if (this.now() - createdAt <= LEGACY_STAGE_MAX_AGE_MS) {
live += 1;
continue;
}
try {
this.deleteLegacyStageById(name);
removed += 1;
} catch (error) {
cleanupFailed += 1;
plaintextMayRemain ||= error instanceof NativeProfileError
? error.plaintextMayRemain !== false
: true;
}
}
}
return { removed, live, cleanupFailed, plaintextMayRemain };
}
/**
* Whether startup or the periodic cleaner has any stage state to inspect.
*
* Absence is the only lock-free result. Any entry or observation failure
* keeps the existing fail-closed sweep, so an unsafe/unreadable stage path
* can never be mistaken for an unused profile subsystem.
*/
stageSweepRequired(): boolean {
for (const path of [this.context.stageRegistryPath, this.context.stagingRoot]) {
try {
lstatSync(path);
return true;
} catch (error) {
if (errorCode(error) !== "ENOENT") return true;
}
}
return false;
}
async sweepStages(): Promise<NativeStageSweepResult> {
return this.withLock(() => this.sweepStagesLocked());
}
async prepareStage(): Promise<{
stageId: string;
writerToken: string;
stagingCodexHome: string;
effectiveCodexHome: string;
leaseExpiresAt: number;
heartbeatIntervalMs: number;
}> {
return this.withLock(async () => {
this.assertNoPendingRecovery();
const sweep = await this.sweepStagesLocked();
if (sweep.plaintextMayRemain) {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"An expired native-login staging session could not be securely removed.",
500,
true,
true,
true,
);
}
requireFileCredentialStore(this.context);
const vault = this.requireVault();
let key: NativeProfileKey | null = null;
let current: NativeEnvelopeSnapshot | null = null;
let reservation: Awaited<ReturnType<NativeProfileStageStore["reserve"]>> | null = null;
try {
key = await this.keyForVault(vault);
current = this.readEnvelope(this.context.authPath);
this.assertCurrentIdentity(vault, current, key);
await this.ensureStagingRoot();
reservation = await this.stageStore.reserve(this.context.stagingRoot);
mkdirSync(reservation.stagingCodexHome, { mode: 0o700 });
await this.hardenPath(reservation.stagingCodexHome);
writeFileSync(join(reservation.stagingCodexHome, "config.toml"), 'cli_auth_credentials_store = "file"\n', { mode: 0o600 });
await this.hardenPath(join(reservation.stagingCodexHome, "config.toml"));
writeFileSync(join(reservation.stagingCodexHome, "stage.json"), `${JSON.stringify({
version: 2,
stageId: reservation.stageId,
leaseId: reservation.leaseId,
homeId: this.context.homeId,
createdAt: this.now(),
}, null, 2)}\n`, { mode: 0o600 });
await this.hardenPath(join(reservation.stagingCodexHome, "stage.json"));
await this.stageStore.activate(reservation);
return {
stageId: reservation.stageId,
writerToken: reservation.writerToken,
stagingCodexHome: reservation.stagingCodexHome,
effectiveCodexHome: this.context.codexHome,
leaseExpiresAt: reservation.leaseExpiresAt,
heartbeatIntervalMs: NATIVE_STAGE_HEARTBEAT_INTERVAL_MS,
};
} catch (error) {
let plaintextMayRemain = false;
if (reservation) {
const record = this.stageStore.recordForStage(reservation.stageId);
if (record) {
try {
const proof = this.stageStore.proofForRecord(record, true);
if (proof) {
const cleanup = await this.cleanupRegisteredStage(proof, "cancelled");
plaintextMayRemain = cleanup.plaintextMayRemain;
} else {
await this.stageStore.remove({ record });
}
} catch {
plaintextMayRemain = true;
}
}
}
if (error instanceof NativeProfileError) {
throw new NativeProfileError(
error.code,
error.message,
error.status,
error.retryable,
plaintextMayRemain || error.cleanupRequired === true ? true : undefined,
plaintextMayRemain || error.plaintextMayRemain === true,
);
}
if (plaintextMayRemain) {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"Native-login staging failed and plaintext may remain.",
500,
false,
true,
true,
);
}
throw error;
} finally {
current?.raw.fill(0);
key?.key.fill(0);
}
});
}
async heartbeatStage(stageId: string, writerToken: string): Promise<{ ok: true; leaseExpiresAt: number }> {
return this.withLock(async () => {
const proof = this.stageStore.verify(stageId, writerToken);
if (proof.expired) {
const cleanup = await this.cleanupRegisteredStage(proof, "expired");
throw new NativeProfileError(
"STAGING_EXPIRED",
"The native-login staging lease expired.",
410,
false,
cleanup.removed ? undefined : true,
cleanup.plaintextMayRemain,
);
}
const leaseExpiresAt = await this.stageStore.heartbeat(proof);
return { ok: true, leaseExpiresAt };
});
}
async finishStage(
stageId: string,
writerToken: string,
labelInput: string,
): Promise<{ effectiveCodexHome: string; profile: NativeProfilePublic; plaintextMayRemain: false }> {
return this.withLock(async () => {
const ownedStage = this.stageStore.verify(stageId, writerToken);
if (ownedStage.expired) {
const cleanup = await this.cleanupRegisteredStage(ownedStage, "expired");
throw new NativeProfileError(
"STAGING_EXPIRED",
"The native-login staging lease expired.",
410,
false,
cleanup.removed ? undefined : true,
cleanup.plaintextMayRemain,
);
}
let target: NativeEnvelopeSnapshot | null = null;
let current: NativeEnvelopeSnapshot | null = null;
let key: NativeProfileKey | null = null;
let operationFailed = false;
let operationError: unknown;
let importCommitted = false;
let result: { effectiveCodexHome: string; profile: NativeProfilePublic; plaintextMayRemain: false } | undefined;
try {
this.assertNoPendingRecovery();
requireFileCredentialStore(this.context);
const label = validateNativeProfileLabel(labelInput);
target = readNativeEnvelope(join(ownedStage.path, "auth.json"));
assertPathIdentity(ownedStage.path, ownedStage.identity, "The native-login staging directory");
current = readNativeEnvelope(this.context.authPath);
const vault = this.requireVault();
if (vault.profiles.length >= MAX_NATIVE_PROFILES) {
throw new NativeProfileError("INVALID_REQUEST", "Native profiles are limited to 32 entries.", 400);
}
key = await this.keyForVault(vault);
this.assertCurrentIdentity(vault, current, key);
const id = this.uuid();
assertUniqueNativeProfileLabel(vault, label, undefined, [id]);
const identityHash = nativeIdentityHash(key.key, target.accountId);
if (vault.profiles.some(profile => profile.identityHash === identityHash)) {
throw new NativeProfileError("PROFILE_ALREADY_EXISTS", "That native identity is already registered.", 409);
}
const timestamp = new Date(this.now()).toISOString();
const currentProfile = this.currentProfile(vault);
const currentSourcePayload = encryptNativeEnvelope(
this.context,
currentProfile.id,
currentProfile.identityHash,
current,
key,
);
const profile: NativeMainProfileRecordV1 = {
id,
label,
identityHash,
identityHint: nativeIdentityHint(identityHash),
state: "inactive",
payload: encryptNativeEnvelope(this.context, id, identityHash, target, key),
createdAt: timestamp,
updatedAt: timestamp,
};
const prospectiveVault = structuredClone(vault);
prospectiveVault.profiles.push(profile);
prospectiveVault.revision += 1;
const currentActivePreflight = structuredClone(prospectiveVault);
currentActivePreflight.revision = Number.MAX_SAFE_INTEGER;
serializeNativeProfileMetadata(currentActivePreflight);
for (const inactiveProfile of prospectiveVault.profiles.filter(item => item.state === "inactive")) {
const activePlacement = structuredClone(prospectiveVault);
activePlacement.revision = Number.MAX_SAFE_INTEGER;
const nextCurrent = activePlacement.profiles.find(item => item.id === currentProfile.id)!;
const nextActive = activePlacement.profiles.find(item => item.id === inactiveProfile.id)!;
nextCurrent.state = "inactive";
nextCurrent.payload = currentSourcePayload;
nextActive.state = "active";
nextActive.payload = null;
activePlacement.activeProfileId = nextActive.id;
serializeNativeProfileMetadata(activePlacement);
}
await this.writeVault(prospectiveVault);
importCommitted = true;
result = {
effectiveCodexHome: this.context.codexHome,
profile: publicNativeProfile(profile),
plaintextMayRemain: false,
};
} catch (error) {
operationFailed = true;
operationError = error;
} finally {
target?.raw.fill(0);
current?.raw.fill(0);
key?.key.fill(0);
}
const cleanup = await this.cleanupRegisteredStage(
ownedStage,
importCommitted ? "imported" : "rejected",
);
if (operationFailed) {
if (operationError instanceof NativeProfileError) {
throw new NativeProfileError(
operationError.code,
operationError.message,
operationError.status,
operationError.retryable,
cleanup.removed ? operationError.cleanupRequired : true,
cleanup.plaintextMayRemain,
);
}
throw new NativeProfileError(
"INTERNAL_ERROR",
cleanup.removed
? "The native profile import failed."
: "The native profile import failed and its staging session could not be securely removed.",
500,
false,
cleanup.removed ? undefined : true,
cleanup.plaintextMayRemain,
);
}
if (!cleanup.removed) {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
importCommitted
? "The native profile was imported, but its staging session could not be securely removed. Do not retry the import; cancel it explicitly."
: "The native-login staging session could not be securely removed; cancel it explicitly.",
500,
false,
importCommitted ? undefined : true,
cleanup.plaintextMayRemain,
);
}
return result!;
});
}
async cancelStage(stageId: string, writerToken: string): Promise<NativeStageCleanupResult> {
return this.withLock(async () => {
const proof = this.stageStore.verify(stageId, writerToken, true, true);
const outcome = proof.record.terminalOutcome ?? "cancelled";
const cleanup = await this.cleanupRegisteredStage(proof, outcome);
if (!cleanup.removed) {
throw new NativeProfileError(
"STAGING_CLEANUP_REQUIRED",
"The native-login staging session could not be securely removed.",
500,
true,
true,
cleanup.plaintextMayRemain,
);
}
return cleanup;
});
}
private resolveTarget(vault: NativeMainProfileVaultV1, target: string): NativeMainProfileRecordV1 {
const selectors = new Map<string, NativeMainProfileRecordV1>();
for (const item of vault.profiles) {
for (const selector of [item.id, item.label]) {
const key = nativeProfileSelectorKey(selector);
if (selectors.has(key)) {
throw new NativeProfileError(
"VAULT_INVALID",
"The native-profile vault contains an ambiguous ID or label selector.",
409,
);
}
selectors.set(key, item);
}
}
const profile = selectors.get(nativeProfileSelectorKey(target));
if (!profile) throw new NativeProfileError("PROFILE_NOT_FOUND", "The requested native profile does not exist.", 404);
if (profile.state !== "inactive" || !profile.payload) {
throw new NativeProfileError("INVALID_REQUEST", "The requested native profile is already active.", 400);
}
return profile;
}
private verifyWrittenEnvelope(expectedDigest: string, expectedIdentityHash: string, key: NativeProfileKey): NativeEnvelopeSnapshot {
const observed = this.readEnvelope(this.context.authPath);
try {
if (observed.digest !== expectedDigest || nativeIdentityHash(key.key, observed.accountId) !== expectedIdentityHash) {
throw new Error("auth read-back mismatch");
}
return observed;
} catch (error) {
observed.raw.fill(0);
throw error;
}
}
async switch(targetSelector: string, confirmedStopped = false): Promise<Record<string, unknown>> {
return this.withLock(async () => {
await this.sweepStagesLocked();
requireFileCredentialStore(this.context);
await this.assertNativeCodexStopped(confirmedStopped);
if (probeNativeProfileRecoveryState(this.context) !== "none") await this.recoverLocked(false);
const beforeVault = this.requireVault();
let key: NativeProfileKey | null = null;
let source: NativeEnvelopeSnapshot | null = null;
let target: NativeEnvelopeSnapshot | null = null;
let journalPrepared = false;
let committed = false;
try {
key = await this.keyForVault(beforeVault);
source = this.readEnvelope(this.context.authPath);
const sourceProfile = this.assertCurrentIdentity(beforeVault, source, key);
const targetProfile = this.resolveTarget(beforeVault, targetSelector);
target = decryptNativeEnvelope(this.context, targetProfile.id, targetProfile.identityHash, targetProfile.payload!, key);
if (nativeIdentityHash(key.key, target.accountId) !== targetProfile.identityHash) {
throw new NativeProfileError("PROFILE_DECRYPT_FAILED", "The selected native profile identity does not match its encrypted record.", 409);
}
const timestamp = new Date(this.now()).toISOString();
const sourcePayload = encryptNativeEnvelope(this.context, sourceProfile.id, sourceProfile.identityHash, source, key);
const afterVault = structuredClone(beforeVault);
const nextSource = afterVault.profiles.find(profile => profile.id === sourceProfile.id)!;
const nextTarget = afterVault.profiles.find(profile => profile.id === targetProfile.id)!;
nextSource.state = "inactive";
nextSource.payload = sourcePayload;
nextSource.updatedAt = timestamp;
nextTarget.state = "active";
nextTarget.payload = null;
nextTarget.updatedAt = timestamp;
afterVault.activeProfileId = nextTarget.id;
afterVault.revision += 1;
const journal: NativeProfileSwitchJournalV1 = {
version: 1,
transactionId: this.uuid(),
homeId: this.context.homeId,
phase: "prepared",
sourceProfileId: sourceProfile.id,
sourceIdentityHash: sourceProfile.identityHash,
sourcePayload,
targetProfileId: targetProfile.id,
targetIdentityHash: targetProfile.identityHash,
targetPayload: targetProfile.payload!,
beforeVault: structuredClone(beforeVault),
afterVault,
createdAt: timestamp,
};
serializeNativeProfileMetadata(afterVault);
serializeNativeProfileJournal({ ...journal, phase: "prepared" });
serializeNativeProfileJournal({ ...journal, phase: "auth-replaced" });
serializeNativeProfileJournal({ ...journal, phase: "vault-committed" });
await this.writeJournal(journal);
journalPrepared = true;
await this.onSwitchBoundary("journal-prepared");
this.assertOperationStorageStable();
await writeNativeMainAuthFileAsync(this.context.authPath, target.text, this.atomicWrite);
const observedTarget = this.verifyWrittenEnvelope(target.digest, targetProfile.identityHash, key);
observedTarget.raw.fill(0);
advanceCodexCredentialMutationEpoch();
await this.onSwitchBoundary("auth-replaced");
journal.phase = "auth-replaced";
await this.writeJournal(journal);
await this.writeVault(afterVault);
committed = true;
await this.onSwitchBoundary("vault-committed");
journal.phase = "vault-committed";
await this.writeJournal(journal);
this.applyTransition(source.accountId, target.accountId);
await this.onSwitchBoundary("runtime-transition-published");
this.removeJournal();
await this.onSwitchBoundary("journal-deleted");
return {
ok: true,
effectiveCodexHome: this.context.codexHome,
activeProfile: publicNativeProfile(nextTarget),
restartRequired: true,
};
} catch (cause) {
if (!journalPrepared) throw cause;
if (committed) {
throw new NativeProfileError("RECOVERY_REQUIRED", "The login changed, but final transaction cleanup requires recovery.", 409);
}
try {
this.assertOperationStorageStable();
await writeNativeMainAuthFileAsync(this.context.authPath, source!.text, this.atomicWrite);
const restored = this.verifyWrittenEnvelope(source!.digest, nativeIdentityHash(key!.key, source!.accountId), key!);
restored.raw.fill(0);
advanceCodexCredentialMutationEpoch();
await this.writeVault(beforeVault);
this.removeJournal();
} catch {
throw new NativeProfileError(
"AUTH_RESTORE_FAILED",
"The original native login could not be verified after rollback; the encrypted recovery journal was retained.",
500,
);
}
throw new NativeProfileError("SWITCH_ROLLED_BACK", "The native-login switch failed and the exact original login was restored.", 409);
} finally {
source?.raw.fill(0);
target?.raw.fill(0);
key?.key.fill(0);
}
});
}
private async recoverLocked(rollback: boolean): Promise<Record<string, unknown>> {
const inspection = inspectNativeProfileJournal(this.context);
const recoveryState = probeNativeProfileRecoveryState(this.context);
if (inspection.status === "invalid" || recoveryState === "unreadable") {
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"The native-profile recovery state is invalid and requires explicit confirmed rollback quarantine.",
409,
);
}
if (recoveryState === "manual") {
if (inspection.status !== "missing") {
throw new NativeProfileError("RECOVERY_REQUIRED", "Manual native-profile recovery remains pending.", 409);
}
return this.clearRecoveryBlockLocked();
}
const journal = inspection.status === "valid" ? inspection.journal : null;
if (!journal) {
return {
ok: true,
recovered: false,
externallyRefreshed: false,
effectiveCodexHome: this.context.codexHome,
};
}
let key: NativeProfileKey | null = null;
let current: ReturnType<typeof readNativeEnvelopeResult> | null = null;
let sourceEnvelope: NativeEnvelopeSnapshot | null = null;
try {
key = await this.keyForVault(journal.beforeVault);
current = readNativeEnvelopeResult(this.context.authPath);
if (current.status !== "ok") {
throw new NativeProfileError("RECOVERY_REQUIRED", "Recovery stopped because the current native login is not readable and confirmed.", 409);
}
const currentHash = nativeIdentityHash(key.key, current.envelope.accountId);
if (rollback) {
if (currentHash === journal.sourceIdentityHash) {
await this.writeVault(journal.beforeVault);
this.removeJournal();
return {
ok: true,
recovered: true,
action: "rollback-source",
externallyRefreshed: current.envelope.digest !== journal.sourcePayload.envelopeSha256,
effectiveCodexHome: this.context.codexHome,
restartRequired: false,
};
}
if (currentHash !== journal.targetIdentityHash) {
throw new NativeProfileError("RECOVERY_REQUIRED", "Recovery found a third or unknown native identity and made no credential write.", 409);
}
sourceEnvelope = decryptNativeEnvelope(
this.context,
journal.sourceProfileId,
journal.sourceIdentityHash,
journal.sourcePayload,
key,
);
let rollbackVault = journal.beforeVault;
const externallyRefreshed = current.envelope.digest !== journal.targetPayload.envelopeSha256;
let rollbackVaultPublished = false;
if (current.envelope.digest !== journal.targetPayload.envelopeSha256) {
rollbackVault = structuredClone(journal.beforeVault);
const targetProfile = rollbackVault.profiles.find(profile =>
profile.id === journal.targetProfileId
&& profile.identityHash === journal.targetIdentityHash
&& profile.state === "inactive"
);
if (!targetProfile) {
throw new NativeProfileError(
"VAULT_INVALID",
"Recovery could not preserve the refreshed target login in its inactive profile and made no credential write.",
409,
);
}
const refreshedTargetPayload = encryptNativeEnvelope(
this.context,
targetProfile.id,
targetProfile.identityHash,
current.envelope,
key,
);
targetProfile.payload = refreshedTargetPayload;
targetProfile.updatedAt = new Date(this.now()).toISOString();
rollbackVault.revision += 1;
const preservedJournal = structuredClone(journal);
preservedJournal.targetPayload = refreshedTargetPayload;
preservedJournal.beforeVault = structuredClone(rollbackVault);
await this.writeJournal(preservedJournal);
await this.writeVault(rollbackVault);
rollbackVaultPublished = true;
}
this.assertOperationStorageStable();
await writeNativeMainAuthFileAsync(this.context.authPath, sourceEnvelope.text, this.atomicWrite);
const restored = this.verifyWrittenEnvelope(sourceEnvelope.digest, journal.sourceIdentityHash, key);
restored.raw.fill(0);
advanceCodexCredentialMutationEpoch();
if (!rollbackVaultPublished) await this.writeVault(rollbackVault);
this.applyTransition(current.envelope.accountId, sourceEnvelope.accountId);
this.removeJournal();
return {
ok: true,
recovered: true,
action: "rollback-source",
externallyRefreshed,
effectiveCodexHome: this.context.codexHome,
restartRequired: true,
};
}
const observation = currentHash === journal.sourceIdentityHash
? { identity: "source" as const, digest: current.envelope.digest === journal.sourcePayload.envelopeSha256 ? "exact" as const : "changed" as const }
: currentHash === journal.targetIdentityHash
? { identity: "target" as const, digest: current.envelope.digest === journal.targetPayload.envelopeSha256 ? "exact" as const : "changed" as const }
: { identity: "other" as const, digest: "unknown" as const };
const decision = decideNativeProfileRecovery(journal.phase, observation);
if (decision.action === "manual-recovery") {
throw new NativeProfileError("RECOVERY_REQUIRED", "Recovery found a third or unknown native identity and made no credential write.", 409);
}
if (decision.action === "rollback-source") {
await this.writeVault(journal.beforeVault);
this.removeJournal();
return {
ok: true,
recovered: true,
action: decision.action,
externallyRefreshed: decision.externallyRefreshed,
effectiveCodexHome: this.context.codexHome,
restartRequired: false,
};
}
sourceEnvelope = decryptNativeEnvelope(
this.context,
journal.sourceProfileId,
journal.sourceIdentityHash,
journal.sourcePayload,
key,
);
await this.writeVault(journal.afterVault);
this.applyTransition(sourceEnvelope.accountId, current.envelope.accountId);
this.removeJournal();
return {
ok: true,
recovered: true,
action: decision.action,
externallyRefreshed: decision.externallyRefreshed,
effectiveCodexHome: this.context.codexHome,
restartRequired: true,
};
} finally {
if (current?.status === "ok") current.envelope.raw.fill(0);
sourceEnvelope?.raw.fill(0);
key?.key.fill(0);
}
}
async recover(rollback = false, confirmedStopped = false): Promise<Record<string, unknown>> {
return this.withLock(async () => {
requireFileCredentialStore(this.context);
const inspection = inspectNativeProfileJournal(this.context);
if (inspection.status === "invalid") {
if (!rollback) {
throw new NativeProfileError(
"RECOVERY_REQUIRED",
"The invalid native-profile recovery journal requires recover --rollback --yes.",
409,
);
}
await this.assertNativeCodexStopped(confirmedStopped);
return this.quarantineInvalidJournalLocked();
}
if (rollback && inspection.status === "valid") {
await this.assertNativeCodexStopped(confirmedStopped);
}
return this.recoverLocked(rollback);
});
}
}