feat(tui): add usage overlay and sidebar for displaying usage statistics and tasks

feat(tui): implement status bar with connection and turn state indicators
feat(tui): create workflow panel for agent status and progress visualization
feat(web): introduce web frontend interface with static file serving
feat(ws): add WebSocket interface for real-time communication and session management

apps/application/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "zesdex-application"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+# Application layer — port traits (interfaces), use cases, DTOs.
+# Depends ONLY on domain. Application services orchestrate domain objects
+# through port traits without knowing concrete implementations.
+[dependencies]
+zesdex-domain = { path = "../domain" }
+serde.workspace = true
+serde_json.workspace = true
+chrono.workspace = true
+uuid.workspace = true
+anyhow.workspace = true
+tracing.workspace = true
+tokio.workspace = true
+base64.workspace = true
+sha2.workspace = true
+url.workspace = true

apps/application/src/auth/mod.rs

@@ -0,0 +1,16 @@
+//! Auth use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's
+//! authentication and session management traits by coordinating
+//! injected repository and port dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`oauth_service`] — `OAuthUseCase`: OAuth 2.0 authorization-code + PKCE flow
+//! - [`session_service`] — `SessionServiceImpl`: session CRUD lifecycle
+
+pub mod oauth_service;
+pub mod session_service;
+
+pub use oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger};
+pub use session_service::SessionServiceImpl;

apps/application/src/auth/oauth_service.rs

@@ -0,0 +1,250 @@
+//! OAuth 2.0 authorization-code + PKCE flow use-case.
+//!
+//! `OAuthUseCase` orchestrates the standard PKCE-enhanced OAuth flow:
+//!
+//! 1. **`start_flow`** — generates a cryptographic PKCE code verifier,
+//!    derives its S256 challenge, creates a CSRF state token, persists
+//!    the verifier + state via `OAuthFlowStore`, and builds an
+//!    authorization URL with all required parameters.
+//! 2. **`complete_flow`** — validates the returned `state` against the
+//!    stored value (CSRF check), reads the stored verifier, delegates
+//!    the token-code exchange to an injected `TokenExchanger`, and
+//!    persists the resulting `OAuthToken` via `OAuthRepository`.
+//! 3. **`get_token`** — loads the stored OAuth token (if any).
+//!
+//! # Portability
+//!
+//! The service is generic over three injected dependencies:
+//! - `R: OAuthRepository` — token persistence
+//! - `S: OAuthFlowStore` — ephemeral flow state (verifier + CSRF state)
+//! - `E: TokenExchanger` — the HTTP token-endpoint exchange
+//!
+//! This keeps all I/O and protocol-level concerns abstracted behind
+//! port traits; the service itself contains only orchestration logic.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::auth::{OAuthConfig, OAuthRepository, OAuthToken, ServiceError};
+
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use sha2::{Digest, Sha256};
+
+// ---------------------------------------------------------------------------
+// Port traits (defined here because they are specific to this use-case)
+// ---------------------------------------------------------------------------
+
+/// Persistence contract for ephemeral OAuth flow state.
+///
+/// Between `start_flow` and `complete_flow` the verifier and CSRF state
+/// must survive across process boundaries (the user opens a browser, the
+/// provider redirects back to a loopback listener on the next invocation).
+///
+/// Implementors store key-value pairs to disk or another durable medium
+/// and clear them after a successful (or failed) flow completion.
+pub trait OAuthFlowStore: Send + Sync {
+    /// Persist the PKCE code verifier and CSRF state token.
+    fn save_flow_state(
+        &self,
+        verifier: &str,
+        state: &str,
+    ) -> Result<(), ServiceError>;
+
+    /// Load the stored PKCE code verifier.
+    fn load_verifier(&self) -> Result<String, ServiceError>;
+
+    /// Load the stored CSRF state token.
+    fn load_state(&self) -> Result<String, ServiceError>;
+
+    /// Clear stored flow state (verifier + state).
+    fn clear(&self) -> Result<(), ServiceError>;
+}
+
+/// Abstraction for exchanging an authorization code for tokens.
+///
+/// Implementors handle the HTTP POST to the provider's token endpoint
+/// with the appropriate form-encoded parameters, parse the JSON
+/// response, and return the extracted `OAuthToken`.
+pub trait TokenExchanger: Send + Sync {
+    /// Exchange an authorization code for an access token.
+    ///
+    /// ## Parameters
+    /// - `token_url` — the provider's token endpoint URL
+    /// - `client_id` — OAuth client identifier
+    /// - `client_secret` — optional client secret
+    /// - `redirect_uri` — must match the URI used in `start_flow`
+    /// - `code` — the authorization code from the provider's redirect
+    /// - `code_verifier` — the PKCE verifier from `start_flow`
+    fn exchange_code(
+        &self,
+        token_url: &str,
+        client_id: &str,
+        client_secret: Option<&str>,
+        redirect_uri: &str,
+        code: &str,
+        code_verifier: &str,
+    ) -> Result<OAuthToken, ServiceError>;
+}
+
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+
+/// Generate a PKCE code-verifier and its S256 code-challenge.
+///
+/// Uses 32 cryptographically random bytes, base64url-encoded (no padding)
+/// for the verifier, then SHA-256 hashes the verifier and base64url-encodes
+/// the digest for the challenge. This satisfies the PKCE `S256` method
+/// which requires a minimum verifier length of 43 characters.
+fn generate_pkce_pair() -> (String, String) {
+    // 32 random bytes → 43 base64url chars (well above the 43-char PKCE
+    // minimum).
+    let mut bytes = [0u8; 32];
+    bytes[..16].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+    bytes[16..].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+
+    let verifier = URL_SAFE_NO_PAD.encode(&bytes);
+    let challenge = {
+        let mut hasher = Sha256::new();
+        hasher.update(verifier.as_bytes());
+        URL_SAFE_NO_PAD.encode(hasher.finalize())
+    };
+    (verifier, challenge)
+}
+
+/// Generate a random CSRF state token (UUID-based, 36 chars).
+fn generate_state_token() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/// Concrete OAuth flow use-case.
+///
+/// Generic over three dependencies:
+/// - `R` — token persistence (`OAuthRepository`)
+/// - `S` — flow-state persistence (`OAuthFlowStore`)
+/// - `E` — token-endpoint HTTP exchange (`TokenExchanger`)
+pub struct OAuthUseCase<R, S, E> {
+    /// Repository for persisting / loading OAuth tokens.
+    pub token_repo: R,
+    /// Store for ephemeral flow state (verifier + CSRF state).
+    pub flow_store: S,
+    /// Token-endpoint HTTP exchanger.
+    pub token_exchanger: E,
+    /// File path for the token JSON file.
+    pub token_path: PathBuf,
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger> OAuthUseCase<R, S, E> {
+    /// Create a new OAuth use-case.
+    pub fn new(
+        token_repo: R,
+        flow_store: S,
+        token_exchanger: E,
+        token_path: PathBuf,
+    ) -> Self {
+        OAuthUseCase {
+            token_repo,
+            flow_store,
+            token_exchanger,
+            token_path,
+        }
+    }
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger>
+    zesdex_domain::auth::OAuthService for OAuthUseCase<R, S, E>
+{
+    fn start_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+    ) -> Result<(String, String), ServiceError> {
+        if config.auth_url.is_empty() {
+            return Err(ServiceError::InvalidConfig(
+                "OAuth auth_url is empty".to_string(),
+            ));
+        }
+
+        let (verifier, challenge) = generate_pkce_pair();
+        let state = generate_state_token();
+
+        // Persist verifier + state so `complete_flow` can retrieve them.
+        self.flow_store.save_flow_state(&verifier, &state)?;
+
+        tracing::debug!(
+            auth_url = %config.auth_url,
+            redirect_uri = %redirect_uri,
+            state_len = state.len(),
+            "starting OAuth flow",
+        );
+
+        let mut url = url::Url::parse(&config.auth_url)
+            .map_err(|e| {
+                ServiceError::InvalidConfig(format!(
+                    "invalid auth_url '{}': {e}",
+                    config.auth_url
+                ))
+            })?;
+
+        url.query_pairs_mut()
+            .append_pair("response_type", "code")
+            .append_pair("client_id", &config.client_id)
+            .append_pair("redirect_uri", redirect_uri)
+            .append_pair("scope", &config.scopes.join(" "))
+            .append_pair("state", &state)
+            .append_pair("code_challenge_method", "S256")
+            .append_pair("code_challenge", &challenge);
+
+        Ok((url.to_string(), state))
+    }
+
+    fn complete_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+        code: &str,
+        state: &str,
+    ) -> Result<OAuthToken, ServiceError> {
+        // CSRF check: validate the returned state against the stored value.
+        let expected_state = self.flow_store.load_state()?;
+        if expected_state != state {
+            return Err(ServiceError::StateMismatch);
+        }
+
+        // Read the PKCE verifier that was saved in `start_flow`.
+        let verifier = self.flow_store.load_verifier()?;
+
+        tracing::debug!(
+            token_url = %config.token_url,
+            code_len = code.len(),
+            "completing OAuth flow — exchanging code for token",
+        );
+
+        // Delegate the HTTP token exchange to the injected exchanger.
+        let token = self.token_exchanger.exchange_code(
+            &config.token_url,
+            &config.client_id,
+            config.client_secret.as_deref(),
+            redirect_uri,
+            code,
+            &verifier,
+        )?;
+
+        // Persist the token and clean up flow state.
+        self.token_repo.save_token(&self.token_path, &token)?;
+        let _ = self.flow_store.clear();
+
+        Ok(token)
+    }
+
+    fn get_token(&self) -> Result<Option<OAuthToken>, ServiceError> {
+        self.token_repo
+            .load_token(&self.token_path)
+            .map_err(ServiceError::Repository)
+    }
+}

apps/application/src/auth/session_service.rs

@@ -0,0 +1,89 @@
+//! Session management use-case.
+//!
+//! `SessionServiceImpl` implements [`SessionService`] from the domain
+//! layer by delegating CRUD operations to injected repository traits.
+//!
+//! # Flow
+//!
+//! - **`create_session`** — generates a UUID v4 id, creates a `Session`
+//!   entity with the given title, persists via `SessionRepository`.
+//! - **`list_all`** — delegates to `SessionRepository::list_sessions`.
+//! - **`archive_session`** — loads session, sets `archived = true`,
+//!   persists the updated entity.
+//!
+//! # Generics
+//!
+//! - `R: SessionRepository` — session CRUD persistence
+//! - `L: SessionLockRepository` — session lock acquire/release
+
+use std::path::PathBuf;
+use tracing;
+use uuid::Uuid;
+
+use zesdex_domain::auth::{
+    ServiceError, Session, SessionId, SessionLockRepository, SessionRepository,
+};
+
+/// Concrete session service backed by injected repository implementations.
+pub struct SessionServiceImpl<R: SessionRepository, L: SessionLockRepository> {
+    /// Repository for session CRUD operations.
+    pub session_repo: R,
+    /// Repository for session lock acquire/release.
+    pub lock_repo: L,
+    /// Base data directory passed to repository methods.
+    pub base_dir: PathBuf,
+}
+
+impl<R: SessionRepository, L: SessionLockRepository> SessionServiceImpl<R, L> {
+    /// Create a new session service with the given repositories and base
+    /// data directory.
+    pub fn new(session_repo: R, lock_repo: L, base_dir: PathBuf) -> Self {
+        SessionServiceImpl {
+            session_repo,
+            lock_repo,
+            base_dir,
+        }
+    }
+}
+
+impl<R: SessionRepository, L: SessionLockRepository>
+    zesdex_domain::auth::SessionService for SessionServiceImpl<R, L>
+{
+    fn create_session(&self, title: &str) -> Result<Session, ServiceError> {
+        let id = SessionId::new(&Uuid::new_v4().to_string())
+            .map_err(|e| ServiceError::Other(e))?;
+        let title_owned = if title.is_empty() {
+            "New Session".to_string()
+        } else {
+            title.to_string()
+        };
+        let session = Session::new(id.into_string(), title_owned);
+        tracing::debug!(session_id = %session.id, title = %session.title, "creating new session");
+        self.session_repo
+            .save_session(&self.base_dir, &session)?;
+        Ok(session)
+    }
+
+    fn list_all(&self) -> Result<Vec<Session>, ServiceError> {
+        tracing::debug!("listing all sessions");
+        self.session_repo
+            .list_sessions(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn archive_session(&self, id: SessionId) -> Result<(), ServiceError> {
+        tracing::debug!(session_id = %id, "archiving session");
+        let mut session = self
+            .session_repo
+            .load_session(&self.base_dir, &id)?;
+        session.archived = true;
+        let millis = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis();
+        session.updated_at = i64::try_from(millis).unwrap_or(i64::MAX);
+        self.session_repo
+            .save_session(&self.base_dir, &session)?;
+        Ok(())
+    }
+}

apps/application/src/cms/conversation_service.rs

@@ -0,0 +1,72 @@
+//! Conversation use-case implementation.
+//!
+//! `ConversationServiceImpl` implements [`ConversationService`] from the
+//! domain layer. It is generic over `R: ConversationRepository`, delegating
+//! all persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method computes the session directory from the session ID, then
+//! delegates the actual I/O to the injected `repo`. Error context is
+//! added at this layer to identify which session caused the failure.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Conversation, ConversationRepository, ServiceError};
+use zesdex_domain::core::ChatMessage;
+
+/// Service implementation for conversation CRUD operations.
+///
+/// Generic over `R: ConversationRepository` so the persistence layer
+/// can be swapped without changing business logic.
+pub struct ConversationServiceImpl<R> {
+    pub repo: R,
+    /// Base directory containing session subdirectories.
+    pub sessions_dir: PathBuf,
+}
+
+impl<R: ConversationRepository> ConversationServiceImpl<R> {
+    /// Create a new service with the given repository and sessions directory.
+    pub fn new(repo: R, sessions_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating ConversationServiceImpl");
+        Self {
+            repo,
+            sessions_dir: sessions_dir.into(),
+        }
+    }
+
+    /// Compute the session directory for a given session id.
+    fn session_dir(&self, session_id: &str) -> PathBuf {
+        self.sessions_dir.join(session_id)
+    }
+}
+
+impl<R: ConversationRepository> zesdex_domain::cms::ConversationService
+    for ConversationServiceImpl<R>
+{
+    fn load_conversation(&self, session_id: &str) -> Result<Conversation, ServiceError> {
+        tracing::debug!("loading conversation for session {session_id}");
+        let dir = self.session_dir(session_id);
+        self.repo.load(&dir).map_err(ServiceError::Repository)
+    }
+
+    fn save_conversation(&self, conv: &Conversation) -> Result<(), ServiceError> {
+        tracing::debug!("saving conversation for session {}", conv.session_id);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+
+    fn add_message(
+        &self,
+        conv: &mut Conversation,
+        msg: ChatMessage,
+    ) -> Result<(), ServiceError> {
+        tracing::debug!("adding message to session {}", conv.session_id);
+        conv.push(msg);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+}

apps/application/src/cms/memory_service.rs

@@ -0,0 +1,59 @@
+//! Memory use-case implementation.
+//!
+//! `MemoryServiceImpl` implements [`MemoryService`] from the domain
+//! layer. It is generic over `R: MemoryRepository`, delegating all
+//! persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method delegates to the injected `repo` with the configured
+//! `memory_dir`. Error context is added at this layer to identify which
+//! memory operation failed.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Memory, MemoryRepository, ServiceError};
+
+/// Service implementation for memory CRUD operations.
+///
+/// Generic over `R: MemoryRepository` so the persistence layer can be
+/// swapped without changing business logic.
+pub struct MemoryServiceImpl<R> {
+    pub repo: R,
+    /// Base directory for memory storage files.
+    pub memory_dir: PathBuf,
+}
+
+impl<R: MemoryRepository> MemoryServiceImpl<R> {
+    /// Create a new service with the given repository and memory directory.
+    pub fn new(repo: R, memory_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating MemoryServiceImpl");
+        Self {
+            repo,
+            memory_dir: memory_dir.into(),
+        }
+    }
+}
+
+impl<R: MemoryRepository> zesdex_domain::cms::MemoryService for MemoryServiceImpl<R> {
+    fn list_memories(&self) -> Result<Vec<String>, ServiceError> {
+        tracing::debug!("listing memories from {:?}", self.memory_dir);
+        self.repo
+            .list(&self.memory_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_memory(&self, memory: &Memory) -> Result<(), ServiceError> {
+        tracing::debug!("saving memory '{}'", memory.name);
+        self.repo.save(&self.memory_dir, memory)?;
+        Ok(())
+    }
+
+    fn delete_memory(&self, name: &str) -> Result<(), ServiceError> {
+        tracing::debug!("deleting memory '{name}'");
+        self.repo
+            .delete(&self.memory_dir, name)
+            .map_err(ServiceError::Repository)
+    }
+}

apps/application/src/cms/mod.rs

@@ -0,0 +1,18 @@
+//! CMS use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's CMS
+//! service traits by coordinating injected repository dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`conversation_service`] — `ConversationServiceImpl`: conversation CRUD
+//! - [`memory_service`] — `MemoryServiceImpl`: long-term memory management
+//! - [`settings_service`] — `SettingsServiceImpl`: settings & app-config management
+
+pub mod conversation_service;
+pub mod memory_service;
+pub mod settings_service;
+
+pub use conversation_service::ConversationServiceImpl;
+pub use memory_service::MemoryServiceImpl;
+pub use settings_service::SettingsServiceImpl;

apps/application/src/cms/settings_service.rs

@@ -0,0 +1,76 @@
+//! Settings and app-config use-case implementation.
+//!
+//! `SettingsServiceImpl` implements [`SettingsService`] from the domain
+//! layer. It is generic over `S: SettingsRepository` and `C: AppConfigRepository`,
+//! delegating persistence to those adapters.
+//!
+//! # Flow
+//!
+//! Each method delegates to the appropriate injected repository with the
+//! configured `base_dir`. The `update_provider` method coordinates between
+//! both repositories: load app config → mutate provider map → save app config.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{
+    AppConfig, AppConfigRepository, ProviderConfig, ServiceError, Settings,
+    SettingsRepository,
+};
+
+/// Service implementation for settings and app-config operations.
+///
+/// Generic over `S: SettingsRepository` and `C: AppConfigRepository` so
+/// the persistence layer can be swapped without changing business logic.
+pub struct SettingsServiceImpl<S, C> {
+    pub settings_repo: S,
+    pub app_config_repo: C,
+    pub base_dir: PathBuf,
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository> SettingsServiceImpl<S, C> {
+    /// Create a new service with the given repositories and base directory.
+    pub fn new(
+        settings_repo: S,
+        app_config_repo: C,
+        base_dir: impl Into<PathBuf>,
+    ) -> Self {
+        tracing::debug!("creating SettingsServiceImpl");
+        Self {
+            settings_repo,
+            app_config_repo,
+            base_dir: base_dir.into(),
+        }
+    }
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository>
+    zesdex_domain::cms::SettingsService for SettingsServiceImpl<S, C>
+{
+    fn load_settings(&self) -> Result<Settings, ServiceError> {
+        tracing::debug!("loading settings");
+        self.settings_repo
+            .load(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_settings(&self, settings: &Settings) -> Result<(), ServiceError> {
+        tracing::debug!("saving settings");
+        self.settings_repo.save(&self.base_dir, settings)?;
+        Ok(())
+    }
+
+    fn update_provider(
+        &self,
+        name: &str,
+        config: &ProviderConfig,
+    ) -> Result<(), ServiceError> {
+        tracing::debug!("updating provider '{name}'");
+        let mut app_config: AppConfig = self.app_config_repo.load(&self.base_dir)?;
+        app_config
+            .providers
+            .insert(name.to_string(), config.clone());
+        self.app_config_repo.save(&self.base_dir, &app_config)?;
+        Ok(())
+    }
+}

apps/application/src/lib.rs

@@ -0,0 +1,51 @@
+//! # Zesdex Application Layer
+//!
+//! Defines port traits (interfaces) and use-case implementations for the
+//! Zesdex application. This crate depends **only** on the domain crate;
+//! it has no knowledge of infrastructure or interface adapters.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! apps/application/src/
+//! ├── lib.rs              — crate root, re-exports
+//! ├── ports/              — Port traits (interfaces to external services)
+//! │   ├── provider.rs     -- ProviderService (LLM chat completion)
+//! │   ├── password.rs     -- PasswordService (hash / verify)
+//! │   ├── token.rs        -- TokenService (JWT create / verify)
+//! │   └── authentication.rs -- AuthService (combined auth)
+//! ├── auth/               — Auth use-cases
+//! │   ├── oauth_service.rs   -- OAuth 2.0 PKCE flow
+//! │   └── session_service.rs -- Session CRUD lifecycle
+//! └── cms/                — CMS use-cases
+//!     ├── conversation_service.rs -- Conversation CRUD
+//!     ├── memory_service.rs       -- Long-term memory management
+//!     └── settings_service.rs     -- Settings & app-config management
+//! ```
+//!
+//! ## Key Design Principle
+//!
+//! Application services are generic over their repository/port dependencies.
+//! Concrete implementations are injected at the composition root, keeping
+//! the use-case logic independent of any specific persistence or infrastructure
+//! technology.
+
+pub mod auth;
+pub mod cms;
+pub mod ports;
+
+// Re-export port traits for ergonomic access.
+pub use ports::*;
+
+// Re-export auth use-cases.
+pub use auth::{
+    oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger},
+    session_service::SessionServiceImpl,
+};
+
+// Re-export CMS use-cases.
+pub use cms::{
+    conversation_service::ConversationServiceImpl,
+    memory_service::MemoryServiceImpl,
+    settings_service::SettingsServiceImpl,
+};

apps/application/src/ports/authentication.rs

@@ -0,0 +1,35 @@
+//! AuthService port — combined authentication operations.
+//!
+//! Defines a high-level authentication trait that composes password
+//! verification and token generation into a single use-case boundary.
+//! Implementations delegate to the injected `PasswordService` and
+//! `TokenService` adapters.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// High-level authentication service combining password verification
+/// and token issuance (login flow).
+///
+/// # Flow
+///
+/// 1. **`authenticate`** — verify a subject's password against a stored hash.
+/// 2. **`issue_tokens`** — generate an access + refresh token pair for a subject.
+///
+/// Implementations are generic over `PasswordService` and `TokenService`
+/// port traits.
+pub trait AuthService: Send + Sync {
+    /// Authenticate a user by verifying a password against a stored hash.
+    ///
+    /// Returns `true` if the password matches, `false` otherwise.
+    fn authenticate(
+        &self,
+        password: &str,
+        hash: &str,
+    ) -> impl Future<Output = Result<bool>> + Send;
+
+    /// Issue a new access + refresh token pair for the given subject.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn issue_tokens(&self, sub: &str) -> Result<(String, String)>;
+}

apps/application/src/ports/mod.rs

@@ -0,0 +1,22 @@
+//! Port traits — interfaces for external / infrastructure services.
+//!
+//! These traits define the boundaries between the application layer and
+//! the outside world. Infrastructure adapters implement these traits;
+//! the application layer depends only on the trait definitions.
+//!
+//! # Ports
+//!
+//! - [`provider`] — `ProviderService`: LLM chat completion (streaming + non-streaming)
+//! - [`password`] — `PasswordService`: password hashing and verification
+//! - [`token`] — `TokenService`: JWT access/refresh token generation and verification
+//! - [`authentication`] — `AuthService`: combined authentication operations
+
+pub mod authentication;
+pub mod password;
+pub mod provider;
+pub mod token;
+
+pub use authentication::AuthService;
+pub use password::PasswordService;
+pub use provider::ProviderService;
+pub use token::TokenService;

apps/application/src/ports/password.rs

@@ -0,0 +1,24 @@
+//! PasswordService port — password hashing and verification abstraction.
+//!
+//! Defines the trait that password-hashing adapters (argon2, bcrypt, etc.)
+//! implement. The application layer depends only on this trait, never on
+//! a concrete hashing library.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// Abstraction for password hashing and verification.
+///
+/// Implementors handle the actual hashing algorithm (argon2, bcrypt, etc.)
+/// and parameter selection. The trait is `Send + Sync` for use in async
+/// service layers.
+pub trait PasswordService: Send + Sync {
+    /// Hash a plaintext password and return the encoded hash string
+    /// (suitable for storage in a credential store).
+    fn hash(&self, password: &str) -> impl Future<Output = Result<String>> + Send;
+
+    /// Verify a plaintext password against a previously-hashed string.
+    ///
+    /// Returns `true` if the password matches the hash, `false` otherwise.
+    fn verify(&self, password: &str, hash: &str) -> impl Future<Output = Result<bool>> + Send;
+}

apps/application/src/ports/provider.rs

@@ -0,0 +1,56 @@
+//! ProviderService port — LLM chat completion provider abstraction.
+//!
+//! Defines the trait that HTTP-based provider clients (OpenAI, Anthropic,
+//! etc.) implement. Supports both non-streaming and SSE-streaming chat
+//! completion requests.
+//!
+//! # Flow
+//!
+//! 1. Caller builds a message list and optional tool definitions.
+//! 2. `chat` sends a non-streaming request and returns the full response.
+//! 3. `chat_stream` sends a streaming request and invokes `on_event` for
+//!    each parsed `StreamEvent` as it arrives, then returns the assembled
+//!    message and usage.
+
+use anyhow::Result;
+use std::future::Future;
+
+use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
+
+/// Abstraction for an LLM provider chat-completion service.
+///
+/// Both methods accept a message list, optional tool definitions, and
+/// generation parameters. Implementors handle authentication, HTTP
+/// transport, retry logic, and response parsing internally.
+///
+/// # Send + Sync
+///
+/// This trait is `Send + Sync` so it can be shared across async tasks
+/// and injected into service structs that require thread safety.
+pub trait ProviderService: Send + Sync {
+    /// Send a non-streaming chat completion request.
+    ///
+    /// Returns the assistant's `ChatMessage` and optional token usage
+    /// `(prompt_tokens, completion_tokens)`.
+    fn chat(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+
+    /// Send a streaming chat completion request.
+    ///
+    /// `on_event` is called for every parsed SSE event and returns `false`
+    /// to signal abort (caller cancellation). Returns the fully assembled
+    /// assistant message and optional usage once the stream completes.
+    fn chat_stream(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+        on_event: Box<dyn FnMut(&StreamEvent) -> bool + Send>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+}

apps/application/src/ports/token.rs

@@ -0,0 +1,26 @@
+//! TokenService port — JWT access and refresh token abstraction.
+//!
+//! Defines the trait that JWT adapter implementations provide. Covers
+//! token generation (pair of access + refresh tokens) and access token
+//! verification (returns the subject claim).
+
+use anyhow::Result;
+
+/// Abstraction for JWT-based token generation and verification.
+///
+/// Implementors handle signing key management, token serialisation,
+/// and expiry validation. The trait is `Send + Sync` for use across
+/// thread boundaries.
+pub trait TokenService: Send + Sync {
+    /// Generate an access + refresh token pair for the given subject
+    /// identifier.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn generate_tokens(&self, sub: &str) -> Result<(String, String)>;
+
+    /// Verify an access token and return the embedded subject claim.
+    ///
+    /// Returns `Err` if the token is expired, malformed, or has an
+    /// invalid signature.
+    fn verify_access_token(&self, token: &str) -> Result<String>;
+}