Skip to content

Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.

17.6 KB
Raw Blame

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:

  1. GET /api/auth/2fa/enable generates a secret and QR code for the current user.
  2. The pending secret is cached for five minutes and encrypted when auth.encryptionKey is configured.
  3. POST /api/auth/2fa/enable verifies the user's password and TOTP code before persisting the secret.
  4. 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:

  1. The client sends login, password, client identifier, and client information.
  2. The configured provider validates the account password under the client scope.
  3. If TOTP is enabled for the user, the registration must also include a valid TOTP or recovery code.
  4. 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/login
POST /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/login
POST /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 /webdav
WebDAV 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/verify
POST /api/auth/2fa/enable
POST /api/auth/2fa/disable
POST /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/:uuid
GET /api/app/link/access/:uuid
POST /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/login
GET /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/refresh
POST /api/auth/token/refresh
POST /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.