docs(auth): document Tailscale auth system end-to-end

Add module-level and inline docs covering the full auth stack:
- axon-server lib.rs: auth modes table, ACL tag→role mapping, request-flow
  diagram, HTTP/gRPC failure codes
- auth.rs: AuthContext caching semantics and config examples; LocalAPI
  Unix-socket protocol note; TailscaleWhoisProvider trait and method docs;
  AuthContext::verify startup-time semantics; preferred_node_name precedence
- gateway.rs: authenticate_http_request middleware flow; auth_error_response
  HTTP status table; request_peer_address real-vs-mock explanation
- service.rs: auth_to_status gRPC status mapping table
- serve.rs: auth_context_from_serve_args priority table; DefaultRoleArg doc
- axon-core auth.rs: four-layer access control overview (RBAC, field masking,
  write policies, database grants)

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

Author: easel

crates/axon-core/src/auth.rs

@@ -1,8 +1,32 @@
-//! Role-based access control (RBAC) for Axon (US-044, FEAT-012).
+//! Role-based and attribute-based access control for Axon (FEAT-012).
 //!
-//! Four built-in roles control access to Axon operations. Roles are derived
-//! from the identity provider (Tailscale ACL tags, OIDC claims, etc.) and
-//! checked at the API handler level before executing each operation.
+//! # Layers
+//!
+//! **Layer 1 — RBAC** ([`Role`], [`CallerIdentity`], [`Operation`])
+//!
+//! Four built-in roles (`Admin > Write > Read > None`) control access to
+//! Axon operations.  Roles are derived from the identity provider (Tailscale
+//! ACL tags, OIDC claims, etc.) by the server layer and passed into handlers
+//! as a [`CallerIdentity`].  Handlers call [`CallerIdentity::check`] to
+//! enforce the minimum required role.
+//!
+//! **Layer 2 — Field-level masking** ([`MaskPolicy`])
+//!
+//! A `MaskPolicy` hides individual entity fields from callers whose role
+//! falls below a configured minimum.  Applied by [`CallerIdentity::apply_masks`]
+//! before returning entity data to the caller.  Admins always see all fields.
+//!
+//! **Layer 3 — Collection write control** ([`WritePolicy`])
+//!
+//! A `WritePolicy` sets a per-collection minimum write role and marks fields
+//! as immutable after creation.  Checked by the handler before any mutation.
+//!
+//! **Layer 4 — Database-scoped grants** ([`DatabaseGrant`], [`GrantRegistry`])
+//!
+//! Grants scope a role to a specific database (or `"*"` for all databases).
+//! Without a matching grant a caller has `Role::None` on that database.
+//! Admins with a global grant bypass per-database checks.  The grant registry
+//! is stored in `__axon_policies__` and enforced at the routing layer.
 
 use serde::{Deserialize, Serialize};
 

crates/axon-server/src/auth.rs

@@ -163,9 +163,22 @@ struct CachedIdentity {
     expires_at: Instant,
 }
 
+/// Abstraction over the Tailscale LocalAPI, enabling test doubles.
+///
+/// The production implementation ([`LocalApiWhoisProvider`]) contacts the
+/// real Tailscale daemon over its Unix socket.  Tests use `FakeWhoisProvider`
+/// to inject pre-canned responses without needing a running Tailscale daemon.
 pub(crate) trait TailscaleWhoisProvider: Send + Sync {
+    /// Verify that the provider is reachable.
+    ///
+    /// Called once at server startup via [`AuthContext::verify`] to surface
+    /// misconfigurations early (e.g., wrong socket path, daemon not running).
     fn verify(&self) -> BoxFuture<'_, Result<(), AuthError>>;
 
+    /// Resolve the identity of the given peer address.
+    ///
+    /// Returns [`AuthError::Unauthorized`] for non-tailnet addresses and
+    /// [`AuthError::ProviderUnavailable`] if the daemon cannot be reached.
     fn whois(
         &self,
         address: SocketAddr,
@@ -225,6 +238,12 @@ impl From<TsWhoisResponse> for TailscaleWhoisResponse {
 }
 
 // ── Direct Unix-socket HTTP client for the Tailscale LocalAPI ────────
+//
+// Tailscale does not bind a TCP port for its LocalAPI — it only listens on
+// a Unix domain socket.  This provider opens a new connection for every
+// request (no connection pooling) because whois calls are rare and caching
+// makes per-request cost negligible.  Each call issues one HTTP/1.1 GET
+// and reads the full response body before closing the socket.
 
 #[derive(Clone)]
 struct LocalApiWhoisProvider {
@@ -322,6 +341,31 @@ impl TailscaleWhoisProvider for LocalApiWhoisProvider {
 }
 
 /// Request authentication state shared by the HTTP and gRPC frontends.
+///
+/// `AuthContext` is cheaply `Clone`d (it wraps `Arc` internally) and intended
+/// to be inserted as Axum router state and tonic service state.
+///
+/// Resolved identities are cached by peer IP for [`cache_ttl`] to avoid a
+/// Unix socket round-trip on every request.  A cache hit requires only an
+/// `RwLock` read — no I/O.  The cache is never actively evicted; stale entries
+/// are ignored on the next lookup if their TTL has expired.
+///
+/// # Configuration examples
+///
+/// ```rust,ignore
+/// // Local development — no auth required
+/// let auth = AuthContext::no_auth();
+///
+/// // Tailscale (production default)
+/// let auth = AuthContext::tailscale(
+///     Role::Read,                                // default role for untagged nodes
+///     "/run/tailscale/tailscaled.sock",
+///     Duration::from_secs(60),                   // identity cache TTL
+/// );
+///
+/// // Guest mode — unauthenticated callers get read access
+/// let auth = AuthContext::guest(Role::Read);
+/// ```
 #[derive(Clone)]
 pub struct AuthContext {
     mode: AuthMode,
@@ -373,6 +417,13 @@ impl AuthContext {
         &self.mode
     }
 
+    /// Verify that the auth provider is reachable.
+    ///
+    /// Called once at server startup before accepting connections.  In
+    /// `NoAuth` and `Guest` modes this is a no-op.  In `Tailscale` mode it
+    /// issues a test request to the Tailscale daemon so a misconfigured
+    /// socket path or a stopped daemon surfaces immediately at startup rather
+    /// than on the first real request.
     pub async fn verify(&self) -> Result<(), AuthError> {
         match &self.provider {
             Some(provider) => provider.verify().await,
@@ -493,6 +544,10 @@ pub fn identity_from_tailscale(whois: &TailscaleWhoisResponse, default_role: &Ro
     }
 }
 
+/// Pick the most human-readable name for a Tailscale node.
+///
+/// Preference order: `ComputedName` → `Hostinfo.Hostname` →
+/// `ComputedNameWithHost` → first label of the FQDN `Name`.
 fn preferred_node_name(node: &TsNode) -> String {
     if !node.computed_name.is_empty() {
         return node.computed_name.clone();

crates/axon-server/src/gateway.rs

@@ -142,6 +142,13 @@ fn axon_error_response(err: AxonError) -> Response {
     }
 }
 
+/// Convert an [`AuthError`] into an HTTP error response.
+///
+/// | `AuthError` variant | HTTP status | JSON code |
+/// |---------------------|-------------|-----------|
+/// | `MissingPeerAddress` / `Unauthorized` | 401 | `"unauthorized"` |
+/// | `Forbidden` | 403 | `"forbidden"` |
+/// | `ProviderUnavailable` | 503 | `"auth_unavailable"` |
 pub(crate) fn auth_error_response(err: AuthError) -> Response {
     match err {
         AuthError::MissingPeerAddress | AuthError::Unauthorized(_) => (
@@ -177,6 +184,11 @@ fn rate_limit_response(limited: &RateLimited) -> Response {
         .into_response()
 }
 
+/// Extract the connecting peer's socket address from an axum request.
+///
+/// Checks both [`axum::extract::ConnectInfo`] (real TCP connections) and
+/// [`axum::extract::connect_info::MockConnectInfo`] (integration tests) so
+/// auth middleware works in both production and test contexts.
 fn request_peer_address(request: &axum::extract::Request) -> Option<SocketAddr> {
     request
         .extensions()
@@ -274,6 +286,22 @@ fn default_namespace_health<S: StorageAdapter>(
     ))
 }
 
+/// Axum middleware layer that resolves the caller's [`Identity`] and injects
+/// it as a typed request extension.
+///
+/// This middleware runs before every route handler.  It:
+/// 1. Extracts the peer socket address via [`request_peer_address`].
+/// 2. Calls [`AuthContext::resolve_peer`] (cache-first, then Tailscale whois).
+/// 3. Inserts the resolved [`Identity`] into `request.extensions`.
+/// 4. On auth failure, short-circuits with an appropriate HTTP error response
+///    (401, 403, or 503) without reaching the route handler.
+///
+/// Route handlers extract identity with:
+/// ```rust,ignore
+/// async fn my_handler(Extension(identity): Extension<Identity>, ...) { ... }
+/// ```
+/// and then call `identity.require_read()` / `require_write()` / `require_admin()`
+/// to enforce the minimum required role for that operation.
 pub(crate) async fn authenticate_http_request(
     State(auth): State<AuthContext>,
     mut request: axum::extract::Request,

crates/axon-server/src/lib.rs

@@ -1,4 +1,46 @@
-// placeholder — filled in by service.rs and gateway.rs modules
+//! Axon server — HTTP gateway, gRPC service, MCP stdio, and authentication.
+//!
+//! # Authentication
+//!
+//! Identity is resolved once per request by [`auth::AuthContext`] and
+//! injected as a typed extension.  Three modes are supported:
+//!
+//! | Mode | Flag | Actor | Role |
+//! |------|------|-------|------|
+//! | `NoAuth` | `--no-auth` | `"anonymous"` | Admin |
+//! | `Tailscale` | *(default)* | node name | from ACL tags |
+//! | `Guest` | `--guest-role <role>` | `"guest"` | configured role |
+//!
+//! In `Tailscale` mode the server contacts the local Tailscale daemon over its
+//! Unix socket (`/run/tailscale/tailscaled.sock` by default) and calls
+//! `/localapi/v0/whois?addr=<peer>` to resolve the connecting node's identity.
+//! Resolved identities are cached by peer IP for the duration of
+//! `--auth-cache-ttl-secs` (default 60 s).
+//!
+//! ACL tag → role mapping:
+//! - `tag:axon-admin` → [`Role::Admin`]
+//! - `tag:axon-write` / `tag:axon-agent` → [`Role::Write`]
+//! - `tag:axon-read` → [`Role::Read`]
+//! - no matching tag → `--tailscale-default-role` (default `read`)
+//!
+//! Connections that are not on the tailnet are rejected with HTTP 401 / gRPC
+//! `UNAUTHENTICATED`.  If the Tailscale daemon is unreachable the server
+//! returns HTTP 503 / gRPC `UNAVAILABLE`.
+//!
+//! # Request flow
+//!
+//! ```text
+//! TCP accept
+//!   └─ authenticate_http_request  (gateway.rs middleware)
+//!        ├─ AuthContext::resolve_peer  →  Identity
+//!        └─ insert Identity into request extensions
+//!             └─ route handler
+//!                  ├─ extract Extension<Identity>
+//!                  ├─ identity.require_read() / require_write() / require_admin()
+//!                  └─ handler logic
+//! ```
+//!
+//! gRPC follows the same pattern via [`service::AxonServiceImpl::authorize`].
 pub mod actor_scope;
 pub mod auth;
 mod collection_listing;

crates/axon-server/src/serve.rs

@@ -23,6 +23,9 @@ pub enum StorageBackend {
     Postgres,
 }
 
+/// CLI-compatible role selection for `--tailscale-default-role` and `--guest-role`.
+///
+/// Converted to [`Role`] via `From<DefaultRoleArg>`.
 #[derive(Clone, Debug, clap::ValueEnum)]
 pub enum DefaultRoleArg {
     Admin,
@@ -135,7 +138,18 @@ pub fn init_tracing(mcp_stdio: bool) {
     let _ = result;
 }
 
-/// Resolve the [`AuthContext`] from [`ServeArgs`].
+/// Build an [`AuthContext`] from the parsed CLI / env flags.
+///
+/// Priority: `--no-auth` > `--guest-role` > Tailscale (default).
+///
+/// | Condition | Mode | Notes |
+/// |-----------|------|-------|
+/// | `--no-auth` | `NoAuth` | All requests get `actor=anonymous, role=Admin`. |
+/// | `--guest-role <role>` | `Guest` | Tailscale daemon not required. |
+/// | *(default)* | `Tailscale` | Contacts `--tailscale-socket` on every cache miss. |
+///
+/// After construction, call [`AuthContext::verify`] (already done in [`serve`])
+/// to fail fast if the daemon is unreachable.
 pub fn auth_context_from_serve_args(args: &ServeArgs) -> AuthContext {
     if args.no_auth {
         AuthContext::no_auth()

crates/axon-server/src/service.rs

@@ -108,6 +108,13 @@ fn entity_to_proto(e: axon_core::types::Entity) -> EntityProto {
     }
 }
 
+/// Convert an [`AuthError`] into a gRPC [`Status`].
+///
+/// | `AuthError` variant | gRPC status |
+/// |---------------------|-------------|
+/// | `MissingPeerAddress` / `Unauthorized` | `UNAUTHENTICATED` |
+/// | `Forbidden` | `PERMISSION_DENIED` |
+/// | `ProviderUnavailable` | `UNAVAILABLE` |
 fn auth_to_status(error: AuthError) -> Status {
     match error {
         AuthError::MissingPeerAddress | AuthError::Unauthorized(_) => {