Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
37.0 KB
Raw Blame
//! Per-request actor identity — who triggered an operation.
//!
//! ai-memory's wiki is single-tenant (no per-page RBAC; everyone with auth sees
//! the same pages), but writes can be **attributed** to the user who made them.
//! Operational session and handoff state is owner-scoped so one operator
//! cannot accidentally finalize or consume another operator's live context.
//! [`ActorContext`] is the typed carrier for that identity, injected once
//! per request by the auth middleware and threaded through to the writer
//! actor so attribution lands in the same SQL transaction as the data.
//!
//! ## Resolution rungs
//!
//! 1. **Anonymous** — no `Authorization` header configured at all.
//!    `ActorContext::default()` (all fields `None`). The pre-multi-user
//!    behaviour; backward-compatible for every existing single-user setup.
//! 2. **Identified single-user (root)** — `AI_MEMORY_AUTH_TOKEN` matches
//!    `config.auth.bearer_token`. Middleware fills `user` / `email` / `name`
//!    from `[auth].root_username` / `root_email` (and optional `root_name`).
//! 3. **Identified multi-user** — bearer token matches an active
//!    `api_credentials.token_hash` row. Middleware fills the actor from the owning user.
//! 4. **External auth proxy** — a trusted sidecar authenticates with the
//!    dedicated proxy bearer and asserts a username or complete OIDC
//!    issuer/subject pair in `X-Memory-Actor-*` headers. Proxy callers are users
//!    unless the stable OIDC pair exactly matches the configured root pair.
//!
//! ## Why not RBAC
//!
//! ai-memory v1's data model is single-tenant by design. Attribution
//! records *who* did a write; it does not gate *whether* they could do it.
//! That keeps the engine focused on "shared memory for a household /
//! small team" without bringing in roles, groups, or per-page ACLs.
//!
//! ## Field choice
//!
//! Every field is `Option<String>` so:
//! - `Default::default()` is a valid anonymous actor (no allocation).
//! - Partial identity (e.g. agent known via hook payload, user not yet
//!   authenticated) is representable.
//! - Serialised payloads omit absent fields rather than emitting `null`
//!   noise — see the `#[serde(skip_serializing_if = "Option::is_none")]`
//!   attributes.

use serde::{Deserialize, Serialize};

/// Identity of the actor that triggered an operation.
///
/// Populated by the auth middleware. Pure data — no I/O, no resolution
/// logic lives here. Cloneable + cheap; threaded through request handlers
/// via `Extension<ActorContext>` and forwarded into the writer actor as
/// part of the write command so attribution and data land atomically.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ActorContext {
    /// Which client triggered the write — `claude-code`, `codex`,
    /// `opencode`, `gemini-cli`, `cursor`, `cli`, `hook`, … Sourced from
    /// the MCP client info or the hook payload's `agent` field.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent: Option<String>,
    /// Human-readable username (e.g. `boss`, `alice`). The stable
    /// attribution key surfaced in the audit log + page frontmatter
    /// `last_modified_by`. `None` = anonymous.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// Optional display name (e.g. `Alice Smith`). For UIs that want to
    /// show "Last edited by Alice Smith" instead of `alice`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Optional email. Surfaced alongside the username in the web UI +
    /// `/api/v1` responses so reviewers know who to ask about a page.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    /// Session id from the agent (when known via the hook payload).
    /// Lets per-session timelines reconstruct "what did this agent do
    /// in this session" against `audit_log` + `observations`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    /// Issuer for the external-auth-proxy rung's OIDC subject. A subject is
    /// unique only within its issuer, so proxy authentication accepts these
    /// two fields only as a pair.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub issuer: Option<String>,
    /// OIDC `sub` claim asserted by an external authenticating proxy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sub: Option<String>,
    /// Reserved for the external-auth-proxy rung: the DCR client UUID
    /// identifying which install of an agent made the request. Same
    /// forward-compat rationale as [`Self::sub`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub client: Option<String>,
}

/// The user this request is authorized *as*, for per-repository grants.
///
/// Distinct from the bare `UserId` the middleware also stamps, and the
/// distinction is the whole point. `UserId` answers "who wrote this" and is
/// always present for a database user, because attribution must not depend on
/// a policy setting. This answers "whose access applies", and is stamped for
/// every database user — never for the root token, which authenticates from
/// configuration and is authorized above per-project granularity, and never on
/// an install with no database users, where there is nobody to tell apart.
///
/// Every guard reads a missing `AuthorizedViewer` as "no per-project check
/// applies". A present one is checked against the project's access mode: an
/// `open` project admits every viewer, which is how every project behaves
/// until an operator restricts it, so stamping every user changes nothing on
/// upgrade.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AuthorizedViewer(pub crate::UserId);

/// Marks a request that authenticated with the legacy browser credential: the
/// root bearer sent as HTTP Basic, or an `ai_memory_auth` cookie an older build
/// set. That path exists only until human auth is set up and admits GET only,
/// so a page served through it can tell the viewer that a change it would post
/// cannot succeed, instead of offering a control that always fails.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LegacyBrowserAuth;

impl AuthorizedViewer {
    /// The user id inside.
    #[must_use]
    pub const fn user(self) -> crate::UserId {
        self.0
    }
}

/// Authorization tier the auth middleware resolved this request to.
///
/// Identity ([`ActorContext`]) carries *who* the request is from;
/// `AuthLevel` carries *what they're allowed to do*. The two are
/// distinct so a handler can guard on "must be root" without also
/// having to inspect or compare username strings against config.
///
/// Available as `Extension<AuthLevel>` on every request after the
/// auth middleware runs. In multi-user mode every `/admin/*` route
/// checks this against [`AuthLevel::Root`] and returns 403 for
/// `User` / 401 for `Anonymous`; normal DB users are allowed on the
/// MCP and read-only API surfaces where writes are attributed to them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuthLevel {
    /// Rung 0: no auth configured. Read-mostly setups; root-only
    /// routes refuse this tier (no root → no user management).
    Anonymous,
    /// Rung 1: authenticated as the configured root user.
    /// Allowed everywhere including user-management endpoints.
    Root,
    /// Rung 2: authenticated via the `users` table.
    /// Allowed on regular routes (write_page, query, etc.) but
    /// refused on root-only admin routes.
    User,
}

/// Coarse-grained capabilities guarded by the auth layer.
///
/// This is intentionally smaller than a role/RBAC system: ai-memory v1 is
/// single-tenant, so the policy surface is "normal read/write is allowed"
/// versus "this operational action needs root". Keeping that decision in one
/// enum prevents future handlers from open-coding subtly different checks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Capability {
    /// Operational `/admin/*` routes. In multi-user mode these are root-only;
    /// in single-user/no-auth mode historical behavior is preserved.
    Admin,
    /// User lifecycle routes (`/admin/users*`). These are root-only even when
    /// multi-user mode is not fully configured.
    UserManagement,
    /// Regular read surfaces (MCP/query/API/wiki reads).
    NormalRead,
    /// Regular write surfaces that attribute to the resolved actor.
    NormalWrite,
    /// Loop-prevention admission-chain skip header.
    SkipAdmissionChain,
}

/// Authorization failure independent of any HTTP framework.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuthzError {
    /// The caller must authenticate before the capability can be used.
    AuthenticationRequired(&'static str),
    /// The caller authenticated, but the capability is root-only.
    Forbidden(&'static str),
}

impl AuthzError {
    /// Human-readable policy message for HTTP/MCP responses.
    #[must_use]
    pub fn message(self) -> &'static str {
        match self {
            AuthzError::AuthenticationRequired(msg) | AuthzError::Forbidden(msg) => msg,
        }
    }

    /// True when the response should be an authentication challenge (HTTP 401).
    #[must_use]
    pub fn is_authentication_required(self) -> bool {
        matches!(self, AuthzError::AuthenticationRequired(_))
    }
}

impl AuthLevel {
    /// Check whether this auth tier can use `capability`.
    ///
    /// `distinguishes_operators` is true when the deployment has DB users or a
    /// configured trusted identity proxy. Operational admin routes keep their
    /// historical bootstrap behavior until either mode is active, while user
    /// management is always root-only.
    pub fn authorize(
        self,
        capability: Capability,
        distinguishes_operators: bool,
    ) -> Result<(), AuthzError> {
        match capability {
            Capability::NormalRead | Capability::NormalWrite => Ok(()),
            Capability::SkipAdmissionChain => match self {
                AuthLevel::User => {
                    Err(AuthzError::Forbidden("admission webhook skip is root-only"))
                }
                AuthLevel::Anonymous | AuthLevel::Root => Ok(()),
            },
            Capability::Admin if !distinguishes_operators => Ok(()),
            Capability::Admin => self.require_root(
                "admin operation requires authentication in multi-user mode",
                "admin operation is root-only in multi-user mode",
            ),
            Capability::UserManagement => self.require_root(
                "user management requires authentication",
                "user management is root-only",
            ),
        }
    }

    fn require_root(
        self,
        anonymous_message: &'static str,
        user_message: &'static str,
    ) -> Result<(), AuthzError> {
        match self {
            AuthLevel::Root => Ok(()),
            AuthLevel::Anonymous => Err(AuthzError::AuthenticationRequired(anonymous_message)),
            AuthLevel::User => Err(AuthzError::Forbidden(user_message)),
        }
    }
}

/// Canonical name of the admission-chain loop-prevention header.
pub const SKIP_ADMISSION_CHAIN_HEADER: &str = "x-memory-skip-admission-chain";

/// Parse the admission-chain skip list from the raw
/// `X-Memory-Skip-Admission-Chain` header value (comma-separated webhook
/// names). Entries are trimmed and empty tokens dropped, so `"a, ,b,"` →
/// `["a", "b"]`; `None` yields an empty list.
#[must_use]
pub fn parse_skip_admission_chain(raw: Option<&str>) -> Vec<String> {
    raw.map(|value| {
        value
            .split(',')
            .map(str::trim)
            .filter(|token| !token.is_empty())
            .map(str::to_string)
            .collect()
    })
    .unwrap_or_default()
}

/// The same list, but honoured only for a caller that holds
/// [`Capability::SkipAdmissionChain`].
///
/// The header is client-controlled, so a regular DB user must not be able to
/// set it and walk past a `reject`-policy admission webhook. Every transport
/// that forwards the skip list (MCP tools, admin routes, hook ingress) goes
/// through this one predicate rather than re-deriving the tier rule.
#[must_use]
pub fn skip_admission_chain_for(level: AuthLevel, raw: Option<&str>) -> Vec<String> {
    if level
        .authorize(Capability::SkipAdmissionChain, true)
        .is_ok()
    {
        parse_skip_admission_chain(raw)
    } else {
        Vec::new()
    }
}

impl ActorContext {
    /// `true` if at least one identity field is set.
    ///
    /// Cheap predicate for "should we record attribution?" — when this
    /// returns `false` the writer can skip the audit-log author_id
    /// stamp (saves a column write per operation) and emit pages without
    /// the `last_modified_by` frontmatter block.
    #[must_use]
    pub fn has_any(&self) -> bool {
        self.agent.is_some()
            || self.user.is_some()
            || self.name.is_some()
            || self.email.is_some()
            || self.session_id.is_some()
            || self.issuer.is_some()
            || self.sub.is_some()
            || self.client.is_some()
    }

    /// Construct the canonical anonymous actor — same as
    /// [`Default::default`], but more readable at call sites where the
    /// intent is "this is an anonymous request".
    #[must_use]
    pub fn anonymous() -> Self {
        Self::default()
    }

    /// Does this actor name a specific human, and under what key?
    ///
    /// Every ownership decision in the engine — which rows a caller may read,
    /// which name a new row is stamped with — goes through here rather than
    /// reaching for [`Self::user`] directly, because "identified" is not the
    /// same question as "has a username". An ingress that terminates OIDC and
    /// forwards only the issuer and subject claims asserts no
    /// `preferred_username`; the auth middleware already resolves that request
    /// to `AuthLevel::User`, so a per-site `.user` check would call the same
    /// request identified for authorization and anonymous for ownership — and
    /// the operator would stop seeing rows they had just written.
    ///
    /// The key is *qualified* — [`IdentityKey::Subject`] or
    /// [`IdentityKey::User`], never a bare string — because the two name
    /// spaces are populated by different parties. A username is chosen by a
    /// person; an OIDC subject is issued by an IdP. Stored raw in one TEXT
    /// column, a username equal to somebody else's subject would silently
    /// share that person's rows. Qualification makes the collision
    /// unrepresentable rather than unlikely.
    ///
    /// An `(issuer, sub)` pair wins whenever both fields are present. OIDC pins
    /// this ordering: the spec defines that pair as the stable identifier and
    /// explicitly forbids relying on `preferred_username` for identity. It is
    /// also the direction that stays stable through the common upgrade — an
    /// ingress that forwarded only `sub` and later starts forwarding a
    /// username keeps the same key. The reverse upgrade (username-only, later
    /// adding the OIDC pair) re-buckets once, at the moment the deployment starts
    /// asserting the stronger identifier. Trusted-proxy ingress requires the
    /// complete issuer/subject pair and rejects either field on its own.
    ///
    /// Blank and whitespace-only values name nobody. A partial OIDC pair is
    /// deliberately not an identity; trusted-proxy ingress rejects it.
    #[must_use]
    pub fn identity_key(&self) -> Option<IdentityKey> {
        let trimmed = |v: &Option<String>| {
            v.as_deref()
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_owned)
        };
        if let (Some(issuer), Some(subject)) = (trimmed(&self.issuer), trimmed(&self.sub)) {
            return Some(IdentityKey::Subject { issuer, subject });
        }
        trimmed(&self.user).map(IdentityKey::User)
    }
}

/// A qualified operator identity — the one value ownership is keyed on.
///
/// The variant is part of the identity: a username and an OIDC subject with
/// equal text are different operators. Everything that persists or compares
/// an identity goes through [`Self::storage_key`], so call sites cannot flatten
/// the namespaces or discard an OIDC issuer.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum IdentityKey {
    /// Named by the OIDC issuer and subject pair. `sub` alone is not globally
    /// unique when a proxy accepts tokens from more than one issuer.
    Subject {
        /// Exact OIDC `iss` value validated by the proxy.
        issuer: String,
        /// Exact OIDC `sub` value validated by the proxy.
        subject: String,
    },
    /// Named by an asserted or configured username. Usernames are display
    /// names in OIDC terms — present, human-readable, and explicitly not
    /// guaranteed stable — so this variant keys a caller only when no
    /// subject was asserted.
    User(String),
}

impl IdentityKey {
    /// Whether this value satisfies the same non-blank, trimmed invariants as
    /// [`ActorContext::identity_key`].
    ///
    /// The enum is public, so storage boundaries use this check before
    /// accepting a directly constructed value.
    #[must_use]
    pub fn is_valid(&self) -> bool {
        self.to_actor_context().identity_key().as_ref() == Some(self)
    }

    /// The TEXT form used for in-memory routing and future owner columns:
    /// `oidc:<issuer-byte-length>:<issuer><subject>` or `user:<name>`.
    ///
    /// Length-prefixing the issuer makes the OIDC form unambiguous without
    /// constraining either value or adding an encoding dependency.
    #[must_use]
    pub fn storage_key(&self) -> String {
        match self {
            Self::Subject { issuer, subject } => {
                format!("oidc:{}:{issuer}{subject}", issuer.len())
            }
            Self::User(user) => format!("user:{user}"),
        }
    }

    /// A bounded, filesystem-safe namespace component for operator-owned data.
    ///
    /// Readable usernames are retained when they are short, contain only
    /// lowercase path/GLOB-safe ASCII, and do not end in a period. Mixed-case
    /// and all other usernames, plus every OIDC identity, use a deterministic
    /// UUIDv5 derived from the fully qualified storage key. This avoids
    /// platform pathname equivalences between distinct identities.
    #[must_use]
    pub fn path_segment(&self) -> String {
        match self {
            Self::User(user)
                if user.len() <= 64
                    && !user.is_empty()
                    && !user.ends_with('.')
                    && user.bytes().all(|byte| {
                        byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"._-".contains(&byte)
                    }) =>
            {
                format!("u-{user}")
            }
            Self::User(_) => format!(
                "uh-{}",
                uuid::Uuid::new_v5(&uuid::Uuid::NAMESPACE_URL, self.storage_key().as_bytes())
                    .as_simple()
            ),
            Self::Subject { .. } => format!(
                "o-{}",
                uuid::Uuid::new_v5(&uuid::Uuid::NAMESPACE_URL, self.storage_key().as_bytes())
                    .as_simple()
            ),
        }
    }

    /// Parse the qualified TEXT form produced by [`Self::storage_key`].
    ///
    /// Stored owners sometimes need to be turned back into a typed actor. The
    /// OIDC form uses the encoded issuer byte length, so neither colons nor
    /// non-ASCII text in the issuer or subject make the split ambiguous.
    #[must_use]
    pub fn from_storage_key(key: &str) -> Option<Self> {
        let parsed = if let Some(user) = key.strip_prefix("user:") {
            Self::User(user.to_owned())
        } else {
            let encoded = key.strip_prefix("oidc:")?;
            let (issuer_len, remainder) = encoded.split_once(':')?;
            let issuer_len = issuer_len.parse::<usize>().ok()?;
            let issuer = remainder.get(..issuer_len)?;
            let subject = remainder.get(issuer_len..)?;
            Self::Subject {
                issuer: issuer.to_owned(),
                subject: subject.to_owned(),
            }
        };
        // Production keys originate in `ActorContext::identity_key`, which
        // trims and rejects blanks. Enforce the same invariant on persisted
        // data so a corrupt `user:` / partial OIDC key cannot become a new
        // ownership bucket when a session is finalized.
        parsed.is_valid().then_some(parsed)
    }

    /// Build an actor that round-trips through [`ActorContext::identity_key`].
    #[must_use]
    pub fn to_actor_context(&self) -> ActorContext {
        match self {
            Self::Subject { issuer, subject } => ActorContext {
                issuer: Some(issuer.clone()),
                sub: Some(subject.clone()),
                ..ActorContext::default()
            },
            Self::User(user) => ActorContext {
                user: Some(user.clone()),
                ..ActorContext::default()
            },
        }
    }
}

/// Which owned rows a caller is allowed to see or act on.
///
/// A row whose owner is `None` is shared: it predates ownership, was written
/// without an actor, or was deliberately published to the whole project.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OwnerFilter {
    /// The caller's own rows plus shared rows. The value is a qualified
    /// [`IdentityKey::storage_key`].
    User(String),
    /// A caller with no identity: shared rows only.
    Unattributed,
    /// Explicit cross-owner access for authorized recovery paths.
    Any,
}

impl OwnerFilter {
    /// Build the owner filter from the canonical actor identity.
    #[must_use]
    pub fn for_actor_context(actor: &ActorContext) -> Self {
        actor.identity_key().map_or(Self::Unattributed, |identity| {
            Self::User(identity.storage_key())
        })
    }

    /// Whether a stored owner passes this filter.
    #[must_use]
    pub fn admits(&self, owner: Option<&str>) -> bool {
        match (self, owner) {
            (_, None) | (Self::Any, _) => true,
            (Self::User(me), Some(owner)) => me == owner,
            (Self::Unattributed, Some(_)) => false,
        }
    }
}

/// Derive the owner stored by an operator-distinguishing deployment.
///
/// A single-operator server leaves rows shared even when its HTTP root has a
/// username, because the same operator's stdio transport carries no actor.
#[must_use]
pub fn owner_identity(
    identity: Option<&IdentityKey>,
    distinguishes_operators: bool,
) -> Option<IdentityKey> {
    distinguishes_operators
        .then(|| identity.filter(|identity| identity.is_valid()).cloned())
        .flatten()
}

/// Derive the qualified owner string stored by an operator-distinguishing
/// deployment.
#[must_use]
pub fn owner_stamp(
    identity: Option<&IdentityKey>,
    distinguishes_operators: bool,
) -> Option<String> {
    owner_identity(identity, distinguishes_operators).map(|identity| identity.storage_key())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn default_is_anonymous() {
        let a = ActorContext::default();
        assert!(!a.has_any(), "default actor must be fully anonymous");
        assert_eq!(a, ActorContext::anonymous());
    }

    #[test]
    fn admin_capability_preserves_single_user_mode() {
        for level in [AuthLevel::Anonymous, AuthLevel::Root, AuthLevel::User] {
            assert_eq!(level.authorize(Capability::Admin, false), Ok(()));
        }
    }

    #[test]
    fn admin_capability_is_root_only_in_multi_user_mode() {
        assert_eq!(AuthLevel::Root.authorize(Capability::Admin, true), Ok(()));
        assert!(matches!(
            AuthLevel::Anonymous.authorize(Capability::Admin, true),
            Err(AuthzError::AuthenticationRequired(
                "admin operation requires authentication in multi-user mode"
            ))
        ));
        assert!(matches!(
            AuthLevel::User.authorize(Capability::Admin, true),
            Err(AuthzError::Forbidden(
                "admin operation is root-only in multi-user mode"
            ))
        ));
    }

    #[test]
    fn user_management_is_always_root_only() {
        assert_eq!(
            AuthLevel::Root.authorize(Capability::UserManagement, false),
            Ok(())
        );
        assert_eq!(
            AuthLevel::Root.authorize(Capability::UserManagement, true),
            Ok(())
        );
        assert!(matches!(
            AuthLevel::Anonymous.authorize(Capability::UserManagement, false),
            Err(AuthzError::AuthenticationRequired(
                "user management requires authentication"
            ))
        ));
        assert!(matches!(
            AuthLevel::User.authorize(Capability::UserManagement, true),
            Err(AuthzError::Forbidden("user management is root-only"))
        ));
    }

    #[test]
    fn skip_admission_chain_rejects_db_users() {
        assert_eq!(
            AuthLevel::Root.authorize(Capability::SkipAdmissionChain, true),
            Ok(())
        );
        assert_eq!(
            AuthLevel::Anonymous.authorize(Capability::SkipAdmissionChain, true),
            Ok(())
        );
        assert!(matches!(
            AuthLevel::User.authorize(Capability::SkipAdmissionChain, true),
            Err(AuthzError::Forbidden("admission webhook skip is root-only"))
        ));
    }

    #[test]
    fn skip_admission_chain_parses_csv_and_honours_the_tier_rule() {
        assert_eq!(
            parse_skip_admission_chain(Some("a, ,b,")),
            vec!["a".to_string(), "b".to_string()]
        );
        assert!(parse_skip_admission_chain(None).is_empty());
        for level in [AuthLevel::Root, AuthLevel::Anonymous] {
            assert_eq!(
                skip_admission_chain_for(level, Some("mirror")),
                vec!["mirror".to_string()],
                "{level:?} may skip a webhook it re-entered from",
            );
        }
        assert!(
            skip_admission_chain_for(AuthLevel::User, Some("mirror")).is_empty(),
            "a DB user must not bypass a reject-policy webhook via a header",
        );
    }

    #[test]
    fn has_any_truth_table() {
        // Each field individually flips has_any() to true. Catches an
        // accidental omission if someone adds a new field and forgets
        // to update the predicate.
        let mut a = ActorContext::default();
        assert!(!a.has_any());

        a.agent = Some("claude-code".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.user = Some("alice".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.name = Some("Alice Smith".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.email = Some("alice@home".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.session_id = Some("s-1".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.issuer = Some("https://idp.example".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.sub = Some("8f3a".into());
        assert!(a.has_any());
        a = ActorContext::default();

        a.client = Some("72836f52".into());
        assert!(a.has_any());
    }

    /// OIDC identity is the issuer and subject pair, never the subject alone.
    #[test]
    fn identity_key_accepts_oidc_pair_without_username() {
        let oidc = ActorContext {
            issuer: Some("https://idp.example".into()),
            sub: Some("oidc-subject-123".into()),
            ..ActorContext::default()
        };
        assert_eq!(
            oidc.identity_key(),
            Some(IdentityKey::Subject {
                issuer: "https://idp.example".into(),
                subject: "oidc-subject-123".into(),
            })
        );
    }

    /// The stable OIDC pair outranks the display username.
    #[test]
    fn identity_key_prefers_oidc_pair_over_user() {
        let both = ActorContext {
            user: Some("alice".into()),
            issuer: Some("https://idp.example".into()),
            sub: Some("oidc-subject-123".into()),
            ..ActorContext::default()
        };
        assert_eq!(
            both.identity_key(),
            Some(IdentityKey::Subject {
                issuer: "https://idp.example".into(),
                subject: "oidc-subject-123".into(),
            })
        );
    }

    #[test]
    fn identity_storage_keys_keep_namespaces_and_issuers_distinct() {
        let by_name = IdentityKey::User("alice".into());
        let issuer_a = IdentityKey::Subject {
            issuer: "https://idp-a.example".into(),
            subject: "alice".into(),
        };
        let issuer_b = IdentityKey::Subject {
            issuer: "https://idp-b.example".into(),
            subject: "alice".into(),
        };
        assert_ne!(by_name.storage_key(), issuer_a.storage_key());
        assert_ne!(issuer_a.storage_key(), issuer_b.storage_key());
        assert_ne!(by_name.path_segment(), issuer_a.path_segment());
        assert_ne!(issuer_a.path_segment(), issuer_b.path_segment());
        let names_filter = OwnerFilter::User(by_name.storage_key());
        assert!(!names_filter.admits(Some(&issuer_a.storage_key())));
    }

    #[test]
    fn identity_path_segments_are_bounded_and_path_safe() {
        let identities = [
            IdentityKey::User("alice".into()),
            IdentityKey::User("../alice[*]".repeat(100)),
            IdentityKey::Subject {
                issuer: "https://idp.example/".repeat(100),
                subject: "../../subject[*]".repeat(100),
            },
        ];
        assert_eq!(identities[0].path_segment(), "u-alice");
        for identity in identities {
            let segment = identity.path_segment();
            assert!(segment.len() <= 67, "{segment}");
            assert!(
                segment
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte)),
                "{segment}"
            );
            assert_eq!(segment, identity.path_segment());
        }
    }

    #[test]
    fn username_path_segments_remain_distinct_under_ascii_case_folding() {
        let lowercase = IdentityKey::User("alice".into()).path_segment();
        let titlecase = IdentityKey::User("Alice".into()).path_segment();
        let uppercase = IdentityKey::User("ALICE".into()).path_segment();
        let trailing_dot = IdentityKey::User("alice.".into()).path_segment();

        assert_eq!(lowercase, "u-alice");
        assert!(titlecase.starts_with("uh-"), "{titlecase}");
        assert!(uppercase.starts_with("uh-"), "{uppercase}");
        assert!(trailing_dot.starts_with("uh-"), "{trailing_dot}");
        assert_ne!(
            lowercase.to_ascii_lowercase(),
            titlecase.to_ascii_lowercase()
        );
        assert_ne!(
            lowercase.to_ascii_lowercase(),
            uppercase.to_ascii_lowercase()
        );
        assert_ne!(
            titlecase.to_ascii_lowercase(),
            uppercase.to_ascii_lowercase()
        );
        assert_ne!(
            lowercase.to_ascii_lowercase(),
            trailing_dot.trim_end_matches('.').to_ascii_lowercase()
        );
    }

    #[test]
    fn storage_key_round_trips_to_actor_without_losing_issuer() {
        for key in [
            IdentityKey::User("alice".into()),
            IdentityKey::User("oidc:4:idpalice".into()),
            IdentityKey::Subject {
                issuer: "https://idp.example/é".into(),
                subject: "subject:42".into(),
            },
        ] {
            assert_eq!(
                IdentityKey::from_storage_key(&key.storage_key()),
                Some(key.clone())
            );
            assert_eq!(key.to_actor_context().identity_key(), Some(key));
        }
        for malformed in [
            "",
            "alice",
            "user:",
            "user:   ",
            "user: alice ",
            "oidc:",
            "oidc:0:subject",
            "oidc:3:idp",
            "oidc:3: idsubject",
            "oidc:x:idpsub",
            "oidc:99:idpsub",
            "oidc:1:ésub",
        ] {
            assert_eq!(
                IdentityKey::from_storage_key(malformed),
                None,
                "{malformed}"
            );
        }
    }

    #[test]
    fn owner_stamp_requires_identity_and_operator_distinction() {
        let key = IdentityKey::Subject {
            issuer: "https://idp.example".into(),
            subject: "oidc-subject-123".into(),
        };
        assert_eq!(owner_identity(Some(&key), false), None);
        assert_eq!(owner_identity(None, true), None);
        assert_eq!(owner_identity(Some(&key), true), Some(key.clone()));
        assert_eq!(
            owner_identity(Some(&IdentityKey::User(" ".into())), true),
            None
        );
        assert_eq!(owner_stamp(Some(&key), false), None);
        assert_eq!(owner_stamp(None, true), None);
        assert_eq!(owner_stamp(Some(&key), true), Some(key.storage_key()));
    }

    #[test]
    fn owner_filter_admit_matrix() {
        let alice = OwnerFilter::for_actor_context(&ActorContext {
            user: Some("alice".into()),
            ..ActorContext::default()
        });
        let owned = IdentityKey::User("alice".into()).storage_key();
        let other = IdentityKey::User("bob".into()).storage_key();

        for filter in [&alice, &OwnerFilter::Unattributed, &OwnerFilter::Any] {
            assert!(filter.admits(None));
        }
        assert!(alice.admits(Some(&owned)));
        assert!(!alice.admits(Some(&other)));
        assert!(!OwnerFilter::Unattributed.admits(Some(&owned)));
        assert!(OwnerFilter::Any.admits(Some(&other)));
    }

    /// Naming nobody stays naming nobody: an agent/session-only actor carries
    /// transport detail, not identity, and blanks are not names.
    #[test]
    fn identity_key_is_none_without_a_named_human() {
        assert_eq!(ActorContext::anonymous().identity_key(), None);
        let transport_only = ActorContext {
            agent: Some("claude-code".into()),
            session_id: Some("s-1".into()),
            client: Some("72836f52".into()),
            ..ActorContext::default()
        };
        assert_eq!(transport_only.identity_key(), None);
        let blank = ActorContext {
            user: Some("   ".into()),
            issuer: Some("\n".into()),
            sub: Some("\t".into()),
            ..ActorContext::default()
        };
        assert_eq!(blank.identity_key(), None);
    }

    #[test]
    fn partial_oidc_pair_does_not_override_username() {
        let actor = ActorContext {
            user: Some("alice".into()),
            sub: Some("oidc-subject-123".into()),
            ..ActorContext::default()
        };
        assert_eq!(
            actor.identity_key(),
            Some(IdentityKey::User("alice".into()))
        );
        let sub_only = ActorContext {
            sub: Some("oidc-subject-123".into()),
            ..ActorContext::default()
        };
        assert_eq!(sub_only.identity_key(), None);
    }

    #[test]
    fn anonymous_serialises_to_empty_object() {
        // Every absent field is omitted (not `null`) — keeps the
        // webhook payload + /api/v1 response shape lean.
        let json = serde_json::to_string(&ActorContext::default()).unwrap();
        assert_eq!(json, "{}");
    }

    #[test]
    fn partial_actor_serialises_only_set_fields() {
        let a = ActorContext {
            user: Some("boss".into()),
            email: Some("[email protected]".into()),
            ..ActorContext::default()
        };
        let json = serde_json::to_string(&a).unwrap();
        // Stable field order is set by the struct definition; serde
        // emits fields in declaration order.
        assert_eq!(json, r#"{"user":"boss","email":"[email protected]"}"#);
    }

    #[test]
    fn round_trip_preserves_all_set_fields() {
        let original = ActorContext {
            agent: Some("codex".into()),
            user: Some("alice".into()),
            name: Some("Alice Smith".into()),
            email: Some("alice@home".into()),
            session_id: Some("019e6d".into()),
            issuer: Some("https://idp.example".into()),
            sub: Some("8f3a-uuid".into()),
            client: Some("72836f52-uuid".into()),
        };
        let json = serde_json::to_string(&original).unwrap();
        let parsed: ActorContext = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, original);
    }

    #[test]
    fn missing_fields_deserialise_to_none() {
        // Forward-compat: a payload from an older sender that omits
        // newly-added fields still deserialises cleanly.
        let parsed: ActorContext = serde_json::from_str(r#"{"user":"boss"}"#).unwrap();
        assert_eq!(parsed.user.as_deref(), Some("boss"));
        assert!(parsed.agent.is_none());
        assert!(parsed.email.is_none());
        assert!(parsed.sub.is_none());
    }

    #[test]
    fn explicit_null_fields_deserialise_to_none() {
        // Some senders (older webhooks, hand-written JSON) emit `null`
        // for absent fields instead of omitting them. Both forms must
        // round-trip to the same anonymous actor.
        let parsed: ActorContext = serde_json::from_str(r#"{"user":null,"agent":null}"#).unwrap();
        assert!(!parsed.has_any());
    }
}