Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(core): P1.1 identity foundation — UserId + ActorContext
AkitaOnRailsa3cc47d6c5ad
diff --git a/crates/ai-memory-core/src/actor.rs b/crates/ai-memory-core/src/actor.rsnew file mode 100644index 00000000..082877e0--- /dev/null+++ b/crates/ai-memory-core/src/actor.rs@@ -0,0 +1,218 @@+//! Per-request actor identity — who triggered an operation.+//!+//! ai-memory's data is single-tenant (no RBAC; everyone with auth sees the+//! same pages), but writes can be **attributed** to the user who made them.+//! [`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+//! `users.token_hash` row. Middleware fills the actor from the row.+//! 4. **External auth proxy** — operator runs an auth sidecar that injects+//! pre-validated `X-Memory-Actor-*` headers; the middleware overlays+//! them onto the rung 2/3 actor. (Scaffolding only in v1 — the `sub`+//! and `client` fields below exist for this use case and the eventual+//! admission webhook chain payload contract.)+//!+//! ## 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>,+ /// Reserved for the external-auth-proxy rung: the JWT `sub` claim+ /// (stable user UUID). Kept `Option<String>` so payloads to the+ /// future admission webhook chain stay forward-compatible with the+ /// shape PR #55 documents — we don't fill it from rungs 0-3.+ #[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>,+}++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.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()+ }+}++#[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 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.sub = Some("8f3a".into());+ assert!(a.has_any());+ a = ActorContext::default();++ a.client = Some("72836f52".into());+ assert!(a.has_any());+ }++ #[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()),+ 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());+ }+}diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rsindex 77b4813a..14dbc99f 100644--- a/crates/ai-memory-core/src/ids.rs+++ b/crates/ai-memory-core/src/ids.rs@@ -83,6 +83,7 @@ id_newtype!(pub SessionId, "Identifier for a single agent run.");id_newtype!(pub ObservationId, "Identifier for a single observation captured during a session.");id_newtype!(pub PageId, "Identifier for a single wiki page version.");id_newtype!(pub HandoffId, "Identifier for a cross-agent handoff record.");+id_newtype!(pub UserId, "Identifier for a registered user (multi-user attribution; see [`crate::actor`]).");/// Relative path of a page within the wiki tree.///diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rsindex 07054f72..631b5927 100644--- a/crates/ai-memory-core/src/lib.rs+++ b/crates/ai-memory-core/src/lib.rs@@ -6,6 +6,7 @@//! trivially unit-testable and free of platform concerns.pub mod active_project;+pub mod actor;pub mod error;pub mod handoff;pub mod ids;@@ -21,10 +22,12 @@ pub const DEFAULT_WORKSPACE_NAME: &str = "default";pub const DEFAULT_PROJECT_NAME: &str = "scratch";pub use active_project::ActiveProject;+pub use actor::ActorContext;pub use error::{MemoryError, MemoryResult};pub use handoff::{Handoff, HandoffState, NewHandoff};pub use ids::{- AgentKind, HandoffId, ObservationId, PageId, PagePath, ProjectId, SessionId, WorkspaceId,+ AgentKind, HandoffId, ObservationId, PageId, PagePath, ProjectId, SessionId, UserId,+ WorkspaceId,};pub use observation::{NewObservation, NewSession, Observation, ObservationKind};pub use page::{LinkTarget, NewPage, Page, Tier};