@cortexkit/claustrum-client 0.1.0

package/dist/identity.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+export function storageFingerprint(storagePath) {
+    const absolutePath = storagePath;
+    let canonicalPath;
+    try {
+        canonicalPath = realpathSync(absolutePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        let ancestor = absolutePath;
+        while (!existsSync(ancestor)) {
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                break;
+            ancestor = parent;
+        }
+        canonicalPath = resolve(realpathSync(ancestor), relative(ancestor, absolutePath));
+    }
+    return createHash('sha256').update(canonicalPath).digest('hex');
+}
+export function storeIdentity(projectRoot, storagePath) {
+    return {
+        project_root: projectRoot,
+        harness: 'opencode',
+        session: `store-${storageFingerprint(storagePath)}`,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, type ClaustrumDetection, type ClaustrumEndpoint, } from './detect.js';
+export { storeIdentity, storageFingerprint } from './identity.js';
+export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, type ManifestHandleAccount, type ManifestHandleFile, type ManifestHandleProvider, type ManifestLockError, type ManifestLockErrorCode, } from './manifest-lock.js';
+export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, type ClaustrumCredentialErrorAction, type ClaustrumCredentialErrorClass, } from './errors.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type ServedCredential, } from './wire.js';
+export { HANDLE_FILE_CONTRACT, HandleFileValidationError, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, } from './detect.js';
+export { storeIdentity, storageFingerprint } from './identity.js';
+export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, } from './manifest-lock.js';
+export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, } from './errors.js';
+export { ClaustrumClient, } from './wire.js';
+export { HANDLE_FILE_CONTRACT, HandleFileValidationError, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, } from './handles.js';

package/dist/manifest-lock.d.ts

@@ -0,0 +1,32 @@
+import { type OpenCodeHandleFileV1 } from './handles.js';
+export declare const MANIFEST_LOCK: {
+    ttlMs: number;
+    renewEveryMs: number;
+    ownerKeys: readonly ['tenant', 'pid', 'claimed_at_ms', 'nonce'];
+    staleTargetRe: RegExp;
+    errorCodes: readonly ['lock_busy', 'owner_invalid', 'renewal_failed'];
+};
+/** Thrown by the lock. Branch on `code`; the message is diagnostic and may be reworded. */
+export type ManifestLockErrorCode = (typeof MANIFEST_LOCK.errorCodes)[number];
+export type ManifestLockError = Error & {
+    code: ManifestLockErrorCode;
+};
+export type ManifestHandleAccount = OpenCodeHandleFileV1['providers'][number]['accounts'][number];
+export type ManifestHandleProvider = OpenCodeHandleFileV1['providers'][number];
+export type ManifestHandleFile = OpenCodeHandleFileV1;
+type TestOptions = {
+    ttlMs?: number;
+    renewEveryMs?: number;
+    retryMinMs?: number;
+    retryMaxMs?: number;
+    afterClaim?: () => Promise<void> | void;
+    beforeEvict?: () => Promise<void>;
+    afterEvictRenameAttempt?: () => Promise<void>;
+    afterEvict?: () => void;
+    beforeManifestRename?: (path: string) => Promise<void>;
+};
+export declare function __setManifestLockTestOptions(options?: TestOptions): void;
+export declare function manifestLockQuarantinePrefix(path: string, basename?: (p: string) => string): string | undefined;
+export declare function withManifestLock<T>(path: string, tenant: string, fn: () => Promise<T> | T): Promise<T>;
+export declare function writeHandleFileLocked(path: string, tenant: string, mutate: (file: ManifestHandleFile) => void | ManifestHandleFile | Promise<void | ManifestHandleFile>): Promise<void>;
+export {};

package/dist/manifest-lock.js

@@ -0,0 +1,277 @@
+import { constants as fsConstants } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { randomBytes, randomInt } from 'node:crypto';
+import { basename as pathBasename, dirname, join } from 'node:path';
+import { HANDLE_FILE_CONTRACT, parseHandleFile } from './handles.js';
+export const MANIFEST_LOCK = { ttlMs: 30_000, renewEveryMs: 10_000, ownerKeys: ['tenant', 'pid', 'claimed_at_ms', 'nonce'], staleTargetRe: /^\.lock\.stale-\d+-(?!\.{1,2}$)(?!.*[. ]$)[^/\\\x00-\x1f:*?"<>|]{1,128}$/, errorCodes: ['lock_busy', 'owner_invalid', 'renewal_failed'] };
+// The claim deadline bounds when the last stale-lock rename is issued, not when it lands:
+// a rename issued at deadline-1ms can complete afterwards, by tens to hundreds of ms on a
+// loaded host. The retry deadline and staleness window both read `ttl` today; if they split,
+// this bound must keep their max so reclamation still covers the longer role.
+const MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS = 5_000;
+let testOptions;
+export function __setManifestLockTestOptions(options) { testOptions = options; }
+// 16 CSPRNG bytes: a collision needs both the same millisecond and the same nonce. Do not
+// simplify this to a counter, pid+timestamp, or a short token.
+const token = () => randomBytes(16).toString('base64url');
+const code = (error) => error?.code;
+const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A tenant classifying a failure must not string-match our prose: a copy-edit would
+// silently reclassify a retryable busy-lock as an unknown error, with nothing failing
+// loudly. The code is the contract; the message is free to change.
+const lockError = (code, message) => Object.assign(new Error(message), { code });
+function parseOwner(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw lockError('owner_invalid', 'manifest lock owner invalid');
+    }
+    if (!value || typeof value !== 'object')
+        throw lockError('owner_invalid', 'manifest lock owner invalid');
+    const owner = value;
+    // Widen the nonce alphabet only after every tenant has this path-safe reader; an older
+    // allowlist reader can otherwise wedge forever on the first owner using the new alphabet.
+    const staleTarget = `.lock.stale-${owner.claimed_at_ms}-${owner.nonce}`;
+    if (MANIFEST_LOCK.ownerKeys.some((key) => !Object.hasOwn(owner, key)) || typeof owner.claimed_at_ms !== 'number' || !Number.isInteger(owner.claimed_at_ms) || owner.claimed_at_ms < 0 || typeof owner.nonce !== 'string' || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
+        throw lockError('owner_invalid', 'manifest lock owner invalid');
+    return owner;
+}
+const readOwner = async (path) => parseOwner(await readFile(path, 'utf8'));
+async function writeOwner(lock, owner) {
+    const target = join(lock, 'owner');
+    const temporary = join(lock, `owner.${process.pid}.${token()}.tmp`);
+    let file;
+    try {
+        file = await open(temporary, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+        await file.chmod(0o600);
+        await file.writeFile(`${JSON.stringify(owner)}\n`);
+        await file.sync();
+        await file.close();
+        file = undefined;
+        await rename(temporary, target);
+    }
+    finally {
+        await file?.close().catch(() => { });
+        await unlink(temporary).catch(() => { });
+    }
+}
+// Split out from the sweep so the platform claim is testable from a POSIX runner: this takes
+// the basename FUNCTION, so a test can drive it with path.win32.basename without pretending
+// a Linux host is Windows. A filesystem test cannot do that -- on Linux a '/' split and
+// basename agree, so the defect below survives every filesystem test written against it.
+//
+// pathBasename, not a split on '/': on Windows the manifest path is backslash-separated, so a
+// '/' split yields the whole path, nothing matches the prefix, and the sweep becomes a silent
+// no-op on the one platform the quarantine bound is hardest to observe. Fails closed -- it
+// cannot reap the wrong directory -- but the feature is inert, which is worse than loud.
+export function manifestLockQuarantinePrefix(path, basename = pathBasename) {
+    const name = basename(path);
+    return name ? name : undefined;
+}
+async function reclaimStaleManifestLockQuarantines(path, ttlMs, claimDeadlineMs) {
+    const reclaimAgeMs = Math.max(ttlMs, claimDeadlineMs) + MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS;
+    let names;
+    try {
+        names = await readdir(dirname(path));
+    }
+    catch {
+        return;
+    }
+    const basename = manifestLockQuarantinePrefix(path);
+    if (!basename)
+        return;
+    await Promise.all(names.map(async (name) => {
+        const staleTarget = name.startsWith(basename) ? name.slice(basename.length) : undefined;
+        if (!staleTarget || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
+            return;
+        const target = join(dirname(path), name);
+        let metadata;
+        try {
+            metadata = await lstat(target);
+        }
+        catch {
+            return;
+        }
+        if (!metadata.isDirectory() || Date.now() - metadata.mtimeMs < reclaimAgeMs)
+            return;
+        await rm(target, { recursive: true, force: true }).catch(() => { });
+    }));
+}
+export async function withManifestLock(path, tenant, fn) {
+    return withLockCommit(path, tenant, async () => fn());
+}
+async function withLockCommit(path, tenant, fn) {
+    const lock = `${path}.lock`, ownerPath = join(lock, 'owner'), ttl = testOptions?.ttlMs ?? MANIFEST_LOCK.ttlMs, renewEvery = testOptions?.renewEveryMs ?? MANIFEST_LOCK.renewEveryMs, retryMin = testOptions?.retryMinMs ?? 25, retryMax = testOptions?.retryMaxMs ?? 75;
+    const nonce = token(), started = Date.now(), deadline = started + ttl;
+    while (true) {
+        try {
+            await mkdir(lock, { mode: 0o700 });
+            await writeOwner(lock, { tenant, pid: process.pid, claimed_at_ms: Date.now(), nonce });
+            await testOptions?.afterClaim?.();
+            break;
+        }
+        catch (error) {
+            if (code(error) !== 'EEXIST') {
+                if (code(error) !== 'ENOENT')
+                    await rm(lock, { recursive: true, force: true }).catch(() => { });
+                throw error;
+            }
+        }
+        let observed, ownerReadError;
+        try {
+            observed = await readOwner(ownerPath);
+        }
+        catch (error) {
+            ownerReadError = error;
+            if (code(error) !== 'ENOENT' && Date.now() >= deadline)
+                throw code(error) === 'owner_invalid' ? error : lockError('lock_busy', 'manifest lock busy');
+        }
+        if (observed && Date.now() - observed.claimed_at_ms >= ttl) {
+            await testOptions?.beforeEvict?.();
+            // The owner record remains because the quarantine is the ABA guard, not an audit log;
+            // bounded reclamation below is what makes that retention finite.
+            const stale = `${lock}.stale-${observed.claimed_at_ms}-${observed.nonce}`;
+            let renameError;
+            try {
+                await rename(lock, stale);
+            }
+            catch (error) {
+                renameError = error;
+            }
+            await testOptions?.afterEvictRenameAttempt?.();
+            if (renameError === undefined) {
+                const moved = await readOwner(join(stale, 'owner')).catch(() => undefined);
+                if (moved?.nonce === observed.nonce && moved.claimed_at_ms === observed.claimed_at_ms) {
+                    testOptions?.afterEvict?.();
+                    continue;
+                }
+                await rename(stale, lock).catch(() => { });
+            }
+            else if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(renameError) ?? ''))
+                throw renameError;
+        }
+        if (Date.now() >= deadline)
+            throw code(ownerReadError) === 'owner_invalid' ? ownerReadError : lockError('lock_busy', 'manifest lock busy');
+        await sleep(Math.min(randomInt(retryMin, retryMax + 1), Math.max(1, deadline - Date.now())));
+    }
+    await reclaimStaleManifestLockQuarantines(path, ttl, deadline - started);
+    let renewal = Promise.resolve(), failed = false, stopped = false;
+    const timer = setInterval(() => { renewal = renewal.then(async () => { if (failed)
+        return; try {
+        const current = await readOwner(ownerPath);
+        if (current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+            throw new Error('lease lost');
+        await writeOwner(lock, { ...current, claimed_at_ms: Date.now() });
+    }
+    catch {
+        failed = true;
+    } }); }, renewEvery);
+    timer.unref?.();
+    const commit = async () => { if (!stopped) {
+        stopped = true;
+        clearInterval(timer);
+        await renewal;
+    } ; const current = await readOwner(ownerPath).catch(() => undefined); if (failed || !current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+        throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted'); };
+    try {
+        const result = await fn(commit);
+        if (failed)
+            throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted');
+        return result;
+    }
+    finally {
+        if (!stopped)
+            clearInterval(timer);
+        await renewal;
+        const current = await readOwner(ownerPath).catch(() => undefined);
+        if (!current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+            console.warn('manifest lock lease lost, not releasing', { path, tenant });
+        else {
+            const release = `${lock}.release-${nonce}`;
+            try {
+                await rename(lock, release);
+                const moved = await readOwner(join(release, 'owner')).catch(() => undefined);
+                if (!moved || moved.nonce !== nonce || Date.now() - moved.claimed_at_ms >= ttl) {
+                    await rename(release, lock).catch(() => { });
+                    console.warn('manifest lock lease lost, not releasing', { path, tenant });
+                }
+                else
+                    await rm(release, { recursive: true, force: true });
+            }
+            catch {
+                console.warn('manifest lock lease lost, not releasing', { path, tenant });
+            }
+        }
+    }
+}
+async function readManifest(path) {
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return { version: 1, providers: [] };
+        throw error;
+    }
+    if (metadata.isSymbolicLink() || !metadata.isFile())
+        throw new Error('handle file must be a regular file');
+    if ((metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+        throw new Error('handle file mode must be exactly 0600');
+    const source = await readFile(path);
+    if (source.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
+        throw new Error('handle file exceeds 256 KiB');
+    return parseHandleFile(JSON.parse(source.toString('utf8')));
+}
+const foreign = (file, tenant) => file.providers.filter((provider) => provider.serve !== tenant).map((provider) => JSON.stringify(provider));
+async function prepareParent(path) { const parent = dirname(path); await mkdir(parent, { recursive: true, mode: 0o700 }); const metadata = await stat(parent); if (!metadata.isDirectory())
+    throw new Error('handle file parent must be a directory'); if ((metadata.mode & 0o002) !== 0 && (metadata.mode & 0o1000) === 0)
+    throw new Error('handle file parent is world-writable without sticky bit'); if ((metadata.mode & 0o022) !== 0)
+    throw new Error('handle file parent must not be group- or other-writable'); }
+async function writeAtomic(path, file, commit) {
+    const bytes = Buffer.from(JSON.stringify(file));
+    if (bytes.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
+        throw new Error('handle file exceeds 256 KiB');
+    // pathBasename for the same reason the quarantine sweep uses it, but this one fails LOUD
+    // rather than inert: a '/' split over a backslash path yields the whole path, so the temp
+    // name embeds separators and a drive-letter colon, join() nests it under its own directory,
+    // and O_CREAT|O_EXCL throws on a name Windows will not accept -- taking the manifest WRITE
+    // down, not just the reclaim. Covered by the dual-basename test, which a POSIX filesystem
+    // test cannot reach.
+    const temporary = join(dirname(path), `.${pathBasename(path)}.${process.pid}.${token()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+        await handle.chmod(0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await chmod(temporary, 0o600);
+        await testOptions?.beforeManifestRename?.(`${path}.lock`);
+        await commit();
+        await rename(temporary, path);
+    }
+    finally {
+        await handle?.close().catch(() => { });
+        await unlink(temporary).catch(() => { });
+    }
+}
+export async function writeHandleFileLocked(path, tenant, mutate) {
+    await prepareParent(path);
+    await withLockCommit(path, tenant, async (commit) => {
+        const before = await readManifest(path), working = structuredClone(before), result = await mutate(working), next = parseHandleFile(result ?? working), beforeForeign = foreign(before, tenant);
+        if (JSON.stringify(foreign(next, tenant)) !== JSON.stringify(beforeForeign))
+            throw new Error('manifest mutation changed another tenant block');
+        await writeAtomic(path, next, commit);
+        if (((await lstat(path)).mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+            throw new Error('manifest readback mode is not 0600');
+        const readback = await readManifest(path);
+        if (JSON.stringify(readback) !== JSON.stringify(next))
+            throw new Error('manifest readback differs');
+        if (JSON.stringify(foreign(readback, tenant)) !== JSON.stringify(beforeForeign))
+            throw new Error('manifest readback changed another tenant block');
+    });
+}

package/dist/wire.d.ts

@@ -0,0 +1,61 @@
+import { SubcClient, type BindIdentity } from '@cortexkit/subc-client';
+export type ClaustrumConnector = (options: {
+    connectionFile: string;
+    handshakeTimeoutMs?: number;
+}) => Promise<SubcClient>;
+export type ClaustrumClientOptions = {
+    connectionFile?: string;
+    handshakeTimeoutMs?: number;
+    projectRoot?: string;
+    storagePath?: string;
+    identity?: BindIdentity;
+    connector?: ClaustrumConnector;
+    logger?: (errorClass: string) => void;
+};
+/**
+ * Credential material plus optional non-secret identity metadata. Missing wire fields remain
+ * `undefined`; a present non-string identity value rejects the response as invalid.
+ */
+export type ServedCredential = {
+    material: string;
+    recordVersion: number;
+    expiresAtMs: number | null;
+    /**
+     * Operator-chosen record label for verifying a caller-held binding. It is not a routing key:
+     * account-scoped routing joins `accountId` with `recordVersion`.
+     */
+    credentialId?: string;
+    /** Non-secret Code Assist project identity, present only for antigravity credentials. */
+    projectId?: string;
+    /**
+     * Provider account identity the served token executes under. Account-scoped routing joins this
+     * value with `recordVersion`; it is neither the operator's credential label nor the bearer handle.
+     */
+    accountId?: string;
+    /** Non-secret account display metadata captured at login. */
+    email?: string;
+    /** Non-secret organization or workspace display metadata captured at login. */
+    orgName?: string;
+};
+export type CredentialStatus = {
+    ready: boolean;
+    lastErrorCode: string | null;
+    leaseHeld: boolean;
+    recordVersion: number;
+    stalePending?: boolean;
+};
+export type ClaustrumReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
+export declare class ClaustrumClient {
+    #private;
+    private constructor();
+    static connect(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
+    getCredential(handle: string, minTtlMs?: number): Promise<ServedCredential>;
+    statusCredential(handle: string): Promise<CredentialStatus>;
+    reportAuthFailure(input: {
+        handle: string;
+        providerStatus: number;
+        recordVersion: number;
+        reporterSource: ClaustrumReporterSource;
+    }): Promise<void>;
+    close(): void;
+}

package/dist/wire.js

@@ -0,0 +1,211 @@
+import { SubcCallError, SubcClient, } from '@cortexkit/subc-client';
+import { resolveClaustrumConnectionPath } from './detect.js';
+import { asCredentialError, ClaustrumCredentialError, hasCredentialError, } from './errors.js';
+import { storeIdentity } from './identity.js';
+const CLAUSTRUM_MODULE_ID = 'claustrum';
+const RECONNECT_BACKOFF_MS = 60_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asRecordVersion(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+        ? value
+        : undefined;
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function decodeCredential(response, logUnknownClass) {
+    if (hasCredentialError(response))
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+    const payload = result?.payload;
+    if (!Array.isArray(payload) ||
+        payload.length === 0 ||
+        !payload.every((value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 255)) {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    const recordVersion = asRecordVersion(result?.record_version);
+    if (recordVersion === undefined) {
+        throw asCredentialError(response, 'invalid_record_version', logUnknownClass);
+    }
+    const rawExpiresAtMs = result?.expires_at_ms;
+    const expiresAtMs = rawExpiresAtMs === undefined || rawExpiresAtMs === null
+        ? null
+        : typeof rawExpiresAtMs === 'number' && Number.isFinite(rawExpiresAtMs)
+            ? rawExpiresAtMs
+            : undefined;
+    if (expiresAtMs === undefined) {
+        throw asCredentialError(response, 'invalid_expiry', logUnknownClass);
+    }
+    const credentialId = result?.credential_id;
+    const projectId = result?.project_id;
+    const accountId = result?.account_id;
+    const email = result?.email;
+    const orgName = result?.org_name;
+    if (!isOptionalString(credentialId) ||
+        !isOptionalString(projectId) ||
+        !isOptionalString(accountId) ||
+        !isOptionalString(email) ||
+        !isOptionalString(orgName)) {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    return {
+        material: new TextDecoder().decode(Uint8Array.from(payload)),
+        recordVersion,
+        expiresAtMs,
+        credentialId,
+        projectId,
+        accountId,
+        email,
+        orgName,
+    };
+}
+function decodeStatus(response, logUnknownClass) {
+    if (hasCredentialError(response))
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+    const recordVersion = asRecordVersion(result?.record_version);
+    if (typeof result?.ready !== 'boolean' ||
+        (result?.last_error_code !== undefined && result?.last_error_code !== null && typeof result?.last_error_code !== 'string') ||
+        typeof result?.lease_held !== 'boolean' ||
+        recordVersion === undefined ||
+        (result?.stale_pending !== undefined && typeof result.stale_pending !== 'boolean')) {
+        throw asCredentialError(response, 'invalid_status', logUnknownClass);
+    }
+    return {
+        ready: result.ready,
+        lastErrorCode: result.last_error_code ?? null,
+        leaseHeld: result.lease_held,
+        recordVersion,
+        ...(result.stale_pending === undefined ? {} : { stalePending: result.stale_pending }),
+    };
+}
+export class ClaustrumClient {
+    #client;
+    #connector;
+    #connectionFile;
+    #handshakeTimeoutMs;
+    #identity;
+    #logger;
+    #reconnecting = null;
+    #nextReconnectAt = 0;
+    #closed = false;
+    constructor(client, connector, connectionFile, handshakeTimeoutMs, identity, logger) {
+        this.#client = client;
+        this.#connector = connector;
+        this.#connectionFile = connectionFile;
+        this.#handshakeTimeoutMs = handshakeTimeoutMs;
+        this.#identity = identity;
+        this.#logger = logger;
+    }
+    static async connect(options = {}) {
+        const connectionFile = resolveClaustrumConnectionPath(options.connectionFile);
+        const connector = options.connector ?? ((connectOptions) => SubcClient.connect(connectOptions));
+        const identity = options.identity ?? storeIdentity(options.projectRoot ?? process.cwd(), options.storagePath ?? process.cwd());
+        const client = await connector({
+            connectionFile,
+            handshakeTimeoutMs: options.handshakeTimeoutMs,
+        });
+        return new ClaustrumClient(client, connector, connectionFile, options.handshakeTimeoutMs, identity, options.logger ?? ((errorClass) => console.warn(errorClass)));
+    }
+    async getCredential(handle, minTtlMs) {
+        const response = await this.#call('credential.get', {
+            handle,
+            min_ttl_ms: minTtlMs,
+            force_refresh: false,
+        });
+        return decodeCredential(response, this.#logger);
+    }
+    async statusCredential(handle) {
+        const response = await this.#call('credential.status', { handle });
+        return decodeStatus(response, this.#logger);
+    }
+    async reportAuthFailure(input) {
+        const response = await this.#call('credential.report_auth_failure', {
+            handle: input.handle,
+            provider_status: input.providerStatus,
+            record_version: input.recordVersion,
+            reporter_source: input.reporterSource,
+        });
+        if (hasCredentialError(response))
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+        if (result?.accepted !== true)
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+    }
+    close() {
+        this.#closed = true;
+        this.#client.close();
+    }
+    async #call(method, params) {
+        try {
+            return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
+                identity: this.#identity,
+                consumerIdentity: null,
+            });
+        }
+        catch (error) {
+            if (this.#shouldReconnect(error)) {
+                try {
+                    await this.#reconnect();
+                }
+                catch (reconnectError) {
+                    throw this.#asTransportError(reconnectError);
+                }
+                try {
+                    return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
+                        identity: this.#identity,
+                        consumerIdentity: null,
+                    });
+                }
+                catch (retryError) {
+                    throw this.#asTransportError(retryError);
+                }
+            }
+            throw this.#asTransportError(error);
+        }
+    }
+    #asTransportError(error) {
+        if (error instanceof ClaustrumCredentialError)
+            return error;
+        const code = error instanceof SubcCallError && error.code ? error.code : 'transport_error';
+        return new ClaustrumCredentialError(code, 'transient', 'retry');
+    }
+    #shouldReconnect(error) {
+        return (!this.#closed &&
+            error instanceof SubcCallError &&
+            error.kind === 'terminal' &&
+            error.code !== 'missing_identity' &&
+            error.code !== 'invalid_control_body');
+    }
+    async #reconnect() {
+        if (this.#closed)
+            throw new Error('Claustrum client is closed');
+        if (this.#reconnecting) {
+            await this.#reconnecting;
+            return;
+        }
+        const now = Date.now();
+        if (now < this.#nextReconnectAt)
+            throw new Error('Claustrum client reconnect is backed off');
+        this.#nextReconnectAt = now + RECONNECT_BACKOFF_MS;
+        this.#reconnecting = this.#connector({
+            connectionFile: this.#connectionFile,
+            handshakeTimeoutMs: this.#handshakeTimeoutMs,
+        })
+            .then((client) => {
+            if (this.#closed) {
+                client.close();
+                throw new Error('Claustrum client is closed');
+            }
+            const previous = this.#client;
+            this.#client = client;
+            previous.close();
+        })
+            .finally(() => {
+            this.#reconnecting = null;
+        });
+        await this.#reconnecting;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cortexkit/claustrum-client",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cortexkit/claustrum.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Policy-free TypeScript transport client for the Claustrum credential vault.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "rm -rf dist && bun run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@cortexkit/subc-client": "^0.8.1"
+  }
+}