@opensecret/react 0.3.1 → 0.3.3

package/README.md

@@ -82,13 +82,40 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
 - `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).
 
 #### Cryptographic Methods
-- `getPrivateKey(): Promise<PrivateKeyResponse>`: Retrieves the user's private key mnemonic phrase. This is used for cryptographic operations and should be kept secure.
-
-- `getPublicKey(algorithm: 'schnorr' | 'ecdsa'): Promise<PublicKeyResponse>`: Retrieves the user's public key for the specified signing algorithm. Supports two algorithms:
+- `getPrivateKey(): Promise<{ mnemonic: string }>`: Retrieves the user's private key mnemonic phrase. This is used for cryptographic operations and should be kept secure.
+
+- `getPrivateKeyBytes(derivationPath?: string): Promise<{ private_key: string }>`: Retrieves the private key bytes for a given BIP32 derivation path. If no 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
+    Examples:
+    - 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`
+
+- `getPublicKey(algorithm: 'schnorr' | 'ecdsa', derivationPath?: string): Promise<PublicKeyResponse>`: Retrieves the user's public key for the specified signing algorithm and optional derivation path. 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)
+  
+  Supports two algorithms:
   - `'schnorr'`: For Schnorr signatures
   - `'ecdsa'`: For ECDSA signatures
 
-- `signMessage(messageBytes: Uint8Array, algorithm: 'schnorr' | 'ecdsa'): Promise<SignatureResponse>`: Signs a message using the specified algorithm. The message must be provided as a Uint8Array of bytes. Returns a signature that can be verified using the corresponding public key.
+- `signMessage(messageBytes: Uint8Array, algorithm: 'schnorr' | 'ecdsa', derivationPath?: string): Promise<SignatureResponse>`: Signs a message using the specified algorithm and optional derivation path. The message must be provided as a Uint8Array of bytes. Returns a signature that can be verified using the corresponding public key.
+  
+  Example message preparation:
+  ```typescript
+  // From string
+  const messageBytes = new TextEncoder().encode("Hello, World!");
+  
+  // From hex
+  const messageBytes = new Uint8Array(Buffer.from("deadbeef", "hex"));
+  ```
 
 ### AI Integration
 
@@ -144,12 +171,20 @@ To build the library, run the following command:
 bun run build
 ```
 
-To pack the library, run the following command:
+Currently this build step requires `npx` because of [a Bun incompatibility with `vite-plugin-dts`](https://github.com/OpenSecretCloud/OpenSecret-SDK/issues/16).
+
+To pack the library (for publishing) run the following command:
 
 ```bash
 bun run pack
 ```
 
+To deploy: 
+
+```bash
+NPM_CONFIG_TOKEN=$NPM_CONFIG_TOKEN bun publish --access public
+```
+
 ## License
 
 This project is licensed under the MIT License.

package/dist/index.d.ts

@@ -28,6 +28,7 @@ declare namespace api {
         initiateGoogleAuth,
         handleGoogleCallback,
         fetchPrivateKey,
+        fetchPrivateKeyBytes,
         signMessage,
         fetchPublicKey,
         convertGuestToEmailAccount,
@@ -38,7 +39,9 @@ declare namespace api {
         GithubAuthResponse,
         GoogleAuthResponse,
         PrivateKeyResponse,
+        PrivateKeyBytesResponse,
         SignMessageResponse,
+        SignMessageRequest,
         PublicKeyResponse,
         ThirdPartyTokenRequest,
         ThirdPartyTokenResponse
@@ -114,7 +117,36 @@ declare function fetchLogout(refresh_token: string): Promise<void>;
 
 declare function fetchPrivateKey(): Promise<PrivateKeyResponse>;
 
-declare function fetchPublicKey(algorithm: SigningAlgorithm): Promise<PublicKeyResponse>;
+/**
+ * Fetches private key bytes for a given derivation path
+ * @param derivationPath - Optional BIP32 derivation path
+ *
+ * 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
+ */
+declare function fetchPrivateKeyBytes(derivationPath?: string): Promise<PrivateKeyBytesResponse>;
+
+/**
+ * Retrieves the public key for a given algorithm and derivation path
+ * @param algorithm - Signing algorithm (schnorr or ecdsa)
+ * @param derivationPath - Optional BIP32 derivation path
+ *
+ * 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)
+ */
+declare function fetchPublicKey(algorithm: SigningAlgorithm, derivationPath?: string): Promise<PublicKeyResponse>;
 
 declare function fetchPut(key: string, value: string): Promise<string>;
 
@@ -335,9 +367,29 @@ export declare type OpenSecretContextType = {
      * @throws {Error} If the private key cannot be retrieved
      */
     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")
+     * @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
+     *
+     * @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
+     */
+    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
      * @returns A promise resolving to the public key response
      * @throws {Error} If the public key cannot be retrieved
      */
@@ -346,6 +398,7 @@ export declare type OpenSecretContextType = {
      * 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
      * @returns A promise resolving to the signature response
      * @throws {Error} If the message signing fails
      */
@@ -487,12 +540,20 @@ export declare type PcrConfig = {
     pcr0DevValues?: string[];
 };
 
+declare type PrivateKeyBytesResponse = {
+    /** 32-byte hex string (64 characters) representing the private key */
+    private_key: string;
+};
+
 declare type PrivateKeyResponse = {
+    /** 12-word BIP39 mnemonic phrase */
     mnemonic: string;
 };
 
 declare type PublicKeyResponse = {
+    /** Public key in hex format */
     public_key: string;
+    /** The algorithm used (schnorr or ecdsa) */
     algorithm: SigningAlgorithm;
 };
 
@@ -511,10 +572,36 @@ declare function setApiUrl(url: string): void;
 
 declare type SigningAlgorithm = "schnorr" | "ecdsa";
 
-declare function signMessage(message_bytes: Uint8Array, algorithm: SigningAlgorithm): Promise<SignMessageResponse>;
+/**
+ * Signs a message using the specified algorithm and derivation path
+ * @param message_bytes - Message to sign as Uint8Array
+ * @param algorithm - Signing algorithm (schnorr or ecdsa)
+ * @param derivationPath - Optional BIP32 derivation path
+ *
+ * Example message preparation:
+ * ```typescript
+ * // From string
+ * const messageBytes = new TextEncoder().encode("Hello, World!");
+ *
+ * // From hex
+ * const messageBytes = new Uint8Array(Buffer.from("deadbeef", "hex"));
+ * ```
+ */
+declare function signMessage(message_bytes: Uint8Array, algorithm: SigningAlgorithm, derivationPath?: string): 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;
+};
 
 declare type SignMessageResponse = {
+    /** Signature in hex format */
     signature: string;
+    /** Message hash in hex format */
     message_hash: string;
 };