@opensecret/react 0.3.4 → 0.4.0

package/README.md

@@ -12,14 +12,19 @@ npm install @opensecret/react
 
 ## Usage
 
-Wrap your application in the `OpenSecretProvider` component and provide the URL of your OpenSecret backend:
+Wrap your application in the `OpenSecretProvider` component and provide:
+1. The URL of your OpenSecret backend
+2. Your project's client ID (a UUID that identifies your project)
 
 ```tsx
 import { OpenSecretProvider } from "@opensecret/react";
 
 function App() {
   return (
-    <OpenSecretProvider apiUrl="{URL}">
+    <OpenSecretProvider 
+      apiUrl="{URL}"
+      clientId="{PROJECT_UUID}"
+    >
       <App />
     </OpenSecretProvider>
   );
@@ -52,10 +57,15 @@ function App() {
 
 ### `OpenSecretProvider`
 
-The `OpenSecretProvider` component is the main entry point for the SDK. It requires a single prop, `apiUrl`, which should be set to the URL of your OpenSecret backend.
+The `OpenSecretProvider` component is the main entry point for the SDK. It requires two props:
+- `apiUrl`: The URL of your OpenSecret backend
+- `clientId`: A UUID that identifies your project/tenant. This is used to scope user accounts and data to your specific project.
 
 ```tsx
-<OpenSecretProvider apiUrl="{URL}">
+<OpenSecretProvider 
+  apiUrl="{URL}"
+  clientId="{PROJECT_UUID}"
+>
   <App />
 </OpenSecretProvider>
 ```
@@ -67,9 +77,9 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
 #### Authentication Methods
 - `signIn(email: string, password: string): Promise<void>`: Signs in a user with the provided email and password.
 - `signUp(email: string, password: string, inviteCode: string, name?: string): Promise<void>`: Signs up a new user with the provided email, password, invite code, and optional name.
-- `signInGuest(id: string, password: string): Promise<void>`: Signs in a guest user with their ID and password.
-- `signUpGuest(password: string, inviteCode: string): Promise<LoginResponse>`: Creates a new guest account with just a password and invite code. Returns a response containing the guest's ID, access token, and refresh token.
-- `convertGuestToUserAccount(email: string, password: string, name?: string): Promise<void>`: Converts current guest account to a regular account with email authentication. Optionally sets the user's name.
+- `signInGuest(id: string, password: string): Promise<void>`: Signs in a guest user with their ID and password. Guest accounts are scoped to the project specified by `clientId`.
+- `signUpGuest(password: string, inviteCode: string): Promise<LoginResponse>`: Creates a new guest account with just a password and invite code. Returns a response containing the guest's ID, access token, and refresh token. The guest account will be associated with the project specified by `clientId`.
+- `convertGuestToUserAccount(email: string, password: string, name?: string): Promise<void>`: Converts current guest account to a regular account with email authentication. Optionally sets the user's name. The account remains associated with the same project it was created under.
 - `signOut(): Promise<void>`: Signs out the current user.
 
 #### Key-Value Storage Methods
@@ -173,6 +183,12 @@ To build the library, run the following command:
 bun run build
 ```
 
+To test the library, run the following command:
+
+```bash
+bun test --env-file .env.local
+```
+
 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:

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 declare namespace api {
     export {
         setApiUrl,
+        getApiUrl,
         fetchLogin,
         fetchGuestLogin,
         fetchSignUp,
@@ -93,9 +94,9 @@ declare const AWS_ROOT_CERT_DER: Uint8Array;
 
 declare function changePassword(currentPassword: string, newPassword: string): Promise<void>;
 
-declare function confirmPasswordReset(email: string, alphanumericCode: string, plaintextSecret: string, newPassword: string): Promise<void>;
+declare function confirmPasswordReset(email: string, alphanumericCode: string, plaintextSecret: string, newPassword: string, client_id: string): Promise<void>;
 
-declare function convertGuestToEmailAccount(email: string, password: string, name?: string): Promise<void>;
+declare function convertGuestToEmailAccount(email: string, password: string, name?: string | null): Promise<void>;
 
 declare const EXPECTED_ROOT_CERT_HASH = "641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b";
 
@@ -105,13 +106,13 @@ declare function fetchDelete(key: string): Promise<void>;
 
 declare function fetchGet(key: string): Promise<string | undefined>;
 
-declare function fetchGuestLogin(id: string, password: string): Promise<LoginResponse>;
+declare function fetchGuestLogin(id: string, password: string, client_id: string): Promise<LoginResponse>;
 
-declare function fetchGuestSignUp(password: string, inviteCode: string): Promise<LoginResponse>;
+declare function fetchGuestSignUp(password: string, inviteCode: string, client_id: string): Promise<LoginResponse>;
 
 declare function fetchList(): Promise<KVListItem[]>;
 
-declare function fetchLogin(email: string, password: string): Promise<LoginResponse>;
+declare function fetchLogin(email: string, password: string, client_id: string): Promise<LoginResponse>;
 
 declare function fetchLogout(refresh_token: string): Promise<void>;
 
@@ -150,7 +151,7 @@ declare function fetchPublicKey(algorithm: SigningAlgorithm, derivationPath?: st
 
 declare function fetchPut(key: string, value: string): Promise<string>;
 
-declare function fetchSignUp(email: string, password: string, inviteCode: string, name?: string | null): Promise<LoginResponse>;
+declare function fetchSignUp(email: string, password: string, inviteCode: string, client_id: string, name?: string | null): Promise<LoginResponse>;
 
 declare function fetchUser(): Promise<UserResponse>;
 
@@ -158,6 +159,8 @@ export declare function generateSecureSecret(): string;
 
 declare function generateThirdPartyToken(audience: string): Promise<ThirdPartyTokenResponse>;
 
+declare function getApiUrl(): string;
+
 declare function getAttestation(forceRefresh?: boolean, apiUrl?: string): Promise<Attestation>;
 
 export declare type GithubAuthResponse = {
@@ -176,9 +179,9 @@ declare function handleGoogleCallback(code: string, state: string, inviteCode: s
 
 export declare function hashSecret(secret: string): Promise<string>;
 
-declare function initiateGitHubAuth(inviteCode?: string): Promise<GithubAuthResponse>;
+declare function initiateGitHubAuth(client_id: string, inviteCode?: string): Promise<GithubAuthResponse>;
 
-declare function initiateGoogleAuth(inviteCode?: string): Promise<GoogleAuthResponse>;
+declare function initiateGoogleAuth(client_id: string, inviteCode?: string): Promise<GoogleAuthResponse>;
 
 declare function keyExchange(clientPublicKey: string, nonce: string): Promise<{
     encrypted_session_key: string;
@@ -208,6 +211,11 @@ 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
+     */
+    clientId: string;
     /**
      * Authenticates a user with email and password
      * @param email - User's email address
@@ -216,7 +224,7 @@ export declare type OpenSecretContextType = {
      * @throws {Error} If login fails
      *
      * @description
-     * - Calls the login API endpoint
+     * - 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
@@ -283,7 +291,7 @@ export declare type OpenSecretContextType = {
      * - Updates the auth state with new user information
      * - Preserves all existing data associated with the guest account
      */
-    convertGuestToUserAccount: (email: string, password: string, name?: string) => Promise<void>;
+    convertGuestToUserAccount: (email: string, password: string, name?: string | null) => Promise<void>;
     /**
      * Logs out the current user
      * @returns A promise that resolves when logout is complete
@@ -355,8 +363,8 @@ export declare type OpenSecretContextType = {
     refetchUser: () => Promise<void>;
     changePassword: typeof api.changePassword;
     refreshAccessToken: typeof api.refreshToken;
-    requestPasswordReset: typeof api.requestPasswordReset;
-    confirmPasswordReset: typeof api.confirmPasswordReset;
+    requestPasswordReset: (email: string, hashedSecret: string) => Promise<void>;
+    confirmPasswordReset: (email: string, alphanumericCode: string, plaintextSecret: string, newPassword: string) => Promise<void>;
     initiateGitHubAuth: (inviteCode: string) => Promise<api.GithubAuthResponse>;
     handleGitHubCallback: (code: string, state: string, inviteCode: string) => Promise<void>;
     initiateGoogleAuth: (inviteCode: string) => Promise<api.GoogleAuthResponse>;
@@ -488,23 +496,30 @@ export declare type OpenSecretContextType = {
  * @param props - Configuration properties for the OpenSecret provider
  * @param props.children - React child components to be wrapped by the provider
  * @param props.apiUrl - URL of OpenSecret enclave backend
+ * @param props.clientId - UUID identifying which project/tenant this instance belongs to
+ * @param props.pcrConfig - Optional PCR configuration for attestation validation
  *
  * @remarks
  * This provider manages:
  * - User authentication state
  * - Authentication methods (sign in, sign up, sign out)
  * - Key-value storage operations
+ * - Project/tenant identification via clientId
  *
  * @example
  * ```tsx
- * <OpenSecretProvider apiUrl='https://preview.opensecret.ai'>
+ * <OpenSecretProvider
+ *   apiUrl='https://preview.opensecret.ai'
+ *   clientId='550e8400-e29b-41d4-a716-446655440000'
+ * >
  *   <App />
  * </OpenSecretProvider>
  * ```
  */
-export declare function OpenSecretProvider({ children, apiUrl, pcrConfig }: {
+export declare function OpenSecretProvider({ children, apiUrl, clientId, pcrConfig }: {
     children: default_2.ReactNode;
     apiUrl: string;
+    clientId: string;
     pcrConfig?: PcrConfig;
 }): JSX_2.Element;
 
@@ -566,7 +581,7 @@ declare function refreshToken(): Promise<RefreshResponse>;
 
 declare function requestNewVerificationCode(): Promise<void>;
 
-declare function requestPasswordReset(email: string, hashedSecret: string): Promise<void>;
+declare function requestPasswordReset(email: string, hashedSecret: string, client_id: string): Promise<void>;
 
 declare function setApiUrl(url: string): void;