@cortexkit/common-auth 0.3.0 → 0.4.1

package/dist/store/schema.d.ts

@@ -25,6 +25,14 @@ export type ApiKeyCredential = {
     authHeader?: 'authorization-bearer' | 'x-api-key';
 };
 export type PoolCredential = OAuthCredential | ApiKeyCredential;
+/**
+ * What `rotate` takes. Rotation refreshes the secret of the endpoint a row
+ * already has, so an API key may leave out `baseURL` (and `authHeader`) to
+ * keep the row's; one it gives must equal the row's.
+ */
+export type RotateCredential = OAuthCredential | (Omit<ApiKeyCredential, 'baseURL'> & {
+    baseURL?: string;
+});
 /** A credential as stored: an OAuth credential also carries its refresh stamp. */
 export type StoredCredential = (OAuthCredential & {
     lastRefreshedAt?: number;
@@ -58,6 +66,41 @@ export interface PoolRow {
     candidate: boolean;
     /** Set when the roster row or the per-row entry failed validation. */
     invalid?: 'roster' | 'entry';
+    /**
+     * Set when a replace stopped between its two writes: the state file holds
+     * the new credential, stamped with the epoch and the identity or endpoint
+     * it belongs to, and the config still holds the replaced row. The row is
+     * shown as the replace leaves it once completed, is never a candidate, and
+     * the next store write on it writes the config to match.
+     */
+    torn?: true;
+}
+/**
+ * Key, inside a state-file account entry, of the stamp naming what the
+ * credential beside it belongs to. Older readers ignore it.
+ */
+export declare const CREDENTIAL_STAMP_KEY = "commonAuthPool";
+/**
+ * The config-side half of a replacement: the identity the new credential
+ * belongs to (absent: none is known) and, for an API key, its endpoint.
+ */
+export interface CredentialBinding {
+    identity?: string;
+    baseURL?: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+}
+/**
+ * Written beside every credential the store puts in the state file. It names
+ * the credential epoch the credential belongs to and a digest of its secret,
+ * so a stamp left beside a credential another writer put there afterwards is
+ * recognisable and ignored. A replace also records the binding it gives the
+ * row, which is what lets a reader complete a replace that stopped after
+ * writing the credential.
+ */
+export interface CredentialStamp {
+    credentialEpoch: number;
+    digest: string;
+    binding?: CredentialBinding;
 }
 export type ConfigClassification = {
     status: 'ready';
@@ -88,6 +131,21 @@ export declare function idProblem(id: unknown): string | undefined;
 /** Same URL rule the older readers apply to an API-key row's `baseURL`. */
 export declare function isValidBaseURL(value: unknown): boolean;
 export declare function fingerprintOf(credential: PoolCredential | StoredCredential): string;
+/**
+ * The digest a credential stamp carries. It is kept apart from the
+ * fingerprint (a different input prefix) so the persisted value is never the
+ * dedupe key.
+ */
+export declare function credentialDigest(credential: PoolCredential | StoredCredential): string;
+export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding?: CredentialBinding): CredentialStamp;
+/**
+ * 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
+ * epoch and nothing could tell the old credential's work from the new one's.
+ */
+export declare function isCredentialEpoch(value: unknown): value is number;
+/** A well-formed stamp, or undefined for anything else (which is ignored). */
+export declare function parseStamp(raw: unknown): CredentialStamp | undefined;
 /** A parsed file, or the reason it could not be parsed. */
 export type FileRead = {
     exists: false;
@@ -102,12 +160,21 @@ export declare function classifyConfig(read: FileRead): ConfigClassification;
 export declare function classifyState(read: FileRead): StateClassification;
 export declare function rosterOf(config: Record<string, unknown>): unknown[];
 export declare function entriesOf(config: Record<string, unknown>): Record<string, unknown>;
+/** The first roster row with this id (the one the pool loads). */
+export declare function rosterRowIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
+/** The per-row entries of a config, created (empty) when absent. */
+export declare function ensureEntries(config: Record<string, unknown>): Record<string, unknown>;
+export declare function entryIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
+/** Sets an entry as an own property, so an id such as `toString` is safe. */
+export declare function setEntryIn(config: Record<string, unknown>, id: string, entry: Record<string, unknown>): void;
 /**
- * Builds the rows of a ready pool. A roster row the older readers would
- * reject, a duplicate id, or a malformed per-row entry makes that one row
- * invalid (never a candidate) and blocks nothing else.
+ * Builds the rows of a ready pool from the files exactly as they are, without
+ * looking at credential stamps (see `loadRows` for the rows every reader
+ * gets). A roster row the older readers would reject, a duplicate id, or a
+ * malformed per-row entry makes that one row invalid (never a candidate) and
+ * blocks nothing else.
  */
-export declare function buildRows(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): PoolRow[];
 /** The row-lock key: recorded wire identity when known, else the local id. */
 export declare function rowLockKey(row: Pick<PoolRow, 'id' | 'identity'>): string;
 /**
@@ -130,4 +197,6 @@ export declare function rosterRowFor(input: {
 /** The state-file fields a credential occupies, in the older readers' names. */
 export declare function stateFieldsFor(credential: PoolCredential, lastRefreshedAt: number | undefined): Record<string, unknown>;
 export declare function storedCredential(credential: PoolCredential, lastRefreshedAt: number | undefined): StoredCredential;
-export declare function credentialProblem(credential: unknown): string | undefined;
+export declare function credentialProblem(credential: unknown, options?: {
+    baseURLOptional?: boolean;
+}): string | undefined;

package/dist/store/schema.js

@@ -13,6 +13,11 @@ export const LEGACY_STORE_VERSION = 1;
  * strictly above it counts as absent when they compare two copies of a token.
  */
 export const REFRESH_STAMP_TOLERANCE_MS = 5 * 60_000;
+/**
+ * Key, inside a state-file account entry, of the stamp naming what the
+ * credential beside it belongs to. Older readers ignore it.
+ */
+export const CREDENTIAL_STAMP_KEY = POOL_KEY;
 export function isRecord(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -46,11 +51,78 @@ export function isValidBaseURL(value) {
         return false;
     }
 }
-export function fingerprintOf(credential) {
-    const secret = credential.type === 'oauth'
+function secretOf(credential) {
+    return credential.type === 'oauth'
         ? `oauth\0${credential.refresh}`
         : `api\0${credential.apiKey}`;
-    return createHash('sha256').update(secret).digest('hex');
+}
+export function fingerprintOf(credential) {
+    return createHash('sha256').update(secretOf(credential)).digest('hex');
+}
+/**
+ * The digest a credential stamp carries. It is kept apart from the
+ * fingerprint (a different input prefix) so the persisted value is never the
+ * dedupe key.
+ */
+export function credentialDigest(credential) {
+    return createHash('sha256')
+        .update(`credential-stamp\0${secretOf(credential)}`)
+        .digest('hex');
+}
+export function stampFor(credential, credentialEpoch, binding) {
+    return {
+        credentialEpoch,
+        digest: credentialDigest(credential),
+        ...(binding ? { binding: { ...binding } } : {}),
+    };
+}
+/**
+ * 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
+ * epoch and nothing could tell the old credential's work from the new one's.
+ */
+export function isCredentialEpoch(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+/** A well-formed stamp, or undefined for anything else (which is ignored). */
+export function parseStamp(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const epoch = raw.credentialEpoch;
+    if (!isCredentialEpoch(epoch))
+        return undefined;
+    if (typeof raw.digest !== 'string')
+        return undefined;
+    if (!('binding' in raw))
+        return { credentialEpoch: epoch, digest: raw.digest };
+    const binding = raw.binding;
+    if (!isRecord(binding))
+        return undefined;
+    if ('identity' in binding &&
+        (typeof binding.identity !== 'string' || !binding.identity))
+        return undefined;
+    if ('baseURL' in binding && !isValidBaseURL(binding.baseURL))
+        return undefined;
+    if ('authHeader' in binding &&
+        binding.authHeader !== 'authorization-bearer' &&
+        binding.authHeader !== 'x-api-key')
+        return undefined;
+    return {
+        credentialEpoch: epoch,
+        digest: raw.digest,
+        binding: {
+            ...(typeof binding.identity === 'string'
+                ? { identity: binding.identity }
+                : {}),
+            ...(typeof binding.baseURL === 'string'
+                ? { baseURL: binding.baseURL.trim() }
+                : {}),
+            ...(binding.authHeader === 'authorization-bearer' ||
+                binding.authHeader === 'x-api-key'
+                ? { authHeader: binding.authHeader }
+                : {}),
+        },
+    };
 }
 export function classifyConfig(read) {
     if (!read.exists)
@@ -126,7 +198,7 @@ function parseEntry(raw, codec) {
     if (!isRecord(raw))
         return undefined;
     const epoch = raw.credentialEpoch;
-    if (typeof epoch !== 'number' || !Number.isInteger(epoch) || epoch < 1)
+    if (!isCredentialEpoch(epoch))
         return undefined;
     if ('needsFirstReading' in raw && typeof raw.needsFirstReading !== 'boolean')
         return undefined;
@@ -176,12 +248,41 @@ function credentialFor(raw, stateEntry) {
             : {}),
     };
 }
+/** The first roster row with this id (the one the pool loads). */
+export function rosterRowIn(config, id) {
+    return rosterOf(config).find((raw) => isRecord(raw) && raw.id === id);
+}
+/** The per-row entries of a config, created (empty) when absent. */
+export function ensureEntries(config) {
+    if (!isRecord(config[POOL_KEY]))
+        config[POOL_KEY] = {};
+    const pool = config[POOL_KEY];
+    if (!isRecord(pool[POOL_ROWS_KEY]))
+        pool[POOL_ROWS_KEY] = {};
+    return pool[POOL_ROWS_KEY];
+}
+export function entryIn(config, id) {
+    const entries = entriesOf(config);
+    const entry = Object.hasOwn(entries, id) ? entries[id] : undefined;
+    return isRecord(entry) ? entry : undefined;
+}
+/** Sets an entry as an own property, so an id such as `toString` is safe. */
+export function setEntryIn(config, id, entry) {
+    Object.defineProperty(ensureEntries(config), id, {
+        value: entry,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
 /**
- * Builds the rows of a ready pool. A roster row the older readers would
- * reject, a duplicate id, or a malformed per-row entry makes that one row
- * invalid (never a candidate) and blocks nothing else.
+ * Builds the rows of a ready pool from the files exactly as they are, without
+ * looking at credential stamps (see `loadRows` for the rows every reader
+ * gets). A roster row the older readers would reject, a duplicate id, or a
+ * malformed per-row entry makes that one row invalid (never a candidate) and
+ * blocks nothing else.
  */
-export function buildRows(config, state, codec) {
+export function buildRawRows(config, state, codec) {
     const entries = entriesOf(config);
     const stateAccounts = stateAccountsOf(state);
     const seen = new Set();
@@ -302,7 +403,7 @@ export function storedCredential(credential, lastRefreshedAt) {
         ...(lastRefreshedAt !== undefined ? { lastRefreshedAt } : {}),
     };
 }
-export function credentialProblem(credential) {
+export function credentialProblem(credential, options = {}) {
     if (!isRecord(credential))
         return 'credential must be an object';
     if (credential.type === 'oauth') {
@@ -315,7 +416,8 @@ export function credentialProblem(credential) {
             return 'api credential needs an api key';
         if (credential.apiKey.trim() !== credential.apiKey)
             return 'api key must not carry surrounding whitespace';
-        if (!isValidBaseURL(credential.baseURL))
+        const omitted = options.baseURLOptional && credential.baseURL === undefined;
+        if (!omitted && !isValidBaseURL(credential.baseURL))
             return 'api credential needs a valid baseURL';
         return undefined;
     }

package/dist/store/torn.d.ts

@@ -0,0 +1,29 @@
+import { type RowEditor } from './identity.js';
+import { type CredentialBinding, type CredentialStamp, type PoolRow, type QuotaCodec } from './schema.js';
+/** Stamps of rows torn between the two writes of a replace, by row id. */
+export declare function tornStamps(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): Map<string, CredentialStamp & {
+    binding: CredentialBinding;
+}>;
+/**
+ * The config half of a replacement: the row's entry moves to the new epoch,
+ * loses its quota and needs a first reading; its roster row gets the new
+ * identity (or loses the old one) and, for an API key, the new endpoint.
+ * Disabling later rows that share the new identity is left to the caller
+ * (`disableIdentityDuplicates`), so several rows can be bound first.
+ */
+export declare function bindReplacement(editor: RowEditor, id: string, credentialEpoch: number, binding: CredentialBinding): void;
+/**
+ * The config with every torn row completed as its replace would have left
+ * it, and the ids completed. The config passed in is not modified; when
+ * nothing is torn it is returned as is.
+ */
+export declare function completeTornRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): {
+    config: Record<string, unknown>;
+    torn: string[];
+};
+/**
+ * The rows every reader gets. A torn row is shown completed (the identity,
+ * endpoint and epoch its stamp names, beside the credential it stamps), is
+ * marked `torn` and is never a candidate; every other row is as on disk.
+ */
+export declare function loadRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];

package/dist/store/torn.js

@@ -0,0 +1,113 @@
+import { disableIdentityDuplicates } from './identity.js';
+import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, entryIn, isRecord, parseStamp, rosterRowIn, setEntryIn, } from './schema.js';
+/*
+ * A replace changes both files: the state file gets the new credential and
+ * the config gets the new epoch, identity or endpoint. It writes the state
+ * file first, stamping the credential with the epoch it belongs to and the
+ * binding (identity, endpoint) the config is about to get. A crash between
+ * the two writes therefore leaves a credential whose stamp is ahead of the
+ * config's epoch, and that is how every reader tells such a torn row from a
+ * whole one. The stamp holds everything the config write would have written,
+ * so a torn row is completed forward: readers are shown the completed row
+ * (never a candidate until it is on disk) and the next store write on it
+ * writes the config to match.
+ *
+ * A stamp counts only beside the credential it was written with (its digest
+ * matches): a writer that does not know about stamps may put another
+ * credential beside an old one, and that stamp then says nothing. A stamp at
+ * or behind the config's epoch is never torn: this store's own writes leave
+ * the state file ahead of the config, never behind it.
+ */
+/** Stamps of rows torn between the two writes of a replace, by row id. */
+export function tornStamps(config, state, codec) {
+    const accounts = isRecord(state.accounts) ? state.accounts : {};
+    const torn = new Map();
+    for (const row of buildRawRows(config, state, codec)) {
+        if (row.invalid || !row.credential)
+            continue;
+        const account = Object.hasOwn(accounts, row.id)
+            ? accounts[row.id]
+            : undefined;
+        if (!isRecord(account))
+            continue;
+        const stamp = parseStamp(account[CREDENTIAL_STAMP_KEY]);
+        if (!stamp?.binding)
+            continue;
+        if (stamp.digest !== credentialDigest(row.credential))
+            continue;
+        // A row without an entry is at epoch 1, as everywhere else.
+        if (stamp.credentialEpoch <= (row.credentialEpoch ?? 1))
+            continue;
+        torn.set(row.id, { ...stamp, binding: stamp.binding });
+    }
+    return torn;
+}
+/**
+ * The config half of a replacement: the row's entry moves to the new epoch,
+ * loses its quota and needs a first reading; its roster row gets the new
+ * identity (or loses the old one) and, for an API key, the new endpoint.
+ * Disabling later rows that share the new identity is left to the caller
+ * (`disableIdentityDuplicates`), so several rows can be bound first.
+ */
+export function bindReplacement(editor, id, credentialEpoch, binding) {
+    const entry = editor.entry(id) ?? {};
+    const next = {
+        ...entry,
+        credentialEpoch,
+        needsFirstReading: true,
+    };
+    delete next.quota;
+    editor.setEntry(id, next);
+    const raw = editor.rosterRow(id);
+    if (!raw)
+        return;
+    if (binding.identity !== undefined)
+        raw.accountId = binding.identity;
+    else
+        delete raw.accountId;
+    if (binding.baseURL !== undefined)
+        raw.baseURL = binding.baseURL;
+    if (binding.authHeader !== undefined)
+        raw.authHeader = binding.authHeader;
+}
+/**
+ * The config with every torn row completed as its replace would have left
+ * it, and the ids completed. The config passed in is not modified; when
+ * nothing is torn it is returned as is.
+ */
+export function completeTornRows(config, state, codec) {
+    const stamps = tornStamps(config, state, codec);
+    if (stamps.size === 0)
+        return { config, torn: [] };
+    const next = structuredClone(config);
+    const editor = {
+        rows: () => buildRawRows(next, state, codec),
+        rosterRow: (id) => rosterRowIn(next, id),
+        entry: (id) => entryIn(next, id),
+        setEntry: (id, entry) => setEntryIn(next, id, entry),
+    };
+    for (const [id, stamp] of stamps)
+        bindReplacement(editor, id, stamp.credentialEpoch, stamp.binding);
+    for (const stamp of stamps.values())
+        if (stamp.binding.identity !== undefined)
+            disableIdentityDuplicates(editor, stamp.binding.identity);
+    return { config: next, torn: [...stamps.keys()] };
+}
+/**
+ * The rows every reader gets. A torn row is shown completed (the identity,
+ * endpoint and epoch its stamp names, beside the credential it stamps), is
+ * marked `torn` and is never a candidate; every other row is as on disk.
+ */
+export function loadRows(config, state, codec) {
+    const { config: whole, torn } = completeTornRows(config, state, codec);
+    const rows = buildRawRows(whole, state, codec);
+    if (torn.length === 0)
+        return rows;
+    for (const row of rows) {
+        if (!torn.includes(row.id))
+            continue;
+        row.torn = true;
+        row.candidate = false;
+    }
+    return rows;
+}

package/package.json

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