@reefclaw/connect 0.1.26 → 0.1.28

package/assets/plugin/venues/hyperliquid/hl-agent-wallet.js

@@ -0,0 +1,118 @@
+// Hyperliquid agent-wallet helpers — format validation + address derivation.
+//
+// Why derivation exists at all: the single most catastrophic mistake a
+// non-technical trader can make in the HL onboarding form is pasting their
+// MASTER wallet's private key where the AGENT key belongs (the master key can
+// withdraw everything; the agent key can only trade). The form cannot tell the
+// two apart — both are 32-byte hex — but the box can: derive the address from
+// the pasted key and refuse when it equals the master walletAddress. The same
+// derived address also lets test_exchange_credentials verify the agent is
+// actually APPROVED for the master account (POST /info extraAgents) before the
+// user goes live.
+//
+// Derivation = secp256k1 pubkey (node:crypto createECDH — stable Node API) +
+// keccak-256 of the 64-byte public key, last 20 bytes (the Ethereum address
+// rule). Node has no keccak (its sha3-256 is NIST-padded, a different hash),
+// so keccak_256 comes from ccxt's vendored noble-hashes — ccxt is pinned at
+// 4.5.37 and the deep path is guarded by a known-vector unit test
+// (hl-agent-wallet.test.ts), so a ccxt bump that moves the file fails loudly.
+// If the import ever breaks at runtime we degrade gracefully: derivation
+// reports 'unavailable' and callers skip the address checks rather than
+// blocking credential entry.
+//
+// SECURITY: this module handles the raw agent private key in memory only —
+// it never logs it, never persists it, and never puts it in a return value.
+import { createECDH, randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+/** secp256k1 group order n — a private key must be in [1, n-1]. */
+const SECP256K1_ORDER = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+/** Generate a fresh secp256k1 private key (0x-prefixed, 64 hex chars) from
+ *  CSPRNG bytes, rejection-sampled into the valid scalar range. This is how
+ *  the box mints its own HL agent wallet — the key is BORN here and never
+ *  leaves the machine (the caller persists it to plugin-config and surfaces
+ *  only the derived PUBLIC address). */
+export function generateAgentPrivateKey() {
+    // Rejection probability per draw is ~2^-128 (order ≈ 2^256) — the loop is
+    // for correctness, not because retries are expected.
+    for (;;) {
+        const candidate = randomBytes(32);
+        const scalar = BigInt(`0x${candidate.toString('hex')}`);
+        if (scalar > 0n && scalar < SECP256K1_ORDER) {
+            return `0x${candidate.toString('hex')}`;
+        }
+    }
+}
+/** Master/agent wallet address: 0x + 40 hex chars. */
+export function isHexAddress(value) {
+    return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value.trim());
+}
+/** Agent private key: 32 bytes of hex, 0x prefix optional (the HL app shows it
+ *  with the prefix; some wallets export without). */
+export function isHexPrivateKey(value) {
+    return typeof value === 'string' && /^(0x)?[0-9a-fA-F]{64}$/.test(value.trim());
+}
+/** Canonical stored form: trimmed, 0x-prefixed, original casing preserved. */
+export function normalizeHexPrivateKey(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith('0x') || trimmed.startsWith('0X') ? `0x${trimmed.slice(2)}` : `0x${trimmed}`;
+}
+let keccakPromise = null;
+/** Load keccak_256 from ccxt's vendored noble-hashes. The package's `exports`
+ *  map only exposes ".", so we resolve the package root from the main entry and
+ *  import the file by path (file URLs bypass the exports map). Returns null on
+ *  any failure — derivation then reports 'unavailable'. */
+function loadKeccak() {
+    if (!keccakPromise) {
+        keccakPromise = (async () => {
+            try {
+                const req = createRequire(import.meta.url);
+                const entry = req.resolve('ccxt');
+                const marker = `${path.sep}ccxt${path.sep}`;
+                const idx = entry.lastIndexOf(marker);
+                if (idx === -1)
+                    return null;
+                const root = entry.slice(0, idx + marker.length - 1);
+                const sha3 = path.join(root, 'js', 'src', 'static_dependencies', 'noble-hashes', 'sha3.js');
+                const mod = (await import(pathToFileURL(sha3).href));
+                return typeof mod.keccak_256 === 'function' ? mod.keccak_256 : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return keccakPromise;
+}
+/** Test seam: reset the memoized keccak loader (unit tests only). */
+export function __resetKeccakCacheForTests() {
+    keccakPromise = null;
+}
+/** Derive the Ethereum address a private key controls (lowercase 0x…40 hex).
+ *  'invalid_key' = the key is malformed or outside the secp256k1 range;
+ *  'unavailable' = the keccak dependency could not be loaded (callers must
+ *  fail OPEN — skip the check, never block credential entry on infra). */
+export async function deriveAddressFromPrivateKey(privateKey) {
+    if (!isHexPrivateKey(privateKey))
+        return { ok: false, reason: 'invalid_key' };
+    const keccak = await loadKeccak();
+    if (!keccak)
+        return { ok: false, reason: 'unavailable' };
+    try {
+        const ecdh = createECDH('secp256k1');
+        ecdh.setPrivateKey(Buffer.from(normalizeHexPrivateKey(privateKey).slice(2), 'hex'));
+        const uncompressed = ecdh.getPublicKey(null, 'uncompressed'); // 0x04 || X || Y (65 bytes)
+        const digest = keccak(Uint8Array.from(uncompressed.subarray(1)));
+        const address = `0x${Buffer.from(digest.subarray(digest.length - 20)).toString('hex')}`;
+        return { ok: true, address };
+    }
+    catch {
+        // createECDH throws on out-of-range keys — malformed input, not infra.
+        return { ok: false, reason: 'invalid_key' };
+    }
+}
+/** Case-insensitive address equality (addresses may arrive checksummed). */
+export function sameAddress(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}

package/assets/plugin/venues/hyperliquid/hl-preflight.d.ts

@@ -0,0 +1,28 @@
+/** Approvals expiring inside this window get a renewal warning — long enough
+ *  to act on, short enough not to nag for months. */
+export declare const HL_EXPIRY_WARN_MS: number;
+export interface HlPreflightInput {
+    walletAddress: string;
+    /** Derived agent address to check approval for; null = skip the check
+     *  (derivation unavailable). */
+    agentAddress: string | null;
+    testnet: boolean;
+    /** Injectable for tests; production uses global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface HlPreflightOutcome {
+    /** clearinghouseState answered and parsed — the master account is queryable. */
+    reachable: boolean;
+    /** Set when !reachable — the raw error string for the caller's message. */
+    unreachableError?: string;
+    /** Perp equity + spot USDC; null when unreachable. */
+    balanceUSDC: number | null;
+    /** true/false = extraAgents answered definitively; null = could not check. */
+    agentApproved: boolean | null;
+    /** Approval expiry (epoch ms) when the exchange reports one. */
+    agentValidUntil: number | null;
+    warnings: string[];
+}
+export declare function hlApiBase(testnet: boolean): string;
+export declare function hlInfo(fetchImpl: typeof fetch, testnet: boolean, body: Record<string, unknown>): Promise<unknown>;
+export declare function hlPreflight(input: HlPreflightInput): Promise<HlPreflightOutcome>;

package/assets/plugin/venues/hyperliquid/hl-preflight.js

@@ -0,0 +1,116 @@
+// Hyperliquid credential preflight — the UNSIGNED verification core shared by
+// test_exchange_credentials (candidate creds) and hl_agent_wallet_status
+// (stored creds). Deliberately takes ADDRESSES ONLY — this module never sees a
+// private key, so it stays outside the credential-holder set.
+//
+// Checks (all keyless POST /info reads — the master address is the query key):
+//   1. clearinghouseState(master) → perp equity. Failure here = "unreachable";
+//      callers hard-fail with the error string.
+//   2. spotClearinghouseState(master) → spot USDC (the unified account
+//      collateralizes perps from spot — verified live on testnet 2026-07-12).
+//      Cosmetic: failure is silently skipped, perp equity alone still answers.
+//   3. extraAgents(master) → is `agentAddress` in the approved list, and when
+//      does the approval expire? Shape [{name,address,validUntil(ms)}] —
+//      verified vs Chainstack/QuickNode HL API references 2026-08-01 (the
+//      official gitbook omits this info type). A definitive miss is the
+//      caller's hard fail; an endpoint error degrades to a warning
+//      (fail-open on infra, closed on an explicit "not approved").
+import { sameAddress } from './hl-agent-wallet.js';
+/** Approvals expiring inside this window get a renewal warning — long enough
+ *  to act on, short enough not to nag for months. */
+export const HL_EXPIRY_WARN_MS = 14 * 24 * 60 * 60 * 1000;
+export function hlApiBase(testnet) {
+    return testnet ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
+}
+export async function hlInfo(fetchImpl, testnet, body) {
+    const res = await fetchImpl(`${hlApiBase(testnet)}/info`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok)
+        throw new Error(`POST /info ${String(body.type)} → ${res.status}`);
+    return res.json();
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function hlPreflight(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const { walletAddress, testnet } = input;
+    const warnings = [];
+    // 1+2. Master account state.
+    let balanceUSDC = null;
+    try {
+        const state = (await hlInfo(fetchImpl, testnet, {
+            type: 'clearinghouseState',
+            user: walletAddress,
+        }));
+        const perpEquity = Number(state?.marginSummary?.accountValue);
+        let total = Number.isFinite(perpEquity) ? perpEquity : 0;
+        try {
+            const spot = (await hlInfo(fetchImpl, testnet, {
+                type: 'spotClearinghouseState',
+                user: walletAddress,
+            }));
+            for (const b of spot?.balances ?? []) {
+                if (String(b?.coin) === 'USDC') {
+                    const t = Number(b?.total);
+                    if (Number.isFinite(t))
+                        total += t;
+                }
+            }
+        }
+        catch {
+            // Spot read is cosmetic — perp equity alone is still a real answer.
+        }
+        balanceUSDC = total;
+        if (total <= 0) {
+            warnings.push('The master account holds no USDC yet — deposit/bridge USDC to Hyperliquid before going live.');
+        }
+    }
+    catch (e) {
+        return {
+            reachable: false,
+            unreachableError: msg(e),
+            balanceUSDC: null,
+            agentApproved: null,
+            agentValidUntil: null,
+            warnings,
+        };
+    }
+    // 3. Agent approval.
+    let agentApproved = null;
+    let agentValidUntil = null;
+    if (input.agentAddress) {
+        try {
+            const agents = (await hlInfo(fetchImpl, testnet, {
+                type: 'extraAgents',
+                user: walletAddress,
+            }));
+            if (Array.isArray(agents)) {
+                const match = agents.find((a) => typeof a?.address === 'string' && sameAddress(a.address, input.agentAddress));
+                agentApproved = match != null;
+                if (match && Number.isFinite(Number(match.validUntil))) {
+                    agentValidUntil = Number(match.validUntil);
+                    const remaining = agentValidUntil - Date.now();
+                    if (remaining <= 0) {
+                        agentApproved = false;
+                        warnings.push('The agent wallet approval has EXPIRED — re-approve it in the Hyperliquid API page.');
+                    }
+                    else if (remaining < HL_EXPIRY_WARN_MS) {
+                        warnings.push(`The agent wallet approval expires in ${Math.ceil(remaining / (24 * 60 * 60 * 1000))} day(s) — renew it soon (approvals last at most 180 days).`);
+                    }
+                }
+            }
+            else {
+                warnings.push('Could not read the approved-agents list — approval not verified.');
+            }
+        }
+        catch {
+            warnings.push('Could not read the approved-agents list — approval not verified.');
+        }
+    }
+    return { reachable: true, balanceUSDC, agentApproved, agentValidUntil, warnings };
+}

package/package.json

@@ -1,32 +1,32 @@
-{
-  "name": "@reefclaw/connect",
-  "version": "0.1.26",
-  "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
-  "type": "module",
-  "bin": {
-    "reefclaw-connect": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "assets"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "bundle-assets": "node scripts/bundle-assets.mjs",
-    "build": "tsc && node scripts/bundle-assets.mjs",
-    "test": "vitest",
-    "test:run": "vitest run"
-  },
-  "dependencies": {
-    "json5": "2.2.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20",
-    "typescript": "^5",
-    "vitest": "^4.0.18"
-  },
-  "license": "MIT",
-  "homepage": "https://reefclaw.com"
-}
+{
+  "name": "@reefclaw/connect",
+  "version": "0.1.28",
+  "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
+  "type": "module",
+  "bin": {
+    "reefclaw-connect": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "bundle-assets": "node scripts/bundle-assets.mjs",
+    "build": "tsc && node scripts/bundle-assets.mjs",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "json5": "2.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^4.0.18"
+  },
+  "license": "MIT",
+  "homepage": "https://reefclaw.com"
+}

package/dist/daemon.js

@@ -1,104 +0,0 @@
-// Keep the bridge running across reboots. Linux/systemd-user is implemented
-// fully; macOS and Windows fall back to printing the manual run command (a
-// launchd/Task-Scheduler unit is a follow-up). The bridge reads its config from
-// ~/.openclaw/openclaw.json, so until the user pastes their connect message the
-// service will start, find no token, and restart — harmless; it connects within
-// seconds of the agent writing the config.
-import { writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir, userInfo } from 'node:os';
-import { BRIDGE_DIR } from './paths.js';
-import { run, which } from './exec.js';
-import { step, ok, info, warn } from './ui.js';
-const SERVICE_NAME = 'reefclaw-bridge';
-const NODE = process.execPath; // absolute path to the node running the installer
-/**
- * Build the systemd user-unit text. Pure + exported so the path-quoting is
- * unit-testable. Both `node` (process.execPath) and `bridgeDir` (under the
- * user's home) can contain spaces. Quoting rules differ per directive:
- *  - ExecStart= is parsed with shell-like word splitting, so an unquoted
- *    `ExecStart=/home/a b/node …` reads the binary as `/home/a` — QUOTE both
- *    the binary and the script path.
- *  - WorkingDirectory= takes the raw value after `=` as a single path (no word
- *    splitting) — spaces are safe UNQUOTED, and quotes are treated as literal
- *    characters, failing the unit with "path is not absolute" (verified live
- *    on systemd 255 / Ubuntu 24.04). Do NOT quote it.
- */
-export function buildSystemdUnit(node, bridgeDir) {
-    const indexJs = join(bridgeDir, 'index.js');
-    return `[Unit]
-Description=ReefClaw connector - bridges OpenClaw to the ReefClaw dashboard
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=${bridgeDir}
-ExecStart="${node}" "${indexJs}" --provider gateway --log-level info
-Restart=always
-RestartSec=5s
-
-[Install]
-WantedBy=default.target
-`;
-}
-function manualHint() {
-    warn('Could not set up an auto-start service on this OS yet.');
-    info('Keep the connector running with this command (leave it open / use your own service manager):');
-    info(`  "${NODE}" "${join(BRIDGE_DIR, 'index.js')}" --provider gateway`);
-}
-function installSystemd() {
-    if (!which('systemctl'))
-        return false;
-    const unitDir = join(homedir(), '.config', 'systemd', 'user');
-    mkdirSync(unitDir, { recursive: true });
-    const unit = buildSystemdUnit(NODE, BRIDGE_DIR);
-    writeFileSync(join(unitDir, `${SERVICE_NAME}.service`), unit, 'utf-8');
-    run('systemctl', ['--user', 'daemon-reload']);
-    const enabled = run('systemctl', ['--user', 'enable', '--now', `${SERVICE_NAME}.service`]);
-    if (!enabled.ok) {
-        warn('systemd --user enable/start did not succeed:');
-        if (enabled.stderr.trim())
-            info(enabled.stderr.trim().split('\n').slice(-2).join('\n'));
-        info(`Try:  systemctl --user enable --now ${SERVICE_NAME}.service`);
-        return false;
-    }
-    // `enable --now` can exit 0 while the unit failed to load (e.g. a bad unit
-    // file setting) — verify the unit actually came up before claiming ✓.
-    // 'active' = running; 'activating' = the expected pre-token restart loop
-    // (the bridge exits until the user pastes their connect message, and
-    // Restart=always re-launches it). Anything else (inactive/failed) means the
-    // unit never loaded.
-    const active = run('systemctl', ['--user', 'is-active', `${SERVICE_NAME}.service`]);
-    const state = active.stdout.trim();
-    if (state !== 'active' && state !== 'activating') {
-        warn(`the service did not come up (state: ${state || 'unknown'}).`);
-        info(`Inspect:  systemctl --user status ${SERVICE_NAME}.service`);
-        return false;
-    }
-    // Linger lets the user service run without an active login session (servers).
-    // Best-effort: needs privileges; non-fatal if it fails.
-    const linger = run('loginctl', ['enable-linger', userInfo().username]);
-    if (linger.ok) {
-        info('enabled linger (service survives logout / reboot)');
-    }
-    else {
-        info('note: run `sudo loginctl enable-linger $USER` so the connector survives logout.');
-    }
-    return true;
-}
-export function installDaemon() {
-    step('Starting the connector as a background service');
-    if (process.platform === 'linux') {
-        if (installSystemd()) {
-            ok(`connector running as a systemd user service (${SERVICE_NAME})`);
-            info(`logs:  journalctl --user -u ${SERVICE_NAME} -f`);
-            return true;
-        }
-        manualHint();
-        return false;
-    }
-    // macOS / Windows: manual for now (launchd / Task Scheduler unit is a follow-up).
-    manualHint();
-    return false;
-}