@cortexkit/common-auth 0.6.0 → 0.8.0

package/dist/store/identity.js

@@ -24,6 +24,22 @@ export function disableIn(tx, id, reason) {
     const entry = tx.entry(id) ?? { credentialEpoch: 1, needsFirstReading: true };
     tx.setEntry(id, { ...entry, disabledReason: reason });
 }
+/**
+ * Marks a row enabled: `enabled: true` in the roster row and no
+ * `disabledReason` in its entry. A row without an entry is not given one.
+ */
+export function enableIn(tx, id) {
+    const raw = tx.rosterRow(id);
+    if (!raw)
+        return;
+    raw.enabled = true;
+    const entry = tx.entry(id);
+    if (entry && 'disabledReason' in entry) {
+        const next = { ...entry };
+        delete next.disabledReason;
+        tx.setEntry(id, next);
+    }
+}
 /**
  * Two enabled OAuth rows with one wire identity are the same account: the
  * earlier row in roster order stays enabled and every later one is disabled

package/dist/store/index.d.ts

@@ -6,12 +6,13 @@ 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 { ProviderStateMutator, RowTransitionMutator, UpdateProviderStateResult, } from './provider-state.js';
+export { DECLINE_TRANSITION } 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, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
+export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, } from './rows.js';
 export type { PullReason } from './runtime.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';

package/dist/store/index.js

@@ -1,6 +1,7 @@
 export { PoolOperationError, PoolReentryError } from './errors.js';
 export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
 export { openPoolStore } from './pool.js';
+export { DECLINE_TRANSITION } from './provider-state.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.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

@@ -118,7 +118,11 @@ export declare class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     commitConfig(options?: {
         counted?: boolean;

package/dist/store/mutate.js

@@ -4,7 +4,7 @@ import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
 import { PoolOperationError, } from './errors.js';
 import { callFailureHook } from './hooks.js';
 import { LockStack, } from './refresh-lock.js';
-import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, rosterRowIn, setEntryIn, } from './schema.js';
+import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, retireEpochsIn, rosterOf, rosterRowIn, setEntryIn, } from './schema.js';
 import { completeTornRows, loadRows } from './torn.js';
 async function readJson(path) {
     let text;
@@ -169,7 +169,11 @@ export class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     async commitConfig(options = {}) {
         const roster = this.roster();
@@ -177,6 +181,14 @@ export class Transaction {
         for (const raw of roster)
             if (isRecord(raw) && typeof raw.id === 'string')
                 rosterIds.add(raw.id);
+        const dropped = new Set();
+        for (const raw of rosterOf(this.snapshot.config))
+            if (isRecord(raw) && typeof raw.id === 'string' && !rosterIds.has(raw.id))
+                dropped.add(raw.id);
+        for (const id of Object.keys(this.entries()))
+            if (!rosterIds.has(id))
+                dropped.add(id);
+        retireEpochsIn(this.config, dropped);
         const entries = this.entries();
         const kept = {};
         for (const [id, entry] of Object.entries(entries)) {

package/dist/store/pool.d.ts

@@ -6,7 +6,7 @@ import { type ProviderStateMutator, type UpdateProviderStateResult } from './pro
 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 CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
+import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult } 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 {
@@ -88,6 +88,13 @@ export interface PoolStore {
     }): Promise<{
         status: InitializeOutcome;
     }>;
+    /**
+     * Adds a row, or completes or rotates the row already holding the id or
+     * the secret. A new row starts at credential epoch 1; since 0.8.0 one
+     * whose id the pool held before starts one past the highest epoch that id
+     * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
+     * refuses (`id-removed`) before writing.
+     */
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
     /**
      * Gives a row a new credential and a new credential epoch. Since 0.6.0 the
@@ -119,19 +126,18 @@ export interface PoolStore {
     /**
      * Sets `enabled: false` and the entry's `disabledReason`. Takes the row
      * lock, then `extraLocks`, then the store locks (the row lock and
-     * `extraLocks` since 0.2.3).
+     * `extraLocks` since 0.2.3). Since 0.7.0 it may be fenced on the
+     * credential the caller's evidence is about (`attribution`) and carry a
+     * provider-state change that lands with it (`providerState`); see
+     * `RowTransitionOptions`.
      */
-    disable(id: string, reason: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    disable(id: string, reason: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * Clears `enabled: false` and `disabledReason` (since 0.2.3); refuses with
      * `duplicate-identity` when another enabled OAuth row holds the row's
-     * identity. Locks as `disable`.
+     * identity. Locks as `disable`, and takes the same options since 0.7.0.
      */
-    enable(id: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    enable(id: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * Deletes the roster row, its per-row entry and its state-file credential
      * (since 0.2.3). Locks as `disable`; `protect` can refuse the id.

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

@@ -1,5 +1,6 @@
 import type { Attribution } from './attribution.js';
 import type { PoolOperation } from './errors.js';
+import { type Transaction } from './mutate.js';
 import type { RowToggleOptions } from './rows.js';
 import { type StoreRuntime } from './runtime.js';
 import { type PoolRow, type ProviderStateCodec } from './schema.js';
@@ -84,3 +85,47 @@ export type UpdateProviderStateResult = {
  * `replace` stamps such a row.
  */
 export declare function updateProviderStateRow(rt: StoreRuntime, id: string, fence: Attribution, mutator: ProviderStateMutator, options?: RowToggleOptions): Promise<UpdateProviderStateResult>;
+/**
+ * Returned by the provider-state mutator of an attributed `disable` or
+ * `enable` to decline the whole transition: nothing is written, neither the
+ * provider state nor the row's enabled flag, and the call resolves with
+ * `declined: true`. A mutator declines when the state it is shown is newer
+ * than what its caller saw, such as an eligibility recorded after the
+ * request whose refusal is being acted on. It is a value of its own because
+ * `undefined` already means "clear the provider state". `Symbol.for` keeps it
+ * equal across two copies of this module loaded in one process.
+ */
+export declare const DECLINE_TRANSITION: unique symbol;
+/**
+ * The provider-state mutator of an attributed `disable` or `enable`: as
+ * `ProviderStateMutator`, and it may also return `DECLINE_TRANSITION`.
+ */
+export type RowTransitionMutator = (current: unknown | undefined, row: PoolRow) => unknown | typeof DECLINE_TRANSITION | Promise<unknown | typeof DECLINE_TRANSITION>;
+/**
+ * What a provider-state mutator asks of a row, worked out under the locks
+ * before anything is written. `changed` carries the row's whole next
+ * state-file account entry (the value, and the stamp rebound to it when its
+ * credential-bound part moved); `value` is the next value, absent when it is
+ * cleared.
+ */
+export type ProviderStatePlan = {
+    kind: 'declined';
+} | {
+    kind: 'unchanged';
+    value?: unknown;
+} | {
+    kind: 'changed';
+    value?: unknown;
+    account: Record<string, unknown>;
+};
+/**
+ * Runs a provider-state mutator for a row loaded under every lock and
+ * already checked by the caller (present, valid, inside its attribution
+ * fence), and plans the write. Refuses (`no-credential`) a row holding no
+ * credential, and (`unbound-credential`) one whose credential carries no
+ * stamp of this store at the row's epoch and identity: no stamp could bind
+ * the value, so no reader would ever show it. `DECLINE_TRANSITION` is
+ * honoured only when `declinable` is set; elsewhere it is not JSON and is
+ * refused as such.
+ */
+export declare function planProviderStateIn(tx: Transaction, codec: ProviderStateCodec, operation: PoolOperation, row: PoolRow, mutator: ProviderStateMutator | RowTransitionMutator, declinable?: boolean): Promise<ProviderStatePlan>;

package/dist/store/provider-state.js

@@ -132,55 +132,92 @@ export async function updateProviderStateRow(rt, id, fence, mutator, options = {
             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))
+            const plan = await planProviderStateIn(tx, codec, operation, row, mutator);
+            if (plan.kind !== 'changed')
                 return {
                     id,
                     outcome: 'unchanged',
-                    ...(next !== undefined ? { providerState: next } : {}),
+                    ...(plan.kind === 'unchanged' && plan.value !== undefined
+                        ? { providerState: plan.value }
+                        : {}),
                 };
-            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);
+            tx.setStateAccount(id, plan.account);
             await tx.commitState();
-            return next === undefined
+            return plan.value === undefined
                 ? { id, outcome: 'cleared' }
-                : { id, outcome: 'updated', providerState: next };
+                : { 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/rows.d.ts

@@ -1,7 +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 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';
@@ -134,23 +134,57 @@ export declare function rotateRow(rt: StoreRuntime, id: string, credential: Rota
     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
@@ -158,7 +192,9 @@ export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTog
  * between the two leaves a row every reader already sees as removed, with
  * only an orphaned state entry that no reader loads; calling `remove` again
  * drops that entry (`completed`). As with every id the store drops, the id is
- * not reused by `add` in this process.
+ * not reused by `add` in this process, and the config write records the
+ * row's credential epoch, so an `add` of the id in any other process starts
+ * past it (see `nextAddEpochIn`).
  */
 export declare function removeRow(rt: StoreRuntime, id: string, options?: RemoveOptions): Promise<RemoveResult>;
 /**