@guveno/wallet-sdk 1.0.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/security.md

@@ -0,0 +1,119 @@
+# Security Considerations
+
+## Storage Model
+
+The SDK separates local state into:
+
+- `metadata.json`: non-sensitive `keys`, `wallets`, and `addresses`
+- `secrets.json`: encrypted key material only
+- `auth-session.json`: saved CLI bearer token plus API session metadata
+
+This separation reduces accidental exposure of secret material, but it is not a substitute for a hardware wallet, HSM, or dedicated secret manager.
+
+## Encryption Model
+
+New wallet creation and import flows always encrypt secret material before persistence.
+
+Current scheme:
+
+- KDF: `scrypt`
+- Cipher: `aes-256-gcm`
+- Protected value: mnemonic only
+
+The encryption password is provided in the SDK or CLI by the user. The backend does not encrypt on the user’s behalf.
+
+## Multi-Chain Model
+
+Each wallet group is bound to exactly one chain:
+
+- `ethereum`
+- `bitcoin`
+- `xrp`
+
+The same mnemonic can back multiple wallet groups across different chains, but each group derives addresses only for its own chain-specific path family.
+
+Internally, the SDK stores:
+
+- one local `key` per mnemonic fingerprint
+- one local `wallet` per chain-specific wallet group
+- one local `address` row per derived account
+
+## Server Persistence Contract
+
+When exporting a wallet for backend storage, the SDK sends:
+
+- `groupName`
+- `chain`
+- `keyFingerprint`
+- `metadataJson`
+- `secretsJson`
+- `addresses`
+
+`metadataJson` contains non-sensitive key, wallet, and address metadata.
+
+`secretsJson` is an encrypted blob generated by the SDK. The backend stores it as received and should not require plaintext mnemonic access for routine storage.
+
+On the backend, the encrypted blob belongs to a `key` record. The uploaded wallet structure and derived addresses are stored separately so the server can index addresses without decrypting the underlying seed material.
+
+## Persisted vs Not Persisted
+
+Persisted:
+
+- mnemonic fingerprint
+- encrypted mnemonic payload
+- wallet group metadata
+- chain identifier
+- derived addresses
+- labels
+- timestamps
+
+Not persisted:
+
+- standalone private keys
+- RPC or network state
+- plaintext mnemonic material on the server
+
+Private keys are derived on demand from the mnemonic rather than stored separately.
+
+## CLI Safety Tradeoffs
+
+Safer options:
+
+- `--mnemonic-file` instead of `--mnemonic`
+- `--password-env` instead of `--password`
+- interactive password prompts instead of inline password flags
+- no mnemonic output unless `--reveal-mnemonic` is explicitly requested
+
+Less safe options:
+
+- passing mnemonics or passwords directly on the command line
+- storing `auth-session.json` in insecure locations
+- exporting wallet JSON to insecure locations
+- reusing weak encryption passwords
+
+## Duplicate Mnemonic Handling
+
+If the same mnemonic is imported again for the same chain, the SDK:
+
+- finds the existing wallet group by mnemonic fingerprint and chain
+- reuses that group
+- derives the next account index from the same seed
+
+If the same mnemonic is imported for a different chain, the SDK creates a separate wallet group because the derivation path family is different.
+
+That second wallet group reuses the same local `key` record and encrypted secret material instead of storing a duplicate encrypted mnemonic blob.
+
+When those groups are uploaded to the backend for the same user, the shared mnemonic fingerprint lets the server reuse one `key` row while keeping separate `wallet` and `address` rows per chain.
+
+## Operational Limits
+
+This SDK is for local wallet management and encrypted wallet-record transport.
+
+It is not intended to replace:
+
+- a hardware wallet
+- an HSM
+- an enterprise secret manager
+- multi-party custody controls
+
+The file store uses atomic replacement plus a lock file, but large-scale concurrent writers are outside the intended operating model.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@guveno/wallet-sdk",
+  "version": "1.0.0",
+  "description": "Add secure crypto custody to your app in minutes — create and manage multi-chain wallets, automate withdrawals, and receive real-time webhooks for Bitcoin, Ethereum, XRP, and Polkadot. Built for exchanges, fintechs, and platforms.",
+  "author": "Guveno LLC",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "guveno",
+    "wallet",
+    "sdk",
+    "hd-wallet",
+    "bip39",
+    "ethereum",
+    "bitcoin",
+    "xrp",
+    "polkadot",
+    "crypto",
+    "custody"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hollaex/guveno-sdk.git"
+  },
+  "homepage": "https://github.com/hollaex/guveno-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/hollaex/guveno-sdk/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist coverage .vitest-temp",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@polkadot/keyring": "^13.5.1",
+    "@polkadot/util": "^13.5.1",
+    "@polkadot/util-crypto": "^13.5.1",
+    "@scure/bip39": "^2.0.1",
+    "@substrate/txwrapper-polkadot": "^7.5.3",
+    "bip32": "^5.0.0",
+    "bitcoinjs-lib": "^7.0.0",
+    "ethers": "^6.16.0",
+    "tiny-secp256k1": "^2.2.4",
+    "xrpl": "^4.6.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  }
+}