@opensecret/react 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -38,6 +38,8 @@ declare namespace api {
         fetchPublicKey,
         convertGuestToEmailAccount,
         generateThirdPartyToken,
+        encryptData,
+        decryptData,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -45,11 +47,15 @@ declare namespace api {
         GoogleAuthResponse,
         PrivateKeyResponse,
         PrivateKeyBytesResponse,
+        KeyOptions,
         SignMessageResponse,
         SignMessageRequest,
         PublicKeyResponse,
         ThirdPartyTokenRequest,
-        ThirdPartyTokenResponse
+        ThirdPartyTokenResponse,
+        EncryptDataRequest,
+        EncryptDataResponse,
+        DecryptDataRequest
     }
 }
 
@@ -193,6 +199,50 @@ declare function createProject(orgId: string, name: string, description?: string
 
 declare function createProjectSecret(orgId: string, projectId: string, keyName: string, secret: string): Promise<ProjectSecret>;
 
+/**
+ * Decrypts data that was previously encrypted with the user's key
+ * @param encryptedData - Base64-encoded encrypted data string
+ * @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 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
+ * - The encrypted_data must be in the exact format returned by the encrypt endpoint
+ */
+declare function decryptData(encryptedData: string, key_options?: KeyOptions): Promise<string>;
+
+declare type DecryptDataRequest = {
+    encrypted_data: string;
+    key_options?: {
+        private_key_derivation_path?: string;
+        seed_phrase_derivation_path?: string;
+    };
+};
+
 declare function deleteOrganization(orgId: string): Promise<void>;
 
 declare function deleteOrganizationInvite(orgId: string, inviteCode: string): Promise<{
@@ -215,6 +265,53 @@ declare type EmailSettings = {
     email_verification_url: string;
 };
 
+/**
+ * Encrypts arbitrary string data using the user's private key
+ * @param data - String content to be encrypted
+ * @param key_options - Key derivation options (see KeyOptions type)
+ * @returns A promise resolving to the encrypted data response
+ * @throws {Error} If:
+ * - 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)
+ * - 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, key_options?: KeyOptions): Promise<EncryptDataResponse>;
+
+declare type EncryptDataRequest = {
+    data: string;
+    key_options?: {
+        private_key_derivation_path?: string;
+        seed_phrase_derivation_path?: string;
+    };
+};
+
+declare type EncryptDataResponse = {
+    encrypted_data: string;
+};
+
 declare const EXPECTED_ROOT_CERT_HASH = "641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b";
 
 declare function fetchAttestationDocument(nonce: string, explicitApiUrl?: string): Promise<string>;
@@ -233,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)
  *
- * 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"
+ * @returns A promise resolving to the private key bytes response
  *
- * 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
+ * @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
+ *
+ * 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
+ *    - 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
  *
- * 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)
+ * @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)
+ *
+ * 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>;
 
@@ -274,7 +418,16 @@ declare function fetchUser(): Promise<UserResponse>;
 
 export declare function generateSecureSecret(): string;
 
-declare function generateThirdPartyToken(audience: string): Promise<ThirdPartyTokenResponse>;
+/**
+ * Generates a JWT token for use with third-party services
+ * @param audience - Optional URL of the service
+ * @returns A promise resolving to the token response containing the JWT
+ *
+ * @description
+ * - If audience is provided, it can be any valid URL
+ * - If audience is omitted, a token with no audience restriction will be generated
+ */
+declare function generateThirdPartyToken(audience?: string): Promise<ThirdPartyTokenResponse>;
 
 declare function getApiUrl(): string;
 
@@ -317,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;
@@ -530,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;
     /**
@@ -632,21 +861,88 @@ export declare type OpenSecretContextType = {
      */
     getAttestationDocument: () => Promise<ParsedAttestationView>;
     /**
-     * Generates a JWT token for use with authorized third-party services
-     * @param audience - The URL of the authorized service (e.g. "https://billing.opensecret.cloud")
+     * Generates a JWT token for use with third-party services
+     * @param audience - Optional URL of the service (e.g. "https://billing.opensecret.cloud")
      * @returns A promise resolving to the token response
      * @throws {Error} If:
      * - The user is not authenticated
-     * - The audience URL is invalid
-     * - The audience URL is not authorized
+     * - The audience URL is invalid (if provided)
      *
      * @description
-     * - Generates a signed JWT token for use with specific authorized third-party services
-     * - The audience must be an pre-authorized URL registered by the developer (e.g. api.devservice.com)
+     * - Generates a signed JWT token for use with third-party services
+     * - If audience is provided, it can be any valid URL
+     * - If audience is omitted, a token with no audience restriction will be generated
      * - Requires an active authentication session
      * - Token can be used to authenticate with the specified service
      */
-    generateThirdPartyToken: (audience: string) => Promise<ThirdPartyTokenResponse>;
+    generateThirdPartyToken: (audience?: string) => Promise<ThirdPartyTokenResponse>;
+    /**
+     * Encrypts arbitrary string data using the user's private key
+     * @param data - String content to be encrypted
+     * @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 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)
+     * - 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 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 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 options for decryption
+     * that were used for encryption.
+     */
+    decryptData: typeof api.decryptData;
 };
 
 /**
@@ -1294,10 +1590,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
@@ -1308,15 +1621,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 = {
@@ -1327,7 +1645,7 @@ declare type SignMessageResponse = {
 };
 
 declare type ThirdPartyTokenRequest = {
-    audience: string;
+    audience?: string;
 };
 
 declare type ThirdPartyTokenResponse = {