@cortexkit/opencode-antigravity-auth 3.0.3 → 3.0.5

package/src/common-auth-embedded/claustrum/enrollment.js

@@ -4,6 +4,7 @@ import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, } from 'n
 import { basename, dirname, extname, isAbsolute, join, resolve, } from 'node:path';
 import { ClaustrumCredentialError, ClaustrumClient as ClaustrumWireClient, writeEnrollmentTokenFile, } from '@cortexkit/claustrum-client';
 import { acquireRefreshFileLock } from '../fs/index.js';
+import { ensurePrivateDirectory as ensureWindowsDirectory, PrivateFileError, readPrivateText, verifySafeDirectory, windowsPrivateFiles, writePrivateAtomic, } from '../fs/private-files.js';
 import { ClaustrumConsumerError } from './errors.js';
 const ENROLLMENT_SCHEMA = 1;
 const ENROLLMENT_FILE_MAX_BYTES = 16 * 1024;
@@ -198,6 +199,21 @@ function parseSecretJson(text) {
     }
 }
 async function readBoundedJson(path) {
+    if (windowsPrivateFiles) {
+        try {
+            await ensureWindowsDirectory(dirname(path));
+            const text = await readPrivateText(path, true);
+            if (Buffer.byteLength(text) > ENROLLMENT_FILE_MAX_BYTES) {
+                throw new ClaustrumConsumerError('unsafe-file', 'Claustrum enrollment file is too large');
+            }
+            return parseSecretJson(text);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
     let descriptor;
     try {
         // O_NOFOLLOW: a symlink planted at the path must not redirect a secret read.
@@ -267,52 +283,76 @@ async function isPrivateGroup(uid, gid, options) {
         return false;
     }
 }
+function ancestorPolicyOptions(options) {
+    if (!options.passwdPath && !options.groupPath)
+        return undefined;
+    return {
+        fs: {
+            readFile: (path) => readFile(path === '/etc/passwd'
+                ? (options.passwdPath ?? path)
+                : path === '/etc/group'
+                    ? (options.groupPath ?? path)
+                    : path),
+        },
+    };
+}
 /**
- * Protect setup writes from directory replacement. Group write access is safe
- * only when local account records prove that the effective user's group is private.
+ * Protect setup writes from directory replacement. On POSIX, group write access
+ * is safe only when local records prove the effective user's group is private;
+ * sticky ancestors are accepted. Windows uses the shared safe-parent policy.
  */
 export async function refuseWritableAncestor(parent, options = {}) {
-    const uid = process.geteuid?.();
-    if (uid === undefined)
-        return;
-    const gid = process.getegid?.();
-    let component;
-    try {
-        component = await realpath(parent);
-    }
-    catch {
-        return;
-    }
-    // Load lazily, once per traversal: account changes take effect on the next write.
-    let privateGroup;
-    for (;;) {
-        const metadata = await stat(component).catch(() => undefined);
-        if (metadata &&
-            (metadata.mode & 0o022) !== 0 &&
-            (metadata.mode & 0o1000) === 0) {
-            if (privateGroup === undefined) {
-                privateGroup =
-                    gid !== undefined && (await isPrivateGroup(uid, gid, options));
-            }
-            if ((metadata.mode & 0o002) !== 0 ||
-                metadata.uid !== uid ||
-                metadata.gid !== gid ||
-                !privateGroup) {
-                throw new ClaustrumConsumerError('unsafe-file', `Claustrum enrollment path has a writable ancestor: ${component}. Another user could replace it. Run: chmod g-w,o-w ${component}`);
-            }
+    if (!windowsPrivateFiles) {
+        const uid = process.geteuid?.();
+        if (uid === undefined)
+            return;
+        const gid = process.getegid?.();
+        let component;
+        try {
+            component = await realpath(parent);
         }
-        const next = dirname(component);
-        if (next === component)
+        catch {
             return;
-        component = next;
+        }
+        // Load lazily, once per traversal: account changes take effect on the next write.
+        let privateGroup;
+        for (;;) {
+            const metadata = await stat(component).catch(() => undefined);
+            if (metadata &&
+                (metadata.mode & 0o022) !== 0 &&
+                (metadata.mode & 0o1000) === 0) {
+                if (privateGroup === undefined) {
+                    privateGroup =
+                        gid !== undefined && (await isPrivateGroup(uid, gid, options));
+                }
+                if ((metadata.mode & 0o002) !== 0 ||
+                    metadata.uid !== uid ||
+                    metadata.gid !== gid ||
+                    !privateGroup) {
+                    throw new ClaustrumConsumerError('unsafe-file', `Claustrum enrollment path has a writable ancestor: ${component}. Another user could replace it. Run: chmod g-w,o-w ${component}`);
+                }
+            }
+            const next = dirname(component);
+            if (next === component)
+                return;
+            component = next;
+        }
+    }
+    try {
+        await verifySafeDirectory(parent, ancestorPolicyOptions(options));
+    }
+    catch (error) {
+        if (!(error instanceof PrivateFileError))
+            throw error;
+        throw new ClaustrumConsumerError('unsafe-file', `Claustrum enrollment parent refused: ${error.path} (${error.reason ?? error.code}). Use a folder that other users cannot write or replace.`);
     }
 }
-/**
- * Create the enrollment directory owner-only (0700), and tighten it to 0700
- * when it already exists with group or other bits, so the token and the
- * request secret never sit in a directory another account can list.
- */
-async function ensurePrivateDirectory(directory) {
+/** POSIX tightens the enrollment directory to 0700; Windows verifies safe ancestry without modifying existing parents. */
+async function ensurePrivateDirectory(directory, options = {}) {
+    if (windowsPrivateFiles) {
+        await ensureWindowsDirectory(directory, false, ancestorPolicyOptions(options));
+        return;
+    }
     await mkdir(directory, { recursive: true, mode: 0o700 });
     const metadata = await stat(directory);
     const uid = process.geteuid?.();
@@ -324,12 +364,14 @@ async function ensurePrivateDirectory(directory) {
 }
 async function writeStateAtomic(path, state, ancestorOptions = {}) {
     const parent = dirname(path);
-    await ensurePrivateDirectory(parent);
+    await ensurePrivateDirectory(parent, ancestorOptions);
     await refuseWritableAncestor(parent, ancestorOptions);
     const bytes = `${JSON.stringify(state)}\n`;
     if (Buffer.byteLength(bytes) > ENROLLMENT_FILE_MAX_BYTES) {
         throw new ClaustrumConsumerError('invalid-state', 'Claustrum enrollment state is too large');
     }
+    if (windowsPrivateFiles)
+        return writePrivateAtomic(path, bytes);
     const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
     let descriptor;
     let created = false;
@@ -496,7 +538,7 @@ export class ClaustrumEnrollmentManager {
         return statusFromState(blocked);
     }
     async reconcile() {
-        await ensurePrivateDirectory(dirname(this.#paths.statePath));
+        await ensurePrivateDirectory(dirname(this.#paths.statePath), this.#ancestorOptions);
         const lock = await acquireRefreshFileLock({
             name: 'ceremony',
             path: this.#paths.statePath,
@@ -616,7 +658,7 @@ export class ClaustrumEnrollmentManager {
                 }
                 // The vault returns the token exactly once: it reaches disk before the
                 // pending metadata (and its secret) is replaced.
-                await ensurePrivateDirectory(dirname(this.#paths.tokenPath));
+                await ensurePrivateDirectory(dirname(this.#paths.tokenPath), this.#ancestorOptions);
                 await refuseWritableAncestor(dirname(this.#paths.tokenPath), this.#ancestorOptions);
                 await this.#writeTokenFile(this.#paths.tokenPath, {
                     token: outcome.token,

package/src/common-auth-embedded/claustrum/roster.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
 import { acquireRefreshFileLock, withLock, writeJsonAtomic, } from '../fs/index.js';
+import { readPrivateText, windowsPrivateFiles } from '../fs/private-files.js';
 import { isQuotaMap, mergeQuotaObservation, } from '../quota/index.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
@@ -289,7 +289,7 @@ function decodeRoster(value) {
 export async function readVaultRoster(path) {
     let text;
     try {
-        text = await readFile(path, 'utf8');
+        text = await readPrivateText(path, windowsPrivateFiles);
     }
     catch (error) {
         if (error.code === 'ENOENT')

package/src/common-auth-embedded/fs/atomic-write.d.ts

@@ -1,3 +1,4 @@
+import { type PrivateWriteOutcome } from './private-files.js';
 export interface AtomicWriteOptions {
     serialize?: (value: unknown) => string;
     beforeRename?: () => Promise<void>;
@@ -5,6 +6,10 @@ export interface AtomicWriteOptions {
     stageName?: () => string;
     /** Sync the staged file and, after rename, its parent directory. Opt-in. */
     durable?: boolean;
+    /** Windows opt-in: flush file bytes, without promising directory metadata durability. */
+    durability?: 'file-only-on-windows';
+    /** Reports Windows rename success, file/directory durability, retry counts and error codes, never file bytes. */
+    onOutcome?: (outcome: PrivateWriteOutcome) => void;
 }
 /** Internal classification of fsync failures, including a failure after rename. */
 export declare class AtomicSyncError extends Error {

package/src/common-auth-embedded/fs/atomic-write.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, open, rename, rm } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { PrivateFileError, verifyPrivate, windowsPrivateFiles, writePrivateAtomic, } from './private-files.js';
 /** Internal classification of fsync failures, including a failure after rename. */
 export class AtomicSyncError extends Error {
     constructor(cause) {
@@ -16,6 +17,18 @@ export async function writeJsonAtomic(path, value, options = {}) {
  * and removed ids here, because a later directory sync cannot undo the rename.
  */
 export async function writeJsonAtomicTracked(path, value, options, onRenamed) {
+    if (windowsPrivateFiles) {
+        return writePrivateAtomic(path, options.serialize
+            ? options.serialize(value)
+            : `${JSON.stringify(value, null, 2)}\n`, {
+            beforeRename: options.beforeRename,
+            stagePath: `${path}.${(options.stageName ?? randomUUID)()}.tmp`,
+            onRenamed,
+            durable: options.durable,
+            durability: options.durability,
+            onOutcome: options.onOutcome,
+        });
+    }
     await mkdir(dirname(path), { recursive: true });
     const tempPath = `${path}.${(options.stageName ?? randomUUID)()}.tmp`;
     let handle;
@@ -63,6 +76,14 @@ export async function writeJsonAtomicTracked(path, value, options, onRenamed) {
 }
 /** Make an already renamed file and its directory durable without rewriting bytes. */
 export async function syncJsonFile(path) {
+    if (windowsPrivateFiles) {
+        await verifyPrivate(path, 'file');
+        const error = new PrivateFileError(path, 'directory-sync-unsupported', {
+            code: 'ENOTSUP',
+        });
+        error.published = true;
+        throw error;
+    }
     const file = await open(path, 'r');
     try {
         await file.sync();

package/src/common-auth-embedded/fs/index.d.ts

@@ -1,6 +1,8 @@
 export type { AtomicWriteOptions } from './atomic-write.js';
 export { writeJsonAtomic } from './atomic-write.js';
 export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { PrivateWriteOutcome } from './private-files.js';
+export { PrivateFileError } from './private-files.js';
 export type { LockLoss, RefreshFileLock } from './refresh-file-lock.js';
 export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
 export type { LockOptions, LockOwnershipDetails } from './with-lock.js';

package/src/common-auth-embedded/fs/index.js

@@ -1,5 +1,6 @@
 export { writeJsonAtomic } from './atomic-write.js';
 export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export { PrivateFileError } from './private-files.js';
 // The try-once lock underneath withLock, for callers that hold a lock across
 // several steps or poll instead of waiting (for example a refresh lease).
 export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';

package/src/common-auth-embedded/fs/private-files.d.ts

@@ -0,0 +1,66 @@
+import { rename } from 'node:fs/promises';
+import type { PosixOwnerOnlyPathAsyncOptions } from '@cortexkit/private-files';
+export declare const windowsPrivateFiles: boolean;
+type Backend = typeof import('@cortexkit/private-files');
+type Kind = 'file' | 'directory';
+/** Tests inject a backend here; production always imports the private-files package. */
+export declare function setPrivateFilesBackendForTest(api?: Backend): void;
+export declare class PrivateFileError extends Error {
+    readonly path: string;
+    readonly stage: string;
+    readonly code: string;
+    readonly win32Code?: number;
+    readonly reason?: string;
+    published: boolean;
+    durabilityConfirmed: boolean;
+    fileDurable: boolean;
+    attempts: number;
+    elapsedMs: number;
+    orphanPath?: string;
+    constructor(path: string, stage: string, cause: unknown);
+}
+export declare function privateOperation<T>(path: string, stage: string, operation: () => Promise<T>): Promise<T>;
+/** Tests only: policy options used by safe-parent checks that pass none. */
+export declare function setSafeParentOptionsForTest(options?: PosixOwnerOnlyPathAsyncOptions): void;
+/** Existing containing directories use the shared entry-integrity policy, not secret-file permissions. */
+export declare function verifySafeDirectory(path: string, options?: PosixOwnerOnlyPathAsyncOptions): Promise<void>;
+/** Repair only the specific owned secret file supplied by a caller, never an existing directory tree. */
+export declare function verifyPrivate(path: string, kind: Kind, migrate?: boolean): Promise<void>;
+/** Create missing components privately; inspect existing ancestors without modifying them. */
+export declare function ensurePrivateDirectory(path: string, _migrate?: boolean, options?: PosixOwnerOnlyPathAsyncOptions): Promise<void>;
+export declare function readPrivateText(path: string, migrate?: boolean): Promise<string>;
+export declare function readPrivateBuffer(path: string, migrate?: boolean): Promise<Buffer>;
+export declare function createPrivateBytes(path: string, bytes: string): Promise<void>;
+export declare function createPrivateDirectoryExclusive(path: string): Promise<void>;
+export interface ReplaceOptions {
+    beforeRename?: () => Promise<void>;
+    /** Absolute monotonic deadline, for an expiring lease. */
+    deadline?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    rename?: typeof rename;
+}
+/** Retry Windows rename sharing/access errors within a budget; they never prove lease contention. */
+export declare function replaceWindowsFile(from: string, to: string, options?: ReplaceOptions): Promise<{
+    attempts: number;
+    elapsedMs: number;
+}>;
+export interface PrivateWriteOutcome {
+    path: string;
+    stage: string;
+    published: boolean;
+    fileDurable: boolean;
+    durabilityConfirmed: boolean;
+    attempts: number;
+    elapsedMs: number;
+    code?: string;
+    win32Code?: number;
+}
+export declare function writePrivateAtomic(path: string, bytes: string, options?: ReplaceOptions & {
+    stagePath?: string;
+    onRenamed?: () => void;
+    durable?: boolean;
+    durability?: 'file-only-on-windows';
+    onOutcome?: (outcome: PrivateWriteOutcome) => void;
+}): Promise<void>;
+export {};

package/src/common-auth-embedded/fs/private-files.js

@@ -0,0 +1,302 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, readFile, rename, unlink } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+export const windowsPrivateFiles = process.platform === 'win32';
+const migrationNotices = new Set();
+function ioCode(detail) {
+    // Native errors retain their Win32 code. Only demonstrated absence/exclusive
+    // collisions are normalized; access/sharing failures never become lost races.
+    if (detail?.reason === 'io-error') {
+        if (detail.win32Code === 2 || detail.win32Code === 3)
+            return 'ENOENT';
+        if (detail.win32Code === 80 || detail.win32Code === 183)
+            return 'EEXIST';
+    }
+    return detail?.code ?? 'ERR_PRIVATE_FILE';
+}
+// Production loads this package only on Windows; POSIX keeps its own directory policy.
+let backend;
+/** Tests inject a backend here; production always imports the private-files package. */
+export function setPrivateFilesBackendForTest(api) {
+    backend = api ? Promise.resolve(api) : undefined;
+}
+function loadBackend() {
+    backend ??= import('@cortexkit/private-files');
+    return backend;
+}
+export class PrivateFileError extends Error {
+    path;
+    stage;
+    code;
+    win32Code;
+    reason;
+    published = false;
+    durabilityConfirmed = false;
+    fileDurable = false;
+    attempts = 0;
+    elapsedMs = 0;
+    orphanPath;
+    constructor(path, stage, cause) {
+        const detail = cause;
+        super(`Private file refused at ${stage}: ${path} (${detail?.reason ?? detail?.code ?? 'io-error'}). Use a safe parent directory. Repair only a named secret file in safe ancestry whose owner the published policy trusts, without changing its owner or any existing directory. Previously exposed credentials may need rotation. Windows requires the private-files native prebuild and an ACL-persisting local filesystem such as NTFS.`, { cause });
+        this.path = path;
+        this.stage = stage;
+        this.name = 'PrivateFileError';
+        this.code = ioCode(detail);
+        this.win32Code = detail?.win32Code;
+        this.reason = detail?.reason;
+    }
+}
+export async function privateOperation(path, stage, operation) {
+    try {
+        return await operation();
+    }
+    catch (cause) {
+        if (cause instanceof PrivateFileError)
+            throw cause;
+        throw new PrivateFileError(path, stage, cause);
+    }
+}
+// Tests inject metadata into safe-parent checks, including checks deep inside
+// callers that take no policy options. Production never sets this.
+let safeParentOptionsForTest;
+/** Tests only: policy options used by safe-parent checks that pass none. */
+export function setSafeParentOptionsForTest(options) {
+    safeParentOptionsForTest = options;
+}
+/** Existing containing directories use the shared entry-integrity policy, not secret-file permissions. */
+export async function verifySafeDirectory(path, options) {
+    path = resolve(path);
+    options ??= safeParentOptionsForTest;
+    await privateOperation(path, 'safe-parent', async () => {
+        const result = await (await loadBackend()).verifySafeParent(path, options);
+        if (result.ok === false) {
+            // Preserve an absent parent's ENOENT so callers can create it privately.
+            if (result.reason === 'io-error' || result.reason === 'wrong-kind')
+                await lstat(path);
+            throw new PrivateFileError(result.level ?? result.path, 'safe-parent', {
+                ...result,
+                code: 'ERR_PRIVATE_FILES_SECURITY',
+            });
+        }
+    });
+}
+/** Repair only the specific owned secret file supplied by a caller, never an existing directory tree. */
+export async function verifyPrivate(path, kind, migrate = false) {
+    path = resolve(path);
+    if (kind === 'directory')
+        return verifySafeDirectory(path);
+    await privateOperation(path, 'verify', async () => {
+        const api = await loadBackend();
+        const result = await api.verifyOwnerOnly(path);
+        let repaired = false;
+        if (!result.ok) {
+            const { reason } = result.refusal;
+            // The result API intentionally omits native IO codes. Use the throwing
+            // API to preserve absence/collision details, never infer them from text.
+            if (reason === 'io-error')
+                await api.verifyPrivatePath(path, kind);
+            // DACL replacement repairs permissions only, never ownership or unsafe ancestry.
+            if (migrate &&
+                [
+                    api.EXTRA_ACE,
+                    api.NOT_PROTECTED,
+                    api.NULL_DACL,
+                    api.EMPTY_DACL,
+                ].includes(reason)) {
+                await verifySafeDirectory(dirname(path));
+                await api.securePrivatePath(path, kind);
+                repaired = true;
+            }
+            else {
+                throw Object.assign(new Error('Owner-only verification refused'), {
+                    reason,
+                    code: 'ERR_PRIVATE_FILES_SECURITY',
+                });
+            }
+        }
+        // Verify the expected object kind and its permissions by handle after repair.
+        await api.verifyPrivatePath(path, kind);
+        if (repaired && !migrationNotices.has(path)) {
+            migrationNotices.add(path);
+            process.emitWarning(`Private permissions tightened: ${path}. This object may have been readable before; rotate credentials if needed.`, 'PrivateFileMigration');
+        }
+    });
+}
+/** Create missing components privately; inspect existing ancestors without modifying them. */
+export async function ensurePrivateDirectory(path, _migrate = false, options) {
+    path = resolve(path);
+    await privateOperation(path, 'directory', async () => {
+        const api = await loadBackend();
+        try {
+            await lstat(path);
+            return await verifySafeDirectory(path, options);
+        }
+        catch (error) {
+            if (ioCode(error) !== 'ENOENT')
+                throw error;
+        }
+        const parent = dirname(path);
+        if (parent === path)
+            throw Object.assign(new Error('Missing root'), { code: 'ENOENT' });
+        await ensurePrivateDirectory(parent, false, options);
+        try {
+            await api.createOwnerOnly(path, { kind: 'dir' });
+        }
+        catch (error) {
+            if (ioCode(error) !== 'EEXIST')
+                throw error;
+        }
+        await verifySafeDirectory(path, options);
+    });
+}
+export async function readPrivateText(path, migrate = false) {
+    if (!windowsPrivateFiles)
+        return readFile(path, 'utf8');
+    return (await readPrivateBuffer(path, migrate)).toString('utf8');
+}
+export async function readPrivateBuffer(path, migrate = false) {
+    if (!windowsPrivateFiles)
+        return readFile(path);
+    path = resolve(path);
+    if (migrate) {
+        await verifySafeDirectory(dirname(path));
+        await verifyPrivate(path, 'file', true);
+    }
+    return privateOperation(path, 'read', async () => (await loadBackend()).readOwnerOnly(path));
+}
+export async function createPrivateBytes(path, bytes) {
+    await verifySafeDirectory(dirname(resolve(path)));
+    await privateOperation(path, 'create', async () => {
+        // The backend verifies the creation handle while empty, before consuming bytes.
+        await (await loadBackend()).createPrivateFile(resolve(path), bytes);
+    });
+}
+export async function createPrivateDirectoryExclusive(path) {
+    await verifySafeDirectory(dirname(resolve(path)));
+    await privateOperation(path, 'directory-create', async () => {
+        await (await loadBackend()).createOwnerOnly(resolve(path), { kind: 'dir' });
+    });
+}
+/** Retry Windows rename sharing/access errors within a budget; they never prove lease contention. */
+export async function replaceWindowsFile(from, to, options = {}) {
+    from = resolve(from);
+    to = resolve(to);
+    const now = options.now ?? (() => performance.now());
+    const start = now();
+    const deadline = Math.min(start + 500, options.deadline ?? Infinity);
+    const delays = [0, 10, 20, 40, 80, 100];
+    let original;
+    let attempts = 0;
+    for (const delay of delays) {
+        if (now() >= deadline)
+            break;
+        if (delay)
+            await (options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(Math.min(delay, Math.max(0, deadline - now())));
+        if (now() >= deadline)
+            break;
+        await options.beforeRename?.();
+        if (now() >= deadline)
+            break;
+        attempts++;
+        try {
+            await (options.rename ?? rename)(from, to);
+            return { attempts, elapsedMs: now() - start };
+        }
+        catch (error) {
+            original ??= error;
+            const detail = error;
+            const candidate = detail.win32Code !== undefined
+                ? detail.win32Code === 32 || detail.win32Code === 33
+                : ['EBUSY', 'EPERM', 'EACCES'].includes(detail.code ?? '') &&
+                    !detail.reason;
+            if (!candidate)
+                break;
+        }
+    }
+    const error = new PrivateFileError(to, 'rename', original ??
+        Object.assign(new Error('Publication deadline expired'), {
+            code: 'ETIMEDOUT',
+        }));
+    error.attempts = attempts;
+    error.elapsedMs = now() - start;
+    throw error;
+}
+export async function writePrivateAtomic(path, bytes, options = {}) {
+    path = resolve(path);
+    await ensurePrivateDirectory(dirname(path));
+    try {
+        await verifyPrivate(path, 'file', true);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const stage = resolve(options.stagePath ?? `${path}.${randomUUID()}.tmp`);
+    if (dirname(stage) !== dirname(path))
+        throw new PrivateFileError(path, 'stage-directory', { code: 'EXDEV' });
+    let created = false;
+    let published = false;
+    let outcome = { attempts: 0, elapsedMs: 0 };
+    let stageName = 'stage-create';
+    const reportOutcome = (error) => {
+        try {
+            options.onOutcome?.({
+                path,
+                stage: error?.stage ?? 'published',
+                published,
+                fileDurable: published,
+                durabilityConfirmed: false,
+                attempts: error?.attempts ?? outcome.attempts,
+                elapsedMs: error?.elapsedMs ?? outcome.elapsedMs,
+                ...(error && { code: error.code, win32Code: error.win32Code }),
+            });
+        }
+        catch {
+            // Outcome observers cannot change whether publication succeeded.
+        }
+    };
+    try {
+        await createPrivateBytes(stage, bytes);
+        created = true;
+        stageName = 'before-rename';
+        outcome = await replaceWindowsFile(stage, path, options);
+        created = false;
+        published = true;
+        stageName = 'published-callback';
+        options.onRenamed?.();
+        stageName = 'published-verify';
+        await verifyPrivate(path, 'file');
+        // createPrivateFile flushes the file. Directory metadata durability has not
+        // been qualified on Windows, so never promise the POSIX directory fsync.
+        if (options.durable && options.durability !== 'file-only-on-windows')
+            throw new PrivateFileError(path, 'directory-sync-unsupported', {
+                code: 'ENOTSUP',
+            });
+        reportOutcome();
+    }
+    catch (cause) {
+        const error = cause instanceof PrivateFileError
+            ? cause
+            : new PrivateFileError(path, stageName, cause);
+        error.published = published;
+        error.fileDurable = published;
+        if (published)
+            Object.assign(error, outcome);
+        if (created) {
+            try {
+                await unlink(stage);
+            }
+            catch {
+                error.orphanPath = stage;
+            }
+            created = false;
+        }
+        reportOutcome(error);
+        throw error;
+    }
+    finally {
+        if (created)
+            await unlink(stage).catch(() => { });
+    }
+}

package/src/common-auth-embedded/fs/refresh-file-lock.d.ts

@@ -29,5 +29,5 @@ export declare function acquireRefreshFileLock(options: {
     onContended?: () => void;
     /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
     onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
-    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
 }): Promise<RefreshFileLock | null>;