Files
faunosteo/packages/supabase/src/mfa.ts
T
bchanot c9ace9aff2 feat(supabase): MFA, species, rights, admin and catalogue access layer (V1-2.5 D)
mfa.ts (closed kinds, TOTP list incl. unverified, enrol, verify, unenrol, assurance); sheets.ts wrappers for species, working copy, account lookup, M7 reads, versions list, drawing download, own grants, with shape parsers. Unit 148, sandbox sheets-admin 5/5 x2.
2026-11-02 16:31:50 +01:00

188 lines
6.1 KiB
TypeScript

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.<kind>`); 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<string, MfaFailureKind> = {
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<TotpFactor[]> {
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<TotpEnrolment> {
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<void> {
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<void> {
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<AssuranceState> {
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) }
}