@cortexkit/common-auth 0.2.5 → 0.2.7

package/dist/commands/seam.js

@@ -0,0 +1,185 @@
+// The one way out of the process for anything the command menu shows. Every
+// payload a renderer receives (the dialog payload and every apply result) is
+// produced here: each part is projected field by field from its definition,
+// so action bodies and stray properties never travel, and the whole payload
+// is then scrubbed of credential-shaped property names as a backstop. Nothing
+// outside this module can build a payload without passing through
+// `dialogPayload` or `applyResult`.
+/** The confirmation shown when an irreversible action names none. */
+export const DEFAULT_IRREVERSIBLE_CONFIRMATION = 'This cannot be undone. Continue?';
+const CREDENTIAL_NAMES = new Set([
+    'access',
+    'refresh',
+    'apikey',
+    'password',
+    'authheader',
+    'credential',
+    'credentials',
+]);
+/**
+ * True for a property name that looks like it holds a secret. Case, `-` and
+ * `_` are ignored, so `api_key`, `API-Key` and `apiKey` all match. Any name
+ * ending in `token`, `key` or `secret` matches: no menu field is named that
+ * way, so a match is a leak whatever the rest of the name says.
+ */
+function isCredentialName(name) {
+    const normalized = name.toLowerCase().replace(/[-_]/g, '');
+    return (CREDENTIAL_NAMES.has(normalized) ||
+        normalized.endsWith('token') ||
+        normalized.endsWith('key') ||
+        normalized.endsWith('secret'));
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** A copy of `value` without credential-shaped properties; their paths go to `found`. */
+function scrub(value, path, found) {
+    if (Array.isArray(value))
+        return value.map((entry, index) => scrub(entry, `${path}[${index}]`, found));
+    if (!isPlainRecord(value))
+        return value;
+    const out = {};
+    for (const [name, entry] of Object.entries(value)) {
+        if (isCredentialName(name)) {
+            found.push(`${path}.${name}`);
+            continue;
+        }
+        Object.defineProperty(out, name, {
+            value: scrub(entry, `${path}.${name}`, found),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return out;
+}
+function sealed(payload, command, logger) {
+    const found = [];
+    const clean = scrub(payload, 'payload', found);
+    if (found.length > 0)
+        logger.warn('credential-shaped field dropped from a command payload', {
+            command,
+            fields: found,
+        });
+    return clean;
+}
+function projectChoice(choice) {
+    return { value: String(choice.value), label: String(choice.label) };
+}
+function projectKnob(knob) {
+    switch (knob.kind) {
+        case 'choice':
+            return {
+                kind: 'choice',
+                id: knob.id,
+                label: knob.label,
+                choices: (knob.choices ?? []).map(projectChoice),
+                ...(knob.value !== undefined ? { value: knob.value } : {}),
+            };
+        case 'toggle':
+            return {
+                kind: 'toggle',
+                id: knob.id,
+                label: knob.label,
+                value: knob.value === true,
+            };
+        case 'number':
+            return {
+                kind: 'number',
+                id: knob.id,
+                label: knob.label,
+                ...(knob.value !== undefined ? { value: knob.value } : {}),
+                ...(knob.min !== undefined ? { min: knob.min } : {}),
+                ...(knob.max !== undefined ? { max: knob.max } : {}),
+                ...(knob.required ? { required: true } : {}),
+            };
+        case 'text':
+            return {
+                kind: 'text',
+                id: knob.id,
+                label: knob.label,
+                ...(knob.value !== undefined ? { value: knob.value } : {}),
+                ...(knob.placeholder !== undefined
+                    ? { placeholder: knob.placeholder }
+                    : {}),
+                ...(knob.masked ? { masked: true } : {}),
+                ...(knob.required ? { required: true } : {}),
+            };
+    }
+}
+/**
+ * The confirmation an action must pass before it runs, or undefined. An
+ * irreversible action always has one, even when its definition (built
+ * outside the type checker) names none.
+ */
+export function confirmationOf(action) {
+    if (action.irreversible === true)
+        return {
+            message: action.confirm || DEFAULT_IRREVERSIBLE_CONFIRMATION,
+            irreversible: true,
+        };
+    if (action.confirm)
+        return { message: action.confirm, irreversible: false };
+    return undefined;
+}
+function projectAction(action) {
+    const confirm = confirmationOf(action);
+    return {
+        id: action.id,
+        label: action.label,
+        ...(action.description !== undefined
+            ? { description: action.description }
+            : {}),
+        knobs: (action.knobs ?? []).map(projectKnob),
+        ...(confirm ? { confirm } : {}),
+    };
+}
+/** The account fields a renderer may show; see `MenuAccount`. */
+export function projectAccount(account) {
+    return {
+        id: account.id,
+        ...(account.label !== undefined ? { label: account.label } : {}),
+        enabled: account.enabled,
+        type: account.type,
+        ...(account.identity !== undefined ? { identity: account.identity } : {}),
+    };
+}
+function projectItem(item) {
+    return {
+        id: item.id,
+        label: item.label,
+        ...(item.detail !== undefined ? { detail: item.detail } : {}),
+        ...(item.account ? { account: projectAccount(item.account) } : {}),
+        ...(item.facts !== undefined ? { facts: item.facts } : {}),
+        actions: (item.actions ?? []).map(projectAction),
+    };
+}
+function projectSection(section) {
+    const { content } = section;
+    return {
+        id: section.id,
+        slot: section.slot,
+        title: section.title,
+        lines: (content.lines ?? []).map(String),
+        items: (content.items ?? []).map(projectItem),
+        actions: (content.actions ?? []).map(projectAction),
+        ...(content.facts !== undefined ? { facts: content.facts } : {}),
+    };
+}
+function projectMenu(command, title, sections) {
+    return { command, title, sections: sections.map(projectSection) };
+}
+/** The payload a host's TUI receives when the slash command opens. */
+export function dialogPayload(command, title, sections, logger) {
+    return sealed({ command, menu: projectMenu(command, title, sections) }, command, logger);
+}
+/** An apply's result: the message and the refreshed menu. */
+export function applyResult(command, title, sections, outcome, logger) {
+    return sealed({
+        command,
+        ok: outcome.ok,
+        text: outcome.text,
+        ...(outcome.needsConfirmation ? { needsConfirmation: true } : {}),
+        menu: projectMenu(command, title, sections),
+    }, command, logger);
+}

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 import type { StoredCredential } from './schema.js';
 /** Every library operation that can fail, as named in the failure value. */
-export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'recordIdentity' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *

package/dist/store/index.d.ts

@@ -14,3 +14,5 @@ export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, Rem
 export type { PullReason } from './runtime.js';
 export type { ApiKeyCredential, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
+export type { PoolSettings, SettingsMutator, SettingsRead, UpdateSettingsOptions, UpdateSettingsResult, } from './settings.js';
+export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/index.js

@@ -3,3 +3,4 @@ export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity
 export { openPoolStore } from './pool.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
+export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/pool.d.ts

@@ -7,6 +7,7 @@ import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from '
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
 import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
 import { type PoolCredential, type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
+import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
 export interface OpenPoolStoreOptions {
     /** The provider every row of this pool belongs to; keys the provider-wide lock. */
     provider: string;
@@ -108,6 +109,17 @@ export interface PoolStore {
      * provider-wide lock. Roster rows and their entries are left unchanged.
      */
     reorder(ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
+    /**
+     * The plugin's settings (since 0.2.6): every top-level key of the config
+     * file except the pool-owned ones (`POOL_OWNED_KEYS`). Never writes.
+     */
+    readSettings(): Promise<SettingsRead>;
+    /**
+     * One locked write of the plugin's settings (since 0.2.6) beside the pool,
+     * in the config file. Refuses a result that sets a pool-owned key
+     * (`invalid-input`). Takes `extraLocks`, then the store locks.
+     */
+    updateSettings(mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;
     recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
         id: string;
         disabled: string[];

package/dist/store/pool.js

@@ -5,6 +5,7 @@ import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
 import { addRow, disableRow, enableRow, recordRowIdentity, removeRow, reorderRows, replaceRow, rotateRow, } from './rows.js';
 import { POOL_SCHEMA_VERSION, } from './schema.js';
+import { readPoolSettings, updatePoolSettings, } from './settings.js';
 /**
  * Process-wide memory per config file: ids whose per-row entry a library
  * write dropped (not reused in this process), and rows a load-time pull
@@ -95,6 +96,8 @@ export function openPoolStore(options) {
         enable: (id, callOptions) => enableRow(rt, id, callOptions),
         remove: (id, callOptions) => removeRow(rt, id, callOptions),
         reorder: (ids, callOptions) => reorderRows(rt, ids, callOptions),
+        readSettings: () => readPoolSettings(rt),
+        updateSettings: (mutator, callOptions) => updatePoolSettings(rt, mutator, callOptions),
         recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
         refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
         recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),

package/dist/store/settings.d.ts

@@ -0,0 +1,63 @@
+import { PoolOperationError } from './errors.js';
+import type { PoolLockSpec } from './refresh-lock.js';
+import type { StoreRuntime } from './runtime.js';
+/**
+ * Top-level config keys the pool owns: the legacy `version`, the legacy
+ * roster (`accounts`) and the pool's own key. A settings write never reads
+ * them into the settings it hands out and refuses a result that sets them,
+ * so the roster and the per-row entries change only through row operations.
+ */
+export declare const POOL_OWNED_KEYS: readonly string[];
+/** The plugin's settings: every top-level config key except the pool-owned ones. */
+export type PoolSettings = Record<string, unknown>;
+export type SettingsRead = {
+    status: 'ready';
+    settings: PoolSettings;
+}
+/**
+ * The config still holds a legacy roster with no pool key. Its settings
+ * read the same way; `updateSettings` refuses until the pool is initialized.
+ */
+ | {
+    status: 'pending-migration';
+    settings: PoolSettings;
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+};
+/**
+ * Receives a private copy of the current settings and either edits it in
+ * place (returning nothing) or returns the complete next settings object.
+ * It runs under the store locks, so it must not call back into the store:
+ * a store operation called from inside it is refused (`PoolReentryError`).
+ */
+export type SettingsMutator = (settings: PoolSettings) => PoolSettings | undefined | Promise<PoolSettings | undefined>;
+/**
+ * Options of `updateSettings`. It names no row, so its failure hook is
+ * handed only the failure; like `reorder` it takes the extra locks, then the
+ * store locks, and no row or provider-wide lock.
+ */
+export interface UpdateSettingsOptions {
+    /** Called once, awaited, on every non-success path, before the extra locks release. */
+    onFailure?: (error: PoolOperationError) => void | Promise<void>;
+    /** Locks taken, in this order, before the store locks. */
+    extraLocks?: readonly PoolLockSpec[];
+}
+export type UpdateSettingsResult = {
+    /** The settings now on disk. */
+    settings: PoolSettings;
+    /** `unchanged` when the mutator left the settings as they were; nothing was written. */
+    outcome: 'updated' | 'unchanged';
+};
+/** Reads the settings without taking a lock or writing anything. */
+export declare function readPoolSettings(rt: StoreRuntime): Promise<SettingsRead>;
+/**
+ * One locked read-modify-write of the plugin's settings in the config file
+ * the pool lives in. The pool must be ready (a pending migration or a load
+ * error refuses before the mutator runs). A mutator result that sets a
+ * pool-owned key refuses (`invalid-input`) with nothing written; a result
+ * equal to the current settings writes nothing. The state file is never
+ * touched, and the pool-owned keys are written back exactly as read.
+ */
+export declare function updatePoolSettings(rt: StoreRuntime, mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;

package/dist/store/settings.js

@@ -0,0 +1,120 @@
+import { isDeepStrictEqual } from 'node:util';
+import { writeJsonAtomic } from '../fs/atomic-write.js';
+import { PoolOperationError } from './errors.js';
+import { assertNotInsideHook, runInsideHook } from './hooks.js';
+import { notReadyError, readPool, runOperation } from './mutate.js';
+import { isRecord, POOL_KEY } from './schema.js';
+/**
+ * Top-level config keys the pool owns: the legacy `version`, the legacy
+ * roster (`accounts`) and the pool's own key. A settings write never reads
+ * them into the settings it hands out and refuses a result that sets them,
+ * so the roster and the per-row entries change only through row operations.
+ */
+export const POOL_OWNED_KEYS = Object.freeze([
+    'version',
+    'accounts',
+    POOL_KEY,
+]);
+function settingsOf(config) {
+    const settings = {};
+    for (const [key, value] of Object.entries(config))
+        if (!POOL_OWNED_KEYS.includes(key))
+            defineKey(settings, key, value);
+    return settings;
+}
+/** Sets a key as an own data property, so a `__proto__` key stays a plain key. */
+function defineKey(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+/**
+ * The next config: the pool-owned keys exactly as read, every settings key
+ * from `next` in its existing position, settings keys `next` dropped left
+ * out, and new settings keys appended.
+ */
+function composeConfig(config, next) {
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (POOL_OWNED_KEYS.includes(key))
+            defineKey(out, key, value);
+        else if (Object.hasOwn(next, key))
+            defineKey(out, key, next[key]);
+    }
+    for (const [key, value] of Object.entries(next))
+        if (!Object.hasOwn(config, key))
+            defineKey(out, key, value);
+    return out;
+}
+function settingsRefusal(message) {
+    return new PoolOperationError({
+        operation: 'updateSettings',
+        phase: 'before-first-write',
+        retryable: false,
+        kind: 'invalid-input',
+        message,
+    });
+}
+/** Reads the settings without taking a lock or writing anything. */
+export async function readPoolSettings(rt) {
+    const result = await readPool(rt.ctx);
+    if (result.status === 'error')
+        return result;
+    return { status: result.status, settings: settingsOf(result.config) };
+}
+/**
+ * One locked read-modify-write of the plugin's settings in the config file
+ * the pool lives in. The pool must be ready (a pending migration or a load
+ * error refuses before the mutator runs). A mutator result that sets a
+ * pool-owned key refuses (`invalid-input`) with nothing written; a result
+ * equal to the current settings writes nothing. The state file is never
+ * touched, and the pool-owned keys are written back exactly as read.
+ */
+export async function updatePoolSettings(rt, mutator, options = {}) {
+    assertNotInsideHook('updateSettings');
+    const { ctx } = rt;
+    const onFailure = options.onFailure;
+    return runOperation(ctx, 'updateSettings', undefined, onFailure && ((_rowId, error) => onFailure(error)), async (locks, progress) => {
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
+        // `mark` is where the store locks start on the lock stack. They are
+        // released at the end of this block, so `onFailure` runs holding only
+        // the caller's extra locks, as it does for every other store operation.
+        const mark = locks.held.length;
+        try {
+            for (const spec of ctx.storeLocks)
+                await locks.acquire(spec);
+            const result = await readPool(ctx);
+            if (result.status !== 'ready')
+                throw notReadyError(result, 'updateSettings', undefined);
+            const current = settingsOf(result.config);
+            const draft = structuredClone(current);
+            const returned = await runInsideHook('updateSettings', () => mutator(draft));
+            const next = returned === undefined ? draft : returned;
+            if (!isRecord(next))
+                throw settingsRefusal('the settings mutator must produce an object');
+            const owned = POOL_OWNED_KEYS.filter((key) => Object.hasOwn(next, key));
+            if (owned.length > 0)
+                throw settingsRefusal(`settings cannot set the pool-owned key(s) ${owned.join(', ')}`);
+            if (isDeepStrictEqual(next, current))
+                return { settings: current, outcome: 'unchanged' };
+            const config = composeConfig(result.config, next);
+            const info = { operation: 'updateSettings', rowId: undefined };
+            await writeJsonAtomic(ctx.configPath, config, {
+                beforeRename: async () => {
+                    await ctx.onStep?.('before-config-write', info);
+                    await locks.assertAll();
+                },
+            });
+            progress.writes++;
+            await ctx.onStep?.('after-config-write', info);
+            return { settings: settingsOf(config), outcome: 'updated' };
+        }
+        finally {
+            await locks.releaseTo(mark);
+        }
+    });
+}

package/package.json

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