Convilyn Auth API (1.0.0)

Creates a new user account and sends verification email.

Important:

• User does NOT receive tokens immediately after signup
• Email verification is REQUIRED before signin
• Verification email is sent automatically
• User must verify email then signin separately

Authenticates user with email and password.

Requirements:

• Email must be verified (403 if not)
• Account must not be locked (423 if locked)
• Account must not be disabled (403 if disabled)

Security:

• 5 failed attempts triggers 15-minute account lock
• Lock expires automatically after duration

Revokes the refresh token for current session.

Note: Always returns success even if token is invalid (security best practice).

Revokes all refresh tokens for the authenticated user.

Use this when:

• User suspects account compromise
• User wants to sign out everywhere
• After password change (optional)

Generate new access token and rotate refresh token.

Token Rotation (Security Feature):

• Each refresh generates a NEW refresh token
• Old refresh token is invalidated immediately
• Client MUST store and use the new refresh token

Reuse Detection (Anti-Replay Attack):

• If an old/rotated token is reused, it indicates a potential token theft
• ALL user sessions are immediately revoked
• User must re-authenticate on all devices

Important: Always update stored refresh token after this call!

Confirms user's email using verification token from email.

Token characteristics:

• One-time use only
• Expires after 24 hours
• Previous tokens are invalidated when new one is requested

Sends a new verification email.

Security (Anti-enumeration):

• Always returns success message regardless of whether email exists
• This prevents attackers from discovering valid email addresses
• Check server logs for actual delivery status

Sends password reset email with secure token.

Security (Anti-enumeration):

• Always returns success regardless of whether email exists
• This prevents attackers from discovering valid email addresses

Token characteristics:

• Expires after 30 minutes
• One-time use only
• Previous reset tokens are invalidated

Resets password using token from email.

Effects:

• Updates password
• Revokes ALL refresh tokens (logout from all devices)
• Sends confirmation email

Important: User must sign in again after password reset.

Changes password for currently logged-in user.

Requirements:

• Must be authenticated
• Current password must be correct
• New password must meet strength requirements

Returns profile data for the authenticated user.

Update current user's profile information.

Requires authentication.

Allows users to update:

• Display name (full_name)
• Preferred locale

Permanently delete current user's account.

Requires authentication.

Effects:

• Soft deletes user account
• Revokes all refresh tokens
• Clears refresh token cookie
• Logs out from all devices

Returns the authenticated user's notification-channel toggles.

Missing keys fall back to defaults (newsletter=false, productUpdates=true, securityAlerts=true). The client always receives a complete view.

Requires authentication.

Partial update — only keys present in the body are written.

This is the canonical unsubscribe endpoint for the marketing newsletter: send {"newsletter": false} to opt out.

Requires authentication.

Starts the Google OIDC sign-in flow.

The server generates a fresh state and PKCE code_verifier, persists them under an OAUTH_STATE#{state} item (TTL ≤ 10 min), and redirects the user agent to Google's /o/oauth2/v2/auth endpoint with code_challenge_method=S256.

Scopes: openid email profile (login only — incremental authorization is used for any future Drive/Calendar work).

Caller: front-end triggers via plain navigation (<a href> or window.location), NOT fetch, because the response is a 302 to a cross-origin URL.

Starts the GitHub OAuth sign-in flow.

The server generates a fresh state and PKCE code_verifier (S256 only — GitHub does not accept plain), persists them under an OAUTH_STATE#{state} item (TTL ≤ 10 min), and redirects to https://github.com/login/oauth/authorize.

Scopes: read:user user:email — user:email is required because GET /user does not return private emails.

Caller: front-end triggers via plain navigation.

Receives Google's authorization-code redirect.

The server:

1. Looks up the OAUTH_STATE#{state} item; rejects if missing, expired, or already consumed (one-shot).
2. Exchanges code + code_verifier for tokens at https://oauth2.googleapis.com/token.
3. Verifies the returned id_token (aud, iss, exp, signature) against Google's published JWKs.
4. Upserts an OAuthAccount keyed by Google sub (NOT email). If no Convilyn user is linked to that sub:
   • If id_token.email_verified is true and the email is not present on any existing Convilyn user → create a new Convilyn user and link.
   • If the email matches an existing email/password account that is NOT already linked to Google → return 409 OAuthLinkingRequired (no automatic merge).
5. Issues Convilyn access_token + HttpOnly refresh_token cookies (same shape as /auth/signin) and redirects to redirect_to.

Receives GitHub's authorization-code redirect.

The server:

1. Looks up the OAUTH_STATE#{state} item; rejects if missing, expired, or already consumed (one-shot).
2. Exchanges code + code_verifier for an access_token at https://github.com/login/oauth/access_token.
3. Calls GET /user to obtain the GitHub id (the stable identity key) and profile fields.
4. Calls GET /user/emails and selects the entry where primary == true && verified == true. If no such entry exists, returns 401 AUTH_OAUTH_TOKEN_INVALID.
5. Upserts an OAuthAccount keyed by GitHub id (NOT email or login). Linking policy is identical to the Google callback — a colliding email on an existing email/password account returns 409 OAuthLinkingRequired.
6. Issues Convilyn access_token + HttpOnly refresh_token cookies and redirects to redirect_to.