@cortexkit/common-auth 0.27.0 → 0.28.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/README.md +0 -16
- package/dist/claustrum/consumer.d.ts +14 -0
- package/dist/claustrum/consumer.js +70 -26
- package/dist/claustrum/enrollment.d.ts +9 -0
- package/dist/claustrum/enrollment.js +52 -20
- package/dist/claustrum/hub.d.ts +8 -0
- package/dist/claustrum/hub.js +138 -66
- package/dist/claustrum/index.d.ts +10 -1
- package/dist/claustrum/index.js +35 -3
- package/dist/claustrum/quota-writer.d.ts +8 -1
- package/dist/claustrum/quota-writer.js +34 -12
- package/dist/claustrum/roster.d.ts +2 -1
- package/dist/claustrum/roster.js +113 -9
- package/dist/fs/file-read-cache.d.ts +8 -0
- package/dist/fs/file-read-cache.js +57 -0
- package/dist/fs/refresh-file-lock.js +16 -3
- package/dist/quota/commit-interval.d.ts +9 -0
- package/dist/quota/commit-interval.js +18 -0
- package/dist/setup/command.js +4 -49
- package/dist/setup/flags.d.ts +50 -0
- package/dist/setup/flags.js +123 -0
- package/dist/setup/index.d.ts +1 -0
- package/dist/setup/index.js +1 -0
- package/dist/setup/types.d.ts +7 -1
- package/dist/store/mutate.d.ts +2 -0
- package/dist/store/mutate.js +4 -0
- package/dist/store/pool.d.ts +6 -1
- package/dist/store/pool.js +1 -1
- package/dist/store/quota-writer.d.ts +5 -1
- package/dist/store/quota-writer.js +27 -13
- package/dist/store/settings.d.ts +1 -1
- package/dist/store/settings.js +16 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,20 +7,4 @@ Shared libraries for the CortexKit auth plugins for OpenCode and Pi: openai-auth
|
|
|
7
7
|
- [OpenCode 2 transport spike](research/opencode2-transport/REPORT.md): can a plugin own the transport on OpenCode 2?
|
|
8
8
|
- [OpenCode 2 native-driver spike](research/opencode2-thin/REPORT.md): multi-account support through hooks on OpenCode 2's built-in OpenAI driver.
|
|
9
9
|
|
|
10
|
-
## Mutation catalogue
|
|
11
|
-
|
|
12
|
-
A passing safety test proves little until it has been seen to fail. [`mutations.toml`](mutations.toml) is the checked-in catalogue: each row deliberately breaks one guard in `src/` (or a CI scan script) and names the Bun test that must fail because of it, so a guard cannot silently stop guarding. A row earns its place by guarding a silent, costly failure: lock exclusion, crash safety, credential loss or leakage, a single-use token used twice, misattributed quota, a wire contract, data loss. Style and cosmetics do not.
|
|
13
|
-
|
|
14
|
-
The pinned [`ckdev-mutate`](https://github.com/cortexkit/commons/tree/9d6b663dac487bb982c7bfd18a96eee2292164ad/crates/cortexkit-mutate) runner replays it from a clean tree. It installs and builds first (fixtures import `dist/`), checks each named test passes, applies the break, rebuilds, requires the test to fail, and restores the source byte for byte:
|
|
15
|
-
|
|
16
|
-
```sh
|
|
17
|
-
cargo install --locked --git https://github.com/cortexkit/commons --rev 9d6b663dac487bb982c7bfd18a96eee2292164ad cortexkit-mutate
|
|
18
|
-
ckdev-mutate check --strict
|
|
19
|
-
ckdev-mutate run --all
|
|
20
|
-
ckdev-mutate run --diff origin/main
|
|
21
|
-
ckdev-mutate run --only fs-lock-try-once-refuses-held-lock
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Every row must report CAUGHT. Replay with the Bun version CI pins (1.3.14): the row `rpc-declared-oversize-413-half-closes` guards the RPC server's workaround for Bun 1.3.14 reusing a connection the server refused with 413. Bun 1.4.2 never reuses it, so that row survives there. Rows are command rows: `{test}` is a Bun `-t` filter, a regular expression over the full test name (describe names and test name joined by spaces), so ids are anchored, escaped, and spell each space `\s`. The shared `scripts/list-bun-tests.mjs` asks Bun's JUnit reporter to list every discovered test as skipped with a never-matching selector, then reconstructs full names from nested describe suites and filters them with the row's JavaScript regular expression. It does not duplicate Bun's test-name formatting or run test bodies. `ckdev-mutate check --strict` verifies each active command row's `expect_red` selects a discovered test. CI replays the rows a pull request's diff selects, the full catalogue on every push to main, and the full catalogue with `--broad` nightly. Never `git checkout` a file while a replay runs: it removes the mutation and fakes a survivor.
|
|
25
|
-
|
|
26
10
|
Licensed under MIT; see [LICENSE](LICENSE).
|
|
@@ -18,6 +18,14 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
|
|
|
18
18
|
tokenPath: string;
|
|
19
19
|
family: ClaustrumFamily;
|
|
20
20
|
connect: () => Promise<ClaustrumScopedClient>;
|
|
21
|
+
/**
|
|
22
|
+
* How long one `connect()` attempt may take before this consumer treats the
|
|
23
|
+
* vault as unreachable (default 10 s). A connect that never settles would
|
|
24
|
+
* otherwise leave every later `refresh()` waiting on the same promise. After
|
|
25
|
+
* the limit the waiters get an unreachable error, the next `refresh()`
|
|
26
|
+
* connects again, and a client that arrives late is closed.
|
|
27
|
+
*/
|
|
28
|
+
connectTimeoutMs?: number;
|
|
21
29
|
/**
|
|
22
30
|
* Whether the plugin currently takes its accounts from the vault (custody
|
|
23
31
|
* mode) rather than from local logins. Checked before every discovery,
|
|
@@ -116,6 +124,12 @@ export interface HubMemberHooks {
|
|
|
116
124
|
projection(): ProjectionOptions;
|
|
117
125
|
onError(error: unknown): void;
|
|
118
126
|
}
|
|
127
|
+
/**
|
|
128
|
+
* How long one connect attempt may take by default. It bounds a connect that
|
|
129
|
+
* never settles; the client's own handshake limit is not guaranteed to cover
|
|
130
|
+
* every stall, and callers waiting on discovery need an answer either way.
|
|
131
|
+
*/
|
|
132
|
+
export declare const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
|
|
119
133
|
/**
|
|
120
134
|
* Build the consumer for one hub member. `options` holds only what the member
|
|
121
135
|
* uses: the hub's roster path for this member and the member's own fields.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { createLogger } from '../logger/index.js';
|
|
2
2
|
import { combineAbortSignals } from '../util/any-signal.js';
|
|
3
|
+
import { ClaustrumUnreachableError } from './availability.js';
|
|
3
4
|
import { ClaustrumScopedCustody, decideScopedRetryAfter401, } from './custody.js';
|
|
4
5
|
import { readClaustrumEnrollmentToken } from './enrollment.js';
|
|
5
6
|
import { ClaustrumConsumerError } from './errors.js';
|
|
@@ -8,6 +9,16 @@ import { pendingVaultQuota, retainVaultQuotaWriter } from './quota-writer.js';
|
|
|
8
9
|
import { acceptVaultRoute, applyVaultQuota, declineVaultRoute, forgetPendingVaultDiscovery, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, vaultRoutingRows, } from './roster.js';
|
|
9
10
|
import { drainShutdown, shutdownWarning } from './shutdown.js';
|
|
10
11
|
import { SAFETY_POLL_MS } from './watch.js';
|
|
12
|
+
/**
|
|
13
|
+
* How long one connect attempt may take by default. It bounds a connect that
|
|
14
|
+
* never settles; the client's own handshake limit is not guaranteed to cover
|
|
15
|
+
* every stall, and callers waiting on discovery need an answer either way.
|
|
16
|
+
*/
|
|
17
|
+
export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
|
|
18
|
+
/** An unreachable vault, raised when a connect passed its time limit. */
|
|
19
|
+
function unreachableConnect() {
|
|
20
|
+
return new ClaustrumUnreachableError();
|
|
21
|
+
}
|
|
11
22
|
let buildHubMember;
|
|
12
23
|
/**
|
|
13
24
|
* Build the consumer for one hub member. `options` holds only what the member
|
|
@@ -125,36 +136,69 @@ export class ClaustrumConsumer {
|
|
|
125
136
|
if (this.#custody)
|
|
126
137
|
return this.#custody;
|
|
127
138
|
if (!this.#connecting) {
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
this.#assertOpen();
|
|
134
|
-
}
|
|
135
|
-
this.#custody = new ClaustrumScopedCustody({
|
|
136
|
-
client,
|
|
137
|
-
family: this.#options.family,
|
|
138
|
-
tokenPath: this.#options.tokenPath,
|
|
139
|
-
parseIdentity: this.#options.parseIdentity,
|
|
140
|
-
requireAssertion: this.#options.requireAssertion,
|
|
141
|
-
now: this.#options.now,
|
|
142
|
-
logger: this.#logger,
|
|
143
|
-
setTimeoutImpl: this.#options.setTimeoutImpl,
|
|
144
|
-
clearTimeoutImpl: this.#options.clearTimeoutImpl,
|
|
145
|
-
});
|
|
146
|
-
if (this.#options.insula && client.insula) {
|
|
147
|
-
this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
|
|
148
|
-
}
|
|
149
|
-
return this.#custody;
|
|
150
|
-
})
|
|
151
|
-
.finally(() => {
|
|
152
|
-
this.#connecting = undefined;
|
|
153
|
-
});
|
|
139
|
+
// A connect that never settles must not hold #connecting open: every
|
|
140
|
+
// later refresh would wait on the same promise. The race below bounds
|
|
141
|
+
// each attempt, and only a client that arrives in time is installed.
|
|
142
|
+
const attempt = { timedOut: false };
|
|
143
|
+
this.#connecting = this.#boundedConnect(attempt);
|
|
154
144
|
this.#track(this.#connecting);
|
|
155
145
|
}
|
|
156
146
|
return this.#wait(this.#connecting);
|
|
157
147
|
}
|
|
148
|
+
/**
|
|
149
|
+
* One `connect()` attempt under `connectTimeoutMs`. The late promise is still
|
|
150
|
+
* observed after the deadline, so a client that arrives then is closed
|
|
151
|
+
* rather than leaked.
|
|
152
|
+
*/
|
|
153
|
+
#boundedConnect(attempt) {
|
|
154
|
+
const setTimer = this.#options.setTimeoutImpl ?? setTimeout;
|
|
155
|
+
const clearTimer = this.#options.clearTimeoutImpl ?? clearTimeout;
|
|
156
|
+
const pending = this.#options.connect().then((client) => {
|
|
157
|
+
if (this.#shutdown.signal.aborted || attempt.timedOut) {
|
|
158
|
+
client.close();
|
|
159
|
+
if (!attempt.timedOut)
|
|
160
|
+
this.#assertOpen();
|
|
161
|
+
throw unreachableConnect();
|
|
162
|
+
}
|
|
163
|
+
this.#custody = new ClaustrumScopedCustody({
|
|
164
|
+
client,
|
|
165
|
+
family: this.#options.family,
|
|
166
|
+
tokenPath: this.#options.tokenPath,
|
|
167
|
+
parseIdentity: this.#options.parseIdentity,
|
|
168
|
+
requireAssertion: this.#options.requireAssertion,
|
|
169
|
+
now: this.#options.now,
|
|
170
|
+
logger: this.#logger,
|
|
171
|
+
setTimeoutImpl: this.#options.setTimeoutImpl,
|
|
172
|
+
clearTimeoutImpl: this.#options.clearTimeoutImpl,
|
|
173
|
+
});
|
|
174
|
+
if (this.#options.insula && client.insula) {
|
|
175
|
+
this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
|
|
176
|
+
}
|
|
177
|
+
return this.#custody;
|
|
178
|
+
});
|
|
179
|
+
let timer;
|
|
180
|
+
const deadline = new Promise((_resolve, reject) => {
|
|
181
|
+
timer = setTimer(() => {
|
|
182
|
+
attempt.timedOut = true;
|
|
183
|
+
if (this.#shutdown.signal.aborted)
|
|
184
|
+
return;
|
|
185
|
+
this.#logger.warn('vault connect timed out', {
|
|
186
|
+
reason: 'unreachable',
|
|
187
|
+
connectTimeoutMs: this.#connectTimeoutMs(),
|
|
188
|
+
});
|
|
189
|
+
reject(unreachableConnect());
|
|
190
|
+
}, this.#connectTimeoutMs());
|
|
191
|
+
timer.unref?.();
|
|
192
|
+
});
|
|
193
|
+
return Promise.race([pending, deadline]).finally(() => {
|
|
194
|
+
if (timer)
|
|
195
|
+
clearTimer(timer);
|
|
196
|
+
this.#connecting = undefined;
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
#connectTimeoutMs() {
|
|
200
|
+
return this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
|
|
201
|
+
}
|
|
158
202
|
/** The last committed roster this instance saw, without any I/O. */
|
|
159
203
|
snapshot() {
|
|
160
204
|
return this.#roster;
|
|
@@ -107,6 +107,15 @@ export interface EnrollmentAncestorOptions {
|
|
|
107
107
|
* sticky ancestors are accepted. Windows uses the shared safe-parent policy.
|
|
108
108
|
*/
|
|
109
109
|
export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
|
|
110
|
+
/**
|
|
111
|
+
* Create `directory` owner-only, or make an existing one owner-only. POSIX:
|
|
112
|
+
* every component it creates gets mode 0700, a directory another user owns is
|
|
113
|
+
* refused, and one that group or others can reach is tightened to 0700.
|
|
114
|
+
* Windows: private-files creates missing components owner-only and verifies
|
|
115
|
+
* existing ones without modifying them. `what` names the directory in the
|
|
116
|
+
* ownership refusal.
|
|
117
|
+
*/
|
|
118
|
+
export declare function ensureClaustrumPrivateDirectory(directory: string, options?: EnrollmentAncestorOptions, what?: string): Promise<void>;
|
|
110
119
|
export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentStatus>;
|
|
111
120
|
/**
|
|
112
121
|
* Resolve the host's account mode from its enrollment files. It never changes
|
|
@@ -3,6 +3,7 @@ import { constants as fsConstants } from 'node:fs';
|
|
|
3
3
|
import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, } from 'node:fs/promises';
|
|
4
4
|
import { basename, dirname, extname, isAbsolute, join, resolve, } from 'node:path';
|
|
5
5
|
import { ClaustrumCredentialError, ClaustrumClient as ClaustrumWireClient, writeEnrollmentTokenFile, } from '@cortexkit/claustrum-client';
|
|
6
|
+
import { FileReadCache } from '../fs/file-read-cache.js';
|
|
6
7
|
import { acquireRefreshFileLock } from '../fs/index.js';
|
|
7
8
|
import { ensurePrivateDirectory as ensureWindowsDirectory, PrivateFileError, readPrivateText, verifySafeDirectory, windowsPrivateFiles, writePrivateAtomic, } from '../fs/private-files.js';
|
|
8
9
|
import { ClaustrumConsumerError } from './errors.js';
|
|
@@ -357,8 +358,15 @@ export async function refuseWritableAncestor(parent, options = {}) {
|
|
|
357
358
|
throw new ClaustrumConsumerError('unsafe-file', `Claustrum enrollment parent refused: ${error.path} (${error.reason ?? error.code}). Use a folder that other users cannot write or replace.`);
|
|
358
359
|
}
|
|
359
360
|
}
|
|
360
|
-
/**
|
|
361
|
-
|
|
361
|
+
/**
|
|
362
|
+
* Create `directory` owner-only, or make an existing one owner-only. POSIX:
|
|
363
|
+
* every component it creates gets mode 0700, a directory another user owns is
|
|
364
|
+
* refused, and one that group or others can reach is tightened to 0700.
|
|
365
|
+
* Windows: private-files creates missing components owner-only and verifies
|
|
366
|
+
* existing ones without modifying them. `what` names the directory in the
|
|
367
|
+
* ownership refusal.
|
|
368
|
+
*/
|
|
369
|
+
export async function ensureClaustrumPrivateDirectory(directory, options = {}, what = 'enrollment directory') {
|
|
362
370
|
if (windowsPrivateFiles) {
|
|
363
371
|
await ensureWindowsDirectory(directory, false, ancestorPolicyOptions(options));
|
|
364
372
|
return;
|
|
@@ -367,14 +375,14 @@ async function ensurePrivateDirectory(directory, options = {}) {
|
|
|
367
375
|
const metadata = await stat(directory);
|
|
368
376
|
const uid = process.geteuid?.();
|
|
369
377
|
if (uid !== undefined && metadata.uid !== uid) {
|
|
370
|
-
throw new ClaustrumConsumerError('unsafe-file',
|
|
378
|
+
throw new ClaustrumConsumerError('unsafe-file', `Claustrum ${what} must be owned by the current user`);
|
|
371
379
|
}
|
|
372
380
|
if ((metadata.mode & 0o077) !== 0)
|
|
373
381
|
await chmod(directory, 0o700);
|
|
374
382
|
}
|
|
375
383
|
async function writeStateAtomic(path, state, ancestorOptions = {}) {
|
|
376
384
|
const parent = dirname(path);
|
|
377
|
-
await
|
|
385
|
+
await ensureClaustrumPrivateDirectory(parent, ancestorOptions);
|
|
378
386
|
await refuseWritableAncestor(parent, ancestorOptions);
|
|
379
387
|
const bytes = `${JSON.stringify(state)}\n`;
|
|
380
388
|
if (Buffer.byteLength(bytes) > ENROLLMENT_FILE_MAX_BYTES) {
|
|
@@ -402,32 +410,56 @@ async function writeStateAtomic(path, state, ancestorOptions = {}) {
|
|
|
402
410
|
await unlink(temporary).catch(() => { });
|
|
403
411
|
}
|
|
404
412
|
}
|
|
413
|
+
const enrollmentStatusCache = new FileReadCache();
|
|
405
414
|
export async function readClaustrumEnrollmentStatus(paths, proposedName) {
|
|
415
|
+
// Windows ACL, owner and ancestry checks are not represented by stat identity.
|
|
416
|
+
// Keep the native private-file validation and full read on every call there.
|
|
417
|
+
const result = windowsPrivateFiles
|
|
418
|
+
? await readEnrollmentStatus(paths, proposedName)
|
|
419
|
+
: await enrollmentStatusCache.read([paths.tokenPath, paths.statePath], async ([tokenPath = paths.tokenPath, statePath = paths.statePath]) => readEnrollmentStatus({ tokenPath, statePath }, proposedName), (identities) => {
|
|
420
|
+
// Recheck the current effective user as well as mode and regular-file kind.
|
|
421
|
+
// lstat probes also prevent a link to the old inode from becoming a hit.
|
|
422
|
+
for (const metadata of identities)
|
|
423
|
+
if (metadata !== 'absent')
|
|
424
|
+
validateReadableSecretFile(metadata);
|
|
425
|
+
});
|
|
426
|
+
const status = { ...result.status };
|
|
427
|
+
if (result.usesProposedName && status.state === 'approved')
|
|
428
|
+
status.proposedName = proposedName;
|
|
429
|
+
return status;
|
|
430
|
+
}
|
|
431
|
+
async function readEnrollmentStatus(paths, proposedName) {
|
|
406
432
|
const tokenValue = await readBoundedJson(paths.tokenPath);
|
|
407
433
|
const token = tokenValue === undefined ? undefined : decodeTokenFile(tokenValue);
|
|
408
434
|
const stateValue = await readBoundedJson(paths.statePath);
|
|
409
435
|
const state = stateValue === undefined ? undefined : decodeEnrollmentState(stateValue);
|
|
410
436
|
if (token) {
|
|
411
437
|
return {
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
state
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
438
|
+
usesProposedName: state === undefined,
|
|
439
|
+
status: {
|
|
440
|
+
state: 'approved',
|
|
441
|
+
proposedName: state?.proposedName ?? proposedName,
|
|
442
|
+
...(state?.phase === 'approved' &&
|
|
443
|
+
state.approvedName !== undefined && {
|
|
444
|
+
approvedName: state.approvedName,
|
|
445
|
+
}),
|
|
446
|
+
tokenGeneration: token.token_generation,
|
|
447
|
+
},
|
|
419
448
|
};
|
|
420
449
|
}
|
|
421
450
|
if (!state)
|
|
422
|
-
return { state: 'idle' };
|
|
451
|
+
return { status: { state: 'idle' }, usesProposedName: false };
|
|
423
452
|
if (state.phase === 'approved') {
|
|
424
453
|
return {
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
454
|
+
usesProposedName: false,
|
|
455
|
+
status: {
|
|
456
|
+
state: 'blocked',
|
|
457
|
+
proposedName: state.proposedName,
|
|
458
|
+
code: 'missing_token',
|
|
459
|
+
},
|
|
428
460
|
};
|
|
429
461
|
}
|
|
430
|
-
return statusFromState(state);
|
|
462
|
+
return { status: statusFromState(state), usesProposedName: false };
|
|
431
463
|
}
|
|
432
464
|
/**
|
|
433
465
|
* Resolve the host's account mode from its enrollment files. It never changes
|
|
@@ -553,7 +585,7 @@ export class ClaustrumEnrollmentManager {
|
|
|
553
585
|
return statusFromState(blocked);
|
|
554
586
|
}
|
|
555
587
|
async reconcile() {
|
|
556
|
-
await
|
|
588
|
+
await ensureClaustrumPrivateDirectory(dirname(this.#paths.statePath), this.#ancestorOptions);
|
|
557
589
|
const lock = await acquireRefreshFileLock({
|
|
558
590
|
name: 'ceremony',
|
|
559
591
|
path: this.#paths.statePath,
|
|
@@ -690,7 +722,7 @@ export class ClaustrumEnrollmentManager {
|
|
|
690
722
|
}
|
|
691
723
|
// The vault returns the token exactly once: it reaches disk before the
|
|
692
724
|
// pending metadata (and its secret) is replaced.
|
|
693
|
-
await
|
|
725
|
+
await ensureClaustrumPrivateDirectory(dirname(this.#paths.tokenPath), this.#ancestorOptions);
|
|
694
726
|
await refuseWritableAncestor(dirname(this.#paths.tokenPath), this.#ancestorOptions);
|
|
695
727
|
await this.#writeTokenFile(this.#paths.tokenPath, {
|
|
696
728
|
token: outcome.token,
|
|
@@ -729,7 +761,7 @@ export class ClaustrumEnrollmentManager {
|
|
|
729
761
|
}
|
|
730
762
|
/** Reset local terminal metadata without connecting to the credential daemon. */
|
|
731
763
|
export async function resetClaustrumEnrollmentState(paths, proposedName) {
|
|
732
|
-
await
|
|
764
|
+
await ensureClaustrumPrivateDirectory(dirname(paths.statePath));
|
|
733
765
|
const lock = await acquireRefreshFileLock({
|
|
734
766
|
name: 'ceremony',
|
|
735
767
|
path: paths.statePath,
|
|
@@ -792,7 +824,7 @@ async function removeIfPresent(path) {
|
|
|
792
824
|
* wrong owner, not owner-only) refuses with `unsafe-file` and both files stay.
|
|
793
825
|
*/
|
|
794
826
|
export async function disconnectClaustrumEnrollment(paths, proposedName) {
|
|
795
|
-
await
|
|
827
|
+
await ensureClaustrumPrivateDirectory(dirname(paths.statePath));
|
|
796
828
|
const lock = await acquireRefreshFileLock({
|
|
797
829
|
// The same lock as the ceremony, so a token written by a concurrent
|
|
798
830
|
// reconcile() can never land after this removes the files.
|
package/dist/claustrum/hub.d.ts
CHANGED
|
@@ -47,6 +47,14 @@ export interface ClaustrumDiscoveryHubOptions {
|
|
|
47
47
|
*/
|
|
48
48
|
family: ClassifyingClaustrumFamily<string>;
|
|
49
49
|
connect: () => Promise<ClaustrumScopedClient>;
|
|
50
|
+
/**
|
|
51
|
+
* How long one `connect()` attempt may take before the hub treats the vault
|
|
52
|
+
* as unreachable (default 10 s, as `ClaustrumConsumerOptions`). The hub's
|
|
53
|
+
* connect is shared by every member waiting for a lease, so an attempt that
|
|
54
|
+
* never settles would hold every one of them; after the limit they get an
|
|
55
|
+
* unreachable error and the next acquire connects again.
|
|
56
|
+
*/
|
|
57
|
+
connectTimeoutMs?: number;
|
|
50
58
|
/**
|
|
51
59
|
* Whether the plugin takes its accounts from the vault. Read from local
|
|
52
60
|
* state only, never from the vault: on every hub tick, and when a member
|
package/dist/claustrum/hub.js
CHANGED
|
@@ -12,11 +12,13 @@
|
|
|
12
12
|
// never replaces a view another process committed after this hub listed.
|
|
13
13
|
import { createHash } from 'node:crypto';
|
|
14
14
|
import { readdir, stat } from 'node:fs/promises';
|
|
15
|
-
import { join } from 'node:path';
|
|
15
|
+
import { dirname, join } from 'node:path';
|
|
16
16
|
import { createLogger } from '../logger/index.js';
|
|
17
17
|
import { combineAbortSignals } from '../util/any-signal.js';
|
|
18
|
-
import {
|
|
18
|
+
import { ClaustrumUnreachableError } from './availability.js';
|
|
19
|
+
import { createHubMember, DEFAULT_CONNECT_TIMEOUT_MS, } from './consumer.js';
|
|
19
20
|
import { ClaustrumScopedCustody, } from './custody.js';
|
|
21
|
+
import { ensureClaustrumPrivateDirectory } from './enrollment.js';
|
|
20
22
|
import { ClaustrumConsumerError } from './errors.js';
|
|
21
23
|
import { DEFAULT_ROUTE_PREFIX, decodedVaultRoster, forgetPendingVaultDiscovery, isVaultRosterLockRefusal, readVaultRoster, refreshVaultRoster, vaultRosterSeed, } from './roster.js';
|
|
22
24
|
import { drainShutdown, shutdownWarning } from './shutdown.js';
|
|
@@ -98,6 +100,10 @@ function closed(message = 'Claustrum custody lease is closed') {
|
|
|
98
100
|
function notActive() {
|
|
99
101
|
return new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
|
|
100
102
|
}
|
|
103
|
+
/** An unreachable vault, raised when a connect passed its time limit. */
|
|
104
|
+
function unreachableConnect() {
|
|
105
|
+
return new ClaustrumUnreachableError();
|
|
106
|
+
}
|
|
101
107
|
/**
|
|
102
108
|
* Follow `pending`, but reject as soon as `signal` aborts. `pending` is
|
|
103
109
|
* still observed afterwards, so its rejection is never unhandled.
|
|
@@ -321,31 +327,54 @@ export class ClaustrumDiscoveryHub {
|
|
|
321
327
|
}
|
|
322
328
|
#connect(generation) {
|
|
323
329
|
const pending = this.#connecting;
|
|
324
|
-
if (pending?.generation === generation)
|
|
330
|
+
if (pending?.generation === generation && pending.promise)
|
|
325
331
|
return pending.promise;
|
|
326
|
-
const entry = {
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
332
|
+
const entry = { generation, timedOut: false };
|
|
333
|
+
// Every acquirer waits on this one connect, so it is bounded: a connect
|
|
334
|
+
// that never settles would otherwise hold them all for the hub's life.
|
|
335
|
+
const connectTimeoutMs = this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
|
|
336
|
+
let timer;
|
|
337
|
+
const connect = this.#options.connect().then((client) => {
|
|
338
|
+
// A connect resolves into its generation only while that generation
|
|
339
|
+
// is current and still wanted; otherwise its client never serves.
|
|
340
|
+
if (entry.timedOut) {
|
|
341
|
+
client.close();
|
|
342
|
+
throw unreachableConnect();
|
|
343
|
+
}
|
|
344
|
+
if (!this.#live(generation) || generation.count <= 0) {
|
|
345
|
+
client.close();
|
|
346
|
+
throw closed('Claustrum connection is no longer wanted');
|
|
347
|
+
}
|
|
348
|
+
generation.custody = new ClaustrumScopedCustody({
|
|
349
|
+
client,
|
|
350
|
+
family: this.#options.family,
|
|
351
|
+
tokenPath: this.#options.tokenPath,
|
|
352
|
+
parseIdentity: this.#options.parseIdentity,
|
|
353
|
+
requireAssertion: this.#options.requireAssertion,
|
|
354
|
+
now: this.#options.now,
|
|
355
|
+
logger: this.#logger,
|
|
356
|
+
setTimeoutImpl: this.#options.setTimeoutImpl,
|
|
357
|
+
clearTimeoutImpl: this.#options.clearTimeoutImpl,
|
|
358
|
+
});
|
|
359
|
+
return generation.custody;
|
|
360
|
+
});
|
|
361
|
+
const deadline = new Promise((_resolve, reject) => {
|
|
362
|
+
timer = (this.#options.setTimeoutImpl ?? setTimeout)(() => {
|
|
363
|
+
entry.timedOut = true;
|
|
364
|
+
if (!this.#live(generation))
|
|
365
|
+
return;
|
|
366
|
+
this.#logger.warn('vault connect timed out', {
|
|
367
|
+
reason: 'unreachable',
|
|
368
|
+
connectTimeoutMs,
|
|
345
369
|
});
|
|
346
|
-
|
|
347
|
-
})
|
|
348
|
-
|
|
370
|
+
reject(unreachableConnect());
|
|
371
|
+
}, connectTimeoutMs);
|
|
372
|
+
timer.unref?.();
|
|
373
|
+
});
|
|
374
|
+
entry.promise = this.#track(Promise.race([connect, deadline]).finally(() => {
|
|
375
|
+
if (timer)
|
|
376
|
+
(this.#options.clearTimeoutImpl ?? clearTimeout)(timer);
|
|
377
|
+
}));
|
|
349
378
|
// Clear only this connect: an older generation's connect settling late
|
|
350
379
|
// must leave a newer generation's pending connect in place.
|
|
351
380
|
const settled = entry.promise.finally(() => {
|
|
@@ -557,10 +586,11 @@ export class ClaustrumDiscoveryHub {
|
|
|
557
586
|
}
|
|
558
587
|
/**
|
|
559
588
|
* Read each member's base view, list once, then commit each member's share
|
|
560
|
-
* of the listing to its roster
|
|
561
|
-
*
|
|
562
|
-
*
|
|
563
|
-
*
|
|
589
|
+
* of the listing to its roster (all members at once, each under its own
|
|
590
|
+
* roster's locks), push it into the member, and retain the union. Each
|
|
591
|
+
* publication step checks first that the generation it started in is
|
|
592
|
+
* still current. A member that this list did not commit is marked pending,
|
|
593
|
+
* so a later tick lists again.
|
|
564
594
|
*/
|
|
565
595
|
async #discover(run) {
|
|
566
596
|
if (!(await this.#readAuthority()))
|
|
@@ -570,12 +600,17 @@ export class ClaustrumDiscoveryHub {
|
|
|
570
600
|
run.generation = generation;
|
|
571
601
|
if (!this.#live(generation))
|
|
572
602
|
return undefined;
|
|
603
|
+
// Folders that could not be made owner-only fail every member's commit,
|
|
604
|
+
// as an unreadable base fails its member's: each is marked pending.
|
|
605
|
+
const folders = await this.#ensureRosterDirectories().then(() => undefined, (error) => error instanceof Error ? error : new Error(String(error)));
|
|
573
606
|
// What each member's file held before the list. Another process may
|
|
574
607
|
// commit while this list runs; the base-view rule then keeps its newer
|
|
575
|
-
// roster rather than replacing it with this older listing.
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
608
|
+
// roster rather than replacing it with this older listing. Each file is
|
|
609
|
+
// read on its own, so the reads run together.
|
|
610
|
+
const bases = new Map(await Promise.all([...this.#members.values()].map(async (entry) => [
|
|
611
|
+
entry,
|
|
612
|
+
await readVaultRoster(entry.path).then((file) => (file ? { file } : {}), (error) => error instanceof Error ? error : new Error(String(error))),
|
|
613
|
+
])));
|
|
579
614
|
if (!this.#live(generation))
|
|
580
615
|
return undefined;
|
|
581
616
|
let inventory;
|
|
@@ -591,43 +626,28 @@ export class ClaustrumDiscoveryHub {
|
|
|
591
626
|
this.#markPending(entry);
|
|
592
627
|
throw error;
|
|
593
628
|
}
|
|
629
|
+
if (!this.#live(generation))
|
|
630
|
+
return undefined;
|
|
631
|
+
// Every member's commit starts at once and none waits for another: each
|
|
632
|
+
// touches only its own roster file and takes only that file's locks (its
|
|
633
|
+
// discovery lease, then its write lock, as `refreshVaultRoster` always
|
|
634
|
+
// does), so no commit ever holds two members' locks and no order between
|
|
635
|
+
// members is needed. The results are then published in member order.
|
|
636
|
+
const members = this.#open();
|
|
637
|
+
const commits = await Promise.all(members.map((entry) => entry.hooks && !entry.closed
|
|
638
|
+
? this.#commit(entry, entry.hooks, inventory, folders ?? bases.get(entry), generation)
|
|
639
|
+
: undefined));
|
|
640
|
+
if (!this.#live(generation))
|
|
641
|
+
return undefined;
|
|
594
642
|
const errors = new Map();
|
|
595
643
|
let complete = true;
|
|
596
|
-
for (const entry of
|
|
597
|
-
if (!this.#live(generation))
|
|
598
|
-
return undefined;
|
|
644
|
+
for (const [index, entry] of members.entries()) {
|
|
599
645
|
const hooks = entry.hooks;
|
|
600
|
-
|
|
646
|
+
const commit = commits[index];
|
|
647
|
+
if (!hooks || !commit)
|
|
601
648
|
continue;
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
credentials: inventory.credentials.filter((credential) => credential.member === entry.provider),
|
|
605
|
-
skipped: inventory.skipped.filter((record) => record.member === entry.provider),
|
|
606
|
-
};
|
|
607
|
-
const base = bases.get(entry);
|
|
608
|
-
let roster;
|
|
609
|
-
try {
|
|
610
|
-
if (!base)
|
|
611
|
-
throw closed('Claustrum hub member has no base view');
|
|
612
|
-
if (base instanceof Error)
|
|
613
|
-
throw base;
|
|
614
|
-
// A member's first roster under this key carries the declines and
|
|
615
|
-
// order of its newest roster under an older key.
|
|
616
|
-
const seed = base.file ? undefined : await this.#seed(entry);
|
|
617
|
-
roster = await refreshVaultRoster({
|
|
618
|
-
path: entry.path,
|
|
619
|
-
custody: { discover: async () => share },
|
|
620
|
-
// Generation g's commit checks that g is still current, not only
|
|
621
|
-
// that vault mode is on, so off-then-on cannot let it into g+1.
|
|
622
|
-
isActive: () => this.#live(generation) && this.#active === true,
|
|
623
|
-
signal: generation.controller.signal,
|
|
624
|
-
projection: () => ({ ...hooks.projection(), ...(seed && { seed }) }),
|
|
625
|
-
listedOver: { view: base.file?.view },
|
|
626
|
-
});
|
|
627
|
-
}
|
|
628
|
-
catch (error) {
|
|
629
|
-
if (!this.#live(generation))
|
|
630
|
-
return undefined;
|
|
649
|
+
if ('error' in commit) {
|
|
650
|
+
const { error } = commit;
|
|
631
651
|
complete = false;
|
|
632
652
|
this.#markPending(entry);
|
|
633
653
|
// Another writer holding or taking this roster's locks is not this
|
|
@@ -640,6 +660,7 @@ export class ClaustrumDiscoveryHub {
|
|
|
640
660
|
errors.set(entry.provider, error);
|
|
641
661
|
continue;
|
|
642
662
|
}
|
|
663
|
+
const { roster } = commit;
|
|
643
664
|
if (!this.#live(generation))
|
|
644
665
|
return undefined;
|
|
645
666
|
// Not this list's roster: vault mode went off, the file was removed
|
|
@@ -679,6 +700,57 @@ export class ClaustrumDiscoveryHub {
|
|
|
679
700
|
this.#discoveredAt = (this.#options.now ?? Date.now)();
|
|
680
701
|
return { errors };
|
|
681
702
|
}
|
|
703
|
+
/**
|
|
704
|
+
* Commit one member's share of `inventory` to its roster file over the
|
|
705
|
+
* base view read before the list. Every failure is returned, not thrown,
|
|
706
|
+
* so one member's failure leaves the other members' commits running.
|
|
707
|
+
*/
|
|
708
|
+
async #commit(entry, hooks, inventory, base, generation) {
|
|
709
|
+
const share = {
|
|
710
|
+
...inventory,
|
|
711
|
+
credentials: inventory.credentials.filter((credential) => credential.member === entry.provider),
|
|
712
|
+
skipped: inventory.skipped.filter((record) => record.member === entry.provider),
|
|
713
|
+
};
|
|
714
|
+
try {
|
|
715
|
+
if (!base)
|
|
716
|
+
throw closed('Claustrum hub member has no base view');
|
|
717
|
+
if (base instanceof Error)
|
|
718
|
+
throw base;
|
|
719
|
+
// A member's first roster under this key carries the declines and
|
|
720
|
+
// order of its newest roster under an older key.
|
|
721
|
+
const seed = base.file ? undefined : await this.#seed(entry);
|
|
722
|
+
const roster = await refreshVaultRoster({
|
|
723
|
+
path: entry.path,
|
|
724
|
+
custody: { discover: async () => share },
|
|
725
|
+
// Generation g's commit checks that g is still current, not only
|
|
726
|
+
// that vault mode is on, so off-then-on cannot let it into g+1.
|
|
727
|
+
isActive: () => this.#live(generation) && this.#active === true,
|
|
728
|
+
signal: generation.controller.signal,
|
|
729
|
+
projection: () => ({ ...hooks.projection(), ...(seed && { seed }) }),
|
|
730
|
+
listedOver: { view: base.file?.view },
|
|
731
|
+
});
|
|
732
|
+
return { roster };
|
|
733
|
+
}
|
|
734
|
+
catch (error) {
|
|
735
|
+
return { error };
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
/**
|
|
739
|
+
* Create the roster folders under the state folder (`rosters`, this host
|
|
740
|
+
* generation and this key) owner-only, as every other Claustrum private
|
|
741
|
+
* folder is: 0700 on POSIX, tightening a folder an earlier release left
|
|
742
|
+
* open, and private-files on Windows. Each is handled on its own so an
|
|
743
|
+
* existing open parent is tightened too. Without this, the first roster
|
|
744
|
+
* lock would create them with the process umask, usually 0755.
|
|
745
|
+
*/
|
|
746
|
+
async #ensureRosterDirectories() {
|
|
747
|
+
for (const directory of [
|
|
748
|
+
dirname(this.#generationDirectory),
|
|
749
|
+
this.#generationDirectory,
|
|
750
|
+
join(this.#generationDirectory, this.#key),
|
|
751
|
+
])
|
|
752
|
+
await ensureClaustrumPrivateDirectory(directory, {}, 'roster directory');
|
|
753
|
+
}
|
|
682
754
|
/**
|
|
683
755
|
* The preferences a member's first roster under this key starts from: the
|
|
684
756
|
* declines and order of the newest roster of the same host generation and
|