@suisei-mcp/agent-signer 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @suisei-mcp/agent-signer
+
+The non-custodial signer for a **Tier-1 Sui agent wallet**.
+
+[`@suisei-mcp/mcp`](../mcp) builds *unsigned* transaction
+bytes and never holds a key. This package is the one piece that does: it
+generates the agent's keypair, stores it **encrypted on your machine**, and
+signs builder bytes. The plaintext key is created here, used here, and
+**never crosses a process boundary** — it never travels through an MCP
+response or into an LLM's context.
+
+## What "Tier-1 agent wallet" means
+
+A real Sui wallet the agent fully controls, funded with a small allowance.
+The agent can stake, transfer, swap — anything — but only up to its
+balance. Blast radius = what you fund. Refill to extend, sweep to revoke.
+Your main wallet is never touched: the agent has its own freshly-generated
+key, and your owner key stays in your real wallet.
+
+## Install
+
+```bash
+npm install -g @suisei-mcp/agent-signer
+```
+
+## Use
+
+Set a passphrase (encrypts the key at rest) and create the wallet:
+
+```bash
+export AGENT_WALLET_PASSPHRASE="something-long-and-private"
+agent-signer create
+# -> { "address": "0x…", "path": "~/.suisei/agent-wallet.json" }
+```
+
+Then the loop with Claude + the MCP:
+
+1. Ask the agent to fund it: it calls `agent_wallet_fund` (owner-signed) so
+   your real wallet sends SUI to the agent address.
+2. Ask the agent to act, e.g. *"stake 1 SUI to the top validator from my
+   agent wallet"* — it builds the tx and gives you `tx_bytes_base64`.
+3. Sign with the agent key:
+   ```bash
+   agent-signer sign <tx_bytes_base64>
+   # -> { "signature": "…" }
+   ```
+4. Tell the agent to `sui_execute_signed_tx` with that signature.
+
+To revoke, ask the agent for `agent_wallet_sweep` (drains the wallet back to
+you), sign it, submit, and stop funding.
+
+## You own the key — back it up or move it
+
+The wallet isn't locked inside this tool. The private key is yours,
+encrypted under your passphrase, and you can take it out anytime:
+
+```bash
+agent-signer export
+# -> { "address": "0x…", "secret_key": "suiprivkey1…", "warning": "…" }
+```
+
+That `suiprivkey1…` is a standard Sui secret. Import it into **Sui Wallet**,
+**Suiet**, or the CLI (`sui keytool import "<suiprivkey1…>" ed25519`) and
+you have the same wallet there. Back it up offline — anyone holding it
+controls the wallet.
+
+Bring your own key instead of generating one:
+
+```bash
+agent-signer import "suiprivkey1…"
+```
+
+Because the key is exportable, losing the keystore file isn't fatal **if
+you backed up the export**. If you didn't and you lose the file or
+passphrase, the agent wallet is gone — but it only ever holds an allowance,
+so create a fresh one and refund. Your owner wallet is untouched.
+
+## Configuration
+
+| Env / flag | Default | Meaning |
+| --- | --- | --- |
+| `AGENT_WALLET_PASSPHRASE` / `--passphrase` | — (required) | Encrypts/decrypts the key |
+| `AGENT_WALLET_PATH` / `--path` | `~/.suisei/agent-wallet.json` | Keystore location |
+
+## Security model
+
+- **Ed25519** key, sealed with **AES-256-GCM** under a **scrypt**-derived
+  key (N=32768). Keystore written `0600`.
+- Wrong passphrase → decryption fails closed (GCM auth tag).
+- `create`/`address` emit only the public address; `sign` emits only a
+  signature. The raw secret is revealed only by an explicit `export` (with
+  a warning) — never incidentally, and never to the MCP or an agent.
+- Lose the keystore or passphrase and the agent wallet is gone — by design
+  it holds only an allowance, so create a fresh one and refund. Your owner
+  wallet (in your real wallet app) is unaffected.
+
+This is **Tier 1** of the agent-wallet design. On-chain policy limits
+(Tier 2) and a multisig co-signer (Tier 3) layer on top — see
+[`docs/AGENT_WALLET_DESIGN.md`](../../docs/AGENT_WALLET_DESIGN.md).
+
+## License
+
+MIT.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { createWallet, walletAddress, signTxBytes, exportSecret, importWallet, defaultPath, } from './index.js';
+/**
+ * agent-signer CLI — the manual signing path for a Tier-1 agent wallet.
+ *
+ *   agent-signer create [--overwrite]      generate + encrypt a new agent key
+ *   agent-signer import <suiprivkey>       seal an existing key as the wallet
+ *   agent-signer export                    reveal the raw key (backup / import elsewhere)
+ *   agent-signer address                   print the agent wallet address
+ *   agent-signer sign <txBytesBase64>      sign builder bytes -> base64 signature
+ *
+ * Passphrase comes from AGENT_WALLET_PASSPHRASE (preferred) or --passphrase.
+ * Keystore path from AGENT_WALLET_PATH or --path (default ~/.suisei/agent-wallet.json).
+ *
+ * Typical loop with Claude + the MCP:
+ *   1. agent builds a tx  -> tx_bytes_base64
+ *   2. agent-signer sign <tx_bytes_base64>  -> copy the "signature"
+ *   3. tell the agent to sui_execute_signed_tx with that signature
+ */
+function flag(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i !== -1 ? process.argv[i + 1] : undefined;
+}
+function has(name) {
+    return process.argv.includes(`--${name}`);
+}
+function getPassphrase() {
+    const p = process.env.AGENT_WALLET_PASSPHRASE ?? flag('passphrase');
+    if (!p) {
+        fail('No passphrase. Set AGENT_WALLET_PASSPHRASE or pass --passphrase <value>. ' +
+            'This encrypts the agent key at rest.');
+    }
+    return p;
+}
+function getPath() {
+    return flag('path') ?? defaultPath();
+}
+function out(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+function fail(msg) {
+    process.stderr.write(`error: ${msg}\n`);
+    process.exit(1);
+}
+async function main() {
+    const cmd = process.argv[2];
+    switch (cmd) {
+        case 'create': {
+            const res = createWallet({
+                passphrase: getPassphrase(),
+                path: getPath(),
+                overwrite: has('overwrite'),
+            });
+            out({
+                created: true,
+                address: res.address,
+                path: res.path,
+                next_step: 'Fund it with the agent_wallet_fund MCP tool (owner-signed), then the agent can spend up to its balance.',
+            });
+            break;
+        }
+        case 'import': {
+            const secret = process.argv[3];
+            if (!secret || secret.startsWith('--')) {
+                fail('Usage: agent-signer import <suiprivkey1...>');
+            }
+            const res = importWallet({
+                passphrase: getPassphrase(),
+                secret,
+                path: getPath(),
+                overwrite: has('overwrite'),
+            });
+            out({ imported: true, address: res.address, path: res.path });
+            break;
+        }
+        case 'export': {
+            const { address, secretBech32 } = exportSecret({
+                passphrase: getPassphrase(),
+                path: getPath(),
+            });
+            out({
+                address,
+                secret_key: secretBech32,
+                warning: 'This is the full private key. Anyone with it controls the wallet. Back it up offline; import into Sui Wallet / Suiet / `sui keytool import` to use it elsewhere.',
+            });
+            break;
+        }
+        case 'address': {
+            out({ address: walletAddress({ passphrase: getPassphrase(), path: getPath() }) });
+            break;
+        }
+        case 'sign': {
+            const txBytesBase64 = process.argv[3];
+            if (!txBytesBase64 || txBytesBase64.startsWith('--')) {
+                fail('Usage: agent-signer sign <txBytesBase64>');
+            }
+            const res = await signTxBytes({
+                passphrase: getPassphrase(),
+                txBytesBase64,
+                path: getPath(),
+            });
+            out({
+                address: res.address,
+                signature: res.signature,
+                next_step: 'Submit with the sui_execute_signed_tx MCP tool: pass the same tx bytes and this signature.',
+            });
+            break;
+        }
+        default:
+            process.stdout.write([
+                'agent-signer — non-custodial signer for a Tier-1 Sui agent wallet',
+                '',
+                'Commands:',
+                '  create [--overwrite]     generate + encrypt a new agent key',
+                '  import <suiprivkey>      seal an existing key as the wallet',
+                '  export                   reveal the raw key (backup / import elsewhere)',
+                '  address                  print the agent wallet address',
+                '  sign <txBytesBase64>     sign builder bytes -> base64 signature',
+                '',
+                'Auth:  AGENT_WALLET_PASSPHRASE (or --passphrase), AGENT_WALLET_PATH (or --path)',
+                '',
+            ].join('\n'));
+            if (cmd && cmd !== 'help' && cmd !== '--help')
+                process.exit(1);
+    }
+}
+main().catch((e) => fail(e instanceof Error ? e.message : String(e)));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+/**
+ * @suisei-mcp/agent-signer — the non-custodial signer for a Tier-1 Sui agent
+ * wallet.
+ *
+ * The MCP toolkit builds unsigned tx bytes and never holds a key. This is
+ * the only piece that does: it generates the agent keypair, stores it
+ * encrypted on the user's machine, and signs tx bytes. The plaintext key
+ * is created here, used here, and never returned across a process boundary
+ * — in particular it never travels through an MCP response or an LLM
+ * context.
+ *
+ * Pair the signature this produces with sui_execute_signed_tx to submit.
+ */
+export interface CreateResult {
+    address: string;
+    path: string;
+}
+/** Generate a fresh agent keypair and persist it encrypted. Returns the address only. */
+export declare function createWallet(opts: {
+    passphrase: string;
+    path?: string;
+    overwrite?: boolean;
+}): CreateResult;
+/** Load and decrypt the agent keypair. Plaintext stays inside this process. */
+export declare function loadKeypair(opts: {
+    passphrase: string;
+    path?: string;
+}): Ed25519Keypair;
+/** The agent wallet address, without decrypting the key (reads the stored address). */
+export declare function walletAddress(opts: {
+    passphrase: string;
+    path?: string;
+}): string;
+/**
+ * Reveal the raw bech32 `suiprivkey...` secret so the user can back it up
+ * or import the agent wallet into a standard wallet (Sui Wallet, Suiet,
+ * `sui keytool import`). This is the user's escape hatch — it proves they,
+ * not us, own the key. Handle the output carefully: anyone with this string
+ * controls the wallet.
+ */
+export declare function exportSecret(opts: {
+    passphrase: string;
+    path?: string;
+}): {
+    address: string;
+    secretBech32: string;
+};
+/**
+ * Import an existing key as the agent wallet: seal a bech32 `suiprivkey...`
+ * (or raw 32-byte) secret into the keystore. Lets a user bring their own
+ * key instead of generating one.
+ */
+export declare function importWallet(opts: {
+    passphrase: string;
+    secret: string;
+    path?: string;
+    overwrite?: boolean;
+}): CreateResult;
+/**
+ * Sign base64 tx bytes (from any @suisei-mcp/mcp builder tool) with the agent
+ * key. Returns the base64 Sui signature to pass to sui_execute_signed_tx.
+ */
+export declare function signTxBytes(opts: {
+    passphrase: string;
+    txBytesBase64: string;
+    path?: string;
+}): Promise<{
+    address: string;
+    signature: string;
+}>;
+export { defaultPath } from './keystore.js';

package/dist/index.js

@@ -0,0 +1,69 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+import { defaultPath, saveSecret, loadSecret, keystoreExists } from './keystore.js';
+/** Generate a fresh agent keypair and persist it encrypted. Returns the address only. */
+export function createWallet(opts) {
+    const path = opts.path ?? defaultPath();
+    if (keystoreExists(path) && !opts.overwrite) {
+        throw new Error(`An agent wallet already exists at ${path}. Pass overwrite to replace it (you will lose the old key).`);
+    }
+    const kp = new Ed25519Keypair();
+    const address = kp.getPublicKey().toSuiAddress();
+    saveSecret({ path, passphrase: opts.passphrase, address, secretBech32: kp.getSecretKey() });
+    return { address, path };
+}
+/** Load and decrypt the agent keypair. Plaintext stays inside this process. */
+export function loadKeypair(opts) {
+    const path = opts.path ?? defaultPath();
+    const { secretBech32 } = loadSecret({ path, passphrase: opts.passphrase });
+    return Ed25519Keypair.fromSecretKey(secretBech32);
+}
+/** The agent wallet address, without decrypting the key (reads the stored address). */
+export function walletAddress(opts) {
+    const path = opts.path ?? defaultPath();
+    return loadSecret({ path, passphrase: opts.passphrase }).address;
+}
+/**
+ * Reveal the raw bech32 `suiprivkey...` secret so the user can back it up
+ * or import the agent wallet into a standard wallet (Sui Wallet, Suiet,
+ * `sui keytool import`). This is the user's escape hatch — it proves they,
+ * not us, own the key. Handle the output carefully: anyone with this string
+ * controls the wallet.
+ */
+export function exportSecret(opts) {
+    const path = opts.path ?? defaultPath();
+    return loadSecret({ path, passphrase: opts.passphrase });
+}
+/**
+ * Import an existing key as the agent wallet: seal a bech32 `suiprivkey...`
+ * (or raw 32-byte) secret into the keystore. Lets a user bring their own
+ * key instead of generating one.
+ */
+export function importWallet(opts) {
+    const path = opts.path ?? defaultPath();
+    if (keystoreExists(path) && !opts.overwrite) {
+        throw new Error(`An agent wallet already exists at ${path}. Pass overwrite to replace it (you will lose the old key).`);
+    }
+    let kp;
+    try {
+        kp = Ed25519Keypair.fromSecretKey(opts.secret.trim());
+    }
+    catch {
+        throw new Error('Invalid secret key. Expected a bech32 "suiprivkey1..." string.');
+    }
+    const address = kp.getPublicKey().toSuiAddress();
+    // Re-serialize through getSecretKey() so storage is always canonical bech32.
+    saveSecret({ path, passphrase: opts.passphrase, address, secretBech32: kp.getSecretKey() });
+    return { address, path };
+}
+/**
+ * Sign base64 tx bytes (from any @suisei-mcp/mcp builder tool) with the agent
+ * key. Returns the base64 Sui signature to pass to sui_execute_signed_tx.
+ */
+export async function signTxBytes(opts) {
+    const kp = loadKeypair({ passphrase: opts.passphrase, path: opts.path });
+    const bytes = new Uint8Array(Buffer.from(opts.txBytesBase64, 'base64'));
+    const { signature } = await kp.signTransaction(bytes);
+    return { address: kp.getPublicKey().toSuiAddress(), signature };
+}
+export { defaultPath } from './keystore.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/keystore.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Encrypted-at-rest keystore for the agent wallet's Ed25519 secret key.
+ *
+ * The secret is sealed with AES-256-GCM under a key derived from a
+ * passphrase via scrypt. We store only ciphertext + the public address.
+ * Nothing here ever returns a plaintext key to a caller other than the
+ * in-process signer, and the file is written 0600. The key never leaves
+ * the user's machine and never enters an agent/LLM context.
+ */
+export interface KeystoreFile {
+    version: 1;
+    address: string;
+    scheme: 'ed25519';
+    kdf: 'scrypt';
+    salt: string;
+    iv: string;
+    auth_tag: string;
+    ciphertext: string;
+    created_at: string;
+}
+/** Default keystore path; override with AGENT_WALLET_PATH. */
+export declare function defaultPath(): string;
+/** Encrypt a bech32 `suiprivkey...` string into a keystore file on disk. */
+export declare function saveSecret(opts: {
+    path: string;
+    passphrase: string;
+    address: string;
+    secretBech32: string;
+}): void;
+/** Decrypt and return the bech32 `suiprivkey...` string. Throws on bad passphrase. */
+export declare function loadSecret(opts: {
+    path: string;
+    passphrase: string;
+}): {
+    address: string;
+    secretBech32: string;
+};
+export declare function keystoreExists(path: string): boolean;

package/dist/keystore.js

@@ -0,0 +1,71 @@
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv, } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const SCRYPT_N = 1 << 15; // 32768
+const SCRYPT_PARAMS = { N: SCRYPT_N, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+/** Default keystore path; override with AGENT_WALLET_PATH. */
+export function defaultPath() {
+    return process.env.AGENT_WALLET_PATH ?? join(homedir(), '.suisei', 'agent-wallet.json');
+}
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32, SCRYPT_PARAMS);
+}
+/** Encrypt a bech32 `suiprivkey...` string into a keystore file on disk. */
+export function saveSecret(opts) {
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = deriveKey(opts.passphrase, salt);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(opts.secretBech32, 'utf8')),
+        cipher.final(),
+    ]);
+    const authTag = cipher.getAuthTag();
+    const file = {
+        version: 1,
+        address: opts.address,
+        scheme: 'ed25519',
+        kdf: 'scrypt',
+        salt: salt.toString('hex'),
+        iv: iv.toString('hex'),
+        auth_tag: authTag.toString('hex'),
+        ciphertext: ciphertext.toString('hex'),
+        created_at: new Date().toISOString(),
+    };
+    mkdirSync(dirname(opts.path), { recursive: true });
+    writeFileSync(opts.path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(opts.path, 0o600);
+    }
+    catch {
+        // best-effort on platforms without POSIX perms
+    }
+}
+/** Decrypt and return the bech32 `suiprivkey...` string. Throws on bad passphrase. */
+export function loadSecret(opts) {
+    if (!existsSync(opts.path)) {
+        throw new Error(`No agent wallet at ${opts.path}. Run "agent-signer create" first.`);
+    }
+    const file = JSON.parse(readFileSync(opts.path, 'utf8'));
+    if (file.version !== 1)
+        throw new Error(`Unsupported keystore version ${file.version}.`);
+    const key = deriveKey(opts.passphrase, Buffer.from(file.salt, 'hex'));
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(file.iv, 'hex'));
+    decipher.setAuthTag(Buffer.from(file.auth_tag, 'hex'));
+    let secretBech32;
+    try {
+        secretBech32 = Buffer.concat([
+            decipher.update(Buffer.from(file.ciphertext, 'hex')),
+            decipher.final(),
+        ]).toString('utf8');
+    }
+    catch {
+        throw new Error('Decryption failed — wrong passphrase or corrupted keystore.');
+    }
+    return { address: file.address, secretBech32 };
+}
+export function keystoreExists(path) {
+    return existsSync(path);
+}
+//# sourceMappingURL=keystore.js.map

package/dist/keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.js","sourceRoot":"","sources":["../src/keystore.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@suisei-mcp/agent-signer",
+  "version": "0.1.0",
+  "description": "Local, non-custodial signer for a Tier-1 Sui agent wallet. Generates and encrypts an agent keypair on the user's machine and signs tx bytes from @suisei-mcp/mcp. The key never leaves the host and never enters an agent's context.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "agent-signer": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "sui",
+    "agent",
+    "wallet",
+    "signer",
+    "non-custodial",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mysten/sui": "^1.45.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3"
+  }
+}