@cortexkit/common-auth 0.6.0 → 0.7.0

package/dist/store/identity.d.ts

@@ -22,6 +22,11 @@ export declare function countUnknownIdentityRows(rows: readonly PoolRow[]): numb
  * without an entry gets one at epoch 1. Nothing is ever deleted.
  */
 export declare function disableIn(tx: RowEditor, id: string, reason: string): void;
+/**
+ * Marks a row enabled: `enabled: true` in the roster row and no
+ * `disabledReason` in its entry. A row without an entry is not given one.
+ */
+export declare function enableIn(tx: RowEditor, id: string): void;
 /**
  * Two enabled OAuth rows with one wire identity are the same account: the
  * earlier row in roster order stays enabled and every later one is disabled

package/dist/store/identity.js

@@ -24,6 +24,22 @@ export function disableIn(tx, id, reason) {
     const entry = tx.entry(id) ?? { credentialEpoch: 1, needsFirstReading: true };
     tx.setEntry(id, { ...entry, disabledReason: reason });
 }
+/**
+ * Marks a row enabled: `enabled: true` in the roster row and no
+ * `disabledReason` in its entry. A row without an entry is not given one.
+ */
+export function enableIn(tx, id) {
+    const raw = tx.rosterRow(id);
+    if (!raw)
+        return;
+    raw.enabled = true;
+    const entry = tx.entry(id);
+    if (entry && 'disabledReason' in entry) {
+        const next = { ...entry };
+        delete next.disabledReason;
+        tx.setEntry(id, next);
+    }
+}
 /**
  * Two enabled OAuth rows with one wire identity are the same account: the
  * earlier row in roster order stays enabled and every later one is disabled

package/dist/store/index.d.ts

@@ -6,12 +6,13 @@ export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity
 export type { HoldPoint, InitializeOutcome, WriteStep } from './mutate.js';
 export type { OpenPoolStoreOptions, PoolLoad, PoolStore, } from './pool.js';
 export { openPoolStore } from './pool.js';
-export type { ProviderStateMutator, UpdateProviderStateResult, } from './provider-state.js';
+export type { ProviderStateMutator, RowTransitionMutator, UpdateProviderStateResult, } from './provider-state.js';
+export { DECLINE_TRANSITION } from './provider-state.js';
 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, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
+export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, } from './rows.js';
 export type { PullReason } from './runtime.js';
 export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, ProviderStateCodec, ProviderStateDrop, ProviderStateReplacement, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';

package/dist/store/index.js

@@ -1,6 +1,7 @@
 export { PoolOperationError, PoolReentryError } from './errors.js';
 export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
 export { openPoolStore } from './pool.js';
+export { DECLINE_TRANSITION } from './provider-state.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
 export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/pool.d.ts

@@ -6,7 +6,7 @@ import { type ProviderStateMutator, type UpdateProviderStateResult } from './pro
 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 CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
+import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult } from './rows.js';
 import { type PoolCredential, type PoolRow, type ProviderStateCodec, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
 import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
 export interface OpenPoolStoreOptions {
@@ -119,19 +119,18 @@ export interface PoolStore {
     /**
      * 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).
+     * `extraLocks` since 0.2.3). Since 0.7.0 it may be fenced on the
+     * credential the caller's evidence is about (`attribution`) and carry a
+     * provider-state change that lands with it (`providerState`); see
+     * `RowTransitionOptions`.
      */
-    disable(id: string, reason: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    disable(id: string, reason: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * 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`.
+     * identity. Locks as `disable`, and takes the same options since 0.7.0.
      */
-    enable(id: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    enable(id: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * 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.

package/dist/store/provider-state.d.ts

@@ -1,5 +1,6 @@
 import type { Attribution } from './attribution.js';
 import type { PoolOperation } from './errors.js';
+import { type Transaction } from './mutate.js';
 import type { RowToggleOptions } from './rows.js';
 import { type StoreRuntime } from './runtime.js';
 import { type PoolRow, type ProviderStateCodec } from './schema.js';
@@ -84,3 +85,47 @@ export type UpdateProviderStateResult = {
  * `replace` stamps such a row.
  */
 export declare function updateProviderStateRow(rt: StoreRuntime, id: string, fence: Attribution, mutator: ProviderStateMutator, options?: RowToggleOptions): Promise<UpdateProviderStateResult>;
+/**
+ * Returned by the provider-state mutator of an attributed `disable` or
+ * `enable` to decline the whole transition: nothing is written, neither the
+ * provider state nor the row's enabled flag, and the call resolves with
+ * `declined: true`. A mutator declines when the state it is shown is newer
+ * than what its caller saw, such as an eligibility recorded after the
+ * request whose refusal is being acted on. It is a value of its own because
+ * `undefined` already means "clear the provider state". `Symbol.for` keeps it
+ * equal across two copies of this module loaded in one process.
+ */
+export declare const DECLINE_TRANSITION: unique symbol;
+/**
+ * The provider-state mutator of an attributed `disable` or `enable`: as
+ * `ProviderStateMutator`, and it may also return `DECLINE_TRANSITION`.
+ */
+export type RowTransitionMutator = (current: unknown | undefined, row: PoolRow) => unknown | typeof DECLINE_TRANSITION | Promise<unknown | typeof DECLINE_TRANSITION>;
+/**
+ * What a provider-state mutator asks of a row, worked out under the locks
+ * before anything is written. `changed` carries the row's whole next
+ * state-file account entry (the value, and the stamp rebound to it when its
+ * credential-bound part moved); `value` is the next value, absent when it is
+ * cleared.
+ */
+export type ProviderStatePlan = {
+    kind: 'declined';
+} | {
+    kind: 'unchanged';
+    value?: unknown;
+} | {
+    kind: 'changed';
+    value?: unknown;
+    account: Record<string, unknown>;
+};
+/**
+ * Runs a provider-state mutator for a row loaded under every lock and
+ * already checked by the caller (present, valid, inside its attribution
+ * fence), and plans the write. Refuses (`no-credential`) a row holding no
+ * credential, and (`unbound-credential`) one whose credential carries no
+ * stamp of this store at the row's epoch and identity: no stamp could bind
+ * the value, so no reader would ever show it. `DECLINE_TRANSITION` is
+ * honoured only when `declinable` is set; elsewhere it is not JSON and is
+ * refused as such.
+ */
+export declare function planProviderStateIn(tx: Transaction, codec: ProviderStateCodec, operation: PoolOperation, row: PoolRow, mutator: ProviderStateMutator | RowTransitionMutator, declinable?: boolean): Promise<ProviderStatePlan>;

package/dist/store/provider-state.js

@@ -132,55 +132,92 @@ export async function updateProviderStateRow(rt, id, fence, mutator, options = {
             const epoch = row.credentialEpoch ?? 1;
             if (epoch !== captured || row.identity !== fence.identity)
                 throw refusal(operation, id, 'attribution', `the provider state for ${id} was read for a credential or account the row no longer holds`, true);
-            const account = tx.stateAccount(id);
-            const rawStamp = account?.[CREDENTIAL_STAMP_KEY];
-            const stamp = parseStamp(rawStamp);
-            if (!isRecord(rawStamp) ||
-                !stamp?.binding ||
-                stamp.digest !== credentialDigest(row.credential) ||
-                stamp.credentialEpoch !== epoch ||
-                stamp.binding.identity !== row.identity)
-                throw refusal(operation, id, 'unbound-credential', `row ${id}'s credential carries no stamp of this store to bind a provider state to (stamp ${row.stamp}); rotate or replace it first`);
-            const current = row.providerState === undefined
-                ? undefined
-                : structuredClone(row.providerState);
-            const returned = await runInsideHook(operation, () => mutator(current, row));
-            const next = returned === undefined
-                ? undefined
-                : acceptProviderState(codec, operation, id, returned, 'the provider state the mutator returned');
-            const held = account !== undefined && Object.hasOwn(account, PROVIDER_STATE_KEY);
-            if (next === undefined
-                ? !held
-                : row.providerState !== undefined &&
-                    JSON.stringify(row.providerState) === JSON.stringify(next))
+            const plan = await planProviderStateIn(tx, codec, operation, row, mutator);
+            if (plan.kind !== 'changed')
                 return {
                     id,
                     outcome: 'unchanged',
-                    ...(next !== undefined ? { providerState: next } : {}),
+                    ...(plan.kind === 'unchanged' && plan.value !== undefined
+                        ? { providerState: plan.value }
+                        : {}),
                 };
-            const nextAccount = { ...account };
-            if (next === undefined) {
-                delete nextAccount[PROVIDER_STATE_KEY];
-                const nextStamp = { ...rawStamp };
-                delete nextStamp.providerState;
-                nextAccount[CREDENTIAL_STAMP_KEY] = nextStamp;
-            }
-            else {
-                nextAccount[PROVIDER_STATE_KEY] = next;
-                const digest = providerStateDigest(codec, next);
-                // A change confined to the part the codec does not bind to the
-                // credential leaves the stamp exactly as it was.
-                if (stamp.providerState !== digest)
-                    nextAccount[CREDENTIAL_STAMP_KEY] = {
-                        ...rawStamp,
-                        providerState: digest,
-                    };
-            }
-            tx.setStateAccount(id, nextAccount);
+            tx.setStateAccount(id, plan.account);
             await tx.commitState();
-            return next === undefined
+            return plan.value === undefined
                 ? { id, outcome: 'cleared' }
-                : { id, outcome: 'updated', providerState: next };
+                : { id, outcome: 'updated', providerState: plan.value };
         });
     });
 }
+/**
+ * Returned by the provider-state mutator of an attributed `disable` or
+ * `enable` to decline the whole transition: nothing is written, neither the
+ * provider state nor the row's enabled flag, and the call resolves with
+ * `declined: true`. A mutator declines when the state it is shown is newer
+ * than what its caller saw, such as an eligibility recorded after the
+ * request whose refusal is being acted on. It is a value of its own because
+ * `undefined` already means "clear the provider state". `Symbol.for` keeps it
+ * equal across two copies of this module loaded in one process.
+ */
+export const DECLINE_TRANSITION = Symbol.for('@cortexkit/common-auth/store/decline-transition');
+/**
+ * Runs a provider-state mutator for a row loaded under every lock and
+ * already checked by the caller (present, valid, inside its attribution
+ * fence), and plans the write. Refuses (`no-credential`) a row holding no
+ * credential, and (`unbound-credential`) one whose credential carries no
+ * stamp of this store at the row's epoch and identity: no stamp could bind
+ * the value, so no reader would ever show it. `DECLINE_TRANSITION` is
+ * honoured only when `declinable` is set; elsewhere it is not JSON and is
+ * refused as such.
+ */
+export async function planProviderStateIn(tx, codec, operation, row, mutator, declinable = false) {
+    const id = row.id;
+    const credential = row.credential;
+    if (!credential)
+        throw refusal(operation, id, 'no-credential', `row ${id} holds no credential`);
+    const epoch = row.credentialEpoch ?? 1;
+    const account = tx.stateAccount(id);
+    const rawStamp = account?.[CREDENTIAL_STAMP_KEY];
+    const stamp = parseStamp(rawStamp);
+    if (!isRecord(rawStamp) ||
+        !stamp?.binding ||
+        stamp.digest !== credentialDigest(credential) ||
+        stamp.credentialEpoch !== epoch ||
+        stamp.binding.identity !== row.identity)
+        throw refusal(operation, id, 'unbound-credential', `row ${id}'s credential carries no stamp of this store to bind a provider state to (stamp ${row.stamp}); rotate or replace it first`);
+    const current = row.providerState === undefined
+        ? undefined
+        : structuredClone(row.providerState);
+    const returned = await runInsideHook(operation, () => mutator(current, row));
+    if (declinable && returned === DECLINE_TRANSITION)
+        return { kind: 'declined' };
+    const next = returned === undefined
+        ? undefined
+        : acceptProviderState(codec, operation, id, returned, 'the provider state the mutator returned');
+    const held = account !== undefined && Object.hasOwn(account, PROVIDER_STATE_KEY);
+    if (next === undefined
+        ? !held
+        : row.providerState !== undefined &&
+            JSON.stringify(row.providerState) === JSON.stringify(next))
+        return { kind: 'unchanged', ...(next !== undefined ? { value: next } : {}) };
+    const nextAccount = { ...account };
+    if (next === undefined) {
+        delete nextAccount[PROVIDER_STATE_KEY];
+        const nextStamp = { ...rawStamp };
+        delete nextStamp.providerState;
+        nextAccount[CREDENTIAL_STAMP_KEY] = nextStamp;
+    }
+    else {
+        nextAccount[PROVIDER_STATE_KEY] = next;
+        const digest = providerStateDigest(codec, next);
+        // A change confined to the part the codec does not bind to the
+        // credential leaves the stamp exactly as it was.
+        if (stamp.providerState !== digest)
+            nextAccount[CREDENTIAL_STAMP_KEY] = { ...rawStamp, providerState: digest };
+    }
+    return {
+        kind: 'changed',
+        ...(next !== undefined ? { value: next } : {}),
+        account: nextAccount,
+    };
+}

package/dist/store/rows.d.ts

@@ -1,7 +1,7 @@
 import type { Attribution } from './attribution.js';
 import { PoolOperationError } from './errors.js';
 import { type Transaction } from './mutate.js';
-import { type ProviderStateWrite } from './provider-state.js';
+import { type ProviderStateWrite, type RowTransitionMutator, type UpdateProviderStateResult } from './provider-state.js';
 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';
@@ -134,23 +134,57 @@ export declare function rotateRow(rt: StoreRuntime, id: string, credential: Rota
     credential: StoredCredential;
 }>;
 /**
- * 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.
+ * Options of `disable` and `enable`. A call that passes neither
+ * `attribution` nor `providerState` behaves exactly as it did before 0.7.0.
  */
-export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: RowToggleOptions): Promise<{
+export interface RowTransitionOptions extends RowToggleOptions {
+    /**
+     * The credential epoch and recorded identity the caller's evidence for the
+     * transition was obtained under (as `recordQuota`'s attribution: an
+     * identity left out means the row had none). The call is refused
+     * (`attribution`, retryable, nothing written) once the row holds another
+     * epoch or identity, so a provider's late answer about a replaced
+     * credential never disables, or switches back on, the row now holding its
+     * successor.
+     */
+    attribution?: Attribution;
+    /**
+     * A provider-state change made in the same transaction as the transition,
+     * under the rules of `updateProviderState` (codec validation, the stamp
+     * rebound to the value, `unbound-credential` for a row no stamp of this
+     * store can bind it to); it requires `attribution`. The value and the
+     * enabled flag land together: no reader, and no crash at any write point,
+     * shows one without the other. Returning `DECLINE_TRANSITION` declines the
+     * whole call and writes nothing.
+     */
+    providerState?: RowTransitionMutator;
+}
+export interface RowTransitionResult {
     id: string;
-}>;
+    /** The provider-state mutator declined: nothing was written. */
+    declined?: true;
+    /**
+     * Set when a provider-state mutator ran and did not decline: what it did
+     * to the value, as `updateProviderState` reports it.
+     */
+    providerStateOutcome?: UpdateProviderStateResult['outcome'];
+    /** The provider state the row now holds, when a mutator ran and left one. */
+    providerState?: unknown;
+}
+/**
+ * Marks a row disabled with a reason. See `RowTransitionOptions` for the
+ * attributed form, which may change the provider state with it.
+ */
+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
  * 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.
+ * enabled writes nothing. See `RowTransitionOptions` for the attributed
+ * form, which may change the provider state with it.
  */
-export declare function enableRow(rt: StoreRuntime, id: string, options?: RowToggleOptions): Promise<{
-    id: string;
-}>;
+export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
 /**
  * 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

package/dist/store/rows.js

@@ -1,11 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
-import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
+import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enableIn, recordIdentityIn, } from './identity.js';
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
-import { acceptProviderState, mergedProviderState, providerStateCoverage, replacementProviderState, } from './provider-state.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 { bindReplacement } from './torn.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 = [
     'access',
@@ -420,72 +421,154 @@ 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.
+ * `disable` and `enable` in one place. Takes the row lock, then the extra
+ * locks, then the store locks, as every row write does, so it waits for a
+ * refresh of the row instead of landing during its provider call.
+ *
+ * With a provider-state mutator that changes the value, the transition is
+ * written as a replace is: the state file first, carrying the value and, in
+ * the stamp, the transition itself; then the config, flipping the row and
+ * recording the transition's mark (see `torn.ts`). A stop between the two
+ * leaves a row every reader shows transitioned beside its new value. When
+ * the config already says what the transition would write (an `enable` of
+ * an enabled row), the value alone is written, in one state write.
  */
-export async function disableRow(rt, id, reason, options = {}) {
-    assertNotInsideHook('disable');
-    return runOperation(rt.ctx, 'disable', id, options.onFailure, async (locks, progress) => {
-        const { row: seen } = await readRow(rt, 'disable', id);
+async function transitionRow(rt, operation, id, flag, options) {
+    assertNotInsideHook(operation);
+    const { ctx } = rt;
+    const codec = ctx.providerState;
+    const fence = options.attribution;
+    const mutator = options.providerState;
+    return runOperation(ctx, operation, id, options.onFailure, async (locks, progress) => {
+        if (fence !== undefined &&
+            !isCredentialEpoch(isRecord(fence) ? fence.credentialEpoch : undefined))
+            throw refusal(operation, id, 'invalid-input', 'the attribution must name a credential epoch that is a positive safe integer');
+        if (mutator !== undefined) {
+            if (typeof mutator !== 'function')
+                throw refusal(operation, id, 'invalid-input', 'the provider-state mutator must be a function');
+            // A provider-state value belongs to one credential, so a change to
+            // it must say which credential it was decided for.
+            if (fence === undefined)
+                throw refusal(operation, id, 'invalid-input', 'a provider-state change needs the attribution of the credential it is for');
+            if (!codec)
+                throw refusal(operation, id, 'invalid-input', 'the store was opened without a provider-state codec');
+        }
+        const { row: seen } = await readRow(rt, operation, 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);
+        return withTransaction(ctx, locks, progress, { operation, rowId: id }, async (tx) => {
+            const loaded = tx.row(id);
+            const row = flag.enabled
+                ? requireUsableRow('enable', id, loaded)
+                : loaded;
             if (!row || !tx.rosterRow(id))
-                throw unknownRow('disable', id);
+                throw unknownRow(operation, id);
             if (rowLockKey(row) !== rowLockKey(seen))
-                throw keyChanged('disable', id);
-            disableIn(tx, id, reason);
+                throw keyChanged(operation, id);
+            if (fence !== undefined) {
+                // An invalid entry has no epoch to compare the fence with.
+                if (row.invalid)
+                    throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
+                if ((row.credentialEpoch ?? 1) !== fence.credentialEpoch ||
+                    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);
+            }
+            // 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;
+            if (flag.enabled && writesConfig && row.type === 'oauth') {
+                const holder = row.identity === undefined
+                    ? undefined
+                    : 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}`);
+            }
+            if (mutator === undefined || codec === undefined) {
+                if (!writesConfig)
+                    return { id };
+                if (flag.enabled)
+                    enableIn(tx, id);
+                else
+                    disableIn(tx, id, flag.reason);
+                await tx.commitConfig();
+                return { id };
+            }
+            if (!row.credential)
+                throw refusal(operation, id, 'no-credential', `row ${id} holds no credential`);
+            // A strict store refuses here, but not for an attribution alone:
+            // disabling or enabling a row whose credential the store cannot
+            // prove is harmless (an unbound row is never a candidate), while
+            // writing a provider state would vouch for that credential.
+            requireBound(operation, row);
+            const plan = await planProviderStateIn(tx, codec, operation, row, mutator, true);
+            if (plan.kind === 'declined')
+                return { id, declined: true };
+            const result = {
+                id,
+                providerStateOutcome: plan.kind === 'unchanged'
+                    ? 'unchanged'
+                    : plan.value === undefined
+                        ? 'cleared'
+                        : 'updated',
+                ...(plan.value !== undefined ? { providerState: plan.value } : {}),
+            };
+            if (plan.kind === 'unchanged') {
+                if (writesConfig) {
+                    if (flag.enabled)
+                        enableIn(tx, id);
+                    else
+                        disableIn(tx, id, flag.reason);
+                    await tx.commitConfig();
+                }
+                return result;
+            }
+            if (!writesConfig) {
+                tx.setStateAccount(id, plan.account);
+                await tx.commitState();
+                return result;
+            }
+            const transition = flag.enabled
+                ? { mark: randomUUID(), enabled: true }
+                : { mark: randomUUID(), enabled: false, reason: flag.reason };
+            const stamp = plan.account[CREDENTIAL_STAMP_KEY];
+            tx.setStateAccount(id, {
+                ...plan.account,
+                [CREDENTIAL_STAMP_KEY]: {
+                    ...stamp,
+                    [TRANSITION_STAMP_KEY]: transition,
+                },
+            });
+            await tx.commitState();
+            applyTransition(tx, id, transition);
             await tx.commitConfig();
-            return { id };
+            return result;
         });
     });
 }
+/**
+ * Marks a row disabled with a reason. See `RowTransitionOptions` for the
+ * attributed form, which may change the provider state with it.
+ */
+export function disableRow(rt, id, reason, options = {}) {
+    return transitionRow(rt, 'disable', id, { enabled: false, 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
  * 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.
+ * enabled writes nothing. See `RowTransitionOptions` for the attributed
+ * form, which may change the provider state with it.
  */
-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 };
-        });
-    });
+export function enableRow(rt, id, options = {}) {
+    return transitionRow(rt, 'enable', id, { enabled: true }, options);
 }
 /**
  * Deletes a row: its roster row and per-row entry (quota, epoch; the identity

package/dist/store/schema.d.ts

@@ -168,9 +168,11 @@ export interface PoolRow {
      * it belongs to, and the config still holds the replaced row. Also set when
      * a write that gives a row its first identity (`recordIdentity`, or a
      * `rotate` or refresh that learns one) stopped after stamping the identity
-     * and before recording it in the config. The row is shown as the write
-     * leaves it once completed, is never a candidate, and the next store write
-     * on it writes the config to match.
+     * and before recording it in the config, and when an attributed `disable`
+     * or `enable` that changed the provider state stopped after its state
+     * write and before flipping the row in the config. The row is shown as the
+     * write leaves it once completed, is never a candidate, and the next store
+     * write on it writes the config to match.
      */
     torn?: true;
     /**

package/dist/store/torn.d.ts

@@ -1,5 +1,31 @@
 import { type RowEditor } from './identity.js';
 import { type CredentialBinding, type CredentialStamp, type PoolRow, type ProviderStateCodec, type QuotaCodec } from './schema.js';
+/** Key, inside a credential stamp, of an attributed enable or disable. */
+export declare const TRANSITION_STAMP_KEY = "transition";
+/**
+ * Key, inside a per-row config entry, of the mark of the last transition the
+ * config carries out. Older readers ignore it.
+ */
+export declare const TRANSITION_MARK_KEY = "transitionMark";
+/**
+ * An attributed enable or disable as its state write records it: `mark` is
+ * unique to that write, `enabled` is the flag it sets, and `reason` the
+ * disabled reason (a disable's only).
+ */
+export interface StampedTransition {
+    mark: string;
+    enabled: boolean;
+    reason?: string;
+}
+/**
+ * Carries a transition out in a config being edited: the row's enabled flag
+ * and reason as the transition says, and its mark recorded in the entry (a
+ * row without an entry gets one at epoch 1, as `disableIn` gives it). An
+ * enable then applies the duplicate-identity rule, as every write that
+ * enables an OAuth row with a known identity does: the earlier row in roster
+ * order keeps the identity.
+ */
+export declare function applyTransition(editor: RowEditor, id: string, transition: StampedTransition): void;
 /** How a row left between the two writes of an operation is completed. */
 export type TornCompletion = {
     kind: 'replace';
@@ -9,6 +35,9 @@ export type TornCompletion = {
 } | {
     kind: 'identity';
     identity: string;
+} | {
+    kind: 'transition';
+    transition: StampedTransition;
 };
 /** Rows left between the two writes of an operation, by row id. */
 export declare function tornStamps(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {

package/dist/store/torn.js

@@ -1,4 +1,4 @@
-import { disableIdentityDuplicates, recordIdentityIn, } from './identity.js';
+import { disableIdentityDuplicates, disableIn, enableIn, recordIdentityIn, } from './identity.js';
 import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, dispatchDigest, entryIn, isRecord, parseStamp, rosterRowIn, setEntryIn, } from './schema.js';
 /*
  * A replace changes both files: the state file gets the new credential and
@@ -46,7 +46,69 @@ import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, dispatchDigest, e
  * exactly (digest and dispatch digest), that names an identity the config
  * does not record; that is completed forward the same way, by recording the
  * identity.
+ *
+ * An attributed `disable` or `enable` that also changes the provider state
+ * follows the same order. Its state write carries the new value and, in the
+ * stamp, the transition (`transition: {mark, enabled, reason?}`, see
+ * `StampedTransition`); its config write then flips the row and records the
+ * transition's mark in the row's entry (`transitionMark`). A stamp bound to
+ * the row (this credential, epoch and identity, the binding that also shows
+ * the provider state beside it) whose transition mark the entry does not
+ * record is such a write stopped between its two writes, and is completed
+ * forward the same way: readers are shown the row disabled or enabled as the
+ * transition says, beside the value written with it. Once the config records
+ * the mark the transition says nothing more, so a later `enable` or
+ * `disable` of the row is never undone by it; a credential write drops it
+ * with the rest of the old stamp.
+ */
+/** Key, inside a credential stamp, of an attributed enable or disable. */
+export const TRANSITION_STAMP_KEY = 'transition';
+/**
+ * Key, inside a per-row config entry, of the mark of the last transition the
+ * config carries out. Older readers ignore it.
  */
+export const TRANSITION_MARK_KEY = 'transitionMark';
+/** The well-formed transition in a raw stamp, or undefined. */
+function stampedTransition(rawStamp) {
+    if (!isRecord(rawStamp))
+        return undefined;
+    const raw = rawStamp[TRANSITION_STAMP_KEY];
+    if (!isRecord(raw))
+        return undefined;
+    if (typeof raw.mark !== 'string' || raw.mark.length === 0)
+        return undefined;
+    if (raw.enabled === true)
+        return { mark: raw.mark, enabled: true };
+    if (raw.enabled === false && typeof raw.reason === 'string')
+        return { mark: raw.mark, enabled: false, reason: raw.reason };
+    return undefined;
+}
+/**
+ * Carries a transition out in a config being edited: the row's enabled flag
+ * and reason as the transition says, and its mark recorded in the entry (a
+ * row without an entry gets one at epoch 1, as `disableIn` gives it). An
+ * enable then applies the duplicate-identity rule, as every write that
+ * enables an OAuth row with a known identity does: the earlier row in roster
+ * order keeps the identity.
+ */
+export function applyTransition(editor, id, transition) {
+    if (transition.enabled)
+        enableIn(editor, id);
+    else
+        disableIn(editor, id, transition.reason ?? '');
+    if (!editor.rosterRow(id))
+        return;
+    const entry = editor.entry(id) ?? {
+        credentialEpoch: 1,
+        needsFirstReading: true,
+    };
+    editor.setEntry(id, { ...entry, [TRANSITION_MARK_KEY]: transition.mark });
+    if (!transition.enabled)
+        return;
+    const row = editor.rows().find((candidate) => candidate.id === id);
+    if (row?.type === 'oauth' && row.identity !== undefined)
+        disableIdentityDuplicates(editor, row.identity);
+}
 /**
  * The credential a torn replace leaves once its config write lands: the
  * credential loaded beside the stamp, with the endpoint the stamp's binding
@@ -122,6 +184,13 @@ export function tornStamps(config, state, codec, options = {}) {
             row.identity === undefined) {
             torn.set(row.id, { kind: 'identity', identity: stamp.binding.identity });
         }
+        else if (stamp.credentialEpoch === epoch &&
+            stamp.binding.identity === row.identity) {
+            const transition = stampedTransition(account[CREDENTIAL_STAMP_KEY]);
+            if (transition &&
+                entryIn(config, row.id)?.[TRANSITION_MARK_KEY] !== transition.mark)
+                torn.set(row.id, { kind: 'transition', transition });
+        }
     }
     return torn;
 }
@@ -175,6 +244,8 @@ export function completeTornRows(config, state, codec, options = {}) {
     for (const [id, completion] of completions) {
         if (completion.kind === 'identity')
             recordIdentityIn(editor, id, completion.identity);
+        else if (completion.kind === 'transition')
+            applyTransition(editor, id, completion.transition);
         else if (completion.stamp.binding.identity !== undefined)
             disableIdentityDuplicates(editor, completion.stamp.binding.identity);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {