@volr/sdk-core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,238 @@
+# @volr/sdk-core
+
+Core cryptography, wallet providers, and EVM utilities for Volr SDK.
+
+## Installation
+
+```bash
+npm install @volr/sdk-core
+# or
+yarn add @volr/sdk-core
+```
+
+## Features
+
+- **EVM Cryptography**: secp256k1 and P-256 (WebAuthn) signing
+- **Passkey Providers**: WebAuthn-based wallet providers
+- **Master Key Encryption**: AES-256-GCM encryption with HKDF key derivation
+- **EIP-7702 Support**: Authorization tuple signing
+- **Session Keys**: EIP-712 session authentication
+- **Type-Safe**: Full TypeScript support with strict types
+
+## Core Concepts
+
+### Wallet Providers
+
+Wallet providers implement the `WalletProviderPort` interface for signing transactions:
+
+```typescript
+import { createPasskeyProvider } from '@volr/sdk-core';
+
+// Create a passkey-based provider
+const provider = createPasskeyProvider(adapter, {
+  prfInput: { origin, projectId, credentialId },
+  encryptedBlob: { cipher, nonce },
+  aad: new TextEncoder().encode('volr/master-seed/v1|userId|passkey|v1'),
+});
+
+// Get EVM address
+const address = await provider.getAddress();
+
+// Sign message
+const signature = await provider.signMessage(messageHash);
+```
+
+### Signers
+
+Signers are lightweight interfaces for signing operations:
+
+```typescript
+import { createSecp256k1Signer } from '@volr/sdk-core';
+
+// Create signer from private key
+const signer = createSecp256k1Signer(privateKeyBytes);
+
+// Sign message
+const signature = await signer.signMessage(messageHash);
+
+// Get address
+const address = await signer.getAddress();
+```
+
+### EIP-7702 Authorization
+
+Sign authorization tuples for EIP-7702 transactions:
+
+```typescript
+import { signAuthorization } from '@volr/sdk-core';
+
+const authTuple = await signAuthorization({
+  signer,
+  chainId: 8453,
+  address: invokerAddress,
+  nonce: 0n,
+});
+```
+
+### Session Signing (EIP-712)
+
+Sign session authentication for sponsored transactions:
+
+```typescript
+import { signSession } from '@volr/sdk-core';
+
+const { sessionSig } = await signSession({
+  signer,
+  from: userAddress,
+  auth: {
+    chainId: 8453,
+    sessionKey: userAddress,
+    expiresAt: Math.floor(Date.now() / 1000) + 900,
+    nonce: 0n,
+    policyId: '0x' + '0'.repeat(64),
+  },
+  calls: [{ target, data, value, gasLimit }],
+  invokerAddress,
+});
+```
+
+### Master Key Encryption
+
+Encrypt and decrypt master seeds with AES-256-GCM:
+
+```typescript
+import { encryptMasterSeed, decryptMasterSeed } from '@volr/sdk-core';
+
+// Encrypt
+const { cipher, nonce } = await encryptMasterSeed({
+  masterSeed: new Uint8Array(32),
+  wrapKey: new Uint8Array(32),
+  aad: new TextEncoder().encode('context'),
+});
+
+// Decrypt
+const masterSeed = await decryptMasterSeed({
+  cipher,
+  nonce,
+  wrapKey,
+  aad,
+});
+```
+
+### Key Derivation (HKDF)
+
+Derive keys using HMAC-based Key Derivation Function:
+
+```typescript
+import { hkdf } from '@volr/sdk-core';
+
+const derivedKey = await hkdf({
+  ikm: inputKeyMaterial,
+  salt: new Uint8Array(32),
+  info: new TextEncoder().encode('context'),
+  length: 32,
+});
+```
+
+## API Reference
+
+### Types
+
+```typescript
+// Wallet provider interface
+interface WalletProviderPort {
+  getAddress(): Promise<`0x${string}`>;
+  signMessage(messageHash: Uint8Array): Promise<Uint8Array>;
+  lock?(): Promise<void>;
+  ensureSession?(opts?: { interactive?: boolean; force?: boolean }): Promise<void>;
+}
+
+// Signer interface
+interface SignerPort {
+  getAddress(): Promise<`0x${string}`>;
+  signMessage(messageHash: Uint8Array): Promise<Uint8Array>;
+}
+
+// EIP-7702 authorization tuple
+interface AuthorizationTuple {
+  chainId: bigint;
+  address: `0x${string}`;
+  nonce: bigint;
+  v: bigint;
+  r: `0x${string}`;
+  s: `0x${string}`;
+}
+
+// Session authentication
+interface SessionAuth {
+  chainId: number;
+  sessionKey: `0x${string}`;
+  expiresAt: number;
+  nonce: bigint;
+  policyId: `0x${string}`;
+}
+
+// Call structure
+interface Call {
+  target: `0x${string}`;
+  data: `0x${string}`;
+  value: bigint;
+  gasLimit: bigint;
+}
+```
+
+### Cryptography
+
+- `encryptMasterSeed()`: Encrypt master seed with AES-256-GCM
+- `decryptMasterSeed()`: Decrypt master seed
+- `hkdf()`: HMAC-based key derivation
+- `zeroize()`: Securely zero out sensitive data
+
+### Signers
+
+- `createSecp256k1Signer()`: Create secp256k1 signer
+- `createPasskeyP256Signer()`: Create P-256 passkey signer
+- `createExternalWalletSigner()`: Create external wallet signer (MetaMask, etc.)
+
+### Providers
+
+- `createPasskeyProvider()`: Create passkey-based wallet provider
+- `createMpcProvider()`: Create MPC-based wallet provider
+
+### EVM Utilities
+
+- `signAuthorization()`: Sign EIP-7702 authorization tuple
+- `signSession()`: Sign EIP-712 session authentication
+- `getAuthNonce()`: Get authorization nonce from RPC
+
+## Security
+
+### Key Management
+
+- Master seeds are encrypted with AES-256-GCM
+- Wrap keys are derived from passkey PRF
+- Private keys are zeroized after use
+- No keys are stored in plain text
+
+### Session Security
+
+- Sessions expire after configurable TTL (default: 15 minutes)
+- Each transaction requires fresh signature
+- Policy constraints enforced on-chain
+- Nonce prevents replay attacks
+
+## Testing
+
+```bash
+# Run tests
+yarn test
+
+# Run tests with coverage
+yarn test:coverage
+```
+
+## License
+
+MIT
+
+