@opensecret/react 1.0.0-beta.4 → 1.0.1

package/README.md

@@ -91,7 +91,7 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
 #### Account Management Methods
 - `refetchUser(): Promise<void>`: Refreshes the user's authentication state.
 - `changePassword(currentPassword: string, newPassword: string): Promise<void>`: Changes the user's password.
-- `generateThirdPartyToken(audience: string): Promise<{ token: string }>`: Generates a JWT token for use with pre-authorized third-party services (e.g. "https://api.devservice.com"). Developers must register this URL in advance (coming soon).
+- `generateThirdPartyToken(audience?: string): Promise<{ token: string }>`: Generates a JWT token for use with third-party services. If an audience is provided, it can be any valid URL. If omitted, a token with no audience restriction will be generated.
 
 #### Cryptographic Methods
 - `getPrivateKey(): Promise<{ mnemonic: string }>`: Retrieves the user's private key mnemonic phrase. This is used for cryptographic operations and should be kept secure.
@@ -129,6 +129,36 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
   const messageBytes = new Uint8Array(Buffer.from("deadbeef", "hex"));
   ```
 
+- `encryptData(data: string, derivationPath?: string): Promise<{ encrypted_data: string }>`: Encrypts arbitrary string data using the user's private key.
+  - Uses AES-256-GCM encryption with a random nonce for each operation
+  - If derivation_path is provided, encryption uses the derived key at that path
+  - If derivation_path is omitted, encryption uses the master key
+  - Returns base64-encoded encrypted data containing the nonce, ciphertext, and authentication tag
+  
+  Example:
+  ```typescript
+  // Encrypt with master key
+  const { encrypted_data } = await os.encryptData("Secret message");
+  
+  // Encrypt with derived key
+  const { encrypted_data } = await os.encryptData("Secret message", "m/44'/0'/0'/0/0");
+  ```
+
+- `decryptData(encryptedData: string, derivationPath?: string): Promise<string>`: Decrypts data that was previously encrypted with the user's key.
+  - Uses AES-256-GCM decryption with authentication tag verification
+  - 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
+  
+  Example:
+  ```typescript
+  // Decrypt with master key
+  const decrypted = await os.decryptData(encrypted_data);
+  
+  // Decrypt with derived key (must use same path as encryption)
+  const decrypted = await os.decryptData(encrypted_data, "m/44'/0'/0'/0/0");
+  ```
+
 ### AI Integration
 
 To get encrypted-to-the-gpu AI chat we provide a special version of `fetch` (`os.aiCustomFetch`) that handles all the encryption. Because we require the user to be logged in, and do the encryption client-side, this is safe to call from the client.
@@ -212,3 +242,4 @@ NPM_CONFIG_TOKEN=$NPM_CONFIG_TOKEN bun publish --access public
 ## License
 
 This project is licensed under the MIT License.
+

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { default as default_2 } from 'react';
-import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { JSX } from 'react/jsx-runtime';
 import { z } from 'zod';
 
 declare function acceptInvite(code: string): Promise<{
@@ -38,6 +38,8 @@ declare namespace api {
         fetchPublicKey,
         convertGuestToEmailAccount,
         generateThirdPartyToken,
+        encryptData,
+        decryptData,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -49,7 +51,10 @@ declare namespace api {
         SignMessageRequest,
         PublicKeyResponse,
         ThirdPartyTokenRequest,
-        ThirdPartyTokenResponse
+        ThirdPartyTokenResponse,
+        EncryptDataRequest,
+        EncryptDataResponse,
+        DecryptDataRequest
     }
 }
 
@@ -193,6 +198,31 @@ 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 derivationPath - Optional BIP32 derivation path
+ * @returns A promise resolving to the decrypted string
+ * @throws {Error} If:
+ * - The encrypted data is malformed
+ * - The derivation path is 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
+ */
+declare function decryptData(encryptedData: string, derivationPath?: string): Promise<string>;
+
+declare type DecryptDataRequest = {
+    encrypted_data: string;
+    derivation_path?: string;
+};
+
 declare function deleteOrganization(orgId: string): Promise<void>;
 
 declare function deleteOrganizationInvite(orgId: string, inviteCode: string): Promise<{
@@ -215,6 +245,37 @@ 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 derivationPath - Optional BIP32 derivation path
+ * @returns A promise resolving to the encrypted data response
+ * @throws {Error} If:
+ * - The derivation path is invalid
+ * - Authentication fails
+ * - Server-side encryption error occurs
+ *
+ * @description
+ * - 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 type EncryptDataRequest = {
+    data: string;
+    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>;
@@ -274,7 +335,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;
 
@@ -632,21 +702,61 @@ 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 derivationPath? - Optional BIP32 derivation path (e.g., 'm/44'/0'/0'/0/0')
+     * @returns A promise resolving to the encrypted data response
+     * @throws {Error} If:
+     * - The derivation path is invalid
+     * - Authentication fails
+     * - Server-side encryption error occurs
+     *
+     * @description
+     * - 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
+     */
+    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')
+     * @returns A promise resolving to the decrypted string
+     * @throws {Error} If:
+     * - The encrypted data is malformed
+     * - The derivation path is 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
+     */
+    decryptData: typeof api.decryptData;
 };
 
 /**
@@ -670,7 +780,7 @@ export declare function OpenSecretDeveloper({ children, apiUrl, pcrConfig }: {
     children: default_2.ReactNode;
     apiUrl: string;
     pcrConfig?: PcrConfig;
-}): JSX_2.Element;
+}): JSX.Element;
 
 export declare type OpenSecretDeveloperAuthState = {
     loading: boolean;
@@ -1034,7 +1144,7 @@ export declare function OpenSecretProvider({ children, apiUrl, clientId, pcrConf
     apiUrl: string;
     clientId: string;
     pcrConfig?: PcrConfig;
-}): JSX_2.Element;
+}): JSX.Element;
 
 declare type Organization = {
     id: string;
@@ -1327,7 +1437,7 @@ declare type SignMessageResponse = {
 };
 
 declare type ThirdPartyTokenRequest = {
-    audience: string;
+    audience?: string;
 };
 
 declare type ThirdPartyTokenResponse = {