@cortexkit/common-auth 0.25.0 → 0.27.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.
Files changed (38) hide show
  1. package/dist/claustrum/consumer.d.ts +63 -2
  2. package/dist/claustrum/consumer.js +250 -9
  3. package/dist/claustrum/custody.d.ts +36 -1
  4. package/dist/claustrum/custody.js +95 -11
  5. package/dist/claustrum/hub.d.ts +187 -0
  6. package/dist/claustrum/hub.js +960 -0
  7. package/dist/claustrum/index.d.ts +3 -2
  8. package/dist/claustrum/index.js +2 -1
  9. package/dist/claustrum/quota-writer.js +4 -54
  10. package/dist/claustrum/roster.d.ts +47 -0
  11. package/dist/claustrum/roster.js +74 -3
  12. package/dist/claustrum/shutdown.d.ts +8 -0
  13. package/dist/claustrum/shutdown.js +42 -0
  14. package/dist/fs/refresh-file-lock.d.ts +1 -1
  15. package/dist/fs/refresh-file-lock.js +20 -11
  16. package/dist/opencode2/errors.d.ts +4 -1
  17. package/dist/opencode2/index.d.ts +2 -2
  18. package/dist/opencode2/index.js +1 -1
  19. package/dist/opencode2/install.d.ts +7 -5
  20. package/dist/opencode2/install.js +139 -13
  21. package/dist/opencode2/types.d.ts +42 -10
  22. package/dist/quota/pending.d.ts +11 -0
  23. package/dist/quota/pending.js +48 -0
  24. package/dist/redaction/index.d.ts +8 -0
  25. package/dist/redaction/index.js +490 -0
  26. package/dist/rpc/rpc-server.js +29 -19
  27. package/dist/setup/command.js +52 -14
  28. package/dist/setup/register.d.ts +2 -0
  29. package/dist/setup/register.js +90 -11
  30. package/dist/store/attribution.d.ts +5 -0
  31. package/dist/store/attribution.js +39 -25
  32. package/dist/store/pool.d.ts +17 -0
  33. package/dist/store/pool.js +18 -3
  34. package/dist/store/pull.js +3 -1
  35. package/dist/store/quota-writer.d.ts +40 -0
  36. package/dist/store/quota-writer.js +298 -0
  37. package/dist/store/runtime.d.ts +2 -0
  38. package/package.json +6 -2
@@ -3,8 +3,9 @@ import type { QuotaObservation } from '../quota/index.js';
3
3
  import type { RoutingRow } from '../routing/index.js';
4
4
  import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
5
5
  import { type ClaustrumLogger } from './errors.js';
6
+ import type { CustodyLease } from './hub.js';
6
7
  import { type InsulaQuotaOptions, type InsulaQuotaResult } from './insula.js';
7
- import { type AccountMapper, type QuotaReceipt, type ReorderVaultRosterResult, type VaultRosterFile } from './roster.js';
8
+ import { type AccountMapper, type ProjectionOptions, type QuotaReceipt, type ReorderVaultRosterResult, type VaultRosterFile } from './roster.js';
8
9
  import { type WatchMode } from './watch.js';
9
10
  export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
10
11
  /**
@@ -65,6 +66,66 @@ export interface ClaustrumWatchState {
65
66
  readonly vault: WatchMode;
66
67
  readonly insula?: WatchMode;
67
68
  }
69
+ /**
70
+ * What a hub member asks of the `ClaustrumDiscoveryHub` that built it.
71
+ * Package-internal: the hub implements it, and `/claustrum` exports neither
72
+ * it nor `createHubMember`.
73
+ */
74
+ export interface HubMemberPort {
75
+ readonly provider: string;
76
+ /** The member's `start()`: make sure the hub's own driver runs. */
77
+ start(): void;
78
+ /**
79
+ * One hub refresh, coalesced across members (one list, one fan-out).
80
+ * Undefined while vault mode is off, or when the connection it ran on was
81
+ * ended before its fan-out finished. `errors` holds each member's own
82
+ * commit error; a failed list rejects instead.
83
+ */
84
+ refresh(): Promise<HubRefreshOutcome | undefined>;
85
+ /**
86
+ * The hub's authority read. The hub, not the member, decides what a false
87
+ * read means: it runs its inactive transition on the first one.
88
+ */
89
+ readAuthority(): Promise<boolean>;
90
+ acquire(signal?: AbortSignal): Promise<CustodyLease>;
91
+ /** False once a lease was released or its connection ended. */
92
+ leaseLive(lease: CustodyLease): boolean;
93
+ /** The hub's grant reach, only while `view` is the view it was read with. */
94
+ grantReach(view: string | undefined): VaultGrantReach | undefined;
95
+ watchMode(): WatchMode;
96
+ keptReceiptState(): KeptReceiptState;
97
+ /** Apply the union of every member's roster in memory to kept receipts. */
98
+ retainUnion(): void;
99
+ forget(credentialId: string): void;
100
+ /** The member closed: the hub stops committing and pushing to it. */
101
+ detach(): void;
102
+ }
103
+ export interface HubRefreshOutcome {
104
+ readonly errors: ReadonlyMap<string, unknown>;
105
+ }
106
+ /** What the hub may do to one member's memory. Package-internal. */
107
+ export interface HubMemberHooks {
108
+ /**
109
+ * Set the roster in memory as a consumer's own refresh does (pending quota
110
+ * readings included) and notify `onRoster` when its view changed.
111
+ */
112
+ install(roster: VaultRosterFile): void;
113
+ /** Vault mode went off: forget the roster. */
114
+ reset(): void;
115
+ roster(): VaultRosterFile | undefined;
116
+ projection(): ProjectionOptions;
117
+ onError(error: unknown): void;
118
+ }
119
+ /**
120
+ * Build the consumer for one hub member. `options` holds only what the member
121
+ * uses: the hub's roster path for this member and the member's own fields.
122
+ * Hub-mode paths never read `tokenPath`, `family` or `connect`, which the hub
123
+ * owns. Package-internal: only `ClaustrumDiscoveryHub.member` calls it.
124
+ */
125
+ export declare function createHubMember<Q>(port: HubMemberPort, options: ClaustrumConsumerOptions<Q>): {
126
+ consumer: ClaustrumConsumer<Q>;
127
+ hooks: HubMemberHooks;
128
+ };
68
129
  export interface SendOptions {
69
130
  /**
70
131
  * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -179,6 +240,6 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
179
240
  */
180
241
  recordAccountQuota(routeId: string, accountIdentity: string, observation: QuotaObservation): Promise<boolean>;
181
242
  close(): void;
182
- /** Close immediately; the last consumer also waits for the writer's bounded drain. */
243
+ /** Close immediately; background work gets 2 s and the quota writer its own 1 s. */
183
244
  dispose(): Promise<void>;
184
245
  }
@@ -6,7 +6,23 @@ import { ClaustrumConsumerError } from './errors.js';
6
6
  import { acquireInsulaQuotaSource, } from './insula.js';
7
7
  import { pendingVaultQuota, retainVaultQuotaWriter } from './quota-writer.js';
8
8
  import { acceptVaultRoute, applyVaultQuota, declineVaultRoute, forgetPendingVaultDiscovery, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, vaultRoutingRows, } from './roster.js';
9
+ import { drainShutdown, shutdownWarning } from './shutdown.js';
9
10
  import { SAFETY_POLL_MS } from './watch.js';
11
+ let buildHubMember;
12
+ /**
13
+ * Build the consumer for one hub member. `options` holds only what the member
14
+ * uses: the hub's roster path for this member and the member's own fields.
15
+ * Hub-mode paths never read `tokenPath`, `family` or `connect`, which the hub
16
+ * owns. Package-internal: only `ClaustrumDiscoveryHub.member` calls it.
17
+ */
18
+ export function createHubMember(port, options) {
19
+ if (!buildHubMember)
20
+ throw new Error('ClaustrumConsumer is not initialized');
21
+ return buildHubMember(port, options);
22
+ }
23
+ function notActive() {
24
+ return new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
25
+ }
10
26
  /**
11
27
  * One plugin host's view of its vault accounts. It turns vault credentials
12
28
  * into rows for `/routing`, authorizes each physical send with the vault, and
@@ -19,6 +35,7 @@ export class ClaustrumConsumer {
19
35
  #options;
20
36
  #shutdown = new AbortController();
21
37
  #logger;
38
+ #warnShutdown;
22
39
  #custody;
23
40
  #connecting;
24
41
  #refreshing;
@@ -30,6 +47,8 @@ export class ClaustrumConsumer {
30
47
  #grantReach;
31
48
  #timer;
32
49
  #started = false;
50
+ #pending = new Set();
51
+ #disposing;
33
52
  #insula;
34
53
  #vaultWatch;
35
54
  #releaseInsulaWatch;
@@ -37,9 +56,23 @@ export class ClaustrumConsumer {
37
56
  /** When this instance last completed a discovery, by `now`. */
38
57
  #discoveredAt;
39
58
  #releaseQuotaWriter;
59
+ /** Set only on a member built by `ClaustrumDiscoveryHub.member`. */
60
+ #hub;
61
+ /** A hub member's one custody lease at a time. */
62
+ #lease;
63
+ /** The lease that issued each receipt, so a 401 goes back through it. */
64
+ #issuedBy = new WeakMap();
65
+ static {
66
+ buildHubMember = (port, options) => {
67
+ const consumer = new ClaustrumConsumer(options);
68
+ consumer.#hub = port;
69
+ return { consumer, hooks: consumer.#hubHooks() };
70
+ };
71
+ }
40
72
  constructor(options) {
41
73
  this.#options = options;
42
74
  this.#logger = options.logger ?? createLogger('claustrum');
75
+ this.#warnShutdown = shutdownWarning(this.#logger, this.#shutdown.signal);
43
76
  this.#releaseQuotaWriter = retainVaultQuotaWriter(options.rosterPath, (publication) => {
44
77
  this.#roster = applyVaultQuota(this.#roster, publication).roster;
45
78
  });
@@ -48,6 +81,11 @@ export class ClaustrumConsumer {
48
81
  this.#shutdown.signal.throwIfAborted();
49
82
  signal?.throwIfAborted();
50
83
  }
84
+ #track(pending) {
85
+ this.#pending.add(pending);
86
+ void pending.then(() => this.#pending.delete(pending), () => this.#pending.delete(pending));
87
+ return pending;
88
+ }
51
89
  async #active() {
52
90
  return (await this.#options.isCustodyActive?.()) ?? true;
53
91
  }
@@ -113,6 +151,7 @@ export class ClaustrumConsumer {
113
151
  .finally(() => {
114
152
  this.#connecting = undefined;
115
153
  });
154
+ this.#track(this.#connecting);
116
155
  }
117
156
  return this.#wait(this.#connecting);
118
157
  }
@@ -130,6 +169,8 @@ export class ClaustrumConsumer {
130
169
  * held the discovery lease and its newer roster was served instead).
131
170
  */
132
171
  grantReach() {
172
+ if (this.#hub)
173
+ return this.#hub.grantReach(this.#roster?.view);
133
174
  const latest = this.#grantReach;
134
175
  return latest && this.#roster?.view === latest.view
135
176
  ? latest.reach
@@ -137,6 +178,8 @@ export class ClaustrumConsumer {
137
178
  }
138
179
  /** How this consumer currently learns about changes, without I/O. */
139
180
  watchState() {
181
+ if (this.#hub)
182
+ return Object.freeze({ vault: this.#hub.watchMode() });
140
183
  return Object.freeze({
141
184
  vault: this.#vaultWatch?.mode ?? 'polling',
142
185
  ...(this.#options.insula && {
@@ -153,6 +196,13 @@ export class ClaustrumConsumer {
153
196
  }
154
197
  /** Whether any account is using an in-memory outage receipt, without I/O. */
155
198
  keptReceiptState() {
199
+ if (this.#hub) {
200
+ // Kept receipts live in the one shared custody, whichever lease reads it.
201
+ const lease = this.#lease;
202
+ return lease && this.#hub.leaseLive(lease)
203
+ ? lease.custody.keptReceiptState()
204
+ : this.#hub.keptReceiptState();
205
+ }
156
206
  return (this.#custody?.keptReceiptState() ??
157
207
  Object.freeze({ active: false, since: null }));
158
208
  }
@@ -162,6 +212,8 @@ export class ClaustrumConsumer {
162
212
  }
163
213
  refresh() {
164
214
  this.#assertOpen();
215
+ if (this.#hub)
216
+ return this.#track(this.#hubRefresh(this.#hub));
165
217
  if (this.#refreshing)
166
218
  return this.#refreshing;
167
219
  this.#refreshing = (async () => {
@@ -169,7 +221,10 @@ export class ClaustrumConsumer {
169
221
  this.#roster = undefined;
170
222
  this.#grantReach = undefined;
171
223
  this.#stopWatch();
172
- this.#custody?.close();
224
+ if (this.#custody) {
225
+ this.#custody.close();
226
+ this.#track(this.#custody.dispose(this.#warnShutdown));
227
+ }
173
228
  this.#custody = undefined;
174
229
  this.#insula?.release();
175
230
  this.#insula = undefined;
@@ -214,6 +269,7 @@ export class ClaustrumConsumer {
214
269
  })().finally(() => {
215
270
  this.#refreshing = undefined;
216
271
  });
272
+ this.#track(this.#refreshing);
217
273
  return this.#refreshing;
218
274
  }
219
275
  /**
@@ -231,6 +287,11 @@ export class ClaustrumConsumer {
231
287
  return;
232
288
  this.#assertOpen();
233
289
  this.#started = true;
290
+ // A hub member has no tick or watch of its own: the hub drives it.
291
+ if (this.#hub) {
292
+ this.#hub.start();
293
+ return;
294
+ }
234
295
  const tick = async () => {
235
296
  try {
236
297
  if (await this.#listDue())
@@ -249,11 +310,11 @@ export class ClaustrumConsumer {
249
310
  return;
250
311
  this.#timer = (this.#options.setTimeoutImpl ?? setTimeout)(() => {
251
312
  this.#timer = undefined;
252
- void tick();
313
+ void this.#track(tick());
253
314
  }, delay);
254
315
  this.#timer.unref?.();
255
316
  };
256
- void tick();
317
+ void this.#track(tick());
257
318
  }
258
319
  /** Whether a background tick must list the vault now. */
259
320
  async #listDue() {
@@ -282,11 +343,13 @@ export class ClaustrumConsumer {
282
343
  // re-applies it to kept receipts exactly as a poll does. A refresh
283
344
  // already in flight may have listed before the change was announced,
284
345
  // so wait for it and list again.
285
- onView: async () => {
346
+ onView: () => this.#track((async () => {
286
347
  while (this.#refreshing)
287
348
  await this.#refreshing.catch(() => { });
349
+ if (this.#shutdown.signal.aborted)
350
+ return;
288
351
  await this.refresh();
289
- },
352
+ })()),
290
353
  // Custody has dropped kept receipts, as a poll meeting the same
291
354
  // refusal from list_scoped would.
292
355
  onRefused: (error) => this.#options.onError?.(error),
@@ -412,6 +475,8 @@ export class ClaustrumConsumer {
412
475
  * poll, and a route whose credential or account changed is refused.
413
476
  */
414
477
  async authorize(routeId, signal) {
478
+ if (this.#hub)
479
+ return this.#hubAuthorize(this.#hub, routeId, signal);
415
480
  this.#assertOpen(signal);
416
481
  const roster = this.#roster ?? (await this.#wait(this.refresh(), signal));
417
482
  if (!roster || !(await this.#active())) {
@@ -459,8 +524,168 @@ export class ClaustrumConsumer {
459
524
  combined.dispose();
460
525
  }
461
526
  }
527
+ /** The hub's handle on this member's memory. */
528
+ #hubHooks() {
529
+ return {
530
+ install: (roster) => {
531
+ if (this.#shutdown.signal.aborted)
532
+ return;
533
+ const changed = roster.view !== this.#roster?.view;
534
+ this.#roster = pendingVaultQuota(this.#options.rosterPath, roster);
535
+ // One subscriber's failure must not stop the hub's fan-out.
536
+ if (changed)
537
+ try {
538
+ this.#options.onRoster?.(roster);
539
+ }
540
+ catch (error) {
541
+ this.#options.onError?.(error);
542
+ }
543
+ },
544
+ reset: () => {
545
+ this.#roster = undefined;
546
+ },
547
+ roster: () => this.#roster,
548
+ projection: () => ({
549
+ reservedRouteIds: new Set(this.#options.reservedRouteIds?.() ?? []),
550
+ routePrefix: this.#options.routePrefix,
551
+ mapAccount: this.#options.mapAccount,
552
+ now: (this.#options.now ?? Date.now)(),
553
+ }),
554
+ onError: (error) => {
555
+ if (!this.#shutdown.signal.aborted)
556
+ this.#options.onError?.(error);
557
+ },
558
+ };
559
+ }
560
+ /**
561
+ * A hub member's refresh is the hub's: the hub has already pushed this
562
+ * member's committed roster into memory when it resolves.
563
+ */
564
+ async #hubRefresh(hub) {
565
+ const outcome = await hub.refresh();
566
+ this.#assertOpen();
567
+ if (!outcome)
568
+ return undefined;
569
+ if (outcome.errors.has(hub.provider))
570
+ throw outcome.errors.get(hub.provider);
571
+ return this.#roster;
572
+ }
573
+ /** Release this member's lease, or only `lease` when one is named. */
574
+ #dropLease(lease) {
575
+ if (lease && this.#lease !== lease)
576
+ return;
577
+ this.#lease?.release();
578
+ this.#lease = undefined;
579
+ }
580
+ /** This member's lease, re-acquired once its connection has ended. */
581
+ async #currentLease(hub, signal) {
582
+ const held = this.#lease;
583
+ if (held && hub.leaseLive(held))
584
+ return held;
585
+ this.#dropLease();
586
+ const lease = await hub.acquire(signal);
587
+ if (this.#shutdown.signal.aborted) {
588
+ lease.release();
589
+ this.#assertOpen();
590
+ }
591
+ // A concurrent authorize may have acquired first; keep one lease.
592
+ const raced = this.#lease;
593
+ if (raced && hub.leaseLive(raced)) {
594
+ lease.release();
595
+ return raced;
596
+ }
597
+ this.#lease = lease;
598
+ return lease;
599
+ }
600
+ /**
601
+ * `authorize` for a hub member. Only the hub's own authority read decides
602
+ * that vault mode is off. If the hub's refresh still leaves this member
603
+ * without a roster, it fails with `route-unavailable` before acquiring a
604
+ * lease or asking for a credential, and no other member is affected.
605
+ */
606
+ async #hubAuthorize(hub, routeId, signal) {
607
+ this.#assertOpen(signal);
608
+ // A failed list rejects here; this member's own failed commit leaves it
609
+ // without a roster, handled below.
610
+ if (!this.#roster)
611
+ await this.#wait(hub.refresh(), signal);
612
+ const roster = this.#roster;
613
+ if (!(await hub.readAuthority())) {
614
+ this.#dropLease();
615
+ throw notActive();
616
+ }
617
+ this.#assertOpen(signal);
618
+ if (!roster)
619
+ throw new ClaustrumConsumerError('route-unavailable', 'Claustrum has no roster for this provider yet');
620
+ const current = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
621
+ this.#assertOpen(signal);
622
+ const observed = roster.rows.find((row) => row.routeId === routeId);
623
+ const configured = current?.rows.find((row) => row.routeId === routeId);
624
+ if (configured && !configured.enabled) {
625
+ if (observed)
626
+ hub.forget(observed.credentialId);
627
+ throw new ClaustrumConsumerError('route-declined', 'Claustrum route is disabled');
628
+ }
629
+ if (!observed ||
630
+ !configured ||
631
+ configured.state !== 'active' ||
632
+ configured.credentialId !== observed.credentialId ||
633
+ configured.accountIdentity !== observed.accountIdentity ||
634
+ configured.credentialType !== observed.credentialType) {
635
+ if (observed)
636
+ hub.forget(observed.credentialId);
637
+ throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is disabled, removed or changed');
638
+ }
639
+ const identity = {
640
+ credentialId: configured.credentialId,
641
+ credentialType: configured.credentialType,
642
+ ...(configured.accountIdentity !== undefined && {
643
+ accountIdentity: configured.accountIdentity,
644
+ }),
645
+ };
646
+ const combined = combineAbortSignals([
647
+ this.#shutdown.signal,
648
+ ...(signal ? [signal] : []),
649
+ ]);
650
+ try {
651
+ for (let attempt = 0;; attempt++) {
652
+ const lease = await this.#currentLease(hub, combined.signal);
653
+ try {
654
+ const served = await lease.custody.authorize(identity, combined.signal, routeId);
655
+ this.#issuedBy.set(served, lease);
656
+ return served;
657
+ }
658
+ catch (error) {
659
+ // Only a lease whose connection ended meanwhile earns one more
660
+ // try, in the current connection; anything else, or a second
661
+ // closed, is the answer.
662
+ if (attempt > 0 ||
663
+ combined.signal.aborted ||
664
+ hub.leaseLive(lease) ||
665
+ !(error instanceof ClaustrumConsumerError) ||
666
+ error.kind !== 'closed')
667
+ throw error;
668
+ this.#dropLease(lease);
669
+ if (!(await hub.readAuthority()))
670
+ throw notActive();
671
+ }
672
+ }
673
+ }
674
+ finally {
675
+ combined.dispose();
676
+ }
677
+ }
462
678
  async reportFailure(attempt, status, source) {
463
679
  this.#assertOpen();
680
+ if (this.#hub) {
681
+ // Only the lease that issued the receipt may report it; once that
682
+ // lease was released or its connection ended, its view throws closed.
683
+ const lease = this.#issuedBy.get(attempt);
684
+ if (!lease)
685
+ throw new ClaustrumConsumerError('no-receipt', 'Claustrum dispatch receipt has no active owner');
686
+ await lease.custody.reportFailure(attempt, status, source);
687
+ return;
688
+ }
464
689
  if (!this.#custody)
465
690
  throw new ClaustrumConsumerError('no-receipt', 'Claustrum dispatch receipt has no active owner');
466
691
  await this.#custody.reportFailure(attempt, status, source);
@@ -519,7 +744,12 @@ export class ClaustrumConsumer {
519
744
  this.#assertOpen();
520
745
  await declineVaultRoute(this.#options.rosterPath, routeId);
521
746
  this.#roster = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
522
- this.#custody?.retain(this.#roster?.rows ?? []);
747
+ // A hub member shares kept receipts with every other member, so they are
748
+ // retained against all members' rosters, never against this one alone.
749
+ if (this.#hub)
750
+ this.#hub.retainUnion();
751
+ else
752
+ this.#custody?.retain(this.#roster?.rows ?? []);
523
753
  }
524
754
  async accept(routeId) {
525
755
  this.#assertOpen();
@@ -581,7 +811,14 @@ export class ClaustrumConsumer {
581
811
  (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
582
812
  this.#timer = undefined;
583
813
  this.#stopWatch();
584
- this.#custody?.close();
814
+ if (this.#custody) {
815
+ this.#custody.close();
816
+ this.#track(this.#custody.dispose(this.#warnShutdown));
817
+ }
818
+ // A hub member gives back its lease; the shared custody stays open.
819
+ this.#lease?.release();
820
+ this.#lease = undefined;
821
+ this.#hub?.detach();
585
822
  this.#insula?.release();
586
823
  this.#insula = undefined;
587
824
  this.#roster = undefined;
@@ -589,9 +826,13 @@ export class ClaustrumConsumer {
589
826
  void this.#releaseQuotaWriter();
590
827
  forgetPendingVaultDiscovery(this.#options.rosterPath);
591
828
  }
592
- /** Close immediately; the last consumer also waits for the writer's bounded drain. */
829
+ /** Close immediately; background work gets 2 s and the quota writer its own 1 s. */
593
830
  async dispose() {
594
831
  this.close();
595
- await this.#releaseQuotaWriter();
832
+ this.#disposing ??= Promise.all([
833
+ drainShutdown(this.#pending, this.#warnShutdown),
834
+ this.#releaseQuotaWriter(),
835
+ ]).then(() => { });
836
+ await this.#disposing;
596
837
  }
597
838
  }
@@ -22,10 +22,35 @@ export interface ClaustrumFamily {
22
22
  category: string;
23
23
  apiKeys?: boolean;
24
24
  }
25
+ /** Non-secret classification facts, including rows decoded by older clients. */
26
+ export interface VaultRowFacts {
27
+ readonly credentialId: string;
28
+ readonly credentialType: string;
29
+ readonly authMethod?: string;
30
+ readonly refreshAdapter?: string;
31
+ readonly providerIds?: readonly string[];
32
+ readonly categories: readonly string[];
33
+ }
34
+ /** A policy that partitions one category without requiring one OAuth adapter. */
35
+ export interface ClassifyingClaustrumFamily<Code extends string> {
36
+ category: string;
37
+ refusalCodes: readonly Code[];
38
+ classify(row: VaultRowFacts): {
39
+ kind: 'not-mine';
40
+ } | {
41
+ kind: 'mine';
42
+ member: string;
43
+ } | {
44
+ kind: 'refused';
45
+ code: Code;
46
+ };
47
+ }
48
+ export type ClaustrumFamilyInput = ClaustrumFamily | ClassifyingClaustrumFamily<string>;
25
49
  /** One vault credential this consumer may serve. Never carries bearer material. */
26
50
  export interface VaultCredential {
27
51
  readonly credentialId: string;
28
52
  readonly credentialType: VaultCredentialType;
53
+ readonly member?: string;
29
54
  /**
30
55
  * The provider account the credential logs into, when the vault's adapter
31
56
  * claims one. Absent means the adapter makes no claim, not a mismatch.
@@ -47,6 +72,7 @@ export type SkippedVaultReason = 'empty credential id' | 'duplicate credential i
47
72
  */
48
73
  export interface SkippedVaultRecord {
49
74
  readonly credentialId?: string;
75
+ readonly member?: string;
50
76
  readonly reason: SkippedVaultReason;
51
77
  }
52
78
  /**
@@ -82,6 +108,13 @@ export interface VaultInventory {
82
108
  readonly view: string;
83
109
  readonly credentials: readonly VaultCredential[];
84
110
  readonly skipped: readonly SkippedVaultRecord[];
111
+ /** Classifying families only: fixed refusal codes, never classifier errors. */
112
+ readonly refused?: readonly {
113
+ credentialId?: string;
114
+ code: string;
115
+ }[];
116
+ /** Classifying families only: rows outside this family's responsibility. */
117
+ readonly notMine?: number;
85
118
  /**
86
119
  * The consumer's grants, as the vault's list reply named them. Undefined means unknown
87
120
  * (the vault or client predates the fields), never zero grants.
@@ -221,7 +254,7 @@ export declare class ClaustrumScopedCustody {
221
254
  #private;
222
255
  constructor(options: {
223
256
  client: ClaustrumScopedClient;
224
- family: ClaustrumFamily;
257
+ family: ClaustrumFamilyInput;
225
258
  tokenPath?: string;
226
259
  readToken?: () => Promise<EnrollmentTokenFile>;
227
260
  parseIdentity?: IdentityParser;
@@ -296,4 +329,6 @@ export declare class ClaustrumScopedCustody {
296
329
  */
297
330
  watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
298
331
  close(): void;
332
+ /** Stop immediately; allow token reads 2 s and share an owner's timeout warning. */
333
+ dispose(onTimeout?: (pendingOperations: number) => void): Promise<void>;
299
334
  }