import type { FaunosteoClient } from './client' /** * TOTP factors of the signed-in account (V1-2.5, contract * docs/development/V1-2_ANATOMICAL_SHEETS.md §5.6, §5.7): list, enrol, * challenge and verify, remove, and the session's assurance level. GoTrue is * the only authority: its `aal2` requirements (a second factor or the removal * of a verified one from `aal1`, docs/development/IDENTITY.md §4.1) come back * as the closed kind `aal2_required`, never worked around here. Every GoTrue * answer is folded into one kind the UI phrases (`mfa.failure.`); the * raw message never reaches the screen. */ export const MFA_FAILURE_KINDS = [ 'aal2_required', 'invalid_code', 'factor_not_found', 'challenge_expired', 'too_many_factors', 'name_taken', 'rate_limited', 'session_expired', 'network', 'unavailable', ] as const export type MfaFailureKind = (typeof MFA_FAILURE_KINDS)[number] export class MfaFailure extends Error { readonly kind: MfaFailureKind constructor(kind: MfaFailureKind, cause?: unknown) { super(`mfa: ${kind}`, { cause }) this.name = 'MfaFailure' this.kind = kind } } /** GoTrue v2.197.0 error codes (auth-js `ErrorCode`) and their kinds. */ const CODE_TO_KIND: Record = { insufficient_aal: 'aal2_required', mfa_verification_failed: 'invalid_code', mfa_verification_rejected: 'invalid_code', mfa_factor_not_found: 'factor_not_found', mfa_challenge_expired: 'challenge_expired', // The challenge was made from another address: a new one is needed. mfa_ip_address_mismatch: 'challenge_expired', too_many_enrolled_mfa_factors: 'too_many_factors', mfa_factor_name_conflict: 'name_taken', over_request_rate_limit: 'rate_limited', session_not_found: 'session_expired', session_expired: 'session_expired', refresh_token_not_found: 'session_expired', refresh_token_already_used: 'session_expired', bad_jwt: 'session_expired', no_authorization: 'session_expired', } interface AuthLikeError { name?: string code?: string status?: number } /** * Maps a GoTrue answer to a closed kind: code first, then the client's own * error classes and the HTTP status. Fails closed to `unavailable` (TOTP * disabled on the server, an unexpected code). */ export function classifyMfaError(error: unknown): MfaFailureKind { if (error instanceof MfaFailure) return error.kind if (error instanceof TypeError) return 'network' const e = (error ?? {}) as AuthLikeError if (e.code && CODE_TO_KIND[e.code]) return CODE_TO_KIND[e.code] if (e.name === 'AuthSessionMissingError') return 'session_expired' if (e.name === 'AuthRetryableFetchError') return 'network' if (e.status === 429) return 'rate_limited' return 'unavailable' } function fail(error: unknown): never { throw new MfaFailure(classifyMfaError(error), error) } export interface TotpFactor { id: string friendlyName: string | null status: 'verified' | 'unverified' createdAt: string } /** * Every TOTP factor of the account, unverified ones included. supabase-js * `listFactors` keeps only verified factors in its `totp` list; its `all` * list is the user's `factors` from `getUser()` (a request to GoTrue, so the * list is current), which is what is read here. */ export async function listTotpFactors( client: FaunosteoClient, ): Promise { const { data, error } = await client.auth.mfa.listFactors() if (error) fail(error) return data.all .filter((factor) => factor.factor_type === 'totp') .map((factor) => ({ id: factor.id, friendlyName: factor.friendly_name || null, status: factor.status === 'verified' ? 'verified' : 'unverified', createdAt: factor.created_at, })) } export interface TotpEnrolment { factorId: string /** The QR code as an SVG data URI (`data:image/svg+xml;utf-8,…`), as supabase-js builds it. */ qrCode: string /** * The shared secret, shown once beside the QR code. Never stored, logged * or sent anywhere by the app: GoTrue keeps it, the user's authenticator * holds it, and it is gone when the enrolment screen closes. */ secret: string /** The otpauth:// URI the QR code encodes; same secrecy as `secret`. */ uri: string } /** * A new, unverified TOTP factor. From `aal1` GoTrue allows it only while the * account has no verified factor (`aal2_required` otherwise). */ export async function enrollTotp( client: FaunosteoClient, friendlyName: string, ): Promise { const { data, error } = await client.auth.mfa.enroll({ factorType: 'totp', friendlyName, }) if (error) fail(error) return { factorId: data.id, qrCode: data.totp.qr_code, secret: data.totp.secret, uri: data.totp.uri, } } /** * Challenges the factor and verifies the code in one step. On success the * client's session is upgraded to `aal2` (GoTrue drops the account's other * `aal1` sessions, IDENTITY.md §4.1). */ export async function verifyTotp( client: FaunosteoClient, factorId: string, code: string, ): Promise { const { error } = await client.auth.mfa.challengeAndVerify({ factorId, code }) if (error) fail(error) } /** Removes a factor; a verified one needs an `aal2` session (`aal2_required`). */ export async function unenrollFactor( client: FaunosteoClient, factorId: string, ): Promise { const { error } = await client.auth.mfa.unenroll({ factorId }) if (error) fail(error) } export type AssuranceLevel = 'aal1' | 'aal2' export interface AssuranceState { /** The level of the current access token; null without a session. */ current: AssuranceLevel | null /** `aal2` once the account holds a verified factor (from the session's user, no request). */ next: AssuranceLevel | null } /** The session's assurance level. A hint for the screens: the server checks the token itself. */ export async function assuranceLevel( client: FaunosteoClient, ): Promise { const { data, error } = await client.auth.mfa.getAuthenticatorAssuranceLevel() if (error) fail(error) const level = (value: string | null): AssuranceLevel | null => value === 'aal1' || value === 'aal2' ? value : null return { current: level(data.currentLevel), next: level(data.nextLevel) } }