@guveno/wallet-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guveno LLC
+
+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,211 @@
+# Guveno Wallet SDK
+
+Add secure crypto custody to your platform — create and manage multi-chain wallets, automate withdrawals, and receive real-time webhooks for Bitcoin, Ethereum, XRP, Polkadot, and more. Built for exchanges, fintechs, and platforms.
+
+A typed TypeScript SDK with client-side key encryption, HD wallet groups, and a fully offline signing path, so the server never holds plaintext key material.
+
+> Prefer the terminal? The [`@guveno/cli`](https://www.npmjs.com/package/@guveno/cli) package wraps this SDK with the same features.
+
+## Install
+
+```bash
+npm install @guveno/wallet-sdk
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+Create a wallet, and you get back a derived address you can fund right away:
+
+```ts
+import { WalletManager } from '@guveno/wallet-sdk';
+
+const manager = new WalletManager();
+
+const created = await manager.createWalletGroup({
+  name: 'treasury-btc',
+  chain: 'bitcoin',
+  words: 24, // 12 or 24-word recovery phrase
+  encryptionPassword: process.env.WALLET_ENCRYPTION_PASSWORD!
+});
+
+console.log(created.firstAccount.address);        // bc1...
+console.log(created.firstAccount.derivationPath); // m/84'/0'/0'/0/0
+```
+
+A **wallet group** is one recovery phrase (seed) on one chain, plus the addresses you derive from it. Derive as many addresses as you need — each gets the next index.
+
+> **What is `WALLET_ENCRYPTION_PASSWORD`?**
+> A passphrase *you* choose. The SDK runs it through scrypt to derive an AES-256-GCM key that encrypts your recovery phrase at rest, before anything touches disk. You must supply the same password later to derive new addresses, export, or decrypt — and it is **never sent to the server and never recoverable if lost**, so store it safely.
+
+## Working with wallets
+
+### Import an existing recovery phrase
+
+```ts
+const imported = await manager.importWalletGroup({
+  name: 'restored-xrp',
+  chain: 'xrp',
+  mnemonic: 'test test test test test test test test test test test junk',
+  encryptionPassword: process.env.WALLET_ENCRYPTION_PASSWORD!
+});
+
+console.log(imported.account.address); // r...
+```
+
+Re-importing the same phrase for the same chain reuses the group and derives the next address. Importing it for a *different* chain creates a new group that reuses the same underlying key — so one seed can back wallets across every chain.
+
+### Derive another address
+
+```ts
+const next = await manager.deriveAddress({
+  group: 'restored-xrp',
+  label: 'ops',
+  encryptionPassword: process.env.WALLET_ENCRYPTION_PASSWORD!
+});
+
+console.log(next.index, next.address); // 1  r...
+```
+
+### List, rename, and label
+
+```ts
+const groups = await manager.listWalletGroups();
+const accounts = await manager.listDerivedAccounts('treasury-btc');
+
+await manager.renameWalletGroup('treasury-btc', 'treasury-btc-main');
+await manager.labelAccount({ group: 'treasury-btc-main', index: 1, label: 'fees' });
+```
+
+For local backup/migration you can also export wallet metadata and records, and decrypt stored secrets with your password — see [examples/](#examples).
+
+## Upload to Guveno (server API)
+
+`GuvenoApiClient` talks to the Guveno API for auth, wallet records, and webhooks. The mnemonic is sealed to your account's encryption key before it ever leaves your machine.
+
+```ts
+import { GuvenoApiClient } from '@guveno/wallet-sdk';
+
+const client = new GuvenoApiClient({ baseUrl: 'https://api.guveno.com/v1' });
+
+const auth = await client.login({
+  email: 'user@example.com',
+  password: process.env.ACCOUNT_PASSWORD!
+});
+client.setAccessToken(auth.accessToken);
+
+const user = await client.getCurrentUser();
+if (!user.encryptionKey) throw new Error('Complete onboarding before uploading wallets.');
+
+const payload = await manager.exportWalletForApi('treasury-btc-main', {
+  recipientPublicKey: user.encryptionKey.publicKey,
+  encryptionPassword: process.env.WALLET_ENCRYPTION_PASSWORD!
+});
+const wallet = await client.createWalletRecord(payload);
+
+console.log(wallet.name);
+```
+
+The sealed secret is stored as `keyAccess`; wallet and address rows stay searchable without ever exposing plaintext secrets.
+
+### Webhooks
+
+Subscribe to deposit/withdrawal events. `createWebhook` returns the `signingSecret` **once** — store it to verify the `x-guveno-signature` header on incoming requests.
+
+```ts
+const webhook = await client.createWebhook({
+  type: 'api',
+  config: { url: 'https://example.com/webhooks/guveno' },
+  events: ['deposit.confirmed', 'withdrawal.confirmed'] // or ['*'] for all
+});
+console.log(webhook.signingSecret); // shown only here
+
+const deliveries = await client.listWebhookDeliveries(webhook.id, { limit: 50 });
+```
+
+All event types are exported as `WEBHOOK_EVENT_TYPES`. Creating/deleting webhooks requires an `owner` or `admin` role.
+
+## Automated withdrawals (hot wallet)
+
+`HotWallet` runs the full `prepare → sign → broadcast` loop for headless callers like an exchange hot wallet — no per-withdrawal human step. The server never holds key material: the mnemonic is resolved from a `KeyProvider`, used **in process** to sign, then dropped.
+
+Authenticate the client with a `gv_live_...` API key whose role is in `WITHDRAWAL_ROLES` (`owner`, `admin`, `manager`, or `signer`). API keys can't read encrypted wallet secrets, which is why the hot wallet sources the mnemonic itself.
+
+```ts
+import { GuvenoApiClient, HotWallet, FileKeyProvider } from '@guveno/wallet-sdk';
+
+const api = new GuvenoApiClient({ baseUrl: 'https://api.guveno.com/v1', apiKey: process.env.GUVENO_API_KEY });
+
+// keys.json: { "<keyFingerprint>": "<bip39 mnemonic>", ... }
+const hot = new HotWallet({ api, keys: new FileKeyProvider('/run/secrets/keys.json') });
+
+const withdrawal = await hot.withdraw({
+  addressId: 100,
+  assetId: 1,
+  toAddress: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+  amount: '1.5'
+});
+console.log(withdrawal.status); // 'broadcast' — confirmation arrives via webhooks
+```
+
+Don't want a plaintext key file? Use `KmsKeyProvider` with a `decrypt` callback backed by AWS KMS, GCP KMS, Vault, or an HSM — the plaintext mnemonic exists only transiently in memory while a withdrawal is signed.
+
+```ts
+import { HotWallet, KmsKeyProvider } from '@guveno/wallet-sdk';
+
+const keys = new KmsKeyProvider({
+  entries: { '<keyFingerprint>': '<base64 KMS ciphertext>' },
+  decrypt: async (ciphertext) => {
+    const out = await kms.decrypt({ CiphertextBlob: Buffer.from(ciphertext, 'base64') });
+    return Buffer.from(out.Plaintext).toString('utf8'); // the mnemonic
+  }
+});
+```
+
+Good to know:
+
+- **Per-address serialization** — withdrawals on the same address are queued so concurrent sends never collide on a nonce; different addresses run in parallel.
+- **Idempotency** — an `idempotencyKey` is auto-generated per call; pass your own to make a retried `withdraw(...)` replay-safe.
+- **All custodied chains are signable** (`SIGNABLE_CHAINS`); Polkadot extrinsics are built fully offline from metadata the server includes in the prepared payload.
+
+## CLI
+
+The `guveno` command-line tool lives in [`@guveno/cli`](https://www.npmjs.com/package/@guveno/cli) — local wallet management, API auth, wallet upload, and webhooks from your terminal.
+
+## Supported chains
+
+| Chain | Address style |
+| --- | --- |
+| Bitcoin | native SegWit `bc1...` |
+| Ethereum | `0x...` |
+| XRP | classic `r...` |
+| Polkadot | SS58 (`1...` mainnet) |
+
+**We're adding new chains regularly** — these four are live today. All use standard HD derivation, so a recovery phrase restores the same accounts in any compatible wallet (Polkadot uses sr25519 substrate junctions, matching Polkadot-JS / Talisman).
+
+## Where your keys are stored
+
+By default the SDK keeps wallet data under `~/.guveno` (override with `GUVENO_WALLET_HOME`):
+
+- `metadata.json` — non-sensitive keys, wallets, and addresses
+- `secrets.json` — your recovery phrase, encrypted with your `WALLET_ENCRYPTION_PASSWORD`
+- `auth-session.json` — saved API session for the CLI
+
+This local store is for single-user workflows, not shared or multi-process custody.
+
+## Security
+
+- The SDK never logs recovery phrases, decrypted secrets, or private keys.
+- `secrets.json` is encrypted client-side with scrypt + AES-256-GCM before it hits disk.
+- Server uploads seal the mnemonic to your account's X25519 public key before sending.
+- Identical recovery phrases for the same company reuse one key record server-side.
+
+More detail: [docs/security.md](./docs/security.md)
+
+## Examples
+
+- [examples/create-wallet-group.ts](./examples/create-wallet-group.ts)
+- [examples/import-and-derive.ts](./examples/import-and-derive.ts)
+- [examples/export-wallet-record.ts](./examples/export-wallet-record.ts)
+- [examples/server-auth-and-upload.ts](./examples/server-auth-and-upload.ts)

package/dist/api/client.d.ts

@@ -0,0 +1,48 @@
+import type { ApiAuthResponse, ApiClientOptions, ApiEmailPasswordInput, ApiPageInfo, ApiSignupResponse, ApiUser, ApiVerifyEmailInput, ApiWalletAddress, ApiWalletDetail, ApiWalletKeySecret, ApiWalletSummary, ApiWebhook, ApiWebhookDelivery, ApiWebhookWithSecret, ApiWithdrawal, BroadcastWithdrawalInput, CreateApiWalletInput, CreateApiWebhookInput, ListApiAddressOptions, ListApiWalletOptions, ListApiWebhookDeliveryOptions, ListApiWithdrawalOptions, PrepareWithdrawalInput, PrepareWithdrawalResult, UpdateApiWalletInput } from './types.js';
+export declare class GuvenoApiClient {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private accessToken;
+    constructor(options?: ApiClientOptions);
+    setAccessToken(accessToken: string | undefined): void;
+    /** Authenticate with a `gv_live_...` API key. Sent as the bearer token, like {@link setAccessToken}. */
+    setApiKey(apiKey: string | undefined): void;
+    /**
+     * Registers an account and triggers a 6-digit verification-code email. No
+     * session is issued — call {@link verifyEmail} with the code to obtain the
+     * access token.
+     */
+    signup(input: ApiEmailPasswordInput): Promise<ApiSignupResponse>;
+    /** Confirms the signup verification code and returns the session token. */
+    verifyEmail(input: ApiVerifyEmailInput): Promise<ApiAuthResponse>;
+    /** Requests a fresh signup verification code for the given email. */
+    resendVerificationCode(email: string): Promise<{
+        email: string;
+    }>;
+    login(input: ApiEmailPasswordInput): Promise<ApiAuthResponse>;
+    getCurrentUser(): Promise<ApiUser>;
+    createWalletRecord(input: CreateApiWalletInput): Promise<ApiWalletDetail>;
+    listWalletRecords(options?: ListApiWalletOptions): Promise<ApiWalletSummary[]>;
+    listWalletRecordPage(options?: ListApiWalletOptions): Promise<{
+        items: ApiWalletSummary[];
+        pageInfo: ApiPageInfo;
+    }>;
+    getWalletRecord(walletId: string | number): Promise<ApiWalletDetail>;
+    getWalletKeySecret(walletId: string | number): Promise<ApiWalletKeySecret>;
+    listWalletAddresses(walletId: string | number, options?: ListApiAddressOptions): Promise<{
+        items: ApiWalletAddress[];
+        pageInfo: ApiPageInfo;
+    }>;
+    updateWalletRecord(walletId: string | number, input: UpdateApiWalletInput): Promise<ApiWalletDetail>;
+    deleteWalletRecord(walletId: string | number): Promise<void>;
+    listWebhooks(): Promise<ApiWebhook[]>;
+    createWebhook(input: CreateApiWebhookInput): Promise<ApiWebhookWithSecret>;
+    listWebhookDeliveries(webhookId: string | number, options?: ListApiWebhookDeliveryOptions): Promise<ApiWebhookDelivery[]>;
+    deleteWebhook(webhookId: string | number): Promise<void>;
+    prepareWithdrawal(input: PrepareWithdrawalInput): Promise<PrepareWithdrawalResult>;
+    broadcastWithdrawal(input: BroadcastWithdrawalInput): Promise<ApiWithdrawal>;
+    getWithdrawal(withdrawalId: string | number): Promise<ApiWithdrawal>;
+    listWithdrawals(options?: ListApiWithdrawalOptions): Promise<ApiWithdrawal[]>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

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