@dungle-scrubs/tallow 0.8.5 → 0.8.7

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Tallow</h1>
 
 <p align="center">
-  An opt-in, fully featured coding agent for your terminal. Built on <a href="https://github.com/nicobrinkkemper/pi-coding-agent">pi</a>.
+  A modular coding agent for your terminal. Built on <a href="https://github.com/nicobrinkkemper/pi-coding-agent">pi</a>.
 </p>
 
 <p align="center">
@@ -23,64 +23,35 @@
 ---
 
 <p align="center">
-  <img src="assets/screenshot.jpg" alt="Tallow multi-agent team coordinating a docs audit" />
+  <img src="assets/screenshot-annotated.png" alt="Tallow session showing status bar, auto-named session, and model selection" />
+  <br />
+  <sub>Shown with a customized <a href="https://wezfurlong.org/wezterm/">WezTerm</a> configuration.</sub>
 </p>
 
-Tallow is opt-in by default: start minimal, then enable only what your project needs.
-It is drop-in compatible with Claude Code projects via `.claude/` bridging.
-Install extensions, themes, and agents in any combination.
-This is a personal project I build in my spare time, so please be patient with
-issue and PR response times.
+Tallow is a terminal coding agent that starts minimal and scales up. Install only the
+extensions, themes, and agents your project needs, or enable everything. It drops into
+existing Claude Code projects via `.claude/` bridging, so nothing breaks when you switch.
+Ships with 50 extensions, 34 themes, and 10 specialized agents.
 
-## Features
-
-- **Most valuable capabilities (non-exhaustive):**
-  - **Multi-model routing** — route work by intent/cost (`auto-cheap`, `auto-balanced`,
-    `auto-premium`) across available providers
-  - **Multi-agent teams** — coordinate specialized agents with shared task boards,
-    dependencies, messaging, and archive/resume
-  - **Context fork** — run isolated subprocess workflows with separate tools/models and
-    merge results back cleanly
-  - **Workspace rewind snapshots** — roll file changes back to earlier conversation turns
-  - **Task primitives + background execution** — explicit task lifecycle tracking and
-    non-blocking long-running work
-  - **Built-in LSP navigation** — definitions, references, hover, and workspace symbol
-    lookup
-- **Opt-in and modular** — install only the pieces you need, skip the rest
-- **Claude Code compatible** — `.claude/` + `.tallow/` directories are bridged so existing
-  project workflows keep working
-- **Fully featured when you want it** — 49 bundled extensions, 34 themes, 8 slash commands,
-  and 10 specialized agents
-- **Session naming** — auto-generated descriptive names for each session, shown in footer
-  and `--list`
-- **Debug mode** — structured JSONL diagnostic logging with `/diag` command
-- **SDK** — embed Tallow in your own scripts and orchestrators
-- **User-owned config** — agents and commands are installed to `~/.tallow/` where you can
-  edit, remove, or add your own
-
-Read the full [documentation](https://tallow.dungle-scrubs.com).
-
-## Requirements
-
-- Node.js ≥ 22
-- An API key for at least one supported LLM provider (Anthropic, OpenAI, Google, etc.)
-
-## Installation
-
-### Global install
+## Quick start
 
 ```bash
-bun install -g tallow
-tallow install
+npm install -g tallow   # or: pnpm add -g tallow / bun install -g tallow
+tallow install          # pick extensions, themes, agents
+tallow                  # start coding
 ```
 
-Or without global install:
+Or try it without installing globally:
 
 ```bash
-bunx tallow install
+npx tallow install      # or: pnpm dlx tallow install / bunx tallow install
 ```
 
-### From source
+> Requires Node.js ≥ 22 and an API key for at least one LLM provider
+> (Anthropic, OpenAI, Google, etc.)
+
+<details>
+<summary><strong>Install from source</strong></summary>
 
 ```bash
 git clone https://github.com/dungle-scrubs/tallow.git
@@ -93,155 +64,85 @@ node dist/install.js
 The installer walks you through selecting extensions, themes, and agents,
 then links the `tallow` binary globally.
 
-## Usage
-
-```bash
-# Interactive mode
-tallow
-
-# Single-shot prompt
-tallow -p "Fix the failing tests"
+</details>
 
-# Pipe input from stdin
-echo "Explain this error" | tallow
-cat README.md | tallow -p "Summarize this"
-git diff | tallow -p "Review these changes"
+## Highlights
 
-# Continue most recent session
-tallow --continue
+**Multi-model routing** — Route tasks by intent and cost across providers.
+`auto-cheap` for boilerplate, `auto-balanced` for everyday work, `auto-premium`
+when accuracy matters.
 
-# Use a specific model
-tallow -m anthropic/claude-sonnet-4-20250514
+**Multi-agent teams** — Spawn specialized agents that share a task board with
+dependencies, messaging, and archive/resume. Coordinate complex work across
+multiple models in parallel.
 
-# Set thinking level
-tallow --thinking high
+**Context fork** — Branch into an isolated subprocess with its own tools and model,
+then merge results back into the main session.
 
-# Run without persisting session
-tallow --no-session
+**Workspace rewind** — Every conversation turn snapshots your file changes. Roll back
+to any earlier turn when something goes wrong.
 
-# Load additional extensions
-tallow -e ./my-extension
+**Background tasks** — Kick off long-running work without blocking the session.
+Track task lifecycle explicitly and check back when ready.
 
-# List saved sessions (shows auto-generated names)
-tallow --list
+**LSP** — Jump to definitions, find references, inspect types, and search
+workspace symbols — no editor required.
 
-# Runtime auth via environment (not persisted)
-TALLOW_API_KEY=sk-ant-... tallow --provider anthropic
+**Claude Code compatible** — Projects with `.claude/` directories (skills, agents,
+commands) work without changes. Both `.tallow/` and `.claude/` are scanned;
+`.tallow/` takes precedence.
 
-# Runtime auth via reference (resolved at runtime)
-TALLOW_API_KEY_REF=op://Services/Anthropic/api-key tallow --provider anthropic
+**User-owned config** — Agents, commands, and extensions install to `~/.tallow/`
+where you own them. Edit, remove, or add your own.
 
-# Run in RPC or JSON mode
-tallow --mode rpc
-
-# Restrict available tools
-tallow --tools read,grep,find      # Only read, grep, find
-tallow --tools readonly            # Preset: read, grep, find, ls
-tallow --tools none                # Chat only, no tools
-
-# Disable all extensions
-tallow --no-extensions
-
-# Print tallow home directory
-tallow --home
-```
-
-`--api-key` was removed to avoid leaking secrets in process arguments.
-Use `TALLOW_API_KEY` or `TALLOW_API_KEY_REF` instead.
-
-### Piped input
-
-Pipe file contents or command output directly into Tallow:
+## Usage
 
 ```bash
-# Stdin becomes the prompt
-echo "What is 2+2?" | tallow
+# Interactive session
+tallow
 
-# Stdin as context + explicit prompt
-cat src/main.ts | tallow -p "Find bugs in this code"
+# Single-shot prompt
+tallow -p "Fix the failing tests"
 
-# Pipe command output
-git log --oneline -20 | tallow -p "Summarize recent changes"
-```
+# Pipe in context
+git diff | tallow -p "Review these changes"
+cat src/main.ts | tallow -p "Find bugs in this code"
 
-When stdin is piped, Tallow automatically enters print mode (single-shot).
-If both stdin and `-p` are provided, stdin is prepended as context before the
-prompt. Piped input is capped at 10 MB. JSON mode (`--mode json`) also
-accepts piped stdin.
+# Continue the last session
+tallow --continue
 
-### Shell interpolation
+# Pick a model and thinking level
+tallow -m anthropic/claude-sonnet-4-20250514 --thinking high
 
-Expand shell commands inline with `` !`command` `` syntax:
+# List saved sessions
+tallow --list
 
+# Restrict available tools
+tallow --tools readonly            # read, grep, find, ls only
+tallow --tools none                # chat only, no tools
 ```
-!`ls -la`
-!`git status`
-!`git branch --show-current`
-```
-
-**Disabled by default.** Enable explicitly with either:
-
-- `TALLOW_ENABLE_SHELL_INTERPOLATION=1` (or `TALLOW_SHELL_INTERPOLATION=1`)
-- `"shellInterpolation": true` in `.tallow/settings.json` or `~/.tallow/settings.json`
 
-When enabled, only allowlisted implicit commands run. The command output
-replaces the pattern before reaching the agent. 5-second timeout, 1 MB
-max output, non-recursive. High-risk explicit shell commands require
-confirmation (`TALLOW_ALLOW_UNSAFE_SHELL=1` bypasses confirmation in
-non-interactive environments).
+### Extension catalog + least-privilege startup
 
-### Slash commands
+Use the extension catalog to inspect what each extension does:
 
-Inside an interactive session, type `/` to see available commands:
-
-| Command | Description |
-|---------|-------------|
-| `/implement` | Implement a feature from a description |
-| `/implement-and-review` | Implement then self-review |
-| `/review` | Review recent changes |
-| `/fix` | Fix a bug from a description |
-| `/test` | Write or fix tests |
-| `/scout-and-plan` | Explore the codebase and create a plan |
-| `/scaffold` | Scaffold a new project |
-| `/question` | Introspect on agent reasoning without triggering actions |
-
-## SDK
-
-Use Tallow programmatically in your own tools:
-
-```typescript
-import { createTallowSession } from "tallow";
-
-const { session } = await createTallowSession({
-  provider: "anthropic",
-  modelId: "claude-sonnet-4-20250514",
-});
+```bash
+tallow extensions          # table view (default)
+tallow extensions --json   # machine-readable catalog
+tallow extensions tasks    # details for one extension ID
+```
 
-session.subscribe((event) => {
-  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
+For least-privilege sessions, start from an explicit allowlist:
 
-await session.prompt("What files are in this directory?");
-session.dispose();
+```bash
+tallow --extensions-only --extension tasks --extension lsp
+tallow --extensions-only --extension read-tool-enhanced --extension write-tool-enhanced
 ```
 
-### SDK options
+Repeat `--extension <selector>` to add only what the task needs.
 
-```typescript
-const tallow = await createTallowSession({
-  cwd: "/path/to/project",
-  provider: "anthropic",
-  modelId: "claude-sonnet-4-20250514",
-  thinkingLevel: "high",
-  session: { type: "memory" },        // Don't persist
-  noBundledExtensions: true,           // Start clean
-  additionalExtensions: ["./my-ext"],   // Add your own
-  systemPrompt: "You are a test bot.",  // Override system prompt
-  apiKey: process.env.ANTHROPIC_API_KEY, // Runtime only, not persisted
-});
-```
+See the [full CLI reference](https://tallow.dungle-scrubs.com) for all flags
+and modes (RPC, JSON, piped stdin, shell interpolation, etc.)
 
 ## Configuration
 
@@ -249,47 +150,38 @@ Tallow stores its configuration in `~/.tallow/`:
 
 | Path | Purpose |
 |------|---------|
-| `~/.tallow/settings.json` | Global settings |
-| `~/.tallow/.env` | Environment variables loaded at startup (supports `op://` refs) |
-| `~/.tallow/auth.json` | Provider auth references (see [SECURITY.md](SECURITY.md)) |
-| `~/.tallow/models.json` | Model configuration |
-| `~/.tallow/keybindings.json` | Keybinding overrides |
-| `~/.tallow/agents/` | Agent profiles (installed from templates, yours to edit) |
-| `~/.tallow/commands/` | Slash commands (installed from templates, yours to edit) |
-| `~/.tallow/extensions/` | User extensions (override bundled ones by name) |
-| `~/.tallow/sessions/` | Persisted conversation sessions |
+| `settings.json` | Global settings (theme, icons, keybindings) |
+| `.env` | Environment variables loaded at startup (supports `op://` refs) |
+| `auth.json` | Provider auth references (see [SECURITY.md](SECURITY.md)) |
+| `models.json` | Model configuration |
+| `agents/` | Agent profiles — yours to edit |
+| `commands/` | Slash commands — yours to edit |
+| `extensions/` | User extensions (override bundled ones by name) |
+| `sessions/` | Persisted conversation sessions |
+
+Project-level overrides live in `.tallow/` within your repo.
 
-Project-level configuration lives in `.tallow/` within your project directory.
+## Extending Tallow
 
-## Icons
+### Themes
 
-Override any TUI glyph in `~/.tallow/settings.json`:
+Switch themes in-session with `/theme`, or set a default:
 
 ```json
-{
-  "icons": {
-    "success": "✔",
-    "error": "✘",
-    "spinner": ["⠋", "⠙", "⠹", "⠸"]
-  }
-}
+{ "theme": "tokyo-night" }
 ```
 
-Only keys you set are overridden — everything else keeps its default.
-See the [icon reference](https://tallow.dungle-scrubs.com/getting-started/icons/) for all available keys.
-
-## Themes
+### Icons
 
-Switch themes inside an interactive session with the `/theme` command,
-or set one in `~/.tallow/settings.json`:
+Override any TUI glyph in `settings.json` — only the keys you set change:
 
 ```json
-{
-  "theme": "tokyo-night"
-}
+{ "icons": { "success": "✔", "error": "✘" } }
 ```
 
-## Writing extensions
+See the [icon reference](https://tallow.dungle-scrubs.com/getting-started/icons/) for all keys.
+
+### Writing extensions
 
 Extensions are TypeScript files that receive the pi `ExtensionAPI`:
 
@@ -306,20 +198,46 @@ export default function myExtension(api: ExtensionAPI): void {
 }
 ```
 
-Place your extension in `~/.tallow/extensions/my-extension/index.ts`.
-If it shares a name with a bundled extension, yours takes precedence.
+Place it in `~/.tallow/extensions/my-extension/index.ts`. If it shares a name
+with a bundled extension, yours takes precedence.
+
+### SDK
+
+Embed Tallow in your own scripts:
+
+```typescript
+import { createTallowSession } from "tallow";
+
+const { session } = await createTallowSession({
+  provider: "anthropic",
+  modelId: "claude-sonnet-4-20250514",
+});
+
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt("What files are in this directory?");
+session.dispose();
+```
+
+See the [SDK docs](https://tallow.dungle-scrubs.com) for all options.
 
 ## Known limitations
 
 - Requires Node.js 22+ (uses modern ESM features)
 - Session persistence is local — no cloud sync
-- The `web_fetch` extension works best with a [Firecrawl](https://firecrawl.dev) API key
-  for JS-heavy pages
+- `web_fetch` works best with a [Firecrawl](https://firecrawl.dev) API key for JS-heavy pages
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
+This is a personal project I build in my spare time — please be patient with
+issue and PR response times.
+
 ## License
 
 [MIT](LICENSE) © Kevin Frilot

package/dist/auth-hardening.d.ts

@@ -1,4 +1,4 @@
-import { type AuthCredential, AuthStorage } from "@mariozechner/pi-coding-agent";
+import { AuthStorage } from "@mariozechner/pi-coding-agent";
 /** Result of the plaintext migration run. */
 export interface MigrationResult {
     /** Providers migrated from plaintext/op:// to secure references. */
@@ -22,30 +22,24 @@ export interface ApiKeySecretStore {
 export interface SecureAuthStorageOptions {
     readonly secretStore?: ApiKeySecretStore;
 }
-/**
- * AuthStorage wrapper that guarantees api_key credentials are persisted as
- * references only (keychain/opchain/env/shell), never as raw values.
- */
-export declare class SecureAuthStorage extends AuthStorage {
+/** Return value from {@link createSecureAuthStorage}. */
+export interface SecureAuthStorageResult {
+    /** AuthStorage instance with secure persistence. */
+    readonly authStorage: AuthStorage;
+    /** Providers migrated from plaintext to secure references on creation. */
     readonly migration: MigrationResult;
-    private readonly authPathValue;
-    private readonly secretStore;
-    /**
-     * Create a secure auth storage instance and run one-time migration.
-     *
-     * @param authPath - Absolute auth.json path
-     * @param options - Optional testing dependencies
-     */
-    constructor(authPath: string, options?: SecureAuthStorageOptions);
-    /**
-     * Persist a provider credential.
-     * API keys are converted to secure references before writing to disk.
-     *
-     * @param provider - Provider ID
-     * @param credential - Credential payload
-     */
-    set(provider: string, credential: AuthCredential): void;
 }
+/**
+ * Create an AuthStorage instance with secure persistence.
+ * Raw API keys are normalized to references at the storage-backend layer,
+ * ensuring they never reach disk in plaintext. Runs one-time migration
+ * for any existing plaintext keys.
+ *
+ * @param authPath - Absolute auth.json path
+ * @param options - Optional testing dependencies
+ * @returns AuthStorage instance and migration result
+ */
+export declare function createSecureAuthStorage(authPath: string, options?: SecureAuthStorageOptions): SecureAuthStorageResult;
 /**
  * Fail when auth.json permissions are insecure.
  *

package/dist/auth-hardening.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-hardening.d.ts","sourceRoot":"","sources":["../src/auth-hardening.ts"],"names":[],"mappings":"AAIA,OAAO,EAEN,KAAK,cAAc,EACnB,WAAW,EACX,MAAM,+BAA+B,CAAC;AASvC,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IACjD,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAYpE;;;;;;OAMG;IACM,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI;CAehE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,iBAA6C,GACxD,gBAAgB,CAMlB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,iBAA6C,GACxD,eAAe,CA0BjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAUhE"}
+{"version":3,"file":"auth-hardening.d.ts","sourceRoot":"","sources":["../src/auth-hardening.ts"],"names":[],"mappings":"AAIA,OAAO,EAGN,WAAW,EAGX,MAAM,+BAA+B,CAAC;AASvC,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAED,yDAAyD;AACzD,MAAM,WAAW,uBAAuB;IACvC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACpC;AA+ED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,wBAA6B,GACpC,uBAAuB,CAUzB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,iBAA6C,GACxD,gBAAgB,CAMlB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,iBAA6C,GACxD,eAAe,CA0BjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAUhE"}

package/dist/auth-hardening.js

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { platform } from "node:os";
 import { dirname } from "node:path";
-import { AuthStorage, } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, FileAuthStorageBackend, } from "@mariozechner/pi-coding-agent";
 import { atomicWriteFileSync, restoreFromBackup } from "./atomic-write.js";
 const AUTH_FILE_MODE = 0o600;
 const AUTH_DIRECTORY_MODE = 0o700;
@@ -10,50 +10,95 @@ const KEYCHAIN_ACCOUNT = "tallow";
 const KEYCHAIN_SERVICE_PREFIX = "tallow.api-key";
 const ENV_REFERENCE_PATTERN = /^[A-Z][A-Z0-9]*_[A-Z0-9_]*$/;
 /**
- * AuthStorage wrapper that guarantees api_key credentials are persisted as
- * references only (keychain/opchain/env/shell), never as raw values.
+ * AuthStorageBackend that intercepts writes to normalize API key credentials.
+ * Wraps FileAuthStorageBackend — raw keys are converted to secure references
+ * (keychain/opchain/env/shell) before they reach disk.
  */
-export class SecureAuthStorage extends AuthStorage {
-    migration;
-    authPathValue;
+class SecureFileAuthStorageBackend {
+    inner;
     secretStore;
     /**
-     * Create a secure auth storage instance and run one-time migration.
-     *
      * @param authPath - Absolute auth.json path
-     * @param options - Optional testing dependencies
+     * @param secretStore - Backend for raw key storage
      */
-    constructor(authPath, options = {}) {
-        super(authPath);
-        this.authPathValue = authPath;
-        this.secretStore = options.secretStore ?? createApiKeySecretStore();
-        assertSecureAuthFilePermissions(authPath);
-        this.migration = migratePlaintextApiKeys(authPath, this.secretStore);
-        if (this.migration.migratedProviders.length > 0) {
-            super.reload();
-        }
+    constructor(authPath, secretStore) {
+        this.inner = new FileAuthStorageBackend(authPath);
+        this.secretStore = secretStore;
     }
     /**
-     * Persist a provider credential.
-     * API keys are converted to secure references before writing to disk.
+     * Execute fn under lock, normalizing any API keys in the write payload.
      *
-     * @param provider - Provider ID
-     * @param credential - Credential payload
+     * @param fn - Lock callback receiving current content
+     * @returns Result from fn
+     */
+    withLock(fn) {
+        return this.inner.withLock((current) => {
+            const lockResult = fn(current);
+            if (lockResult.next !== undefined) {
+                lockResult.next = this.normalizeStorageContent(lockResult.next);
+            }
+            return lockResult;
+        });
+    }
+    /**
+     * Async variant of withLock.
+     *
+     * @param fn - Async lock callback receiving current content
+     * @returns Result from fn
+     */
+    withLockAsync(fn) {
+        return this.inner.withLockAsync(async (current) => {
+            const lockResult = await fn(current);
+            if (lockResult.next !== undefined) {
+                lockResult.next = this.normalizeStorageContent(lockResult.next);
+            }
+            return lockResult;
+        });
+    }
+    /**
+     * Parse JSON content and normalize any raw API keys to secure references.
+     *
+     * @param jsonContent - Serialized auth data
+     * @returns Normalized JSON content
      */
-    set(provider, credential) {
-        if (credential.type !== "api_key") {
-            super.set(provider, credential);
-            assertSecureAuthFilePermissions(this.authPathValue);
-            return;
+    normalizeStorageContent(jsonContent) {
+        try {
+            const data = JSON.parse(jsonContent);
+            let changed = false;
+            for (const [provider, credential] of Object.entries(data)) {
+                if (credential?.type !== "api_key" || typeof credential.key !== "string")
+                    continue;
+                const normalized = normalizeApiKeyValue(provider, credential.key, this.secretStore);
+                if (normalized !== credential.key) {
+                    data[provider].key = normalized;
+                    changed = true;
+                }
+            }
+            return changed ? JSON.stringify(data, null, 2) : jsonContent;
+        }
+        catch {
+            return jsonContent;
         }
-        const secureCredential = {
-            type: "api_key",
-            key: normalizeApiKeyValue(provider, credential.key, this.secretStore),
-        };
-        super.set(provider, secureCredential);
-        assertSecureAuthFilePermissions(this.authPathValue);
     }
 }
+/**
+ * Create an AuthStorage instance with secure persistence.
+ * Raw API keys are normalized to references at the storage-backend layer,
+ * ensuring they never reach disk in plaintext. Runs one-time migration
+ * for any existing plaintext keys.
+ *
+ * @param authPath - Absolute auth.json path
+ * @param options - Optional testing dependencies
+ * @returns AuthStorage instance and migration result
+ */
+export function createSecureAuthStorage(authPath, options = {}) {
+    const secretStore = options.secretStore ?? createApiKeySecretStore();
+    assertSecureAuthFilePermissions(authPath);
+    const migration = migratePlaintextApiKeys(authPath, secretStore);
+    const backend = new SecureFileAuthStorageBackend(authPath, secretStore);
+    const authStorage = AuthStorage.fromStorage(backend);
+    return { authStorage, migration };
+}
 /**
  * Fail when auth.json permissions are insecure.
  *