@cortexkit/common-auth 0.5.0 → 0.7.0

package/dist/store/rows.js

@@ -1,10 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
-import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
+import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enableIn, recordIdentityIn, } from './identity.js';
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
+import { acceptProviderState, mergedProviderState, planProviderStateIn, 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 { bindReplacement } from './torn.js';
+import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, PROVIDER_STATE_KEY, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
+import { applyTransition, bindReplacement, TRANSITION_STAMP_KEY, } from './torn.js';
 /** Fields of a state entry that belong to the credential it replaces. */
 const CREDENTIAL_STATE_FIELDS = [
     'access',
@@ -90,6 +92,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 +114,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 +144,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 +188,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 +216,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 +251,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 +288,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 +307,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 +327,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 +353,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 +368,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 +396,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) {
@@ -367,72 +421,154 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
     });
 }
 /**
- * Marks a row disabled. Since 0.2.3 it takes the row lock and the caller's
- * extra locks before the store locks, as the other row writes do, so it waits
- * for a refresh of the row instead of landing during its provider call.
+ * `disable` and `enable` in one place. Takes the row lock, then the extra
+ * locks, then the store locks, as every row write does, so it waits for a
+ * refresh of the row instead of landing during its provider call.
+ *
+ * With a provider-state mutator that changes the value, the transition is
+ * written as a replace is: the state file first, carrying the value and, in
+ * the stamp, the transition itself; then the config, flipping the row and
+ * recording the transition's mark (see `torn.ts`). A stop between the two
+ * leaves a row every reader shows transitioned beside its new value. When
+ * the config already says what the transition would write (an `enable` of
+ * an enabled row), the value alone is written, in one state write.
  */
-export async function disableRow(rt, id, reason, options = {}) {
-    assertNotInsideHook('disable');
-    return runOperation(rt.ctx, 'disable', id, options.onFailure, async (locks, progress) => {
-        const { row: seen } = await readRow(rt, 'disable', id);
+async function transitionRow(rt, operation, id, flag, options) {
+    assertNotInsideHook(operation);
+    const { ctx } = rt;
+    const codec = ctx.providerState;
+    const fence = options.attribution;
+    const mutator = options.providerState;
+    return runOperation(ctx, operation, id, options.onFailure, async (locks, progress) => {
+        if (fence !== undefined &&
+            !isCredentialEpoch(isRecord(fence) ? fence.credentialEpoch : undefined))
+            throw refusal(operation, id, 'invalid-input', 'the attribution must name a credential epoch that is a positive safe integer');
+        if (mutator !== undefined) {
+            if (typeof mutator !== 'function')
+                throw refusal(operation, id, 'invalid-input', 'the provider-state mutator must be a function');
+            // A provider-state value belongs to one credential, so a change to
+            // it must say which credential it was decided for.
+            if (fence === undefined)
+                throw refusal(operation, id, 'invalid-input', 'a provider-state change needs the attribution of the credential it is for');
+            if (!codec)
+                throw refusal(operation, id, 'invalid-input', 'the store was opened without a provider-state codec');
+        }
+        const { row: seen } = await readRow(rt, operation, id);
         await locks.acquire(rowLockSpec(rt, seen));
         for (const extra of options.extraLocks ?? [])
             await locks.acquire(extra);
-        return withTransaction(rt.ctx, locks, progress, { operation: 'disable', rowId: id }, async (tx) => {
-            const row = tx.row(id);
+        return withTransaction(ctx, locks, progress, { operation, rowId: id }, async (tx) => {
+            const loaded = tx.row(id);
+            const row = flag.enabled
+                ? requireUsableRow('enable', id, loaded)
+                : loaded;
             if (!row || !tx.rosterRow(id))
-                throw unknownRow('disable', id);
+                throw unknownRow(operation, id);
             if (rowLockKey(row) !== rowLockKey(seen))
-                throw keyChanged('disable', id);
-            disableIn(tx, id, reason);
+                throw keyChanged(operation, id);
+            if (fence !== undefined) {
+                // An invalid entry has no epoch to compare the fence with.
+                if (row.invalid)
+                    throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
+                if ((row.credentialEpoch ?? 1) !== fence.credentialEpoch ||
+                    row.identity !== fence.identity)
+                    throw refusal(operation, id, 'attribution', `the ${operation} of ${id} was issued for a credential or account the row no longer holds`, true);
+            }
+            // An enable of a row that is already enabled has nothing to write
+            // to the config; a disable always rewrites it, as it always has.
+            const writesConfig = !flag.enabled || !row.enabled || row.disabledReason !== undefined;
+            if (flag.enabled && writesConfig && row.type === 'oauth') {
+                const holder = row.identity === undefined
+                    ? undefined
+                    : tx
+                        .rows()
+                        .find((other) => other.id !== id &&
+                        other.invalid === undefined &&
+                        other.type === 'oauth' &&
+                        other.enabled &&
+                        other.identity === row.identity);
+                if (holder)
+                    throw refusal('enable', id, 'duplicate-identity', `row ${holder.id} is enabled with the same identity as row ${id}`);
+            }
+            if (mutator === undefined || codec === undefined) {
+                if (!writesConfig)
+                    return { id };
+                if (flag.enabled)
+                    enableIn(tx, id);
+                else
+                    disableIn(tx, id, flag.reason);
+                await tx.commitConfig();
+                return { id };
+            }
+            if (!row.credential)
+                throw refusal(operation, id, 'no-credential', `row ${id} holds no credential`);
+            // A strict store refuses here, but not for an attribution alone:
+            // disabling or enabling a row whose credential the store cannot
+            // prove is harmless (an unbound row is never a candidate), while
+            // writing a provider state would vouch for that credential.
+            requireBound(operation, row);
+            const plan = await planProviderStateIn(tx, codec, operation, row, mutator, true);
+            if (plan.kind === 'declined')
+                return { id, declined: true };
+            const result = {
+                id,
+                providerStateOutcome: plan.kind === 'unchanged'
+                    ? 'unchanged'
+                    : plan.value === undefined
+                        ? 'cleared'
+                        : 'updated',
+                ...(plan.value !== undefined ? { providerState: plan.value } : {}),
+            };
+            if (plan.kind === 'unchanged') {
+                if (writesConfig) {
+                    if (flag.enabled)
+                        enableIn(tx, id);
+                    else
+                        disableIn(tx, id, flag.reason);
+                    await tx.commitConfig();
+                }
+                return result;
+            }
+            if (!writesConfig) {
+                tx.setStateAccount(id, plan.account);
+                await tx.commitState();
+                return result;
+            }
+            const transition = flag.enabled
+                ? { mark: randomUUID(), enabled: true }
+                : { mark: randomUUID(), enabled: false, reason: flag.reason };
+            const stamp = plan.account[CREDENTIAL_STAMP_KEY];
+            tx.setStateAccount(id, {
+                ...plan.account,
+                [CREDENTIAL_STAMP_KEY]: {
+                    ...stamp,
+                    [TRANSITION_STAMP_KEY]: transition,
+                },
+            });
+            await tx.commitState();
+            applyTransition(tx, id, transition);
             await tx.commitConfig();
-            return { id };
+            return result;
         });
     });
 }
+/**
+ * Marks a row disabled with a reason. See `RowTransitionOptions` for the
+ * attributed form, which may change the provider state with it.
+ */
+export function disableRow(rt, id, reason, options = {}) {
+    return transitionRow(rt, 'disable', id, { enabled: false, reason }, options);
+}
 /**
  * Clears a row's `enabled: false` and its `disabledReason` in one config
  * write. An OAuth row whose recorded identity another enabled OAuth row holds
  * stays disabled and the call refuses (`duplicate-identity`): the same rule
  * that makes `add` store such a row disabled. Enabling a row that is already
- * enabled writes nothing.
+ * enabled writes nothing. See `RowTransitionOptions` for the attributed
+ * form, which may change the provider state with it.
  */
-export async function enableRow(rt, id, options = {}) {
-    assertNotInsideHook('enable');
-    return runOperation(rt.ctx, 'enable', id, options.onFailure, async (locks, progress) => {
-        const { row: seen } = await readRow(rt, 'enable', id);
-        await locks.acquire(rowLockSpec(rt, seen));
-        for (const extra of options.extraLocks ?? [])
-            await locks.acquire(extra);
-        return withTransaction(rt.ctx, locks, progress, { operation: 'enable', rowId: id }, async (tx) => {
-            const row = requireUsableRow('enable', id, tx.row(id));
-            if (rowLockKey(row) !== rowLockKey(seen))
-                throw keyChanged('enable', id);
-            if (row.enabled && row.disabledReason === undefined)
-                return { id };
-            if (row.type === 'oauth' && row.identity !== undefined) {
-                const holder = tx
-                    .rows()
-                    .find((other) => other.id !== id &&
-                    other.invalid === undefined &&
-                    other.type === 'oauth' &&
-                    other.enabled &&
-                    other.identity === row.identity);
-                if (holder)
-                    throw refusal('enable', id, 'duplicate-identity', `row ${holder.id} is enabled with the same identity as row ${id}`);
-            }
-            const raw = tx.rosterRow(id);
-            raw.enabled = true;
-            const entry = tx.entry(id);
-            if (entry && 'disabledReason' in entry) {
-                const next = { ...entry };
-                delete next.disabledReason;
-                tx.setEntry(id, next);
-            }
-            await tx.commitConfig();
-            return { id };
-        });
-    });
+export function enableRow(rt, id, options = {}) {
+    return transitionRow(rt, 'enable', id, { enabled: true }, options);
 }
 /**
  * Deletes a row: its roster row and per-row entry (quota, epoch; the identity

package/dist/store/schema.d.ts

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