@cortexkit/claustrum-client 0.5.0 → 0.6.1

package/dist/ancestor-permissions.d.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export type AncestorIdentity = {
+    euid: number | undefined;
+    egid: number | undefined;
+    passwdPath: string;
+    groupPath: string;
+};
+export declare const ancestorIdentityContext: AsyncLocalStorage<AncestorIdentity>;
+/**
+ * Debian OpenSSH's user-group-modes rule: ancestors without group/world-write, or with sticky, are safe.
+ * Without sticky, group-write requires effective uid/gid ownership and local passwd/group
+ * files proving the group contains only this user, with no other primary-group users.
+ * World-write never qualifies; anything the local account files cannot prove refuses.
+ * The twin accepts_ancestor in opencode_files.rs must keep the identical permission rule.
+ */
+export declare function acceptsAncestor(metadata: {
+    mode: number;
+    uid?: number;
+    gid?: number;
+}, identity?: AncestorIdentity): Promise<boolean>;

package/dist/ancestor-permissions.js

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFile } from 'node:fs/promises';
+export const ancestorIdentityContext = new AsyncLocalStorage();
+function records(source, count) {
+    return source.split('\n').filter((line) => line.trim() !== '' && !line.trimStart().startsWith('#')).map((line) => {
+        const fields = line.split(':');
+        if (fields.length !== count || !fields[0] || /\s/.test(fields[0]) || !/^\d+$/.test(fields[2]) || !Number.isSafeInteger(Number(fields[2])) || Number(fields[2]) > 0xffffffff || (count === 7 && (!/^\d+$/.test(fields[3]) || !Number.isSafeInteger(Number(fields[3])) || Number(fields[3]) > 0xffffffff))) {
+            throw new Error('malformed account record');
+        }
+        if (count === 4 && fields[3] !== '' && fields[3].split(',').some((name) => name === '' || /\s/.test(name)))
+            throw new Error('malformed group members');
+        return fields;
+    });
+}
+/**
+ * Debian OpenSSH's user-group-modes rule: ancestors without group/world-write, or with sticky, are safe.
+ * Without sticky, group-write requires effective uid/gid ownership and local passwd/group
+ * files proving the group contains only this user, with no other primary-group users.
+ * World-write never qualifies; anything the local account files cannot prove refuses.
+ * The twin accepts_ancestor in opencode_files.rs must keep the identical permission rule.
+ */
+export async function acceptsAncestor(metadata, identity = ancestorIdentityContext.getStore() ?? {
+    euid: process.geteuid?.(), egid: process.getegid?.(), passwdPath: '/etc/passwd', groupPath: '/etc/group',
+}) {
+    if ((metadata.mode & 0o022) === 0 || (metadata.mode & 0o1000) !== 0)
+        return true;
+    if ((metadata.mode & 0o002) !== 0 || identity.euid === undefined || identity.egid === undefined || metadata.uid !== identity.euid || metadata.gid !== identity.egid)
+        return false;
+    try {
+        const passwd = records(new TextDecoder('utf-8', { fatal: true }).decode(await readFile(identity.passwdPath)), 7);
+        const groups = records(new TextDecoder('utf-8', { fatal: true }).decode(await readFile(identity.groupPath)), 4);
+        const users = passwd.filter((entry) => Number(entry[2]) === identity.euid);
+        const matchingGroups = groups.filter((entry) => Number(entry[2]) === identity.egid);
+        if (users.length !== 1 || matchingGroups.length !== 1)
+            return false;
+        const name = users[0][0];
+        return (matchingGroups[0][3] === '' || matchingGroups[0][3].split(',').every((member) => member === name)) &&
+            !passwd.some((entry) => Number(entry[2]) !== identity.euid && Number(entry[3]) === identity.egid);
+    }
+    catch {
+        // Local files must prove exclusivity; unavailable or malformed NSS data cannot grant an exception.
+        return false;
+    }
+}

package/dist/detect.d.ts

@@ -13,6 +13,7 @@ export type ClaustrumDetection = {
     path: string;
     reason: string;
 };
+export declare function userConnectionToken(getuid?: (() => number) | null, env?: NodeJS.ProcessEnv): 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

@@ -6,36 +6,15 @@ 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.
+// Keep discovery in the CLI's order: exclusive SUBC_CONNECTION_FILE, runtime,
+// HOME, exact per-user temp name, then an unambiguous temp glob. The glob supports
+// daemons whose token derivation differs without guessing between other users.
 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();
+    const runtime = process.env.XDG_RUNTIME_DIR;
     if (runtime)
         return join(runtime, PRODUCTION_FILE_NAME);
     const home = homeTierPath();
@@ -47,7 +26,9 @@ function highestPriorityAbsentMarker() {
     return join(userInfo().homedir, '.local', 'share', 'cortexkit', 'run', PRODUCTION_FILE_NAME);
 }
 function findExistingConnectionPath() {
-    const runtime = process.env.XDG_RUNTIME_DIR?.trim();
+    if (process.env.SUBC_CONNECTION_FILE)
+        return process.env.SUBC_CONNECTION_FILE;
+    const runtime = process.env.XDG_RUNTIME_DIR;
     if (runtime) {
         const p = join(runtime, PRODUCTION_FILE_NAME);
         if (safeIsFile(p))
@@ -56,17 +37,31 @@ function findExistingConnectionPath() {
     const home = homeTierPath();
     if (home && safeIsFile(home))
         return home;
+    const exact = join(tmpdir(), `${TEMP_PREFIX}${userConnectionToken()}${TEMP_SUFFIX}`);
+    if (safeIsFile(exact))
+        return exact;
     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 userConnectionToken(getuid = process.getuid ?? null, env = process.env) {
+    if (getuid)
+        return String(getuid());
+    for (const key of ['USER', 'USERNAME', 'HOME', 'USERPROFILE']) {
+        const value = env[key];
+        if (value)
+            return Array.from(value, (character) => /^[a-zA-Z0-9_-]$/.test(character) ? character : '_').join('');
+    }
+    return 'unknown';
+}
 export function getDefaultClaustrumConnectionPath() {
     return findExistingConnectionPath() ?? highestPriorityAbsentMarker();
 }
 export function resolveClaustrumConnectionPath(explicit) {
     return (explicit?.trim() ||
+        process.env.SUBC_CONNECTION_FILE ||
         process.env.CLAUSTRUM_SUBC_CONNECTION?.trim() ||
         getDefaultClaustrumConnectionPath());
 }

package/dist/enrollment.d.ts

@@ -5,8 +5,8 @@ export type EnrollmentTokenFile = {
 /**
  * Atomically replace a consumer's enrollment credential.
  *
- * The file is always mode 0600 and every canonical ancestor is rejected when it is
- * group- or world-writable without sticky. This is the same rule implemented by the
+ * The file is always mode 0600. Writable canonical ancestors require sticky or a
+ * proven user-private group. This is the same rule implemented by the
  * shipped `refuse_writable_ancestor` symbol in `opencode_files.rs`.
  */
 export declare function writeEnrollmentTokenFile(path: string, value: EnrollmentTokenFile): Promise<void>;

package/dist/enrollment.js

@@ -1,3 +1,4 @@
+import { acceptsAncestor } from './ancestor-permissions.js';
 import { randomBytes } from 'node:crypto';
 import { chmod, mkdir, open, realpath, rename, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
@@ -23,7 +24,7 @@ async function refuseWritableAncestor(parent) {
         const metadata = await stat(component).catch(() => undefined);
         // Canonicalisation already traversed this component. If a later stat races with a
         // rename, let the create/rename operation below report the concrete failure.
-        if (metadata && (metadata.mode & 0o022) !== 0 && (metadata.mode & 0o1000) === 0) {
+        if (metadata && !(await acceptsAncestor(metadata))) {
             throw new Error(`enrollment token ancestor ${component} is group- or world-writable without sticky bit`);
         }
         const next = dirname(component);
@@ -35,8 +36,8 @@ async function refuseWritableAncestor(parent) {
 /**
  * Atomically replace a consumer's enrollment credential.
  *
- * The file is always mode 0600 and every canonical ancestor is rejected when it is
- * group- or world-writable without sticky. This is the same rule implemented by the
+ * The file is always mode 0600. Writable canonical ancestors require sticky or a
+ * proven user-private group. This is the same rule implemented by the
  * shipped `refuse_writable_ancestor` symbol in `opencode_files.rs`.
  */
 export async function writeEnrollmentTokenFile(path, value) {

package/dist/handles.d.ts

@@ -33,6 +33,7 @@ type HandleFileStat = {
     isSymbolicLink?(): boolean;
     mode: number;
     size?: number;
+    gid?: number;
     uid?: number;
     mtimeMs?: number;
 };

package/dist/handles.js

@@ -3,6 +3,7 @@ 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';
+import { acceptsAncestor } from './ancestor-permissions.js';
 export const HANDLE_FILE_CONTRACT = {
     maxBytes: 256 * 1024,
     mode: 0o600,
@@ -200,16 +201,14 @@ async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
         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) {
+        // Group-write counts as well as world-write: a directory writer can unlink and
+        // replace a mode-0600 file regardless of its file permissions or owner. Owning
+        // the directory does not exclude other group members. Sticky exempts both bits
+        // because a writer may unlink only files they own. Without sticky, group-write
+        // is safe only when local account files prove a user-private effective group;
+        // world-write is never exempt. Keep this rule identical to Rust's accepts_ancestor
+        // and parent check in opencode_files.rs.
+        if (!(await acceptsAncestor(parent))) {
             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
@@ -244,7 +243,7 @@ async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
                 catch {
                     ancestor = undefined;
                 }
-                if (ancestor && (ancestor.mode & 0o022) !== 0 && (ancestor.mode & 0o1000) === 0) {
+                if (ancestor && !(await acceptsAncestor(ancestor))) {
                     invalid(`handle file ancestor ${component} is group- or world-writable without sticky bit`);
                 }
                 const next = dirname(component);

package/dist/manifest-lock.js

@@ -1,5 +1,6 @@
+import { acceptsAncestor } from './ancestor-permissions.js';
 import { constants as fsConstants } from 'node:fs';
-import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, 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';
@@ -128,6 +129,28 @@ async function withLockCommit(path, tenant, fn) {
             if (code(error) !== 'ENOENT' && Date.now() >= deadline)
                 throw code(error) === 'owner_invalid' ? error : lockError('lock_busy', 'manifest lock busy');
         }
+        if (!observed && code(ownerReadError) === 'ENOENT') {
+            const metadata = await lstat(lock).catch(() => undefined);
+            if (metadata?.isDirectory() && Date.now() - metadata.mtimeMs >= ttl) {
+                await testOptions?.beforeEvict?.();
+                const stale = `${lock}.stale-${Math.floor(metadata.mtimeMs)}-${token()}`;
+                try {
+                    await rename(lock, stale);
+                    // A claimant may have published its owner while the eviction was pending.
+                    const moved = await lstat(stale);
+                    const ownerExists = await lstat(join(stale, 'owner')).then(() => true, (error) => code(error) !== 'ENOENT');
+                    if (!ownerExists && moved.mtimeMs === metadata.mtimeMs) {
+                        testOptions?.afterEvict?.();
+                        continue;
+                    }
+                    await rename(stale, lock).catch(() => { });
+                }
+                catch (error) {
+                    if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(error) ?? ''))
+                        throw error;
+                }
+            }
+        }
         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;
@@ -226,10 +249,47 @@ async function readManifest(path) {
     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 refuseWritableAncestors(parent) {
+    let component;
+    try {
+        component = await realpath(parent);
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+        const next = dirname(parent);
+        if (next !== parent)
+            await refuseWritableAncestors(next);
+        return;
+    }
+    for (;;) {
+        const metadata = await stat(component);
+        if (!(await acceptsAncestor(metadata)))
+            throw new Error('handle file ancestor is group- or world-writable without sticky bit');
+        const next = dirname(component);
+        if (next === component)
+            return;
+        component = next;
+    }
+}
+async function prepareParent(path) {
+    const parent = dirname(path);
+    // Check existing ancestors before creating directories under a replaceable tree.
+    if (process.platform !== 'win32')
+        await refuseWritableAncestors(parent);
+    const existing = await stat(parent).catch((error) => { if (code(error) !== 'ENOENT')
+        throw error; return undefined; });
+    if (existing && typeof process.getuid === 'function' && existing.uid !== process.getuid())
+        throw new Error('handle file parent is not owned by the current uid');
+    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 (typeof process.getuid === 'function' && metadata.uid !== process.getuid())
+        throw new Error('handle file parent is not owned by the current uid');
+    if (process.platform !== 'win32')
+        await refuseWritableAncestors(parent);
+}
 async function writeAtomic(path, file, commit) {
     const bytes = Buffer.from(JSON.stringify(file));
     if (bytes.byteLength > HANDLE_FILE_CONTRACT.maxBytes)

package/dist/wire.d.ts

@@ -186,26 +186,29 @@ export declare class ClaustrumClient {
 /**
  * A row from the caller's own grant-covered inventory.
  *
- * TWO SELECTION AXES, AND THEY ANSWER DIFFERENT QUESTIONS. Pick by what you are about
+ * Selection fields answer different questions. Pick by what you are about
  * to do with the token:
  *
+ * - `providerIds` — operator-assigned catalog provider ids; match exactly, with no fallback.
+ * - `authMethod` — the closed authentication method derived from the unsealed record,
+ *   not the id spelling. Absent on sign/open-only rows or when no method is defined.
+ *
  * - `refreshAdapter` — whose PROTOCOL the credential speaks. Use it when the token
  *   goes to a provider's own endpoints. Anything else is invalid there.
  * - `serves` — which model VENDORS are reachable through it. Use it when choosing
  *   where a model can be served from, and the protocol is not yours to care about.
  *
- * Never the id spelling, in either case: on a live vault 8 rows serve Anthropic models
- * and 3 of them contain no "anthropic" anywhere in their id.
- *
- * An earlier version of this comment called `serves` "the routing axis" full stop. That
- * was written before `refreshAdapter` existed and is wrong for the protocol-native case:
- * it would send a Claude OAuth request to `apikey:openrouter`.
+ * Never infer these fields from the id spelling. A credential reaching Anthropic models
+ * through OpenRouter still speaks OpenRouter's protocol, not Anthropic's.
  */
 export interface ScopedInventoryRow {
     readonly id: string;
     readonly categories: readonly string[];
     readonly credentialType: string;
     readonly serves: readonly string[];
+    /** Operator-assigned catalog ids, always present, including an empty set. */
+    readonly providerIds: readonly string[];
+    readonly authMethod?: 'apikey' | 'chatgpt' | 'antigravity' | 'oauth';
     /**
      * Which provider protocol this credential speaks. Absent for static keys.
      *

package/dist/wire.js

@@ -54,8 +54,15 @@ export function decodeCredential(response, logUnknownClass) {
         !isOptionalString(orgName)) {
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     }
+    let material;
+    try {
+        material = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(payload));
+    }
+    catch {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
     return {
-        material: new TextDecoder().decode(Uint8Array.from(payload)),
+        material,
         recordVersion,
         expiresAtMs,
         credentialId,
@@ -250,7 +257,7 @@ export class ClaustrumClient {
         const result = decodeEnrollmentResult(response, this.#logger);
         const token = result.token;
         const generation = result.token_generation;
-        if (typeof token !== 'string' || token.length === 0 || typeof generation !== 'number') {
+        if (typeof token !== 'string' || token.length === 0 || typeof generation !== 'number' || !Number.isInteger(generation) || generation < 0) {
             throw asCredentialError(response, 'invalid_response', this.#logger);
         }
         return { token, tokenGeneration: generation };
@@ -260,8 +267,9 @@ export class ClaustrumClient {
         this.#client.close();
     }
     async #call(method, params) {
+        const sentClient = this.#client;
         try {
-            return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
+            return await sentClient.call(CLAUSTRUM_MODULE_ID, method, params, {
                 identity: this.#identity,
                 consumerIdentity: null,
             });
@@ -269,7 +277,8 @@ export class ClaustrumClient {
         catch (error) {
             if (this.#shouldReconnect(error)) {
                 try {
-                    await this.#reconnect();
+                    if (this.#client === sentClient)
+                        await this.#reconnect();
                 }
                 catch (reconnectError) {
                     throw this.#asTransportError(reconnectError);
@@ -392,6 +401,12 @@ export function decodeScopedInventory(response, logUnknownClass) {
                 : undefined;
         if (createdAtMs === undefined)
             throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        const authMethod = row.auth_method;
+        if (authMethod !== undefined &&
+            authMethod !== 'apikey' && authMethod !== 'chatgpt' &&
+            authMethod !== 'antigravity' && authMethod !== 'oauth') {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
         if (!isOptionalString(row.refresh_adapter)) {
             throw asCredentialError(response, 'invalid_response', logUnknownClass);
         }
@@ -403,6 +418,8 @@ export function decodeScopedInventory(response, logUnknownClass) {
             categories: strings(row.categories),
             credentialType: row.type,
             serves: strings(row.serves),
+            providerIds: strings(row.provider_ids),
+            authMethod,
             state: row.state,
             refreshAdapter: row.refresh_adapter,
             recordVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "repository": {
     "type": "git",