@cortexkit/common-auth 0.21.0 → 0.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@ import { readClaustrumEnrollmentToken } from './enrollment.js';
5
5
  import { ClaustrumConsumerError } from './errors.js';
6
6
  import { acquireInsulaQuotaSource } from './insula.js';
7
7
  import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
8
- import { SAFETY_POLL_MS, ScopedRosterWatch } from './watch.js';
8
+ import { SAFETY_POLL_MS } from './watch.js';
9
9
  /**
10
10
  * One plugin host's view of its vault accounts. It turns vault credentials
11
11
  * into rows for `/routing`, authorizes each physical send with the vault, and
@@ -19,8 +19,6 @@ export class ClaustrumConsumer {
19
19
  #shutdown = new AbortController();
20
20
  #logger;
21
21
  #custody;
22
- /** The custody's client, kept so `start()` can open its vault watch. */
23
- #client;
24
22
  #connecting;
25
23
  #refreshing;
26
24
  #roster;
@@ -90,7 +88,6 @@ export class ClaustrumConsumer {
90
88
  client.close();
91
89
  this.#assertOpen();
92
90
  }
93
- this.#client = client;
94
91
  this.#custody = new ClaustrumScopedCustody({
95
92
  client,
96
93
  family: this.#options.family,
@@ -143,9 +140,8 @@ export class ClaustrumConsumer {
143
140
  }
144
141
  /** Close the watches with the connection they belong to. */
145
142
  #stopWatch() {
146
- this.#vaultWatch?.stop();
143
+ this.#vaultWatch?.close();
147
144
  this.#vaultWatch = undefined;
148
- this.#client = undefined;
149
145
  this.#releaseInsulaWatch?.();
150
146
  this.#releaseInsulaWatch = undefined;
151
147
  }
@@ -271,42 +267,30 @@ export class ClaustrumConsumer {
271
267
  * reached in vault mode: a host in local mode never connects.
272
268
  */
273
269
  #openWatch() {
274
- const client = this.#client;
275
- if (this.#shutdown.signal.aborted || !client || !this.#custody)
270
+ const custody = this.#custody;
271
+ if (this.#shutdown.signal.aborted || !custody)
276
272
  return;
277
- if (!this.#vaultWatch) {
278
- const watch = new ScopedRosterWatch({
279
- client,
280
- enrollmentToken: async () => (await readClaustrumEnrollmentToken(this.#options.tokenPath)).token,
281
- view: () => this.#roster?.view,
282
- // The existing discovery, so a watched change commits the roster and
283
- // re-applies it to kept receipts exactly as a poll does. A refresh
284
- // already in flight may have listed before the change was announced,
285
- // so wait for it and list again.
286
- discover: async () => {
287
- while (this.#refreshing)
288
- await this.#refreshing.catch(() => { });
289
- await this.refresh();
290
- },
291
- onRefused: (error) => {
292
- // As a poll that met the same refusal from list_scoped would.
293
- this.#custody?.listFailed(error);
273
+ // The same entry point a host without a consumer uses, so both apply
274
+ // notices, refusals and outages alike.
275
+ this.#vaultWatch ??= custody.watchRoster({
276
+ view: () => this.#roster?.view,
277
+ // The existing discovery, so a watched change commits the roster and
278
+ // re-applies it to kept receipts exactly as a poll does. A refresh
279
+ // already in flight may have listed before the change was announced,
280
+ // so wait for it and list again.
281
+ onView: async () => {
282
+ while (this.#refreshing)
283
+ await this.#refreshing.catch(() => { });
284
+ await this.refresh();
285
+ },
286
+ // Custody has dropped kept receipts, as a poll meeting the same
287
+ // refusal from list_scoped would.
288
+ onRefused: (error) => this.#options.onError?.(error),
289
+ onError: (error) => {
290
+ if (!this.#shutdown.signal.aborted)
294
291
  this.#options.onError?.(error);
295
- },
296
- onTransportLost: () => this.#custody?.transportLost(),
297
- onReachable: () => this.#custody?.reachable(),
298
- onError: (error) => {
299
- if (!this.#shutdown.signal.aborted)
300
- this.#options.onError?.(error);
301
- },
302
- logger: this.#logger,
303
- now: this.#options.now,
304
- setTimeoutImpl: this.#options.setTimeoutImpl,
305
- clearTimeoutImpl: this.#options.clearTimeoutImpl,
306
- });
307
- this.#vaultWatch = watch;
308
- watch.start();
309
- }
292
+ },
293
+ });
310
294
  if (this.#options.insula && this.#insula && !this.#releaseInsulaWatch)
311
295
  this.#releaseInsulaWatch = this.#insula.source.watch({
312
296
  provider: this.#options.insula.provider,
@@ -1,7 +1,7 @@
1
1
  import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
2
2
  import { type ClaustrumLogger } from './errors.js';
3
3
  import type { InsulaUsageTransport } from './insula.js';
4
- import type { ScopedWatchSource } from './watch.js';
4
+ import { type ScopedWatchSource, type WatchMode } from './watch.js';
5
5
  /**
6
6
  * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
7
7
  * run time and keep polling without it.
@@ -149,6 +149,46 @@ export interface KeptReceiptState {
149
149
  readonly active: boolean;
150
150
  readonly since: number | null;
151
151
  }
152
+ export interface ClaustrumRosterWatchOptions {
153
+ /**
154
+ * Run the host's own discovery (`custody.discover()`, then its roster
155
+ * commit). Called with the newest notice's view when that view differs from
156
+ * the last discovered one, when a notice shows a sequence gap or a new
157
+ * epoch, and on the first notice of a watch re-opened after a close (the
158
+ * time between two watches was not observed). One call runs at a time;
159
+ * notices that arrive meanwhile earn at most one more call, which runs only
160
+ * if the view still differs. A rejection goes to `onError`.
161
+ */
162
+ onView: (view: string) => unknown;
163
+ /**
164
+ * The view of the roster the host last committed. Defaults to the view of
165
+ * the last successful `custody.discover()` (outage probes excluded). Pass it
166
+ * when the host can commit a roster it did not list itself (a peer process
167
+ * held the discovery lease) or can fail after listing.
168
+ */
169
+ view?: () => string | undefined;
170
+ /**
171
+ * Called whenever the mode changes. The watch starts in `polling`. Keep the
172
+ * host's own list timer at its usual pace unless the mode is `watching`.
173
+ */
174
+ onMode?: (mode: WatchMode) => void;
175
+ /**
176
+ * The vault refused the watch, and its confirming `list_scoped` read it with
177
+ * this error (a revoked enrollment answers `not_found`). Custody has already
178
+ * applied it as it applies a refused discovery (`listFailed`: every kept
179
+ * receipt is dropped); handle it as the host handles that refusal.
180
+ */
181
+ onRefused?: (error: unknown) => void;
182
+ /** A failed `onView`, or a watch that could not be opened. */
183
+ onError?: (error: unknown) => void;
184
+ }
185
+ /** A vault watch held by a custody; see `ClaustrumScopedCustody.watchRoster`. */
186
+ export interface ClaustrumRosterWatch {
187
+ /** How the host currently learns about changes. */
188
+ readonly mode: WatchMode;
189
+ /** Stop the watch and its timers. Safe to call more than once. */
190
+ close(): void;
191
+ }
152
192
  /** Reads the provider identity a served token executes under, when the plugin can tell. */
153
193
  export type IdentityParser = (accessToken: string) => string | undefined;
154
194
  /** Only a new version of the same account may replace an in-flight 401. */
@@ -235,5 +275,25 @@ export declare class ClaustrumScopedCustody {
235
275
  * custody did not issue is refused rather than reported.
236
276
  */
237
277
  reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
278
+ /**
279
+ * Watch this consumer's visible vault accounts instead of listing them on a
280
+ * short timer. Opens one `watchScoped` on this custody's client and calls
281
+ * `onView` when the host must run its discovery (see
282
+ * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
283
+ * (before 0.12.0) or a vault that answers `unknown_method` reports
284
+ * `fallback` and opens nothing. A watch that closes before any notice was
285
+ * never accepted: the client reads once to learn why, and the watch reports
286
+ * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
287
+ * loop. A watch that closes after notices is re-opened after
288
+ * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
289
+ * starts this custody's outage, exactly as an unreachable call does, and
290
+ * the first notice of a watch ends it. Timers are unreferenced; `close()`
291
+ * on the returned watch or on this custody stops it.
292
+ *
293
+ * The watch keeps no history, so the host still lists on a slow timer while
294
+ * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
295
+ * other mode the host keeps its usual list timer.
296
+ */
297
+ watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
238
298
  close(): void;
239
299
  }
@@ -4,6 +4,7 @@ import { ClaustrumUnreachableError, classifyVaultFailure, } from './availability
4
4
  import { readClaustrumEnrollmentToken } from './enrollment.js';
5
5
  import { ClaustrumConsumerError } from './errors.js';
6
6
  import { CUSTODY_PLACEHOLDER_PREFIX } from './host-slot.js';
7
+ import { ScopedRosterWatch, } from './watch.js';
7
8
  /** Only a new version of the same account may replace an in-flight 401. */
8
9
  export function isScopedCredentialRotation(served, current) {
9
10
  return (current !== undefined &&
@@ -132,6 +133,9 @@ export class ClaustrumScopedCustody {
132
133
  #lastProbeAt = -Infinity;
133
134
  #probeDelay = 2_000;
134
135
  #closed = false;
136
+ /** The view of the last successful `discover()`, for `watchRoster`. */
137
+ #discoveredView;
138
+ #watches = new Set();
135
139
  constructor(options) {
136
140
  const tokenPath = options.tokenPath;
137
141
  if (options.readToken) {
@@ -197,7 +201,9 @@ export class ClaustrumScopedCustody {
197
201
  this.#probing = true;
198
202
  // Both triggers share list_scoped discovery, including its receipt-drop rules.
199
203
  // Sends never await discovery or let idle backoff delay the next send probe.
200
- void this.discover()
204
+ // A probe commits no roster, so it is not the host's discovery and does
205
+ // not move the view a roster watch compares notices against.
206
+ void this.#list()
201
207
  .catch(() => {
202
208
  if (idle && this.#outage)
203
209
  this.#probeDelay = Math.min(this.#probeDelay * 2, 30_000);
@@ -271,6 +277,11 @@ export class ClaustrumScopedCustody {
271
277
  * skipped records: they simply are not this consumer's.
272
278
  */
273
279
  async discover(signal) {
280
+ const inventory = await this.#list(signal);
281
+ this.#discoveredView = inventory.view;
282
+ return inventory;
283
+ }
284
+ async #list(signal) {
274
285
  let inventory;
275
286
  let token;
276
287
  try {
@@ -567,6 +578,61 @@ export class ClaustrumScopedCustody {
567
578
  throw error;
568
579
  }
569
580
  }
581
+ /**
582
+ * Watch this consumer's visible vault accounts instead of listing them on a
583
+ * short timer. Opens one `watchScoped` on this custody's client and calls
584
+ * `onView` when the host must run its discovery (see
585
+ * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
586
+ * (before 0.12.0) or a vault that answers `unknown_method` reports
587
+ * `fallback` and opens nothing. A watch that closes before any notice was
588
+ * never accepted: the client reads once to learn why, and the watch reports
589
+ * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
590
+ * loop. A watch that closes after notices is re-opened after
591
+ * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
592
+ * starts this custody's outage, exactly as an unreachable call does, and
593
+ * the first notice of a watch ends it. Timers are unreferenced; `close()`
594
+ * on the returned watch or on this custody stops it.
595
+ *
596
+ * The watch keeps no history, so the host still lists on a slow timer while
597
+ * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
598
+ * other mode the host keeps its usual list timer.
599
+ */
600
+ watchRoster(options) {
601
+ this.#check();
602
+ const watch = new ScopedRosterWatch({
603
+ client: this.#client,
604
+ enrollmentToken: () => this.#token(),
605
+ view: options.view ?? (() => this.#discoveredView),
606
+ discover: async (view) => {
607
+ await options.onView(view);
608
+ },
609
+ onRefused: (error) => {
610
+ // Apply a refused watch as discover() applies a refused account
611
+ // listing: every kept receipt is dropped.
612
+ this.listFailed(error);
613
+ options.onRefused?.(error);
614
+ },
615
+ onTransportLost: () => this.transportLost(),
616
+ onReachable: () => this.reachable(),
617
+ onError: options.onError,
618
+ onMode: options.onMode,
619
+ logger: this.#logger,
620
+ now: this.#now,
621
+ setTimeoutImpl: this.#setTimeout,
622
+ clearTimeoutImpl: this.#clearTimeout,
623
+ });
624
+ this.#watches.add(watch);
625
+ watch.start();
626
+ return {
627
+ get mode() {
628
+ return watch.mode;
629
+ },
630
+ close: () => {
631
+ this.#watches.delete(watch);
632
+ watch.stop();
633
+ },
634
+ };
635
+ }
570
636
  close() {
571
637
  if (this.#closed)
572
638
  return;
@@ -574,6 +640,9 @@ export class ClaustrumScopedCustody {
574
640
  if (this.#probeTimer)
575
641
  this.#clearTimeout(this.#probeTimer);
576
642
  this.#probeTimer = undefined;
643
+ for (const watch of this.#watches)
644
+ watch.stop();
645
+ this.#watches.clear();
577
646
  this.#kept.clear();
578
647
  this.#client.close();
579
648
  }
@@ -3,7 +3,7 @@ import type { ClaustrumScopedClient } from './custody.js';
3
3
  export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
4
4
  export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
5
5
  export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
6
- export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
6
+ export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
7
7
  export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
8
8
  export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
9
9
  export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
@@ -106,8 +106,9 @@ export interface ScopedRosterWatchOptions {
106
106
  /**
107
107
  * The host's existing discovery: `list_scoped`, the roster commit and
108
108
  * everything that follows it. The watch never reads the vault list itself.
109
+ * `view` is the view the newest notice carried.
109
110
  */
110
- discover: () => Promise<unknown>;
111
+ discover: (view: string) => Promise<unknown>;
111
112
  /**
112
113
  * The vault refused the watch, and the confirming `list_scoped` read it
113
114
  * with this error (a revoked enrollment ends both with `not_found`). Handle
@@ -109,8 +109,9 @@ export class ScopedRosterWatch {
109
109
  this.#reads = new CoalescedRead(async () => {
110
110
  const force = this.#force;
111
111
  this.#force = false;
112
+ // A read is only ever requested by a notice, which set #latestView.
112
113
  if (force || this.#latestView !== this.#options.view())
113
- await this.#options.discover();
114
+ await this.#options.discover(this.#latestView ?? '');
114
115
  }, (error) => {
115
116
  if (!this.#stopped)
116
117
  this.#options.onError?.(error);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cortexkit/common-auth",
3
- "version": "0.21.0",
3
+ "version": "0.21.1",
4
4
  "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
5
5
  "license": "MIT",
6
6
  "repository": {