@opensecret/react 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -47,6 +47,7 @@ declare namespace api {
         GoogleAuthResponse,
         PrivateKeyResponse,
         PrivateKeyBytesResponse,
+        KeyOptions,
         SignMessageResponse,
         SignMessageRequest,
         PublicKeyResponse,
@@ -201,26 +202,45 @@ declare function createProjectSecret(orgId: string, projectId: string, keyName:
 /**
  * Decrypts data that was previously encrypted with the user's key
  * @param encryptedData - Base64-encoded encrypted data string
- * @param derivationPath - Optional BIP32 derivation path
+ * @param key_options - Key derivation options (see KeyOptions type)
  * @returns A promise resolving to the decrypted string
  * @throws {Error} If:
  * - The encrypted data is malformed
- * - The derivation path is invalid
+ * - The derivation paths are invalid
  * - Authentication fails
  * - Server-side decryption error occurs
  *
  * @description
+ * This function supports multiple decryption approaches:
+ *
+ * 1. Decrypt with master key (no derivation parameters)
+ *
+ * 2. Decrypt with BIP-32 derived key
+ *    - Derives a child key from the master seed using BIP-32
+ *
+ * 3. Decrypt with BIP-85 derived key
+ *    - Derives a child mnemonic using BIP-85, then uses its master key
+ *
+ * 4. Decrypt with combined BIP-85 and BIP-32 derivation
+ *    - First derives a child mnemonic via BIP-85
+ *    - Then applies BIP-32 derivation to derive a key from that seed
+ *
+ * IMPORTANT: You must use the exact same derivation paths for decryption
+ * that were used for encryption.
+ *
+ * Technical details:
  * - Uses AES-256-GCM decryption with authentication tag verification
  * - Extracts the nonce from the first 12 bytes of the encrypted data
- * - If derivation_path is provided, decryption uses the derived key at that path
- * - If derivation_path is omitted, decryption uses the master key
  * - The encrypted_data must be in the exact format returned by the encrypt endpoint
  */
-declare function decryptData(encryptedData: string, derivationPath?: string): Promise<string>;
+declare function decryptData(encryptedData: string, key_options?: KeyOptions): Promise<string>;
 
 declare type DecryptDataRequest = {
     encrypted_data: string;
-    derivation_path?: string;
+    key_options?: {
+        private_key_derivation_path?: string;
+        seed_phrase_derivation_path?: string;
+    };
 };
 
 declare function deleteOrganization(orgId: string): Promise<void>;
@@ -248,28 +268,44 @@ declare type EmailSettings = {
 /**
  * Encrypts arbitrary string data using the user's private key
  * @param data - String content to be encrypted
- * @param derivationPath - Optional BIP32 derivation path
+ * @param key_options - Key derivation options (see KeyOptions type)
  * @returns A promise resolving to the encrypted data response
  * @throws {Error} If:
- * - The derivation path is invalid
+ * - The derivation paths are invalid
  * - Authentication fails
  * - Server-side encryption error occurs
  *
  * @description
+ * This function supports multiple encryption approaches:
+ *
+ * 1. Encrypt with master key (no derivation parameters)
+ *
+ * 2. Encrypt with BIP-32 derived key
+ *    - Derives a child key from the master seed using BIP-32
+ *
+ * 3. Encrypt with BIP-85 derived key
+ *    - Derives a child mnemonic using BIP-85, then uses its master key
+ *
+ * 4. Encrypt with combined BIP-85 and BIP-32 derivation
+ *    - First derives a child mnemonic via BIP-85
+ *    - Then applies BIP-32 derivation to derive a key from that seed
+ *
+ * Technical details:
  * - Encrypts data with AES-256-GCM
  * - A random nonce is generated for each encryption operation (included in the result)
- * - If derivation_path is provided, encryption uses the derived key at that path
- * - If derivation_path is omitted, encryption uses the master key
  * - The encrypted_data format:
  *   - First 12 bytes: Nonce used for encryption (prepended to ciphertext)
  *   - Remaining bytes: AES-256-GCM encrypted ciphertext + authentication tag
  *   - The entire payload is base64-encoded for safe transport
  */
-declare function encryptData(data: string, derivationPath?: string): Promise<EncryptDataResponse>;
+declare function encryptData(data: string, key_options?: KeyOptions): Promise<EncryptDataResponse>;
 
 declare type EncryptDataRequest = {
     data: string;
-    derivation_path?: string;
+    key_options?: {
+        private_key_derivation_path?: string;
+        seed_phrase_derivation_path?: string;
+    };
 };
 
 declare type EncryptDataResponse = {
@@ -294,38 +330,85 @@ declare function fetchLogin(email: string, password: string, client_id: string):
 
 declare function fetchLogout(refresh_token: string): Promise<void>;
 
-declare function fetchPrivateKey(): Promise<PrivateKeyResponse>;
+/**
+ * Fetches the private key as a mnemonic phrase with optional derivation paths
+ * @param key_options - Optional key derivation options (see KeyOptions type)
+ *
+ * @returns A promise resolving to the private key response containing the mnemonic
+ *
+ * @description
+ * - If seed_phrase_derivation_path is provided, a child mnemonic is derived via BIP-85
+ * - If seed_phrase_derivation_path is omitted, the master mnemonic is returned
+ * - BIP-85 allows deriving child mnemonics from a master seed in a deterministic way
+ * - Common BIP-85 path format: m/83696968'/39'/0'/[entropy in bits]'/[index]'
+ *   where entropy is typically 12' for 12-word mnemonics
+ */
+declare function fetchPrivateKey(key_options?: KeyOptions): Promise<PrivateKeyResponse>;
 
 /**
- * Fetches private key bytes for a given derivation path
- * @param derivationPath - Optional BIP32 derivation path
+ * Fetches private key bytes for the given derivation options
+ * @param key_options - Key derivation options (see KeyOptions type)
+ *
+ * @returns A promise resolving to the private key bytes response
+ *
+ * @description
+ * This function supports multiple derivation approaches:
+ *
+ * 1. Master key only (no parameters)
+ *    - Returns the master private key bytes
+ *
+ * 2. BIP-32 derivation only
+ *    - Uses a single derivation path to derive a child key from the master seed
+ *    - Supports both absolute and relative paths with hardened derivation:
+ *      - Absolute path: "m/44'/0'/0'/0/0"
+ *      - Relative path: "0'/0'/0'/0/0"
+ *      - Hardened notation: "44'" or "44h"
+ *    - Common paths:
+ *      - BIP44 (Legacy): m/44'/0'/0'/0/0
+ *      - BIP49 (SegWit): m/49'/0'/0'/0/0
+ *      - BIP84 (Native SegWit): m/84'/0'/0'/0/0
+ *      - BIP86 (Taproot): m/86'/0'/0'/0/0
  *
- * Supports both absolute and relative paths with hardened derivation:
- * - Absolute path: "m/44'/0'/0'/0/0"
- * - Relative path: "0'/0'/0'/0/0"
- * - Hardened notation: "44'" or "44h"
+ * 3. BIP-85 derivation only
+ *    - Derives a child mnemonic from the master seed using BIP-85
+ *    - Then returns the master private key of that derived seed
+ *    - Example path: "m/83696968'/39'/0'/12'/0'"
  *
- * Common paths:
- * - BIP44 (Legacy): m/44'/0'/0'/0/0
- * - BIP49 (SegWit): m/49'/0'/0'/0/0
- * - BIP84 (Native SegWit): m/84'/0'/0'/0/0
- * - BIP86 (Taproot): m/86'/0'/0'/0/0
+ * 4. Combined BIP-85 and BIP-32 derivation
+ *    - First derives a child mnemonic via BIP-85
+ *    - Then applies BIP-32 derivation to that derived seed
+ *    - This allows for more complex derivation schemes
  */
-declare function fetchPrivateKeyBytes(derivationPath?: string): Promise<PrivateKeyBytesResponse>;
+declare function fetchPrivateKeyBytes(key_options?: KeyOptions): Promise<PrivateKeyBytesResponse>;
 
 /**
- * Retrieves the public key for a given algorithm and derivation path
+ * Retrieves the public key for a given algorithm and derivation options
  * @param algorithm - Signing algorithm (schnorr or ecdsa)
- * @param derivationPath - Optional BIP32 derivation path
+ * @param key_options - Key derivation options (see KeyOptions type)
+ *
+ * @returns A promise resolving to the public key response
+ *
+ * @description
+ * The derivation paths determine which key is used to generate the public key:
+ *
+ * 1. Master key (no derivation parameters)
+ *    - Returns the public key corresponding to the master private key
+ *
+ * 2. BIP-32 derived key
+ *    - Returns the public key for a derived child key
+ *    - Useful for:
+ *      - Separating keys by purpose (e.g., different chains or applications)
+ *      - Generating deterministic addresses
+ *      - Supporting different address formats (Legacy, SegWit, Native SegWit, Taproot)
  *
- * The derivation path determines which child key pair is used,
- * allowing different public keys to be generated from the same master key.
- * This is useful for:
- * - Separating keys by purpose (e.g., different chains or applications)
- * - Generating deterministic addresses
- * - Supporting different address formats (Legacy, SegWit, Native SegWit, Taproot)
+ * 3. BIP-85 derived key
+ *    - Returns the public key for the master key of a BIP-85 derived seed
+ *
+ * 4. Combined BIP-85 and BIP-32 derivation
+ *    - First derives a child mnemonic via BIP-85
+ *    - Then applies BIP-32 derivation to get the corresponding public key
  */
-declare function fetchPublicKey(algorithm: SigningAlgorithm, derivationPath?: string): Promise<PublicKeyResponse>;
+declare function fetchPublicKey(algorithm: SigningAlgorithm, key_options?: KeyOptions): Promise<PublicKeyResponse>;
 
 declare function fetchPut(key: string, value: string): Promise<string>;
 
@@ -387,6 +470,22 @@ declare function keyExchange(clientPublicKey: string, nonce: string, explicitApi
     session_id: string;
 }>;
 
+/**
+ * Options for key derivation operations
+ */
+declare type KeyOptions = {
+    /**
+     * BIP-85 derivation path to derive a child mnemonic
+     * Examples: "m/83696968'/39'/0'/12'/0'"
+     */
+    seed_phrase_derivation_path?: string;
+    /**
+     * BIP-32 derivation path to derive a child key from the master (or BIP-85 derived) seed
+     * Examples: "m/44'/0'/0'/0/0"
+     */
+    private_key_derivation_path?: string;
+};
+
 export declare type KVListItem = {
     key: string;
     value: string;
@@ -600,44 +699,104 @@ export declare type OpenSecretContextType = {
     handleGoogleCallback: (code: string, state: string, inviteCode: string) => Promise<void>;
     /**
      * Retrieves the user's private key mnemonic phrase
+     * @param options - Optional key derivation options
      * @returns A promise resolving to the private key response
      * @throws {Error} If the private key cannot be retrieved
+     *
+     * @description
+     * This function supports two modes:
+     *
+     * 1. Master mnemonic (no parameters)
+     *    - Returns the user's master 12-word BIP39 mnemonic
+     *
+     * 2. BIP-85 derived mnemonic
+     *    - Derives a child mnemonic using BIP-85
+     *    - Requires seed_phrase_derivation_path in options
+     *    - Example: "m/83696968'/39'/0'/12'/0'"
      */
     getPrivateKey: typeof api.fetchPrivateKey;
     /**
-     * Retrieves the private key bytes for a given derivation path
-     * @param derivationPath - Optional BIP32 derivation path (e.g. "m/44'/0'/0'/0/0")
+     * Retrieves the private key bytes for the given derivation options
+     * @param options - Optional key derivation options or legacy BIP32 derivation path string
      * @returns A promise resolving to the private key bytes response
      * @throws {Error} If:
      * - The private key bytes cannot be retrieved
-     * - The derivation path is invalid
+     * - The derivation paths are invalid
      *
      * @description
-     * - If no derivation path is provided, returns the master private key bytes
-     * - Supports both absolute (starting with "m/") and relative paths
-     * - Supports hardened derivation using either ' or h notation
-     * - Common paths:
-     *   - BIP44 (Legacy): m/44'/0'/0'/0/0
-     *   - BIP49 (SegWit): m/49'/0'/0'/0/0
-     *   - BIP84 (Native SegWit): m/84'/0'/0'/0/0
-     *   - BIP86 (Taproot): m/86'/0'/0'/0/0
+     * This function supports multiple derivation approaches:
+     *
+     * 1. Master key only (no parameters)
+     *    - Returns the master private key bytes
+     *
+     * 2. BIP-32 derivation only
+     *    - Uses a single derivation path to derive a child key from the master seed
+     *    - Supports both absolute and relative paths with hardened derivation:
+     *      - Absolute path: "m/44'/0'/0'/0/0"
+     *      - Relative path: "0'/0'/0'/0/0"
+     *      - Hardened notation: "44'" or "44h"
+     *    - Common paths:
+     *      - BIP44 (Legacy): m/44'/0'/0'/0/0
+     *      - BIP49 (SegWit): m/49'/0'/0'/0/0
+     *      - BIP84 (Native SegWit): m/84'/0'/0'/0/0
+     *      - BIP86 (Taproot): m/86'/0'/0'/0/0
+     *
+     * 3. BIP-85 derivation only
+     *    - Derives a child mnemonic from the master seed using BIP-85
+     *    - Then returns the master private key of that derived seed
+     *    - Example path: "m/83696968'/39'/0'/12'/0'"
+     *
+     * 4. Combined BIP-85 and BIP-32 derivation
+     *    - First derives a child mnemonic via BIP-85
+     *    - Then applies BIP-32 derivation to that derived seed
      */
     getPrivateKeyBytes: typeof api.fetchPrivateKeyBytes;
     /**
      * Retrieves the user's public key for the specified algorithm
      * @param algorithm - The signing algorithm ('schnorr' or 'ecdsa')
-     * @param derivationPath - Optional BIP32 derivation path
+     * @param options - Optional key derivation options or legacy BIP32 derivation path string
      * @returns A promise resolving to the public key response
      * @throws {Error} If the public key cannot be retrieved
+     *
+     * @description
+     * The derivation paths determine which key is used to generate the public key:
+     *
+     * 1. Master key (no derivation parameters)
+     *    - Returns the public key corresponding to the master private key
+     *
+     * 2. BIP-32 derived key
+     *    - Returns the public key for a derived child key
+     *
+     * 3. BIP-85 derived key
+     *    - Returns the public key for the master key of a BIP-85 derived seed
+     *
+     * 4. Combined BIP-85 and BIP-32 derivation
+     *    - First derives a child mnemonic via BIP-85
+     *    - Then applies BIP-32 derivation to get the corresponding public key
      */
     getPublicKey: typeof api.fetchPublicKey;
     /**
      * Signs a message using the specified algorithm
      * @param messageBytes - The message to sign as a Uint8Array
      * @param algorithm - The signing algorithm ('schnorr' or 'ecdsa')
-     * @param derivationPath - Optional BIP32 derivation path
+     * @param options - Optional key derivation options or legacy BIP32 derivation path string
      * @returns A promise resolving to the signature response
      * @throws {Error} If the message signing fails
+     *
+     * @description
+     * This function supports multiple signing approaches:
+     *
+     * 1. Sign with master key (no derivation parameters)
+     *
+     * 2. Sign with BIP-32 derived key
+     *    - Derives a child key from the master seed using BIP-32
+     *
+     * 3. Sign with BIP-85 derived key
+     *    - Derives a child mnemonic using BIP-85, then uses its master key
+     *
+     * 4. Sign with combined BIP-85 and BIP-32 derivation
+     *    - First derives a child mnemonic via BIP-85
+     *    - Then applies BIP-32 derivation to derive a key from that seed
      */
     signMessage: typeof api.signMessage;
     /**
@@ -720,41 +879,68 @@ export declare type OpenSecretContextType = {
     /**
      * Encrypts arbitrary string data using the user's private key
      * @param data - String content to be encrypted
-     * @param derivationPath? - Optional BIP32 derivation path (e.g., 'm/44'/0'/0'/0/0')
+     * @param options - Optional key derivation options or legacy BIP32 derivation path string
      * @returns A promise resolving to the encrypted data response
      * @throws {Error} If:
-     * - The derivation path is invalid
+     * - The derivation paths are invalid
      * - Authentication fails
      * - Server-side encryption error occurs
      *
      * @description
+     * This function supports multiple encryption approaches:
+     *
+     * 1. Encrypt with master key (no derivation parameters)
+     *
+     * 2. Encrypt with BIP-32 derived key
+     *    - Derives a child key from the master seed using BIP-32
+     *    - Example: "m/44'/0'/0'/0/0"
+     *
+     * 3. Encrypt with BIP-85 derived key
+     *    - Derives a child mnemonic using BIP-85, then uses its master key
+     *    - Example: { seed_phrase_derivation_path: "m/83696968'/39'/0'/12'/0'" }
+     *
+     * 4. Encrypt with combined BIP-85 and BIP-32 derivation
+     *    - First derives a child mnemonic via BIP-85
+     *    - Then applies BIP-32 derivation to derive a key from that seed
+     *    - Example: {
+     *        seed_phrase_derivation_path: "m/83696968'/39'/0'/12'/0'",
+     *        private_key_derivation_path: "m/44'/0'/0'/0/0"
+     *      }
+     *
+     * Technical details:
      * - Encrypts data with AES-256-GCM
      * - A random nonce is generated for each encryption operation (included in the result)
-     * - If derivation_path is provided, encryption uses the derived key at that path
-     * - If derivation_path is omitted, encryption uses the master key
-     * - The encrypted_data format:
-     *   - First 12 bytes: Nonce used for encryption (prepended to ciphertext)
-     *   - Remaining bytes: AES-256-GCM encrypted ciphertext + authentication tag
-     *   - The entire payload is base64-encoded for safe transport
+     * - The encrypted_data format includes the nonce and is base64-encoded
      */
     encryptData: typeof api.encryptData;
     /**
      * Decrypts data that was previously encrypted with the user's key
      * @param encryptedData - Base64-encoded encrypted data string
-     * @param derivationPath? - Optional BIP32 derivation path (e.g., 'm/44'/0'/0'/0/0')
+     * @param options - Optional key derivation options or legacy BIP32 derivation path string
      * @returns A promise resolving to the decrypted string
      * @throws {Error} If:
      * - The encrypted data is malformed
-     * - The derivation path is invalid
+     * - The derivation paths are invalid
      * - Authentication fails
      * - Server-side decryption error occurs
      *
      * @description
-     * - Uses AES-256-GCM decryption with authentication tag verification
-     * - Extracts the nonce from the first 12 bytes of the encrypted data
-     * - If derivation_path is provided, decryption uses the derived key at that path
-     * - If derivation_path is omitted, decryption uses the master key
-     * - The encrypted_data must be in the exact format returned by the encrypt endpoint
+     * This function supports multiple decryption approaches:
+     *
+     * 1. Decrypt with master key (no derivation parameters)
+     *
+     * 2. Decrypt with BIP-32 derived key
+     *    - Derives a child key from the master seed using BIP-32
+     *
+     * 3. Decrypt with BIP-85 derived key
+     *    - Derives a child mnemonic using BIP-85, then uses its master key
+     *
+     * 4. Decrypt with combined BIP-85 and BIP-32 derivation
+     *    - First derives a child mnemonic via BIP-85
+     *    - Then applies BIP-32 derivation to derive a key from that seed
+     *
+     * IMPORTANT: You must use the exact same derivation options for decryption
+     * that were used for encryption.
      */
     decryptData: typeof api.decryptData;
 };
@@ -1192,14 +1378,35 @@ export declare type ParsedAttestationView = {
     validatedPcr0Hash: Pcr0ValidationResult | null;
 };
 
+/**
+ * Result of PCR0 validation
+ */
 export declare type Pcr0ValidationResult = {
+    /** Whether the PCR0 hash matches a known good value */
     isMatch: boolean;
+    /** Human-readable description of the validation result */
     text: string;
+    /** Timestamp of when the PCR was verified (for remote attestation) */
+    verifiedAt?: string;
 };
 
+/**
+ * Configuration options for PCR validation
+ */
 export declare type PcrConfig = {
+    /** Additional custom PCR0 values for production environments */
     pcr0Values?: string[];
+    /** Additional custom PCR0 values for development environments */
     pcr0DevValues?: string[];
+    /** Enable/disable remote attestation (defaults to true) */
+    remoteAttestation?: boolean;
+    /** Custom URLs for remote attestation */
+    remoteAttestationUrls?: {
+        /** URL for production PCR history */
+        prod?: string;
+        /** URL for development PCR history */
+        dev?: string;
+    };
 };
 
 declare namespace platformApi {
@@ -1404,10 +1611,27 @@ declare function setPlatformApiUrl(url: string): void;
 declare type SigningAlgorithm = "schnorr" | "ecdsa";
 
 /**
- * Signs a message using the specified algorithm and derivation path
+ * Signs a message using the specified algorithm and derivation options
  * @param message_bytes - Message to sign as Uint8Array
  * @param algorithm - Signing algorithm (schnorr or ecdsa)
- * @param derivationPath - Optional BIP32 derivation path
+ * @param key_options - Key derivation options (see KeyOptions type)
+ *
+ * @returns A promise resolving to the signature response
+ *
+ * @description
+ * This function supports multiple signing approaches:
+ *
+ * 1. Sign with master key (no derivation parameters)
+ *
+ * 2. Sign with BIP-32 derived key
+ *    - Derives a child key from the master seed using BIP-32
+ *
+ * 3. Sign with BIP-85 derived key
+ *    - Derives a child mnemonic using BIP-85, then uses its master key
+ *
+ * 4. Sign with combined BIP-85 and BIP-32 derivation
+ *    - First derives a child mnemonic via BIP-85
+ *    - Then applies BIP-32 derivation to derive a key from that seed
  *
  * Example message preparation:
  * ```typescript
@@ -1418,15 +1642,20 @@ declare type SigningAlgorithm = "schnorr" | "ecdsa";
  * const messageBytes = new Uint8Array(Buffer.from("deadbeef", "hex"));
  * ```
  */
-declare function signMessage(message_bytes: Uint8Array, algorithm: SigningAlgorithm, derivationPath?: string): Promise<SignMessageResponse>;
+declare function signMessage(message_bytes: Uint8Array, algorithm: SigningAlgorithm, key_options?: KeyOptions): Promise<SignMessageResponse>;
 
 declare type SignMessageRequest = {
     /** Base64-encoded message to sign */
     message_base64: string;
     /** Signing algorithm to use (schnorr or ecdsa) */
     algorithm: SigningAlgorithm;
-    /** Optional BIP32 derivation path (e.g., "m/44'/0'/0'/0/0") */
-    derivation_path?: string;
+    /** Optional key derivation options */
+    key_options?: {
+        /** Optional BIP32 derivation path (e.g., "m/44'/0'/0'/0/0") */
+        private_key_derivation_path?: string;
+        /** Optional BIP-85 seed phrase derivation path (e.g., "m/83696968'/39'/0'/12'/0'") */
+        seed_phrase_derivation_path?: string;
+    };
 };
 
 declare type SignMessageResponse = {