Authentication and Security Model

Security Boundaries

SyncTV separates security into several boundaries:

• User authentication: password, OPAQUE, WebAuthn/passkey, email codes, and OAuth2.
• User 2FA: optional per user and requires at least two local authentication methods.
• Access tokens: issued after login completion for HTTP/gRPC business APIs.
• Management control plane: the CLI management endpoint, separate from user tokens.
• Provider upstream access: providers own upstream headers and credentials; the proxy does not guess client headers.
• Cluster internal authentication: inter-node gRPC uses cluster.secret.

Local login and OAuth2 are separate trust paths. When 2FA is enabled, local login must complete a second factor. OAuth2 does not count as local 2FA, but it can independently issue an accepted authentication context.

Login Methods and 2FA

Method	First factor	Second factor	Notes
Password/OPAQUE	Yes	Available only when the server returns MFA_METHOD_PASSWORD	OPAQUE login is not the same as the password MFA verifier
WebAuthn/passkey	Yes	Yes	Requires WebAuthn configuration and a bound credential
Email code	Yes	Yes	Requires SMTP and email-code delivery
OAuth2	Yes	No	OAuth2 does not participate in local 2FA, but 2FA-enabled users may log in with OAuth2

Before enabling 2FA, SyncTV verifies that the user has at least two usable local methods. After enabling 2FA, local single-factor login creates an MFA session instead of immediately issuing final tokens.

Note

OAuth2 is an independent login trust source. It is not counted as a local 2FA first or second factor. A 2FA-enabled user can still log in with OAuth2, and OAuth2-issued tokens are accepted for that login path.

Token Context

After 2FA is enabled, old single-factor refresh tokens should not keep rotating the session. Tokens issued after MFA or OAuth2 carry an accepted authentication context.

Semantics:

• 2FA disabled: normal local login, MFA login, and OAuth2 tokens follow normal token rules.
• 2FA enabled: local login must complete a second factor; refresh tokens must come from MFA or OAuth2 context.
• 2FA disabled again: single-factor and MFA/OAuth2 contexts are accepted until token expiry or revocation.

MFA Sessions

When a local first factor succeeds and a second factor is required, SyncTV creates a short-lived MFA session instead of issuing final tokens.

Client flow:

1. Complete the first-factor login request.
2. If MFA is required, read the remaining available methods.
3. If email is available, call the email-code send API immediately.
4. Complete MFA with the session ID and second-factor proof.
5. Store the final access and refresh tokens.

Failed MFA password attempts are recorded by brute-force protection and cannot bypass the normal password failure counters.

User Preferences and Security Settings

User preferences store user-level settings. two_factor_enabled is security-sensitive.

Constraints:

• Enabling 2FA requires at least two usable local methods.
• Removing a passkey while 2FA is enabled must still leave at least two usable local methods. Other authentication-method removal flows should follow the same product rule.
• Admin-initiated preference updates must respect role hierarchy. A non-root admin cannot modify root or equally privileged users.

Management Control Plane

Management gRPC is used by the CLI and operational commands.

Production rules:

• Prefer Unix socket transport.
• If using TCP, set management.auth_token.
• Do not expose management TCP publicly.
• Inject tokens from files or secret managers.
• Keep management.enable_reflection disabled in production.

The management token is not a user access token. Treat it as infrastructure-level secret material.

Provider and Proxy Security

Providers decide upstream request headers. The proxy layer executes provider-supplied headers only.

Consequences:

• Raw client Range, Accept, User-Agent, and similar headers are not automatically forwarded by the proxy.
• If an upstream requires Range, the provider must explicitly select it.
• If a direct URL is bound to User-Agent, client-facing headers and proxy upstream headers should match.
• If a client cannot set required headers, use proxy mode.

See Media Providers for credential configuration and Playback and Proxy for direct, proxy, and playback-info selection.

Required Reading

• Security and Secrets: Configure JWT, OPAQUE, provider credential encryption, password policy, CORS, and trusted proxies.
• Email and OAuth2: Configure email codes, SMTP, and runtime OAuth2 provider settings.
• WebAuthn: Configure passkey RP ID, origins, allowed origins, and challenge timeout.
• Rate Limits: Configure HTTP, gRPC, chat, WebSocket, and authentication rate limits.