docs(supabase): V1-2.5 checkpoint decisions, TOTP reuse measured, lost-factor review

IDENTITY 4.1 asserted reuse span (step N and N+1), 4.2 lost authenticator paths and gaps, production prerequisite; V1-2 contract 12.3, 13, 17.10, 17.11; design README accepted deviations; REVUE L15 and object_conflict EN; M7 header.
This commit is contained in:
bchanot committed 2026-11-02 22:57:22 +01:00
1 parent 0499a39389
commit dcb1a94ee4
9 files changed
+161 -16

No files matched your search

@@ -10,6 +10,7 @@
*/
import { PASSWORD, confirmedAccount, rest, signIn, sql, stack, uniqueEmail, type Account } from './stack'
import { authRequest, claimsOf, enrolTotp, verifyTotp, type Factor, type MfaResult } from './mfa'
import { TOTP_STEP_SECONDS, totpCode } from './totp'
interface Session {
access: string
@@ -56,6 +57,24 @@ const withFactor = async (tag: string) => {
return { account: a, factor, aal2: sessionOf(verified) }
}
/** Sleeps into the start of a TOTP step with at least `minLeftS` seconds left. */
const intoFreshStep = async (minLeftS: number) => {
const stepMs = TOTP_STEP_SECONDS * 1000
const leftMs = stepMs - (Date.now() % stepMs)
if (leftMs <= minLeftS * 1000) await new Promise((r) => setTimeout(r, leftMs + 500))
}
/** Sleeps over the next step boundary (the code of the new step is then current). */
const intoNextStep = async () => {
const stepMs = TOTP_STEP_SECONDS * 1000
await new Promise((r) => setTimeout(r, stepMs - (Date.now() % stepMs) + 500))
}
/** Challenge then verify with a code fixed by the caller (the secret is never read back). */
const verifyWith = async (token: string, factor: Factor, code: string) => {
const challenge = await authRequest('POST', `/factors/${factor.id}/challenge`, token, {})
if (challenge.status !== 200) return challenge
return authRequest('POST', `/factors/${factor.id}/verify`, token, { challenge_id: challenge.body.id, code })
}
/** has_mfa() and has_aal2_session() evaluated with `token`'s claims, as PostgREST sets them. */
const helpersFor = async (token: string) => {
const out = await sql(`begin;
@@ -249,4 +268,33 @@ describe('GoTrue v2.197.0 TOTP behaviour (V1-2.5 C1)', () => {
expect([aal(tokens[0]), amr(tokens[0])]).toEqual(['aal1', ['otp']])
expect(await sql(`select email from auth.users where id = '${a.id}'`)).toBe(newEmail)
})
it('11. a TOTP code is accepted again within its window: same step, next step, not the one after', async () => {
// Measured, not documented (IDENTITY.md §4.1): GoTrue keeps no used-code
// record in this image. The code C of step N is verified by session A,
// then by a second aal1 session B signed in after A's verify, then by A
// again; C is still accepted one step later and refused two steps later.
const { account: a, factor } = await withFactor('mfa-reuse')
await intoNextStep()
await intoFreshStep(8)
const code = totpCode(factor.secret)
const A = await passwordSession(a.email)
const first = await verifyWith(A.access, factor, code)
expect(outcome(first)).toEqual([200, null])
const B = await passwordSession(a.email)
// B is alive before the code is sent: the refusal below cannot be a dead session.
expect([outcome(await authRequest('GET', '/user', B.access)), aal(B.access)]).toEqual([[200, null], 'aal1'])
const reused = await verifyWith(B.access, factor, code)
expect(outcome(reused)).toEqual([200, null])
expect(aal(reused.body.access_token as string)).toBe('aal2')
expect(outcome(await verifyWith(sessionOf(first).access, factor, code))).toEqual([200, null])
// Step N+1 (one step of skew): still accepted.
await intoNextStep()
const D = await passwordSession(a.email)
expect(outcome(await verifyWith(D.access, factor, code))).toEqual([200, null])
// Step N+2: refused. The span of C is its step and the next one (30 to 60 s).
await intoNextStep()
const E = await passwordSession(a.email)
expect(outcome(await verifyWith(E.access, factor, code))).toEqual([422, 'mfa_verification_failed'])
}, 180_000)
})