homeio

1/**
2 * Shared contracts for the auth domain. Lives in `lib/shared/` so it can be
3 * imported from both server routes and client UI without crossing the
4 * `server-only` boundary.
5 */
6
7export type TwoFactorErrorCode =
8  | "already_enabled"
9  | "not_enabled"
10  | "not_enrolled"
11  | "no_pending_enrollment"
12  | "invalid_totp"
13  | "invalid_backup_code"
14  | "partial_auth_expired"
15  | "partial_auth_consumed"
16  | "too_many_attempts";
17
18/**
19 * Response from `POST /api/v1/auth/2fa/setup`. The server has persisted an
20 * unconfirmed `totp_secret` on the user row; calling `verify` with a valid
21 * code is what flips `totp_enabled = true`.
22 *
23 * `qrCodeSvg` is a complete `<svg ...>...</svg>` element ready to drop into
24 * the DOM. `secret` is the base32 string for users whose authenticator app
25 * cannot scan the QR.
26 */
27export type TwoFactorSetupResponse = {
28  secret: string;
29  otpAuthUrl: string;
30  qrCodeSvg: string;
31};
32
33export type TwoFactorVerifyRequest = {
34  code: string;
35};
36
37export type TwoFactorVerifyResponse = {
38  enabled: true;
39  enrolledAt: string;
40  backupCodes: string[];
41};
42
43export type TwoFactorDisableRequest = {
44  code: string;
45};
46
47export type TwoFactorDisableResponse = {
48  enabled: false;
49};
50
51export type TwoFactorStatus = {
52  enabled: boolean;
53  enrolledAt: string | null;
54};
55
56/**
57 * Response shape for `POST /api/auth/login`.
58 *
59 * Non-TOTP users see the original `{ id, username }` payload bit-for-bit;
60 * existing clients keep working without any code change. Users with TOTP
61 * enabled get the second branch instead — no session cookie is issued and
62 * the caller must finish the flow at `/api/v1/auth/login/totp` (A8) using
63 * the short-lived `partialAuthToken`. Clients discriminate by the presence
64 * of `requiresTotp`.
65 */
66export type LoginSuccessData = {
67  id: string;
68  username: string;
69};
70
71export type LoginRequiresTotpData = {
72  requiresTotp: true;
73  partialAuthToken: string;
74};
75
76export type LoginResponseData = LoginSuccessData | LoginRequiresTotpData;
77
78/**
79 * Payload returned by `GET /api/auth/me`. Embeds the 2FA status so the
80 * settings UI can render the enrolment badge without an extra round-trip.
81 */
82export type CurrentUserData = {
83  id: string;
84  username: string;
85  isDemoMode?: boolean;
86  twoFactor: TwoFactorStatus;
87};
88