###############################################################################
# OAuth Providers — Microsoft 365 + Google (B-2.4)
###############################################################################
#
# These providers complement (do NOT replace) the generic OIDC SSO at
# config/env.sso.example. Both can be enabled simultaneously: users see
# Microsoft 365, Google, and SSO buttons on /login, plus the magic-link
# fallback that does not require any OAuth provider.
#
# IMPORTANT — Loi 25 art. 14 (consent must be granular, free, informed):
# OAuth signups still require Loi 25 consent capture via
# /auth/oauth/finish-signup BEFORE the User row is created. Existing
# users (matched by sso_subject or email) skip the consent page and log
# in directly.
#
# Magic-link login (/auth/magic-link, /auth/magic-link/<token>) reuses
# the SMTP settings from env.email.example — no additional env vars needed.

###############################################################################
# Microsoft 365 (Microsoft Entra ID, formerly Azure AD)
###############################################################################
# 1. Register a new app at https://entra.microsoft.com
#    > Identity > Applications > App registrations > New registration
# 2. Set the redirect URI to:
#       https://your-domain.example/auth/oauth/microsoft/callback
# 3. Generate a client secret under Certificates & secrets > Client secrets
# 4. Set MS_CLIENT_ID to the Application (client) ID
# 5. Set MS_CLIENT_SECRET to the secret VALUE (NOT the secret ID)
#
# Tenant restriction: by default the OAuth flow accepts users from any
# Microsoft tenant (server_metadata_url uses /common/). To restrict to a
# specific organization, edit src/auth/oauth_providers.py and replace
# /common/ with your tenant ID (e.g. /your-tenant-id-guid/).
#
# MS_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# MS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

###############################################################################
# Google (Google Cloud Console)
###############################################################################
# 1. Create an OAuth client at https://console.cloud.google.com
#    > APIs & Services > Credentials > Create Credentials > OAuth client ID
#    Application type: "Web application"
# 2. Set the redirect URI to:
#       https://your-domain.example/auth/oauth/google/callback
# 3. Configure the OAuth consent screen in the same console
#    (must be in "Production" status to accept users outside the test list)
# 4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the credentials page
#
# GOOGLE_CLIENT_ID=xxxxxxxxxxxx-xxxxxxxxxxxx.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

###############################################################################
# Notes
###############################################################################
#
# Token storage:
# - sso_provider stores the literal string "microsoft" or "google"
# - sso_subject stores the OAuth `sub` claim (provider-issued user ID)
# - email_verified is set to True automatically (the provider has
#   already verified the email address)
# - password is NULL for OAuth-only accounts; users can set a password
#   later via /forgot-password if they want a fallback login method
#
# Magic-link tokens:
# - Stateless via itsdangerous.URLSafeTimedSerializer
# - 15-minute expiry, signed with SECRET_KEY + salt 'magic-link-login'
# - No DB column — tokens are not single-use within the 15-min window
# - SMTP must be configured (see env.email.example) for the link to send

###############################################################################
# WebAuthn / Passkey (B-2.6)
###############################################################################
# Phishing-resistant 2nd factor via FIDO2 hardware keys (YubiKey etc.) and
# device biometrics (Touch ID, Windows Hello). Browsers strictly enforce that
# the values below match the page making the WebAuthn API call:
#
# - WEBAUTHN_RP_ID : the registrable host name (NO scheme, NO port). Must
#   match the eTLD+1 of the page or be a parent domain. For dictia.ca use
#   'dictia.ca'; for staging at app.staging.dictia.ca use 'dictia.ca' or
#   'staging.dictia.ca'. Defaults to 'localhost' for local development.
#
# - WEBAUTHN_RP_NAME : the display name shown to the user inside their
#   authenticator's prompt (e.g. 'Sign in to DictIA'). Defaults to 'DictIA'.
#
# - WEBAUTHN_ORIGIN : the FULL origin including scheme + host + optional
#   port. MUST equal window.location.origin on the client side. Mismatches
#   are rejected by the browser before the request even reaches the server.
#   Defaults to 'http://localhost:8899' for local development.
#
# Credentials are persisted in user.webauthn_credentials (JSON column,
# added in B-2.1). Each credential dict contains base64url id, public_key,
# sign_count (anti-cloning per WebAuthn §6.1.1), transports, name, and
# created_at. The 4 JSON endpoints (register/begin, register/finish,
# auth/begin, auth/finish) are CSRF-exempt at Flask-WTF level because
# CSRFProtect cannot read tokens from a JSON body without app-wide config.
# An X-CSRFToken header is still sent by the client as defence-in-depth.
#
# WEBAUTHN_RP_ID=dictia.ca
# WEBAUTHN_RP_NAME=DictIA
# WEBAUTHN_ORIGIN=https://dictia.ca
