@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/store/pool.d.ts

@@ -0,0 +1,196 @@
+import { type Attribution } from './attribution.js';
+import type { PoolOperationError } from './errors.js';
+import type { PoolLogger } from './hooks.js';
+import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mutate.js';
+import { type ProviderStateMutator, type UpdateProviderStateResult } from './provider-state.js';
+import { type PublicationReceipt, type PublishOptions, type PublishPlan, type PublishResult } from './publication.js';
+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 AddOptions, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult, type RowWriteOptions } 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 {
+    /** The provider every row of this pool belongs to; keys the provider-wide lock. */
+    provider: string;
+    configPath: string;
+    statePath: string;
+    quota: QuotaCodec;
+    /**
+     * The codec of the provider state kept beside each row's credential (see
+     * `ProviderStateCodec`). Without it no row shows a provider state, and
+     * every write that would set one refuses (`invalid-input`); writes that
+     * leave it alone keep the value on disk as it is, and `replace` clears it.
+     */
+    providerState?: ProviderStateCodec;
+    /**
+     * Refuse every credential this store did not stamp (default false, which
+     * loads unstamped and mis-stamped credentials as older writers left them).
+     * When true, a row whose `stamp` is not `bound` loads `unbound` and is no
+     * candidate, and every operation that would use or keep its credential or
+     * what was observed about it (`refresh`, quota pulls, `recordQuota`,
+     * `recordIdentity`, `rotate`, and an `add` of the same secret or onto the
+     * same credential-less row) refuses with `unbound-credential` before any
+     * provider call or write, checked again under the locks and at commit.
+     * Nothing makes such a row bound except `replace`, which starts a new
+     * credential epoch and drops what was observed about the old one.
+     * An interrupted add's state-only orphan is recovered only when its stamp
+     * binds the stored and incoming material, including a supplied identity and
+     * an API key's endpoint/header. Otherwise add refuses `unbound-credential`
+     * without writing; `remove(id)` explicitly discards the orphan.
+     */
+    requireCredentialStamps?: boolean;
+    /** Require an exact secret fingerprint for every roster-publication removal. */
+    requireRemovedFingerprint?: boolean;
+    /** Injected clock for leases, refresh stamps and `addedAt`. */
+    now?: () => number;
+    /**
+     * Ordered store-lock list held across every read-modify-write. Defaults to
+     * the older writers' `save` lock at the config path, then at the state path.
+     */
+    storeLocks?: readonly PoolLockSpec[];
+    /** Defaults for every lock the store takes (see `POOL_LOCK_DEFAULTS`). */
+    lockOptions?: Partial<PoolLockOptions>;
+    /** Overrides for the row locks only. */
+    rowLockOptions?: Partial<PoolLockOptions>;
+    /** The provider-wide lock; defaults to `provider-<provider>` beside the state file. */
+    providerLock?: PoolLockSpec;
+    /** Quota pull hook, fired without being awaited. */
+    pull?: PullHook;
+    /** Receives every pull failure, since no caller awaits a pull. */
+    onPullFailure?: (rowId: string, error: PoolOperationError) => void | Promise<void>;
+    logger?: PoolLogger;
+    /** Named write steps, awaited; a test seam for crash and ownership rows. */
+    onStep?: StoreContext['onStep'];
+    /** Awaitable hold points on the refresh and pull paths; a test seam. */
+    hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
+    onLockEvent?: LockEnvironment['onLockEvent'];
+    onLockStep?: LockEnvironment['onLockStep'];
+}
+export type PoolLoad = {
+    status: 'ready';
+    schemaVersion: number;
+    rows: PoolRow[];
+} | {
+    status: 'pending-migration';
+    roster: unknown[];
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+    kind?: 'snapshot-contended';
+    retryable?: true;
+};
+export interface PoolStore {
+    /** Reads the pool and fires first-reading pulls; never writes a file itself. */
+    load(): Promise<PoolLoad>;
+    /** Reads the pool without firing anything. */
+    read(): Promise<PoolLoad>;
+    /**
+     * Turns a pending-migration config into an empty pool (the pool key with no
+     * row entries) in one locked config write, dropping the named top-level
+     * keys and keeping the rest. The start of a plugin's migration; a ready
+     * pool is left alone. Failures carry operation `initialize`.
+     */
+    initialize(input?: {
+        dropKeys?: readonly string[];
+    }): Promise<{
+        status: InitializeOutcome;
+    }>;
+    /**
+     * Adds a row, or completes or rotates the row already holding the id or
+     * the secret. A new row starts at credential epoch 1; since 0.8.0 one
+     * whose id the pool held before starts one past the highest epoch that id
+     * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
+     * refuses (`id-removed`) before writing.
+     */
+    add(input: AddInput, options?: AddOptions): Promise<AddResult>;
+    publishRoster(plan: PublishPlan, options?: PublishOptions): Promise<PublishResult>;
+    publication(operationId: string): Promise<PublicationReceipt | undefined>;
+    /**
+     * Gives a row a new credential and a new credential epoch. Since 0.6.0 the
+     * row's provider state is whatever `ProviderStateCodec.onReplace` returns;
+     * without that hook it is `input.providerState`, else cleared.
+     * Optional `attribution` fences the write on the prior credential under the
+     * locks, before any write or replacement hook; see `RowWriteOptions`.
+     */
+    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
+        id: string;
+        credential: StoredCredential;
+        credentialEpoch: number;
+    }>;
+    /**
+     * Refreshes the secret a row holds without changing its account or
+     * endpoint. Since 0.4.1 an API key may leave out `baseURL` and `authHeader`
+     * to keep the row's, and one that gives another is refused
+     * (`endpoint-mismatch`) before writing: that is a `replace`.
+     * Takes the same optional attribution fence as `replace` (`RowWriteOptions`).
+     */
+    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
+        id: string;
+        credential: StoredCredential;
+    }>;
+    /**
+     * Changes a row's provider state without touching its credential (since
+     * 0.6.0), under the row lock, `extraLocks` and the store locks. Refuses
+     * (`attribution`) once the row has moved off the credential epoch or
+     * identity in `fence`, and (`unknown-row`) once it is removed.
+     */
+    updateProviderState(id: string, fence: Attribution, mutator: ProviderStateMutator, options?: RowToggleOptions): Promise<UpdateProviderStateResult>;
+    /**
+     * 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). 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?: 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`, and takes the same options since 0.7.0.
+     */
+    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.
+     */
+    remove(id: string, options?: RemoveOptions): Promise<RemoveResult>;
+    /**
+     * Sets the roster order (since 0.2.4) in one config write. `ids` must name
+     * every roster id exactly once; anything else refuses with `invalid-order`
+     * and writes nothing. Takes `extraLocks`, then the store locks; no row or
+     * provider-wide lock. Roster rows and their entries are left unchanged.
+     */
+    reorder(ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
+    /**
+     * The plugin's settings (since 0.2.6): every top-level key of the config
+     * file except the pool-owned ones (`POOL_OWNED_KEYS`). Never writes.
+     */
+    readSettings(): Promise<SettingsRead>;
+    /**
+     * One locked write of the plugin's settings (since 0.2.6) beside the pool,
+     * in the config file. Refuses a result that sets a pool-owned key
+     * (`invalid-input`). Takes `extraLocks`, then the store locks.
+     */
+    updateSettings(mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;
+    /**
+     * Records the identity a lookup found for the row's credential. Since
+     * 0.3.1 it takes the credential epoch the lookup was issued for, and
+     * refuses a lookup that completes after the row was replaced
+     * (`attribution`) or a row recorded for another account
+     * (`identity-mismatch`).
+     */
+    recordIdentity(id: string, identity: string, attribution: Pick<Attribution, 'credentialEpoch'>, options?: RowOperationOptions): Promise<{
+        id: string;
+        disabled: string[];
+    }>;
+    refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
+    recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
+    /** Fires a pull for a row admission refused for want of a reading. */
+    requestReading(id: string): void;
+    /** Resolves once every pull fired so far has settled. */
+    pullsSettled(): Promise<void>;
+}
+export declare function openPoolStore(options: OpenPoolStoreOptions): PoolStore;

package/dist/common-auth-embedded/store/pool.js

@@ -0,0 +1,120 @@
+import { recordQuota } from './attribution.js';
+import { initializePool, readPool, } from './mutate.js';
+import { updateProviderStateRow, } from './provider-state.js';
+import { publication, publishRoster, } from './publication.js';
+import { PullScheduler } from './pull.js';
+import { refreshRow, } from './refresh.js';
+import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
+import { addRow, disableRow, enableRow, recordRowIdentity, removeRow, reorderRows, replaceRow, rotateRow, } from './rows.js';
+import { POOL_SCHEMA_VERSION, } from './schema.js';
+import { readPoolSettings, updatePoolSettings, } from './settings.js';
+/**
+ * Process-wide memory per config file: ids whose per-row entry a library
+ * write dropped (not reused in this process), and rows a load-time pull
+ * already fired for.
+ */
+const processMemory = new Map();
+function memoryFor(configPath) {
+    let memory = processMemory.get(configPath);
+    if (!memory) {
+        memory = { removedIds: new Set(), firedAtLoad: new Set() };
+        processMemory.set(configPath, memory);
+    }
+    return memory;
+}
+function toLoad(result) {
+    if (result.status === 'ready')
+        return {
+            status: 'ready',
+            schemaVersion: POOL_SCHEMA_VERSION,
+            rows: result.rows,
+        };
+    if (result.status === 'pending-migration')
+        return {
+            status: 'pending-migration',
+            roster: Array.isArray(result.config.accounts)
+                ? result.config.accounts
+                : [],
+        };
+    return result;
+}
+export function openPoolStore(options) {
+    const memory = memoryFor(options.configPath);
+    const lockDefaults = {
+        ...POOL_LOCK_DEFAULTS,
+        ...options.lockOptions,
+    };
+    const ctx = {
+        provider: options.provider,
+        configPath: options.configPath,
+        statePath: options.statePath,
+        codec: options.quota,
+        ...(options.providerState ? { providerState: options.providerState } : {}),
+        now: options.now ?? Date.now,
+        storeLocks: options.storeLocks ?? [
+            { name: 'save', path: options.configPath },
+            { name: 'save', path: options.statePath },
+        ],
+        lockDefaults,
+        lockEnv: {
+            now: options.now ?? Date.now,
+            ...(options.onLockEvent ? { onLockEvent: options.onLockEvent } : {}),
+            ...(options.onLockStep ? { onLockStep: options.onLockStep } : {}),
+        },
+        removedIds: memory.removedIds,
+        requireCredentialStamps: options.requireCredentialStamps === true,
+        requireRemovedFingerprint: options.requireRemovedFingerprint === true,
+        ...(options.logger ? { logger: options.logger } : {}),
+        ...(options.onStep ? { onStep: options.onStep } : {}),
+        ...(options.hold ? { hold: options.hold } : {}),
+    };
+    const pulls = new PullScheduler(() => rt, options.pull, options.onPullFailure, memory.firedAtLoad, options.logger);
+    const rt = {
+        ctx,
+        providerLock: options.providerLock ?? {
+            name: `provider-${encodeURIComponent(options.provider)}`,
+            path: options.statePath,
+        },
+        rowLockOptions: options.rowLockOptions ?? {},
+        firePull: (id, reason) => pulls.fire(id, reason),
+    };
+    return {
+        async load() {
+            const result = await readPool(ctx);
+            if (result.status === 'ready') {
+                // A torn row is no candidate, but its pull is fired too: the pull
+                // completes the row on disk before reading it, so an interrupted
+                // replace of an OAuth row heals at the next load.
+                for (const row of result.rows)
+                    if ((row.candidate || (row.torn && row.enabled)) &&
+                        row.type === 'oauth' &&
+                        row.needsFirstReading)
+                        pulls.fire(row.id, 'load');
+            }
+            return toLoad(result);
+        },
+        async read() {
+            return toLoad(await readPool(ctx));
+        },
+        async initialize(input = {}) {
+            return { status: await initializePool(ctx, input.dropKeys ?? []) };
+        },
+        add: (input, callOptions) => addRow(rt, input, callOptions),
+        publishRoster: (plan, callOptions) => publishRoster(rt, plan, callOptions),
+        publication: (operationId) => publication(rt, operationId),
+        replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
+        rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),
+        updateProviderState: (id, fence, mutator, callOptions) => updateProviderStateRow(rt, id, fence, mutator, callOptions),
+        disable: (id, reason, callOptions) => disableRow(rt, id, reason, callOptions),
+        enable: (id, callOptions) => enableRow(rt, id, callOptions),
+        remove: (id, callOptions) => removeRow(rt, id, callOptions),
+        reorder: (ids, callOptions) => reorderRows(rt, ids, callOptions),
+        readSettings: () => readPoolSettings(rt),
+        updateSettings: (mutator, callOptions) => updatePoolSettings(rt, mutator, callOptions),
+        recordIdentity: (id, identity, attribution, callOptions) => recordRowIdentity(rt, id, identity, attribution, callOptions),
+        refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
+        recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),
+        requestReading: (id) => pulls.fire(id, 'admission'),
+        pullsSettled: () => pulls.settled(),
+    };
+}

package/dist/common-auth-embedded/store/provider-state.d.ts

@@ -0,0 +1,131 @@
+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';
+/**
+ * What a credential write does to the provider state beside it: `keep`
+ * leaves the value on disk as it is (bound by the new stamp only if the old
+ * stamp bound it to the same row, epoch and identity), `set` stores a value
+ * the codec accepted, and `clear` deletes it.
+ */
+export type ProviderStateWrite = {
+    kind: 'keep';
+} | {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/**
+ * A provider state as the store will store it: a JSON round trip of it (so
+ * its digest is the same once read back from disk), accepted by the codec.
+ * Refused before anything is written when the store has no codec, the value
+ * is not JSON, or the codec rejects it.
+ */
+export declare function acceptProviderState(codec: ProviderStateCodec | undefined, operation: PoolOperation, id: string, value: unknown, what?: string): unknown;
+/**
+ * The write for a value a credential write brings (`add` of a secret the
+ * pool holds, `rotate`, a refresh): merged with the row's value on disk by
+ * the codec's `merge` when both exist, else the incoming value as is.
+ */
+export declare function mergedProviderState(codec: ProviderStateCodec | undefined, operation: PoolOperation, id: string, onDisk: unknown, incoming: unknown): ProviderStateWrite;
+/**
+ * The provider state a replace leaves on the row, decided before anything is
+ * written: whatever the codec's `onReplace` returns (undefined clears it), or
+ * without that hook the value handed to `replace`, else nothing. The old
+ * credential's value is never kept by default: it describes the account the
+ * replaced credential belonged to.
+ */
+export declare function replacementProviderState(codec: ProviderStateCodec | undefined, row: PoolRow, credentialEpoch: number, identity: string | undefined, incoming: unknown): ProviderStateWrite;
+/**
+ * The provider-state digest the stamp of a credential write carries, and the
+ * state-file fields it changes. `set` binds the new value; `keep` carries the
+ * old stamp's digest forward only when that stamp bound it to this row as it
+ * stood before the write (same credential lineage, the epoch being written,
+ * the identity recorded before the write); `clear` binds nothing.
+ */
+export declare function providerStateCoverage(codec: ProviderStateCodec | undefined, write: ProviderStateWrite, prior: Record<string, unknown> | undefined, priorRow: PoolRow | undefined, credentialEpoch: number): string | undefined;
+/**
+ * Receives a private copy of the row's provider state (undefined when the row
+ * shows none) and the row as loaded under the locks, and returns the next
+ * provider state; returning undefined clears it, so a mutator that means to
+ * keep the value returns it. It runs under the row lock and the store locks,
+ * so it must not call back into the store (`PoolReentryError`).
+ */
+export type ProviderStateMutator = (current: unknown | undefined, row: PoolRow) => unknown | Promise<unknown>;
+export type UpdateProviderStateResult = {
+    id: string;
+    /** The provider state now on disk; absent when the row has none. */
+    providerState?: unknown;
+    /**
+     * `unchanged`: the mutator returned what the row already shows (or cleared
+     * a row that holds none); nothing was written.
+     */
+    outcome: 'updated' | 'cleared' | 'unchanged';
+};
+/**
+ * Changes a row's provider state without touching its credential, in one
+ * state-file write under the row lock, the caller's extra locks and the
+ * store locks. `fence` is what the caller read the row at: the write is
+ * refused (`attribution`, retryable) when the row has since moved to another
+ * credential epoch or recorded identity, and (`unknown-row`) once it is
+ * removed, so a writer that read the row before a replace or a removal never
+ * lands its value on the new credential or brings a removed row's state back.
+ *
+ * The value is bound by the stamp already beside the credential. When its
+ * credential-bound part is unchanged the stamp is left byte for byte as it
+ * is; otherwise only the stamp's provider-state digest changes, so the
+ * credential's stamp status never moves. With `requireCredentialStamps`, an
+ * unbound row refuses (`unbound-credential`) as every other strict path
+ * does. Without it, a row whose stamp was not written by this store with this
+ * credential at the row's epoch and identity refuses the same way: no stamp
+ * could bind the value, so no reader would ever show it. A `rotate` or
+ * `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/common-auth-embedded/store/provider-state.js

@@ -0,0 +1,226 @@
+import { assertNotInsideHook, runInsideHook } from './hooks.js';
+import { runOperation, withTransaction } from './mutate.js';
+import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
+import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialDigest, isCredentialEpoch, isRecord, PROVIDER_STATE_KEY, parseStamp, providerStateDigest, rowLockKey, } from './schema.js';
+/**
+ * A provider state as the store will store it: a JSON round trip of it (so
+ * its digest is the same once read back from disk), accepted by the codec.
+ * Refused before anything is written when the store has no codec, the value
+ * is not JSON, or the codec rejects it.
+ */
+export function acceptProviderState(codec, operation, id, value, what = 'the provider state') {
+    if (!codec)
+        throw refusal(operation, id, 'invalid-input', 'the store was opened without a provider-state codec');
+    let normalized;
+    try {
+        const text = JSON.stringify(value);
+        normalized = text === undefined ? undefined : JSON.parse(text);
+    }
+    catch {
+        normalized = undefined;
+    }
+    if (normalized === undefined)
+        throw refusal(operation, id, 'invalid-provider-state', `${what} cannot be stored as JSON`);
+    if (!codec.validate(normalized))
+        throw refusal(operation, id, 'invalid-provider-state', `the provider-state codec rejected ${what}`);
+    return normalized;
+}
+/**
+ * The write for a value a credential write brings (`add` of a secret the
+ * pool holds, `rotate`, a refresh): merged with the row's value on disk by
+ * the codec's `merge` when both exist, else the incoming value as is.
+ */
+export function mergedProviderState(codec, operation, id, onDisk, incoming) {
+    if (onDisk === undefined || !codec?.merge)
+        return { kind: 'set', value: incoming };
+    return {
+        kind: 'set',
+        value: acceptProviderState(codec, operation, id, codec.merge(structuredClone(onDisk), structuredClone(incoming)), 'the merged provider state'),
+    };
+}
+/**
+ * The provider state a replace leaves on the row, decided before anything is
+ * written: whatever the codec's `onReplace` returns (undefined clears it), or
+ * without that hook the value handed to `replace`, else nothing. The old
+ * credential's value is never kept by default: it describes the account the
+ * replaced credential belonged to.
+ */
+export function replacementProviderState(codec, row, credentialEpoch, identity, incoming) {
+    const hook = codec?.onReplace;
+    const next = hook
+        ? hook(row.providerState === undefined
+            ? undefined
+            : structuredClone(row.providerState), {
+            id: row.id,
+            credentialEpoch,
+            ...(row.identity !== undefined
+                ? { previousIdentity: row.identity }
+                : {}),
+            ...(identity !== undefined ? { identity } : {}),
+            ...(incoming !== undefined
+                ? { incoming: structuredClone(incoming) }
+                : {}),
+        })
+        : incoming;
+    if (next === undefined)
+        return { kind: 'clear' };
+    if (!hook)
+        return { kind: 'set', value: next };
+    return {
+        kind: 'set',
+        value: acceptProviderState(codec, 'replace', row.id, next, 'the provider state onReplace returned'),
+    };
+}
+/**
+ * The provider-state digest the stamp of a credential write carries, and the
+ * state-file fields it changes. `set` binds the new value; `keep` carries the
+ * old stamp's digest forward only when that stamp bound it to this row as it
+ * stood before the write (same credential lineage, the epoch being written,
+ * the identity recorded before the write); `clear` binds nothing.
+ */
+export function providerStateCoverage(codec, write, prior, priorRow, credentialEpoch) {
+    if (write.kind === 'set')
+        return providerStateDigest(codec, write.value);
+    if (write.kind === 'clear')
+        return undefined;
+    return boundProviderStateDigest(prior, priorRow?.credential, credentialEpoch, priorRow?.identity);
+}
+/**
+ * Changes a row's provider state without touching its credential, in one
+ * state-file write under the row lock, the caller's extra locks and the
+ * store locks. `fence` is what the caller read the row at: the write is
+ * refused (`attribution`, retryable) when the row has since moved to another
+ * credential epoch or recorded identity, and (`unknown-row`) once it is
+ * removed, so a writer that read the row before a replace or a removal never
+ * lands its value on the new credential or brings a removed row's state back.
+ *
+ * The value is bound by the stamp already beside the credential. When its
+ * credential-bound part is unchanged the stamp is left byte for byte as it
+ * is; otherwise only the stamp's provider-state digest changes, so the
+ * credential's stamp status never moves. With `requireCredentialStamps`, an
+ * unbound row refuses (`unbound-credential`) as every other strict path
+ * does. Without it, a row whose stamp was not written by this store with this
+ * credential at the row's epoch and identity refuses the same way: no stamp
+ * could bind the value, so no reader would ever show it. A `rotate` or
+ * `replace` stamps such a row.
+ */
+export async function updateProviderStateRow(rt, id, fence, mutator, options = {}) {
+    assertNotInsideHook('updateProviderState');
+    const { ctx } = rt;
+    const operation = 'updateProviderState';
+    return runOperation(ctx, operation, id, options.onFailure, async (locks, progress) => {
+        const codec = ctx.providerState;
+        if (!codec)
+            throw refusal(operation, id, 'invalid-input', 'the store was opened without a provider-state codec');
+        if (typeof mutator !== 'function')
+            throw refusal(operation, id, 'invalid-input', 'a mutator is required');
+        const captured = isRecord(fence) ? fence.credentialEpoch : undefined;
+        if (!isCredentialEpoch(captured))
+            throw refusal(operation, id, 'invalid-input', 'the credential epoch the provider state was read at is required');
+        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(ctx, locks, progress, { operation, rowId: id }, async (tx) => {
+            const row = tx.row(id);
+            if (!row)
+                throw unknownRow(operation, id);
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw refusal(operation, id, 'row-key-changed', `row ${id}'s wire identity changed while its lock was being taken`, true);
+            if (row.invalid)
+                throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
+            if (!row.credential)
+                throw refusal(operation, id, 'no-credential', `row ${id} holds no credential`);
+            requireBound(operation, row);
+            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 plan = await planProviderStateIn(tx, codec, operation, row, mutator);
+            if (plan.kind !== 'changed')
+                return {
+                    id,
+                    outcome: 'unchanged',
+                    ...(plan.kind === 'unchanged' && plan.value !== undefined
+                        ? { providerState: plan.value }
+                        : {}),
+                };
+            tx.setStateAccount(id, plan.account);
+            await tx.commitState();
+            return plan.value === undefined
+                ? { id, outcome: 'cleared' }
+                : { 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,
+    };
+}