fix(docs): fix markdown lint errors in OIDC architecture docs

Add blank lines before lists and fenced code blocks to satisfy
markdownlint MD031 and MD032 rules.

Author: mrunalp

architecture/oidc-auth.md

@@ -4,21 +4,14 @@ OpenShell supports OAuth2/OIDC (OpenID Connect) as an authentication mode alongs
 
 ## Architecture
 
-```
-                                    +-------------------+
-                                    |    Keycloak /      |
-                                    |    OIDC Provider   |
-                                    +--------+----------+
-                                             |
-                          JWKS (cached)      |  Token exchange
-                          +---------+--------+---------+
-                          |                            |
-                          v                            v
-+----------+    Bearer token    +-----------+    Auth Code    +---------+
-|          | -----------------> |           | <-------------- |         |
-|   CLI    |    gRPC metadata   |  Gateway  |    + PKCE       | Browser |
-|          | <----------------- |  Server   |                 |         |
-+----------+    response        +-----------+                 +---------+
+```mermaid
+graph LR
+    CLI -->|"Bearer token<br/>(gRPC metadata)"| Gateway["Gateway<br/>Server"]
+    Gateway -->|response| CLI
+    Gateway -->|"JWKS (cached)"| Keycloak["Keycloak /<br/>OIDC Provider"]
+    Browser -->|"Auth Code + PKCE"| Gateway
+    Keycloak -->|"Token exchange"| CLI
+    Keycloak -->|"Token exchange"| Browser
 ```
 
 ## Auth Modes
@@ -151,6 +144,7 @@ GET {jwks_uri}                                 ->  { keys: [...] }
 ```
 
 Keys are cached in memory with a configurable TTL (default: 1 hour). A `refresh_mutex` serializes refresh operations so concurrent requests coalesce into a single HTTP fetch. The cache refreshes:
+
 - When the TTL expires (on next request, re-checked under the mutex to avoid thundering herd).
 - Immediately when a JWT references a `kid` not in the cache (handles key rotation).
 
@@ -192,6 +186,7 @@ These methods accept either an OIDC Bearer token (CLI users) or a sandbox secret
 | `OpenShell/GetSandboxConfig` | CLI reads effective sandbox policy and settings; sandbox callers may still use the shared secret |
 
 **Sandbox-secret restriction on `UpdateConfig`:** When a sandbox-secret-authenticated caller invokes `UpdateConfig`, the handler in `policy.rs` enforces strict scope limits via `validate_sandbox_secret_update()`. The caller:
+
 - **Must** provide a sandbox `name` (sandbox-scoped only).
 - **Must** include a `policy` payload (policy sync only).
 - **May not** set `global = true` (no global config mutation).

architecture/oidc-local-testing.md

@@ -19,6 +19,7 @@ mise run keycloak
 Wait for "Keycloak is ready." The script prints connection info including test users.
 
 Verify:
+
 ```bash
 curl -s http://localhost:8180/realms/openshell/.well-known/openid-configuration | jq .issuer
 # Expected: "http://localhost:8180/realms/openshell"
@@ -37,6 +38,7 @@ cargo run -p openshell-server -- \
 ```
 
 You should see:
+
 ```
 OIDC JWT validation enabled (issuer: http://localhost:8180/realms/openshell)
 Server listening address=0.0.0.0:8080

crates/openshell-bootstrap/src/lib.rs

@@ -130,7 +130,7 @@ pub struct DeployOptions {
     pub oidc_audience: String,
     /// OIDC client ID for CLI login. Defaults to "openshell-cli".
     pub oidc_client_id: String,
-    /// OIDC roles claim path (e.g. "realm_access.roles").
+    /// OIDC roles claim path (e.g. `realm_access.roles`).
     pub oidc_roles_claim: Option<String>,
     /// OIDC admin role name.
     pub oidc_admin_role: Option<String>,
@@ -266,11 +266,11 @@ fn apply_oidc_gateway_metadata(
         && let Some(existing) = existing
         && existing.auth_mode.as_deref() == Some("oidc")
     {
-        metadata.auth_mode = existing.auth_mode.clone();
-        metadata.oidc_issuer = existing.oidc_issuer.clone();
-        metadata.oidc_client_id = existing.oidc_client_id.clone();
-        metadata.oidc_audience = existing.oidc_audience.clone();
-        metadata.oidc_scopes = existing.oidc_scopes.clone();
+        metadata.auth_mode.clone_from(&existing.auth_mode);
+        metadata.oidc_issuer.clone_from(&existing.oidc_issuer);
+        metadata.oidc_client_id.clone_from(&existing.oidc_client_id);
+        metadata.oidc_audience.clone_from(&existing.oidc_audience);
+        metadata.oidc_scopes.clone_from(&existing.oidc_scopes);
     }
 }
 

crates/openshell-bootstrap/src/metadata.rs

@@ -56,12 +56,12 @@ pub struct GatewayMetadata {
     pub oidc_client_id: Option<String>,
 
     /// OIDC audience for the resource server (API). When different from
-    /// client_id, the CLI requests this audience in the token exchange.
-    /// When `None`, defaults to the client_id.
+    /// `client_id`, the CLI requests this audience in the token exchange.
+    /// When `None`, defaults to the `client_id`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub oidc_audience: Option<String>,
 
-    /// Space-separated OAuth2 scopes to request during OIDC login.
+    /// Space-separated `OAuth2` scopes to request during OIDC login.
     /// When set, tokens will include these scopes for fine-grained access control.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub oidc_scopes: Option<String>,

crates/openshell-bootstrap/src/oidc_token.rs

@@ -16,10 +16,10 @@ use std::path::PathBuf;
 /// OIDC token bundle persisted to disk.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OidcTokenBundle {
-    /// OAuth2 access token (JWT).
+    /// `OAuth2` access token (JWT).
     pub access_token: String,
 
-    /// OAuth2 refresh token. `None` for client_credentials grants.
+    /// `OAuth2` refresh token. `None` for `client_credentials` grants.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub refresh_token: Option<String>,
 

crates/openshell-cli/src/bootstrap.rs

@@ -191,13 +191,22 @@ pub async fn run_bootstrap(
 
     // Deploy the gateway. The deploy flow auto-resumes from existing state
     // when it finds one. If that fails, fall back to a full recreate.
-    let handle = match deploy_gateway_with_panel(build_options(false), &gateway_name, location)
-        .await
+    let handle = match Box::pin(deploy_gateway_with_panel(
+        build_options(false),
+        &gateway_name,
+        location,
+    ))
+    .await
     {
         Ok(handle) => handle,
         Err(resume_err) => {
             tracing::warn!("auto-bootstrap resume failed, falling back to recreate: {resume_err}");
-            deploy_gateway_with_panel(build_options(true), &gateway_name, location).await?
+            Box::pin(deploy_gateway_with_panel(
+                build_options(true),
+                &gateway_name,
+                location,
+            ))
+            .await?
         }
     };
     let server = handle.gateway_endpoint().to_string();

crates/openshell-cli/src/main.rs

@@ -882,7 +882,7 @@ enum GatewayCommands {
         #[arg(long, requires = "oidc_issuer")]
         oidc_user_role: Option<String>,
 
-        /// Space-separated OAuth2 scopes to request during OIDC login.
+        /// Space-separated `OAuth2` scopes to request during OIDC login.
         #[arg(long, requires = "oidc_issuer")]
         oidc_scopes: Option<String>,
 
@@ -982,7 +982,7 @@ enum GatewayCommands {
         #[arg(long, requires = "oidc_issuer")]
         oidc_audience: Option<String>,
 
-        /// Space-separated OAuth2 scopes to request during OIDC login.
+        /// Space-separated `OAuth2` scopes to request during OIDC login.
         /// When set, tokens will include these scopes for fine-grained access control.
         #[arg(long, requires = "oidc_issuer")]
         oidc_scopes: Option<String>,
@@ -1873,7 +1873,7 @@ async fn main() -> Result<()> {
                     oidc_user_role.as_deref(),
                     oidc_scopes.as_deref(),
                     oidc_scopes_claim.as_deref(),
-                )
+                ))
                 .await?;
             }
             GatewayCommands::Stop {

crates/openshell-cli/src/oidc_auth.rs

@@ -4,7 +4,7 @@
 //! OIDC authentication flows for CLI gateway login.
 //!
 //! Implements Authorization Code + PKCE (interactive browser flow) and
-//! Client Credentials (CI/automation) OAuth2 grant types against a
+//! Client Credentials (CI/automation) `OAuth2` grant types against a
 //! Keycloak-compatible OIDC provider.
 
 use bytes::Bytes;
@@ -219,7 +219,7 @@ pub async fn oidc_client_credentials_flow(
     ))
 }
 
-/// Refresh an OIDC token using the refresh_token grant.
+/// Refresh an OIDC token using the `refresh_token` grant.
 ///
 /// Preserves the existing refresh token if the server does not return a new
 /// one (per OAuth 2.0 spec, the refresh response may omit `refresh_token`).
@@ -245,7 +245,7 @@ pub async fn oidc_refresh_token(bundle: &OidcTokenBundle) -> Result<OidcTokenBun
     let mut refreshed =
         bundle_from_oauth2_response(&token_response, &bundle.issuer, &bundle.client_id);
     if refreshed.refresh_token.is_none() {
-        refreshed.refresh_token = bundle.refresh_token.clone();
+        refreshed.refresh_token.clone_from(&bundle.refresh_token);
     }
     Ok(refreshed)
 }
@@ -288,8 +288,8 @@ fn bundle_from_oauth2_response(
         .as_secs();
 
     OidcTokenBundle {
-        access_token: resp.access_token().secret().to_string(),
-        refresh_token: resp.refresh_token().map(|rt| rt.secret().to_string()),
+        access_token: resp.access_token().secret().clone(),
+        refresh_token: resp.refresh_token().map(|rt| rt.secret().clone()),
         expires_at: resp.expires_in().map(|ei| now + ei.as_secs()),
         issuer: issuer.to_string(),
         client_id: client_id.to_string(),
@@ -305,7 +305,7 @@ fn percent_decode(s: &str) -> String {
             let hi = bytes.next().and_then(|b| char::from(b).to_digit(16));
             let lo = bytes.next().and_then(|b| char::from(b).to_digit(16));
             if let (Some(h), Some(l)) = (hi, lo) {
-                out.push((h * 16 + l) as u8);
+                out.push(u8::try_from(h * 16 + l).unwrap_or(b'%'));
             } else {
                 out.push(b'%');
             }
@@ -354,7 +354,7 @@ async fn run_oidc_callback_server(
         tokio::spawn(async move {
             let service = service_fn(move |req| {
                 let state = Arc::clone(&state);
-                async move { Ok::<_, Infallible>(handle_oidc_callback(req, state).await) }
+                async move { Ok::<_, Infallible>(handle_oidc_callback(req, state)) }
             });
 
             if let Err(error) = Builder::new(TokioExecutor::new())
@@ -367,7 +367,7 @@ async fn run_oidc_callback_server(
     }
 }
 
-async fn handle_oidc_callback(
+fn handle_oidc_callback(
     req: hyper::Request<hyper::body::Incoming>,
     state: Arc<CallbackState>,
 ) -> Response<Full<Bytes>> {

crates/openshell-cli/src/run.rs

@@ -955,6 +955,7 @@ where
 ///
 /// An `ssh://` endpoint (e.g., `ssh://user@host:8080`) is shorthand for
 /// `--remote user@host` with the gateway endpoint derived from the URL.
+#[allow(clippy::too_many_arguments)]
 pub async fn gateway_add(
     endpoint: &str,
     name: Option<&str>,
@@ -1338,7 +1339,7 @@ pub fn gateway_logout(name: &str) -> Result<()> {
         }
     }
 
-    eprintln!("{} Logged out of gateway '{name}'", "✓".green().bold(),);
+    eprintln!("{} Logged out of gateway '{name}'", "✓".green().bold());
     Ok(())
 }
 
@@ -1680,15 +1681,15 @@ pub async fn gateway_admin_deploy(
         }
     }
 
-    let handle = deploy_gateway_with_panel(options, name, location).await?;
+    let handle = Box::pin(deploy_gateway_with_panel(options, name, location)).await?;
 
     // Persist oidc_scopes in gateway metadata so `gateway login` can
     // request the correct scopes later.
-    if let Some(scopes) = oidc_scopes {
-        if let Ok(mut meta) = openshell_bootstrap::load_gateway_metadata(name) {
-            meta.oidc_scopes = Some(scopes.to_string());
-            let _ = store_gateway_metadata(name, &meta);
-        }
+    if let Some(scopes) = oidc_scopes
+        && let Ok(mut meta) = openshell_bootstrap::load_gateway_metadata(name)
+    {
+        meta.oidc_scopes = Some(scopes.to_string());
+        let _ = store_gateway_metadata(name, &meta);
     }
 
     // Wait for the gRPC endpoint to actually accept connections before

crates/openshell-cli/src/tls.rs

@@ -292,21 +292,19 @@ pub async fn build_channel(server: &str, tls: &TlsOptions) -> Result<Channel> {
         // OIDC bearer auth over HTTPS: use mTLS certs for the transport layer
         // when available (server may still require client certs), and layer
         // the Bearer token on top via the interceptor.
-        match require_tls_materials(server, tls) {
-            Ok(materials) => build_tonic_tls_config(&materials),
-            Err(_) => {
+        require_tls_materials(server, tls).map_or_else(
+            |_| {
                 let resolved = tls.with_default_paths(server);
-                if let Some(ca_path) = resolved.ca.as_ref() {
-                    if let Ok(ca_pem) = std::fs::read(ca_path) {
+                resolved
+                    .ca
+                    .as_ref()
+                    .and_then(|ca_path| std::fs::read(ca_path).ok())
+                    .map_or_else(ClientTlsConfig::new, |ca_pem| {
                         ClientTlsConfig::new().ca_certificate(Certificate::from_pem(ca_pem))
-                    } else {
-                        ClientTlsConfig::new()
-                    }
-                } else {
-                    ClientTlsConfig::new()
-                }
-            }
-        }
+                    })
+            },
+            |materials| build_tonic_tls_config(&materials),
+        )
     } else if tls.edge_token.is_some() {
         // Edge bearer mode — routed through tunnel above; if we reach here
         // the server is not HTTPS so connect plaintext.
@@ -331,11 +329,13 @@ pub async fn grpc_client(server: &str, tls: &TlsOptions) -> Result<GrpcClient> {
     Ok(OpenShellClient::with_interceptor(channel, interceptor))
 }
 
-/// Interceptor that injects authentication headers into every outgoing
-/// gRPC request. Supports OIDC Bearer tokens (standard `authorization`
-/// header) and Cloudflare Access tokens (custom headers). When no token
-/// is set, acts as a no-op. OIDC takes precedence over edge tokens.
+/// Interceptor that injects authentication headers into every outgoing gRPC request.
+///
+/// Supports OIDC Bearer tokens (standard `authorization` header) and
+/// Cloudflare Access tokens (custom headers). When no token is set, acts
+/// as a no-op. OIDC takes precedence over edge tokens.
 #[derive(Clone)]
+#[allow(clippy::struct_field_names)]
 pub struct EdgeAuthInterceptor {
     /// Standard `authorization: Bearer <token>` for OIDC.
     bearer_value: Option<tonic::metadata::MetadataValue<tonic::metadata::Ascii>>,