@cortexkit/common-auth 0.20.0 → 0.21.0

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,6 +5,7 @@ import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScoped
5
5
  import { type ClaustrumLogger } from './errors.js';
6
6
  import { type InsulaQuotaOptions } from './insula.js';
7
7
  import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
8
+ import { type WatchMode } from './watch.js';
8
9
  export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
9
10
  /**
10
11
  * The roster file: one row per vault account (route id, credential id,
@@ -41,6 +42,12 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
41
42
  */
42
43
  onRoster?: (roster: VaultRosterFile) => void;
43
44
  onError?: (error: unknown) => void;
45
+ /**
46
+ * How often `start()` ticks. A tick lists the vault when no vault watch is
47
+ * open (before it is accepted, or when the vault or the client cannot
48
+ * watch), and otherwise only every five minutes, as a safety net. A tick
49
+ * polls insula (at most once a minute) only while its watch is not open.
50
+ */
44
51
  pollIntervalMs?: number;
45
52
  setTimeoutImpl?: typeof setTimeout;
46
53
  clearTimeoutImpl?: typeof clearTimeout;
@@ -49,6 +56,15 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
49
56
  /** Optional background quota source. In-band readings still use recordQuota. */
50
57
  insula?: InsulaQuotaOptions<Q>;
51
58
  }
59
+ /**
60
+ * How a started consumer learns about changes, for logs and status displays.
61
+ * `insula` is present when the consumer was given an insula source. Never
62
+ * carries secrets.
63
+ */
64
+ export interface ClaustrumWatchState {
65
+ readonly vault: WatchMode;
66
+ readonly insula?: WatchMode;
67
+ }
52
68
  export interface SendOptions {
53
69
  /**
54
70
  * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -81,11 +97,23 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
81
97
  * held the discovery lease and its newer roster was served instead).
82
98
  */
83
99
  grantReach(): VaultGrantReach | undefined;
100
+ /** How this consumer currently learns about changes, without I/O. */
101
+ watchState(): ClaustrumWatchState;
84
102
  /** Whether any account is using an in-memory outage receipt, without I/O. */
85
103
  keptReceiptState(): KeptReceiptState;
86
104
  /** Rows for `/routing`, from the last committed roster. */
87
105
  routingRows(): RoutingRow[];
88
106
  refresh(): Promise<VaultRosterFile | undefined>;
107
+ /**
108
+ * Poll in the background and open the vault and insula watches. Until the
109
+ * vault watch is accepted, and whenever it is unavailable, every tick lists
110
+ * the vault exactly as before watches existed. While it is open a tick
111
+ * lists only when five minutes have passed since the last discovery, since
112
+ * the watch keeps no history; it still checks `isCustodyActive`, so a switch
113
+ * to local mode closes the connection as quickly as before. Insula is
114
+ * polled on the tick only while its own watch is not open. A host not in
115
+ * vault mode makes no request.
116
+ */
89
117
  start(): void;
90
118
  /**
91
119
  * Fetch on a background tick, at most once per minute across projects with
@@ -5,6 +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
9
  /**
9
10
  * One plugin host's view of its vault accounts. It turns vault credentials
10
11
  * into rows for `/routing`, authorizes each physical send with the vault, and
@@ -18,6 +19,8 @@ export class ClaustrumConsumer {
18
19
  #shutdown = new AbortController();
19
20
  #logger;
20
21
  #custody;
22
+ /** The custody's client, kept so `start()` can open its vault watch. */
23
+ #client;
21
24
  #connecting;
22
25
  #refreshing;
23
26
  #roster;
@@ -29,6 +32,10 @@ export class ClaustrumConsumer {
29
32
  #timer;
30
33
  #started = false;
31
34
  #insula;
35
+ #vaultWatch;
36
+ #releaseInsulaWatch;
37
+ /** When this instance last completed a discovery, by `now`. */
38
+ #discoveredAt;
32
39
  constructor(options) {
33
40
  this.#options = options;
34
41
  this.#logger = options.logger ?? createLogger('claustrum');
@@ -83,6 +90,7 @@ export class ClaustrumConsumer {
83
90
  client.close();
84
91
  this.#assertOpen();
85
92
  }
93
+ this.#client = client;
86
94
  this.#custody = new ClaustrumScopedCustody({
87
95
  client,
88
96
  family: this.#options.family,
@@ -91,6 +99,8 @@ export class ClaustrumConsumer {
91
99
  requireAssertion: this.#options.requireAssertion,
92
100
  now: this.#options.now,
93
101
  logger: this.#logger,
102
+ setTimeoutImpl: this.#options.setTimeoutImpl,
103
+ clearTimeoutImpl: this.#options.clearTimeoutImpl,
94
104
  });
95
105
  if (this.#options.insula && client.insula) {
96
106
  this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
@@ -122,6 +132,23 @@ export class ClaustrumConsumer {
122
132
  ? latest.reach
123
133
  : undefined;
124
134
  }
135
+ /** How this consumer currently learns about changes, without I/O. */
136
+ watchState() {
137
+ return Object.freeze({
138
+ vault: this.#vaultWatch?.mode ?? 'polling',
139
+ ...(this.#options.insula && {
140
+ insula: this.#insula?.source.watchMode() ?? 'polling',
141
+ }),
142
+ });
143
+ }
144
+ /** Close the watches with the connection they belong to. */
145
+ #stopWatch() {
146
+ this.#vaultWatch?.stop();
147
+ this.#vaultWatch = undefined;
148
+ this.#client = undefined;
149
+ this.#releaseInsulaWatch?.();
150
+ this.#releaseInsulaWatch = undefined;
151
+ }
125
152
  /** Whether any account is using an in-memory outage receipt, without I/O. */
126
153
  keptReceiptState() {
127
154
  return (this.#custody?.keptReceiptState() ??
@@ -139,6 +166,7 @@ export class ClaustrumConsumer {
139
166
  if (!(await this.#active())) {
140
167
  this.#roster = undefined;
141
168
  this.#grantReach = undefined;
169
+ this.#stopWatch();
142
170
  this.#custody?.close();
143
171
  this.#custody = undefined;
144
172
  this.#insula?.release();
@@ -181,12 +209,23 @@ export class ClaustrumConsumer {
181
209
  // notification, and the poll runs every few seconds.
182
210
  if (roster && changed)
183
211
  this.#options.onRoster?.(roster);
212
+ this.#discoveredAt = (this.#options.now ?? Date.now)();
184
213
  return roster;
185
214
  })().finally(() => {
186
215
  this.#refreshing = undefined;
187
216
  });
188
217
  return this.#refreshing;
189
218
  }
219
+ /**
220
+ * Poll in the background and open the vault and insula watches. Until the
221
+ * vault watch is accepted, and whenever it is unavailable, every tick lists
222
+ * the vault exactly as before watches existed. While it is open a tick
223
+ * lists only when five minutes have passed since the last discovery, since
224
+ * the watch keeps no history; it still checks `isCustodyActive`, so a switch
225
+ * to local mode closes the connection as quickly as before. Insula is
226
+ * polled on the tick only while its own watch is not open. A host not in
227
+ * vault mode makes no request.
228
+ */
190
229
  start() {
191
230
  if (this.#started)
192
231
  return;
@@ -194,8 +233,10 @@ export class ClaustrumConsumer {
194
233
  this.#started = true;
195
234
  const tick = async () => {
196
235
  try {
197
- await this.refresh();
236
+ if (await this.#listDue())
237
+ await this.refresh();
198
238
  await this.refreshInsulaQuota();
239
+ this.#openWatch();
199
240
  }
200
241
  catch (error) {
201
242
  if (!this.#shutdown.signal.aborted)
@@ -214,6 +255,65 @@ export class ClaustrumConsumer {
214
255
  };
215
256
  void tick();
216
257
  }
258
+ /** Whether a background tick must list the vault now. */
259
+ async #listDue() {
260
+ if (this.#vaultWatch?.mode !== 'watching')
261
+ return true;
262
+ const now = (this.#options.now ?? Date.now)();
263
+ if (this.#discoveredAt === undefined ||
264
+ now - this.#discoveredAt >= SAFETY_POLL_MS)
265
+ return true;
266
+ // refresh() is what closes the connection when the host left vault mode.
267
+ return !(await this.#active());
268
+ }
269
+ /**
270
+ * Open the vault and insula watches once a vault connection exists. Only
271
+ * reached in vault mode: a host in local mode never connects.
272
+ */
273
+ #openWatch() {
274
+ const client = this.#client;
275
+ if (this.#shutdown.signal.aborted || !client || !this.#custody)
276
+ 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);
294
+ 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
+ }
310
+ if (this.#options.insula && this.#insula && !this.#releaseInsulaWatch)
311
+ this.#releaseInsulaWatch = this.#insula.source.watch({
312
+ provider: this.#options.insula.provider,
313
+ setTimeoutImpl: this.#options.setTimeoutImpl,
314
+ clearTimeoutImpl: this.#options.clearTimeoutImpl,
315
+ });
316
+ }
217
317
  /**
218
318
  * Fetch on a background tick, at most once per minute across projects with
219
319
  * the same daemon and enrollment token path. Admission must use the cache
@@ -291,6 +391,7 @@ export class ClaustrumConsumer {
291
391
  if (!roster || !(await this.#active())) {
292
392
  this.#custody?.close();
293
393
  this.#custody = undefined;
394
+ this.#stopWatch();
294
395
  this.#insula?.release();
295
396
  this.#insula = undefined;
296
397
  throw new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
@@ -444,6 +545,7 @@ export class ClaustrumConsumer {
444
545
  if (this.#timer)
445
546
  (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
446
547
  this.#timer = undefined;
548
+ this.#stopWatch();
447
549
  this.#custody?.close();
448
550
  this.#insula?.release();
449
551
  this.#insula = undefined;
@@ -1,9 +1,14 @@
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';
5
+ /**
6
+ * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
7
+ * run time and keep polling without it.
8
+ */
4
9
  export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
5
10
  insula?: InsulaUsageTransport;
6
- };
11
+ } & ScopedWatchSource;
7
12
  /** The two credential types a plugin's family can hold; routing differs by type. */
8
13
  export type VaultCredentialType = 'oauth' | 'api_key';
9
14
  /**
@@ -167,7 +172,7 @@ export declare const KEPT_RECEIPT_MARGIN_MS = 60000;
167
172
  /**
168
173
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
169
174
  * enrollment token as authorization. Used by every host of a plugin. Every
170
- * physical send still asks the vault first. Only an unreachable vault permits
175
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
171
176
  * reuse of the last validated receipt, in memory and bounded by its expiry.
172
177
  * The enrollment token is re-read per operation so revocation and disconnect
173
178
  * still take effect without a process restart.
@@ -190,7 +195,13 @@ export declare class ClaustrumScopedCustody {
190
195
  requireAssertion?: boolean;
191
196
  now?: () => number;
192
197
  logger?: ClaustrumLogger;
198
+ setTimeoutImpl?: typeof setTimeout;
199
+ clearTimeoutImpl?: typeof clearTimeout;
193
200
  });
201
+ /** A watch losing its transport is the same outage as an unreachable read. */
202
+ transportLost(error?: unknown): void;
203
+ /** Any vault answer ends transport fallback, even when it refuses access. */
204
+ reachable(): void;
194
205
  /**
195
206
  * List this consumer's credentials. A record that cannot be used is skipped
196
207
  * and warned about rather than failing the whole list, so one bad record
@@ -198,6 +209,13 @@ export declare class ClaustrumScopedCustody {
198
209
  * skipped records: they simply are not this consumer's.
199
210
  */
200
211
  discover(signal?: AbortSignal): Promise<VaultInventory>;
212
+ /**
213
+ * Apply a failed account listing: any answer from the vault (a refusal such
214
+ * as a revoked enrollment's `not_found`) drops every kept receipt, while an
215
+ * unreachable vault keeps them. A vault watch that ends with the same
216
+ * refusal calls this too, so both paths treat it alike.
217
+ */
218
+ listFailed(error: unknown): void;
201
219
  /** Discard bearer material when a route is removed, declined or rebound. */
202
220
  forget(credentialId: string): void;
203
221
  /** Apply an already-held roster; this never fetches credentials or writes it. */
@@ -207,7 +225,7 @@ export declare class ClaustrumScopedCustody {
207
225
  })[]): void;
208
226
  /** A frozen, non-secret summary for a plugin's status display. */
209
227
  keptReceiptState(): KeptReceiptState;
210
- /** Ask the vault first; retain one validated receipt per credential in memory only. */
228
+ /** Ask the vault while reachable; retain one validated receipt in memory only. */
211
229
  authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal, routeId?: string): Promise<ClaustrumScopedAttempt>;
212
230
  /**
213
231
  * Report that a send this consumer actually made was rejected. Only a 401
@@ -106,7 +106,7 @@ function grantReachOf(listed) {
106
106
  /**
107
107
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
108
108
  * enrollment token as authorization. Used by every host of a plugin. Every
109
- * physical send still asks the vault first. Only an unreachable vault permits
109
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
110
110
  * reuse of the last validated receipt, in memory and bounded by its expiry.
111
111
  * The enrollment token is re-read per operation so revocation and disconnect
112
112
  * still take effect without a process restart.
@@ -123,6 +123,14 @@ export class ClaustrumScopedCustody {
123
123
  #reports = new WeakMap();
124
124
  #kept = new Map();
125
125
  #keptAttempts = new WeakMap();
126
+ #setTimeout;
127
+ #clearTimeout;
128
+ #outage = false;
129
+ #outageError = new ClaustrumUnreachableError();
130
+ #probeTimer;
131
+ #probing = false;
132
+ #lastProbeAt = -Infinity;
133
+ #probeDelay = 2_000;
126
134
  #closed = false;
127
135
  constructor(options) {
128
136
  const tokenPath = options.tokenPath;
@@ -141,6 +149,63 @@ export class ClaustrumScopedCustody {
141
149
  this.#requireAssertion = options.requireAssertion ?? false;
142
150
  this.#now = options.now ?? Date.now;
143
151
  this.#logger = options.logger ?? defaultLogger;
152
+ this.#setTimeout = options.setTimeoutImpl ?? setTimeout;
153
+ this.#clearTimeout = options.clearTimeoutImpl ?? clearTimeout;
154
+ }
155
+ /** A watch losing its transport is the same outage as an unreachable read. */
156
+ transportLost(error) {
157
+ if (this.#closed || this.#outage)
158
+ return;
159
+ this.#outage = true;
160
+ this.#outageError =
161
+ error instanceof ClaustrumCredentialError
162
+ ? error
163
+ : new ClaustrumUnreachableError();
164
+ this.#logger.warn('serving kept vault receipt', { reason: 'unreachable' });
165
+ this.#scheduleProbe();
166
+ }
167
+ /** Any vault answer ends transport fallback, even when it refuses access. */
168
+ reachable() {
169
+ if (this.#closed || !this.#outage)
170
+ return;
171
+ this.#outage = false;
172
+ if (this.#probeTimer)
173
+ this.#clearTimeout(this.#probeTimer);
174
+ this.#probeTimer = undefined;
175
+ this.#probeDelay = 2_000;
176
+ for (const kept of this.#kept.values())
177
+ kept.since = null;
178
+ (this.#logger.info ?? defaultLogger.info)('vault receipt serving resumed', { reason: 'reachable' });
179
+ }
180
+ #scheduleProbe() {
181
+ if (this.#closed || !this.#outage || this.#probeTimer || this.#probing)
182
+ return;
183
+ this.#probeTimer = this.#setTimeout(() => {
184
+ this.#probeTimer = undefined;
185
+ this.#probe(true);
186
+ }, this.#probeDelay);
187
+ this.#probeTimer.unref?.();
188
+ }
189
+ #probe(idle = false) {
190
+ if (this.#closed || !this.#outage || this.#probing)
191
+ return;
192
+ if (this.#now() - this.#lastProbeAt < 1_000) {
193
+ this.#scheduleProbe();
194
+ return;
195
+ }
196
+ this.#lastProbeAt = this.#now();
197
+ this.#probing = true;
198
+ // Both triggers share list_scoped discovery, including its receipt-drop rules.
199
+ // Sends never await discovery or let idle backoff delay the next send probe.
200
+ void this.discover()
201
+ .catch(() => {
202
+ if (idle && this.#outage)
203
+ this.#probeDelay = Math.min(this.#probeDelay * 2, 30_000);
204
+ })
205
+ .finally(() => {
206
+ this.#probing = false;
207
+ this.#scheduleProbe();
208
+ });
144
209
  }
145
210
  #check(signal) {
146
211
  if (this.#closed)
@@ -179,6 +244,10 @@ export class ClaustrumScopedCustody {
179
244
  }
180
245
  catch (error) {
181
246
  this.#check(signal);
247
+ if (classifyVaultFailure(error) === 'unreachable')
248
+ this.transportLost(error);
249
+ else
250
+ this.reachable();
182
251
  // Keep the vault's own refusals (ClaustrumCredentialError, carrying
183
252
  // code, class and action); replace any other error, whose text may echo
184
253
  // request params that include the enrollment token.
@@ -192,6 +261,7 @@ export class ClaustrumScopedCustody {
192
261
  removeAbortListener?.();
193
262
  }
194
263
  this.#check(signal);
264
+ this.reachable();
195
265
  return result;
196
266
  }
197
267
  /**
@@ -214,8 +284,7 @@ export class ClaustrumScopedCustody {
214
284
  inventory = await this.#call(() => this.#client.listScoped(token), signal);
215
285
  }
216
286
  catch (error) {
217
- if (classifyVaultFailure(error) !== 'unreachable')
218
- this.#kept.clear();
287
+ this.listFailed(error);
219
288
  throw error;
220
289
  }
221
290
  const skipped = [];
@@ -264,6 +333,20 @@ export class ClaustrumScopedCustody {
264
333
  ...(grantReach && { grantReach }),
265
334
  };
266
335
  }
336
+ /**
337
+ * Apply a failed account listing: any answer from the vault (a refusal such
338
+ * as a revoked enrollment's `not_found`) drops every kept receipt, while an
339
+ * unreachable vault keeps them. A vault watch that ends with the same
340
+ * refusal calls this too, so both paths treat it alike.
341
+ */
342
+ listFailed(error) {
343
+ if (classifyVaultFailure(error) === 'unreachable')
344
+ this.transportLost(error);
345
+ else {
346
+ this.reachable();
347
+ this.#kept.clear();
348
+ }
349
+ }
267
350
  /** Discard bearer material when a route is removed, declined or rebound. */
268
351
  forget(credentialId) {
269
352
  this.#kept.delete(credentialId);
@@ -298,7 +381,7 @@ export class ClaustrumScopedCustody {
298
381
  ? attempt.credentialType === 'api_key'
299
382
  : attempt.expiresAtMs - this.#now() > KEPT_RECEIPT_MARGIN_MS;
300
383
  }
301
- /** Ask the vault first; retain one validated receipt per credential in memory only. */
384
+ /** Ask the vault while reachable; retain one validated receipt in memory only. */
302
385
  async authorize(identity, signal, routeId = 'vault') {
303
386
  this.#check(signal);
304
387
  const { credentialId, credentialType, accountIdentity } = identity;
@@ -318,10 +401,12 @@ export class ClaustrumScopedCustody {
318
401
  this.#kept.clear();
319
402
  throw error;
320
403
  }
404
+ if (this.#outage && kept) {
405
+ this.#probe();
406
+ return this.#serveKept(credentialId, kept, token, routeId);
407
+ }
321
408
  try {
322
409
  const attempt = await this.#authorizeFresh({ credentialId, credentialType, accountIdentity }, token, signal);
323
- if (kept?.since !== null && kept?.since !== undefined)
324
- (this.#logger.info ?? defaultLogger.info)('vault receipt serving resumed', { routeId, reason: 'reachable' });
325
410
  this.#kept.set(credentialId, { attempt, routeId, since: null });
326
411
  return attempt;
327
412
  }
@@ -331,26 +416,24 @@ export class ClaustrumScopedCustody {
331
416
  this.forget(credentialId);
332
417
  throw error;
333
418
  }
334
- // A concurrent refusal or 401 may already have discarded this entry.
335
- if (!kept ||
336
- this.#kept.get(credentialId) !== kept ||
337
- !this.#usable(kept.attempt)) {
338
- this.forget(credentialId);
339
- throw error;
340
- }
341
- if (kept.since === null) {
342
- kept.since = this.#now();
343
- this.#logger.warn('serving kept vault receipt', {
344
- routeId,
345
- reason: 'unreachable',
346
- });
347
- }
348
- const attempt = Object.freeze(Object.defineProperty({ ...kept.attempt, fromKeptReceipt: true }, 'accessToken', { value: kept.attempt.accessToken, enumerable: false }));
349
- this.#provenance.set(attempt, token);
350
- this.#keptAttempts.set(attempt, routeId);
351
- return attempt;
419
+ return this.#serveKept(credentialId, kept, token, routeId, error);
352
420
  }
353
421
  }
422
+ #serveKept(credentialId, kept, token, routeId, error = this.#outageError) {
423
+ // A concurrent refusal or 401 may already have discarded this entry.
424
+ if (!kept ||
425
+ this.#kept.get(credentialId) !== kept ||
426
+ !this.#usable(kept.attempt)) {
427
+ this.forget(credentialId);
428
+ throw error;
429
+ }
430
+ if (kept.since === null)
431
+ kept.since = this.#now();
432
+ const attempt = Object.freeze(Object.defineProperty({ ...kept.attempt, fromKeptReceipt: true }, 'accessToken', { value: kept.attempt.accessToken, enumerable: false }));
433
+ this.#provenance.set(attempt, token);
434
+ this.#keptAttempts.set(attempt, routeId);
435
+ return attempt;
436
+ }
354
437
  /**
355
438
  * Fetch and validate a fresh receipt before retaining it. The vault assertion
356
439
  * (or the plugin's token parse) must agree with the roster when both exist.
@@ -488,6 +571,9 @@ export class ClaustrumScopedCustody {
488
571
  if (this.#closed)
489
572
  return;
490
573
  this.#closed = true;
574
+ if (this.#probeTimer)
575
+ this.#clearTimeout(this.#probeTimer);
576
+ this.#probeTimer = undefined;
491
577
  this.#kept.clear();
492
578
  this.#client.close();
493
579
  }
@@ -2,14 +2,15 @@ import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
2
2
  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
- export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
5
+ export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
6
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';
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';
10
- export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWindow, } from './insula.js';
10
+ export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWatch, type InsulaUsageWindow, type InsulaWatchOptions, } from './insula.js';
11
11
  export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
12
12
  export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
13
+ export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
13
14
  /**
14
15
  * Connect the client that lists and fetches this consumer's vault credentials
15
16
  * on the request path. `connectionFile` is required: this library
@@ -15,6 +15,7 @@ export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHO
15
15
  export { acquireInsulaQuotaSource, } from './insula.js';
16
16
  export { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
17
17
  export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
18
+ export { ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, WATCH_RETRY_MS, } from './watch.js';
18
19
  /**
19
20
  * Connect the client that lists and fetches this consumer's vault credentials
20
21
  * on the request path. `connectionFile` is required: this library
@@ -1,4 +1,5 @@
1
1
  import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
2
+ import { type WatchMode } from './watch.js';
2
3
  /** Insula's window fields are open: plugins choose which limits they understand. */
3
4
  export interface InsulaUsageWindow {
4
5
  usedPercent: number;
@@ -43,21 +44,68 @@ export interface InsulaQuotaOptions<Q> {
43
44
  */
44
45
  normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
45
46
  }
47
+ /**
48
+ * A held-open `usage.watch` stream. `closed` resolves when insula ends the
49
+ * stream (STREAM_END at shutdown, or a reply that ends it) or after `stop()`,
50
+ * and rejects with insula's refusal (an error with a `code`, such as
51
+ * `unknown_method` from an insula that predates the method, or
52
+ * `usage_watch_limit` when 64 watches are already open) or with the
53
+ * transport failure.
54
+ */
55
+ export interface InsulaUsageWatch {
56
+ stop(): void;
57
+ readonly closed: Promise<void>;
58
+ }
46
59
  /** Optional transport for custom scoped clients; getUsage must not retry refusals. */
47
60
  export interface InsulaUsageTransport {
48
61
  connectionFile: string;
49
62
  getUsage(): Promise<unknown>;
63
+ /**
64
+ * Open a `usage.watch` stream, passing each notice's raw JSON body to
65
+ * `onNotice`. Optional: a transport without it is polled as before.
66
+ */
67
+ watchUsage?(onNotice: (body: Uint8Array) => void): InsulaUsageWatch;
50
68
  }
51
69
  /** Constructing this transport opens no connection; getUsage opens one per call. */
52
70
  export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
53
71
  connectionFile: string;
54
72
  }): InsulaUsageTransport;
73
+ export interface InsulaWatchOptions {
74
+ /**
75
+ * The provider this watcher reads. A notice that names only other
76
+ * providers then needs no read; unset means every notice does.
77
+ */
78
+ provider?: string;
79
+ /**
80
+ * setTimeout and clearTimeout for the waits before re-subscribing or retrying
81
+ * a watch. Defaults to the global timers; tests inject virtual ones.
82
+ */
83
+ setTimeoutImpl?: typeof setTimeout;
84
+ clearTimeoutImpl?: typeof clearTimeout;
85
+ }
55
86
  export declare class InsulaQuotaSource {
56
87
  #private;
57
88
  private readonly transport;
58
89
  private readonly key;
59
90
  constructor(transport: InsulaUsageTransport, key: string);
91
+ /**
92
+ * The background poll: at most one usage.get per minute per daemon and
93
+ * enrollment token. While a watch is open it reads nothing, because insula's
94
+ * notices announce every new reading. If insula stops announcing an account,
95
+ * that account's last entry grows older than the freshness limit `current()`
96
+ * applies, `current()` returns nothing for it, and the plugin falls back to
97
+ * its own provider poll for that account.
98
+ */
60
99
  refresh(now: number): Promise<void>;
100
+ /** How this source currently learns about usage changes, for logs. */
101
+ watchMode(): WatchMode;
102
+ /**
103
+ * Hold a `usage.watch` open while any watcher wants it, and re-read
104
+ * usage.get when a notice says something changed. Watchers of one source
105
+ * share one watch, since insula admits only 64 per process. Returns the
106
+ * release; the last release closes the watch.
107
+ */
108
+ watch(options?: InsulaWatchOptions): () => void;
61
109
  current(provider: string, accountId: string, now: number): {
62
110
  entry: InsulaUsageEntry;
63
111
  context: InsulaQuotaContext;