@reefclaw/connect 0.1.0

package/assets/bridge/utils/skill-signing.js

@@ -0,0 +1,138 @@
+// Ed25519 signature verification for OTA SKILL.md updates.
+//
+// Security finding C1 (docs/PRE_LAUNCH_SECURITY_HARDENING.md §2.5 + Appendix B):
+// the relay is treated as a DUMB TRANSPORT. A pushed/pulled SKILL.md is applied
+// only if it carries a valid signature from the operator's offline private key,
+// whose PUBLIC key is pinned here in the build. A leaked ADMIN_SECRET, a
+// compromised relay process, or a tampered Durable-Object value therefore
+// CANNOT rewrite an agent's trading instructions — they all fail verification.
+//
+// Key provisioning (one-time, operator, OFFLINE):
+//   1. python scripts/gen-skill-signing-key.py
+//   2. paste the printed PUBLIC key (base64) into TRUSTED_SKILL_SIGNING_KEYS below
+//   3. put the printed PRIVATE key into .env.deploy as SKILL_SIGNING_PRIVATE_KEY
+//      (gitignored — keep it offline; NEVER on the relay or any server)
+//   4. rebuild + redeploy the skill (deploy-skillmd-ota.py is already wired to sign)
+//
+// Until a key is pinned, OTA is FAIL-CLOSED (every push rejected) while
+// SKILL_OTA_REQUIRE_SIGNATURE is on (the default). Normal trading is unaffected
+// — only the OTA-update path gates on this.
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseSkillVersion } from './skill-version.js';
+/**
+ * Pinned Ed25519 PUBLIC keys (base64 of the raw 32-byte key) trusted to sign OTA
+ * SKILL.md updates. Multiple entries enable key rotation (accept current + next,
+ * retire the old after every client has updated). EMPTY until the operator pins
+ * one — see the header for provisioning.
+ */
+export const TRUSTED_SKILL_SIGNING_KEYS = [
+// 'Base64OfRaw32BytePublicKey=' ← paste from scripts/gen-skill-signing-key.py
+];
+const OTA_STATE_PATH = join(homedir(), '.openclaw', 'workspace', '.skill-ota-state.json');
+/** Lowercase hex SHA-256 of the UTF-8 content. MUST match the Python signer. */
+export function sha256Hex(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Canonical signed message — MUST match deploy-skillmd-ota.py byte-for-byte. */
+export function signedMessage(version, contentSha256, signedAt) {
+    return `${version}\n${contentSha256}\n${signedAt}`;
+}
+/**
+ * Is OTA signature verification enforced?
+ *
+ * Default **OFF** while C1 (signed OTA) is ON HOLD — see
+ * docs/PRE_LAUNCH_SECURITY_HARDENING.md §2.5. Keeping it off by default makes
+ * this whole module DORMANT, so deploying skill/relay for UNRELATED reasons can
+ * never break the existing (unsigned) OTA flow — no env flag to remember.
+ *
+ * To ENABLE signed-OTA (when the agent-update mechanism is finalized): pin a
+ * public key in TRUSTED_SKILL_SIGNING_KEYS **and** set
+ * SKILL_OTA_REQUIRE_SIGNATURE=on. Both are required — a pinned key alone does
+ * nothing without the flag, and the flag alone fails closed (no key → reject).
+ */
+export function signatureRequired() {
+    return (process.env.SKILL_OTA_REQUIRE_SIGNATURE ?? 'off').toLowerCase() === 'on';
+}
+function publicKeyFromRawB64(b64) {
+    try {
+        const raw = Buffer.from(b64, 'base64');
+        if (raw.length !== 32)
+            return null; // raw Ed25519 public key is exactly 32 bytes
+        return createPublicKey({
+            format: 'jwk',
+            key: { kty: 'OKP', crv: 'Ed25519', x: raw.toString('base64url') },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify a signed OTA envelope against the pinned (or supplied) trusted keys.
+ * Checks: required fields present, content hash matches (no tampering), the
+ * frontmatter version matches the signed version (no number-bump replay), and
+ * the Ed25519 signature verifies under some trusted key. Pure — does NOT touch
+ * disk or the replay clock; the caller enforces monotonic signedAt.
+ */
+export function verifySkillSignature(env, opts) {
+    const keys = opts?.trustedKeys ?? TRUSTED_SKILL_SIGNING_KEYS;
+    if (keys.length === 0) {
+        return { ok: false, reason: 'no trusted signing keys configured — pin a public key in skill-signing.ts (see scripts/gen-skill-signing-key.py)' };
+    }
+    if (!env.signature || !env.signedAt || !env.contentSha256) {
+        return { ok: false, reason: 'missing signature/signedAt/contentSha256 (unsigned push)' };
+    }
+    if (sha256Hex(env.content) !== env.contentSha256) {
+        return { ok: false, reason: 'content hash mismatch (tampered content)' };
+    }
+    const frontmatterVersion = parseSkillVersion(env.content);
+    if (frontmatterVersion !== env.version) {
+        return { ok: false, reason: `version mismatch (envelope ${env.version} vs frontmatter ${frontmatterVersion ?? 'none'})` };
+    }
+    const msg = Buffer.from(signedMessage(env.version, env.contentSha256, env.signedAt), 'utf8');
+    let sig;
+    try {
+        sig = Buffer.from(env.signature, 'base64');
+    }
+    catch {
+        return { ok: false, reason: 'signature is not valid base64' };
+    }
+    for (const keyB64 of keys) {
+        const pub = publicKeyFromRawB64(keyB64);
+        if (!pub)
+            continue;
+        try {
+            if (cryptoVerify(null, msg, pub, sig))
+                return { ok: true };
+        }
+        catch {
+            /* malformed key/sig for this candidate — try the next */
+        }
+    }
+    return { ok: false, reason: 'signature does not verify under any trusted key' };
+}
+/** Last applied signedAt as epoch ms, 0 if none/unreadable (replay clock). */
+export function readLastAppliedSignedAtMs() {
+    try {
+        const raw = readFileSync(OTA_STATE_PATH, 'utf-8');
+        const t = JSON.parse(raw).lastAppliedSignedAt;
+        const ms = t ? new Date(t).getTime() : 0;
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Persist the signedAt of the just-applied update (monotonic replay clock). */
+export function recordAppliedSignedAt(signedAt) {
+    try {
+        mkdirSync(join(homedir(), '.openclaw', 'workspace'), { recursive: true });
+        writeFileSync(OTA_STATE_PATH, JSON.stringify({ lastAppliedSignedAt: signedAt }), 'utf-8');
+    }
+    catch {
+        /* best-effort — if this fails the replay window is bounded to one process life */
+    }
+}

package/assets/bridge/utils/skill-version.d.ts

@@ -0,0 +1,17 @@
+/** Extract version from SKILL.md frontmatter */
+export declare function parseSkillVersion(content: string): string | null;
+/** Read current SKILL.md version from disk */
+export declare function readLocalSkillVersion(): string | null;
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Non-semver inputs (or null) are treated as -Infinity so a valid semver always
+ * wins, which is the safe direction for "should I accept this OTA push?".
+ */
+export declare function compareSemver(a: string | null, b: string | null): number;
+/** Validate SKILL.md content is well-formed */
+export declare function validateSkillContent(content: string): {
+    valid: boolean;
+    version: string | null;
+    error?: string;
+};

package/assets/bridge/utils/skill-version.js

@@ -0,0 +1,71 @@
+// SKILL.md version parsing utility for OTA updates
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
+/** Extract version from SKILL.md frontmatter */
+export function parseSkillVersion(content) {
+    const match = content.match(/^---[\s\S]*?version:\s*(\S+)[\s\S]*?---/);
+    return match ? match[1] : null;
+}
+/** Read current SKILL.md version from disk */
+export function readLocalSkillVersion() {
+    try {
+        const content = readFileSync(SKILL_MD_PATH, 'utf-8');
+        return parseSkillVersion(content);
+    }
+    catch {
+        return null;
+    }
+}
+const MAX_SKILL_CONTENT_SIZE = 100_000; // 100KB
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Non-semver inputs (or null) are treated as -Infinity so a valid semver always
+ * wins, which is the safe direction for "should I accept this OTA push?".
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        if (!v || !SEMVER_REGEX.test(v))
+            return null;
+        const [maj, min, pat] = v.split('.').map(Number);
+        return [maj, min, pat];
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa && !pb)
+        return 0;
+    if (!pa)
+        return -1;
+    if (!pb)
+        return 1;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return 1;
+        if (pa[i] < pb[i])
+            return -1;
+    }
+    return 0;
+}
+/** Validate SKILL.md content is well-formed */
+export function validateSkillContent(content) {
+    if (content.length > MAX_SKILL_CONTENT_SIZE) {
+        return { valid: false, version: null, error: `Content too large (${content.length} bytes, max ${MAX_SKILL_CONTENT_SIZE})` };
+    }
+    if (!content.startsWith('---')) {
+        return { valid: false, version: null, error: 'Missing frontmatter delimiter' };
+    }
+    const version = parseSkillVersion(content);
+    if (!version) {
+        return { valid: false, version: null, error: 'No version in frontmatter' };
+    }
+    if (!SEMVER_REGEX.test(version)) {
+        return { valid: false, version, error: `Invalid version format: ${version} (expected semver x.y.z)` };
+    }
+    if (content.length < 100) {
+        return { valid: false, version, error: 'Content suspiciously short' };
+    }
+    return { valid: true, version };
+}

package/assets/plugin/audit/mode-transition-audit.d.ts

@@ -0,0 +1,11 @@
+import type { TradingMode } from '../types.js';
+export interface ModeTransitionAuditEntry {
+    ts: string;
+    previousMode: TradingMode;
+    targetMode: TradingMode;
+    acknowledged: boolean;
+    ok: boolean;
+    reason?: string;
+    testnet?: boolean;
+}
+export declare function recordModeTransition(entry: Omit<ModeTransitionAuditEntry, 'ts'>, pluginId?: string): void;

package/assets/plugin/audit/mode-transition-audit.js

@@ -0,0 +1,29 @@
+// Mode-transition audit — append-only JSONL record of every set_trading_mode call.
+//
+// Written BEFORE the adapter swap (so even a crashed transition leaves a trail)
+// and updated with the outcome. Intended for post-incident review and regulatory
+// defence ("the operator acknowledged the LIVE transition at 2026-04-20T14:32:11Z").
+//
+// Path: ~/.openclaw/plugins/<pluginId>/mode-transitions.jsonl
+// Append-only; never truncated. One JSON object per line.
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'mode-audit';
+function resolvePath(pluginId) {
+    const dir = join(resolvePluginsBaseDir(), pluginId ?? 'reefclaw-paper-trading');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return join(dir, 'mode-transitions.jsonl');
+}
+export function recordModeTransition(entry, pluginId) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    try {
+        appendFileSync(resolvePath(pluginId), JSON.stringify(full) + '\n', 'utf8');
+        logger.info(TAG, `${full.previousMode} → ${full.targetMode} ok=${full.ok} ack=${full.acknowledged}`);
+    }
+    catch (err) {
+        logger.error(TAG, `Failed to write audit entry: ${formatError(err)}`);
+    }
+}

package/assets/plugin/balance-utils.d.ts

@@ -0,0 +1,36 @@
+import type { CcxtBalance } from './types.js';
+/**
+ * Read the total quote-currency balance from a CCXT balance map.
+ *
+ * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
+ * the larger balance. Summing both was incorrect because Binance
+ * cross-margin accounting reports position margin/value as a phantom
+ * balance in the settlement currency (e.g., opening an ATOM/USDT
+ * position with a USDC-funded account creates a USDT "balance" entry
+ * equal to the position's notional, inflating getQuoteBalance by the
+ * position value and causing the KPI to double-count).
+ *
+ * For wallet/equity/NAV reads on Binance Futures, prefer
+ * `getQuoteWalletBalance(balance)` — it handles BNFCR.
+ */
+export declare function getQuoteBalance(balanceMap: Record<string, number> | undefined): number;
+/**
+ * Read the effective wallet-equivalent quote balance from a Binance Futures
+ * fetchBalance response, including the BNFCR realized-PnL accumulator.
+ *
+ * Why this exists: Binance multi-asset accounts settle realized PnL into
+ * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
+ * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
+ * mixes uPnl into the total, which double-counts when the caller adds
+ * position uPnl on top. This helper reads `info.assets[i].walletBalance`
+ * directly, which excludes uPnl by construction.
+ *
+ * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
+ * (not max'd) because it is independent of the funded stablecoin — a
+ * USDC-funded account with cumulative losses shows USDC unchanged plus
+ * BNFCR negative; the user's true wallet is the sum.
+ *
+ * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
+ * absent (mock balances in unit tests, non-Binance exchanges).
+ */
+export declare function getQuoteWalletBalance(balance: CcxtBalance | null | undefined): number;

package/assets/plugin/balance-utils.js

@@ -0,0 +1,98 @@
+// Utility for reading quote-currency balance from CCXT balance objects.
+// Binance USDⓈ-M Futures settles in USDT or USDC — accounts may hold either or both.
+// On multi-asset accounts a third asset, BNFCR, accumulates realized PnL as a
+// signed wallet line (negative = cumulative loss, positive = cumulative gain).
+/**
+ * Read the total quote-currency balance from a CCXT balance map.
+ *
+ * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
+ * the larger balance. Summing both was incorrect because Binance
+ * cross-margin accounting reports position margin/value as a phantom
+ * balance in the settlement currency (e.g., opening an ATOM/USDT
+ * position with a USDC-funded account creates a USDT "balance" entry
+ * equal to the position's notional, inflating getQuoteBalance by the
+ * position value and causing the KPI to double-count).
+ *
+ * For wallet/equity/NAV reads on Binance Futures, prefer
+ * `getQuoteWalletBalance(balance)` — it handles BNFCR.
+ */
+export function getQuoteBalance(balanceMap) {
+    if (!balanceMap)
+        return 0;
+    const usdt = balanceMap.USDT ?? 0;
+    const usdc = balanceMap.USDC ?? 0;
+    // Use whichever currency has the larger wallet balance (the funded one).
+    // If both are zero, return 0. If both are funded, use the larger.
+    return Math.max(usdt, usdc);
+}
+/**
+ * Read the effective wallet-equivalent quote balance from a Binance Futures
+ * fetchBalance response, including the BNFCR realized-PnL accumulator.
+ *
+ * Why this exists: Binance multi-asset accounts settle realized PnL into
+ * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
+ * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
+ * mixes uPnl into the total, which double-counts when the caller adds
+ * position uPnl on top. This helper reads `info.assets[i].walletBalance`
+ * directly, which excludes uPnl by construction.
+ *
+ * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
+ * (not max'd) because it is independent of the funded stablecoin — a
+ * USDC-funded account with cumulative losses shows USDC unchanged plus
+ * BNFCR negative; the user's true wallet is the sum.
+ *
+ * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
+ * absent (mock balances in unit tests, non-Binance exchanges).
+ */
+export function getQuoteWalletBalance(balance) {
+    if (!balance)
+        return 0;
+    // Prefer Binance's own account-level wallet aggregate when present.
+    // `/fapi/v3/account` (CCXT passes it through verbatim at `info`) returns
+    // `totalWalletBalance` — in Multi-Assets Mode this is the USD-denominated
+    // sum across all margin assets, with each non-USD collateral valued at
+    // Binance's live index price (verified against developers.binance.com →
+    // Account Information V3, 2026-05-16). It also excludes uPnL by
+    // construction (marginBalance = walletBalance + uPnL), matching this
+    // function's "wallet, uPnL added by caller" contract.
+    //
+    // Why this beats the per-asset reconstruction below: summing
+    // `max(USDT,USDC) + BNFCR` values USDC at FACE 1.0000, but Binance values
+    // USDC collateral at the live USDC/USD index (~0.9998). That made the
+    // dashboard wallet permanently ~$0.2 high vs the Binance app on this
+    // account (always-on, same-sign, slowly varying with the USDC peg —
+    // 2026-05-16 "figures slightly off always"). totalWalletBalance is the
+    // exact number the app's Futures "Wallet Balance" shows. The read path is
+    // already REST (`LiveAdapter.getBalance` → `fetchBalance()` every poll),
+    // so this is zero freshness regression — same cadence, correct value.
+    const info = balance?.info;
+    if (info && info.totalWalletBalance != null) {
+        const twb = parseFloat(String(info.totalWalletBalance));
+        if (Number.isFinite(twb))
+            return twb;
+    }
+    // Fallback (no Binance aggregate — non-Binance exchange, mock balances in
+    // unit tests, or a WS-store-derived balance object): the legacy
+    // face-value per-asset reconstruction. Carries the documented ~USDC-index
+    // drift but is the best available when the aggregate is absent.
+    const assets = balance?.info?.assets;
+    if (!Array.isArray(assets))
+        return getQuoteBalance(balance.total);
+    let usdt = 0;
+    let usdc = 0;
+    let bnfcr = 0;
+    for (const a of assets) {
+        if (!a || typeof a.asset !== 'string')
+            continue;
+        const wb = parseFloat(String(a.walletBalance ?? 0));
+        if (!Number.isFinite(wb))
+            continue;
+        if (a.asset === 'USDT')
+            usdt = wb;
+        else if (a.asset === 'USDC')
+            usdc = wb;
+        else if (a.asset === 'BNFCR')
+            bnfcr = wb;
+    }
+    return Math.max(usdt, usdc) + bnfcr;
+}

package/assets/plugin/ccxt/binance-ban-gate.d.ts

@@ -0,0 +1,47 @@
+/** Thrown by `assertNotBanned` while the gate is closed. Carries the
+ *  remaining cooldown so callers/telemetry can reason about it. Methods
+ *  catch this in their existing catch block — it is NOT meant to escape
+ *  the API layer with special handling; it degrades to the method's normal
+ *  failure contract. */
+export declare class BinanceBannedError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, context: string);
+}
+/** Thrown by the proactive weight pacer. Subclass of BinanceBannedError so
+ *  every `instanceof BinanceBannedError` check and every method's existing
+ *  catch keep working unchanged — it degrades to the same null/[]/throw
+ *  contract (treated exactly like a transient fetch failure). The distinct
+ *  name lets journal/telemetry tell prevention apart from a real IP ban. */
+export declare class BinanceWeightPacedError extends BinanceBannedError {
+    constructor(retryAfterMs: number, context: string);
+}
+/** Fast pre-flight check. Call as the first line inside a Binance call's
+ *  try-block. Throws `BinanceBannedError` (no network) while the gate is
+ *  open. */
+export declare function assertNotBanned(context: string): void;
+/** Inspect a failed call's error and arm/extend the gate on a Binance
+ *  rate-limit signal. Non-rate-limit errors are ignored (normal transient
+ *  handling stays in the caller). Safe to call with any error shape. */
+export declare function noteBinanceError(err: unknown): void;
+/** Relax the soft-429 ladder after a clean call. (A hard 418 window is NOT
+ *  shortened by this — only Binance's stated expiry clears it.) */
+export declare function noteSuccess(): void;
+/** Reconcile the local weight estimate against Binance truth from a response
+ *  header (`x-mbx-used-weight-1m`). Best-effort: callers pass whatever header
+ *  bag they have; absent/garbage values are ignored. The local estimate
+ *  leads (counts in-flight calls Binance hasn't tallied yet), so we take the
+ *  MAX within the window — never let a lagging header lower our guard. A
+ *  header far BELOW the estimate means Binance's minute rolled; re-anchor the
+ *  window to Binance's clock so we don't shed for a stale local total. */
+export declare function noteResponseWeight(headers: Record<string, string> | undefined | null): void;
+/** Test/diagnostic helper — current gate state. */
+export declare function getBanGateState(): {
+    banUntilMs: number;
+    remainingMs: number;
+    rateLimitStep: number;
+    weightUsed: number;
+    weightCeiling: number;
+    cosmeticCeiling: number;
+};
+/** Test-only reset. Not used in production code paths. */
+export declare function __resetBanGateForTests(): void;