dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/src/signal-channels.js

@@ -0,0 +1,312 @@
+// dexterm autotrade — the trade-fire delivery channels and their config (task-1645, 0.2.0 card A).
+//
+// The user enables any of these, in ONE place: the `signals` block of $DEXTERM_HOME/connectors.json, next to the
+// Telegram setup (`dexterm autotrade signal channels …`, shown by `dexterm telegram status` too). No secret is in
+// the file: the webhook's HMAC secret lives in the OS keychain store, like the bot token.
+//
+//   webhook    POST the signal line to a loopback URL (http://127.0.0.1|localhost|[::1]) or a user https URL.
+//              Headers: x-dexterm-signature (HMAC, signal.ts), x-dexterm-nonce, idempotency-key. Redirects are an
+//              error. 2xx = ack, 409 = duplicate (ack), 408/425/429 and 5xx/network = retry, other 4xx = rejected.
+//   cmd        `--signal-cmd`: an argv (absolute program path, no shell, no PATH lookup); the signal line on stdin;
+//              a minimal environment (no dexterm secret, DEXTERM_SIGNAL_SIGNATURE when an HMAC secret is set).
+//              Exit 0 = ack, 2 = rejected, 3 = duplicate (ack), anything else or a 10 s timeout = retry.
+//   jsonl      append the line to a stream file (default autotrade/real/signals.jsonl, 0600); an executor tails it.
+//              task-1654: `signed` (opt-in, needs the HMAC secret) writes each line as an envelope instead,
+//              {"schema":"dexterm-trade-fire-envelope/1","signature":"t=…,v1=…","signal":"<the exact signal line>"},
+//              so a tailing executor can verify the HMAC like the webhook's.
+//   mcp        append to autotrade/real/mcp-feed.jsonl, which the MCP tool `trade_fire_feed` reads (status only).
+//   telegram   the human-visible copy to the paired chat (the bot cannot be the executor's input: a bot cannot read
+//              another bot's messages). Never sufficient on its own for real mode.
+import { spawn } from 'node:child_process';
+import { closeSync, fsyncSync, mkdirSync, openSync, writeSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { chooseSecretStore, secretStore, SIGNAL_HMAC_ITEM } from "./chat/secrets.js";
+import { loadConnectors, saveConnectors, CONNECTORS_SCHEMA, defaultTelegram } from "./chat/config.js";
+import { inert, shortMint, usdShort } from "./chat/format.js";
+import { realDir } from "./outbox.js";
+import { clampTtl, signBody, SIGNAL_TTL_DEFAULT_SEC } from "./signal.js";
+export const defaultSignalsConfig = () => ({
+    webhook: { enabled: false, url: null, secretStore: null }, cmd: { enabled: false, argv: [] }, jsonl: { enabled: false, path: null, signed: false },
+    mcp: { enabled: false }, telegram: { enabled: true }, ttlSec: SIGNAL_TTL_DEFAULT_SEC, executor: { listenPort: null },
+});
+export const streamPathDefault = (home) => join(realDir(home), 'signals.jsonl');
+export const mcpFeedPath = (home) => join(realDir(home), 'mcp-feed.jsonl');
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+/** null when the URL may receive signals: loopback http(s), or https anywhere. No credentials in the URL. */
+export function webhookUrlProblem(u) {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        return 'not a URL';
+    }
+    if (url.username || url.password)
+        return 'credentials in a URL are refused (the HMAC secret lives in the keychain)';
+    if (url.protocol === 'https:')
+        return null;
+    if (url.protocol === 'http:' && LOOPBACK.has(url.hostname))
+        return null;
+    return 'use https://, or http:// to 127.0.0.1 / localhost / [::1] only';
+}
+export function argvProblem(argv) {
+    if (!Array.isArray(argv) || argv.length < 1 || argv.length > 16)
+        return 'the command is an argv array of 1 to 16 strings';
+    if (!argv.every((a) => typeof a === 'string' && a.length > 0 && a.length <= 512 && !a.includes('\0')))
+        return 'every argv item is a non-empty string (512 chars max)';
+    if (!isAbsolute(argv[0]))
+        return 'the program is an absolute path (no shell, no PATH lookup)';
+    return null;
+}
+/** Read the `signals` block; anything invalid is turned off (fail closed), with the reasons. */
+export function parseSignalsConfig(raw) {
+    const c = defaultSignalsConfig();
+    const problems = [];
+    const r = (raw && typeof raw === 'object' ? raw : {});
+    const w = (r.webhook ?? {});
+    if (typeof w.url === 'string') {
+        const p = webhookUrlProblem(w.url);
+        if (p)
+            problems.push(`webhook: ${p}`);
+        else
+            c.webhook.url = w.url;
+    }
+    c.webhook.enabled = w.enabled === true && c.webhook.url !== null;
+    c.webhook.secretStore = w.secretStore === 'keychain' || w.secretStore === 'libsecret' || w.secretStore === 'file' ? w.secretStore : null;
+    const m = (r.cmd ?? {});
+    if (m.argv !== undefined) {
+        const p = argvProblem(m.argv);
+        if (p)
+            problems.push(`cmd: ${p}`);
+        else
+            c.cmd.argv = [...m.argv];
+    }
+    c.cmd.enabled = m.enabled === true && c.cmd.argv.length > 0;
+    const j = (r.jsonl ?? {});
+    if (typeof j.path === 'string') {
+        if (isAbsolute(j.path))
+            c.jsonl.path = j.path;
+        else
+            problems.push('jsonl: the stream path must be absolute');
+    }
+    c.jsonl.enabled = j.enabled === true;
+    c.jsonl.signed = j.signed === true;
+    const ex = (r.executor ?? {});
+    if (ex.listenPort !== undefined && ex.listenPort !== null) {
+        const n = Number(ex.listenPort);
+        if (Number.isInteger(n) && n >= 1024 && n <= 65535)
+            c.executor.listenPort = n;
+        else
+            problems.push('executor: listenPort must be a whole number from 1024 to 65535');
+    }
+    c.mcp.enabled = (r.mcp ?? {}).enabled === true;
+    c.telegram.enabled = (r.telegram ?? {}).enabled !== false;
+    c.ttlSec = clampTtl(typeof r.ttlSec === 'number' ? r.ttlSec : SIGNAL_TTL_DEFAULT_SEC);
+    return { config: c, problems };
+}
+/** The `signals` block of connectors.json (a missing file or block = the defaults: only the Telegram copy). */
+export function loadSignalsConfig(home) {
+    const c = loadConnectors(home);
+    if (!c.ok)
+        return { config: { ...defaultSignalsConfig(), telegram: { enabled: false } }, problems: [c.error] };
+    return parseSignalsConfig(c.config.signals);
+}
+/** Write the `signals` block back, keeping the Telegram setup as it is. */
+export function saveSignalsConfig(home, sc) {
+    const c = loadConnectors(home);
+    if (!c.ok)
+        throw new Error(c.error);
+    saveConnectors(home, { ...(c.ok ? c.config : { schema: CONNECTORS_SCHEMA, telegram: defaultTelegram() }), signals: sc });
+}
+export function enabledChannels(c) {
+    return [c.webhook.enabled ? 'webhook' : null, c.cmd.enabled ? 'cmd' : null, c.jsonl.enabled ? 'jsonl' : null, c.mcp.enabled ? 'mcp' : null, c.telegram.enabled ? 'telegram' : null].filter((x) => !!x);
+}
+export class WebhookChannel {
+    name = 'webhook';
+    o;
+    constructor(o) {
+        const p = webhookUrlProblem(o.url);
+        if (p)
+            throw new Error(`webhook: ${p}`);
+        this.o = o;
+    }
+    async deliver(s, line) {
+        const headers = { 'content-type': 'application/json', 'x-dexterm-nonce': String(s.nonce), 'idempotency-key': s.id, 'user-agent': 'dexterm-trade-fire/1' };
+        const secret = this.o.secret();
+        if (secret)
+            headers['x-dexterm-signature'] = signBody(secret, line, (this.o.now ?? Date.now)());
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.o.timeoutMs ?? 5000);
+        try {
+            const f = this.o.fetch ?? globalThis.fetch;
+            const res = await f(this.o.url, { method: 'POST', headers, body: line, redirect: 'error', signal: ac.signal });
+            if (res.status >= 200 && res.status < 300)
+                return { ok: true };
+            if (res.status === 409)
+                return { ok: true, duplicate: true };
+            if (res.status === 408 || res.status === 425 || res.status === 429 || res.status >= 500)
+                return { ok: false, retry: true, why: `http ${res.status}` };
+            return { ok: false, retry: false, why: `http ${res.status}` };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: ac.signal.aborted ? 'timeout' : e.message.slice(0, 120) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+// ───────────────────────────── command hook ─────────────────────────────
+export class CommandChannel {
+    name = 'cmd';
+    o;
+    constructor(o) {
+        const p = argvProblem(o.argv);
+        if (p)
+            throw new Error(`signal-cmd: ${p}`);
+        this.o = o;
+    }
+    deliver(s, line) {
+        const secret = this.o.secret?.() ?? null;
+        // A minimal environment: no token, no RPC URL, no DEXTERM_* setting leaks into the user's executor.
+        const env = { PATH: process.env.PATH ?? '/usr/bin:/bin', LANG: process.env.LANG ?? 'C.UTF-8', DEXTERM_SIGNAL_NONCE: String(s.nonce), DEXTERM_SIGNAL_ID: s.id };
+        if (process.env.HOME)
+            env.HOME = process.env.HOME;
+        if (process.env.SystemRoot)
+            env.SystemRoot = process.env.SystemRoot;
+        if (secret)
+            env.DEXTERM_SIGNAL_SIGNATURE = signBody(secret, line, (this.o.now ?? Date.now)());
+        return new Promise((done) => {
+            let settled = false;
+            const finish = (r) => { if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                done(r);
+            } };
+            let child;
+            try {
+                child = spawn(this.o.argv[0], this.o.argv.slice(1), { shell: false, env, stdio: ['pipe', 'ignore', 'ignore'], windowsHide: true });
+            }
+            catch (e) {
+                done({ ok: false, retry: true, why: `spawn: ${e.message.slice(0, 100)}` });
+                return;
+            }
+            const timer = setTimeout(() => { child.kill('SIGKILL'); finish({ ok: false, retry: true, why: 'timeout' }); }, this.o.timeoutMs ?? 10_000);
+            child.on('error', (e) => finish({ ok: false, retry: true, why: `spawn: ${e.message.slice(0, 100)}` }));
+            child.on('close', (code) => finish(code === 0 ? { ok: true } : code === 3 ? { ok: true, duplicate: true } : code === 2 ? { ok: false, retry: false, why: 'rejected (exit 2)' } : { ok: false, retry: true, why: `exit ${code}` }));
+            child.stdin.on('error', () => { });
+            child.stdin.end(`${line}\n`);
+        });
+    }
+}
+// ───────────────────────────── JSONL stream / MCP feed ─────────────────────────────
+export const ENVELOPE_SCHEMA = 'dexterm-trade-fire-envelope/1';
+export class JsonlChannel {
+    name;
+    path;
+    signer;
+    /** task-1654: `signed` = HMAC envelope lines (a secret must be set, else the line is retried until one is). */
+    constructor(path, name = 'jsonl', signed) { this.path = path; this.name = name; this.signer = signed ? { secret: signed.secret, now: signed.now ?? Date.now } : null; }
+    async deliver(_s, line) {
+        let out = line;
+        if (this.signer) {
+            const secret = this.signer.secret();
+            if (!secret)
+                return { ok: false, retry: true, why: 'signed stream: no HMAC secret set (dexterm autotrade signal secret generate --out FILE)' };
+            out = JSON.stringify({ schema: ENVELOPE_SCHEMA, signature: signBody(secret, line, this.signer.now()), signal: line });
+        }
+        try {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            const fd = openSync(this.path, 'a', 0o600);
+            try {
+                writeSync(fd, `${out}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: e.code ?? e.message.slice(0, 80) };
+        }
+    }
+}
+// ───────────────────────────── Telegram copy ─────────────────────────────
+/** The human-visible copy (plain text lines, the LIVE badge). The symbol is already sanitized; it still goes through inert(). */
+export function telegramLines(s, now = Date.now()) {
+    const left = Math.max(0, Math.round((s.expiresAt - now) / 1000));
+    const strat = `${inert(s.strategy.id, 32)} v${inert(s.strategy.version, 12)}`;
+    if (s.type === 'halted') {
+        // task-1679 (0.2.0 decision): open positions at the end of a real run must be impossible to miss.
+        const open = s.open ?? [];
+        return [
+            `LIVE TRADE FIRE · HALTED · ${inert(s.reason, 40)}`,
+            `${s.outstanding.length} outstanding signal(s) · run ${inert(s.runId.slice(-12), 16)} · account ${inert(s.accountId, 32)} · nonce ${s.nonce}`,
+            ...(open.length ? [`${open.length} position(s): ${open.slice(0, 10).map(shortMint).join(', ')}${open.length > 10 ? ` +${open.length - 10} more` : ''}`, 'these positions are still open: manage them in your executor', 'until the next real run of this strategy, dexterm sends NO signal for them, sells included'] : []),
+            'no more signals from this run',
+        ];
+    }
+    if (s.type === 'test')
+        return ['LIVE TRADE FIRE · TEST', `nonce ${s.nonce} · account ${inert(s.accountId, 32)} · never trade on this`];
+    const size = s.side === 'buy' ? `${s.sizeSol} SOL (${usdShort(s.sizeUsd)}, ${s.pctOfBook}% of book)` : `${Math.round((s.sellFraction ?? 1) * 1000) / 10}% of the position (~${s.sizeSol} SOL)`;
+    return [
+        `LIVE TRADE FIRE · ${s.side.toUpperCase()} "${inert(s.symbol, 16)}" ${shortMint(s.mint)}`,
+        `${size}${s.exitReason ? ` · ${inert(s.exitReason, 40)}` : ''}`,
+        `${strat} · account ${inert(s.accountId, 32)} · nonce ${s.nonce} · ignore after ${left} s`,
+        'your executor acts on it, not this chat',
+    ];
+}
+export class TelegramCopyChannel {
+    name = 'telegram';
+    send;
+    now;
+    constructor(send, now = Date.now) { this.send = send; this.now = now; }
+    async deliver(s) {
+        try {
+            await this.send(telegramLines(s, this.now()));
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: e.message.slice(0, 120) };
+        }
+    }
+}
+// ───────────────────────────── from the config ─────────────────────────────
+/** Where the webhook's HMAC secret is (the store setup recorded, else the best on this machine). */
+export function hmacStore(home, sc, env = process.env) {
+    return sc.webhook.secretStore ? secretStore(sc.webhook.secretStore, home, SIGNAL_HMAC_ITEM) : chooseSecretStore(home, env, process.platform, SIGNAL_HMAC_ITEM);
+}
+/**
+ * The channel objects for a config. Without a Telegram sender (outside a run) the copy is deferred: it stays pending
+ * in the outbox for the next run instead of being dropped. The secret is read once, on first use.
+ */
+export function channelsFromConfig(home, sc, o = {}) {
+    let cached;
+    const store = o.secret ?? hmacStore(home, sc, o.env);
+    const secret = () => { if (cached === undefined) {
+        try {
+            cached = store.get();
+        }
+        catch {
+            cached = null;
+        }
+    } return cached; };
+    const out = [];
+    const defer = [];
+    if (sc.webhook.enabled && sc.webhook.url)
+        out.push(new WebhookChannel({ url: sc.webhook.url, secret, fetch: o.fetch, now: o.now }));
+    if (sc.cmd.enabled && sc.cmd.argv.length)
+        out.push(new CommandChannel({ argv: sc.cmd.argv, secret, now: o.now }));
+    if (sc.jsonl.enabled)
+        out.push(new JsonlChannel(sc.jsonl.path ?? streamPathDefault(home), 'jsonl', sc.jsonl.signed ? { secret, now: o.now } : undefined));
+    if (sc.mcp.enabled)
+        out.push(new JsonlChannel(mcpFeedPath(home), 'mcp'));
+    if (sc.telegram.enabled) {
+        if (o.telegram)
+            out.push(new TelegramCopyChannel(o.telegram, o.now));
+        else
+            defer.push('telegram');
+    }
+    return { channels: out, defer };
+}

package/dist/packages/autotrade/src/signal.js

@@ -0,0 +1,196 @@
+// dexterm autotrade — the LIVE TRADE FIRE signal, `dexterm-trade-fire/1` (task-1645, 0.2.0 card A).
+//
+// A strategy in mode "real" trades exactly like paper (same clamp, exits, monitor and ledger: the paper fill model is
+// the monitor's own view), and every buy or sell it fills also becomes one of these signals for the user's OWN
+// executor (a Telegram trading bot of their choice, or any script). dexterm holds no key, signs no transaction and
+// builds none: a signal is a request the executor may act on, ignore, or reject.
+//
+//   type "trade"    side buy|sell, mint, sanitized symbol, size in SOL / USD / % of book (a sell also as the fraction
+//                   of the position), price + mcap + liquidity context, exit reason for a sell, strategy id/version/
+//                   hash, run id, account id, nonce, idempotency key, issued/expires, `paper: false`
+//   type "halted"   the run stopped (end, halt, kill, a lost runner): every outstanding signal's nonce, a reason, and
+//                   `open`: the mints dexterm still counts as held for the account (the next real run of the
+//                   strategy takes them over and keeps their exits; they still count against the open-position cap)
+//   type "test"     `dexterm autotrade signal test`: proves the channel; an executor must never trade on it
+//
+// Rules an executor follows (and SignalReceiver below implements, for scripts and the tests' fake executors):
+//   1. verify the HMAC header when a secret is set (`x-dexterm-signature: t=<unix s>,v1=<hex>` over "<t>.<body>")
+//   2. ignore anything past `expiresAt` (the TTL): a late signal is never acted on
+//   3. dedupe by nonce (and the idempotency key `id`): delivery is at-least-once, so a repeat is normal
+//   4. act only on the account id it was set up for
+//
+// Firewall: nothing token-authored rides along except the symbol, reduced to [A-Za-z0-9._$-] (16 chars). No name,
+// no description, no links, no agent text, no paths, no keys. Every other field is an engine number or an id that
+// dexterm validated itself.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+export const TRADE_FIRE_SCHEMA = 'dexterm-trade-fire/1';
+export const SIGNAL_TTL_DEFAULT_SEC = 60;
+export const SIGNAL_TTL_MIN_SEC = 10;
+export const SIGNAL_TTL_MAX_SEC = 600;
+/** How far a signature's timestamp may sit from the receiver's clock. */
+export const SIGNATURE_TOLERANCE_SEC = 300;
+const SOL_MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const ACCOUNT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const RUN_RE = /^[A-Za-z0-9._:-]{1,96}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+/** The only token text a signal carries: NFKC, then [A-Za-z0-9._$-] only, 16 chars, '?' when nothing is left. */
+export function sanitizeSymbol(s) {
+    const t = String(s ?? '').normalize('NFKC').replace(/[^A-Za-z0-9._$-]/g, '').slice(0, 16);
+    return t || '?';
+}
+/** An engine reason ("hard-stop", "time_review:no-answer") reduced to [a-z0-9:_-], 40 chars. */
+export function sanitizeReason(s) {
+    return String(s ?? '').toLowerCase().replace(/[^a-z0-9:_-]/g, '-').replace(/-+/g, '-').slice(0, 40) || 'unknown';
+}
+export const signalIdOf = (accountId, runId, nonce) => createHash('sha256').update(`${TRADE_FIRE_SCHEMA}|${accountId}|${runId}|${nonce}`).digest('hex').slice(0, 32);
+export const clampTtl = (sec) => Math.min(SIGNAL_TTL_MAX_SEC, Math.max(SIGNAL_TTL_MIN_SEC, Math.round(Number.isFinite(sec) ? sec : SIGNAL_TTL_DEFAULT_SEC)));
+const r6 = (v) => Math.round(v * 1e6) / 1e6;
+const r2 = (v) => Math.round(v * 100) / 100;
+const fin = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+function base(type, h) {
+    const ttlSec = clampTtl(h.ttlSec);
+    return {
+        schema: TRADE_FIRE_SCHEMA, type, id: signalIdOf(h.accountId, h.runId, h.nonce), nonce: h.nonce, issuedAt: h.now, expiresAt: h.now + ttlSec * 1000, ttlSec,
+        runId: h.runId, accountId: h.accountId, strategy: { id: h.strategy.id, version: h.strategy.version, hash: h.strategy.hash.slice(0, 64) }, paper: false,
+    };
+}
+/** A trade signal; throws on anything that is not a plain engine value (fail closed: no signal rather than a bad one). */
+export function buildTradeSignal(t, h) {
+    if (!SOL_MINT_RE.test(t.mint))
+        throw new Error('signal: mint is not a base58 address');
+    if (!(t.solUsd > 0))
+        throw new Error('signal: no SOL/USD price');
+    // A buy states a positive size; a sell's size is the modelled proceeds and can be ~0 (a rug exit must still go out).
+    if (t.side === 'buy' ? !(t.sizeUsd > 0) : !(t.sizeUsd >= 0))
+        throw new Error('signal: size must be positive');
+    const s = {
+        ...base('trade', h), type: 'trade', side: t.side, mint: t.mint, symbol: sanitizeSymbol(t.symbol),
+        sizeSol: r6(t.sizeUsd / t.solUsd), sizeUsd: r2(t.sizeUsd), pctOfBook: t.bookUsd > 0 ? Math.round((t.sizeUsd / t.bookUsd) * 1000) / 10 : 0,
+        sellFraction: t.side === 'sell' ? Math.min(1, Math.max(0, r6(t.sellFraction ?? 1))) : null,
+        price: { usd: fin(t.priceUsd), mcap: fin(t.mcap), liqUsd: fin(t.liqUsd), solUsd: r2(t.solUsd) },
+        exitReason: t.side === 'sell' ? sanitizeReason(t.exitReason) : null,
+        slippageBps: Math.round(t.slippageBps), maxImpactPct: t.maxImpactPct, positionId: t.positionId && /^[A-Za-z0-9._-]{1,48}$/.test(t.positionId) ? t.positionId : null,
+        ...(t.model ? { model: { priceUsd: fin(t.model.priceUsd), tokens: fin(t.model.tokens) } } : {}),
+    };
+    const v = validateSignal(s);
+    if (!v.ok)
+        throw new Error(`signal: ${v.error}`);
+    return s;
+}
+export function buildHaltedSignal(reason, outstanding, h, open = []) {
+    return { ...base('halted', h), type: 'halted', reason: sanitizeReason(reason), outstanding: [...new Set(outstanding)].filter((n) => Number.isInteger(n) && n > 0).sort((a, b) => a - b).slice(0, 500), open: [...new Set(open)].filter((m) => SOL_MINT_RE.test(m)).sort().slice(0, 100) };
+}
+export function buildTestSignal(h) {
+    return { ...base('test', h), type: 'test', test: true, note: 'channel test: never trade on this' };
+}
+/** One line of JSON, fixed key order (the webhook body, the hook's stdin, the stream line: byte-identical). */
+export const signalLine = (s) => JSON.stringify(s);
+/** Strict shape check: used on replay of the outbox and by receivers. */
+export function validateSignal(x) {
+    const s = x;
+    if (!s || typeof s !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (s.schema !== TRADE_FIRE_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (s.type !== 'trade' && s.type !== 'halted' && s.type !== 'test')
+        return { ok: false, error: 'type' };
+    if (!Number.isSafeInteger(s.nonce) || s.nonce < 1)
+        return { ok: false, error: 'nonce' };
+    if (typeof s.id !== 'string' || !HEX32.test(s.id))
+        return { ok: false, error: 'id' };
+    if (typeof s.accountId !== 'string' || !ACCOUNT_ID_RE.test(s.accountId))
+        return { ok: false, error: 'accountId' };
+    if (typeof s.runId !== 'string' || !RUN_RE.test(s.runId))
+        return { ok: false, error: 'runId' };
+    if (s.id !== signalIdOf(s.accountId, s.runId, s.nonce))
+        return { ok: false, error: 'id does not match account/run/nonce' };
+    if (s.paper !== false)
+        return { ok: false, error: 'paper must be false' };
+    if (!fin(s.issuedAt) || !fin(s.expiresAt) || s.expiresAt <= s.issuedAt)
+        return { ok: false, error: 'times' };
+    const st = s.strategy;
+    if (!st || typeof st.id !== 'string' || !ID_RE.test(st.id) || typeof st.version !== 'string' || typeof st.hash !== 'string')
+        return { ok: false, error: 'strategy' };
+    if (s.type === 'trade') {
+        if (s.side !== 'buy' && s.side !== 'sell')
+            return { ok: false, error: 'side' };
+        if (typeof s.mint !== 'string' || !SOL_MINT_RE.test(s.mint))
+            return { ok: false, error: 'mint' };
+        if (typeof s.symbol !== 'string' || s.symbol !== sanitizeSymbol(s.symbol))
+            return { ok: false, error: 'symbol' };
+        if (s.side === 'buy' ? !(fin(s.sizeSol) > 0) || !(fin(s.sizeUsd) > 0) : !(fin(s.sizeSol) >= 0) || !(fin(s.sizeUsd) >= 0))
+            return { ok: false, error: 'size' };
+        if (s.side === 'sell' && !(fin(s.sellFraction) > 0 && s.sellFraction <= 1))
+            return { ok: false, error: 'sellFraction' };
+    }
+    if (s.type === 'test' && s.test !== undefined && s.test !== true)
+        return { ok: false, error: 'test' };
+    if (s.type === 'test' && 'mint' in s)
+        return { ok: false, error: 'a test signal names no mint' };
+    if (s.type === 'trade' && s.model !== undefined && (typeof s.model !== 'object' || s.model === null))
+        return { ok: false, error: 'model' };
+    if (s.type === 'halted' && s.open !== undefined && (!Array.isArray(s.open) || s.open.length > 100 || !s.open.every((m) => typeof m === 'string' && SOL_MINT_RE.test(m))))
+        return { ok: false, error: 'open' };
+    return { ok: true, signal: s };
+}
+// ───────────────────────────── HMAC ─────────────────────────────
+/** `t=<unix s>,v1=<hex sha256 hmac of "<t>.<body>">`. */
+export function signBody(secret, body, nowMs) {
+    const t = Math.floor(nowMs / 1000);
+    return `t=${t},v1=${createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')}`;
+}
+export function verifyBody(secret, header, body, nowMs, toleranceSec = SIGNATURE_TOLERANCE_SEC) {
+    const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/.exec(String(header ?? ''));
+    if (!m)
+        return { ok: false, why: 'signature-missing' };
+    const t = Number(m[1]);
+    if (Math.abs(nowMs / 1000 - t) > toleranceSec)
+        return { ok: false, why: 'signature-stale' };
+    const want = createHmac('sha256', secret).update(`${t}.${body}`).digest();
+    const got = Buffer.from(m[2], 'hex');
+    return got.length === want.length && timingSafeEqual(got, want) ? { ok: true } : { ok: false, why: 'signature-bad' };
+}
+/**
+ * What a well-behaved executor does with an incoming signal: signature (when a secret is set), shape, account, TTL,
+ * replay (nonce and id). A duplicate is reported as such so a transport can ack it (at-least-once delivery).
+ * Exported for users' scripts and for the fake executors of the tests; dexterm itself never executes anything.
+ */
+export class SignalReceiver {
+    seen = new Set();
+    maxNonce = 0;
+    o;
+    constructor(o) { this.o = o; }
+    receive(body, signature) {
+        const now = (this.o.now ?? Date.now)();
+        if (this.o.secret) {
+            const v = verifyBody(this.o.secret, signature, body, now);
+            if (!v.ok)
+                return { ok: false, why: v.why };
+        }
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            return { ok: false, why: 'not-json' };
+        }
+        const v = validateSignal(raw);
+        if (!v.ok)
+            return { ok: false, why: `invalid:${v.error}` };
+        const s = v.signal;
+        if (s.accountId !== this.o.accountId)
+            return { ok: false, why: 'wrong-account', signal: s };
+        if (this.seen.has(s.id) || this.seen.has(`n${s.nonce}`))
+            return { ok: false, why: 'duplicate', signal: s };
+        if (now > s.expiresAt)
+            return { ok: false, why: 'expired', signal: s };
+        // A nonce at or below one already acted on (that is not a duplicate of it) is a replay of an old signal.
+        if (s.nonce <= this.maxNonce && s.type !== 'halted')
+            return { ok: false, why: 'nonce-replay', signal: s };
+        this.seen.add(s.id);
+        this.seen.add(`n${s.nonce}`);
+        this.maxNonce = Math.max(this.maxNonce, s.nonce);
+        return { ok: true, signal: s };
+    }
+}