@cortexkit/anthropic-auth-core 1.22.0 → 1.23.0

package/dist/claustrum.js

@@ -1,10 +1,101 @@
-import { readFile } from 'node:fs/promises';
-import { userInfo } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants, readdirSync, statSync, } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
 import { SubcCallError, SubcClient, } from '@cortexkit/subc-client';
+import { CUSTODY_HANDLE_PATTERN } from './constants.js';
+import { parseJsonRedacted } from './json';
 import { logger } from './logger';
-export function getDefaultClaustrumConnectionPath() {
+export const PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME = 'subc-connection.json';
+const CLAUSTRUM_TEMP_PREFIX = 'subc-';
+const CLAUSTRUM_TEMP_SUFFIX = '.connection.json';
+function safeIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function listSubcTempConnectionFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    for (const name of entries) {
+        if (typeof name !== 'string')
+            continue;
+        if (!name.startsWith(CLAUSTRUM_TEMP_PREFIX) ||
+            !name.endsWith(CLAUSTRUM_TEMP_SUFFIX)) {
+            continue;
+        }
+        const candidate = join(dir, name);
+        if (safeIsFile(candidate))
+            matches.push(candidate);
+    }
+    matches.sort();
+    return matches;
+}
+export function findExistingClaustrumConnectionPath(env = process.env) {
+    const runtime = env.XDG_RUNTIME_DIR?.trim();
+    if (runtime) {
+        const candidate = join(runtime, PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME);
+        if (safeIsFile(candidate))
+            return candidate;
+    }
+    const home = env.HOME?.trim();
+    if (home) {
+        const candidate = join(home, '.local', 'share', 'cortexkit', 'run', PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME);
+        if (safeIsFile(candidate))
+            return candidate;
+    }
     const uid = process.getuid?.() ?? userInfo().uid;
-    return `/run/user/${uid}/subc-connection.json`;
+    const linuxRun = `/run/user/${uid}/${PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME}`;
+    if (safeIsFile(linuxRun))
+        return linuxRun;
+    const tempMatches = listSubcTempConnectionFiles(tmpdir());
+    if (tempMatches.length === 1)
+        return tempMatches[0];
+    return undefined;
+}
+export function getDefaultClaustrumConnectionPath(env = process.env) {
+    const existing = findExistingClaustrumConnectionPath(env);
+    if (existing)
+        return existing;
+    const runtime = env.XDG_RUNTIME_DIR?.trim();
+    if (runtime && (process.platform !== 'darwin' || safeIsFile(runtime))) {
+        return join(runtime, PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME);
+    }
+    if (process.platform === 'darwin') {
+        const home = env.HOME?.trim() || userInfo().homedir;
+        return join(home, '.local', 'share', 'cortexkit', 'run', PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME);
+    }
+    const uid = process.getuid?.() ?? userInfo().uid;
+    return `/run/user/${uid}/${PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME}`;
+}
+export function resolveClaustrumConnectionPath(explicit, env = process.env) {
+    return (explicit?.trim() ||
+        env.OPENCODE_ANTHROPIC_AUTH_CLAUSTRUM_CONNECTION_FILE?.trim() ||
+        env.CLAUSTRUM_SUBC_CONNECTION?.trim() ||
+        getDefaultClaustrumConnectionPath(env));
+}
+export function resolveCustodyHandlesPath(config, env) {
+    const configuredPath = config?.handlesFile?.trim();
+    if (configuredPath)
+        return configuredPath;
+    const environmentPath = env.CLAUSTRUM_OPENCODE_HANDLES;
+    if (environmentPath && isAbsolute(environmentPath))
+        return environmentPath;
+    const configHome = env.XDG_CONFIG_HOME?.trim() || join(env.HOME || homedir(), '.config');
+    return join(configHome, 'cortexkit', 'opencode-handles.json');
+}
+export function getDefaultClaustrumHandlesPath() {
+    return resolveCustodyHandlesPath(undefined, process.env);
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -18,19 +109,20 @@ function isEndpoint(value) {
         value.port > 0 &&
         value.port <= 65_535);
 }
-export async function detectClaustrumConnection(path = getDefaultClaustrumConnectionPath()) {
+export async function detectClaustrumConnection(explicitPath) {
+    const path = resolveClaustrumConnectionPath(explicitPath);
     let raw;
     try {
-        raw = await readFile(path, 'utf8');
+        raw = await fs.readFile(path, 'utf8');
     }
     catch (error) {
-        const code = error.code;
+        const code = errorCode(error);
         if (code === 'ENOENT')
             return { status: 'absent', path };
         return {
             status: 'malformed',
             path,
-            reason: `unreadable (${code ?? 'unknown'})`,
+            reason: `unreadable (${code})`,
         };
     }
     let value;
@@ -72,14 +164,22 @@ export const CUSTODY_TOMBSTONE_PREFIX = 'claustrum-tombstone:v1:';
 export function custodyTombstoneKey(provider) {
     return `${CUSTODY_TOMBSTONE_PREFIX}${provider}`;
 }
+export function custodyTombstoneOAuth(provider) {
+    // An empty access value makes Claustrum's deployed sealer reject this loader marker.
+    return {
+        type: 'oauth',
+        access: '',
+        refresh: custodyTombstoneKey(provider),
+        expires: 0,
+    };
+}
 export function isCustodyTombstoneValue(value) {
     return typeof value === 'string' && value.startsWith(CUSTODY_TOMBSTONE_PREFIX);
 }
 export function isCustodyTombstoneOAuth(auth, provider) {
     if (!isRecord(auth) || auth.type !== 'oauth')
         return false;
-    const key = custodyTombstoneKey(provider);
-    return auth.refresh === key && auth.access === key;
+    return auth.refresh === custodyTombstoneKey(provider);
 }
 export class CustodyTombstoneRefreshError extends Error {
     provider;
@@ -90,16 +190,24 @@ export class CustodyTombstoneRefreshError extends Error {
         this.name = 'CustodyTombstoneRefreshError';
     }
 }
+export class CustodyTombstoneLoginError extends Error {
+    provider;
+    code = 'custody_tombstone_login';
+    constructor(provider) {
+        super(`${provider} main slot is custodied; run /login to sign in locally`);
+        this.provider = provider;
+        this.name = 'CustodyTombstoneLoginError';
+    }
+}
 export function assertNotCustodyTombstone(refreshToken, provider) {
     if (isCustodyTombstoneValue(refreshToken)) {
         throw new CustodyTombstoneRefreshError(provider);
     }
 }
 const CUSTODY_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-// The suffix is base64url for 256 CSPRNG bits; its charset is not fixture-derived.
-const CUSTODY_HANDLE_PATTERN = /^ckh_[A-Za-z0-9_-]{43}$/;
 const RESERVED_CUSTODY_IDS = new Set(['__proto__', 'constructor', 'prototype']);
-function isCustodyId(value) {
+const CUSTODY_CREDENTIAL_PREFIX = 'oauth:anthropic:';
+export function isValidCustodyLabel(value) {
     return (typeof value === 'string' &&
         CUSTODY_ID_PATTERN.test(value) &&
         !RESERVED_CUSTODY_IDS.has(value));
@@ -107,43 +215,867 @@ function isCustodyId(value) {
 export function isValidCustodyHandle(value) {
     return typeof value === 'string' && CUSTODY_HANDLE_PATTERN.test(value);
 }
-export function readCustodyHandles(json, provider) {
-    if (!isCustodyId(provider)) {
-        throw new Error(`Invalid custody provider id ${provider}`);
+export function custodyCredentialId(label) {
+    if (!isValidCustodyLabel(label))
+        throw new CustodyManifestSelectionError('invalid-label');
+    return `${CUSTODY_CREDENTIAL_PREFIX}${label}`;
+}
+// A resolved MANIFEST binding carries the credential id verbatim (the parser
+// stores it as-written and the resolver returns it; round 2 dropped the
+// parse-time derivation check). Anything else — legacy source, unresolved,
+// or a manifest entry whose id happens to be undefined — derives from the
+// label, the only id the caller can construct without a binding in hand.
+// Callers building completion records (local-exit, reachability probe)
+// pass this single rule instead of inlining it.
+export function custodyCredentialIdFromResolution(resolution, label) {
+    if (resolution.status === 'resolved' && resolution.source === 'manifest') {
+        return resolution.credentialId ?? custodyCredentialId(label);
+    }
+    return custodyCredentialId(label);
+}
+function isValidCustodyCredentialId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+// The manifest is a co-tenant file: a sibling plugin (`provider: 'openai'`,
+// `serve: 'openai-auth'`) writes its own block in the same file. Provider
+// scoping is what stops us from binding its handles — the parser has to
+// enforce it because the sibling plugin never talks to us.
+//
+// Scope on the SECOND colon-separated segment (the provider segment). The
+// first segment is a "kind" prefix the vault owner extends (`oauth:`,
+// `chatgpt:`, `antigravity:`, `apikey:`, …) and the rule deliberately does
+// NOT enumerate or constrain it: enumerating the kinds would reject live
+// credentials the moment a new one ships. The third-and-later segments are
+// the label, which is never consulted here — the label is the lookup key
+// elsewhere, not an authorization check.
+function isScopedCustodyCredentialId(value, provider) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    const segments = value.split(':');
+    return segments[1] === provider;
+}
+function legacyOrUnresolved(account, reason) {
+    if (account.claustrumHandle) {
+        return {
+            status: 'resolved',
+            source: 'legacy',
+            handle: account.claustrumHandle,
+        };
+    }
+    return { status: 'unresolved', reason };
+}
+/**
+ * | manifest state | legacy handle | result |
+ * | --- | --- | --- |
+ * | matching ready entry | any | manifest handle |
+ * | absent or invalid | present | legacy handle |
+ * | no matching ready entry | present | legacy handle |
+ * | foreign serve | any | unresolved |
+ * | superseded matching entry | any | unresolved |
+ */
+export function resolveCustodyHandle(input) {
+    const { account, manifest, duplicateOAuthLabels } = input;
+    if (manifest && manifest.serve !== 'anthropic-auth') {
+        return { status: 'unresolved', reason: 'foreign-serve' };
+    }
+    if (!account.label)
+        return legacyOrUnresolved(account, 'missing-label');
+    if (!isValidCustodyLabel(account.label)) {
+        return legacyOrUnresolved(account, 'invalid-label');
+    }
+    if (duplicateOAuthLabels?.has(account.label)) {
+        return legacyOrUnresolved(account, 'duplicate-label');
+    }
+    if (!manifest)
+        return legacyOrUnresolved(account, 'missing-entry');
+    if (manifest.corruptLabels?.has(account.label)) {
+        return { status: 'unresolved', reason: 'corrupt-binding' };
+    }
+    // The manifest carries the credential id verbatim; the runtime fence in
+    // custody-mode.ts is the one that compares it against vault ground truth.
+    const entry = manifest.accounts.find((candidate) => candidate.label === account.label);
+    if (!entry)
+        return legacyOrUnresolved(account, 'missing-entry');
+    if (manifest.superseded.has(entry.handle)) {
+        return { status: 'unresolved', reason: 'superseded' };
+    }
+    return {
+        status: 'resolved',
+        source: 'manifest',
+        handle: entry.handle,
+        credentialId: entry.credentialId,
+    };
+}
+export function readCustodyHandles(json, provider, serve) {
+    if (!isValidCustodyLabel(provider)) {
+        throw new Error('invalid manifest provider');
+    }
+    if (!isRecord(json) ||
+        !Object.hasOwn(json, 'version') ||
+        json.version !== 1) {
+        throw new Error('invalid manifest version');
     }
-    const providers = isRecord(json) && Array.isArray(json.providers) ? json.providers : [];
-    const source = providers.find((entry) => isRecord(entry) &&
+    if (!Object.hasOwn(json, 'providers') || !Array.isArray(json.providers)) {
+        throw new Error('missing manifest providers');
+    }
+    const providerEntries = json.providers.filter((entry) => isRecord(entry) &&
         Object.hasOwn(entry, 'provider') &&
         entry.provider === provider);
-    if (!source || !Array.isArray(source.accounts)) {
-        throw new Error(`Missing custody handles for provider ${provider}`);
+    if (providerEntries.length === 0) {
+        throw new CustodyManifestSelectionError('missing-provider');
+    }
+    const source = providerEntries.find((entry) => Object.hasOwn(entry, 'serve') && entry.serve === serve);
+    if (!source)
+        throw new CustodyManifestSelectionError('foreign-serve');
+    if (!Object.hasOwn(source, 'accounts') || !Array.isArray(source.accounts)) {
+        throw new Error('invalid manifest accounts');
+    }
+    // The label is the sole lookup key; two entries with the same label cannot
+    // tell the resolver which one to bind, so every such entry is marked corrupt
+    // rather than silently picking a winner.
+    const labelCounts = new Map();
+    for (const candidate of source.accounts) {
+        if (!isRecord(candidate) ||
+            !Object.hasOwn(candidate, 'label') ||
+            typeof candidate.label !== 'string' ||
+            !isValidCustodyLabel(candidate.label))
+            continue;
+        labelCounts.set(candidate.label, (labelCounts.get(candidate.label) ?? 0) + 1);
+    }
+    const duplicateLabels = new Set([...labelCounts].filter(([, count]) => count > 1).map(([label]) => label));
+    const superseded = new Set();
+    const corruptLabels = new Set();
+    const accounts = [];
+    for (const entry of source.accounts) {
+        if (!isRecord(entry))
+            throw new Error('invalid account entry');
+        if (!Object.hasOwn(entry, 'label') || typeof entry.label !== 'string') {
+            throw new Error('invalid account label');
+        }
+        if (!isValidCustodyLabel(entry.label)) {
+            throw new Error('invalid account label');
+        }
+        if (!Object.hasOwn(entry, 'handle') ||
+            !Object.hasOwn(entry, 'credential_id') ||
+            typeof entry.handle !== 'string' ||
+            !isValidCustodyHandle(entry.handle) ||
+            !isScopedCustodyCredentialId(entry.credential_id, provider)) {
+            corruptLabels.add(entry.label);
+            continue;
+        }
+        if (duplicateLabels.has(entry.label)) {
+            corruptLabels.add(entry.label);
+            continue;
+        }
+        if (Object.hasOwn(entry, 'superseded')) {
+            if (!Array.isArray(entry.superseded)) {
+                corruptLabels.add(entry.label);
+                continue;
+            }
+            let malformed = false;
+            for (const handle of entry.superseded) {
+                if (!isValidCustodyHandle(handle)) {
+                    malformed = true;
+                    break;
+                }
+            }
+            if (malformed) {
+                corruptLabels.add(entry.label);
+                continue;
+            }
+            for (const handle of entry.superseded)
+                superseded.add(handle);
+        }
+        accounts.push({
+            label: entry.label,
+            handle: entry.handle,
+            credentialId: entry.credential_id,
+        });
     }
     return {
-        provider: String(source.provider),
-        serve: String(source.serve),
-        shape: String(source.shape),
-        accounts: source.accounts.flatMap((entry) => {
-            if (!isRecord(entry))
-                return [];
-            if (!Object.hasOwn(entry, 'label') ||
-                !Object.hasOwn(entry, 'handle') ||
-                !Object.hasOwn(entry, 'credential_id') ||
-                typeof entry.label !== 'string' ||
-                typeof entry.handle !== 'string' ||
-                !isCustodyId(entry.label) ||
-                !isValidCustodyHandle(entry.handle) ||
-                typeof entry.credential_id !== 'string')
-                return [];
-            return [
-                {
-                    label: entry.label,
-                    handle: entry.handle,
-                    credentialId: entry.credential_id,
-                },
-            ];
-        }),
+        version: 1,
+        provider,
+        serve,
+        accounts,
+        superseded,
+        corruptLabels,
     };
 }
+export const CUSTODY_MANIFEST_SELECTION_ERROR_CODES = [
+    'foreign-serve',
+    'invalid-label',
+    'missing-provider',
+];
+export class CustodyManifestSelectionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const MAX_CUSTODY_MANIFEST_BYTES = 256 * 1024;
+function errorCode(error) {
+    const code = error.code;
+    return typeof code === 'string' ? code : 'unknown';
+}
+function validateManifestFile(stats, expectedUid) {
+    const mode = Number(stats.mode);
+    if (stats.isSymbolicLink())
+        return 'manifest is a symlink';
+    if (!stats.isFile())
+        return 'manifest is not a regular file';
+    if ((mode & 0o777) !== 0o600)
+        return 'manifest mode must be 0600';
+    if (stats.uid !== expectedUid)
+        return 'manifest owner does not match';
+    return null;
+}
+function validateManifestParent(stats, expectedUid) {
+    const mode = Number(stats.mode);
+    if (stats.uid !== expectedUid)
+        return 'manifest parent owner does not match';
+    if ((mode & 0o1000) !== 0)
+        return null;
+    if ((mode & 0o002) !== 0) {
+        return 'manifest parent is world-writable';
+    }
+    if ((mode & 0o020) !== 0)
+        return 'manifest parent is group-writable';
+    return null;
+}
+export class CustodyHandleManifestReader {
+    #cache;
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    async read() {
+        const expectedUid = this.#options.expectedUid ?? process.getuid?.() ?? userInfo().uid;
+        let pathStats;
+        try {
+            pathStats = await fs.lstat(this.#options.path);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return { status: 'absent' };
+            return { status: 'invalid', reason: `unreadable (${errorCode(error)})` };
+        }
+        const fileReason = validateManifestFile(pathStats, expectedUid);
+        if (fileReason)
+            return { status: 'invalid', reason: fileReason };
+        try {
+            const parentReason = validateManifestParent(await fs.lstat(dirname(this.#options.path)), expectedUid);
+            if (parentReason)
+                return { status: 'invalid', reason: parentReason };
+        }
+        catch (error) {
+            return { status: 'invalid', reason: `unreadable (${errorCode(error)})` };
+        }
+        let handle;
+        try {
+            handle = await fs.open(this.#options.path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+            // The validated descriptor, not the path, is the authority for content and metadata after open.
+            const openedStats = await handle.stat();
+            const openedFileReason = validateManifestFile(openedStats, expectedUid);
+            if (openedFileReason)
+                return { status: 'invalid', reason: openedFileReason };
+            if (this.#cache?.mtimeMs === openedStats.mtimeMs &&
+                this.#cache.size === openedStats.size) {
+                return this.#cache.result;
+            }
+            const bytes = new Uint8Array(MAX_CUSTODY_MANIFEST_BYTES + 1);
+            const { bytesRead } = await handle.read(bytes, 0, bytes.byteLength, 0);
+            if (bytesRead > MAX_CUSTODY_MANIFEST_BYTES) {
+                return { status: 'invalid', reason: 'manifest exceeds maximum size' };
+            }
+            let json;
+            try {
+                json = parseJsonRedacted(new TextDecoder().decode(bytes.subarray(0, bytesRead)));
+            }
+            catch (error) {
+                return {
+                    status: 'invalid',
+                    reason: error instanceof Error ? error.message : 'invalid JSON',
+                };
+            }
+            let parsed;
+            try {
+                parsed = readCustodyHandles(json, this.#options.provider, this.#options.serve);
+            }
+            catch (error) {
+                if (error instanceof CustodyManifestSelectionError) {
+                    if (error.code !== 'invalid-label') {
+                        const result = { status: 'ignored', reason: error.code };
+                        this.#cache = {
+                            mtimeMs: openedStats.mtimeMs,
+                            size: openedStats.size,
+                            result,
+                        };
+                        return result;
+                    }
+                }
+                return {
+                    status: 'invalid',
+                    reason: error instanceof Error ? error.message : 'invalid manifest',
+                };
+            }
+            const manifest = {
+                version: parsed.version,
+                provider: this.#options.provider,
+                serve: this.#options.serve,
+                accounts: parsed.accounts,
+                superseded: parsed.superseded,
+                corruptLabels: parsed.corruptLabels,
+            };
+            const result = { status: 'ready', manifest };
+            this.#cache = {
+                mtimeMs: openedStats.mtimeMs,
+                size: openedStats.size,
+                result,
+            };
+            return result;
+        }
+        catch (error) {
+            return { status: 'invalid', reason: `unreadable (${errorCode(error)})` };
+        }
+        finally {
+            await handle?.close().catch(() => { });
+        }
+    }
+}
+export const CUSTODY_MANIFEST_LOCK_TTL_MS = 30_000;
+export const CUSTODY_MANIFEST_LOCK_RENEW_MS = 10_000;
+export const CUSTODY_MANIFEST_LOCK_RETRY_MIN_MS = 50;
+export const CUSTODY_MANIFEST_LOCK_RETRY_MAX_MS = 150;
+const CUSTODY_MANIFEST_STALE_LOCK_REAP_AGE_MS = 24 * 60 * 60 * 1000;
+const CUSTODY_MANIFEST_STALE_LOCK_REAP_LIMIT = 32;
+let custodyManifestLockTestOptions;
+export function __setCustodyManifestLockTestOptions(options) {
+    custodyManifestLockTestOptions = options;
+}
+export const CUSTODY_MANIFEST_LOCK_ERROR_CODES = [
+    'lock_busy',
+    'owner_invalid',
+    'renewal_failed',
+];
+export class CustodyManifestLockError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class CustodyManifestLockBusyError extends CustodyManifestLockError {
+    constructor(message) {
+        super(message, 'lock_busy');
+    }
+}
+export class CustodyManifestLockOwnerInvalidError extends CustodyManifestLockError {
+    constructor(message) {
+        super(message, 'owner_invalid');
+    }
+}
+export class CustodyManifestLockLeaseLostError extends CustodyManifestLockError {
+    constructor(message) {
+        super(message, 'renewal_failed');
+    }
+}
+function isEvictableCustodyManifestLockNonce(nonce) {
+    // An allowlist freezes lock compatibility across independently upgrading readers;
+    // reject only unsafe characters so a widened nonce cannot wedge an older reader.
+    for (const character of nonce) {
+        const code = character.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return (nonce.length > 0 &&
+        nonce.length <= 128 &&
+        nonce !== '.' &&
+        nonce !== '..' &&
+        !/[\\/:*?"<>|]/.test(nonce) &&
+        !/[. ]$/.test(nonce));
+}
+export function __deriveCustodyManifestStaleLockPrefix(lockPath, pathBasename) {
+    return `${pathBasename(lockPath)}.stale-`;
+}
+async function reapStaleCustodyManifestLocks(lockPath) {
+    const parent = dirname(lockPath);
+    const prefix = __deriveCustodyManifestStaleLockPrefix(lockPath, basename);
+    let entries;
+    try {
+        entries = await fs.readdir(parent, { withFileTypes: true });
+    }
+    catch (error) {
+        logger.debug('claustrum', 'stale manifest lock reaper failed', {
+            error: errorCode(error),
+        });
+        return;
+    }
+    let reaped = 0;
+    for (const entry of entries) {
+        if (reaped >= CUSTODY_MANIFEST_STALE_LOCK_REAP_LIMIT)
+            return;
+        if (!entry.isDirectory() || !entry.name.startsWith(prefix))
+            continue;
+        const quarantinePath = join(parent, entry.name);
+        try {
+            const stat = await fs.lstat(quarantinePath);
+            if (!stat.isDirectory() ||
+                Date.now() - stat.mtimeMs < CUSTODY_MANIFEST_STALE_LOCK_REAP_AGE_MS) {
+                continue;
+            }
+            await fs.rm(quarantinePath, { recursive: true, force: true });
+            reaped += 1;
+        }
+        catch (error) {
+            logger.debug('claustrum', 'stale manifest lock reaper failed', {
+                error: errorCode(error),
+            });
+        }
+    }
+}
+export async function withCustodyManifestLock(path, fn) {
+    const lockPath = `${path}.lock`;
+    const now = custodyManifestLockTestOptions?.now ?? Date.now;
+    const setIntervalImpl = custodyManifestLockTestOptions?.setIntervalImpl ?? globalThis.setInterval;
+    const clearIntervalImpl = custodyManifestLockTestOptions?.clearIntervalImpl ??
+        globalThis.clearInterval;
+    const ttlMs = custodyManifestLockTestOptions?.ttlMs ?? CUSTODY_MANIFEST_LOCK_TTL_MS;
+    const retryMinMs = custodyManifestLockTestOptions?.retryMinMs ??
+        CUSTODY_MANIFEST_LOCK_RETRY_MIN_MS;
+    const retryMaxMs = custodyManifestLockTestOptions?.retryMaxMs ??
+        CUSTODY_MANIFEST_LOCK_RETRY_MAX_MS;
+    const startedAt = now();
+    const nonce = randomUUID();
+    const ownerPath = join(lockPath, 'owner');
+    async function writeOwner(claimedAtMs) {
+        const temporaryOwnerPath = join(lockPath, `owner.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await fs.open(temporaryOwnerPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+            await handle.writeFile(`${JSON.stringify({
+                tenant: 'anthropic-auth',
+                pid: process.pid,
+                claimed_at_ms: claimedAtMs,
+                nonce,
+            })}\n`);
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await fs.rename(temporaryOwnerPath, ownerPath);
+        }
+        finally {
+            await handle?.close().catch(() => { });
+            await fs.unlink(temporaryOwnerPath).catch(() => { });
+        }
+    }
+    async function claim() {
+        try {
+            await fs.mkdir(lockPath, { mode: 0o700 });
+        }
+        catch (error) {
+            if (errorCode(error) !== 'EEXIST')
+                throw error;
+            return false;
+        }
+        try {
+            await writeOwner(now());
+        }
+        catch (error) {
+            await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+            throw error;
+        }
+        return true;
+    }
+    const deadline = startedAt + ttlMs;
+    let claimed = false;
+    while (!claimed) {
+        claimed = await claim();
+        if (claimed)
+            break;
+        let ownerClaimedAtMs;
+        let ownerNonce;
+        let ownerInvalid = false;
+        try {
+            const owner = JSON.parse(await fs.readFile(ownerPath, 'utf8'));
+            if (isRecord(owner) &&
+                typeof owner.claimed_at_ms === 'number' &&
+                Number.isFinite(owner.claimed_at_ms) &&
+                typeof owner.nonce === 'string' &&
+                isEvictableCustodyManifestLockNonce(owner.nonce)) {
+                ownerClaimedAtMs = owner.claimed_at_ms;
+                ownerNonce = owner.nonce;
+                await custodyManifestLockTestOptions?.afterStaleOwnerRead?.();
+            }
+            else
+                ownerInvalid = true;
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT')
+                ownerInvalid = true;
+        }
+        if (ownerClaimedAtMs !== undefined &&
+            ownerNonce !== undefined &&
+            now() - ownerClaimedAtMs >= ttlMs) {
+            const claimedPath = `${lockPath}.stale-${ownerClaimedAtMs}-${ownerNonce}`;
+            try {
+                await fs.rename(lockPath, claimedPath);
+            }
+            catch (error) {
+                if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(errorCode(error)))
+                    throw error;
+            }
+            continue;
+        }
+        if (now() >= deadline && ownerInvalid)
+            throw new CustodyManifestLockOwnerInvalidError('manifest lock owner invalid');
+        if (now() >= deadline)
+            throw new CustodyManifestLockBusyError('manifest lock busy');
+        const retryMs = retryMinMs + Math.floor(Math.random() * (retryMaxMs - retryMinMs + 1));
+        await new Promise((resolve) => setTimeout(resolve, Math.min(retryMs, Math.max(1, deadline - now()))));
+    }
+    let renewalFailed = false;
+    let renewalInFlight;
+    async function ownsCurrentLease() {
+        if (renewalFailed)
+            return false;
+        try {
+            const owner = JSON.parse(await fs.readFile(ownerPath, 'utf8'));
+            return (isRecord(owner) &&
+                owner.pid === process.pid &&
+                owner.nonce === nonce &&
+                typeof owner.claimed_at_ms === 'number' &&
+                Number.isFinite(owner.claimed_at_ms) &&
+                now() - owner.claimed_at_ms < ttlMs);
+        }
+        catch {
+            return false;
+        }
+    }
+    async function assertLease() {
+        await renewalInFlight;
+        if (!(await ownsCurrentLease()))
+            throw new CustodyManifestLockLeaseLostError('manifest lock renewal failed; write aborted');
+    }
+    const renewal = setIntervalImpl(() => {
+        renewalInFlight = writeOwner(now()).catch(() => {
+            renewalFailed = true;
+        });
+    }, custodyManifestLockTestOptions?.renewalIntervalMs ??
+        Math.min(CUSTODY_MANIFEST_LOCK_RENEW_MS, Math.floor(ttlMs / 3)));
+    if ('unref' in renewal)
+        renewal.unref();
+    try {
+        return await fn(assertLease, nonce);
+    }
+    finally {
+        clearIntervalImpl(renewal);
+        if (!(await ownsCurrentLease())) {
+            logger.warn('claustrum', 'manifest lock lease lost, not releasing', {
+                id: path,
+            });
+        }
+        else {
+            await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+        }
+        await reapStaleCustodyManifestLocks(lockPath);
+    }
+}
+function refusal(reason, code) {
+    return code === undefined
+        ? { status: 'refused', reason }
+        : { status: 'refused', reason, code };
+}
+function isOurManifestBlock(value) {
+    return (isRecord(value) &&
+        value.provider === 'anthropic' &&
+        value.serve === 'anthropic-auth');
+}
+export async function writeCustodyHandleManifestEntry(input) {
+    if (!isValidCustodyLabel(input.entry.label) ||
+        !isValidCustodyHandle(input.entry.handle) ||
+        !isScopedCustodyCredentialId(input.entry.credentialId, 'anthropic')) {
+        return refusal('invalid entry');
+    }
+    try {
+        return await withCustodyManifestLock(input.path, (assertLease, nonce) => writeCustodyHandleManifestEntryLocked(input, assertLease, nonce));
+    }
+    catch (error) {
+        if (error instanceof CustodyManifestLockBusyError) {
+            return refusal('manifest lock busy', error.code);
+        }
+        if (error instanceof CustodyManifestLockOwnerInvalidError) {
+            return refusal('manifest lock owner invalid', error.code);
+        }
+        if (error instanceof CustodyManifestLockLeaseLostError) {
+            return refusal('manifest lock renewal failed; write aborted', error.code);
+        }
+        return refusal(`unreadable (${errorCode(error)})`);
+    }
+}
+export async function removeCustodyHandleManifestEntry(input) {
+    if (!isValidCustodyLabel(input.entry.label) ||
+        !isValidCustodyHandle(input.entry.handle) ||
+        !isValidCustodyCredentialId(input.entry.credentialId)) {
+        return { status: 'refused' };
+    }
+    try {
+        const result = await withCustodyManifestLock(input.path, async (assertLease, nonce) => {
+            const expectedUid = input.expectedUid ?? process.getuid?.() ?? userInfo().uid;
+            const parent = dirname(input.path);
+            try {
+                const parentReason = validateManifestParent(await fs.lstat(parent), expectedUid);
+                if (parentReason)
+                    return 'refused';
+            }
+            catch (error) {
+                return errorCode(error) === 'ENOENT' ? 'missing' : 'refused';
+            }
+            let document;
+            let handle;
+            try {
+                const pathStats = await fs.lstat(input.path);
+                const pathReason = validateManifestFile(pathStats, expectedUid);
+                if (pathReason)
+                    return 'refused';
+                handle = await fs.open(input.path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+                const openedReason = validateManifestFile(await handle.stat(), expectedUid);
+                if (openedReason)
+                    return 'refused';
+                const bytes = new Uint8Array(MAX_CUSTODY_MANIFEST_BYTES + 1);
+                const { bytesRead } = await handle.read(bytes, 0, bytes.byteLength, 0);
+                if (bytesRead > MAX_CUSTODY_MANIFEST_BYTES)
+                    return 'refused';
+                const parsed = parseJsonRedacted(new TextDecoder().decode(bytes.subarray(0, bytesRead)));
+                if (!isRecord(parsed) ||
+                    parsed.version !== 1 ||
+                    !Array.isArray(parsed.providers)) {
+                    return 'refused';
+                }
+                document = parsed;
+                if (parsed.providers.some(isOurManifestBlock)) {
+                    try {
+                        readCustodyHandles(parsed, 'anthropic', 'anthropic-auth');
+                    }
+                    catch {
+                        return 'refused';
+                    }
+                }
+            }
+            catch (error) {
+                if (errorCode(error) === 'ENOENT')
+                    return 'missing';
+                return 'refused';
+            }
+            finally {
+                await handle?.close().catch(() => { });
+            }
+            const providers = document.providers;
+            if (!Array.isArray(providers))
+                return 'refused';
+            const blockIndex = providers.findIndex(isOurManifestBlock);
+            if (blockIndex === -1)
+                return 'missing';
+            const block = providers[blockIndex];
+            if (!isOurManifestBlock(block) || !Array.isArray(block.accounts)) {
+                return 'refused';
+            }
+            const matchesEntry = (account) => isRecord(account) &&
+                account.label === input.entry.label &&
+                account.handle === input.entry.handle &&
+                account.credential_id === input.entry.credentialId;
+            const matchIndex = block.accounts.findIndex(matchesEntry);
+            if (matchIndex === -1)
+                return 'missing';
+            const accounts = block.accounts.filter((account) => !matchesEntry(account));
+            const serialized = JSON.stringify({
+                ...document,
+                providers: providers.map((provider, index) => index === blockIndex ? { ...block, accounts } : provider),
+            }, null, 2);
+            if (new TextEncoder().encode(serialized).byteLength >
+                MAX_CUSTODY_MANIFEST_BYTES) {
+                return 'refused';
+            }
+            const temporaryPath = join(`${input.path}.lock`, `manifest.${nonce}.tmp`);
+            let temporaryHandle;
+            try {
+                temporaryHandle = await fs.open(temporaryPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+                await temporaryHandle.writeFile(serialized);
+                await temporaryHandle.sync();
+                await temporaryHandle.close();
+                temporaryHandle = undefined;
+                await assertLease();
+                await custodyManifestLockTestOptions?.beforeRename?.();
+                try {
+                    await fs.rename(temporaryPath, input.path);
+                }
+                catch (error) {
+                    if (errorCode(error) === 'ENOENT')
+                        throw new CustodyManifestLockLeaseLostError('manifest lock renewal failed; write aborted');
+                    throw error;
+                }
+                return 'removed';
+            }
+            catch (error) {
+                if (error instanceof CustodyManifestLockLeaseLostError)
+                    throw error;
+                return 'refused';
+            }
+            finally {
+                await temporaryHandle?.close().catch(() => { });
+                await fs.unlink(temporaryPath).catch(() => { });
+            }
+        });
+        return result === 'refused' ? { status: 'refused' } : result;
+    }
+    catch (error) {
+        if (error instanceof CustodyManifestLockError) {
+            return { status: 'refused', code: error.code };
+        }
+        return { status: 'refused' };
+    }
+}
+export async function writeCustodyHandleManifestEntryLocked(input, assertLease, lockNonce) {
+    const expectedUid = input.expectedUid ?? process.getuid?.() ?? userInfo().uid;
+    const parent = dirname(input.path);
+    try {
+        const parentReason = validateManifestParent(await fs.lstat(parent), expectedUid);
+        if (parentReason)
+            return refusal(parentReason);
+    }
+    catch (error) {
+        return refusal(`unreadable (${errorCode(error)})`);
+    }
+    let document;
+    let corruptLabels = new Set();
+    let handle;
+    try {
+        const pathStats = await fs.lstat(input.path);
+        const pathReason = validateManifestFile(pathStats, expectedUid);
+        if (pathReason)
+            return refusal(pathReason);
+        handle = await fs.open(input.path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        const openedReason = validateManifestFile(await handle.stat(), expectedUid);
+        if (openedReason)
+            return refusal(openedReason);
+        const bytes = new Uint8Array(MAX_CUSTODY_MANIFEST_BYTES + 1);
+        const { bytesRead } = await handle.read(bytes, 0, bytes.byteLength, 0);
+        if (bytesRead > MAX_CUSTODY_MANIFEST_BYTES)
+            return refusal('manifest exceeds maximum size');
+        const parsed = parseJsonRedacted(new TextDecoder().decode(bytes.subarray(0, bytesRead)));
+        if (!isRecord(parsed) ||
+            parsed.version !== 1 ||
+            !Array.isArray(parsed.providers)) {
+            return refusal('invalid manifest');
+        }
+        document = parsed;
+        if (parsed.providers.some(isOurManifestBlock)) {
+            try {
+                corruptLabels = readCustodyHandles(parsed, 'anthropic', 'anthropic-auth').corruptLabels;
+            }
+            catch {
+                return refusal('invalid manifest');
+            }
+        }
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT') {
+            document = { version: 1, providers: [] };
+        }
+        else if (error instanceof SyntaxError) {
+            return refusal('invalid JSON');
+        }
+        else {
+            return refusal(`unreadable (${errorCode(error)})`);
+        }
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+    const providers = document.providers;
+    if (!Array.isArray(providers))
+        return refusal('invalid manifest');
+    const blockIndex = providers.findIndex(isOurManifestBlock);
+    let nextProviders;
+    if (blockIndex === -1) {
+        nextProviders = [
+            ...providers,
+            {
+                provider: 'anthropic',
+                shape: 'oauth',
+                serve: 'anthropic-auth',
+                accounts: [
+                    {
+                        label: input.entry.label,
+                        handle: input.entry.handle,
+                        credential_id: input.entry.credentialId,
+                    },
+                ],
+            },
+        ];
+    }
+    else {
+        const block = providers[blockIndex];
+        if (!isOurManifestBlock(block) || !Array.isArray(block.accounts))
+            return refusal('invalid manifest');
+        const matching = block.accounts.filter((account) => isRecord(account) && account.label === input.entry.label);
+        if (matching.length === 1 &&
+            matching[0]?.handle === input.entry.handle &&
+            matching[0]?.credential_id === input.entry.credentialId &&
+            block.shape === 'oauth' &&
+            !corruptLabels.has(input.entry.label)) {
+            return { status: 'unchanged' };
+        }
+        const replacement = {
+            ...(corruptLabels.has(input.entry.label)
+                ? {}
+                : (matching.find(isRecord) ?? {})),
+            label: input.entry.label,
+            handle: input.entry.handle,
+            credential_id: input.entry.credentialId,
+        };
+        const accounts = block.accounts.flatMap((account) => isRecord(account) && account.label === input.entry.label ? [] : [account]);
+        const firstMatch = block.accounts.findIndex((account) => isRecord(account) && account.label === input.entry.label);
+        accounts.splice(firstMatch === -1 ? accounts.length : firstMatch, 0, replacement);
+        nextProviders = providers.map((provider, index) => index === blockIndex ? { ...block, shape: 'oauth', accounts } : provider);
+    }
+    const serialized = JSON.stringify({ ...document, providers: nextProviders }, null, 2);
+    if (new TextEncoder().encode(serialized).byteLength > MAX_CUSTODY_MANIFEST_BYTES) {
+        return refusal('manifest exceeds maximum size');
+    }
+    // Eviction renames the lock directory, so its temp follows the evicted owner
+    // into quarantine instead of remaining able to overwrite a successor's manifest.
+    // Quarantine reclaim deletes the evicted temp; it contains ids, never secrets.
+    const temporaryPath = join(`${input.path}.lock`, `manifest.${lockNonce}.tmp`);
+    let temporaryHandle;
+    try {
+        temporaryHandle = await fs.open(temporaryPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+        await temporaryHandle.writeFile(serialized);
+        await temporaryHandle.sync();
+        await temporaryHandle.close();
+        temporaryHandle = undefined;
+        await assertLease();
+        await custodyManifestLockTestOptions?.beforeRename?.();
+        try {
+            await fs.rename(temporaryPath, input.path);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                throw new CustodyManifestLockLeaseLostError('manifest lock renewal failed; write aborted');
+            throw error;
+        }
+        return { status: 'written' };
+    }
+    catch (error) {
+        if (error instanceof CustodyManifestLockLeaseLostError)
+            throw error;
+        return refusal(`unreadable (${errorCode(error)})`);
+    }
+    finally {
+        await temporaryHandle?.close().catch(() => { });
+        await fs.unlink(temporaryPath).catch(() => { });
+    }
+}
 export class ClaustrumClient {
     #client;
     #connector;
@@ -159,7 +1091,7 @@ export class ClaustrumClient {
         this.#handshakeTimeoutMs = handshakeTimeoutMs;
     }
     static async connect(options = {}) {
-        const connectionFile = options.connectionFile ?? getDefaultClaustrumConnectionPath();
+        const connectionFile = options.connectionFile ?? resolveClaustrumConnectionPath();
         const connector = options.connector ??
             ((connectOptions) => SubcClient.connect(connectOptions));
         const client = await connector({
@@ -367,6 +1299,9 @@ function decodeCredentialGetResponse(response) {
         ...(typeof result?.account_id === 'string' && {
             accountId: result.account_id,
         }),
+        ...(typeof result?.credential_id === 'string' && {
+            credentialId: result.credential_id,
+        }),
     };
 }
 export class ClaustrumCredentialCache {
@@ -386,7 +1321,7 @@ export class ClaustrumCredentialCache {
             throw new RangeError('minTtlMs must be a non-negative safe integer');
         }
     }
-    async get(handle, minTtlMs = this.#minTtlMs) {
+    async get(handle, minTtlMs = this.#minTtlMs, options = {}) {
         if (!Number.isSafeInteger(minTtlMs) || minTtlMs < 0) {
             throw new RangeError('minTtlMs must be a non-negative safe integer');
         }
@@ -405,7 +1340,7 @@ export class ClaustrumCredentialCache {
         const pending = this.#inFlight.get(handle);
         if (pending)
             return pending;
-        const load = this.#load(handle, minTtlMs);
+        const load = this.#load(handle, minTtlMs, options.cacheIf);
         this.#inFlight.set(handle, load);
         try {
             return await load;
@@ -418,6 +1353,9 @@ export class ClaustrumCredentialCache {
     peek(handle) {
         return this.#cache.get(handle);
     }
+    abandonPending(handle) {
+        this.#inFlight.delete(handle);
+    }
     seedForTest(handle, credential) {
         this.#cache.set(handle, credential);
     }
@@ -493,7 +1431,7 @@ export class ClaustrumCredentialCache {
                 this.#inFlight.delete(handle);
         });
     }
-    async #load(handle, minTtlMs) {
+    async #load(handle, minTtlMs, cacheIf) {
         let response;
         try {
             response = await this.#client.call(CLAUSTRUM_MODULE_ID, 'credential.get', {
@@ -512,9 +1450,13 @@ export class ClaustrumCredentialCache {
             recordVersion: result.recordVersion,
             ...(result.projectId !== undefined && { projectId: result.projectId }),
             ...(result.accountId !== undefined && { accountId: result.accountId }),
+            ...(result.credentialId !== undefined && {
+                credentialId: result.credentialId,
+            }),
         };
         if (credential.expiresAtMs !== null &&
-            credential.expiresAtMs > this.#now()) {
+            credential.expiresAtMs > this.#now() &&
+            (cacheIf?.() ?? true)) {
             this.#cache.set(handle, credential);
         }
         return credential;