@reefclaw/connect 0.1.33 → 0.1.34

package/assets/plugin/tools/set-trading-mode.d.ts

@@ -1,6 +1,8 @@
 import type { PluginRuntime } from '../onboarding/runtime.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { TradingMode } from '../types.js';
+import type { HlCredentials } from '../venues/hyperliquid/hl-private.js';
+import { type HlAgentApprovalVerdict } from '../venues/hyperliquid/hl-agent-wallet.js';
 import { type VenueId } from '../venues/registry.js';
 export interface SetTradingModeArgs {
     mode: TradingMode;
@@ -27,6 +29,10 @@ export interface SetTradingModeDeps {
      *  wired to the boot venue and a mixed-venue runtime is not a valid state.
      *  Absent (legacy tests) → guard skipped. */
     bootVenue?: VenueId;
+    /** Injectable approval check (tests). DEFAULTS TO THE REAL ONE — unlike
+     *  bootVenue this gate is on unless explicitly stubbed, so production
+     *  wiring can never forget it. */
+    hlApprovalCheck?: (creds: HlCredentials) => Promise<HlAgentApprovalVerdict>;
     /** Override the config file path — tests use this. */
     configPath?: string;
 }

package/assets/plugin/tools/set-trading-mode.js

@@ -12,6 +12,7 @@
 // by design: the check lives once, at registration, for all operator tools.
 import { readPluginConfig } from '../config/plugin-config-io.js';
 import { validateModeTransition, modeRequiresCredentials } from '../onboarding/mode-ladder.js';
+import { checkHlAgentApproval, } from '../venues/hyperliquid/hl-agent-wallet.js';
 import { parseVenue } from '../venues/registry.js';
 import { logger } from '../logger.js';
 import { recordModeTransition } from '../audit/mode-transition-audit.js';
@@ -133,6 +134,48 @@ export async function setTradingModeTool(args, deps) {
             reason: 'acknowledgment_required',
         };
     }
+    // 4.5. HL agent-approval preflight (E2E audit 2026-08-11 #7). An agent key
+    // that is not in the master account's extraAgents list — or whose approval
+    // expired (they last ≤180 days) — signs orders Hyperliquid rejects one by
+    // one: the flip would "succeed", the dashboard would look healthy, and
+    // every order would bounce. Refuse ONLY on a definitive negative from the
+    // exchange; derivation/network failures fail OPEN with a warning (infra
+    // must never block a deliberate operator action — same rule as the
+    // credential-entry guards).
+    let preflightWarnings = [];
+    if (venue === 'hyperliquid' && hlCredentials) {
+        let verdict;
+        try {
+            verdict = await (deps.hlApprovalCheck ?? checkHlAgentApproval)(hlCredentials);
+        }
+        catch (err) {
+            verdict = {
+                approved: null,
+                validUntil: null,
+                warnings: [
+                    `Approval preflight errored (${err instanceof Error ? err.message : String(err)}) — approval not verified.`,
+                ],
+            };
+        }
+        if (verdict.approved === false) {
+            recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'hl_agent_not_approved' });
+            const why = verdict.warnings.length > 0 ? ` ${verdict.warnings.join(' ')}` : '';
+            return {
+                ok: false,
+                message: `Hyperliquid reports this agent wallet is NOT approved to trade for ${hlCredentials.walletAddress}.` +
+                    `${why} Every live order would be rejected. Approve it first: Dashboard → Settings → ` +
+                    `Exchange connection → Hyperliquid (the guided setup signs one approveAgent transaction), ` +
+                    `then retry ${target}.`,
+                previousMode,
+                mode: previousMode,
+                readiness: deps.runtime.adapter.readiness,
+                reason: 'hl_agent_not_approved',
+            };
+        }
+        preflightWarnings = verdict.warnings;
+        for (const w of preflightWarnings)
+            logger.warn(TAG, `HL preflight: ${w}`);
+    }
     // 5. Persist the new mode.
     try {
         const { updatePluginConfig } = await import('../config/plugin-config-io.js');
@@ -162,7 +205,11 @@ export async function setTradingModeTool(args, deps) {
     });
     return {
         ok: true,
-        message: `Trading mode changed from ${previousMode} to ${target}`,
+        // Preflight warnings (near-expiry approval, zero balance, unverifiable
+        // approval) ride the success message — the operator just took a real-money
+        // action and these are the things to fix before the first order.
+        message: `Trading mode changed from ${previousMode} to ${target}` +
+            (preflightWarnings.length > 0 ? `. Note: ${preflightWarnings.join(' ')}` : ''),
         previousMode,
         mode: deps.runtime.mode,
         readiness: deps.runtime.adapter.readiness,

package/assets/plugin/venues/hyperliquid/hl-agent-wallet.d.ts

@@ -27,3 +27,29 @@ export declare function __resetKeccakCacheForTests(): void;
 export declare function deriveAddressFromPrivateKey(privateKey: string): Promise<DeriveAddressResult>;
 /** Case-insensitive address equality (addresses may arrive checksummed). */
 export declare function sameAddress(a: string, b: string): boolean;
+/** One-call approval verdict for the STORED credentials — derivation + the
+ *  unsigned preflight, packaged for the live-flip gate in set_trading_mode
+ *  (E2E audit 2026-08-11 #7: an unapproved/expired agent key reached LIVE
+ *  with a healthy-looking dashboard and every order rejected).
+ *
+ *  Lives HERE, not in hl-preflight.ts, because it takes the PRIVATE KEY —
+ *  hl-preflight's module boundary is addresses-only by design.
+ *
+ *  Verdict semantics (the caller refuses ONLY on `approved === false`):
+ *    false = the exchange answered definitively — the agent address is not in
+ *            extraAgents, or its approval has expired. Real money would be
+ *            un-tradeable; block the flip.
+ *    null  = could not verify (derivation unavailable, HL unreachable,
+ *            extraAgents unreadable). Fail OPEN — infra must never block a
+ *            deliberate operator action; the warning travels instead.
+ *    true  = approved (warnings may still carry a near-expiry nudge). */
+export interface HlAgentApprovalVerdict {
+    approved: boolean | null;
+    validUntil: number | null;
+    warnings: string[];
+}
+export declare function checkHlAgentApproval(creds: {
+    walletAddress: string;
+    agentPrivateKey: string;
+    testnet?: boolean;
+}, fetchImpl?: typeof fetch): Promise<HlAgentApprovalVerdict>;

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

@@ -116,3 +116,35 @@ export async function deriveAddressFromPrivateKey(privateKey) {
 export function sameAddress(a, b) {
     return a.trim().toLowerCase() === b.trim().toLowerCase();
 }
+export async function checkHlAgentApproval(creds, fetchImpl) {
+    const derived = await deriveAddressFromPrivateKey(creds.agentPrivateKey);
+    if (!derived.ok) {
+        return {
+            approved: null,
+            validUntil: null,
+            warnings: [
+                derived.reason === 'invalid_key'
+                    ? 'The stored agent key looks malformed — approval could not be verified.'
+                    : 'Could not derive the agent wallet address on this host — approval not verified.',
+            ],
+        };
+    }
+    const { hlPreflight } = await import('./hl-preflight.js');
+    const pre = await hlPreflight({
+        walletAddress: creds.walletAddress,
+        agentAddress: derived.address,
+        testnet: creds.testnet === true,
+        fetchImpl,
+    });
+    if (!pre.reachable) {
+        return {
+            approved: null,
+            validUntil: null,
+            warnings: [
+                `Could not reach Hyperliquid to verify the agent approval (${pre.unreachableError ?? 'unknown error'}).`,
+                ...pre.warnings,
+            ],
+        };
+    }
+    return { approved: pre.agentApproved, validUntil: pre.agentValidUntil, warnings: pre.warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {