@cortexkit/common-auth 0.5.0 → 0.7.0

package/dist/store/provider-state.js

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

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, type RowTransitionMutator, type UpdateProviderStateResult } from './provider-state.js';
 import type { PoolLockSpec } from './refresh-lock.js';
 import { type StoreRuntime } from './runtime.js';
 import { type CredentialBinding, type PoolCredential, type PoolRow, type RotateCredential, type StoredCredential } from './schema.js';
@@ -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,39 +121,70 @@ 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;
 }>;
 /**
- * Marks a row disabled. Since 0.2.3 it takes the row lock and the caller's
- * extra locks before the store locks, as the other row writes do, so it waits
- * for a refresh of the row instead of landing during its provider call.
+ * Options of `disable` and `enable`. A call that passes neither
+ * `attribution` nor `providerState` behaves exactly as it did before 0.7.0.
  */
-export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: RowToggleOptions): Promise<{
+export interface RowTransitionOptions extends RowToggleOptions {
+    /**
+     * The credential epoch and recorded identity the caller's evidence for the
+     * transition was obtained under (as `recordQuota`'s attribution: an
+     * identity left out means the row had none). The call is refused
+     * (`attribution`, retryable, nothing written) once the row holds another
+     * epoch or identity, so a provider's late answer about a replaced
+     * credential never disables, or switches back on, the row now holding its
+     * successor.
+     */
+    attribution?: Attribution;
+    /**
+     * A provider-state change made in the same transaction as the transition,
+     * under the rules of `updateProviderState` (codec validation, the stamp
+     * rebound to the value, `unbound-credential` for a row no stamp of this
+     * store can bind it to); it requires `attribution`. The value and the
+     * enabled flag land together: no reader, and no crash at any write point,
+     * shows one without the other. Returning `DECLINE_TRANSITION` declines the
+     * whole call and writes nothing.
+     */
+    providerState?: RowTransitionMutator;
+}
+export interface RowTransitionResult {
     id: string;
-}>;
+    /** The provider-state mutator declined: nothing was written. */
+    declined?: true;
+    /**
+     * Set when a provider-state mutator ran and did not decline: what it did
+     * to the value, as `updateProviderState` reports it.
+     */
+    providerStateOutcome?: UpdateProviderStateResult['outcome'];
+    /** The provider state the row now holds, when a mutator ran and left one. */
+    providerState?: unknown;
+}
+/**
+ * Marks a row disabled with a reason. See `RowTransitionOptions` for the
+ * attributed form, which may change the provider state with it.
+ */
+export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
 /**
  * Clears a row's `enabled: false` and its `disabledReason` in one config
  * write. An OAuth row whose recorded identity another enabled OAuth row holds
  * stays disabled and the call refuses (`duplicate-identity`): the same rule
  * that makes `add` store such a row disabled. Enabling a row that is already
- * enabled writes nothing.
+ * enabled writes nothing. See `RowTransitionOptions` for the attributed
+ * form, which may change the provider state with it.
  */
-export declare function enableRow(rt: StoreRuntime, id: string, options?: RowToggleOptions): Promise<{
-    id: string;
-}>;
+export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
 /**
  * Deletes a row: its roster row and per-row entry (quota, epoch; the identity
  * lives in the roster row) in one config write, then its credential and