Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.
Two-Factor Authentication
Sync-in provides local two-factor authentication (2FA) through TOTP. This module is not selected by auth.provider; it is a shared step-up layer used
by local password authentication, LDAP authentication, selected account-management routes, administrator actions, API token issuance, and client
registration.
The current implementation supports:
- six-digit TOTP codes;
- QR-code setup from an
otpauth://URL; - pending setup secrets cached for five minutes;
- optional encryption of stored TOTP secrets and recovery codes with
auth.encryptionKey; - five single-use recovery codes generated when TOTP is enabled;
- browser login verification through a temporary 2FA cookie;
- bearer-token issuance with TOTP verification through a request header;
- current-password confirmation for enable, disable, and selected step-up routes;
- administrator reset of another user's TOTP after administrator step-up verification;
- local-password fallback for routes that require a step-up when the user has no active TOTP secret.
TOTP is controlled globally by auth.mfa.totp.enabled, which defaults to true. A user is considered TOTP-enabled when their stored secrets contain
twoFaSecret.
Browser login flow
- The client posts credentials to
/api/auth/login. - The configured password provider validates the login and password.
- If global TOTP is disabled or the user has no
twoFaSecret, Sync-in issues the final local session cookies immediately. - If TOTP is required, Sync-in issues only temporary 2FA cookies and returns a response whose user payload contains
twoFaEnabled: true. - The client posts a TOTP code or recovery code to
/api/auth/2fa/login/verify. - Sync-in validates the temporary 2FA access cookie, CSRF header, account access, and verification code.
- On success, Sync-in issues the final local session cookies and clears the temporary 2FA access cookie.
The temporary access cookie uses the same cookie name as the regular access cookie, but is scoped to /api/auth/2fa/login/verify and has token type
access_2fa. The temporary CSRF cookie uses the normal CSRF cookie name and is replaced by the final CSRF cookie after successful verification.
Temporary 2FA cookies expire after five minutes. The temporary JWT intentionally contains only the minimum identity data required to finish login:
user ID, login, language, role, and twoFaEnabled: true.
Setup flow
TOTP setup starts with:
GET /api/auth/2fa/enable
The route is authenticated and limited to regular users. It returns:
| Field | Description |
|---|---|
secret |
TOTP secret shown to the user for manual authenticator setup. |
qrDataUrl |
QR code data URL generated from the TOTP setup URL. |
Sync-in stores the pending setup secret in cache for five minutes. The response disables caching with Cache-Control: no-store.
Users whose browser session was created through OIDC can open this setup flow from their profile. The final enable or reset request still verifies the current local Sync-in password; OIDC-created users must set a known local password first.
The user completes setup with:
POST /api/auth/2fa/enable
Body:
| Field | Required | Description |
|---|---|---|
password |
Yes | Current local Sync-in password. |
code |
Yes | TOTP code generated from the pending secret. |
isRecoveryCode |
No | Shared verification flag; setup is normally completed with a TOTP code. |
When the password and code are valid, Sync-in stores the TOTP secret in user secrets, generates five recovery codes, removes the pending cache entry, and sends an email notification when mail notifications are available. Recovery codes are returned only in this enable response.
If the pending secret has expired, setup fails and the user must start again with GET /api/auth/2fa/enable.
Disable flow
TOTP is disabled with:
POST /api/auth/2fa/disable
Body:
| Field | Required | Description |
|---|---|---|
password |
Yes | Current local Sync-in password. |
code |
Yes | TOTP code or recovery code. |
isRecoveryCode |
No | Set to true when code is a recovery code. |
On success, Sync-in removes both twoFaSecret and recoveryCodes from user secrets and sends an email notification when mail notifications are
available.
Recovery codes
Enabling TOTP generates five recovery codes. They are stored in user secrets after applying the same secret encryption rule as the TOTP secret.
Recovery codes are single-use. Validation is transactional: only the request that still finds the encrypted code in the latest user secrets can
consume it successfully. A consumed or unknown recovery code returns Invalid code.
Recovery codes can be used for:
- browser login verification;
- disabling TOTP;
- client registration when the user has TOTP enabled.
Step-up guards that read the sync-in-two-fa-code header validate that header as a TOTP code only; they do not set isRecoveryCode.
Step-up guards
Some authenticated routes require a fresh 2FA or password step-up. Sync-in exposes three guard variants:
| Guard | Password header | TOTP header | Behavior |
|---|---|---|---|
AuthTwoFaVerificationGuard |
Required | Required only when TOTP is active | Used for destructive administrator actions. |
AuthTwoFaVerificationWithoutPasswordGuard |
Not required | Required only when TOTP is active | Used when the request already proved the password or only needs TOTP. |
AuthTwoFaVerificationOrPasswordGuard |
Required only when TOTP is inactive | Required when TOTP is active | Used for app-password generation and revocation. |
The shared headers are:
sync-in-two-fa-password
sync-in-two-fa-code
When global TOTP is disabled, or when the loaded user has no TOTP secret, guards that allow password fallback use the current local password instead of a TOTP code. Guards without password fallback simply allow the request when TOTP is inactive.
API tokens and client registration
Bearer tokens are requested with:
POST /api/auth/token
The password provider validates credentials first. If global TOTP is enabled and the user has a TOTP secret, the request must include:
sync-in-two-fa-code: 123456
The token route does not require sync-in-two-fa-password because the password was already validated by the local authentication guard.
Desktop and CLI client registration also uses the configured password provider first. When TOTP is active for the user, the registration request must
include a code value. Sync-in first validates it as a TOTP code, then as a recovery code if TOTP validation fails.
WebDAV cannot complete an interactive TOTP challenge. When global TOTP is enabled and the user has a TOTP secret, WebDAV accepts only a valid WebDAV-scoped app password, not the primary account password.
Password attempts and account access
TOTP verification always reloads the user and applies the normal account-access checks. A missing user, inactive account, or account within the 15-minute password-attempt lock period is rejected before code validation. The lock expires automatically and blocked requests do not extend it.
After a successful password step for a TOTP-enabled login, password attempts are preserved until the TOTP step succeeds. A successful TOTP step resets attempts; a failed password or failed code increments attempts through the shared access tracking path.
Enable and disable requests verify the current local password before validating the code. A wrong password updates access tracking as a failed 2FA
operation and returns Incorrect code or password.
Secret storage
If auth.encryptionKey is configured, Sync-in encrypts:
- pending setup secrets before storing them in cache;
- persisted
twoFaSecretvalues; - persisted recovery codes.
If auth.encryptionKey is not configured, these values are stored as plain secrets in the configured cache or database user secrets.
Changing or removing auth.encryptionKey after users enable TOTP makes existing TOTP secrets and recovery codes unreadable.
Configuration reference
TOTP settings
| Setting | Default | Description |
|---|---|---|
auth.mfa.totp.enabled |
true |
Enables local Sync-in TOTP enforcement for users with twoFaSecret. |
auth.mfa.totp.issuer |
Sync-in |
Issuer label embedded in the TOTP setup URL and displayed by authenticator apps. |
Related settings
| Setting | Default | Description |
|---|---|---|
auth.encryptionKey |
Unset | Encrypts user secrets, including TOTP secrets and recovery codes. |
auth.token.access.secret |
Required | Also used as the signing secret for temporary access_2fa tokens. |
auth.token.csrf.secret |
Derived from refresh token config | Used to sign the CSRF cookie checked during 2FA login verification. |
The temporary access_2fa and csrf_2fa token configurations are derived at startup. They reuse the normal access and CSRF cookie names and use a
fixed five-minute expiration.
Current boundaries
- Only TOTP is implemented; WebAuthn, passkeys, SMS, email OTP, and push approval are not implemented.
- TOTP settings are global; there is no per-provider or per-group TOTP policy.
- Recovery codes are generated only when TOTP is enabled and are returned only once.
- Step-up header verification validates
sync-in-two-fa-codeas a TOTP code only, not as a recovery code. - OIDC browser login does not receive an additional Sync-in TOTP challenge after the OIDC callback; MFA for that path is expected to be enforced by the identity provider.
- Enable and disable flows require the current local Sync-in password, even when the current browser session was created by OIDC.
- TOTP secrets and recovery codes depend on
auth.encryptionKeywhen encryption is enabled; changing that key requires a reset of existing user TOTP state.