@cortexkit/claustrum-client 0.1.0 → 0.2.0

package/dist/enrollment.d.ts

@@ -0,0 +1,12 @@
+export type EnrollmentTokenFile = {
+    token: string;
+    token_generation: number;
+};
+/**
+ * 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
+ * shipped `refuse_writable_ancestor` symbol in `opencode_files.rs`.
+ */
+export declare function writeEnrollmentTokenFile(path: string, value: EnrollmentTokenFile): Promise<void>;

package/dist/enrollment.js

@@ -0,0 +1,67 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, open, realpath, rename, stat, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+function validateTokenFile(value) {
+    if (!TOKEN_RE.test(value.token))
+        throw new Error('enrollment token must be exactly 64 lowercase hex characters');
+    if (!Number.isSafeInteger(value.token_generation) || value.token_generation < 1) {
+        throw new Error('enrollment token generation must be a positive safe integer');
+    }
+}
+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 && (metadata.mode & 0o022) !== 0 && (metadata.mode & 0o1000) === 0) {
+            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;
+    }
+}
+/**
+ * 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
+ * shipped `refuse_writable_ancestor` symbol in `opencode_files.rs`.
+ */
+export async function writeEnrollmentTokenFile(path, value) {
+    validateTokenFile(value);
+    const parent = dirname(path);
+    await mkdir(parent, { recursive: true, mode: 0o700 });
+    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 descriptor.sync();
+            await chmod(temporary, 0o600);
+        }
+        finally {
+            await descriptor.close();
+        }
+        await rename(temporary, path);
+        created = false;
+    }
+    finally {
+        if (created)
+            await unlink(temporary).catch(() => undefined);
+    }
+}

package/dist/handles.d.ts

@@ -12,6 +12,7 @@ export type HandleAccount = {
     handle: string;
     credential_id: string;
     superseded?: string[];
+    minTtlMs?: number;
 };
 export type HandleProvider = {
     provider: string;
@@ -24,6 +25,7 @@ export type OpenCodeHandleFileV1 = {
     providers: HandleProvider[];
 };
 export declare function identifierIsValid(value: unknown): value is string;
+export declare function credentialIdMatchesProvider(value: unknown, provider: string): value is string;
 export declare function parseHandleFile(value: unknown): OpenCodeHandleFileV1;
 type HandleFileStat = {
     isFile(): boolean;

package/dist/handles.js

@@ -30,6 +30,12 @@ function handleIsValid(handle) {
 export function identifierIsValid(value) {
     return typeof value === 'string' && HANDLE_FILE_CONTRACT.labelRe.test(value) && !FORBIDDEN_IDENTIFIERS.has(value);
 }
+export function credentialIdMatchesProvider(value, provider) {
+    if (typeof value !== 'string')
+        return false;
+    const segments = value.split(':');
+    return value.length > 0 && segments[1] === provider && segments.every((segment) => segment.length > 0);
+}
 function invalid(message) {
     throw new HandleFileValidationError(message);
 }
@@ -66,6 +72,9 @@ export function parseHandleFile(value) {
             labels.add(account.label);
             if (!handleIsValid(account.handle))
                 invalid(`provider ${index} account ${account.label} has invalid handle`);
+            if (account.minTtlMs !== undefined && !(Number.isSafeInteger(account.minTtlMs) && account.minTtlMs >= 0)) {
+                invalid(`provider ${index} account ${account.label} has invalid minTtlMs`);
+            }
             // 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
@@ -100,9 +109,8 @@ export function parseHandleFile(value) {
             // 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)) {
+            // rule in credentialIdMatchesProvider is different: it reddens, and is pinned.
+            if (!credentialIdMatchesProvider(account.credential_id, item.provider)) {
                 invalid(`provider ${index} account ${account.label} has invalid credential id`);
             }
             if (account.superseded?.some((handle) => !handleIsValid(handle))) {

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, type ClaustrumDetection, type ClaustrumEndpoint, } from './detect.js';
 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 ServedCredential, } from './wire.js';
-export { HANDLE_FILE_CONTRACT, HandleFileValidationError, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, 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/index.js

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

package/dist/wire.d.ts

@@ -57,5 +57,124 @@ export declare class ClaustrumClient {
         recordVersion: number;
         reporterSource: ClaustrumReporterSource;
     }): Promise<void>;
+    /**
+     * Enumerate what this caller's grants cover.
+     *
+     * `params` is `{}` and must be PRESENT: the vault rejects an absent or null params
+     * object, so a caller cannot ask a different question by omitting it.
+     */
+    listScoped(enrollmentToken?: string): Promise<readonly ScopedInventoryRow[]>;
+    /**
+     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     *
+     * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
+     * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
+     * serving a token that will die inside the caller's own margin. That class means
+     * reduce-and-retry, never wait-and-retry.
+     */
+    getScoped(input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        minTtlMs?: number;
+    }): Promise<ServedCredential>;
+    /**
+     * Report a served credential dead, addressed by id rather than by handle.
+     *
+     * VERSION-FENCED: `recordVersion` must be the one this caller was SERVED. A report
+     * against a since-refreshed version is accepted and does nothing, which is the point --
+     * a stale report must not kill a fresh token. `accepted: true` is the receipt that the
+     * report was taken, never evidence that it applied.
+     */
+    reportAuthFailureScoped(input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        providerStatus: number;
+        recordVersion: number;
+        reporterSource: ClaustrumReporterSource;
+    }): Promise<void>;
+    /**
+     * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
+     * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.
+     *
+     * IDEMPOTENT ON (name, secret): re-proposing with the same secret returns the SAME
+     * `requestId`. That exists because `requestId` is minted server-side, so a consumer
+     * cannot persist it before proposing -- a crash in that window would otherwise leave it
+     * holding a secret it cannot poll with and a name held until TTL. Persist the secret
+     * BEFORE calling this, and a crash costs nothing.
+     *
+     * A different secret on the same name is a different caller and is refused.
+     */
+    enrollPropose(input: {
+        name: string;
+        requestSecretHash: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    /**
+     * Poll a proposal. Returns `pending` until an operator decides, then exactly once
+     * returns the token.
+     *
+     * THE TOKEN IS RETURNED ONCE. Persist it before doing anything else with it; a lost
+     * token needs a fresh ceremony, not a second poll.
+     */
+    enrollPoll(input: {
+        requestId: string;
+        requestSecret: string;
+    }): Promise<EnrollmentPollOutcome>;
+    /** Exchange a live token for its successor. The old token dies when the new one is issued. */
+    enrollRotate(input: {
+        token: string;
+    }): Promise<{
+        token: string;
+        tokenGeneration: number;
+    }>;
     close(): void;
 }
+/**
+ * A row from the caller's own grant-covered inventory.
+ *
+ * `serves` is the ROUTING AXIS, not the id spelling. `apikey:openrouter` and
+ * `antigravity:google` both serve Anthropic models and contain no "anthropic"
+ * anywhere in their ids, so a consumer that filters on the id segment silently
+ * drops working accounts. Measured on a live vault: 8 Anthropic-capable rows, 3 of
+ * them invisible to an id-substring filter.
+ */
+export interface ScopedInventoryRow {
+    readonly id: string;
+    readonly categories: readonly string[];
+    readonly credentialType: string;
+    readonly serves: readonly string[];
+    /**
+     * Which provider protocol this credential speaks. Absent for static keys.
+     *
+     * SELECT ON THIS, NOT ON `serves`, WHEN THE TOKEN GOES TO A PROVIDER'S OWN ENDPOINTS.
+     * Measured on a live vault: eight rows serve Anthropic models and only five are Claude
+     * OAuth -- openrouter, antigravity and cursor reach Anthropic models through their own
+     * APIs. The id spelling does not separate them either: two contain no "anthropic" at
+     * all, and `credentialType === 'oauth'` catches antigravity and cursor too.
+     */
+    readonly refreshAdapter?: string;
+    readonly state: string;
+    readonly recordVersion: number;
+    readonly operations: readonly string[];
+    /**
+     * NOT SERVED TODAY. The field is absent from `ListScopedCredential`, so this is always
+     * null; it is declared because a consumer's discovery high-water mark needs it and the
+     * absence should be visible in the type rather than discovered at runtime.
+     */
+    readonly createdAtMs: number | null;
+    readonly accountId?: string;
+    readonly email?: string;
+    readonly orgName?: string;
+}
+/** What a poll found. `pending` is not an error: the operator has not decided yet. */
+export type EnrollmentPollOutcome = {
+    readonly status: 'pending';
+} | {
+    readonly status: 'approved';
+    readonly name: string;
+    readonly token: string;
+    readonly tokenGeneration: number;
+} | {
+    readonly status: 'denied';
+};

package/dist/wire.js

@@ -134,6 +134,103 @@ export class ClaustrumClient {
         if (result?.accepted !== true)
             throw asCredentialError(response, 'invalid_response', this.#logger);
     }
+    /**
+     * Enumerate what this caller's grants cover.
+     *
+     * `params` is `{}` and must be PRESENT: the vault rejects an absent or null params
+     * object, so a caller cannot ask a different question by omitting it.
+     */
+    async listScoped(enrollmentToken) {
+        const response = await this.#call('credential.list_scoped', enrollmentToken === undefined ? {} : { enrollment_token: enrollmentToken });
+        return decodeScopedInventory(response, this.#logger);
+    }
+    /**
+     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     *
+     * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
+     * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
+     * serving a token that will die inside the caller's own margin. That class means
+     * reduce-and-retry, never wait-and-retry.
+     */
+    async getScoped(input) {
+        const response = await this.#call('credential.get_scoped', {
+            credential_id: input.credentialId,
+            enrollment_token: input.enrollmentToken,
+            min_ttl_ms: input.minTtlMs,
+        });
+        return decodeCredential(response, this.#logger);
+    }
+    /**
+     * Report a served credential dead, addressed by id rather than by handle.
+     *
+     * VERSION-FENCED: `recordVersion` must be the one this caller was SERVED. A report
+     * against a since-refreshed version is accepted and does nothing, which is the point --
+     * a stale report must not kill a fresh token. `accepted: true` is the receipt that the
+     * report was taken, never evidence that it applied.
+     */
+    async reportAuthFailureScoped(input) {
+        const response = await this.#call('credential.report_auth_failure', {
+            credential_id: input.credentialId,
+            enrollment_token: input.enrollmentToken,
+            provider_status: input.providerStatus,
+            record_version: input.recordVersion,
+            reporter_source: input.reporterSource,
+        });
+        if (hasCredentialError(response))
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+        if (result?.accepted !== true)
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+    }
+    /**
+     * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
+     * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.
+     *
+     * IDEMPOTENT ON (name, secret): re-proposing with the same secret returns the SAME
+     * `requestId`. That exists because `requestId` is minted server-side, so a consumer
+     * cannot persist it before proposing -- a crash in that window would otherwise leave it
+     * holding a secret it cannot poll with and a name held until TTL. Persist the secret
+     * BEFORE calling this, and a crash costs nothing.
+     *
+     * A different secret on the same name is a different caller and is refused.
+     */
+    async enrollPropose(input) {
+        const response = await this.#call('auth.enroll_propose', {
+            proposed_name: input.name,
+            request_secret_hash: input.requestSecretHash,
+        });
+        const result = decodeEnrollmentResult(response, this.#logger);
+        const requestId = result.request_id;
+        if (typeof requestId !== 'string' || requestId.length === 0) {
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        }
+        return { requestId };
+    }
+    /**
+     * Poll a proposal. Returns `pending` until an operator decides, then exactly once
+     * returns the token.
+     *
+     * THE TOKEN IS RETURNED ONCE. Persist it before doing anything else with it; a lost
+     * token needs a fresh ceremony, not a second poll.
+     */
+    async enrollPoll(input) {
+        const response = await this.#call('auth.enroll_poll', {
+            request_id: input.requestId,
+            request_secret: input.requestSecret,
+        });
+        return decodeEnrollmentPoll(response, this.#logger);
+    }
+    /** Exchange a live token for its successor. The old token dies when the new one is issued. */
+    async enrollRotate(input) {
+        const response = await this.#call('auth.enroll_rotate', { token: input.token });
+        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') {
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        }
+        return { token, tokenGeneration: generation };
+    }
     close() {
         this.#closed = true;
         this.#client.close();
@@ -209,3 +306,95 @@ export class ClaustrumClient {
         await this.#reconnecting;
     }
 }
+function decodeScopedInventory(response, logUnknownClass) {
+    if (hasCredentialError(response))
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+    const rows = result?.credentials;
+    if (!Array.isArray(rows))
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    return rows.map((row) => {
+        if (!isRecord(row))
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        const recordVersion = asRecordVersion(row.record_version);
+        if (recordVersion === undefined) {
+            throw asCredentialError(response, 'invalid_record_version', logUnknownClass);
+        }
+        const strings = (value) => {
+            if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+                throw asCredentialError(response, 'invalid_response', logUnknownClass);
+            }
+            return value;
+        };
+        // THE FIELD IS `id`, NOT `credential_id`. `get` and `status` echo `credential_id`
+        // for binding verification; an inventory row IS the credential, so it does not name
+        // the concept twice. Reading the wrong key yields undefined for every row and says
+        // nothing about why -- which is exactly what it did to my own probe.
+        // THE WIRE KEY IS `type`, NOT `credential_type`. The Rust field is named
+        // `credential_type` (because `type` is a keyword) and carries
+        // `#[serde(rename = "type")]`, so the FIELD name and the WIRE name differ and reading
+        // the field name gets undefined for every row.
+        //
+        // Second instance of this exact mistake in one evening: my probe read
+        // `credential_id` where the row says `id` and printed "?" for all seventeen. Both
+        // times I wrote the decoder from the Rust struct rather than from a served payload,
+        // which is the habit this test exists to break.
+        if (typeof row.id !== 'string' || typeof row.type !== 'string' || typeof row.state !== 'string') {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
+        const createdAtMs = row.created_at_ms === undefined || row.created_at_ms === null
+            ? null
+            : typeof row.created_at_ms === 'number' && Number.isFinite(row.created_at_ms)
+                ? row.created_at_ms
+                : undefined;
+        if (createdAtMs === undefined)
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        if (!isOptionalString(row.refresh_adapter)) {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
+        if (!isOptionalString(row.account_id) || !isOptionalString(row.email) || !isOptionalString(row.org_name)) {
+            throw asCredentialError(response, 'invalid_response', logUnknownClass);
+        }
+        return {
+            id: row.id,
+            categories: strings(row.categories),
+            credentialType: row.type,
+            serves: strings(row.serves),
+            state: row.state,
+            refreshAdapter: row.refresh_adapter,
+            recordVersion,
+            operations: strings(row.operations),
+            createdAtMs,
+            accountId: row.account_id,
+            email: row.email,
+            orgName: row.org_name,
+        };
+    });
+}
+function decodeEnrollmentResult(response, logUnknownClass) {
+    if (hasCredentialError(response))
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+    if (result === undefined)
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    return result;
+}
+function decodeEnrollmentPoll(response, logUnknownClass) {
+    const result = decodeEnrollmentResult(response, logUnknownClass);
+    const status = result.status;
+    if (status === 'pending')
+        return { status: 'pending' };
+    if (status === 'denied')
+        return { status: 'denied' };
+    if (status !== 'approved')
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    const { name, token, token_generation: generation } = result;
+    if (typeof name !== 'string' ||
+        typeof token !== 'string' ||
+        token.length === 0 ||
+        typeof generation !== 'number' ||
+        !Number.isInteger(generation)) {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    return { status: 'approved', name, token, tokenGeneration: generation };
+}

package/package.json

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