@cortexkit/common-auth 0.3.0 → 0.4.1

package/dist/commands/menu.js

@@ -4,7 +4,7 @@
 // caller's context.
 import { createLogger } from '../logger/index.js';
 import { builtinSections, } from './builtins.js';
-import { applyResult, confirmationOf, dialogPayload, } from './seam.js';
+import { applyResult, confirmationOf, createTextRedactor, dialogPayload, projectFailure, } from './seam.js';
 const BUILTIN_IDS = new Set([
     'accounts',
     'quota',
@@ -19,12 +19,16 @@ const BUILTIN_IDS = new Set([
  * reuses and rebinds one context object for the next session cannot pull an
  * earlier invocation's feedback over to it.
  */
-function ownInvocation(invocation) {
+function ownInvocation(invocation, redact) {
     const { sessionId } = invocation;
     const notify = invocation.notify.bind(invocation);
+    // A notification leaves the process just as a payload does, so its text
+    // goes through the same redactor.
     return Object.freeze({
         ...(sessionId !== undefined ? { sessionId } : {}),
-        notify,
+        notify: (message, kind) => kind === undefined
+            ? notify(redact(String(message)))
+            : notify(redact(String(message)), kind),
     });
 }
 function coerceOne(knob, raw) {
@@ -94,6 +98,8 @@ function findAction(sections, request) {
 }
 export function createCommandMenu(options) {
     const logger = options.logger ?? createLogger('commands');
+    const redact = createTextRedactor(options.redaction);
+    const seam = { logger, redact };
     const now = options.now ?? Date.now;
     const extras = options.extras ?? [];
     const seen = new Set();
@@ -116,7 +122,7 @@ export function createCommandMenu(options) {
             logger.warn('command menu section failed to build', {
                 command: options.command,
                 section: id,
-                error: error instanceof Error ? error.message : String(error),
+                error: redact(error instanceof Error ? error.message : String(error)),
             });
             return {
                 id,
@@ -148,30 +154,36 @@ export function createCommandMenu(options) {
     return {
         command: options.command,
         async open(invocation) {
-            const own = ownInvocation(invocation);
-            return dialogPayload(options.command, options.title, await sections(own), logger);
+            const own = ownInvocation(invocation, redact);
+            return dialogPayload(options.command, options.title, await sections(own), seam);
         },
         async apply(request, invocation) {
-            const own = ownInvocation(invocation);
-            const finish = async (outcome) => applyResult(options.command, options.title, await sections(own), outcome, logger);
+            const own = ownInvocation(invocation, redact);
+            const finish = async (outcome) => applyResult(options.command, options.title, await sections(own), outcome, seam);
             const action = request.command === options.command
                 ? findAction(await sections(own), request)
                 : undefined;
             if (!action)
                 return finish({
                     ok: false,
+                    code: 'unavailable',
                     text: 'That action is no longer available.',
                 });
             const confirmation = confirmationOf(action);
             if (confirmation && request.confirmed !== true)
                 return finish({
                     ok: false,
+                    code: 'needs-confirmation',
                     text: confirmation.message,
                     needsConfirmation: true,
                 });
             const coerced = coerceValues(action.knobs ?? [], request.values);
             if ('problem' in coerced)
-                return finish({ ok: false, text: coerced.problem });
+                return finish({
+                    ok: false,
+                    code: 'invalid-input',
+                    text: coerced.problem,
+                });
             let outcome;
             try {
                 const result = await action.run({
@@ -180,17 +192,26 @@ export function createCommandMenu(options) {
                     invocation: own,
                 });
                 outcome =
-                    typeof result === 'string' ? { ok: true, text: result } : result;
+                    typeof result === 'string'
+                        ? { ok: true, text: result }
+                        : {
+                            ok: result.ok,
+                            text: result.text,
+                            ...(result.ok ? {} : { code: result.code ?? 'refused' }),
+                        };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                // The raw text goes only to the log (redacted); the user sees the
+                // projected code and message, never the exception's own words.
+                const failure = projectFailure(error);
                 logger.warn('command menu action failed', {
                     command: options.command,
                     section: request.sectionId,
                     action: request.actionId,
-                    error: message,
+                    code: failure.code,
+                    error: redact(error instanceof Error ? error.message : String(error)),
                 });
-                outcome = { ok: false, text: message };
+                outcome = { ok: false, ...failure };
             }
             return finish(outcome);
         },

package/dist/commands/model.d.ts

@@ -120,6 +120,13 @@ export interface CommandApplyResult {
     command: string;
     ok: boolean;
     text: string;
+    /**
+     * A stable code naming why the apply failed; present on every failure.
+     * The library's own codes are `unavailable`, `needs-confirmation`,
+     * `invalid-input`, `refused`, `action-failed` and `pool-<store failure
+     * kind>`; a plugin's `CommandError` or `ActionOutcome` names its own.
+     */
+    code?: string;
     /** True when the action was refused only for want of a confirmation. */
     needsConfirmation?: boolean;
     menu: CommandMenuModel;
@@ -138,6 +145,8 @@ export interface CommandInvocation {
 export interface ActionOutcome {
     ok: boolean;
     text: string;
+    /** The failure's stable code; a failure without one is `refused`. */
+    code?: string;
 }
 export interface ActionInput {
     values: KnobValues;

package/dist/commands/seam.d.ts

@@ -1,8 +1,35 @@
+import { type RedactionOptions } from '../logger/index.js';
 import type { ActionDefinition, CommandApplyResult, CommandDialogPayload, ItemDefinition, MenuAccount, MenuConfirmation, SectionContent, SectionSlot } from './model.js';
 /** Where a dropped field is reported. Names only, never values. */
 export interface SeamLogger {
     warn(message: string, data?: unknown): void;
 }
+/** Masks the secret-shaped parts of one string. */
+export type TextRedactor = (text: string) => string;
+/** The string redactor every value crossing the seam goes through. */
+export declare function createTextRedactor(options?: RedactionOptions): TextRedactor;
+/**
+ * A failure whose message was written for the user. An action throws it to
+ * show `message` with the stable `code`; any other thrown value is shown only
+ * as a generic message, because its text may quote a request, a response or
+ * a credential. `code` is lowercase letters, digits and dashes; anything else
+ * is reported as `action-failed`.
+ */
+export declare class CommandError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** What a failed action shows: a stable code and a message safe to display. */
+export interface ProjectedFailure {
+    code: string;
+    text: string;
+}
+/** The code and message shown for an exception the seam cannot vouch for. */
+export declare const ACTION_FAILED: ProjectedFailure;
+/** The code and display text for a thrown value; never its raw text. */
+export declare function projectFailure(error: unknown): ProjectedFailure;
 /** A built-in item may carry the account it shows; plugin items cannot. */
 export interface ResolvedItem extends ItemDefinition {
     account?: MenuAccount;
@@ -18,6 +45,11 @@ export interface ResolvedSection {
 }
 /** The confirmation shown when an irreversible action names none. */
 export declare const DEFAULT_IRREVERSIBLE_CONFIRMATION = "This cannot be undone. Continue?";
+/** What every payload builder needs besides the payload itself. */
+export interface SeamContext {
+    logger: SeamLogger;
+    redact: TextRedactor;
+}
 /**
  * The confirmation an action must pass before it runs, or undefined. An
  * irreversible action always has one, even when its definition (built
@@ -27,10 +59,14 @@ export declare function confirmationOf(action: ActionDefinition): MenuConfirmati
 /** The account fields a renderer may show; see `MenuAccount`. */
 export declare function projectAccount(account: MenuAccount): MenuAccount;
 /** The payload a host's TUI receives when the slash command opens. */
-export declare function dialogPayload(command: string, title: string, sections: readonly ResolvedSection[], logger: SeamLogger): CommandDialogPayload;
-/** An apply's result: the message and the refreshed menu. */
-export declare function applyResult(command: string, title: string, sections: readonly ResolvedSection[], outcome: {
+export declare function dialogPayload(command: string, title: string, sections: readonly ResolvedSection[], seam: SeamContext): CommandDialogPayload;
+/** How an apply ended, before the seam turns it into a payload. */
+export interface ApplyOutcome {
     ok: boolean;
     text: string;
+    /** Present on every failure. */
+    code?: string;
     needsConfirmation?: boolean;
-}, logger: SeamLogger): CommandApplyResult;
+}
+/** An apply's result: the message and the refreshed menu. */
+export declare function applyResult(command: string, title: string, sections: readonly ResolvedSection[], outcome: ApplyOutcome, seam: SeamContext): CommandApplyResult;

package/dist/commands/seam.js

@@ -2,9 +2,97 @@
 // 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
+// is then scrubbed as a backstop: credential-shaped property names are
+// dropped and every string value is passed through the redactor. Nothing
 // outside this module can build a payload without passing through
-// `dialogPayload` or `applyResult`.
+// `dialogPayload` or `applyResult`. A failed action never shows its raw
+// exception text: `projectFailure` turns it into a stable code and a message
+// the library or the plugin wrote for the user.
+import { createRedactor } from '../logger/index.js';
+import { PoolOperationError } from '../store/index.js';
+/**
+ * Secret shapes the seam masks on top of the logger's (bearer tokens, `sk-`
+ * keys, JWTs, vault host tokens): a value assigned to a secret-named field
+ * (`client_secret=…`, `"api_key": "…"`, `Authorization: …`), and a run of 32
+ * or more hex digits, the shape of a minted request secret. A plugin adds its
+ * provider's key shapes through `RedactionOptions.extraValuePatterns`.
+ */
+const SEAM_VALUE_PATTERNS = [
+    /\b[\w-]*(?:secret|token|password|passwd|api[_-]?key|authorization|verifier)["']?\s*[:=]\s*["']?(?:(?:Bearer|Basic)\s+)?[^\s"'&,;}]+/gi,
+    /\b[0-9a-fA-F]{32,}\b/g,
+];
+/** The string redactor every value crossing the seam goes through. */
+export function createTextRedactor(options = {}) {
+    const { redactStrings } = createRedactor({
+        ...options,
+        extraValuePatterns: [
+            ...SEAM_VALUE_PATTERNS,
+            ...(options.extraValuePatterns ?? []),
+        ],
+    });
+    return (text) => redactStrings(text);
+}
+/**
+ * A failure whose message was written for the user. An action throws it to
+ * show `message` with the stable `code`; any other thrown value is shown only
+ * as a generic message, because its text may quote a request, a response or
+ * a credential. `code` is lowercase letters, digits and dashes; anything else
+ * is reported as `action-failed`.
+ */
+export class CommandError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'CommandError';
+        this.code = code;
+    }
+}
+const CODE_SHAPE = /^[a-z][a-z0-9-]{0,63}$/;
+/** The code and message shown for an exception the seam cannot vouch for. */
+export const ACTION_FAILED = {
+    code: 'action-failed',
+    text: 'That action failed.',
+};
+/**
+ * Store failure kinds whose message the store composes itself from row ids
+ * and the plugin's own refusal reasons (`protect`). Other kinds can carry a
+ * lock or filesystem error's text, or an arbitrary exception from a hook, so
+ * they show a generic message with the kind as the code.
+ */
+const STORE_KINDS_WITH_OWN_MESSAGE = new Set([
+    'unknown-row',
+    'invalid-row',
+    'invalid-input',
+    'id-exists',
+    'id-removed',
+    'type-mismatch',
+    'no-credential',
+    'row-disabled',
+    'row-protected',
+    'duplicate-identity',
+    'row-key-changed',
+    'invalid-order',
+    'pending-migration',
+    'provider',
+    'pull',
+    'attribution',
+]);
+/** The code and display text for a thrown value; never its raw text. */
+export function projectFailure(error) {
+    if (error instanceof CommandError)
+        return {
+            code: CODE_SHAPE.test(error.code) ? error.code : ACTION_FAILED.code,
+            text: error.message,
+        };
+    if (error instanceof PoolOperationError)
+        return {
+            code: `pool-${error.kind}`,
+            text: STORE_KINDS_WITH_OWN_MESSAGE.has(error.kind)
+                ? error.message
+                : `The account pool could not do that (${error.kind}).`,
+        };
+    return ACTION_FAILED;
+}
 /** The confirmation shown when an irreversible action names none. */
 export const DEFAULT_IRREVERSIBLE_CONFIRMATION = 'This cannot be undone. Continue?';
 const CREDENTIAL_NAMES = new Set([
@@ -32,20 +120,29 @@ function isCredentialName(name) {
 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) {
+/**
+ * A copy of `value` without credential-shaped properties and with every
+ * string redacted; the paths of both go to `report`.
+ */
+function scrub(value, path, report) {
+    if (typeof value === 'string') {
+        const clean = report.redact(value);
+        if (clean !== value)
+            report.redacted.push(path);
+        return clean;
+    }
     if (Array.isArray(value))
-        return value.map((entry, index) => scrub(entry, `${path}[${index}]`, found));
+        return value.map((entry, index) => scrub(entry, `${path}[${index}]`, report));
     if (!isPlainRecord(value))
         return value;
     const out = {};
     for (const [name, entry] of Object.entries(value)) {
         if (isCredentialName(name)) {
-            found.push(`${path}.${name}`);
+            report.dropped.push(`${path}.${name}`);
             continue;
         }
         Object.defineProperty(out, name, {
-            value: scrub(entry, `${path}.${name}`, found),
+            value: scrub(entry, `${path}.${name}`, report),
             enumerable: true,
             writable: true,
             configurable: true,
@@ -53,13 +150,22 @@ function scrub(value, path, found) {
     }
     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', {
+function sealed(payload, command, seam) {
+    const report = {
+        redact: seam.redact,
+        dropped: [],
+        redacted: [],
+    };
+    const clean = scrub(payload, 'payload', report);
+    if (report.dropped.length > 0)
+        seam.logger.warn('credential-shaped field dropped from a command payload', {
+            command,
+            fields: report.dropped,
+        });
+    if (report.redacted.length > 0)
+        seam.logger.warn('secret-shaped text masked in a command payload', {
             command,
-            fields: found,
+            fields: report.redacted,
         });
     return clean;
 }
@@ -94,11 +200,15 @@ function projectKnob(knob) {
                 ...(knob.required ? { required: true } : {}),
             };
         case 'text':
+            // A masked input holds a secret, so its current value is never shown;
+            // the action still receives it when the user leaves the input alone.
             return {
                 kind: 'text',
                 id: knob.id,
                 label: knob.label,
-                ...(knob.value !== undefined ? { value: knob.value } : {}),
+                ...(knob.value !== undefined && !knob.masked
+                    ? { value: knob.value }
+                    : {}),
                 ...(knob.placeholder !== undefined
                     ? { placeholder: knob.placeholder }
                     : {}),
@@ -170,16 +280,19 @@ 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);
+export function dialogPayload(command, title, sections, seam) {
+    return sealed({ command, menu: projectMenu(command, title, sections) }, command, seam);
 }
 /** An apply's result: the message and the refreshed menu. */
-export function applyResult(command, title, sections, outcome, logger) {
+export function applyResult(command, title, sections, outcome, seam) {
     return sealed({
         command,
         ok: outcome.ok,
-        text: outcome.text,
+        text: String(outcome.text),
+        ...(!outcome.ok && outcome.code !== undefined
+            ? { code: CODE_SHAPE.test(outcome.code) ? outcome.code : 'refused' }
+            : {}),
         ...(outcome.needsConfirmation ? { needsConfirmation: true } : {}),
         menu: projectMenu(command, title, sections),
-    }, command, logger);
+    }, command, seam);
 }

package/dist/dump/index.d.ts

@@ -32,6 +32,33 @@ export interface DumpOptions {
      * It receives the redacted body.
      */
     summarize?: (body: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Byte cap for the dump artifacts in `dir`. When it is above zero, a sweep
+     * runs after a successful dump, at most once per `sweepIntervalMs`, and
+     * evicts whole dumps, oldest first, until the artifacts fit. Default off:
+     * the directory grows without bound.
+     */
+    maxBytes?: number;
+    /** Least time between two automatic sweeps. Default five minutes. */
+    sweepIntervalMs?: number;
+    /**
+     * A dump whose newest file is younger than this is never evicted, so a
+     * sweep cannot remove a dump whose response is still being attached.
+     * Default one minute.
+     */
+    sweepMinAgeMs?: number;
+    /**
+     * A response staging file older than this is left over from a crashed
+     * write and is removed by any sweep, even under the cap. Default ten
+     * minutes.
+     */
+    partialStaleMs?: number;
+    /**
+     * Remove the files a dump did write when another file of the same dump
+     * failed, so a failed dump leaves no half group behind. Default false: the
+     * files that were written stay.
+     */
+    cleanupFailedDumps?: boolean;
 }
 export interface DumpInput {
     /** The session the request belongs to; missing means `session-unknown`. */
@@ -70,6 +97,35 @@ export interface DumpResult {
         metadata: string;
         request: string;
     };
+    /**
+     * Where `dumpResponse` writes this dump's response artifact. Nothing is
+     * there until a response is attached.
+     */
+    responseFile: string;
+}
+/**
+ * What a plugin knows about the upstream response to a dumped request. Every
+ * field is optional; the artifact holds only what was given, redacted like the
+ * request. Pass no response content: the artifact is evidence about the
+ * response (who answered, what it cost), not a copy of it.
+ */
+export interface DumpResponseInput {
+    status?: number;
+    /** The provider's id for the request or response, for support lookups. */
+    requestId?: string;
+    /** The usage block the provider reported. */
+    usage?: unknown;
+    /**
+     * False while a stream is still open or when it ended without its final
+     * frame. Default true.
+     */
+    complete?: boolean;
+    /** Further provider fields, such as the model or the stop reason. */
+    fields?: Record<string, unknown>;
+}
+export interface DumpSweepResult {
+    removed: number;
+    freedBytes: number;
 }
 export interface Dumper {
     isEnabled(): boolean;
@@ -80,7 +136,45 @@ export interface Dumper {
      * and never throws into the request path.
      */
     dump(input: DumpInput): Promise<DumpResult | undefined>;
+    /**
+     * Write the response artifact of an earlier dump as
+     * `<id>.response.json`, replacing any earlier one, so a stream can record
+     * its opening usage and later its final usage. Does nothing for an
+     * undefined dump. Returns the path, or undefined when the write failed
+     * (logged, never thrown).
+     */
+    dumpResponse(dump: DumpResult | undefined, input: DumpResponseInput): Promise<string | undefined>;
+    /**
+     * Apply the byte cap now, whatever the sweep interval. Does nothing when
+     * `maxBytes` is not above zero.
+     */
+    sweep(protectedPaths?: readonly string[]): Promise<DumpSweepResult>;
+}
+export interface SweepDumpDirectoryOptions {
+    dir: string;
+    /** Byte cap for the dump artifacts; zero or less disables the sweep. */
+    maxBytes: number;
+    /** Files never removed, such as the dump just written. */
+    protectedPaths?: readonly string[];
+    /** Milliseconds since the epoch. Default `Date.now()`. */
+    now?: number;
+    /** A dump whose newest file is younger than this is kept. Default one minute. */
+    minAgeMs?: number;
+    /** A response staging file older than this is removed. Default ten minutes. */
+    partialStaleMs?: number;
+    logger?: DumpLogger;
 }
+/**
+ * Hold the dump artifacts in `dir` to `maxBytes`. Only file names a dumper
+ * writes are counted or removed, so unrelated files in a directory the user
+ * chose survive. A dump's files are evicted together, oldest dump first by
+ * its newest file, because a body without its metadata (or the reverse) is no
+ * use to anyone. Dumps younger than `minAgeMs`, protected paths and symlinks
+ * are kept, and a symlinked directory is refused outright. Response staging
+ * files left by a crash are reclaimed once stale, even under the cap.
+ * Best-effort: a failure removes less, and never throws.
+ */
+export declare function sweepDumpDirectory(options: SweepDumpDirectoryOptions): Promise<DumpSweepResult>;
 /**
  * Where two bodies first and last differ, in string offsets into the dumped
  * (redacted) text. Offsets count UTF-16 units, as the plugins' cache analysis