@cortexkit/claustrum-client 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @cortexkit/claustrum-client
+
+Policy-free TypeScript transport for the Claustrum credential vault. Consumers own
+credential caching, refresh, account scheduling, and retry policy.
+
+## Wire contract callers depend on
+
+• The daemon records a durable anomaly alarm after 64 fetches in 60 seconds or
+  16 distinct handles on one connection. It still serves those requests. Timed-out
+  gets count, and the detector resets on reconnect. Use one warm attempt per
+  account per tick and apply per-handle backoff after transient failures.
+• `credential.get` is bimodal: resident records return in microseconds, while an
+  expiry-skew refresh can take seconds. Request paths should peek cached state,
+  not call `get` speculatively.
+• `permanent` with `not_found` means the handle is unknown OR revoked — uniform refusal
+  by design (the vault cannot enumerate which). Treat it as gone either way: re-run
+  `ck auth migrate-opencode` to mint a fresh handle; the prior record, if any, is kept.
+• `auth_required` means the record is latched and needs reauthentication.
+• Unknown server error classes are bounded to `transient`; callers must retry them
+  rather than treating a forward-compatible class as permanent.
+
+The client sends `consumerIdentity: null` for every managed request so inherited
+`SUBC_MODULE_ID` and `SUBC_LAUNCH_NONCE` cannot impersonate a supervising host.
+
+## OpenCode handle-file exports
+
+`defaultHandleFilePath`, `readHandleFile`, `handleFileRevision`, and `parseHandleFile`
+are exported for tenant plugins consuming the OpenCode handle manifest. The shared
+`HANDLE_FILE_CONTRACT` is pinned to `maxBytes: 262144`, `mode: 0o600`,
+`labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/`, and `handleRe: /^ckh_[A-Za-z0-9_-]{43}$/`.
+
+## Testing a consumer of this client
+
+Three things on a developer box silently satisfy what a consumer's test is trying to
+prove. Each was found by a consumer shipping green and failing elsewhere.
+
+• **A connection file at the default path is a host fact, not a fixture.** If the vault
+  runs on the machine, `detectClaustrumConnection` finds it whether or not a test set it
+  up, so a suite can pass on the daemon's real socket and fail anywhere without one.
+  Force it absent (`CLAUSTRUM_SUBC_CONNECTION=/nonexistent/x.json`, and clear
+  `XDG_RUNTIME_DIR`) and prove the suite still passes.
+• **Tests default into the operator's live config.** A suite that resolves
+  `~/.config/opencode` without an override writes lock files and manifests beside real
+  credentials — passing locally, and mutating state no CI runner has.
+• **A bare `bun` run is not an oracle for module resolution.** The Bun CLI auto-installs
+  a public dependency it cannot resolve; a compiled binary does not. All readings below
+  are bun 1.3.14, same module, no `node_modules` — a toolchain behaviour with no version
+  attached reads as permanent, and this one is a moving target by construction.
+
+  ```
+  bun run m.mjs / bun -e
+      resolves, with or without a package.json in scope, from any cwd,
+      on a cold install cache
+
+  bun build --compile, static import
+      error: Could not resolve: "X". Maybe you need to "bun install"?
+      NO BINARY PRODUCED
+
+  bun build --compile, dynamic import of a disk module
+      builds; fails in the consumer's process at import:
+      ERR_MODULE_NOT_FOUND Cannot find package 'X'
+  ```
+
+  Both compiled shapes matter and they fail at opposite ends. A bare dependency the
+  compiler can see is refused early and loudly, before any artifact exists. One it cannot
+  see — a plugin or a path-imported client loaded at runtime — survives the build and
+  fails at import inside the host, which is exactly where a credential client cannot
+  afford to fail. Since this client's consumers are daemons and plugins, exercise
+  resolution under a compiled loader or the real host, never a bare CLI run.
+
+  On macOS, sign the compiled probe (`codesign --force --sign -`) before trusting its
+  result: a freshly linked unsigned binary is SIGKILLed, and `rc=137` with empty stderr
+  reads as a resolution failure while being a signature one.
+
+The shape is the same in all three: the producing machine supplies the thing under test.
+A passing check on it is evidence only when the ambient supply is removed first.

package/dist/detect.d.ts

@@ -0,0 +1,18 @@
+import { type Endpoint as SubcEndpoint } from '@cortexkit/subc-client';
+export type ClaustrumEndpoint = SubcEndpoint;
+export type ClaustrumDetection = {
+    status: 'available';
+    schema: number;
+    wireVersion: number;
+    endpoints: ClaustrumEndpoint[];
+} | {
+    status: 'absent';
+    path: string;
+} | {
+    status: 'malformed';
+    path: string;
+    reason: string;
+};
+export declare function getDefaultClaustrumConnectionPath(): string;
+export declare function resolveClaustrumConnectionPath(explicit?: string): string;
+export declare function detectClaustrumConnection(explicitPath?: string): Promise<ClaustrumDetection>;

package/dist/detect.js

@@ -0,0 +1,145 @@
+import { readdirSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { PROTOCOL_VERSION, readConnectionFile, } from '@cortexkit/subc-client';
+const PRODUCTION_FILE_NAME = 'subc-connection.json';
+const TEMP_PREFIX = 'subc-';
+const TEMP_SUFFIX = '.connection.json';
+// The default discovery order MUST mirror `ck` / the daemon, because a client that picks a
+// different file ends up talking to the wrong daemon. The Rust source of truth (sibling
+// pin, NOT regenerated here) is:
+//
+//   crates/credentials-module/src/bin/credentials_cli.rs :: discover_subc_connection_file
+//     -> XDG_RUNTIME_DIR/subc-connection.json, else
+//        ~/.local/share/cortexkit/run/subc-connection.json, else
+//        <tempdir>/subc-<token>.connection.json  (glob; ambiguity REFUSES)
+//
+//   crates/subc-core/src/bootstrap.rs :: connection_file_path_with_source
+//     -> XDG_RUNTIME_DIR/subc-connection.json, else
+//        <tempdir>/subc-<user_connection_token()>.connection.json
+//     where user_connection_token() is the UID on unix (via a probe-file UID read),
+//     else a sanitized USER/USERNAME/HOME/USERPROFILE value, else "unknown".
+//
+// The OLD client derived `${uid}` itself via `process.getuid()`, but the daemon may
+// produce a different token (sanitized user on macOS, the literal "unknown" if all of
+// the lookups miss). The glob is the only way to mirror the daemon without re-deriving
+// the token (which is filesystem-side-effecting per the Rust side comment).
+// The home tier resolves from `$HOME` byte-for-byte, mirroring `non_empty_env("HOME")`
+// in `discover_subc_connection_file`: only the empty string is absent, and whitespace
+// is not trimmed. The Rust code does NOT fall back to a `getpwuid`-style lookup; the
+// client must not either, or an operator who points HOME at a per-test fixture loses
+// the daemon they started there.
+function homeTierPath() {
+    const homeEnv = process.env.HOME;
+    return homeEnv ? join(homeEnv, '.local', 'share', 'cortexkit', 'run', PRODUCTION_FILE_NAME) : undefined;
+}
+function highestPriorityAbsentMarker() {
+    const runtime = process.env.XDG_RUNTIME_DIR?.trim();
+    if (runtime)
+        return join(runtime, PRODUCTION_FILE_NAME);
+    const home = homeTierPath();
+    if (home)
+        return home;
+    // HOME unset — the Rust tier falls through to the tempdir glob with no fixed path.
+    // Surface the os-reported home so `detectClaustrumConnection` returns an `absent`
+    // path the operator can fix; without this, the caller gets a misleading `./...` path.
+    return join(userInfo().homedir, '.local', 'share', 'cortexkit', 'run', PRODUCTION_FILE_NAME);
+}
+function findExistingConnectionPath() {
+    const runtime = process.env.XDG_RUNTIME_DIR?.trim();
+    if (runtime) {
+        const p = join(runtime, PRODUCTION_FILE_NAME);
+        if (safeIsFile(p))
+            return p;
+    }
+    const home = homeTierPath();
+    if (home && safeIsFile(home))
+        return home;
+    const matches = listSubcConnectionFiles(tmpdir());
+    // A single matching file IS the daemon; multiple matches mean different OS users
+    // happened to share the temp dir. Picking one would route credential-bearing
+    // requests at another user's daemon, so REFUSE both picks and the absent path.
+    return matches.length === 1 ? matches[0] : undefined;
+}
+export function getDefaultClaustrumConnectionPath() {
+    return findExistingConnectionPath() ?? highestPriorityAbsentMarker();
+}
+export function resolveClaustrumConnectionPath(explicit) {
+    return (explicit?.trim() ||
+        process.env.CLAUSTRUM_SUBC_CONNECTION?.trim() ||
+        getDefaultClaustrumConnectionPath());
+}
+function safeIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function listSubcConnectionFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    for (const name of entries) {
+        if (typeof name !== 'string')
+            continue;
+        if (!name.startsWith(TEMP_PREFIX) || !name.endsWith(TEMP_SUFFIX))
+            continue;
+        const candidate = join(dir, name);
+        if (safeIsFile(candidate))
+            matches.push(candidate);
+    }
+    matches.sort();
+    return matches;
+}
+// The transport's typed reader validates `wire_version` against PROTOCOL_VERSION but does
+// not currently surface the value. Read it from the raw JSON so detection reports what the
+// daemon actually advertised, with the PROTOCOL_VERSION fallback for legacy files that
+// omitted the additive field.
+async function readAdvertisedWireVersion(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.wire_version === 'number' ? parsed.wire_version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function detectClaustrumConnection(explicitPath) {
+    const path = resolveClaustrumConnectionPath(explicitPath);
+    let value;
+    try {
+        value = await readConnectionFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { status: 'absent', path };
+        }
+        return {
+            status: 'malformed',
+            path,
+            reason: 'connection file could not be read or validated',
+        };
+    }
+    const advertised = await readAdvertisedWireVersion(path);
+    return {
+        status: 'available',
+        schema: value.schema,
+        wireVersion: advertised ?? PROTOCOL_VERSION,
+        endpoints: value.endpoints,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare const ERROR_CLASS_WIRE_SET: readonly ['transient', 'permanent', 'auth_required', 'context_overflow'];
+export type ClaustrumCredentialErrorClass = (typeof ERROR_CLASS_WIRE_SET)[number];
+export type ClaustrumCredentialErrorAction = 'gone' | 'reauth' | 'retry' | 'reduce_and_retry';
+export declare class ClaustrumCredentialError extends Error {
+    readonly code: string;
+    readonly action: ClaustrumCredentialErrorAction;
+    readonly ['class']: ClaustrumCredentialErrorClass;
+    constructor(code: string, errorClass: ClaustrumCredentialErrorClass, action: ClaustrumCredentialErrorAction);
+}
+type UnknownClassLogger = (errorClass: string) => void;
+export declare function credentialErrorAction(errorClass: ClaustrumCredentialErrorClass): ClaustrumCredentialErrorAction;
+export declare function asCredentialError(response: unknown, fallbackCode?: string, logUnknownClass?: UnknownClassLogger): ClaustrumCredentialError;
+export declare function hasCredentialError(response: unknown): boolean;
+export {};

package/dist/errors.js

@@ -0,0 +1,63 @@
+export const ERROR_CLASS_WIRE_SET = [
+    'transient',
+    'permanent',
+    'auth_required',
+    'context_overflow',
+];
+export class ClaustrumCredentialError extends Error {
+    code;
+    action;
+    ['class'];
+    constructor(code, errorClass, action) {
+        super(`Claustrum credential request failed: ${code}`);
+        this.code = code;
+        this.action = action;
+        this.name = 'ClaustrumCredentialError';
+        this['class'] = errorClass;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function credentialErrorAction(errorClass) {
+    switch (errorClass) {
+        case 'permanent':
+            return 'gone';
+        case 'auth_required':
+            return 'reauth';
+        case 'context_overflow':
+            return 'reduce_and_retry';
+        case 'transient':
+            return 'retry';
+    }
+}
+export function asCredentialError(response, fallbackCode = 'invalid_response', logUnknownClass = (errorClass) => console.warn(errorClass)) {
+    const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+    const error = result && isRecord(result.error) ? result.error : undefined;
+    const rawClass = error?.class;
+    const rawCode = error?.code;
+    // The wire contract in `crates/credentials-module/src/read_surface.rs` carries BOTH
+    // `class` and `code` on every error envelope. A frame missing `code` is therefore
+    // malformed: even when `class` is itself in the wire set, the half-formed envelope
+    // is not a valid permanent reason — preserving `class` would let a malicious or
+    // broken peer drive a `gone` action with `{ error: { class: 'permanent' } }`.
+    // Anthropic's cut-line rule (unknown or absent class → transient) generalises to
+    // any malformed envelope; both fields must be present and class must be known.
+    const hasValidClass = typeof rawClass === 'string' && ERROR_CLASS_WIRE_SET.includes(rawClass);
+    const hasCode = typeof rawCode === 'string';
+    const envelopeValid = hasValidClass && hasCode;
+    const errorClass = envelopeValid
+        ? rawClass
+        : 'transient';
+    if (typeof rawClass !== 'string')
+        logUnknownClass('unknown');
+    else if (!hasValidClass)
+        logUnknownClass(rawClass);
+    const code = hasCode ? rawCode : fallbackCode;
+    return new ClaustrumCredentialError(code, errorClass, credentialErrorAction(errorClass));
+}
+export function hasCredentialError(response) {
+    return (isRecord(response) &&
+        isRecord(response.result) &&
+        isRecord(response.result.error));
+}

package/dist/handles.d.ts

@@ -0,0 +1,59 @@
+export declare const HANDLE_FILE_CONTRACT: {
+    readonly maxBytes: number;
+    readonly mode: 384;
+    readonly labelRe: RegExp;
+    readonly handleRe: RegExp;
+};
+export declare class HandleFileValidationError extends Error {
+    name: string;
+}
+export type HandleAccount = {
+    label: string;
+    handle: string;
+    credential_id: string;
+    superseded?: string[];
+};
+export type HandleProvider = {
+    provider: string;
+    shape: 'api' | 'oauth';
+    serve: string;
+    accounts: HandleAccount[];
+};
+export type OpenCodeHandleFileV1 = {
+    version: 1;
+    providers: HandleProvider[];
+};
+export declare function identifierIsValid(value: unknown): value is string;
+export declare function parseHandleFile(value: unknown): OpenCodeHandleFileV1;
+type HandleFileStat = {
+    isFile(): boolean;
+    isDirectory?(): boolean;
+    isSymbolicLink?(): boolean;
+    mode: number;
+    size?: number;
+    uid?: number;
+    mtimeMs?: number;
+};
+type HandleFileDescriptor = {
+    read?(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }> | {
+        bytesRead: number;
+    };
+    stat(): Promise<HandleFileStat>;
+    readFile(options: {
+        encoding: 'utf8';
+    }): Promise<string>;
+    close(): Promise<void>;
+};
+export type HandleFileIo = {
+    stat?: (path: string) => Promise<HandleFileStat>;
+    lstat?: (path: string) => Promise<HandleFileStat>;
+    readFile?: (path: string, encoding: 'utf8') => Promise<string>;
+    open?: (path: string) => Promise<HandleFileDescriptor>;
+    currentUid?: () => number | undefined;
+};
+export declare function defaultHandleFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function readHandleFile(path?: string, io?: HandleFileIo): Promise<OpenCodeHandleFileV1>;
+export declare function handleFileRevision(path?: string, io?: HandleFileIo): Promise<string>;
+export {};

package/dist/handles.js

@@ -0,0 +1,286 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat as nodeLstat, open as nodeOpen, readFile, realpath, stat as nodeStat } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+export const HANDLE_FILE_CONTRACT = {
+    maxBytes: 256 * 1024,
+    mode: 0o600,
+    // Shape only: identifier validity also rejects FORBIDDEN_IDENTIFIERS; use
+    // identifierIsValid for validation so callers do not accept parser-rejected labels.
+    labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/,
+    handleRe: /^ckh_[A-Za-z0-9_-]{43}$/,
+};
+const FORBIDDEN_IDENTIFIERS = new Set(['__proto__', 'constructor', 'prototype']);
+export class HandleFileValidationError extends Error {
+    name = 'HandleFileValidationError';
+}
+function isAccount(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const account = value;
+    return typeof account.label === 'string' && typeof account.handle === 'string' &&
+        typeof account.credential_id === 'string' &&
+        (account.superseded === undefined ||
+            (Array.isArray(account.superseded) && account.superseded.every((handle) => typeof handle === 'string')));
+}
+function handleIsValid(handle) {
+    return typeof handle === 'string' && HANDLE_FILE_CONTRACT.handleRe.test(handle);
+}
+export function identifierIsValid(value) {
+    return typeof value === 'string' && HANDLE_FILE_CONTRACT.labelRe.test(value) && !FORBIDDEN_IDENTIFIERS.has(value);
+}
+function invalid(message) {
+    throw new HandleFileValidationError(message);
+}
+export function parseHandleFile(value) {
+    if (!value || typeof value !== 'object')
+        invalid('handle file must be an object');
+    const file = value;
+    if (file.version !== 1 || !Array.isArray(file.providers)) {
+        invalid('handle file must have version 1 and providers');
+    }
+    const providerIds = new Set();
+    const providers = file.providers.map((provider, index) => {
+        if (!provider || typeof provider !== 'object')
+            invalid(`provider ${index} must be an object`);
+        const item = provider;
+        if (!identifierIsValid(item.provider))
+            invalid(`provider ${index} has invalid provider`);
+        if (providerIds.has(item.provider))
+            invalid(`provider ${index} duplicates provider ${item.provider}`);
+        providerIds.add(item.provider);
+        if (item.shape !== 'api' && item.shape !== 'oauth')
+            invalid(`provider ${index} has invalid shape`);
+        if (typeof item.serve !== 'string' || !item.serve)
+            invalid(`provider ${index} requires serve`);
+        if (!Array.isArray(item.accounts) || item.accounts.length === 0 || !item.accounts.every(isAccount)) {
+            invalid(`provider ${index} has invalid accounts`);
+        }
+        const labels = new Set();
+        for (const account of item.accounts) {
+            if (!identifierIsValid(account.label))
+                invalid(`provider ${index} has an invalid account label`);
+            if (labels.has(account.label))
+                invalid(`provider ${index} duplicates account label ${account.label}`);
+            labels.add(account.label);
+            if (!handleIsValid(account.handle))
+                invalid(`provider ${index} account ${account.label} has invalid handle`);
+            // Segment 2 of the credential id must BE the provider block it sits in. Without
+            // this the check was non-empty-string only, so an `oauth:openai` binding parsed
+            // cleanly inside an `anthropic` block -- a cross-provider smuggle that every
+            // tenant reading this manifest would have honoured. Two peer tenants found the
+            // same hole in their own parsers independently.
+            //
+            // SCOPED TO SEGMENT 2 ONLY, deliberately. Segment 1 (the kind) is an OPEN SET --
+            // `oauth:`, `chatgpt:`, `antigravity:`, `apikey:` are all live in this vault today
+            // -- so a kind allowlist would refuse real ids. Segment 3+ (the label) is
+            // operator-chosen and may be absent: main is the 2-segment `oauth:anthropic`,
+            // fallbacks are 3-segment. Constraining either would reject the deployment this
+            // contract describes.
+            //
+            // NO SEGMENT MAY BE EMPTY. Segment 2 alone is what fences the provider, but a
+            // position-1 check ignores the rest of the string, and that left two ids passing
+            // that name credentials which cannot exist: `:anthropic:x` (empty kind) and
+            // `oauth:anthropic:` (empty label) both satisfy "segment 2 is the provider"
+            // literally. Neither is a smuggle; both defer a GUARANTEED resolve-time failure
+            // past the door, and under custody a resolve-time failure on a tombstoned account
+            // is a dark route rather than a refused row.
+            //
+            // It also removes an asymmetry nobody designed and everyone would read as a bug:
+            // `oauth::anthropic` rejected while `:anthropic:x` passed, purely because the
+            // check indexed position 1 and ignored positions 0 and 2. Agreed with the peer
+            // tenant and mirrored on their side, so this is chosen rather than defaulted --
+            // the previous behaviour was two independent defaults that happened to differ.
+            //
+            // The emptiness guard is ALSO explicit rather than a consequence: `''.split(':')`
+            // yields `['']`, whose `[1]` is `undefined` and cannot equal a provider string,
+            // so an empty id would reject anyway -- but that is a coincidence doing
+            // load-bearing work, and the check this replaced (`!account.credential_id`) was
+            // the emptiness guard. NO TEST DISTINGUISHES THAT ONE (empty rejects with or
+            // without it, verified by removal), so it is kept for a future reader who loosens
+            // the comparison, not for an arm it could never redden. The non-empty-SEGMENT
+            // rule below is different: it reddens, and is pinned.
+            const segments = account.credential_id.split(':');
+            if (!account.credential_id || segments[1] !== item.provider || segments.some((segment) => segment.length === 0)) {
+                invalid(`provider ${index} account ${account.label} has invalid credential id`);
+            }
+            if (account.superseded?.some((handle) => !handleIsValid(handle))) {
+                invalid(`provider ${index} account ${account.label} has invalid superseded handle`);
+            }
+        }
+        return {
+            provider: item.provider,
+            shape: item.shape,
+            serve: item.serve,
+            accounts: item.accounts.map((account) => ({
+                ...account,
+                ...(account.superseded === undefined ? {} : { superseded: account.superseded }),
+            })),
+        };
+    });
+    return { version: 1, providers };
+}
+export function defaultHandleFilePath(env = process.env) {
+    if (env.CLAUSTRUM_OPENCODE_HANDLES)
+        return env.CLAUSTRUM_OPENCODE_HANDLES;
+    const configHome = env.XDG_CONFIG_HOME || (env.HOME ? join(env.HOME, '.config') : '.config');
+    return join(configHome, 'cortexkit', 'opencode-handles.json');
+}
+function currentUid() {
+    return process.getuid?.() ?? userInfo().uid;
+}
+async function readBounded(descriptor, cap) {
+    if (!descriptor.read)
+        throw new Error('readBounded requires a descriptor exposing read()');
+    const buffer = Buffer.alloc(cap + 1);
+    let total = 0;
+    while (total < cap + 1) {
+        const chunk = await descriptor.read(buffer, total, buffer.length - total, total);
+        if (chunk.bytesRead === 0)
+            break;
+        total += chunk.bytesRead;
+    }
+    return { buffer, bytes: total > cap ? -1 : total };
+}
+async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
+    const stat = io.stat ?? nodeStat;
+    const lstat = io.lstat ?? nodeLstat;
+    const read = io.readFile ?? readFile;
+    const openFd = io.open ?? ((candidate) => nodeOpen(candidate, constants.O_RDONLY | constants.O_NOFOLLOW));
+    let descriptor;
+    try {
+        let metadata;
+        try {
+            if (io.lstat || io.readFile) {
+                metadata = await lstat(path);
+            }
+            else {
+                descriptor = await openFd(path);
+                metadata = await descriptor.stat();
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { file: { version: 1, providers: [] } };
+            if (error.code === 'ELOOP')
+                invalid('handle file must not be a symlink');
+            invalid(`cannot stat handle file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (metadata.isSymbolicLink?.())
+            invalid('handle file must not be a symlink');
+        if (!metadata.isFile())
+            invalid('handle file must be a regular file');
+        if ((metadata.size ?? 0) > HANDLE_FILE_CONTRACT.maxBytes)
+            invalid('handle file exceeds 256 KiB');
+        if ((metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+            invalid('handle file mode must be exactly 0600');
+        const uid = io.currentUid ?? currentUid;
+        const expectedUid = uid();
+        if (expectedUid !== undefined && metadata.uid !== undefined && metadata.uid !== expectedUid) {
+            invalid('handle file is not owned by the current uid');
+        }
+        let parent;
+        try {
+            parent = await stat(dirname(path));
+        }
+        catch (error) {
+            invalid(`cannot stat handle file parent: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!parent.isDirectory?.())
+            invalid('handle file parent must be a directory');
+        if (expectedUid !== undefined && parent.uid !== undefined && parent.uid !== expectedUid) {
+            invalid('handle file parent is not owned by the current uid');
+        }
+        // GROUP-WRITABLE COUNTS, NOT ONLY WORLD-WRITABLE. Directory write permission governs
+        // unlink and create, so anyone who can write the parent can replace a mode-0600 file
+        // wholesale however tightly the file itself is locked. The owner check above does not
+        // close it: a directory I own can still be 0770, and then any other uid in that group
+        // can swap the handle file for one of theirs. A cross-uid attacker is not conceded by
+        // this threat model the way a same-uid one is.
+        //
+        // Sticky exempts both bits for one reason: with it set, a writer may only unlink files
+        // they own. Mirrors the Rust check in opencode_files.rs; the two must not drift.
+        if ((parent.mode & 0o022) !== 0 && (parent.mode & 0o1000) === 0) {
+            invalid('handle file parent is group- or world-writable without sticky bit');
+        }
+        // EVERY ANCESTOR, NOT JUST THIS ONE, OR THE GUARANTEE DOES NOT COMPOSE. The immediate
+        // parent being 0700 protects nothing when a directory above it is group-writable:
+        // anyone who can create and unlink there renames it aside and substitutes their own
+        // tree. Walk to '/' rather than $HOME -- a stopping point read from the environment is
+        // attacker-influenceable and undefined when unset.
+        //
+        // realpath FIRST: an unresolved walk is defeated by a symlink component pointing
+        // somewhere permissive, and every individual stat still passes while the loop is about
+        // a path we never read through.
+        //
+        // Mirrors refuse_writable_ancestor in subc-transport 0.7.0 and in opencode_files.rs;
+        // three implementations of one rule must not drift.
+        let resolved;
+        try {
+            resolved = await realpath(dirname(path));
+        }
+        catch {
+            // Unresolvable: the read that follows reports the real errno, and refusing here
+            // would replace a precise failure with a permissions verdict about a path we could
+            // not resolve.
+            resolved = undefined;
+        }
+        if (resolved !== undefined) {
+            let component = resolved;
+            for (;;) {
+                let ancestor;
+                try {
+                    ancestor = await stat(component);
+                }
+                catch {
+                    ancestor = undefined;
+                }
+                if (ancestor && (ancestor.mode & 0o022) !== 0 && (ancestor.mode & 0o1000) === 0) {
+                    invalid(`handle file ancestor ${component} is group- or world-writable without sticky bit`);
+                }
+                const next = dirname(component);
+                if (next === component)
+                    break;
+                component = next;
+            }
+        }
+        let source;
+        try {
+            if (descriptor) {
+                const { buffer, bytes } = await readBounded(descriptor, HANDLE_FILE_CONTRACT.maxBytes);
+                if (bytes === -1)
+                    invalid('handle file exceeds 256 KiB');
+                source = buffer.subarray(0, bytes).toString('utf8');
+            }
+            else {
+                source = await read(path, 'utf8');
+            }
+        }
+        catch (error) {
+            if (error instanceof HandleFileValidationError)
+                throw error;
+            invalid(`cannot read handle file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch {
+            invalid('handle file contains invalid JSON');
+        }
+        return { file: parseHandleFile(value), source, mtimeMs: metadata.mtimeMs };
+    }
+    finally {
+        await descriptor?.close();
+    }
+}
+export async function readHandleFile(path = defaultHandleFilePath(), io = {}) {
+    return (await readHandleSnapshot(path, io)).file;
+}
+export async function handleFileRevision(path = defaultHandleFilePath(), io = {}) {
+    const snapshot = await readHandleSnapshot(path, io);
+    if (snapshot.source === undefined)
+        invalid('cannot revise absent handle file');
+    return `${snapshot.mtimeMs ?? 0}:${createHash('sha256').update(snapshot.source).digest('hex')}`;
+}

package/dist/identity.d.ts

@@ -0,0 +1,3 @@
+import type { BindIdentity } from '@cortexkit/subc-client';
+export declare function storageFingerprint(storagePath: string): string;
+export declare function storeIdentity(projectRoot: string, storagePath: string): BindIdentity;