@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.
- package/dist/claustrum/consumer.d.ts +28 -0
- package/dist/claustrum/consumer.js +103 -1
- package/dist/claustrum/custody.d.ts +21 -3
- package/dist/claustrum/custody.js +110 -24
- package/dist/claustrum/index.d.ts +3 -2
- package/dist/claustrum/index.js +1 -0
- package/dist/claustrum/insula.d.ts +48 -0
- package/dist/claustrum/insula.js +286 -21
- package/dist/claustrum/watch.d.ts +140 -0
- package/dist/claustrum/watch.js +253 -0
- package/dist/quota/format.d.ts +3 -0
- package/dist/quota/format.js +69 -1
- package/dist/quota/index.d.ts +1 -1
- package/dist/quota/projection.d.ts +16 -0
- package/package.json +4 -4
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
package/dist/claustrum/index.js
CHANGED
|
@@ -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;
|