@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
|
|
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?.
|
|
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
|
|
275
|
-
if (this.#shutdown.signal.aborted || !
|
|
270
|
+
const custody = this.#custody;
|
|
271
|
+
if (this.#shutdown.signal.aborted || !custody)
|
|
276
272
|
return;
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
package/dist/claustrum/watch.js
CHANGED
|
@@ -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.
|
|
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": {
|