@cortexkit/common-auth 0.6.0 → 0.8.0

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 { 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 = [
     'access',
@@ -258,6 +259,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,
@@ -266,7 +273,7 @@ export async function addRow(rt, input, options = {}) {
                 addedAt: ctx.now(),
             }));
             tx.setEntry(id, {
-                credentialEpoch: 1,
+                credentialEpoch,
                 needsFirstReading: credential.type === 'oauth',
             });
             let outcome = 'added';
@@ -420,72 +427,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
@@ -494,7 +583,9 @@ export async 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;
 /**
@@ -168,9 +177,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;
     /**
@@ -346,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

package/dist/store/schema.js

@@ -5,6 +5,15 @@ export const POOL_KEY = 'commonAuthPool';
 export const POOL_SCHEMA_VERSION = 1;
 /** Property of `commonAuthPool` holding the per-row entries, keyed by local id. */
 export 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 const POOL_RETIRED_EPOCHS_KEY = 'retiredEpochs';
 /** The `version` older readers of the same files expect at the top level. */
 export const LEGACY_STORE_VERSION = 1;
 /**
@@ -410,11 +419,15 @@ function credentialFor(raw, stateEntry) {
 export function rosterRowIn(config, id) {
     return rosterOf(config).find((raw) => isRecord(raw) && raw.id === id);
 }
-/** The per-row entries of a config, created (empty) when absent. */
-export function ensureEntries(config) {
+/** The pool object of a config, created (empty) when absent. */
+function ensurePool(config) {
     if (!isRecord(config[POOL_KEY]))
         config[POOL_KEY] = {};
-    const pool = config[POOL_KEY];
+    return config[POOL_KEY];
+}
+/** The per-row entries of a config, created (empty) when absent. */
+export function ensureEntries(config) {
+    const pool = ensurePool(config);
     if (!isRecord(pool[POOL_ROWS_KEY]))
         pool[POOL_ROWS_KEY] = {};
     return pool[POOL_ROWS_KEY];
@@ -433,6 +446,77 @@ export function setEntryIn(config, id, entry) {
         configurable: true,
     });
 }
+/**
+ * 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 function retiredEpochIn(config, id) {
+    const pool = config[POOL_KEY];
+    if (!isRecord(pool))
+        return undefined;
+    const retired = pool[POOL_RETIRED_EPOCHS_KEY];
+    if (!isRecord(retired) || !Object.hasOwn(retired, id))
+        return undefined;
+    const epoch = retired[id];
+    return isCredentialEpoch(epoch) ? epoch : undefined;
+}
+/**
+ * The epoch a per-row entry claims, read without validating the rest of the
+ * entry, or undefined when it names none a reader would accept.
+ */
+function entryEpochIn(config, id) {
+    const epoch = entryIn(config, id)?.credentialEpoch;
+    return isCredentialEpoch(epoch) ? epoch : 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 function nextAddEpochIn(config, id) {
+    return (Math.max(retiredEpochIn(config, id) ?? 0, entryEpochIn(config, id) ?? 0) + 1);
+}
+/**
+ * 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 function retireEpochsIn(config, dropped) {
+    const ids = [...dropped];
+    if (ids.length === 0)
+        return;
+    const pool = ensurePool(config);
+    const previous = isRecord(pool[POOL_RETIRED_EPOCHS_KEY])
+        ? pool[POOL_RETIRED_EPOCHS_KEY]
+        : {};
+    const next = {};
+    const define = (id, epoch) => Object.defineProperty(next, id, {
+        value: epoch,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    for (const [id, epoch] of Object.entries(previous))
+        if (isCredentialEpoch(epoch))
+            define(id, epoch);
+    for (const id of ids)
+        define(id, Math.max(retiredEpochIn(config, id) ?? 0, entryEpochIn(config, id) ?? 1));
+    pool[POOL_RETIRED_EPOCHS_KEY] = next;
+}
 /**
  * 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

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.8.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": {