@cortexkit/common-auth 0.5.0 → 0.7.0

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,31 @@
 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';
+/** Key, inside a credential stamp, of an attributed enable or disable. */
+export declare const TRANSITION_STAMP_KEY = "transition";
+/**
+ * Key, inside a per-row config entry, of the mark of the last transition the
+ * config carries out. Older readers ignore it.
+ */
+export declare const TRANSITION_MARK_KEY = "transitionMark";
+/**
+ * An attributed enable or disable as its state write records it: `mark` is
+ * unique to that write, `enabled` is the flag it sets, and `reason` the
+ * disabled reason (a disable's only).
+ */
+export interface StampedTransition {
+    mark: string;
+    enabled: boolean;
+    reason?: string;
+}
+/**
+ * Carries a transition out in a config being edited: the row's enabled flag
+ * and reason as the transition says, and its mark recorded in the entry (a
+ * row without an entry gets one at epoch 1, as `disableIn` gives it). An
+ * enable then applies the duplicate-identity rule, as every write that
+ * enables an OAuth row with a known identity does: the earlier row in roster
+ * order keeps the identity.
+ */
+export declare function applyTransition(editor: RowEditor, id: string, transition: StampedTransition): void;
 /** How a row left between the two writes of an operation is completed. */
 export type TornCompletion = {
     kind: 'replace';
@@ -9,6 +35,9 @@ export type TornCompletion = {
 } | {
     kind: 'identity';
     identity: string;
+} | {
+    kind: 'transition';
+    transition: StampedTransition;
 };
 /** Rows left between the two writes of an operation, by row id. */
 export declare function tornStamps(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {
@@ -45,4 +74,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

@@ -1,4 +1,4 @@
-import { disableIdentityDuplicates, recordIdentityIn, } from './identity.js';
+import { disableIdentityDuplicates, disableIn, enableIn, recordIdentityIn, } from './identity.js';
 import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, dispatchDigest, entryIn, isRecord, parseStamp, rosterRowIn, setEntryIn, } from './schema.js';
 /*
  * A replace changes both files: the state file gets the new credential and
@@ -46,7 +46,69 @@ import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, dispatchDigest, e
  * exactly (digest and dispatch digest), that names an identity the config
  * does not record; that is completed forward the same way, by recording the
  * identity.
+ *
+ * An attributed `disable` or `enable` that also changes the provider state
+ * follows the same order. Its state write carries the new value and, in the
+ * stamp, the transition (`transition: {mark, enabled, reason?}`, see
+ * `StampedTransition`); its config write then flips the row and records the
+ * transition's mark in the row's entry (`transitionMark`). A stamp bound to
+ * the row (this credential, epoch and identity, the binding that also shows
+ * the provider state beside it) whose transition mark the entry does not
+ * record is such a write stopped between its two writes, and is completed
+ * forward the same way: readers are shown the row disabled or enabled as the
+ * transition says, beside the value written with it. Once the config records
+ * the mark the transition says nothing more, so a later `enable` or
+ * `disable` of the row is never undone by it; a credential write drops it
+ * with the rest of the old stamp.
+ */
+/** Key, inside a credential stamp, of an attributed enable or disable. */
+export const TRANSITION_STAMP_KEY = 'transition';
+/**
+ * Key, inside a per-row config entry, of the mark of the last transition the
+ * config carries out. Older readers ignore it.
  */
+export const TRANSITION_MARK_KEY = 'transitionMark';
+/** The well-formed transition in a raw stamp, or undefined. */
+function stampedTransition(rawStamp) {
+    if (!isRecord(rawStamp))
+        return undefined;
+    const raw = rawStamp[TRANSITION_STAMP_KEY];
+    if (!isRecord(raw))
+        return undefined;
+    if (typeof raw.mark !== 'string' || raw.mark.length === 0)
+        return undefined;
+    if (raw.enabled === true)
+        return { mark: raw.mark, enabled: true };
+    if (raw.enabled === false && typeof raw.reason === 'string')
+        return { mark: raw.mark, enabled: false, reason: raw.reason };
+    return undefined;
+}
+/**
+ * Carries a transition out in a config being edited: the row's enabled flag
+ * and reason as the transition says, and its mark recorded in the entry (a
+ * row without an entry gets one at epoch 1, as `disableIn` gives it). An
+ * enable then applies the duplicate-identity rule, as every write that
+ * enables an OAuth row with a known identity does: the earlier row in roster
+ * order keeps the identity.
+ */
+export function applyTransition(editor, id, transition) {
+    if (transition.enabled)
+        enableIn(editor, id);
+    else
+        disableIn(editor, id, transition.reason ?? '');
+    if (!editor.rosterRow(id))
+        return;
+    const entry = editor.entry(id) ?? {
+        credentialEpoch: 1,
+        needsFirstReading: true,
+    };
+    editor.setEntry(id, { ...entry, [TRANSITION_MARK_KEY]: transition.mark });
+    if (!transition.enabled)
+        return;
+    const row = editor.rows().find((candidate) => candidate.id === id);
+    if (row?.type === 'oauth' && row.identity !== undefined)
+        disableIdentityDuplicates(editor, row.identity);
+}
 /**
  * The credential a torn replace leaves once its config write lands: the
  * credential loaded beside the stamp, with the endpoint the stamp's binding
@@ -122,6 +184,13 @@ export function tornStamps(config, state, codec, options = {}) {
             row.identity === undefined) {
             torn.set(row.id, { kind: 'identity', identity: stamp.binding.identity });
         }
+        else if (stamp.credentialEpoch === epoch &&
+            stamp.binding.identity === row.identity) {
+            const transition = stampedTransition(account[CREDENTIAL_STAMP_KEY]);
+            if (transition &&
+                entryIn(config, row.id)?.[TRANSITION_MARK_KEY] !== transition.mark)
+                torn.set(row.id, { kind: 'transition', transition });
+        }
     }
     return torn;
 }
@@ -175,6 +244,8 @@ export function completeTornRows(config, state, codec, options = {}) {
     for (const [id, completion] of completions) {
         if (completion.kind === 'identity')
             recordIdentityIn(editor, id, completion.identity);
+        else if (completion.kind === 'transition')
+            applyTransition(editor, id, completion.transition);
         else if (completion.stamp.binding.identity !== undefined)
             disableIdentityDuplicates(editor, completion.stamp.binding.identity);
     }
@@ -192,7 +263,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.7.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": {