Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.
Authentication
The authentication module owns local sessions, API tokens, HTTP Basic authentication for WebDAV, configured authentication providers, and Sync-in
TOTP verification.
Sync-in supports three authentication providers:
| Provider | Value | Responsibility |
|---|---|---|
| MySQL | mysql |
Authenticate local users against the password stored in the Sync-in database. |
| LDAP | ldap |
Authenticate regular users against LDAP, with controlled local fallback for guests, administrators, application scopes, and configured fallback cases. |
| OpenID Connect | oidc |
Delegate browser authentication to one OIDC provider, then issue local Sync-in cookies. See providers/oidc/oidc.md for the detailed OIDC contract. |
Regardless of provider, Sync-in authorizes requests with local user records, roles, permissions, and locally issued tokens after authentication succeeds.
Link pseudo-users are excluded from normal authentication lookups. They can only authenticate through the public link flow, using the link UUID and optional link password.
Browser session flow
The browser login endpoint is:
POST /api/auth/login
It uses local credential validation through the configured provider. When Sync-in TOTP is disabled globally or the user has no TOTP secret, a successful login creates the final session cookies directly.
When TOTP is enabled globally and the user has a TOTP secret, the password step does not create a final session. It creates a temporary 2FA session instead:
sync-in-access -> tokenType access_2fa, path /api/auth/2fa/login/verify
sync-in-csrf -> temporary CSRF value
The client then posts the verification code to:
POST /api/auth/2fa/login/verify
After a valid TOTP or recovery code, Sync-in clears the temporary 2FA access cookie and issues the final cookies.
Cookies and tokens
Final browser sessions use four cookie types:
| Token | Default cookie | Path | Purpose |
|---|---|---|---|
access |
sync-in-access |
/ |
Short-lived JWT used for normal authenticated HTTP requests. |
refresh |
sync-in-refresh |
/api/auth/refresh |
Longer-lived JWT used to renew browser cookies. |
ws |
sync-in-ws |
/socket.io |
JWT dedicated to websocket authentication. |
csrf |
sync-in-csrf |
/ |
Signed CSRF token paired with the access or refresh JWT CSRF claim. |
Access, refresh, websocket, and temporary 2FA tokens are HTTP-only cookies. CSRF cookies are intentionally readable by the client so the signed value
can be echoed in the sync-in-csrf request header.
Cookie-backed unsafe requests validate CSRF only when the matching access, refresh, or temporary 2FA token came from cookies. Safe methods skip CSRF validation. Bearer-token requests are not tied to the CSRF cookie.
POST /api/auth/refresh rotates the browser access, refresh, websocket, and CSRF cookies while preserving the remaining refresh-token lifetime.
POST /api/auth/logout clears all known authentication cookies on their configured paths.
API token flow
Non-browser clients can request bearer tokens from:
POST /api/auth/token
POST /api/auth/token/refresh
POST /api/auth/token uses the same password provider as browser login. If Sync-in TOTP is enabled for the user, the request must also pass the TOTP
verification guard with the sync-in-two-fa-code header. The password was already validated by the local guard, so this route does not require the
sync-in-two-fa-password header.
POST /api/auth/token/refresh accepts a valid refresh token and returns a new access token plus a refresh token whose expiration is capped by the
remaining lifetime of the original refresh token.
TOTP lifecycle
TOTP is controlled by auth.mfa.totp.enabled. The default is enabled. A user is considered TOTP-enabled when their secrets contain twoFaSecret.
Initialization:
GET /api/auth/2fa/enablegenerates a secret and QR code for the current user.- The pending secret is cached for five minutes and encrypted when
auth.encryptionKeyis configured. POST /api/auth/2fa/enableverifies the user's password and TOTP code before persisting the secret.- Enabling TOTP generates five single-use recovery codes.
Disabling TOTP requires the current password plus a valid TOTP or recovery code. Administrator reset of another user's TOTP requires administrator role and the administrator's own 2FA verification guard.
TOTP codes are six digits. Verification accepts the current time window with a drift of one window. Recovery codes are stored in user secrets,
encrypted when auth.encryptionKey is configured, and consumed transactionally; a used recovery code cannot be reused.
Sensitive routes that use the shared 2FA verification guard read these headers:
sync-in-two-fa-password
sync-in-two-fa-code
Routes can choose whether the password is always required, never required, or used only as a fallback when TOTP is not enabled.
Application scopes
Some authentication flows are non-interactive and pass an AUTH_SCOPE to the configured provider:
| Scope | Used by | TOTP handling |
|---|---|---|
client |
Desktop, CLI, and sync-core client registration | The account password can authenticate the first registration, then a TOTP or recovery code is required when TOTP is enabled for the user. |
webdav |
HTTP Basic authentication on WebDAV routes | TOTP cannot be challenged interactively; see the WebDAV rule below. |
Scoped authentication can validate app passwords stored in user secrets. App passwords are scoped to one application and do not grant access to other scopes.
App passwords
Generating and revoking app passwords are self-service actions protected by the usual Sync-in step-up: TOTP when enabled, otherwise local password confirmation.
WebDAV and TOTP
WebDAV uses HTTP Basic authentication and cannot complete the interactive Sync-in TOTP challenge. For that reason, the WebDAV password rule is:
- if Sync-in TOTP is disabled globally or the user has no TOTP secret, WebDAV accepts the primary account password or a valid WebDAV app password;
- if Sync-in TOTP is enabled globally and the user has a TOTP secret, WebDAV does not accept the primary account password;
- in that 2FA case, WebDAV accepts only a valid app password with
app: webdav.
The primary password comparison is still executed for scoped-auth timing, but a successful primary-password match is ignored for 2FA-protected WebDAV.
Only successful WebDAV Basic-auth results are cached for the configured access-token lifetime (15 minutes by default). Failed credentials and refusals caused by account state are never cached, so credentials can be checked again immediately after an account is unlocked (subject to rate limits). Cached successful results for a user are cleared after changes to their login, email, password, active state, role, direct or group-derived permissions, or TOTP state, after account deletion, and when a WebDAV app password is revoked. Cache keys use a domain-separated HMAC-SHA-256 keyed with the access-token secret; the cache therefore does not persist an unkeyed fast digest of the submitted password.
Client registration
The desktop and CLI client registration flow uses AUTH_SCOPE.CLIENT:
- The client sends login, password, client identifier, and client information.
- The configured provider validates the account password under the
clientscope. - If TOTP is enabled for the user, the registration must also include a valid TOTP or recovery code.
- Sync-in creates or reuses the registered client and returns a client token.
Client tokens are long-lived registration credentials, not user passwords. Their default lifetime is 120d; a token is renewed when it has less than
60d remaining. Authenticated clients can ask Sync-in to issue either browser cookies or bearer tokens for the registered owner.
Provider-specific notes
MySQL delegates password checks directly to the local user manager.
LDAP authenticates regular users against LDAP. Local password authentication is still used for guest users and application scopes. Administrators can use local password fallback as break-glass access when LDAP authentication fails according to the configured fallback rules. Administrator accounts should therefore have a local Sync-in password configured and kept available for break-glass recovery.
OIDC browser login delegates the primary authentication and MFA policy to the identity provider. Sync-in does not add its local TOTP challenge after a
successful OIDC callback. Local password paths can still exist with OIDC selected for guests, administrators, scoped application authentication, and
regular users when explicitly enabled. OIDC-created users can set a known local password from their profile while authenticated through OIDC, for
local password access or password-fallback step-up. Users authenticated through OIDC can also configure Sync-in TOTP from their profile; enable,
reset, and disable flows still verify the local Sync-in password. Administrator accounts should have a local Sync-in password configured and kept
available for break-glass recovery. See providers/oidc/oidc.md.
Authentication rate limiting
Sensitive authentication and verification routes explicitly use AuthRateLimitGuard. The guard is selective rather than global: an unguarded route
does not inherit this policy merely because it belongs to the authentication module.
The table covers credential and challenge routes plus notable routes without a Sync-in limiter. Every configured limit below uses a rolling 60-second
window and a 60-second block. Route/IP limits return HTTP 429; the shared local-password work limit returns the generic HTTP 401.
| Authentication path | HTTP route(s) | Route/IP limit | Additional limit |
|---|---|---|---|
| Local password (MySQL, OIDC local access, LDAP guest or fallback) | POST /api/auth/loginPOST /api/auth/token |
6 requests / 60 s per route and IP | 20 local password validations / 60 s per normalized login or email, shared across routes, scopes, and IPs. |
| Direct LDAP authentication | POST /api/auth/loginPOST /api/auth/token |
6 / 60 s per route and IP | A valid LDAP entry skips the local-password limit. If LDAP returns no entry, the local validator runs, including its dummy path. |
| Desktop/CLI registration with a password | POST /api/app/sync/register |
6 / 60 s per route and IP | 20 / 60 s when the local validator runs. A valid LDAP entry skips this limit; no-entry results consume it. |
| Client-token exchange | POST /api/app/sync/auth/:type |
6 / 60 s per route and IP | No local-password limit; this route validates a registered client token. |
| WebDAV HTTP Basic | PROPFIND /PROPFIND /webdavWebDAV operations on /webdav/* |
60 provider lookups / 60 s per IP | 20 / 60 s when local password validation runs. Only successful credentials are cached and skip both limits; OPTIONS skips Basic auth. |
| TOTP verification or management | POST /api/auth/2fa/login/verifyPOST /api/auth/2fa/enablePOST /api/auth/2fa/disablePOST /api/auth/2fa/reset/user/:id |
6 / 60 s per route and IP | No shared local-password limit, including when a TOTP management route checks the current password. |
| Public-link validation, access, and password | GET /api/app/link/validation/:uuidGET /api/app/link/access/:uuidPOST /api/app/link/auth/:uuid |
6 / 60 s per route and IP | Link-password attempts have their own account lock, not the shared local-password limit. |
| Public-link download | GET /api/app/link/download/:uuid |
30 / 60 s per route and IP | No shared local-password limit. |
| OIDC browser redirect and callback | GET /api/auth/oidc/loginGET /api/auth/oidc/callback |
No Sync-in route/IP limit | No local-password limit; primary authentication occurs at the identity provider. |
| Refresh or existing-session registration | POST /api/auth/refreshPOST /api/auth/token/refreshPOST /api/app/sync/register/auth |
No AuthRateLimitGuard |
These paths validate an existing token or session, not a submitted account password. |
The default policy allows six requests for the same route and client IP in a rolling 60-second window. Every request that reaches the guard counts,
regardless of its authentication outcome. The next request starts a 60-second block and returns HTTP 429 with
Too many requests. Please try again later. Requests received during that block do not extend it. Rate-limit response headers expose the configured
limit, remaining requests, reset delay, and block retry delay. Individual routes can override the default policy when their traffic profile requires
another limit.
Nest builds each limiter key from the controller handler, throttler name, and req.ip, which keeps counters separate between routes and clients. The
client address therefore follows Fastify's server.trustProxy configuration. Limiter state is updated atomically in the configured shared cache,
whether the cache adapter is MySQL or Redis, so concurrent server workers observe the same counter and block period.
Rate limiting and the temporary account lock cover different levels. The route limiter bounds requests from one IP before expensive authentication
work. A separate shared limiter bounds local password checks for each submitted login or email (case-insensitive) to 20 attempts in a rolling
60-second window, across IPs and authentication scopes. Dummy checks after unsuccessful LDAP authentication also count. Once exceeded, both existing
and unknown identifiers skip bcrypt and receive the same generic HTTP 401 as invalid credentials on local password paths. All local password
validation attempts count, including successful ones; cached successful WebDAV credentials do not require another validation.
The temporary account lock still prevents authentication after repeated failures, but password checks below the shared limit continue so its state
cannot be inferred from a pre-authentication response. WebDAV does not cache any failed validation, including one denied by the shared work limit.
Repeated failures therefore consume the per-IP and, for local password validation, per-identifier limits. The former negative cache only helped with
repeated identical login/password pairs; changing the submitted password bypassed it. These limits are not a global CPU budget: a distributed source
can still spread attempts across many identifiers, so an edge or reverse-proxy limit remains a complementary deployment control. WebDAV HTTP Basic
authentication uses its own per-IP rate-limit policy rather than the default route guard described here.