@cortexkit/claustrum-client 0.11.0 → 0.12.0

package/README.md

@@ -47,6 +47,76 @@ 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.
 
+## Watching for changes
+
+Since 0.12.0, `client.watchScoped(onNotice, { enrollmentToken? })` holds an
+`auth.watch_scoped` request on a dedicated route. It returns `{ stop(), closed }`.
+`stop()` is idempotent and resolves `closed` as `{ kind: 'stopped' }`. Notices have
+exactly `{ kind: 'changed', epoch, seq, view, keys }`; malformed notices reject
+`closed` with `ScopedWatchError` (`code: 'invalid_notice'`). Callback exceptions
+also reject it (`callback_failed`); async callbacks must handle their own rejection.
+Sequence gaps and new epochs are delivered, not silently filtered.
+
+**The caller owns reconnecting and re-subscribing.** Read `listScoped` on connect.
+On every notice, re-read if `view` differs from the last listing actually read,
+`epoch` is new, or `seq` skipped. Notices are sheddable hints, not an event journal.
+`keys` matters only to consumers that announce vault-held public keys: re-read
+those keys when that digest changes, independently of the inventory view.
+
+`@cortexkit/subc-client` 0.22 reports Response (including refusal) and STREAM_END
+frames as the same successful subscription close, without the Response body.
+Every accepted vault watch immediately sends notice seq 1, so the client uses
+whether any notices arrived to interpret that ambiguous close:
+
+| `closed` outcome | Caller action |
+| --- | --- |
+| `ended` (closed after notices) | Re-read and re-subscribe once for this close. A mid-watch revocation may take this extra round trip to discover. |
+| `refused`, with the existing typed credential `error` | Stop. Never reconnect for that refusal. |
+| `not_accepting` | Zero notices, then one successful `listScoped` confirmation. The vault may be draining: wait for reconnect or a caller-chosen delay, not a tight re-subscribe loop. |
+| `transport_lost`, with the original SDK `error` (including `route_closed`) | Reconnect, re-read, then re-watch. |
+| `unsupported` (`unknown_method`) | Fall back to polling `listScoped`. |
+
+A zero-notice close performs exactly one `listScoped` using the same enrollment
+token: its refusal becomes `refused`, its success becomes `not_accepting`. There is
+no automatic retry or reconnection in that confirmation read. Malformed replies
+reject `closed` with `ScopedWatchError('invalid_response')`.
+
+```ts
+let client = await ClaustrumClient.connect(connectionOptions)
+for (;;) {
+  let lastView = (await client.listScoped(token)).view // read on every connect/reopen
+  let epoch: string | undefined
+  let seq = 0
+  let reads = Promise.resolve()
+  let readError: unknown
+  const watch = client.watchScoped((notice) => {
+    const discontinuity = notice.epoch !== epoch || notice.seq !== seq + 1
+    epoch = notice.epoch
+    seq = notice.seq
+    reads = reads.then(async () => {
+      if (discontinuity || notice.view !== lastView) {
+        const listing = await client.listScoped(token)
+        lastView = listing.view // acknowledge the digest actually read, not the hint
+        useInventory(listing)
+      }
+    }).catch((error) => { readError = error; watch.stop() })
+    // Key-announcing callers separately compare notice.keys and re-read held keys.
+  }, { enrollmentToken: token })
+  let outcome
+  try { outcome = await watch.closed; await reads; if (readError) throw readError }
+  catch (error) { watch.stop(); throw error } // malformed notice/read/callback failure
+  if (outcome.kind === 'ended') continue // one new watch per close, never hidden retries
+  if (outcome.kind === 'transport_lost') {
+    client.close()
+    client = await ClaustrumClient.connect(connectionOptions)
+    continue
+  }
+  if (outcome.kind === 'not_accepting') { await callerBackoff(); continue }
+  if (outcome.kind === 'unsupported') await pollScopedInventory(client, token)
+  break // refused or explicitly stopped
+}
+```
+
 ## OpenCode handle-file exports
 
 `defaultHandleFilePath`, `readHandleFile`, `handleFileRevision`, and `parseHandleFile`

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollmen
 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 ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ScopedWatchError, type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions, type ScopedWatchOutcome, } from './watch.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

@@ -4,4 +4,5 @@ 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 { ScopedWatchError, } from './watch.js';
 export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, } from './handles.js';

package/dist/watch.d.ts

@@ -0,0 +1,38 @@
+import type { BindIdentity, SubcClient } from '@cortexkit/subc-client';
+import { ClaustrumCredentialError } from './errors.js';
+export type ScopedWatchNotice = {
+    kind: 'changed';
+    epoch: string;
+    seq: number;
+    view: string;
+    keys: string;
+};
+export type ScopedWatchOutcome = {
+    kind: 'refused';
+    error: ClaustrumCredentialError;
+} | {
+    kind: 'ended';
+} | {
+    kind: 'not_accepting';
+} | {
+    kind: 'transport_lost';
+    error: unknown;
+} | {
+    kind: 'unsupported';
+} | {
+    kind: 'stopped';
+};
+export declare class ScopedWatchError extends Error {
+    readonly code: 'invalid_notice' | 'callback_failed' | 'invalid_response';
+    constructor(code: 'invalid_notice' | 'callback_failed' | 'invalid_response');
+}
+export type ScopedWatch = {
+    stop(): void;
+    closed: Promise<ScopedWatchOutcome>;
+};
+export type ScopedWatchOptions = {
+    enrollmentToken?: string;
+};
+/** Decode only the notice schema; sequence gaps and new epochs belong to the consumer. */
+export declare function decodeScopedWatchNotice(bytes: Uint8Array): ScopedWatchNotice;
+export declare function openScopedWatch(client: Pick<SubcClient, 'routeOpen' | 'subscribe' | 'closeRoute'>, identity: BindIdentity, onNotice: (notice: ScopedWatchNotice) => void, options: ScopedWatchOptions, readScoped: () => Promise<unknown>): ScopedWatch;

package/dist/watch.js

@@ -0,0 +1,104 @@
+import { ClaustrumCredentialError } from './errors.js';
+export class ScopedWatchError extends Error {
+    code;
+    constructor(code) {
+        super(`Scoped watch failed: ${code}`);
+        this.code = code;
+        this.name = 'ScopedWatchError';
+    }
+}
+/** Decode only the notice schema; sequence gaps and new epochs belong to the consumer. */
+export function decodeScopedWatchNotice(bytes) {
+    try {
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (value === null || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'epoch,keys,kind,seq,view' ||
+            value.kind !== 'changed' || typeof value.epoch !== 'string' || value.epoch.length === 0 ||
+            !Number.isSafeInteger(value.seq) || value.seq <= 0 ||
+            typeof value.view !== 'string' || typeof value.keys !== 'string')
+            throw new ScopedWatchError('invalid_notice');
+        return value;
+    }
+    catch {
+        throw new ScopedWatchError('invalid_notice');
+    }
+}
+export function openScopedWatch(client, identity, onNotice, options, readScoped) {
+    let settled = false;
+    let notices = 0;
+    let subscription;
+    let route;
+    let resolve;
+    let reject;
+    const closed = new Promise((yes, no) => { resolve = yes; reject = no; });
+    const finish = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        subscription?.unsubscribe();
+        if (route)
+            void client.closeRoute(route).catch(() => { });
+        if (outcome instanceof ScopedWatchError)
+            reject(outcome);
+        else
+            resolve(outcome);
+    };
+    void (async () => {
+        try {
+            route = await client.routeOpen({ kind: 'management_surface', module_id: 'claustrum' }, identity, { consumerIdentity: null });
+            if (settled) {
+                await client.closeRoute(route);
+                return;
+            }
+            subscription = client.subscribe(route, {
+                method: 'auth.watch_scoped',
+                params: options.enrollmentToken === undefined ? {} : { enrollment_token: options.enrollmentToken },
+            }, (bytes) => {
+                if (settled)
+                    return;
+                let notice;
+                try {
+                    notice = decodeScopedWatchNotice(bytes);
+                }
+                catch {
+                    finish(new ScopedWatchError('invalid_notice'));
+                    return;
+                }
+                notices++;
+                try {
+                    onNotice(notice);
+                }
+                catch {
+                    finish(new ScopedWatchError('callback_failed'));
+                }
+            });
+            await subscription.closed;
+            if (settled)
+                return;
+            // The SDK erases Response bodies. Only an immediate close needs a confirming
+            // list read; after notices, the caller reopens once to discover a revocation.
+            if (notices > 0)
+                finish({ kind: 'ended' });
+            else {
+                try {
+                    await readScoped();
+                    finish({ kind: 'not_accepting' });
+                }
+                catch (error) {
+                    if (error instanceof ClaustrumCredentialError && error.code !== 'invalid_response') {
+                        finish({ kind: 'refused', error });
+                    }
+                    else if (error instanceof ClaustrumCredentialError)
+                        finish(new ScopedWatchError('invalid_response'));
+                    else
+                        finish({ kind: 'transport_lost', error });
+                }
+            }
+        }
+        catch (error) {
+            const code = error !== null && typeof error === 'object' && 'code' in error ? error.code : undefined;
+            finish(code === 'unknown_method' ? { kind: 'unsupported' } : { kind: 'transport_lost', error });
+        }
+    })();
+    return { stop: () => finish({ kind: 'stopped' }), closed };
+}

package/dist/wire.d.ts

@@ -1,4 +1,5 @@
 import { SubcClient, type BindIdentity } from '@cortexkit/subc-client';
+import { type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions } from './watch.js';
 export type ClaustrumConnector = (options: {
     connectionFile: string;
     handshakeTimeoutMs?: number;
@@ -107,6 +108,8 @@ export declare class ClaustrumClient {
      * object, so a caller cannot ask a different question by omitting it.
      */
     listScoped(enrollmentToken?: string): Promise<ScopedInventory>;
+    /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
+    watchScoped(onNotice: (notice: ScopedWatchNotice) => void, options?: ScopedWatchOptions): ScopedWatch;
     /**
      * Fetch by credential id, authorized by a grant rather than a bearer handle.
      *

package/dist/wire.js

@@ -2,6 +2,7 @@ import { SubcCallError, SubcClient, } from '@cortexkit/subc-client';
 import { resolveClaustrumConnectionPath } from './detect.js';
 import { asCredentialError, ClaustrumCredentialError, hasCredentialError, } from './errors.js';
 import { storeIdentity } from './identity.js';
+import { openScopedWatch } from './watch.js';
 const CLAUSTRUM_MODULE_ID = 'claustrum';
 const RECONNECT_BACKOFF_MS = 60_000;
 function isRecord(value) {
@@ -163,6 +164,14 @@ export class ClaustrumClient {
         const response = await this.#call('credential.list_scoped', enrollmentToken === undefined ? {} : { enrollment_token: enrollmentToken });
         return decodeScopedInventory(response, this.#logger);
     }
+    /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
+    watchScoped(onNotice, options = {}) {
+        const client = this.#client;
+        return openScopedWatch(client, this.#identity, onNotice, options, async () => {
+            const response = await client.call('claustrum', 'credential.list_scoped', options.enrollmentToken === undefined ? {} : { enrollment_token: options.enrollmentToken }, { identity: this.#identity, consumerIdentity: null });
+            return decodeScopedInventory(response, this.#logger);
+        });
+    }
     /**
      * Fetch by credential id, authorized by a grant rather than a bearer handle.
      *

package/package.json

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