Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(neural-trader): #2068 ADR-126 Phase 4 β€” Ed25519-signed backtest artifacts

ruv48cb0a7ee8d9
diff --git a/.github/workflows/v3-ci.yml b/.github/workflows/v3-ci.yml
index a4afbf728a..c2f4e3b85a 100644
--- a/.github/workflows/v3-ci.yml
+++ b/.github/workflows/v3-ci.yml
@@ -44,6 +44,14 @@ on:
- 'plugins/ruflo-neural-trader/src/sublinear-adapter.mjs'
- 'plugins/ruflo-neural-trader/skills/trader-portfolio-cg/**'
- 'scripts/smoke-neural-trader-portfolio-cg.mjs'
+ # Neural-trader backtest signing (#2068, ADR-126 Phase 4) β€” Ed25519
+ # tamper-evidence for paper→live promotion; verifier MUST pin to a
+ # trusted key (CWE-347 / #1922 pattern).
+ - 'plugins/ruflo-neural-trader/src/signed-artifact.ts'
+ - 'plugins/ruflo-neural-trader/src/signed-artifact.mjs'
+ - 'plugins/ruflo-neural-trader/skills/trader-backtest/**'
+ - 'plugins/ruflo-neural-trader/skills/trader-cloud-backtest/**'
+ - 'scripts/smoke-neural-trader-backtest-signing.mjs'
# Plugin-registry CWE-347 regression smoke (#1922) β€” `discovery.ts`
# signature verifier + the smoke fixture must stay in lockstep.
- 'v3/@claude-flow/cli/src/plugins/store/discovery.ts'
@@ -80,6 +88,12 @@ on:
- 'plugins/ruflo-neural-trader/src/sublinear-adapter.mjs'
- 'plugins/ruflo-neural-trader/skills/trader-portfolio-cg/**'
- 'scripts/smoke-neural-trader-portfolio-cg.mjs'
+ # Neural-trader backtest signing (#2068, ADR-126 Phase 4)
+ - 'plugins/ruflo-neural-trader/src/signed-artifact.ts'
+ - 'plugins/ruflo-neural-trader/src/signed-artifact.mjs'
+ - 'plugins/ruflo-neural-trader/skills/trader-backtest/**'
+ - 'plugins/ruflo-neural-trader/skills/trader-cloud-backtest/**'
+ - 'scripts/smoke-neural-trader-backtest-signing.mjs'
# Plugin-registry CWE-347 regression (#1922)
- 'v3/@claude-flow/cli/src/plugins/store/discovery.ts'
- 'v3/@claude-flow/cli/src/transfer/ipfs/client.ts'
@@ -678,6 +692,56 @@ jobs:
- name: Run portfolio CG smoke
run: node scripts/smoke-neural-trader-portfolio-cg.mjs
+ neural-trader-backtest-signing-smoke:
+ # Regression guard for ruvnet/ruflo#2068 β€” ADR-126 Phase 4.
+ #
+ # Phase 4 wires Ed25519-signed backtest artifacts so the paper→live
+ # promotion gate has cryptographic tamper evidence. The signing scheme
+ # mirrors the CWE-347 plugin-registry pattern (#1922): canonical body
+ # = JSON.stringify without signature fields; verifier pins to a
+ # caller-supplied `trustedPublicKey`, NOT to the served self-asserted
+ # `witnessPublicKey` field (which an attacker can swap freely).
+ #
+ # Three load-bearing artifacts must stay in lockstep:
+ # 1. `src/signed-artifact.ts` β€” the typed signer/verifier contract.
+ # 2. `src/signed-artifact.mjs` β€” the runtime mirror imported by the
+ # smoke + (future) skill harnesses (the plugin has no build step).
+ # 3. `skills/trader-backtest/SKILL.md` + `skills/trader-cloud-backtest/SKILL.md`
+ # β€” the call sites that sign before store + verify before promote.
+ #
+ # The smoke runs three layers:
+ # [1/3] STATIC CONTRACT β€” verifier pins to trustedPublicKey (NOT to
+ # artifact.witnessPublicKey), canonical body strips BOTH
+ # signature fields, .ts and .mjs runtime mirrors agree.
+ # [2/3] CRYPTO ROUND-TRIP with real Ed25519 β€” happy path, tampered
+ # body fails, empty sig/pubkey fails, swapped served pubkey
+ # still verifies (pin is real), wrong trusted pubkey fails.
+ # [3/3] CALL-SITE BYTE check β€” trader-cloud-backtest/SKILL.md calls
+ # verifyBacktestArtifact AND documents the fail-closed branch;
+ # trader-backtest/SKILL.md references the signer + degraded
+ # warning + RUFLO_WITNESS_KEY_PATH env var.
+ #
+ # If a future PR drops the verify call, reverts to pinning the served
+ # field, or removes the fail-closed branch, this smoke catches it
+ # before merge.
+ name: neural-trader backtest signing smoke (#2068, ADR-126 Phase 4)
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '22'
+
+ - name: Install root deps (for @noble/ed25519)
+ run: npm install --legacy-peer-deps --no-audit --no-fund --ignore-scripts
+
+ - name: Run backtest signing smoke
+ run: node scripts/smoke-neural-trader-backtest-signing.mjs
+
plugin-registry-signature-smoke:
# Regression guard for ruvnet/ruflo#1922 (CWE-347 β€” improper verification
# of cryptographic signature). The plugin-registry signature verifier in
diff --git a/plugins/ruflo-neural-trader/skills/trader-backtest/SKILL.md b/plugins/ruflo-neural-trader/skills/trader-backtest/SKILL.md
index 02b6aae6af..9d943aca03 100644
--- a/plugins/ruflo-neural-trader/skills/trader-backtest/SKILL.md
+++ b/plugins/ruflo-neural-trader/skills/trader-backtest/SKILL.md
@@ -1,10 +1,10 @@
---
name: trader-backtest
-description: Run a historical backtest using npx neural-trader with Rust/NAPI engine (8-19x faster) and walk-forward validation
+description: Run a historical backtest using npx neural-trader with Rust/NAPI engine (8-19x faster) and walk-forward validation; Ed25519-sign the result for paper→live tamper evidence (ADR-126 Phase 4)
allowed-tools: Bash Read mcp__claude-flow__memory_store mcp__claude-flow__memory_retrieve mcp__claude-flow__memory_search mcp__claude-flow__memory_delete mcp__claude-flow__neural_train mcp__claude-flow__agentdb_pattern-store
argument-hint: "<strategy-name> --symbol <TICKER> [--period 2020-2024]"
---
-Run a historical backtest using the `neural-trader` Rust/NAPI engine.
+Run a historical backtest using the `neural-trader` Rust/NAPI engine, then Ed25519-sign the result so the paper→live promotion gate has cryptographic tamper evidence (ADR-126 Phase 4 + CWE-347 pattern).
Steps:
1. Ensure neural-trader is available:
@@ -20,14 +20,28 @@ Steps:
```bash
npx neural-trader --backtest --strategy multi-indicator --position-sizing kelly --symbol SPY --period 2020-2024
```
-4. Capture performance metrics from output: total return, annualized return, Sharpe ratio, Sortino ratio, max drawdown, win rate, profit factor, number of trades
+4. Capture performance metrics from output: total return, annualized return, Sharpe ratio, Sortino ratio, max drawdown, win rate, profit factor, number of trades.
5. Dedup prior backtests for the same `(strategyId, paramsHash)` before storing the fresh one (ADR-125 lifecycle / ADR-126 Phase 2 β€” `keep-newest` semantics):
- Search: `mcp__claude-flow__memory_search({ query: "backtest STRATEGY paramsHash:PARAMS_HASH", namespace: "trading-backtests", limit: 10 })`
- For each hit whose key matches `backtest-STRATEGY-*` AND whose stored `paramsHash` equals the current run's hash, delete it: `mcp__claude-flow__memory_delete({ key: "OLD_KEY", namespace: "trading-backtests" })`
- (Note: even without this proactive step, the `MemoryConsolidator.dedup('keep-newest')` background pass introduced in `@claude-flow/[email protected]` runs every 6h and will eventually converge. Doing it inline keeps `memory_search` results deterministic immediately after a re-run.)
-6. Store backtest results (long-lived; no TTL β€” backtest history is the audit trail that ADR-126 Phase 4 will Ed25519-sign):
- `mcp__claude-flow__memory_store({ key: "backtest-STRATEGY-TIMESTAMP", value: "RESULTS_JSON", namespace: "trading-backtests" })`
-7. If Sharpe > 1.5, store as successful pattern:
+6. **Sign the artifact (ADR-126 Phase 4):**
+ - Build the `SignedBacktestArtifact` body β€” `{ strategyId, paramsHash, dataRange: {from,to}, metrics, runsHash, generatedAt }` β€” where `paramsHash = sha256(canonical params JSON)`, `runsHash = sha256(canonical runs array JSON)`, and `generatedAt = new Date().toISOString()`.
+ - Resolve the witness signing key. The skill reads the key path in this order; the FIRST that resolves wins:
+ 1. `RUFLO_WITNESS_KEY_PATH` env var β€” points to a JSON file with `{ "privateKey": "<hex>" }`.
+ 2. `verification/witness-key.json` (the ADR-103 default path, if present).
+ - If the key resolves: call `signBacktestArtifact(body, privateKeyHex)` from `plugins/ruflo-neural-trader/src/signed-artifact.mjs`. The returned value is a `SignedBacktestArtifact` with `schema`, `witnessPublicKey: "ed25519:<hex>"`, and `witnessSignature: "<hex>"` populated.
+ - If NEITHER path resolves: log a loud warning — `"[WARN] ruflo-neural-trader: no witness signing key found (RUFLO_WITNESS_KEY_PATH unset, verification/witness-key.json missing) — storing backtest artifact in UNSIGNED degraded mode. paper→live promotion will be refused by trader-cloud-backtest until a signed artifact replaces this one."` — and store the body unsigned. NEVER silently fall back.
+7. **Store the (possibly signed) artifact** to the canonical `trading-backtests` namespace:
+ `mcp__claude-flow__memory_store({ key: "backtest-STRATEGY-TIMESTAMP", value: JSON.stringify(signedArtifact), namespace: "trading-backtests" })`
+ The stored value contains `witnessSignature` + `witnessPublicKey` when signed; downstream consumers (`trader-cloud-backtest`) MUST call `verifyBacktestArtifact(artifact, trustedPublicKey)` before promoting any artifact to live.
+8. If Sharpe > 1.5, store as successful pattern:
`mcp__claude-flow__agentdb_pattern-store({ pattern: "profitable-STRATEGY_TYPE", data: "PARAMS_AND_RESULTS" })`
-8. Train SONA on the outcome:
+9. Train SONA on the outcome:
`mcp__claude-flow__neural_train({ patternType: "trading-strategy", epochs: 10 })`
+
+### Key sourcing & key rotation (ADR-103)
+
+- The witness key is a 32-byte Ed25519 private key, stored as `{ "privateKey": "<64-hex-chars>" }` in a JSON file referenced by `RUFLO_WITNESS_KEY_PATH`. Keep it OUT of the repo. For local development, generate one once with `node -e "import('@noble/ed25519').then(async ed=>{const sk=crypto.getRandomValues(new Uint8Array(32));console.log(Buffer.from(sk).toString('hex'))})"` and write it to `~/.ruflo/witness-key.json`.
+- Production deployments pin the corresponding PUBLIC key in project config and supply it as `trustedPublicKey` to `verifyBacktestArtifact(...)` β€” never trust the `witnessPublicKey` field on the artifact itself (CWE-347 / #1922).
+- Key rotation: re-sign existing backtest entries with the new key OR explicitly mark pre-rotation artifacts as non-promotable. Same pattern as ADR-103.
diff --git a/plugins/ruflo-neural-trader/skills/trader-cloud-backtest/SKILL.md b/plugins/ruflo-neural-trader/skills/trader-cloud-backtest/SKILL.md
index 1c60c3fea4..fecf6f09f2 100644
--- a/plugins/ruflo-neural-trader/skills/trader-cloud-backtest/SKILL.md
+++ b/plugins/ruflo-neural-trader/skills/trader-cloud-backtest/SKILL.md
@@ -55,9 +55,11 @@ Prereq: `ANTHROPIC_API_KEY` (or `CLAUDE_API_KEY`) + Managed Agents beta access.
5. **Pull artifacts (if needed):** `managed_agent_prompt({ sessionId, message: "cat /tmp/equity.csv" })` or `managed_agent_events` and read the tool_result.
-6. **Ingest locally:**
- - `memory_store({ key: "backtest-<strategy>-<ts>", value: <metrics+params JSON>, namespace: "trading-backtests" })`
- - If Sharpe > 1.5: `agentdb_pattern-store({ pattern: "profitable-<strategy-type>", data: "<params + results>" })`
+6. **Ingest locally + Ed25519 verify (ADR-126 Phase 4 fail-closed gate):**
+ - Build the `SignedBacktestArtifact` body from the cloud-returned metrics + params hash + runs hash. Sign it locally with `signBacktestArtifact(body, privateKeyHex)` from `plugins/ruflo-neural-trader/src/signed-artifact.mjs` (key resolution same as `trader-backtest`: `RUFLO_WITNESS_KEY_PATH` β†’ `verification/witness-key.json` β†’ degraded-unsigned warning).
+ - **Before storing OR promoting the artifact to a live strategy**: call `await verifyBacktestArtifact(artifact, trustedPublicKey)` where `trustedPublicKey` is the pinned project-config Ed25519 public key (NOT the `artifact.witnessPublicKey` field β€” that's attacker-controllable; see CWE-347 / #1922). If verification returns `false`: **REFUSE to promote** β€” emit a loud error `"[ERROR] ruflo-neural-trader: SignedBacktestArtifact signature INVALID against trusted key β€” refusing to promote to live strategy"` and return early. This is the fail-closed gate per ADR-126.
+ - On verify success: `memory_store({ key: "backtest-<strategy>-<ts>", value: JSON.stringify(signedArtifact), namespace: "trading-backtests" })`. The stored value carries `witnessSignature` + `witnessPublicKey`.
+ - If Sharpe > 1.5: `agentdb_pattern-store({ pattern: "profitable-<strategy-type>", data: "<params + results>" })`.
- Record the run's container time + token cost to the `cost-tracking` namespace (per ADR-117 β€” cloud sessions bill until terminated).
7. **Terminate immediately** β€” results in hand:
diff --git a/plugins/ruflo-neural-trader/src/signed-artifact.mjs b/plugins/ruflo-neural-trader/src/signed-artifact.mjs
new file mode 100644
index 0000000000..896cd10d98
--- /dev/null
+++ b/plugins/ruflo-neural-trader/src/signed-artifact.mjs
@@ -0,0 +1,98 @@
+// SignedBacktestArtifact β€” runtime ES module mirror of signed-artifact.ts.
+//
+// Why this file exists:
+// The plugin (ruflo-neural-trader) has no package.json / tsconfig /
+// build step β€” it ships skills + agents + scripts only. The `.ts`
+// file is the documented type-shape + source of truth (ADR-126
+// Phase 4 spec). This `.mjs` file is the runtime that the smoke
+// (`scripts/smoke-neural-trader-backtest-signing.mjs`) imports
+// directly, with zero compile step.
+//
+// Both files MUST stay in sync β€” any change to one is a change to the
+// other. The smoke contract-checks the .ts file and runtime-tests the
+// .mjs file; a divergence will fail one half of the smoke.
+//
+// Refs: ADR-126 Phase 4, CWE-347 pattern (#1922), ADR-103 witness.
+
+/**
+ * Sign the body of a backtest artifact. Returns the fully-formed
+ * SignedBacktestArtifact envelope including witnessPublicKey + witnessSignature.
+ */
+export async function signBacktestArtifact(body, privateKeyHex) {
+ const ed = await import('@noble/ed25519');
+ const privateKey = hexToBytes(privateKeyHex);
+ if (privateKey.length !== 32) {
+ throw new Error(
+ `signBacktestArtifact: privateKey must be 32 bytes (got ${privateKey.length})`,
+ );
+ }
+ const canonical = canonicalBytes(body);
+ const signatureBytes = await ed.signAsync(canonical, privateKey);
+ const publicKeyBytes = await ed.getPublicKeyAsync(privateKey);
+ return {
+ schema: 'ruflo-neural-trader-backtest/v1',
+ ...body,
+ witnessPublicKey: `ed25519:${bytesToHex(publicKeyBytes)}`,
+ witnessSignature: bytesToHex(signatureBytes),
+ };
+}
+
+/**
+ * Verify a signed backtest artifact against a caller-supplied trusted key.
+ *
+ * Pins to `trustedPublicKey`, NOT to artifact.witnessPublicKey. The latter
+ * is attacker-controllable; pinning to it defeats the entire verification.
+ * (CWE-347 / #1922 β€” same pattern the plugin-registry verifier uses.)
+ */
+export async function verifyBacktestArtifact(artifact, trustedPublicKey) {
+ if (!artifact || !artifact.witnessSignature || !trustedPublicKey) return false;
+ const ed = await import('@noble/ed25519');
+ const body = {
+ strategyId: artifact.strategyId,
+ paramsHash: artifact.paramsHash,
+ dataRange: artifact.dataRange,
+ metrics: artifact.metrics,
+ runsHash: artifact.runsHash,
+ generatedAt: artifact.generatedAt,
+ };
+ const canonical = canonicalBytes(body);
+ try {
+ const pubKeyHex = trustedPublicKey.replace(/^ed25519:/, '');
+ const pubKey = hexToBytes(pubKeyHex);
+ if (pubKey.length !== 32) return false;
+ const sig = hexToBytes(artifact.witnessSignature);
+ if (sig.length !== 64) return false;
+ return await ed.verifyAsync(sig, canonical, pubKey);
+ } catch {
+ return false;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// helpers (parity with .ts source)
+// ---------------------------------------------------------------------------
+
+function canonicalBytes(body) {
+ const message = JSON.stringify(body);
+ return new TextEncoder().encode(message);
+}
+
+function hexToBytes(hex) {
+ const clean = hex.replace(/^0x/, '');
+ if (clean.length % 2 !== 0) {
+ throw new Error('hexToBytes: odd-length hex string');
+ }
+ const out = new Uint8Array(clean.length / 2);
+ for (let i = 0; i < out.length; i++) {
+ out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+ }
+ return out;
+}
+
+function bytesToHex(bytes) {
+ let s = '';
+ for (let i = 0; i < bytes.length; i++) {
+ s += bytes[i].toString(16).padStart(2, '0');
+ }
+ return s;
+}
diff --git a/plugins/ruflo-neural-trader/src/signed-artifact.ts b/plugins/ruflo-neural-trader/src/signed-artifact.ts
new file mode 100644
index 0000000000..3bbf26a939
--- /dev/null
+++ b/plugins/ruflo-neural-trader/src/signed-artifact.ts
@@ -0,0 +1,186 @@
+/**
+ * SignedBacktestArtifact β€” Phase 4 of ADR-126
+ *
+ * Ed25519-signed envelope for `trading-backtests` entries. The paper→live
+ * promotion gate stores backtest results as the artifact below; the cloud
+ * backtest pipeline (`trader-cloud-backtest`) verifies the signature with a
+ * pinned trusted key BEFORE promoting any artifact to a live strategy.
+ *
+ * Signing scheme β€” mirrors the CWE-347 plugin-registry pattern exactly
+ * (scripts/smoke-plugin-registry-signature.mjs:80-130, the verified-good
+ * reference for "sign with Ed25519, pin to a trusted key, fail closed"):
+ *
+ * 1. Build the artifact body WITHOUT signature fields
+ * (no `witnessSignature`, no `witnessPublicKey`).
+ * 2. `JSON.stringify(...)` plain β€” no whitespace, no sort.
+ * 3. Sign the resulting bytes with Ed25519.
+ * 4. Verify pins to a caller-supplied `trustedPublicKey`,
+ * NOT to the self-asserted `witnessPublicKey` field on the artifact
+ * (an attacker controls that field; pinning to it is a no-op).
+ *
+ * Key sourcing:
+ * - The signer accepts a 32-byte private key as a hex string. The
+ * `trader-backtest` skill resolves the key at runtime via the env var
+ * `RUFLO_WITNESS_KEY_PATH` (a JSON file with a `{ "privateKey": "<hex>" }`
+ * field). If unset, callers may fall back to the legacy ADR-103 witness
+ * key path; if neither is available, the skill stores the artifact in
+ * UNSIGNED degraded mode with a loud warning β€” never silently.
+ *
+ * - The verifier accepts a `trustedPublicKey` as `"ed25519:<hex>"` or
+ * plain `<hex>`. Production deployments pin this in project config.
+ *
+ * Refs:
+ * - ADR-126 Phase 4 β€” the integration plan
+ * - ADR-103 β€” witness temporal history
+ * - CWE-347 / #1922 β€” the pattern this signing scheme matches
+ * - scripts/smoke-plugin-registry-signature.mjs β€” the reference smoke
+ */
+
+/* ---------------------------------------------------------------------- */
+/* Public types */
+/* ---------------------------------------------------------------------- */
+
+export interface SignedBacktestArtifact {
+ schema: 'ruflo-neural-trader-backtest/v1';
+ strategyId: string;
+ paramsHash: string; // sha256 of canonical params JSON
+ dataRange: { from: string; to: string };
+ metrics: Record<string, number>;
+ runsHash: string; // sha256 of the canonical runs array JSON
+ generatedAt: string; // ISO timestamp
+ witnessPublicKey: string; // 'ed25519:<hex>' β€” self-asserted (NOT pinned by verifier)
+ witnessSignature: string; // hex of the Ed25519 signature over the canonical body
+}
+
+/** The body that gets signed β€” everything except the two signature fields. */
+export type SignedBacktestArtifactBody = Omit<
+ SignedBacktestArtifact,
+ 'witnessPublicKey' | 'witnessSignature' | 'schema'
+>;
+
+/* ---------------------------------------------------------------------- */
+/* Signing + verification */
+/* ---------------------------------------------------------------------- */
+
+/**
+ * Sign the body of a backtest artifact and return the fully-formed
+ * `SignedBacktestArtifact` envelope.
+ *
+ * The signature covers the artifact body WITHOUT `witnessSignature` and
+ * WITHOUT `witnessPublicKey` (CWE-347 pattern). This means an attacker who
+ * swaps the served `witnessPublicKey` field cannot bypass verification when
+ * the verifier pins to a trusted key (which is the only safe verifier).
+ *
+ * @param body β€” the artifact body (everything except signature fields + schema)
+ * @param privateKeyHex β€” 32-byte Ed25519 private key as hex string (no 'ed25519:' prefix)
+ * @returns β€” the signed artifact ready to be stored
+ */
+export async function signBacktestArtifact(
+ body: SignedBacktestArtifactBody,
+ privateKeyHex: string,
+): Promise<SignedBacktestArtifact> {
+ const ed = await import('@noble/ed25519');
+ const privateKey = hexToBytes(privateKeyHex);
+ if (privateKey.length !== 32) {
+ throw new Error(
+ `signBacktestArtifact: privateKey must be 32 bytes (got ${privateKey.length})`,
+ );
+ }
+
+ // Canonical body = the artifact WITHOUT signature fields, plain JSON.stringify.
+ // Matches scripts/smoke-plugin-registry-signature.mjs:193-200.
+ const canonical = canonicalBytes(body);
+ const signatureBytes = await ed.signAsync(canonical, privateKey);
+ const publicKeyBytes = await ed.getPublicKeyAsync(privateKey);
+
+ return {
+ schema: 'ruflo-neural-trader-backtest/v1',
+ ...body,
+ witnessPublicKey: `ed25519:${bytesToHex(publicKeyBytes)}`,
+ witnessSignature: bytesToHex(signatureBytes),
+ };
+}
+
+/**
+ * Verify a signed backtest artifact against a caller-supplied trusted
+ * public key. Returns `true` iff the signature is valid for the canonical
+ * body under the TRUSTED key.
+ *
+ * IMPORTANT β€” the verifier pins to `trustedPublicKey`, NOT to the artifact's
+ * `witnessPublicKey` field. The artifact's self-asserted public key is
+ * untrusted input: an attacker who tampers with the stored entry can swap
+ * that field freely. Pinning to a trusted key supplied by project config
+ * is the only safe pattern (CWE-347 / #1922).
+ *
+ * @param artifact β€” the artifact to verify (may have been tampered)
+ * @param trustedPublicKey β€” caller-supplied trusted pubkey, with or without 'ed25519:' prefix
+ * @returns β€” true iff signature verifies against the trusted key
+ */
+export async function verifyBacktestArtifact(
+ artifact: SignedBacktestArtifact,
+ trustedPublicKey: string,
+): Promise<boolean> {
+ if (!artifact || !artifact.witnessSignature || !trustedPublicKey) return false;
+ const ed = await import('@noble/ed25519');
+
+ // Strip BOTH signature fields (and schema, which is constant) to get the
+ // canonical body that was signed.
+ const body: SignedBacktestArtifactBody = {
+ strategyId: artifact.strategyId,
+ paramsHash: artifact.paramsHash,
+ dataRange: artifact.dataRange,
+ metrics: artifact.metrics,
+ runsHash: artifact.runsHash,
+ generatedAt: artifact.generatedAt,
+ };
+ const canonical = canonicalBytes(body);
+
+ try {
+ const pubKeyHex = trustedPublicKey.replace(/^ed25519:/, '');
+ const pubKey = hexToBytes(pubKeyHex);
+ if (pubKey.length !== 32) return false;
+ const sig = hexToBytes(artifact.witnessSignature);
+ if (sig.length !== 64) return false;
+ return await ed.verifyAsync(sig, canonical, pubKey);
+ } catch {
+ return false;
+ }
+}
+
+/* ---------------------------------------------------------------------- */
+/* Helpers */
+/* ---------------------------------------------------------------------- */
+
+/**
+ * Canonical bytes for signing = `JSON.stringify(body)` UTF-8 encoded.
+ *
+ * Matches the plugin-registry signer (publish-registry.ts:127-151) and the
+ * CWE-347 smoke (smoke-plugin-registry-signature.mjs:193-200): plain
+ * `JSON.stringify` with NO whitespace and NO key sort. The body shape is
+ * authored by us (the signer), so deterministic key order is guaranteed by
+ * construction β€” no canonicalizer needed.
+ */
+function canonicalBytes(body: SignedBacktestArtifactBody): Uint8Array {
+ const message = JSON.stringify(body);
+ return new TextEncoder().encode(message);
+}
+
+function hexToBytes(hex: string): Uint8Array {
+ const clean = hex.replace(/^0x/, '');
+ if (clean.length % 2 !== 0) {
+ throw new Error(`hexToBytes: odd-length hex string`);
+ }
+ const out = new Uint8Array(clean.length / 2);
+ for (let i = 0; i < out.length; i++) {
+ out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+ }
+ return out;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+ let s = '';
+ for (let i = 0; i < bytes.length; i++) {
+ s += bytes[i].toString(16).padStart(2, '0');
+ }
+ return s;
+}
diff --git a/scripts/smoke-neural-trader-backtest-signing.mjs b/scripts/smoke-neural-trader-backtest-signing.mjs
new file mode 100644
index 0000000000..e1b50f2833
--- /dev/null
+++ b/scripts/smoke-neural-trader-backtest-signing.mjs
@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * Smoke test for ADR-126 Phase 4 (#2068) β€” Ed25519-signed backtest artifacts.
+ *
+ * Locks in three layers (modelled on scripts/smoke-plugin-registry-signature.mjs,
+ * the CWE-347 reference for "sign with Ed25519, pin to a trusted key, fail
+ * closed"):
+ *
+ * [1/3] STATIC CONTRACT on signed-artifact.{ts,mjs}:
+ * - both files exist and export `signBacktestArtifact` +
+ * `verifyBacktestArtifact`
+ * - the verifier pins to a caller-supplied `trustedPublicKey`, NOT
+ * to artifact.witnessPublicKey (CWE-347 / #1922)
+ * - canonical message construction strips BOTH `witnessSignature`
+ * AND `witnessPublicKey` before stringifying β€” otherwise an
+ * attacker who swaps the served pubkey can re-sign the body.
+ * - canonical message is JSON.stringify (no whitespace, no sort) β€”
+ * matches the plugin-registry signer scheme exactly.
+ *
+ * [2/3] CRYPTO ROUND-TRIP with real Ed25519 against the .mjs runtime:
+ * - signed fixture verifies with the trusted pubkey
+ * - tampered body fails
+ * - empty signature fails
+ * - empty pubkey fails
+ * - swapped served `witnessPublicKey` (attacker scenario) β€” still
+ * verifies because we pin to the TRUSTED pubkey, not the served field
+ * - wrong trusted pubkey fails (proves the pin is real, not a no-op)
+ *
+ * [3/3] CALL-SITE BYTE check on trader-cloud-backtest/SKILL.md:
+ * - skill contains an `verifyBacktestArtifact(...)` call
+ * - skill contains a fail-closed branch on the failure path (refuse
+ * to promote / return early / error message)
+ *
+ * If a future PR drops the verify call, reverts the canonical-message
+ * construction, or removes the fail-closed branch, this smoke catches it
+ * before merge.
+ *
+ * Usage: node scripts/smoke-neural-trader-backtest-signing.mjs
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { TextEncoder } from 'node:util';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..');
+const PLUGIN_DIR = join(REPO_ROOT, 'plugins', 'ruflo-neural-trader');
+const ARTIFACT_TS = join(PLUGIN_DIR, 'src', 'signed-artifact.ts');
+const ARTIFACT_MJS = join(PLUGIN_DIR, 'src', 'signed-artifact.mjs');
+const TRADER_BACKTEST_MD = join(PLUGIN_DIR, 'skills', 'trader-backtest', 'SKILL.md');
+const CLOUD_BACKTEST_MD = join(PLUGIN_DIR, 'skills', 'trader-cloud-backtest', 'SKILL.md');
+
+const failures = [];
+function check(label, ok, detail = '') {
+ if (ok) console.log(` βœ“ ${label}`);
+ else {
+ console.log(` βœ— ${label}${detail ? ' β€” ' + detail : ''}`);
+ failures.push(label);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Part 1 β€” Static contract on signed-artifact.{ts,mjs}
+// ---------------------------------------------------------------------------
+
+console.log('[1/3] Static contract on signed-artifact.{ts,mjs}');
+
+if (!existsSync(ARTIFACT_TS)) {
+ failures.push('signed-artifact.ts not found');
+} else {
+ const src = readFileSync(ARTIFACT_TS, 'utf8');
+ check(
+ 'TS exports `signBacktestArtifact` + `verifyBacktestArtifact`',
+ /export\s+async\s+function\s+signBacktestArtifact\s*\(/.test(src) &&
+ /export\s+async\s+function\s+verifyBacktestArtifact\s*\(/.test(src),
+ 'expected both functions to be exported as async',
+ );
+ check(
+ 'TS declares `SignedBacktestArtifact` interface with required fields',
+ /interface\s+SignedBacktestArtifact/.test(src) &&
+ /schema\s*:\s*'ruflo-neural-trader-backtest\/v1'/.test(src) &&
+ /witnessPublicKey\s*:\s*string/.test(src) &&
+ /witnessSignature\s*:\s*string/.test(src) &&
+ /paramsHash\s*:\s*string/.test(src) &&
+ /runsHash\s*:\s*string/.test(src),
+ 'shape per ADR-126 Phase 4 spec',
+ );
+ // Verifier MUST pin to caller's trustedPublicKey, not the served field.
+ // We assert this by looking for the param `trustedPublicKey` in the
+ // verifier signature AND for `replace(/^ed25519:/, '')` on it (the pin
+ // path) AND for the absence of any `artifact.witnessPublicKey` usage
+ // INSIDE the verifier body's pubkey computation.
+ if (/export\s+async\s+function\s+verifyBacktestArtifact\s*\(\s*[^)]*trustedPublicKey/.test(src)) {
+ check('TS verifier accepts `trustedPublicKey` as a parameter', true);
+ } else {
+ check('TS verifier accepts `trustedPublicKey` as a parameter', false, 'verifier MUST take trustedPublicKey as second arg, not infer from artifact');
+ }
+ // The verifier must NOT use artifact.witnessPublicKey when computing the
+ // verification pubkey (the served field is attacker-controllable).
+ const verifierBody = (() => {
+ const m = /export\s+async\s+function\s+verifyBacktestArtifact[\s\S]*?\{([\s\S]*?)\n\}/.exec(src);
+ return m ? m[1] : '';
+ })();
+ check(
+ 'TS verifier does NOT consume artifact.witnessPublicKey for verification',
+ verifierBody && !/artifact\.witnessPublicKey/.test(verifierBody),
+ 'reading artifact.witnessPublicKey defeats the pin β€” pin to trustedPublicKey only',
+ );
+ // Canonical message construction must strip BOTH signature fields.
+ // The TS version does this implicitly by building a `body` object that
+ // omits `witnessPublicKey`, `witnessSignature`, and `schema`. We grep
+ // for that pattern.
+ check(
+ 'TS verifier builds canonical body WITHOUT witnessSignature + witnessPublicKey',
+ /const\s+body[\s\S]{0,300}?strategyId:\s*artifact\.strategyId/.test(src) &&
+ !/body\.witnessSignature\s*=/.test(src) &&
+ !/body\.witnessPublicKey\s*=/.test(src),
+ 'canonical body MUST exclude both signature fields before stringify',
+ );
+ check(
+ 'TS canonical bytes use plain JSON.stringify (no whitespace, no sort)',
+ /JSON\.stringify\(\s*body\s*\)/.test(src),
+ 'match the plugin-registry signer scheme: plain JSON.stringify',
+ );
+}
+
+if (!existsSync(ARTIFACT_MJS)) {
+ failures.push('signed-artifact.mjs (runtime mirror) not found');
+} else {
+ const mjs = readFileSync(ARTIFACT_MJS, 'utf8');
+ check(
+ 'MJS runtime exports `signBacktestArtifact` + `verifyBacktestArtifact`',
+ /export\s+async\s+function\s+signBacktestArtifact\b/.test(mjs) &&
+ /export\s+async\s+function\s+verifyBacktestArtifact\b/.test(mjs),
+ '.mjs mirror must keep parity with the .ts source',
+ );
+ check(
+ 'MJS verifier pins to caller-supplied `trustedPublicKey`',
+ /verifyBacktestArtifact\s*\(\s*artifact\s*,\s*trustedPublicKey/.test(mjs) &&
+ /trustedPublicKey\.replace\(\s*\/\^ed25519:\/\s*,\s*''\)/.test(mjs),
+ 'verifier param name must be trustedPublicKey AND it must be the one normalized',
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Part 2 β€” Crypto round-trip with real Ed25519
+// ---------------------------------------------------------------------------
+
+console.log('\n[2/3] Crypto round-trip via the .mjs runtime');
+
+let ed;
+try {
+ ed = await import('@noble/ed25519');
+} catch (err) {
+ failures.push('@noble/ed25519 not installed β€” run `npm install` at repo root');
+ console.error(` βœ— @noble/ed25519 import failed: ${err.message}`);
+}
+
+let signBacktestArtifact, verifyBacktestArtifact;
+try {
+ const mod = await import(pathToFileURL(ARTIFACT_MJS).href);
+ signBacktestArtifact = mod.signBacktestArtifact;
+ verifyBacktestArtifact = mod.verifyBacktestArtifact;
+} catch (err) {
+ failures.push('signed-artifact.mjs runtime import failed');
+ console.error(` βœ— runtime import failed: ${err.message}`);
+}
+
+if (ed && signBacktestArtifact && verifyBacktestArtifact) {
+ // Deterministic test key (same scheme as the plugin-registry smoke).
+ const privateKey = new Uint8Array(32);
+ for (let i = 0; i < 32; i++) privateKey[i] = (i * 19 + 7) % 256;
+ const privateKeyHex = Buffer.from(privateKey).toString('hex');
+ const publicKeyBytes = await ed.getPublicKeyAsync(privateKey);
+ const trustedPubKeyHex = `ed25519:${Buffer.from(publicKeyBytes).toString('hex')}`;
+
+ const body = {
+ strategyId: 'momentum-spy-2024',
+ paramsHash: 'a'.repeat(64),
+ dataRange: { from: '2020-01-01', to: '2024-12-31' },
+ metrics: { sharpe: 1.8, maxDrawdown: 0.11, totalReturn: 0.42 },
+ runsHash: 'b'.repeat(64),
+ generatedAt: '2026-05-19T12:00:00.000Z',
+ };
+
+ const signed = await signBacktestArtifact(body, privateKeyHex);
+
+ // (a) happy path
+ check(
+ 'signed fixture verifies with the trusted pubkey',
+ await verifyBacktestArtifact(signed, trustedPubKeyHex),
+ );
+
+ // sanity: artifact has the documented shape
+ check(
+ 'signed artifact carries schema + witnessPublicKey + witnessSignature',
+ signed.schema === 'ruflo-neural-trader-backtest/v1' &&
+ typeof signed.witnessPublicKey === 'string' &&
+ signed.witnessPublicKey.startsWith('ed25519:') &&
+ typeof signed.witnessSignature === 'string' &&
+ signed.witnessSignature.length === 128,
+ `got: schema=${signed.schema} pk-len=${signed.witnessPublicKey?.length} sig-len=${signed.witnessSignature?.length}`,
+ );
+
+ // (b) tamper one byte of the body β†’ verify fails
+ const tampered = JSON.parse(JSON.stringify(signed));
+ tampered.metrics.sharpe = 99.9; // attacker inflates Sharpe to clear promotion gate
+ check(
+ 'tampered body (sharpe inflated) fails verification',
+ !(await verifyBacktestArtifact(tampered, trustedPubKeyHex)),
+ 'inflating metrics MUST invalidate the signature',
+ );
+
+ // (c) empty signature fails
+ check(
+ 'empty signature fails',
+ !(await verifyBacktestArtifact({ ...signed, witnessSignature: '' }, trustedPubKeyHex)),
+ );
+
+ // (d) empty pubkey fails
+ check(
+ 'empty trusted pubkey fails',
+ !(await verifyBacktestArtifact(signed, '')),
+ );
+
+ // (e) swap served witnessPublicKey to a different value β†’ verify still
+ // succeeds because we pin to the TRUSTED key (CWE-347 / #1922).
+ const swappedServed = {
+ ...signed,
+ witnessPublicKey: 'ed25519:' + '0'.repeat(64),
+ };
+ check(
+ 'verifier ignores swapped served witnessPublicKey (pinned to trusted key)',
+ await verifyBacktestArtifact(swappedServed, trustedPubKeyHex),
+ 'pin to trustedPublicKey MUST override the served self-asserted pubkey',
+ );
+
+ // (f) different trusted pubkey fails β€” proves the pin is real
+ const wrongTrusted = 'ed25519:' + '0'.repeat(64);
+ check(
+ 'wrong trusted pubkey fails (pin is real, not a no-op)',
+ !(await verifyBacktestArtifact(signed, wrongTrusted)),
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Part 3 β€” Call-site byte check on trader-cloud-backtest/SKILL.md
+// ---------------------------------------------------------------------------
+
+console.log('\n[3/3] Call-site byte check on trader-cloud-backtest/SKILL.md');
+
+if (!existsSync(CLOUD_BACKTEST_MD)) {
+ failures.push('trader-cloud-backtest/SKILL.md not found');
+} else {
+ const skill = readFileSync(CLOUD_BACKTEST_MD, 'utf8');
+ check(
+ 'skill calls `verifyBacktestArtifact(artifact, trustedPublicKey)`',
+ /verifyBacktestArtifact\s*\([^)]*trustedPublicKey/.test(skill),
+ 'skill must invoke the verifier with the pinned trusted pubkey before promotion',
+ );
+ check(
+ 'skill documents the fail-closed branch (refuse to promote)',
+ /refuse to promote/i.test(skill) &&
+ (/return\s+early/i.test(skill) || /return\s*;/.test(skill) || /\[ERROR\]/.test(skill)),
+ 'skill must show explicit refusal + early-return on verify failure',
+ );
+ check(
+ 'skill references the pinned trusted pubkey path (NOT the served field)',
+ /trustedPublicKey/.test(skill) && /NOT\s+the\s+`?artifact\.witnessPublicKey`?\s+field|attacker-controllable/i.test(skill),
+ 'docs must call out CWE-347: pin to trusted key, not served self-asserted field',
+ );
+}
+
+// Also verify the trader-backtest skill mentions signing in its flow.
+if (!existsSync(TRADER_BACKTEST_MD)) {
+ failures.push('trader-backtest/SKILL.md not found');
+} else {
+ const skill = readFileSync(TRADER_BACKTEST_MD, 'utf8');
+ check(
+ 'trader-backtest skill references signBacktestArtifact',
+ /signBacktestArtifact/.test(skill),
+ 'skill must invoke the signer when a key is present',
+ );
+ check(
+ 'trader-backtest skill documents the degraded-unsigned warning path',
+ /UNSIGNED degraded mode/.test(skill) || /unsigned.*degraded/i.test(skill),
+ 'no-key case must be logged loudly, never silent',
+ );
+ check(
+ 'trader-backtest skill documents RUFLO_WITNESS_KEY_PATH env var',
+ /RUFLO_WITNESS_KEY_PATH/.test(skill),
+ 'production key sourcing must be documented',
+ );
+}
+
+// ---------------------------------------------------------------------------
+console.log('');
+if (failures.length > 0) {
+ console.log(`FAIL: ${failures.length} issue(s) β€” see above`);
+ process.exit(1);
+} else {
+ console.log('OK: ADR-126 Phase 4 backtest-signing β€” schema + signer + verifier + skill gates verified');
+ process.exit(0);
+}