@cortexkit/common-auth 0.5.0 → 0.6.0

package/dist/fs/index.d.ts

@@ -1,6 +1,7 @@
 export type { AtomicWriteOptions } from './atomic-write.js';
 export { writeJsonAtomic } from './atomic-write.js';
 export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { LockLoss, RefreshFileLock } from './refresh-file-lock.js';
 export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
-export type { LockOptions } from './with-lock.js';
+export type { LockOptions, LockOwnershipDetails } from './with-lock.js';
 export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/fs/refresh-file-lock.d.ts

@@ -1,4 +1,18 @@
 export declare function isLostMarkerRaceError(error: unknown): boolean;
+export interface LockLoss {
+    readonly reason: 'taken-over' | 'expired' | 'unreadable' | 'renewal-failed' | 'marker-lost';
+    readonly expectedOwnerId: string;
+    readonly observedOwnerId?: string;
+    readonly observedExpiresAt?: number;
+}
+export interface RefreshFileLock {
+    readonly ownerId: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+    /** Resolves once on detected loss; remains pending after an owner's release. */
+    whenLost(): Promise<LockLoss>;
+    hasLost(): boolean;
+}
 export declare function acquireRefreshFileLock(options: {
     name: string;
     ttlMs: number;
@@ -12,7 +26,4 @@ export declare function acquireRefreshFileLock(options: {
     renew?: boolean;
     renewIntervalMs?: number;
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
-}): Promise<{
-    release: () => Promise<void>;
-    assertOwned: () => Promise<void>;
-} | null>;
+}): Promise<RefreshFileLock | null>;

package/dist/fs/refresh-file-lock.js

@@ -19,6 +19,30 @@ export async function acquireRefreshFileLock(options) {
     const now = options.now ?? Date.now;
     let renewTimer = null;
     let released = false;
+    let loss;
+    let resolveLoss;
+    const lostPromise = new Promise((resolve) => {
+        resolveLoss = resolve;
+    });
+    function recordLoss(reason, owner) {
+        if (loss || released)
+            return;
+        loss = Object.freeze({
+            reason,
+            expectedOwnerId: ownerId,
+            ...(typeof owner?.ownerId === 'string'
+                ? { observedOwnerId: owner.ownerId }
+                : {}),
+            ...(typeof owner?.expiresAt === 'number'
+                ? { observedExpiresAt: owner.expiresAt }
+                : {}),
+        });
+        if (renewTimer) {
+            clearRefreshLockRenewalTimeout(renewTimer);
+            renewTimer = null;
+        }
+        resolveLoss(loss);
+    }
     let renewalInFlight = null;
     // Only the owner of this exclusively-created marker may remove or renew a
     // lock. A contender recovering a stale marker can accidentally rename a newer
@@ -203,7 +227,7 @@ export async function acquireRefreshFileLock(options) {
         }
     }
     function scheduleRenewal() {
-        if (!options.renew || released)
+        if (!options.renew || released || loss)
             return;
         const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
         renewTimer = setRefreshLockRenewalTimeout(() => {
@@ -213,19 +237,25 @@ export async function acquireRefreshFileLock(options) {
                     const markerAcquired = await withEvictionMarker(async () => {
                         const owner = await readOwner();
                         const currentNow = now();
-                        if (released || owner?.ownerId !== ownerId) {
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (owner?.ownerId !== ownerId) {
+                            recordLoss('taken-over', owner);
                             shouldReschedule = false;
                             return;
                         }
                         // An expired lease is no longer ours to extend; a contender may
                         // already be eligible to acquire it.
-                        if (Number(owner?.expiresAt) <= currentNow) {
+                        if (!(Number(owner?.expiresAt) > currentNow)) {
+                            recordLoss('expired', owner);
                             shouldReschedule = false;
                             return;
                         }
                         if (options.onStep)
                             await options.onStep('renewal-owner-confirmed');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -233,7 +263,7 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-fenced');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -241,10 +271,15 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-ready');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
                         await writeOwner();
                         if (!(await ownsEvictionMarker())) {
                             // If marker ownership cannot be read, stop claiming the lease
                             // and remove only a record that still carries our owner id.
+                            recordLoss('marker-lost');
                             shouldReschedule = false;
                             await relinquishLockAfterMarkerLoss();
                             return;
@@ -255,7 +290,17 @@ export async function acquireRefreshFileLock(options) {
                     }
                 }
                 catch {
-                    // Transient marker and filesystem failures retry on the next interval.
+                    // Retry transient failures only while the lease can still be verified.
+                    try {
+                        const owner = await readOwner();
+                        if (owner?.ownerId !== ownerId)
+                            recordLoss('taken-over', owner);
+                        else if (!(Number(owner?.expiresAt) > now()))
+                            recordLoss('expired', owner);
+                    }
+                    catch {
+                        recordLoss('renewal-failed');
+                    }
                 }
                 finally {
                     if (options.onStep) {
@@ -266,7 +311,7 @@ export async function acquireRefreshFileLock(options) {
                             // Errors from the onStep observer must not reject the renewal.
                         }
                     }
-                    if (shouldReschedule && !released)
+                    if (shouldReschedule && !released && !loss)
                         scheduleRenewal();
                 }
             })();
@@ -341,20 +386,35 @@ export async function acquireRefreshFileLock(options) {
         return null;
     scheduleRenewal();
     return {
+        ownerId,
+        whenLost: () => lostPromise,
+        hasLost: () => loss !== undefined,
         assertOwned: async () => {
+            let observed;
             try {
                 const owner = await readOwner();
+                observed = owner;
                 if (!released &&
+                    !loss &&
                     owner?.ownerId === ownerId &&
                     Number(owner?.expiresAt) > now())
                     return;
+                recordLoss(owner?.ownerId !== ownerId ? 'taken-over' : 'expired', owner);
             }
             catch {
                 // Unreadable ownership is not evidence of a valid lease.
+                recordLoss('unreadable');
             }
             throw new LockOwnershipError({
                 target: options.path,
                 name: options.name,
+                expectedOwnerId: ownerId,
+                ...(typeof observed?.ownerId === 'string'
+                    ? { observedOwnerId: observed.ownerId }
+                    : {}),
+                ...(typeof observed?.expiresAt === 'number'
+                    ? { observedExpiresAt: observed.expiresAt }
+                    : {}),
             });
         },
         release: async () => {

package/dist/fs/with-lock.d.ts

@@ -11,15 +11,16 @@ export declare class LockContentionError extends Error {
         timeoutMs: number;
     });
 }
+export interface LockOwnershipDetails {
+    target: string;
+    name: string;
+    expectedOwnerId?: string;
+    observedOwnerId?: string;
+    observedExpiresAt?: number;
+}
 export declare class LockOwnershipError extends Error {
-    readonly details: {
-        target: string;
-        name: string;
-    };
-    constructor(details: {
-        target: string;
-        name: string;
-    });
+    readonly details: LockOwnershipDetails;
+    constructor(details: LockOwnershipDetails);
 }
 export interface LockOptions {
     name: string;

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 import type { StoredCredential } from './schema.js';
 /** Every library operation that can fail, as named in the failure value. */
-export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'updateProviderState' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *
@@ -19,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
  * lock outcomes (a wait that ran out, and a lease found lost); the rest are
  * refusals and failures of the operation itself.
  */
-export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
+export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'invalid-provider-state' | 'after-persist-hook' | 'unexpected';
 /**
  * The single failure value of every store operation. `committed` is present
  * only when the operation had already written a credential to the state file

package/dist/store/index.d.ts

@@ -6,13 +6,14 @@ 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 { PullHook, PullRequest } from './pull.js';
 export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
 export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
+export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
 export type { PullReason } from './runtime.js';
-export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
-export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
+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';
 export type { PoolSettings, SettingsMutator, SettingsRead, UpdateSettingsOptions, UpdateSettingsResult, } from './settings.js';
 export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/index.js

@@ -2,5 +2,5 @@ export { PoolOperationError, PoolReentryError } from './errors.js';
 export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
 export { openPoolStore } from './pool.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } 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';
 export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/mutate.d.ts

@@ -1,7 +1,7 @@
 import { type PoolFailurePhase, type PoolOperation, PoolOperationError } from './errors.js';
 import { type PoolLogger } from './hooks.js';
 import { type LockEnvironment, LockStack, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
-import { type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
+import { type PoolRow, type ProviderStateCodec, type QuotaCodec, type StoredCredential } from './schema.js';
 /** Named points on the write path, for crash and ownership injection. */
 export type WriteStep = 'before-config-write' | 'after-config-write' | 'before-state-write' | 'after-state-write';
 /** Awaitable pause points on the pull and refresh paths. */
@@ -11,6 +11,8 @@ export interface StoreContext {
     configPath: string;
     statePath: string;
     codec: QuotaCodec;
+    /** The provider-state codec; without one no row shows a provider state. */
+    providerState?: ProviderStateCodec;
     now: () => number;
     storeLocks: readonly PoolLockSpec[];
     lockDefaults: PoolLockOptions;

package/dist/store/mutate.js

@@ -41,6 +41,7 @@ export async function readPool(ctx) {
         state: state.state,
         rows: loadRows(config.config, state.state, ctx.codec, {
             requireCredentialStamps: ctx.requireCredentialStamps === true,
+            ...(ctx.providerState ? { providerState: ctx.providerState } : {}),
         }),
     };
 }
@@ -90,6 +91,9 @@ export class Transaction {
     rows() {
         return loadRows(this.config, this.state, this.ctx.codec, {
             requireCredentialStamps: this.ctx.requireCredentialStamps === true,
+            ...(this.ctx.providerState
+                ? { providerState: this.ctx.providerState }
+                : {}),
         });
     }
     row(id) {

package/dist/store/pool.d.ts

@@ -2,11 +2,12 @@ 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 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 RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
-import { type PoolCredential, type PoolRow, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.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 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. */
@@ -14,6 +15,13 @@ export interface OpenPoolStoreOptions {
     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).
@@ -81,9 +89,12 @@ export interface PoolStore {
         status: InitializeOutcome;
     }>;
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
-    replace(id: string, credential: PoolCredential, input?: {
-        identity?: string;
-    }, options?: RowOperationOptions): Promise<{
+    /**
+     * 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.
+     */
+    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
         id: string;
         credential: StoredCredential;
         credentialEpoch: number;
@@ -94,12 +105,17 @@ export interface PoolStore {
      * to keep the row's, and one that gives another is refused
      * (`endpoint-mismatch`) before writing: that is a `replace`.
      */
-    rotate(id: string, credential: RotateCredential, input?: {
-        identity?: string;
-    }, options?: RowOperationOptions): Promise<{
+    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowOperationOptions): 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

package/dist/store/pool.js

@@ -1,5 +1,6 @@
 import { recordQuota } from './attribution.js';
 import { initializePool, readPool, } from './mutate.js';
+import { updateProviderStateRow, } from './provider-state.js';
 import { PullScheduler } from './pull.js';
 import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
@@ -47,6 +48,7 @@ export function openPoolStore(options) {
         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 },
@@ -98,6 +100,7 @@ export function openPoolStore(options) {
         add: (input, callOptions) => addRow(rt, input, callOptions),
         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),

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

@@ -0,0 +1,86 @@
+import type { Attribution } from './attribution.js';
+import type { PoolOperation } from './errors.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>;

package/dist/store/provider-state.js

@@ -0,0 +1,186 @@
+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,
+            ...(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 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))
+                return {
+                    id,
+                    outcome: 'unchanged',
+                    ...(next !== undefined ? { providerState: 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,
+                    };
+            }
+            tx.setStateAccount(id, nextAccount);
+            await tx.commitState();
+            return next === undefined
+                ? { id, outcome: 'cleared' }
+                : { id, outcome: 'updated', providerState: next };
+        });
+    });
+}

package/dist/store/refresh.d.ts

@@ -10,6 +10,14 @@ export interface ProviderRefreshResult {
     expiresIn?: number;
     /** The account's wire identity, when the provider reports one. */
     identity?: string;
+    /**
+     * Provider state that changes with the new token (needs the store's
+     * provider-state codec). It is merged with the row's value on disk
+     * (`ProviderStateCodec.merge`) and written in the same state write as the
+     * rotated credential, under the same commit fence. Left out, the row keeps
+     * its value.
+     */
+    providerState?: unknown;
 }
 export type ProviderRefresh = (credential: OAuthCredential & {
     lastRefreshedAt?: number;

package/dist/store/refresh.js

@@ -2,6 +2,7 @@ import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
 import { recordIdentityIn } from './identity.js';
 import { runOperation, withTransaction } from './mutate.js';
+import { acceptProviderState, mergedProviderState } from './provider-state.js';
 import { rotateIn } from './rows.js';
 import { readRow, refusal, requireBound, rowLockSpec, } from './runtime.js';
 import { rotationStamp, rotationStampUntrusted, rowLockKey, } from './schema.js';
@@ -98,6 +99,9 @@ export async function refreshRow(rt, id, provider, options = {}) {
         }
         if (typeof result?.refresh !== 'string' || !result.refresh.trim())
             throw refusal('refresh', id, 'provider', 'the provider returned no refresh token', true);
+        const incoming = result.providerState === undefined
+            ? undefined
+            : acceptProviderState(ctx.providerState, 'refresh', id, result.providerState, 'the provider state the provider returned');
         const commit = await withTransaction(ctx, locks, progress, { operation: 'refresh', rowId: id }, async (tx) => {
             const current = tx.row(id);
             const entry = tx.entry(id);
@@ -142,6 +146,11 @@ export async function refreshRow(rt, id, provider, options = {}) {
             const stored = await rotateIn(rt, tx, id, credential, {
                 stamp: rotationStamp(prior, now),
                 identity: learnt,
+                ...(incoming !== undefined
+                    ? {
+                        providerState: mergedProviderState(ctx.providerState, 'refresh', id, current.providerState, incoming),
+                    }
+                    : {}),
             });
             let identity = current.identity;
             if (learnt !== undefined) {

package/dist/store/rows.d.ts

@@ -1,6 +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 { 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';
@@ -80,6 +81,24 @@ export interface AddInput {
     credential: PoolCredential;
     identity?: string;
     label?: string;
+    /**
+     * Provider state for the credential, written in the same state write as
+     * the credential (needs the store's provider-state codec). On an `add`
+     * that rotates a row already holding this secret it is merged with the
+     * row's value (`ProviderStateCodec.merge`); left out, that row keeps its
+     * value.
+     */
+    providerState?: unknown;
+}
+/** What `replace` and `rotate` take beside the credential. */
+export interface CredentialWriteInput {
+    identity?: string;
+    /**
+     * Provider state written in the same state write as the credential. For
+     * `rotate` it is merged with the row's value; left out, the row keeps its
+     * value. For `replace` see `ProviderStateCodec.onReplace`.
+     */
+    providerState?: unknown;
 }
 export type AddResult = {
     /** The row holding the credential; an existing row's id on a re-add. */
@@ -102,18 +121,15 @@ export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string,
     clearErrors?: boolean;
     binding?: CredentialBinding;
     identity?: string;
+    providerState?: ProviderStateWrite;
 }): Promise<StoredCredential>;
 export declare function addRow(rt: StoreRuntime, input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
-export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: {
-    identity?: string;
-}, options?: RowOperationOptions): Promise<{
+export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
     id: string;
     credential: StoredCredential;
     credentialEpoch: number;
 }>;
-export declare function rotateRow(rt: StoreRuntime, id: string, credential: RotateCredential, input?: {
-    identity?: string;
-}, options?: RowOperationOptions): Promise<{
+export declare function rotateRow(rt: StoreRuntime, id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
     id: string;
     credential: StoredCredential;
 }>;

package/dist/store/rows.js

@@ -2,8 +2,9 @@ import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
 import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
+import { acceptProviderState, mergedProviderState, providerStateCoverage, replacementProviderState, } from './provider-state.js';
 import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
-import { CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.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';
 /** Fields of a state entry that belong to the credential it replaces. */
 const CREDENTIAL_STATE_FIELDS = [
@@ -90,6 +91,14 @@ function bindingInTx(tx, id, stored, learnt) {
 export async function rotateIn(rt, tx, id, given, extra = {}) {
     const credential = onRowEndpoint(tx, id, given);
     const prior = tx.stateAccount(id);
+    const stateWrite = extra.providerState ?? { kind: 'keep' };
+    const epoch = tx.entry(id)?.credentialEpoch;
+    const credentialEpoch = typeof epoch === 'number' ? epoch : 1;
+    // The provider state goes in the same state write as the credential and
+    // its stamp, so no reader ever sees one without the other. A kept value is
+    // bound by the new stamp only if the old one bound it to this row at the
+    // epoch being written; a replace moves the epoch, so it never keeps one.
+    const providerStateBinding = providerStateCoverage(rt.ctx.providerState, stateWrite, prior, prior && Object.hasOwn(prior, PROVIDER_STATE_KEY) ? tx.row(id) : undefined, credentialEpoch);
     const priorStamp = typeof prior?.lastRefreshedAt === 'number'
         ? prior.lastRefreshedAt
         : undefined;
@@ -104,12 +113,20 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
         delete kept.lastQuotaRefreshError;
         delete kept.quota;
     }
+    if (stateWrite.kind === 'clear')
+        delete kept[PROVIDER_STATE_KEY];
+    else if (stateWrite.kind === 'set')
+        kept[PROVIDER_STATE_KEY] = stateWrite.value;
     const stored = storedCredential(credential, stamp);
-    const epoch = tx.entry(id)?.credentialEpoch;
     tx.setStateAccount(id, {
         ...kept,
         ...stateFieldsFor(credential, stamp),
-        [CREDENTIAL_STAMP_KEY]: stampFor(stored, typeof epoch === 'number' ? epoch : 1, extra.binding ?? bindingInTx(tx, id, stored, extra.identity), { replace: extra.binding !== undefined }),
+        [CREDENTIAL_STAMP_KEY]: stampFor(stored, credentialEpoch, extra.binding ?? bindingInTx(tx, id, stored, extra.identity), {
+            replace: extra.binding !== undefined,
+            ...(providerStateBinding !== undefined
+                ? { providerState: providerStateBinding }
+                : {}),
+        }),
     });
     await tx.commitState(stored);
     return stored;
@@ -126,9 +143,14 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
 async function stampIdentityIn(tx, row, identity) {
     if (!row.credential || row.stamp !== 'bound')
         return;
+    const account = tx.stateAccount(row.id);
+    // The provider state stays bound across the identity being learnt: the old
+    // stamp bound it to the row with no identity, the new one to the identity
+    // the config is about to record.
+    const providerState = boundProviderStateDigest(account, row.credential, row.credentialEpoch ?? 1, row.identity);
     tx.setStateAccount(row.id, {
-        ...(tx.stateAccount(row.id) ?? {}),
-        [CREDENTIAL_STAMP_KEY]: stampFor(row.credential, row.credentialEpoch ?? 1, bindingInTx(tx, row.id, row.credential, identity)),
+        ...(account ?? {}),
+        [CREDENTIAL_STAMP_KEY]: stampFor(row.credential, row.credentialEpoch ?? 1, bindingInTx(tx, row.id, row.credential, identity), providerState !== undefined ? { providerState } : {}),
     });
     await tx.commitState();
 }
@@ -165,6 +187,9 @@ export async function addRow(rt, input, options = {}) {
     const { id, credential, identity, label } = input;
     const result = await runOperation(ctx, 'add', id, options.onFailure, async (locks, progress) => {
         checkInput('add', id, credential);
+        const incoming = input.providerState === undefined
+            ? undefined
+            : acceptProviderState(ctx.providerState, 'add', id, input.providerState);
         if (ctx.removedIds.has(id))
             throw refusal('add', id, 'id-removed', `id ${id} was removed from the roster in this process and is not reused`);
         await locks.acquire(rowLockSpec(rt, { id, identity }));
@@ -190,7 +215,13 @@ export async function addRow(rt, input, options = {}) {
                     same.identity !== undefined &&
                     identity !== same.identity)
                     throw identityMismatch('add', same.id);
-                const stored = await rotateIn(rt, tx, same.id, credential);
+                const stored = await rotateIn(rt, tx, same.id, credential, {
+                    ...(incoming !== undefined
+                        ? {
+                            providerState: mergedProviderState(ctx.providerState, 'add', same.id, same.providerState, incoming),
+                        }
+                        : {}),
+                });
                 return { id: same.id, outcome: 'rotated', credential: stored };
             }
             const existing = rows.find((row) => row.id === id);
@@ -219,6 +250,9 @@ export async function addRow(rt, input, options = {}) {
                     });
                 const stored = await rotateIn(rt, tx, id, credential, {
                     clearErrors: true,
+                    ...(incoming !== undefined
+                        ? { providerState: { kind: 'set', value: incoming } }
+                        : {}),
                 });
                 if (!existing.hasEntry)
                     await tx.commitConfig();
@@ -253,7 +287,11 @@ export async function addRow(rt, input, options = {}) {
             // roster row could load beside a credential left under its id by an
             // interrupted removal. Nothing of such a leftover entry is kept.
             tx.dropStateAccount(id);
-            const stored = await rotateIn(rt, tx, id, credential);
+            const stored = await rotateIn(rt, tx, id, credential, {
+                ...(incoming !== undefined
+                    ? { providerState: { kind: 'set', value: incoming } }
+                    : {}),
+            });
             await tx.commitConfig();
             return { id, outcome, credential: stored };
         });
@@ -268,6 +306,9 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
     const { ctx } = rt;
     const result = await runOperation(ctx, 'replace', id, options.onFailure, async (locks, progress) => {
         checkInput('replace', id, credential);
+        const incoming = input.providerState === undefined
+            ? undefined
+            : acceptProviderState(ctx.providerState, 'replace', id, input.providerState);
         const { row: seen } = await readRow(rt, 'replace', id);
         await locks.acquire(rowLockSpec(rt, seen));
         if (credential.type === 'oauth')
@@ -285,6 +326,9 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
             // Refused before anything is written; the row keeps its credential.
             if (!isCredentialEpoch(credentialEpoch))
                 throw refusal('replace', id, 'invalid-row', `row ${id}'s credential epoch cannot advance past ${Number.MAX_SAFE_INTEGER}; remove the row and add the new credential as a new row`);
+            // Decided before anything is written: a hook that throws or
+            // returns a value the codec rejects leaves the row as it was.
+            const providerState = replacementProviderState(ctx.providerState, row, credentialEpoch, input.identity, incoming);
             const binding = {
                 ...(input.identity !== undefined
                     ? { identity: input.identity }
@@ -308,6 +352,7 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
             const stored = await rotateIn(rt, tx, id, credential, {
                 clearErrors: true,
                 binding,
+                providerState,
             });
             await tx.commitConfig();
             return { id, credential: stored, credentialEpoch };
@@ -322,6 +367,9 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
     const { ctx } = rt;
     return runOperation(ctx, 'rotate', id, options.onFailure, async (locks, progress) => {
         checkInput('rotate', id, credential);
+        const incoming = input.providerState === undefined
+            ? undefined
+            : acceptProviderState(ctx.providerState, 'rotate', id, input.providerState);
         const { row: seen } = await readRow(rt, 'rotate', id);
         await locks.acquire(rowLockSpec(rt, seen));
         if (input.identity !== undefined && credential.type === 'oauth')
@@ -347,6 +395,11 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
                 : undefined;
             const stored = await rotateIn(rt, tx, id, credential, {
                 identity: learnt,
+                ...(incoming !== undefined
+                    ? {
+                        providerState: mergedProviderState(ctx.providerState, 'rotate', id, row.providerState, incoming),
+                    }
+                    : {}),
             });
             let configChanged = false;
             if (!row.hasEntry) {

package/dist/store/schema.d.ts

@@ -42,6 +42,69 @@ export interface QuotaCodec {
     validate(value: unknown): boolean;
     merge(stored: unknown | undefined, observation: unknown): unknown;
 }
+/**
+ * What `ProviderStateCodec.onReplace` is told about a replacement: the row,
+ * the credential epoch the new credential starts, the identity the replace
+ * records (absent: none), and the provider state the caller handed to
+ * `replace`, if any.
+ */
+export interface ProviderStateReplacement {
+    id: string;
+    credentialEpoch: number;
+    identity?: string;
+    incoming?: unknown;
+}
+/**
+ * Codec for the provider state a plugin keeps beside each row's credential
+ * (a project id, a device fingerprint, eligibility times: whatever belongs to
+ * that credential). The store never interprets the value: it stores it as
+ * JSON, asks `validate` before every write and on every load, and calls the
+ * hooks below where two values meet. Every hook is synchronous and runs
+ * under the store locks.
+ */
+export interface ProviderStateCodec {
+    validate(value: unknown): boolean;
+    /**
+     * The part of a (valid) value that belongs to the credential: what is true
+     * of the account the credential signs in to, such as a project id or a
+     * device fingerprint, as opposed to what the plugin merely tracks about
+     * its use, such as a cooldown or a cursor. The credential stamp covers the
+     * digest of exactly this projection, so a foreign edit of it hides the
+     * value, while the rest may change through `updateProviderState` without
+     * the stamp being rewritten. It must be a pure function of the value that
+     * returns JSON with a deterministic key order. Without it the whole value
+     * is credential-bound.
+     */
+    credentialBound?(value: unknown): unknown;
+    /**
+     * Combines the value on disk with one a write brings (`add` of a secret the
+     * pool already holds, `rotate`, or a refresh whose provider returned a
+     * state). Called only when the row has a value on disk; without it the
+     * incoming value replaces the stored one. Its result is validated.
+     */
+    merge?(onDisk: unknown, incoming: unknown): unknown;
+    /**
+     * The provider state of a row once `replace` gives it a new credential
+     * epoch. `previous` is the old credential's value (undefined when the row
+     * shows none). Returning undefined clears it. Without this hook a replace
+     * keeps the value handed to `replace` and otherwise clears the state.
+     */
+    onReplace?(previous: unknown | undefined, replacement: ProviderStateReplacement): unknown | undefined;
+}
+/**
+ * Why a row shows no provider state although the state file holds one for it.
+ *
+ * `uncovered`: the value's credential-bound part (see
+ * `ProviderStateCodec.credentialBound`) is not the one this store last
+ * wrote beside the row's credential at its credential epoch and recorded
+ * identity. Another writer edited it, or
+ * wrote the credential beside it without knowing about it (an older version
+ * of this library, which drops the coverage, or a writer that does not know
+ * the pool at all), or it belongs to an earlier credential of the row.
+ * `invalid`: the value is covered but the codec rejects it, or the store was
+ * opened without a provider-state codec.
+ */
+export type ProviderStateDrop = 'uncovered' | 'invalid';
 /**
  * What the stamp beside a row's credential proves (see `CredentialStamp`).
  *
@@ -82,6 +145,18 @@ export interface PoolRow {
     disabledReason?: string;
     /** The opaque quota map, as validated by the codec. */
     quota?: unknown;
+    /**
+     * The opaque provider state kept beside the credential, as validated by
+     * the provider-state codec. Absent when the row has none, or when the one
+     * on disk is not shown (see `providerStateDropped`).
+     */
+    providerState?: unknown;
+    /**
+     * Set when the state file holds a provider state for the row that is not
+     * shown, and why. The value stays on disk untouched until a write on the
+     * row sets or clears it; the row itself stays usable.
+     */
+    providerStateDropped?: ProviderStateDrop;
     hasEntry: boolean;
     /** A row that may be refreshed, pulled for, or admitted. */
     candidate: boolean;
@@ -147,6 +222,12 @@ export interface CredentialBinding {
  * only on replace. `replace` marks a stamp written by a replace, which is
  * what lets a reader complete a replace that stopped after writing the
  * credential: a stamp from any other write is never completed as torn.
+ *
+ * `providerState` is the digest of the credential-bound part of the provider
+ * state beside the credential (see `providerStateDigest`); it is absent when
+ * the row has none, so the stamp of a row without provider state is exactly
+ * what 0.5.0 wrote. It is apart from `digest` and `dispatch`, which keep
+ * their meaning: the credential's stamp status never depends on it.
  */
 export interface CredentialStamp {
     credentialEpoch: number;
@@ -154,7 +235,13 @@ export interface CredentialStamp {
     dispatch?: string;
     binding?: CredentialBinding;
     replace?: true;
+    providerState?: string;
 }
+/**
+ * Key, inside a state-file account entry, of the provider state kept beside
+ * the credential. Older readers ignore it.
+ */
+export declare const PROVIDER_STATE_KEY = "commonAuthProviderState";
 export type ConfigClassification = {
     status: 'ready';
     exists: boolean;
@@ -208,7 +295,28 @@ export declare function dispatchDigest(credential: PoolCredential | StoredCreden
  */
 export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding: CredentialBinding, options?: {
     replace?: boolean;
+    providerState?: string;
 }): CredentialStamp;
+/**
+ * The digest a stamp carries for a provider state: of its credential-bound
+ * part (`ProviderStateCodec.credentialBound`, the whole value without it), as
+ * it serializes. The store only ever stores values that survive a JSON round
+ * trip unchanged, so the digest of a value read back from disk equals the one
+ * computed when it was written. Its input prefix differs from every other
+ * digest the store writes.
+ */
+export declare function providerStateDigest(codec: Pick<ProviderStateCodec, 'credentialBound'> | undefined, value: unknown): string;
+/**
+ * The provider-state digest of the stamp in a state-file account entry, when
+ * that stamp binds it to this row: written with this credential (its lineage
+ * digest matches), at this credential epoch, naming this recorded identity.
+ * Whether the value beside it still has that digest is checked apart, by
+ * `providerStateFields`; this alone is what a write that keeps the value
+ * carries into the stamp it writes, so a value no stamp of this store bound
+ * to the row stays unbound rather than being vouched for, and one edited
+ * after it was bound stays detectably edited.
+ */
+export declare function boundProviderStateDigest(account: unknown, credential: PoolCredential | StoredCredential | undefined, credentialEpoch: number | undefined, identity: string | undefined): string | undefined;
 /**
  * A credential epoch is a positive safe integer. Above `MAX_SAFE_INTEGER`,
  * adding one may give back the same number, so a replace would not move the
@@ -245,7 +353,7 @@ export declare function setEntryIn(config: Record<string, unknown>, id: string,
  * malformed per-row entry makes that one row invalid (never a candidate) and
  * blocks nothing else.
  */
-export declare function buildRawRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];
+export declare function buildRawRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, providerCodec?: ProviderStateCodec): PoolRow[];
 /** The row-lock key: recorded wire identity when known, else the local id. */
 export declare function rowLockKey(row: Pick<PoolRow, 'id' | 'identity'>): string;
 /**

package/dist/store/schema.js

@@ -18,6 +18,11 @@ export const REFRESH_STAMP_TOLERANCE_MS = 5 * 60_000;
  * credential beside it belongs to. Older readers ignore it.
  */
 export const CREDENTIAL_STAMP_KEY = POOL_KEY;
+/**
+ * Key, inside a state-file account entry, of the provider state kept beside
+ * the credential. Older readers ignore it.
+ */
+export const PROVIDER_STATE_KEY = 'commonAuthProviderState';
 export function isRecord(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -112,8 +117,49 @@ export function stampFor(credential, credentialEpoch, binding, options = {}) {
         dispatch: dispatchDigest(credential),
         binding: { ...binding },
         ...(options.replace ? { replace: true } : {}),
+        ...(options.providerState !== undefined
+            ? { providerState: options.providerState }
+            : {}),
     };
 }
+/**
+ * The digest a stamp carries for a provider state: of its credential-bound
+ * part (`ProviderStateCodec.credentialBound`, the whole value without it), as
+ * it serializes. The store only ever stores values that survive a JSON round
+ * trip unchanged, so the digest of a value read back from disk equals the one
+ * computed when it was written. Its input prefix differs from every other
+ * digest the store writes.
+ */
+export function providerStateDigest(codec, value) {
+    const bound = codec?.credentialBound ? codec.credentialBound(value) : value;
+    return createHash('sha256')
+        .update(`provider-state\0${JSON.stringify(bound ?? null)}`)
+        .digest('hex');
+}
+/**
+ * The provider-state digest of the stamp in a state-file account entry, when
+ * that stamp binds it to this row: written with this credential (its lineage
+ * digest matches), at this credential epoch, naming this recorded identity.
+ * Whether the value beside it still has that digest is checked apart, by
+ * `providerStateFields`; this alone is what a write that keeps the value
+ * carries into the stamp it writes, so a value no stamp of this store bound
+ * to the row stays unbound rather than being vouched for, and one edited
+ * after it was bound stays detectably edited.
+ */
+export function boundProviderStateDigest(account, credential, credentialEpoch, identity) {
+    if (!credential || credentialEpoch === undefined)
+        return undefined;
+    if (!isRecord(account) || !Object.hasOwn(account, PROVIDER_STATE_KEY))
+        return undefined;
+    const stamp = parseStamp(account[CREDENTIAL_STAMP_KEY]);
+    if (!stamp ||
+        stamp.providerState === undefined ||
+        stamp.digest !== credentialDigest(credential) ||
+        stamp.credentialEpoch !== credentialEpoch ||
+        stamp.binding?.identity !== identity)
+        return undefined;
+    return stamp.providerState;
+}
 /**
  * A credential epoch is a positive safe integer. Above `MAX_SAFE_INTEGER`,
  * adding one may give back the same number, so a replace would not move the
@@ -135,15 +181,20 @@ export function parseStamp(raw) {
         return undefined;
     if ('replace' in raw && raw.replace !== true)
         return undefined;
+    if ('providerState' in raw && typeof raw.providerState !== 'string')
+        return undefined;
     const marks = {
         ...(typeof raw.dispatch === 'string' ? { dispatch: raw.dispatch } : {}),
         ...(raw.replace === true ? { replace: true } : {}),
+        ...(typeof raw.providerState === 'string'
+            ? { providerState: raw.providerState }
+            : {}),
     };
-    // Every stamp that carries a dispatch digest is written with a binding; one
-    // without is not a stamp this store writes, and it would leave the row's
-    // identity unchecked.
+    // Every stamp that carries a dispatch digest or a provider-state digest is
+    // written with a binding; one without is not a stamp this store writes,
+    // and it would leave the row's identity unchecked.
     if (!('binding' in raw))
-        return 'dispatch' in raw || 'replace' in raw
+        return 'dispatch' in raw || 'replace' in raw || 'providerState' in raw
             ? undefined
             : { credentialEpoch: epoch, digest: raw.digest };
     const binding = raw.binding;
@@ -389,7 +440,7 @@ export function setEntryIn(config, id, entry) {
  * malformed per-row entry makes that one row invalid (never a candidate) and
  * blocks nothing else.
  */
-export function buildRawRows(config, state, codec) {
+export function buildRawRows(config, state, codec, providerCodec) {
     const entries = entriesOf(config);
     const stateAccounts = stateAccountsOf(state);
     const seen = new Set();
@@ -419,6 +470,9 @@ export function buildRawRows(config, state, codec) {
         const entry = hasEntry ? parseEntry(entries[id], codec) : undefined;
         const credential = credentialFor(raw, stateAccounts[id]);
         const enabled = raw.enabled !== false;
+        // A row without a per-row entry is at credential epoch 1 (the epoch the
+        // store stamps and later gives it), so its stamp is checked against 1.
+        const stampEpoch = entry ? entry.credentialEpoch : hasEntry ? undefined : 1;
         const identity = typeof raw.accountId === 'string' && raw.accountId
             ? raw.accountId
             : undefined;
@@ -440,9 +494,8 @@ export function buildRawRows(config, state, codec) {
                 ? { disabledReason: entry.disabledReason }
                 : {}),
             ...(entry && 'quota' in entry ? { quota: entry.quota } : {}),
-            // A row without a per-row entry is at credential epoch 1 (the epoch the
-            // store stamps and later gives it), so its stamp is checked against 1.
-            stamp: stampStatusOf(credential, entry ? entry.credentialEpoch : hasEntry ? undefined : 1, identity, stateAccounts[id]),
+            ...providerStateFields(stateAccounts[id], credential, stampEpoch, identity, providerCodec),
+            stamp: stampStatusOf(credential, stampEpoch, identity, stateAccounts[id]),
         };
         if (hasEntry && !entry) {
             row.invalid = 'entry';
@@ -454,6 +507,30 @@ export function buildRawRows(config, state, codec) {
     }
     return rows;
 }
+/**
+ * The provider-state fields of a loaded row. A value on disk is shown only
+ * when the stamp beside the credential binds a provider state to this row's
+ * credential, epoch and identity (see `boundProviderStateDigest`), the codec
+ * accepts the value, and the value's credential-bound part has the digest
+ * that stamp names. Otherwise the row says why it shows none and stays
+ * usable: the value is the plugin's own derived data, which it can rebuild,
+ * and the credential beside it may well be sound.
+ */
+function providerStateFields(account, credential, credentialEpoch, identity, codec) {
+    if (!isRecord(account) || !Object.hasOwn(account, PROVIDER_STATE_KEY))
+        return {};
+    const digest = boundProviderStateDigest(account, credential, credentialEpoch, identity);
+    if (digest === undefined)
+        return { providerStateDropped: 'uncovered' };
+    const value = account[PROVIDER_STATE_KEY];
+    // The value is validated before it is projected, so the projection only
+    // ever sees a value of the shape the codec accepts.
+    if (!codec?.validate(value))
+        return { providerStateDropped: 'invalid' };
+    if (providerStateDigest(codec, value) !== digest)
+        return { providerStateDropped: 'uncovered' };
+    return { providerState: value };
+}
 /** The row-lock key: recorded wire identity when known, else the local id. */
 export function rowLockKey(row) {
     return row.identity ?? row.id;

package/dist/store/torn.d.ts

@@ -1,5 +1,5 @@
 import { type RowEditor } from './identity.js';
-import { type CredentialBinding, type CredentialStamp, type PoolRow, type QuotaCodec } from './schema.js';
+import { type CredentialBinding, type CredentialStamp, type PoolRow, type ProviderStateCodec, type QuotaCodec } from './schema.js';
 /** How a row left between the two writes of an operation is completed. */
 export type TornCompletion = {
     kind: 'replace';
@@ -45,4 +45,5 @@ export declare function completeTornRows(config: Record<string, unknown>, state:
  */
 export declare function loadRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {
     requireCredentialStamps?: boolean;
+    providerState?: ProviderStateCodec;
 }): PoolRow[];

package/dist/store/torn.js

@@ -192,7 +192,10 @@ export function completeTornRows(config, state, codec, options = {}) {
  */
 export function loadRows(config, state, codec, options = {}) {
     const { config: whole, torn } = completeTornRows(config, state, codec, options);
-    const rows = buildRawRows(whole, state, codec);
+    // A torn replace wrote its provider state beside the new credential, under
+    // the stamp naming the new epoch, so the completed row shows the new
+    // credential with the state written for it, never with the old one.
+    const rows = buildRawRows(whole, state, codec, options.providerState);
     for (const row of rows) {
         if (torn.includes(row.id)) {
             row.torn = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.5.0",
+  "version": "0.6.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": {