@opensecret/react 1.2.0 → 1.3.0

package/README.md

@@ -380,6 +380,104 @@ To deploy:
 NPM_CONFIG_TOKEN=$NPM_CONFIG_TOKEN bun publish --access public
 ```
 
+### Documentation Development
+
+The SDK documentation is built using [Docusaurus](https://docusaurus.io/), a modern documentation framework. The documentation is automatically generated from TypeScript code comments and supplemented with manually written guides.
+
+#### Getting Started with Documentation
+
+To start the documentation development server:
+
+```bash
+bun run docs:dev
+```
+
+This will start the Docusaurus development server and open the documentation in your browser at http://localhost:3000/. The server supports hot-reloading, so any changes you make to the documentation will be immediately reflected in the browser.
+
+#### Building Documentation
+
+To build the documentation for production:
+
+```bash
+bun run docs:build
+```
+
+This will generate static HTML, JavaScript, and CSS files in the `website/build` directory.
+
+To serve the built documentation locally:
+
+```bash
+bun run docs:serve
+```
+
+#### Documentation Structure
+
+The documentation is organized into the following directories:
+
+- `/website/docs/` - Contains all manual documentation files
+  - `index.md` - The documentation landing page
+  - `/guides/` - Step-by-step guides for using the SDK
+  - `/api/` - API reference documentation (mostly auto-generated)
+
+#### API Reference Documentation
+
+The API reference documentation is automatically generated from TypeScript code comments using [TypeDoc](https://typedoc.org/). To update the API documentation:
+
+1. Write proper JSDoc comments in the TypeScript source code
+2. Run `bun run docs:build` to regenerate the documentation
+
+Important notes for API documentation:
+
+- Use standard JSDoc syntax for documenting parameters, return types, and descriptions
+- For Markdown in JSDoc comments, be aware that backticks (`) must be properly escaped
+- For code examples with apostrophes (e.g., BIP paths like `m/44'/0'/0'/0/0`), use backslash escaping: `m/44\'/0\'/0\'/0/0`
+
+#### Adding New Guides
+
+To add a new guide:
+
+1. Create a new Markdown file in the `/website/docs/guides/` directory
+2. Add frontmatter at the top of the file:
+   ```md
+   ---
+   title: Your Guide Title
+   sidebar_position: X  # Controls the order in the sidebar
+   ---
+   ```
+3. Update the sidebar configuration in `/website/sidebars.ts` if needed
+
+#### Customizing the Documentation
+
+The main configuration files for Docusaurus are:
+
+- `/website/docusaurus.config.ts` - Main Docusaurus configuration
+- `/website/sidebars.ts` - Sidebar configuration
+- `/website/typedoc.json` - TypeDoc configuration for API docs
+
+To customize the appearance:
+
+- Edit `/website/src/css/custom.css` for global styles
+- Create or modify components in `/website/src/components/`
+
+#### Deployment
+
+The documentation can be deployed to various platforms like GitHub Pages, Netlify, or Vercel. For CloudFlare Pages deployment, as mentioned in our guideline:
+
+1. In CloudFlare Pages, create a new project connected to your GitHub repo
+2. Use these build settings:
+   - Build command: `cd website && bun run build`
+   - Build output directory: `website/build`
+3. Set up a custom domain through CloudFlare's dashboard
+
+#### Troubleshooting
+
+Common issues:
+
+- If TypeDoc fails to generate documentation, check the JSDoc comments for syntax errors
+- If you see "Could not parse expression with acorn" errors, there are likely unescaped characters in code examples
+- If links are broken, check that the referenced pages exist and paths are correct
+- For sidebar issues, verify that the sidebar configuration in `sidebars.ts` is correct
+
 ## License
 
 This project is licensed under the MIT License.

package/dist/index.d.ts

@@ -32,6 +32,9 @@ declare namespace api {
         handleGitHubCallback,
         initiateGoogleAuth,
         handleGoogleCallback,
+        initiateAppleAuth,
+        handleAppleCallback,
+        handleAppleNativeSignIn,
         fetchPrivateKey,
         fetchPrivateKeyBytes,
         signMessage,
@@ -45,6 +48,8 @@ declare namespace api {
         KVListItem,
         GithubAuthResponse,
         GoogleAuthResponse,
+        AppleAuthResponse,
+        AppleUser,
         PrivateKeyResponse,
         PrivateKeyBytesResponse,
         KeyOptions,
@@ -107,6 +112,32 @@ export declare interface ApiEndpoint {
     context: ApiContext;
 }
 
+/**
+ * Response from initiating Apple OAuth authentication
+ * @property auth_url - The Apple authorization URL to redirect the user to
+ * @property state - The state parameter used to prevent CSRF attacks
+ */
+declare type AppleAuthResponse = {
+    auth_url: string;
+    state: string;
+};
+
+/**
+ * Apple user information returned from native Apple Sign-In
+ * @property user_identifier - The user's unique ID from Apple
+ * @property identity_token - The JWT token from Apple used for authentication
+ * @property email - Optional email address (only provided on first sign-in)
+ * @property given_name - Optional user's first name (only provided on first sign-in)
+ * @property family_name - Optional user's last name (only provided on first sign-in)
+ */
+declare type AppleUser = {
+    user_identifier: string;
+    identity_token: string;
+    email?: string;
+    given_name?: string;
+    family_name?: string;
+};
+
 declare interface Attestation {
     sessionKey: Uint8Array | null;
     sessionId: string | null;
@@ -453,12 +484,65 @@ export declare type GoogleAuthResponse = {
     csrf_token: string;
 };
 
+/**
+ * Completes Apple OAuth authentication after user is redirected back to your app
+ * @param code - The authorization code from Apple
+ * @param state - The state parameter returned by Apple (should match the original state)
+ * @param inviteCode - Invite code for new user registration
+ * @returns A promise resolving to login response with access and refresh tokens
+ * @description
+ * This function completes the Apple OAuth authentication process by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Exchanging the authorization code for tokens
+ * 3. Creating or authenticating the user account
+ *
+ * This function should be called in your OAuth callback route after
+ * the user is redirected back from Apple's authentication page.
+ */
+declare function handleAppleCallback(code: string, state: string, inviteCode: string): Promise<LoginResponse>;
+
+/**
+ * Handles native Apple Sign-In for iOS devices
+ * @param appleUser - Apple user data from the native Sign in with Apple API
+ * @param client_id - The client ID for your OpenSecret project
+ * @param inviteCode - Optional invite code for new user registration
+ * @returns A promise resolving to login response with access and refresh tokens
+ * @description
+ * This function is specifically for use with iOS native Sign in with Apple:
+ * 1. Validates the Apple identity token and user information
+ * 2. Creates or authenticates the user account
+ * 3. Returns authentication tokens
+ *
+ * Unlike OAuth flow, this method doesn't require redirects and is used
+ * directly with the credential data from Apple's native authentication.
+ *
+ * Note: Email and name information are only provided by Apple on the first
+ * authentication. Your backend should store this information for future use.
+ */
+declare function handleAppleNativeSignIn(appleUser: AppleUser, client_id: string, inviteCode?: string): Promise<LoginResponse>;
+
 declare function handleGitHubCallback(code: string, state: string, inviteCode: string): Promise<LoginResponse>;
 
 declare function handleGoogleCallback(code: string, state: string, inviteCode: string): Promise<LoginResponse>;
 
 export declare function hashSecret(secret: string): Promise<string>;
 
+/**
+ * Initiates Apple OAuth authentication flow
+ * @param client_id - The client ID for your OpenSecret project
+ * @param inviteCode - Optional invite code for new user registration
+ * @returns A promise resolving to the Apple auth response containing auth URL and state
+ * @description
+ * This function starts the Apple OAuth authentication process by:
+ * 1. Generating a secure state parameter to prevent CSRF attacks
+ * 2. Getting an authorization URL from the OpenSecret backend
+ * 3. Returning the URL that the client should redirect to
+ *
+ * After the user authenticates with Apple, they will be redirected back to your application.
+ * The handleAppleCallback function should be used to complete the authentication process.
+ */
+declare function initiateAppleAuth(client_id: string, inviteCode?: string): Promise<AppleAuthResponse>;
+
 declare function initiateGitHubAuth(client_id: string, inviteCode?: string): Promise<GithubAuthResponse>;
 
 declare function initiateGoogleAuth(client_id: string, inviteCode?: string): Promise<GoogleAuthResponse>;
@@ -526,8 +610,10 @@ declare type OAuthProviderSettings = {
 declare type OAuthSettings = {
     google_oauth_enabled: boolean;
     github_oauth_enabled: boolean;
+    apple_oauth_enabled: boolean;
     google_oauth_settings?: OAuthProviderSettings;
     github_oauth_settings?: OAuthProviderSettings;
+    apple_oauth_settings?: OAuthProviderSettings;
 };
 
 export declare type OpenSecretAuthState = {
@@ -540,22 +626,22 @@ export declare const OpenSecretContext: default_2.Context<OpenSecretContextType>
 export declare type OpenSecretContextType = {
     auth: OpenSecretAuthState;
     /**
-     * The client ID for this project/tenant
-     * @description A UUID that identifies which project/tenant this instance belongs to
+     * The client ID for this project/tenant.
+     * A UUID that identifies which project/tenant this instance belongs to.
      */
     clientId: string;
     /**
-     * Authenticates a user with email and password
-     * @param email - User's email address
-     * @param password - User's password
-     * @returns A promise that resolves when authentication is complete
-     * @throws {Error} If login fails
+     * Authenticates a user with email and password.
      *
-     * @description
      * - Calls the login API endpoint with the configured clientId
      * - Stores access_token and refresh_token in localStorage
      * - Updates the auth state with user information
      * - Throws an error if authentication fails
+     *
+     * @param email - User's email address
+     * @param password - User's password
+     * @returns A promise that resolves when authentication is complete
+     * @throws {Error} If login fails
      */
     signIn: (email: string, password: string) => Promise<void>;
     /**
@@ -567,7 +653,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise that resolves when account creation is complete
      * @throws {Error} If signup fails
      *
-     * @description
+     *
      * - Calls the registration API endpoint
      * - Stores access_token and refresh_token in localStorage
      * - Updates the auth state with new user information
@@ -581,7 +667,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise that resolves when authentication is complete
      * @throws {Error} If login fails
      *
-     * @description
+     *
      * - Calls the login API endpoint
      * - Stores access_token and refresh_token in localStorage
      * - Updates the auth state with user information
@@ -595,7 +681,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise that resolves to the login response containing the guest ID
      * @throws {Error} If signup fails
      *
-     * @description
+     *
      * - Calls the registration API endpoint
      * - Stores access_token and refresh_token in localStorage
      * - Updates the auth state with new user information
@@ -613,7 +699,7 @@ export declare type OpenSecretContextType = {
      * - The email address is already in use
      * - The user is not authenticated
      *
-     * @description
+     *
      * - Upgrades the currently signed-in guest account (identified by their UUID) to a full email account
      * - Requires the user to be currently authenticated as a guest
      * - Updates the auth state with new user information
@@ -625,7 +711,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise that resolves when logout is complete
      * @throws {Error} If logout fails
      *
-     * @description
+     *
      * - Calls the logout API endpoint with the current refresh_token
      * - Removes access_token, refresh_token from localStorage
      * - Removes session-related items from sessionStorage
@@ -638,7 +724,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise resolving to the stored value
      * @throws {Error} If the key cannot be retrieved
      *
-     * @description
+     *
      * - Calls the authenticated API endpoint to fetch a value
      * - Returns undefined if the key does not exist
      * - Requires an active authentication session
@@ -652,7 +738,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise resolving to the server's response
      * @throws {Error} If the value cannot be stored
      *
-     * @description
+     *
      * - Calls the authenticated API endpoint to store a value
      * - Requires an active authentication session
      * - Overwrites any existing value for the given key
@@ -664,7 +750,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise resolving to an array of stored items
      * @throws {Error} If the list cannot be retrieved
      *
-     * @description
+     *
      * - Calls the authenticated API endpoint to fetch all stored items
      * - Returns an array of key-value pairs with metadata
      * - Requires an active authentication session
@@ -678,7 +764,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise resolving when the deletion is complete
      * @throws {Error} If the key cannot be deleted
      *
-     * @description
+     *
      * - Calls the authenticated API endpoint to remove a specific key
      * - Requires an active authentication session
      * - Throws an error if the deletion fails (including for non-existent keys)
@@ -697,13 +783,16 @@ export declare type OpenSecretContextType = {
     handleGitHubCallback: (code: string, state: string, inviteCode: string) => Promise<void>;
     initiateGoogleAuth: (inviteCode: string) => Promise<api.GoogleAuthResponse>;
     handleGoogleCallback: (code: string, state: string, inviteCode: string) => Promise<void>;
+    initiateAppleAuth: (inviteCode: string) => Promise<api.AppleAuthResponse>;
+    handleAppleCallback: (code: string, state: string, inviteCode: string) => Promise<void>;
+    handleAppleNativeSignIn: (appleUser: api.AppleUser, 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)
@@ -723,7 +812,7 @@ export declare type OpenSecretContextType = {
      * - The private key bytes cannot be retrieved
      * - The derivation paths are invalid
      *
-     * @description
+     *
      * This function supports multiple derivation approaches:
      *
      * 1. Master key only (no parameters)
@@ -758,7 +847,7 @@ export declare type OpenSecretContextType = {
      * @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)
@@ -776,27 +865,15 @@ export declare type OpenSecretContextType = {
      */
     getPublicKey: typeof api.fetchPublicKey;
     /**
-     * Signs a message using the specified algorithm
+     * Signs a message using the specified algorithm.
+     * This function supports multiple signing approaches: master key (no derivation),
+     * BIP-32 derived key, BIP-85 derived key, or combined BIP-85 and BIP-32 derivation.
+     *
      * @param messageBytes - The message to sign as a Uint8Array
      * @param algorithm - The signing algorithm ('schnorr' or 'ecdsa')
      * @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;
     /**
@@ -853,7 +930,7 @@ export declare type OpenSecretContextType = {
      * @returns A promise resolving to the parsed attestation document
      * @throws {Error} If attestation fails or is invalid
      *
-     * @description
+     *
      * This is a convenience function that:
      * 1. Fetches the attestation document with a random nonce
      * 2. Authenticates the document
@@ -868,7 +945,7 @@ export declare type OpenSecretContextType = {
      * - The user is not authenticated
      * - The audience URL is invalid (if provided)
      *
-     * @description
+     *
      * - 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
@@ -886,25 +963,25 @@ export declare type OpenSecretContextType = {
      * - 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"
+     *    - 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'" }
+     *    - 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"
+     *        seed_phrase_derivation_path: "m/83696968\'/39\'/0\'/12\'/0\'",
+     *        private_key_derivation_path: "m/44\'/0\'/0\'/0/0"
      *      }
      *
      * Technical details:
@@ -924,7 +1001,7 @@ export declare type OpenSecretContextType = {
      * - Authentication fails
      * - Server-side decryption error occurs
      *
-     * @description
+     *
      * This function supports multiple decryption approaches:
      *
      * 1. Decrypt with master key (no derivation parameters)
@@ -983,7 +1060,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @param password - Developer's password
      * @returns A promise that resolves to the login response with access and refresh tokens
      *
-     * @description
+     *
      * - Calls the login API endpoint
      * - Stores access_token and refresh_token in localStorage
      * - Updates the developer state with user information
@@ -996,7 +1073,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves when verification is complete
      * @throws {Error} If verification fails
      *
-     * @description
+     *
      * - Takes the verification code from the verification email link
      * - Calls the verification API endpoint
      * - Updates email_verified status if successful
@@ -1007,7 +1084,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves to a success message
      * @throws {Error} If the user is already verified or request fails
      *
-     * @description
+     *
      * - Used when the user needs a new verification email
      * - Requires the user to be authenticated
      * - Sends a new verification email to the user's registered email address
@@ -1024,7 +1101,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves when the reset request is successfully processed
      * @throws {Error} If the request fails or the email doesn't exist
      *
-     * @description
+     *
      * - Sends a password reset request for a platform developer
      * - The server will send an email with an alphanumeric code
      * - The email and hashed_secret are paired for the reset process
@@ -1040,7 +1117,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves when the password is successfully reset
      * @throws {Error} If the verification fails or the request is invalid
      *
-     * @description
+     *
      * - Completes the password reset process using the code from the email
      * - Requires the plaintext_secret that matches the previously sent hashed_secret
      * - Sets the new password if all verification succeeds
@@ -1054,7 +1131,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves when the password is successfully changed
      * @throws {Error} If current password is incorrect or the request fails
      *
-     * @description
+     *
      * - Requires the user to be authenticated
      * - Verifies the current password before allowing the change
      * - Updates to the new password if verification succeeds
@@ -1068,7 +1145,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @param name - Optional developer name
      * @returns A promise that resolves to the login response with access and refresh tokens
      *
-     * @description
+     *
      * - Calls the registration API endpoint
      * - Stores access_token and refresh_token in localStorage
      * - Updates the developer state with new user information
@@ -1078,7 +1155,7 @@ export declare type OpenSecretDeveloperContextType = {
     /**
      * Signs out the current developer by removing authentication tokens
      *
-     * @description
+     *
      * - Calls the logout API endpoint with the current refresh_token
      * - Removes access_token, refresh_token from localStorage
      * - Resets the developer state to show no user is authenticated
@@ -1089,7 +1166,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise that resolves when the refresh is complete
      * @throws {Error} If the refresh fails
      *
-     * @description
+     *
      * - Retrieves the latest developer information from the server
      * - Updates the developer state with fresh data
      * - Useful after making changes that affect developer profile or organization membership
@@ -1124,7 +1201,7 @@ export declare type OpenSecretDeveloperContextType = {
      * @returns A promise resolving to the parsed attestation document
      * @throws {Error} If attestation fails or is invalid
      *
-     * @description
+     *
      * This is a convenience function that:
      * 1. Fetches the attestation document with a random nonce
      * 2. Authenticates the document