@cortexkit/common-auth 0.7.0 → 0.9.0

package/dist/rpc/rpc-server.js

@@ -4,15 +4,47 @@ import { createServer, } from 'node:http';
 import { join } from 'node:path';
 import { isSessionId, } from './notifications.js';
 import { sweepRpcState, writePortFile } from './port-file.js';
+/**
+ * Thrown by an `apply` or `drain` handler to refuse a request with a 4xx
+ * status. Its message is sent on the wire as `{error: message}`, so it must
+ * be written for the client and never quote a credential. Any other error a
+ * handler throws answers 500 with a fixed code.
+ */
+export class RpcRequestError extends Error {
+    status;
+    constructor(status, message) {
+        if (!Number.isInteger(status) || status < 400 || status > 499)
+            throw new RangeError(`RpcRequestError status must be 4xx, got ${status}`);
+        super(message);
+        this.name = 'RpcRequestError';
+        this.status = status;
+    }
+}
+const MAX_BODY_BYTES = 1_000_000;
+/** The request body exceeded the cap; answered 413. */
+class BodyTooLargeError extends Error {
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
+        const tooLarge = () => {
+            // Keep reading and discarding the rest, so the client finishes sending
+            // and can read the 413 instead of seeing a reset connection.
+            req.removeAllListeners('data');
+            req.on('data', () => { });
+            req.resume();
+            reject(new BodyTooLargeError('body too large'));
+        };
+        const declared = Number(req.headers['content-length']);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            tooLarge();
+            return;
+        }
         const chunks = [];
         let size = 0;
         req.on('data', (chunk) => {
             size += chunk.length;
-            if (size > 1_000_000) {
-                req.destroy();
-                reject(new Error('body too large'));
+            if (size > MAX_BODY_BYTES) {
+                tooLarge();
                 return;
             }
             chunks.push(chunk);
@@ -21,6 +53,23 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
+class ApplyDeadlineError extends Error {
+}
+/** Settle with `work`, or reject at `ms` while `work` keeps running. */
+async function withDeadline(work, ms) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ApplyDeadlineError('apply deadline exceeded')), ms);
+    });
+    // A handler that fails after its deadline has nobody left to answer.
+    work.catch(() => { });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function tokenOk(header, token) {
     if (!header?.startsWith('Bearer '))
         return false;
@@ -45,25 +94,43 @@ export async function startRpcServer(options) {
     server.requestTimeout = receiptTimeoutMs;
     server.headersTimeout = receiptTimeoutMs;
     async function dispatch(req, res) {
-        const json = (status, value) => {
-            // Guard against writing to a socket that was destroyed (e.g. when
-            // readBody rejected after req.destroy() on an oversized body).
+        const json = (status, value, headers = {}) => {
+            // Guard against writing to a socket that is already gone (the
+            // inactivity timeout destroys it).
             if (res.headersSent || res.writableEnded || res.destroyed)
                 return;
-            res.writeHead(status, { 'content-type': 'application/json' });
+            res.writeHead(status, { 'content-type': 'application/json', ...headers });
             res.end(JSON.stringify(value));
         };
         try {
-            const url = req.url ?? '';
-            if (req.method === 'GET' && url === '/health')
+            // Route on the pathname alone, so a query string does not turn a known
+            // method into a 404.
+            const path = new URL(req.url ?? '/', 'http://127.0.0.1').pathname;
+            if (req.method === 'GET' && path === '/health')
                 return json(200, { ok: true });
-            if (req.method !== 'POST' || !url.startsWith('/rpc/'))
+            if (req.method !== 'POST' || !path.startsWith('/rpc/'))
                 return json(404, { error: 'not found' });
             if (!tokenOk(req.headers.authorization, token))
                 return json(401, { error: 'unauthorized' });
-            const method = url.slice('/rpc/'.length);
-            const body = await readBody(req);
-            const params = JSON.parse(body || '{}');
+            const method = path.slice('/rpc/'.length);
+            let body;
+            try {
+                body = await readBody(req);
+            }
+            catch (error) {
+                if (!(error instanceof BodyTooLargeError))
+                    throw error;
+                // Close the connection after answering: the rest of the oversized
+                // body is not worth keeping the socket for.
+                return json(413, { error: 'body too large' }, { connection: 'close' });
+            }
+            let params;
+            try {
+                params = JSON.parse(body || '{}');
+            }
+            catch {
+                return json(400, { error: 'invalid json' });
+            }
             if (method === 'pending-notifications') {
                 if (options.requireSession === true && !isSessionId(params.sessionId))
                     return json(400, { error: 'session required' });
@@ -78,12 +145,29 @@ export async function startRpcServer(options) {
                 return json(200, { messages });
             }
             if (method === 'apply') {
-                const result = await options.apply(params);
+                const work = Promise.resolve(options.apply(params));
+                const result = options.applyDeadlineMs === undefined
+                    ? await work
+                    : await withDeadline(work, options.applyDeadlineMs);
                 return json(200, result);
             }
             return json(404, { error: 'unknown method' });
         }
         catch (error) {
+            if (error instanceof RpcRequestError) {
+                log.debug('rpc request refused', {
+                    pid: process.pid,
+                    status: error.status,
+                });
+                return json(error.status, { error: error.message });
+            }
+            if (error instanceof ApplyDeadlineError) {
+                log.warn('rpc apply deadline exceeded', {
+                    pid: process.pid,
+                    deadlineMs: options.applyDeadlineMs,
+                });
+                return json(504, { error: 'handler deadline exceeded' });
+            }
             // A handler's exception can quote a request or a credential, so its
             // text goes to the plugin's log channel only; the wire gets a fixed code.
             log.warn('rpc request failed', {

package/dist/sidebar-file/sidebar-file.d.ts

@@ -68,6 +68,16 @@ export interface SidebarFileOptions<T> {
      * that the lock was lost. Without it such a write is only reported.
      */
     repair?: SidebarRepair<T>;
+    /**
+     * Name of the lock writers coordinate on, as `<path>.<lockName>.lock`.
+     * Defaults to `'sidebar-write'`. It names both the lock a write takes and
+     * the lock whose ownership is checked before the rename, so a takeover of
+     * this name refuses the write. A plugin keeping an existing writer's lock
+     * identity passes that writer's name; mutual exclusion with that writer is
+     * promised only while it holds a live lease of the same name in the same
+     * lock-file format, not for its stale-lock reclamation or renewal.
+     */
+    lockName?: string;
 }
 export interface SidebarFile<T> {
     read(): Promise<T>;

package/dist/sidebar-file/sidebar-file.js

@@ -43,6 +43,7 @@ export function createSidebarFile(options) {
     };
     const lockOptions = {
         ...WRITER_LOCK_CONSTANTS.sidebar,
+        name: options.lockName ?? WRITER_LOCK_CONSTANTS.sidebar.name,
         timeoutMs: options.timeoutMs ?? WRITER_LOCK_CONSTANTS.sidebar.timeoutMs,
     };
     /**

package/dist/store/attribution.d.ts

@@ -2,8 +2,19 @@ import { type StoreRuntime } from './runtime.js';
 /**
  * What a pull or refresh captured about its row (named by id alongside) when
  * it was issued. A result applies only while the row with that id still has
- * this credential epoch and this recorded identity; a replaced credential bumps the epoch, so work issued
- * for the old one is discarded.
+ * this credential epoch and this recorded identity; a replaced credential
+ * bumps the epoch, so work issued for the old one is discarded.
+ *
+ * The epoch names one credential lineage of the row: a credential given by
+ * `add` or `replace`, through every refresh and `rotate` of it, which keep
+ * the epoch. Since 0.8.0 that holds across removal too: a row added under an
+ * id the pool held before starts past every epoch that id held (the store
+ * records them when it drops a row, in the config file, so every process
+ * sees it), so an attribution taken for a removed row is refused once the id
+ * is added again, even with the same identity. Writers older than 0.8.0
+ * start a re-added id at epoch 1 again, and a writer that does not know the
+ * pool can remove and re-add a row without the store seeing it; work
+ * attributed across either may still apply to the new credential.
  */
 export interface Attribution {
     credentialEpoch: number;

package/dist/store/errors.d.ts

@@ -19,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
  * lock outcomes (a wait that ran out, and a lease found lost); the rest are
  * refusals and failures of the operation itself.
  */
-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' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'invalid-provider-state' | 'after-persist-hook' | 'unexpected';
+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';
 /**
  * The single failure value of every store operation. `committed` is present
  * only when the operation had already written a credential to the state file

package/dist/store/identity.d.ts

@@ -9,6 +9,8 @@ export interface RowEditor {
     entry(id: string): Record<string, unknown> | undefined;
     setEntry(id: string, entry: Record<string, unknown>): void;
 }
+/** Prefix of a refresh quarantine reason, followed by JSON of the expected and returned identities. */
+export declare const IDENTITY_CONTRADICTED_REASON_PREFIX = "identity-contradicted: ";
 /** The reason recorded on a row disabled because an earlier row is the same account. */
 export declare const DUPLICATE_IDENTITY_REASON = "duplicate-identity";
 /**

package/dist/store/identity.js

@@ -1,3 +1,5 @@
+/** Prefix of a refresh quarantine reason, followed by JSON of the expected and returned identities. */
+export const IDENTITY_CONTRADICTED_REASON_PREFIX = 'identity-contradicted: ';
 /** The reason recorded on a row disabled because an earlier row is the same account. */
 export const DUPLICATE_IDENTITY_REASON = 'duplicate-identity';
 /**
@@ -22,7 +24,13 @@ export function disableIn(tx, id, reason) {
         return;
     raw.enabled = false;
     const entry = tx.entry(id) ?? { credentialEpoch: 1, needsFirstReading: true };
-    tx.setEntry(id, { ...entry, disabledReason: reason });
+    // A routine disable must not erase the evidence needed to refuse enable.
+    const quarantined = typeof entry.disabledReason === 'string' &&
+        entry.disabledReason.startsWith(IDENTITY_CONTRADICTED_REASON_PREFIX);
+    tx.setEntry(id, {
+        ...entry,
+        disabledReason: quarantined ? entry.disabledReason : reason,
+    });
 }
 /**
  * Marks a row enabled: `enabled: true` in the roster row and no

package/dist/store/mutate.d.ts

@@ -118,7 +118,11 @@ export declare class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     commitConfig(options?: {
         counted?: boolean;

package/dist/store/mutate.js

@@ -4,7 +4,7 @@ import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
 import { PoolOperationError, } from './errors.js';
 import { callFailureHook } from './hooks.js';
 import { LockStack, } from './refresh-lock.js';
-import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, rosterRowIn, setEntryIn, } from './schema.js';
+import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, retireEpochsIn, rosterOf, rosterRowIn, setEntryIn, } from './schema.js';
 import { completeTornRows, loadRows } from './torn.js';
 async function readJson(path) {
     let text;
@@ -169,7 +169,11 @@ export class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     async commitConfig(options = {}) {
         const roster = this.roster();
@@ -177,6 +181,14 @@ export class Transaction {
         for (const raw of roster)
             if (isRecord(raw) && typeof raw.id === 'string')
                 rosterIds.add(raw.id);
+        const dropped = new Set();
+        for (const raw of rosterOf(this.snapshot.config))
+            if (isRecord(raw) && typeof raw.id === 'string' && !rosterIds.has(raw.id))
+                dropped.add(raw.id);
+        for (const id of Object.keys(this.entries()))
+            if (!rosterIds.has(id))
+                dropped.add(id);
+        retireEpochsIn(this.config, dropped);
         const entries = this.entries();
         const kept = {};
         for (const [id, entry] of Object.entries(entries)) {

package/dist/store/pool.d.ts

@@ -88,6 +88,13 @@ export interface PoolStore {
     }): Promise<{
         status: InitializeOutcome;
     }>;
+    /**
+     * Adds a row, or completes or rotates the row already holding the id or
+     * the secret. A new row starts at credential epoch 1; since 0.8.0 one
+     * whose id the pool held before starts one past the highest epoch that id
+     * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
+     * refuses (`id-removed`) before writing.
+     */
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
     /**
      * Gives a row a new credential and a new credential epoch. Since 0.6.0 the

package/dist/store/refresh.d.ts

@@ -27,7 +27,11 @@ export interface RefreshOptions {
     providerLock?: PoolLockSpec;
     /** Taken after the provider-wide lock in this order, released in reverse. */
     extraLocks?: readonly PoolLockSpec[];
-    /** Awaited once the rotation is persisted and the store locks released. */
+    /**
+     * Awaited once an ordinary rotation is persisted and the store locks released.
+     * Never called for `identity-contradicted`: its credential must not propagate
+     * as the row's recorded account.
+     */
     onPersisted?: (rowId: string, credential: StoredCredential) => void | Promise<void>;
     onFailure?: FailureHook;
     /**
@@ -42,6 +46,18 @@ export type RefreshOutcome = {
     rowId: string;
     credential: StoredCredential;
     identity?: string;
+}
+/**
+ * The provider's successor credential is stored bound to expectedIdentity,
+ * not returnedIdentity. The row stays disabled until the adapter supplies
+ * an identity-validated replacement credential through replace.
+ */
+ | {
+    status: 'identity-contradicted';
+    rowId: string;
+    expectedIdentity: string;
+    returnedIdentity: string;
+    credential: StoredCredential;
 } | {
     status: 'refused';
     rowId: string;

package/dist/store/refresh.js

@@ -1,11 +1,13 @@
+import { randomUUID } from 'node:crypto';
 import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
-import { recordIdentityIn } from './identity.js';
+import { IDENTITY_CONTRADICTED_REASON_PREFIX, recordIdentityIn, } from './identity.js';
 import { runOperation, withTransaction } from './mutate.js';
 import { acceptProviderState, mergedProviderState } from './provider-state.js';
 import { rotateIn } from './rows.js';
 import { readRow, refusal, requireBound, rowLockSpec, } from './runtime.js';
 import { rotationStamp, rotationStampUntrusted, rowLockKey, } from './schema.js';
+import { applyTransition } from './torn.js';
 function requireRefreshable(id, row) {
     if (!row)
         throw refusal('refresh', id, 'unknown-row', `no row ${id} in the pool`);
@@ -137,6 +139,21 @@ export async function refreshRow(rt, id, provider, options = {}) {
                 refresh: result.refresh,
                 expires: result.expires,
             };
+            const contradiction = current.identity !== undefined &&
+                result.identity !== undefined &&
+                current.identity !== result.identity
+                ? {
+                    expectedIdentity: current.identity,
+                    returnedIdentity: result.identity,
+                }
+                : undefined;
+            const transition = contradiction
+                ? {
+                    mark: randomUUID(),
+                    enabled: false,
+                    reason: `${IDENTITY_CONTRADICTED_REASON_PREFIX}${JSON.stringify(contradiction)}`,
+                }
+                : undefined;
             const learnt = current.identity === undefined && result.identity
                 ? result.identity
                 : undefined;
@@ -145,6 +162,11 @@ export async function refreshRow(rt, id, provider, options = {}) {
             // forward rather than leaving an identity no stamp proves.
             const stored = await rotateIn(rt, tx, id, credential, {
                 stamp: rotationStamp(prior, now),
+                // Write state first with the disable marker, then config below.
+                // Once the successor is durable, recovery projects the disable even
+                // if config has not landed. A crash before the first rename still
+                // loses an in-memory provider reply, as in any ordinary refresh.
+                transition,
                 identity: learnt,
                 ...(incoming !== undefined
                     ? {
@@ -152,16 +174,27 @@ export async function refreshRow(rt, id, provider, options = {}) {
                     }
                     : {}),
             });
+            if (transition !== undefined) {
+                applyTransition(tx, id, transition);
+                await tx.commitConfig();
+            }
             let identity = current.identity;
             if (learnt !== undefined) {
                 recordIdentityIn(tx, id, learnt);
                 identity = learnt;
                 await tx.commitConfig();
             }
-            return { stored, identity, refused: undefined };
+            return { stored, identity, contradiction, refused: undefined };
         });
         if (commit.refused !== undefined)
             return { status: 'refused', rowId: id, reason: commit.refused };
+        if (commit.contradiction !== undefined)
+            return {
+                status: 'identity-contradicted',
+                rowId: id,
+                ...commit.contradiction,
+                credential: commit.stored,
+            };
         if (options.onPersisted) {
             try {
                 const persisted = options.onPersisted;

package/dist/store/rows.d.ts

@@ -5,6 +5,7 @@ import { type ProviderStateWrite, type RowTransitionMutator, type UpdateProvider
 import type { PoolLockSpec } from './refresh-lock.js';
 import { type StoreRuntime } from './runtime.js';
 import { type CredentialBinding, type PoolCredential, type PoolRow, type RotateCredential, type StoredCredential } from './schema.js';
+import { type StampedTransition } from './torn.js';
 export type FailureHook = (rowId: string, error: PoolOperationError) => void | Promise<void>;
 export interface RowOperationOptions {
     /** Called once, awaited, on every non-success path, before locks release. */
@@ -122,6 +123,8 @@ export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string,
     binding?: CredentialBinding;
     identity?: string;
     providerState?: ProviderStateWrite;
+    /** Config transition persisted with the successor credential for crash recovery. */
+    transition?: StampedTransition;
 }): Promise<StoredCredential>;
 export declare function addRow(rt: StoreRuntime, input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
 export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
@@ -178,7 +181,9 @@ export interface RowTransitionResult {
 export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
 /**
  * Clears a row's `enabled: false` and its `disabledReason` in one config
- * write. An OAuth row whose recorded identity another enabled OAuth row holds
+ * write. An identity-contradicted row refuses with `identity-contradicted`
+ * until the caller validates a replacement's identity and supplies it to replace.
+ * An OAuth row whose recorded identity another enabled OAuth row holds
  * stays disabled and the call refuses (`duplicate-identity`): the same rule
  * that makes `add` store such a row disabled. Enabling a row that is already
  * enabled writes nothing. See `RowTransitionOptions` for the attributed
@@ -192,7 +197,9 @@ export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTra
  * between the two leaves a row every reader already sees as removed, with
  * only an orphaned state entry that no reader loads; calling `remove` again
  * drops that entry (`completed`). As with every id the store drops, the id is
- * not reused by `add` in this process.
+ * not reused by `add` in this process, and the config write records the
+ * row's credential epoch, so an `add` of the id in any other process starts
+ * past it (see `nextAddEpochIn`).
  */
 export declare function removeRow(rt: StoreRuntime, id: string, options?: RemoveOptions): Promise<RemoveResult>;
 /**

package/dist/store/rows.js

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
-import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enableIn, recordIdentityIn, } from './identity.js';
+import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enableIn, IDENTITY_CONTRADICTED_REASON_PREFIX, recordIdentityIn, } from './identity.js';
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
 import { acceptProviderState, mergedProviderState, planProviderStateIn, providerStateCoverage, replacementProviderState, } from './provider-state.js';
 import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
-import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, PROVIDER_STATE_KEY, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
+import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, nextAddEpochIn, PROVIDER_STATE_KEY, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
 import { applyTransition, bindReplacement, TRANSITION_STAMP_KEY, } from './torn.js';
 /** Fields of a state entry that belong to the credential it replaces. */
 const CREDENTIAL_STATE_FIELDS = [
@@ -122,12 +122,17 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
     tx.setStateAccount(id, {
         ...kept,
         ...stateFieldsFor(credential, stamp),
-        [CREDENTIAL_STAMP_KEY]: stampFor(stored, credentialEpoch, extra.binding ?? bindingInTx(tx, id, stored, extra.identity), {
-            replace: extra.binding !== undefined,
-            ...(providerStateBinding !== undefined
-                ? { providerState: providerStateBinding }
+        [CREDENTIAL_STAMP_KEY]: {
+            ...(extra.transition !== undefined
+                ? { [TRANSITION_STAMP_KEY]: extra.transition }
                 : {}),
-        }),
+            ...stampFor(stored, credentialEpoch, extra.binding ?? bindingInTx(tx, id, stored, extra.identity), {
+                replace: extra.binding !== undefined,
+                ...(providerStateBinding !== undefined
+                    ? { providerState: providerStateBinding }
+                    : {}),
+            }),
+        },
     });
     await tx.commitState(stored);
     return stored;
@@ -259,6 +264,12 @@ export async function addRow(rt, input, options = {}) {
                     await tx.commitConfig();
                 return { id, outcome: 'completed', credential: stored };
             }
+            // An id the pool held before starts past every epoch it held, so
+            // work attributed to the earlier row's credential, from this
+            // process or another, never matches the new one.
+            const credentialEpoch = nextAddEpochIn(tx.config, id);
+            if (!isCredentialEpoch(credentialEpoch))
+                throw refusal('add', id, 'id-removed', `id ${id} has held every credential epoch and is not reused; add the credential under another id`);
             tx.roster().push(rosterRowFor({
                 id,
                 credential,
@@ -267,7 +278,7 @@ export async function addRow(rt, input, options = {}) {
                 addedAt: ctx.now(),
             }));
             tx.setEntry(id, {
-                credentialEpoch: 1,
+                credentialEpoch,
                 needsFirstReading: credential.type === 'oauth',
             });
             let outcome = 'added';
@@ -474,6 +485,9 @@ async function transitionRow(rt, operation, id, flag, options) {
                     row.identity !== fence.identity)
                     throw refusal(operation, id, 'attribution', `the ${operation} of ${id} was issued for a credential or account the row no longer holds`, true);
             }
+            if (flag.enabled &&
+                row.disabledReason?.startsWith(IDENTITY_CONTRADICTED_REASON_PREFIX))
+                throw refusal('enable', id, 'identity-contradicted', `row ${id} needs an identity-validated credential replacement before it can be enabled`);
             // An enable of a row that is already enabled has nothing to write
             // to the config; a disable always rewrites it, as it always has.
             const writesConfig = !flag.enabled || !row.enabled || row.disabledReason !== undefined;
@@ -561,7 +575,9 @@ export function disableRow(rt, id, reason, options = {}) {
 }
 /**
  * Clears a row's `enabled: false` and its `disabledReason` in one config
- * write. An OAuth row whose recorded identity another enabled OAuth row holds
+ * write. An identity-contradicted row refuses with `identity-contradicted`
+ * until the caller validates a replacement's identity and supplies it to replace.
+ * An OAuth row whose recorded identity another enabled OAuth row holds
  * stays disabled and the call refuses (`duplicate-identity`): the same rule
  * that makes `add` store such a row disabled. Enabling a row that is already
  * enabled writes nothing. See `RowTransitionOptions` for the attributed
@@ -577,7 +593,9 @@ export function enableRow(rt, id, options = {}) {
  * between the two leaves a row every reader already sees as removed, with
  * only an orphaned state entry that no reader loads; calling `remove` again
  * drops that entry (`completed`). As with every id the store drops, the id is
- * not reused by `add` in this process.
+ * not reused by `add` in this process, and the config write records the
+ * row's credential epoch, so an `add` of the id in any other process starts
+ * past it (see `nextAddEpochIn`).
  */
 export async function removeRow(rt, id, options = {}) {
     assertNotInsideHook('remove');

package/dist/store/schema.d.ts

@@ -4,6 +4,15 @@ export declare const POOL_KEY = "commonAuthPool";
 export declare const POOL_SCHEMA_VERSION = 1;
 /** Property of `commonAuthPool` holding the per-row entries, keyed by local id. */
 export declare const POOL_ROWS_KEY = "rows";
+/**
+ * Property of `commonAuthPool` (since 0.8.0) holding, per id, the highest
+ * credential epoch a row with that id held when the store last dropped it
+ * from the pool. A row added later under the same id starts past it (see
+ * `nextAddEpochIn`), so an attribution taken for the dropped row never
+ * matches the new one. Older readers ignore it, and older writers keep it
+ * as they keep every pool key they do not know.
+ */
+export declare const POOL_RETIRED_EPOCHS_KEY = "retiredEpochs";
 /** The `version` older readers of the same files expect at the top level. */
 export declare const LEGACY_STORE_VERSION = 1;
 /**
@@ -348,6 +357,37 @@ export declare function ensureEntries(config: Record<string, unknown>): Record<s
 export declare function entryIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
 /** Sets an entry as an own property, so an id such as `toString` is safe. */
 export declare function setEntryIn(config: Record<string, unknown>, id: string, entry: Record<string, unknown>): void;
+/**
+ * The credential epoch recorded for a dropped id (see
+ * `POOL_RETIRED_EPOCHS_KEY`), or undefined when none is. A value that is not
+ * a credential epoch counts as none.
+ */
+export declare function retiredEpochIn(config: Record<string, unknown>, id: string): number | undefined;
+/**
+ * The credential epoch `add` gives a new row with this id: one past the
+ * highest epoch the id is known to have held, which is the epoch recorded
+ * when the store dropped it, or the epoch of an entry left behind by a writer
+ * that removed only its roster row; 1 for an id the pool never held.
+ *
+ * An attribution names a row by id and credential epoch (and identity), and
+ * an id is chosen by the plugin, so it is often the same one again (`main`).
+ * Were a re-added row to start at epoch 1 again, an attribution taken for the
+ * removed row's credential would match the new credential exactly, in this
+ * process or any other. Starting past every earlier epoch makes such an
+ * attribution fail as it does after a `replace`. The result may lie past the
+ * safe integers (an id whose last row was at `Number.MAX_SAFE_INTEGER`);
+ * `add` refuses such an id.
+ */
+export declare function nextAddEpochIn(config: Record<string, unknown>, id: string): number;
+/**
+ * Records, in a config being written, the epochs of the ids it drops: for
+ * each, the epoch its entry claims (1 for a row without one, the epoch such a
+ * row is at), kept only when above what is already recorded, so the record
+ * for an id never goes down. Valid recorded values of other ids are kept; a
+ * record that is not an object, or a value in it that is not an epoch, says
+ * nothing and is replaced. An entry whose epoch cannot be read records 1.
+ */
+export declare function retireEpochsIn(config: Record<string, unknown>, dropped: Iterable<string>): void;
 /**
  * Builds the rows of a ready pool from the files exactly as they are, without
  * looking at credential stamps (see `loadRows` for the rows every reader