Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Registered-user domain types + validation.
//!
//! The storage shape lives in `ai-memory-store`; this module owns the
//! **pure types** + **input validation** that both the writer (insert
//! path) and the CLI / admin endpoint (caller path) share. Keeping the
//! rules in core means the same `MemoryError::InvalidUsername`
//! materialises whether a username is rejected by the CLI, the HTTP
//! handler, or the writer actor — one source of truth.
//!
//! ## Attribution, not RBAC
//!
//! See [`crate::actor`] for the broader rationale: ai-memory's data is
//! single-tenant by design. A `User` row records *who* a write came
//! from; it does not gate *whether* the write was allowed. Human
//! `role=root` vs `role=user` only affects web-session capabilities;
//! a native API credential always authenticates as [`crate::AuthLevel::User`].
//!
//! ## Credential classes (referenced here, implemented in `ai-memory-store`)
//!
//! Human passwords are Argon2id PHC strings on `users.password_hash` and
//! never authenticate as Bearer. Native machine keys are 256-bit secrets
//! with prefix [`NATIVE_API_KEY_PREFIX`]; the store keeps
//! `SHA-256(token || ":" || pepper)` in `api_credentials`. Web sessions
//! use prefix [`SESSION_SECRET_PREFIX`] and store only SHA-256 of the
//! secret (no pepper). See `ai_memory_store::users` / `api_credentials`
//! / `web_sessions`.
use serde::{Deserialize, Serialize};
use crate::{ApiCredentialId, MemoryError, UserId};
/// Web-session secret prefix. A human password that equals this prefix
/// is rejected so a leaked session cookie cannot be reused as a password.
pub const SESSION_SECRET_PREFIX: &str = "ams_";
/// Native engine-issued API key prefix (`aim_…`). Distinct from the
/// external `amk_` keys issued by mcp-auth.
pub const NATIVE_API_KEY_PREFIX: &str = "aim_";
/// External mcp-auth consumer-key prefix. Human passwords must not
/// impersonate this class either.
pub const EXTERNAL_API_KEY_PREFIX: &str = "amk_";
/// Minimum UTF-8 byte length of a human password.
pub const MIN_HUMAN_PASSWORD_BYTES: usize = 12;
/// Maximum UTF-8 byte length of a human password.
pub const MAX_HUMAN_PASSWORD_BYTES: usize = 1024;
/// Maximum username length. Anything longer is a misconfiguration; the
/// engine, CLI, and web UI all assume a small username fits in a single
/// terminal column / table cell.
pub const MAX_USERNAME_LEN: usize = 64;
/// Maximum email length per RFC 5321 §4.5.3.1.3 (path length).
pub const MAX_EMAIL_LEN: usize = 254;
/// Human role stored on `users.role`. Only two values exist; a native
/// API credential never inherits Root from this field.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UserRole {
/// Console operator. A web session for this role is
/// [`crate::AuthLevel::Root`].
Root,
/// Default human role. Web sessions and native API keys are
/// [`crate::AuthLevel::User`].
#[default]
User,
}
impl UserRole {
/// Wire / SQL value.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Root => "root",
Self::User => "user",
}
}
/// Parse a stored `users.role` value.
///
/// # Errors
/// Returns [`MemoryError::MalformedRecord`] for any other string.
pub fn parse(value: &str) -> Result<Self, MemoryError> {
match value {
"root" => Ok(Self::Root),
"user" => Ok(Self::User),
other => Err(MemoryError::MalformedRecord(format!(
"unknown user role {other:?}"
))),
}
}
}
/// A registered user as stored. `id` is the UUIDv7 primary key; the
/// other fields mirror the public `users` columns. Password hashes,
/// session hashes, CSRF hashes, and API-key hashes never appear here.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct User {
/// Stable identity. Used by `audit_log.author_id` and
/// `pages.author_id` foreign keys.
pub id: UserId,
/// Validated username (see [`validate_username`]).
pub username: String,
/// Optional display name for "Last edited by Alice Smith" style UIs.
pub name: Option<String>,
/// Optional email; validated by [`validate_email`] before insert.
pub email: Option<String>,
/// Microseconds since epoch — V01 convention.
pub created_at: i64,
/// Microseconds since epoch; `None` until the first authenticated
/// request from this user. Updated fire-and-forget per request.
pub last_seen_at: Option<i64>,
/// Human role. Native API credentials ignore this for AuthLevel.
pub role: UserRole,
/// The next web login must change the password before `/admin` or
/// `/api/v1` become available.
pub must_change_password: bool,
/// Microseconds since epoch; `None` means human login is enabled.
pub disabled_at: Option<i64>,
/// `true` when `users.password_hash` is populated. Token-only
/// brownfield rows are `false` ("API only") until reset-password.
pub has_password: bool,
}
impl User {
/// `true` when human login is currently allowed.
#[must_use]
pub fn is_human_enabled(&self) -> bool {
self.disabled_at.is_none() && self.has_password
}
}
/// Public metadata for one native API credential. The authenticating
/// hash is never serialised.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApiCredential {
/// Stable credential id. Brownfield copies use the parent `user_id`.
pub id: ApiCredentialId,
/// Owning human (or brownfield) identity.
pub user_id: UserId,
/// Operator-supplied label.
pub label: String,
/// Optional non-authenticating preview (e.g. last four of `aim_…`).
#[serde(skip_serializing_if = "Option::is_none")]
pub preview: Option<String>,
/// Microseconds since epoch.
pub created_at: i64,
/// Microseconds since epoch; `None` until first use.
#[serde(skip_serializing_if = "Option::is_none")]
pub last_used_at: Option<i64>,
/// Optional absolute expiry.
#[serde(skip_serializing_if = "Option::is_none")]
pub expires_at: Option<i64>,
/// Microseconds since epoch when revoked; `None` means active.
#[serde(skip_serializing_if = "Option::is_none")]
pub revoked_at: Option<i64>,
}
/// Pre-insert shape for a new user. Carries the inputs the caller
/// (CLI / admin endpoint) collected; the actual token generation +
/// hashing lives in `ai-memory-store::users` since it owns the
/// per-server pepper.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NewUser {
/// Required. Will be trimmed + validated; rejected if empty after
/// trim, longer than [`MAX_USERNAME_LEN`], or contains whitespace /
/// control characters / common separator chars.
pub username: String,
/// Optional display name. Trimmed; empty string is normalised to
/// `None` so the DB doesn't store distinct `""` and `NULL`.
pub name: Option<String>,
/// Optional email. Trimmed + lowercased + validated by
/// [`validate_email`]; empty string is normalised to `None`.
pub email: Option<String>,
}
impl NewUser {
/// In-place validate + normalise. Returns the same error kinds the
/// CLI and admin endpoint surface to the operator.
///
/// # Errors
/// - [`MemoryError::InvalidUsername`] when the username is empty
/// after trim, too long, or contains forbidden characters.
/// - [`MemoryError::InvalidEmail`] when an email is supplied but
/// fails the basic format check.
pub fn validate(&mut self) -> Result<(), MemoryError> {
self.username = self.username.trim().to_string();
validate_username(&self.username)?;
if let Some(name) = self.name.as_mut() {
*name = name.trim().to_string();
}
if self.name.as_deref() == Some("") {
self.name = None;
}
if let Some(email) = self.email.as_mut() {
*email = email.trim().to_lowercase();
}
match self.email.as_deref() {
Some("") => self.email = None,
Some(e) => validate_email(e)?,
None => {}
}
Ok(())
}
}
/// Validate a username after trim. Rules — kept minimal per the v0.8
/// design call (no complex policies, just enough to keep weird
/// characters out):
///
/// - non-empty;
/// - at most [`MAX_USERNAME_LEN`] characters (code points, not bytes);
/// - no control characters (`is_control`);
/// - no whitespace anywhere (usernames are identifiers, not free text);
/// - no common separator / quoting characters that would make CLI
/// quoting + URL embedding painful: `/ \ : ; , " ' ` `.
///
/// UTF-8 letters / digits / `.` / `-` / `_` / `@` are allowed, so
/// emails-as-usernames (`alice@home`) work for operators who want them.
///
/// # Errors
/// Returns [`MemoryError::InvalidUsername`] on any rule violation.
pub fn validate_username(s: &str) -> Result<(), MemoryError> {
if s.is_empty() {
return Err(MemoryError::InvalidUsername("empty after trim".into()));
}
let len = s.chars().count();
if len > MAX_USERNAME_LEN {
return Err(MemoryError::InvalidUsername(format!(
"{len} characters, exceeds max {MAX_USERNAME_LEN}"
)));
}
for ch in s.chars() {
if ch.is_control() {
return Err(MemoryError::InvalidUsername(format!(
"control character U+{:04X}",
ch as u32
)));
}
if ch.is_whitespace() {
return Err(MemoryError::InvalidUsername(format!(
"whitespace character {ch:?}"
)));
}
if matches!(ch, '/' | '\\' | ':' | ';' | ',' | '"' | '\'' | '`') {
return Err(MemoryError::InvalidUsername(format!(
"separator character {ch:?}"
)));
}
}
Ok(())
}
/// Basic email-format check. Intentionally permissive — operators may
/// use intranet-style addresses (`alice@home`) without a public TLD, so
/// we don't require a dot in the domain. Rules:
///
/// - at most [`MAX_EMAIL_LEN`] characters;
/// - exactly one `@`;
/// - non-empty local + non-empty domain;
/// - no whitespace anywhere;
/// - no control characters.
///
/// This is the "doesn't look obviously wrong" check, not RFC 5322
/// compliance. Quoted local parts, IP-literal domains in brackets, and
/// other rare-but-valid forms are not supported.
///
/// # Errors
/// Returns [`MemoryError::InvalidEmail`] on any rule violation.
pub fn validate_email(s: &str) -> Result<(), MemoryError> {
let len = s.chars().count();
if len > MAX_EMAIL_LEN {
return Err(MemoryError::InvalidEmail(format!(
"{len} characters, exceeds max {MAX_EMAIL_LEN}"
)));
}
for ch in s.chars() {
if ch.is_control() {
return Err(MemoryError::InvalidEmail(format!(
"control character U+{:04X}",
ch as u32
)));
}
if ch.is_whitespace() {
return Err(MemoryError::InvalidEmail(format!(
"whitespace character {ch:?}"
)));
}
}
let mut parts = s.split('@');
let local = parts.next().unwrap_or_default();
let domain = parts.next().unwrap_or_default();
if parts.next().is_some() {
return Err(MemoryError::InvalidEmail("multiple `@` characters".into()));
}
if local.is_empty() {
return Err(MemoryError::InvalidEmail("empty local part".into()));
}
if domain.is_empty() {
return Err(MemoryError::InvalidEmail("empty domain part".into()));
}
Ok(())
}
/// Validate a human password before Argon2id hashing.
///
/// Policy (AUTH-010): 12–1024 UTF-8 bytes; not a reserved credential
/// prefix ([`SESSION_SECRET_PREFIX`], [`NATIVE_API_KEY_PREFIX`],
/// [`EXTERNAL_API_KEY_PREFIX`]); not equal to `username` or any
/// configured reserved secret (recovery token, machine-root bearer,
/// actor-proxy bearer). Token-hash collision is checked by the store
/// against `api_credentials` hashes only.
///
/// Failures always use the same generic [`MemoryError::InvalidPassword`]
/// text so callers cannot distinguish which rule fired.
///
/// # Errors
/// Returns [`MemoryError::InvalidPassword`] on any policy violation.
pub fn validate_human_password(
password: &str,
username: Option<&str>,
reserved_plaintext: &[&str],
) -> Result<(), MemoryError> {
const GENERIC: &str = "does not meet policy";
let bytes = password.len();
if !(MIN_HUMAN_PASSWORD_BYTES..=MAX_HUMAN_PASSWORD_BYTES).contains(&bytes) {
return Err(MemoryError::InvalidPassword(GENERIC.into()));
}
if password.starts_with(SESSION_SECRET_PREFIX)
|| password.starts_with(NATIVE_API_KEY_PREFIX)
|| password.starts_with(EXTERNAL_API_KEY_PREFIX)
{
return Err(MemoryError::InvalidPassword(GENERIC.into()));
}
if username.is_some_and(|name| password == name) {
return Err(MemoryError::InvalidPassword(GENERIC.into()));
}
if reserved_plaintext
.iter()
.any(|secret| !secret.is_empty() && password == *secret)
{
return Err(MemoryError::InvalidPassword(GENERIC.into()));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
// ── username validation ───────────────────────────────────────
#[test]
fn username_accepts_simple() {
assert!(validate_username("alice").is_ok());
assert!(validate_username("boss").is_ok());
assert!(validate_username("user_1").is_ok());
assert!(validate_username("a.b-c").is_ok());
}
#[test]
fn username_accepts_email_style() {
// Emails-as-usernames must work for operators who want them.
assert!(validate_username("alice@home").is_ok());
assert!(validate_username("[email protected]").is_ok());
}
#[test]
fn username_accepts_utf8_letters() {
assert!(validate_username("bóss").is_ok());
assert!(validate_username("ボス").is_ok());
}
#[test]
fn username_rejects_empty() {
assert!(validate_username("").is_err());
}
#[test]
fn username_rejects_whitespace() {
for s in ["boss man", "boss\tman", "boss\nman", " boss", "boss "] {
assert!(
validate_username(s).is_err(),
"whitespace must be rejected: {s:?}"
);
}
}
#[test]
fn username_rejects_control_chars() {
assert!(validate_username("boss\x00").is_err());
assert!(validate_username("boss\x07man").is_err());
assert!(validate_username("boss\x7fman").is_err());
}
#[test]
fn username_rejects_separator_chars() {
for ch in ['/', '\\', ':', ';', ',', '"', '\'', '`'] {
let s = format!("boss{ch}man");
assert!(
validate_username(&s).is_err(),
"{ch:?} must be rejected: {s:?}"
);
}
}
#[test]
fn username_rejects_over_length() {
let too_long = "a".repeat(MAX_USERNAME_LEN + 1);
assert!(validate_username(&too_long).is_err());
let just_right = "a".repeat(MAX_USERNAME_LEN);
assert!(validate_username(&just_right).is_ok());
}
// ── email validation ──────────────────────────────────────────
#[test]
fn email_accepts_typical() {
assert!(validate_email("[email protected]").is_ok());
assert!(validate_email("[email protected]").is_ok());
assert!(validate_email("[email protected]").is_ok());
}
#[test]
fn email_accepts_intranet_no_tld() {
// Homelab users have `alice@home` setups; the basic check must
// not require a dot in the domain.
assert!(validate_email("alice@home").is_ok());
assert!(validate_email("boss@localhost").is_ok());
}
#[test]
fn email_rejects_missing_at() {
assert!(validate_email("alice.example.com").is_err());
}
#[test]
fn email_rejects_multiple_at() {
assert!(validate_email("alice@@example.com").is_err());
assert!(validate_email("a@b@c").is_err());
}
#[test]
fn email_rejects_empty_parts() {
assert!(validate_email("@example.com").is_err());
assert!(validate_email("alice@").is_err());
assert!(validate_email("@").is_err());
}
#[test]
fn email_rejects_whitespace() {
for s in ["alice @example.com", "alice@ example.com", " [email protected]"] {
assert!(
validate_email(s).is_err(),
"whitespace must be rejected: {s:?}"
);
}
}
#[test]
fn email_rejects_control_chars() {
assert!(validate_email("alice\x00@example.com").is_err());
}
#[test]
fn email_rejects_over_length() {
let local = "a".repeat(MAX_EMAIL_LEN);
let too_long = format!("{local}@x");
assert!(validate_email(&too_long).is_err());
}
// ── NewUser::validate normalisation ───────────────────────────
#[test]
fn new_user_trims_username() {
let mut nu = NewUser {
username: " alice ".into(),
name: None,
email: None,
};
nu.validate().unwrap();
assert_eq!(nu.username, "alice");
}
#[test]
fn new_user_normalises_empty_optionals_to_none() {
let mut nu = NewUser {
username: "alice".into(),
name: Some(" ".into()),
email: Some(" ".into()),
};
nu.validate().unwrap();
assert_eq!(nu.name, None);
assert_eq!(nu.email, None);
}
#[test]
fn new_user_lowercases_email() {
let mut nu = NewUser {
username: "alice".into(),
name: None,
email: Some("[email protected]".into()),
};
nu.validate().unwrap();
assert_eq!(nu.email.as_deref(), Some("[email protected]"));
}
#[test]
fn new_user_trims_name() {
let mut nu = NewUser {
username: "alice".into(),
name: Some(" Alice Smith ".into()),
email: None,
};
nu.validate().unwrap();
// Internal whitespace is fine in a display name — only the
// edges get trimmed.
assert_eq!(nu.name.as_deref(), Some("Alice Smith"));
}
#[test]
fn new_user_rejects_invalid_username() {
let mut nu = NewUser {
username: "boss man".into(),
name: None,
email: None,
};
assert!(matches!(
nu.validate(),
Err(MemoryError::InvalidUsername(_))
));
}
#[test]
fn new_user_rejects_invalid_email() {
let mut nu = NewUser {
username: "alice".into(),
name: None,
email: Some("not-an-email".into()),
};
assert!(matches!(nu.validate(), Err(MemoryError::InvalidEmail(_))));
}
#[test]
fn human_password_accepts_typical() {
assert!(validate_human_password("twelve chars!!", Some("alice"), &[]).is_ok());
}
#[test]
fn human_password_rejects_short_long_prefix_and_reserved() {
let ok = "twelve chars!!";
assert!(validate_human_password(&ok[..11], None, &[]).is_err());
let too_long = "a".repeat(MAX_HUMAN_PASSWORD_BYTES + 1);
assert!(validate_human_password(&too_long, None, &[]).is_err());
assert!(validate_human_password(&format!("ams_{ok}"), None, &[]).is_err());
assert!(validate_human_password(&format!("aim_{ok}"), None, &[]).is_err());
assert!(validate_human_password(&format!("amk_{ok}"), None, &[]).is_err());
assert!(validate_human_password(ok, Some(ok), &[]).is_err());
assert!(validate_human_password(ok, Some("alice"), &[ok]).is_err());
}
#[test]
fn user_role_round_trips() {
assert_eq!(UserRole::parse("root").unwrap(), UserRole::Root);
assert_eq!(UserRole::parse("user").unwrap(), UserRole::User);
assert!(UserRole::parse("admin").is_err());
assert_eq!(UserRole::Root.as_str(), "root");
assert_eq!(UserRole::default(), UserRole::User);
}
}