@projectsolo/solo-mission-mcp 0.21.13 → 0.22.0

package/src/solana/wallet.test.ts

@@ -7,8 +7,9 @@
  *
  * `fixtures/test-keypair.json.enc` is a throwaway, never-funded devnet keypair — safe to check in.
  */
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'fs';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import { decryptOpenSslAes256CbcPbkdf2, SolanaWalletUnavailable } from './wallet';
 
@@ -43,3 +44,85 @@ describe('decryptOpenSslAes256CbcPbkdf2', () => {
     );
   });
 });
+
+describe('loadSolanaWallet sources', () => {
+  const VARS = [
+    'SOLO_SOLANA_KEYPAIR',
+    'SOLO_SOLANA_KEYPAIR_PATH',
+    'SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH',
+    'SOLO_SOLANA_KEYPAIR_PASSWORD_FILE',
+  ];
+  const saved: Record<string, string | undefined> = {};
+  let dir: string;
+
+  // The wallet module caches the first successful load, so each test imports a fresh copy.
+  const freshWallet = async () => {
+    vi.resetModules();
+    return import('./wallet');
+  };
+
+  beforeEach(() => {
+    for (const v of VARS) {
+      saved[v] = process.env[v];
+      delete process.env[v];
+    }
+    dir = mkdtempSync(join(tmpdir(), 'solo-wallet-test-'));
+  });
+
+  afterEach(() => {
+    for (const v of VARS) {
+      if (saved[v] === undefined) delete process.env[v];
+      else process.env[v] = saved[v];
+    }
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects the removed raw-key env var and names both replacements', async () => {
+    const w = await freshWallet();
+    process.env.SOLO_SOLANA_KEYPAIR = decryptOpenSslAes256CbcPbkdf2(encrypted, PASSPHRASE).toString('utf8');
+    // Counted as configured so get_solana_wallet surfaces this error, not generic setup help.
+    expect(w.hasSolanaWallet()).toBe(true);
+    const err = await w.loadSolanaWallet().catch((e) => e);
+    expect(err).toBeInstanceOf(w.SolanaWalletUnavailable);
+    expect(err.message).toMatch(/SOLO_SOLANA_KEYPAIR \(the raw key in an environment variable\) is no longer supported/);
+    expect(err.message).toMatch(/SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH \+\s+SOLO_SOLANA_KEYPAIR_PASSWORD_FILE/);
+    expect(err.message).toMatch(/SOLO_SOLANA_KEYPAIR_PATH/);
+  });
+
+  it('rejects the removed var even when a supported source is also set', async () => {
+    const w = await freshWallet();
+    process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH = join(FIXTURE_DIR, 'test-keypair.json.enc');
+    const pass = join(dir, 'pass');
+    writeFileSync(pass, PASSPHRASE + '\n');
+    process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE = pass;
+    process.env.SOLO_SOLANA_KEYPAIR = '[1,2,3]';
+    await expect(w.loadSolanaWallet()).rejects.toThrow(/no longer supported/);
+  });
+
+  it('loads the encrypted keyfile + passphrase file', async () => {
+    const w = await freshWallet();
+    process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH = join(FIXTURE_DIR, 'test-keypair.json.enc');
+    const pass = join(dir, 'pass');
+    writeFileSync(pass, PASSPHRASE + '\n');
+    process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE = pass;
+    expect(w.hasSolanaWallet()).toBe(true);
+    expect((await w.loadSolanaWallet()).publicKey).toBe(expectedPubkey);
+  });
+
+  it('loads a plaintext keyfile from SOLO_SOLANA_KEYPAIR_PATH', async () => {
+    const w = await freshWallet();
+    const keyfile = join(dir, 'id.json');
+    writeFileSync(keyfile, decryptOpenSslAes256CbcPbkdf2(encrypted, PASSPHRASE));
+    process.env.SOLO_SOLANA_KEYPAIR_PATH = keyfile;
+    expect((await w.loadSolanaWallet()).publicKey).toBe(expectedPubkey);
+  });
+
+  it('reports no wallet, with key-storage guidance, when nothing is set', async () => {
+    const w = await freshWallet();
+    expect(w.hasSolanaWallet()).toBe(false);
+    const err = await w.loadSolanaWallet().catch((e) => e);
+    expect(err.message).toMatch(/no wallet source configured/);
+    expect(err.message).toMatch(/secret manager/);
+    expect(err.message).not.toMatch(/SOLO_SOLANA_KEYPAIR\b(?!_)/);
+  });
+});

package/src/solana/wallet.ts

@@ -1,8 +1,8 @@
 /**
  * The agent's Solana wallet.
  *
- * An agent needs SOL as well as USDC to sponsor a Solana mission, and that is new — on Base it
- * needed only ETH for gas and USDC for the budget. The rent line has no EVM analogue:
+ * An agent needs SOL as well as USDC to sponsor a Solana mission: SOL for transaction fees and for
+ * account rent, a refundable deposit that is easy to miss because it is not a fee:
  *
  *   Task account rent      ~0.00374 SOL   ($0.374)  — partly recovered on close_task
  *   TaskVault token account ~0.00204 SOL   ($0.204)  — recovered in full on close_task
@@ -20,23 +20,30 @@
  * one. That is the whole point of the partial-signing flow: a compromised backend cannot move a
  * sponsor's funds, because it never holds the signing key.
  *
- * AT REST, prefer SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE over the
- * plain SOLO_SOLANA_KEYPAIR / SOLO_SOLANA_KEYPAIR_PATH pair. `solana-keygen new`'s own output is a
- * plaintext JSON byte array — chmod 600 protects it from other users on the box, but not from
- * whoever gets that one file (a compromised account, a stray backup, a copied disk image). The
- * encrypted form splits the secret in two: the ciphertext and the passphrase file are only useful
- * together, matching what `references/wallet-setup.md` already does for the Base private key
- * (openssl-encrypt at rest, decrypt only transiently). Encrypt with the exact command below so the
+ * WHERE THE KEY COMES FROM. Two sources, both files:
+ *
+ *   SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE   (recommended)
+ *   SOLO_SOLANA_KEYPAIR_PATH                                                 (plaintext keyfile)
+ *
+ * The raw key in an environment variable (SOLO_SOLANA_KEYPAIR) is no longer accepted: env vars
+ * are inherited by every child process and end up in shell history and client config files, and
+ * the ClawHub audit penalised exactly that pattern. If it is still set, loading the wallet fails
+ * with an error naming the replacements rather than ignoring it.
+ *
+ * `solana-keygen new`'s own output is a plaintext JSON byte array — chmod 600 protects it from
+ * other users on the box, but not from whoever gets that one file (a compromised account, a stray
+ * backup, a copied disk image). The encrypted form splits the secret in two: the ciphertext and
+ * the passphrase file are only useful together. Encrypt with the exact command below so the
  * decryptor here (which reimplements OpenSSL's KDF, not shells out to it) derives the same key:
  *
  *   openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256 \
  *     -in ~/.config/solana/solo-sponsor.json -out solo-sponsor.json.enc
  *   chmod 600 solo-sponsor.json.enc
- *   echo -n "your-passphrase" > keystore.pass && chmod 600 keystore.pass
  *   # then delete the plaintext solo-sponsor.json
  *
- * The plain SOLO_SOLANA_KEYPAIR / SOLO_SOLANA_KEYPAIR_PATH pair still works, unchanged, for
- * quick-start / devnet use where this doesn't matter.
+ * Keep the keyfile and the passphrase in a secret manager and have it write the files when the MCP
+ * server starts (see KEY_STORAGE_GUIDANCE). Never type either into chat, argv or shell history.
+ * Remote signing (KMS/HSM) is not supported yet.
  */
 
 import { readFileSync } from 'fs';
@@ -48,16 +55,29 @@ export interface SolanaWallet {
   secretKey: Uint8Array;
 }
 
+/** Where to keep the key. Shared by the wallet error and get_solana_wallet's setup help. */
+export const KEY_STORAGE_GUIDANCE =
+  'Keep the keyfile and the passphrase in your secret manager and have it write the files when ' +
+  'the MCP server starts: for example 1Password (`op inject`, `op read --out-file`), a HashiCorp ' +
+  'Vault Agent template, GCP Secret Manager (`gcloud secrets versions access`), or the macOS ' +
+  'Keychain (`security find-generic-password -w`). Never paste the key or the passphrase into ' +
+  'chat, a command line or shell history.';
+
+/** The raw-key env var this package used to accept. Setting it is now an error, not ignored. */
+export const REMOVED_INLINE_KEY_VAR = 'SOLO_SOLANA_KEYPAIR';
+
 export class SolanaWalletUnavailable extends Error {
   constructor(reason: string) {
     super(
       `Solana wallet unavailable: ${reason}\n\n` +
         'Set one of:\n' +
         '  SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE\n' +
-        '                            - recommended: an openssl-aes-256-cbc-pbkdf2-encrypted\n' +
-        '                              keyfile plus a separate passphrase file (chmod 600 both)\n' +
-        '  SOLO_SOLANA_KEYPAIR       - JSON byte array, as `solana-keygen` writes it (plaintext)\n' +
-        '  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json), plaintext\n\n' +
+        '                            - recommended: a keyfile encrypted with\n' +
+        '                              `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`\n' +
+        '                              plus a separate passphrase file (chmod 600 both)\n' +
+        '  SOLO_SOLANA_KEYPAIR_PATH  - path to a plaintext `solana-keygen` keyfile\n' +
+        '                              (e.g. ~/.config/solana/id.json, chmod 600)\n\n' +
+        `${KEY_STORAGE_GUIDANCE}\n\n` +
         'The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a\n' +
         'refundable deposit, not a fee: most of it returns when the task is closed.',
     );
@@ -65,6 +85,20 @@ export class SolanaWalletUnavailable extends Error {
   }
 }
 
+/**
+ * Throws if the removed raw-key env var is set. Checked before any other source, so a stale
+ * config fails loudly instead of the key sitting in the environment unnoticed.
+ */
+export function assertNoInlineKeyVar(): void {
+  if ((process.env[REMOVED_INLINE_KEY_VAR] ?? '').trim() !== '') {
+    throw new SolanaWalletUnavailable(
+      `${REMOVED_INLINE_KEY_VAR} (the raw key in an environment variable) is no longer supported. ` +
+        'Unset it, and move the key into a file referenced by SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + ' +
+        'SOLO_SOLANA_KEYPAIR_PASSWORD_FILE (recommended) or SOLO_SOLANA_KEYPAIR_PATH.',
+    );
+  }
+}
+
 /**
  * Decrypts a file produced by `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`.
  *
@@ -140,14 +174,15 @@ let cachedWallet: SolanaWallet | undefined;
  * Loads the agent's wallet.
  *
  * Read at call time, not at module load, so a tool that never touches Solana works in a process
- * with no wallet configured at all — an agent running Base missions should not need one.
+ * with no wallet configured at all — an agent running only free off-chain missions should not
+ * need one.
  */
 export async function loadSolanaWallet(): Promise<SolanaWallet> {
   if (cachedWallet) return cachedWallet;
+  assertNoInlineKeyVar();
 
   const encryptedPath = process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH;
   const passwordFile = process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE;
-  const inline = process.env.SOLO_SOLANA_KEYPAIR;
   const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
 
   let raw: string;
@@ -170,8 +205,6 @@ export async function loadSolanaWallet(): Promise<SolanaWallet> {
       throw new SolanaWalletUnavailable(`cannot read ${passwordFile}: ${(e as Error).message}`);
     }
     raw = decryptOpenSslAes256CbcPbkdf2(encrypted, password).toString('utf8');
-  } else if (inline && inline.trim() !== '') {
-    raw = inline;
   } else if (path && path.trim() !== '') {
     try {
       raw = readFileSync(expandHome(path), 'utf8');
@@ -180,7 +213,7 @@ export async function loadSolanaWallet(): Promise<SolanaWallet> {
     }
   } else {
     throw new SolanaWalletUnavailable(
-      'no wallet source configured (checked SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH, SOLO_SOLANA_KEYPAIR, SOLO_SOLANA_KEYPAIR_PATH)',
+      'no wallet source configured (checked SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH, SOLO_SOLANA_KEYPAIR_PATH)',
     );
   }
 
@@ -191,13 +224,17 @@ export async function loadSolanaWallet(): Promise<SolanaWallet> {
   return cachedWallet;
 }
 
-/** Whether a Solana wallet is configured, without throwing. */
+/**
+ * Whether a Solana wallet is configured, without throwing. The removed raw-key var counts as
+ * "configured" on purpose: the caller then loads the wallet and surfaces the error that names the
+ * replacements, instead of showing generic setup help that never mentions the stale var.
+ */
 export function hasSolanaWallet(): boolean {
   return Boolean(
     cachedWallet ||
+      (process.env[REMOVED_INLINE_KEY_VAR] ?? '').trim() ||
       ((process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH ?? '').trim() &&
         (process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE ?? '').trim()) ||
-      (process.env.SOLO_SOLANA_KEYPAIR ?? '').trim() ||
       (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? '').trim(),
   );
 }
@@ -221,16 +258,22 @@ export async function associatedTokenAddress(mint: string, owner: string): Promi
   return address.toBase58();
 }
 
-/** Signs a base64 transaction built by the backend, returning it base64-encoded. */
+/**
+ * Signs a base64 transaction built by the backend, returning it base64-encoded.
+ *
+ * Fills in ONLY this wallet's signature slot, on the wire bytes. A v2 lottery funding transaction
+ * arrives already co-signed by the platform Operator over the exact message; the message and every
+ * other signature are left byte-for-byte as received — never stripped, reordered or re-serialised —
+ * and that is asserted before the result is returned (see `addOwnSignature`).
+ */
 export async function signTransaction(
   transactionBase64: string,
   wallet: SolanaWallet,
 ): Promise<string> {
-  const { Keypair, Transaction } = await import('@solana/web3.js');
-  const kp = Keypair.fromSecretKey(wallet.secretKey);
-  const tx = Transaction.from(Buffer.from(transactionBase64, 'base64'));
-  // partialSign, not sign: the transaction may carry other signature slots, and `sign` would
-  // discard them.
-  tx.partialSign(kp);
-  return tx.serialize().toString('base64');
+  const { addOwnSignature } = await import('./wire.js');
+  return addOwnSignature(
+    Buffer.from(transactionBase64, 'base64'),
+    wallet.secretKey,
+    wallet.publicKey,
+  ).toString('base64');
 }

package/src/solana/wire.test.ts

@@ -0,0 +1,129 @@
+/**
+ * The wire decoder and the signer. The signer is what keeps a lottery's Operator co-signature
+ * intact, so it is checked byte-for-byte: against web3.js for a single-signer transaction, and
+ * against the real co-signed fixture for the two-signer case.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { Keypair, PublicKey, Transaction } from '@solana/web3.js'
+import {
+  addOwnSignature,
+  base58Decode,
+  base58Encode,
+  ed25519Verify,
+  isEmptySignature,
+  isSignerIndex,
+  isWritableIndex,
+  parseWireTransaction,
+  publicKeyOfSecret,
+} from './wire'
+import { decryptOpenSslAes256CbcPbkdf2, signTransaction } from './wallet'
+
+const FIX = join(__dirname, 'fixtures')
+const load = (f: string) => JSON.parse(readFileSync(join(FIX, f), 'utf8'))
+const lottery = load('funding-transaction-v2-lottery.json')
+const plain = load('funding-transaction-v2-plain.json')
+const raw = (fx: any) => Buffer.from(fx.response.transaction_base64, 'base64')
+
+// The never-funded test sponsor both v2 fixtures were built for.
+const sponsorSecret = Uint8Array.from(
+  JSON.parse(
+    decryptOpenSslAes256CbcPbkdf2(
+      readFileSync(join(FIX, 'test-keypair.json.enc')),
+      'test-only-fixture-passphrase',
+    ).toString('utf8'),
+  ),
+)
+const sponsor = Keypair.fromSecretKey(sponsorSecret)
+const wallet = { publicKey: sponsor.publicKey.toBase58(), secretKey: sponsorSecret }
+
+describe('parseWireTransaction', () => {
+  for (const [label, fx] of [['lottery', lottery], ['non-lottery', plain]] as const) {
+    it(`decodes the ${label} fixture exactly as web3.js does`, () => {
+      const ours = parseWireTransaction(raw(fx))
+      const theirs = Transaction.from(raw(fx))
+      expect(ours.accountKeys[0]).toBe(theirs.feePayer!.toBase58())
+      expect(ours.recentBlockhash).toBe(theirs.recentBlockhash)
+      expect(ours.message.equals(theirs.serializeMessage())).toBe(true)
+      expect(ours.instructions).toHaveLength(theirs.instructions.length)
+      const ix = ours.instructions[0]
+      const tix = theirs.instructions[0]
+      expect(ours.accountKeys[ix.programIdIndex]).toBe(tix.programId.toBase58())
+      expect(ix.data.equals(tix.data)).toBe(true)
+      ix.accountIndexes.forEach((k, i) => {
+        expect(ours.accountKeys[k]).toBe(tix.keys[i].pubkey.toBase58())
+        expect(isSignerIndex(ours, k)).toBe(tix.keys[i].isSigner)
+        expect(isWritableIndex(ours, k)).toBe(tix.keys[i].isWritable)
+      })
+      expect(ours.signatures.map((s) => s.toString('hex'))).toEqual(
+        theirs.signatures.map((s) => (s.signature ? Buffer.from(s.signature).toString('hex') : '00'.repeat(64))),
+      )
+    })
+  }
+
+  it('refuses trailing bytes, truncation and versioned messages', () => {
+    expect(() => parseWireTransaction(Buffer.concat([raw(plain), Buffer.from([0])]))).toThrow(/trailing/)
+    expect(() => parseWireTransaction(raw(plain).subarray(0, 100))).toThrow(/truncated/)
+    const versioned = Buffer.from(raw(plain))
+    versioned[1 + 64] |= 0x80
+    expect(() => parseWireTransaction(versioned)).toThrow(/versioned/)
+  })
+
+  it('base58 round-trips like PublicKey', () => {
+    for (const k of [PublicKey.default, new PublicKey(lottery.sponsor), Keypair.generate().publicKey]) {
+      expect(base58Encode(k.toBytes())).toBe(k.toBase58())
+      expect(base58Decode(k.toBase58()).equals(Buffer.from(k.toBytes()))).toBe(true)
+    }
+  })
+})
+
+describe('addOwnSignature', () => {
+  it('produces exactly what web3.js partialSign produces for a single-signer transaction', () => {
+    const t = Transaction.from(raw(plain))
+    t.partialSign(sponsor)
+    const ours = addOwnSignature(raw(plain), sponsorSecret, wallet.publicKey)
+    expect(ours.equals(t.serialize())).toBe(true)
+  })
+
+  it('keeps the Operator co-signature byte-for-byte and adds a valid sponsor signature', () => {
+    const before = parseWireTransaction(raw(lottery))
+    const operator = before.accountKeys[1]
+    expect(ed25519Verify(before.signatures[1], before.message, operator)).toBe(true)
+    expect(isEmptySignature(before.signatures[0])).toBe(true)
+
+    const after = parseWireTransaction(addOwnSignature(raw(lottery), sponsorSecret, wallet.publicKey))
+    expect(after.message.equals(before.message)).toBe(true)
+    expect(after.signatures[1].equals(before.signatures[1])).toBe(true)
+    expect(ed25519Verify(after.signatures[1], after.message, operator)).toBe(true)
+    expect(ed25519Verify(after.signatures[0], after.message, wallet.publicKey)).toBe(true)
+    // What the runtime checks: every required signature present and valid.
+    expect(Transaction.from(addOwnSignature(raw(lottery), sponsorSecret, wallet.publicKey)).verifySignatures()).toBe(true)
+  })
+
+  it('refuses to sign a transaction this wallet is not a signer of', () => {
+    const other = Keypair.generate()
+    expect(() => addOwnSignature(raw(plain), other.secretKey, other.publicKey.toBase58())).toThrow(
+      /not a required signer/,
+    )
+  })
+
+  it('refuses a secret key that does not derive the claimed public key', () => {
+    expect(() => addOwnSignature(raw(plain), Keypair.generate().secretKey, wallet.publicKey)).toThrow(
+      /does not derive/,
+    )
+    expect(publicKeyOfSecret(sponsorSecret)).toBe(wallet.publicKey)
+  })
+})
+
+describe('signTransaction (wallet)', () => {
+  it('signs a co-signed lottery transaction without disturbing the co-signature', async () => {
+    const signed = Buffer.from(await signTransaction(lottery.response.transaction_base64, wallet), 'base64')
+    const before = raw(lottery)
+    expect(signed.length).toBe(before.length)
+    const tx = parseWireTransaction(signed)
+    // Only the sponsor's 64 bytes changed.
+    expect(signed.subarray(tx.signatureOffset + 64).equals(before.subarray(tx.signatureOffset + 64))).toBe(true)
+    expect(ed25519Verify(tx.signatures[0], tx.message, wallet.publicKey)).toBe(true)
+  })
+})