8000 feat(store): open and write keystore files by aeitwoen · Pull Request #182 · agntn/keys · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## OVERVIEW

TypeScript library providing a unified interface for key generation, address derivation, wallet creation, and message signing across 18 blockchains (Bitcoin, Bitcoin Cash, Bitcoin Gold, Bitcoin SV, Litecoin, Dash, Decred, Dogecoin, Zcash, eCash, Ethereum, Base, Solana, Stellar, Aptos, Cardano, SUI, TRON). Curves, base encodings and HD derivation come from @noble/@scure, every hash from @agntn/hashes. Nothing in the package is audited or meant for production, real funds or sensitive data.
TypeScript library providing a unified interface for key generation, address derivation, wallet creation, and message signing across 18 blockchains (Bitcoin, Bitcoin Cash, Bitcoin Gold, Bitcoin SV, Litecoin, Dash, Decred, Dogecoin, Zcash, eCash, Ethereum, Base, Solana, Stellar, Aptos, Cardano, SUI, TRON). Curves, base encodings and HD derivation come from @noble/@scure, every hash from @agntn/hashes, AES from @agntn/ciphers. Nothing in the package is audited or meant for production, real funds or sensitive data.

## STRUCTURE

Expand Down Expand Up @@ -44,6 +44,7 @@ keys/
| Core signature | `src/utils/secp256k1/compact-signature.ts` | Base64 `header | | r | | s`for the Bitcoin family and Decred;`recoverMessageSigner` reads it |
| Change public API | `src/index.ts` | Re-exports only, never add logic here |
| Change agent tools | `src/tools.ts`, `src/tool-schemas.ts`, `src/tool-operations.ts` | One definition per tool; a new tool also gets its file in `docs/server/mcp/tools/` |
| Keystore files | `src/utils/store/` | Web3 Secret Storage v3: scrypt/PBKDF2, AES-128-CTR from `@agntn/ciphers/aes` |
| Add BIP/derivation | `src/utils/bip32/`, `bip39/`, `bip44/`, `slip10/` | Subdirs with index.ts |
| Mnemonic to wallet | `src/blockchain.ts` → `deriveHDWallet` + `src/utils/hd.ts` | Bitcoin family infers the address type; Sui overrides it, Cardano throws (CIP-1852) |
| Xpub to address | `src/utils/extended-key.ts` → `deriveXpubWallet` on the base class | SLIP-0132 prefixes pick the type on the Bitcoin family; normal levels only, no xprv |
Expand Down Expand Up @@ -98,12 +99,12 @@ pnpm test:mcp # build and exercise every MCP tool over stdio
## NOTES

- **CI runs**: lint -> type check -> build -> vp test with coverage (Node 26, pnpm through `setup-vp`). Autofix workflow commits lint fixes on PRs.
- **Package exports** expose `"."`, `"./mcp"`, `"./blockchains/*"`, and the HD derivation subpaths `"./bip32"`, `"./bip39"`, `"./bip44"` and `"./slip10"`, plus `"./bip38"` for encrypted key headers, `"./brainwallet"` for salted brainwallet keys, `"./electrum"` for Electrum seeds, `"./secp256k1"` for SEC1 public key conversion and `"./wif"` for wallet import format; other utils remain internal.
- **Package exports** expose `"."`, `"./mcp"`, `"./blockchains/*"`, and the HD derivation subpaths `"./bip32"`, `"./bip39"`, `"./bip44"` and `"./slip10"`, plus `"./bip38"` for encrypted key headers, `"./store"` for Web3 Secret Storage keystores, `"./brainwallet"` for salted brainwallet keys, `"./electrum"` for Electrum seeds, `"./secp256k1"` for SEC1 public key conversion and `"./wif"` for wallet impor 8000 t format; other utils remain internal.
- **Agent tools** - `src/tools.ts` declares each tool once with `defineTool` from `@agntn/tools`, and `createMcpServer`, `registerPiTools` and `registerOmpTools` serve the same list, validating every call against the schema before the executor runs. Schemas take `Type` from `@agntn/tools`, never a bare `typebox` import, which OMP rewrites to its omptype facade. OMP gets the JSON Schema through `pi.typebox.Type.Unsafe` and drops a blank optional string the schema refuses before the call. The executors load on the first call, so registering the tools or starting `keys mcp` loads no chain. `callSummaries` in the same file gives the Pi and OMP status lines their summary.
- **Shipped extensions** - `files` lists both extensions, and they load `dist/tools.mjs` from the package, `src/tools.ts` in a checkout. `test/public-exports.test.ts` runs a tool from each extension with only the shipped files.
- **OMP extension** - `packages/omp/extensions/keys.ts` keeps both dynamic imports of the tools literal and takes `Text` from the OMP package root. OMP does not expand globs in the manifest, so `omp.extensions` names the file. `test/omp-extension.test.ts` holds its registrations to the definitions Pi gets.
- **MCP transport** runs through `keys mcp`. Inside a checkout, `dist/cli.mjs` loads the MCP command from `src/`, like the Pi and OMP extensions, so a local server only needs a restart after a change. The npm package has no `src/commands` and runs the bundle. A copy under `node_modules` keeps the bundle too, because Node does not strip types there. The source needs production dependencies only. `KEYS_DIST=1` forces the bundle in a checkout, as `test/cli.test.ts` and `test/eval-mcp.mjs` do. Changes to `src/cli.ts` itself still need `pnpm build`. stdout is reserved for JSON-RPC, and `createMcpServer()` remains importable for hosts with their own transport. `toolListings` and `callTool()` from the same module feed the remote server at `keys.agntn.dev/mcp` (see `docs/AGENTS.md`).
- **utils/ has mixed structure** - plain `.ts` files (address, encoding, crypto-hash, ed25519, ed25519-chains, evm, signing) and subdirectories with `index.ts` (bip32/, bip38/, bip39/, bip44/, electrum/, secp256k1/, slip10/, wif/).
- **utils/ has mixed structure** - plain `.ts` files (address, encoding, crypto-hash, ed25519, ed25519-chains, evm, signing) and subdirectories with `index.ts` (bip32/, bip38/, bip39/, bip44/, electrum/, secp256k1/, slip10/, store/, wif/).
- **`__cardano/notes.md`** - research notes for Cardano implementation, not code. The actual implementation is `cardano.ts`.
- **Shared secp256k1 fixture** - `secp256k1TestVectors.publicKeyCompressed` is the key of `privateKey`, shared by the signing round trips and the address tests. The Bitcoin address generators decode the SEC1 point before hashing, so an invented key fails them.
- **Not audited** - the README and the first guide page open with a `Not audited` caution. It names no dependency, so it stays true when @noble/@scure give way to `@agntn/*`.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,8 @@ Without the flag `deriveHDWallet` throws. With it you get the wallet and a warni

Brainwallets are a puzzle favorite too, and the salted kind hides a trap. brainwallet.io runs scrypt, then SHA-256 over the hex of the result, not its bytes. Miss that and you get a valid key to the wrong address. `derive` from `@agntn/keys/brainwallet` takes the whole recipe: KDF, costs, salt and what SHA-256 reads. Agents get `keys_brainwallet_derive`. It answers with the public key, the address and a match against your target. Never the private key. Recipes: [Wallets](https://keys.agntn.dev/guide/wallets).

Got an old `UTC--...` file from MyEtherWallet or geth? That's a keystore, and `@agntn/keys/store` opens it. `decrypt(file, password)` gives the key back, `encrypt` writes a new file, `inspect` reads the KDF without a password. Agents get `keys_store_decrypt`. It says whether the password fits and gives the address, never the key. More: [Keys](https://keys.agntn.dev/guide/keys).

And a signed message is a clue. Somebody proves they hold an address with `signmessage`? That base64 gives away the public key behind it. `btc.recoverMessageSigner(message, signature)` reads it back, `keys_message_recover` does the same for agents. Any well formed signature recovers some key for any message, though. So check the address match, not just that a key came out.

## ⛓️ Chains
Expand Down
1 change: 1 addition & 0 deletions build.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ export default defineBuildConfig({
"./src/utils/electrum/index.ts",
"./src/utils/secp256k1/index.ts",
"./src/utils/slip10/index.ts",
"./src/utils/store/index.ts",
"./src/utils/wif/index.ts",
...blockchainInputs,
],
Expand Down
2 changes: 1 addition & 1 deletion docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Three resolution traps, all because the repo root is its own pnpm workspace:

`@agntn/keys/mcp` is a second alias, for `../src/mcp.ts`. A file in `server/mcp/tools/` names one tool and nothing else: `keysMcpTool()` takes the name, prose and annotations from `toolListings` and runs `callTool()` from there, so a tool changed in `src/` changes here without an edit. A new tool in `src/tools.ts` needs one more file here, and `test/docs-mcp.test.ts` fails until it has one. `@nuxtjs/mcp-toolkit` wants Zod, so its schema is `z.fromJSONSchema()` over the TypeBox one, passed as the whole object so an unknown key is refused instead of stripped. A schema error reads in Zod's words. Every other answer is the text `keys mcp` gives.

On the `cloudflare_module` preset the toolkit hands its server to `createMcpHandler` from `agents`, which tells an SDK v1 server apart with `instanceof`. pnpm installs one copy of `@modelcontextprotocol/sdk` per `zod` peer it resolves, so the toolkit and `agents` can each get their own and every request fails with "createMcpHandler received an unsupported server". `nitro.alias` points every import of the SDK at the copy in `docs/node_modules`. Keep it until both resolve the same one. `@agntn/tools` and `@modelcontextprotocol/server` are dependencies here for `src/mcp.ts`, pinned to the root's versions and deduped like the others; `@modelcontextprotocol/sdk` stays for the toolkit and `agents`. They run on the worker only, so they stay out of `optimizeDeps`. The library writes bigint literals, so `nitro.esbuild` targets es2022.
On the `cloudflare_module` preset the toolkit hands its server to `createMcpHandler` from `agents`, which tells an SDK v1 server apart with `instanceof`. pnpm installs one copy of `@modelcontextprotocol/sdk` per `zod` peer it resolves, so the toolkit and `agents` can each get their own and every request fails with "createMcpHandler received an unsupported server". `nitro.alias` points every import of the SDK at the copy in `docs/node_modules`. Keep it until both resolve the same one. `@agntn/ciphers`, `@agntn/tools` and `@modelcontextprotocol/server` are dependencies here for `src/mcp.ts`, pinned to the root's versions and deduped like the others; `@modelcontextprotocol/sdk` stays for the toolkit and `agents`. They run on the worker only, so they stay out of `optimizeDeps`. The library writes bigint literals, so `nitro.esbuild` targets es2022.

`/mcp` is the one place where key material reaches the server, because an agent sends it there on purpose. The worker must not log or keep it: no `evlog` module, no `observability` block in `wrangler.jsonc`, no `console` call with tool arguments. The page at `content/1.guide/1.index.md#remote-mcp` says so to users.

Expand Down
44 changes: 44 additions & 0 deletions docs/content/1.guide/2.keys.md
10000
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,50 @@ That's a test vector from the BIP, lot 263183 and sequence 1 like the spec says.

Nothing gets decrypted here and no passphrase gets guessed. BIP38 runs the passphrase through scrypt so that guessing hurts, and it does.

## Keystore files

Remember the `UTC--2017-...` file MyEtherWallet made you download? That's a keystore. Geth, ethers and MyEtherWallet all write the same JSON, Web3 Secret Storage version 3. The password goes through scrypt or PBKDF2. AES-128-CTR locks the key. A Keccak MAC tells a wrong password from a right one. And it's not dead. Geth and Foundry still write it, MetaMask still imports it.

`@agntn/keys/store` opens one:

```js
import { decrypt, inspect } from "@agntn/keys/store";
import Ethereum from "@agntn/keys/blockchains/ethereum";

const file = {
version: 3,
id: "fecfc4ce-e956-48fd-953b-30f8b52ed66c",
crypto: {
cipher: "aes-128-ctr",
cipherparams: { iv: "e0c41130a323adc1446fc82f724bca2f" },
ciphertext: "9517cd5bdbe69076f9bf5057248c6c050141e970efa36ce53692d5d59a3984",
kdf: "scrypt",
kdfparams: {
dklen: 32,
n: 2,
r: 8,
p: 1,
salt: "711f816911c92d649fb4c84b047915679933555030b3552c1212609b38208c63",
},
mac: "d5e116151c6aa71470e67a7d42c9620c75c4d23229847dcc127794f0732b0db5",
},
};
inspect(file).kdf; // 'scrypt'
const key = decrypt(file, "foo");
const wallet = new Ethereum().deriveWallet(key.toHex());
wallet.address;
```

That's `0xd1E64E5480bFaf733Ba7D48712DEcb8227797a4e`. The file comes from geth's test data. Look at the ciphertext: 31 bytes, not 32. Early geth dropped leading zero bytes of the key. `decrypt` pads them back, like geth does.

A wrong password throws `KeystorePasswordError`. A key that doesn't match the stored `address` throws too. `Crypto` with a capital C, the way ethers writes it, reads fine. `inspect` gives the KDF, its costs and the stored address without any password.

`encrypt(key, password)` goes the other way. By default it uses geth's cost, scrypt with `n: 262144`, `r: 8` and `p: 1`. That's about a second. Pass `kdf: { kdf: "pbkdf2", c: 262144 }` for PBKDF2. The password goes in as UTF-8, exactly as typed, like geth. ethers runs NFKC over it first. Plain text is the same either way, a ligature is not.

Version 1 and 2 files and the presale wallet don't open here. An old scrypt file with `r: 1` and `n` of 65536 or more doesn't either. `@agntn/hashes` keeps scrypt inside RFC 7914 and refuses it.

MCP and Pi call it `keys_store_decrypt`. You get the KDF, the stored address and whether the password fits. If it does, the public key and the address. Never the private key. A file that wants more scrypt memory than geth's standard gets refused before the KDF runs. The password is still in the transcript, so keep real ones out.

## The shape you get back

```typescript
Expand Down
1 change: 1 addition & 0 deletions docs/nuxt.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ const librarySource = resolve(import.meta.dirname, "../src");

/** Runtime deps under src/index.ts and src/mcp.ts, installed here so they resolve from docs/node_modules. */
const libraryDependencies = [
"@agntn/ciphers",
"@agntn/hashes",
"@agntn/tools",
"@modelcontextprotocol/server",
Expand Down
1 change: 1 addition & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"deploy": "pnpm build && wrangler deploy"
},
"dependencies": {
"@agntn/ciphers": "0.5.0",
"@agntn/hashes": "0.4.0",
"@agntn/tools": "0.0.0",
"@modelcontextprotocol/sdk": "1.30.1",
Expand Down
44 changes: 44 additions & 0 deletions docs/pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

103AD
1 change: 1 addition & 0 deletions docs/server/mcp/tools/keys-store-decrypt.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export default keysMcpTool("keys_store_decrypt");
5 changes: 5 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@
"types": "./dist/utils/secp256k1/index.d.mts",
"default": "./dist/utils/secp256k1/index.mjs"
},
"./store": {
"types": "./dist/utils/store/index.d.mts",
"default": "./dist/utils/store/index.mjs"
},
"./slip10": {
"types": "./dist/utils/slip10/index.d.mts",
"default": "./dist/utils/slip10/index.mjs"
Expand Down Expand Up @@ -117,6 +121,7 @@
"docs:build": "pnpm --dir docs build"
},
"dependencies": {
"@agntn/ciphers": "0.5.0",
"@agntn/hashes": "0.4.0",
"@agntn/tools": "0.0.0",
"@modelcontextprotocol/server": "2.2.0",
Expand Down
Loading
Loading
0