@cortexkit/common-auth 0.9.4 → 0.10.0

package/dist/claustrum/enrollment.d.ts

@@ -91,6 +91,16 @@ export declare function hostEnrollmentPaths(input: {
     override?: string;
     cwd?: string;
 }): ClaustrumEnrollmentPaths;
+/** Account-file paths are injectable for isolated setup tests; no environment overrides. */
+export interface EnrollmentAncestorOptions {
+    passwdPath?: string;
+    groupPath?: string;
+}
+/**
+ * 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.
+ */
+export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
 export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentStatus>;
 /**
  * Read fresh bearer material for one scoped operation; never publish it.
@@ -111,6 +121,7 @@ export declare class ClaustrumEnrollmentManager {
         now?: () => number;
         mintSecret?: () => string;
         writeTokenFile?: typeof writeEnrollmentTokenFile;
+        ancestorOptions?: EnrollmentAncestorOptions;
     });
     status(): Promise<ClaustrumEnrollmentStatus>;
     resetTerminal(): Promise<ClaustrumEnrollmentResetResult>;

package/dist/claustrum/enrollment.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
-import { chmod, mkdir, open, realpath, rename, stat, unlink, } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, } from 'node:fs/promises';
 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';
@@ -183,7 +183,7 @@ function validateReadableSecretFile(metadata) {
     if ((metadata.mode & 0o077) !== 0) {
         throw new ClaustrumConsumerError('unsafe-file', 'Claustrum enrollment file must be owner-only');
     }
-    const expectedUid = process.getuid?.();
+    const expectedUid = process.geteuid?.();
     if (expectedUid !== undefined && metadata.uid !== expectedUid) {
         throw new ClaustrumConsumerError('unsafe-file', 'Claustrum enrollment file must be owned by the current user');
     }
@@ -221,11 +221,61 @@ async function readBoundedJson(path) {
         await descriptor.close();
     }
 }
+function accountRecords(text, fields) {
+    const records = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '' || line.startsWith('#'))
+            continue;
+        const parts = line.split(':');
+        if (parts.length !== fields ||
+            !/^[^\s:,]+$/.test(parts[0] ?? '') ||
+            !/^\d+$/.test(parts[2] ?? '') ||
+            !Number.isSafeInteger(Number(parts[2])) ||
+            (fields === 7 &&
+                (!/^\d+$/.test(parts[3] ?? '') ||
+                    !Number.isSafeInteger(Number(parts[3])))) ||
+            (fields === 4 &&
+                parts[3] !== '' &&
+                !/^[^\s:,]+(?:,[^\s:,]+)*$/.test(parts[3] ?? '')))
+            return undefined;
+        records.push(parts);
+    }
+    return records;
+}
+async function isPrivateGroup(uid, gid, options) {
+    try {
+        const [passwdText, groupText] = await Promise.all([
+            readFile(options.passwdPath ?? '/etc/passwd', 'utf8'),
+            readFile(options.groupPath ?? '/etc/group', 'utf8'),
+        ]);
+        const users = accountRecords(passwdText, 7);
+        const groups = accountRecords(groupText, 4);
+        if (!users || !groups)
+            return false;
+        const owners = users.filter((user) => Number(user[2]) === uid);
+        const matchingGroups = groups.filter((group) => Number(group[2]) === gid);
+        if (owners.length !== 1 || matchingGroups.length !== 1)
+            return false;
+        const name = owners[0]?.[0];
+        const members = matchingGroups[0]?.[3] ?? '';
+        return ((members === '' ||
+            members.split(',').every((member) => member === name)) &&
+            !users.some((user) => Number(user[2]) !== uid && Number(user[3]) === gid));
+    }
+    catch {
+        // Missing local records (including NSS-only accounts) cannot prove exclusivity.
+        return false;
+    }
+}
 /**
- * Refuse a path below any group- or world-writable directory without the
- * sticky bit: another user could swap the file out from under us there.
+ * 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.
  */
-async function refuseWritableAncestor(parent) {
+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);
@@ -233,12 +283,23 @@ async function refuseWritableAncestor(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) {
-            throw new ClaustrumConsumerError('unsafe-file', 'Claustrum enrollment path has an unsafe writable ancestor');
+            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)
@@ -254,17 +315,17 @@ async function refuseWritableAncestor(parent) {
 async function ensurePrivateDirectory(directory) {
     await mkdir(directory, { recursive: true, mode: 0o700 });
     const metadata = await stat(directory);
-    const uid = process.getuid?.();
+    const uid = process.geteuid?.();
     if (uid !== undefined && metadata.uid !== uid) {
         throw new ClaustrumConsumerError('unsafe-file', 'Claustrum enrollment directory must be owned by the current user');
     }
     if ((metadata.mode & 0o077) !== 0)
         await chmod(directory, 0o700);
 }
-async function writeStateAtomic(path, state) {
+async function writeStateAtomic(path, state, ancestorOptions = {}) {
     const parent = dirname(path);
     await ensurePrivateDirectory(parent);
-    await refuseWritableAncestor(parent);
+    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');
@@ -321,7 +382,10 @@ export async function readClaustrumEnrollmentStatus(paths, proposedName) {
  * Re-reading per operation is what lets an operator reissue a token on disk.
  */
 export async function readClaustrumEnrollmentToken(tokenPath) {
-    await refuseWritableAncestor(tokenPath);
+    // Reads rely on O_NOFOLLOW and regular, owner-only, effective-uid-owned files:
+    // another user cannot plant a file owned by us. Ancestor checks protect writes
+    // from placing our secret in a swapped directory, not reads; keep their
+    // realpath/stat and account-file I/O off the authorization path.
     const value = await readBoundedJson(tokenPath);
     if (value === undefined)
         throw new ClaustrumConsumerError('not-enrolled', 'Claustrum enrollment is not configured');
@@ -368,7 +432,9 @@ export class ClaustrumEnrollmentManager {
     #now;
     #mintSecret;
     #writeTokenFile;
+    #ancestorOptions;
     constructor(options) {
+        this.#ancestorOptions = options.ancestorOptions ?? {};
         this.#client = options.client;
         this.#paths = options.paths;
         this.#proposedName = options.proposedName;
@@ -392,7 +458,7 @@ export class ClaustrumEnrollmentManager {
             errorCode: code,
             updatedAt: this.#now(),
         };
-        await writeStateAtomic(this.#paths.statePath, blocked);
+        await writeStateAtomic(this.#paths.statePath, blocked, this.#ancestorOptions);
         return statusFromState(blocked);
     }
     async reconcile() {
@@ -421,7 +487,7 @@ export class ClaustrumEnrollmentManager {
                         tokenGeneration: token.token_generation,
                         updatedAt: this.#now(),
                     };
-                    await writeStateAtomic(this.#paths.statePath, approved);
+                    await writeStateAtomic(this.#paths.statePath, approved, this.#ancestorOptions);
                     state = approved;
                 }
                 return {
@@ -442,7 +508,7 @@ export class ClaustrumEnrollmentManager {
                     errorCode: 'missing_token',
                     updatedAt: this.#now(),
                 };
-                await writeStateAtomic(this.#paths.statePath, blocked);
+                await writeStateAtomic(this.#paths.statePath, blocked, this.#ancestorOptions);
                 return statusFromState(blocked);
             }
             if (state && state.phase !== 'pending')
@@ -462,7 +528,7 @@ export class ClaustrumEnrollmentManager {
                 // The secret is on disk before the proposal leaves the process: the
                 // vault answers a repeated proposal with the same secret with the same
                 // request id, so a crash between propose and saving the id costs nothing.
-                await writeStateAtomic(this.#paths.statePath, state);
+                await writeStateAtomic(this.#paths.statePath, state, this.#ancestorOptions);
             }
             if (!state.requestId) {
                 try {
@@ -478,7 +544,7 @@ export class ClaustrumEnrollmentManager {
                         requestId: proposed.requestId,
                         updatedAt: this.#now(),
                     };
-                    await writeStateAtomic(this.#paths.statePath, state);
+                    await writeStateAtomic(this.#paths.statePath, state, this.#ancestorOptions);
                 }
                 catch (error) {
                     const refusal = classifyEnrollmentError(error);
@@ -511,11 +577,13 @@ export class ClaustrumEnrollmentManager {
                         proposedName: state.proposedName,
                         updatedAt: this.#now(),
                     };
-                    await writeStateAtomic(this.#paths.statePath, denied);
+                    await writeStateAtomic(this.#paths.statePath, denied, this.#ancestorOptions);
                     return statusFromState(denied);
                 }
                 // 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 refuseWritableAncestor(dirname(this.#paths.tokenPath), this.#ancestorOptions);
                 await this.#writeTokenFile(this.#paths.tokenPath, {
                     token: outcome.token,
                     token_generation: outcome.tokenGeneration,
@@ -528,7 +596,7 @@ export class ClaustrumEnrollmentManager {
                     tokenGeneration: outcome.tokenGeneration,
                     updatedAt: this.#now(),
                 };
-                await writeStateAtomic(this.#paths.statePath, approved);
+                await writeStateAtomic(this.#paths.statePath, approved, this.#ancestorOptions);
                 return statusFromState(approved);
             }
             catch (error) {

package/dist/claustrum/index.d.ts

@@ -7,7 +7,7 @@ export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, Cla
 export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
 export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
-export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library

package/dist/claustrum/roster.d.ts

@@ -86,11 +86,16 @@ export declare function projectVaultRoster(previous: VaultRosterFile | undefined
  */
 export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
 export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/** The ownership assertion available to a roster mutation callback. */
+export interface VaultRosterLockContext {
+    assertOwned: () => Promise<void>;
+}
 /**
  * Read, change and write the roster under its write lock. `change` returns
- * undefined to leave the file as it is.
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
  */
-export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined) => Promise<{
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined, context: VaultRosterLockContext) => Promise<{
     next?: VaultRosterFile;
     result: T;
 }> | {

package/dist/claustrum/roster.js

@@ -313,12 +313,15 @@ const WRITE_LOCK = {
 const DISCOVERY_LEASE = { name: 'claustrum-roster', ttlMs: 30_000 };
 /**
  * Read, change and write the roster under its write lock. `change` returns
- * undefined to leave the file as it is.
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
  */
 export async function mutateVaultRoster(path, change) {
     return withLock(path, WRITE_LOCK, async (lock) => {
         const current = await readVaultRoster(path);
-        const { next, result } = await change(current);
+        const { next, result } = await change(current, {
+            assertOwned: () => lock.assertOwned(),
+        });
         if (next) {
             await lock.assertOwned();
             await writeJsonAtomic(path, next);

package/dist/fs/refresh-file-lock.d.ts

@@ -25,5 +25,9 @@ export declare function acquireRefreshFileLock(options: {
     now?: () => number;
     renew?: boolean;
     renewIntervalMs?: number;
-    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | '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>;
+    /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
+    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>;
 }): Promise<RefreshFileLock | null>;

package/dist/fs/refresh-file-lock.js

@@ -24,6 +24,27 @@ export async function acquireRefreshFileLock(options) {
     const lostPromise = new Promise((resolve) => {
         resolveLoss = resolve;
     });
+    function notifyTimerStep(event) {
+        try {
+            const result = options.onRenewalTimer?.(event);
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Timer observer failures must not replace the lock operation result.
+        }
+    }
+    function cancelRenewalTimer() {
+        if (!renewTimer)
+            return;
+        clearRefreshLockRenewalTimeout(renewTimer);
+        renewTimer = null;
+        notifyTimerStep('cancelled');
+    }
     function recordLoss(reason, owner) {
         if (loss || released)
             return;
@@ -37,10 +58,7 @@ export async function acquireRefreshFileLock(options) {
                 ? { observedExpiresAt: owner.expiresAt }
                 : {}),
         });
-        if (renewTimer) {
-            clearRefreshLockRenewalTimeout(renewTimer);
-            renewTimer = null;
-        }
+        cancelRenewalTimer();
         resolveLoss(loss);
     }
     let renewalInFlight = null;
@@ -211,9 +229,10 @@ export async function acquireRefreshFileLock(options) {
         }
         return true;
     }
-    // Marker loss after a write may mean our record replaced a successor's.
-    // Delete only a record still owned by us; a concurrent successor write can
-    // then yield zero winners, never two.
+    // Marker loss after a write may mean another contender has taken over.
+    // Delete only a record still owned by us, so an already-installed
+    // successor is preserved. The owner read and the removal are not atomic:
+    // a successor record written between them can still be deleted.
     async function relinquishLockAfterMarkerLoss() {
         for (let attempt = 0; attempt < MAX_STEAL_ATTEMPTS; attempt++) {
             if (options.onStep)
@@ -241,6 +260,7 @@ export async function acquireRefreshFileLock(options) {
             return;
         const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
         renewTimer = setRefreshLockRenewalTimeout(() => {
+            renewTimer = null;
             const renewal = (async () => {
                 let shouldReschedule = !released;
                 try {
@@ -333,6 +353,22 @@ export async function acquireRefreshFileLock(options) {
         }, intervalMs);
         if ('unref' in renewTimer)
             renewTimer.unref();
+        notifyTimerStep('scheduled');
+    }
+    function contended() {
+        try {
+            const result = options.onContended?.();
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Observers cannot change whether the lock is acquired.
+        }
+        return null;
     }
     let acquired = await tryAcquire();
     if (!acquired) {
@@ -341,7 +377,9 @@ export async function acquireRefreshFileLock(options) {
             if (acquired)
                 break;
             if (await lockIsLive())
-                return null;
+                return contended();
+            if (options.onStep)
+                await options.onStep('stale-lock-observed');
             try {
                 if (!(await tryAcquireEvictionMarker())) {
                     await backoff();
@@ -360,7 +398,7 @@ export async function acquireRefreshFileLock(options) {
             }
             try {
                 if (await lockIsLive())
-                    return null;
+                    return contended();
                 // Verify marker ownership before removing a lock found not live.
                 if (!(await ownsEvictionMarker()))
                     return null;
@@ -374,14 +412,18 @@ export async function acquireRefreshFileLock(options) {
                 // Fence check 3: re-verify ownership after removing the stale lock.
                 if (!(await ownsEvictionMarker()))
                     return null;
+                if (options.onStep)
+                    await options.onStep('stale-lock-removed');
                 acquired = await tryAcquire();
                 if (!acquired)
                     return null;
+                if (options.onStep)
+                    await options.onStep('stale-lock-recreated');
                 // Fence check 4: re-verify ownership after acquiring the lock. If the
                 // marker was stolen between tryAcquire and this check, release the
                 // just-acquired lock and return null (fail-closed).
                 if (!(await ownsEvictionMarker())) {
-                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    await relinquishLockAfterMarkerLoss();
                     acquired = false;
                     return null;
                 }
@@ -429,10 +471,7 @@ export async function acquireRefreshFileLock(options) {
         },
         release: async () => {
             released = true;
-            if (renewTimer) {
-                clearRefreshLockRenewalTimeout(renewTimer);
-                renewTimer = null;
-            }
+            cancelRenewalTimer();
             await renewalInFlight;
             for (let attempt = 0; attempt < MAX_STEAL_ATTEMPTS; attempt++) {
                 try {

package/dist/rpc/rpc-server.js

@@ -24,20 +24,29 @@ export class RpcRequestError extends Error {
 const MAX_BODY_BYTES = 1_000_000;
 /** The request body exceeded the cap; answered 413. */
 class BodyTooLargeError extends Error {
+    declaredOversize;
+    constructor(declaredOversize) {
+        super('body too large');
+        this.declaredOversize = declaredOversize;
+    }
 }
 function readBody(req) {
     return new Promise((resolve, reject) => {
-        const tooLarge = () => {
-            // Keep reading and discarding the rest, so the client finishes sending
-            // and can read the 413 instead of seeing a reset connection.
+        const tooLarge = (declaredOversize = false) => {
+            // Streamed overflow drains without closing at response finish: doing so
+            // caused EPIPE on a Bun 1.4.2 uploader. Declared oversize also drains, but
+            // half-closes after the 413: Bun 1.3.14 reused refused fetch connections
+            // despite Connection: close. Half-close preserved complete 413 JSON for
+            // tested fetch and slow declared-length uploaders on both runtimes (see
+            // research/load-probe/RPC-413-CLOSE.md for the delivery/lifecycle samples).
             req.removeAllListeners('data');
             req.on('data', () => { });
             req.resume();
-            reject(new BodyTooLargeError('body too large'));
+            reject(new BodyTooLargeError(declaredOversize));
         };
         const declared = Number(req.headers['content-length']);
         if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
-            tooLarge();
+            tooLarge(true);
             return;
         }
         const chunks = [];
@@ -133,8 +142,21 @@ export async function startRpcServer(options) {
             catch (error) {
                 if (!(error instanceof BodyTooLargeError))
                     throw error;
-                // Close the connection after answering: the rest of the oversized
-                // body is not worth keeping the socket for.
+                if (error.declaredOversize) {
+                    const socket = req.socket;
+                    res.once('finish', () => {
+                        socket.end();
+                        // Bound an abandoned upload to two seconds, matching the server's
+                        // default request-delivery timeout. end() alone left Bun 1.3.14
+                        // compatibility sockets open.
+                        const timer = setTimeout(() => socket.destroy(), 2_000);
+                        timer.unref();
+                        req.once('end', () => socket.destroy());
+                        socket.once('close', () => clearTimeout(timer));
+                        if (req.complete)
+                            socket.destroy();
+                    });
+                }
                 return json(413, { error: 'body too large' }, { connection: 'close' });
             }
             let params;

package/dist/store/refresh-lock.d.ts

@@ -19,7 +19,7 @@ export interface PoolLockSpec extends Partial<PoolLockOptions> {
  */
 export declare const POOL_LOCK_DEFAULTS: Readonly<PoolLockOptions>;
 export type LockEvent = {
-    type: 'acquired' | 'released';
+    type: 'acquired' | 'released' | 'contended';
     name: string;
     path: string;
 };

package/dist/store/refresh-lock.js

@@ -17,6 +17,24 @@ export const POOL_LOCK_DEFAULTS = Object.freeze({
  * expired during the wait.
  */
 export async function acquirePoolLock(spec, defaults, env) {
+    const emit = (type) => {
+        try {
+            const result = env.onLockEvent?.({
+                type,
+                name: spec.name,
+                path: spec.path,
+            });
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Lock observers must not affect acquisition or release.
+        }
+    };
     const options = { ...defaults, ...definedOnly(spec) };
     const started = performance.now();
     for (;;) {
@@ -26,6 +44,7 @@ export async function acquirePoolLock(spec, defaults, env) {
             ttlMs: options.ttlMs,
             now: env.now,
             renew: options.renew,
+            onContended: () => emit('contended'),
             ...(options.renewIntervalMs !== undefined
                 ? { renewIntervalMs: options.renewIntervalMs }
                 : {}),
@@ -36,22 +55,14 @@ export async function acquirePoolLock(spec, defaults, env) {
                 : {}),
         });
         if (lock) {
-            env.onLockEvent?.({
-                type: 'acquired',
-                name: spec.name,
-                path: spec.path,
-            });
+            emit('acquired');
             const held = {
                 name: spec.name,
                 path: spec.path,
                 assertOwned: () => lock.assertOwned(),
                 release: async () => {
                     await lock.release();
-                    env.onLockEvent?.({
-                        type: 'released',
-                        name: spec.name,
-                        path: spec.path,
-                    });
+                    emit('released');
                 },
             };
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {
@@ -85,7 +85,7 @@
     "dist/"
   ],
   "scripts": {
-    "build": "bun scripts/check-installed-ranges.mjs && tsc -p tsconfig.build.json",
+    "build": "bun scripts/check-local-deps.mjs && bun scripts/check-installed-ranges.mjs && tsc -p tsconfig.build.json",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "types": "bun run typecheck",
@@ -94,7 +94,7 @@
     "lint": "biome check .",
     "prepublishOnly": "bun run build",
     "check:ranges": "bun scripts/check-installed-ranges.mjs",
-    "check:claustrum-040": "bun scripts/check-claustrum-040.mjs",
+    "check:claustrum-floor": "bun scripts/check-claustrum-floor.mjs",
     "check:opentui-0511": "bun scripts/check-opentui-0511.mjs"
   },
   "dependencies": {
@@ -104,7 +104,7 @@
     "@opentui/core": ">=0.5.11",
     "@opentui/solid": ">=0.5.11",
     "solid-js": "1.9.12",
-    "@cortexkit/claustrum-client": ">=0.4.0",
+    "@cortexkit/claustrum-client": ">=0.6.2",
     "@opencode/plugin": ">=2.0.21"
   },
   "peerDependenciesMeta": {
@@ -126,7 +126,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
-    "@cortexkit/claustrum-client": "0.5.0",
+    "@cortexkit/claustrum-client": "0.6.2",
     "@opencode/plugin": "2.0.21",
     "@opentui/core": ">=0.5.12",
     "@opentui/solid": ">=0.5.12",