feat(auth,server,cli): per-principal RBAC user-role registry (US-048)

Adds an explicit user-role registry backed by the control-plane SQLite
database.  Tailscale provides identity; Axon now owns authorisation.

Role resolution priority:
  1. Axon user-role registry (login → role, overrides everything)
  2. Tailscale ACL tag mapping (tag:axon-admin/write/read)
  3. --tailscale-default-role fallback

Changes:
- user_roles.rs: new UserRoleStore (Arc<RwLock<HashMap>>) with
  write-through SQLite persistence and full unit tests
- control_plane.rs: migrate_user_roles() in schema migration; wrapper
  methods list/set/remove_user_role()
- auth.rs: AuthContext gains user_roles field; resolve_peer checks
  registry before tag-based fallback; with_user_roles() builder;
  two new tests for registry override behaviour
- control_plane_routes.rs: ControlPlaneState gains UserRoleStore;
  GET /control/users, PUT /control/users/{login},
  DELETE /control/users/{login} endpoints; 5 new HTTP tests
- serve.rs: loads user roles from DB at startup, shares store with
  both AuthContext and ControlPlaneState
- axon-cli: `axon user grant/revoke/list` — HTTP client mode calls
  REST API; embedded mode opens control-plane SQLite directly
- axon-config: control_plane_sqlite_path() helper
- gateway.rs / service.rs: update actor assertions to user_login
  (identity_from_tailscale already returned login; tests were stale)

Spec: FEAT-012-authorization.md updated with US-048 and V4 status row.

Verification: cargo check --workspace, cargo test --workspace (254 lib
tests pass; 1 pre-existing api_contract failure unrelated)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: easel

crates/axon-cli/src/client.rs

@@ -416,6 +416,39 @@ impl HttpClient {
         Self::parse_response(resp)
     }
 
+    // ── User-role management ─────────────────────────────────────────────────
+
+    /// `GET /control/users` — list all explicit user-role assignments.
+    pub fn list_users(&self) -> Result<Value> {
+        let resp = self
+            .client
+            .get(format!("{}/control/users", self.base_url))
+            .send()
+            .context("failed to send list-users request")?;
+        Self::parse_response(resp)
+    }
+
+    /// `PUT /control/users/{login}` — assign a role to a principal.
+    pub fn set_user_role(&self, login: &str, role: &str) -> Result<Value> {
+        let resp = self
+            .client
+            .put(format!("{}/control/users/{login}", self.base_url))
+            .json(&serde_json::json!({ "role": role }))
+            .send()
+            .context("failed to send set-user-role request")?;
+        Self::parse_response(resp)
+    }
+
+    /// `DELETE /control/users/{login}` — remove an explicit role assignment.
+    pub fn remove_user_role(&self, login: &str) -> Result<Value> {
+        let resp = self
+            .client
+            .delete(format!("{}/control/users/{login}", self.base_url))
+            .send()
+            .context("failed to send remove-user-role request")?;
+        Self::parse_response(resp)
+    }
+
     // ── Internal helpers ─────────────────────────────────────────────────────
 
     /// Parse a response: if 2xx, return the JSON body; otherwise return an error.

crates/axon-cli/src/main.rs

@@ -145,6 +145,33 @@ enum Command {
         #[arg(long, short = 'd', default_value = "1")]
         depth: usize,
     },
+
+    /// Manage per-principal role assignments.
+    #[cfg(feature = "serve")]
+    #[command(subcommand)]
+    User(UserCmd),
+}
+
+#[cfg(feature = "serve")]
+#[derive(Subcommand)]
+enum UserCmd {
+    /// Grant a role to a principal (creates or updates the assignment).
+    Grant {
+        /// The user's login name (e.g. `erik@example.com`).
+        login: String,
+        /// The role to assign: `admin`, `write`, or `read`.
+        role: String,
+    },
+    /// Revoke the explicit role assignment for a principal.
+    ///
+    /// After revocation, the principal falls back to tag-based or default role
+    /// resolution on their next request.
+    Revoke {
+        /// The user's login name.
+        login: String,
+    },
+    /// List all explicit user-role assignments.
+    List,
 }
 
 #[derive(Subcommand)]
@@ -645,6 +672,11 @@ pub fn run(cli: Cli) -> Result<()> {
             println!("{}", axon_config::paths::config_file().display());
             return Ok(());
         }
+        #[cfg(feature = "serve")]
+        Command::User(_) => {
+            // User commands are handled in client mode (HTTP) or embedded mode
+            // (direct SQLite) below; no early return here.
+        }
         _ => {}
     }
 
@@ -709,13 +741,97 @@ pub fn run(cli: Cli) -> Result<()> {
             &cli.output,
             &mut handler,
         ),
+        // User-role commands against the control-plane database directly.
+        #[cfg(feature = "serve")]
+        Command::User(cmd) => run_user_embedded(cmd, &cli.output),
         // Already handled above; unreachable
         #[cfg(feature = "serve")]
         Command::Serve(_) | Command::Mcp { .. } => unreachable!(),
         Command::Doctor | Command::Init { .. } | Command::Server(_) | Command::Config(ConfigCmd::Path) => unreachable!(),
     }
 }
 
+/// Run `axon user` commands against the control-plane SQLite database directly
+/// (no server required).
+#[cfg(feature = "serve")]
+fn run_user_embedded(cmd: UserCmd, format: &OutputFormat) -> Result<()> {
+    use axon_server::auth::Role;
+    use axon_server::control_plane::ControlPlaneDb;
+
+    let cp_path = axon_config::paths::control_plane_sqlite_path()
+        .to_string_lossy()
+        .into_owned();
+    let db = ControlPlaneDb::open(&cp_path)
+        .with_context(|| format!("failed to open control-plane database: {cp_path}"))?;
+
+    match cmd {
+        UserCmd::List => {
+            let entries = db
+                .list_user_roles()
+                .map_err(|e| anyhow::anyhow!("failed to list user roles: {e}"))?;
+            let users: Vec<serde_json::Value> = entries
+                .iter()
+                .map(|e| serde_json::json!({ "login": e.login, "role": e.role }))
+                .collect();
+            match format {
+                OutputFormat::Json | OutputFormat::Yaml => {
+                    print_serialized(&serde_json::json!({ "users": users }), format);
+                }
+                OutputFormat::Table => {
+                    if entries.is_empty() {
+                        println!("No explicit user-role assignments.");
+                    } else {
+                        for e in &entries {
+                            let role_str = serde_json::to_string(&e.role).unwrap_or_default();
+                            println!("{:<40} {}", e.login, role_str.trim_matches('"'));
+                        }
+                    }
+                }
+            }
+            Ok(())
+        }
+        UserCmd::Grant { login, role } => {
+            let role: Role = match role.as_str() {
+                "admin" => Role::Admin,
+                "write" => Role::Write,
+                "read" => Role::Read,
+                other => anyhow::bail!("unknown role '{other}'; must be admin, write, or read"),
+            };
+            db.set_user_role(&login, &role)
+                .map_err(|e| anyhow::anyhow!("failed to set role: {e}"))?;
+            match format {
+                OutputFormat::Json | OutputFormat::Yaml => {
+                    print_serialized(&serde_json::json!({ "login": login, "role": role }), format);
+                }
+                OutputFormat::Table => {
+                    let role_str = serde_json::to_string(&role).unwrap_or_default();
+                    println!("Granted {} to {login}", role_str.trim_matches('"'));
+                }
+            }
+            Ok(())
+        }
+        UserCmd::Revoke { login } => {
+            let removed = db
+                .remove_user_role(&login)
+                .map_err(|e| anyhow::anyhow!("failed to revoke role: {e}"))?;
+            if removed {
+                match format {
+                    OutputFormat::Json | OutputFormat::Yaml => {
+                        print_serialized(
+                            &serde_json::json!({ "login": login, "deleted": true }),
+                            format,
+                        );
+                    }
+                    OutputFormat::Table => println!("Revoked explicit role for {login}"),
+                }
+            } else {
+                anyhow::bail!("no explicit role assigned to '{login}'");
+            }
+            Ok(())
+        }
+    }
+}
+
 #[cfg(feature = "serve")]
 fn run_server_command(cli: Cli) -> Result<()> {
     let rt = tokio::runtime::Runtime::new().context("failed to create tokio runtime")?;
@@ -2264,6 +2380,21 @@ fn run_client_mode(cli: Cli, client: client::HttpClient) -> Result<()> {
         Command::Bead(_) => {
             anyhow::bail!("bead commands are not yet available in client mode");
         }
+        #[cfg(feature = "serve")]
+        Command::User(cmd) => match cmd {
+            UserCmd::List => {
+                let resp = client.list_users()?;
+                print_serialized(&resp, &cli.output);
+            }
+            UserCmd::Grant { login, role } => {
+                let resp = client.set_user_role(&login, &role)?;
+                print_serialized(&resp, &cli.output);
+            }
+            UserCmd::Revoke { login } => {
+                let resp = client.remove_user_role(&login)?;
+                print_serialized(&resp, &cli.output);
+            }
+        },
         // These are handled before mode detection; unreachable in client mode
         Command::Serve(_) | Command::Mcp { .. } | Command::Doctor | Command::Init { .. }
         | Command::Server(_) | Command::Config(ConfigCmd::Path) => unreachable!(),

crates/axon-config/src/paths.rs

@@ -50,6 +50,13 @@ pub fn default_sqlite_path() -> PathBuf {
     data_dir().join("axon.db")
 }
 
+/// Returns the default path for the control-plane SQLite database.
+///
+/// Equivalent to `data_dir()/axon-control-plane.db`.
+pub fn control_plane_sqlite_path() -> PathBuf {
+    data_dir().join("axon-control-plane.db")
+}
+
 /// Returns the directory for per-tenant data.
 ///
 /// Equivalent to `data_dir()/tenants/`.

crates/axon-server/src/auth.rs

@@ -377,6 +377,8 @@ pub struct AuthContext {
     provider: Option<Arc<dyn TailscaleWhoisProvider>>,
     cache: Arc<RwLock<HashMap<IpAddr, CachedIdentity>>>,
     cache_ttl: Duration,
+    /// Per-principal role registry.  Overrides tag-based role resolution.
+    user_roles: crate::user_roles::UserRoleStore,
 }
 
 impl Default for AuthContext {
@@ -393,6 +395,7 @@ impl AuthContext {
             provider: None,
             cache: Arc::new(RwLock::new(HashMap::new())),
             cache_ttl: Duration::from_secs(60),
+            user_roles: crate::user_roles::UserRoleStore::default(),
         }
     }
 
@@ -403,6 +406,7 @@ impl AuthContext {
             provider: None,
             cache: Arc::new(RwLock::new(HashMap::new())),
             cache_ttl: Duration::from_secs(0),
+            user_roles: crate::user_roles::UserRoleStore::default(),
         }
     }
 
@@ -417,6 +421,22 @@ impl AuthContext {
         Self::with_provider(mode, provider, cache_ttl)
     }
 
+    /// Replace the user-role store with `store`.
+    ///
+    /// Both the returned `AuthContext` and the original `store` handle share
+    /// the same underlying `Arc`, so mutations through either are immediately
+    /// visible.
+    #[must_use]
+    pub fn with_user_roles(mut self, store: crate::user_roles::UserRoleStore) -> Self {
+        self.user_roles = store;
+        self
+    }
+
+    /// Return a reference to the shared user-role store.
+    pub fn user_roles(&self) -> &crate::user_roles::UserRoleStore {
+        &self.user_roles
+    }
+
     #[must_use]
     pub fn mode(&self) -> &AuthMode {
         &self.mode
@@ -453,7 +473,23 @@ impl AuthContext {
                         "tailscale auth is enabled but no LocalAPI provider is configured".into(),
                     )
                 })?;
-                let identity = identity_from_tailscale(&provider.whois(peer).await?, default_role);
+                let whois = provider.whois(peer).await?;
+
+                // Priority: (1) Axon user-role registry by login, (2) ACL tags,
+                // (3) --tailscale-default-role.
+                let role = if whois.user_login.is_empty() {
+                    role_from_tags(&whois.tags, default_role)
+                } else {
+                    self.user_roles
+                        .get(&whois.user_login)
+                        .unwrap_or_else(|| role_from_tags(&whois.tags, default_role))
+                };
+                let actor = if whois.user_login.is_empty() {
+                    whois.node_name.clone()
+                } else {
+                    whois.user_login.clone()
+                };
+                let identity = Identity { actor, role };
                 self.store_cached_identity(peer_ip, identity.clone()).await;
                 Ok(identity)
             }
@@ -491,6 +527,7 @@ impl AuthContext {
             provider: Some(provider),
             cache: Arc::new(RwLock::new(HashMap::new())),
             cache_ttl,
+            user_roles: crate::user_roles::UserRoleStore::default(),
         }
     }
 }
@@ -548,10 +585,10 @@ const fn role_priority(role: &Role) -> u8 {
 /// whose login name is empty, the node name is used as a fallback so that
 /// automated agents still produce a meaningful actor string.
 pub fn identity_from_tailscale(whois: &TailscaleWhoisResponse, default_role: &Role) -> Identity {
-    let actor = if !whois.user_login.is_empty() {
-        whois.user_login.clone()
-    } else {
+    let actor = if whois.user_login.is_empty() {
         whois.node_name.clone()
+    } else {
+        whois.user_login.clone()
     };
     Identity {
         actor,
@@ -977,4 +1014,78 @@ mod tests {
         assert!(id.require_write().is_ok());
         assert!(id.require_admin().is_ok());
     }
+
+    // ── User-role registry tests (US-048) ─────────────────────────────────────
+
+    #[tokio::test]
+    async fn user_role_registry_overrides_tag_based_role() {
+        use crate::user_roles::{UserRoleEntry, UserRoleStore};
+
+        let address = SocketAddr::from(([100, 101, 102, 103], 443));
+        // Tailscale says the node has no axon tags → default role would be Read.
+        let provider = Arc::new(FakeWhoisProvider::with_result(
+            address,
+            Ok(TailscaleWhoisResponse {
+                node_name: "erikd-laptop".into(),
+                user_login: "erik@example.com".into(),
+                tags: vec![],
+            }),
+        ));
+        let store = UserRoleStore::default();
+        store.load_from_entries(vec![UserRoleEntry {
+            login: "erik@example.com".into(),
+            role: Role::Write,
+        }]);
+        let context = AuthContext::with_provider(
+            AuthMode::Tailscale {
+                default_role: Role::Read,
+            },
+            provider,
+            Duration::from_secs(60),
+        )
+        .with_user_roles(store);
+
+        let identity = context
+            .resolve_peer(Some(address))
+            .await
+            .expect("should resolve");
+        assert_eq!(identity.actor, "erik@example.com");
+        // Registry grants Write, overriding the Read default.
+        assert_eq!(identity.role, Role::Write);
+    }
+
+    #[tokio::test]
+    async fn user_role_registry_overrides_acl_tag_role() {
+        use crate::user_roles::{UserRoleEntry, UserRoleStore};
+
+        let address = SocketAddr::from(([100, 101, 102, 104], 443));
+        // Tailscale tags say Admin, but registry says Read.
+        let provider = Arc::new(FakeWhoisProvider::with_result(
+            address,
+            Ok(TailscaleWhoisResponse {
+                node_name: "erikd-laptop".into(),
+                user_login: "restricted@example.com".into(),
+                tags: vec!["tag:axon-admin".into()],
+            }),
+        ));
+        let store = UserRoleStore::default();
+        store.load_from_entries(vec![UserRoleEntry {
+            login: "restricted@example.com".into(),
+            role: Role::Read,
+        }]);
+        let context = AuthContext::with_provider(
+            AuthMode::Tailscale {
+                default_role: Role::Read,
+            },
+            provider,
+            Duration::from_secs(60),
+        )
+        .with_user_roles(store);
+
+        let identity = context
+            .resolve_peer(Some(address))
+            .await
+            .expect("should resolve");
+        assert_eq!(identity.role, Role::Read);
+    }
 }