@egintegrations/auth-services 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-22
+
+### Added
+- Initial release of @egintegrations/auth-services
+- TokenManager - Generic token storage with secure store
+- SingletonTokenManager - Singleton pattern for simple token management
+- BiometricAuth - Configurable biometric authentication (Face ID / Touch ID)
+- SecureKeyStore - Generic secure key/value storage with prefix support
+- Convenience functions for direct secure storage access
+- Comprehensive test suite with 100% coverage (69 tests)
+- Full TypeScript support with type definitions
+- ESM and CommonJS module support
+
+### Notes
+- Extracted from AutismTrainerApp authentication services
+- Refactored to be configurable and reusable
+- TokenManager supports custom storage keys
+- BiometricAuth supports custom prompt messages and fallback labels
+- SecureKeyStore supports key prefixes for namespace isolation
+- Removed app-specific user management and role-based access control
+- Works with Expo and bare React Native applications

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EGI Integrations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,554 @@
+# @egintegrations/auth-services
+
+React Native authentication utilities for token management, biometric authentication, and secure key storage. Works with Expo and bare React Native.
+
+## Features
+
+- **TokenManager**: Secure token storage and retrieval
+- **BiometricAuth**: Face ID / Touch ID authentication
+- **SecureKeyStore**: Generic secure key/value storage
+- **TypeScript**: Full type safety with TypeScript support
+- **Configurable**: Customizable storage keys, prompts, and behavior
+- **Well-tested**: 100% test coverage (69 tests)
+- **Dual Module**: ESM and CommonJS support
+
+## Installation
+
+```bash
+npm install @egintegrations/auth-services expo-secure-store expo-local-authentication
+```
+
+### Peer Dependencies
+
+This package requires:
+- `expo-secure-store` >= 12.0.0
+- `expo-local-authentication` >= 13.0.0  
+- `react-native` >= 0.70.0
+
+## Quick Start
+
+```typescript
+import { TokenManager, BiometricAuth, SecureKeyStore } from '@egintegrations/auth-services';
+
+// Token management
+const tokenManager = new TokenManager();
+await tokenManager.saveToken('your-auth-token');
+const token = await tokenManager.getToken();
+
+// Biometric authentication
+const bioAuth = new BiometricAuth();
+if (await bioAuth.canAuthenticate()) {
+  await bioAuth.enable('username');
+  const username = await bioAuth.authenticate();
+}
+
+// Secure key storage
+const keyStore = new SecureKeyStore({ keyPrefix: 'app_' });
+await keyStore.set('api_key', 'secret-key');
+const apiKey = await keyStore.get('api_key');
+```
+
+## TokenManager
+
+Manages authentication tokens in secure storage.
+
+### Basic Usage
+
+```typescript
+import { TokenManager } from '@egintegrations/auth-services';
+
+// Create manager with default storage key
+const tokenManager = new TokenManager();
+
+// Save token
+await tokenManager.saveToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+
+// Get token
+const token = await tokenManager.getToken();
+
+// Check if token exists
+const hasToken = await tokenManager.hasToken();
+
+// Clear token
+await tokenManager.clearToken();
+```
+
+### Custom Storage Key
+
+```typescript
+// Use custom storage key for multiple token types
+const accessTokenManager = new TokenManager({ storageKey: 'access_token' });
+const refreshTokenManager = new TokenManager({ storageKey: 'refresh_token' });
+
+await accessTokenManager.saveToken('access-token-123');
+await refreshTokenManager.saveToken('refresh-token-456');
+```
+
+### Singleton Pattern
+
+For simple apps with single token:
+
+```typescript
+import { SingletonTokenManager } from '@egintegrations/auth-services';
+
+// All methods are static
+await SingletonTokenManager.saveToken('token');
+const token = await SingletonTokenManager.getToken();
+const hasToken = await SingletonTokenManager.hasToken();
+await SingletonTokenManager.clearToken();
+```
+
+## BiometricAuth
+
+Manages biometric authentication (Face ID / Touch ID).
+
+### Check Availability
+
+```typescript
+import { BiometricAuth } from '@egintegrations/auth-services';
+
+const bioAuth = new BiometricAuth();
+
+// Check if device supports biometric auth
+const canAuth = await bioAuth.canAuthenticate();
+
+// Get biometric type
+const type = await bioAuth.getBiometricType(); // 'faceId' | 'touchId' | 'fingerprint' | 'none'
+```
+
+### Enable Biometric Login
+
+```typescript
+const bioAuth = new BiometricAuth();
+
+try {
+  // Prompt user to authenticate and enable biometric login
+  await bioAuth.enable('username');
+  console.log('Biometric login enabled');
+} catch (error) {
+  console.error('Failed to enable biometric:', error.message);
+}
+```
+
+### Authenticate with Biometrics
+
+```typescript
+const bioAuth = new BiometricAuth();
+
+try {
+  // Prompt biometric authentication
+  const username = await bioAuth.authenticate();
+  console.log('Authenticated as:', username);
+} catch (error) {
+  console.error('Authentication failed:', error.message);
+}
+```
+
+### Custom Prompts
+
+```typescript
+const bioAuth = new BiometricAuth({
+  promptMessages: {
+    enable: 'Enable Face ID for MyApp',
+    authenticate: 'Sign in to MyApp',
+  },
+  fallbackLabel: 'Use Password',
+});
+
+await bioAuth.enable('user@example.com');
+const username = await bioAuth.authenticate();
+```
+
+### Manage Saved Username
+
+```typescript
+const bioAuth = new BiometricAuth();
+
+// Save username without prompting
+await bioAuth.saveUsername('newuser@example.com');
+
+// Get saved username (only if biometric is enabled)
+const savedUsername = await bioAuth.getSavedUsername();
+
+// Clear saved username
+await bioAuth.clearSavedUsername();
+
+// Disable biometric completely
+await bioAuth.disable();
+```
+
+### Complete Login Flow Example
+
+```typescript
+import { BiometricAuth, TokenManager } from '@egintegrations/auth-services';
+
+const bioAuth = new BiometricAuth();
+const tokenManager = new TokenManager();
+
+async function loginWithBiometric() {
+  try {
+    // Check if biometric is enabled
+    const isEnabled = await bioAuth.isEnabled();
+    
+    if (!isEnabled) {
+      console.log('Biometric not enabled, use password login');
+      return;
+    }
+
+    // Authenticate
+    const username = await bioAuth.authenticate();
+    
+    // Call your API to get token
+    const response = await fetch('https://api.example.com/auth/biometric', {
+      method: 'POST',
+      body: JSON.stringify({ username }),
+    });
+    
+    const { token } = await response.json();
+    
+    // Save token
+    await tokenManager.saveToken(token);
+    
+    console.log('Logged in as:', username);
+  } catch (error) {
+    console.error('Biometric login failed:', error.message);
+  }
+}
+```
+
+## SecureKeyStore
+
+Generic secure key-value storage with namespace support.
+
+### Basic Usage
+
+```typescript
+import { SecureKeyStore } from '@egintegrations/auth-services';
+
+const store = new SecureKeyStore();
+
+// Store value
+await store.set('api_key', 'sk-1234567890');
+
+// Retrieve value
+const apiKey = await store.get('api_key');
+
+// Check if key exists
+const hasKey = await store.has('api_key');
+
+// Delete key
+await store.delete('api_key');
+```
+
+### Namespace Isolation
+
+```typescript
+// Create separate stores for different purposes
+const apiStore = new SecureKeyStore({ keyPrefix: 'api_' });
+const userStore = new SecureKeyStore({ keyPrefix: 'user_' });
+
+await apiStore.set('openai_key', 'sk-...');
+await userStore.set('preference', 'dark_mode');
+
+// Keys are isolated
+const apiKeys = await apiStore.get('openai_key'); // Works
+const userKeys = await userStore.get('openai_key'); // null (different namespace)
+```
+
+### Clear Multiple Keys
+
+```typescript
+const store = new SecureKeyStore({ keyPrefix: 'app_' });
+
+await store.set('key1', 'value1');
+await store.set('key2', 'value2');
+await store.set('key3', 'value3');
+
+// Clear specific keys
+await store.clear(['key1', 'key2']);
+```
+
+### Convenience Functions
+
+For simple use cases without creating a store instance:
+
+```typescript
+import {
+  getSecureKey,
+  setSecureKey,
+  deleteSecureKey,
+  hasSecureKey,
+} from '@egintegrations/auth-services';
+
+// Direct access to secure storage (no prefix)
+await setSecureKey('my_key', 'my_value');
+const value = await getSecureKey('my_key');
+const exists = await hasSecureKey('my_key');
+await deleteSecureKey('my_key');
+```
+
+## Advanced Examples
+
+### Complete Authentication System
+
+```typescript
+import {
+  TokenManager,
+  BiometricAuth,
+  SecureKeyStore,
+} from '@egintegrations/auth-services';
+
+class AuthService {
+  private tokenManager = new TokenManager();
+  private bioAuth = new BiometricAuth({
+    promptMessages: {
+      enable: 'Enable Face ID for faster login',
+      authenticate: 'Authenticate to continue',
+    },
+  });
+  private keyStore = new SecureKeyStore({ keyPrefix: 'auth_' });
+
+  async login(username: string, password: string): Promise<void> {
+    // Call your API
+    const response = await fetch('https://api.example.com/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password }),
+    });
+
+    const { token } = await response.json();
+
+    // Save token
+    await this.tokenManager.saveToken(token);
+
+    // Offer biometric enrollment if available
+    const canAuth = await this.bioAuth.canAuthenticate();
+    if (canAuth) {
+      await this.bioAuth.enable(username);
+    }
+  }
+
+  async loginWithBiometric(): Promise<void> {
+    const username = await this.bioAuth.authenticate();
+
+    // Exchange biometric authentication for token
+    const response = await fetch('https://api.example.com/auth/biometric', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username }),
+    });
+
+    const { token } = await response.json();
+    await this.tokenManager.saveToken(token);
+  }
+
+  async logout(): Promise<void> {
+    await this.tokenManager.clearToken();
+    // Keep biometric enabled for next login
+  }
+
+  async getAuthToken(): Promise<string | null> {
+    return this.tokenManager.getToken();
+  }
+
+  async isAuthenticated(): Promise<boolean> {
+    return this.tokenManager.hasToken();
+  }
+
+  async saveApiKey(service: string, key: string): Promise<void> {
+    await this.keyStore.set(`${service}_key`, key);
+  }
+
+  async getApiKey(service: string): Promise<string | null> {
+    return this.keyStore.get(`${service}_key`);
+  }
+}
+
+// Usage
+const auth = new AuthService();
+
+// Normal login
+await auth.login('user@example.com', 'password123');
+
+// Biometric login
+if (await auth.bioAuth.canAuthenticate()) {
+  await auth.loginWithBiometric();
+}
+
+// Get auth token for API calls
+const token = await auth.getAuthToken();
+```
+
+### API Integration with TokenManager
+
+```typescript
+import { TokenManager } from '@egintegrations/auth-services';
+import { ApiClient } from '@egintegrations/api-client';
+
+const tokenManager = new TokenManager();
+
+// Create API client
+const apiClient = new ApiClient({
+  baseUrl: 'https://api.example.com',
+});
+
+// Add token to all requests
+apiClient.addRequestInterceptor(async (config) => {
+  const token = await tokenManager.getToken();
+  if (token) {
+    config.headers = config.headers || {};
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// Handle 401 errors
+apiClient.addErrorInterceptor(async (error) => {
+  if (error.response?.status === 401) {
+    await tokenManager.clearToken();
+    // Redirect to login
+  }
+  throw error;
+});
+```
+
+## API Reference
+
+### TokenManager
+
+#### Constructor
+```typescript
+new TokenManager(config?: TokenManagerConfig)
+```
+
+**Config:**
+- `storageKey?: string` - Storage key (default: 'auth_token')
+
+#### Methods
+- `getToken(): Promise<string | null>` - Get stored token
+- `saveToken(token: string): Promise<void>` - Save token
+- `clearToken(): Promise<void>` - Delete token
+- `hasToken(): Promise<boolean>` - Check if token exists
+
+### SingletonTokenManager
+
+Static methods matching TokenManager interface.
+
+### BiometricAuth
+
+#### Constructor
+```typescript
+new BiometricAuth(config?: BiometricAuthConfig)
+```
+
+**Config:**
+- `savedUsernameKey?: string` - Username storage key (default: 'biometric_username')
+- `enabledKey?: string` - Enabled flag key (default: 'biometric_enabled')
+- `promptMessages?: { enable?: string, authenticate?: string }` - Custom prompts
+- `fallbackLabel?: string` - Fallback button label (default: 'Use password')
+
+#### Methods
+- `canAuthenticate(): Promise<boolean>` - Check device support
+- `isEnabled(): Promise<boolean>` - Check if biometric enabled
+- `enable(username: string): Promise<void>` - Enable biometric login
+- `disable(): Promise<void>` - Disable biometric login
+- `getBiometricType(): Promise<BiometricType>` - Get biometric type
+- `authenticate(): Promise<string>` - Authenticate and get username
+- `saveUsername(username: string): Promise<void>` - Save username
+- `clearSavedUsername(): Promise<void>` - Clear username
+- `getSavedUsername(): Promise<string | null>` - Get saved username
+
+### SecureKeyStore
+
+#### Constructor
+```typescript
+new SecureKeyStore(config?: SecureKeyStoreConfig)
+```
+
+**Config:**
+- `keyPrefix?: string` - Key prefix for namespace isolation (default: 'secure_key_')
+
+#### Methods
+- `get(key: string): Promise<string | null>` - Get value
+- `set(key: string, value: string): Promise<void>` - Set value
+- `delete(key: string): Promise<void>` - Delete key
+- `has(key: string): Promise<boolean>` - Check if key exists
+- `clear(keys?: string[]): Promise<void>` - Clear multiple keys
+
+## Error Handling
+
+All methods can throw errors. Always use try-catch:
+
+```typescript
+try {
+  await tokenManager.saveToken(token);
+} catch (error) {
+  console.error('Failed to save token:', error);
+}
+
+try {
+  const username = await bioAuth.authenticate();
+} catch (error) {
+  console.error('Biometric auth failed:', error.message);
+  // Handle failure (show password login)
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass (`npm test`)
+2. Code coverage remains 100%
+3. TypeScript types are properly defined
+4. Code follows the existing style (run `npm run lint`)
+
+## License
+
+MIT © EGI Integrations
+
+## Extracted From
+
+This package was extracted from AutismTrainerApp's authentication services and refactored to be reusable across React Native applications.
+
+**What was removed:**
+- App-specific user management (roles, permissions, progress tracking)
+- Local user database and AsyncStorage user management
+- Supervised user relationships
+- Application-specific authentication flows
+
+**What was kept and improved:**
+- Token management (now configurable)
+- Biometric authentication (now with custom prompts)
+- Secure key storage (now with namespace support)
+
+## Related Packages
+
+- [@egintegrations/api-client](https://www.npmjs.com/package/@egintegrations/api-client) - HTTP client for API integrations
+- [@egintegrations/core-utils](https://www.npmjs.com/package/@egintegrations/core-utils) - Utility functions
+
+## Support
+
+For issues and questions, please open an issue on [GitHub](https://github.com/EGIntegrations/egi-comp-library/issues).

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+interface TokenManagerConfig {
+    storageKey?: string;
+}
+declare class TokenManager {
+    private storageKey;
+    constructor(config?: TokenManagerConfig);
+    getToken(): Promise<string | null>;
+    saveToken(token: string): Promise<void>;
+    clearToken(): Promise<void>;
+    hasToken(): Promise<boolean>;
+}
+declare class SingletonTokenManager {
+    private static instance;
+    private static defaultKey;
+    private constructor();
+    static getInstance(storageKey?: string): TokenManager;
+    static getToken(): Promise<string | null>;
+    static saveToken(token: string): Promise<void>;
+    static clearToken(): Promise<void>;
+    static hasToken(): Promise<boolean>;
+}
+
+interface BiometricAuthConfig {
+    savedUsernameKey?: string;
+    enabledKey?: string;
+    promptMessages?: {
+        enable?: string;
+        authenticate?: string;
+    };
+    fallbackLabel?: string;
+}
+type BiometricType = 'faceId' | 'touchId' | 'fingerprint' | 'none';
+declare class BiometricAuth {
+    private savedUsernameKey;
+    private enabledKey;
+    private promptMessages;
+    private fallbackLabel;
+    constructor(config?: BiometricAuthConfig);
+    canAuthenticate(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
+    enable(username: string): Promise<void>;
+    disable(): Promise<void>;
+    getBiometricType(): Promise<BiometricType>;
+    authenticate(): Promise<string>;
+    saveUsername(username: string): Promise<void>;
+    clearSavedUsername(): Promise<void>;
+    getSavedUsername(): Promise<string | null>;
+}
+
+interface SecureKeyStoreConfig {
+    keyPrefix?: string;
+}
+declare class SecureKeyStore {
+    private keyPrefix;
+    constructor(config?: SecureKeyStoreConfig);
+    private getFullKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    clear(keys?: string[]): Promise<void>;
+}
+declare function getSecureKey(key: string): Promise<string | null>;
+declare function setSecureKey(key: string, value: string): Promise<void>;
+declare function deleteSecureKey(key: string): Promise<void>;
+declare function hasSecureKey(key: string): Promise<boolean>;
+
+export { BiometricAuth, type BiometricAuthConfig, type BiometricType, SecureKeyStore, type SecureKeyStoreConfig, SingletonTokenManager, TokenManager, type TokenManagerConfig, deleteSecureKey, getSecureKey, hasSecureKey, setSecureKey };