@cortexkit/claustrum-client 0.3.0 → 0.5.0

package/README.md

@@ -16,6 +16,11 @@ credential caching, refresh, account scheduling, and retry policy.
   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.
+• `statusCredential` on an unknown or revoked handle RESOLVES, it does not throw: it
+  returns `ready: false, lastErrorCode: 'not_found'` with `recordVersion`, `credentialId`
+  and `stalePending` absent. Since 0.5.0 `CredentialStatus.recordVersion` is optional for
+  that reason; handle `undefined` rather than defaulting it to a number, which would read
+  as a version older than every real one.
 • Unknown server error classes are bounded to `transient`; callers must retry them
   rather than treating a forward-compatible class as permanent.
 

package/dist/wire.d.ts

@@ -15,6 +15,14 @@ export type ClaustrumClientOptions = {
 /**
  * Credential material plus optional non-secret identity metadata. Missing wire fields remain
  * `undefined`; a present non-string identity value rejects the response as invalid.
+ *
+ * An absent identity field means the vault had nothing to assert — NOT that identity failed.
+ * Consumers must not collapse absence into mismatch: assert on presence, refuse on a present
+ * difference, and serve (log, if it matters) when the field is missing. Absence proves neither
+ * the right identity nor the wrong one, so treating it as a failure converts a vault that could
+ * not answer into a consumer that cannot serve. The vault records no per-read success (at most
+ * the first scoped read per principal), and nothing at all when a consumer declines to serve, so
+ * an outage caused that way is visible only to the consumer that caused it.
  */
 export type ServedCredential = {
     material: string;
@@ -30,6 +38,12 @@ export type ServedCredential = {
     /**
      * Provider account identity the served token executes under. Account-scoped routing joins this
      * value with `recordVersion`; it is neither the operator's credential label nor the bearer handle.
+     *
+     * BEST-EFFORT, NEVER GUARANTEED, including for JWT providers. The vault parses the claim live
+     * from the served access token and falls back to stored login-time identity; both legs can be
+     * empty, and the serve path yields nothing rather than fabricating an id. It is absent when the
+     * provider has no known claim, the token does not carry one, or no identity was captured at
+     * login. Do not gate serving on its presence.
      */
     accountId?: string;
     /** Non-secret account display metadata captured at login. */
@@ -37,14 +51,43 @@ export type ServedCredential = {
     /** Non-secret organization or workspace display metadata captured at login. */
     orgName?: string;
 };
+/**
+ * Non-secret health for one handle, read without minting anything.
+ *
+ * An unresolved handle (unknown or revoked) is an ordinary answer, not an error: it decodes
+ * as `ready: false, lastErrorCode: 'not_found'` with `credentialId`, `recordVersion` and
+ * `stalePending` all absent. The vault omits them on purpose so a probe learns nothing about
+ * what exists and no placeholder value is asserted about a record it never saw.
+ */
 export type CredentialStatus = {
     ready: boolean;
     lastErrorCode: string | null;
     leaseHeld: boolean;
-    recordVersion: number;
+    /**
+     * Operator-chosen record label the handle resolved to, for verifying a binding the caller
+     * already holds. Not a routing key. Absent when the handle did not resolve.
+     */
+    credentialId?: string;
+    /**
+     * The record's change cursor, present only when the handle resolved to a record.
+     *
+     * Optional, and OMITTED from the object rather than defaulted, because there is no honest
+     * default: 0 or -1 would compare as older than every real version, so a poller would read a
+     * revoked handle as a change it had yet to see, forever. With the key absent, TypeScript
+     * refuses arithmetic or ordering on it until the caller has handled `undefined`, and
+     * `'recordVersion' in status` is false. Never replace absence with a number (`?? 0`).
+     */
+    recordVersion?: number;
     stalePending?: boolean;
 };
 export type ClaustrumReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
+/**
+ * Exported for the golden-reply test only; `index.ts` re-exports by name, so this does not
+ * widen the published surface.
+ */
+export declare function decodeCredential(response: unknown, logUnknownClass: (errorClass: string) => void): ServedCredential;
+/** Exported for the golden-reply test only, like `decodeCredential`. */
+export declare function decodeStatus(response: unknown, logUnknownClass: (errorClass: string) => void): CredentialStatus;
 export declare class ClaustrumClient {
     #private;
     private constructor();
@@ -198,6 +241,12 @@ export interface ScopedInventory {
     readonly rows: readonly ScopedInventoryRow[];
     readonly view: string;
 }
+/**
+ * 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,
+ * because a key check passes on a decoder that reads the wrong key.
+ */
+export declare function decodeScopedInventory(response: unknown, logUnknownClass: (errorClass: string) => void): ScopedInventory;
 /** What a poll found. `pending` is not an error: the operator has not decided yet. */
 export type EnrollmentPollOutcome = {
     readonly status: 'pending';

package/dist/wire.js

@@ -15,7 +15,11 @@ function asRecordVersion(value) {
 function isOptionalString(value) {
     return value === undefined || typeof value === 'string';
 }
-function decodeCredential(response, logUnknownClass) {
+/**
+ * Exported for the golden-reply test only; `index.ts` re-exports by name, so this does not
+ * widen the published surface.
+ */
+export function decodeCredential(response, logUnknownClass) {
     if (hasCredentialError(response))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
@@ -61,15 +65,22 @@ function decodeCredential(response, logUnknownClass) {
         orgName,
     };
 }
-function decodeStatus(response, logUnknownClass) {
+/** Exported for the golden-reply test only, like `decodeCredential`. */
+export function decodeStatus(response, logUnknownClass) {
     if (hasCredentialError(response))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
-    const recordVersion = asRecordVersion(result?.record_version);
+    // Absent is a valid reply (the handle did not resolve); a PRESENT value that is not a
+    // non-negative integer is malformed. The producer omits the key rather than nulling it,
+    // so an explicit null is refused too.
+    const rawRecordVersion = result?.record_version;
+    const recordVersion = rawRecordVersion === undefined ? undefined : asRecordVersion(rawRecordVersion);
+    const credentialId = result?.credential_id;
     if (typeof result?.ready !== 'boolean' ||
         (result?.last_error_code !== undefined && result?.last_error_code !== null && typeof result?.last_error_code !== 'string') ||
         typeof result?.lease_held !== 'boolean' ||
-        recordVersion === undefined ||
+        (rawRecordVersion !== undefined && recordVersion === undefined) ||
+        !isOptionalString(credentialId) ||
         (result?.stale_pending !== undefined && typeof result.stale_pending !== 'boolean')) {
         throw asCredentialError(response, 'invalid_status', logUnknownClass);
     }
@@ -77,7 +88,8 @@ function decodeStatus(response, logUnknownClass) {
         ready: result.ready,
         lastErrorCode: result.last_error_code ?? null,
         leaseHeld: result.lease_held,
-        recordVersion,
+        ...(credentialId === undefined ? {} : { credentialId }),
+        ...(recordVersion === undefined ? {} : { recordVersion }),
         ...(result.stale_pending === undefined ? {} : { stalePending: result.stale_pending }),
     };
 }
@@ -286,7 +298,14 @@ export class ClaustrumClient {
             error instanceof SubcCallError &&
             error.kind === 'terminal' &&
             error.code !== 'missing_identity' &&
-            error.code !== 'invalid_control_body');
+            error.code !== 'invalid_control_body' &&
+            // The daemon answers unknown_module only when no module with this id is
+            // registered or supervised at all; a vault that is restarting or warming up
+            // is reported as module_warming or target_unavailable, which the SDK already
+            // retries in place. A fresh connection to the same daemon gets the same
+            // answer, and the wasted reconnect would also start the reconnect backoff,
+            // leaving a genuinely wedged connection unable to recover for a minute.
+            error.code !== 'unknown_module');
     }
     async #reconnect() {
         if (this.#closed)
@@ -318,7 +337,12 @@ export class ClaustrumClient {
         await this.#reconnecting;
     }
 }
-function decodeScopedInventory(response, logUnknownClass) {
+/**
+ * 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,
+ * because a key check passes on a decoder that reads the wrong key.
+ */
+export function decodeScopedInventory(response, logUnknownClass) {
     if (hasCredentialError(response))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;

package/package.json

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