@contember/engine-tenant-api 2.1.0-rc.3 → 2.2.0-alpha.10

package/tests/cases/unit/idp/oidcRevalidate.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, test } from 'bun:test'
+import { errors } from 'openid-client'
+import { revalidateOIDC, tokenSetToSessionState } from '../../../../src/model/service/idp/providers/OIDCHelpers.js'
+import { IDPSessionState } from '../../../../src/model/service/idp/index.js'
+
+const session = (tokens: Record<string, unknown>, sessionId = 'sid-1'): IDPSessionState => ({ sessionId, tokens })
+
+describe('revalidateOIDC — refresh', () => {
+	test('valid: rotates the refresh token and returns fresh claims', async () => {
+		const client = {
+			refresh: async (token: string) => {
+				expect(token).toBe('refresh-old')
+				return {
+					refresh_token: 'refresh-new',
+					access_token: 'access-new',
+					id_token: 'id-new',
+					expires_at: 1_900_000_000,
+					claims: () => ({ sub: 'user-1', email: 'a@b.cz' }),
+				}
+			},
+		} as any
+
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'refresh-old' }))
+
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			// claims are normalized the SAME way sign-in normalizes them (identity fields mapped on top of the
+			// raw claims), so an `always` mapping reconciles against an identical surface on refresh.
+			expect(result.claims).toEqual({ sub: 'user-1', email: 'a@b.cz', externalIdentifier: 'user-1', emailVerified: false })
+			// id_token present + surface rebuilt → complete, so the caller may run `unmatched: "remove"` here too.
+			expect(result.claimsComplete).toBe(true)
+			expect(result.idpSession?.tokens?.refresh_token).toBe('refresh-new')
+			expect(result.idpSession?.sessionId).toBe('sid-1')
+			expect(result.idpSession?.expiresAt).toEqual(new Date(1_900_000_000 * 1000))
+		}
+	})
+
+	test('fetchUserInfo: merges userinfo into the refresh surface (same as sign-in)', async () => {
+		// At sign-in, `fetchUserInfo` merges userinfo over the id-token claims; the refresh path does the SAME,
+		// so a rule keyed on a userinfo-only claim (e.g. `groups`) resolves on refresh too.
+		const client = {
+			refresh: async () => ({
+				refresh_token: 'refresh-new',
+				access_token: 'access-new',
+				id_token: 'id-new',
+				claims: () => ({ sub: 'user-1', email: 'a@b.cz' }),
+			}),
+			userinfo: async (token: any) => {
+				expect(token.access_token).toBe('access-new')
+				return { sub: 'user-1', groups: ['IT-Admins'] }
+			},
+		} as any
+
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'refresh-old' }), { fetchUserInfo: true })
+
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			expect((result.claims as any)?.groups).toEqual(['IT-Admins'])
+			expect((result.claims as any)?.email).toBe('a@b.cz')
+			expect(result.claimsComplete).toBe(true)
+		}
+	})
+
+	test('fetchUserInfo failure → keep session, skip the sync (no claims, surface not complete)', async () => {
+		// The IdP already vouched for the session via the successful refresh; a failed userinfo fetch must not
+		// fail revalidation. Drop the claims so the sync is skipped (and removal can never run off a half-built
+		// surface) and retry on a later refresh.
+		const client = {
+			refresh: async () => ({
+				refresh_token: 'refresh-new',
+				access_token: 'access-new',
+				id_token: 'id-new',
+				claims: () => ({ sub: 'user-1' }),
+			}),
+			userinfo: async () => {
+				throw new Error('userinfo unreachable')
+			},
+		} as any
+
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'refresh-old' }), { fetchUserInfo: true })
+
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			expect(result.claims).toBeUndefined()
+			expect(result.claimsComplete).toBe(false)
+			// the session is still kept (rotated token persisted)
+			expect(result.idpSession?.tokens?.refresh_token).toBe('refresh-new')
+		}
+	})
+
+	test('non-rotating IdP: refresh omits the refresh token → keep the stored one (no spurious revoke)', async () => {
+		// RFC 6749 §6 — a refresh response MAY omit refresh_token; the client keeps the old one.
+		const client = {
+			refresh: async (token: string) => {
+				expect(token).toBe('refresh-old')
+				return {
+					access_token: 'access-new',
+					expires_at: 1_900_000_000,
+					claims: () => ({ sub: 'user-1' }),
+				}
+			},
+		} as any
+
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'refresh-old', id_token: 'id-old' }))
+
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			// preserved from the stored session, not lost
+			expect(result.idpSession?.tokens?.refresh_token).toBe('refresh-old')
+			expect(result.idpSession?.tokens?.id_token).toBe('id-old')
+			expect(result.idpSession?.tokens?.access_token).toBe('access-new')
+		}
+	})
+
+	test('revoked: no refresh token stored', async () => {
+		const result = await revalidateOIDC({} as any, 'refresh', session({}))
+		expect(result).toEqual({ status: 'revoked', reason: 'no_refresh_token' })
+	})
+
+	test('revoked: IdP rejects the grant (invalid_grant)', async () => {
+		const client = {
+			refresh: async () => {
+				throw new errors.OPError({ error: 'invalid_grant' })
+			},
+		} as any
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'x' }))
+		expect(result).toEqual({ status: 'revoked', reason: 'invalid_grant' })
+	})
+
+	test('transient failure propagates (does NOT revoke)', async () => {
+		const client = {
+			refresh: async () => {
+				throw new Error('ECONNREFUSED')
+			},
+		} as any
+		await expect(revalidateOIDC(client, 'refresh', session({ refresh_token: 'x' }))).rejects.toThrow('ECONNREFUSED')
+	})
+
+	test('attributesKey: nested claims are lifted to the top level on the refresh path (same as sign-in)', async () => {
+		// A09 (SEC-2): an `attributesKey` provider (e.g. Apereo CAS) nests its claims under `attributes`; the
+		// `claimMapping` option wires that lift into `revalidateOIDC` so its mapping resolves identically on refresh.
+		const client = {
+			refresh: async () => ({
+				refresh_token: 'refresh-new',
+				id_token: 'id-new',
+				claims: () => ({ sub: 'signed', attributes: { groups: ['IT-Admins'], sub: 'spoofed' } }),
+			}),
+		} as any
+
+		const result = await revalidateOIDC(client, 'refresh', session({ refresh_token: 'refresh-old' }), { claimMapping: { attributesKey: 'attributes' } })
+
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			// the nested `groups` is surfaced top-level for rule matching…
+			expect((result.claims as any)?.groups).toEqual(['IT-Admins'])
+			// …while a signed top-level claim keeps precedence over an attributes-level value of the same name
+			expect((result.claims as any)?.sub).toBe('signed')
+		}
+	})
+})
+
+describe('revalidateOIDC — userinfo', () => {
+	test('valid: returns userinfo claims', async () => {
+		const client = {
+			userinfo: async (token: string) => {
+				expect(token).toBe('access-1')
+				return { sub: 'user-1', groups: ['admins'] }
+			},
+		} as any
+		const result = await revalidateOIDC(client, 'userinfo', session({ access_token: 'access-1' }))
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			expect(result.claims).toEqual({ sub: 'user-1', groups: ['admins'], externalIdentifier: 'user-1', emailVerified: false })
+			// userinfo carries no id-token claims → narrower than sign-in's surface → additive-only on refresh.
+			expect(result.claimsComplete).toBe(false)
+		}
+	})
+
+	test('attributesKey: userinfo nested claims are lifted to the top level', async () => {
+		const client = {
+			userinfo: async () => ({ sub: 'user-1', attributes: { groups: ['admins'] } }),
+		} as any
+		const result = await revalidateOIDC(client, 'userinfo', session({ access_token: 'access-1' }), { claimMapping: { attributesKey: 'attributes' } })
+		expect(result.status).toBe('valid')
+		if (result.status === 'valid') {
+			expect((result.claims as any)?.groups).toEqual(['admins'])
+		}
+	})
+
+	test('revoked: no access token', async () => {
+		const result = await revalidateOIDC({} as any, 'userinfo', session({}))
+		expect(result).toEqual({ status: 'revoked', reason: 'no_access_token' })
+	})
+
+	test('revoked: bare 401 with no parseable error code', async () => {
+		// RFC 6750 allows a 401 without a `WWW-Authenticate` error param; openid-client then
+		// surfaces a non-standard `error` string. A 401 is still definitive → revoked.
+		const client = {
+			userinfo: async () => {
+				throw new errors.OPError({ error: 'expected 200 OK, got: 401 Unauthorized' }, { statusCode: 401 } as any)
+			},
+		} as any
+		const result = await revalidateOIDC(client, 'userinfo', session({ access_token: 'a' }))
+		expect(result).toEqual({ status: 'revoked', reason: 'userinfo_unauthorized' })
+	})
+
+	test('transient: a 503 from userinfo propagates (does NOT revoke)', async () => {
+		const client = {
+			userinfo: async () => {
+				throw new errors.OPError({ error: 'expected 200 OK, got: 503 Service Unavailable' }, { statusCode: 503 } as any)
+			},
+		} as any
+		await expect(revalidateOIDC(client, 'userinfo', session({ access_token: 'a' }))).rejects.toThrow()
+	})
+})
+
+describe('revalidateOIDC — introspection', () => {
+	test('valid when active', async () => {
+		const client = { introspect: async () => ({ active: true }) } as any
+		const result = await revalidateOIDC(client, 'introspection', session({ access_token: 'a' }))
+		expect(result.status).toBe('valid')
+	})
+
+	test('revoked when inactive', async () => {
+		const client = { introspect: async () => ({ active: false }) } as any
+		const result = await revalidateOIDC(client, 'introspection', session({ access_token: 'a' }))
+		expect(result).toEqual({ status: 'revoked', reason: 'inactive' })
+	})
+
+	test('a 401 from introspection is transient (client-auth/config), NOT a revoked token', async () => {
+		// Introspection reports revoked tokens with 200 `{active:false}`; a 401 means the
+		// client failed to authenticate to the introspection endpoint → must not log users out.
+		const client = {
+			introspect: async () => {
+				throw new errors.OPError({ error: 'expected 200 OK, got: 401 Unauthorized' }, { statusCode: 401 } as any)
+			},
+		} as any
+		await expect(revalidateOIDC(client, 'introspection', session({ access_token: 'a' }))).rejects.toThrow()
+	})
+})
+
+describe('tokenSetToSessionState', () => {
+	test('captures only present tokens and converts expiry to a Date', () => {
+		const state = tokenSetToSessionState({ refresh_token: 'r', expires_at: 1000 } as any, 'sid-2')
+		expect(state).toEqual({
+			sessionId: 'sid-2',
+			tokens: { refresh_token: 'r' },
+			expiresAt: new Date(1000 * 1000),
+		})
+	})
+
+	test('falls back to previous refresh/id tokens when the new token set omits them', () => {
+		const state = tokenSetToSessionState(
+			{ access_token: 'a-new', expires_at: 1000 } as any,
+			'sid-3',
+			{ refresh_token: 'r-old', id_token: 'i-old', access_token: 'a-old' },
+		)
+		expect(state.tokens).toEqual({ refresh_token: 'r-old', id_token: 'i-old', access_token: 'a-new' })
+	})
+
+	test('prefers the new tokens over the previous ones when both are present', () => {
+		const state = tokenSetToSessionState(
+			{ refresh_token: 'r-new', access_token: 'a-new' } as any,
+			'sid-4',
+			{ refresh_token: 'r-old' },
+		)
+		expect(state.tokens?.refresh_token).toBe('r-new')
+	})
+})

package/tests/cases/unit/loginRiskAnalyzer.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from 'bun:test'
+import crypto from 'node:crypto'
+import { ipPrefix, LoginRiskAnalyzer, PriorLogin, RiskWeight } from '../../../src/index.js'
+
+const hash = (value: crypto.BinaryLike, algo: string) => crypto.createHash(algo).update(value).digest()
+const analyzer = new LoginRiskAnalyzer(hash)
+
+const policy = (overrides: Partial<{ enabled: boolean; historySize: number; emailThreshold: number; stepUpThreshold: number }> = {}) => ({
+	enabled: true,
+	historySize: 10,
+	emailThreshold: 1,
+	stepUpThreshold: 3,
+	...overrides,
+})
+
+const prior = (overrides: Partial<PriorLogin> = {}): PriorLogin => ({
+	geoCountry: 'CZ',
+	deviceFingerprint: 'fp-known',
+	ip: '10.0.0.5',
+	...overrides,
+})
+
+describe('LoginRiskAnalyzer.fingerprint', () => {
+	test('hashes the user-agent deterministically', () => {
+		const ua = 'Mozilla/5.0 (X11; Linux x86_64)'
+		expect(analyzer.fingerprint(ua)).toBe(crypto.createHash('sha256').update(ua).digest('hex'))
+	})
+
+	test('returns null for absent/empty UA', () => {
+		expect(analyzer.fingerprint(undefined)).toBeNull()
+		expect(analyzer.fingerprint(null)).toBeNull()
+		expect(analyzer.fingerprint('')).toBeNull()
+	})
+})
+
+describe('ipPrefix', () => {
+	test('coarsens IPv4 to /24', () => {
+		expect(ipPrefix('203.0.113.42')).toBe('203.0.113.0/24')
+		// same /24, different host → same prefix → treated as known
+		expect(ipPrefix('203.0.113.1')).toBe(ipPrefix('203.0.113.200'))
+	})
+
+	test('different /24 yields a different prefix', () => {
+		expect(ipPrefix('203.0.113.1')).not.toBe(ipPrefix('203.0.99.1'))
+	})
+
+	test('coarsens IPv6 to /48', () => {
+		expect(ipPrefix('2001:db8:abcd:1234::1')).toBe('2001:db8:abcd::/48')
+	})
+
+	test('IPv6 is canonicalized: case and leading zeros do not change the prefix', () => {
+		// Same /48 written upper-case / with leading zeros must map to one key, or the
+		// IP signal would falsely fire `new_ip_prefix` for a known network.
+		expect(ipPrefix('2001:DB8:ABCD::1')).toBe('2001:db8:abcd::/48')
+		expect(ipPrefix('2001:0db8:00ab::1')).toBe('2001:db8:ab::/48')
+		expect(ipPrefix('2001:0db8:00ab::1')).toBe(ipPrefix('2001:db8:ab:0:0:0:0:5'))
+	})
+
+	test('IPv6 :: compression is expanded consistently', () => {
+		// `2001:db8::1` and `2001:db8:0:0::5` are the same /48 → same key.
+		expect(ipPrefix('2001:db8::1')).toBe('2001:db8:0::/48')
+		expect(ipPrefix('2001:db8::1')).toBe(ipPrefix('2001:db8:0:0::5'))
+		// ...but a different third hextet is a different /48 → not collapsed.
+		expect(ipPrefix('2001:db8::1')).not.toBe(ipPrefix('2001:db8:1::1'))
+	})
+
+	test('unwraps IPv4-mapped IPv6', () => {
+		expect(ipPrefix('::ffff:203.0.113.42')).toBe('203.0.113.0/24')
+		// also the fully/partly expanded mapped form, not just the `::ffff:` shorthand.
+		expect(ipPrefix('0:0:0:0:0:ffff:203.0.113.42')).toBe('203.0.113.0/24')
+	})
+
+	test('a non-mapped IPv6 ending in :ffff:<dotted-quad> stays a /48, not a bogus /24', () => {
+		// The IPv4-mapped form requires the leading 80 bits to be zero. An address with
+		// a non-zero prefix that merely ends in `:ffff:1.2.3.4` (or NAT64 `64:ff9b::`)
+		// is a normal IPv6 address — it must coarsen to its /48, never collapse to the
+		// embedded dotted-quad's /24 (which would both miss real network changes and
+		// false-fire when the same /48 is written two ways).
+		expect(ipPrefix('2001:db8::ffff:1.2.3.4')).toBe('2001:db8:0::/48')
+		expect(ipPrefix('64:ff9b::ffff:1.2.3.4')).toBe('64:ff9b:0::/48')
+		expect(ipPrefix('64:ff9b::1.2.3.4')).toBe('64:ff9b:0::/48')
+		// ...and they must not collide with the genuine IPv4-mapped /24.
+		expect(ipPrefix('2001:db8::ffff:1.2.3.4')).not.toBe(ipPrefix('::ffff:1.2.3.4'))
+		// two different non-mapped /48s sharing a trailing dotted-quad stay distinct.
+		expect(ipPrefix('2001:db8::ffff:1.2.3.4')).not.toBe(ipPrefix('2001:dba::ffff:1.2.3.4'))
+	})
+
+	test('falls back to the raw value for an unparseable IPv6', () => {
+		// expandIpv6 rejects malformed input → ipPrefix returns a stable, lower-cased raw
+		// string (never throws, never mints a bogus prefix), and two distinct junk values
+		// do not collapse to one key.
+		expect(ipPrefix('1::2::3')).toBe('1::2::3')
+		expect(ipPrefix('2001:db8::g')).toBe('2001:db8::g')
+		expect(ipPrefix('1::2::3')).not.toBe(ipPrefix('4::5::6'))
+	})
+
+	test('returns null for empty/null', () => {
+		expect(ipPrefix(null)).toBeNull()
+		expect(ipPrefix('')).toBeNull()
+		expect(ipPrefix('   ')).toBeNull()
+	})
+})
+
+describe('LoginRiskAnalyzer.score', () => {
+	test('no history → no signals, allow (first login is trusted)', () => {
+		const result = analyzer.score({ geoCountry: 'US', deviceFingerprint: 'fp-new', ip: '198.51.100.7' }, [], policy())
+		expect(result).toEqual({ score: 0, action: 'allow', reasons: [] })
+	})
+
+	test('all signals match a prior login → score 0, allow', () => {
+		const history = [prior()]
+		const result = analyzer.score({ geoCountry: 'CZ', deviceFingerprint: 'fp-known', ip: '10.0.0.99' }, history, policy())
+		expect(result.score).toBe(0)
+		expect(result.action).toBe('allow')
+		expect(result.reasons).toEqual([])
+	})
+
+	test('new country alone is high → step-up at default thresholds', () => {
+		const history = [prior()]
+		const result = analyzer.score({ geoCountry: 'US', deviceFingerprint: 'fp-known', ip: '10.0.0.5' }, history, policy())
+		expect(result.score).toBe(RiskWeight.newCountry)
+		expect(result.reasons).toEqual(['new_country'])
+		expect(result.action).toBe('stepUp')
+	})
+
+	test('new device alone is medium → email (below step-up threshold)', () => {
+		const history = [prior()]
+		const result = analyzer.score({ geoCountry: 'CZ', deviceFingerprint: 'fp-new', ip: '10.0.0.5' }, history, policy())
+		expect(result.score).toBe(RiskWeight.newDevice)
+		expect(result.reasons).toEqual(['new_device'])
+		expect(result.action).toBe('email')
+	})
+
+	test('new IP prefix alone is low → email', () => {
+		const history = [prior({ ip: '10.0.0.5' })]
+		const result = analyzer.score({ geoCountry: 'CZ', deviceFingerprint: 'fp-known', ip: '203.0.113.9' }, history, policy())
+		expect(result.score).toBe(RiskWeight.newIpPrefix)
+		expect(result.reasons).toEqual(['new_ip_prefix'])
+		expect(result.action).toBe('email')
+	})
+
+	test('signals are cumulative across signals', () => {
+		const history = [prior()]
+		const result = analyzer.score({ geoCountry: 'US', deviceFingerprint: 'fp-new', ip: '203.0.113.9' }, history, policy())
+		expect(result.score).toBe(RiskWeight.newCountry + RiskWeight.newDevice + RiskWeight.newIpPrefix)
+		expect(result.reasons).toEqual(['new_country', 'new_device', 'new_ip_prefix'])
+		expect(result.action).toBe('stepUp')
+	})
+
+	test('a signal with no baseline in history does not fire (cold start)', () => {
+		// History exists, but no prior login ever recorded a country or a device
+		// fingerprint (those columns were null before the feature/geo header was
+		// turned on). With nothing to deviate from, neither signal may fire —
+		// otherwise enabling the feature would step-up every returning user's first
+		// login. Only the IP signal has a baseline here, and it matches → allow.
+		const history: PriorLogin[] = [
+			{ geoCountry: null, deviceFingerprint: null, ip: '10.0.0.5' },
+			{ geoCountry: null, deviceFingerprint: null, ip: '10.0.0.6' },
+		]
+		const result = analyzer.score({ geoCountry: 'US', deviceFingerprint: 'fp-new', ip: '10.0.0.9' }, history, policy())
+		expect(result.reasons).toEqual([])
+		expect(result.score).toBe(0)
+		expect(result.action).toBe('allow')
+	})
+
+	test('a signal fires once a baseline for it exists, even when other rows are null', () => {
+		// One prior login carries a country; the rest are null. A different current
+		// country is now genuinely new because there is a baseline to deviate from.
+		const history: PriorLogin[] = [
+			{ geoCountry: null, deviceFingerprint: 'fp-known', ip: '10.0.0.5' },
+			{ geoCountry: 'CZ', deviceFingerprint: null, ip: '10.0.0.6' },
+		]
+		const result = analyzer.score({ geoCountry: 'US', deviceFingerprint: 'fp-known', ip: '10.0.0.5' }, history, policy())
+		expect(result.reasons).toEqual(['new_country'])
+		expect(result.score).toBe(RiskWeight.newCountry)
+	})
+
+	test('a value known from ANY prior login does not fire', () => {
+		// country only ever seen on login A, device only on login B → both known.
+		const history = [
+			prior({ geoCountry: 'DE', deviceFingerprint: 'fp-a', ip: '10.1.0.1' }),
+			prior({ geoCountry: 'CZ', deviceFingerprint: 'fp-b', ip: '10.2.0.1' }),
+		]
+		const result = analyzer.score({ geoCountry: 'CZ', deviceFingerprint: 'fp-a', ip: '10.3.0.1' }, history, policy())
+		expect(result.reasons).toEqual(['new_ip_prefix'])
+	})
+
+	test('absent current country never fires the country signal', () => {
+		const history = [prior({ geoCountry: 'CZ' })]
+		const result = analyzer.score({ geoCountry: null, deviceFingerprint: 'fp-known', ip: '10.0.0.5' }, history, policy())
+		expect(result.reasons).not.toContain('new_country')
+		expect(result.score).toBe(0)
+	})
+
+	test('thresholds are honored: a higher email threshold suppresses the email action', () => {
+		const history = [prior()]
+		// new device = 2; with emailThreshold 3, that is below → allow.
+		const result = analyzer.score(
+			{ geoCountry: 'CZ', deviceFingerprint: 'fp-new', ip: '10.0.0.5' },
+			history,
+			policy({ emailThreshold: 3, stepUpThreshold: 5 }),
+		)
+		expect(result.score).toBe(2)
+		expect(result.action).toBe('allow')
+	})
+})

package/tests/cases/unit/otpManager.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test'
+import { Buffer } from 'buffer'
+import { createConnectionMock, ExpectedQuery } from '@contember/database-tester'
+import { DatabaseContext, OtpAuthenticator, OtpError, OtpManager, PersonRow, Providers } from '../../../src/index.js'
+
+const now = new Date('2019-09-04 12:00')
+
+const otpAuthenticator = new OtpAuthenticator({
+	now: () => now,
+	randomBytes: () => Promise.resolve(Buffer.alloc(20)),
+})
+
+// A reversible "encryption": prefixes the plaintext with a marker. decrypt strips it.
+const ENC_PREFIX = 'ENC:'
+const makeDecrypt = (needsReEncrypt = false) => (value: Buffer, version: number) => {
+	expect(version).toBeGreaterThanOrEqual(1)
+	const str = value.toString('utf8')
+	if (!str.startsWith(ENC_PREFIX)) {
+		throw new Error('cannot decrypt')
+	}
+	return Promise.resolve({ value: Buffer.from(str.slice(ENC_PREFIX.length), 'utf8'), needsReEncrypt })
+}
+const decrypt = makeDecrypt(false)
+const encrypt = (value: Buffer) => Promise.resolve({ value: Buffer.from(ENC_PREFIX + value.toString('utf8')), version: 2 })
+
+const REENCRYPT_SQL =
+	`update "tenant"."person_mfa" set "totp_secret" = ?, "totp_secret_version" = ? where "person_id" = ? and "totp_secret_version" = ?`
+
+const baseProviders = (overrides: Partial<Providers> = {}): Providers => ({
+	bcrypt: () => Promise.resolve('x'),
+	bcryptCompare: () => Promise.resolve(true),
+	now: () => now,
+	randomBytes: () => Promise.resolve(Buffer.alloc(20)),
+	uuid: () => 'uuid',
+	decrypt,
+	encrypt,
+	encryptionEnabled: true,
+	hash: value => Buffer.from(value.toString()),
+	...overrides,
+})
+
+const makeDb = (queries: ExpectedQuery[], providers: Providers) => {
+	const connection = createConnectionMock(queries)
+	const client = connection.createClient('tenant', { module: 'tenant' })
+	return new DatabaseContext(client, providers)
+}
+
+const basePerson: PersonRow = {
+	id: '123e4567-e89b-12d3-a456-000000000001',
+	password_hash: null,
+	identity_id: 'i1',
+	otp_secret: null,
+	otp_secret_version: null,
+	otp_activated_at: null,
+	otp_pending_secret: null,
+	otp_pending_version: null,
+	otp_pending_created_at: null,
+	email_otp_enabled: false,
+	email: 'john@doe.com',
+	name: null,
+	roles: [],
+	disabled_at: null,
+	passwordless_enabled: null,
+	mfa_grace_until: null,
+	is_in_grace: false,
+	email_verified_at: null,
+	email_verification_required: false,
+}
+
+describe('OtpManager.verifyOtp', () => {
+	test('validates a legacy version-0 (plaintext otpauth URI) secret and re-encrypts it on success', async () => {
+		const providers = baseProviders()
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const person: PersonRow = {
+			...basePerson,
+			otp_secret: Buffer.from(otp.uri, 'utf8'),
+			otp_secret_version: 0,
+			otp_activated_at: now,
+		}
+		const token = otpAuthenticator.generate(otp)
+
+		// Successful verify re-encrypts: base32 of the URI, encrypted (version>=1),
+		// guarded on the old version 0.
+		const queries: ExpectedQuery[] = [{
+			sql: REENCRYPT_SQL,
+			parameters: [Buffer.from(ENC_PREFIX + otp.secret), 2, person.id, 0],
+			response: { rowCount: 1 },
+		}]
+		const db = makeDb(queries, providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyOtp(db, person, token)).toBe(true)
+		expect(queries).toHaveLength(0)
+	})
+
+	test('does NOT re-encrypt a version-0 secret when verification fails', async () => {
+		const providers = baseProviders()
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const person: PersonRow = {
+			...basePerson,
+			otp_secret: Buffer.from(otp.uri, 'utf8'),
+			otp_secret_version: 0,
+			otp_activated_at: now,
+		}
+		const db = makeDb([], providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyOtp(db, person, '000000')).toBe(false)
+	})
+
+	test('round-trips an encrypted version>=1 secret without re-encrypting (needsReEncrypt=false)', async () => {
+		const providers = baseProviders()
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const encrypted = await encrypt(Buffer.from(otp.secret, 'utf8'))
+		const person: PersonRow = {
+			...basePerson,
+			otp_secret: encrypted.value,
+			otp_secret_version: encrypted.version,
+			otp_activated_at: now,
+		}
+		const token = otpAuthenticator.generate(otp)
+		const db = makeDb([], providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyOtp(db, person, token)).toBe(true)
+		expect(await manager.verifyOtp(db, person, '000000')).toBe(false)
+	})
+
+	test('re-encrypts a version>=1 secret when decrypt signals needsReEncrypt', async () => {
+		const providers = baseProviders({ decrypt: makeDecrypt(true) })
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const encrypted = await encrypt(Buffer.from(otp.secret, 'utf8'))
+		const person: PersonRow = {
+			...basePerson,
+			otp_secret: encrypted.value,
+			otp_secret_version: encrypted.version,
+			otp_activated_at: now,
+		}
+		const token = otpAuthenticator.generate(otp)
+
+		const queries: ExpectedQuery[] = [{
+			sql: REENCRYPT_SQL,
+			parameters: [Buffer.from(ENC_PREFIX + otp.secret), 2, person.id, encrypted.version],
+			response: { rowCount: 1 },
+		}]
+		const db = makeDb(queries, providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyOtp(db, person, token)).toBe(true)
+		expect(queries).toHaveLength(0)
+	})
+
+	test('verify still succeeds when re-encryption (encrypt) throws — best-effort swallow', async () => {
+		const providers = baseProviders({
+			encrypt: () => Promise.reject(new Error('encrypt boom')),
+		})
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const person: PersonRow = {
+			...basePerson,
+			otp_secret: Buffer.from(otp.uri, 'utf8'),
+			otp_secret_version: 0,
+			otp_activated_at: now,
+		}
+		const token = otpAuthenticator.generate(otp)
+		const db = makeDb([], providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyOtp(db, person, token)).toBe(true)
+	})
+
+	test('throws when no active secret is configured', async () => {
+		const providers = baseProviders()
+		const db = makeDb([], providers)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		await expect(manager.verifyOtp(db, basePerson, '123456')).rejects.toBeInstanceOf(OtpError)
+	})
+
+	test('verifyPendingOtp validates against the pending slot and never re-encrypts', async () => {
+		const providers = baseProviders({ decrypt: makeDecrypt(true) })
+		const otp = await otpAuthenticator.create('john', 'contember')
+		const encrypted = await encrypt(Buffer.from(otp.secret, 'utf8'))
+		const person: PersonRow = {
+			...basePerson,
+			otp_pending_secret: encrypted.value,
+			otp_pending_version: encrypted.version,
+			otp_pending_created_at: now,
+		}
+		const token = otpAuthenticator.generate(otp)
+		const manager = new OtpManager(otpAuthenticator, providers)
+		expect(await manager.verifyPendingOtp(person, token)).toBe(true)
+	})
+})