@cortexkit/common-auth 0.11.7 → 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.
@@ -5,8 +5,36 @@ import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enable
5
5
  import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
6
6
  import { acceptProviderState, mergedProviderState, planProviderStateIn, providerStateCoverage, replacementProviderState, } from './provider-state.js';
7
7
  import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
8
- import { boundProviderStateDigest, buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, credentialProblem, dispatchDigest, fingerprintOf, idProblem, isCredentialEpoch, isRecord, nextAddEpochIn, POOL_KEY, PROVIDER_STATE_KEY, parseStamp, providerStateDigest, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
8
+ import { boundProviderStateDigest, buildRawRows, CREDENTIAL_STAMP_KEY, canonicalDigest, credentialDigest, credentialProblem, dispatchDigest, fingerprintOf, idProblem, isCredentialEpoch, isRecord, nextAddEpochIn, POOL_KEY, PROVIDER_STATE_KEY, parseStamp, providerStateDigest, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
9
9
  import { applyTransition, bindReplacement, TRANSITION_STAMP_KEY, } from './torn.js';
10
+ export async function protectIn(tx, id, protect) {
11
+ if (!protect)
12
+ return;
13
+ const rows = tx.rows().map((row) => {
14
+ const { id, type, label, enabled, disabledReason, identity, credentialEpoch, stamp, staged, torn, invalid, } = row;
15
+ return {
16
+ id,
17
+ type,
18
+ label,
19
+ enabled,
20
+ disabledReason,
21
+ identity,
22
+ credentialEpoch,
23
+ stamp,
24
+ staged,
25
+ torn,
26
+ invalid,
27
+ };
28
+ });
29
+ const reason = await runInsideHook(tx.info.operation, () => protect({
30
+ id,
31
+ row: rows.find((row) => row.id === id),
32
+ rows,
33
+ config: structuredClone(tx.snapshot.config),
34
+ }));
35
+ if (reason !== undefined)
36
+ throw refusal(tx.info.operation, id, 'row-protected', reason);
37
+ }
10
38
  /** Fields of a state entry that belong to the credential it replaces. */
11
39
  const CREDENTIAL_STATE_FIELDS = [
12
40
  'access',
@@ -45,7 +73,13 @@ function onRowEndpoint(tx, id, credential) {
45
73
  throw refusal(tx.info.operation, id, 'invalid-input', 'api credential needs a valid baseURL');
46
74
  return { ...credential, baseURL: credential.baseURL };
47
75
  }
48
- const endpoint = rowEndpoint(raw);
76
+ const projected = tx.row(id)?.credential;
77
+ const endpoint = projected?.type === 'api'
78
+ ? {
79
+ baseURL: projected.baseURL.trim(),
80
+ authHeader: projected.authHeader ?? 'authorization-bearer',
81
+ }
82
+ : rowEndpoint(raw);
49
83
  const baseURL = credential.baseURL?.trim() ?? endpoint.baseURL;
50
84
  const authHeader = credential.authHeader ?? endpoint.authHeader;
51
85
  if (baseURL !== endpoint.baseURL || authHeader !== endpoint.authHeader)
@@ -65,10 +99,13 @@ function onRowEndpoint(tx, id, credential) {
65
99
  */
66
100
  function bindingInTx(tx, id, stored, learnt) {
67
101
  const raw = tx.rosterRow(id);
102
+ const projected = tx.row(id);
68
103
  const identity = learnt ??
69
- (isRecord(raw) && typeof raw.accountId === 'string' && raw.accountId
70
- ? raw.accountId
71
- : undefined);
104
+ (projected
105
+ ? projected.identity
106
+ : isRecord(raw) && typeof raw.accountId === 'string' && raw.accountId
107
+ ? raw.accountId
108
+ : undefined);
72
109
  return {
73
110
  ...(identity !== undefined ? { identity } : {}),
74
111
  ...(stored.type === 'api'
@@ -80,20 +117,18 @@ function bindingInTx(tx, id, stored, learnt) {
80
117
  };
81
118
  }
82
119
  /**
83
- * Writes a credential into the state file (one write), stamped with the
84
- * credential epoch the row's entry holds in `tx` (1 without an entry) and a
85
- * binding: for a replace, the one the config is about to get (and the stamp
86
- * is marked as a replace's); for every other write, the row's config as it
87
- * stands in `tx` with the identity the operation is about to record
88
- * (`identity`, see `bindingInTx`). A rotation is the same lineage: no epoch
89
- * bump, no identity or quota change. An API key must belong to the endpoint
90
- * the row holds in `tx` (see `onRowEndpoint`).
120
+ * Build the credential and its state entry without writing. The stamp records
121
+ * the credential's epoch, identity and API endpoint so readers can verify that
122
+ * they belong together. A replacement records the new epoch and account; a
123
+ * rotation keeps the current epoch, account and quota. Pending writes are read
124
+ * as completed when choosing those fields, even while disk config is behind.
125
+ * Endpoint checks and provider-state encoding finish here, before any repair.
91
126
  */
92
- export async function rotateIn(rt, tx, id, given, extra = {}) {
127
+ function planRotationIn(rt, tx, id, given, extra = {}) {
93
128
  const credential = onRowEndpoint(tx, id, given);
94
129
  const prior = tx.stateAccount(id);
95
130
  const stateWrite = extra.providerState ?? { kind: 'keep' };
96
- const epoch = tx.entry(id)?.credentialEpoch;
131
+ const epoch = tx.row(id)?.credentialEpoch ?? tx.entry(id)?.credentialEpoch;
97
132
  const credentialEpoch = typeof epoch === 'number' ? epoch : 1;
98
133
  // The provider state goes in the same state write as the credential and
99
134
  // its stamp, so no reader ever sees one without the other. A kept value is
@@ -119,10 +154,11 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
119
154
  else if (stateWrite.kind === 'set')
120
155
  kept[PROVIDER_STATE_KEY] = stateWrite.value;
121
156
  const stored = storedCredential(credential, stamp);
122
- tx.setStateAccount(id, {
157
+ const account = {
123
158
  ...kept,
124
159
  ...stateFieldsFor(credential, stamp),
125
160
  [CREDENTIAL_STAMP_KEY]: {
161
+ ...(extra.staged ? { staged: extra.staged } : {}),
126
162
  ...(extra.transition !== undefined
127
163
  ? { [TRANSITION_STAMP_KEY]: extra.transition }
128
164
  : {}),
@@ -133,9 +169,17 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
133
169
  : {}),
134
170
  }),
135
171
  },
136
- });
137
- await tx.commitState(stored);
138
- return stored;
172
+ };
173
+ return { stored, account };
174
+ }
175
+ async function persistRotationIn(tx, id, plan) {
176
+ tx.setStateAccount(id, plan.account);
177
+ await tx.commitState(plan.stored);
178
+ return plan.stored;
179
+ }
180
+ /** Validate the endpoint and encode provider state and its stamp before committing state. */
181
+ export async function rotateIn(rt, tx, id, given, extra = {}) {
182
+ return persistRotationIn(tx, id, planRotationIn(rt, tx, id, given, extra));
139
183
  }
140
184
  /**
141
185
  * Restamps a bound row's credential, unchanged, so its stamp names the
@@ -179,13 +223,13 @@ function requireUsableRow(operation, id, row, credential) {
179
223
  throw refusal(operation, id, 'type-mismatch', `row ${id} holds a ${row.type} credential`);
180
224
  return row;
181
225
  }
182
- function validateAttribution(operation, id, fence) {
226
+ export function validateAttribution(operation, id, fence) {
183
227
  if (fence !== undefined &&
184
228
  !isCredentialEpoch(isRecord(fence) ? fence.credentialEpoch : undefined))
185
229
  throw refusal(operation, id, 'invalid-input', 'the attribution must name a credential epoch that is a positive safe integer');
186
230
  }
187
231
  /** Exact recorded identity, including absence, is part of a credential fence. */
188
- function assertRowAttribution(operation, id, row, fence) {
232
+ export function assertRowAttribution(operation, id, row, fence) {
189
233
  if (!row)
190
234
  throw unknownRow(operation, id);
191
235
  // A row that failed validation has no usable credential epoch to compare.
@@ -271,31 +315,208 @@ function matchingInterruptedAdd(rt, tx, input, incoming) {
271
315
  return refuse();
272
316
  return orphan;
273
317
  }
318
+ /** Complete an interrupted staged add only when its stamp and stored credential match. */
319
+ function replayStagedAdd(rt, tx, input, incoming) {
320
+ const { id, credential, identity, label } = input;
321
+ const raw = tx.rosterRow(id);
322
+ const fail = () => {
323
+ throw refusal('add', id, raw ? 'id-exists' : 'unbound-credential', `row ${id} does not match this staged add`);
324
+ };
325
+ const account = tx.stateAccount(id);
326
+ const stamp = parseStamp(account?.[CREDENTIAL_STAMP_KEY]);
327
+ const staged = stamp?.staged;
328
+ if (!stamp?.binding ||
329
+ !staged ||
330
+ stamp.replace ||
331
+ stamp.dispatch === undefined)
332
+ return fail();
333
+ if (raw &&
334
+ (raw.type !== credential.type ||
335
+ raw.label !== label ||
336
+ raw.accountId !== identity))
337
+ return fail();
338
+ if (staged.reservation !== input.stage?.reservation ||
339
+ staged.label !== label ||
340
+ staged.disabledReason !== input.disabled?.reason ||
341
+ stamp.binding.identity !== identity)
342
+ return fail();
343
+ const incomingDigest = incoming === undefined ? undefined : canonicalDigest(incoming);
344
+ const storedValue = account?.[PROVIDER_STATE_KEY];
345
+ const storedDigest = storedValue === undefined ? undefined : canonicalDigest(storedValue);
346
+ if (staged.providerState !== incomingDigest ||
347
+ staged.providerState !== storedDigest)
348
+ return fail();
349
+ if (credentialDigest(credential) !== stamp.digest ||
350
+ dispatchDigest(credential) !== stamp.dispatch)
351
+ return fail();
352
+ const config = raw
353
+ ? tx.config
354
+ : {
355
+ accounts: [
356
+ {
357
+ ...rosterRowFor({
358
+ id,
359
+ credential: credential.type === 'api'
360
+ ? {
361
+ ...credential,
362
+ baseURL: stamp.binding.baseURL ?? '',
363
+ authHeader: stamp.binding.authHeader,
364
+ }
365
+ : credential,
366
+ identity: stamp.binding.identity,
367
+ label: staged.label,
368
+ addedAt: 0,
369
+ }),
370
+ enabled: false,
371
+ },
372
+ ],
373
+ [POOL_KEY]: {
374
+ rows: {
375
+ [id]: {
376
+ credentialEpoch: stamp.credentialEpoch,
377
+ disabledReason: staged.disabledReason,
378
+ staged: { reservation: staged.reservation },
379
+ },
380
+ },
381
+ },
382
+ };
383
+ const row = buildRawRows(config, tx.state, rt.ctx.codec, rt.ctx.providerState).find((row) => row.id === id);
384
+ if (!row?.credential ||
385
+ row.invalid ||
386
+ row.stamp !== 'bound' ||
387
+ row.type !== credential.type ||
388
+ row.enabled ||
389
+ row.label !== staged.label ||
390
+ row.identity !== stamp.binding.identity ||
391
+ row.disabledReason !== staged.disabledReason ||
392
+ row.staged?.reservation !== staged.reservation)
393
+ return fail();
394
+ if (raw)
395
+ return {
396
+ id,
397
+ outcome: 'exists',
398
+ credential: row.credential,
399
+ credentialEpoch: stamp.credentialEpoch,
400
+ };
401
+ if (nextAddEpochIn(tx.config, id) !== stamp.credentialEpoch)
402
+ return fail();
403
+ tx.roster().push({
404
+ ...rosterRowFor({ id, credential, identity, label, addedAt: rt.ctx.now() }),
405
+ enabled: false,
406
+ });
407
+ tx.setEntry(id, {
408
+ credentialEpoch: stamp.credentialEpoch,
409
+ needsFirstReading: credential.type === 'oauth',
410
+ disabledReason: staged.disabledReason,
411
+ staged: { reservation: staged.reservation },
412
+ });
413
+ return tx.commitConfig().then(() => ({
414
+ id,
415
+ outcome: 'completed',
416
+ credential: row.credential,
417
+ credentialEpoch: stamp.credentialEpoch,
418
+ }));
419
+ }
274
420
  export async function addRow(rt, input, options = {}) {
275
421
  assertNotInsideHook('add');
276
422
  const { ctx } = rt;
277
423
  const { id, credential, identity, label } = input;
424
+ const preparing = input.stage !== undefined || input.disabled !== undefined;
278
425
  const result = await runOperation(ctx, 'add', id, options.onFailure, async (locks, progress) => {
279
426
  checkInput('add', id, credential);
427
+ const mode = options.onExisting ?? 'rotate';
428
+ if (input.stage !== undefined && mode === 'rotate')
429
+ throw refusal('add', id, 'invalid-input', "a staged add needs onExisting: 'refuse' or 'stage-duplicate'");
430
+ if (!['rotate', 'refuse', 'stage-duplicate'].includes(mode) ||
431
+ (input.stage !== undefined &&
432
+ ((label !== undefined && typeof label !== 'string') ||
433
+ (identity !== undefined &&
434
+ (typeof identity !== 'string' || !identity)))) ||
435
+ (input.disabled !== undefined &&
436
+ (!isRecord(input.disabled) ||
437
+ typeof input.disabled.reason !== 'string')) ||
438
+ (input.stage !== undefined &&
439
+ (!isRecord(input.stage) ||
440
+ typeof input.stage.reservation !== 'string' ||
441
+ !input.stage.reservation ||
442
+ !input.disabled)) ||
443
+ (mode === 'stage-duplicate' && (!input.disabled || !input.stage)))
444
+ throw refusal('add', id, 'invalid-input', 'staging requires a reservation and a disabled reason');
280
445
  const incoming = input.providerState === undefined
281
446
  ? undefined
282
447
  : acceptProviderState(ctx.providerState, 'add', id, input.providerState);
283
- if (ctx.removedIds.has(id))
284
- throw refusal('add', id, 'id-removed', `id ${id} was removed from the roster in this process and is not reused`);
285
448
  await locks.acquire(rowLockSpec(rt, { id, identity }));
286
449
  if (credential.type === 'oauth')
287
450
  await locks.acquire(options.providerLock ?? rt.providerLock);
288
451
  for (const extra of options.extraLocks ?? [])
289
452
  await locks.acquire(extra);
290
453
  return withTransaction(ctx, locks, progress, { operation: 'add', rowId: id }, async (tx) => {
454
+ await protectIn(tx, id, options.protect);
455
+ const stateAccounts = isRecord(tx.state.accounts)
456
+ ? tx.state.accounts
457
+ : {};
458
+ const stagedOrphan = Object.entries(stateAccounts).find(([orphanId, account]) => {
459
+ if (orphanId === id ||
460
+ tx.rosterRow(orphanId) ||
461
+ !isRecord(account))
462
+ return false;
463
+ const stamp = account[CREDENTIAL_STAMP_KEY];
464
+ if (!isRecord(stamp) || !Object.hasOwn(stamp, 'staged'))
465
+ return false;
466
+ return credential.type === 'oauth'
467
+ ? account.refresh === credential.refresh
468
+ : typeof account.apiKey === 'string' &&
469
+ account.apiKey.trim() === credential.apiKey.trim();
470
+ });
471
+ if (stagedOrphan)
472
+ throw refusal('add', stagedOrphan[0], 'row-staged', `orphan ${stagedOrphan[0]} reserves this secret until its staged add is replayed or removed`);
473
+ if (ctx.removedIds.has(id))
474
+ throw refusal('add', id, 'id-removed', `id ${id} was removed from the roster in this process and is not reused`);
475
+ if (input.stage &&
476
+ mode !== 'rotate' &&
477
+ (tx.rosterRow(id) || hasStateAccount(tx.state, id)))
478
+ return replayStagedAdd(rt, tx, input, incoming);
479
+ if (mode === 'rotate') {
480
+ tx.assertNotStaged(id);
481
+ const holder = tx
482
+ .rows()
483
+ .find((row) => row.fingerprint === fingerprintOf(credential));
484
+ if (holder)
485
+ tx.assertNotStaged(holder.id);
486
+ }
487
+ if (mode === 'refuse') {
488
+ const holder = tx
489
+ .rows()
490
+ .find((row) => row.fingerprint === fingerprintOf(credential) ||
491
+ (row.id === id && row.credential));
492
+ const accounts = isRecord(tx.state.accounts)
493
+ ? tx.state.accounts
494
+ : {};
495
+ const stateHolder = Object.entries(accounts).find(([, account]) => {
496
+ if (!isRecord(account))
497
+ return false;
498
+ if (credential.type === 'oauth')
499
+ return account.refresh === credential.refresh;
500
+ return (typeof account.apiKey === 'string' &&
501
+ account.apiKey.trim() === credential.apiKey.trim());
502
+ })?.[0];
503
+ const holdingId = holder?.id ?? stateHolder ?? id;
504
+ if (holder ||
505
+ stateHolder !== undefined ||
506
+ hasStateAccount(tx.state, id))
507
+ throw refusal('add', holdingId, 'credential-exists', `row ${holdingId} already holds this secret or id`);
508
+ }
509
+ if (mode === 'stage-duplicate' &&
510
+ (tx.rosterRow(id) || hasStateAccount(tx.state, id)))
511
+ throw refusal('add', id, 'id-exists', `row ${id} already exists`);
291
512
  const orphan = matchingInterruptedAdd(rt, tx, input, incoming);
292
- if (!orphan)
293
- await tx.completeTorn();
294
513
  const rows = tx.rows();
295
514
  const fingerprint = fingerprintOf(credential);
296
- const same = !orphan &&
515
+ const same = mode === 'rotate' &&
516
+ !orphan &&
297
517
  rows.find((row) => row.invalid === undefined && row.fingerprint === fingerprint);
298
518
  if (same) {
519
+ tx.assertNotStaged(same.id);
299
520
  // Re-adding a secret whose stamp is not proved would rotate it in
300
521
  // and keep the identity and quota recorded beside it, making that
301
522
  // unproved record look bound. The add is refused instead, and the
@@ -309,14 +530,22 @@ export async function addRow(rt, input, options = {}) {
309
530
  same.identity !== undefined &&
310
531
  identity !== same.identity)
311
532
  throw identityMismatch('add', same.id);
312
- const stored = await rotateIn(rt, tx, same.id, credential, {
533
+ const prepared = planRotationIn(rt, tx, same.id, credential, {
313
534
  ...(incoming !== undefined
314
535
  ? {
315
536
  providerState: mergedProviderState(ctx.providerState, 'add', same.id, same.providerState, incoming),
316
537
  }
317
538
  : {}),
318
539
  });
319
- return { id: same.id, outcome: 'rotated', credential: stored };
540
+ await tx.completeTorn();
541
+ tx.assertNotStaged(same.id);
542
+ const stored = await persistRotationIn(tx, same.id, prepared);
543
+ return {
544
+ id: same.id,
545
+ outcome: 'rotated',
546
+ credential: stored,
547
+ credentialEpoch: same.credentialEpoch ?? 1,
548
+ };
320
549
  }
321
550
  const existing = rows.find((row) => row.id === id);
322
551
  if (existing) {
@@ -342,15 +571,22 @@ export async function addRow(rt, input, options = {}) {
342
571
  credentialEpoch: 1,
343
572
  needsFirstReading: credential.type === 'oauth',
344
573
  });
345
- const stored = await rotateIn(rt, tx, id, credential, {
574
+ const prepared = planRotationIn(rt, tx, id, credential, {
346
575
  clearErrors: true,
347
576
  ...(incoming !== undefined
348
577
  ? { providerState: { kind: 'set', value: incoming } }
349
578
  : {}),
350
579
  });
580
+ await tx.completeTorn();
581
+ const stored = await persistRotationIn(tx, id, prepared);
351
582
  if (!existing.hasEntry)
352
583
  await tx.commitConfig();
353
- return { id, outcome: 'completed', credential: stored };
584
+ return {
585
+ id,
586
+ outcome: 'completed',
587
+ credential: stored,
588
+ credentialEpoch: existing.credentialEpoch ?? 1,
589
+ };
354
590
  }
355
591
  // An id the pool held before starts past every epoch it held, so
356
592
  // work attributed to the earlier row's credential, from this
@@ -371,9 +607,18 @@ export async function addRow(rt, input, options = {}) {
371
607
  tx.setEntry(id, {
372
608
  credentialEpoch,
373
609
  needsFirstReading: credential.type === 'oauth',
610
+ ...(input.stage
611
+ ? { staged: { reservation: input.stage.reservation } }
612
+ : {}),
374
613
  });
375
614
  let outcome = 'added';
376
- if (addedIdentity !== undefined && credential.type === 'oauth') {
615
+ if (input.disabled) {
616
+ disableIn(tx, id, input.disabled.reason);
617
+ outcome = 'added-disabled';
618
+ }
619
+ if (!input.disabled &&
620
+ addedIdentity !== undefined &&
621
+ credential.type === 'oauth') {
377
622
  // Same account, different credential: kept on disk, disabled.
378
623
  const holder = rows.find((row) => row.invalid === undefined &&
379
624
  row.type === 'oauth' &&
@@ -389,7 +634,12 @@ export async function addRow(rt, input, options = {}) {
389
634
  // completion preserves the credential, stamp and provider state
390
635
  // byte for byte; a crash leaves either this orphan or a whole row.
391
636
  await tx.commitConfig();
392
- return { id, outcome, credential: orphan.credential };
637
+ return {
638
+ id,
639
+ outcome,
640
+ credential: orphan.credential,
641
+ credentialEpoch: orphan.credentialEpoch ?? credentialEpoch,
642
+ };
393
643
  }
394
644
  // The credential is written first. A crash before the config write
395
645
  // then leaves a state entry no roster row names, which no reader
@@ -397,16 +647,34 @@ export async function addRow(rt, input, options = {}) {
397
647
  // roster row could load beside a credential left under its id by an
398
648
  // interrupted removal. Nothing of such a leftover entry is kept.
399
649
  tx.dropStateAccount(id);
400
- const stored = await rotateIn(rt, tx, id, credential, {
650
+ const prepared = planRotationIn(rt, tx, id, credential, {
651
+ ...(input.stage && input.disabled
652
+ ? {
653
+ staged: {
654
+ reservation: input.stage.reservation,
655
+ disabledReason: input.disabled.reason,
656
+ ...(label !== undefined ? { label } : {}),
657
+ ...(incoming !== undefined
658
+ ? { providerState: canonicalDigest(incoming) }
659
+ : {}),
660
+ },
661
+ }
662
+ : {}),
401
663
  ...(incoming !== undefined
402
664
  ? { providerState: { kind: 'set', value: incoming } }
403
665
  : {}),
404
666
  });
667
+ if (mode === 'rotate')
668
+ await tx.completeTorn();
669
+ const stored = await persistRotationIn(tx, id, prepared);
405
670
  await tx.commitConfig();
406
- return { id, outcome, credential: stored };
671
+ return { id, outcome, credential: stored, credentialEpoch };
407
672
  }, { completeTorn: false });
408
673
  });
409
- if (credential.type === 'oauth' &&
674
+ // Even a pull that skips its disabled row can repair other interrupted rows.
675
+ // A disabled or staged add must leave those other rows untouched.
676
+ if (!preparing &&
677
+ credential.type === 'oauth' &&
410
678
  (result.outcome === 'added' || result.outcome === 'completed'))
411
679
  rt.firePull(result.id, 'add');
412
680
  return result;
@@ -580,6 +848,8 @@ async function transitionRow(rt, operation, id, flag, options) {
580
848
  for (const extra of options.extraLocks ?? [])
581
849
  await locks.acquire(extra);
582
850
  return withTransaction(ctx, locks, progress, { operation, rowId: id }, async (tx) => {
851
+ await protectIn(tx, id, options.protect);
852
+ tx.assertNotStaged(id);
583
853
  const loaded = tx.row(id);
584
854
  const row = flag.enabled
585
855
  ? requireUsableRow('enable', id, loaded)
@@ -588,8 +858,9 @@ async function transitionRow(rt, operation, id, flag, options) {
588
858
  throw unknownRow(operation, id);
589
859
  if (rowLockKey(row) !== rowLockKey(seen))
590
860
  throw keyChanged(operation, id);
591
- if (fence !== undefined)
861
+ if (fence !== undefined) {
592
862
  assertRowAttribution(operation, id, row, fence);
863
+ }
593
864
  if (flag.enabled &&
594
865
  row.disabledReason?.startsWith(IDENTITY_CONTRADICTED_REASON_PREFIX))
595
866
  throw refusal('enable', id, 'identity-contradicted', `row ${id} needs an identity-validated credential replacement before it can be enabled`);
@@ -610,6 +881,7 @@ async function transitionRow(rt, operation, id, flag, options) {
610
881
  throw refusal('enable', id, 'duplicate-identity', `row ${holder.id} is enabled with the same identity as row ${id}`);
611
882
  }
612
883
  if (mutator === undefined || codec === undefined) {
884
+ await tx.completeTorn();
613
885
  if (!writesConfig)
614
886
  return { id };
615
887
  if (flag.enabled)
@@ -629,6 +901,7 @@ async function transitionRow(rt, operation, id, flag, options) {
629
901
  const plan = await planProviderStateIn(tx, codec, operation, row, mutator, true);
630
902
  if (plan.kind === 'declined')
631
903
  return { id, declined: true };
904
+ await tx.completeTorn();
632
905
  const result = {
633
906
  id,
634
907
  providerStateOutcome: plan.kind === 'unchanged'
@@ -668,7 +941,7 @@ async function transitionRow(rt, operation, id, flag, options) {
668
941
  applyTransition(tx, id, transition);
669
942
  await tx.commitConfig();
670
943
  return result;
671
- });
944
+ }, { completeTorn: false });
672
945
  });
673
946
  }
674
947
  /**
@@ -712,6 +985,11 @@ export async function removeRow(rt, id, options = {}) {
712
985
  throw refusal('remove', id, 'invalid-input', 'id must be non-empty');
713
986
  const fence = options.attribution;
714
987
  validateAttribution('remove', id, fence);
988
+ if (options.staged !== undefined &&
989
+ (!isRecord(options.staged) ||
990
+ typeof options.staged.reservation !== 'string' ||
991
+ !options.staged.reservation))
992
+ throw refusal('remove', id, 'invalid-input', 'a staged removal needs a reservation');
715
993
  const result = await readPool(ctx);
716
994
  if (result.status !== 'ready')
717
995
  throw notReadyError(result, 'remove', id);
@@ -723,6 +1001,15 @@ export async function removeRow(rt, id, options = {}) {
723
1001
  for (const extra of options.extraLocks ?? [])
724
1002
  await locks.acquire(extra);
725
1003
  return withTransaction(ctx, locks, progress, { operation: 'remove', rowId: id }, async (tx) => {
1004
+ const reservation = tx.reservation(id);
1005
+ if (reservation !== undefined) {
1006
+ if (!isRecord(reservation) ||
1007
+ !options.staged ||
1008
+ reservation.reservation !== options.staged.reservation)
1009
+ throw refusal('remove', id, 'row-staged', `row ${id} is reserved for roster publication`);
1010
+ }
1011
+ else if (options.staged)
1012
+ throw refusal('remove', id, 'attribution', `row ${id} is no longer reserved`);
726
1013
  const row = tx.row(id);
727
1014
  const orphan = hasStateAccount(tx.state, id);
728
1015
  if (!row && !orphan)
@@ -747,6 +1034,8 @@ export async function removeRow(rt, id, options = {}) {
747
1034
  throw refusal('remove', id, 'row-protected', reason);
748
1035
  }
749
1036
  if (row) {
1037
+ if (fence === undefined)
1038
+ await tx.completeTorn();
750
1039
  tx.dropRosterRows(id);
751
1040
  await tx.commitConfig();
752
1041
  }
@@ -758,18 +1047,18 @@ export async function removeRow(rt, id, options = {}) {
758
1047
  },
759
1048
  // An attributed removal is refused, when it is, with nothing written:
760
1049
  // completing another row's interrupted write first would be a write.
761
- { completeTorn: fence === undefined });
1050
+ { completeTorn: false });
762
1051
  });
763
1052
  }
764
1053
  /** An attributed removal of a roster row: bound, not torn, same epoch and identity. */
765
- function assertBoundRowAttribution(id, row, fence) {
766
- assertRowAttribution('remove', id, row, fence);
1054
+ export function assertBoundRowAttribution(id, row, fence, operation = 'remove') {
1055
+ assertRowAttribution(operation, id, row, fence);
767
1056
  // A torn row is between the two writes of another operation; which
768
1057
  // credential it holds is not settled, so no attribution can match it.
769
1058
  if (row.torn)
770
- throw refusal('remove', id, 'attribution', `row ${id} is between the writes of another operation; retry once it completes`, true);
1059
+ throw refusal(operation, id, 'attribution', `row ${id} is between the writes of another operation; retry once it completes`, true);
771
1060
  if (row.stamp !== 'bound')
772
- throw refusal('remove', id, 'unbound-credential', `row ${id}'s credential is not bound to its stamp, so the removal cannot be attributed to it`);
1061
+ throw refusal(operation, id, 'unbound-credential', `row ${id}'s credential is not bound to its stamp, so the removal cannot be attributed to it`);
773
1062
  }
774
1063
  /**
775
1064
  * An attributed removal of an orphan. The orphan is loaded the way an
@@ -1,6 +1,7 @@
1
1
  import { PoolOperationError } from './errors.js';
2
2
  import { notReadyError, readPool, } from './mutate.js';
3
- import { rowLockKey } from './schema.js';
3
+ import { assertNotReserved } from './reserved.js';
4
+ import { CREDENTIAL_STAMP_KEY, entryIn, isRecord, rowLockKey, } from './schema.js';
4
5
  /**
5
6
  * The row lock's (name, path): keyed by the row's recorded wire identity when
6
7
  * known, else its local id, beside the state file. The key is prefixed and
@@ -19,6 +20,17 @@ export async function readRow(rt, operation, id) {
19
20
  if (result.status !== 'ready')
20
21
  throw notReadyError(result, operation, id);
21
22
  const row = result.rows.find((candidate) => candidate.id === id);
23
+ const entry = entryIn(result.config, id);
24
+ const accounts = result.state.accounts;
25
+ const account = isRecord(accounts) && Object.hasOwn(accounts, id) ? accounts[id] : undefined;
26
+ const stamp = isRecord(account) ? account[CREDENTIAL_STAMP_KEY] : undefined;
27
+ if (row &&
28
+ !['enable', 'disable'].includes(operation) &&
29
+ entry &&
30
+ Object.hasOwn(entry, 'staged'))
31
+ assertNotReserved(operation, id, entry.staged);
32
+ if (!row && isRecord(stamp) && Object.hasOwn(stamp, 'staged'))
33
+ assertNotReserved(operation, id, stamp.staged);
22
34
  if (!row)
23
35
  throw unknownRow(operation, id);
24
36
  return { result, row };
@@ -154,6 +154,10 @@ export interface PoolRow {
154
154
  credentialEpoch?: number;
155
155
  needsFirstReading: boolean;
156
156
  disabledReason?: string;
157
+ /** Store-owned reservation; only `publishRoster` releases it for ordinary use. */
158
+ staged?: {
159
+ reservation: string;
160
+ };
157
161
  /** The opaque quota map, as validated by the codec. */
158
162
  quota?: unknown;
159
163
  /**
@@ -249,7 +253,21 @@ export interface CredentialStamp {
249
253
  binding?: CredentialBinding;
250
254
  replace?: true;
251
255
  providerState?: string;
256
+ staged?: StagedStamp;
252
257
  }
258
+ /** Original staged-add metadata, persisted with the credential before config exists. */
259
+ export interface StagedStamp {
260
+ reservation: string;
261
+ label?: string;
262
+ disabledReason: string;
263
+ providerState?: string;
264
+ }
265
+ /** Canonical JSON: recursively sorted object keys, preserved array order. */
266
+ export declare function canonicalJson(value: unknown): string;
267
+ export declare function canonicalDigest(value: unknown): string;
268
+ export declare function parseReservation(raw: unknown): {
269
+ reservation: string;
270
+ } | undefined;
253
271
  /**
254
272
  * Key, inside a state-file account entry, of the provider state kept beside
255
273
  * the credential. Older readers ignore it.