@cortexkit/common-auth 0.11.8 → 0.12.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.
@@ -98,6 +98,8 @@ function addedText(name, result) {
98
98
  return `Finished adding ${name}.`;
99
99
  case 'rotated':
100
100
  return `${name} was already in the pool; its credential was updated.`;
101
+ case 'exists':
102
+ return `${name} was already in the pool; its credential is unchanged.`;
101
103
  }
102
104
  }
103
105
  /**
@@ -3,5 +3,18 @@ export interface AtomicWriteOptions {
3
3
  beforeRename?: () => Promise<void>;
4
4
  /** Test seam for forcing staging-name collisions; defaults to randomUUID. */
5
5
  stageName?: () => string;
6
+ /** Sync the staged file and, after rename, its parent directory. Opt-in. */
7
+ durable?: boolean;
8
+ }
9
+ /** Internal classification of fsync failures, including a failure after rename. */
10
+ export declare class AtomicSyncError extends Error {
11
+ constructor(cause: unknown);
6
12
  }
7
13
  export declare function writeJsonAtomic(path: string, value: unknown, options?: AtomicWriteOptions): Promise<void>;
14
+ /**
15
+ * Notify internal callers at the rename. The store records committed writes
16
+ * and removed ids here, because a later directory sync cannot undo the rename.
17
+ */
18
+ export declare function writeJsonAtomicTracked(path: string, value: unknown, options: AtomicWriteOptions, onRenamed?: () => void): Promise<void>;
19
+ /** Make an already renamed file and its directory durable without rewriting bytes. */
20
+ export declare function syncJsonFile(path: string): Promise<void>;
@@ -1,7 +1,21 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { mkdir, open, rename, rm } from 'node:fs/promises';
3
3
  import { dirname } from 'node:path';
4
+ /** Internal classification of fsync failures, including a failure after rename. */
5
+ export class AtomicSyncError extends Error {
6
+ constructor(cause) {
7
+ super('file or directory sync failed', { cause });
8
+ this.name = 'AtomicSyncError';
9
+ }
10
+ }
4
11
  export async function writeJsonAtomic(path, value, options = {}) {
12
+ await writeJsonAtomicTracked(path, value, options);
13
+ }
14
+ /**
15
+ * Notify internal callers at the rename. The store records committed writes
16
+ * and removed ids here, because a later directory sync cannot undo the rename.
17
+ */
18
+ export async function writeJsonAtomicTracked(path, value, options, onRenamed) {
5
19
  await mkdir(dirname(path), { recursive: true });
6
20
  const tempPath = `${path}.${(options.stageName ?? randomUUID)()}.tmp`;
7
21
  let handle;
@@ -13,11 +27,32 @@ export async function writeJsonAtomic(path, value, options = {}) {
13
27
  ? options.serialize(value)
14
28
  : `${JSON.stringify(value, null, 2)}\n`, 'utf8');
15
29
  await handle.chmod(0o600);
30
+ if (options.durable) {
31
+ try {
32
+ await handle.sync();
33
+ }
34
+ catch (cause) {
35
+ throw new AtomicSyncError(cause);
36
+ }
37
+ }
16
38
  await handle.close();
17
39
  handle = undefined;
18
40
  await options.beforeRename?.();
19
41
  await rename(tempPath, path);
20
42
  created = false;
43
+ onRenamed?.();
44
+ if (options.durable) {
45
+ const directory = await open(dirname(path), 'r');
46
+ try {
47
+ await directory.sync();
48
+ }
49
+ catch (cause) {
50
+ throw new AtomicSyncError(cause);
51
+ }
52
+ finally {
53
+ await directory.close();
54
+ }
55
+ }
21
56
  }
22
57
  finally {
23
58
  await handle?.close().catch(() => { });
@@ -26,3 +61,20 @@ export async function writeJsonAtomic(path, value, options = {}) {
26
61
  await rm(tempPath, { force: true }).catch(() => { });
27
62
  }
28
63
  }
64
+ /** Make an already renamed file and its directory durable without rewriting bytes. */
65
+ export async function syncJsonFile(path) {
66
+ const file = await open(path, 'r');
67
+ try {
68
+ await file.sync();
69
+ }
70
+ finally {
71
+ await file.close();
72
+ }
73
+ const directory = await open(dirname(path), 'r');
74
+ try {
75
+ await directory.sync();
76
+ }
77
+ finally {
78
+ await directory.close();
79
+ }
80
+ }
@@ -64,14 +64,13 @@ export interface RegisterOpenCode2AuthMethodsOptions<T> {
64
64
  readonly now?: () => number;
65
65
  }
66
66
  /**
67
- * Registers the plugin's login methods with the host so that a login lands in
68
- * the plugin's pool and the host keeps only a placeholder credential.
67
+ * Registers the plugin's own login methods with the host so that a login lands
68
+ * in the plugin's pool and the host keeps only a placeholder credential.
69
69
  *
70
- * Host-driven refresh never reaches the pool: it hands back a fresh
71
- * placeholder whatever it is given. A real credential stored by an earlier
72
- * login under one of these method IDs is therefore replaced by a placeholder
73
- * at its first refresh; a plugin that wants to import such a login must read
74
- * it (`ctx.integration.connection`) before that happens.
70
+ * Host-driven refresh never reaches the pool: it renews only this integration's
71
+ * placeholder and refuses every other credential without replacing it. Plugins
72
+ * must register under their own method IDs; a plugin importing an existing
73
+ * host login should read it through `ctx.integration.connection` instead.
75
74
  */
76
75
  export declare function registerOpenCode2AuthMethods<T>(ctx: {
77
76
  readonly integration: Pick<Plugin.Context['integration'], 'transform'>;
@@ -39,14 +39,13 @@ export function isPlaceholderCredential(value, integrationID) {
39
39
  return matches(value.access) && matches(value.refresh);
40
40
  }
41
41
  /**
42
- * Registers the plugin's login methods with the host so that a login lands in
43
- * the plugin's pool and the host keeps only a placeholder credential.
42
+ * Registers the plugin's own login methods with the host so that a login lands
43
+ * in the plugin's pool and the host keeps only a placeholder credential.
44
44
  *
45
- * Host-driven refresh never reaches the pool: it hands back a fresh
46
- * placeholder whatever it is given. A real credential stored by an earlier
47
- * login under one of these method IDs is therefore replaced by a placeholder
48
- * at its first refresh; a plugin that wants to import such a login must read
49
- * it (`ctx.integration.connection`) before that happens.
45
+ * Host-driven refresh never reaches the pool: it renews only this integration's
46
+ * placeholder and refuses every other credential without replacing it. Plugins
47
+ * must register under their own method IDs; a plugin importing an existing
48
+ * host login should read it through `ctx.integration.connection` instead.
50
49
  */
51
50
  export async function registerOpenCode2AuthMethods(ctx, options) {
52
51
  const now = options.now ?? Date.now;
@@ -86,7 +85,12 @@ export async function registerOpenCode2AuthMethods(ctx, options) {
86
85
  integrationID,
87
86
  method: login.method,
88
87
  authorize: authorizeWith(login),
89
- refresh: async (credential) => placeholderFor(credential.methodID),
88
+ refresh: async (credential) => {
89
+ if (!isPlaceholderCredential(credential, integrationID)) {
90
+ throw new Error("This login method refreshes only its pool placeholder; sign in again with the plugin's login method.");
91
+ }
92
+ return placeholderFor(credential.methodID);
93
+ },
90
94
  ...(options.label === undefined ? {} : { label: () => options.label }),
91
95
  });
92
96
  }
@@ -16,6 +16,7 @@ export async function recordQuota(rt, id, attribution, observation) {
16
16
  if (!isCredentialEpoch(attribution?.credentialEpoch))
17
17
  throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
18
18
  await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
19
+ tx.assertNotStaged(id);
19
20
  const row = tx.row(id);
20
21
  if (!row)
21
22
  throw unknownRow('pull', id);
@@ -1,6 +1,6 @@
1
1
  import type { StoredCredential } from './schema.js';
2
2
  /** Every library operation that can fail, as named in the failure value. */
3
- export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'updateProviderState' | 'refresh' | 'pull';
3
+ export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'updateProviderState' | 'refresh' | 'pull' | 'publishRoster';
4
4
  /**
5
5
  * How far an operation got before it failed.
6
6
  *
@@ -19,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
19
19
  * lock outcomes (a wait that ran out, and a lease found lost); the rest are
20
20
  * refusals and failures of the operation itself.
21
21
  */
22
- export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'identity-contradicted' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'invalid-provider-state' | 'after-persist-hook' | 'unexpected';
22
+ export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'snapshot-contended' | 'publication-sync' | 'publication-incomplete' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'row-staged' | 'credential-exists' | 'publication-mismatch' | 'duplicate-identity' | 'identity-mismatch' | 'identity-contradicted' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'invalid-provider-state' | 'after-persist-hook' | 'unexpected';
23
23
  /**
24
24
  * The single failure value of every store operation. `committed` is present
25
25
  * only when the operation had already written a credential to the state file
@@ -8,6 +8,7 @@ export const DUPLICATE_IDENTITY_REASON = 'duplicate-identity';
8
8
  */
9
9
  export function countUnknownIdentityRows(rows) {
10
10
  return rows.filter((row) => row.invalid === undefined &&
11
+ !row.staged &&
11
12
  row.type === 'oauth' &&
12
13
  row.enabled &&
13
14
  row.credential !== undefined &&
@@ -57,6 +58,7 @@ export function disableIdentityDuplicates(tx, identity) {
57
58
  const holders = tx
58
59
  .rows()
59
60
  .filter((row) => row.invalid === undefined &&
61
+ !row.staged &&
60
62
  row.type === 'oauth' &&
61
63
  row.enabled &&
62
64
  row.identity === identity);
@@ -8,11 +8,12 @@ export type { OpenPoolStoreOptions, PoolLoad, PoolStore, } from './pool.js';
8
8
  export { openPoolStore } from './pool.js';
9
9
  export type { ProviderStateMutator, RowTransitionMutator, UpdateProviderStateResult, } from './provider-state.js';
10
10
  export { DECLINE_TRANSITION } from './provider-state.js';
11
+ export type { PublicationReceipt, PublishOptions, PublishPlan, PublishResult, } from './publication.js';
11
12
  export type { PullHook, PullRequest } from './pull.js';
12
13
  export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
13
14
  export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
14
15
  export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
15
- export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, RowWriteOptions, } from './rows.js';
16
+ export type { AddInput, AddOptions, AddResult, CredentialWriteInput, FailureHook, ProtectFn, ProtectView, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowProjection, RowToggleOptions, RowTransitionOptions, RowTransitionResult, RowWriteOptions, } from './rows.js';
16
17
  export type { PullReason } from './runtime.js';
17
18
  export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, ProviderStateCodec, ProviderStateDrop, ProviderStateReplacement, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
18
19
  export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
@@ -31,6 +31,7 @@ export interface StoreContext {
31
31
  * `OpenPoolStoreOptions.requireCredentialStamps`).
32
32
  */
33
33
  requireCredentialStamps?: boolean;
34
+ requireRemovedFingerprint?: boolean;
34
35
  }
35
36
  export interface Snapshot {
36
37
  configExists: boolean;
@@ -48,8 +49,14 @@ export type ReadResult = ({
48
49
  status: 'error';
49
50
  file: 'config' | 'state';
50
51
  reason: string;
52
+ kind?: 'snapshot-contended';
53
+ retryable?: true;
51
54
  };
52
- /** Reads and classifies both files. Never writes. */
55
+ /**
56
+ * Validate config/state/config bytes without locks. Roster replacement writes
57
+ * config before deleting old state credentials. Re-read a changed config so an
58
+ * old roster cannot be paired with state from which its accounts were removed.
59
+ */
53
60
  export declare function readPool(ctx: StoreContext): Promise<ReadResult>;
54
61
  /** The refusal for a pool that is not ready, as a failure value. */
55
62
  export declare function notReadyError(result: Exclude<ReadResult, {
@@ -58,6 +65,8 @@ export declare function notReadyError(result: Exclude<ReadResult, {
58
65
  /** What an operation has written so far; decides the failure phase. */
59
66
  export interface Progress {
60
67
  writes: number;
68
+ /** The roster config was renamed into place, or its committed receipt was found. */
69
+ publicationDecided?: true;
61
70
  /** The credential the operation's state write put on disk, once it has. */
62
71
  committed?: StoredCredential;
63
72
  }
@@ -89,6 +98,9 @@ export declare class Transaction {
89
98
  */
90
99
  rows(): PoolRow[];
91
100
  row(id: string): PoolRow | undefined;
101
+ /** Read the config marker, or an orphan's stamp; never use a caller's reservation. */
102
+ reservation(id: string): unknown;
103
+ assertNotStaged(id: string): void;
92
104
  roster(): unknown[];
93
105
  /** The first roster row with this id (the one the pool loads). */
94
106
  rosterRow(id: string): Record<string, unknown> | undefined;
@@ -126,9 +138,17 @@ export declare class Transaction {
126
138
  */
127
139
  commitConfig(options?: {
128
140
  counted?: boolean;
141
+ durable?: boolean;
142
+ publicationDecision?: boolean;
129
143
  }): Promise<void>;
130
144
  /** Writes the state: every unrecognised top-level and per-row key kept. */
131
- commitState(committed?: StoredCredential): Promise<void>;
145
+ commitState(committed?: StoredCredential, options?: {
146
+ durable?: boolean;
147
+ }): Promise<void>;
148
+ assertAll(): Promise<void>;
149
+ syncState(): Promise<void>;
150
+ markPublicationDecision(): void;
151
+ syncConfig(): Promise<void>;
132
152
  private write;
133
153
  }
134
154
  /** What `initializePool` did. */
@@ -1,21 +1,26 @@
1
1
  import { readFile } from 'node:fs/promises';
2
- import { writeJsonAtomic } from '../fs/atomic-write.js';
2
+ import { setTimeout as snapshotDelay } from 'node:timers/promises';
3
+ import { AtomicSyncError, syncJsonFile, writeJsonAtomic, writeJsonAtomicTracked, } from '../fs/atomic-write.js';
3
4
  import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
4
5
  import { PoolOperationError, } from './errors.js';
5
6
  import { callFailureHook } from './hooks.js';
6
7
  import { LockStack, } from './refresh-lock.js';
7
- import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, retireEpochsIn, rosterOf, rosterRowIn, setEntryIn, } from './schema.js';
8
+ import { assertNotReserved } from './reserved.js';
9
+ import { CREDENTIAL_STAMP_KEY, classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, retireEpochsIn, rosterOf, rosterRowIn, setEntryIn, } from './schema.js';
8
10
  import { completeTornRows, loadRows } from './torn.js';
9
- async function readJson(path) {
10
- let text;
11
+ async function readText(path) {
11
12
  try {
12
- text = await readFile(path, 'utf8');
13
+ return await readFile(path, 'utf8');
13
14
  }
14
15
  catch (error) {
15
16
  if (error.code === 'ENOENT')
16
- return { exists: false };
17
+ return undefined;
17
18
  throw error;
18
19
  }
20
+ }
21
+ function parseFile(text) {
22
+ if (text === undefined)
23
+ return { exists: false };
19
24
  try {
20
25
  return { exists: true, value: JSON.parse(text) };
21
26
  }
@@ -23,30 +28,60 @@ async function readJson(path) {
23
28
  return { exists: true, parseError };
24
29
  }
25
30
  }
26
- /** Reads and classifies both files. Never writes. */
31
+ /**
32
+ * Validate config/state/config bytes without locks. Roster replacement writes
33
+ * config before deleting old state credentials. Re-read a changed config so an
34
+ * old roster cannot be paired with state from which its accounts were removed.
35
+ */
27
36
  export async function readPool(ctx) {
28
- const config = classifyConfig(await readJson(ctx.configPath));
29
- if (config.status === 'error')
30
- return { status: 'error', file: 'config', reason: config.reason };
31
- const state = classifyState(await readJson(ctx.statePath));
32
- if (state.status === 'error')
33
- return { status: 'error', file: 'state', reason: state.reason };
34
- if (config.status === 'pending-migration')
35
- return { status: 'pending-migration', config: config.config };
37
+ for (let attempt = 0; attempt < 3; attempt++) {
38
+ const configText = await readText(ctx.configPath);
39
+ const stateText = await readText(ctx.statePath);
40
+ const checkedConfigText = await readText(ctx.configPath);
41
+ if (configText !== checkedConfigText) {
42
+ if (attempt < 2)
43
+ await snapshotDelay(2 + Math.floor(Math.random() * 4));
44
+ continue;
45
+ }
46
+ const config = classifyConfig(parseFile(configText));
47
+ if (config.status === 'error')
48
+ return { status: 'error', file: 'config', reason: config.reason };
49
+ const state = classifyState(parseFile(stateText));
50
+ if (state.status === 'error')
51
+ return { status: 'error', file: 'state', reason: state.reason };
52
+ if (config.status === 'pending-migration')
53
+ return { status: 'pending-migration', config: config.config };
54
+ return {
55
+ status: 'ready',
56
+ configExists: config.exists,
57
+ stateExists: state.exists,
58
+ config: config.config,
59
+ state: state.state,
60
+ rows: loadRows(config.config, state.state, ctx.codec, {
61
+ requireCredentialStamps: ctx.requireCredentialStamps === true,
62
+ ...(ctx.providerState ? { providerState: ctx.providerState } : {}),
63
+ }),
64
+ };
65
+ }
36
66
  return {
37
- status: 'ready',
38
- configExists: config.exists,
39
- stateExists: state.exists,
40
- config: config.config,
41
- state: state.state,
42
- rows: loadRows(config.config, state.state, ctx.codec, {
43
- requireCredentialStamps: ctx.requireCredentialStamps === true,
44
- ...(ctx.providerState ? { providerState: ctx.providerState } : {}),
45
- }),
67
+ status: 'error',
68
+ file: 'config',
69
+ kind: 'snapshot-contended',
70
+ retryable: true,
71
+ reason: 'The store was changing; retry the operation once writes settle.',
46
72
  };
47
73
  }
48
74
  /** The refusal for a pool that is not ready, as a failure value. */
49
75
  export function notReadyError(result, operation, rowId, phase = 'before-first-write') {
76
+ if (result.status === 'error' && result.kind === 'snapshot-contended')
77
+ return new PoolOperationError({
78
+ operation,
79
+ ...(rowId !== undefined ? { rowId } : {}),
80
+ phase,
81
+ kind: 'snapshot-contended',
82
+ retryable: true,
83
+ message: result.reason,
84
+ });
50
85
  return new PoolOperationError({
51
86
  operation,
52
87
  ...(rowId !== undefined ? { rowId } : {}),
@@ -99,6 +134,20 @@ export class Transaction {
99
134
  row(id) {
100
135
  return this.rows().find((row) => row.id === id);
101
136
  }
137
+ /** Read the config marker, or an orphan's stamp; never use a caller's reservation. */
138
+ reservation(id) {
139
+ if (this.rosterRow(id)) {
140
+ const entry = this.entry(id);
141
+ return entry && Object.hasOwn(entry, 'staged') ? entry.staged : undefined;
142
+ }
143
+ const stamp = this.stateAccount(id)?.[CREDENTIAL_STAMP_KEY];
144
+ return isRecord(stamp) && Object.hasOwn(stamp, 'staged')
145
+ ? stamp.staged
146
+ : undefined;
147
+ }
148
+ assertNotStaged(id) {
149
+ assertNotReserved(this.info.operation, id, this.reservation(id));
150
+ }
102
151
  roster() {
103
152
  if (!Array.isArray(this.config.accounts))
104
153
  this.config.accounts = [];
@@ -200,9 +249,6 @@ export class Transaction {
200
249
  configurable: true,
201
250
  });
202
251
  }
203
- else {
204
- this.ctx.removedIds.add(id);
205
- }
206
252
  }
207
253
  const pool = this.config[POOL_KEY];
208
254
  const next = {
@@ -215,31 +261,68 @@ export class Transaction {
215
261
  [POOL_ROWS_KEY]: kept,
216
262
  },
217
263
  };
218
- await this.write(this.ctx.configPath, next, 'config', options.counted ?? true);
264
+ await this.write(this.ctx.configPath, next, 'config', options.counted ?? true, options.durable ?? false, () => {
265
+ if (options.publicationDecision)
266
+ this.markPublicationDecision();
267
+ for (const id of dropped)
268
+ this.ctx.removedIds.add(id);
269
+ this.config = next;
270
+ });
219
271
  this.config = next;
220
272
  }
221
273
  /** Writes the state: every unrecognised top-level and per-row key kept. */
222
- async commitState(committed) {
274
+ async commitState(committed, options = {}) {
223
275
  const next = {
224
276
  ...this.state,
225
277
  version: LEGACY_STORE_VERSION,
226
278
  accounts: isRecord(this.state.accounts) ? this.state.accounts : {},
227
279
  };
228
- await this.write(this.ctx.statePath, next, 'state');
280
+ await this.write(this.ctx.statePath, next, 'state', true, options.durable ?? false);
229
281
  this.state = next;
230
282
  if (committed)
231
283
  this.progress.committed = committed;
232
284
  }
233
- async write(path, value, file, counted = true) {
234
- await writeJsonAtomic(path, value, {
285
+ async assertAll() {
286
+ await this.locks.assertAll();
287
+ }
288
+ async syncState() {
289
+ await this.assertAll();
290
+ try {
291
+ if (this.snapshot.stateExists)
292
+ await syncJsonFile(this.ctx.statePath);
293
+ }
294
+ catch (cause) {
295
+ throw new PoolOperationError({
296
+ operation: this.info.operation,
297
+ rowId: this.info.rowId,
298
+ phase: 'before-first-write',
299
+ kind: 'publication-sync',
300
+ retryable: true,
301
+ message: 'Publication sync failed before the decision; nothing was written. Retry the same plan.',
302
+ cause,
303
+ });
304
+ }
305
+ }
306
+ markPublicationDecision() {
307
+ this.progress.publicationDecided = true;
308
+ }
309
+ async syncConfig() {
310
+ await this.assertAll();
311
+ await syncJsonFile(this.ctx.configPath);
312
+ }
313
+ async write(path, value, file, counted = true, durable = false, onRenamed) {
314
+ await writeJsonAtomicTracked(path, value, {
315
+ durable,
235
316
  beforeRename: async () => {
236
317
  await this.ctx.onStep?.(`before-${file}-write`, this.info);
237
318
  // Ownership is proved immediately before the rename, on every lease.
238
319
  await this.locks.assertAll();
239
320
  },
321
+ }, () => {
322
+ if (counted)
323
+ this.progress.writes++;
324
+ onRenamed?.();
240
325
  });
241
- if (counted)
242
- this.progress.writes++;
243
326
  await this.ctx.onStep?.(`after-${file}-write`, this.info);
244
327
  }
245
328
  }
@@ -304,6 +387,9 @@ export async function withTransaction(ctx, locks, progress, info, fn, options =
304
387
  if (result.status !== 'ready')
305
388
  throw notReadyError(result, info.operation, info.rowId, progress.writes > 0 ? 'after-first-write' : 'before-first-write');
306
389
  const tx = new Transaction(ctx, result, locks, progress, info);
390
+ if (info.rowId !== undefined &&
391
+ !['add', 'remove', 'pull', 'publishRoster', 'enable', 'disable'].includes(info.operation))
392
+ tx.assertNotStaged(info.rowId);
307
393
  if (options.completeTorn ?? true)
308
394
  await tx.completeTorn();
309
395
  return await fn(tx);
@@ -320,6 +406,26 @@ export function toFailure(error, operation, rowId, progress) {
320
406
  ? 'after-first-write'
321
407
  : 'before-first-write';
322
408
  const committed = phase === 'after-first-write' ? progress.committed : undefined;
409
+ if (operation === 'publishRoster' && progress.publicationDecided)
410
+ return new PoolOperationError({
411
+ operation,
412
+ ...(rowId !== undefined ? { rowId } : {}),
413
+ phase,
414
+ kind: 'publication-incomplete',
415
+ retryable: true,
416
+ message: 'The publication may already be decided. Replay the same plan or check publication(operationId).',
417
+ cause: error,
418
+ });
419
+ if (operation === 'publishRoster' && error instanceof AtomicSyncError)
420
+ return new PoolOperationError({
421
+ operation,
422
+ ...(rowId !== undefined ? { rowId } : {}),
423
+ phase,
424
+ kind: 'publication-sync',
425
+ retryable: true,
426
+ message: 'Publication sync failed before the decision; nothing was written. Retry the same plan.',
427
+ cause: error,
428
+ });
323
429
  if (error instanceof PoolOperationError) {
324
430
  if (error.phase === phase &&
325
431
  error.rowId === rowId &&
@@ -3,10 +3,11 @@ import type { PoolOperationError } from './errors.js';
3
3
  import type { PoolLogger } from './hooks.js';
4
4
  import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mutate.js';
5
5
  import { type ProviderStateMutator, type UpdateProviderStateResult } from './provider-state.js';
6
+ import { type PublicationReceipt, type PublishOptions, type PublishPlan, type PublishResult } from './publication.js';
6
7
  import { type PullHook } from './pull.js';
7
8
  import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
8
9
  import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
9
- import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult, type RowWriteOptions } from './rows.js';
10
+ import { type AddInput, type AddOptions, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult, type RowWriteOptions } from './rows.js';
10
11
  import { type PoolCredential, type PoolRow, type ProviderStateCodec, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
11
12
  import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
12
13
  export interface OpenPoolStoreOptions {
@@ -39,6 +40,8 @@ export interface OpenPoolStoreOptions {
39
40
  * without writing; `remove(id)` explicitly discards the orphan.
40
41
  */
41
42
  requireCredentialStamps?: boolean;
43
+ /** Require an exact secret fingerprint for every roster-publication removal. */
44
+ requireRemovedFingerprint?: boolean;
42
45
  /** Injected clock for leases, refresh stamps and `addedAt`. */
43
46
  now?: () => number;
44
47
  /**
@@ -75,6 +78,8 @@ export type PoolLoad = {
75
78
  status: 'error';
76
79
  file: 'config' | 'state';
77
80
  reason: string;
81
+ kind?: 'snapshot-contended';
82
+ retryable?: true;
78
83
  };
79
84
  export interface PoolStore {
80
85
  /** Reads the pool and fires first-reading pulls; never writes a file itself. */
@@ -99,7 +104,9 @@ export interface PoolStore {
99
104
  * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
100
105
  * refuses (`id-removed`) before writing.
101
106
  */
102
- add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
107
+ add(input: AddInput, options?: AddOptions): Promise<AddResult>;
108
+ publishRoster(plan: PublishPlan, options?: PublishOptions): Promise<PublishResult>;
109
+ publication(operationId: string): Promise<PublicationReceipt | undefined>;
103
110
  /**
104
111
  * Gives a row a new credential and a new credential epoch. Since 0.6.0 the
105
112
  * row's provider state is whatever `ProviderStateCodec.onReplace` returns;
@@ -1,6 +1,7 @@
1
1
  import { recordQuota } from './attribution.js';
2
2
  import { initializePool, readPool, } from './mutate.js';
3
3
  import { updateProviderStateRow, } from './provider-state.js';
4
+ import { publication, publishRoster, } from './publication.js';
4
5
  import { PullScheduler } from './pull.js';
5
6
  import { refreshRow, } from './refresh.js';
6
7
  import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
@@ -62,6 +63,7 @@ export function openPoolStore(options) {
62
63
  },
63
64
  removedIds: memory.removedIds,
64
65
  requireCredentialStamps: options.requireCredentialStamps === true,
66
+ requireRemovedFingerprint: options.requireRemovedFingerprint === true,
65
67
  ...(options.logger ? { logger: options.logger } : {}),
66
68
  ...(options.onStep ? { onStep: options.onStep } : {}),
67
69
  ...(options.hold ? { hold: options.hold } : {}),
@@ -98,6 +100,8 @@ export function openPoolStore(options) {
98
100
  return { status: await initializePool(ctx, input.dropKeys ?? []) };
99
101
  },
100
102
  add: (input, callOptions) => addRow(rt, input, callOptions),
103
+ publishRoster: (plan, callOptions) => publishRoster(rt, plan, callOptions),
104
+ publication: (operationId) => publication(rt, operationId),
101
105
  replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
102
106
  rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),
103
107
  updateProviderState: (id, fence, mutator, callOptions) => updateProviderStateRow(rt, id, fence, mutator, callOptions),
@@ -0,0 +1,47 @@
1
+ import type { Attribution } from './attribution.js';
2
+ import type { PoolLockSpec } from './refresh-lock.js';
3
+ import { type FailureHook, type ProtectFn } from './rows.js';
4
+ import { type StoreRuntime } from './runtime.js';
5
+ export interface PublishPlan {
6
+ operationId: string;
7
+ remove: Array<{
8
+ id: string;
9
+ attribution: Attribution;
10
+ fingerprint?: string;
11
+ }>;
12
+ finalize: Array<{
13
+ id: string;
14
+ attribution: Attribution;
15
+ reservation: string;
16
+ enabled: boolean;
17
+ disabledReason?: string;
18
+ }>;
19
+ order: string[];
20
+ }
21
+ export interface PublicationReceipt {
22
+ operationId: string;
23
+ planDigest: string;
24
+ phase: 'committed' | 'cleaned';
25
+ removed: Array<{
26
+ id: string;
27
+ credentialEpoch: number;
28
+ }>;
29
+ finalized: Array<{
30
+ id: string;
31
+ credentialEpoch: number;
32
+ reservation: string;
33
+ enabled: boolean;
34
+ }>;
35
+ }
36
+ export interface PublishOptions {
37
+ protect?: ProtectFn;
38
+ extraLocks?: PoolLockSpec[];
39
+ providerLock?: PoolLockSpec;
40
+ onFailure?: FailureHook;
41
+ }
42
+ export interface PublishResult {
43
+ outcome: 'published' | 'cleaned' | 'already-cleaned';
44
+ receipt: PublicationReceipt;
45
+ }
46
+ export declare function publication(rt: StoreRuntime, operationId: string): Promise<PublicationReceipt | undefined>;
47
+ export declare function publishRoster(rt: StoreRuntime, plan: PublishPlan, options?: PublishOptions): Promise<PublishResult>;