dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/trade/kill-switch.js

@@ -0,0 +1,47 @@
+// dexterm T1 — the PANIC kill switch (SPEC §6.4 "panic key", §6.5 `panic()`; task-1310 round 2).
+//
+// The cheapest safe version of the signer's panic path tonight: a marker file under ~/.dexterm. While
+// it exists, the live executor refuses every plan and every confirm, in EVERY process that reads it
+// (the file is re-read on each check, never cached), so `dexterm wallet panic` from a second terminal
+// stops a trade that another dexterm is about to sign. A file we cannot parse counts as ENGAGED
+// (fail closed). Releasing it (`dexterm wallet resume`) requires a real TTY keypress — see the CLI.
+// This module holds no keys and performs no network I/O.
+import { readFileSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export function defaultPanicPath() {
+    return join(homedir(), '.dexterm', 'trading.panic');
+}
+export class KillSwitch {
+    path;
+    constructor(path = defaultPanicPath()) { this.path = path; }
+    /** The engaged record, or null when live trading is allowed. Always re-reads the file. */
+    engaged() {
+        if (!existsSync(this.path))
+            return null;
+        try {
+            const raw = JSON.parse(readFileSync(this.path, 'utf8'));
+            return { engagedAt: Number(raw.engagedAt) || 0, reason: typeof raw.reason === 'string' ? raw.reason.slice(0, 200) : 'panic' };
+        }
+        catch {
+            return { engagedAt: 0, reason: 'panic file unreadable (treated as engaged)' };
+        }
+    }
+    /** Engage: disable live trading everywhere. Idempotent; the first reason is kept. */
+    engage(reason = 'panic', now = Date.now()) {
+        const existing = this.engaged();
+        if (existing)
+            return existing;
+        const rec = { engagedAt: now, reason: reason.slice(0, 200) };
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
+        return rec;
+    }
+    /** Release: returns true when a panic was engaged. The CLI gates this behind a TTY keypress. */
+    release() {
+        if (!existsSync(this.path))
+            return false;
+        rmSync(this.path, { force: true });
+        return true;
+    }
+}

package/dist/packages/data/src/trade/link-store.js

@@ -0,0 +1,52 @@
+// dexterm T1 — the linked-wallet store. dexterm persists ONLY the public key (an address; never a
+// private key, seed or signature). Kept in a small JSON file outside any repo, mode 600 as
+// defence-in-depth even though a pubkey is public. The bridge (bridge.ts) produces the pubkey; this
+// just remembers it so the status bar can show "linked: <short>" and the executor knows the signer.
+import { readFileSync, writeFileSync, rmSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+const B58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+export function defaultLinkPath() {
+    return join(homedir(), '.dexterm', 'wallet-link.json');
+}
+export function shortPubkey(pk) {
+    return pk.length > 10 ? `${pk.slice(0, 4)}…${pk.slice(-4)}` : pk;
+}
+export class WalletLinkStore {
+    path;
+    constructor(path = defaultLinkPath()) { this.path = path; }
+    /** The linked wallet, or null when none / unreadable / malformed. */
+    get() {
+        try {
+            if (!existsSync(this.path))
+                return null;
+            const raw = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (typeof raw.publicKey !== 'string' || !B58.test(raw.publicKey))
+                return null;
+            return { publicKey: raw.publicKey, linkedAt: Number(raw.linkedAt) || 0, network: typeof raw.network === 'string' ? raw.network : undefined };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Persist a linked wallet. Validates the pubkey is base58; refuses anything that is not an address. */
+    set(publicKey, opts = {}) {
+        if (!B58.test(publicKey))
+            throw new Error('refusing to store a non-base58 value as a wallet pubkey');
+        const rec = { publicKey, linkedAt: opts.now ?? Date.now(), network: opts.network };
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch { /* best effort on platforms without chmod */ }
+        return rec;
+    }
+    /** Remove the link; returns true when a link existed. */
+    clear() {
+        if (!existsSync(this.path))
+            return false;
+        rmSync(this.path, { force: true });
+        return true;
+    }
+}

package/dist/packages/data/src/trade/plans/confirm.js

@@ -0,0 +1,157 @@
+// task-1355 — the CONFIRM GATE: three confirmation tiers, all bound to the plan hash (SPEC §6.13.4).
+//
+//   tier 1  keypress    (DEFAULT)  hold a physical key >= HOLD_MS on the plan card, or a Phantom approval
+//   tier 2  ptt-held               speak "send it <code>" WHILE the push-to-talk key is physically held
+//   tier 3  hands-free             speak "send it <code>" with the key up — only after the "this is less
+//                                  safe" risk popup was accepted by keypress (local, logged, reversible,
+//                                  expires), and with lower caps
+//
+// The signer side issues a CHALLENGE for one plan hash: {code, readBack, expiresAt}. The read-back is
+// what is spoken/rendered; the two-digit code inside it is what the user must echo. A confirmation is
+// accepted only if the challenge is unconsumed, unexpired, for the CURRENT plan hash, and the evidence
+// satisfies the tier. On success the gate returns a GESTURE PROOF (single-use) that the engine's `arm`
+// consumes. Nothing in this file can execute anything; it only decides whether a proof exists.
+// Ported from the task-1292 reference simulation (research/task-1292/sim/confirm.mjs), typed.
+export const HOLD_MS = 400;
+export const CHALLENGE_TTL_MS = { 'keypress': 90_000, 'ptt-held': 20_000, 'hands-free': 12_000 };
+/** The mic is muted while the read-back is spoken; a "confirm" that lands inside this window after it is echo. */
+export const ECHO_GUARD_MS = 300;
+export const RISK_ACCEPT_TTL_MS = 24 * 3600_000;
+const PHRASE_RE = /^\s*send it[,\s]+(\d{2})\s*$/i;
+export class ConfirmError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'ConfirmError';
+        this.reason = reason;
+    }
+}
+export class Settings {
+    clock;
+    journal;
+    gateOff = false;
+    risk = null;
+    constructor(clock, journal) { this.clock = clock; this.journal = journal; }
+    /** Turning the keypress gate off needs the risk popup accepted BY KEYPRESS. Logged. Expires. Reversible. */
+    acceptRiskPopup(gesture) {
+        if (gesture?.gesture !== 'keypress')
+            throw new ConfirmError('risk-needs-keypress', 'the "less safe" popup can only be accepted with a keypress');
+        const now = this.clock.now();
+        this.risk = { acceptedAt: now, expiresAt: now + RISK_ACCEPT_TTL_MS, text: 'this is less safe' };
+        this.gateOff = true;
+        this.journal?.append('settings.gate-off', { data: { acceptedAt: now, expiresAt: this.risk.expiresAt, by: 'keypress' } });
+    }
+    restoreGate() { this.gateOff = false; this.risk = null; this.journal?.append('settings.gate-on', {}); }
+    handsFreeAllowed(now) { return this.gateOff && this.risk !== null && now <= this.risk.expiresAt; }
+}
+export class ConfirmGate {
+    clock;
+    journal;
+    settings;
+    rng;
+    challenges = new Map();
+    proofs = new Map();
+    n = 0;
+    handsFreeAllowed() { return this.settings.handsFreeAllowed(this.clock.now()); }
+    constructor({ clock, journal, settings, rng = Math.random }) {
+        this.clock = clock;
+        this.journal = journal;
+        this.settings = settings;
+        this.rng = rng;
+    }
+    /** Issue a challenge for a plan at a tier. The code is random per challenge so a recording cannot be replayed. */
+    issue(plan, tier, readBackText) {
+        if (!(tier in CHALLENGE_TTL_MS))
+            throw new ConfirmError('bad-tier', 'unknown tier');
+        const now = this.clock.now();
+        const code = String(10 + Math.floor(this.rng() * 90)); // 10..99
+        const c = {
+            id: `ch_${++this.n}`, planId: plan.id, planHash: plan.hash, tier, code, issuedAt: now, expiresAt: now + CHALLENGE_TTL_MS[tier],
+            readBack: `${readBackText} Confirm code ${code}.`, readBackSpokenUntil: now + 2500, consumed: false,
+        };
+        this.challenges.set(c.id, c);
+        this.journal?.append('confirm.challenge', { planId: plan.id, data: { challengeId: c.id, planHash: plan.hash, tier, expiresAt: c.expiresAt } });
+        return c;
+    }
+    /**
+     * Try to confirm. `currentPlan` is the plan the engine holds NOW for that id (hash may have moved).
+     * Returns a gesture proof, or throws ConfirmError with a typed reason. Every outcome is journaled.
+     */
+    confirm({ challengeId, evidence }, currentPlan) {
+        const c = this.challenges.get(challengeId);
+        const now = this.clock.now();
+        const journal = this.journal;
+        // function declaration (not an arrow) so its `never` return narrows `c`/`currentPlan` below.
+        function fail(reason, message) {
+            journal?.append('confirm.refused', { planId: c?.planId ?? null, data: { challengeId, reason } });
+            throw new ConfirmError(reason, message);
+        }
+        if (!c)
+            fail('unknown-challenge', 'no such challenge');
+        if (c.consumed)
+            fail('challenge-consumed', 'this confirmation was already used (replay)');
+        if (now > c.expiresAt)
+            fail('challenge-expired', 'the confirmation window closed; re-read the plan');
+        if (!currentPlan || currentPlan.id !== c.planId)
+            fail('plan-gone', 'the plan no longer exists');
+        if (currentPlan.hash !== c.planHash)
+            fail('plan-hash-mismatch', 'the plan changed since it was read back; confirm the new one');
+        if (currentPlan.status !== 'proposed')
+            fail('plan-not-proposed', `plan is ${currentPlan.status}`);
+        const gesture = this.checkEvidence(c, evidence, now, fail);
+        c.consumed = true;
+        const proof = { id: `proof_${c.id}`, kind: 'gesture', signerIssued: true, gesture, tier: c.tier, subject: `plan:${c.planId}:${c.planHash}`, at: now, consumed: false };
+        this.proofs.set(proof.id, proof);
+        this.journal?.append('confirm.accepted', { planId: c.planId, data: { challengeId: c.id, tier: c.tier, gesture, planHash: c.planHash } });
+        return proof;
+    }
+    checkEvidence(c, ev, now, fail) {
+        if (!ev || typeof ev !== 'object')
+            fail('no-evidence', 'no confirmation evidence');
+        const e = ev;
+        if (c.tier === 'keypress') {
+            if (e.kind === 'phantom-approval' && e.approvedPlanHash === c.planHash)
+                return 'phantom';
+            if (e.kind !== 'keypress')
+                fail('tier-mismatch', 'a keypress-tier challenge needs a keypress (or Phantom approval)');
+            const kp = e;
+            if (!(kp.holdMs >= HOLD_MS))
+                fail('hold-too-short', `hold the key for at least ${HOLD_MS} ms`);
+            if (kp.synthetic)
+                fail('synthetic-key', 'synthetic key events are not a gesture');
+            return 'keypress';
+        }
+        // spoken tiers
+        if (e.kind !== 'spoken')
+            fail('tier-mismatch', 'this challenge needs a spoken confirmation');
+        const sp = e;
+        if (sp.speakerCount !== 1)
+            fail('multiple-speakers', 'more than one speaker');
+        if (sp.echoFlag)
+            fail('echo', 'the recogniser flagged echo of our own audio');
+        if (sp.utteranceStart < c.readBackSpokenUntil + ECHO_GUARD_MS)
+            fail('echo-window', 'confirmation arrived while the read-back was still being spoken');
+        const m = PHRASE_RE.exec(sp.phrase ?? '');
+        if (!m)
+            fail('bad-phrase', 'say "send it" followed by the two-digit code');
+        if (m[1] !== c.code)
+            fail('bad-code', 'wrong confirmation code');
+        if (c.tier === 'ptt-held') {
+            if (!(typeof sp.pttDownAt === 'number' && typeof sp.pttUpAt === 'number'))
+                fail('ptt-not-held', 'push-to-talk was not held');
+            if (!(sp.pttDownAt <= sp.utteranceStart && sp.utteranceEnd <= sp.pttUpAt))
+                fail('ptt-not-held', 'the confirmation must be spoken entirely while the talk key is held');
+            return 'spoken-ptt';
+        }
+        // hands-free
+        if (!this.settings.handsFreeAllowed(now))
+            fail('gate-on', 'hands-free confirm is off: the keypress gate is on (accept the "less safe" popup first)');
+        if (sp.pttHeld)
+            return 'spoken-ptt'; // holding the key is always at least as good
+        return 'spoken-free';
+    }
+}
+/** The caps multiplier a gesture earns (keypress/phantom = full mandate caps; spoken = less). */
+export function gestureTier(gesture) {
+    return gesture === 'keypress' || gesture === 'phantom' ? 'keypress' : gesture === 'spoken-ptt' ? 'ptt-held' : 'hands-free';
+}