@deadvault/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,210 @@
+/**
+ * @deadvault/sdk — Type definitions.
+ * @module
+ */
+/** A single vault entry (password, API key, TOTP secret, etc.) */
+interface VaultEntry {
+    /** Unique identifier (UUID v4) */
+    id: string;
+    /** Human‑readable label (e.g. "GitHub", "OpenAI API") */
+    label: string;
+    /** The secret value (password, API key, or Base32 TOTP seed) */
+    secret: string;
+    /** Optional URL for autofill matching */
+    url?: string;
+    /** Category tag (e.g. "API Keys", "Passwords") */
+    category?: string;
+    /** Unix timestamp in milliseconds when created */
+    createdAt: number;
+    /** Unix timestamp in milliseconds when last modified */
+    updatedAt: number;
+    /** Entry type — defaults to `"password"` for backward compatibility */
+    type?: "password" | "totp";
+    /** TOTP‑specific configuration (only relevant when `type === "totp"`) */
+    totpConfig?: {
+        /** HMAC algorithm — defaults to `"SHA1"` (standard) */
+        algorithm?: "SHA1" | "SHA256";
+        /** Code length — defaults to `6` */
+        digits?: 6 | 8;
+        /** Time step in seconds — defaults to `30` */
+        period?: number;
+    };
+}
+/** Decrypted vault payload */
+interface VaultData {
+    /** Data format version (currently `1`) */
+    version: number;
+    /** All vault entries */
+    entries: VaultEntry[];
+}
+/** Supported chain name shorthands */
+type ChainName = "base" | "ethereum" | "arbitrum" | "optimism";
+/** Constructor options for {@link DeadVault} */
+interface DeadVaultConfig {
+    /** Chain name shorthand (default: `"base"`) */
+    chain?: ChainName;
+    /** Numeric chain ID — takes precedence over `chain` */
+    chainId?: number;
+    /** Custom JSON‑RPC endpoint (overrides built‑in defaults) */
+    rpcUrl?: string;
+}
+/** Options for {@link DeadVault.read} */
+interface ReadOptions {
+    /** Wallet address that owns the vault (`0x…`) */
+    address: string;
+    /** Master password used during encryption */
+    password: string;
+    /** Wallet signature needed for v2‑encrypted vaults */
+    walletSignature?: string;
+}
+/** Options for {@link DeadVault.write} */
+interface WriteOptions {
+    /** Vault data to encrypt and store on‑chain */
+    data: VaultData;
+    /** Master password for encryption */
+    password: string;
+    /** Hex‑encoded private key for signing the transaction (`0x…`) */
+    privateKey: string;
+    /** Wallet signature for v2 encryption (created via {@link DeadVault.signKdfMessage}) */
+    walletSignature: string;
+}
+/** Result returned by {@link DeadVault.write} */
+interface WriteResult {
+    /** Transaction hash (`0x…`) */
+    hash: string;
+    /** Block number the transaction was mined in */
+    blockNumber: bigint;
+}
+/** Fee information returned by {@link DeadVault.getWriteFee} */
+interface FeeInfo {
+    /** Fee amount in wei */
+    wei: bigint;
+    /** Fee formatted as a decimal ETH string */
+    eth: string;
+}
+
+/**
+ * DeadVault SDK — Main client class.
+ *
+ * Usage:
+ *   const vault = new DeadVault({ chain: "base" });
+ *   const data  = await vault.read({ address, password, walletSignature });
+ *   const entry = vault.findEntry(data, { label: "OpenAI" });
+ *   const code  = await vault.generateTOTP(entry);
+ */
+
+declare class DeadVault {
+    private readonly chainId;
+    private readonly rpcUrl?;
+    private readonly vaultAddress;
+    private client;
+    constructor(config?: DeadVaultConfig);
+    /**
+     * Read and decrypt a vault from the chain.
+     * Returns the decrypted VaultData with all entries.
+     */
+    read(options: ReadOptions): Promise<VaultData>;
+    /**
+     * Encrypt and write vault data on-chain.
+     * Requires a private key for the transaction + wallet signature for v2 encryption.
+     */
+    write(options: WriteOptions): Promise<WriteResult>;
+    /**
+     * Find an entry in vault data by label, category, URL, or custom predicate.
+     */
+    findEntry(data: VaultData, match: {
+        label?: string;
+        category?: string;
+        url?: string;
+    } | ((entry: VaultEntry) => boolean)): VaultEntry | undefined;
+    /**
+     * Find all matching entries.
+     */
+    findEntries(data: VaultData, match: {
+        label?: string;
+        category?: string;
+        url?: string;
+        type?: "password" | "totp";
+    } | ((entry: VaultEntry) => boolean)): VaultEntry[];
+    /**
+     * Generate a TOTP code from a vault entry.
+     * The entry must have type "totp" and contain a base32 secret.
+     */
+    generateTOTP(entry: VaultEntry): Promise<string>;
+    /**
+     * Get the remaining seconds in the current TOTP window.
+     */
+    getTOTPTimeRemaining(period?: number): number;
+    /**
+     * Get the write fee for this chain.
+     */
+    getWriteFee(): Promise<FeeInfo>;
+    /**
+     * Check if an address has an unlimited pass (no fee required).
+     */
+    hasPass(address: string): Promise<boolean>;
+    /**
+     * Check if an address has a vault on-chain.
+     */
+    hasVault(address: string): Promise<boolean>;
+    /**
+     * Sign the KDF message with a private key.
+     * Returns the wallet signature needed for v2 read/write operations.
+     */
+    signKdfMessage(privateKey: string): Promise<string>;
+    /** Get the chain ID this client is configured for */
+    getChainId(): number;
+    /** Get the vault contract address */
+    getVaultAddress(): `0x${string}`;
+}
+
+/**
+ * TOTP (Time-Based One-Time Password) Generator — RFC 6238
+ * Uses Web Crypto API for HMAC. No external dependencies.
+ */
+/** Decode a Base32-encoded string */
+declare function base32Decode(input: string): Uint8Array;
+type TOTPAlgorithm = "SHA1" | "SHA256";
+interface TOTPParams {
+    secret: string;
+    algorithm?: TOTPAlgorithm;
+    digits?: 6 | 8;
+    period?: number;
+}
+/** Generate the current TOTP code */
+declare function generateTOTP(params: TOTPParams): Promise<string>;
+/** Get remaining seconds in the current TOTP window */
+declare function getTOTPTimeRemaining(period?: number): number;
+/** Validate a base32 TOTP secret — checks it decodes to >= 10 bytes */
+declare function isValidTOTPSecret(secret: string): boolean;
+
+/**
+ * Chain configuration — contract addresses, RPCs, chain objects, and ABI.
+ * @module
+ */
+
+/** DeadVault proxy addresses per chain ID */
+declare const VAULT_ADDRESSES: Record<number, `0x${string}`>;
+/** Human‑friendly chain name → chain ID lookup */
+declare const CHAIN_NAME_TO_ID: Record<string, number>;
+
+/**
+ * AES-256-GCM encryption/decryption using Web Crypto API.
+ * Compatible with Node.js 18+, Deno, Bun, and Cloudflare Workers.
+ *
+ * v1: PBKDF2(password, salt, 600k, SHA-256) → AES-256-GCM
+ *     Format: salt(16) || iv(12) || ciphertext
+ *
+ * v2: PBKDF2(password + walletSignature, salt, 600k, SHA-256) → AES-256-GCM
+ *     Format: 0xDEAD00 || 0x02 || salt(16) || iv(12) || ciphertext
+ */
+declare const KDF_SIGN_MESSAGE: string;
+declare function detectVersionFromHex(hexCiphertext: string): number;
+/** Encrypt plaintext with password only (v1 format) */
+declare function encrypt(plaintext: string, password: string): Promise<string>;
+/** Encrypt plaintext with password + wallet signature (v2 format) */
+declare function encryptV2(plaintext: string, password: string, walletSignature: string): Promise<string>;
+/** Decrypt a hex ciphertext. Auto-detects v1/v2 format. */
+declare function decrypt(hexCiphertext: string, password: string, walletSignature?: string): Promise<string>;
+
+export { CHAIN_NAME_TO_ID, DeadVault, type DeadVaultConfig, type FeeInfo, KDF_SIGN_MESSAGE, type ReadOptions, type TOTPAlgorithm, type TOTPParams, VAULT_ADDRESSES, type VaultData, type VaultEntry, type WriteOptions, type WriteResult, base32Decode, decrypt, detectVersionFromHex, encrypt, encryptV2, generateTOTP, getTOTPTimeRemaining, isValidTOTPSecret };

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @deadvault/sdk — Type definitions.
+ * @module
+ */
+/** A single vault entry (password, API key, TOTP secret, etc.) */
+interface VaultEntry {
+    /** Unique identifier (UUID v4) */
+    id: string;
+    /** Human‑readable label (e.g. "GitHub", "OpenAI API") */
+    label: string;
+    /** The secret value (password, API key, or Base32 TOTP seed) */
+    secret: string;
+    /** Optional URL for autofill matching */
+    url?: string;
+    /** Category tag (e.g. "API Keys", "Passwords") */
+    category?: string;
+    /** Unix timestamp in milliseconds when created */
+    createdAt: number;
+    /** Unix timestamp in milliseconds when last modified */
+    updatedAt: number;
+    /** Entry type — defaults to `"password"` for backward compatibility */
+    type?: "password" | "totp";
+    /** TOTP‑specific configuration (only relevant when `type === "totp"`) */
+    totpConfig?: {
+        /** HMAC algorithm — defaults to `"SHA1"` (standard) */
+        algorithm?: "SHA1" | "SHA256";
+        /** Code length — defaults to `6` */
+        digits?: 6 | 8;
+        /** Time step in seconds — defaults to `30` */
+        period?: number;
+    };
+}
+/** Decrypted vault payload */
+interface VaultData {
+    /** Data format version (currently `1`) */
+    version: number;
+    /** All vault entries */
+    entries: VaultEntry[];
+}
+/** Supported chain name shorthands */
+type ChainName = "base" | "ethereum" | "arbitrum" | "optimism";
+/** Constructor options for {@link DeadVault} */
+interface DeadVaultConfig {
+    /** Chain name shorthand (default: `"base"`) */
+    chain?: ChainName;
+    /** Numeric chain ID — takes precedence over `chain` */
+    chainId?: number;
+    /** Custom JSON‑RPC endpoint (overrides built‑in defaults) */
+    rpcUrl?: string;
+}
+/** Options for {@link DeadVault.read} */
+interface ReadOptions {
+    /** Wallet address that owns the vault (`0x…`) */
+    address: string;
+    /** Master password used during encryption */
+    password: string;
+    /** Wallet signature needed for v2‑encrypted vaults */
+    walletSignature?: string;
+}
+/** Options for {@link DeadVault.write} */
+interface WriteOptions {
+    /** Vault data to encrypt and store on‑chain */
+    data: VaultData;
+    /** Master password for encryption */
+    password: string;
+    /** Hex‑encoded private key for signing the transaction (`0x…`) */
+    privateKey: string;
+    /** Wallet signature for v2 encryption (created via {@link DeadVault.signKdfMessage}) */
+    walletSignature: string;
+}
+/** Result returned by {@link DeadVault.write} */
+interface WriteResult {
+    /** Transaction hash (`0x…`) */
+    hash: string;
+    /** Block number the transaction was mined in */
+    blockNumber: bigint;
+}
+/** Fee information returned by {@link DeadVault.getWriteFee} */
+interface FeeInfo {
+    /** Fee amount in wei */
+    wei: bigint;
+    /** Fee formatted as a decimal ETH string */
+    eth: string;
+}
+
+/**
+ * DeadVault SDK — Main client class.
+ *
+ * Usage:
+ *   const vault = new DeadVault({ chain: "base" });
+ *   const data  = await vault.read({ address, password, walletSignature });
+ *   const entry = vault.findEntry(data, { label: "OpenAI" });
+ *   const code  = await vault.generateTOTP(entry);
+ */
+
+declare class DeadVault {
+    private readonly chainId;
+    private readonly rpcUrl?;
+    private readonly vaultAddress;
+    private client;
+    constructor(config?: DeadVaultConfig);
+    /**
+     * Read and decrypt a vault from the chain.
+     * Returns the decrypted VaultData with all entries.
+     */
+    read(options: ReadOptions): Promise<VaultData>;
+    /**
+     * Encrypt and write vault data on-chain.
+     * Requires a private key for the transaction + wallet signature for v2 encryption.
+     */
+    write(options: WriteOptions): Promise<WriteResult>;
+    /**
+     * Find an entry in vault data by label, category, URL, or custom predicate.
+     */
+    findEntry(data: VaultData, match: {
+        label?: string;
+        category?: string;
+        url?: string;
+    } | ((entry: VaultEntry) => boolean)): VaultEntry | undefined;
+    /**
+     * Find all matching entries.
+     */
+    findEntries(data: VaultData, match: {
+        label?: string;
+        category?: string;
+        url?: string;
+        type?: "password" | "totp";
+    } | ((entry: VaultEntry) => boolean)): VaultEntry[];
+    /**
+     * Generate a TOTP code from a vault entry.
+     * The entry must have type "totp" and contain a base32 secret.
+     */
+    generateTOTP(entry: VaultEntry): Promise<string>;
+    /**
+     * Get the remaining seconds in the current TOTP window.
+     */
+    getTOTPTimeRemaining(period?: number): number;
+    /**
+     * Get the write fee for this chain.
+     */
+    getWriteFee(): Promise<FeeInfo>;
+    /**
+     * Check if an address has an unlimited pass (no fee required).
+     */
+    hasPass(address: string): Promise<boolean>;
+    /**
+     * Check if an address has a vault on-chain.
+     */
+    hasVault(address: string): Promise<boolean>;
+    /**
+     * Sign the KDF message with a private key.
+     * Returns the wallet signature needed for v2 read/write operations.
+     */
+    signKdfMessage(privateKey: string): Promise<string>;
+    /** Get the chain ID this client is configured for */
+    getChainId(): number;
+    /** Get the vault contract address */
+    getVaultAddress(): `0x${string}`;
+}
+
+/**
+ * TOTP (Time-Based One-Time Password) Generator — RFC 6238
+ * Uses Web Crypto API for HMAC. No external dependencies.
+ */
+/** Decode a Base32-encoded string */
+declare function base32Decode(input: string): Uint8Array;
+type TOTPAlgorithm = "SHA1" | "SHA256";
+interface TOTPParams {
+    secret: string;
+    algorithm?: TOTPAlgorithm;
+    digits?: 6 | 8;
+    period?: number;
+}
+/** Generate the current TOTP code */
+declare function generateTOTP(params: TOTPParams): Promise<string>;
+/** Get remaining seconds in the current TOTP window */
+declare function getTOTPTimeRemaining(period?: number): number;
+/** Validate a base32 TOTP secret — checks it decodes to >= 10 bytes */
+declare function isValidTOTPSecret(secret: string): boolean;
+
+/**
+ * Chain configuration — contract addresses, RPCs, chain objects, and ABI.
+ * @module
+ */
+
+/** DeadVault proxy addresses per chain ID */
+declare const VAULT_ADDRESSES: Record<number, `0x${string}`>;
+/** Human‑friendly chain name → chain ID lookup */
+declare const CHAIN_NAME_TO_ID: Record<string, number>;
+
+/**
+ * AES-256-GCM encryption/decryption using Web Crypto API.
+ * Compatible with Node.js 18+, Deno, Bun, and Cloudflare Workers.
+ *
+ * v1: PBKDF2(password, salt, 600k, SHA-256) → AES-256-GCM
+ *     Format: salt(16) || iv(12) || ciphertext
+ *
+ * v2: PBKDF2(password + walletSignature, salt, 600k, SHA-256) → AES-256-GCM
+ *     Format: 0xDEAD00 || 0x02 || salt(16) || iv(12) || ciphertext
+ */
+declare const KDF_SIGN_MESSAGE: string;
+declare function detectVersionFromHex(hexCiphertext: string): number;
+/** Encrypt plaintext with password only (v1 format) */
+declare function encrypt(plaintext: string, password: string): Promise<string>;
+/** Encrypt plaintext with password + wallet signature (v2 format) */
+declare function encryptV2(plaintext: string, password: string, walletSignature: string): Promise<string>;
+/** Decrypt a hex ciphertext. Auto-detects v1/v2 format. */
+declare function decrypt(hexCiphertext: string, password: string, walletSignature?: string): Promise<string>;
+
+export { CHAIN_NAME_TO_ID, DeadVault, type DeadVaultConfig, type FeeInfo, KDF_SIGN_MESSAGE, type ReadOptions, type TOTPAlgorithm, type TOTPParams, VAULT_ADDRESSES, type VaultData, type VaultEntry, type WriteOptions, type WriteResult, base32Decode, decrypt, detectVersionFromHex, encrypt, encryptV2, generateTOTP, getTOTPTimeRemaining, isValidTOTPSecret };