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/infrastructure/services/mod.rs

@@ -35,6 +35,7 @@ pub mod noop_face_analyzer;
 pub mod oidc_service;
 #[cfg(feature = "faces-onnx")]
 pub mod onnx_face_analyzer;
+pub mod opaque_service;
 pub mod password_hasher;
 pub mod path_resolver_service;
 pub mod path_service;

src/infrastructure/services/opaque_service.rs

@@ -0,0 +1,407 @@
+//! OPAQUE aPAKE service (Phase 0 substrate).
+//!
+//! OPAQUE (RFC 9807) is a zero-knowledge password-authenticated key exchange:
+//! the passphrase never leaves the client, not on registration and not on
+//! login. This module wraps the [`opaque_ke`] crate with a stable ciphersuite
+//! type alias ([`OxiCloudSuite`]), a lazily-loaded per-process
+//! [`ServerSetup`] persisted via env var, and a small handful of thin
+//! wrappers over the four handshake steps.
+//!
+//! ## Phase 0 scope
+//!
+//! Endpoints are not yet wired. This module ships the primitives so the
+//! subsequent phases can layer registration + login handlers, silent
+//! migration hooks, and the eventual `opaque_only` cutover on top without
+//! re-designing the type shape.
+//!
+//! ## Ciphersuite (frozen at v1)
+//!
+//! | Slot          | Choice                                                 |
+//! |---------------|--------------------------------------------------------|
+//! | `OprfCs`      | [`Ristretto255`] — SHA-512-backed VOPRF ciphersuite    |
+//! | `KeGroup`     | [`Ristretto255`] — same group for the AKE              |
+//! | `KeyExchange` | [`TripleDh`] — 3DH mutual auth (opaque-ke default AKE) |
+//! | `Ksf`         | [`argon2::Argon2`] — memory-hard client-side stretch   |
+//!
+//! **Changing any slot invalidates every previously-minted envelope.**
+//! Bumped via [`OpaqueConfig::ciphersuite_version`] with a matching
+//! DB-level `opaque_ciphersuite_version` column so a future migration can
+//! decide per-user whether to re-register or refuse login until the client
+//! re-registers.
+//!
+//! ## What lives where
+//!
+//! The KSF is applied CLIENT-side — RFC 9807 puts the memory-hard stretch
+//! before the OPRF exchange so the server never runs Argon2. The Argon2
+//! params in [`OpaqueConfig`] are therefore a CLIENT concern (published to
+//! the SPA at page-load); the server binds the type at compile time so the
+//! wire shape matches but never invokes it.
+
+use opaque_ke::CipherSuite;
+use opaque_ke::Ristretto255;
+use opaque_ke::ServerSetup;
+use opaque_ke::key_exchange::tripledh::TripleDh;
+use rand_core::OsRng;
+
+use crate::common::config::OpaqueConfig;
+use crate::common::errors::{DomainError, ErrorKind};
+
+/// OxiCloud's OPAQUE ciphersuite binding. See the module-level table for
+/// the slot choices and the invariants around changing them.
+///
+/// Zero-sized — this type exists only to name the ciphersuite for the
+/// generic `opaque_ke` machinery; no instances are ever constructed.
+#[derive(Debug, Clone, Copy)]
+pub struct OxiCloudSuite;
+
+impl CipherSuite for OxiCloudSuite {
+    type OprfCs = Ristretto255;
+    type KeGroup = Ristretto255;
+    type KeyExchange = TripleDh;
+    type Ksf = argon2::Argon2<'static>;
+}
+
+/// A configured OPAQUE server. Holds the persistent [`ServerSetup`] plus a
+/// clone of the runtime [`OpaqueConfig`] so callers don't have to plumb
+/// both. Cheap to clone — [`ServerSetup`] is a small keypair blob.
+#[derive(Debug, Clone)]
+pub struct OpaqueService {
+    setup: ServerSetup<OxiCloudSuite>,
+    config: OpaqueConfig,
+}
+
+impl OpaqueService {
+    /// Build the service from runtime config. Expects the operator to have
+    /// persisted the server setup already (via `OXICLOUD_OPAQUE_SERVER_SETUP`);
+    /// call [`OpaqueService::generate_server_setup_b64`] first-time and print
+    /// the value for the operator to paste into their env before enabling
+    /// `OXICLOUD_OPAQUE_MODE`.
+    ///
+    /// Rejects with `InternalError` if the setup is missing / malformed, or
+    /// with `AccessDenied` if the mode is `off` (guarding against
+    /// accidental use before the operator has explicitly opted in).
+    pub fn from_config(config: OpaqueConfig) -> Result<Self, DomainError> {
+        if config.mode == OpaqueMode::Off {
+            return Err(DomainError::access_denied(
+                "opaque",
+                "OPAQUE is disabled (OXICLOUD_OPAQUE_MODE=off)",
+            ));
+        }
+        let setup_b64 = config.server_setup_b64.as_deref().ok_or_else(|| {
+            DomainError::new(
+                ErrorKind::InternalError,
+                "opaque",
+                "OXICLOUD_OPAQUE_SERVER_SETUP is required when OPAQUE is enabled — \
+                 generate one with `oxicloud opaque-setup` and persist it in the env",
+            )
+        })?;
+        let setup = decode_server_setup(setup_b64)?;
+        Ok(Self { setup, config })
+    }
+
+    /// Runtime OPAQUE mode. Handlers can gate behaviour on this without
+    /// reaching for the whole config — see the phase plan in
+    /// `docs/plan/opaque.md`.
+    pub fn mode(&self) -> OpaqueMode {
+        self.config.mode
+    }
+
+    /// The bound ciphersuite version, stamped into `opaque_ciphersuite_version`
+    /// on registration so future migrations can reason per-user.
+    pub fn ciphersuite_version(&self) -> i16 {
+        self.config.ciphersuite_version
+    }
+
+    /// The persistent server setup — passed to `ServerRegistration::start`
+    /// and `ServerLogin::start` in the handler layer. Kept accessible so
+    /// callers can hold their own refs to it if they need to (e.g. inside
+    /// a Tokio task), avoiding an extra `Arc` layer.
+    pub fn setup(&self) -> &ServerSetup<OxiCloudSuite> {
+        &self.setup
+    }
+
+    /// Generate a fresh server setup and return it as base64. Called once
+    /// per deployment; the returned string must be persisted in
+    /// `OXICLOUD_OPAQUE_SERVER_SETUP` and NEVER rotated (rotating
+    /// invalidates every existing envelope — see
+    /// `docs/plan/opaque.md` §Phase 0).
+    pub fn generate_server_setup_b64() -> String {
+        use base64::Engine as _;
+        let mut rng = OsRng;
+        let setup = ServerSetup::<OxiCloudSuite>::new(&mut rng);
+        base64::engine::general_purpose::STANDARD.encode(setup.serialize())
+    }
+}
+
+fn decode_server_setup(b64: &str) -> Result<ServerSetup<OxiCloudSuite>, DomainError> {
+    use base64::Engine as _;
+    let bytes = base64::engine::general_purpose::STANDARD
+        .decode(b64.trim())
+        .map_err(|e| {
+            DomainError::new(
+                ErrorKind::InternalError,
+                "opaque",
+                format!("OXICLOUD_OPAQUE_SERVER_SETUP is not valid base64: {e}"),
+            )
+        })?;
+    ServerSetup::<OxiCloudSuite>::deserialize(&bytes).map_err(|e| {
+        DomainError::new(
+            ErrorKind::InternalError,
+            "opaque",
+            format!(
+                "OXICLOUD_OPAQUE_SERVER_SETUP payload does not match ciphersuite v1: {e}. \
+                 If you rotated the ciphersuite, every user must re-register."
+            ),
+        )
+    })
+}
+
+/// Runtime OPAQUE mode. Drives whether the endpoints exist at all
+/// (`Off`), run alongside the legacy password path (`Migrate`), or are
+/// the only accepted mechanism for users with an envelope (`OpaqueOnly`).
+///
+/// Progression matches the phase plan — see `docs/plan/opaque.md`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OpaqueMode {
+    /// Endpoints 404; no OPAQUE state ever mints. Default. Phase 0-1.
+    Off,
+    /// Endpoints live. Legacy login also accepted; successful legacy login
+    /// silently mints an envelope. Phase 2-3.
+    Migrate,
+    /// Endpoints live. Legacy login refused for users with
+    /// `opaque_migrated_at IS NOT NULL`. Phase 4+.
+    OpaqueOnly,
+}
+
+impl OpaqueMode {
+    /// Case-insensitive parse. Unknown token returns `None` so callers can
+    /// log-and-default (mirrors [`crate::common::config::AuthMethod::parse`]).
+    pub fn parse(s: &str) -> Option<Self> {
+        match s.trim().to_ascii_lowercase().as_str() {
+            "off" | "disabled" => Some(Self::Off),
+            "migrate" => Some(Self::Migrate),
+            "opaque_only" | "opaque-only" => Some(Self::OpaqueOnly),
+            _ => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn generate_and_round_trip_server_setup() {
+        // Fresh setup encodes to base64, decodes back into an equivalent
+        // ServerSetup, and yields a usable OpaqueService when threaded
+        // through the config layer.
+        let b64 = OpaqueService::generate_server_setup_b64();
+        assert!(!b64.is_empty(), "setup must be non-empty");
+        let cfg = OpaqueConfig {
+            mode: OpaqueMode::Migrate,
+            server_setup_b64: Some(b64.clone()),
+            ..OpaqueConfig::default()
+        };
+        let svc = OpaqueService::from_config(cfg).expect("service builds from valid config");
+        assert_eq!(svc.mode(), OpaqueMode::Migrate);
+        // Round-trip check: re-serialising the loaded setup produces the
+        // same bytes as the generator emitted.
+        use base64::Engine as _;
+        let re_encoded = base64::engine::general_purpose::STANDARD.encode(svc.setup().serialize());
+        assert_eq!(re_encoded, b64);
+    }
+
+    #[test]
+    fn from_config_rejects_off_mode() {
+        // Guard rail: explicitly refuses to build in Off mode so a stray
+        // caller cannot accidentally exercise the primitives when the
+        // operator has disabled OPAQUE.
+        let cfg = OpaqueConfig {
+            mode: OpaqueMode::Off,
+            server_setup_b64: Some(OpaqueService::generate_server_setup_b64()),
+            ..OpaqueConfig::default()
+        };
+        let err = OpaqueService::from_config(cfg).expect_err("must reject Off");
+        assert_eq!(err.kind, ErrorKind::AccessDenied);
+    }
+
+    #[test]
+    fn from_config_rejects_missing_setup() {
+        // Enabling OPAQUE without persisting the setup is a boot-time
+        // misconfiguration — surface it with a clear error rather than
+        // silently generating a fresh (and unpersisted) keypair.
+        let cfg = OpaqueConfig {
+            mode: OpaqueMode::Migrate,
+            server_setup_b64: None,
+            ..OpaqueConfig::default()
+        };
+        let err = OpaqueService::from_config(cfg).expect_err("must reject missing setup");
+        assert_eq!(err.kind, ErrorKind::InternalError);
+        assert!(err.to_string().contains("OXICLOUD_OPAQUE_SERVER_SETUP"));
+    }
+
+    #[test]
+    fn from_config_rejects_malformed_setup() {
+        // Truncated / garbled base64 is caught at boot with a helpful
+        // pointer to the ciphersuite-rotation caveat.
+        let cfg = OpaqueConfig {
+            mode: OpaqueMode::Migrate,
+            server_setup_b64: Some("not-base64!".to_string()),
+            ..OpaqueConfig::default()
+        };
+        let err = OpaqueService::from_config(cfg).expect_err("must reject malformed setup");
+        assert_eq!(err.kind, ErrorKind::InternalError);
+    }
+
+    /// End-to-end round-trip through OPAQUE's four messages, using the
+    /// ciphersuite this service actually binds. This is the load-bearing
+    /// smoke test for Phase 0: proves the crate is wired correctly, the
+    /// ServerSetup we serialise / deserialise is functional, and the client
+    /// and server sides negotiate a matching session key given the correct
+    /// passphrase (and disagree on the wrong one).
+    ///
+    /// Fast Argon2 params (8 KiB / 1 iter / 1 lane) keep the test in the
+    /// millisecond range — production clients pass their own configured
+    /// Argon2 instance via `ClientRegistrationFinishParameters` /
+    /// `ClientLoginFinishParameters`, so the test's choice of KSF params
+    /// does NOT contaminate the runtime behaviour of the service.
+    #[test]
+    fn round_trip_register_and_login_matches_session_keys() {
+        use opaque_ke::{
+            ClientLogin, ClientLoginFinishParameters, ClientRegistration,
+            ClientRegistrationFinishParameters, ServerLogin, ServerLoginStartParameters,
+            ServerRegistration,
+        };
+        use rand_core::OsRng;
+
+        // ── Server bootstrap (mirrors the production `from_config` path) ─
+        let b64 = OpaqueService::generate_server_setup_b64();
+        let svc = OpaqueService::from_config(OpaqueConfig {
+            mode: OpaqueMode::Migrate,
+            server_setup_b64: Some(b64),
+            ..OpaqueConfig::default()
+        })
+        .expect("service builds");
+
+        // Test-scoped fast KSF — override the client-side Argon2 via the
+        // finish-parameters plumb so we don't pay the 256 MiB / 3-iter
+        // production defaults for every test run.
+        let ksf = argon2::Argon2::new(
+            argon2::Algorithm::Argon2id,
+            argon2::Version::V0x13,
+            argon2::Params::new(8, 1, 1, None).expect("valid test argon2 params"),
+        );
+
+        let user_id = b"alice@example.com";
+        let passphrase = b"correct horse battery staple";
+
+        // ── Registration ────────────────────────────────────────────────
+        let mut client_rng = OsRng;
+        let client_reg_start =
+            ClientRegistration::<OxiCloudSuite>::start(&mut client_rng, passphrase)
+                .expect("client registration start");
+        let server_reg_start = ServerRegistration::<OxiCloudSuite>::start(
+            svc.setup(),
+            client_reg_start.message,
+            user_id,
+        )
+        .expect("server registration start");
+        let client_reg_finish = client_reg_start
+            .state
+            .finish(
+                &mut client_rng,
+                passphrase,
+                server_reg_start.message,
+                ClientRegistrationFinishParameters::new(
+                    opaque_ke::Identifiers::default(),
+                    Some(&ksf),
+                ),
+            )
+            .expect("client registration finish");
+        let password_file = ServerRegistration::<OxiCloudSuite>::finish(client_reg_finish.message);
+        let password_file_bytes = password_file.serialize();
+
+        // ── Login (correct passphrase → session keys match) ─────────────
+        let client_login_start = ClientLogin::<OxiCloudSuite>::start(&mut client_rng, passphrase)
+            .expect("client login start");
+        let stored = ServerRegistration::<OxiCloudSuite>::deserialize(&password_file_bytes)
+            .expect("password file deserialises");
+        let mut server_rng = OsRng;
+        let server_login_start = ServerLogin::start(
+            &mut server_rng,
+            svc.setup(),
+            Some(stored),
+            client_login_start.message,
+            user_id,
+            ServerLoginStartParameters::default(),
+        )
+        .expect("server login start");
+        let client_login_finish = client_login_start
+            .state
+            .finish(
+                passphrase,
+                server_login_start.message,
+                ClientLoginFinishParameters::new(
+                    None,
+                    opaque_ke::Identifiers::default(),
+                    Some(&ksf),
+                ),
+            )
+            .expect("client login finish");
+        let server_login_finish = server_login_start
+            .state
+            .finish(client_login_finish.message)
+            .expect("server login finish");
+        assert_eq!(
+            client_login_finish.session_key.as_slice(),
+            server_login_finish.session_key.as_slice(),
+            "OPAQUE session keys must match on both sides after a successful login"
+        );
+        assert!(
+            !client_login_finish.export_key.as_slice().is_empty(),
+            "client export_key must be populated (E2EE KEK bridge input)"
+        );
+
+        // ── Login (wrong passphrase → client finish must fail) ──────────
+        let bad_login_start =
+            ClientLogin::<OxiCloudSuite>::start(&mut client_rng, b"wrong-passphrase")
+                .expect("client login start (wrong pass)");
+        let stored_again =
+            ServerRegistration::<OxiCloudSuite>::deserialize(&password_file_bytes).unwrap();
+        let bad_server_login = ServerLogin::start(
+            &mut server_rng,
+            svc.setup(),
+            Some(stored_again),
+            bad_login_start.message,
+            user_id,
+            ServerLoginStartParameters::default(),
+        )
+        .expect("server login start (wrong pass)");
+        let bad_client_finish = bad_login_start.state.finish(
+            b"wrong-passphrase",
+            bad_server_login.message,
+            ClientLoginFinishParameters::new(None, opaque_ke::Identifiers::default(), Some(&ksf)),
+        );
+        assert!(
+            bad_client_finish.is_err(),
+            "client finish must reject a wrong passphrase — this is the whole point of OPAQUE"
+        );
+    }
+
+    #[test]
+    fn mode_parse_case_insensitive_and_alias_tolerant() {
+        assert_eq!(OpaqueMode::parse("off"), Some(OpaqueMode::Off));
+        assert_eq!(OpaqueMode::parse("OFF"), Some(OpaqueMode::Off));
+        assert_eq!(OpaqueMode::parse("disabled"), Some(OpaqueMode::Off));
+        assert_eq!(OpaqueMode::parse("migrate"), Some(OpaqueMode::Migrate));
+        assert_eq!(
+            OpaqueMode::parse("opaque_only"),
+            Some(OpaqueMode::OpaqueOnly)
+        );
+        assert_eq!(
+            OpaqueMode::parse("opaque-only"),
+            Some(OpaqueMode::OpaqueOnly)
+        );
+        assert_eq!(OpaqueMode::parse("nope"), None);
+    }
+}