@totalreclaw/totalreclaw 3.3.12-rc.2 → 3.3.12-rc.21

package/dist/batch-gate.js

@@ -0,0 +1,40 @@
+/**
+ * Boot-time chain-gate predicate for client-side `executeBatch` UserOp
+ * submission. Spec #281 §9 Phase 1 (item imp-16).
+ *
+ * The gate batches via `executeBatch` on Gnosis (chain 100). After ops-1
+ * (2026-06-05) BOTH tiers run on Gnosis, so both now batch — the chain==100
+ * check is retained as a safety guard (a non-100 chain, which shouldn't occur
+ * after ops-1, falls back to single-fact). The legacy Free ⇒ Base Sepolia
+ * (84532) single-fact path is gone with the retired two-tier routing (#402).
+ * The `TOTALRECLAW_GNOSIS_BATCH_ENABLED` env var is a hard kill-switch —
+ * setting it to `false` disables batching regardless of chain, so ops can
+ * revert to single-fact submission without a client redeploy. Behaviour of
+ * `shouldBatchOnChain` is unchanged by #402.
+ *
+ * Read at boot only (module-load time). Per-write reads would re-parse the
+ * env on every submission — too expensive for the auto-extraction hot path
+ * and pointless because the env doesn't change mid-process.
+ *
+ * Sibling work-leaves wire `shouldBatchOnChain` into `submitFactBatchOnChain`
+ * (TS) and `agent/lifecycle.py` (Python mirror in `batch_gate.py`); this
+ * module ships the primitive only.
+ *
+ * Env read is centralized in entry.ts (env-reading seam, Task 1.3 of the
+ * OpenClaw native integration plan, 2026-06-21).
+ */
+import { isGnosisBatchEnabledAtBoot } from './entry.js';
+const GNOSIS_CHAIN_ID = 100;
+export function shouldBatchOnChain(chainId) {
+    if (!isGnosisBatchEnabledAtBoot())
+        return false;
+    return chainId === GNOSIS_CHAIN_ID;
+}
+export const __testing = {
+    readGateForTests(env, chainId) {
+        const enabled = (env.TOTALRECLAW_GNOSIS_BATCH_ENABLED ?? '').toLowerCase() !== 'false';
+        if (!enabled)
+            return false;
+        return chainId === GNOSIS_CHAIN_ID;
+    },
+};

package/dist/billing-cache.js

@@ -11,8 +11,9 @@
  * 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`)
  *   - does NOT import anything that performs outbound I/O
  *
  * Do NOT add any outbound-request call to this file — a single match for
@@ -33,25 +34,21 @@ 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);
 }
 // ---------------------------------------------------------------------------
 // Read / write
@@ -71,8 +68,9 @@ 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 override in sync with the persisted authoritative chain_id
+        // across process restarts.
+        syncChainIdFromBilling(raw.chain_id);
         return raw;
     }
     catch {
@@ -96,5 +94,5 @@ export function writeBillingCache(cache) {
     }
     // 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);
+    syncChainIdFromBilling(cache.chain_id);
 }

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);
@@ -181,6 +182,11 @@ export function buildCanonicalClaimV1(input) {
     if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
         canonical.embedding_model_id = input.embeddingModelId;
     }
+    // am-1: Crystal-shaped debrief structured metadata. Re-attached after
+    // validation using the same plugin-extra pattern as volatility.
+    if (fact.crystalMetadata) {
+        canonical.metadata = fact.crystalMetadata;
+    }
     return JSON.stringify(canonical);
 }
 /**
@@ -406,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
@@ -133,6 +133,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,19 +202,19 @@ 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;
     },
     dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
     entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
@@ -202,6 +238,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);
+}

package/dist/crypto.js

@@ -1,138 +1,18 @@
 /**
- * TotalReclaw Plugin - Crypto Operations (WASM-backed)
- *
- * Thin re-exports over `@totalreclaw/core` WASM module. Same function
- * signatures as the previous implementation so callers don't need to change.
- *
- * The WASM module handles BIP-39 key derivation, XChaCha20-Poly1305 encrypt/
- * decrypt, SHA-256 blind indices, HMAC-SHA256 content fingerprints,
- * and LSH seed derivation.
- *
- * Key derivation chain (BIP-39 — handled by WASM):
- *   mnemonic -> BIP-39 PBKDF2 -> 512-bit seed
- *     -> HKDF-SHA256(seed, salt, "totalreclaw-auth-key-v1",       32) -> authKey
- *     -> HKDF-SHA256(seed, salt, "totalreclaw-encryption-key-v1", 32) -> encryptionKey
- *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
- */
-// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
-// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
-// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
-// this file called bare `require('@totalreclaw/core')` and every consumer
-// died with `require is not defined`. Matches the pattern already used by
-// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
-// retype-setscope. See issue #124.
-import { createRequire } from 'node:module';
-const requireWasm = createRequire(import.meta.url);
-let _wasm = null;
-function getWasm() {
-    if (!_wasm)
-        _wasm = requireWasm('@totalreclaw/core');
-    return _wasm;
-}
-// ---------------------------------------------------------------------------
-// BIP-39 Validation
-// ---------------------------------------------------------------------------
-/**
- * Check if the input looks like a BIP-39 mnemonic (12 or 24 words).
- *
- * Lenient: accepts phrases where all words look like valid BIP-39 words
- * (allows invalid checksums, which LLMs sometimes generate).
- */
-export function isBip39Mnemonic(input) {
-    const words = input.trim().split(/\s+/);
-    return words.length === 12 || words.length === 24;
-}
-// Re-export for backward compatibility
-export const validateMnemonic = isBip39Mnemonic;
-// ---------------------------------------------------------------------------
-// Key Derivation
-// ---------------------------------------------------------------------------
-/**
- * Derive auth, encryption, and dedup keys from a recovery phrase.
- *
- * Delegates to the WASM module for BIP-39 seed derivation and HKDF
- * key separation. Uses the lenient variant for phrases where all words
- * are valid but the checksum fails.
- *
- * @param password     - BIP-39 12/24-word mnemonic
- * @param existingSalt - Ignored for BIP-39 path (salt is deterministic)
- */
-export function deriveKeys(password, existingSalt) {
-    const trimmed = password.trim();
-    // Try strict validation first, fall back to lenient
-    let result;
-    try {
-        result = getWasm().deriveKeysFromMnemonic(trimmed);
-    }
-    catch {
-        result = getWasm().deriveKeysFromMnemonicLenient(trimmed);
-    }
-    return {
-        authKey: Buffer.from(result.auth_key, 'hex'),
-        encryptionKey: Buffer.from(result.encryption_key, 'hex'),
-        dedupKey: Buffer.from(result.dedup_key, 'hex'),
-        salt: Buffer.from(result.salt, 'hex'),
-    };
-}
-// ---------------------------------------------------------------------------
-// LSH Seed Derivation
-// ---------------------------------------------------------------------------
-/**
- * Derive a 32-byte seed for the LSH hasher.
- *
- * Delegates to the WASM module.
- */
-export function deriveLshSeed(password, salt) {
-    const seedHex = getWasm().deriveLshSeed(password.trim(), salt.toString('hex'));
-    return new Uint8Array(Buffer.from(seedHex, 'hex'));
-}
-// ---------------------------------------------------------------------------
-// Auth Key Hash
-// ---------------------------------------------------------------------------
-/**
- * Compute the SHA-256 hash of the auth key.
- */
-export function computeAuthKeyHash(authKey) {
-    return getWasm().computeAuthKeyHash(authKey.toString('hex'));
-}
-// ---------------------------------------------------------------------------
-// XChaCha20-Poly1305 Encrypt / Decrypt
-// ---------------------------------------------------------------------------
-/**
- * Encrypt a UTF-8 plaintext string with XChaCha20-Poly1305.
- *
- * Wire format (base64-encoded):
- *   [nonce: 24 bytes][tag: 16 bytes][ciphertext: variable]
- */
-export function encrypt(plaintext, encryptionKey) {
-    return getWasm().encrypt(plaintext, encryptionKey.toString('hex'));
-}
-/**
- * Decrypt a base64-encoded XChaCha20-Poly1305 blob back to a UTF-8 string.
- */
-export function decrypt(encryptedBase64, encryptionKey) {
-    return getWasm().decrypt(encryptedBase64, encryptionKey.toString('hex'));
-}
-// ---------------------------------------------------------------------------
-// Blind Indices
-// ---------------------------------------------------------------------------
-/**
- * Generate blind indices (SHA-256 hashes of tokens) for a text string.
- *
- * Delegates to the WASM module which performs tokenization, stemming,
- * and SHA-256 hashing.
- */
-export function generateBlindIndices(text) {
-    return getWasm().generateBlindIndices(text);
-}
-// ---------------------------------------------------------------------------
-// Content Fingerprint (Dedup)
-// ---------------------------------------------------------------------------
-/**
- * Compute an HMAC-SHA256 content fingerprint for exact-duplicate detection.
- *
- * @returns 64-character hex string.
- */
-export function generateContentFingerprint(plaintext, dedupKey) {
-    return getWasm().generateContentFingerprint(plaintext, dedupKey.toString('hex'));
-}
+ * crypto.ts — legacy re-export shim.
+ *
+ * Phase 1 (Task 1.1) of the OpenClaw native integration
+ * (docs/plans/2026-06-21-openclaw-native-integration-plan.md, 2026-06-21):
+ * the pure-compute vault primitives (XChaCha20-Poly1305 encrypt/decrypt,
+ * BIP-39 key derivation, blind indices, content fingerprints, LSH seed,
+ * auth-key hash) have moved to `vault-crypto.ts`. This file remains as a
+ * thin re-export so existing importers (`index.ts`, `tr-cli.ts`,
+ * `tr-cli-export-helper.ts`, `pair-cli-relay.ts`) do not break in this
+ * pass — a big-bang rewrite of the 331KB monolith's import graph is out
+ * of scope for the scanner-clean split.
+ *
+ * Nothing here reads the environment or hits the network; all key
+ * material and nonces are passed in by callers. See vault-crypto.ts for
+ * the implementation.
+ */
+export { isBip39Mnemonic, validateMnemonic, deriveKeys, deriveLshSeed, computeAuthKeyHash, encrypt, decrypt, generateBlindIndices, generateContentFingerprint, } from './vault-crypto.js';