Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat: add authenticated self-service native API keys
Vinicius Miguel3c501ab55bf7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex b8055aa5..1efb9338 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -45,6 +45,19 @@ jobs:- uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2- run: cargo clippy --workspace --all-targets -- -D warnings+ self-service-keys:+ name: optional self-service-keys+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable+ with:+ components: clippy+ - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2+ - run: cargo clippy --workspace --all-targets --features ai-memory-cli/self-service-keys -- -D warnings+ - run: cargo test -p ai-memory-mcp --features self-service-keys self_service_keys+ - run: cargo test -p ai-memory-cli --features self-service-keys --lib self_service_keys+test:name: test (${{ matrix.os }})strategy:diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8a2f8424..5f285b39 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,11 @@ version in [`docs/changelog/`](docs/changelog/):## [Unreleased]+### Added+- Added optional human-session self-service native API keys, gated by the+ `self-service-keys` build feature and runtime switch. Reused existing+ authentication, credential hashing, and SQLite storage. (#1231)+## [3.0.0] - 2026-10-13### Addeddiff --git a/README.md b/README.mdindex 65c4a6f4..8d254b5d 100644--- a/README.md+++ b/README.md@@ -674,3 +674,6 @@ MIT. See [LICENSE](LICENSE).This codebase is being built collaboratively with Claude Code(Anthropic Claude Opus 4.7) following the plan documented in`docs/design-decisions.md`.++Optional [self-service MCP API keys](docs/self-service-keys.md) reuse existing+browser authentication and are disabled by default.diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.tomlindex 0261aa99..37c020ac 100644--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@ -23,6 +23,10 @@ path = "src/main.rs"# a second ~120 MB harness binary for it that contains no tests.test = false+[features]+default = []+self-service-keys = ["ai-memory-mcp/self-service-keys"]+[dependencies]ai-memory-consolidate.workspace = trueai-memory-core.workspace = truediff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 2834f73a..72661b26 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -3336,6 +3336,11 @@ pub enum TransportKind {/// Arguments for `serve`.#[derive(Debug, Args)]pub struct ServeArgs {+ /// Enable optional browser-session management API (requires an opt-in build).+ #[cfg(feature = "self-service-keys")]+ #[arg(long, env = "AI_MEMORY_ENABLE_SELF_SERVICE_KEYS")]+ pub enable_self_service_keys: bool,+/// Transport to expose the MCP server on.#[arg(long, value_enum, default_value_t = TransportKind::Stdio)]pub transport: TransportKind,@@ -3468,6 +3473,33 @@ pub struct WritePageArgs {#[cfg(test)]mod tests {+ #[cfg(feature = "self-service-keys")]+ #[test]+ fn self_service_keys_is_runtime_opt_in() {+ let parsed = Cli::try_parse_from(["ai-memory", "serve"]).unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(!args.enable_self_service_keys);+ let parsed = Cli::try_parse_from([+ "ai-memory",+ "serve",+ "--transport",+ "http",+ "--enable-self-service-keys",+ ])+ .unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(args.enable_self_service_keys);+ }+ #[cfg(not(feature = "self-service-keys"))]+ #[test]+ fn self_service_keys_flag_is_absent_by_default() {+ assert!(Cli::try_parse_from(["ai-memory", "serve", "--enable-self-service-keys"]).is_err());+ }+use super::*;use clap::{CommandFactory, Parser};use std::collections::BTreeSet;diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 4dba5368..1ca18ba7 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1151,6 +1151,10 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {validate_web_ui_args(args.enable_web, args.web_ui_dir.as_deref())?;refuse_a_missing_token_file(&config.auth)?;+ #[cfg(feature = "self-service-keys")]+ if args.enable_self_service_keys && !matches!(args.transport, TransportKind::Http) {+ anyhow::bail!("--enable-self-service-keys requires --transport http");+ }config.require_llm_fallback_credentials()?;// Merge config + CLI CORS origins (config first, CLI adds new entries).@@ -1834,6 +1838,24 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {auth_state.clone(),expire_legacy_cookie_mw,)));+ #[cfg(feature = "self-service-keys")]+ let router = if args.enable_self_service_keys {+ router.merge(ai_memory_mcp::self_service_keys::router(+ ai_memory_mcp::self_service_keys::SelfServiceKeysState {+ reader: store.reader.clone(),+ writer: store.writer.clone(),+ pepper: config+ .auth+ .token_pepper+ .clone()+ .filter(|p| !p.trim().is_empty())+ .map(TokenPepper::new),+ },+ auth_state.clone(),+ ))+ } else {+ router+ };let router = apply_host_layer(router, config.allowed_hosts.clone());// Host the entire surface under the configured base path. Empty// base = root (unchanged). The auth/host layers are alreadydiff --git a/crates/ai-memory-mcp/Cargo.toml b/crates/ai-memory-mcp/Cargo.tomlindex 5ad36d8f..aaccd21c 100644--- a/crates/ai-memory-mcp/Cargo.toml+++ b/crates/ai-memory-mcp/Cargo.toml@@ -12,6 +12,10 @@ description = "MCP server transport and tool router for ai-memory."# statically links the whole dep graph and gets scanned by macOS on# first run.+[features]+default = []+self-service-keys = []+[dependencies]ai-memory-core.workspace = trueai-memory-consolidate.workspace = truediff --git a/crates/ai-memory-mcp/src/lib.rs b/crates/ai-memory-mcp/src/lib.rsindex 7a4c3295..54e87947 100644--- a/crates/ai-memory-mcp/src/lib.rs+++ b/crates/ai-memory-mcp/src/lib.rs@@ -38,3 +38,6 @@ extern crate self as ai_memory_mcp;#[cfg(test)]#[path = "../tests/suite/mod.rs"]mod integration;++#[cfg(feature = "self-service-keys")]+pub mod self_service_keys;diff --git a/crates/ai-memory-mcp/src/self_service_keys.rs b/crates/ai-memory-mcp/src/self_service_keys.rsnew file mode 100644index 00000000..baf16483--- /dev/null+++ b/crates/ai-memory-mcp/src/self_service_keys.rs@@ -0,0 +1,137 @@+//! Personal native API keys through existing browser-session authentication.+use crate::{auth::AuthState, human_auth::require_session};+use ai_memory_core::{ApiCredentialId, UserId};+use ai_memory_store::{ReaderPool, StoreError, TokenPepper, WriterHandle};+use axum::{+ Extension, Json, Router,+ extract::{Path, State},+ http::{Request, StatusCode, header},+ middleware::{self, Next},+ response::{IntoResponse, Response},+ routing::{get, post},+};+use serde::Deserialize;+use serde_json::{Value, json};+use std::sync::Arc;+/// Dependencies resolved once at startup; credentials never read server config.+#[derive(Clone)]+pub struct SelfServiceKeysState {+ /// Read pool for credential ownership.+ pub reader: ReaderPool,+ /// Existing single writer.+ pub writer: WriterHandle,+ /// Server-configured native-key pepper.+ pub pepper: Option<TokenPepper>,+}+/// Human sessions only. Machine bearers and pending password changes are refused.+pub fn router(state: SelfServiceKeysState, auth: Arc<AuthState>) -> Router {+ Router::new()+ .route(+ "/management/v1/credentials",+ get(credentials).post(create_credential),+ )+ .route(+ "/management/v1/credentials/{id}/revoke",+ post(revoke_credential),+ )+ .with_state(Arc::new(state))+ .layer(middleware::from_fn(ready))+ .layer(middleware::from_fn_with_state(auth, require_session))+ .layer(middleware::from_fn(no_store))+}+async fn no_store(req: Request<axum::body::Body>, next: Next) -> Response {+ let mut response = next.run(req).await;+ response.headers_mut().insert(+ header::CACHE_CONTROL,+ axum::http::HeaderValue::from_static("private, no-store"),+ );+ response+}++async fn ready(+ Extension(live): Extension<ai_memory_store::LiveWebSession>,+ req: Request<axum::body::Body>,+ next: Next,+) -> Response {+ if live.user.must_change_password {+ return error(StatusCode::FORBIDDEN, "password change required");+ }+ next.run(req).await+}++fn error(status: StatusCode, message: &str) -> Response {+ (status, Json(json!({"error": message}))).into_response()+}++fn store_error(e: StoreError) -> Response {+ match e {+ StoreError::NotFound(_) => error(StatusCode::NOT_FOUND, "not found"),+ StoreError::Forbidden(message) => error(StatusCode::FORBIDDEN, message),+ StoreError::InvalidState(message) => error(StatusCode::CONFLICT, &message),+ other => {+ tracing::warn!(error = %other, "management store operation failed");+ error(+ StatusCode::INTERNAL_SERVER_ERROR,+ "management operation failed",+ )+ }+ }+}++async fn credentials(+ State(state): State<Arc<SelfServiceKeysState>>,+ Extension(user): Extension<UserId>,+) -> Result<Json<Value>, Response> {+ Ok(Json(+ json!({"credentials": state.reader.list_api_credentials_for_user(user).await.map_err(store_error)?}),+ ))+}++#[derive(Deserialize)]+struct KeyBody {+ label: String,+}++async fn create_credential(+ State(state): State<Arc<SelfServiceKeysState>>,+ Extension(user): Extension<UserId>,+ Json(body): Json<KeyBody>,+) -> Result<Json<Value>, Response> {+ let pepper = state+ .pepper+ .as_ref()+ .ok_or_else(|| error(StatusCode::CONFLICT, "API keys are not configured"))?;+ let token = ai_memory_store::generate_api_key().map_err(store_error)?;+ let id = state+ .writer+ .create_api_credential(+ ApiCredentialId::new(),+ user,+ body.label,+ ai_memory_store::hash_token(&token, pepper),+ Some(ai_memory_store::api_key_preview(&token)),+ )+ .await+ .map_err(store_error)?;+ Ok(Json(json!({"id": id, "token": token})))+}++async fn revoke_credential(+ State(state): State<Arc<SelfServiceKeysState>>,+ Extension(user): Extension<UserId>,+ Path(id): Path<ApiCredentialId>,+) -> Result<Json<Value>, Response> {+ let key = state+ .reader+ .find_api_credential(id)+ .await+ .map_err(store_error)?+ .filter(|key| key.user_id == user)+ .ok_or_else(|| error(StatusCode::NOT_FOUND, "credential not found"))?;+ state+ .writer+ .revoke_api_credential(key.id)+ .await+ .map_err(store_error)?;+ Ok(Json(json!({"revoked": true})))+}diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rsindex 1c8fb5c4..aac13724 100644--- a/crates/ai-memory-mcp/tests/suite/mod.rs+++ b/crates/ai-memory-mcp/tests/suite/mod.rs@@ -40,3 +40,6 @@ mod retrieval_via_tools;mod slot_identity;mod stress_autoscope;mod web_search_parity;++#[cfg(feature = "self-service-keys")]+mod self_service_keys;diff --git a/crates/ai-memory-mcp/tests/suite/self_service_keys.rs b/crates/ai-memory-mcp/tests/suite/self_service_keys.rsnew file mode 100644index 00000000..5b8a73b9--- /dev/null+++ b/crates/ai-memory-mcp/tests/suite/self_service_keys.rs@@ -0,0 +1,282 @@+//! Adversarial management tests exercise real cookie/CSRF and writer isolation.+use ai_memory_core::{NewUser, UserId, UserRole};+use ai_memory_mcp::{+ HumanAuthRuntime,+ auth::AuthState,+ human_auth::LoginLimiter,+ self_service_keys::{SelfServiceKeysState as ManagementState, router},+};+use ai_memory_store::{Store, TokenPepper, hash_session_secret};+use axum::{+ Router,+ body::Body,+ http::{Request, StatusCode},+};+use serde_json::{Value, json};+use std::sync::Arc;+use tempfile::TempDir;+use tower::ServiceExt;++struct Browser {+ cookie: String,+ csrf: String,+ user: UserId,+}+struct Harness {+ _tmp: TempDir,+ store: Store,+ router: Router,+ alice: Browser,+ bob: Browser,+ root: Browser,+}++async fn browser(store: &Store, name: &str, role: UserRole, must_change: bool) -> Browser {+ let phc = ai_memory_store::password::hash_password("password-for-test".into())+ .await+ .unwrap();+ let user = store+ .writer+ .create_human_user(+ NewUser {+ username: name.into(),+ name: None,+ email: None,+ },+ role,+ Some(phc.clone()),+ must_change,+ )+ .await+ .unwrap();+ let secret = ai_memory_store::web_sessions::generate_session_secret().unwrap();+ let csrf = ai_memory_store::web_sessions::generate_csrf_secret().unwrap();+ store+ .writer+ .issue_web_session(+ user,+ phc,+ role,+ must_change,+ hash_session_secret(&secret),+ hash_session_secret(&csrf),+ )+ .await+ .unwrap();+ Browser {+ user,+ cookie: format!("ai_memory_session={secret}; ai_memory_csrf={csrf}"),+ csrf,+ }+}+async fn harness() -> Harness {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let alice = browser(&store, "alice", UserRole::User, false).await;+ let bob = browser(&store, "bob", UserRole::User, false).await;+ let root = browser(&store, "root", UserRole::Root, false).await;+ let auth = Arc::new(+ AuthState::new(Some("root-bearer".into())).with_human(HumanAuthRuntime {+ reader: store.reader.clone(),+ writer: store.writer.clone(),+ recovery_token_hash: None,+ root_username: "root".into(),+ root_name: None,+ root_email: None,+ reserved_passwords: vec![],+ trusted_proxy_cidrs: vec![],+ limiter: Arc::new(LoginLimiter::default()),+ }),+ );+ let router = router(+ ManagementState {+ reader: store.reader.clone(),+ writer: store.writer.clone(),+ pepper: Some(TokenPepper::new("test-pepper")),+ },+ auth,+ );+ Harness {+ _tmp: tmp,+ store,+ router,+ alice,+ bob,+ root,+ }+}+async fn call(+ h: &Harness,+ browser: Option<&Browser>,+ method: &str,+ uri: &str,+ body: Value,+ csrf: bool,+) -> (StatusCode, Value) {+ let mut request = Request::builder()+ .method(method)+ .uri(uri)+ .header("content-type", "application/json");+ if let Some(browser) = browser {+ request = request.header("cookie", &browser.cookie);+ if csrf {+ request = request.header("x-csrf-token", &browser.csrf);+ }+ }+ let response = h+ .router+ .clone()+ .oneshot(request.body(Body::from(body.to_string())).unwrap())+ .await+ .unwrap();+ assert_eq!(response.headers()["cache-control"], "private, no-store");+ let status = response.status();+ let bytes = axum::body::to_bytes(response.into_body(), 1_000_000)+ .await+ .unwrap();+ (+ status,+ serde_json::from_slice(&bytes).unwrap_or(Value::Null),+ )+}++#[tokio::test]+async fn self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls()+ {+ let h = harness().await;+ let path = "/management/v1/credentials";+ assert_eq!(+ call(&h, None, "GET", path, Value::Null, false).await.0,+ StatusCode::UNAUTHORIZED+ );+ let response = h+ .router+ .clone()+ .oneshot(+ Request::builder()+ .uri(path)+ .header("authorization", "Bearer root-bearer")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(response.status(), StatusCode::UNAUTHORIZED);+ assert_eq!(+ call(+ &h,+ Some(&h.alice),+ "POST",+ path,+ json!({"label":"missing-csrf"}),+ false+ )+ .await+ .0,+ StatusCode::FORBIDDEN+ );+ let pending = browser(&h.store, "pending", UserRole::User, true).await;+ assert_eq!(+ call(+ &h,+ Some(&pending),+ "POST",+ path,+ json!({"label":"refused"}),+ true+ )+ .await+ .0,+ StatusCode::FORBIDDEN+ );+ let issued = call(+ &h,+ Some(&h.alice),+ "POST",+ path,+ json!({"label":"own key","username":"bob"}),+ true,+ )+ .await;+ assert_eq!(issued.0, StatusCode::OK);+ assert!(issued.1["token"].as_str().unwrap().starts_with("aim_"));+ let credentials = h+ .store+ .reader+ .list_api_credentials_for_user(h.alice.user)+ .await+ .unwrap();+ assert_eq!(credentials.len(), 1);+ assert_eq!(credentials[0].user_id, h.alice.user);+ assert!(+ h.store+ .reader+ .list_api_credentials_for_user(h.bob.user)+ .await+ .unwrap()+ .is_empty()+ );+ let revoke = format!(+ "/management/v1/credentials/{}/revoke",+ issued.1["id"].as_str().unwrap()+ );+ assert_eq!(+ call(&h, Some(&h.bob), "POST", &revoke, json!({}), true)+ .await+ .0,+ StatusCode::NOT_FOUND+ );+ assert_eq!(+ call(&h, Some(&h.alice), "POST", &revoke, json!({}), false)+ .await+ .0,+ StatusCode::FORBIDDEN+ );+ assert!(+ h.store+ .reader+ .list_api_credentials_for_user(h.alice.user)+ .await+ .unwrap()[0]+ .revoked_at+ .is_none()+ );+ assert_eq!(+ call(&h, Some(&h.alice), "POST", &revoke, json!({}), true)+ .await+ .0,+ StatusCode::OK+ );+ assert!(+ h.store+ .reader+ .list_api_credentials_for_user(h.alice.user)+ .await+ .unwrap()[0]+ .revoked_at+ .is_some()+ );+ // A root browser also issues only a key owned by its immutable user id.+ assert_eq!(+ call(+ &h,+ Some(&h.root),+ "POST",+ path,+ json!({"label":"root's machine key"}),+ true+ )+ .await+ .0,+ StatusCode::OK+ );+ assert_eq!(+ h.store+ .reader+ .list_api_credentials_for_user(h.root.user)+ .await+ .unwrap()+ .len(),+ 1+ );+}diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 074bc464..5d15de5b 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -110,6 +110,8 @@ means the boundary is not built yet.| 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned |+| 18 | Human-session self-service native API keys | `mcp/src/self_service_keys.rs`: human session/CSRF and completed password change; creation takes authenticated `UserId`, never a supplied username; revocation verifies immutable owner; existing native keys remain User-level. | `self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls` (anonymous/machine/CSRF/pending-password/foreign-id refusal, supplied username ignored, legitimate User/Root controls). | Adversarial controls and guard-removal proofs. |+## Keeping this current (the standing protocol)1. **Touch a guard, add/extend its adversarial test.** Any change to code in thediff --git a/docs/self-service-keys.md b/docs/self-service-keys.mdnew file mode 100644index 00000000..de82e202--- /dev/null+++ b/docs/self-service-keys.md@@ -0,0 +1,22 @@+# Self-service MCP API keys++Build with `--features self-service-keys` and start the HTTP server with+`--enable-self-service-keys` (`AI_MEMORY_ENABLE_SELF_SERVICE_KEYS=true`). Both+switches default to off. Existing human browser sessions may GET or POST+`/management/v1/credentials` and POST `/management/v1/credentials/{id}/revoke`.+Machine bearers and password-change-required sessions cannot use these routes;+mutations require the existing CSRF cookie/header pair.++POST a `label` to create a key for the authenticated immutable user id. The+server returns the `aim_` key once and stores only its peppered hash. Configure+`[auth] token_pepper` as for the existing native-key administration commands.+Revocation refuses another user's credential id. Listing returns metadata and+previews, never token material. Responses use `Cache-Control: private, no-store`.++Use the key as an Authorization: Bearer credential for `/mcp` and lifecycle+hooks. It remains User-level even when its owner is an Admin. Disabling browser+access does not revoke machine keys; revoke them separately. No identity+provider, password implementation, database, or schema is added.++Run `cargo t -p ai-memory-mcp --features self-service-keys` for the adversarial+anonymous, machine, CSRF, pending-password, foreign-id, and legitimate owner tests.diff --git a/docs/users.md b/docs/users.mdindex a5b582c8..2e3cb1fc 100644--- a/docs/users.md+++ b/docs/users.md@@ -803,3 +803,5 @@ ones who should keep access; nothing is granted automatically.authenticates as, like any other. The Keycloak/OIDC `sid` claim is also not an ai-memory agentsession id; session auto-scope needs the lifecycle-hook session id or explicit`workspace` + `project` / `scopes`.++See [Self-service MCP API keys](self-service-keys.md) for the opt-in HTTP surface.