Skip to content

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

Rust

feat: allow authenticated users to purge owned sessions

Vinicius Miguel01b97835abd7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8055aa5..6e665da0 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
+ session-management:
+ name: optional session-management
+ 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/session-management -- -D warnings
+ - run: cargo test -p ai-memory-mcp --features session-management session_management
+ - run: cargo test -p ai-memory-cli --features session-management --lib session_management
+
test:
name: test (${{ matrix.os }})
strategy:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a2f8424..758a51e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,11 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Added
+- Added optional human-session session inspection and owned purging, gated by the
+ `session-management` build feature and runtime switch. Reused existing human
+ authentication, authorization, and SQLite storage. (#1231)
+
## [3.0.0] - 2026-10-13
### Added
diff --git a/README.md b/README.md
index 65c4a6f4..8f86a7d3 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`.
+
+The optional [human-session session inspection and owned purging](docs/session-management.md)
+uses existing browser authentication and is disabled by default.
diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.toml
index 0261aa99..79749c86 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 = []
+session-management = ["ai-memory-mcp/session-management"]
+
[dependencies]
ai-memory-consolidate.workspace = true
ai-memory-core.workspace = true
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 2834f73a..5275369e 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 = "session-management")]
+ #[arg(long, env = "AI_MEMORY_ENABLE_SESSION_MANAGEMENT")]
+ pub enable_session_management: bool,
+
/// Transport to expose the MCP server on.
#[arg(long, value_enum, default_value_t = TransportKind::Stdio)]
pub transport: TransportKind,
@@ -3468,6 +3473,35 @@ pub struct WritePageArgs {
#[cfg(test)]
mod tests {
+ #[cfg(feature = "session-management")]
+ #[test]
+ fn session_management_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_session_management);
+ let parsed = Cli::try_parse_from([
+ "ai-memory",
+ "serve",
+ "--transport",
+ "http",
+ "--enable-session-management",
+ ])
+ .unwrap();
+ let Command::Serve(args) = parsed.command else {
+ panic!("serve")
+ };
+ assert!(args.enable_session_management);
+ }
+ #[cfg(not(feature = "session-management"))]
+ #[test]
+ fn session_management_flag_is_absent_by_default() {
+ assert!(
+ Cli::try_parse_from(["ai-memory", "serve", "--enable-session-management"]).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.rs
index 4dba5368..b0e4c251 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 = "session-management")]
+ if args.enable_session_management && !matches!(args.transport, TransportKind::Http) {
+ anyhow::bail!("--enable-session-management requires --transport http");
+ }
config.require_llm_fallback_credentials()?;
// Merge config + CLI CORS origins (config first, CLI adds new entries).
@@ -1834,6 +1838,19 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
auth_state.clone(),
expire_legacy_cookie_mw,
)));
+ #[cfg(feature = "session-management")]
+ let router = if args.enable_session_management {
+ router.merge(ai_memory_mcp::session_management::router(
+ ai_memory_mcp::session_management::SessionManagementState {
+ reader: store.reader.clone(),
+ writer: store.writer.clone(),
+ wiki: wiki.clone(),
+ },
+ 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 already
diff --git a/crates/ai-memory-mcp/Cargo.toml b/crates/ai-memory-mcp/Cargo.toml
index 5ad36d8f..e38c4b65 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 = []
+session-management = []
+
[dependencies]
ai-memory-core.workspace = true
ai-memory-consolidate.workspace = true
diff --git a/crates/ai-memory-mcp/src/lib.rs b/crates/ai-memory-mcp/src/lib.rs
index 7a4c3295..a4d3620f 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 = "session-management")]
+pub mod session_management;
diff --git a/crates/ai-memory-mcp/src/session_management.rs b/crates/ai-memory-mcp/src/session_management.rs
new file mode 100644
index 00000000..02a1821c
--- /dev/null
+++ b/crates/ai-memory-mcp/src/session_management.rs
@@ -0,0 +1,374 @@
+//! Browser-session management. Machine credentials never authenticate this surface.
+
+use std::sync::Arc;
+
+use ai_memory_core::{
+ ActorContext, AuthLevel, AuthorizedViewer, Capability, OwnerFilter, SessionId, UserId,
+};
+use ai_memory_store::{
+ Compaction, ObservationOrder, ObservationPage, ProjectAccess, PurgeMode, ReaderPool,
+ StoreError, WriterHandle,
+};
+use ai_memory_wiki::{AdmissionContext, AdmissionOp, Wiki};
+use axum::extract::{Path, Query, State};
+use axum::http::{Request, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Extension, Json, Router};
+use serde::Deserialize;
+use serde_json::{Value, json};
+
+use crate::auth::AuthState;
+use crate::human_auth::require_session;
+
+// Bounds browser reads. Returned with each page so client offsets cannot drift.
+const MANAGEMENT_PAGE_SIZE: usize = 50;
+
+/// Dependencies resolved once at server startup.
+#[derive(Clone)]
+pub struct SessionManagementState {
+ /// Read pool; all listings remain scope/owner filtered.
+ pub reader: ReaderPool,
+ /// Single writer actor.
+ pub writer: WriterHandle,
+ /// Canonical disk/SQL mutation path.
+ pub wiki: Wiki,
+}
+
+/// Authenticated JSON routes for the opt-in management console.
+/// Browser cookies and CSRF use the existing human-auth middleware.
+/// Callers mount this only when the runtime switch is enabled.
+pub fn router(state: SessionManagementState, auth: Arc<AuthState>) -> Router {
+ Router::new()
+ .route("/management/v1/projects", get(projects))
+ .route("/management/v1/sessions", get(sessions))
+ .route(
+ "/management/v1/sessions/{id}/observations",
+ get(observations),
+ )
+ .route("/management/v1/sessions/{id}/purge", post(purge))
+ .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",
+ )
+ }
+ }
+}
+
+fn is_admin(level: AuthLevel) -> bool {
+ level.authorize(Capability::Admin, true).is_ok()
+}
+
+fn owners(level: AuthLevel, actor: &ActorContext) -> OwnerFilter {
+ if is_admin(level) {
+ OwnerFilter::Any
+ } else {
+ OwnerFilter::for_actor_context(actor)
+ }
+}
+
+#[derive(Deserialize)]
+struct ScopeQuery {
+ workspace: String,
+ project: String,
+ #[serde(default)]
+ offset: usize,
+}
+
+async fn scope(
+ state: &SessionManagementState,
+ q: &ScopeQuery,
+ viewer: Option<Extension<AuthorizedViewer>>,
+ access: ProjectAccess,
+) -> Result<ai_memory_store::ResolvedScope, Response> {
+ ai_memory_store::lookup_existing_scope_guarded(
+ &state.reader,
+ &q.workspace,
+ &q.project,
+ viewer.map(|Extension(v)| v.user()),
+ access,
+ )
+ .await
+ .map_err(|e| {
+ if e.is_forbidden() {
+ error(StatusCode::FORBIDDEN, "project access denied")
+ } else if e.is_not_found() {
+ error(StatusCode::NOT_FOUND, "project not found")
+ } else {
+ error(StatusCode::BAD_REQUEST, "invalid scope")
+ }
+ })
+}
+
+async fn projects(
+ State(state): State<Arc<SessionManagementState>>,
+ viewer: Option<Extension<AuthorizedViewer>>,
+) -> Result<Json<Value>, Response> {
+ let projects = state
+ .reader
+ .list_projects_with_stats(viewer.map(|Extension(v)| v.user()))
+ .await
+ .map_err(store_error)?;
+ Ok(Json(json!({"projects": projects})))
+}
+
+async fn sessions(
+ State(state): State<Arc<SessionManagementState>>,
+ Query(q): Query<ScopeQuery>,
+ viewer: Option<Extension<AuthorizedViewer>>,
+ Extension(level): Extension<AuthLevel>,
+ Extension(actor): Extension<ActorContext>,
+) -> Result<Json<Value>, Response> {
+ let s = scope(&state, &q, viewer, ProjectAccess::Read).await?;
+ let sessions = state
+ .reader
+ .sessions_for_scope(
+ s.workspace_id,
+ s.project_id,
+ owners(level, &actor),
+ true,
+ MANAGEMENT_PAGE_SIZE,
+ q.offset,
+ )
+ .await
+ .map_err(store_error)?;
+ Ok(Json(
+ json!({"sessions": sessions, "page_size": MANAGEMENT_PAGE_SIZE}),
+ ))
+}
+
+async fn observations(
+ State(state): State<Arc<SessionManagementState>>,
+ Query(q): Query<ScopeQuery>,
+ Path(id): Path<SessionId>,
+ viewer: Option<Extension<AuthorizedViewer>>,
+ Extension(level): Extension<AuthLevel>,
+ Extension(actor): Extension<ActorContext>,
+) -> Result<Json<Value>, Response> {
+ let s = scope(&state, &q, viewer, ProjectAccess::Read).await?;
+ if state
+ .reader
+ .session_summary_scoped(s.workspace_id, s.project_id, id, owners(level, &actor))
+ .await
+ .map_err(store_error)?
+ .is_none()
+ {
+ return Err(error(StatusCode::NOT_FOUND, "session not found"));
+ }
+ let page = state
+ .reader
+ .session_observations_scoped(
+ s.workspace_id,
+ s.project_id,
+ id,
+ ObservationPage {
+ limit: MANAGEMENT_PAGE_SIZE,
+ offset: q.offset,
+ order: ObservationOrder::Asc,
+ kinds: None,
+ query: None,
+ },
+ )
+ .await
+ .map_err(store_error)?;
+ Ok(Json(json!({
+ "records": page.records,
+ "total": page.total,
+ "elided_other_scope": page.elided_other_scope,
+ "page_size": MANAGEMENT_PAGE_SIZE,
+ })))
+}
+
+#[derive(Deserialize)]
+struct PurgeBody {
+ workspace: String,
+ project: String,
+ #[serde(default)]
+ confirm: bool,
+ #[serde(default)]
+ dry_run: bool,
+}
+
+async fn purge(
+ State(state): State<Arc<SessionManagementState>>,
+ Path(id): Path<SessionId>,
+ viewer: Option<Extension<AuthorizedViewer>>,
+ Extension(level): Extension<AuthLevel>,
+ Extension(actor): Extension<ActorContext>,
+ Extension(user): Extension<UserId>,
+ Json(body): Json<PurgeBody>,
+) -> Result<Json<Value>, Response> {
+ let q = ScopeQuery {
+ workspace: body.workspace,
+ project: body.project,
+ offset: 0,
+ };
+ let s = scope(&state, &q, viewer, ProjectAccess::Write).await?;
+ let admin = is_admin(level);
+ let owner = actor
+ .identity_key()
+ .ok_or_else(|| error(StatusCode::FORBIDDEN, "operator identity required"))?;
+ // Refuse before admission/checkpoint side effects; the writer rechecks inside its transaction.
+ let session = state
+ .reader
+ .session_summary_scoped(s.workspace_id, s.project_id, id, owners(level, &actor))
+ .await
+ .map_err(store_error)?
+ .ok_or_else(|| error(StatusCode::NOT_FOUND, "session not found"))?;
+ if !admin && session.actor_user.as_deref() != Some(owner.storage_key().as_str()) {
+ return Err(error(StatusCode::NOT_FOUND, "session not found"));
+ }
+ // Preflight collateral before admission/checkpoints; the writer repeats
+ // this check at commit so a changed grant or session cannot race deletion.
+ let preview = if admin {
+ state
+ .writer
+ .purge_session(
+ s.workspace_id,
+ s.project_id,
+ id,
+ Some(user),
+ Compaction::Skip,
+ PurgeMode::Preview,
+ )
+ .await
+ } else {
+ state
+ .writer
+ .purge_owned_session(
+ s.workspace_id,
+ s.project_id,
+ id,
+ owner.clone(),
+ Some(user),
+ PurgeMode::Preview,
+ )
+ .await
+ }
+ .map_err(store_error)?;
+ if body.dry_run {
+ return Ok(Json(report(&preview, true, &[], &[])));
+ }
+ if !body.confirm {
+ return Err(error(
+ StatusCode::BAD_REQUEST,
+ "destructive operation requires confirm=true",
+ ));
+ }
+ // Both human and machine administration use the same Wiki primitives.
+ // This orchestration stays explicit here because self-service must recheck
+ // exact ownership and project grants, unlike the root-only admin surface.
+ let dispatch = state
+ .wiki
+ .admit_purge_session(
+ s.workspace_id,
+ s.project_id,
+ Some(AdmissionContext {
+ workspace: q.workspace,
+ project: q.project,
+ op: AdmissionOp::PurgeSession,
+ actor,
+ ..Default::default()
+ }),
+ )
+ .await
+ .map_err(|e| {
+ tracing::warn!(error = %e, "purge admission failed");
+ error(StatusCode::CONFLICT, "purge was refused")
+ })?;
+ state
+ .wiki
+ .commit_all(&format!("pre-management-purge-session {id}"))
+ .map_err(|e| {
+ tracing::warn!(error = %e, "purge checkpoint failed");
+ error(StatusCode::INTERNAL_SERVER_ERROR, "checkpoint failed")
+ })?;
+ let outcome = if admin {
+ state
+ .wiki
+ .purge_session(
+ s.workspace_id,
+ s.project_id,
+ id,
+ Some(user),
+ Compaction::Skip,
+ )
+ .await
+ } else {
+ state
+ .wiki
+ .purge_owned_session(s.workspace_id, s.project_id, id, owner, Some(user))
+ .await
+ }
+ .map_err(|e| match e {
+ ai_memory_wiki::WikiError::Store(e) => store_error(e),
+ other => {
+ tracing::warn!(error = %other, "session purge failed");
+ error(StatusCode::INTERNAL_SERVER_ERROR, "session purge failed")
+ }
+ })?;
+ let mut dispatch = dispatch;
+ if let Some(ctx) = dispatch.as_mut() {
+ ctx.partial_failure = !outcome.files_failed.is_empty();
+ }
+ state.wiki.dispatch_purge(dispatch.as_ref());
+ if let Err(e) = state
+ .wiki
+ .commit_all(&format!("management-purge-session {id}"))
+ {
+ tracing::warn!(error = %e, "post-purge checkpoint failed");
+ }
+ Ok(Json(report(
+ &outcome.summary,
+ false,
+ &outcome.files_deleted,
+ &outcome.files_failed,
+ )))
+}
+
+fn report(
+ s: &ai_memory_store::PurgeSessionSummary,
+ dry_run: bool,
+ deleted: &[ai_memory_core::PagePath],
+ failed: &[ai_memory_core::PagePath],
+) -> Value {
+ json!({"dry_run": dry_run, "observations_deleted": s.observations_deleted, "handoffs_deleted": s.handoffs_deleted, "pages_deleted": s.pages_deleted, "auto_improve_runs_deleted": s.auto_improve_runs_deleted, "removed_paths": s.removed_paths, "collateral_observations_deleted": s.collateral_observations_deleted, "collateral_handoffs_denulled": s.collateral_handoffs_denulled, "files_deleted": deleted, "files_failed": failed})
+}
diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rs
index 1c8fb5c4..541116d6 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 = "session-management")]
+mod session_management;
diff --git a/crates/ai-memory-mcp/tests/suite/session_management.rs b/crates/ai-memory-mcp/tests/suite/session_management.rs
new file mode 100644
index 00000000..80573d16
--- /dev/null
+++ b/crates/ai-memory-mcp/tests/suite/session_management.rs
@@ -0,0 +1,690 @@
+//! Adversarial management tests exercise real cookie/CSRF and writer isolation.
+use ai_memory_core::{
+ ActorContext, AgentKind, NewSession, NewUser, OwnerFilter, ProjectId, SessionId, UserId,
+ UserRole, WorkspaceId,
+};
+use ai_memory_mcp::{
+ HumanAuthRuntime,
+ auth::AuthState,
+ human_auth::LoginLimiter,
+ session_management::{SessionManagementState as ManagementState, router},
+};
+use ai_memory_store::{Store, hash_session_secret};
+use ai_memory_wiki::{Wiki, WritePageRequest};
+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,
+ wiki: Wiki,
+ router: Router,
+ alice: Browser,
+ bob: Browser,
+ root: Browser,
+ ws: WorkspaceId,
+ project: ProjectId,
+}
+
+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 {
+ harness_with_chain(None).await
+}
+async fn harness_with_chain(chain: Option<ai_memory_wiki::AdmissionChain>) -> Harness {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let mut wiki = Wiki::new(tmp.path(), store.writer.clone())
+ .unwrap()
+ .with_store_reader(store.reader.clone());
+ if let Some(chain) = chain {
+ wiki = wiki.with_admission_chain(chain);
+ }
+ 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 ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let project = store
+ .writer
+ .get_or_create_project(ws, "app", None)
+ .await
+ .unwrap();
+ 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(),
+ wiki: wiki.clone(),
+ },
+ auth,
+ );
+ Harness {
+ _tmp: tmp,
+ store,
+ wiki,
+ router,
+ alice,
+ bob,
+ root,
+ ws,
+ project,
+ }
+}
+async fn session(h: &Harness, owner: Option<&str>) -> SessionId {
+ let id = SessionId::new();
+ h.store
+ .writer
+ .begin_session(NewSession {
+ occurred_at: None,
+ id,
+ workspace_id: h.ws,
+ project_id: h.project,
+ agent_kind: AgentKind::Codex,
+ cwd: None,
+ actor_user: owner.map(|name| format!("user:{name}")),
+ })
+ .await
+ .unwrap();
+ id
+}
+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 management_refuses_foreign_ids_shared_deletion_and_missing_csrf_with_admin_control() {
+ let h = harness().await;
+ let alice = session(&h, Some("alice")).await;
+ let bob = session(&h, Some("bob")).await;
+ let shared = session(&h, None).await;
+ let uri = "/management/v1/sessions?workspace=default&project=app";
+ assert_eq!(
+ call(&h, None, "GET", uri, Value::Null, false).await.0,
+ StatusCode::UNAUTHORIZED
+ );
+ let response = h
+ .router
+ .clone()
+ .oneshot(
+ Request::builder()
+ .uri(uri)
+ .header("authorization", "Bearer root-bearer")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ response.status(),
+ StatusCode::UNAUTHORIZED,
+ "machine bearer cannot authenticate browser management"
+ );
+ let (status, listing) = call(&h, Some(&h.alice), "GET", uri, Value::Null, false).await;
+ assert_eq!(status, StatusCode::OK);
+ let ids: Vec<_> = listing["sessions"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|s| s["session_id"].as_str().unwrap())
+ .collect();
+ assert!(ids.contains(&alice.to_string().as_str()));
+ assert!(ids.contains(&shared.to_string().as_str()));
+ assert!(!ids.contains(&bob.to_string().as_str()));
+ assert_eq!(
+ call(&h, Some(&h.root), "GET", uri, Value::Null, false)
+ .await
+ .1["sessions"]
+ .as_array()
+ .unwrap()
+ .len(),
+ 3
+ );
+ let observations =
+ format!("/management/v1/sessions/{bob}/observations?workspace=default&project=app");
+ assert_eq!(
+ call(&h, Some(&h.alice), "GET", &observations, Value::Null, false)
+ .await
+ .0,
+ StatusCode::NOT_FOUND
+ );
+ assert_eq!(
+ call(&h, Some(&h.bob), "GET", &observations, Value::Null, false)
+ .await
+ .0,
+ StatusCode::OK
+ );
+ for sid in [bob, shared] {
+ for dry_run in [false, true] {
+ let uri = format!("/management/v1/sessions/{sid}/purge");
+ assert_eq!(call(&h, Some(&h.alice), "POST", &uri, json!({"workspace":"default", "project":"app", "confirm":true, "dry_run":dry_run}), true).await.0, StatusCode::NOT_FOUND);
+ }
+ assert!(
+ h.store
+ .reader
+ .session_summary_scoped(h.ws, h.project, sid, OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ }
+ let uri = format!("/management/v1/sessions/{alice}/purge");
+ let body = json!({"workspace":"default", "project":"app", "confirm":true});
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &uri, body.clone(), false)
+ .await
+ .0,
+ StatusCode::FORBIDDEN
+ );
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.alice),
+ "POST",
+ &uri,
+ json!({"workspace":"default", "project":"app", "dry_run":true, "confirm":true}),
+ true
+ )
+ .await
+ .0,
+ StatusCode::OK
+ );
+ assert!(
+ h.store
+ .reader
+ .session_summary_scoped(h.ws, h.project, alice, OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.alice),
+ "POST",
+ &uri,
+ json!({"workspace":"default", "project":"app"}),
+ true
+ )
+ .await
+ .0,
+ StatusCode::BAD_REQUEST
+ );
+ // A legitimate purge removes its summary but preserves maintained shared knowledge.
+ for (path, frontmatter) in [
+ (
+ format!("sessions/{alice}.md"),
+ json!({"session_id":alice.to_string()}),
+ ),
+ ("concepts/team.md".into(), json!({})),
+ ] {
+ h.wiki
+ .write_page(WritePageRequest {
+ workspace_id: h.ws,
+ project_id: h.project,
+ path: ai_memory_core::PagePath::new(path).unwrap(),
+ frontmatter,
+ body: "# Shared knowledge".into(),
+ tier: ai_memory_core::Tier::Semantic,
+ pinned: false,
+ title: None,
+ admission_ctx: None,
+ author_id: Some(h.alice.user),
+ actor: ActorContext::default(),
+ evidence: vec![],
+ })
+ .await
+ .unwrap();
+ }
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &uri, body.clone(), true)
+ .await
+ .0,
+ StatusCode::OK
+ );
+ assert!(
+ h.store
+ .reader
+ .session_summary_scoped(h.ws, h.project, alice, OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(
+ !h.wiki
+ .abs_path(
+ h.ws,
+ h.project,
+ &ai_memory_core::PagePath::new(format!("sessions/{alice}.md")).unwrap()
+ )
+ .exists()
+ );
+ assert!(
+ h.wiki
+ .abs_path(
+ h.ws,
+ h.project,
+ &ai_memory_core::PagePath::new("concepts/team.md").unwrap()
+ )
+ .exists()
+ );
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.root),
+ "POST",
+ &format!("/management/v1/sessions/{bob}/purge"),
+ body,
+ true
+ )
+ .await
+ .0,
+ StatusCode::OK
+ );
+}
+
+#[tokio::test]
+async fn management_raw_session_ids_fail_closed_on_wrong_and_partial_scope() {
+ let h = harness().await;
+ let sid = session(&h, Some("alice")).await;
+ let other_workspace = h
+ .store
+ .writer
+ .get_or_create_workspace("other")
+ .await
+ .unwrap();
+ h.store
+ .writer
+ .get_or_create_project(other_workspace, "app", None)
+ .await
+ .unwrap();
+ h.store
+ .writer
+ .get_or_create_project(h.ws, "other", None)
+ .await
+ .unwrap();
+ for browser in [&h.alice, &h.root] {
+ for (workspace, project) in [
+ ("other", "app"),
+ ("default", "other"),
+ ("default", "missing"),
+ ] {
+ let uri = format!(
+ "/management/v1/sessions/{sid}/observations?workspace={workspace}&project={project}"
+ );
+ assert_eq!(
+ call(&h, Some(browser), "GET", &uri, Value::Null, false)
+ .await
+ .0,
+ StatusCode::NOT_FOUND
+ );
+ let uri = format!("/management/v1/sessions/{sid}/purge");
+ for dry_run in [true, false] {
+ assert_eq!(call(&h, Some(browser), "POST", &uri, json!({"workspace":workspace,"project":project,"dry_run":dry_run,"confirm":true}), true).await.0, StatusCode::NOT_FOUND);
+ }
+ }
+ for query in ["", "workspace=default", "project=app"] {
+ let uri = format!("/management/v1/sessions/{sid}/observations?{query}");
+ assert_eq!(
+ call(&h, Some(browser), "GET", &uri, Value::Null, false)
+ .await
+ .0,
+ StatusCode::BAD_REQUEST
+ );
+ }
+ for body in [json!({"workspace":"default"}), json!({"project":"app"})] {
+ assert_eq!(
+ call(
+ &h,
+ Some(browser),
+ "POST",
+ &format!("/management/v1/sessions/{sid}/purge"),
+ body,
+ true
+ )
+ .await
+ .0,
+ StatusCode::UNPROCESSABLE_ENTITY
+ );
+ }
+ assert_eq!(
+ call(
+ &h,
+ Some(browser),
+ "GET",
+ &format!(
+ "/management/v1/sessions/{sid}/observations?workspace=default&project=app"
+ ),
+ Value::Null,
+ false
+ )
+ .await
+ .0,
+ StatusCode::OK
+ );
+ }
+ assert!(
+ h.store
+ .reader
+ .find_project(h.ws, "missing".into())
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(
+ h.store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_some()
+ );
+}
+
+#[tokio::test]
+async fn management_purge_admission_rejection_preserves_rows_and_files() {
+ use ai_memory_wiki::{AdmissionChain, AdmissionOp, FailurePolicy, WebhookConfig};
+ use std::sync::atomic::{AtomicBool, Ordering};
+ let allowed = Arc::new(AtomicBool::new(false));
+ let calls = Arc::new(std::sync::Mutex::new(Vec::<Value>::new()));
+ let hook = Router::new().route(
+ "/guard",
+ axum::routing::post({
+ let allowed = allowed.clone();
+ let calls = calls.clone();
+ move |axum::Json(payload): axum::Json<Value>| {
+ calls.lock().unwrap().push(payload);
+ let allowed = allowed.load(Ordering::SeqCst);
+ async move {
+ if allowed {
+ StatusCode::NO_CONTENT
+ } else {
+ StatusCode::FORBIDDEN
+ }
+ }
+ }
+ }),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let server = tokio::spawn(async move { axum::serve(listener, hook).await.unwrap() });
+ let chain = AdmissionChain::new(vec![WebhookConfig {
+ name: "management-guard".into(),
+ url: format!("http://{address}/guard"),
+ timeout_ms: 1_000,
+ failure_policy: FailurePolicy::Reject,
+ events: vec![AdmissionOp::PurgeSession],
+ blocking: true,
+ }])
+ .unwrap();
+ let h = harness_with_chain(Some(chain)).await;
+ let sid = session(&h, Some("alice")).await;
+ let path = ai_memory_core::PagePath::new(format!("sessions/{sid}.md")).unwrap();
+ h.wiki
+ .write_page(WritePageRequest {
+ workspace_id: h.ws,
+ project_id: h.project,
+ path: path.clone(),
+ frontmatter: json!({"session_id":sid.to_string()}),
+ body: "# Retained until admitted".into(),
+ tier: ai_memory_core::Tier::Episodic,
+ pinned: false,
+ title: None,
+ admission_ctx: None,
+ author_id: Some(h.alice.user),
+ actor: ActorContext::default(),
+ evidence: vec![],
+ })
+ .await
+ .unwrap();
+ let abs = h.wiki.abs_path(h.ws, h.project, &path);
+ let before = std::fs::read(&abs).unwrap();
+ let uri = format!("/management/v1/sessions/{sid}/purge");
+ let body = json!({"workspace":"default","project":"app","confirm":true});
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.alice),
+ "POST",
+ &uri,
+ json!({"workspace":"default","project":"app","dry_run":true,"confirm":true}),
+ true
+ )
+ .await
+ .0,
+ StatusCode::OK
+ );
+ assert!(
+ calls.lock().unwrap().is_empty(),
+ "preview must not run admission"
+ );
+ assert_eq!(std::fs::read(&abs).unwrap(), before);
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &uri, body.clone(), true)
+ .await
+ .0,
+ StatusCode::CONFLICT
+ );
+ assert!(
+ h.store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ assert_eq!(std::fs::read(&abs).unwrap(), before);
+ assert!(
+ h.wiki
+ .purged_sessions(h.ws, h.project)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ allowed.store(true, Ordering::SeqCst);
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &uri, body, true).await.0,
+ StatusCode::OK
+ );
+ assert!(!abs.exists());
+ assert!(
+ h.store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let recorded = calls.lock().unwrap();
+ assert_eq!(recorded.len(), 2);
+ for payload in recorded.iter() {
+ assert_eq!(payload["ctx"]["workspace"], "default");
+ assert_eq!(payload["ctx"]["project"], "app");
+ assert_eq!(payload["ctx"]["actor"]["user"], "alice");
+ assert_eq!(payload["ctx"]["op"], "purge_session");
+ }
+ server.abort();
+}
+
+#[tokio::test]
+async fn management_pagination_reports_its_limit_and_keeps_pages_disjoint() {
+ use ai_memory_core::{NewObservation, ObservationKind, Sanitized, Sanitizer};
+ let h = harness().await;
+ let uri = "/management/v1/sessions?workspace=default&project=app";
+ let limit = call(&h, Some(&h.alice), "GET", uri, Value::Null, false)
+ .await
+ .1["page_size"]
+ .as_u64()
+ .unwrap() as usize;
+ let mut ids = Vec::new();
+ for _ in 0..limit + 1 {
+ ids.push(session(&h, Some("alice")).await);
+ }
+ let first = call(&h, Some(&h.alice), "GET", uri, Value::Null, false)
+ .await
+ .1;
+ let next = call(
+ &h,
+ Some(&h.alice),
+ "GET",
+ &format!("{uri}&offset={limit}"),
+ Value::Null,
+ false,
+ )
+ .await
+ .1;
+ assert_eq!(first["sessions"].as_array().unwrap().len(), limit);
+ assert_eq!(next["sessions"].as_array().unwrap().len(), 1);
+ let next_id = &next["sessions"][0]["session_id"];
+ assert!(
+ first["sessions"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .all(|row| &row["session_id"] != next_id)
+ );
+ for index in 0..limit + 1 {
+ h.store
+ .writer
+ .insert_observation(Sanitized::new(
+ NewObservation {
+ session_id: ids[0],
+ workspace_id: h.ws,
+ project_id: h.project,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: format!("event {index}"),
+ body: format!("event body {index}"),
+ importance: 5,
+ occurred_at: None,
+ },
+ &Sanitizer::default(),
+ ))
+ .await
+ .unwrap();
+ }
+ let uri = format!(
+ "/management/v1/sessions/{}/observations?workspace=default&project=app",
+ ids[0]
+ );
+ let first = call(&h, Some(&h.alice), "GET", &uri, Value::Null, false)
+ .await
+ .1;
+ let next = call(
+ &h,
+ Some(&h.alice),
+ "GET",
+ &format!("{uri}&offset={limit}"),
+ Value::Null,
+ false,
+ )
+ .await
+ .1;
+ assert_eq!(first["page_size"], limit);
+ assert_eq!(first["total"], limit + 1);
+ assert_eq!(first["records"].as_array().unwrap().len(), limit);
+ assert_eq!(next["records"].as_array().unwrap().len(), 1);
+ let next_id = &next["records"][0]["id"];
+ assert!(
+ first["records"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .all(|row| &row["id"] != next_id)
+ );
+}
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index c9c409db..5da2b195 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -5984,6 +5984,30 @@ pub fn purge_session(
author_id: Option<ai_memory_core::UserId>,
compaction: Compaction,
mode: PurgeMode,
+) -> StoreResult<PurgeSessionSummary> {
+ purge_session_with_owner(
+ conn,
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ compaction,
+ mode,
+ None,
+ )
+}
+
+// Ownership is checked inside the deletion transaction, including previews.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn purge_session_with_owner(
+ conn: &mut Connection,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ author_id: Option<ai_memory_core::UserId>,
+ compaction: Compaction,
+ mode: PurgeMode,
+ owner: Option<&ai_memory_core::IdentityKey>,
) -> StoreResult<PurgeSessionSummary> {
let wid = workspace_id.as_bytes();
let pid = project_id.as_bytes();
@@ -6005,6 +6029,27 @@ pub fn purge_session(
)));
}
+ if let Some(owner) = owner {
+ let user = author_id.ok_or(StoreError::Forbidden("operator required"))?;
+ let authz = crate::project_authz::resolve_project_authz_strict(
+ &tx,
+ workspace_id,
+ project_id,
+ &crate::ProjectPrincipal::user(user),
+ true,
+ )?;
+ crate::authorize_project(&authz, crate::ProjectAccess::Write)
+ .map_err(|_| StoreError::Forbidden("project write access required"))?;
+ let owned: bool = tx.query_row(
+ "SELECT actor_user = ?4 FROM sessions WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3",
+ rusqlite::params![&sid[..], &wid[..], &pid[..], owner.storage_key()],
+ |row| Ok(row.get::<_, Option<bool>>(0)?.unwrap_or(false)),
+ )?;
+ if !owned {
+ return Err(StoreError::NotFound("session not found".into()));
+ }
+ }
+
// ---- collect, before anything is cut ----
// The recorded summary, plus every version at the session's page path
@@ -6118,6 +6163,13 @@ pub fn purge_session(
|row| row.get(0),
)?;
+ if owner.is_some() && (collateral_observations_deleted > 0 || collateral_handoffs_denulled > 0)
+ {
+ return Err(StoreError::InvalidState(
+ "session spans projects; an administrator must purge it".into(),
+ ));
+ }
+
if mode == PurgeMode::Preview {
// Same counts a confirmed purge would produce, read the same way it
// decides what to delete — via `SELECT`, never a `DELETE` rolled
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index ab72c425..e8aee7b6 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -489,6 +489,7 @@ pub(crate) enum WriteCmd {
/// [`crate::ops::PurgeMode::Preview`] stops right after counting and
/// never issues the delete — see [`crate::ops::PurgeMode`]'s doc.
mode: crate::ops::PurgeMode,
+ owner: Option<IdentityKey>,
reply: oneshot::Sender<StoreResult<crate::ops::PurgeSessionSummary>>,
},
/// Reclaim free pages on demand: rebuild the FTS indexes and `VACUUM`,
@@ -2313,6 +2314,55 @@ impl WriterHandle {
author_id: Option<ai_memory_core::UserId>,
compaction: crate::ops::Compaction,
mode: crate::ops::PurgeMode,
+ ) -> StoreResult<crate::ops::PurgeSessionSummary> {
+ self.purge_session_with_owner(
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ compaction,
+ mode,
+ None,
+ )
+ .await
+ }
+
+ /// Purge only a session stamped with this exact operator, never shared legacy rows.
+ /// Cross-project cascades are refused. Ownership is checked by the writer transaction.
+ ///
+ /// # Errors
+ /// Returns NotFound for a foreign/shared session, or propagates store failures.
+ pub async fn purge_owned_session(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ owner: IdentityKey,
+ author_id: Option<UserId>,
+ mode: crate::ops::PurgeMode,
+ ) -> StoreResult<crate::ops::PurgeSessionSummary> {
+ self.purge_session_with_owner(
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ crate::ops::Compaction::Skip,
+ mode,
+ Some(owner),
+ )
+ .await
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ async fn purge_session_with_owner(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ author_id: Option<UserId>,
+ compaction: crate::ops::Compaction,
+ mode: crate::ops::PurgeMode,
+ owner: Option<IdentityKey>,
) -> StoreResult<crate::ops::PurgeSessionSummary> {
let (tx, rx) = oneshot::channel();
self.send(WriteCmd::PurgeSession {
@@ -2322,6 +2372,7 @@ impl WriterHandle {
author_id,
compaction,
mode,
+ owner,
reply: tx,
})
.await?;
@@ -4227,9 +4278,10 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
author_id,
compaction,
mode,
+ owner,
reply,
} => {
- let result = ops::purge_session(
+ let result = ops::purge_session_with_owner(
&mut conn,
workspace_id,
project_id,
@@ -4237,6 +4289,7 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
author_id,
compaction,
mode,
+ owner.as_ref(),
);
send_or_warn(reply, result, "purge_session");
}
diff --git a/crates/ai-memory-store/tests/suite/multi_session.rs b/crates/ai-memory-store/tests/suite/multi_session.rs
index 5a5d3816..759c94ea 100644
--- a/crates/ai-memory-store/tests/suite/multi_session.rs
+++ b/crates/ai-memory-store/tests/suite/multi_session.rs
@@ -3665,3 +3665,274 @@ async fn observation_excerpts_follow_the_session_owner_while_the_vote_stays_shar
.unwrap();
assert!(hit.snippet.contains("quasar"), "{}", hit.snippet);
}
+
+/// The self-service purge checks exact ownership in the writer transaction,
+/// including previews; shared legacy rows are readable but never user-deletable.
+#[tokio::test]
+async fn owned_session_purge_refuses_foreign_shared_and_wrong_scope_sessions() {
+ use ai_memory_core::IdentityKey;
+ use ai_memory_store::{Compaction, PurgeMode};
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let user = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "purge-alice".into(),
+ name: None,
+ email: None,
+ },
+ ai_memory_core::UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ let mut sessions = Vec::new();
+ for owner in [Some("user:purge-alice"), Some("user:purge-bob"), None] {
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ occurred_at: None,
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: None,
+ actor_user: owner.map(str::to_string),
+ })
+ .await
+ .unwrap();
+ sessions.push(sid);
+ }
+ for mode in [PurgeMode::Preview, PurgeMode::Commit] {
+ for (project, sid) in [
+ (proj, sessions[1]),
+ (proj, sessions[2]),
+ (other, sessions[0]),
+ ] {
+ let result = store
+ .writer
+ .purge_owned_session(
+ ws,
+ project,
+ sid,
+ IdentityKey::User("purge-alice".into()),
+ Some(user),
+ mode,
+ )
+ .await;
+ assert!(matches!(result, Err(StoreError::NotFound(_))));
+ assert!(
+ store
+ .reader
+ .session_summary_scoped(ws, proj, sid, OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ }
+ }
+ store
+ .writer
+ .purge_owned_session(
+ ws,
+ proj,
+ sessions[0],
+ IdentityKey::User("purge-alice".into()),
+ Some(user),
+ PurgeMode::Preview,
+ )
+ .await
+ .unwrap();
+ assert!(
+ store
+ .reader
+ .session_summary_scoped(ws, proj, sessions[0], OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ // Simulate a grant revoked after the HTTP preflight: the writer must refuse.
+ store
+ .writer
+ .set_access_mode(proj, ai_memory_store::AccessMode::Restricted)
+ .await
+ .unwrap();
+ assert!(matches!(
+ store
+ .writer
+ .purge_owned_session(
+ ws,
+ proj,
+ sessions[0],
+ IdentityKey::User("purge-alice".into()),
+ Some(user),
+ PurgeMode::Commit
+ )
+ .await,
+ Err(StoreError::Forbidden(_))
+ ));
+ store
+ .writer
+ .set_access_mode(proj, ai_memory_store::AccessMode::Open)
+ .await
+ .unwrap();
+ store
+ .writer
+ .purge_owned_session(
+ ws,
+ proj,
+ sessions[0],
+ IdentityKey::User("purge-alice".into()),
+ Some(user),
+ PurgeMode::Commit,
+ )
+ .await
+ .unwrap();
+ assert!(
+ store
+ .reader
+ .session_summary_scoped(ws, proj, sessions[0], OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ // Admin control remains able to purge an ownerless legacy session.
+ store
+ .writer
+ .purge_session(
+ ws,
+ proj,
+ sessions[2],
+ Some(user),
+ Compaction::Skip,
+ PurgeMode::Commit,
+ )
+ .await
+ .unwrap();
+}
+
+#[tokio::test]
+async fn owned_session_purge_refuses_cross_project_cascades_with_admin_control() {
+ use ai_memory_core::{IdentityKey, NewObservation, ObservationKind, Sanitized, Sanitizer};
+ use ai_memory_store::{Compaction, PurgeMode};
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let user = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "cascade-alice".into(),
+ name: None,
+ email: None,
+ },
+ ai_memory_core::UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let foreign = store
+ .writer
+ .get_or_create_project(ws, "foreign", None)
+ .await
+ .unwrap();
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ occurred_at: None,
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: None,
+ actor_user: Some("user:cascade-alice".into()),
+ })
+ .await
+ .unwrap();
+ let observation = NewObservation {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: foreign,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: "foreign record".into(),
+ body: "must survive a self-service purge".into(),
+ importance: 5,
+ occurred_at: None,
+ };
+ store
+ .writer
+ .insert_observation(Sanitized::new(observation, &Sanitizer::default()))
+ .await
+ .unwrap();
+ for mode in [PurgeMode::Preview, PurgeMode::Commit] {
+ assert!(matches!(
+ store
+ .writer
+ .purge_owned_session(
+ ws,
+ proj,
+ sid,
+ IdentityKey::User("cascade-alice".into()),
+ Some(user),
+ mode
+ )
+ .await,
+ Err(StoreError::InvalidState(_))
+ ));
+ assert_eq!(
+ store
+ .reader
+ .observations_for_session(sid)
+ .await
+ .unwrap()
+ .len(),
+ 1
+ );
+ }
+ let preview = store
+ .writer
+ .purge_session(
+ ws,
+ proj,
+ sid,
+ Some(user),
+ Compaction::Skip,
+ PurgeMode::Preview,
+ )
+ .await
+ .unwrap();
+ assert_eq!(preview.collateral_observations_deleted, 1);
+ store
+ .writer
+ .purge_session(
+ ws,
+ proj,
+ sid,
+ Some(user),
+ Compaction::Skip,
+ PurgeMode::Commit,
+ )
+ .await
+ .unwrap();
+ assert!(
+ store
+ .reader
+ .observations_for_session(sid)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+}
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 41b9a89a..fae6de67 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -1603,6 +1603,51 @@ impl Wiki {
session_id: SessionId,
author_id: Option<UserId>,
compaction: ai_memory_store::Compaction,
+ ) -> WikiResult<PurgeSessionOutcome> {
+ self.purge_session_with_owner(
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ compaction,
+ None,
+ )
+ .await
+ }
+
+ /// Purge an operator's own session through the canonical disk/SQL mutation path.
+ /// Shared sessions and cross-project cascades require the admin path.
+ ///
+ /// # Errors
+ /// Returns store ownership/scope failures before removing files.
+ pub async fn purge_owned_session(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ owner: ai_memory_core::IdentityKey,
+ author_id: Option<UserId>,
+ ) -> WikiResult<PurgeSessionOutcome> {
+ self.purge_session_with_owner(
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ ai_memory_store::Compaction::Skip,
+ Some(owner),
+ )
+ .await
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ async fn purge_session_with_owner(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ author_id: Option<UserId>,
+ compaction: ai_memory_store::Compaction,
+ owner: Option<ai_memory_core::IdentityKey>,
) -> WikiResult<PurgeSessionOutcome> {
self.inspect_project_tree(workspace_id, project_id)?;
let _guard = self.mutation_lock.write().await;
@@ -1612,17 +1657,29 @@ impl Wiki {
// `WriterHandle::purge_session` instead, bypassing this wrapper
// entirely, so the file-removal loop below never runs over paths
// that a preview only *predicts* would be removed.
- let summary = self
- .writer
- .purge_session(
- workspace_id,
- project_id,
- session_id,
- author_id,
- compaction,
- ai_memory_store::PurgeMode::Commit,
- )
- .await?;
+ let summary = if let Some(owner) = owner {
+ self.writer
+ .purge_owned_session(
+ workspace_id,
+ project_id,
+ session_id,
+ owner,
+ author_id,
+ ai_memory_store::PurgeMode::Commit,
+ )
+ .await?
+ } else {
+ self.writer
+ .purge_session(
+ workspace_id,
+ project_id,
+ session_id,
+ author_id,
+ compaction,
+ ai_memory_store::PurgeMode::Commit,
+ )
+ .await?
+ };
let mut files_deleted = Vec::with_capacity(summary.removed_paths.len());
let mut files_failed = Vec::new();
for path in &summary.removed_paths {
@@ -7983,6 +8040,180 @@ mod tests {
);
}
+ async fn owned_session_with_page(
+ tmp: &TempDir,
+ ) -> (
+ Store,
+ Wiki,
+ WorkspaceId,
+ ProjectId,
+ UserId,
+ SessionId,
+ PagePath,
+ ) {
+ let (store, wiki, ws, proj) = scoped(tmp).await;
+ let user = store
+ .writer
+ .create_human_user(
+ ai_memory_core::NewUser {
+ username: "purge-owner".into(),
+ name: None,
+ email: None,
+ },
+ ai_memory_core::UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(ai_memory_core::NewSession {
+ occurred_at: None,
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: ai_memory_core::AgentKind::Codex,
+ cwd: None,
+ actor_user: Some("user:purge-owner".into()),
+ })
+ .await
+ .unwrap();
+ let path = PagePath::new(format!("sessions/{sid}.md")).unwrap();
+ let page = wiki
+ .write_page(req(
+ ws,
+ proj,
+ path.as_str(),
+ "owned session body",
+ serde_json::json!({"title":"Owned session"}),
+ ))
+ .await
+ .unwrap();
+ store.writer.end_session(sid, Some(page)).await.unwrap();
+ (store, wiki, ws, proj, user, sid, path)
+ }
+
+ #[tokio::test]
+ async fn owned_session_purge_authorization_failure_preserves_page_and_index() {
+ use ai_memory_core::IdentityKey;
+ let tmp = TempDir::new().unwrap();
+ let (store, wiki, ws, proj, user, sid, path) = owned_session_with_page(&tmp).await;
+ let abs = wiki.abs_path(ws, proj, &path);
+ let before = std::fs::read(&abs).unwrap();
+ assert!(matches!(
+ wiki.purge_owned_session(
+ ws,
+ proj,
+ sid,
+ IdentityKey::User("foreign".into()),
+ Some(user)
+ )
+ .await,
+ Err(WikiError::Store(ai_memory_store::StoreError::NotFound(_)))
+ ));
+ store
+ .writer
+ .set_access_mode(proj, ai_memory_store::AccessMode::Restricted)
+ .await
+ .unwrap();
+ assert!(matches!(
+ wiki.purge_owned_session(
+ ws,
+ proj,
+ sid,
+ IdentityKey::User("purge-owner".into()),
+ Some(user)
+ )
+ .await,
+ Err(WikiError::Store(ai_memory_store::StoreError::Forbidden(_)))
+ ));
+ assert_eq!(std::fs::read(&abs).unwrap(), before);
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ assert!(
+ !store
+ .reader
+ .search_pages("owned".into(), 10, None)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ assert!(wiki.purged_sessions(ws, proj).await.unwrap().is_empty());
+ // Removing the restriction provides a legitimate control for the same file.
+ store
+ .writer
+ .set_access_mode(proj, ai_memory_store::AccessMode::Open)
+ .await
+ .unwrap();
+ let outcome = wiki
+ .purge_owned_session(
+ ws,
+ proj,
+ sid,
+ IdentityKey::User("purge-owner".into()),
+ Some(user),
+ )
+ .await
+ .unwrap();
+ assert_eq!(outcome.files_deleted, vec![path]);
+ assert!(!abs.exists());
+ }
+
+ #[tokio::test]
+ async fn owned_session_purge_cleanup_failure_is_reported_and_tombstoned() {
+ let tmp = TempDir::new().unwrap();
+ let (store, wiki, ws, proj, user, sid, path) = owned_session_with_page(&tmp).await;
+ let abs = wiki.abs_path(ws, proj, &path);
+ let before = std::fs::read(&abs).unwrap();
+ // A directory in place of a file forces cleanup failure on every platform,
+ // including privileged test runners that ignore read-only permissions.
+ std::fs::remove_file(&abs).unwrap();
+ std::fs::create_dir(&abs).unwrap();
+ let outcome = wiki
+ .purge_owned_session(
+ ws,
+ proj,
+ sid,
+ ai_memory_core::IdentityKey::User("purge-owner".into()),
+ Some(user),
+ )
+ .await
+ .unwrap();
+ assert_eq!(outcome.files_failed, vec![path.clone()]);
+ assert!(outcome.files_deleted.is_empty());
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(wiki.purged_sessions(ws, proj).await.unwrap().contains(&sid));
+ // Simulate the leftover file returning during recovery. Reindex must
+ // honor the tombstone instead of resurrecting the deleted summary.
+ std::fs::remove_dir(&abs).unwrap();
+ std::fs::write(&abs, before).unwrap();
+ let summary = wiki.reindex_all().await.unwrap();
+ assert_eq!(summary.skipped_purged_sessions, 1);
+ assert!(
+ store
+ .reader
+ .search_pages("owned".into(), 10, None)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ }
+
#[tokio::test]
async fn purge_session_store_failure_preserves_page_file() {
let tmp = TempDir::new().unwrap();
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 074bc464..85fc7557 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 |
+| 17 | Human-session session inspection and owned purging | `mcp/src/session_management.rs`: human session/CSRF, completed password change, guarded scope lookup, exact ownership; `ops::purge_session_with_owner`: transaction ownership/write-grant checks and collateral refusal; `Wiki::purge_owned_session`: mutation lock, admission/checkpoints, partial cleanup/tombstones. | MCP `session_management` suite (foreign/shared/raw ids, wrong/partial scopes, anonymous/machine/CSRF, admission refusal, owner/Admin controls); store `multi_session::owned_session_purge_*`; wiki `owned_session_purge_authorization_failure_preserves_page_and_index`, `owned_session_purge_cleanup_failure_is_reported_and_tombstoned`. | 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 the
diff --git a/docs/session-management.md b/docs/session-management.md
new file mode 100644
index 00000000..c8568992
--- /dev/null
+++ b/docs/session-management.md
@@ -0,0 +1,28 @@
+# Self-service session management
+
+Build with `--features session-management` and start the HTTP server with
+`--enable-session-management` (`AI_MEMORY_ENABLE_SESSION_MANAGEMENT=true`).
+Both switches default to off. This enables `/management/v1/projects`,
+`/management/v1/sessions`, `/management/v1/sessions/{id}/observations`, and
+`/management/v1/sessions/{id}/purge` for existing human browser sessions.
+Machine bearers and password-change-required sessions are refused; mutations
+require the existing CSRF cookie/header pair.
+
+Listings require explicit workspace/project scope and return `page_size`.
+Users see their own and shared legacy sessions, but can delete only an exactly
+owned session with current project write access. Admins may inspect and purge
+any session. Ownership and grants are checked again in the writer transaction;
+shared sessions and cross-project collateral require an Admin. Pages remain
+shared within authorized projects; attribution never becomes a page read filter.
+
+POST purge with `dry_run: true` to preview, or `confirm: true` to delete. A preview
+has no disk, audit, or admission effects. Confirmed purges use the canonical wiki
+mutation lock, admission webhooks, pre/post git checkpoints, and replay tombstones.
+Maintained knowledge and later manual page versions survive. Database purges
+cannot be rolled back after file cleanup fails: `files_failed` reports the
+remaining paths, and recovery honors the tombstone. Git history, backups, and
+native transcripts can retain earlier content.
+
+Run `cargo t -p ai-memory-mcp --features session-management`,
+`cargo t -p ai-memory-store -E 'test(/owned_session_purge/)'`, and
+`cargo t -p ai-memory-wiki -E 'test(/owned_session_purge/)'` for the boundary tests.
diff --git a/docs/users.md b/docs/users.md
index a5b582c8..8739fc7e 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 agent
session id; session auto-scope needs the lifecycle-hook session id or explicit
`workspace` + `project` / `scopes`.
+
+See [Human-session session inspection and owned purging](session-management.md) for the opt-in HTTP surface.