@cedros/login-react 0.0.1

package/dist/utils/apiClient.d.ts

@@ -0,0 +1,78 @@
+import { AuthError } from '../types';
+export interface ApiClientConfig {
+    baseUrl: string;
+    timeoutMs?: number;
+    retryAttempts?: number;
+    getAccessToken?: () => string | null;
+}
+/**
+ * M-02: Response validator function type.
+ * Returns the validated data or throws on invalid shape.
+ */
+export type ResponseValidator<T> = (data: unknown) => T;
+export interface RequestOptions<T = unknown> {
+    method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    credentials?: RequestCredentials;
+    skipRetry?: boolean;
+    /** M-02: Optional validator to verify response shape at runtime */
+    validator?: ResponseValidator<T>;
+}
+/**
+ * Creates an authentication error from response data
+ */
+export declare function createAuthError(data: {
+    code?: string;
+    message?: string;
+    details?: Record<string, unknown>;
+}, fallbackMessage: string): AuthError;
+/**
+ * Creates a network error
+ */
+export declare function createNetworkError(): AuthError;
+/**
+ * API client for making authenticated requests with timeout and retry support
+ */
+export declare class ApiClient {
+    private baseUrl;
+    private timeoutMs;
+    private retryAttempts;
+    private getAccessToken?;
+    constructor(config: ApiClientConfig);
+    /**
+     * Make an API request with timeout and optional retry
+     */
+    request<T>(options: RequestOptions<T>): Promise<T>;
+    /**
+     * POST request helper
+     */
+    post<T>(path: string, body: unknown, options?: Partial<RequestOptions<T>>): Promise<T>;
+    /**
+     * GET request helper
+     */
+    get<T>(path: string, options?: Partial<RequestOptions<T>>): Promise<T>;
+    /**
+     * PATCH request helper
+     */
+    patch<T>(path: string, body: unknown, options?: Partial<RequestOptions<T>>): Promise<T>;
+    /**
+     * DELETE request helper
+     */
+    delete<T>(path: string, options?: Partial<RequestOptions<T>>): Promise<T>;
+}
+/**
+ * M-02: Helper to create a basic object shape validator.
+ * Checks that required keys exist and are of expected types.
+ * @example
+ * const validateUser = createValidator<User>({
+ *   id: 'string',
+ *   email: 'string',
+ *   role: 'string',
+ * });
+ */
+export declare function createValidator<T>(shape: Record<keyof T & string, 'string' | 'number' | 'boolean' | 'object'>): ResponseValidator<T>;
+/**
+ * Converts API errors to AuthError format
+ */
+export declare function handleApiError(err: unknown, fallbackMessage: string): AuthError;

package/dist/utils/cryptoShim.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shim for Node's `crypto` module.
+ * Maps `require('crypto')` / `import 'crypto'` to Web Crypto API in the browser.
+ * Used by vite.config.ts alias to support CJS dependencies that expect Node crypto.
+ */
+declare const _default: Crypto;
+export default _default;
+export declare const webcrypto: Crypto;
+export declare const subtle: SubtleCrypto;
+export declare const getRandomValues: {
+    <T extends ArrayBufferView>(array: T): T;
+    <T extends ArrayBufferView>(array: T): T;
+};
+export declare const randomUUID: {
+    (): `${string}-${string}-${string}-${string}-${string}`;
+    (): `${string}-${string}-${string}-${string}-${string}`;
+};

package/dist/utils/csrf.d.ts

@@ -0,0 +1 @@
+export declare function getCsrfToken(): string | null;

package/dist/utils/deviceDetection.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Device detection utilities
+ */
+/**
+ * Detects if the current device is an Apple device (macOS, iOS, iPadOS).
+ * Apple Sign In is most useful on Apple devices where users have Apple ID readily available.
+ *
+ * @returns true if running on an Apple device
+ *
+ * @example
+ * ```tsx
+ * if (isAppleDevice()) {
+ *   // Show Apple Sign In button
+ * }
+ * ```
+ */
+export declare function isAppleDevice(): boolean;

package/dist/utils/embeddedWallet.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Embedded wallet detection utilities
+ *
+ * Allows other Cedros modules (like cedros-pay) to detect if an embedded
+ * wallet is available in the current application.
+ *
+ * @security The window global only exposes availability info, NOT the signing
+ * function. Signing must go through React context to prevent unauthorized access.
+ */
+/** Window global name for embedded wallet detection */
+declare const GLOBAL_KEY = "__CEDROS_EMBEDDED_WALLET__";
+/**
+ * Embedded wallet info exposed via window global
+ */
+export interface EmbeddedWalletInfo {
+    /** Whether user has enrolled SSS embedded wallet */
+    available: boolean;
+    /** Solana public key (base58) if available */
+    publicKey: string | null;
+}
+declare global {
+    interface Window {
+        [GLOBAL_KEY]?: EmbeddedWalletInfo;
+    }
+}
+/**
+ * Set embedded wallet availability on window global
+ *
+ * Called by CedrosLoginProvider when wallet.exposeAvailability is true.
+ *
+ * @internal
+ */
+export declare function setEmbeddedWalletGlobal(info: EmbeddedWalletInfo): void;
+/**
+ * Clear embedded wallet availability from window global
+ *
+ * Called when user logs out or config changes.
+ *
+ * @internal
+ */
+export declare function clearEmbeddedWalletGlobal(): void;
+/**
+ * Check if embedded wallet is available
+ *
+ * Use this in other Cedros modules (like cedros-pay) to detect
+ * if an embedded wallet is available for signing.
+ *
+ * @example
+ * ```tsx
+ * import { isEmbeddedWalletAvailable, getEmbeddedWalletInfo } from '@cedros/login-react';
+ *
+ * // Simple check
+ * if (isEmbeddedWalletAvailable()) {
+ *   // Show "Pay with Crypto" button
+ * }
+ *
+ * // Get full info
+ * const walletInfo = getEmbeddedWalletInfo();
+ * if (walletInfo?.available && walletInfo.publicKey) {
+ *   console.log('User wallet:', walletInfo.publicKey);
+ * }
+ * ```
+ *
+ * @returns true if embedded wallet is enrolled and available
+ */
+export declare function isEmbeddedWalletAvailable(): boolean;
+/**
+ * Get embedded wallet info
+ *
+ * Returns the full wallet info object if available.
+ *
+ * @returns Wallet info or null if not exposed
+ */
+export declare function getEmbeddedWalletInfo(): EmbeddedWalletInfo | null;
+export {};

package/dist/utils/inviteApi.d.ts

@@ -0,0 +1,31 @@
+import { Invite, CreateInviteRequest, AcceptInviteRequest, CreateInviteResponse, AcceptInviteResponse } from '../types';
+/**
+ * API client for invite operations
+ */
+export declare class InviteApiClient {
+    private client;
+    constructor(baseUrl: string, timeoutMs?: number, retryAttempts?: number, getAccessToken?: () => string | null);
+    /**
+     * List all pending invites for an organization
+     */
+    listInvites(orgId: string, limit?: number, offset?: number): Promise<{
+        invites: Invite[];
+        total: number;
+    }>;
+    /**
+     * Create a new invite
+     */
+    createInvite(orgId: string, data: CreateInviteRequest): Promise<CreateInviteResponse>;
+    /**
+     * Cancel a pending invite
+     */
+    cancelInvite(orgId: string, inviteId: string): Promise<void>;
+    /**
+     * Resend an invite email
+     */
+    resendInvite(orgId: string, inviteId: string): Promise<void>;
+    /**
+     * Accept an invite (public endpoint)
+     */
+    acceptInvite(data: AcceptInviteRequest): Promise<AcceptInviteResponse>;
+}

package/dist/utils/memberApi.d.ts

@@ -0,0 +1,23 @@
+import { Member, UpdateMemberRoleRequest } from '../types';
+/**
+ * API client for member operations within an organization
+ */
+export declare class MemberApiClient {
+    private client;
+    constructor(baseUrl: string, timeoutMs?: number, retryAttempts?: number, getAccessToken?: () => string | null);
+    /**
+     * List all members of an organization
+     */
+    listMembers(orgId: string, limit?: number, offset?: number): Promise<{
+        members: Member[];
+        total: number;
+    }>;
+    /**
+     * Update a member's role
+     */
+    updateMemberRole(orgId: string, userId: string, data: UpdateMemberRoleRequest): Promise<Member>;
+    /**
+     * Remove a member from the organization
+     */
+    removeMember(orgId: string, userId: string): Promise<void>;
+}

package/dist/utils/orgApi.d.ts

@@ -0,0 +1,36 @@
+import { Organization, OrgWithMembership, CreateOrgRequest, UpdateOrgRequest, AuthorizeRequest, AuthorizeResponse, PermissionsResponse } from '../types';
+/**
+ * API client for organization operations
+ */
+export declare class OrgApiClient {
+    private client;
+    constructor(baseUrl: string, timeoutMs?: number, retryAttempts?: number, getAccessToken?: () => string | null);
+    /**
+     * List all organizations the current user belongs to
+     */
+    listOrgs(): Promise<OrgWithMembership[]>;
+    /**
+     * Get a single organization by ID
+     */
+    getOrg(orgId: string): Promise<Organization>;
+    /**
+     * Create a new organization
+     */
+    createOrg(data: CreateOrgRequest): Promise<Organization>;
+    /**
+     * Update an organization
+     */
+    updateOrg(orgId: string, data: UpdateOrgRequest): Promise<Organization>;
+    /**
+     * Delete an organization
+     */
+    deleteOrg(orgId: string): Promise<void>;
+    /**
+     * Check authorization for an action
+     */
+    authorize(data: AuthorizeRequest): Promise<AuthorizeResponse>;
+    /**
+     * Get current user's permissions in an organization
+     */
+    getPermissions(orgId: string): Promise<PermissionsResponse>;
+}

package/dist/utils/sanitization.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Input sanitization utilities for security
+ */
+/**
+ * Sanitizes an image URL to prevent XSS and other attacks.
+ *
+ * ## Security Properties
+ *
+ * - Only allows HTTPS URLs (prevents protocol-based attacks)
+ * - Blocks javascript:, data:, vbscript:, file: protocols
+ * - Returns undefined for invalid URLs
+ *
+ * ## Limitations (S-20/SEC-08)
+ *
+ * This function validates the URL protocol but does NOT validate the domain.
+ * Any HTTPS URL will pass validation, including URLs from untrusted domains.
+ * This is intentional - domain allowlisting is application-specific and should
+ * be implemented at the consumer level (see example below).
+ *
+ * If your application requires domain validation (e.g., only allowing images
+ * from trusted CDNs), implement additional validation:
+ *
+ * @example Domain allowlisting (application-level)
+ * ```ts
+ * const ALLOWED_DOMAINS = ['cdn.example.com', 'images.trusted.org'];
+ *
+ * function isAllowedImageUrl(url: string): boolean {
+ *   const sanitized = sanitizeImageUrl(url);
+ *   if (!sanitized) return false;
+ *
+ *   try {
+ *     const hostname = new URL(sanitized).hostname;
+ *     return ALLOWED_DOMAINS.some(d => hostname === d || hostname.endsWith('.' + d));
+ *   } catch {
+ *     return false;
+ *   }
+ * }
+ * ```
+ *
+ * @param url - The URL to sanitize
+ * @returns The sanitized URL or undefined if invalid
+ *
+ * @example Basic usage
+ * ```ts
+ * sanitizeImageUrl('https://example.com/avatar.png') // 'https://example.com/avatar.png'
+ * sanitizeImageUrl('javascript:alert(1)') // undefined
+ * sanitizeImageUrl('data:image/svg+xml,...') // undefined
+ * ```
+ */
+export declare function sanitizeImageUrl(url: string | undefined | null): string | undefined;
+/**
+ * Sanitizes an external link URL for use in href attributes.
+ *
+ * Security goals:
+ * - Block dangerous protocols (javascript:, data:, vbscript:, file:)
+ * - Only allow http/https absolute URLs
+ */
+export declare function sanitizeExternalUrl(url: string | undefined | null): string | undefined;
+/**
+ * Sanitizes user-provided text to prevent XSS in text content.
+ * Escapes HTML special characters.
+ *
+ * @param text - The text to sanitize
+ * @returns The sanitized text
+ */
+export declare function sanitizeText(text: string | undefined | null): string;

package/dist/utils/sessionApi.d.ts

@@ -0,0 +1,16 @@
+import { Session, RevokeAllSessionsResponse } from '../types';
+/**
+ * API client for session management operations
+ */
+export declare class SessionApiClient {
+    private client;
+    constructor(baseUrl: string, timeoutMs?: number, retryAttempts?: number, getAccessToken?: () => string | null);
+    /**
+     * List all active sessions for the current user
+     */
+    listSessions(): Promise<Session[]>;
+    /**
+     * Revoke all sessions (logout from all devices)
+     */
+    revokeAllSessions(): Promise<RevokeAllSessionsResponse>;
+}

package/dist/utils/silentWalletEnroll.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Silent wallet enrollment utility
+ *
+ * Performs wallet enrollment in the background without UI interaction.
+ * Used for auto-enrolling wallets during registration.
+ *
+ * Security: Uses the same Shamir Secret Sharing scheme as manual enrollment.
+ * The recovery phrase is not shown - user can retrieve it later if needed.
+ */
+export interface SilentEnrollOptions {
+    /** User's password for Share A encryption */
+    password: string;
+    /** Server base URL */
+    serverUrl: string;
+    /** Access token for authentication (optional if using cookies) */
+    accessToken?: string;
+    /** Request timeout in ms */
+    timeoutMs?: number;
+}
+export interface SilentEnrollResult {
+    success: boolean;
+    solanaPubkey?: string;
+    error?: string;
+}
+/**
+ * Silently enroll a wallet for a user
+ *
+ * This function performs the complete wallet enrollment process:
+ * 1. Generate 32-byte seed
+ * 2. Split into 3 Shamir shares (threshold 2)
+ * 3. Encrypt Share A with password-derived key (Argon2id)
+ * 4. Derive Solana public key from seed
+ * 5. Upload encrypted Share A + plaintext Share B to server
+ *
+ * The recovery phrase (Share C) is not returned - user can recover it
+ * later through the wallet recovery flow if needed.
+ *
+ * @param options - Enrollment options
+ * @returns Result with success status and Solana public key
+ */
+export declare function silentWalletEnroll(options: SilentEnrollOptions): Promise<SilentEnrollResult>;

package/dist/utils/systemSettingsApi.d.ts

@@ -0,0 +1,18 @@
+import { ListSystemSettingsResponse, UpdateSettingRequest, UpdateSystemSettingsResponse } from '../types';
+/**
+ * API client for system settings operations (admin only)
+ */
+export declare class SystemSettingsApiClient {
+    private client;
+    constructor(baseUrl: string, timeoutMs?: number, retryAttempts?: number, getAccessToken?: () => string | null);
+    /**
+     * Get all system settings grouped by category
+     * Requires system admin privileges
+     */
+    getSettings(): Promise<ListSystemSettingsResponse>;
+    /**
+     * Update one or more system settings
+     * Requires system admin privileges
+     */
+    updateSettings(settings: UpdateSettingRequest[]): Promise<UpdateSystemSettingsResponse>;
+}

package/dist/utils/tabSync.d.ts

@@ -0,0 +1,46 @@
+import { AuthUser } from '../types';
+type AuthSyncEvent = {
+    type: 'login';
+    user: AuthUser;
+} | {
+    type: 'logout';
+} | {
+    type: 'refresh';
+};
+type AuthSyncCallback = (event: AuthSyncEvent) => void;
+/**
+ * Cross-tab synchronization for auth state using BroadcastChannel
+ * UI-6 FIX: Use addEventListener/removeEventListener for proper cleanup.
+ */
+export declare class TabSync {
+    private channel;
+    private callback;
+    private boundHandler;
+    constructor();
+    /**
+     * Handle incoming sync messages
+     */
+    private handleMessage;
+    /**
+     * Set the callback for sync events from other tabs
+     */
+    setCallback(callback: AuthSyncCallback): void;
+    /**
+     * Broadcast login event to other tabs
+     */
+    broadcastLogin(user: AuthUser): void;
+    /**
+     * Broadcast logout event to other tabs
+     */
+    broadcastLogout(): void;
+    /**
+     * Broadcast token refresh event to other tabs
+     */
+    broadcastRefresh(): void;
+    /**
+     * Close the channel and clean up references
+     * UI-6: Use removeEventListener for proper cleanup
+     */
+    close(): void;
+}
+export {};

package/dist/utils/tokenManager.d.ts

@@ -0,0 +1,107 @@
+import { TokenPair, SessionStorage } from '../types';
+/**
+ * Token manager for storing and auto-refreshing tokens
+ *
+ * ## Security Warning: localStorage Storage
+ *
+ * When using `localStorage` or `sessionStorage`, tokens are stored in the browser
+ * and are **vulnerable to XSS attacks**. Any JavaScript running
+ * on your page (including third-party scripts, browser extensions, or malicious
+ * code injected via XSS) can read these tokens.
+ *
+ * **Recommendations:**
+ * - Use `cookie` storage with httpOnly cookies (tokens stored server-side)
+ * - If localStorage is required, implement strong Content Security Policy (CSP)
+ * - Sanitize all user input and output
+ * - Regularly audit third-party dependencies
+ *
+ * @example
+ * // Recommended: cookie storage (tokens in httpOnly cookies)
+ * const manager = new TokenManager('cookie');
+ *
+ * // Use with caution: localStorage (XSS vulnerable)
+ * const manager = new TokenManager('localStorage');
+ */
+export interface TokenManagerOptions {
+    /**
+     * Allow `localStorage`/`sessionStorage` token persistence.
+     *
+     * @security This is intentionally opt-in because these storage modes are vulnerable
+     * to XSS token theft.
+     */
+    allowWebStorage?: boolean;
+}
+export declare class TokenManager {
+    private storage;
+    private requestedStorage;
+    private storageKey;
+    private tokens;
+    private expiresAt;
+    private refreshTimer;
+    private onRefreshNeeded;
+    private onSessionExpired;
+    private onRefreshError;
+    private isDestroyed;
+    private allowWebStorage;
+    constructor(storage?: SessionStorage, persistKey?: string, options?: TokenManagerOptions);
+    /**
+     * S-18/UI-XSS: Warn about localStorage XSS vulnerability in all environments.
+     * Security warnings should not be suppressed in production - operators need
+     * to be aware of the security implications of their storage choices.
+     */
+    private warnIfLocalStorage;
+    /**
+     * Set the callback for when tokens need to be refreshed
+     */
+    setRefreshCallback(callback: () => Promise<void>): void;
+    /**
+     * Set the callback for when session expires
+     */
+    setSessionExpiredCallback(callback: () => void): void;
+    /**
+     * Set the callback for when token refresh fails
+     * This allows the UI to show an error message to the user
+     */
+    setRefreshErrorCallback(callback: (error: Error) => void): void;
+    /**
+     * Store tokens and schedule auto-refresh
+     */
+    setTokens(tokens: TokenPair): void;
+    /**
+     * Get the current access token
+     * UI-4 FIX: Store token in local variable before expiry check to eliminate TOCTOU race.
+     * UI-TOK-01 FIX: Check isDestroyed to prevent access after manager is cleaned up.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Get the current refresh token
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Clear stored tokens
+     */
+    clear(): void;
+    /**
+     * Check if tokens are stored
+     */
+    hasTokens(): boolean;
+    /**
+     * Destroy the token manager and clean up resources.
+     * Call this when unmounting components or cleaning up to prevent memory leaks.
+     * P-02: Also sets isDestroyed flag to prevent timer callbacks from executing.
+     */
+    destroy(): void;
+    /**
+     * Get time until token expiry in ms
+     */
+    getTimeUntilExpiry(): number;
+    private scheduleRefresh;
+    private cancelRefresh;
+    private loadFromStorage;
+    /**
+     * Validate that parsed data matches expected StoredTokenData structure
+     */
+    private isValidStoredTokenData;
+    private saveToStorage;
+    private clearStorage;
+}

package/dist/utils/unlockCredential.d.ts

@@ -0,0 +1,5 @@
+import { UnlockCredential, UnlockCredentialRequest } from '../types/wallet';
+/**
+ * Convert UnlockCredential to API request format.
+ */
+export declare function toCredentialRequest(credential: UnlockCredential): UnlockCredentialRequest;

package/dist/utils/validation.d.ts

@@ -0,0 +1,48 @@
+import { PasswordValidation } from '../types';
+/**
+ * Password validation rules:
+ * - Minimum 10 characters
+ * - At least 1 uppercase letter (A-Z)
+ * - At least 1 lowercase letter (a-z)
+ * - At least 1 number (0-9)
+ * - At least 1 special character (@$!%*?&#^())
+ *
+ * Note: All checks are performed regardless of early failures to prevent
+ * timing attacks that could reveal which requirements are met.
+ */
+export declare function validatePassword(password: string): PasswordValidation;
+/**
+ * Validate email format with robust validation.
+ *
+ * Validates:
+ * - Proper format with @ symbol
+ * - Valid characters in local and domain parts
+ * - Domain must have at least one dot (TLD required)
+ * - Maximum length per RFC 5321
+ *
+ * UI-13: Note on case normalization - This function validates format only,
+ * it does NOT normalize case. Per RFC 5321, local-part is technically
+ * case-sensitive (though most providers ignore case). Callers should
+ * normalize emails (e.g., toLowerCase) before API calls and storage.
+ *
+ * @param email - The email address to validate
+ * @returns true if the email format is valid
+ */
+export declare function validateEmail(email: string): boolean;
+/**
+ * Validate Solana public key format.
+ *
+ * A valid Solana public key:
+ * - Is 43-44 characters long (base58 encoding of 32 bytes)
+ * - Contains only valid base58 characters
+ *
+ * @param publicKey - The public key string to validate
+ * @returns true if the public key format is valid
+ *
+ * @example
+ * ```ts
+ * validateSolanaPublicKey('DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263') // true
+ * validateSolanaPublicKey('invalid') // false
+ * ```
+ */
+export declare function validateSolanaPublicKey(publicKey: string): boolean;

package/dist/utils/walletDetection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wallet detection utilities for Solana browser wallets
+ */
+/**
+ * Detects if any Solana wallet extensions are installed in the browser.
+ * Checks for common wallet adapters like Phantom, Solflare, Backpack, etc.
+ *
+ * @returns true if at least one Solana wallet is detected
+ *
+ * @example
+ * ```tsx
+ * if (detectSolanaWallets()) {
+ *   // Show Solana login button
+ * }
+ * ```
+ */
+export declare function detectSolanaWallets(): boolean;
+/**
+ * Returns list of detected Solana wallet names (for debugging/display)
+ *
+ * @returns Array of detected wallet provider names
+ */
+export declare function getDetectedWalletNames(): string[];