feat(auth): allow trusting a device to skip the second factor

Add an opt-in "remember this device" at the second-factor step. On opt-in
a random token is minted, set in an httpOnly+Secure+SameSite=Strict cookie,
and only its HMAC hash is stored in a new TrustedDevice table. A later sign-in
from the same browser still requires the password (factor 1); a matching,
unexpired trusted device lets the login skip factor 2 only.

The token is never accepted for step-up — a trusted-device login does not stamp
mfaVerifiedAt — so a stolen device cookie cannot reach a destructive action.
Trusted devices are listed and revocable from the security surface, are revoked
wholesale when the second factor is removed or the user signs out everywhere,
and cascade away on account deletion. A recovery-code login never trusts the
browser. Migration 0204 adds the table (and the instance-wide mfa_required
policy column that the enforcement work reads).
This commit is contained in:
Marc-André Bombeck committed 2026-06-27 21:49:39 +02:00
1 parent 45a49f3d6d
commit 135bb04f0d
27 files changed
+1277 -8

No files matched your search

+88
View File
@@ -163,6 +163,26 @@ const sessionListResponse = z
})
.meta({ id: "SessionListResponse" });
const trustedDeviceListResponse = z
.object({
devices: z.array(
z.object({
id: z.string(),
label: z
.string()
.nullable()
.describe("Coarse, IP-free device label (e.g. 'Firefox on macOS')."),
createdAt: z.iso.datetime({ offset: true }),
lastUsedAt: z.iso.datetime({ offset: true }),
expiresAt: z.iso.datetime({ offset: true }),
isCurrent: z
.boolean()
.describe("True for the device making this request."),
}),
),
})
.meta({ id: "TrustedDeviceListResponse" });
const signOutEverywhereResponse = z
.object({
sessionsRevoked: z
@@ -647,6 +667,74 @@ export const authPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/auth/me/trusted-devices": {
get: {
tags: ["Auth"],
summary: "List trusted devices",
description:
"v1.23 — the 'remember this device' list. A trusted device skips the second factor for 30 days (the password is still required). Returns only an IP-free device label + lifecycle timestamps, never the token.",
responses: {
"200": {
description: "Trusted devices for the caller.",
content: {
"application/json": {
schema: dataEnvelope(
trustedDeviceListResponse,
"TrustedDeviceListEnvelope",
),
},
},
},
...stdResponses,
},
},
delete: {
tags: ["Auth"],
summary: "Forget every trusted device",
description:
"v1.23 — revokes all trusted devices for the caller and clears the caller's own trusted-device cookie.",
responses: {
"200": {
description: "All trusted devices revoked.",
content: {
"application/json": {
schema: dataEnvelope(
z.object({ revoked: z.number().int() }),
"TrustedDeviceRevokeAllEnvelope",
),
},
},
},
...stdResponses,
},
},
},
"/api/auth/me/trusted-devices/{id}": {
delete: {
tags: ["Auth"],
summary: "Revoke a single trusted device",
description:
"v1.23 — revokes one trusted device by id, scoped to the authenticated user (a foreign id returns 404).",
responses: {
"200": {
description: "Trusted device revoked.",
content: {
"application/json": {
schema: dataEnvelope(
z.object({ revoked: z.boolean() }),
"TrustedDeviceRevokeEnvelope",
),
},
},
},
"404": {
description: "Trusted device not found or not owned by the caller.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
"/api/auth/me/security-activity": {
get: {
tags: ["Auth"],