@tenxyte/core 0.1.5 → 0.9.0

package/src/modules/security.ts

@@ -1,122 +1,313 @@
-import { TenxyteHttpClient } from '../http/client';
-import { TokenPair } from '../types';
-
-export interface OtpRequestParams {
-    email?: string;
-    phone_country_code?: string;
-    phone_number?: string;
-    type: 'email_verification' | 'phone_verification' | 'password_reset';
-}
-
-export interface VerifyOtpEmailParams {
-    email: string;
-    code: string;
-}
-
-export interface VerifyOtpPhoneParams {
-    phone_country_code: string;
-    phone_number: string;
-    code: string;
-}
-
-export interface Setup2FAResponse {
-    qr_code_url: string;
-    secret: string;
-    backup_codes: string[];
-}
-
-export interface WebAuthnRegisterBeginResponse {
-    publicKey: any; // CredentialCreationOptions
-}
-
-export interface WebAuthnAuthenticateBeginResponse {
-    publicKey: any; // CredentialRequestOptions
-}
-
-export class SecurityModule {
-    constructor(private client: TenxyteHttpClient) { }
-
-    // --- OTP Verification --- //
-
-    async requestOtp(data: OtpRequestParams): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/otp/request/', data);
-    }
-
-    async verifyOtpEmail(data: VerifyOtpEmailParams): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/otp/verify/email/', data);
-    }
-
-    async verifyOtpPhone(data: VerifyOtpPhoneParams): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/otp/verify/phone/', data);
-    }
-
-    // --- TOTP / 2FA --- //
-
-    async get2FAStatus(): Promise<{ is_enabled: boolean; backup_codes_remaining: number }> {
-        return this.client.get('/api/v1/auth/2fa/status/');
-    }
-
-    async setup2FA(): Promise<Setup2FAResponse> {
-        return this.client.post<Setup2FAResponse>('/api/v1/auth/2fa/setup/');
-    }
-
-    async confirm2FA(totp_code: string): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/2fa/confirm/', { totp_code });
-    }
-
-    async disable2FA(totp_code: string, password?: string): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/2fa/disable/', { totp_code, password });
-    }
-
-    async regenerateBackupCodes(totp_code: string): Promise<{ backup_codes: string[] }> {
-        return this.client.post('/api/v1/auth/2fa/backup-codes/', { totp_code });
-    }
-
-    // --- Password Management --- //
-
-    async resetPasswordRequest(data: { email?: string; phone_country_code?: string; phone_number?: string }): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/password/reset/request/', data);
-    }
-
-    async resetPasswordConfirm(data: { otp_code: string; new_password: string; email?: string; phone_country_code?: string; phone_number?: string }): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/password/reset/confirm/', data);
-    }
-
-    async changePassword(data: { current_password: string; new_password: string }): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/password/change/', data);
-    }
-
-    async checkPasswordStrength(data: { password: string; email?: string }): Promise<{ score: number; feedback: string[] }> {
-        return this.client.post('/api/v1/auth/password/strength/', data);
-    }
-
-    async getPasswordRequirements(): Promise<any> {
-        return this.client.get('/api/v1/auth/password/requirements/');
-    }
-
-    // --- WebAuthn / Passkeys --- //
-
-    async registerWebAuthnBegin(): Promise<WebAuthnRegisterBeginResponse> {
-        return this.client.post<WebAuthnRegisterBeginResponse>('/api/v1/auth/webauthn/register/begin/');
-    }
-
-    async registerWebAuthnComplete(data: any): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/webauthn/register/complete/', data);
-    }
-
-    async authenticateWebAuthnBegin(data?: { email?: string }): Promise<WebAuthnAuthenticateBeginResponse> {
-        return this.client.post<WebAuthnAuthenticateBeginResponse>('/api/v1/auth/webauthn/authenticate/begin/', data || {});
-    }
-
-    async authenticateWebAuthnComplete(data: any): Promise<TokenPair> {
-        return this.client.post<TokenPair>('/api/v1/auth/webauthn/authenticate/complete/', data);
-    }
-
-    async listWebAuthnCredentials(): Promise<any[]> {
-        return this.client.get<any[]>('/api/v1/auth/webauthn/credentials/');
-    }
-
-    async deleteWebAuthnCredential(credentialId: string): Promise<void> {
-        return this.client.delete<void>(`/api/v1/auth/webauthn/credentials/${credentialId}/`);
-    }
-}
+import { TenxyteHttpClient } from '../http/client';
+import { TenxyteUser, TokenPair } from '../types';
+import { base64urlToBuffer, bufferToBase64url } from '../utils/base64url';
+
+export class SecurityModule {
+    constructor(private client: TenxyteHttpClient) { }
+
+    // ─── 2FA (TOTP) Management ───
+
+    /**
+     * Get the current 2FA status for the authenticated user.
+     * @returns Information about whether 2FA is enabled and how many backup codes remain.
+     */
+    async get2FAStatus(): Promise<{ is_enabled: boolean; backup_codes_remaining: number }> {
+        return this.client.get('/api/v1/auth/2fa/status/');
+    }
+
+    /**
+     * Start the 2FA enrollment process.
+     * @returns The secret key and QR code URL to be scanned by an Authenticator app.
+     */
+    async setup2FA(): Promise<{
+        message: string;
+        secret: string;
+        manual_entry_key: string;
+        qr_code: string;
+        provisioning_uri: string;
+        backup_codes: string[];
+        warning: string;
+    }> {
+        return this.client.post('/api/v1/auth/2fa/setup/');
+    }
+
+    /**
+     * Confirm the 2FA setup by providing the first TOTP code generated by the Authenticator app.
+     * @param totpCode - The 6-digit code.
+     */
+    async confirm2FA(totpCode: string): Promise<{
+        message: string;
+        is_enabled: boolean;
+        enabled_at: string;
+    }> {
+        return this.client.post('/api/v1/auth/2fa/confirm/', { totp_code: totpCode });
+    }
+
+    /**
+     * Disable 2FA for the current user.
+     * Usually requires re-authentication or providing the active password/totp code.
+     * @param totpCode - The current 6-digit code to verify intent.
+     * @param password - (Optional) The user's password if required by backend policy.
+     */
+    async disable2FA(totpCode: string, password?: string): Promise<{
+        message: string;
+        is_enabled: boolean;
+        disabled_at: string;
+        backup_codes_invalidated: boolean;
+    }> {
+        return this.client.post('/api/v1/auth/2fa/disable/', { totp_code: totpCode, password });
+    }
+
+    /**
+     * Invalidate old backup codes and explicitly generate a new batch.
+     * @param totpCode - An active TOTP code to verify intent.
+     */
+    async regenerateBackupCodes(totpCode: string): Promise<{
+        message: string;
+        backup_codes: string[];
+        codes_count: number;
+        generated_at?: string;
+        warning: string;
+    }> {
+        return this.client.post('/api/v1/auth/2fa/backup-codes/', { totp_code: totpCode });
+    }
+
+    // ─── Verification OTP (Email / Phone) ───
+
+    /**
+     * Request an OTP code to be dispatched to the user's primary contact method.
+     * @param type - The channel type ('email' or 'phone').
+     */
+    async requestOtp(type: 'email' | 'phone'): Promise<{
+        message: string;
+        otp_id: number;
+        expires_at: string;
+        channel: 'email' | 'phone';
+        masked_recipient: string;
+    }> {
+        return this.client.post('/api/v1/auth/otp/request/', { type: type === 'email' ? 'email_verification' : 'phone_verification' });
+    }
+
+    /**
+     * Verify an email confirmation OTP.
+     * @param code - The numeric code received via email.
+     */
+    async verifyOtpEmail(code: string): Promise<{
+        message: string;
+        email_verified: boolean;
+        verified_at: string;
+    }> {
+        return this.client.post('/api/v1/auth/otp/verify/email/', { code });
+    }
+
+    /**
+     * Verify a phone confirmation OTP (SMS dispatch).
+     * @param code - The numeric code received via SMS.
+     */
+    async verifyOtpPhone(code: string): Promise<{
+        message: string;
+        phone_verified: boolean;
+        verified_at: string;
+        phone_number: string;
+    }> {
+        return this.client.post('/api/v1/auth/otp/verify/phone/', { code });
+    }
+
+    // ─── Password Sub-module ───
+
+    /**
+     * Triggers a password reset flow, dispatching an OTP to the target.
+     * @param target - Either an email address or a phone configuration payload.
+     */
+    async resetPasswordRequest(target: { email: string } | { phone_country_code: string; phone_number: string }): Promise<{ message: string }> {
+        return this.client.post('/api/v1/auth/password/reset/request/', target);
+    }
+
+    /**
+     * Confirm a password reset using the OTP dispatched by `resetPasswordRequest`.
+     * @param data - The OTP code and the new matching password fields.
+     */
+    async resetPasswordConfirm(data: {
+        email?: string;
+        phone_country_code?: string;
+        phone_number?: string;
+        otp_code: string;
+        new_password: string;
+        confirm_password: string;
+    }): Promise<{ message: string }> {
+        return this.client.post('/api/v1/auth/password/reset/confirm/', data);
+    }
+
+    /**
+     * Change password for an already authenticated user.
+     * @param currentPassword - The existing password to verify intent.
+     * @param newPassword - The distinct new password.
+     */
+    async changePassword(currentPassword: string, newPassword: string): Promise<{ message: string }> {
+        return this.client.post('/api/v1/auth/password/change/', {
+            current_password: currentPassword,
+            new_password: newPassword,
+        });
+    }
+
+    /**
+     * Evaluate the strength of a potential password against backend policies.
+     * @param password - The password string to test.
+     * @param email - (Optional) The user's email to ensure the password doesn't contain it.
+     */
+    async checkPasswordStrength(password: string, email?: string): Promise<{
+        score: number;
+        strength: string;
+        is_valid: boolean;
+        errors: string[];
+        requirements: {
+            min_length: number;
+            require_lowercase: boolean;
+            require_uppercase: boolean;
+            require_numbers: boolean;
+            require_special: boolean;
+        };
+    }> {
+        return this.client.post('/api/v1/auth/password/strength/', { password, email });
+    }
+
+    /**
+     * Fetch the password complexity requirements enforced by the Tenxyte backend.
+     */
+    async getPasswordRequirements(): Promise<{
+        requirements: Record<string, boolean | number>;
+        min_length: number;
+        max_length: number;
+    }> {
+        return this.client.get('/api/v1/auth/password/requirements/');
+    }
+
+    // ─── WebAuthn / Passkeys (FIDO2) ───
+
+    /**
+     * Register a new WebAuthn device (Passkey/Biometrics/Security Key) for the authenticated user.
+     * Integrates transparently with the browser `navigator.credentials` API.
+     * @param deviceName - Optional human-readable name for the device being registered.
+     */
+    async registerWebAuthn(deviceName?: string): Promise<{
+        message: string;
+        credential: {
+            id: number;
+            device_name: string;
+            created_at: string;
+        };
+    }> {
+        // 1. Begin registration
+        const optionsResponse = await this.client.post<any>('/api/v1/auth/webauthn/register/begin/');
+
+        // 2. Map options for the browser
+        const publicKeyOpts = optionsResponse.publicKey;
+        publicKeyOpts.challenge = base64urlToBuffer(publicKeyOpts.challenge);
+        publicKeyOpts.user.id = base64urlToBuffer(publicKeyOpts.user.id);
+        if (publicKeyOpts.excludeCredentials) {
+            publicKeyOpts.excludeCredentials.forEach((cred: any) => {
+                cred.id = base64urlToBuffer(cred.id);
+            });
+        }
+
+        // 3. Request credential creation from the Authenticator
+        const cred = await navigator.credentials.create({ publicKey: publicKeyOpts }) as PublicKeyCredential;
+        if (!cred) {
+            throw new Error('WebAuthn registration was aborted or failed.');
+        }
+
+        const response = cred.response as AuthenticatorAttestationResponse;
+
+        // 4. Complete registration on the backend
+        const completionPayload = {
+            device_name: deviceName,
+            credential: {
+                id: cred.id,
+                type: cred.type,
+                rawId: bufferToBase64url(cred.rawId),
+                response: {
+                    attestationObject: bufferToBase64url(response.attestationObject),
+                    clientDataJSON: bufferToBase64url(response.clientDataJSON),
+                },
+            },
+        };
+
+        return this.client.post('/api/v1/auth/webauthn/register/complete/', completionPayload);
+    }
+
+    /**
+     * Authenticate via WebAuthn (Passkey) without requiring a password.
+     * Integrates transparently with the browser `navigator.credentials` API.
+     * @param email - The email address identifying the user account (optional if discoverable credentials are used).
+     * @returns A session token pair and the user context upon successful cryptographic challenge verification.
+     */
+    async authenticateWebAuthn(email?: string): Promise<{
+        access: string;
+        refresh: string;
+        user: TenxyteUser;
+        message: string;
+        credential_used: string;
+    }> {
+        // 1. Begin authentication
+        const optionsResponse = await this.client.post<any>('/api/v1/auth/webauthn/authenticate/begin/', email ? { email } : {});
+
+        // 2. Map options for the browser
+        const publicKeyOpts = optionsResponse.publicKey;
+        publicKeyOpts.challenge = base64urlToBuffer(publicKeyOpts.challenge);
+        if (publicKeyOpts.allowCredentials) {
+            publicKeyOpts.allowCredentials.forEach((cred: any) => {
+                cred.id = base64urlToBuffer(cred.id);
+            });
+        }
+
+        // 3. Request assertion from the Authenticator
+        const cred = await navigator.credentials.get({ publicKey: publicKeyOpts }) as PublicKeyCredential;
+        if (!cred) {
+            throw new Error('WebAuthn authentication was aborted or failed.');
+        }
+
+        const response = cred.response as AuthenticatorAssertionResponse;
+
+        // 4. Complete authentication on the backend
+        const completionPayload = {
+            credential: {
+                id: cred.id,
+                type: cred.type,
+                rawId: bufferToBase64url(cred.rawId),
+                response: {
+                    authenticatorData: bufferToBase64url(response.authenticatorData),
+                    clientDataJSON: bufferToBase64url(response.clientDataJSON),
+                    signature: bufferToBase64url(response.signature),
+                    userHandle: response.userHandle ? bufferToBase64url(response.userHandle) : null,
+                },
+            },
+        };
+
+        return this.client.post('/api/v1/auth/webauthn/authenticate/complete/', completionPayload);
+    }
+
+    /**
+     * List all registered WebAuthn credentials for the active user.
+     */
+    async listWebAuthnCredentials(): Promise<{
+        credentials: Array<{
+            id: number;
+            device_name: string;
+            created_at: string;
+            last_used_at: string | null;
+            authenticator_type: string;
+            is_resident_key: boolean;
+        }>;
+        count: number;
+    }> {
+        return this.client.get('/api/v1/auth/webauthn/credentials/');
+    }
+
+    /**
+     * Delete a specific WebAuthn credential, removing its capability to sign in.
+     * @param credentialId - The internal ID of the credential to delete.
+     */
+    async deleteWebAuthnCredential(credentialId: number): Promise<void> {
+        return this.client.delete(`/api/v1/auth/webauthn/credentials/${credentialId}/`);
+    }
+}

package/src/modules/user.ts

@@ -1,80 +1,95 @@
-import { TenxyteHttpClient } from '../http/client';
-
-export interface UpdateProfileParams {
-    first_name?: string;
-    last_name?: string;
-    [key: string]: any; // Allow custom metadata updates
-}
-
-export interface AdminUpdateUserParams {
-    first_name?: string;
-    last_name?: string;
-    is_active?: boolean;
-    is_locked?: boolean;
-    max_sessions?: number;
-    max_devices?: number;
-}
-
-export class UserModule {
-    constructor(private client: TenxyteHttpClient) { }
-
-    // --- Standard Profile Actions --- //
-
-    async getProfile(): Promise<any> {
-        return this.client.get('/api/v1/auth/me/');
-    }
-
-    async updateProfile(data: UpdateProfileParams): Promise<any> {
-        return this.client.patch('/api/v1/auth/me/', data);
-    }
-
-    /**
-     * Upload an avatar using FormData.
-     * Ensure the environment supports FormData (browser or Node.js v18+).
-     * @param formData The FormData object containing the 'avatar' field.
-     */
-    async uploadAvatar(formData: FormData): Promise<any> {
-        return this.client.patch('/api/v1/auth/me/', formData);
-    }
-
-    async deleteAccount(password: string, otpCode?: string): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/request-account-deletion/', {
-            password,
-            otp_code: otpCode
-        });
-    }
-
-    // --- Admin Actions Mapping --- //
-
-    async listUsers(params?: Record<string, any>): Promise<any[]> {
-        return this.client.get<any[]>('/api/v1/auth/admin/users/', { params });
-    }
-
-    async getUser(userId: string): Promise<any> {
-        return this.client.get(`/api/v1/auth/admin/users/${userId}/`);
-    }
-
-    async adminUpdateUser(userId: string, data: AdminUpdateUserParams): Promise<any> {
-        return this.client.patch(`/api/v1/auth/admin/users/${userId}/`, data);
-    }
-
-    async adminDeleteUser(userId: string): Promise<void> {
-        return this.client.delete<void>(`/api/v1/auth/admin/users/${userId}/`);
-    }
-
-    async banUser(userId: string, reason: string = ''): Promise<void> {
-        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/ban/`, { reason });
-    }
-
-    async unbanUser(userId: string): Promise<void> {
-        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/unban/`);
-    }
-
-    async lockUser(userId: string, durationMinutes: number = 30, reason: string = ''): Promise<void> {
-        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/lock/`, { duration_minutes: durationMinutes, reason });
-    }
-
-    async unlockUser(userId: string): Promise<void> {
-        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/unlock/`);
-    }
-}
+import { TenxyteHttpClient } from '../http/client';
+
+export interface UpdateProfileParams {
+    first_name?: string;
+    last_name?: string;
+    [key: string]: any; // Allow custom metadata updates
+}
+
+export interface AdminUpdateUserParams {
+    first_name?: string;
+    last_name?: string;
+    is_active?: boolean;
+    is_locked?: boolean;
+    max_sessions?: number;
+    max_devices?: number;
+}
+
+export class UserModule {
+    constructor(private client: TenxyteHttpClient) { }
+
+    // --- Standard Profile Actions --- //
+
+    /** Retrieve your current comprehensive Profile metadata matching the active network bearer token. */
+    async getProfile(): Promise<any> {
+        return this.client.get('/api/v1/auth/me/');
+    }
+
+    /** Modify your active profile core details or injected application metadata. */
+    async updateProfile(data: UpdateProfileParams): Promise<any> {
+        return this.client.patch('/api/v1/auth/me/', data);
+    }
+
+    /**
+     * Upload an avatar using FormData.
+     * Ensure the environment supports FormData (browser or Node.js v18+).
+     * @param formData The FormData object containing the 'avatar' field.
+     */
+    async uploadAvatar(formData: FormData): Promise<any> {
+        return this.client.patch('/api/v1/auth/me/', formData);
+    }
+
+    /**
+     * Trigger self-deletion of an entire account data boundary.
+     * @param password - Requires the active system password as destructive proof of intent.
+     * @param otpCode - (Optional) If an OTP was queried prior to attempting account deletion.
+     */
+    async deleteAccount(password: string, otpCode?: string): Promise<void> {
+        return this.client.post<void>('/api/v1/auth/request-account-deletion/', {
+            password,
+            otp_code: otpCode
+        });
+    }
+
+    // --- Admin Actions Mapping --- //
+
+    /** (Admin only) Lists users paginated matching criteria. */
+    async listUsers(params?: Record<string, any>): Promise<any[]> {
+        return this.client.get<any[]>('/api/v1/auth/admin/users/', { params });
+    }
+
+    /** (Admin only) Gets deterministic data related to a remote unassociated user. */
+    async getUser(userId: string): Promise<any> {
+        return this.client.get(`/api/v1/auth/admin/users/${userId}/`);
+    }
+
+    /** (Admin only) Modifies configuration/details or capacity bounds related to a remote unassociated user. */
+    async adminUpdateUser(userId: string, data: AdminUpdateUserParams): Promise<any> {
+        return this.client.patch(`/api/v1/auth/admin/users/${userId}/`, data);
+    }
+
+    /** (Admin only) Force obliterate a User boundary. Can affect relational database stability if not bound carefully. */
+    async adminDeleteUser(userId: string): Promise<void> {
+        return this.client.delete<void>(`/api/v1/auth/admin/users/${userId}/`);
+    }
+
+    /** (Admin only) Apply a permanent suspension / ban state globally on a user token footprint. */
+    async banUser(userId: string, reason: string = ''): Promise<void> {
+        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/ban/`, { reason });
+    }
+
+    /** (Admin only) Recover a user footprint from a global ban state. */
+    async unbanUser(userId: string): Promise<void> {
+        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/unban/`);
+    }
+
+    /** (Admin only) Apply a temporary lock bounding block on a user interaction footprint. */
+    async lockUser(userId: string, durationMinutes: number = 30, reason: string = ''): Promise<void> {
+        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/lock/`, { duration_minutes: durationMinutes, reason });
+    }
+
+    /** (Admin only) Releases an arbitrary temporary system lock placed on a user bounds. */
+    async unlockUser(userId: string): Promise<void> {
+        return this.client.post<void>(`/api/v1/auth/admin/users/${userId}/unlock/`);
+    }
+}