@totalreclaw/totalreclaw 3.3.12-rc.9 → 3.3.12

package/dist/billing-cache.js

@@ -11,8 +11,12 @@
  * This module:
  *   - reads/writes `~/.totalreclaw/billing-cache.json` (path from CONFIG)
  *   - exports `BillingCache`, `BILLING_CACHE_PATH`, `BILLING_CACHE_TTL`
- *   - keeps the chain-id override in sync with the cached tier so Pro-tier
- *     UserOps sign against chain 100 and Free-tier stays on 84532
+ *   - keeps the chain-id override in sync with the relay's authoritative
+ *     `chain_id` (after ops-1 both tiers are on Gnosis 100; the client consumes
+ *     the relay value verbatim — see `syncChainIdFromBilling`)
+ *   - keeps the DataEdge-address override in sync with the relay's
+ *     authoritative `data_edge_address` (staging vs prod contract; consumed
+ *     verbatim — see `syncDataEdgeAddressFromBilling`, #460)
  *   - does NOT import anything that performs outbound I/O
  *
  * Do NOT add any outbound-request call to this file — a single match for
@@ -22,7 +26,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { CONFIG, setChainIdOverride } from './config.js';
+import { CONFIG, setChainIdOverride, setDataEdgeAddressOverride } from './config.js';
+/** A plausible EVM address — anything else from billing is ignored (#460). */
+const DATA_EDGE_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -33,25 +39,45 @@ export const BILLING_CACHE_TTL = 2 * 60 * 60 * 1000; // 2 hours
 // Chain-id sync
 // ---------------------------------------------------------------------------
 /**
- * Apply the billing tier to the runtime chain override.
+ * Apply the relay's authoritative `chain_id` to the runtime chain override.
  *
- * Pro tier → chain 100 (Gnosis mainnet). Free tier (or unknown) stays on
- * 84532 (Base Sepolia). The relay routes Pro UserOps to Gnosis, so the
- * client MUST sign them against chain 100 — otherwise the bundler returns
- * AA23 (invalid signature). See MCP's equivalent path in mcp/src/index.ts.
+ * After ops-1 (2026-06-05) both tiers run on Gnosis (chain 100) and the relay
+ * returns an authoritative `chain_id` in `/v1/billing/status`. The client MUST
+ * consume that verbatim — the old tier→chain derivation (Free ⇒ 84532 Base
+ * Sepolia) was retired two-tier logic that mis-signed FREE-tier UserOps
+ * against the wrong chain and queried a Base-Sepolia RPC for a Gnosis-deployed
+ * sender, producing deterministic AA10 (#402).
  *
- * Called from `readBillingCache` and `writeBillingCache` so that every cache
- * read or write keeps the chain override in sync with the cached tier.
- * Idempotent — calling with the same tier is a no-op.
+ * A missing / non-finite `chain_id` (older relay, partial payload) defaults to
+ * 100 — never 84532. Called from `readBillingCache` and `writeBillingCache` so
+ * every cache read or write keeps the override in sync. Idempotent.
  */
-export function syncChainIdFromTier(tier) {
-    if (tier === 'pro') {
-        setChainIdOverride(100);
-    }
-    else {
-        // Free or unknown → reset to the default free-tier chain.
-        setChainIdOverride(84532);
-    }
+export function syncChainIdFromBilling(chainId) {
+    setChainIdOverride(typeof chainId === 'number' && Number.isFinite(chainId) ? chainId : 100);
+}
+// ---------------------------------------------------------------------------
+// DataEdge-address sync
+// ---------------------------------------------------------------------------
+/**
+ * Apply the relay's authoritative `data_edge_address` to the runtime DataEdge
+ * override. Mirrors `syncChainIdFromBilling`.
+ *
+ * The relay routes each environment to its own DataEdge (staging is on-chain
+ * isolated). If the client ignores this and uses the WASM-baked default (the
+ * PROD DataEdge), writes against the staging relay mine on the prod contract
+ * while reads come from the staging subgraph → empty recall + phantom
+ * "stored=N" success (#460).
+ *
+ * A missing / malformed `data_edge_address` (older relay, partial payload,
+ * junk) clears the override (`null`) so resolution falls through to the WASM
+ * default — never a stale value. Only a plausible address
+ * (`0x` + 40 hex) is honored. Called from `readBillingCache` and
+ * `writeBillingCache` so every cache read or write keeps the override in sync.
+ * Idempotent. The explicit env override (`TOTALRECLAW_DATA_EDGE_ADDRESS`)
+ * still wins — it is the first term in `getSubgraphConfig`.
+ */
+export function syncDataEdgeAddressFromBilling(address) {
+    setDataEdgeAddressOverride(typeof address === 'string' && DATA_EDGE_ADDRESS_RE.test(address) ? address : null);
 }
 // ---------------------------------------------------------------------------
 // Read / write
@@ -71,8 +97,10 @@ export function readBillingCache() {
         const raw = JSON.parse(fs.readFileSync(BILLING_CACHE_PATH, 'utf-8'));
         if (!raw.checked_at || Date.now() - raw.checked_at > BILLING_CACHE_TTL)
             return null;
-        // Keep chain override in sync with persisted tier across process restarts.
-        syncChainIdFromTier(raw.tier);
+        // Keep chain + DataEdge overrides in sync with the persisted authoritative
+        // values across process restarts.
+        syncChainIdFromBilling(raw.chain_id);
+        syncDataEdgeAddressFromBilling(raw.data_edge_address);
         return raw;
     }
     catch {
@@ -94,7 +122,9 @@ export function writeBillingCache(cache) {
     catch {
         // Best-effort — don't block on cache write failure.
     }
-    // Sync chain override AFTER the write so in-process UserOp signing picks
-    // up the correct chain immediately, even if the disk write failed.
-    syncChainIdFromTier(cache.tier);
+    // Sync chain + DataEdge overrides AFTER the write so in-process UserOp
+    // signing + subgraph reads pick up the correct chain and contract
+    // immediately, even if the disk write failed.
+    syncChainIdFromBilling(cache.chain_id);
+    syncDataEdgeAddressFromBilling(cache.data_edge_address);
 }

package/dist/claims-helper.js

@@ -11,6 +11,7 @@
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { isValidMemoryType, isValidMemoryTypeV1, V0_TO_V1_TYPE, VALID_MEMORY_SCOPES, VALID_MEMORY_SOURCES, VALID_MEMORY_VOLATILITIES, VALID_MEMORY_TYPES_V1, } from './extractor.js';
+import { envStringLower } from './entry.js';
 // Lazy-load WASM. We use createRequire so this module loads cleanly under
 // both the OpenClaw runtime (CJS-ish tsx) and bare Node ESM (used by tests).
 const requireWasm = createRequire(import.meta.url);
@@ -411,7 +412,7 @@ export function resolveDigestMode() {
  * @internal Not public config — emergency kill-switch only.
  */
 export function resolveAutoResolveMode() {
-    const raw = (process.env.TOTALRECLAW_AUTO_RESOLVE_MODE ?? '').trim().toLowerCase();
+    const raw = envStringLower('TOTALRECLAW_AUTO_RESOLVE_MODE');
     if (raw === 'off')
         return 'off';
     if (raw === 'shadow')

package/dist/config.js

@@ -90,10 +90,10 @@ export function getSessionId() {
 }
 /**
  * Runtime override for chain ID, set after the relay billing response is
- * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
- * (Gnosis mainnet). The relay routes Pro writes to Gnosis, so Pro-tier
- * UserOps MUST be signed against chain 100 — otherwise the bundler rejects
- * the signature with AA23.
+ * read. After the ops-1 single-chain migration (2026-05), ALL tiers (free
+ * + Pro) are on Gnosis mainnet (chain 100). The default below is 100.
+ * The relay routes all writes to Gnosis, so UserOps MUST be signed against
+ * chain 100 — otherwise the bundler rejects the signature with AA24.
  *
  * See index.ts: after the billing lookup completes, call
  * `setChainIdOverride(100)` for Pro users. Free users can leave the
@@ -107,6 +107,35 @@ export function setChainIdOverride(chainId) {
 export function __resetChainIdOverrideForTests() {
     _chainIdOverride = null;
 }
+/**
+ * Runtime override for the DataEdge contract address, set after the relay
+ * billing response is read. The relay returns an authoritative
+ * `data_edge_address` in `/v1/billing/status` (staging routes to the isolated
+ * staging DataEdge, production to the prod DataEdge). Chain-aware clients MUST
+ * consume it verbatim — otherwise writes mine on the WASM-baked prod DataEdge
+ * while reads hit the relay's subgraph, so recall silently returns empty
+ * against staging (#460). Mirrors `_chainIdOverride`.
+ *
+ * `null` means "no billing override" → fall through to the WASM default. The
+ * explicit operator env override (`TOTALRECLAW_DATA_EDGE_ADDRESS`, exposed as
+ * `CONFIG.dataEdgeAddress`) always wins over this.
+ */
+let _dataEdgeAddressOverride = null;
+export function setDataEdgeAddressOverride(address) {
+    _dataEdgeAddressOverride = address;
+}
+/**
+ * Read the billing-sourced DataEdge override (or `''` when unset). Used by
+ * `getSubgraphConfig` as the middle term of the env → billing → WASM-default
+ * resolution order (#460).
+ */
+export function getDataEdgeAddressOverride() {
+    return _dataEdgeAddressOverride ?? '';
+}
+/** Reset the DataEdge override — used by tests. */
+export function __resetDataEdgeAddressOverrideForTests() {
+    _dataEdgeAddressOverride = null;
+}
 export const CONFIG = {
     // Core — recoveryPhrase reads from override first, then env var.
     // Use getRecoveryPhrase() for dynamic access; this property is for
@@ -133,6 +162,42 @@ export const CONFIG = {
     serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
     selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
     credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
+    // cred-3 stage 1 — credential-provider abstraction.
+    //
+    // `file` (default) preserves the legacy behavior: read/write
+    // `credentialsPath` directly via fs-helpers.
+    //
+    // `external` instructs the plugin to load credentials from an
+    // out-of-process source at boot. Two transports are supported (mutually
+    // exclusive — JSON wins if both set):
+    //   1. `externalCredentialsJson` — raw JSON string of CredentialsFile,
+    //      injected at process start by the secret manager (Railway secrets,
+    //      Docker `--env-file`, K8s envFrom). Most ergonomic for cloud
+    //      deployments where the secret manager already exposes secrets as
+    //      env vars.
+    //   2. `externalCredentialsPath` — filesystem path to a JSON file the
+    //      secret manager mounts (Docker Compose `secrets:` block,
+    //      K8s secret volumeMount, tmpfs populated by an ops wrapper that
+    //      fetches from AWS Secrets Manager / Hetzner Vault before boot).
+    //
+    // `external` mode is read-only: write/clear are no-ops with a warning
+    // (the secret manager owns the source of truth — the plugin must not
+    // write back through this path).
+    //
+    // See `docs/guides/production-deployment.md` for the LUKS / dm-crypt
+    // pattern and managed-secret-store wiring examples.
+    credentialsProvider: (() => {
+        const v = (process.env.TOTALRECLAW_CREDENTIALS_PROVIDER ?? '').trim().toLowerCase();
+        return v === 'external' ? 'external' : 'file';
+    })(),
+    externalCredentialsJson: (() => {
+        const v = (process.env.TOTALRECLAW_EXTERNAL_CREDENTIALS_JSON ?? '').trim();
+        return v.length > 0 ? v : null;
+    })(),
+    externalCredentialsPath: (() => {
+        const v = (process.env.TOTALRECLAW_EXTERNAL_CREDENTIALS_PATH ?? '').trim();
+        return v.length > 0 ? v : null;
+    })(),
     // 3.2.0 onboarding state file — separate from credentials.json so it
     // never contains secrets. Loaded on every plugin init + on every
     // before_tool_call gate check.
@@ -166,21 +231,28 @@ export const CONFIG = {
         || (process.env.TOTALRECLAW_SERVER_URL
             ? process.env.TOTALRECLAW_SERVER_URL.replace(/^https?:\/\//, 'wss://').replace(/^http:/, 'ws:')
             : 'wss://api.totalreclaw.xyz')).replace(/\/+$/, ''),
-    // Chain — chainId is no longer user-configurable. It is auto-detected from
-    // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
-    // 100). The default here is used only before the first billing lookup
+    // Chain — chainId is no longer user-configurable. After the ops-1 single-
+    // chain migration, ALL tiers are on Gnosis (100). The default here is 100.
     // completes. Self-hosted users can still point at a custom DataEdge via
     // TOTALRECLAW_DATA_EDGE_ADDRESS / TOTALRECLAW_ENTRYPOINT_ADDRESS /
     // TOTALRECLAW_RPC_URL (undocumented; internal knobs).
     //
-    // Reads the runtime override set by the billing auto-detect in index.ts.
-    // Falls back to 84532 (free tier / pre-billing-lookup). Must be a getter,
-    // not a literal — a literal would freeze all Pro-tier UserOps to the
-    // wrong chainId and AA23 at the bundler.
+    // Reads the runtime override set from the relay's authoritative chain_id
+    // (syncChainIdFromBilling). Falls back to 100 (Gnosis) pre-billing-lookup —
+    // after ops-1 both tiers are on Gnosis, so 84532 is never the default (#402).
+    // Must be a getter, not a literal — a literal would freeze UserOps to the
+    // wrong chainId and fail signature validation at the bundler.
     get chainId() {
-        return _chainIdOverride ?? 84532;
+        return _chainIdOverride ?? 100;
+    },
+    // Explicit operator env override for the DataEdge contract. Stays env-only:
+    // it is the FIRST term of `getSubgraphConfig`'s env → billing → WASM-default
+    // resolution order, so it wins over the relay's authoritative
+    // `data_edge_address` (see `getDataEdgeAddressOverride` / #460). Getter, not
+    // a literal, so it reflects the live env rather than freezing at module load.
+    get dataEdgeAddress() {
+        return process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '';
     },
-    dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
     entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
     rpcUrl: process.env.TOTALRECLAW_RPC_URL || '',
     // 3.3.3-rc.1 (issue #187 — ONNX decouple): kill switch for the
@@ -202,6 +274,12 @@ export const CONFIG = {
     // See: docs/specs/totalreclaw/client-consistency.md
     cosineThreshold: parseFloat(process.env.TOTALRECLAW_COSINE_THRESHOLD ?? '0.15'),
     extractInterval: parseInt(process.env.TOTALRECLAW_EXTRACT_INTERVAL ?? process.env.TOTALRECLAW_EXTRACT_EVERY_TURNS ?? '3', 10),
+    // Self-hosted fallback for max-facts-per-extraction. `undefined` when the
+    // env var is unset so getMaxFactsPerExtraction() can fall through to the
+    // billing cache then the built-in MAX_FACTS_PER_EXTRACTION constant.
+    maxFactsPerExtraction: process.env.TOTALRECLAW_MAX_FACTS_PER_EXTRACTION
+        ? parseInt(process.env.TOTALRECLAW_MAX_FACTS_PER_EXTRACTION, 10)
+        : undefined,
     relevanceThreshold: parseFloat(process.env.TOTALRECLAW_RELEVANCE_THRESHOLD ?? '0.3'),
     semanticSkipThreshold: parseFloat(process.env.TOTALRECLAW_SEMANTIC_SKIP_THRESHOLD ?? '0.85'),
     cacheTtlMs: parseInt(process.env.TOTALRECLAW_CACHE_TTL_MS ?? String(5 * 60 * 1000), 10),

package/dist/consolidation.js

@@ -18,10 +18,13 @@
  * and `clusterFacts` WASM functions when available, falling back to local
  * implementations that use WASM-backed `cosineSimilarity`.
  *
- * Threshold helpers remain local (they read process.env).
+ * Threshold helpers remain local; their env reads are centralized in
+ * entry.ts (env-reading seam, Task 1.3 of the OpenClaw native
+ * integration plan, 2026-06-21).
  */
 import { createRequire } from 'node:module';
 import { cosineSimilarity } from './reranker.js';
+import { envNumber } from './entry.js';
 // ---------------------------------------------------------------------------
 // Lazy-load WASM core (mirrors claims-helper.ts / contradiction-sync.ts
 // pattern — plays nicely under both the OpenClaw runtime (CJS-ish tsx) and
@@ -44,13 +47,7 @@ function getWasm() {
  * Must be a number in [0, 1]. Falls back to 0.85 if invalid or unset.
  */
 export function getStoreDedupThreshold() {
-    const envVal = process.env.TOTALRECLAW_STORE_DEDUP_THRESHOLD;
-    if (envVal !== undefined) {
-        const parsed = parseFloat(envVal);
-        if (!isNaN(parsed) && parsed >= 0 && parsed <= 1)
-            return parsed;
-    }
-    return 0.85;
+    return envNumber('TOTALRECLAW_STORE_DEDUP_THRESHOLD', 0.85, { min: 0, max: 1 });
 }
 /**
  * Get the cosine similarity threshold for bulk consolidation clustering.
@@ -59,13 +56,7 @@ export function getStoreDedupThreshold() {
  * Must be a number in [0, 1]. Falls back to 0.88 if invalid or unset.
  */
 export function getConsolidationThreshold() {
-    const envVal = process.env.TOTALRECLAW_CONSOLIDATION_THRESHOLD;
-    if (envVal !== undefined) {
-        const parsed = parseFloat(envVal);
-        if (!isNaN(parsed) && parsed >= 0 && parsed <= 1)
-            return parsed;
-    }
-    return 0.88;
+    return envNumber('TOTALRECLAW_CONSOLIDATION_THRESHOLD', 0.88, { min: 0, max: 1 });
 }
 /** Maximum candidates to compare against during store-time dedup. */
 export const STORE_DEDUP_MAX_CANDIDATES = 200;

package/dist/contradiction-sync.js

@@ -16,8 +16,8 @@
  */
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { envHomedir, envNumber, envString, envStringLower, } from './entry.js';
 import { computeEntityTrapdoor, isDigestBlob, } from './claims-helper.js';
 const requireWasm = createRequire(import.meta.url);
 let _wasm = null;
@@ -31,10 +31,10 @@ function getWasm() {
 // ---------------------------------------------------------------------------
 /** Where feedback, decisions, and weights live. `~/.totalreclaw/` by default. */
 function resolveStateDir() {
-    const override = process.env.TOTALRECLAW_STATE_DIR;
-    if (override && override.length > 0)
+    const override = envString('TOTALRECLAW_STATE_DIR');
+    if (override.length > 0)
         return override;
-    return path.join(os.homedir(), '.totalreclaw');
+    return path.join(envHomedir(), '.totalreclaw');
 }
 function ensureStateDir() {
     const dir = resolveStateDir();
@@ -292,7 +292,11 @@ function _resolveWithCandidatesCore(core, input, items, byId) {
     const { newClaim, newClaimId, newEmbedding, weightsJson, thresholdLower, thresholdUpper, nowUnixSeconds, logger } = input;
     let actionsJson;
     try {
-        actionsJson = core.resolveWithCandidates(JSON.stringify(newClaim), newClaimId, JSON.stringify(newEmbedding), JSON.stringify(items), weightsJson, thresholdLower, thresholdUpper, Math.floor(nowUnixSeconds), TIE_ZONE_SCORE_TOLERANCE);
+        actionsJson = core.resolveWithCandidates(JSON.stringify(newClaim), newClaimId, JSON.stringify(newEmbedding), JSON.stringify(items), weightsJson, thresholdLower, thresholdUpper, 
+        // wasm-bindgen declares `now_unix` as i64 → JS BigInt. Node ≥26 rejects
+        // the implicit Number→BigInt coercion that older runtimes tolerated, so
+        // wrap explicitly (same as the legacy path below + loadWeightsFile).
+        BigInt(Math.floor(nowUnixSeconds)), TIE_ZONE_SCORE_TOLERANCE);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -453,7 +457,7 @@ function _resolveWithLegacyPipeline(core, input, items, byId) {
 export async function detectAndResolveContradictions(input) {
     const { newClaim, newClaimId, newEmbedding, subgraphOwner, authKeyHex, encryptionKey, deps, logger, } = input;
     // Read env per-call so tests can toggle without module reload.
-    const raw = (process.env.TOTALRECLAW_AUTO_RESOLVE_MODE ?? '').trim().toLowerCase();
+    const raw = envStringLower('TOTALRECLAW_AUTO_RESOLVE_MODE');
     const mode = raw === 'off' ? 'off' : raw === 'shadow' ? 'shadow' : 'active';
     if (mode === 'off')
         return [];
@@ -687,15 +691,11 @@ export const TUNING_LOOP_MIN_INTERVAL_SECONDS = 3600;
  * empty, non-numeric, or negative.
  */
 export function getTuningLoopMinIntervalSeconds() {
-    const raw = process.env.TOTALRECLAW_TUNING_MIN_INTERVAL_OVERRIDE_SECONDS;
-    if (raw === undefined || raw === null || raw === '') {
-        return TUNING_LOOP_MIN_INTERVAL_SECONDS;
-    }
-    const parsed = Number(raw);
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        return TUNING_LOOP_MIN_INTERVAL_SECONDS;
-    }
-    return parsed;
+    // envNumber returns the fallback for unset/empty/non-finite/negative —
+    // recovering the original 3-guard contract in one call.
+    return envNumber('TOTALRECLAW_TUNING_MIN_INTERVAL_OVERRIDE_SECONDS', TUNING_LOOP_MIN_INTERVAL_SECONDS, {
+        min: 0,
+    });
 }
 /**
  * Walk `decisions.jsonl` in reverse and find the most recent `supersede_existing`

package/dist/credential-provider.js

@@ -0,0 +1,145 @@
+/**
+ * credential-provider — credential source abstraction (cred-3 stage 1).
+ *
+ * The plugin needs to load its `CredentialsFile` (mnemonic + userId + salt +
+ * scope_address) from one of two sources without per-deployment forks:
+ *
+ *   1. `file` — read/write `~/.totalreclaw/credentials.json` directly
+ *      (legacy behavior; default).
+ *   2. `external` — read from a secret manager that exposes the JSON as
+ *      either an env var (Railway secrets, Docker `--env-file`, K8s
+ *      `envFrom`) OR a mounted file path (Docker Compose `secrets:`,
+ *      K8s secret volumeMount, tmpfs populated by an ops wrapper that
+ *      pulls from a managed vault before plugin start).
+ *
+ * Stage 1 introduces the abstraction + integration test. Stage 2 routes
+ * Hermes Python through the same surface; stage 3 routes MCP and ships a
+ * concrete vault adapter. Plugin call sites are not yet rewired to go
+ * through the provider — that's a follow-up so behavior under the default
+ * `file` mode is byte-identical to today.
+ *
+ * Scanner constraints (see skill/scripts/check-scanner.mjs):
+ *   - This file MUST avoid any subprocess module import. Both transport
+ *     flavors here use `node:fs` only.
+ *   - This file MUST avoid network-word substrings to keep the
+ *     exfiltration rule quiet. All env reads are centralized in
+ *     `config.ts`; we accept resolved values here.
+ *
+ * Phrase-safety:
+ *   - The mnemonic is never logged from this file. Errors reference only
+ *     transport names + sizes, never the raw payload.
+ *   - File writes preserve mode `0o600` via the existing fs-helpers
+ *     `writeCredentialsJson`.
+ *   - `external` mode is read-only by design — the secret manager owns
+ *     the source of truth; writing back would split it.
+ */
+import fs from 'node:fs';
+import { CONFIG } from './config.js';
+import { loadCredentialsJson, writeCredentialsJson, deleteCredentialsFile, } from './fs-helpers.js';
+/**
+ * Default provider — delegates to the existing fs-helpers functions.
+ * Behavior is identical to direct `loadCredentialsJson` / `writeCredentialsJson`
+ * / `deleteCredentialsFile` calls, so wiring a call site through this
+ * provider in `file` mode produces zero behavior delta.
+ */
+export class FileCredentialProvider {
+    credentialsPath;
+    mode = 'file';
+    constructor(credentialsPath) {
+        this.credentialsPath = credentialsPath;
+    }
+    load() {
+        return loadCredentialsJson(this.credentialsPath);
+    }
+    save(creds) {
+        return writeCredentialsJson(this.credentialsPath, creds);
+    }
+    clear() {
+        return deleteCredentialsFile(this.credentialsPath);
+    }
+}
+/**
+ * External provider — reads credentials from a secret manager via one of
+ * two transports (env-injected JSON wins if both are set).
+ *
+ *   Inline JSON  (`TOTALRECLAW_EXTERNAL_CREDENTIALS_JSON`)
+ *     The raw `CredentialsFile` JSON, injected as an env var at process
+ *     start. Most ergonomic for managed platforms that expose secrets as
+ *     env vars (Railway secrets, Heroku config vars, K8s `envFrom`).
+ *
+ *   File mount   (`TOTALRECLAW_EXTERNAL_CREDENTIALS_PATH`)
+ *     A path to a JSON file the secret manager mounts. Pattern works for
+ *     Docker Compose `secrets:` blocks, K8s secret `volumeMount`s, and
+ *     tmpfs paths populated by an ops wrapper script that fetched the
+ *     payload from a vault (AWS Secrets Manager, Hetzner Vault, etc.)
+ *     before plugin start.
+ *
+ * Both flavors are read-only — `save()` and `clear()` return `false` and
+ * the caller logs a warn. The secret manager is the canonical source;
+ * writing back would create two competing truths.
+ */
+export class ExternalCredentialProvider {
+    options;
+    mode = 'external';
+    constructor(options) {
+        this.options = options;
+    }
+    load() {
+        const raw = this.readRaw();
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Parse error — return null so the bootstrap path can decide how to
+            // surface (typically: log + fall through to fresh-generate, same as
+            // a corrupt credentials.json on disk). We deliberately do not echo
+            // the payload here even on parse failure.
+            return null;
+        }
+    }
+    save(_creds) {
+        return false;
+    }
+    clear() {
+        return false;
+    }
+    readRaw() {
+        if (this.options.inlineJson !== null) {
+            return this.options.inlineJson;
+        }
+        if (this.options.filePath !== null) {
+            try {
+                if (!fs.existsSync(this.options.filePath))
+                    return null;
+                return fs.readFileSync(this.options.filePath, 'utf-8');
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Factory — pick the configured provider. Reads from `CONFIG` (single
+ * source of truth for env vars) so tests can override by mutating the
+ * config snapshot or by passing explicit deps to the constructors.
+ *
+ * In `external` mode with neither transport set, we still return an
+ * `ExternalCredentialProvider` so the caller observes the configured
+ * mode + sees `null` from `load()`. The caller is responsible for
+ * surfacing the misconfiguration; we do not silently fall back to
+ * `file` mode (that would mask a deploy-time mistake by reading a
+ * stale `credentials.json` left on disk).
+ */
+export function getCredentialProvider(config = CONFIG) {
+    if (config.credentialsProvider === 'external') {
+        return new ExternalCredentialProvider({
+            inlineJson: config.externalCredentialsJson,
+            filePath: config.externalCredentialsPath,
+        });
+    }
+    return new FileCredentialProvider(config.credentialsPath);
+}