@hu3rror/pi-failover 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 gooyoung (original pi-failover)
+Copyright (c) 2026 Hu3rror (independent fork maintainer)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# pi-failover
+
+Automatic credential and provider failover for [Pi coding agent](https://github.com/nicobailon/pi-coding-agent) `>=0.84.2`.
+
+- [中文说明](./README.zh-CN.md)
+
+```bash
+pi install npm:@hu3rror/pi-failover
+```
+
+`pi-failover` helps a Pi session keep going when the current credential or provider becomes unavailable. It works with Pi's existing `auth.json` and adds one extension field, `backupKeys`, for API-key providers. The legacy `key-backup` spelling is still recognized on read.
+
+## About this fork
+
+`pi-failover` is MIT-licensed, originally by [gooyoung](https://github.com/gooyoung).
+This repository is an independently maintained and independently published fork,
+distributed on npm as `@hu3rror/pi-failover`; runtime behavior and `auth.json`
+conventions are unchanged.
+
+## Quick Start
+
+### 1. Install the extension
+
+```bash
+pi install npm:@hu3rror/pi-failover
+```
+
+### 2. Edit `auth.json`
+
+`pi-failover` reads only Pi's `auth.json` from `getAgentDir()`, which is usually:
+
+```text
+~/.pi/agent/auth.json
+```
+
+If `PI_CODING_AGENT_DIR` is set, Pi's own agent-directory resolution still applies.
+
+Keep Pi's primary credential as-is and add `backupKeys` to any API-key provider that should have same-provider backups. The field accepts either one literal, non-empty string or a non-empty array of literal, non-empty strings:
+
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "primary-api-key",
+    "backupKeys": ["backup-api-key-1", "backup-api-key-2"]
+  },
+  "openai-codex": {
+    "type": "oauth",
+    "access": "...",
+    "refresh": "...",
+    "expires": 1767225600000
+  }
+}
+```
+
+The existing string form remains equivalent to a one-item array. Array entries are tried in order. If the array is empty or any item is invalid, the entire backup field is ignored and the provider remains available only through its primary credential. The legacy `key-backup` spelling is read only when `backupKeys` is absent; when both fields are present, `backupKeys` wins.
+
+### 3. Verify that failover is active
+
+Start Pi and run:
+
+```text
+/failover status
+```
+
+The command shows redacted runtime status only. It never prints raw credential values.
+
+If the active key receives a handled failure during a user request, `pi-failover` can:
+
+- switch to the next backup key for the same provider
+- switch to the next configured provider
+- retry the same user request automatically after a successful switch
+- show only the final provider error when every configured option is exhausted
+
+Intermediate provider errors are replaced by a hidden continuation, so no second user message is required. TUI and RPC modes still show one redacted warning for each applied credential or provider switch.
+
+Example warnings emitted after a backup-credential switch and provider switches:
+
+![Backup credential switch warning](https://raw.githubusercontent.com/hu3rror/pi-failover/main/docs/images/failover-backup-credential-switch.png)
+![Provider switch warnings](https://raw.githubusercontent.com/hu3rror/pi-failover/main/docs/images/failover-provider-switches.png)
+
+If all failover options are exhausted while Pi still has a built-in automatic retry pending, the extension keeps the last active credential in place until that retry finishes. A successful retry keeps that credential active; after a final failure, the extension restores its runtime overrides and reports exhaustion once. This prevents Pi's retry from unexpectedly falling back to a primary credential that already failed.
+
+## Configuration Notes
+
+- `pi-failover` never reads or writes `keyrouter.json`.
+- `backupKeys` contains one or more keys for the same provider, not provider fallbacks. The legacy `key-backup` spelling is still recognized on read when `backupKeys` is absent.
+- Provider fallback order follows the top-level insertion order in `auth.json`.
+- OAuth entries can participate in provider fallback, but they do not support backup fields.
+- Every `backupKeys` value is treated as a literal string. Values are not expanded from environment variables or commands.
+- Pi's `/login` flow can rewrite `auth.json` and remove unknown extension fields, so `backupKeys` may need to be re-added after logging in again.
+
+## How Failover Works
+
+Within one user request, failed credentials and providers are disabled or cooled before the hidden continuation runs. A successful `2xx` response marks the active credential or provider healthy.
+
+| Failure | What pi-failover does |
+| --- | --- |
+| `401` / `403` | Disables the current credential for the session, switches to the next backup key or the next provider, then retries the same request. |
+| `429` | Cools down the current credential by `Retry-After`, or by 60 seconds when the header is absent, switches to the next backup key, then retries. |
+| `529` or overloaded responses | Cools down the provider by `Retry-After`, or by 30 seconds when the header is absent, changes provider, then retries. |
+| `500`, `502`, `503`, `504`, network, timeout | Cools down the provider for 30 seconds, changes provider, then retries. |
+| Other failures | Leaves Pi's normal error handling unchanged. |
+
+When switching providers, `pi-failover` prefers the current model ID. If that model is unavailable on the next provider, it uses that provider's first available model. The extension calls Pi's `setModel()`, so the new default model persists. There is no automatic failback to the original provider later.
+
+Status and warning messages identify credential slots without exposing values: the primary credential is `primary`, the first backup is `backup`, and later backups are `backup-2`, `backup-3`, and so on.
+
+## Commands
+
+- `/failover login`: interactively add a backup API key to an `api_key` provider; run it bare to pick from the current providers, or pass a provider name (`/failover login <provider>`, with autocompletion); the key is entered in a prompt (never on the command line), confirmed, then written to `auth.json` and the catalog is rebuilt
+- `/failover status`: shows redacted failover state
+- `/failover reload`: restores extension-owned overrides, then rereads `auth.json`
+
+## Output Modes
+
+| Mode | Notifications |
+| --- | --- |
+| TUI | Yes |
+| RPC | Yes |
+| JSON | No UI notifications; transparent retries still run |
+| print | No UI notifications; transparent retries still run |
+
+## Migration Notes
+
+If migrating from `~/.pi/keyrouter.json`, move each provider's primary credential into Pi's `auth.json`, then place either one backup string or an ordered backup array in `backupKeys`. Reorder the top-level entries in `auth.json` to control provider fallback order.
+
+There is no dual-read migration path. `pi-failover` uses only `auth.json`.
+
+## Security Notes
+
+- Treat `auth.json` as a secret file.
+- Do not commit credentials.
+- Restrict file permissions appropriately.
+- `pi-failover` keeps status and error messages redacted.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run audit
+npm pack --dry-run
+```
+
+`npm run audit` checks the dev-only dependency tree against the official npm registry. The only runtime dependency is `proper-lockfile`, used to guard `auth.json` writes.

package/README.zh-CN.md

@@ -0,0 +1,146 @@
+# pi-failover
+
+面向 [Pi coding agent](https://github.com/nicobailon/pi-coding-agent) `>=0.84.2` 的自动凭证与 provider 故障切换扩展。
+
+- [English README](./README.md)
+
+```bash
+pi install npm:@hu3rror/pi-failover
+```
+
+`pi-failover` 用于在当前凭证或 provider 不可用时，继续让 Pi 会话向下执行。它直接复用 Pi 现有的 `auth.json`，并为 API key provider 增加一个扩展字段 `backupKeys`。旧拼写 `key-backup` 在读取时仍会被识别。
+
+## 关于本分支（fork）
+
+`pi-failover` 采用 MIT 许可，原作者为 [gooyoung](https://github.com/gooyoung)。
+本仓库是其独立维护、独立发布的 fork，npm 分发名为
+`@hu3rror/pi-failover`；运行时行为与 `auth.json` 约定保持不变。
+
+## 快速开始
+
+### 1. 安装扩展
+
+```bash
+pi install npm:@hu3rror/pi-failover
+```
+
+### 2. 修改 `auth.json`
+
+`pi-failover` 只读取 Pi `getAgentDir()` 下的 `auth.json`，默认位置通常是：
+
+```text
+~/.pi/agent/auth.json
+```
+
+如果设置了 `PI_CODING_AGENT_DIR`，仍然沿用 Pi 自身的 agent 目录解析规则。
+
+保留 Pi 原有的主凭证，并在需要同 provider 备用 key 的 API-key provider 上增加 `backupKeys` 字段。该字段既可以是一个字面量、非空字符串，也可以是由字面量、非空字符串组成的非空数组：
+
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "primary-api-key",
+    "backupKeys": ["backup-api-key-1", "backup-api-key-2"]
+  },
+  "openai-codex": {
+    "type": "oauth",
+    "access": "...",
+    "refresh": "...",
+    "expires": 1767225600000
+  }
+}
+```
+
+现有字符串形式等价于只含一项的数组，数组中的凭证按书写顺序尝试。如果数组为空或任一元素无效，整个备用字段都会被忽略，该 provider 仍只能使用主凭证。旧拼写 `key-backup` 仅在 `backupKeys` 缺失时才会被读取；两字段同时存在时，`backupKeys` 优先。
+
+### 3. 验证故障切换已启用
+
+启动 Pi 后执行：
+
+```text
+/failover status
+```
+
+该命令只显示脱敏后的运行时状态，不会输出原始凭证值。
+
+当当前 key 在一次用户请求中遇到已接管的故障时，`pi-failover` 会按情况执行：
+
+- 切到同一 provider 的下一把备用 key
+- 切到下一个已配置 provider
+- 成功切换后自动重试同一次用户请求
+- 当所有可选项都耗尽时，只显示最后一次 provider 错误
+
+中间 provider 错误会被替换为隐藏的续跑消息，因此用户无需再次发送相同内容。TUI 和 RPC 模式仍会为每次实际生效的凭据或 provider 切换显示一条脱敏警告。
+
+以下是切换到备用凭证及切换 provider 后显示的警告示例：
+
+![切换到备用凭证的警告](https://raw.githubusercontent.com/hu3rror/pi-failover/main/docs/images/failover-backup-credential-switch.png)
+
+![切换 provider 的警告](https://raw.githubusercontent.com/hu3rror/pi-failover/main/docs/images/failover-provider-switches.png)
+
+如果所有 failover 选项已经耗尽，但 Pi 仍有内置自动重试尚未执行，扩展会保留最后一个实际使用的凭证，直到该重试结束。重试成功时继续保留该凭证；最终仍失败时，扩展才恢复其运行时 override，并只报告一次 exhausted。这样可以避免 Pi 的重试意外切回已经失败的主凭证。
+
+## 配置说明
+
+- `pi-failover` 不会读取或写入 `keyrouter.json`。
+- `backupKeys` 表示同一 provider 的一把或多把备用 key，不表示 provider 级切换。旧拼写 `key-backup` 在 `backupKeys` 缺失时仍会被识别。
+- provider 的切换顺序由 `auth.json` 顶层字段的插入顺序决定。
+- OAuth 条目可以参与 provider 级切换，但不支持备用字段。
+- `backupKeys` 中的每个值都按字面量字符串处理，不支持从环境变量或命令动态展开。
+- Pi 的 `/login` 流程可能会重写 `auth.json` 并移除未知扩展字段，因此重新登录后可能需要再次补上 `backupKeys`。
+
+## 故障切换规则
+
+同一次用户请求内，失败的凭证或 provider 会先被禁用或进入冷却，再执行隐藏续跑。收到成功的 `2xx` 响应后，当前凭证或 provider 会被标记为健康。
+
+| 故障类型 | `pi-failover` 的处理方式 |
+| --- | --- |
+| `401` / `403` | 将当前凭证在本次会话中标记为不可用，切换到下一把备用 key 或下一个 provider，然后重试同一次请求。 |
+| `429` | 按 `Retry-After` 冷却当前凭证；如果没有该响应头，则冷却 60 秒，切换到下一把备用 key 后重试。 |
+| `529` 或 overloaded 响应 | 按 `Retry-After` 冷却当前 provider；如果没有该响应头，则冷却 30 秒，切换 provider 后重试。 |
+| `500`、`502`、`503`、`504`、网络错误、超时 | 将当前 provider 冷却 30 秒，切换 provider 后重试。 |
+| 其他故障 | 保持 Pi 原有的错误处理逻辑，不额外接管。 |
+
+发生 provider 切换时，`pi-failover` 会优先保留当前 model ID；如果目标 provider 没有该 model，则退回到该 provider 的第一个可用 model。扩展内部会调用 Pi 的 `setModel()`，因此新的默认 model 会持续生效；后续不会自动切回原 provider。
+
+状态和警告信息只显示脱敏后的凭证槽位：主凭证为 `primary`，第一把备用凭证为 `backup`，后续依次为 `backup-2`、`backup-3`……
+
+## 命令
+
+- `/failover login`：交互式地为 `api_key` provider 添加备用 key；不带参数时从现有 provider 中选择，也可直接指定 provider（`/failover login <provider>`，支持自动补全）；key 在输入框中录入（绝不通过命令行参数传入），经确认后写入 `auth.json` 并立即重建 failover catalog，新 key 立即可用
+- `/failover status`：查看脱敏后的故障切换状态
+- `/failover reload`：恢复扩展接管的 override，然后重新读取 `auth.json`
+
+## 输出模式
+
+| 模式 | 通知行为 |
+| --- | --- |
+| TUI | 显示通知 |
+| RPC | 显示通知 |
+| JSON | 不显示 UI 通知，但仍会执行透明重试 |
+| print | 不显示 UI 通知，但仍会执行透明重试 |
+
+## 迁移说明
+
+如果从 `~/.pi/keyrouter.json` 迁移，需要把每个 provider 的主凭证搬到 Pi 的 `auth.json` 中，再把一把备用 key 字符串或按顺序排列的备用 key 数组写入 `backupKeys`。如需控制 provider 切换顺序，可直接调整 `auth.json` 顶层条目的顺序。
+
+当前没有双读迁移模式，`pi-failover` 只读取 `auth.json`。
+
+## 安全说明
+
+- 将 `auth.json` 视为敏感文件。
+- 不要提交凭证内容。
+- 应限制文件访问权限。
+- `pi-failover` 的状态和错误信息默认保持脱敏。
+
+## 开发
+
+```bash
+npm test
+npm run typecheck
+npm run audit
+npm pack --dry-run
+```
+
+`npm run audit` 对官方 npm registry 检查仅用于开发的依赖树。发布包唯一的运行时依赖是 `proper-lockfile`，用于守卫 `auth.json` 的写入。

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@hu3rror/pi-failover",
+	"version": "0.2.0",
+	"description": "Automatic API credential and provider failover for Pi coding agent.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/hu3rror/pi-failover.git"
+	},
+	"bugs": {
+		"url": "https://github.com/hu3rror/pi-failover/issues"
+	},
+	"homepage": "https://github.com/hu3rror/pi-failover#readme",
+	"type": "module",
+	"packageManager": "npm@11.12.1",
+	"main": "./src/index.ts",
+	"files": [
+		"src",
+		"README.md",
+		"tsconfig.json",
+		"LICENSE"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test tests/*.test.ts",
+		"audit": "npm audit --registry=https://registry.npmjs.org"
+	},
+	"keywords": [
+		"pi",
+		"pi-coding-agent",
+		"pi-extension",
+		"pi-packages",
+		"pi-failover",
+		"failover",
+		"llm-failover",
+		"key-failover",
+		"provider-failover",
+		"rate-limit",
+		"fallback",
+		"llm-fallback",
+		"key-router"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.84.2"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org"
+	},
+	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.84.2",
+		"@types/node": "^25.9.1",
+		"@types/proper-lockfile": "^4.1.4",
+		"tsx": "^4.19.0",
+		"typescript": "^6.0.3"
+	},
+	"dependencies": {
+		"proper-lockfile": "4.1.2"
+	}
+}

package/src/add-backup-key.ts

@@ -0,0 +1,126 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { lockSync } from "proper-lockfile";
+import {
+	isApiKeyCredential,
+	isLiteralBackupKey,
+	isOAuthCredential,
+	normalizeBackupKeys,
+	pickBackupField,
+} from "./auth-catalog.ts";
+
+export type AddBackupKeyRejection =
+	| "invalid-key"
+	| "unknown-provider"
+	| "oauth-provider"
+	| "unreadable"
+	| "malformed"
+	| "locked";
+
+export type AddBackupKeyResult =
+	| { ok: true; changed: true; provider: string; backupKeys: string[] }
+	| { ok: true; changed: false; provider: string; backupKeys: string[] }
+	| { ok: false; reason: AddBackupKeyRejection };
+
+export interface AddBackupKeyOptions {
+	authPath?: string;
+}
+
+// The mode applies only on file creation, mirroring Pi's FileAuthStorageBackend.
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf-8", mode: 0o600 } as const;
+
+/**
+ * Appends a validated backup key to a provider's `backupKeys` in `auth.json`.
+ *
+ * Mirrors Pi's official write method (`FileAuthStorageBackend.withLock`):
+ * lockfile-guarded read-modify-write, `0600` permissions, 2-space JSON, other
+ * credentials and provider order preserved. The default `authPath` mirrors the
+ * catalog loader's injection point.
+ */
+export function addBackupKey(
+	providerId: string,
+	backupKey: string,
+	options: AddBackupKeyOptions = {},
+): AddBackupKeyResult {
+	const authPath = options.authPath ?? join(getAgentDir(), "auth.json");
+
+	if (!isLiteralBackupKey(backupKey)) return { ok: false, reason: "invalid-key" };
+
+	let release: (() => void) | undefined;
+	try {
+		release = acquireLockSync(authPath);
+	} catch (error) {
+		return lockFailureResult(error);
+	}
+
+	try {
+		let content: string;
+		try {
+			content = fs.readFileSync(authPath, "utf-8");
+		} catch (error) {
+			if (isNodeErrorWithCode(error, "ENOENT")) return { ok: false, reason: "unknown-provider" };
+			return { ok: false, reason: "unreadable" };
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(content);
+		} catch {
+			return { ok: false, reason: "malformed" };
+		}
+		if (!isRecord(parsed)) return { ok: false, reason: "malformed" };
+
+		const credential = parsed[providerId];
+		if (credential === undefined) return { ok: false, reason: "unknown-provider" };
+		if (!isRecord(credential)) return { ok: false, reason: "malformed" };
+		if (isOAuthCredential(credential)) return { ok: false, reason: "oauth-provider" };
+		if (!isApiKeyCredential(credential)) return { ok: false, reason: "malformed" };
+
+		const existing = normalizeBackupKeys(pickBackupField(credential).value) ?? [];
+		if (existing.includes(backupKey)) {
+			return { ok: true, changed: false, provider: providerId, backupKeys: existing };
+		}
+
+		const backupKeys = [...existing, backupKey];
+		const updated = { ...parsed, [providerId]: { ...credential, backupKeys } };
+		fs.writeFileSync(authPath, JSON.stringify(updated, null, 2), AUTH_FILE_WRITE_OPTIONS);
+		return { ok: true, changed: true, provider: providerId, backupKeys };
+	} finally {
+		release?.();
+	}
+}
+
+/**
+ * Acquires the `<authPath>.lock` guard, retrying `ELOCKED` briefly, mirroring
+ * Pi's FileAuthStorageBackend retry loop.
+ */
+function acquireLockSync(authPath: string): () => void {
+	const maxAttempts = 10;
+	const delayMs = 20;
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return lockSync(authPath, { realpath: false });
+		} catch (error) {
+			if (!isNodeErrorWithCode(error, "ELOCKED") || attempt >= maxAttempts) throw error;
+			const start = Date.now();
+			while (Date.now() - start < delayMs) {
+				// Synchronous busy-wait to keep the whole operation a plain function.
+			}
+		}
+	}
+}
+
+function lockFailureResult(error: unknown): AddBackupKeyResult {
+	if (isNodeErrorWithCode(error, "ENOENT")) return { ok: false, reason: "unknown-provider" };
+	if (isNodeErrorWithCode(error, "ELOCKED")) return { ok: false, reason: "locked" };
+	return { ok: false, reason: "unreadable" };
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/auth-catalog.ts

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface AuthProviderEntry {
+	provider: string;
+	type: "api_key" | "oauth";
+	backupKeys?: string[];
+}
+
+export interface AuthCatalogDiagnostic {
+	message: string;
+	provider?: string;
+	field?: "backupKeys" | "key-backup";
+}
+
+export interface AuthCatalog {
+	enabled: boolean;
+	providers: AuthProviderEntry[];
+	diagnostics: AuthCatalogDiagnostic[];
+}
+
+interface LoadAuthCatalogOptions {
+	authPath?: string;
+}
+
+type AuthCredential = Record<string, unknown>;
+
+export function loadAuthCatalog(options: LoadAuthCatalogOptions = {}): AuthCatalog {
+	const authPath = options.authPath ?? join(getAgentDir(), "auth.json");
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(fs.readFileSync(authPath, "utf-8"));
+	} catch (error) {
+		return disabledCatalog(error instanceof SyntaxError ? "Could not parse auth.json" : "Could not read auth.json");
+	}
+
+	if (!isRecord(parsed)) {
+		return disabledCatalog("Expected auth.json to contain an object");
+	}
+
+	const providers: AuthProviderEntry[] = [];
+	const diagnostics: AuthCatalogDiagnostic[] = [];
+
+	for (const [provider, credential] of Object.entries(parsed)) {
+		if (!isRecord(credential)) continue;
+
+		if (isApiKeyCredential(credential)) {
+			const entry: AuthProviderEntry = { provider, type: "api_key" };
+			const backupField = pickBackupField(credential);
+			const backupKeys = normalizeBackupKeys(backupField.value);
+			if (backupKeys) {
+				entry.backupKeys = backupKeys;
+			} else if (backupField.value !== undefined) {
+				diagnostics.push({ provider, field: backupField.name, message: `Ignored invalid ${backupField.name}` });
+			}
+			providers.push(entry);
+			continue;
+		}
+
+		if (isOAuthCredential(credential)) {
+			providers.push({ provider, type: "oauth" });
+		}
+	}
+
+	return { enabled: true, providers, diagnostics };
+}
+
+export function pickBackupField(credential: AuthCredential): { name: "backupKeys" | "key-backup"; value: unknown } {
+	const backupKeys = credential["backupKeys"];
+	if (backupKeys !== undefined) {
+		return { name: "backupKeys", value: backupKeys };
+	}
+	return { name: "key-backup", value: credential["key-backup"] };
+}
+
+export function normalizeBackupKeys(value: unknown): string[] | undefined {
+	if (isLiteralBackupKey(value)) return [value];
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	return value.every(isLiteralBackupKey) ? value : undefined;
+}
+
+export function isLiteralBackupKey(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0 && !value.startsWith("!") && !/\$(?:\{|[A-Za-z_])/.test(value);
+}
+
+function disabledCatalog(message: string): AuthCatalog {
+	return { enabled: false, providers: [], diagnostics: [{ message }] };
+}
+
+function isRecord(value: unknown): value is AuthCredential {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isApiKeyCredential(value: AuthCredential): boolean {
+	const validKey = value.key === undefined || typeof value.key === "string";
+	const validEnv =
+		value.env === undefined ||
+		(isRecord(value.env) && Object.values(value.env).every((entry) => typeof entry === "string"));
+	return value.type === "api_key" && validKey && validEnv;
+}
+
+export function isOAuthCredential(value: AuthCredential): boolean {
+	return (
+		value.type === "oauth" &&
+		typeof value.access === "string" &&
+		typeof value.refresh === "string" &&
+		typeof value.expires === "number" &&
+		Number.isFinite(value.expires)
+	);
+}