@cortexkit/common-auth 0.2.1 → 0.2.3

package/dist/routing/sticky.d.ts

@@ -1,5 +1,5 @@
 import { type ProjectedQuota } from '../quota/projection.js';
-import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type WindowRef } from './admission.js';
+import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type RoutingRow, type WindowRef } from './admission.js';
 import { type StickyPin } from './pins.js';
 export declare const QUOTA_STALENESS_MS: number;
 export declare const MIN_RESET_HOURS: number;
@@ -63,14 +63,40 @@ export interface StickySelection {
  * configured order, preferring one with an applicable reset credit.
  */
 export declare function selectStickyCandidate(input: StickySelectionInput): StickySelection | undefined;
+/** Reserve percent per window label; a missing label reserves nothing. */
+export type ReservePercent = Readonly<Record<string, number>>;
+/**
+ * Reserve percentages per row: a map keyed by row id, or a function of the
+ * row. A row the map lacks, or for which the function returns undefined,
+ * takes the shared `reservePercent`.
+ */
+export type RowReservePercent = ReadonlyMap<string, ReservePercent> | ((row: RoutingRow) => ReservePercent | undefined);
+/**
+ * What a valid pin does when its row is not dispatched.
+ *
+ * `keep`: the pin is retained whatever kept its row from this request.
+ *
+ * `move-on-confirmed-exhaustion`: the pin moves to the row this request is
+ * dispatched to when its own row was refused as confirmed exhausted (a spent
+ * window with a future reset, or a spent credit budget) or killed by the
+ * killswitch. A refusal for unknown quota (no reading yet, a missing window,
+ * an exhausted reading without a usable reset) and an exclusion (rate-limit
+ * mark, refresh backoff) keep the pin while this request is served elsewhere.
+ * With no admissible row the pin is retained either way.
+ */
+export type RefusedPinPolicy = 'keep' | 'move-on-confirmed-exhaustion';
 export interface StickyRouteInput extends AdmissionInput {
     requestBytes: number;
     /** Bytes already committed per row, for example from other sessions' pins. */
     pendingBytes?: ReadonlyMap<string, number>;
     /** Killswitch verdict per row; a missing row passes. */
     killswitch?: ReadonlyMap<string, boolean>;
-    /** Reserve percent per window label, applied to every row. */
-    reservePercent?: Readonly<Record<string, number>>;
+    /** Reserve percent per window label, for every row without its own. */
+    reservePercent?: ReservePercent;
+    /** Per-row reserves, which replace `reservePercent` for the rows they cover. */
+    rowReservePercent?: RowReservePercent;
+    /** Defaults to `keep`. */
+    refusedPinPolicy?: RefusedPinPolicy;
     resetCreditsApplicable?: ReadonlyMap<string, number>;
     /** The session's current pin, if it has one. */
     pin?: StickyPin;
@@ -80,8 +106,9 @@ export interface StickyRouteInput extends AdmissionInput {
 }
 /**
  * What the caller does with the session's pin: keep it, replace it with
- * `pin`, or drop it. A valid pin is always kept, even when this request was
- * routed elsewhere because its row was refused or excluded.
+ * `pin`, or drop it. Under the default `keep` policy a valid pin is always
+ * kept, even when this request was routed elsewhere because its row was
+ * refused, excluded or killed; `refusedPinPolicy` can move it instead.
  */
 export type PinAction = {
     action: 'retain';

package/dist/routing/sticky.js

@@ -233,6 +233,24 @@ export function routeSticky(input) {
             };
         }
     }
+    // A spent window with a future reset, a spent credit budget and a killswitch
+    // verdict all say the pinned row will not serve until some known later time,
+    // so the pin may move. A row refused for want of a usable reading, or
+    // excluded by a short rate-limit mark or refresh backoff, may serve again on
+    // the next reading, so its pin stays.
+    const pinRefusal = input.pin ? refusals.get(input.pin.accountId) : undefined;
+    const pinMoves = pinValid &&
+        input.pin !== undefined &&
+        input.refusedPinPolicy === 'move-on-confirmed-exhaustion' &&
+        (input.killswitch?.get(input.pin.accountId) === false ||
+            pinRefusal?.reason === 'exhausted' ||
+            pinRefusal?.reason === 'budget-spent');
+    const reserveFor = (row) => {
+        const perRow = typeof input.rowReservePercent === 'function'
+            ? input.rowReservePercent(row)
+            : input.rowReservePercent?.get(row.id);
+        return perRow ?? input.reservePercent ?? {};
+    };
     const scope = input.scope;
     let candidates = input.rows
         .map((row, configuredOrder) => ({ row, configuredOrder }))
@@ -246,7 +264,7 @@ export function routeSticky(input) {
                 ? undefined
                 : (admitted.get(row.id)?.projection ??
                     projectQuota(row.quota, scope)),
-            reservePercent: input.reservePercent ?? {},
+            reservePercent: reserveFor(row),
             configuredOrder,
             ...(credits === undefined ? {} : { resetCreditsApplicable: credits }),
             ...(killswitchPasses === undefined ? {} : { killswitchPasses }),
@@ -284,7 +302,7 @@ export function routeSticky(input) {
             ...(selection.quotaCheckedAt === undefined
                 ? {}
                 : { quotaCheckedAt: selection.quotaCheckedAt }),
-            pin: pinValid
+            pin: pinValid && !pinMoves
                 ? { action: 'retain' }
                 : {
                     action: 'assign',

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 import type { StoredCredential } from './schema.js';
 /** Every library operation that can fail, as named in the failure value. */
-export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'recordIdentity' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'recordIdentity' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *
@@ -16,7 +16,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-key-changed' | 'refresh-stamp-ahead' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | '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' | 'row-key-changed' | 'refresh-stamp-ahead' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | '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/index.d.ts

@@ -10,7 +10,7 @@ export type { PullHook, PullRequest } from './pull.js';
 export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
 export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export type { AddInput, AddResult, FailureHook, RowOperationOptions, } from './rows.js';
+export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, RowOperationOptions, RowToggleOptions, } from './rows.js';
 export type { PullReason } from './runtime.js';
 export type { ApiKeyCredential, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';

package/dist/store/mutate.d.ts

@@ -76,10 +76,18 @@ export declare class Transaction {
     roster(): unknown[];
     /** The first roster row with this id (the one the pool loads). */
     rosterRow(id: string): Record<string, unknown> | undefined;
+    /**
+     * Drops every roster row carrying this id. The row's per-row entry goes with
+     * it on the next `commitConfig`, which drops entries for ids no longer in
+     * the roster. Returns how many roster rows were dropped.
+     */
+    dropRosterRows(id: string): number;
     entries(): Record<string, unknown>;
     entry(id: string): Record<string, unknown> | undefined;
     setEntry(id: string, entry: Record<string, unknown>): void;
     stateAccount(id: string): Record<string, unknown> | undefined;
+    /** Drops the row's credential and runtime fields from the state file's accounts. */
+    dropStateAccount(id: string): void;
     setStateAccount(id: string, fields: Record<string, unknown>): void;
     /**
      * Writes the config: legacy `version: 1` and the legacy roster beside

package/dist/store/mutate.js

@@ -94,6 +94,17 @@ export class Transaction {
     rosterRow(id) {
         return this.roster().find((raw) => isRecord(raw) && raw.id === id);
     }
+    /**
+     * Drops every roster row carrying this id. The row's per-row entry goes with
+     * it on the next `commitConfig`, which drops entries for ids no longer in
+     * the roster. Returns how many roster rows were dropped.
+     */
+    dropRosterRows(id) {
+        const roster = this.roster();
+        const kept = roster.filter((raw) => !(isRecord(raw) && raw.id === id));
+        this.config.accounts = kept;
+        return roster.length - kept.length;
+    }
     entries() {
         if (!isRecord(this.config[POOL_KEY]))
             this.config[POOL_KEY] = {};
@@ -120,6 +131,11 @@ export class Transaction {
         const entry = Object.hasOwn(accounts, id) ? accounts[id] : undefined;
         return isRecord(entry) ? entry : undefined;
     }
+    /** Drops the row's credential and runtime fields from the state file's accounts. */
+    dropStateAccount(id) {
+        if (isRecord(this.state.accounts) && Object.hasOwn(this.state.accounts, id))
+            delete this.state.accounts[id];
+    }
     setStateAccount(id, fields) {
         if (!isRecord(this.state.accounts))
             this.state.accounts = {};

package/dist/store/pool.d.ts

@@ -5,7 +5,7 @@ import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mut
 import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
-import { type AddInput, type AddResult, type RowOperationOptions } from './rows.js';
+import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
 import { type PoolCredential, type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
 export interface OpenPoolStoreOptions {
     /** The provider every row of this pool belongs to; keys the provider-wide lock. */
@@ -80,9 +80,27 @@ export interface PoolStore {
         id: string;
         credential: StoredCredential;
     }>;
-    disable(id: string, reason: string, options?: Pick<RowOperationOptions, 'onFailure'>): Promise<{
+    /**
+     * Sets `enabled: false` and the entry's `disabledReason`. Takes the row
+     * lock, then `extraLocks`, then the store locks (the row lock and
+     * `extraLocks` since 0.2.3).
+     */
+    disable(id: string, reason: string, options?: RowToggleOptions): Promise<{
+        id: string;
+    }>;
+    /**
+     * Clears `enabled: false` and `disabledReason` (since 0.2.3); refuses with
+     * `duplicate-identity` when another enabled OAuth row holds the row's
+     * identity. Locks as `disable`.
+     */
+    enable(id: string, options?: RowToggleOptions): Promise<{
         id: string;
     }>;
+    /**
+     * Deletes the roster row, its per-row entry and its state-file credential
+     * (since 0.2.3). Locks as `disable`; `protect` can refuse the id.
+     */
+    remove(id: string, options?: RemoveOptions): Promise<RemoveResult>;
     recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
         id: string;
         disabled: string[];

package/dist/store/pool.js

@@ -3,7 +3,7 @@ import { initializePool, readPool, } from './mutate.js';
 import { PullScheduler } from './pull.js';
 import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
-import { addRow, disableRow, recordRowIdentity, replaceRow, rotateRow, } from './rows.js';
+import { addRow, disableRow, enableRow, recordRowIdentity, removeRow, replaceRow, rotateRow, } from './rows.js';
 import { POOL_SCHEMA_VERSION, } from './schema.js';
 /**
  * Process-wide memory per config file: ids whose per-row entry a library
@@ -92,6 +92,8 @@ export function openPoolStore(options) {
         replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
         rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),
         disable: (id, reason, callOptions) => disableRow(rt, id, reason, callOptions),
+        enable: (id, callOptions) => enableRow(rt, id, callOptions),
+        remove: (id, callOptions) => removeRow(rt, id, callOptions),
         recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
         refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
         recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),

package/dist/store/rows.d.ts

@@ -2,14 +2,61 @@ import type { PoolOperationError } from './errors.js';
 import { type Transaction } from './mutate.js';
 import type { PoolLockSpec } from './refresh-lock.js';
 import { type StoreRuntime } from './runtime.js';
-import { type PoolCredential, type StoredCredential } from './schema.js';
+import { type PoolCredential, type PoolRow, type StoredCredential } from './schema.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. */
     onFailure?: FailureHook;
     /** The provider-wide lock, when an operation may change identity keying. */
     providerLock?: PoolLockSpec;
+    /**
+     * Further locks taken after the row lock and the provider-wide lock, in
+     * this order, before the store locks: the same place `refresh` takes its
+     * extra locks, so a caller holding legacy locks around a row write and a
+     * refresh of that row acquire them in one order and cannot deadlock.
+     */
+    extraLocks?: readonly PoolLockSpec[];
 }
+/**
+ * Options of `disable`, `enable` and `remove`. The provider-wide lock guards
+ * changes to the recorded identity a row lock is named by; none of these
+ * three records an identity, so none takes it. The extra locks are taken
+ * where every other row write takes them, after the row lock and before the
+ * store locks.
+ */
+export type RowToggleOptions = Pick<RowOperationOptions, 'onFailure' | 'extraLocks'>;
+/** What a `remove` protect predicate is shown, read under every lock. */
+export interface RemoveView {
+    /**
+     * The row as loaded; undefined when the roster no longer holds the id and
+     * only its state-file entry is left (a removal interrupted between writes).
+     */
+    row: PoolRow | undefined;
+    /** The config file as read under the store locks. */
+    config: Readonly<Record<string, unknown>>;
+    /** The state file as read under the store locks. */
+    state: Readonly<Record<string, unknown>>;
+}
+export interface RemoveOptions extends RowToggleOptions {
+    /**
+     * Awaited under every lock before anything is written; a reason refuses
+     * the removal (kind `row-protected`) with both files unchanged. The store
+     * keeps no record of a plugin's in-flight work, so this is where a plugin
+     * refuses an id it reserves or one its own pending-operation record (kept
+     * in the config or state file) still names: reading that record from the
+     * locked files here cannot race a writer that holds the store locks.
+     */
+    protect?: (id: string, view: RemoveView) => string | undefined | Promise<string | undefined>;
+}
+export type RemoveResult = {
+    id: string;
+    /**
+     * `removed`: the roster row was dropped (and its state entry, if any).
+     * `completed`: only a state-file entry was left, by a removal interrupted
+     * between its config and state writes, and it is now dropped.
+     */
+    outcome: 'removed' | 'completed';
+};
 export interface AddInput {
     id: string;
     credential: PoolCredential;
@@ -44,9 +91,34 @@ export declare function rotateRow(rt: StoreRuntime, id: string, credential: Pool
     id: string;
     credential: StoredCredential;
 }>;
-export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: Pick<RowOperationOptions, 'onFailure'>): Promise<{
+/**
+ * Marks a row disabled. Since 0.2.3 it takes the row lock and the caller's
+ * extra locks before the store locks, as the other row writes do, so it waits
+ * for a refresh of the row instead of landing during its provider call.
+ */
+export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: RowToggleOptions): Promise<{
+    id: string;
+}>;
+/**
+ * Clears a row's `enabled: false` and its `disabledReason` in one config
+ * write. 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.
+ */
+export declare function enableRow(rt: StoreRuntime, id: string, options?: RowToggleOptions): Promise<{
     id: string;
 }>;
+/**
+ * Deletes a row: its roster row and per-row entry (quota, epoch; the identity
+ * lives in the roster row) in one config write, then its credential and
+ * runtime fields in one state write. The config goes first, so a crash
+ * 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.
+ */
+export declare function removeRow(rt: StoreRuntime, id: string, options?: RemoveOptions): Promise<RemoveResult>;
 export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, options?: RowOperationOptions): Promise<{
     id: string;
     disabled: string[];

package/dist/store/rows.js

@@ -1,6 +1,6 @@
-import { assertNotInsideHook } from './hooks.js';
+import { assertNotInsideHook, runInsideHook } from './hooks.js';
 import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
-import { runOperation, withTransaction } from './mutate.js';
+import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
 import { readRow, refusal, rowLockSpec, unknownRow, } from './runtime.js';
 import { credentialProblem, fingerprintOf, idProblem, isRecord, rosterRowFor, rotationStamp, rowLockKey, stateFieldsFor, storedCredential, } from './schema.js';
 /** Fields of a state entry that belong to the credential it replaces. */
@@ -78,6 +78,8 @@ export async function addRow(rt, input, options = {}) {
         await locks.acquire(rowLockSpec(rt, { id, identity }));
         if (credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'add', rowId: id }, async (tx) => {
             const rows = tx.rows();
             const fingerprint = fingerprintOf(credential);
@@ -150,6 +152,8 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
         await locks.acquire(rowLockSpec(rt, seen));
         if (credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'replace', rowId: id }, async (tx) => {
             const row = requireUsableRow('replace', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
@@ -197,6 +201,8 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
         await locks.acquire(rowLockSpec(rt, seen));
         if (input.identity !== undefined && credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'rotate', rowId: id }, async (tx) => {
             const row = requireUsableRow('rotate', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
@@ -220,15 +226,134 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
         });
     });
 }
+/**
+ * Marks a row disabled. Since 0.2.3 it takes the row lock and the caller's
+ * extra locks before the store locks, as the other row writes do, so it waits
+ * for a refresh of the row instead of landing during its provider call.
+ */
 export async function disableRow(rt, id, reason, options = {}) {
     assertNotInsideHook('disable');
-    return runOperation(rt.ctx, 'disable', id, options.onFailure, async (locks, progress) => withTransaction(rt.ctx, locks, progress, { operation: 'disable', rowId: id }, async (tx) => {
-        if (!tx.rosterRow(id))
-            throw unknownRow('disable', id);
-        disableIn(tx, id, reason);
-        await tx.commitConfig();
-        return { id };
-    }));
+    return runOperation(rt.ctx, 'disable', id, options.onFailure, async (locks, progress) => {
+        const { row: seen } = await readRow(rt, 'disable', id);
+        await locks.acquire(rowLockSpec(rt, seen));
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
+        return withTransaction(rt.ctx, locks, progress, { operation: 'disable', rowId: id }, async (tx) => {
+            const row = tx.row(id);
+            if (!row || !tx.rosterRow(id))
+                throw unknownRow('disable', id);
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw keyChanged('disable', id);
+            disableIn(tx, id, reason);
+            await tx.commitConfig();
+            return { id };
+        });
+    });
+}
+/**
+ * Clears a row's `enabled: false` and its `disabledReason` in one config
+ * write. 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.
+ */
+export async function enableRow(rt, id, options = {}) {
+    assertNotInsideHook('enable');
+    return runOperation(rt.ctx, 'enable', id, options.onFailure, async (locks, progress) => {
+        const { row: seen } = await readRow(rt, 'enable', id);
+        await locks.acquire(rowLockSpec(rt, seen));
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
+        return withTransaction(rt.ctx, locks, progress, { operation: 'enable', rowId: id }, async (tx) => {
+            const row = requireUsableRow('enable', id, tx.row(id));
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw keyChanged('enable', id);
+            if (row.enabled && row.disabledReason === undefined)
+                return { id };
+            if (row.type === 'oauth' && row.identity !== undefined) {
+                const holder = tx
+                    .rows()
+                    .find((other) => other.id !== id &&
+                    other.invalid === undefined &&
+                    other.type === 'oauth' &&
+                    other.enabled &&
+                    other.identity === row.identity);
+                if (holder)
+                    throw refusal('enable', id, 'duplicate-identity', `row ${holder.id} is enabled with the same identity as row ${id}`);
+            }
+            const raw = tx.rosterRow(id);
+            raw.enabled = true;
+            const entry = tx.entry(id);
+            if (entry && 'disabledReason' in entry) {
+                const next = { ...entry };
+                delete next.disabledReason;
+                tx.setEntry(id, next);
+            }
+            await tx.commitConfig();
+            return { id };
+        });
+    });
+}
+/**
+ * Deletes a row: its roster row and per-row entry (quota, epoch; the identity
+ * lives in the roster row) in one config write, then its credential and
+ * runtime fields in one state write. The config goes first, so a crash
+ * 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.
+ */
+export async function removeRow(rt, id, options = {}) {
+    assertNotInsideHook('remove');
+    const { ctx } = rt;
+    return runOperation(ctx, 'remove', id, options.onFailure, async (locks, progress) => {
+        // Only a non-string or empty id is refused: a roster row whose id the
+        // older readers would trim is invalid, and removing it is a repair.
+        if (typeof id !== 'string' || id.length === 0)
+            throw refusal('remove', id, 'invalid-input', 'id must be non-empty');
+        const result = await readPool(ctx);
+        if (result.status !== 'ready')
+            throw notReadyError(result, 'remove', id);
+        const seen = result.rows.find((row) => row.id === id);
+        if (!seen && !hasStateAccount(result.state, id))
+            throw unknownRow('remove', id);
+        const seenKey = rowLockKey(seen ?? { id });
+        await locks.acquire(rowLockSpec(rt, seen ?? { id }));
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
+        return withTransaction(ctx, locks, progress, { operation: 'remove', rowId: id }, async (tx) => {
+            const row = tx.row(id);
+            const orphan = hasStateAccount(tx.state, id);
+            if (!row && !orphan)
+                throw unknownRow('remove', id);
+            if (rowLockKey(row ?? { id }) !== seenKey)
+                throw keyChanged('remove', id);
+            const protect = options.protect;
+            if (protect) {
+                const view = {
+                    row,
+                    config: tx.snapshot.config,
+                    state: tx.snapshot.state,
+                };
+                const reason = await runInsideHook('remove', () => protect(id, view));
+                if (reason !== undefined)
+                    throw refusal('remove', id, 'row-protected', reason);
+            }
+            if (row) {
+                tx.dropRosterRows(id);
+                await tx.commitConfig();
+            }
+            if (orphan) {
+                tx.dropStateAccount(id);
+                await tx.commitState();
+            }
+            return { id, outcome: row ? 'removed' : 'completed' };
+        });
+    });
+}
+function hasStateAccount(state, id) {
+    const accounts = state.accounts;
+    return isRecord(accounts) && Object.hasOwn(accounts, id);
 }
 export async function recordRowIdentity(rt, id, identity, options = {}) {
     assertNotInsideHook('recordIdentity');
@@ -238,6 +363,8 @@ export async function recordRowIdentity(rt, id, identity, options = {}) {
         const { row: seen } = await readRow(rt, 'recordIdentity', id);
         await locks.acquire(rowLockSpec(rt, seen));
         await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(rt.ctx, locks, progress, { operation: 'recordIdentity', rowId: id }, async (tx) => {
             const row = requireUsableRow('recordIdentity', id, tx.row(id));
             if (rowLockKey(row) !== rowLockKey(seen))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Shared plumbing for the CortexKit auth plugins: loopback RPC, file locks and atomic writes, logger, sidebar state file, TUI preferences and TUI build.",
   "license": "MIT",
   "repository": {