feat(auth): bring opaque (RFC 9807) auth

OPAQUE (RFC 9807) implementation (using `opaque-ke` crate)

    with opaque authentfication, server will never receive the password (in the auth=password mode)
    this is a must have to create trust with users to permit end to end encryption in the future
    (we cannot know if user use the same password/passphrase for his asymetric key or his oxicloud auth,
    this is why server must never have the password)

    pass1: prepare server

src/common/config.rs

@@ -1648,6 +1648,156 @@ impl Default for OidcConfig {
     }
 }
 
+/// OPAQUE aPAKE configuration (RFC 9807, Phase 0 substrate).
+///
+/// OPAQUE is a zero-knowledge password-authenticated key exchange: the
+/// passphrase never leaves the client. This struct carries the runtime
+/// knobs the server needs (mode, ciphersuite version, persisted
+/// [`ServerSetup`] blob) plus the client-side KSF params the SPA reads
+/// out of `/api/health` to configure its Argon2.
+///
+/// **The KSF params are client-side.** RFC 9807 runs Argon2 on the client
+/// before the OPRF exchange; the server never invokes it. The params live
+/// here so the operator has one source of truth and the SPA can fetch
+/// them at page load — changing them requires re-registration for
+/// affected users.
+#[derive(Debug, Clone)]
+pub struct OpaqueConfig {
+    /// Runtime mode gate. See
+    /// [`crate::infrastructure::services::opaque_service::OpaqueMode`]
+    /// for the state-machine and the phase-plan mapping.
+    ///
+    /// Env: `OXICLOUD_OPAQUE_MODE` (`off` | `migrate` | `opaque_only`).
+    /// Default: `off`.
+    pub mode: crate::infrastructure::services::opaque_service::OpaqueMode,
+    /// Base64-encoded [`opaque_ke::ServerSetup`] blob. Generated once
+    /// per deployment and persisted verbatim — rotating this invalidates
+    /// every user's registration. Runbook: on first boot with
+    /// `OXICLOUD_OPAQUE_MODE != off`, if this is unset, print a fatal
+    /// message with a fresh setup for the operator to paste into their
+    /// env, then exit.
+    ///
+    /// Env: `OXICLOUD_OPAQUE_SERVER_SETUP`. No default.
+    pub server_setup_b64: Option<String>,
+    /// Ciphersuite version stamped into `auth.users.opaque_ciphersuite_version`
+    /// on registration. Bumping this without changing the actual
+    /// ciphersuite type alias in the service module is meaningless;
+    /// bumping this WITH a type change invalidates all envelopes.
+    ///
+    /// Env: not exposed. Compile-time constant, currently `1`.
+    pub ciphersuite_version: i16,
+    /// Client-side Argon2id memory cost in KiB. Published to the SPA so
+    /// the client can construct a matching `argon2::Argon2` before
+    /// running `ClientRegistration::start` / `ClientLogin::start`.
+    ///
+    /// Env: `OXICLOUD_OPAQUE_KSF_MEMORY_KIB`. Default: `262144` (256 MiB).
+    pub ksf_memory_kib: u32,
+    /// Client-side Argon2id iteration count.
+    ///
+    /// Env: `OXICLOUD_OPAQUE_KSF_ITERATIONS`. Default: `3`.
+    pub ksf_iterations: u32,
+    /// Client-side Argon2id parallelism (lanes).
+    ///
+    /// Env: `OXICLOUD_OPAQUE_KSF_PARALLELISM`. Default: `4`.
+    pub ksf_parallelism: u32,
+}
+
+impl Default for OpaqueConfig {
+    fn default() -> Self {
+        Self {
+            mode: crate::infrastructure::services::opaque_service::OpaqueMode::Off,
+            server_setup_b64: None,
+            ciphersuite_version: 1,
+            ksf_memory_kib: 262_144,
+            ksf_iterations: 3,
+            ksf_parallelism: 4,
+        }
+    }
+}
+
+impl OpaqueConfig {
+    /// Load OPAQUE configuration from environment variables. Mirrors the
+    /// pattern used by [`OidcConfig::from_env`] — every field falls back
+    /// to the [`Default`] impl when unset, so the config is safe to
+    /// construct even in `Off` mode.
+    pub fn from_env() -> Self {
+        use std::env;
+        let mut cfg = Self::default();
+        if let Ok(v) = env::var("OXICLOUD_OPAQUE_MODE") {
+            match crate::infrastructure::services::opaque_service::OpaqueMode::parse(&v) {
+                Some(m) => cfg.mode = m,
+                None => {
+                    tracing::warn!(
+                        target: "oxicloud::config",
+                        value = %v,
+                        "OXICLOUD_OPAQUE_MODE has an unrecognised value — keeping default (off). \
+                         Accepted: off | migrate | opaque_only"
+                    );
+                }
+            }
+        }
+        if let Ok(v) = env::var("OXICLOUD_OPAQUE_SERVER_SETUP") {
+            cfg.server_setup_b64 = Some(v);
+        }
+        if let Ok(v) = env::var("OXICLOUD_OPAQUE_KSF_MEMORY_KIB")
+            && let Ok(n) = v.parse::<u32>()
+        {
+            cfg.ksf_memory_kib = n;
+        }
+        if let Ok(v) = env::var("OXICLOUD_OPAQUE_KSF_ITERATIONS")
+            && let Ok(n) = v.parse::<u32>()
+        {
+            cfg.ksf_iterations = n;
+        }
+        if let Ok(v) = env::var("OXICLOUD_OPAQUE_KSF_PARALLELISM")
+            && let Ok(n) = v.parse::<u32>()
+        {
+            cfg.ksf_parallelism = n;
+        }
+        cfg
+    }
+
+    /// Runtime mode after cross-checking against the auth-method allowlist.
+    ///
+    /// OPAQUE is fundamentally a **password** mechanism — its only reason
+    /// to exist is to replace `POST /api/auth/login`. An operator running
+    /// OIDC-only or magic-link-only (`OXICLOUD_AUTH_METHODS=oidc` or
+    /// `=magic_link`) has no password path for OPAQUE to shadow; any
+    /// non-`Off` mode would be a no-op that still nagged them for
+    /// `OXICLOUD_OPAQUE_SERVER_SETUP` at boot.
+    ///
+    /// This helper resolves the misconfig quietly: if password isn't in
+    /// the allowlist AND OPAQUE mode is non-`Off`, we downgrade to `Off`
+    /// and emit an audit-channel INFO explaining why (so it shows up in
+    /// operator log tailing without being a startup warning that fails
+    /// health checks). Every OPAQUE-facing caller — the DI factory, the
+    /// endpoint router, the migration hook — MUST read this and never
+    /// touch `self.mode` directly.
+    pub fn effective_mode(
+        &self,
+        auth: &AuthConfig,
+    ) -> crate::infrastructure::services::opaque_service::OpaqueMode {
+        use crate::infrastructure::services::opaque_service::OpaqueMode;
+        if self.mode == OpaqueMode::Off {
+            return OpaqueMode::Off;
+        }
+        if !auth.is_method_allowed(AuthMethod::Password) {
+            tracing::info!(
+                target: "audit",
+                event = "opaque.mode_downgraded",
+                reason = "password_auth_disabled",
+                configured_mode = ?self.mode,
+                "OXICLOUD_OPAQUE_MODE is configured but password auth is disabled \
+                 via OXICLOUD_AUTH_METHODS — treating OPAQUE as off. \
+                 OPAQUE only replaces the password login path; enable password \
+                 in OXICLOUD_AUTH_METHODS to make this setting take effect."
+            );
+            return OpaqueMode::Off;
+        }
+        self.mode
+    }
+}
+
 impl OidcConfig {
     /// Load OIDC configuration from environment variables only
     pub fn from_env() -> Self {
@@ -2338,6 +2488,10 @@ pub struct AppConfig {
     pub database: DatabaseConfig,
     /// Authentication configuration
     pub auth: AuthConfig,
+    /// OPAQUE (RFC 9807) zero-knowledge password auth configuration.
+    /// Substrate only in Phase 0 — endpoints are inert until
+    /// `OXICLOUD_OPAQUE_MODE != off`.
+    pub opaque: OpaqueConfig,
     /// Feature configuration
     pub features: FeaturesConfig,
     /// OIDC configuration
@@ -2406,6 +2560,7 @@ impl Default for AppConfig {
             storage_entries: Vec::new(),
             database: DatabaseConfig::default(),
             auth: AuthConfig::default(),
+            opaque: OpaqueConfig::default(),
             features: FeaturesConfig::default(),
             oidc: OidcConfig::default(),
             wopi: WopiConfig::default(),
@@ -3448,6 +3603,11 @@ impl AppConfig {
             }
         }
 
+        // OPAQUE aPAKE — env-driven substrate wired via its own loader so the
+        // AppConfig::from_env body doesn't have to know the internals of the
+        // new mode enum / KSF param triple. See `OpaqueConfig::from_env`.
+        config.opaque = OpaqueConfig::from_env();
+
         config
     }
 
@@ -4167,4 +4327,66 @@ mod tests {
             assert_eq!(cli_fp, parser_fp);
         }
     }
+
+    // ── OPAQUE effective-mode cross-check ────────────────────────────────
+    //
+    // OPAQUE is fundamentally a password mechanism; enabling its mode when
+    // password auth is disabled would be a no-op that still nagged
+    // operators for `OXICLOUD_OPAQUE_SERVER_SETUP` at boot. The
+    // `effective_mode` helper resolves that quietly by downgrading to
+    // Off + emitting an audit log, and these tests pin the truth table.
+
+    fn auth_with_methods(methods: Vec<AuthMethod>) -> AuthConfig {
+        AuthConfig {
+            allowed_auth_methods: methods,
+            ..AuthConfig::default()
+        }
+    }
+
+    #[test]
+    fn effective_mode_stays_off_when_configured_off() {
+        use crate::infrastructure::services::opaque_service::OpaqueMode;
+        let opaque = OpaqueConfig::default(); // mode = Off
+        let auth = auth_with_methods(vec![AuthMethod::Password]);
+        assert_eq!(opaque.effective_mode(&auth), OpaqueMode::Off);
+    }
+
+    #[test]
+    fn effective_mode_passes_through_when_password_allowed() {
+        use crate::infrastructure::services::opaque_service::OpaqueMode;
+        for mode in [OpaqueMode::Migrate, OpaqueMode::OpaqueOnly] {
+            let opaque = OpaqueConfig {
+                mode,
+                ..OpaqueConfig::default()
+            };
+            // Empty allowlist means "all methods allowed" per the existing
+            // convention, so password is implicitly in.
+            let empty_auth = auth_with_methods(vec![]);
+            assert_eq!(opaque.effective_mode(&empty_auth), mode);
+            // Explicit allowlist including Password.
+            let with_password = auth_with_methods(vec![AuthMethod::Password]);
+            assert_eq!(opaque.effective_mode(&with_password), mode);
+            // Multi-method allowlist including Password.
+            let mixed = auth_with_methods(vec![AuthMethod::Password, AuthMethod::MagicLink]);
+            assert_eq!(opaque.effective_mode(&mixed), mode);
+        }
+    }
+
+    #[test]
+    fn effective_mode_downgrades_to_off_when_password_disabled() {
+        use crate::infrastructure::services::opaque_service::OpaqueMode;
+        for mode in [OpaqueMode::Migrate, OpaqueMode::OpaqueOnly] {
+            let opaque = OpaqueConfig {
+                mode,
+                ..OpaqueConfig::default()
+            };
+            // Magic-link-only deployment — no password path for OPAQUE
+            // to shadow, so effective mode must be Off regardless of the
+            // configured value. The audit log line is a side effect we
+            // don't try to assert on (tracing capture would be overkill
+            // for this straightforward truth table).
+            let magic_only = auth_with_methods(vec![AuthMethod::MagicLink]);
+            assert_eq!(opaque.effective_mode(&magic_only), OpaqueMode::Off);
+        }
+    }
 }

src/common/di.rs

@@ -1909,6 +1909,50 @@ impl AppServiceFactory {
             user_lifecycle_handle = Some(user_lifecycle);
         }
 
+        // OPAQUE aPAKE substrate — construct only when effective_mode != Off.
+        // The `effective_mode` helper resolves the cross-check against
+        // `OXICLOUD_AUTH_METHODS` (password must be enabled for OPAQUE to
+        // have anything to shadow), so OIDC-only / magic-link-only
+        // deployments transparently get `opaque_service = None` even if
+        // the operator accidentally set `OXICLOUD_OPAQUE_MODE=migrate`.
+        //
+        // Failing here (missing SERVER_SETUP, malformed base64, ciphersuite
+        // drift) refuses server boot — same fail-closed posture as the
+        // auth-service init above. Better to catch a misconfigured
+        // deployment at startup than at first login attempt.
+        let opaque_service = {
+            use crate::infrastructure::services::opaque_service::{OpaqueMode, OpaqueService};
+            let effective = self.config.opaque.effective_mode(&self.config.auth);
+            if effective == OpaqueMode::Off {
+                None
+            } else {
+                let svc = OpaqueService::from_config(self.config.opaque.clone()).map_err(|e| {
+                    tracing::error!(
+                        "FATAL: OPAQUE mode is {:?} but service failed to initialize: {}",
+                        effective,
+                        e
+                    );
+                    DomainError::internal_error(
+                        "OpaqueInit",
+                        format!(
+                            "OXICLOUD_OPAQUE_MODE={:?} but the OPAQUE service failed: {}. \
+                             Persist a valid OXICLOUD_OPAQUE_SERVER_SETUP or set \
+                             OXICLOUD_OPAQUE_MODE=off. Refusing to start.",
+                            effective, e
+                        ),
+                    )
+                })?;
+                tracing::info!(
+                    target: "audit",
+                    event = "opaque.service_initialized",
+                    mode = ?effective,
+                    ciphersuite_version = svc.ciphersuite_version(),
+                    "OPAQUE substrate active — endpoints will be wired in a subsequent phase"
+                );
+                Some(Arc::new(svc))
+            }
+        };
+
         // Shared App Password service — created once, used by both NC routes and native API
         let shared_app_pw_svc: Option<Arc<AppPasswordService>> =
             if self.config.nextcloud.enabled || self.config.features.enable_auth {
@@ -2003,6 +2047,7 @@ impl AppServiceFactory {
             maintenance_pool: Some(maintenance_pool),
             mount_router,
             auth_service: auth_services,
+            opaque_service,
             nextcloud: nextcloud_services,
             admin_settings_service: None,
             storage_settings_service: None,
@@ -2749,6 +2794,17 @@ pub struct AppState {
     pub mount_router:
         Arc<crate::application::services::external_mount_router::MountRouter>,
     pub auth_service: Option<AuthServices>,
+    /// OPAQUE aPAKE substrate (RFC 9807). Populated only when
+    /// [`OpaqueConfig::effective_mode`] is not `Off` — that method
+    /// cross-checks `OXICLOUD_OPAQUE_MODE` against
+    /// `OXICLOUD_AUTH_METHODS` so an OIDC-only or magic-link-only
+    /// deployment gets `None` here even if `OXICLOUD_OPAQUE_MODE` was
+    /// set (with an audit-channel INFO explaining why). `None` also
+    /// means the future OPAQUE endpoints must 404 — a handler that
+    /// unwraps this without a nil check would break the phase gate.
+    pub opaque_service: Option<
+        Arc<crate::infrastructure::services::opaque_service::OpaqueService>,
+    >,
     pub nextcloud: Option<NextcloudServices>,
     pub admin_settings_service: Option<Arc<AdminSettingsService>>,
     /// WASM plugin management (list/install/toggle/remove), backing the admin