@cortexkit/claustrum-client 0.15.0 → 0.17.0

package/README.md

@@ -76,6 +76,11 @@ copy. One behaviour reaches callers: while the vault is restarting or refusing r
 opens as retryable, a call now keeps retrying for up to 90 s (paced, with jitter) instead
 of 30 s. Give every vault call on a latency-sensitive path its own timeout.
 
+**Changed in 0.16.0:** the dependency is now `@cortexkit/subc-client` ^0.24.0.
+The SDK negotiates FIFO request/watch windows and retries only daemon-origin
+`route_busy` refusals within the request deadline. Claustrum adds no busy retry;
+older daemons keep the SDK's previous behavior.
+
 ## Reading credential material
 
 The wire payload is opaque bytes. `getCredential(handle, minTtlMs?)` and
@@ -161,10 +166,44 @@ for (;;) {
 }
 ```
 
+## Enrollment
+
+`enrollPropose` accepts an optional `displayName`, for example
+`{ name: 'consumer', requestSecretHash, displayName: 'Claude sign-in for Pi' }`.
+The person sees and approves the proposed label, or replaces it during approval.
+This option needs a vault build with enrollment display-name support; an older
+vault refuses the `display_name` field as `invalid_params`. Omit `displayName`
+for compatibility with older vaults.
+
+Use `newEnrollmentSecret()` to prepare an enrollment proposal. It generates 32
+random bytes as exactly 64 lowercase hex characters, plus `requestSecretHash`:
+the lowercase hex SHA-256 of the **32 decoded bytes**, not of the UTF-8 hex text.
+`enrollmentSecretHash(requestSecret)` recomputes the hash of a persisted secret
+and refuses anything other than exactly 64 lowercase hex characters.
+
+```ts
+import { ClaustrumClient, newEnrollmentSecret } from '@cortexkit/claustrum-client'
+
+const client = await ClaustrumClient.connect()
+const { requestSecret, requestSecretHash } = newEnrollmentSecret()
+// Persist the secret privately before proposing so a crash can recover the poll.
+await persistRequestSecret(requestSecret)
+const { requestId } = await client.enrollPropose({ name: 'consumer', requestSecretHash })
+await persistRequestId(requestId)
+// After operator approval, poll with the original secret, not its hash.
+const outcome = await client.enrollPoll({ requestId, requestSecret })
+```
+
+The persistence functions above are caller-provided. Re-proposing the same name
+with the same persisted secret/hash recovers the request id after a lost reply.
+Only `pending` means poll again; an approved outcome returns the token once, so
+persist it with `writeEnrollmentTokenFile` before using it. Never log the request
+secret or token.
+
 ## Private files and Windows support
 
 Enrollment tokens support Windows as well as Unix. The client uses
-`@cortexkit/store` 0.2.1 or newer: exclusive private creation
+`@cortexkit/store` 0.2.3 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

package/dist/enrollment.d.ts

@@ -3,5 +3,12 @@ export type EnrollmentTokenFile = {
     token: string;
     token_generation: number;
 };
+/** Hash the 32 decoded bytes, not the UTF-8 text of the hex request secret. */
+export declare function enrollmentSecretHash(requestSecret: string): string;
+/** Mint an enrollment request secret and the hash to send with the proposal. */
+export declare function newEnrollmentSecret(): {
+    requestSecret: string;
+    requestSecretHash: string;
+};
 export declare function createEnrollmentWriter(checkPath?: typeof checkPrivatePath): (path: string, value: EnrollmentTokenFile) => Promise<void>;
 export declare const writeEnrollmentTokenFile: (path: string, value: EnrollmentTokenFile) => Promise<void>;

package/dist/enrollment.js

@@ -1,9 +1,21 @@
 import { createPrivateFile } from '@cortexkit/store';
 import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.js';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { open, rename, unlink } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 const TOKEN_RE = /^[0-9a-f]{64}$/;
+/** Hash the 32 decoded bytes, not the UTF-8 text of the hex request secret. */
+export function enrollmentSecretHash(requestSecret) {
+    if (typeof requestSecret !== 'string' || requestSecret.length !== 64 || !TOKEN_RE.test(requestSecret)) {
+        throw new Error('enrollment request secret must be exactly 64 lowercase hex characters');
+    }
+    return createHash('sha256').update(Buffer.from(requestSecret, 'hex')).digest('hex');
+}
+/** Mint an enrollment request secret and the hash to send with the proposal. */
+export function newEnrollmentSecret() {
+    const requestSecret = randomBytes(32).toString('hex');
+    return { requestSecret, requestSecretHash: enrollmentSecretHash(requestSecret) };
+}
 function validateTokenFile(value) {
     if (!TOKEN_RE.test(value.token))
         throw new Error('enrollment token must be exactly 64 lowercase hex characters');

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { enrollmentSecretHash, newEnrollmentSecret, writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollment.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 ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, type ServedCredentialBytes, } from './wire.js';
 export { ScopedWatchError, type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions, type ScopedWatchOutcome, } from './watch.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, } from './detect.js';
 export { storeIdentity, storageFingerprint } from './identity.js';
-export { writeEnrollmentTokenFile, } from './enrollment.js';
+export { enrollmentSecretHash, newEnrollmentSecret, writeEnrollmentTokenFile, } from './enrollment.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, } from './errors.js';
 export { ClaustrumClient, } from './wire.js';
 export { ScopedWatchError, } from './watch.js';

package/dist/wire.d.ts

@@ -179,10 +179,14 @@ export declare class ClaustrumClient {
      * BEFORE calling this, and a crash costs nothing.
      *
      * A different secret on the same name is a different caller and is refused.
+     * Optional `displayName` proposes a person-facing label for operator approval. It
+     * needs a vault build with enrollment display-name support; an older vault refuses
+     * the `display_name` field as `invalid_params`. Omit it for older vaults.
      */
     enrollPropose(input: {
         name: string;
         requestSecretHash: string;
+        displayName?: string;
     }): Promise<{
         requestId: string;
     }>;

package/dist/wire.js

@@ -296,11 +296,15 @@ export class ClaustrumClient {
      * BEFORE calling this, and a crash costs nothing.
      *
      * A different secret on the same name is a different caller and is refused.
+     * Optional `displayName` proposes a person-facing label for operator approval. It
+     * needs a vault build with enrollment display-name support; an older vault refuses
+     * the `display_name` field as `invalid_params`. Omit it for older vaults.
      */
     async enrollPropose(input) {
         const response = await this.#call('auth.enroll_propose', {
             proposed_name: input.name,
             request_secret_hash: input.requestSecretHash,
+            ...(input.displayName !== undefined ? { display_name: input.displayName } : {}),
         });
         const result = decodeEnrollmentResult(response, this.#logger);
         const requestId = result.request_id;

package/package.json

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