@reefclaw/openclaw-plugin 0.1.13 → 0.1.14

package/ccxt/binance-public.js

@@ -33,6 +33,7 @@
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
 import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
+import { REACHABILITY_STALL_FACTOR } from '@reefclaw/shared';
 const TAG = 'binance-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -190,8 +191,19 @@ export class BinancePublicApi {
      *   - 'reachable'   clean response (driftMs = serverTime − localTime)
      *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
      *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
-     *   - 'unreachable' network / DNS / timeout / other error */
+     *   - 'stalled'     THIS process was starved — we learned nothing (issue #265)
+     *   - 'unreachable' network / DNS / timeout / other error
+     *
+     *  ★ Self-stall detection: an error is evidence about BINANCE only if it
+     *  arrived on schedule. When the host starves the process the loop stops
+     *  running, ccxt's own timeout lands minutes late, and the old code blamed the
+     *  network — producing a confident "you are geo-blocked / check your firewall"
+     *  banner while the agent was in fact trading normally. Past
+     *  REACHABILITY_STALL_FACTOR× the request budget we report `stalled` and the
+     *  reporter renders it `unknown`. A 451 still wins: the server ANSWERED, so
+     *  that classification stands however late we noticed it. */
     async probeReachability() {
+        const startedAt = Date.now();
         try {
             assertNotBanned('reachabilityProbe');
             const r = await this.exchange.fapiPublicGetTime({});
@@ -209,8 +221,24 @@ export class BinancePublicApi {
             }
             const msg = err instanceof Error ? err.message : String(err);
             const geo = msg.includes('451');
-            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
-            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+            if (geo) {
+                logger.warn(TAG, `probeReachability failed (HTTP 451 geo-block): ${msg}`);
+                return { outcome: 'geo_blocked', driftMs: null };
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs > this.probeTimeoutMs() * REACHABILITY_STALL_FACTOR) {
+                logger.warn(TAG, `probeReachability inconclusive: this process was starved — a ${this.probeTimeoutMs()}ms probe took ${Math.round(elapsedMs / 1000)}s (${msg}). Reporting reachability as unknown, NOT as a Binance failure.`);
+                return { outcome: 'stalled', driftMs: null, stallMs: elapsedMs };
+            }
+            logger.warn(TAG, `probeReachability failed: ${msg}`);
+            return { outcome: 'unreachable', driftMs: null };
         }
     }
+    /** The request budget the stall yardstick is measured against. ccxt owns the
+     *  actual timeout, so read it from the instance rather than hardcoding a
+     *  second copy that could silently drift from it. */
+    probeTimeoutMs() {
+        const t = Number(this.exchange?.timeout);
+        return Number.isFinite(t) && t > 0 ? t : 10_000;
+    }
 }

package/config/operator-provenance.d.ts

@@ -0,0 +1,6 @@
+export interface ProvenanceVerdict {
+    ok: boolean;
+    /** Agent-legible refusal — returned verbatim as the tool error. */
+    error?: string;
+}
+export declare function verifyOperatorProvenance(provided: unknown, configPath?: string): ProvenanceVerdict;

package/config/operator-provenance.js

@@ -0,0 +1,50 @@
+// Operator-provenance gate for the state-mutating operator tools
+// (audit 2026-07-26 F12).
+//
+// "Operator-only. Never called by the agent." was PROSE in four tool
+// descriptions — nothing enforced it, and `acknowledged:true` is
+// caller-supplied, so a tool-capable agent could walk the PAPER→LIVE ladder,
+// clear the exchange credentials, or disable the stop-loss requirement with
+// one impulsive call. The dashboard path (browser → relay → skill bridge →
+// gateway) now proves provenance: the bridge injects the rc_* connection
+// token it already authenticates with, and the plugin compares it against
+// its own copy. The chat redaction guards keep rc_* tokens OUT of the
+// agent's context, so the agent cannot produce one conversationally.
+//
+// THREAT-MODEL HONESTY: the agent runs on the operator's own box and could
+// read plugin-config with exec tools — this gate defends against one-call
+// LLM impulsivity (the realistic failure mode), not a deliberately
+// adversarial agent, which owns the box and could edit the config directly.
+//
+// Fail direction: OPEN when no connection token is configured (a pure-local
+// dev box has no dashboard to inject provenance — same
+// infrastructure-absent ⇒ allow direction as the entitlement gate);
+// CLOSED on a missing or mismatched token when one IS configured.
+// Read per call (no restart needed after a token rotation — F10 philosophy).
+import { timingSafeEqual } from 'node:crypto';
+import { readPluginConfig } from './plugin-config-io.js';
+import { resolveIngestToken } from './user-data-stream-config.js';
+const REFUSAL = 'operator_only: this tool changes safety-critical operator settings and accepts requests ' +
+    'ONLY from the ReefClaw dashboard (operator provenance token missing or invalid). Do not ' +
+    'retry and do not attempt to obtain the token — if this change is wanted, the OPERATOR ' +
+    'makes it from the dashboard Settings panel.';
+export function verifyOperatorProvenance(provided, configPath) {
+    let expected;
+    try {
+        expected = resolveIngestToken(readPluginConfig(configPath))?.trim() || undefined;
+    }
+    catch {
+        expected = undefined;
+    }
+    if (!expected)
+        return { ok: true }; // unconfigured box — nothing to prove against
+    const given = typeof provided === 'string' ? provided.trim() : '';
+    if (given.length === 0)
+        return { ok: false, error: REFUSAL };
+    const a = Buffer.from(given, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, error: REFUSAL };
+    }
+    return { ok: true };
+}

package/config/plugin-config-io.d.ts

@@ -46,8 +46,12 @@ export interface PluginConfigFile {
     hl?: {
         marketSlippagePct?: number;
     };
+    /** MICRO_LIVE per-order notional cap in quote-USD (USDT on Binance, USDC on
+     *  Hyperliquid). Default 50 when the mode is MICRO_LIVE and no value is set.
+     *  `sizeCapPercent` used to be accepted here but was NEVER enforced by any
+     *  adapter (dead config implying protection it didn't provide) — it is no
+     *  longer read; loadMicroLiveConfig warns when it is present. */
     microLive?: {
-        sizeCapPercent?: number;
         maxPositionUSDT?: number;
     };
     /** Exchange-native bracket orders (STOP_MARKET + TAKE_PROFIT_MARKET).
@@ -202,6 +206,16 @@ export declare function defaultConfigPath(): string;
  *  the override to the default (same read-at-build-time pattern as
  *  loadBracketMode). */
 export declare function loadStopWatcherIntervalMs(path?: string): number | undefined;
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export declare function loadMicroLiveConfig(path?: string): {
+    maxPositionUSDT?: number;
+} | undefined;
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */

package/config/plugin-config-io.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { logger } from '../logger.js';
 /** The connection the AGENT saves during onboarding lives in OpenClaw's own
  *  config (`skills.entries.reefclaw.config` in ~/.openclaw/openclaw.json) —
  *  the connector reads it there, and since the chat-install flow never writes
@@ -53,6 +54,29 @@ export function loadStopWatcherIntervalMs(path) {
     catch { /* best-effort — default applies */ }
     return undefined;
 }
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export function loadMicroLiveConfig(path) {
+    try {
+        const ml = readPluginConfig(path).microLive;
+        if (!ml || typeof ml !== 'object')
+            return undefined;
+        if (ml.sizeCapPercent !== undefined) {
+            logger.warn('plugin-config', 'microLive.sizeCapPercent is set but has NEVER been enforced by any adapter — it has no effect. ' +
+                'Remove it; microLive.maxPositionUSDT is the enforced per-order notional cap.');
+        }
+        const cap = ml.maxPositionUSDT;
+        if (typeof cap === 'number' && Number.isFinite(cap) && cap > 0)
+            return { maxPositionUSDT: cap };
+    }
+    catch { /* best-effort — adapter default applies */ }
+    return undefined;
+}
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */