feat(auth): document and verify Cloudflare Access OIDC sign-in

[absolutepraya]

Goal

Make Cloudflare Access a documented, tested optional OpenID Connect sign-in provider for this fork.

This should be application-level SSO through Karakeep's existing generic OIDC provider, not a Cloudflare Access self-hosted application in front of the whole hostname. The latter would add a second login and can interfere with browser extensions, mobile clients, webhooks, RSS and other non-browser traffic.

Current state

• Karakeep already registers a generic OIDC provider when OAUTH_WELLKNOWN_URL is set.
• It supports PKCE and state checks, configurable scopes, provider name, timeout, password-auth disablement and automatic OAuth redirect.
• Its documented callback is <NEXTAUTH_URL>/api/auth/callback/custom.
• No Cloudflare Access-specific recipe, compatibility verification, or regression coverage exists.
• The existing Managed OAuth configuration used for the remote MCP is not the correct integration. This needs a separate Cloudflare Access Generic OIDC SaaS application, which exposes a per-client OIDC discovery URL, client ID and client secret.

Cloudflare references:

• Generic OIDC SaaS application
• OIDC configuration endpoint details

Scope

• Add a fork-owned deployment guide for configuring a Cloudflare Access Generic OIDC SaaS application:
  • redirect URI: <NEXTAUTH_URL>/api/auth/callback/custom
  • discovery URL: https://<team>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<client-id>/.well-known/openid-configuration
  • client ID and client secret from the same Access application
  • scopes: openid email profile
  • least-privilege Access allow policy and an explicit deny/unauthorized-user outcome
• Provide a production environment example using the existing OAUTH_* and auth-mode variables. Use placeholders only, never real values.
• Define migration behavior for an existing local account:
  • retain local password login by default;
  • document the explicit opt-in needed to link a trusted existing email;
  • document OAuth-only mode using DISABLE_PASSWORD_AUTH=true and OAUTH_AUTO_REDIRECT=true;
  • recommend testing in a non-production deployment before disabling the password fallback.
• Add regression coverage for provider registration and sign-in-page behavior in both mixed-auth and OAuth-only modes.
• Add an operator verification checklist: successful login, rejected unauthorized identity, callback/redirect behavior, account-linking behavior, local fallback, and logout/session expiry.
• Keep Cloudflare Access app credentials in deployment secrets only. Do not commit them, pass Access headers into the app, or enable Managed OAuth for this web-login flow.

Acceptance criteria

• A fresh self-hosted deployment can configure Cloudflare Access OIDC using only the documented values and reach a successful Karakeep sign-in.
• An identity outside the Access policy is rejected before Karakeep creates or authenticates an account.
• Existing password accounts retain access until an operator explicitly turns on OAuth-only mode.
• Existing email account linking remains opt-in and is clearly documented as safe only for the trusted Cloudflare Access issuer.
• The document distinguishes this OIDC SaaS application from an Access-protected web hostname and from MCP Managed OAuth.
• Tests cover the configuration paths added or relied upon by the guide.