@cortexkit/claustrum-client 0.7.0 → 0.10.0

package/README.md

@@ -28,6 +28,15 @@ credential caching, refresh, account scheduling, and retry policy.
   no provider ids are set. Since 0.6.2 a daemon too old to send the field decodes the
   same way, so a newer client still lists against an older daemon. `authMethod` stays
   optional.
+• Since 0.10.0 `listScoped` also returns `grants` (how many grants the caller holds)
+  and `grantTuples` (`{ selectorKind, selector, operation }` per grant). They tell two
+  empty listings apart: `rows: []` with `grants === 0` means the caller has no grant;
+  `rows: []` with `grants > 0` means it holds a grant that currently reaches no
+  credential, usually a category no credential carries yet (the operator's fix is
+  `ck auth set-category`, or `ck auth reclassify --from-registry` for credentials created
+  before categories existed). Both are `undefined` against a vault too old to send
+  them; treat that as unknown, not as zero. A present but malformed value refuses the
+  reply like any other malformed field.
 
 The client sends `consumerIdentity: null` for every managed request so inherited
 `SUBC_MODULE_ID` and `SUBC_LAUNCH_NONCE` cannot impersonate a supervising host.
@@ -39,6 +48,32 @@ are exported for tenant plugins consuming the OpenCode handle manifest. The shar
 `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}$/`.
 
+### Private files and Windows support
+
+Enrollment tokens support Windows as well as Unix. Reading a handle manifest works on
+Windows; writing one does not: the manifest lock's stale-lock eviction renames a lock
+another process may hold open, which Windows refuses, so `withManifestLock` and
+`writeHandleFileLocked` reject on Windows with code `unsupported_platform` rather than
+risk two writers overlapping. The client uses `@cortexkit/store` 0.2.1 or newer: exclusive private creation
+protects files before any secret bytes are written, and atomic replacement keeps
+that protection. Unix files use mode 0600 and new directories use 0700. On Windows,
+the store's `@cortexkit/private-files` native module creates owner-only ACLs and the
+async path check verifies real security descriptors, not Node's emulated mode bits
+or an AppData-location heuristic. Existing directories are checked, not silently
+repaired. Unsupported filesystems or unavailable native modules refuse the operation.
+Windows requires supported local, ACL-persisting drives; UNC/network paths and
+reparse points are refused. Windows ACL enforcement can only be qualified in CI,
+not by passing Unix tests locally.
+
+**Changed in 0.9.0:** Unix ancestors must now be owned by the current effective user
+or root. A foreign-owned ancestor is refused even at mode 0755; a non-root-owned
+sticky ancestor is also refused. Put the files under a folder you own. Root-owned
+sticky directories such as `/tmp` remain usable when the immediate child is your
+own non-group/world-writable directory. The Debian user-private-group exception is
+preserved: an owned, non-sticky group-writable directory (including a 0775
+`~/.config` under umask 0002) is accepted only when local `/etc/passwd` and
+`/etc/group` prove the effective group contains no other users.
+
 ## Testing a consumer of this client
 
 Three things on a developer box silently satisfy what a consumer's test is trying to

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. 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`.
+ * Creation uses owner-only Unix permissions or native Windows ACLs before writing
+ * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
+ * users, and on Windows also verifies the completed parent's owner-only ACL.
  */
 export declare function writeEnrollmentTokenFile(path: string, value: EnrollmentTokenFile): Promise<void>;

package/dist/enrollment.js

@@ -1,7 +1,8 @@
-import { acceptsAncestor } from './ancestor-permissions.js';
+import { createPrivateFile } from '@cortexkit/store';
+import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.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';
+import { open, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
 const TOKEN_RE = /^[0-9a-f]{64}$/;
 function validateTokenFile(value) {
     if (!TOKEN_RE.test(value.token))
@@ -11,49 +12,43 @@ function validateTokenFile(value) {
     }
 }
 async function refuseWritableAncestor(parent) {
-    let component;
-    try {
-        component = await realpath(parent);
-    }
-    catch {
-        // The following file operation reports the precise filesystem error. A permissions
-        // verdict about a path that could not be resolved would hide that useful failure.
-        return;
-    }
-    for (;;) {
-        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 && !(await acceptsAncestor(metadata))) {
-            throw new Error(`enrollment token ancestor ${component} is group- or world-writable without sticky bit`);
-        }
-        const next = dirname(component);
-        if (next === component)
-            return;
-        component = next;
-    }
+    const result = await checkPrivatePath(parent);
+    if (!result.ok)
+        throw new Error(notPrivate('enrollment token folder', result));
 }
 /**
  * Atomically replace a consumer's enrollment credential.
  *
- * 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`.
+ * Creation uses owner-only Unix permissions or native Windows ACLs before writing
+ * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
+ * users, and on Windows also verifies the completed parent's owner-only ACL.
  */
 export async function writeEnrollmentTokenFile(path, value) {
     validateTokenFile(value);
+    path = resolve(path);
     const parent = dirname(path);
-    await mkdir(parent, { recursive: true, mode: 0o700 });
+    // Native Windows creation rejects ancestors that other users can replace. A missing
+    // private parent can be created under a safe but non-private folder; afterwards the
+    // async check also requires the completed parent's protected owner-only ACL.
+    if (process.platform !== 'win32')
+        await refuseWritableAncestor(parent);
+    await createPrivateParents(parent);
     await refuseWritableAncestor(parent);
     const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
     let created = false;
     try {
-        const descriptor = await open(temporary, 'wx', 0o600);
         created = true;
         try {
-            await descriptor.writeFile(`${JSON.stringify(value)}\n`, 'utf8');
+            await createPrivateFile(temporary, `${JSON.stringify(value)}\n`);
+        }
+        catch (error) {
+            if (privateCreationCode(error) === 'EEXIST')
+                created = false;
+            throw error;
+        }
+        const descriptor = await open(temporary, 'r+');
+        try {
             await descriptor.sync();
-            await chmod(temporary, 0o600);
         }
         finally {
             await descriptor.close();

package/dist/handles.js

@@ -1,9 +1,9 @@
 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 { lstat as nodeLstat, open as nodeOpen, readFile, stat as nodeStat } from 'node:fs/promises';
 import { userInfo } from 'node:os';
-import { dirname, join } from 'node:path';
-import { acceptsAncestor } from './ancestor-permissions.js';
+import { dirname, join, resolve } from 'node:path';
+import { checkPrivatePath, notPrivate } from './private-path.js';
 export const HANDLE_FILE_CONTRACT = {
     maxBytes: 256 * 1024,
     mode: 0o600,
@@ -137,7 +137,7 @@ export function defaultHandleFilePath(env = process.env) {
     return join(configHome, 'cortexkit', 'opencode-handles.json');
 }
 function currentUid() {
-    return process.getuid?.() ?? userInfo().uid;
+    return process.platform === 'win32' ? undefined : process.getuid?.() ?? userInfo().uid;
 }
 async function readBounded(descriptor, cap) {
     if (!descriptor.read)
@@ -153,6 +153,7 @@ async function readBounded(descriptor, cap) {
     return { buffer, bytes: total > cap ? -1 : total };
 }
 async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
+    path = resolve(path);
     const stat = io.stat ?? nodeStat;
     const lstat = io.lstat ?? nodeLstat;
     const read = io.readFile ?? readFile;
@@ -182,7 +183,7 @@ async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
             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)
+        if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
             invalid('handle file mode must be exactly 0600');
         const uid = io.currentUid ?? currentUid;
         const expectedUid = uid();
@@ -201,57 +202,18 @@ 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-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
-        // 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 && !(await acceptsAncestor(ancestor))) {
-                    invalid(`handle file ancestor ${component} is group- or world-writable without sticky bit`);
-                }
-                const next = dirname(component);
-                if (next === component)
-                    break;
-                component = next;
-            }
-        }
+        // HandleFileIo's injected stat supplies ancestor metadata as well as the immediate
+        // parent. Pass that metadata to @cortexkit/store's Unix path check.
+        const fixtureStat = io.stat && (async (candidate) => {
+            const value = await io.stat(candidate);
+            return { ...value, isDirectory: () => value.isDirectory?.() ?? false };
+        });
+        const protection = await checkPrivatePath(process.platform === 'win32' ? path : dirname(path), fixtureStat ? {
+            euid: expectedUid,
+            fs: { stat: fixtureStat, lstat: fixtureStat },
+        } : undefined);
+        if (!protection.ok)
+            invalid(notPrivate('handle file folder', protection));
         let source;
         try {
             if (descriptor) {

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { storeIdentity, storageFingerprint } from './identity.js';
 export { writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollment.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 EnrollmentPollOutcome, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
 export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';

package/dist/manifest-lock.d.ts

@@ -4,7 +4,7 @@ export declare const MANIFEST_LOCK: {
     renewEveryMs: number;
     ownerKeys: readonly ['tenant', 'pid', 'claimed_at_ms', 'nonce'];
     staleTargetRe: RegExp;
-    errorCodes: readonly ['lock_busy', 'owner_invalid', 'renewal_failed'];
+    errorCodes: readonly ['lock_busy', 'owner_invalid', 'renewal_failed', 'unsupported_platform'];
 };
 /** Thrown by the lock. Branch on `code`; the message is diagnostic and may be reworded. */
 export type ManifestLockErrorCode = (typeof MANIFEST_LOCK.errorCodes)[number];

package/dist/manifest-lock.js

@@ -1,10 +1,10 @@
-import { acceptsAncestor } from './ancestor-permissions.js';
-import { constants as fsConstants } from 'node:fs';
-import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, unlink } from 'node:fs/promises';
+import { createPrivateDirectory, createPrivateFile } from '@cortexkit/store';
+import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.js';
+import { lstat, 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 { basename as pathBasename, dirname, join, resolve } 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'] };
+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', 'unsupported_platform'] };
 // 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,
@@ -15,12 +15,13 @@ 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 code = privateCreationCode;
 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 });
+const unsupportedOnWindows = () => lockError('unsupported_platform', 'handle-file manifest locking is not supported on Windows');
 function parseOwner(source) {
     let value;
     try {
@@ -45,9 +46,8 @@ async function writeOwner(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 createPrivateFile(temporary, `${JSON.stringify(owner)}\n`);
+        file = await open(temporary, 'r+');
         await file.sync();
         await file.close();
         file = undefined;
@@ -104,11 +104,18 @@ export async function withManifestLock(path, tenant, fn) {
     return withLockCommit(path, tenant, async () => fn());
 }
 async function withLockCommit(path, tenant, fn) {
+    // Stale-lock eviction renames the lock directory while another process may hold it
+    // open. That is safe under POSIX rename; on Windows CI two evictors both won and a
+    // rename of an open lock failed with EPERM. Until the protocol is proven there,
+    // refuse rather than risk two writers overlapping on the shared handle file.
+    if (process.platform === 'win32')
+        throw unsupportedOnWindows();
+    path = resolve(path);
     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 createPrivateDirectory(lock);
             await writeOwner(lock, { tenant, pid: process.pid, claimed_at_ms: Date.now(), nonce });
             await testOptions?.afterClaim?.();
             break;
@@ -241,8 +248,11 @@ async function readManifest(path) {
     }
     if (metadata.isSymbolicLink() || !metadata.isFile())
         throw new Error('handle file must be a regular file');
-    if ((metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+    if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
         throw new Error('handle file mode must be exactly 0600');
+    const protection = await checkPrivatePath(path);
+    if (!protection.ok)
+        throw new Error(notPrivate('handle file folder', protection));
     const source = await readFile(path);
     if (source.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
         throw new Error('handle file exceeds 256 KiB');
@@ -250,27 +260,9 @@ async function readManifest(path) {
 }
 const foreign = (file, tenant) => file.providers.filter((provider) => provider.serve !== tenant).map((provider) => JSON.stringify(provider));
 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;
-    }
+    const protection = await checkPrivatePath(parent);
+    if (!protection.ok)
+        throw new Error(notPrivate('handle file folder', protection));
 }
 async function prepareParent(path) {
     const parent = dirname(path);
@@ -281,14 +273,13 @@ async function prepareParent(path) {
         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 });
+    await createPrivateParents(parent);
     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);
+    await refuseWritableAncestors(parent);
 }
 async function writeAtomic(path, file, commit) {
     const bytes = Buffer.from(JSON.stringify(file));
@@ -303,13 +294,11 @@ async function writeAtomic(path, file, commit) {
     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 createPrivateFile(temporary, bytes);
+        handle = await open(temporary, 'r+');
         await handle.sync();
         await handle.close();
         handle = undefined;
-        await chmod(temporary, 0o600);
         await testOptions?.beforeManifestRename?.(`${path}.lock`);
         await commit();
         await rename(temporary, path);
@@ -320,13 +309,20 @@ async function writeAtomic(path, file, commit) {
     }
 }
 export async function writeHandleFileLocked(path, tenant, mutate) {
+    // Refuse before any path check, so a Windows caller gets the platform reason rather
+    // than a private-path refusal from the parent check that runs next.
+    if (process.platform === 'win32')
+        throw unsupportedOnWindows();
+    path = resolve(path);
     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)
+        if (process.platform !== 'win32' && ((await lstat(path)).mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+            throw new Error('manifest readback mode is not 0600');
+        if (!(await checkPrivatePath(path)).ok)
             throw new Error('manifest readback mode is not 0600');
         const readback = await readManifest(path);
         if (JSON.stringify(readback) !== JSON.stringify(next))

package/dist/private-path.d.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { type OwnerOnlyPathAsyncOptions, type OwnerOnlyPathResult } from '@cortexkit/store';
+export declare const privatePathContext: AsyncLocalStorage<OwnerOnlyPathAsyncOptions>;
+export declare const checkPrivatePath: (path: string, options?: OwnerOnlyPathAsyncOptions) => Promise<OwnerOnlyPathResult>;
+/**
+ * The refusal text for a path the store judged not private. It names the folder and the
+ * store's own reason (foreign owner, world-writable, a sticky folder without an
+ * owner-only child, a Windows ACL problem, ...), so the operator sees the actual cause.
+ */
+export declare function notPrivate(subject: string, result: Extract<OwnerOnlyPathResult, {
+    ok: false;
+}>): string;
+/** Native creation errors use Win32 numbers rather than Node's exclusive-create codes. */
+export declare function privateCreationCode(error: unknown): string | undefined;
+/** Create missing components privately without repairing permissions on existing directories. */
+export declare function createPrivateParents(path: string): Promise<void>;

package/dist/private-path.js

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { checkOwnerOnlyPathAsync, createPrivateDirectory } from '@cortexkit/store';
+// Tests run the ownership check against fixture uids and account files through this
+// context, isolated per concurrent test. It is internal: the package `exports` map
+// exposes only the index, so consumers cannot reach it.
+export const privatePathContext = new AsyncLocalStorage();
+export const checkPrivatePath = (path, options) => checkOwnerOnlyPathAsync(resolve(path), privatePathContext.getStore() ?? options);
+/**
+ * The refusal text for a path the store judged not private. It names the folder and the
+ * store's own reason (foreign owner, world-writable, a sticky folder without an
+ * owner-only child, a Windows ACL problem, ...), so the operator sees the actual cause.
+ */
+export function notPrivate(subject, result) {
+    return `${subject} ${result.path} is not private: ${result.reason}`;
+}
+/** Native creation errors use Win32 numbers rather than Node's exclusive-create codes. */
+export function privateCreationCode(error) {
+    const value = error;
+    if (value?.code === 'ERR_PRIVATE_FILES_SECURITY' && value.reason === 'io-error') {
+        if (value.win32Code === 80 || value.win32Code === 183)
+            return 'EEXIST';
+        if (value.win32Code === 2 || value.win32Code === 3)
+            return 'ENOENT';
+    }
+    return value?.code;
+}
+/** Create missing components privately without repairing permissions on existing directories. */
+export async function createPrivateParents(path) {
+    try {
+        await stat(path);
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const parent = dirname(path);
+    if (parent !== path)
+        await createPrivateParents(parent);
+    try {
+        await createPrivateDirectory(path);
+    }
+    catch (error) {
+        if (privateCreationCode(error) !== 'EEXIST')
+            throw error;
+        if (!(await stat(path)).isDirectory())
+            throw error;
+    }
+}

package/dist/wire.d.ts

@@ -212,8 +212,13 @@ export interface ScopedInventoryRow {
      * which is also what an unmapped credential reports.
      */
     readonly providerIds: readonly string[];
-    /** Operator assertion, unknown when absent; pricing owns the vocabulary. */
+    /**
+     * Subscription tier to price this account by; absent means unknown. An operator's
+     * `ck auth set-plan` value takes precedence over the tier detected from the provider;
+     * `planTierSource` says which one this is.
+     */
     readonly planTier?: string;
+    readonly planTierSource?: 'operator' | 'detected';
     readonly authMethod?: 'apikey' | 'chatgpt' | 'antigravity' | 'oauth';
     /**
      * Which provider protocol this credential speaks. Absent for static keys.
@@ -245,10 +250,38 @@ export interface ScopedInventoryRow {
  * and deliberately NOT over `record_version`, so a routine token refresh does not move it.
  * Compare it against the previous call's to decide whether to reconcile at all; it is an
  * opaque string and nothing but equality is defined on it.
+ *
+ * `grants` and `grantTuples` say what this caller is GRANTED, independent of what those
+ * grants currently reach. They are the only way to tell two empty listings apart:
+ *
+ * - `rows: []` with `grants === 0`: the caller holds no grant at all. The remedy is a
+ *   grant (`ck auth grant`).
+ * - `rows: []` with `grants > 0`: the caller holds a grant that currently reaches no
+ *   credential, typically a category no credential carries yet. The remedy is on the
+ *   credential side (`ck auth set-category`, or `ck auth reclassify --from-registry` for
+ *   credentials created before categories existed), not another grant.
+ *
+ * `grantTuples` lists each grant as `{ selectorKind, selector, operation }` (for example
+ * `{ selectorKind: 'category', selector: 'openai-native', operation: 'read' }`), so a
+ * consumer can name the selector that matched nothing. `grants` is its length.
+ *
+ * Both are `undefined` when the vault is too old to send them. That means "unknown",
+ * not "no grant": do not read an absent count as zero.
  */
 export interface ScopedInventory {
     readonly rows: readonly ScopedInventoryRow[];
     readonly view: string;
+    readonly grants: number | undefined;
+    readonly grantTuples: readonly ScopedGrantTuple[] | undefined;
+}
+/** One grant the caller holds, as the vault's `list_scoped` reply names it. */
+export interface ScopedGrantTuple {
+    /** `exact` or `category`; decoded as an open string. */
+    readonly selectorKind: string;
+    /** A credential id for `exact`, a bare category name for `category`. */
+    readonly selector: string;
+    /** The granted operation, e.g. `read` or `list`; decoded as an open string. */
+    readonly operation: string;
 }
 /**
  * Exported for the golden-reply test only; `index.ts` re-exports by name, so this does not

package/dist/wire.js

@@ -346,6 +346,7 @@ export class ClaustrumClient {
         await this.#reconnecting;
     }
 }
+const GRANT_TUPLE_KEYS = ['operation', 'selector', 'selector_kind'];
 /**
  * Exported for the golden-reply test only; `index.ts` re-exports by name, so this does not
  * widen the published surface. The test drives THIS function rather than asserting keys,
@@ -407,6 +408,10 @@ export function decodeScopedInventory(response, logUnknownClass) {
             throw asCredentialError(response, 'invalid_response', logUnknownClass);
         }
         const authMethod = row.auth_method;
+        const planTierSource = row.plan_tier_source;
+        if (planTierSource !== undefined && planTierSource !== 'operator' && planTierSource !== 'detected') {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
         if (authMethod !== undefined &&
             authMethod !== 'apikey' && authMethod !== 'chatgpt' &&
             authMethod !== 'antigravity' && authMethod !== 'oauth') {
@@ -430,6 +435,7 @@ export function decodeScopedInventory(response, logUnknownClass) {
             providerIds: row.provider_ids === undefined ? [] : strings(row.provider_ids),
             authMethod,
             planTier,
+            planTierSource,
             state: row.state,
             refreshAdapter: row.refresh_adapter,
             recordVersion,
@@ -440,7 +446,38 @@ export function decodeScopedInventory(response, logUnknownClass) {
             orgName: row.org_name,
         };
     });
-    return { rows: decoded, view };
+    // ABSENT IS UNKNOWN, PRESENT MUST BE WELL-FORMED. A vault from before these fields
+    // omits both, and refusing that would fail every listing against a still-supported
+    // vault. A present but malformed value is a broken reply, and decoding it leniently
+    // would hand the caller a grant count it cannot trust to tell "no grant" from "a grant
+    // that reaches nothing".
+    const rawGrants = result?.grants;
+    let grants;
+    if (rawGrants !== undefined) {
+        if (typeof rawGrants !== 'number' || !Number.isSafeInteger(rawGrants) || rawGrants < 0) {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
+        grants = rawGrants;
+    }
+    const rawTuples = result?.grant_tuples;
+    let grantTuples;
+    if (rawTuples !== undefined) {
+        if (!Array.isArray(rawTuples))
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        grantTuples = rawTuples.map((tuple) => {
+            if (!isRecord(tuple) ||
+                Object.keys(tuple).length !== GRANT_TUPLE_KEYS.length ||
+                !GRANT_TUPLE_KEYS.every((key) => typeof tuple[key] === 'string')) {
+                throw asCredentialError(response, 'invalid_response', logUnknownClass);
+            }
+            return {
+                selectorKind: tuple.selector_kind,
+                selector: tuple.selector,
+                operation: tuple.operation,
+            };
+        });
+    }
+    return { rows: decoded, view, grants, grantTuples };
 }
 function decodeEnrollmentResult(response, logUnknownClass) {
     if (hasCredentialError(response))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,6 +27,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@cortexkit/store": "^0.2.1",
     "@cortexkit/subc-client": "^0.16.0"
   }
 }

package/dist/ancestor-permissions.d.ts

@@ -1,20 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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;
-    }
-}