@opensecret/react 0.4.0 → 1.0.0-beta.1

package/README.md

@@ -189,6 +189,12 @@ To test the library, run the following command:
 bun test --env-file .env.local
 ```
 
+To test a specific file or test case:
+
+```bash
+bun test --test-name-pattern="Developer login and token storage" src/lib/developer.test.ts --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

@@ -2,6 +2,10 @@ import { default as default_2 } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { z } from 'zod';
 
+declare function acceptInvite(code: string): Promise<{
+    message: string;
+}>;
+
 declare namespace api {
     export {
         setApiUrl,
@@ -49,6 +53,54 @@ declare namespace api {
     }
 }
 
+export declare const apiConfig: ApiConfigService;
+
+/**
+ * ApiConfig service that manages URL configuration for both contexts
+ */
+declare class ApiConfigService {
+    private _appApiUrl;
+    private _platformApiUrl;
+    /**
+     * Configure the API URLs for both app and platform contexts
+     */
+    configure(appApiUrl: string, platformApiUrl: string): void;
+    /**
+     * Get the platform API URL
+     */
+    get platformApiUrl(): string;
+    /**
+     * Get the app API URL
+     */
+    get appApiUrl(): string;
+    /**
+     * Determine if a path is for the platform context
+     */
+    isPlatformPath(path: string): boolean;
+    /**
+     * Get the API endpoint for a given path
+     */
+    resolveEndpoint(path: string): ApiEndpoint;
+    /**
+     * Build a complete URL for an API path
+     */
+    buildUrl(path: string): string;
+    /**
+     * Get the appropriate refresh token function name for a given path
+     */
+    getRefreshFunction(path: string): "platformRefreshToken" | "refreshToken";
+}
+
+/**
+ * API configuration service that manages endpoints for both app and platform APIs
+ */
+export declare type ApiContext = "app" | "platform";
+
+export declare interface ApiEndpoint {
+    baseUrl: string;
+    context: ApiContext;
+}
+
 declare interface Attestation {
     sessionKey: Uint8Array | null;
     sessionId: string | null;
@@ -98,9 +150,37 @@ declare function confirmPasswordReset(email: string, alphanumericCode: string, p
 
 declare function convertGuestToEmailAccount(email: string, password: string, name?: string | null): Promise<void>;
 
+declare function createOrganization(name: string): Promise<Organization>;
+
+declare function createProject(orgId: string, name: string, description?: string): Promise<Project>;
+
+declare function createProjectSecret(orgId: string, projectId: string, keyName: string, secret: string): Promise<ProjectSecret>;
+
+declare function deleteOrganization(orgId: string): Promise<void>;
+
+declare function deleteOrganizationInvite(orgId: string, inviteCode: string): Promise<{
+    message: string;
+}>;
+
+declare function deleteProject(orgId: string, projectId: string): Promise<void>;
+
+declare function deleteProjectSecret(orgId: string, projectId: string, keyName: string): Promise<void>;
+
+declare type DeveloperResponse = PlatformUser & {
+    organizations: PlatformOrg[];
+};
+
+export declare type DeveloperRole = "owner" | "admin" | "developer" | "viewer";
+
+declare type EmailSettings = {
+    provider: string;
+    send_from: string;
+    email_verification_url: string;
+};
+
 declare const EXPECTED_ROOT_CERT_HASH = "641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b";
 
-declare function fetchAttestationDocument(nonce: string): Promise<string>;
+declare function fetchAttestationDocument(nonce: string, explicitApiUrl?: string): Promise<string>;
 
 declare function fetchDelete(key: string): Promise<void>;
 
@@ -161,7 +241,17 @@ declare function generateThirdPartyToken(audience: string): Promise<ThirdPartyTo
 
 declare function getApiUrl(): string;
 
-declare function getAttestation(forceRefresh?: boolean, apiUrl?: string): Promise<Attestation>;
+declare function getAttestation(forceRefresh?: boolean, explicitApiUrl?: string): Promise<Attestation>;
+
+declare function getEmailSettings(orgId: string, projectId: string): Promise<EmailSettings>;
+
+declare function getOAuthSettings(orgId: string, projectId: string): Promise<OAuthSettings>;
+
+declare function getOrganizationInvite(orgId: string, inviteCode: string): Promise<OrganizationInvite>;
+
+declare function getPlatformApiUrl(): string;
+
+declare function getProject(orgId: string, projectId: string): Promise<Project>;
 
 export declare type GithubAuthResponse = {
     auth_url: string;
@@ -183,7 +273,9 @@ declare function initiateGitHubAuth(client_id: string, inviteCode?: string): Pro
 
 declare function initiateGoogleAuth(client_id: string, inviteCode?: string): Promise<GoogleAuthResponse>;
 
-declare function keyExchange(clientPublicKey: string, nonce: string): Promise<{
+declare function inviteDeveloper(orgId: string, email: string, role?: string): Promise<OrganizationInvite>;
+
+declare function keyExchange(clientPublicKey: string, nonce: string, explicitApiUrl?: string): Promise<{
     encrypted_session_key: string;
     session_id: string;
 }>;
@@ -195,6 +287,16 @@ export declare type KVListItem = {
     updated_at: number;
 };
 
+declare function listOrganizationInvites(orgId: string): Promise<OrganizationInvite[]>;
+
+declare function listOrganizationMembers(orgId: string): Promise<OrganizationMember[]>;
+
+declare function listOrganizations(): Promise<Organization[]>;
+
+declare function listProjects(orgId: string): Promise<Project[]>;
+
+declare function listProjectSecrets(orgId: string, projectId: string): Promise<ProjectSecret[]>;
+
 export declare type LoginResponse = {
     id: string;
     email?: string;
@@ -202,6 +304,26 @@ export declare type LoginResponse = {
     refresh_token: string;
 };
 
+declare type MeResponse = {
+    user: PlatformUser;
+    organizations: PlatformOrg[];
+};
+
+/**
+ * Provider-specific OAuth settings
+ */
+declare type OAuthProviderSettings = {
+    client_id: string;
+    redirect_url: string;
+};
+
+declare type OAuthSettings = {
+    google_oauth_enabled: boolean;
+    github_oauth_enabled: boolean;
+    google_oauth_settings?: OAuthProviderSettings;
+    github_oauth_settings?: OAuthProviderSettings;
+};
+
 export declare type OpenSecretAuthState = {
     loading: boolean;
     user?: api.UserResponse;
@@ -490,6 +612,289 @@ export declare type OpenSecretContextType = {
     generateThirdPartyToken: (audience: string) => Promise<ThirdPartyTokenResponse>;
 };
 
+/**
+ * Provider component for OpenSecret developer operations.
+ * This provider is used for managing organizations, projects, and developer access.
+ *
+ * @param props - Configuration properties for the OpenSecret developer provider
+ * @param props.children - React child components to be wrapped by the provider
+ * @param props.apiUrl - URL of OpenSecret developer API
+ *
+ * @example
+ * ```tsx
+ * <OpenSecretDeveloper
+ *   apiUrl='https://developer.opensecret.cloud'
+ * >
+ *   <App />
+ * </OpenSecretDeveloper>
+ * ```
+ */
+export declare function OpenSecretDeveloper({ children, apiUrl, pcrConfig }: {
+    children: default_2.ReactNode;
+    apiUrl: string;
+    pcrConfig?: PcrConfig;
+}): JSX_2.Element;
+
+export declare type OpenSecretDeveloperAuthState = {
+    loading: boolean;
+    developer?: DeveloperResponse;
+};
+
+export declare const OpenSecretDeveloperContext: default_2.Context<OpenSecretDeveloperContextType>;
+
+export declare type OpenSecretDeveloperContextType = {
+    auth: OpenSecretDeveloperAuthState;
+    /**
+     * Signs in a developer with email and password
+     * @param email - Developer's email address
+     * @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
+     * - Throws an error if authentication fails
+     */
+    signIn: (email: string, password: string) => Promise<platformApi.PlatformLoginResponse>;
+    /**
+     * Registers a new developer account
+     * @param email - Developer's email address
+     * @param password - Developer's password
+     * @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
+     * - Throws an error if account creation fails
+     */
+    signUp: (email: string, password: string, name?: string) => Promise<platformApi.PlatformLoginResponse>;
+    /**
+     * 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
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Refreshes the developer's authentication state
+     * @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
+     */
+    refetchDeveloper: () => Promise<void>;
+    /**
+     * Additional PCR0 hashes to validate against
+     */
+    pcrConfig: PcrConfig;
+    /**
+     * Gets attestation from the enclave
+     */
+    getAttestation: typeof getAttestation;
+    /**
+     * Authenticates an attestation document
+     */
+    authenticate: typeof authenticate;
+    /**
+     * Parses an attestation document for viewing
+     */
+    parseAttestationForView: (document: AttestationDocument, cabundle: Uint8Array[], pcrConfig?: PcrConfig) => Promise<ParsedAttestationView>;
+    /**
+     * AWS root certificate in DER format
+     */
+    awsRootCertDer: typeof AWS_ROOT_CERT_DER;
+    /**
+     * Expected hash of the AWS root certificate
+     */
+    expectedRootCertHash: typeof EXPECTED_ROOT_CERT_HASH;
+    /**
+     * Gets and verifies an attestation document from the enclave
+     * @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
+     * 3. Parses it for viewing
+     */
+    getAttestationDocument: () => Promise<ParsedAttestationView>;
+    /**
+     * Creates a new organization
+     * @param name - Organization name
+     * @returns A promise that resolves to the created organization
+     */
+    createOrganization: (name: string) => Promise<Organization>;
+    /**
+     * Lists all organizations the developer has access to
+     * @returns A promise resolving to array of organization details
+     */
+    listOrganizations: () => Promise<Organization[]>;
+    /**
+     * Deletes an organization (requires owner role)
+     * @param orgId - Organization ID
+     */
+    deleteOrganization: (orgId: string) => Promise<void>;
+    /**
+     * Creates a new project within an organization
+     * @param orgId - Organization ID
+     * @param name - Project name
+     * @param description - Optional project description
+     * @returns A promise that resolves to the project details including client ID
+     */
+    createProject: (orgId: string, name: string, description?: string) => Promise<Project>;
+    /**
+     * Lists all projects within an organization
+     * @param orgId - Organization ID
+     * @returns A promise resolving to array of project details
+     */
+    listProjects: (orgId: string) => Promise<Project[]>;
+    /**
+     * Gets a single project by ID
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @returns A promise resolving to the project details
+     */
+    getProject: (orgId: string, projectId: string) => Promise<Project>;
+    /**
+     * Updates project details
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @param updates - Object containing fields to update
+     */
+    updateProject: (orgId: string, projectId: string, updates: {
+        name?: string;
+        description?: string;
+        status?: string;
+    }) => Promise<Project>;
+    /**
+     * Deletes a project
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     */
+    deleteProject: (orgId: string, projectId: string) => Promise<void>;
+    /**
+     * Creates a new secret for a project
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @param keyName - Secret key name (must be alphanumeric)
+     * @param secret - Secret value (must be base64 encoded by the caller)
+     *
+     * Example:
+     * ```typescript
+     * // To encode a string secret
+     * import { encode } from "@stablelib/base64";
+     * const encodedSecret = encode(new TextEncoder().encode("my-secret-value"));
+     *
+     * // Now pass the encoded secret to the function
+     * createProjectSecret(orgId, projectId, "mySecretKey", encodedSecret);
+     * ```
+     */
+    createProjectSecret: (orgId: string, projectId: string, keyName: string, secret: string) => Promise<ProjectSecret>;
+    /**
+     * Lists all secrets for a project
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     */
+    listProjectSecrets: (orgId: string, projectId: string) => Promise<ProjectSecret[]>;
+    /**
+     * Deletes a project secret
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @param keyName - Secret key name
+     */
+    deleteProjectSecret: (orgId: string, projectId: string, keyName: string) => Promise<void>;
+    /**
+     * Gets email configuration for a project
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     */
+    getEmailSettings: (orgId: string, projectId: string) => Promise<EmailSettings>;
+    /**
+     * Updates email configuration
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @param settings - Email settings
+     */
+    updateEmailSettings: (orgId: string, projectId: string, settings: EmailSettings) => Promise<EmailSettings>;
+    /**
+     * Gets OAuth settings for a project
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     */
+    getOAuthSettings: (orgId: string, projectId: string) => Promise<OAuthSettings>;
+    /**
+     * Updates OAuth configuration
+     * @param orgId - Organization ID
+     * @param projectId - Project ID
+     * @param settings - OAuth settings
+     */
+    updateOAuthSettings: (orgId: string, projectId: string, settings: OAuthSettings) => Promise<OAuthSettings>;
+    /**
+     * Creates an invitation to join an organization
+     * @param orgId - Organization ID
+     * @param email - Developer's email address
+     * @param role - Role to assign (defaults to "admin")
+     */
+    inviteDeveloper: (orgId: string, email: string, role?: string) => Promise<OrganizationInvite>;
+    /**
+     * Lists all members of an organization
+     * @param orgId - Organization ID
+     */
+    listOrganizationMembers: (orgId: string) => Promise<OrganizationMember[]>;
+    /**
+     * Lists all pending invitations for an organization
+     * @param orgId - Organization ID
+     */
+    listOrganizationInvites: (orgId: string) => Promise<OrganizationInvite[]>;
+    /**
+     * Gets a specific invitation by code
+     * @param orgId - Organization ID
+     * @param inviteCode - Invitation UUID code
+     */
+    getOrganizationInvite: (orgId: string, inviteCode: string) => Promise<OrganizationInvite>;
+    /**
+     * Deletes an invitation
+     * @param orgId - Organization ID
+     * @param inviteCode - Invitation UUID code
+     */
+    deleteOrganizationInvite: (orgId: string, inviteCode: string) => Promise<{
+        message: string;
+    }>;
+    /**
+     * Updates a member's role
+     * @param orgId - Organization ID
+     * @param userId - User ID to update
+     * @param role - New role to assign
+     */
+    updateMemberRole: (orgId: string, userId: string, role: string) => Promise<OrganizationMember>;
+    /**
+     * Removes a member from the organization
+     * @param orgId - Organization ID
+     * @param userId - User ID to remove
+     */
+    removeMember: (orgId: string, userId: string) => Promise<void>;
+    /**
+     * Accepts an organization invitation
+     * @param code - Invitation UUID code
+     */
+    acceptInvite: (code: string) => Promise<{
+        message: string;
+    }>;
+    /**
+     * Returns the current OpenSecret developer API URL being used
+     */
+    apiUrl: string;
+};
+
 /**
  * Provider component for OpenSecret authentication and key-value storage.
  *
@@ -523,6 +928,30 @@ export declare function OpenSecretProvider({ children, apiUrl, clientId, pcrConf
     pcrConfig?: PcrConfig;
 }): JSX_2.Element;
 
+declare type Organization = {
+    id: string;
+    name: string;
+};
+
+export declare type OrganizationDetails = Organization;
+
+declare type OrganizationInvite = {
+    code: string;
+    email: string;
+    role: string;
+    used: boolean;
+    expires_at: string;
+    created_at: string;
+    updated_at: string;
+    organization_name?: string;
+};
+
+declare type OrganizationMember = {
+    user_id: string;
+    role: string;
+    name?: string;
+};
+
 export declare type ParsedAttestationView = {
     moduleId: string;
     publicKey: string | null;
@@ -555,6 +984,109 @@ export declare type PcrConfig = {
     pcr0DevValues?: string[];
 };
 
+declare namespace platformApi {
+    export {
+        setPlatformApiUrl,
+        getPlatformApiUrl,
+        platformLogin,
+        platformRegister,
+        platformLogout,
+        platformRefreshToken,
+        createOrganization,
+        listOrganizations,
+        deleteOrganization,
+        createProject,
+        listProjects,
+        getProject,
+        updateProject,
+        deleteProject,
+        createProjectSecret,
+        listProjectSecrets,
+        deleteProjectSecret,
+        getEmailSettings,
+        updateEmailSettings,
+        getOAuthSettings,
+        updateOAuthSettings,
+        inviteDeveloper,
+        listOrganizationInvites,
+        getOrganizationInvite,
+        deleteOrganizationInvite,
+        listOrganizationMembers,
+        updateMemberRole,
+        removeMember,
+        acceptInvite,
+        platformMe,
+        PlatformLoginResponse,
+        PlatformRefreshResponse,
+        PlatformOrg,
+        PlatformUser,
+        MeResponse,
+        Organization,
+        OrganizationInvite,
+        Project,
+        ProjectSecret,
+        ProjectSettings,
+        EmailSettings,
+        OAuthProviderSettings,
+        OAuthSettings,
+        OrganizationMember
+    }
+}
+
+declare function platformLogin(email: string, password: string): Promise<PlatformLoginResponse>;
+
+declare type PlatformLoginResponse = {
+    id: string;
+    email: string;
+    name?: string;
+    access_token: string;
+    refresh_token: string;
+};
+
+declare function platformLogout(refresh_token: string): Promise<void>;
+
+declare function platformMe(): Promise<MeResponse>;
+
+declare type PlatformOrg = {
+    id: string;
+    name: string;
+    role?: string;
+    created_at?: string;
+    updated_at?: string;
+};
+
+declare type PlatformRefreshResponse = {
+    access_token: string;
+    refresh_token: string;
+};
+
+/**
+ * Refreshes platform access and refresh tokens
+ *
+ * This function:
+ * 1. Gets the refresh token from localStorage
+ * 2. Calls the platform-specific refresh endpoint (/platform/refresh)
+ * 3. Updates localStorage with the new tokens
+ *
+ * The platform refresh endpoint expects:
+ * - A refresh token with audience "platform_refresh" in the request body
+ * - The request to be encrypted according to the platform's encryption scheme
+ *
+ * It returns new access and refresh tokens if validation succeeds.
+ */
+declare function platformRefreshToken(): Promise<PlatformRefreshResponse>;
+
+declare function platformRegister(email: string, password: string, name?: string): Promise<PlatformLoginResponse>;
+
+declare type PlatformUser = {
+    id: string;
+    email: string;
+    name?: string;
+    email_verified: boolean;
+    created_at: string;
+    updated_at: string;
+};
+
 declare type PrivateKeyBytesResponse = {
     /** 32-byte hex string (64 characters) representing the private key */
     private_key: string;
@@ -565,6 +1097,30 @@ declare type PrivateKeyResponse = {
     mnemonic: string;
 };
 
+declare type Project = {
+    id: string;
+    client_id: string;
+    name: string;
+    description?: string;
+    status: string;
+    created_at: string;
+};
+
+export declare type ProjectDetails = Project;
+
+declare type ProjectSecret = {
+    key_name: string;
+    created_at: string;
+    updated_at: string;
+};
+
+export declare type ProjectSettings = {
+    category: string;
+    settings: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+};
+
 declare type PublicKeyResponse = {
     /** Public key in hex format */
     public_key: string;
@@ -579,12 +1135,16 @@ declare type RefreshResponse = {
 
 declare function refreshToken(): Promise<RefreshResponse>;
 
+declare function removeMember(orgId: string, userId: string): Promise<void>;
+
 declare function requestNewVerificationCode(): Promise<void>;
 
 declare function requestPasswordReset(email: string, hashedSecret: string, client_id: string): Promise<void>;
 
 declare function setApiUrl(url: string): void;
 
+declare function setPlatformApiUrl(url: string): void;
+
 declare type SigningAlgorithm = "schnorr" | "ecdsa";
 
 /**
@@ -628,8 +1188,22 @@ declare type ThirdPartyTokenResponse = {
     token: string;
 };
 
+declare function updateEmailSettings(orgId: string, projectId: string, settings: EmailSettings): Promise<EmailSettings>;
+
+declare function updateMemberRole(orgId: string, userId: string, role: string): Promise<OrganizationMember>;
+
+declare function updateOAuthSettings(orgId: string, projectId: string, settings: OAuthSettings): Promise<OAuthSettings>;
+
+declare function updateProject(orgId: string, projectId: string, updates: {
+    name?: string;
+    description?: string;
+    status?: string;
+}): Promise<Project>;
+
 export declare function useOpenSecret(): OpenSecretContextType;
 
+export declare function useOpenSecretDeveloper(): OpenSecretDeveloperContextType;
+
 export declare type UserResponse = {
     user: {
         id: string;