@deadvault/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DEADBOX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @deadvault/sdk
+
+Decentralized credential store SDK for AI agents, servers & scripts. Read, write, and manage encrypted secrets stored on-chain via the [DeadVault](https://vault.dead.box) smart contract.
+
+Part of the [DEADBOX](https://dead.box) ecosystem.
+
+## Features
+
+- **Read & write** encrypted vaults on-chain (Base, Ethereum, Arbitrum, Optimism)
+- **AES-256-GCM** encryption with PBKDF2 key derivation (600k iterations)
+- **TOTP generation** — RFC 6238 codes from vault entries
+- **Zero dependencies** beyond `viem` as a peer dependency
+- **Isomorphic** — works in Node.js 18+, Deno, Bun, Cloudflare Workers
+- **ESM + CJS** dual output with full TypeScript types
+
+## Install
+
+```bash
+npm install @deadvault/sdk viem
+```
+
+## Quick Start
+
+```ts
+import { DeadVault } from "@deadvault/sdk";
+
+const vault = new DeadVault({ chain: "base" });
+
+// Read & decrypt
+const data = await vault.read({
+  address: "0xYourAddress",
+  password: "master-password",
+});
+
+// Find a specific entry
+const key = vault.findEntry(data, { label: "OpenAI" });
+console.log(key?.secret); // sk-...
+```
+
+## Constructor
+
+```ts
+const vault = new DeadVault(config);
+```
+
+| Option    | Type     | Default  | Description                                          |
+|-----------|----------|----------|------------------------------------------------------|
+| `chain`   | `string` | `"base"` | Chain name: `base`, `ethereum`, `arbitrum`, `optimism` |
+| `chainId` | `number` | `8453`   | Chain ID (overrides `chain`)                         |
+| `rpcUrl`  | `string` | —        | Custom RPC URL                                       |
+
+## Reading Secrets
+
+```ts
+const data = await vault.read({
+  address: "0x...",
+  password: "secret",
+  walletSignature: "0x...", // required for v2 vaults
+});
+```
+
+Returns `VaultData` with an `entries` array of `VaultEntry` objects.
+
+## Finding Entries
+
+```ts
+// By label (case-insensitive substring)
+vault.findEntry(data, { label: "OpenAI" });
+
+// By category
+vault.findEntry(data, { category: "API Keys" });
+
+// By URL
+vault.findEntry(data, { url: "github.com" });
+
+// Custom predicate
+vault.findEntry(data, (e) => e.secret.startsWith("sk-"));
+
+// Find all matching
+vault.findEntries(data, { type: "totp" });
+```
+
+## Writing Secrets
+
+```ts
+// Sign the KDF message (needed for v2 encryption)
+const sig = await vault.signKdfMessage("0xPrivateKey");
+
+// Read existing vault
+const data = await vault.read({
+  address: "0xYourAddress",
+  password: "secret",
+  walletSignature: sig,
+});
+
+// Add an entry
+data.entries.push({
+  id: crypto.randomUUID(),
+  label: "New API Key",
+  secret: "sk-abc123...",
+  category: "API Keys",
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+});
+
+// Write back on-chain
+const result = await vault.write({
+  data,
+  password: "secret",
+  privateKey: "0xPrivateKey",
+  walletSignature: sig,
+});
+
+console.log("TX:", result.hash);
+console.log("Block:", result.blockNumber);
+```
+
+## TOTP Generation
+
+```ts
+const totpEntries = vault.findEntries(data, { type: "totp" });
+
+for (const entry of totpEntries) {
+  const code = await vault.generateTOTP(entry);
+  const remaining = vault.getTOTPTimeRemaining();
+  console.log(`${entry.label}: ${code} (${remaining}s remaining)`);
+}
+```
+
+## Utilities
+
+```ts
+// Check write fee
+const fee = await vault.getWriteFee();
+console.log(fee.wei);  // 23255813953488n
+console.log(fee.eth);  // "0.00002326"
+
+// Check unlimited pass
+const hasPass = await vault.hasPass("0x...");
+
+// Check if vault exists
+const exists = await vault.hasVault("0x...");
+```
+
+## Supported Chains
+
+| Chain        | ID      | Contract                                       |
+|--------------|---------|-------------------------------------------------|
+| Base         | `8453`  | `0xF74C1131E11aF8dc10F25bAa977dD0B86d4A5C37`   |
+| Ethereum     | `1`     | `0xF74C1131E11aF8dc10F25bAa977dD0B86d4A5C37`   |
+| Arbitrum One | `42161` | `0x33939ede1A19A64EE755F1B5B3284A8E71F68484`   |
+| Optimism     | `10`    | `0x33939ede1A19A64EE755F1B5B3284A8E71F68484`   |
+
+## Encryption
+
+All vault data is encrypted client-side before being stored on-chain.
+
+- **v1**: `PBKDF2(password, salt, 600k, SHA-256)` → AES-256-GCM
+- **v2**: `PBKDF2(password + walletSignature, salt, 600k, SHA-256)` → AES-256-GCM
+
+The SDK always writes v2 and can read both formats.
+
+## Low-Level Exports
+
+For advanced use cases, the SDK also exports crypto and chain primitives:
+
+```ts
+import {
+  encrypt,
+  encryptV2,
+  decrypt,
+  detectVersionFromHex,
+  KDF_SIGN_MESSAGE,
+  generateTOTP,
+  getTOTPTimeRemaining,
+  isValidTOTPSecret,
+  base32Decode,
+  VAULT_ADDRESSES,
+  CHAIN_NAME_TO_ID,
+} from "@deadvault/sdk";
+```
+
+## Security
+
+- Encryption keys are derived locally — private keys and passwords never leave the client
+- All on-chain data is encrypted ciphertext — the contract stores opaque blobs
+- PBKDF2 with 600,000 iterations for brute-force resistance
+- v2 encryption binds the key to the wallet via a signature, preventing password-only attacks
+
+## Requirements
+
+- Node.js ≥ 18 (Web Crypto API)
+- `viem` ≥ 2.0.0 as peer dependency
+
+## License
+
+MIT — see [LICENSE](./LICENSE)