Skip to content

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

Rust

fix: close post-merge audit gaps

AkitaOnRailse63fa16476b7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 376cd949..89542dea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,9 @@ version in [`docs/changelog/`](docs/changelog/):
Argon2id verifier. A restored database with existing keys now refuses to
serve under a different `[auth].token_pepper` instead of silently making
every key return 401; pepper rotation remains allowed while no keys exist.
+ A pre-verifier backup containing keys fails restore until the operator
+ supplies the original pepper and explicitly confirms it with
+ `--accept-legacy-api-key-pepper`.
([#1495](https://github.com/akitaonrails/ai-memory/issues/1495))
- Defined `ai-memory backup` as an online data snapshot rather than a complete
@@ -36,12 +39,15 @@ version in [`docs/changelog/`](docs/changelog/):
- Accepted the exact CRLF migration checksums written by Windows-native
releases before v3.1.2 and replaced them transactionally with the current
LF checksums before strict migration validation. Unknown migration changes
- still fail closed. ([#1499](https://github.com/akitaonrails/ai-memory/issues/1499))
+ still fail closed. Bare hook reinstallation also preserves the Windows
+ exec-form `--capture-assistant` opt-in instead of looking only inside the
+ command string. ([#1499](https://github.com/akitaonrails/ai-memory/issues/1499))
- Held `ai-memory run` heartbeat notices while the harness owns the terminal
and printed them after it exits, so a server outage no longer writes into the
harness TUI. Only the first and latest notices are replayed, with a count of
- the rest.
+ the rest. A transport outage that changes into a server-side lease rejection
+ is reported as a new state instead of being hidden as the same failure.
([#1500](https://github.com/akitaonrails/ai-memory/issues/1500))
- Dropped stopwords from the quoted bag of words a search falls back to when
@@ -55,7 +61,7 @@ version in [`docs/changelog/`](docs/changelog/):
drops everything the source project owns, the same set `purge-project`
deletes. This includes managed workstreams, cross-project messages,
auto-improvement and profile-harvest state, consolidation jobs, ingest keys,
- entities, page feedback, purge tombstones and project grants as well as
+ entities, page feedback, per-session purge tombstones and project grants as well as
sessions, observations and handoffs. The `400` for sending both a project
name and an id, or neither, applies to the admin endpoints; the CLI resolves
a missing project from the marker, the git remote, then the directory name.
@@ -80,6 +86,11 @@ version in [`docs/changelog/`](docs/changelog/):
entries keep working. `uninstall --only hooks` keeps the stored key while
such a bridge entry remains. ([#1490](https://github.com/akitaonrails/ai-memory/issues/1490))
+- Scoped implicit bridge credentials to their configured endpoint, rejected a
+ malformed stored user key instead of falling through to root, made failed
+ installs roll back newly stored credentials, and included the absolute data
+ dir in Claude Code's printed session-aware command as well as its JSON entry.
+
## [3.1.2] - 2026-10-20
### Fixed
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 6095512e..a3a63d4e 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -2308,6 +2308,10 @@ pub struct RestoreArgs {
/// Overwrite an existing non-empty data dir.
#[arg(long)]
pub force: bool,
+ /// Confirm that the configured token pepper is the original one for a
+ /// pre-verifier backup that already contains native API keys.
+ #[arg(long)]
+ pub accept_legacy_api_key_pepper: bool,
}
/// Arguments for `restore-agents`.
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 2f07f4ad..76dd47cc 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -1301,21 +1301,33 @@ fn baked_capture_assistant(existing: &str) -> Option<bool> {
for entry in entries {
// Nested (`hooks:[{command}]`) or flat (`{command}`) shape.
let nested = entry.get("hooks").and_then(serde_json::Value::as_array);
- let commands: Vec<&str> = match nested {
- Some(inner) => inner
- .iter()
- .filter_map(|e| e.get("command").and_then(|c| c.as_str()))
- .collect(),
- None => entry
- .get("command")
- .and_then(|c| c.as_str())
- .into_iter()
- .collect(),
+ let hook_entries: Vec<&serde_json::Value> = match nested {
+ Some(inner) => inner.iter().collect(),
+ None => vec![entry],
};
- for command in commands {
- if hook_command_is_ours(command) {
+ for hook_entry in hook_entries {
+ let Some(command) = hook_entry.get("command").and_then(|c| c.as_str()) else {
+ continue;
+ };
+ let args = hook_entry.get("args").and_then(serde_json::Value::as_array);
+ let recognizer = args.map_or_else(
+ || command.to_owned(),
+ |args| {
+ let suffix = args
+ .iter()
+ .filter_map(serde_json::Value::as_str)
+ .collect::<Vec<_>>()
+ .join(" ");
+ format!("{command} {suffix}")
+ },
+ );
+ if hook_command_is_ours(&recognizer) {
saw_ai_memory = true;
- if command.contains("--capture-assistant") {
+ let args_have_marker = args.is_some_and(|args| {
+ args.iter()
+ .any(|arg| arg.as_str() == Some("--capture-assistant"))
+ });
+ if command.contains("--capture-assistant") || args_have_marker {
has_marker = true;
}
}
@@ -11183,11 +11195,8 @@ model = "gpt-5"
/// auto-wire issues — must PRESERVE a user's existing assistant-capture
/// opt-in, not silently strip it.
///
- /// Unix-gated: `--capture-assistant` is baked onto the native Stop command on
- /// POSIX-native platforms; the Windows Claude command form does not carry the
- /// flag in its rendered JSON, so there is nothing to drop or preserve there.
- /// The preserve logic itself (`baked_capture_assistant`) has no platform
- /// branch.
+ /// Unix-gated because this end-to-end render uses the host platform. The
+ /// parser itself has a platform-independent Windows exec-form regression.
#[cfg(unix)]
#[test]
fn a_bare_reapply_preserves_an_existing_capture_assistant_opt_in() {
@@ -11216,6 +11225,25 @@ model = "gpt-5"
);
}
+ #[test]
+ fn windows_exec_form_preserves_capture_assistant_from_args() {
+ let settings = serde_json::json!({
+ "hooks": {
+ "Stop": [{
+ "hooks": [{
+ "type": "command",
+ "command": r"C:\Program Files\ai-memory\ai-memory.exe",
+ "args": ["hook", "--event", "stop", "--agent", "claude-code", "--server-url", "http://127.0.0.1:49374", "--capture-assistant"]
+ }]
+ }]
+ }
+ });
+ assert_eq!(
+ baked_capture_assistant(&serde_json::to_string(&settings).unwrap()),
+ Some(true)
+ );
+ }
+
/// The preserve logic must not false-positive: a fresh install without the
/// flag stays off.
#[test]
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 4d5385a1..2d51cc2f 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -159,19 +159,36 @@ pub(crate) fn run_with_opencode_dialect(
// open.
let bridge_carries_token = matches!(args.client, McpClient::Muse)
|| (args.client == McpClient::ClaudeCode && args.session_aware);
- if args.apply
+ let may_store_bridge_key = args.apply
&& token_given
&& bridge_carries_token
&& config.auth.configured_bearer_token().is_none()
&& config.runtime_env.host_cwd().is_none()
- && let Some(token) = args.auth_token.as_deref()
- && store_bridge_key(&config.data_dir, token)
- {
- args.auth_token = None;
- args.bridge_data_dir = Some(config.data_dir.clone());
- }
+ && same_mcp_endpoint(
+ &config.server_url,
+ args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
+ );
validate_args(&args)?;
if args.apply {
+ if may_store_bridge_key
+ && let Some(token) = args.auth_token.clone()
+ && let Some(stored) = store_bridge_key(&config.data_dir, &token)
+ {
+ args.auth_token = None;
+ args.bridge_data_dir = Some(config.data_dir.clone());
+ if let Err(error) = apply_to_config_file(&args) {
+ if stored == HookCredential::Seeded
+ && crate::config::read_hook_auth_token(&config.data_dir).as_deref()
+ == Some(token.as_str())
+ {
+ crate::config::clear_hook_auth_token(&config.data_dir).with_context(
+ || "rolling back the bridge credential after MCP config update failed",
+ )?;
+ }
+ return Err(error);
+ }
+ return Ok(());
+ }
return apply_to_config_file(&args);
}
let snippet = match args.client {
@@ -243,11 +260,10 @@ fn route_file_token(args: &mut InstallMcpArgs, token_file: &Path) -> Result<()>
}
/// Store `token` in `<data_dir>/auth-token` for the bridge, the file and
-/// format `install-hooks --apply` uses. `false` when the bridge would not read
-/// this key from there: a different key is already stored (it belongs to the
-/// install's hooks and is left alone), the hooks sign in with OIDC, or the
-/// write failed. The caller then keeps the key in the entry.
-fn store_bridge_key(data_dir: &Path, token: &str) -> bool {
+/// format `install-hooks --apply` uses. Returns whether this call created the
+/// files or found the same key; `None` means the caller must keep the key in
+/// the entry.
+fn store_bridge_key(data_dir: &Path, token: &str) -> Option<HookCredential> {
// The hooks present an OIDC `auth.json` only while no key is stored, so
// storing one here would quietly switch them to this key.
if crate::config::read_hook_auth_token(data_dir).is_none()
@@ -260,15 +276,15 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {
"[ai-memory] this install's hooks sign in with OIDC; keeping the --auth-token key \
in the MCP entry, as before, so they keep doing so"
);
- return false;
+ return None;
}
match crate::local_auth::seed_hook_credential(data_dir, token) {
- Ok(HookCredential::Seeded | HookCredential::Current) => {
+ Ok(outcome @ (HookCredential::Seeded | HookCredential::Current)) => {
eprintln!(
"[ai-memory] stored the bridge's key in {}; the MCP entry carries no token",
crate::config::hook_auth_token_path_in(data_dir).display()
);
- true
+ Some(outcome)
}
Ok(HookCredential::KeptOther) => {
eprintln!(
@@ -276,7 +292,7 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {
hooks; keeping the --auth-token key in the MCP entry, as before",
crate::config::hook_auth_token_path_in(data_dir).display()
);
- false
+ None
}
Err(e) => {
eprintln!(
@@ -284,7 +300,7 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {
the MCP entry, as before",
data_dir.display()
);
- false
+ None
}
}
}
@@ -552,6 +568,16 @@ pub(crate) fn mcp_server_url_from_base(server_url: &str) -> String {
}
}
+pub(crate) fn same_mcp_endpoint(left: &str, right: &str) -> bool {
+ fn normalized(url: &str) -> String {
+ mcp_server_url_from_base(url).split_once('?').map_or_else(
+ || mcp_server_url_from_base(url),
+ |(base, _)| base.to_owned(),
+ )
+ }
+ normalized(left) == normalized(right)
+}
+
fn validate_args(args: &InstallMcpArgs) -> Result<()> {
if args.session_aware && !matches!(args.client, McpClient::ClaudeCode) {
bail!("--session-aware is supported only for --client claude-code");
@@ -2156,11 +2182,18 @@ fn render_claude_code(args: &InstallMcpArgs, config_path: &Path) -> Result<Strin
.as_deref()
.map(|token| format!(" --env \"AI_MEMORY_AUTH_TOKEN={token}\""))
.unwrap_or_default();
+ let data_dir = args
+ .bridge_data_dir
+ .as_ref()
+ .map_or_else(String::new, |path| {
+ format!(" --data-dir {}", shell_quote(&path.to_string_lossy()))
+ });
format!(
- "claude mcp add --transport stdio{env} {name} -- \\\n {command} mcp-bridge --server-url {url}",
+ "claude mcp add --transport stdio{env} {name} -- \\\n {command} mcp-bridge --server-url {url}{data_dir}",
name = args.name,
command = shell_quote(&bridge_command()),
url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
+ data_dir = data_dir,
)
} else if let Some(b) = &bearer {
format!(
@@ -4008,6 +4041,7 @@ mod tests {
let mut args = args_with_token(McpClient::ClaudeCode);
args.server_url = Some("https://memory.example/mcp".into());
args.session_aware = true;
+ args.bridge_data_dir = Some(PathBuf::from("/srv/AI Memory/data"));
let entry = build_mcp_entry(&args).unwrap();
@@ -4015,7 +4049,13 @@ mod tests {
assert_eq!(entry["command"], bridge_command());
assert_eq!(
entry["args"],
- json!(["mcp-bridge", "--server-url", "https://memory.example/mcp"])
+ json!([
+ "mcp-bridge",
+ "--server-url",
+ "https://memory.example/mcp",
+ "--data-dir",
+ "/srv/AI Memory/data"
+ ])
);
assert_eq!(entry["env"]["AI_MEMORY_AUTH_TOKEN"], "test-token-deadbeef");
assert!(entry.get("url").is_none());
@@ -4027,6 +4067,7 @@ mod tests {
"{} mcp-bridge --server-url",
shell_quote(&bridge_command())
)));
+ assert!(rendered.contains("--data-dir '/srv/AI Memory/data'"));
}
#[test]
@@ -4526,6 +4567,23 @@ mod tests {
assert!(install(&configured, McpClient::ClaudeCode, true).contains(KEY));
assert_eq!(stored(&configured), None);
+ let remote = config_in("different-endpoint");
+ let remote_file = remote.data_dir.with_extension("remote.json");
+ let mut remote_args = args_for(McpClient::ClaudeCode);
+ remote_args.apply = true;
+ remote_args.session_aware = true;
+ remote_args.config_file = Some(remote_file.clone());
+ remote_args.server_url = Some("https://other.example/mcp".into());
+ remote_args.auth_token = Some(KEY.into());
+ run_with_opencode_dialect(&remote, remote_args, None).unwrap();
+ let remote_text = std::fs::read_to_string(remote_file).unwrap();
+ assert!(remote_text.contains(KEY));
+ assert_eq!(
+ stored(&remote),
+ None,
+ "a key for another server is not hook auth"
+ );
+
let other = config_in("other");
crate::config::store_hook_auth_token(&other.data_dir, "aim_hooks_key").unwrap();
assert!(install(&other, McpClient::ClaudeCode, true).contains(KEY));
@@ -4559,6 +4617,27 @@ mod tests {
assert_eq!(stored(&http), None);
}
+ #[test]
+ fn failed_bridge_apply_rolls_back_a_newly_stored_key() {
+ let tmp = tempfile::tempdir().unwrap();
+ let config = Config {
+ data_dir: tmp.path().join("data"),
+ ..Config::default()
+ };
+ let config_file = tmp.path().join("broken.json");
+ std::fs::write(&config_file, "[]").unwrap();
+ let mut args = args_for(McpClient::ClaudeCode);
+ args.apply = true;
+ args.session_aware = true;
+ args.config_file = Some(config_file);
+ args.auth_token = Some("aim_must_rollback".into());
+
+ let error = run_with_opencode_dialect(&config, args, None).unwrap_err();
+ assert!(error.to_string().contains("object"), "{error:#}");
+ assert_eq!(crate::config::read_hook_auth_token(&config.data_dir), None);
+ assert!(!crate::config::hook_auth_header_path_in(&config.data_dir).exists());
+ }
+
#[test]
fn mcp_server_url_defaults_to_configured_server_url() {
let config = Config {
diff --git a/crates/ai-memory-cli/src/commands/mcp_bridge.rs b/crates/ai-memory-cli/src/commands/mcp_bridge.rs
index e10b8b82..8107a30d 100644
--- a/crates/ai-memory-cli/src/commands/mcp_bridge.rs
+++ b/crates/ai-memory-cli/src/commands/mcp_bridge.rs
@@ -51,7 +51,7 @@ use rmcp::transport::{StreamableHttpClientTransport, Transport, stdio};
use rmcp::{ErrorData as McpError, Peer, ServerHandler, ServiceExt};
use crate::cli::{BridgeAgent, McpBridgeArgs};
-use crate::commands::install_mcp::mcp_server_url_from_base;
+use crate::commands::install_mcp::{mcp_server_url_from_base, same_mcp_endpoint};
use crate::config::Config;
const ACTOR_SESSION_HEADER: HeaderName = HeaderName::from_static("x-memory-actor-session-id");
@@ -260,27 +260,53 @@ fn bridge_base_url<'a>(flag: Option<&'a str>, configured: &'a str) -> &'a str {
.unwrap_or(configured)
}
-/// The bearer the bridge sends: a configured one (`AI_MEMORY_AUTH_TOKEN`,
-/// `[auth].bearer_token`, `[auth].bearer_token_file`), else the key stored for
-/// this install's hooks in `<data_dir>/auth-token`, else the root token
-/// `Config::load` discovered on a loopback install. The stored key outranks
-/// discovery so a host that runs the server and a client sends the user's key
-/// rather than root.
-fn bridge_bearer(config: &Config) -> Option<String> {
+/// The bearer the bridge sends. Configured credentials may intentionally
+/// follow an explicit remote URL. Implicit install-local credentials may not:
+/// both the stored hook key and a discovered root key are scoped to the
+/// configured endpoint that caused them to be found.
+fn bridge_bearer(config: &Config, server_url: &str) -> Result<Option<String>> {
let usable = |token: &str| !token.trim().is_empty();
- config
+ if let Some(token) = config
.auth
.configured_bearer_token()
.filter(|token| usable(token))
.map(str::to_owned)
- .or_else(|| crate::config::read_hook_auth_token(&config.data_dir))
- .or_else(|| {
- config
- .auth
- .bearer_token
- .clone()
- .filter(|token| usable(token))
- })
+ {
+ return Ok(Some(token));
+ }
+
+ if !same_mcp_endpoint(&config.server_url, server_url) {
+ return Ok(None);
+ }
+
+ let stored_path = crate::config::hook_auth_token_path_in(&config.data_dir);
+ match std::fs::read_to_string(&stored_path) {
+ Ok(raw) => {
+ let token = raw.trim();
+ if token.is_empty() {
+ anyhow::bail!(
+ "stored bridge credential {} is blank; repair or remove it instead of falling back to root",
+ stored_path.display()
+ );
+ }
+ return Ok(Some(token.to_owned()));
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+ Err(error) => {
+ return Err(error).with_context(|| {
+ format!("reading stored bridge credential {}", stored_path.display())
+ });
+ }
+ }
+
+ if crate::commands::hook_spool::is_loopback_url(server_url) {
+ return Ok(config
+ .auth
+ .bearer_token
+ .clone()
+ .filter(|token| usable(token)));
+ }
+ Ok(None)
}
/// Run the stdio bridge, session-aware or session-less (see the module docs).
@@ -296,7 +322,7 @@ pub async fn run(config: &Config, args: McpBridgeArgs) -> Result<()> {
args.server_url.as_deref(),
&config.server_url,
));
- let bearer = bridge_bearer(config);
+ let bearer = bridge_bearer(config, &server_url)?;
let transport = StreamableHttpClientTransport::from_config(upstream_config(
&server_url,
session_id,
@@ -661,16 +687,31 @@ mod tests {
data_dir: tmp.path().to_path_buf(),
..Config::default()
};
- assert_eq!(bridge_bearer(&config), None);
+ assert_eq!(bridge_bearer(&config, &config.server_url).unwrap(), None);
crate::config::store_hook_auth_token(tmp.path(), "aim_stored").unwrap();
- assert_eq!(bridge_bearer(&config).as_deref(), Some("aim_stored"));
+ assert_eq!(
+ bridge_bearer(&config, &config.server_url)
+ .unwrap()
+ .as_deref(),
+ Some("aim_stored")
+ );
config.auth.bearer_token = Some("configured".into());
- assert_eq!(bridge_bearer(&config).as_deref(), Some("configured"));
+ assert_eq!(
+ bridge_bearer(&config, &config.server_url)
+ .unwrap()
+ .as_deref(),
+ Some("configured")
+ );
config.auth.bearer_token = Some(" ".into());
- assert_eq!(bridge_bearer(&config).as_deref(), Some("aim_stored"));
+ assert_eq!(
+ bridge_bearer(&config, &config.server_url)
+ .unwrap()
+ .as_deref(),
+ Some("aim_stored")
+ );
}
/// Adversarial: on a host that runs the server and a client from one data
@@ -696,11 +737,69 @@ mod tests {
let discovered = discovered_root();
assert_eq!(discovered.auth.bearer_token.as_deref(), Some("root-token"));
- assert_eq!(bridge_bearer(&discovered).as_deref(), Some("root-token"));
+ assert_eq!(
+ bridge_bearer(&discovered, &discovered.server_url)
+ .unwrap()
+ .as_deref(),
+ Some("root-token")
+ );
crate::config::store_hook_auth_token(tmp.path(), "aim_user_key").unwrap();
let both = discovered_root();
assert_eq!(both.auth.bearer_token.as_deref(), Some("root-token"));
- assert_eq!(bridge_bearer(&both).as_deref(), Some("aim_user_key"));
+ assert_eq!(
+ bridge_bearer(&both, &both.server_url).unwrap().as_deref(),
+ Some("aim_user_key")
+ );
+ }
+
+ #[test]
+ fn implicit_local_credentials_never_follow_a_server_url_override() {
+ let tmp = tempfile::tempdir().unwrap();
+ let mut config = Config {
+ data_dir: tmp.path().to_path_buf(),
+ server_url: "http://127.0.0.1:49374".into(),
+ ..Config::default()
+ };
+ config.auth.bearer_token = Some("discovered-root".into());
+ config.auth.token_file = Some(crate::config::ResolvedTokenFile {
+ path: tmp.path().join("auth-tokens/default"),
+ loaded: true,
+ discovered: true,
+ });
+ crate::config::store_hook_auth_token(tmp.path(), "stored-user").unwrap();
+
+ assert_eq!(
+ bridge_bearer(&config, "https://remote.example/mcp").unwrap(),
+ None
+ );
+
+ config.auth.token_file = None;
+ assert_eq!(
+ bridge_bearer(&config, "https://remote.example/mcp")
+ .unwrap()
+ .as_deref(),
+ Some("discovered-root"),
+ "an explicitly configured credential remains remote-capable"
+ );
+ }
+
+ #[test]
+ fn malformed_stored_credential_fails_instead_of_escalating_to_root() {
+ let tmp = tempfile::tempdir().unwrap();
+ let mut config = Config {
+ data_dir: tmp.path().to_path_buf(),
+ ..Config::default()
+ };
+ config.auth.bearer_token = Some("discovered-root".into());
+ config.auth.token_file = Some(crate::config::ResolvedTokenFile {
+ path: tmp.path().join("auth-tokens/default"),
+ loaded: true,
+ discovered: true,
+ });
+ std::fs::write(crate::config::hook_auth_token_path_in(tmp.path()), " \n").unwrap();
+
+ let error = bridge_bearer(&config, &config.server_url).unwrap_err();
+ assert!(error.to_string().contains("is blank"), "{error:#}");
}
}
diff --git a/crates/ai-memory-cli/src/commands/restore.rs b/crates/ai-memory-cli/src/commands/restore.rs
index 804a5cbf..0574e33d 100644
--- a/crates/ai-memory-cli/src/commands/restore.rs
+++ b/crates/ai-memory-cli/src/commands/restore.rs
@@ -49,7 +49,7 @@ const CONFIG_FILE: &str = "config.toml";
/// data dir is non-empty without `--force`, the tarball cannot be
/// extracted, or the restored store fails to open. In every one of those
/// cases the live data dir is left as it was.
-pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {
+pub async fn run(config: &Config, args: RestoreArgs) -> Result<()> {
let siblings = sibling_processes();
if !siblings.is_empty() {
bail!(busy_message("restore", &siblings));
@@ -59,7 +59,14 @@ pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {
bail!("source tarball {} not found", args.from.display());
}
- restore_data_dir(&config.data_dir, &args.from, args.force)?;
+ restore_data_dir_with_legacy_pepper(
+ &config.data_dir,
+ &args.from,
+ args.force,
+ config.auth.token_pepper.as_deref(),
+ args.accept_legacy_api_key_pepper,
+ )
+ .await?;
info!("restore complete");
println!(
"restored {} -> {}",
@@ -74,7 +81,18 @@ pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {
/// staged store has opened; the live `wiki/`, `db/` and (when the archive
/// carries one) `config.toml` are then exchanged for the staged copies by
/// rename and rolled back if any step of the exchange fails.
-fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {
+#[cfg(test)]
+async fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {
+ restore_data_dir_with_legacy_pepper(data_dir, from, force, None, false).await
+}
+
+async fn restore_data_dir_with_legacy_pepper(
+ data_dir: &Path,
+ from: &Path,
+ force: bool,
+ token_pepper: Option<&str>,
+ accept_legacy_api_key_pepper: bool,
+) -> Result<()> {
let wiki = data_dir.join("wiki");
let db = data_dir.join("db").join("memory.sqlite");
let occupied = (wiki.is_dir() && std::fs::read_dir(&wiki)?.next().is_some()) || db.is_file();
@@ -96,7 +114,15 @@ fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {
let staging = data_dir.join(format!(".restore-staging-{stamp}"));
let previous = data_dir.join(format!(".restore-previous-{stamp}"));
- let outcome = stage_then_swap(data_dir, from, &staging, &previous);
+ let outcome = stage_then_swap(
+ data_dir,
+ from,
+ &staging,
+ &previous,
+ token_pepper,
+ accept_legacy_api_key_pepper,
+ )
+ .await;
// The staging dir is scratch in every outcome: on success its contents
// were moved into place, on failure the live data was never touched.
if staging.exists()
@@ -111,7 +137,14 @@ fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {
outcome
}
-fn stage_then_swap(data_dir: &Path, from: &Path, staging: &Path, previous: &Path) -> Result<()> {
+async fn stage_then_swap(
+ data_dir: &Path,
+ from: &Path,
+ staging: &Path,
+ previous: &Path,
+ token_pepper: Option<&str>,
+ accept_legacy_api_key_pepper: bool,
+) -> Result<()> {
std::fs::create_dir(staging)
.with_context(|| format!("creating staging dir {}", staging.display()))?;
@@ -130,7 +163,36 @@ fn stage_then_swap(data_dir: &Path, from: &Path, staging: &Path, previous: &Path
// live is touched. Dropping the store joins the writer thread and
// closes every connection, so the directory can be renamed afterwards
// on Windows as well.
- drop(Store::open(staging).context("opening restored store")?);
+ let store = Store::open(staging).context("opening restored store")?;
+ let has_api_credentials = store.reader.api_credentials_exist().await?;
+ let has_pepper_verifier = store
+ .reader
+ .api_credential_pepper_verifier()
+ .await?
+ .is_some();
+ if has_api_credentials && !has_pepper_verifier {
+ if !accept_legacy_api_key_pepper {
+ bail!(
+ "the backup contains API keys but predates token-pepper verification; restore the original [auth].token_pepper and rerun with --accept-legacy-api-key-pepper to confirm it (the live data was not changed)"
+ );
+ }
+ let pepper = token_pepper
+ .filter(|value| !value.trim().is_empty())
+ .context(
+ "--accept-legacy-api-key-pepper requires the original non-blank [auth].token_pepper",
+ )?;
+ let verifier = ai_memory_store::password::hash_password(pepper.to_owned())
+ .await
+ .context("binding the confirmed legacy API-key pepper")?;
+ if !store
+ .writer
+ .bind_api_credential_pepper_verifier(verifier)
+ .await?
+ {
+ bail!("the restored API-key pepper verifier could not be bound");
+ }
+ }
+ drop(store);
// 3. Exchange the live directories for the staged ones.
swap_into_place(data_dir, staging, previous)?;
@@ -286,6 +348,7 @@ fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()>
#[cfg(test)]
mod tests {
use super::*;
+ use ai_memory_core::{ApiCredentialId, NewUser, UserRole};
fn archive_with_entry(path: &str, entry_type: tar::EntryType) -> Vec<u8> {
let mut bytes = Vec::new();
@@ -567,6 +630,48 @@ mod tests {
std::fs::read(tmp.path().join("db/memory.sqlite")).unwrap()
}
+ async fn legacy_api_key_sqlite_bytes() -> Vec<u8> {
+ let tmp = tempfile::TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let user_id = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "legacy-restore-user".into(),
+ name: None,
+ email: None,
+ },
+ UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ store
+ .writer
+ .create_api_credential(
+ ApiCredentialId::new(),
+ user_id,
+ "legacy-key".into(),
+ [0xA5; 32],
+ Some("...test".into()),
+ )
+ .await
+ .unwrap();
+ assert!(
+ store
+ .reader
+ .api_credential_pepper_verifier()
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let snapshot = tmp.path().join("legacy-snapshot.sqlite");
+ store.reader.snapshot_to(snapshot.clone()).await.unwrap();
+ drop(store);
+ std::fs::read(snapshot).unwrap()
+ }
+
/// A gzipped tarball holding the given regular files.
fn gz_tarball(entries: &[(&str, &[u8])]) -> Vec<u8> {
use std::io::Write as _;
@@ -604,14 +709,16 @@ mod tests {
path
}
- #[test]
- fn restore_force_keeps_live_data_when_the_tarball_is_not_a_gzip_stream() {
+ #[tokio::test]
+ async fn restore_force_keeps_live_data_when_the_tarball_is_not_a_gzip_stream() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
let from = write_tarball(scratch.path(), "bad.tar.gz", b"this is not a gzip stream");
- let err = restore_data_dir(data.path(), &from, true).unwrap_err();
+ let err = restore_data_dir(data.path(), &from, true)
+ .await
+ .unwrap_err();
assert!(
format!("{err:#}").contains("extracting"),
@@ -620,15 +727,17 @@ mod tests {
assert_live_data_untouched(data.path());
}
- #[test]
- fn restore_force_keeps_live_data_when_the_tarball_is_truncated() {
+ #[tokio::test]
+ async fn restore_force_keeps_live_data_when_the_tarball_is_truncated() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
let whole = good_archive();
let from = write_tarball(scratch.path(), "cut.tar.gz", &whole[..whole.len() / 2]);
- let err = restore_data_dir(data.path(), &from, true).unwrap_err();
+ let err = restore_data_dir(data.path(), &from, true)
+ .await
+ .unwrap_err();
assert!(
format!("{err:#}").contains("extracting"),
@@ -637,8 +746,8 @@ mod tests {
assert_live_data_untouched(data.path());
}
- #[test]
- fn restore_force_keeps_live_data_when_an_entry_is_outside_the_allowed_layout() {
+ #[tokio::test]
+ async fn restore_force_keeps_live_data_when_an_entry_is_outside_the_allowed_layout() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
@@ -655,7 +764,9 @@ mod tests {
]),
);
- let err = restore_data_dir(data.path(), &from, true).unwrap_err();
+ let err = restore_data_dir(data.path(), &from, true)
+ .await
+ .unwrap_err();
assert!(
format!("{err:#}").contains("unexpected path"),
@@ -664,8 +775,8 @@ mod tests {
assert_live_data_untouched(data.path());
}
- #[test]
- fn restore_force_keeps_live_data_when_the_restored_store_cannot_open() {
+ #[tokio::test]
+ async fn restore_force_keeps_live_data_when_the_restored_store_cannot_open() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
@@ -678,7 +789,9 @@ mod tests {
]),
);
- let err = restore_data_dir(data.path(), &from, true).unwrap_err();
+ let err = restore_data_dir(data.path(), &from, true)
+ .await
+ .unwrap_err();
assert!(
format!("{err:#}").contains("opening restored store"),
@@ -687,14 +800,16 @@ mod tests {
assert_live_data_untouched(data.path());
}
- #[test]
- fn restore_refuses_a_populated_data_dir_without_force() {
+ #[tokio::test]
+ async fn restore_refuses_a_populated_data_dir_without_force() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());
- let err = restore_data_dir(data.path(), &from, false).unwrap_err();
+ let err = restore_data_dir(data.path(), &from, false)
+ .await
+ .unwrap_err();
assert!(
err.to_string().contains("pass --force"),
@@ -703,14 +818,14 @@ mod tests {
assert_live_data_untouched(data.path());
}
- #[test]
- fn restore_force_replaces_the_live_data_with_the_archive() {
+ #[tokio::test]
+ async fn restore_force_replaces_the_live_data_with_the_archive() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());
- restore_data_dir(data.path(), &from, true).unwrap();
+ restore_data_dir(data.path(), &from, true).await.unwrap();
assert_eq!(
std::fs::read(data.path().join("wiki/default/project/notes/new.md")).unwrap(),
@@ -744,8 +859,8 @@ mod tests {
drop(Store::open(data.path()).unwrap());
}
- #[test]
- fn restore_keeps_the_live_config_when_the_archive_carries_none() {
+ #[tokio::test]
+ async fn restore_keeps_the_live_config_when_the_archive_carries_none() {
let data = tempfile::TempDir::new().unwrap();
seed_live_data(data.path());
let scratch = tempfile::TempDir::new().unwrap();
@@ -759,7 +874,7 @@ mod tests {
]),
);
- restore_data_dir(data.path(), &from, true).unwrap();
+ restore_data_dir(data.path(), &from, true).await.unwrap();
assert_eq!(
std::fs::read(data.path().join("config.toml")).unwrap(),
@@ -772,13 +887,13 @@ mod tests {
assert!(restore_scratch_dirs(data.path()).is_empty());
}
- #[test]
- fn restore_into_an_empty_data_dir_needs_no_force() {
+ #[tokio::test]
+ async fn restore_into_an_empty_data_dir_needs_no_force() {
let data = tempfile::TempDir::new().unwrap();
let scratch = tempfile::TempDir::new().unwrap();
let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());
- restore_data_dir(data.path(), &from, false).unwrap();
+ restore_data_dir(data.path(), &from, false).await.unwrap();
assert_eq!(
std::fs::read(data.path().join("wiki/default/project/notes/new.md")).unwrap(),
@@ -787,4 +902,56 @@ mod tests {
assert!(data.path().join("db/memory.sqlite").is_file());
assert!(restore_scratch_dirs(data.path()).is_empty());
}
+
+ #[tokio::test]
+ async fn legacy_api_key_restore_requires_original_pepper_confirmation() {
+ let data = tempfile::TempDir::new().unwrap();
+ seed_live_data(data.path());
+ let scratch = tempfile::TempDir::new().unwrap();
+ let db = legacy_api_key_sqlite_bytes().await;
+ let from = write_tarball(
+ scratch.path(),
+ "legacy.tar.gz",
+ &gz_tarball(&[("db/memory.sqlite", db.as_slice())]),
+ );
+
+ let refused = restore_data_dir_with_legacy_pepper(
+ data.path(),
+ &from,
+ true,
+ Some("original-pepper"),
+ false,
+ )
+ .await
+ .unwrap_err();
+ assert!(
+ refused
+ .to_string()
+ .contains("--accept-legacy-api-key-pepper"),
+ "unexpected error: {refused:#}"
+ );
+ assert_live_data_untouched(data.path());
+
+ restore_data_dir_with_legacy_pepper(
+ data.path(),
+ &from,
+ true,
+ Some("original-pepper"),
+ true,
+ )
+ .await
+ .unwrap();
+ let restored = Store::open(data.path()).unwrap();
+ let verifier = restored
+ .reader
+ .api_credential_pepper_verifier()
+ .await
+ .unwrap()
+ .expect("confirmed pepper must be sealed into the restored database");
+ assert!(
+ ai_memory_store::password::verify_password("original-pepper".into(), verifier)
+ .await
+ .unwrap()
+ );
+ }
}
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index ea20193f..7445f72e 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -188,6 +188,7 @@ struct AutoSessionCandidate {
#[derive(Debug, Default)]
struct HeartbeatHealth {
consecutive_failures: u64,
+ last_failure_kind: Option<HeartbeatFailureKind>,
/// Set while the harness owns the terminal: a line written to stderr then
/// lands inside its TUI (the prompt box, mid-render), so notices are held
/// until the harness exits.
@@ -232,19 +233,27 @@ impl HeartbeatHealth {
lines
}
- fn record_failure(&mut self) -> bool {
- let first = self.consecutive_failures == 0;
+ fn record_failure(&mut self, kind: HeartbeatFailureKind) -> bool {
+ let changed = self.last_failure_kind != Some(kind);
self.consecutive_failures = self.consecutive_failures.saturating_add(1);
- first
+ self.last_failure_kind = Some(kind);
+ changed
}
fn record_success(&mut self) -> bool {
let recovered = self.consecutive_failures > 0;
self.consecutive_failures = 0;
+ self.last_failure_kind = None;
recovered
}
}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum HeartbeatFailureKind {
+ Unreachable,
+ Rejected,
+}
+
fn resolve_opencode_for_launch(
requested: Option<RunHarnessChoice>,
executable: Option<&OsStr>,
@@ -2134,13 +2143,21 @@ async fn capture_interrupts(interrupted: CancellationToken) {
/// finished, cancelled, or expired by a later prepare. Reporting it as an
/// outage sends the operator looking for a server that never went away.
fn heartbeat_failure_notice(error: &anyhow::Error) -> String {
+ if heartbeat_failure_kind(error) == HeartbeatFailureKind::Rejected {
+ format!("ai-memory: managed workstream heartbeat rejected: {error:#}; retrying quietly")
+ } else {
+ "ai-memory: server unavailable; managed workstream heartbeat will retry quietly".to_string()
+ }
+}
+
+fn heartbeat_failure_kind(error: &anyhow::Error) -> HeartbeatFailureKind {
if error
.chain()
.any(|cause| cause.downcast_ref::<ServerResponseError>().is_some())
{
- format!("ai-memory: managed workstream heartbeat rejected: {error:#}; retrying quietly")
+ HeartbeatFailureKind::Rejected
} else {
- "ai-memory: server unavailable; managed workstream heartbeat will retry quietly".to_string()
+ HeartbeatFailureKind::Unreachable
}
}
@@ -2171,7 +2188,7 @@ async fn send_managed_heartbeat_with_timeout(
);
}
Ok(()) => {}
- Err(error) if health.record_failure() => {
+ Err(error) if health.record_failure(heartbeat_failure_kind(error)) => {
tracing::debug!(error = %error, "managed workstream heartbeat became unavailable");
health.notify(heartbeat_failure_notice(error));
}
@@ -5861,12 +5878,13 @@ mod tests {
fn heartbeat_health_reports_each_outage_and_recovery_once() {
let mut health = HeartbeatHealth::default();
- assert!(health.record_failure());
- assert!(!health.record_failure());
- assert!(!health.record_failure());
+ assert!(health.record_failure(HeartbeatFailureKind::Unreachable));
+ assert!(!health.record_failure(HeartbeatFailureKind::Unreachable));
+ assert!(health.record_failure(HeartbeatFailureKind::Rejected));
+ assert!(!health.record_failure(HeartbeatFailureKind::Rejected));
assert!(health.record_success());
assert!(!health.record_success());
- assert!(health.record_failure());
+ assert!(health.record_failure(HeartbeatFailureKind::Unreachable));
}
#[test]
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 215963ca..89467b16 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -352,10 +352,16 @@ async fn validate_api_credential_pepper_binding(
let verifier = ai_memory_store::password::hash_password(pepper.to_owned())
.await
.context("binding the configured API credential pepper")?;
- store
+ let bound = store
.writer
- .set_api_credential_pepper_verifier(verifier)
+ .bind_api_credential_pepper_verifier(verifier)
.await?;
+ if !bound {
+ anyhow::bail!(
+ "API credentials were added while binding [auth].token_pepper; restart so the \
+ server can verify the final credential state"
+ );
+ }
Ok(())
}
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 77b92eae..3cc8f53e 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -3416,11 +3416,42 @@ pub fn hook_auth_header_path_in(data_dir: &Path) -> PathBuf {
/// Propagates IO failures from creating the data dir or writing either file.
pub fn store_hook_auth_token(data_dir: &Path, token: &str) -> std::io::Result<()> {
std::fs::create_dir_all(data_dir)?;
- write_secret(&hook_auth_token_path_in(data_dir), token)?;
- write_secret(
- &hook_auth_header_path_in(data_dir),
- &format!("Authorization: Bearer {token}\n"),
- )
+ let token_path = hook_auth_token_path_in(data_dir);
+ let header_path = hook_auth_header_path_in(data_dir);
+ let previous_token = read_optional_secret_bytes(&token_path)?;
+ let previous_header = read_optional_secret_bytes(&header_path)?;
+
+ write_secret(&token_path, token)?;
+ if let Err(error) = write_secret(&header_path, &format!("Authorization: Bearer {token}\n")) {
+ let token_rollback = restore_secret_bytes(&token_path, previous_token.as_deref());
+ let header_rollback = restore_secret_bytes(&header_path, previous_header.as_deref());
+ if let Err(rollback) = token_rollback.and(header_rollback) {
+ return Err(std::io::Error::other(format!(
+ "writing hook credential pair failed ({error}); rollback also failed ({rollback})"
+ )));
+ }
+ return Err(error);
+ }
+ Ok(())
+}
+
+fn read_optional_secret_bytes(path: &Path) -> std::io::Result<Option<Vec<u8>>> {
+ match std::fs::read(path) {
+ Ok(bytes) => Ok(Some(bytes)),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+ Err(error) => Err(error),
+ }
+}
+
+fn restore_secret_bytes(path: &Path, previous: Option<&[u8]>) -> std::io::Result<()> {
+ match previous {
+ Some(bytes) => write_secret_bytes(path, bytes),
+ None => match std::fs::remove_file(path) {
+ Ok(()) => Ok(()),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+ Err(error) => Err(error),
+ },
+ }
}
/// Remove a persisted bearer pair. Absent files are not an error.
@@ -3460,6 +3491,10 @@ pub(crate) fn read_trimmed_secret(path: &Path) -> Option<String> {
/// The mode is set on the handle before any bytes are written on Unix, so the
/// secret is never briefly world-readable between `create` and `set_permissions`.
fn write_secret(path: &Path, contents: &str) -> std::io::Result<()> {
+ write_secret_bytes(path, contents.as_bytes())
+}
+
+fn write_secret_bytes(path: &Path, contents: &[u8]) -> std::io::Result<()> {
#[cfg(unix)]
{
use std::io::Write as _;
@@ -3470,7 +3505,7 @@ fn write_secret(path: &Path, contents: &str) -> std::io::Result<()> {
.truncate(true)
.mode(0o600)
.open(path)?;
- file.write_all(contents.as_bytes())
+ file.write_all(contents)
}
#[cfg(not(unix))]
{
@@ -3505,7 +3540,15 @@ fn canonicalise_or_keep(p: &Path) -> PathBuf {
{
return canon_parent.join(name);
}
- p.to_path_buf()
+ if p.is_absolute() {
+ return p.to_path_buf();
+ }
+ // A nested path may have no existing ancestor beyond the current
+ // directory yet. Keep the invocation-time meaning when this path is later
+ // embedded in an MCP entry launched from an unrelated project directory.
+ std::env::current_dir()
+ .map(|cwd| cwd.join(p))
+ .unwrap_or_else(|_| p.to_path_buf())
}
/// Normalize home for prefix-match comparisons: accept either slash spelling,
@@ -3606,6 +3649,25 @@ mod tests {
);
}
+ #[test]
+ fn an_invalid_header_target_cannot_partially_replace_the_token() {
+ let tmp = TempDir::new().unwrap();
+ let dd = tmp.path().join("data");
+ std::fs::create_dir_all(hook_auth_header_path_in(&dd)).unwrap();
+
+ let error = store_hook_auth_token(&dd, "must-not-stick").unwrap_err();
+ assert_ne!(error.kind(), std::io::ErrorKind::NotFound);
+ assert!(!hook_auth_token_path_in(&dd).exists());
+ }
+
+ #[test]
+ fn a_nested_nonexistent_relative_data_dir_becomes_absolute() {
+ let relative = Path::new("target/nonexistent-ai-memory-test/data");
+ let resolved = canonicalise_or_keep(relative);
+ assert!(resolved.is_absolute(), "{}", resolved.display());
+ assert!(resolved.ends_with(relative));
+ }
+
/// Absent, empty, and whitespace-only files all read as "no token" rather
/// than as an empty bearer, which would send `Authorization: Bearer `.
#[test]
diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rs
index ed5dbf88..df30de1b 100644
--- a/crates/ai-memory-cli/src/lib.rs
+++ b/crates/ai-memory-cli/src/lib.rs
@@ -148,7 +148,7 @@ pub async fn run() -> Result<()> {
Command::Backup(args) => commands::backup::run(&config, args).await,
Command::BackupAgents(args) => commands::backup_agents::run(&config, args),
Command::ExportOkf(args) => commands::export_okf::run(&config, args).await,
- Command::Restore(args) => commands::restore::run(&config, args),
+ Command::Restore(args) => commands::restore::run(&config, args).await,
Command::RestoreAgents(args) => commands::restore_agents::run(&config, args),
Command::Reindex(args) => commands::reindex::run(&config, args).await,
Command::InstallHooks(args) => commands::install_hooks::run(&config, args),
diff --git a/crates/ai-memory-store/src/api_credentials.rs b/crates/ai-memory-store/src/api_credentials.rs
index bc7048fa..8d16c175 100644
--- a/crates/ai-memory-store/src/api_credentials.rs
+++ b/crates/ai-memory-store/src/api_credentials.rs
@@ -275,24 +275,26 @@ pub fn api_credential_pepper_verifier(conn: &Connection) -> StoreResult<Option<S
.map_err(StoreError::from)
}
-/// Insert or replace the verifier for the configured native-key pepper.
+/// Bind the verifier for the configured native-key pepper.
///
-/// The caller decides whether replacement is allowed after checking whether
-/// any credentials exist. Keeping that policy above this storage primitive
-/// lets startup perform the expensive Argon2id verification off the writer
-/// thread.
+/// An upgraded database may have credentials but no verifier yet, so the
+/// initial insert is always allowed. Once a verifier exists, replacement is
+/// allowed only while `api_credentials` is empty. Enforcing that condition in
+/// this writer-thread statement keeps a future caller from rotating the
+/// verifier out from under existing hashes.
///
/// # Errors
/// SQL failures.
-pub fn set_api_credential_pepper_verifier(conn: &Connection, verifier: &str) -> StoreResult<()> {
- conn.execute(
+pub fn bind_api_credential_pepper_verifier(conn: &Connection, verifier: &str) -> StoreResult<bool> {
+ let changed = conn.execute(
"INSERT INTO api_credential_pepper_state (singleton, verifier, updated_at) \
VALUES (1, ?1, ?2) \
ON CONFLICT(singleton) DO UPDATE SET \
- verifier = excluded.verifier, updated_at = excluded.updated_at",
+ verifier = excluded.verifier, updated_at = excluded.updated_at \
+ WHERE NOT EXISTS (SELECT 1 FROM api_credentials)",
params![verifier, Timestamp::now().as_microsecond()],
)?;
- Ok(())
+ Ok(changed == 1)
}
fn row_to_credential(row: &rusqlite::Row<'_>) -> rusqlite::Result<ApiCredential> {
@@ -480,6 +482,45 @@ mod tests {
assert_eq!(cols, 0, "V79 drops the 1.x token columns");
}
+ #[test]
+ fn pepper_verifier_can_bind_legacy_keys_but_cannot_rotate_under_keys() {
+ let mut conn = Connection::open_in_memory().unwrap();
+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+ crate::migrations::run(&mut conn).unwrap();
+ let mut user = NewUser {
+ username: "pepper-owner".into(),
+ name: None,
+ email: None,
+ };
+ user.validate().unwrap();
+ let user_id =
+ users::insert_human_user(&conn, &user, UserRole::User, Some("phc"), false).unwrap();
+ let credential_id = ApiCredentialId::new();
+ insert_api_credential(
+ &conn,
+ credential_id,
+ user_id,
+ "legacy",
+ &[7_u8; TOKEN_HASH_LEN],
+ None,
+ )
+ .unwrap();
+
+ assert!(bind_api_credential_pepper_verifier(&conn, "original-phc").unwrap());
+ assert!(!bind_api_credential_pepper_verifier(&conn, "replacement-phc").unwrap());
+ assert_eq!(
+ api_credential_pepper_verifier(&conn).unwrap().as_deref(),
+ Some("original-phc")
+ );
+
+ conn.execute("DELETE FROM api_credentials", []).unwrap();
+ assert!(bind_api_credential_pepper_verifier(&conn, "replacement-phc").unwrap());
+ assert_eq!(
+ api_credential_pepper_verifier(&conn).unwrap().as_deref(),
+ Some("replacement-phc")
+ );
+ }
+
fn column_count(conn: &Connection, table: &str, column: &str) -> i64 {
conn.query_row(
"SELECT COUNT(*) FROM pragma_table_info(?1) WHERE name = ?2",
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index d56783c7..d90ebee0 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -719,9 +719,9 @@ pub(crate) enum WriteCmd {
id: ApiCredentialId,
reply: oneshot::Sender<StoreResult<bool>>,
},
- SetApiCredentialPepperVerifier {
+ BindApiCredentialPepperVerifier {
verifier: String,
- reply: oneshot::Sender<StoreResult<()>>,
+ reply: oneshot::Sender<StoreResult<bool>>,
},
TouchUserLastSeen {
user_id: UserId,
@@ -3245,9 +3245,9 @@ impl WriterHandle {
///
/// # Errors
/// Writer closed / SQL.
- pub async fn set_api_credential_pepper_verifier(&self, verifier: String) -> StoreResult<()> {
+ pub async fn bind_api_credential_pepper_verifier(&self, verifier: String) -> StoreResult<bool> {
let (tx, rx) = oneshot::channel();
- self.send(WriteCmd::SetApiCredentialPepperVerifier {
+ self.send(WriteCmd::BindApiCredentialPepperVerifier {
verifier,
reply: tx,
})
@@ -4783,9 +4783,9 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = api_credentials::touch_api_credential(&conn, id);
send_or_warn(reply, result, "touch_api_credential");
}
- WriteCmd::SetApiCredentialPepperVerifier { verifier, reply } => {
- let result = api_credentials::set_api_credential_pepper_verifier(&conn, &verifier);
- send_or_warn(reply, result, "set_api_credential_pepper_verifier");
+ WriteCmd::BindApiCredentialPepperVerifier { verifier, reply } => {
+ let result = api_credentials::bind_api_credential_pepper_verifier(&conn, &verifier);
+ send_or_warn(reply, result, "bind_api_credential_pepper_verifier");
}
WriteCmd::TouchUserLastSeen { user_id, reply } => {
let result = users::touch_user_last_seen(&conn, user_id);
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index afd52f16..0b943138 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -731,9 +731,11 @@ cwd parameters use their canonical names.
`ai-memory mcp-bridge` is a transport adapter, not a second tool
implementation. It serves the upstream tool catalogue over local stdio and
delegates tool calls to the configured HTTP server through rmcp's client
-transport, authenticating with the bearer `Config::load` resolved, so the
-server keeps the same auth, scope resolver, and tool handlers as direct HTTP
-clients. It has two modes, chosen by the entry that launches it:
+transport. It uses the bearer `Config::load` resolved, or the install's stored
+hook key before a loopback-only discovered root key. Implicit install-local
+keys are accepted only for that install's configured endpoint. The server
+therefore keeps the same auth, scope resolver, and tool handlers as direct
+HTTP clients. It has two modes, chosen by the entry that launches it:
- session-aware (Claude Code, `install-mcp --client claude-code
--session-aware`, and every Claude Code entry on a token-file install; and
diff --git a/docs/backup.md b/docs/backup.md
index 80409bf4..02ef3ee2 100644
--- a/docs/backup.md
+++ b/docs/backup.md
@@ -150,24 +150,25 @@ Two caveats:
synthesized. Treat the remote the same way you treat any project source:
private repository, restrictive access controls.
-## Backing up the whole data dir (mirror + push)
+## Backing up a wiki/config mirror plus SQLite snapshot
-For a full-install backup (wiki, raw ledger, sanitized config), the
-supported pattern is a scheduled rsync into a mirror git repository, followed
-by a git push. This avoids running git operations against the live wiki
-repository (which the server writes to) while still giving you a single
-remote with the full recoverable state.
+For a scheduled off-site copy, mirror the wiki and selected config into a
+private git repository, then ask the running server for a separate consistent
+SQLite snapshot. The mirror is intentionally incomplete; the snapshot carries
+the DB-only state that `reindex` cannot reconstruct. Either copy may contain
+secrets or private memory and must be protected accordingly.
A worked example lives at
[`docs/examples/backup/`](examples/backup/README.md) and consists of:
- `ai-memory-snapshot.sh`: an idempotent rsync + `git commit && git push` +
- tarball script driven by six environment variables.
+ online `ai-memory backup` script driven by environment variables.
- `ai-memory-backup.service`: a `systemd --user` oneshot unit that runs it.
- `ai-memory-backup.timer`: a daily user timer with a randomised delay and
`Persistent=true` so a missed run after a reboot still fires.
- `.gitignore`: an exclusion list to drop into the root of the mirror
- repository so derived state and secrets never land in commits.
+ repository so derived state and common standalone secret files do not land
+ in commits. It cannot remove secrets stored inline in `config.toml`.
The high-level flow, one invocation per day (adjust the timer for a different
cadence):
@@ -182,9 +183,10 @@ cadence):
changed; skip if there is no delta.
4. `git push origin main` with a timeout so a hung network does not block the
next run.
-5. `tar czf $TARBALL_DIR/ai-memory-$(date +%F).tar.gz` a copy of the same
- tree, so the DB and models can be recovered without a `reindex` after a
- catastrophic disk loss.
+5. Run `ai-memory backup --to
+ $TARBALL_DIR/ai-memory-$(date +%F).tar.gz` so SQLite is copied through its
+ online backup API rather than racing the live WAL. Models are not included;
+ redownload them after recovery.
6. Rotate old tarballs and old script logs on a retention window (30 days by
default).
@@ -219,11 +221,14 @@ out-of-scope for v1). What that means in practice:
- **Least-privilege push credential.** Prefer an SSH deploy key or a
fine-grained personal-access token scoped to the mirror repository only.
Rotate on the same cadence you rotate other long-lived push credentials.
-- **Explicit secret exclusion.** The example script rejects any file matching
+- **Explicit secret exclusion.** The example script excludes files matching
`SECRET_EXCLUDES` (`*.env`, `auth.json`, `.secrets`, `*.pem`, `*.key`, `*.crt` by default), and the
suggested mirror-repo `.gitignore` matches the same set. Add anything else
install-specific (private CA bundles, host-side certificates, cloud
- credential files) to both lists.
+ credential files) to both lists. These path rules do not inspect TOML:
+ `[auth]` tokens, `token_pepper`, or sensitive LLM headers stored inline in
+ `config.toml` will be committed. Remove them from the mirror or encrypt and
+ access-control the repository as a secret store.
- **Encryption at rest is out of scope for ai-memory.** If your threat model
requires it, either put the mirror on an encrypted remote (`git-crypt`,
GitLab's group-level encryption, a self-hosted Gitea over TLS with disk
diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.md
index b94527f9..30e639d8 100644
--- a/docs/design-marketplace-plugins.md
+++ b/docs/design-marketplace-plugins.md
@@ -326,7 +326,7 @@ install.
| Server URL | `userConfig.server_url` (string) | empty (shipped; proposed `http://127.0.0.1:49374`) | Read by the launcher from `CLAUDE_PLUGIN_OPTION_SERVER_URL`; MCP gets `${user_config.server_url}`. Empty means the `server_url` of the ai-memory config, for hooks and MCP alike |
| Binary path | `userConfig.ai_memory_bin` (string) | `ai-memory` | For installs off `PATH` |
| Data dir | `userConfig.data_dir` (string) | empty | Only for a non-default data dir |
-| Token | **none in the plugin** | — | Hooks read `<data_dir>/auth-token`, the OIDC `auth.json` or a server profile; `mcp-bridge` reads the bearer `Config::load` resolves. Same files `setup`, `install-hooks --auth-token` and `auth login` already write |
+| Token | **none in the plugin** | — | Hooks read `<data_dir>/auth-token`, the OIDC `auth.json` or a server profile; `mcp-bridge` uses configured auth, then the same stored hook key, then loopback-only discovered root auth. Implicit install-local keys never follow an endpoint override. Same files `setup`, `install-hooks --auth-token` and `auth login` already write |
| Project override, capture mode, `ignore_paths`, briefing, server routing | `.ai-memory.toml` marker, persisted capture mode, `servers.toml` profiles | as today | The native hook already enforces all of these. Nothing is duplicated into plugin settings |
Keeping the token out of the plugin keeps one credential store for hooks, MCP
diff --git a/docs/examples/backup/.gitignore b/docs/examples/backup/.gitignore
index 4c3cde78..50ef0796 100644
--- a/docs/examples/backup/.gitignore
+++ b/docs/examples/backup/.gitignore
@@ -7,10 +7,11 @@
# _prompts pages, since those are irreplaceable.
# - Keep raw/ if you want the untouched observation ledger, drop it if you
# want a small repository.
-# - Never commit derived state (db/) or downloaded weights (models/), and
-# never commit secrets.
+# - Never commit derived state (db/) or downloaded weights (models/).
+# - Exclude common standalone secret files. This cannot redact credentials
+# stored inline in config.toml; omit that file or encrypt the repository.
-# Secrets — belt and braces alongside the rsync SECRET_EXCLUDES list.
+# Common standalone secrets — belt and braces alongside SECRET_EXCLUDES.
config/*.env
config/**/*.env
config/auth.json
diff --git a/docs/examples/backup/README.md b/docs/examples/backup/README.md
index fc58ad27..d4903c70 100644
--- a/docs/examples/backup/README.md
+++ b/docs/examples/backup/README.md
@@ -1,8 +1,9 @@
# Remote git backup example
Sample scripts + unit files that push an ai-memory install to a remote git
-repository on a daily cadence, keeping a tarball on a second location for the
-SQLite index and models cache that the mirror repo deliberately excludes.
+repository on a daily cadence, keeping an online `ai-memory backup` snapshot
+on a second location for the SQLite state that the mirror repo deliberately
+excludes. Models remain redownloadable and are not backed up.
See [`docs/backup.md`](../../backup.md) for the walkthrough. The pieces in this
directory are:
@@ -77,4 +78,9 @@ private repository, a fine-grained token scoped to that one repo (or an SSH
deploy key), and rotate credentials the same way you rotate any other
long-lived push credential. The script never commits files matched by
`SECRET_EXCLUDES` (default: `*.env`, `auth.json`, `.secrets`, `*.pem`, `*.key`, `*.crt`); the mirror
-repo's `.gitignore` catches anything the rsync exclude missed.
+repo's `.gitignore` catches anything the rsync exclude missed. The separate
+online snapshot may include `<data_dir>/config.toml`, including secrets stored
+inline there, and always contains private memory data. The git mirror can also
+include inline secrets from the copied config directory because filename globs
+cannot redact TOML values. Inspect or encrypt both outputs and protect them as
+secret-bearing artifacts.
diff --git a/docs/examples/backup/ai-memory-snapshot.sh b/docs/examples/backup/ai-memory-snapshot.sh
index f7d7f09b..8480d803 100644
--- a/docs/examples/backup/ai-memory-snapshot.sh
+++ b/docs/examples/backup/ai-memory-snapshot.sh
@@ -6,10 +6,8 @@
# excluding derived state and secrets (see .gitignore in this dir).
# 2. commit + push the mirror to a remote git repository when anything
# changed.
-# 3. write a compressed tarball of the same tree to a second location
-# (a mounted external disk, a network share, or on WSL2 the Windows-side
-# filesystem) so the SQLite index can be recovered from disk even if the
-# remote repository is unreachable.
+# 3. ask the running server for a consistent online backup (wiki + SQLite +
+# data-dir config.toml) and write it to a second location.
#
# Assumptions:
# - You already ran `git init && git remote add origin <url>` inside
@@ -19,7 +17,7 @@
# - $DATA_SRC is the ai-memory data dir (`ai-memory status` prints it) and
# $CFG_SRC is where your provider env-file lives.
#
-# Configure these four variables for your host, or export them from the
+# Configure these variables for your host, or export them from the
# systemd unit's Environment= lines. Sample values are commented out.
: "${REPO_DIR:=$HOME/ai-memory-backup}" # local mirror checkout, `git init`'d and pointed at a remote
: "${DATA_SRC:=$HOME/.local/share/ai-memory}" # ai-memory data dir
@@ -87,23 +85,9 @@ else
timeout 180 git push origin "$(git rev-parse --abbrev-ref HEAD)" 2>&1 | tail -10
fi
-echo "--- tarball to second location ---"
+echo "--- online data snapshot to second location ---"
tarball="$TARBALL_DIR/ai-memory-$stamp.tar.gz"
-tar_excludes=(
- --exclude=.git
- --exclude=models
- --exclude=db
- --exclude=logs
- --exclude=.serve.lock
-)
-for glob in $SECRET_EXCLUDES; do
- tar_excludes+=(--exclude="$glob")
-done
-# Use paths relative to $HOME so the archive is portable across usernames.
-tar czf "$tarball" "${tar_excludes[@]}" \
- -C "$HOME" \
- "${DATA_SRC#$HOME/}" \
- "${CFG_SRC#$HOME/}"
+ai-memory --data-dir "$DATA_SRC" backup --to "$tarball"
echo "tarball: $(ls -lh "$tarball" | awk '{print $5, $9}')"
echo "--- rotate tarballs (retention: ${TARBALL_RETENTION_DAYS}d) ---"
diff --git a/docs/install.md b/docs/install.md
index 4733d71a..74ae8731 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1025,8 +1025,9 @@ opt-in**: enable the server first, then the client:
The client sanitizes (built-in patterns) and truncates the excerpt before it
touches the spool or wire; the server re-scrubs with its `[sanitize]` patterns
before storing. If either side is off, or the marker is malformed, the Stop
-stays empty. Re-running `install-hooks` without `--capture-assistant` removes
-the flag (idempotent). `--capture-assistant` is Claude Code, Codex and
+stays empty. Re-running `install-hooks` without `--capture-assistant` preserves
+an existing opt-in. To remove it, run `ai-memory uninstall --only hooks
+--apply --yes`, then reinstall without the flag. `--capture-assistant` is Claude Code, Codex and
OpenCode 2 (`--agent opencode2`) on a native hook platform only; on any other agent or the script fallback the
installer refuses it rather than enabling something that cannot take effect. Assistant text is
privacy-sensitive. Read the `SECURITY.md` notes on what it can contain and where
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 962066ce..bc8d1c73 100644
--- a/docs/lifecycle-ops.md
+++ b/docs/lifecycle-ops.md
@@ -624,7 +624,7 @@ deletes: its `sessions`, `observations`, and `handoffs` (the raw episodic
capture log), its managed workstreams with their native sessions, runs,
events and `raw/workstreams/` segments, the cross-project messages it sent
or received, auto-improvement and profile-harvest state, session-consolidation
-jobs, ingest deduplication keys, entities, page feedback, purge tombstones and
+jobs, ingest deduplication keys, entities, page feedback, per-session purge tombstones and
project grants. The moved pages start a fresh supersession chain (the real
page history lives in the wiki's git mirror). The append-only audit trail
remains, with references to the removed source ids. The `true-move` path has
@@ -1142,10 +1142,13 @@ move: `ai-memory backup` first, then proceed.
This tarball is an online **data snapshot**, not a complete host image. It
intentionally excludes `auth-tokens/`, the hook-side `auth-token` and
`auth-header` files, `raw/`, logs, models, and a config passed from outside the
-data dir with `--config`. That keeps bearer credentials out of an archive that
-is commonly copied between machines, and avoids racing the actively appended
+data dir with `--config`. The included `<data_dir>/config.toml` is archived
+verbatim and may itself contain inline root/proxy/recovery credentials, the
+API-key pepper, or sensitive LLM headers. Always protect the snapshot as a
+secret-bearing artifact. Excluding the separate credential files limits the
+copied auth material; omitting `raw/` avoids racing the actively appended
managed-workstream ledger. The SQLite snapshot still contains the searchable
-managed-workstream events; omitting `raw/` loses their immutable source copy.
+managed-workstream events, but loses their immutable source copy.
For a move to another host, carry these beside the snapshot through a
separately encrypted or otherwise access-controlled backup:
@@ -1167,7 +1170,10 @@ restored database contains native API credentials but the destination loads a
different pepper, `serve` refuses instead of starting with keys that can never
authenticate. A database first opened by a version that predates this verifier
cannot prove which pepper created its existing hashes; for those older
-snapshots, restoring the original external config remains mandatory.
+snapshots, restoring the original external config remains mandatory. Restore
+refuses such a database until the operator supplies that original pepper and
+adds `--accept-legacy-api-key-pepper`, which seals a verifier into the staged
+database before the live data is changed.
Restoring a backup follows the inverse:
@@ -1199,7 +1205,9 @@ Order of operations:
2. Extract the tarball into a staging directory beside the live data
(`<data_dir>/.restore-staging-<stamp>/`), validating every entry.
3. Open the staged store so pending migrations run and the SQLite
- snapshot is verified, still without touching the live data.
+ snapshot is verified, still without touching the live data. A legacy
+ database with API keys but no pepper verifier stops here unless the original
+ pepper is configured and `--accept-legacy-api-key-pepper` was passed.
4. Swap: rename the live `wiki/` and `db/` (and `config.toml`, when the
archive carries one) aside, rename the staged copies into place, then
delete the previous data. Each move is a same-filesystem rename; if
@@ -1221,6 +1229,10 @@ Failure modes:
a snapshot the current binary cannot open** (for example a backup taken
by a newer release) → exits with the error; the existing `wiki/` and
`db/` are left as they were.
+- **Legacy backup has API keys but no pepper verifier** → restore the original
+ `[auth].token_pepper` through the current config/environment and rerun with
+ `--accept-legacy-api-key-pepper`. This flag confirms provenance; it cannot
+ determine whether an unknown pepper is correct.
- **A rename in the swap fails and cannot be reversed** → exits with an
`INCONSISTENT STATE` message naming the
`<data_dir>/.restore-previous-<stamp>/` directory that still holds the
diff --git a/docs/users.md b/docs/users.md
index 44de5870..52696cf3 100644
--- a/docs/users.md
+++ b/docs/users.md
@@ -424,8 +424,10 @@ a different pepper instead of starting with keys that can only return 401.
Restore the original pepper from a separately protected configuration backup
rather than deleting identities or keys: `ai-memory backup` includes only a
`config.toml` inside the data dir, while packaged systemd units load one from
-outside it. Snapshots created before the verifier existed cannot be checked
-and still require the original config.
+outside it. A restore of a snapshot created before the verifier existed fails
+closed when keys are present. Load the original pepper and explicitly confirm
+it with `ai-memory restore --accept-legacy-api-key-pepper`; the staged database
+is sealed before it replaces live data.
### 2. Add another human