Skip to content

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

Rust

fix(serve): honor the configured base path

Samir Hanna Verzac40b0345a5de
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e65cba04..69c556fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,9 @@ version in [`docs/changelog/`](docs/changelog/):
### Fixed
+- Honored `base_path` from `config.toml` when mounting the HTTP server, so
+ thin clients and the web UI use the same prefix. Explicit flag and environment
+ overrides, including an empty value to serve at the root, kept their precedence (#PR).
- Refused empty and whitespace-only `--workspace` and `--project` flags at the
shared CLI scope-resolution choke point (`resolve_scope`,
`resolve_scope_noting_marker_project`, `resolve_scope_with_marker`, and
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index ae405676..d39da150 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -3623,15 +3623,15 @@ pub struct ServeArgs {
/// --enable-web is set.
#[arg(long, env = "AI_MEMORY_WEB_UI_DIR")]
pub web_ui_dir: Option<PathBuf>,
- /// Base path the whole HTTP surface is served under. Empty (default)
- /// keeps every route at the host root — byte-identical to previous
- /// behaviour. Set e.g. `/wiki` to host ai-memory under a URL subpath
+ /// Base path the whole HTTP surface is served under (default: from config).
+ /// Empty (the configuration default) keeps every route at the host root.
+ /// Set e.g. `/wiki` to host ai-memory under a URL subpath
/// behind a reverse proxy that preserves the prefix; then `/mcp`,
/// `/api/v1`, `/hook` and the web UI all live under it (`/wiki/mcp`,
/// `/wiki/api/v1`, …). The value is normalised to `/<core>` (leading
/// slash, no trailing); `/` and `` both mean root.
- #[arg(long, env = "AI_MEMORY_BASE_PATH", default_value = "")]
- pub base_path: String,
+ #[arg(long, env = "AI_MEMORY_BASE_PATH")]
+ pub base_path: Option<String>,
/// Slug the web UI is mounted at, WITHIN `--base-path`. Default `/web`
/// (the read-only `/api/v1` API always stays at `<base>/api/v1`). Set
/// `/` to serve the UI at the base root itself (e.g. `/wiki` instead of
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 8bf886b7..cad1a922 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -1854,11 +1854,12 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
auth_state.clone(),
require_dual_auth,
));
- let base_path = normalize_prefix(&args.base_path);
- if base_path.is_empty() && !args.base_path.trim_matches('/').trim().is_empty() {
+ let configured_base_path = args.base_path.as_deref().unwrap_or(&config.base_path);
+ let base_path = normalize_prefix(configured_base_path);
+ if base_path.is_empty() && !configured_base_path.trim_matches('/').trim().is_empty() {
tracing::warn!(
- raw = %args.base_path,
- "AI_MEMORY_BASE_PATH is not a safe path prefix; serving at root instead",
+ raw = %configured_base_path,
+ "configured base path is not a safe path prefix; serving at root instead",
);
}
// Symmetric warning for `--web-slug` / `AI_MEMORY_WEB_SLUG`. The
@@ -1873,7 +1874,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
"AI_MEMORY_WEB_SLUG is not a safe path prefix; serving the web UI at the base-path root instead",
);
}
- let base_href = web_base_href(&args.base_path, &args.web_slug);
+ let base_href = web_base_href(configured_base_path, &args.web_slug);
let web = split_web_routers(
args.enable_web,
store.reader.clone(),
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index de48861a..648fa6e9 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -332,10 +332,9 @@ pub struct Config {
/// CLI commands prepend it to every `/admin/*` request so deployments
/// hosted behind a reverse proxy under a subpath don't 404. Settable via
/// `AI_MEMORY_BASE_PATH`. Empty for root-mounted deployments (the
- /// default). The `serve` subcommand reads the same env var via clap and
- /// nests its router accordingly; this field is what the thin-client
- /// path needs to discover the same prefix without a second
- /// `std::env::var` call (invariant: one config-read path).
+ /// default). The `serve` subcommand uses this value unless an explicit
+ /// flag or env override wins, so it mounts the same prefix thin clients
+ /// resolve without another environment read (invariant: one config-read path).
#[serde(default)]
pub base_path: String,
/// Operator home directory, captured once here (the single config-read
diff --git a/crates/ai-memory-cli/tests/suite/main.rs b/crates/ai-memory-cli/tests/suite/main.rs
index 2e159c49..e5d12747 100644
--- a/crates/ai-memory-cli/tests/suite/main.rs
+++ b/crates/ai-memory-cli/tests/suite/main.rs
@@ -38,6 +38,7 @@ mod repo_layout;
mod routing_instructions;
mod routing_skills;
mod run_offline;
+mod serve_config;
mod serve_shutdown;
mod server_profiles;
mod service_host_windows;
diff --git a/crates/ai-memory-cli/tests/suite/serve_config.rs b/crates/ai-memory-cli/tests/suite/serve_config.rs
new file mode 100644
index 00000000..b6e870d7
--- /dev/null
+++ b/crates/ai-memory-cli/tests/suite/serve_config.rs
@@ -0,0 +1,223 @@
+//! The server and thin clients must resolve the same configured HTTP mount.
+
+/// These tests start the shipped binary with isolated homes and stores.
+mod slow {
+ use std::path::Path;
+ use std::process::Command;
+ use std::time::Duration;
+
+ use reqwest::StatusCode;
+
+ use crate::e2e_support::{ServerGuard, hermetic, start_serve};
+
+ const BIN: &str = env!("CARGO_BIN_EXE_ai-memory");
+ const TOKEN: &str = "base-path-fixture-root";
+
+ fn command(root: &Path) -> Command {
+ let mut command = hermetic(BIN);
+ command
+ .env("HOME", root)
+ .env("USERPROFILE", root)
+ .env("AI_MEMORY_HOME", root)
+ .env("AI_MEMORY_DATA_DIR", root.join("data"))
+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none")
+ .env("AI_MEMORY_BACKFILL_ON_START", "false")
+ .env("RUST_LOG", "off")
+ .current_dir(root);
+ command
+ }
+
+ async fn serve(
+ client: &reqwest::Client,
+ root: &Path,
+ config_prefix: Option<&str>,
+ env_prefix: Option<&str>,
+ flag_prefix: Option<&str>,
+ with_web_auth: bool,
+ ) -> (ServerGuard, String) {
+ std::fs::create_dir_all(root.join("data")).unwrap();
+ start_serve(client, &root.join("serve.log"), |port| {
+ let mut config = format!("bind = \"127.0.0.1:{port}\"\n");
+ if let Some(prefix) = config_prefix {
+ config.push_str(&format!("base_path = {prefix:?}\n"));
+ }
+ config.push_str(
+ "[maintenance]\nenabled = false\n[auto_improve.scheduler]\nenabled = false\n",
+ );
+ if with_web_auth {
+ config.push_str(&format!("[auth]\nbearer_token = {TOKEN:?}\n"));
+ }
+ std::fs::write(root.join("data/config.toml"), config).unwrap();
+ let mut command = command(root);
+ command.args(["serve", "--transport", "http", "--no-watcher"]);
+ if let Some(prefix) = env_prefix {
+ command.env("AI_MEMORY_BASE_PATH", prefix);
+ }
+ if let Some(prefix) = flag_prefix {
+ command.args(["--base-path", prefix]);
+ }
+ if with_web_auth {
+ command.arg("--enable-web");
+ }
+ command
+ })
+ .await
+ }
+
+ fn client() -> reqwest::Client {
+ reqwest::Client::builder()
+ .no_proxy()
+ .timeout(Duration::from_secs(5))
+ .redirect(reqwest::redirect::Policy::none())
+ .build()
+ .unwrap()
+ }
+
+ #[tokio::test]
+ async fn toml_base_path_keeps_clients_web_and_auth_on_the_same_mount() {
+ let root = tempfile::tempdir().unwrap();
+ let client = client();
+ let (_server, origin) = serve(&client, root.path(), Some("/wiki/"), None, None, true).await;
+
+ assert_eq!(
+ client
+ .get(format!("{origin}/wiki/healthz"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::OK,
+ );
+ for path in ["/healthz", "/admin/status", "/web/login"] {
+ assert_eq!(
+ client
+ .get(format!("{origin}{path}"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::NOT_FOUND,
+ "root route {path} must not alias the configured mount",
+ );
+ }
+ let status_url = format!("{origin}/wiki/admin/status");
+ for bearer in [None, Some("wrong-fixture-token")] {
+ let mut request = client.get(&status_url);
+ if let Some(bearer) = bearer {
+ request = request.bearer_auth(bearer);
+ }
+ assert_eq!(
+ request.send().await.unwrap().status(),
+ StatusCode::UNAUTHORIZED
+ );
+ }
+ assert_eq!(
+ client
+ .get(&status_url)
+ .bearer_auth(TOKEN)
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::OK,
+ );
+ assert_eq!(
+ client
+ .get(&status_url)
+ .bearer_auth(TOKEN)
+ .header("host", "foreign.invalid")
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::FORBIDDEN,
+ );
+
+ let login = client
+ .get(format!("{origin}/wiki/web/login"))
+ .send()
+ .await
+ .unwrap();
+ assert_eq!(login.status(), StatusCode::OK);
+ assert!(
+ login
+ .text()
+ .await
+ .unwrap()
+ .contains("<base href=\"/wiki/web/\"")
+ );
+ assert_eq!(
+ client
+ .get(format!("{origin}/favicon.ico"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::OK,
+ "the public favicon stays at the host root",
+ );
+
+ let output = command(root.path())
+ .args(["status", "--json"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ let status: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+ assert_eq!(status["counts"]["sessions"], 0);
+ }
+
+ #[tokio::test]
+ async fn base_path_flag_and_env_override_toml_including_explicit_root() {
+ let client = client();
+ for (env, flag, expected) in [
+ (Some("/env"), None, "/env"),
+ (Some("/env"), Some("/flag"), "/flag"),
+ (Some("/env"), Some(""), ""),
+ (Some(""), None, ""),
+ (None, Some("/"), ""),
+ ] {
+ let root = tempfile::tempdir().unwrap();
+ let (_server, origin) =
+ serve(&client, root.path(), Some("/wiki"), env, flag, false).await;
+ assert_eq!(
+ client
+ .get(format!("{origin}{expected}/healthz"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::OK,
+ "env={env:?}, flag={flag:?}",
+ );
+ assert_eq!(
+ client
+ .get(format!("{origin}/wiki/healthz"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::NOT_FOUND,
+ );
+ }
+ }
+
+ #[tokio::test]
+ async fn no_base_path_keeps_the_root_mount() {
+ let root = tempfile::tempdir().unwrap();
+ let client = client();
+ let (_server, origin) = serve(&client, root.path(), None, None, None, false).await;
+ assert_eq!(
+ client
+ .get(format!("{origin}/healthz"))
+ .send()
+ .await
+ .unwrap()
+ .status(),
+ StatusCode::OK,
+ );
+ }
+}
diff --git a/docs/https-via-proxy.md b/docs/https-via-proxy.md
index 6d55a618..f4b14dab 100644
--- a/docs/https-via-proxy.md
+++ b/docs/https-via-proxy.md
@@ -146,6 +146,11 @@ and tell ai-memory about it:
AI_MEMORY_BASE_PATH=/wiki
```
+Alternatively, set `base_path = "/wiki"` in `config.toml`; the server and
+thin-client commands both read it. For `serve`, `--base-path` overrides
+`AI_MEMORY_BASE_PATH`, which overrides the file. An explicitly empty value
+or `/` selects the host root even when the file names a prefix.
+
```caddyfile
memory.example.com {
handle /wiki/* {
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 23b2d5a6..c8ef6750 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -113,7 +113,7 @@ the legitimate restricted-project control and the failed-query cases.
| 11k | Server-side ingest drop list: tool id/name lists (#1241) and whole event kinds (`[ingest] drop_events`) | `ai-memory-hooks/src/drop_list.rs` `IngestDropList`: `matches` for the tool lists (a tool-call id by prefix, a tool name exactly) and `matches_event_kind` for the whole kinds (every `[ingest] drop_events` value parsed with the typed `HookEvent::parse`; `session-start`/`session-end` and the `other` bucket rejected), both validated once in `Config::load` (tool lists: at most 64 entries of 128 printable characters each). Checked in `router.rs` `admit_hook` and the `handle_hook_batch` loop after the subagent exclusion (`should_drop_subagent`) and before the rate limiter, ingest semaphore, sanitizer, and storage, so a marked subagent event seeds the tracking set its unmarked tail is dropped against even when its tool id, tool name, or event kind is listed. The tool lists match only tool events and are read through the per-agent mapping `capture_policy::tool_payload_fields` that tool metadata uses. A drop answers 202 and counts as `dropped_by_policy`; the matched value is never logged | tool lists: `router.rs` `the_ingest_drop_list_drops_before_any_capacity_is_spent`, `the_ingest_drop_list_applies_to_hook_batches`, `marked_tool_policy_drops_seed_subagent_tracking_before_single_ingress_matching`, and `marked_tool_policy_drops_seed_subagent_tracking_before_batch_matching` cover capacity, batch acknowledgements, id-prefix and exact-name seeding order, unmarked tails, and stored controls; `drop_list.rs` unit tests cover bounds, exact matching, and each agent's native fields. Whole kinds: `router.rs` `the_ingest_drop_events_drops_the_named_kind_and_keeps_the_rest`, `the_ingest_drop_events_drops_before_any_capacity_is_spent`, `the_ingest_drop_events_consumes_no_rate_budget`, `the_ingest_drop_events_batch_reports_per_index_outcomes_and_only_stores_the_kept`, `the_ingest_drop_events_keeps_dropping_the_unmarked_subagent_tail`, `the_ingest_drop_events_keeps_dropping_the_unmarked_subagent_tail_in_batches`, and `a_marked_event_of_a_dropped_kind_still_seeds_subagent_tracking`; `drop_list.rs` `drop_events_*` tests cover typed matching and rejected state/unknown kinds. Moving any matcher before subagent exclusion fails its single/batch tail tests; removing either batch matcher fails its batch contract | STRONG. The list applies to every project on the server; it narrows what is stored and never widens access |
| 11l | Marketplace plugin front door: a plugin-launched event gets exactly the native hook's capture policy, scope and server routing, is captured once beside settings-file hooks, and sends nothing without the binary (#1166) | `plugins/*/scripts/ai-memory-hook` (rendered from `crates/ai-memory-cli/templates/plugin/ai-memory-hook.sh` by `render_plugins.rs`) has no capture logic: it only finds the binary (an `ai_memory_bin` option is honoured only as an absolute path, so a checkout cannot plant a relative one) and runs `ai-memory hook` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`, `hook` first so the Docker wrapper routes it, omitting `--server-url` when the option is empty (a pre-3.0 binary's usage error, exit 2 before it reads stdin, is retried once against the default local server with a stderr hint), and without a binary drains stdin, prints `{}` (guidance on `session-start` only) and exits 0; `hook.rs` `is_dropped_plugin_copy` + `plugin_origin.rs` `drops_plugin_event` drop a plugin copy when the user `settings.json` (honouring `CLAUDE_CONFIG_DIR`) or the checkout's `.claude/settings.local.json` carries an ai-memory hook for the same event (`install_hooks::hooks_file_delivers_ai_memory_event`); a Droid-launched copy (`droid-plugin`) is checked against the one file Droid reads hooks from (`~/.factory/hooks.json`, else the `hooks` key of `~/.factory/settings.json`); a Muse-launched copy (`muse-plugin`, recognized by `MUSE_PLUGIN_ID` with `MUSE_SESSION_ID`) is checked against the `hooks` key of `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json`, and its subagent events are dropped; both drop a folderless session (no `cwd`, or a Claude desktop `scratch-workspaces` cwd); Codex plugin events are never de-duplicated (an untrusted settings hook is skipped silently, so dropping could lose the event); the drift test keeps every plugin hook on the native path (no `hooks/<agent>/*.sh`, no credential in any plugin file) | CLI `tests/suite/plugins.rs` through the committed launcher and the real binary: `ignore_paths_hold_through_the_plugin` (ignored path never spooled; public-file control kept), `allowlist_mode_holds_through_the_plugin` (unmarked checkout emits nothing, prompts included; marked control captured), `marker_scope_routes_plugin_events`, `server_profiles_route_plugin_events` (profile URL and token, never the plugin's URL), `a_settings_hook_for_the_same_event_drops_the_plugin_copy` (user and project settings; unwired-event and no-settings controls), `a_droid_hook_for_the_same_event_drops_the_droid_plugin_copy` (Droid `hooks.json`; no-Droid-hook, Claude-settings-only, unwired-event and folderless controls), `a_muse_hook_for_the_same_event_drops_the_muse_plugin_copy` (Muse `settings.json`; no-Muse-hook, Claude-settings-only and unwired-event controls; subagent and folderless events dropped), `plugin_origin.rs` `muse_plugin_copy_is_dropped_when_muse_settings_hooks_deliver_the_event` (a matcher-narrowed hook does not count) and `test_plugin_launcher.sh` (an inherited `MUSE_SESSION_ID` without `MUSE_PLUGIN_ID` stays `claude-code`), `folderless_sessions_are_not_captured_through_the_plugin`, `without_a_binary_nothing_is_sent_and_the_agent_is_not_blocked`, `foreign_hosts_are_attributed_or_ignored`, `committed_plugins_match_the_renderer`, `plugin_tree_carries_no_credentials`; `plugin_origin.rs` unit tests (`codex_plugin_events_are_never_deduplicated_against_settings`, `droid_settings_hooks_count_only_while_hooks_json_is_absent`, `only_a_catch_all_matcher_suppresses_the_plugin_copy`: a settings hook narrowed by a matcher never drops the plugin copy); `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `tests/hooks/test_plugin_launcher.sh` (a relative `ai_memory_bin` planted in the checkout is never run; PATH control); `tests/e2e/claude_plugin_smoke.py` (real `claude -p`: settings hook plus plugin give one `user-prompt`) | STRONG. Verified 2026-10-13: removing the `is_dropped_plugin_copy` guard fails the de-duplication and folderless tests (and the smoke reports `user-prompt x2`); disabling the native `Drop` disposition or the allowlist gate fails the `ignore_paths` and allowlist tests through the launcher. Not covered: tool events from a live model turn (no credential in CI), Windows Git Bash, Cowork and the desktop Code tab (see `docs/design-marketplace-plugins.md`) |
| 11m | The server never opens a filesystem path named in a hook payload | `ai-memory-hooks/src/payload.rs` `HookEnvelope::from_query_and_body` (run by `/hook` and every `/hook/batch` item) only reads the posted JSON; Antigravity step-log enrichment (`antigravity.rs` `enrich_antigravity_step_output`, which opens `<artifactDirectoryPath or transcriptPath dir>/.system_generated/steps/<stepIdx>/output.txt`) runs only client-side in `ai-memory-cli/src/commands/hook.rs` against the client's own home, and the server stores whatever `tool_response` the client sent | `router.rs` `a_hook_payload_cannot_make_the_server_read_its_own_disk` (an Antigravity `PostToolUse` batch naming a server-only directory through `artifactDirectoryPath` and through `transcriptPath`; no stored observation or file contains the server-side sentinel); `payload.rs` `envelope_parsing_never_reads_a_payload_named_antigravity_artifact` and `antigravity_post_tool_use_renders_client_enriched_output` (control: client-supplied output still rendered) | STRONG. Both adversarial tests fail with the server-side enrichment call reinstated (the sentinel file content is stored and readable through search) |
-| 12 | Network/auth posture, including auth on by default for new installs (an existing install keeps loopback no-auth until `ai-memory auth enable`) | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer`; `serve.rs` mounts `/identity` inside the host and machine-auth gates even with web disabled; `nix/nixos-module.nix` treats only literal `127.0.0.1`/`::1` as loopback, requires exactly one secret environment source for other binds, keeps secret auth and `llm_headers` values out of the Nix store, and brackets IPv6 in `ExecStart`; new-install default: `commands/init.rs` `root_bearer_for_new_config` mints a root bearer only on a fresh data dir (no config file and no database) and only when no bearer is supplied otherwise, via `local_auth.rs` `provision_root_token` (`auth-tokens/` `0700`, file `0600`, atomic, reused when present) and records the relative `[auth].bearer_token_file`; `config.rs` `apply_bearer_token_file` reads it once (`AI_MEMORY_AUTH_TOKEN` wins, inline + file together refused, a missing or blank file leaves no bearer) and `discover_root_token` lets a packaged install's client commands use `<data_dir>/auth-tokens/default` only with no config file at the probed path, a loopback server URL and no registered `default` profile (`http_client.rs` `is_loopback_url`, shared by every caller, decides loopback from the host `reqwest` parses and refuses any URL carrying user information); `serve.rs` `refuse_a_missing_token_file` stops a server whose configured file holds no token; `AuthSettings::renderable_bearer_token` keeps a file-sourced token out of every renderer: `install_mcp.rs` `route_file_token` (Claude Code gets the session-aware `ai-memory mcp-bridge` entry, Codex and Prime Agent name `AI_MEMORY_AUTH_TOKEN`, every other client a `stdio_bridge_entry` that runs `mcp-bridge --no-session-id` in its documented stdio shape, Pi keeps its extension, ZCode (HTTP-only) is refused) and `mcp_bridge.rs`, which authenticates with the config-resolved bearer and connects upstream before serving stdio, so a refused token ends it with `401 Unauthorized` instead of hanging; `mcp_bridge.rs` `bridge_bearer` sends a configured bearer, else the hook key stored in `<data_dir>/auth-token`, else the discovered loopback root token (`AuthSettings::configured_bearer_token` leaves discovery out, so a server+client host never sends root over a stored user key), and the fallback is in the bridge only (`Config::load` never reads that file, so `serve` neither requires nor accepts it); `install_mcp.rs` `store_bridge_key` stores an explicit `--auth-token` there for the Claude Code and Muse bridge entries on `--apply` and writes the entry with `--data-dir` and no key, keeping the key inline when a configured bearer would win, a different key is stored, the hooks use OIDC, the store fails or the Docker helper runs; `uninstall.rs` keeps the stored key on `--only hooks` while `install_mcp::bridge_entry_remains`; `uninstall.rs` `mcp_entry_is_ours` / `toml_mcp_entry_targets` recognise bridge entries by `install_mcp::bridge_entry_url`; `auth_enable.rs` `rewire_clients` re-registers every client whose entry targets this server, `install_hooks.rs` (persisted to the hook credential files, never inlined, not even on the F5 persist-failure fallback), `setup_agent.rs`, `run_autowire.rs`, `setup.rs` (runs `init`, adopts the minted token in memory through `adopt_token_file`, and calls the installers with no explicit token; the rendered user unit carries none; `user_service.rs` `is_rendered_by_setup` lets `uninstall` stop and delete only a unit carrying `setup`'s identity line whose SHA-256 still matches, never a hand-written or edited one); `local_auth.rs` `seed_hook_credential` gives hooks the token through `auth-token`/`auth-header` and keeps a different stored credential; `uninstall.rs` keeps the root bearer (`server_profiles::clear_tokens` `keep`); `commands/auth_enable.rs` is the idempotent opt-in | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401; `serve.rs` `machine_identity_remains_authenticated_with_web_disabled_and_expired_keys` (wrong and expired keys refused, valid machine key accepted, web remains disabled); `flake.nix` `nixos-module-eval` refuses `localhost` and `0.0.0.0` without a secret source, refuses two secret sources, `settings.auth` secrets, and `settings.llm_headers`, with literal IPv4/IPv6 loopback and one-source controls; `cli/tests/suite/auth_default_e2e.rs` against the shipped binary: `a_fresh_install_requires_the_token_and_its_own_clients_still_work` (after `init`, unauthenticated `/mcp`, `/hook`, `/api/v1/projects`, `/admin/status` → 401 and `/healthz` → 200; the same requests with the token succeed; the native hook delivers with no token in its environment, `status` authenticates through config, `mcp-bridge` lists tools; the token is in neither process's `/proc/<pid>/cmdline`; after `install-hooks`, `install-mcp --apply` for every client it writes (21, by default config path under the test home), a refused ZCode install and `auth enable` twice, a scan of the whole home finds the token nowhere and a scan of the data dir finds it only in the token file and the two hook credential files), `an_existing_install_is_unchanged_until_auth_enable` (control: a pre-default install serves every route open and `status` names the fix; `auth enable` twice is idempotent, rewires Claude Code to the bridge, and after a restart the routes refuse and the hook still delivers), `a_packaged_install_with_an_external_config_wires_its_clients`, `uninstall_keeps_the_root_bearer_and_a_missing_one_stops_the_server`, `a_host_client_given_the_token_file_by_env_authenticates`; `init.rs` `a_fresh_init_mints_a_root_bearer_the_loader_reads`, `init_on_an_existing_install_does_not_turn_auth_on`, `init_with_a_supplied_bearer_mints_nothing`, `re_running_init_keeps_the_same_root_bearer`; `config.rs` `a_relative_bearer_token_file_resolves_against_the_data_dir`, `a_missing_or_blank_bearer_token_file_is_reported_not_guessed`, `the_env_token_wins_over_the_bearer_token_file`, `an_inline_bearer_and_a_bearer_token_file_together_are_refused`, `a_client_without_a_config_file_discovers_the_root_bearer`, `root_bearer_discovery_is_refused_outside_its_narrow_case` (existing config, remote URL, a remote host behind loopback-looking user information, `default` profile, env token); `http_client.rs` `loopback_url_is_decided_by_the_parsed_host` (user-information, fragment and query forms, look-alike domains, `localhost.`, `0.0.0.0` and IPv4-mapped IPv6 refused; `127.0.0.0/8`, `[::1]` and `localhost` in any case accepted); `mcp_bridge.rs` `discovered_root_never_leaves_loopback_but_the_stored_user_key_follows_the_entry` (adversarial: remote and user-information `--server-url` forms get no root key; control: an unnamed loopback server does); `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (`tools/list` and a scoped `memory_query` through `mcp-bridge --no-session-id` against a fresh auth-on server, the token in neither the bridge's `/proc/<pid>/cmdline` nor its `/proc/<pid>/environ`; control: the session-aware mode still refuses to start without `CLAUDE_CODE_SESSION_ID`) and `a_bridge_without_the_token_is_refused_cleanly_not_hung` (exits promptly naming `401 Unauthorized`); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id`, `a_session_less_upstream_config_carries_no_session_header`, `stdio_bridge_forwards_tools_and_session_header_in_both_http_modes` (control); `config.rs` `config_load_never_adopts_the_stored_hook_key` (adversarial: a stored hook key leaves the loaded bearer empty, so `serve` on that data dir neither requires nor accepts it; control: a `bearer_token_file` naming the same file is adopted); `mcp_bridge.rs` `bridge_bearer_puts_the_stored_hook_key_below_a_configured_bearer` (a configured bearer wins, a blank one does not), `a_stored_user_key_outranks_the_discovered_root_token` (adversarial: discoverable loopback root plus a stored key sends the stored key; control: discovery alone still sends root); `install_mcp.rs` `an_explicit_key_for_a_bridge_is_stored_instead_of_written_inline` (Claude Code and Muse entries carry no key and name the data dir, the stored pair is the hooks' format; controls keeping the key inline and storing nothing: print path, configured bearer, a different stored key, OIDC hooks, Docker helper, HTTP entry); `removal.rs` `an_explicit_bridge_key_is_stored_and_outlives_only_hooks_removal`; `install_mcp.rs` `a_file_sourced_token_wires_every_client_without_entering_its_config` (every written client: no token, no header, an entry that reaches the server; ZCode refused and unwritten), `stdio_bridge_entries_follow_each_clients_documented_shape`, `inline_and_explicit_tokens_still_embed_as_before` (control); `uninstall.rs` `bridge_entries_are_recognised_by_their_upstream_url` (JSON, OpenCode array and TOML shapes; a bridge to another server and a foreign command are kept); `install_hooks.rs` `a_file_sourced_token_is_persisted_but_never_embedded`; `auth_enable.rs` `enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config` (every client pre-wired over HTTP is re-registered, ZCode reported as manual, the second run byte-identical), `enable_leaves_an_entry_for_another_server_alone`, `enable_refuses_while_a_default_profile_would_share_the_token`; `local_auth.rs` `the_root_bearer_is_owner_only`, `seeding_never_replaces_a_different_hook_credential`; `setup_e2e.rs` `setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit` (one `setup --yes` in a fresh temp home: the token is in no file under the home but the token file and the two hook credential files, not in the user unit and not in `setup`'s output; the self-check's `memory_status` and a hook event authenticate through the file; `uninstall` then disables and deletes the unit once and a second `uninstall` calls nothing), `uninstall_leaves_a_unit_it_did_not_write` (adversarial: the packaged unit copied by hand is kept, no `systemctl` call); `user_service.rs` `a_foreign_or_edited_unit_is_left_alone`, `rendered_units_carry_an_identity_that_survives_only_unedited` | STRONG. Bite checks for the new-install default: with fresh-install minting disabled the fresh e2e routes answer without a token and the `init` tests fail; with `renderable_bearer_token` returning the file token, `install-mcp`, `install-hooks`, `auth enable` and the e2e scans find it in harness configs; without the `serve` refusal a server whose token file was deleted keeps running (the e2e times out on it); without the hook seeding the fresh e2e hook is refused; without `clear_tokens` `keep` uninstall deletes the root bearer; with `route_file_token` no longer choosing the stdio bridge the every-client and `auth enable` tests fail; with `auth enable` skipping the re-registration its test fails; with the session-less mode forwarding an inherited id the bridge unit test fails; without the 401 naming the refusal e2e fails; without bridge-entry recognition the uninstall test fails; with `Config::load` adopting the stored hook key, without the bridge fallback, with discovery counted as a configured bearer, or with `install-mcp` never storing the key, the matching new test fails; with `setup` handing the token to `install-mcp` its scan finds it in `.claude.json`; with `is_rendered_by_setup` accepting any unit, the foreign-unit tests fail; with discovery removed the packaged e2e gets 401, and with each discovery guard removed the matching case of `root_bearer_discovery_is_refused_outside_its_narrow_case` fails. Residual: a hand-edited `servers.toml` that adds a `default` profile after the root bearer exists would read the root bearer as that profile's token (`server add` refuses it, `auth enable` refuses while it exists); ZCode takes only HTTP entries and is refused, so it needs a manual entry; the stdio entries for Zero, Muse Code and DeepSeek Harness follow their documented or source-level format but were not run against those clients |
+| 12 | Network/auth posture, including auth on by default for new installs (an existing install keeps loopback no-auth until `ai-memory auth enable`) | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer`; `serve.rs` mounts `/identity` inside the host and machine-auth gates even with web disabled; `nix/nixos-module.nix` treats only literal `127.0.0.1`/`::1` as loopback, requires exactly one secret environment source for other binds, keeps secret auth and `llm_headers` values out of the Nix store, and brackets IPv6 in `ExecStart`; new-install default: `commands/init.rs` `root_bearer_for_new_config` mints a root bearer only on a fresh data dir (no config file and no database) and only when no bearer is supplied otherwise, via `local_auth.rs` `provision_root_token` (`auth-tokens/` `0700`, file `0600`, atomic, reused when present) and records the relative `[auth].bearer_token_file`; `config.rs` `apply_bearer_token_file` reads it once (`AI_MEMORY_AUTH_TOKEN` wins, inline + file together refused, a missing or blank file leaves no bearer) and `discover_root_token` lets a packaged install's client commands use `<data_dir>/auth-tokens/default` only with no config file at the probed path, a loopback server URL and no registered `default` profile (`http_client.rs` `is_loopback_url`, shared by every caller, decides loopback from the host `reqwest` parses and refuses any URL carrying user information); `serve.rs` `refuse_a_missing_token_file` stops a server whose configured file holds no token; `AuthSettings::renderable_bearer_token` keeps a file-sourced token out of every renderer: `install_mcp.rs` `route_file_token` (Claude Code gets the session-aware `ai-memory mcp-bridge` entry, Codex and Prime Agent name `AI_MEMORY_AUTH_TOKEN`, every other client a `stdio_bridge_entry` that runs `mcp-bridge --no-session-id` in its documented stdio shape, Pi keeps its extension, ZCode (HTTP-only) is refused) and `mcp_bridge.rs`, which authenticates with the config-resolved bearer and connects upstream before serving stdio, so a refused token ends it with `401 Unauthorized` instead of hanging; `mcp_bridge.rs` `bridge_bearer` sends a configured bearer, else the hook key stored in `<data_dir>/auth-token`, else the discovered loopback root token (`AuthSettings::configured_bearer_token` leaves discovery out, so a server+client host never sends root over a stored user key), and the fallback is in the bridge only (`Config::load` never reads that file, so `serve` neither requires nor accepts it); `install_mcp.rs` `store_bridge_key` stores an explicit `--auth-token` there for the Claude Code and Muse bridge entries on `--apply` and writes the entry with `--data-dir` and no key, keeping the key inline when a configured bearer would win, a different key is stored, the hooks use OIDC, the store fails or the Docker helper runs; `uninstall.rs` keeps the stored key on `--only hooks` while `install_mcp::bridge_entry_remains`; `uninstall.rs` `mcp_entry_is_ours` / `toml_mcp_entry_targets` recognise bridge entries by `install_mcp::bridge_entry_url`; `auth_enable.rs` `rewire_clients` re-registers every client whose entry targets this server, `install_hooks.rs` (persisted to the hook credential files, never inlined, not even on the F5 persist-failure fallback), `setup_agent.rs`, `run_autowire.rs`, `setup.rs` (runs `init`, adopts the minted token in memory through `adopt_token_file`, and calls the installers with no explicit token; the rendered user unit carries none; `user_service.rs` `is_rendered_by_setup` lets `uninstall` stop and delete only a unit carrying `setup`'s identity line whose SHA-256 still matches, never a hand-written or edited one); `local_auth.rs` `seed_hook_credential` gives hooks the token through `auth-token`/`auth-header` and keeps a different stored credential; `uninstall.rs` keeps the root bearer (`server_profiles::clear_tokens` `keep`); `commands/auth_enable.rs` is the idempotent opt-in | `cli/tests/suite/serve_config.rs` `toml_base_path_keeps_clients_web_and_auth_on_the_same_mount` (TOML-selected prefix: missing/wrong bearer → 401, valid bearer → 200, forged Host → 403; no unprefixed admin alias; public liveness/login/favicon and the configured CLI client remain reachable); `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401; `serve.rs` `machine_identity_remains_authenticated_with_web_disabled_and_expired_keys` (wrong and expired keys refused, valid machine key accepted, web remains disabled); `flake.nix` `nixos-module-eval` refuses `localhost` and `0.0.0.0` without a secret source, refuses two secret sources, `settings.auth` secrets, and `settings.llm_headers`, with literal IPv4/IPv6 loopback and one-source controls; `cli/tests/suite/auth_default_e2e.rs` against the shipped binary: `a_fresh_install_requires_the_token_and_its_own_clients_still_work` (after `init`, unauthenticated `/mcp`, `/hook`, `/api/v1/projects`, `/admin/status` → 401 and `/healthz` → 200; the same requests with the token succeed; the native hook delivers with no token in its environment, `status` authenticates through config, `mcp-bridge` lists tools; the token is in neither process's `/proc/<pid>/cmdline`; after `install-hooks`, `install-mcp --apply` for every client it writes (21, by default config path under the test home), a refused ZCode install and `auth enable` twice, a scan of the whole home finds the token nowhere and a scan of the data dir finds it only in the token file and the two hook credential files), `an_existing_install_is_unchanged_until_auth_enable` (control: a pre-default install serves every route open and `status` names the fix; `auth enable` twice is idempotent, rewires Claude Code to the bridge, and after a restart the routes refuse and the hook still delivers), `a_packaged_install_with_an_external_config_wires_its_clients`, `uninstall_keeps_the_root_bearer_and_a_missing_one_stops_the_server`, `a_host_client_given_the_token_file_by_env_authenticates`; `init.rs` `a_fresh_init_mints_a_root_bearer_the_loader_reads`, `init_on_an_existing_install_does_not_turn_auth_on`, `init_with_a_supplied_bearer_mints_nothing`, `re_running_init_keeps_the_same_root_bearer`; `config.rs` `a_relative_bearer_token_file_resolves_against_the_data_dir`, `a_missing_or_blank_bearer_token_file_is_reported_not_guessed`, `the_env_token_wins_over_the_bearer_token_file`, `an_inline_bearer_and_a_bearer_token_file_together_are_refused`, `a_client_without_a_config_file_discovers_the_root_bearer`, `root_bearer_discovery_is_refused_outside_its_narrow_case` (existing config, remote URL, a remote host behind loopback-looking user information, `default` profile, env token); `http_client.rs` `loopback_url_is_decided_by_the_parsed_host` (user-information, fragment and query forms, look-alike domains, `localhost.`, `0.0.0.0` and IPv4-mapped IPv6 refused; `127.0.0.0/8`, `[::1]` and `localhost` in any case accepted); `mcp_bridge.rs` `discovered_root_never_leaves_loopback_but_the_stored_user_key_follows_the_entry` (adversarial: remote and user-information `--server-url` forms get no root key; control: an unnamed loopback server does); `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (`tools/list` and a scoped `memory_query` through `mcp-bridge --no-session-id` against a fresh auth-on server, the token in neither the bridge's `/proc/<pid>/cmdline` nor its `/proc/<pid>/environ`; control: the session-aware mode still refuses to start without `CLAUDE_CODE_SESSION_ID`) and `a_bridge_without_the_token_is_refused_cleanly_not_hung` (exits promptly naming `401 Unauthorized`); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id`, `a_session_less_upstream_config_carries_no_session_header`, `stdio_bridge_forwards_tools_and_session_header_in_both_http_modes` (control); `config.rs` `config_load_never_adopts_the_stored_hook_key` (adversarial: a stored hook key leaves the loaded bearer empty, so `serve` on that data dir neither requires nor accepts it; control: a `bearer_token_file` naming the same file is adopted); `mcp_bridge.rs` `bridge_bearer_puts_the_stored_hook_key_below_a_configured_bearer` (a configured bearer wins, a blank one does not), `a_stored_user_key_outranks_the_discovered_root_token` (adversarial: discoverable loopback root plus a stored key sends the stored key; control: discovery alone still sends root); `install_mcp.rs` `an_explicit_key_for_a_bridge_is_stored_instead_of_written_inline` (Claude Code and Muse entries carry no key and name the data dir, the stored pair is the hooks' format; controls keeping the key inline and storing nothing: print path, configured bearer, a different stored key, OIDC hooks, Docker helper, HTTP entry); `removal.rs` `an_explicit_bridge_key_is_stored_and_outlives_only_hooks_removal`; `install_mcp.rs` `a_file_sourced_token_wires_every_client_without_entering_its_config` (every written client: no token, no header, an entry that reaches the server; ZCode refused and unwritten), `stdio_bridge_entries_follow_each_clients_documented_shape`, `inline_and_explicit_tokens_still_embed_as_before` (control); `uninstall.rs` `bridge_entries_are_recognised_by_their_upstream_url` (JSON, OpenCode array and TOML shapes; a bridge to another server and a foreign command are kept); `install_hooks.rs` `a_file_sourced_token_is_persisted_but_never_embedded`; `auth_enable.rs` `enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config` (every client pre-wired over HTTP is re-registered, ZCode reported as manual, the second run byte-identical), `enable_leaves_an_entry_for_another_server_alone`, `enable_refuses_while_a_default_profile_would_share_the_token`; `local_auth.rs` `the_root_bearer_is_owner_only`, `seeding_never_replaces_a_different_hook_credential`; `setup_e2e.rs` `setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit` (one `setup --yes` in a fresh temp home: the token is in no file under the home but the token file and the two hook credential files, not in the user unit and not in `setup`'s output; the self-check's `memory_status` and a hook event authenticate through the file; `uninstall` then disables and deletes the unit once and a second `uninstall` calls nothing), `uninstall_leaves_a_unit_it_did_not_write` (adversarial: the packaged unit copied by hand is kept, no `systemctl` call); `user_service.rs` `a_foreign_or_edited_unit_is_left_alone`, `rendered_units_carry_an_identity_that_survives_only_unedited` | STRONG. For the TOML-prefixed server, removing the admin bearer layer makes the refusal test return 200 instead of 401; removing the Host layer returns 200 instead of 403. Bite checks for the new-install default: with fresh-install minting disabled the fresh e2e routes answer without a token and the `init` tests fail; with `renderable_bearer_token` returning the file token, `install-mcp`, `install-hooks`, `auth enable` and the e2e scans find it in harness configs; without the `serve` refusal a server whose token file was deleted keeps running (the e2e times out on it); without the hook seeding the fresh e2e hook is refused; without `clear_tokens` `keep` uninstall deletes the root bearer; with `route_file_token` no longer choosing the stdio bridge the every-client and `auth enable` tests fail; with `auth enable` skipping the re-registration its test fails; with the session-less mode forwarding an inherited id the bridge unit test fails; without the 401 naming the refusal e2e fails; without bridge-entry recognition the uninstall test fails; with `Config::load` adopting the stored hook key, without the bridge fallback, with discovery counted as a configured bearer, or with `install-mcp` never storing the key, the matching new test fails; with `setup` handing the token to `install-mcp` its scan finds it in `.claude.json`; with `is_rendered_by_setup` accepting any unit, the foreign-unit tests fail; with discovery removed the packaged e2e gets 401, and with each discovery guard removed the matching case of `root_bearer_discovery_is_refused_outside_its_narrow_case` fails. Residual: a hand-edited `servers.toml` that adds a `default` profile after the root bearer exists would read the root bearer as that profile's token (`server add` refuses it, `auth enable` refuses while it exists); ZCode takes only HTTP entries and is refused, so it needs a manual entry; the stdio entries for Zero, Muse Code and DeepSeek Harness follow their documented or source-level format but were not run against those clients |
| 12b | Managed-workstream provenance privacy, stable replay identity and server event namespace | `ai-memory-core/src/workstream.rs` `scrub_workstream_provenance`; `ai-memory-hooks/src/workstream.rs` `finish_run` reserved client-id check and `sanitize_events` before immutable segments, with `sanitize_events` and `append_boundary_events` scrubbing event/checkpoint/losses content *before* the 64 KiB cap so a cap-straddling secret is never cut into an unmatchable prefix (#1113); `ai-memory-store/src/workstream.rs` `finish_run` stable identity check and `stored_event`, scrubbing content with the explicitly supplied configured sanitizer before its 16 KiB store-boundary bound; no changes to the typed observation boundary | `store/tests/suite/workstream_provenance.rs` `workstream_provenance_is_bounded_scrubbed_and_idempotent_before_storage` (hostile and oversized source ids, unknown metadata, legitimate correlation, retry and distinct event ids), `workstream_provenance_legacy_reads_strip_secrets_and_unknown_metadata` (search and tail, malformed/oversized legacy JSON), `workstream_provenance_reused_event_id_retains_data_and_refuses_identity_change` (first indexed version retained, identity refusal and batch rollback), `workstream_provenance_replay_survives_sanitizer_changes` (new extra patterns and removal of a built-in-pattern allowlist exemption, with identity-refusal control), `workstream_provenance_replay_preserves_legacy_rows_above_bounds`, `workstream_provenance_finished_run_ignores_late_events`, `workstream_provenance_retry_with_marker_matching_pattern_is_idempotent`, `workstream_content_is_scrubbed_before_the_store_cap` (a credential straddling the 16 KiB store cap is redacted, not persisted as an unmatchable prefix; benign control verbatim; #1113); `hooks` `workstream_provenance_finish_scrubs_before_raw_segment_and_search` (custom sanitizer, immutable segment, SQL recovery and finished-run no-op), `workstream_provenance_client_cannot_use_server_event_ids` (reserved ids refused before raw writes, normal client event and server-generated checkpoint/loss controls), `finish_run_scrubs_event_content_before_the_byte_cap` and `finish_run_scrubs_boundary_events_before_the_byte_cap` (a credential straddling the 64 KiB event cap is redacted in the raw segment and never reaches the index; checkpoint/losses and benign controls; #1113); `cli/tests/suite/workstream_provenance.rs` (text/JSON and old server DTOs) | STRONG: privacy, stable-identity and reserved-namespace regressions fail with their guards bypassed; an isolated allowlist bypass fails on the unknown key, and bypassing the raw-id search authorization returns 200 where its test requires 403. No provenance is emitted in startup packets, and old raw segments are not rewritten |
| 12c | Browser cross-origin writes refused on an unauthenticated server (a foreign page in the operator's browser, DNS rebinding, and a LAN host where browsers send no fetch metadata) | `serve.rs` `refuse_cross_origin_browser_requests` / `is_cross_origin_browser_request`, layered on the machine (`/mcp`, `/hook*`, `/handoff`, `/workstream/*`, `/identity`) and admin (`/admin/*`) routes when auth is off: `Sec-Fetch-Site` other than `same-origin`/`none` → 403, or, without fetch metadata, an `Origin` whose authority is not the `Host` → 403; and `is_non_script_browser_request`: any `Sec-Fetch-Dest` other than `empty` (case-insensitive; non-UTF-8 refused) → 403 whatever `Sec-Fetch-Site` says, so links, images, navigations, iframes and form posts are refused even as `same-origin` or `none`. Browsers send fetch metadata over plain HTTP only to a potentially trustworthy host, so on any other `Host` (a LAN address or name in the allowlist, `0.0.0.0`, `host.docker.internal`; `is_loopback_host` admits only `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`) `handoff_fetch_lacks_client_marker` also refuses `GET`/`HEAD /handoff` without a non-empty `X-AI-Memory-Client` header (`ai_memory_hooks::CLIENT_MARKER_HEADER`) → 403 whose body names both remedies (re-stage hooks, or set a bearer token). A page cannot add that header without a preflight these routes never answer. `/handoff` is the one state-changing `GET` on these routes; the other `GET`s are reads a foreign page cannot see the answer to, and every cross-origin `POST` carries `Origin`. Every first-party client sends the marker: the native hook (`hook_capture.rs` `post_hook`/`post_batch`/`get_handoff`), CLI subcommands (`http_client.rs` `ServerEndpoint::authenticate`), every curl in `hooks/_lib.sh`, both header tables in `hooks/lib/ai-memory-hook.ps1`, and the generated TypeScript integrations (`render_shared.rs` `ts_auth_headers_fn` plus the spool drain). Loopback hosts keep accepting a fetch without it, so hooks staged before the header existed still work on a default install, except that a request carrying any proxy forwarding header (`Forwarded`, `X-Forwarded-For`/`-Host`/`-Proto`/`-Server`/`-Port`, `X-Original-Forwarded-For`, `X-Real-IP`, `X-Client-IP`, `CF-Connecting-IP`, `True-Client-IP`, `Via`; `PROXY_HEADERS`) counts as non-loopback, since a plain-HTTP proxy can rewrite `Host` to loopback while the browser behind it sent no fetch metadata. No first-party client sends those headers. Hooks, the CLI and MCP clients send none of these headers; the web UI's same-origin `/admin/pending-writes` calls are `fetch()` (`Sec-Fetch-Dest: empty`) and pass. Behind it, axum `Json` and rmcp's `Content-Type: application/json` check refuse the preflight-free content types (`text/plain`, form-urlencoded, multipart) with 415; `require_allowed_host` (and rmcp `allowed_hosts` on `/mcp`) refuses a rebinding `Host`; machine/admin routes carry no CORS layer, so a preflight never comes back permissive. A stored wiki page viewed in the built-in web UI could otherwise turn the guard's same-origin allowance into a claim: `ai-memory-web/src/markdown.rs` `safe_image_url` / `is_safe_image_target` render as `#` any image target that is root-relative, a network path, carries a `..` segment (also percent-encoded), or, for a UI mounted at the base-path root, starts with a server route segment Every `/web` surface (built-in pages including `/web/pending`, the login page, a custom SPA and `/api/v1`) answers `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'none'` (`ai-memory-web/src/mount.rs` `deny_framing`), because a framed page's own Approve/Reject `fetch()` is same-origin and the guard rightly lets it through | `cli/tests/suite/cross_origin_e2e.rs` `browser_cross_origin_requests_cannot_write_to_an_unauthenticated_loopback_server`, against the shipped `serve`: every write route (`/hook`, `/hook/batch`, MCP `memory_write_page`/`memory_delete_page`/`memory_message_send`/`memory_handoff_accept`, `/admin/write-page`/`delete-page`/`purge-project`/`messages/send`, `/workstream/runs`) × each simple content type × modern, Origin-only and fetch-metadata-only browser shapes → 4xx; body-less `GET /handoff` (which claims the single-use baton), `POST /admin/profile/rebuild` and `POST /admin/backup` → 403; a rebinding `Host` → 403; preflights answer no `Access-Control-Allow-*`; `GET /handoff` as a same-origin `document` or `image` and as a `Sec-Fetch-Site: none` `document` → 403 with the baton still open. Then a canary scan of the whole data dir, page/project/handoff survival, and legitimate controls (JSON MCP calls, a JSON hook → 202, the web UI's same-origin `/admin/pending-writes` list and approve reach their handlers, the anonymous active-project pointer is unmoved after the refused `/handoff` fetches while the closing hook-style fetch claims the baton and moves it). `serve.rs` `cross_origin_browser_request_detection` and `non_script_browser_request_detection` (header tables) and `cross_origin_browser_guard_applies_only_without_auth` (same-origin `image` and `none` `document` refused, same-origin `empty` passes, both pass with auth on); `ai-memory-web` `markdown.rs` `neutralises_images_that_reach_server_routes` (`/handoff?…`, `/admin/backup`, `//host/…`, `../` and `%2e%2e/` traversal, root-mounted route names refused) with `preserves_relative_images` as the legitimate control. `cross_origin_e2e.rs` `handoff_fetch_on_a_lan_host_requires_the_client_marker`, against a `serve` that allowlists a LAN name and address: `GET` and `HEAD /handoff` through either without the marker, and with an empty one → 403 carrying the remedy text, with the baton still open and the active-project pointer unmoved; controls: a marked fetch through the LAN name claims the baton, and a marker-less fetch through `127.0.0.1` (a hook staged before the marker) claims the next one; then a `127.0.0.1` fetch carrying each proxy forwarding header and no marker → 403 with the baton still open, and the same fetch with the marker claims it. `serve.rs` `loopback_host_detection`, `handoff_fetch_client_marker_decision` (incl. a loopback `Host` with each proxy header, refused without the marker and admitted with it, and a named row per header so none can drop out of the list) and `handoff_client_marker_guard_on_lan_hosts_and_under_a_base_path` (also under a `--base-path` nest; inactive with auth on). Front-door parity: `hook_capture.rs` `every_native_hook_request_carries_the_client_marker` (handoff GET, hook POST, batch POST), `http_client.rs` `authenticate_no_token_sets_only_the_client_marker`, the client-marker block of `tests/hooks/test_lib.sh` (every curl branch of the GET, the POST and the drain, plus a static check that every PowerShell header table carries it and every `Invoke-WebRequest` passes one), `render_shared.rs` `assert_every_ts_request_carries_client_marker` run for OpenCode, OpenCode 2, OMP, Pi and OpenClaw, `external_capture_ts.rs` (the rendered OpenCode plugin under Node sends no unmarked request) and `external_capture_powershell.rs` `every_request_carries_the_client_marker` (Windows leg); `ai-memory-web/src/mount.rs` `web_surfaces_refuse_to_be_framed` (`/web`, `/web/pending`, `/web/login`, `/api/v1/projects` all carry both headers; bites with `deny_framing` neutralized) | STRONG with listed residuals. Bite checks: with the marker check disabled, the LAN e2e marker-less `GET /handoff` returns 200 and the unit layer test fails; with the proxy-header rule disabled, the proxied loopback e2e fetch claims the baton and the unit decision test fails; dropping the marker from the native handoff GET, the shell token-drain curl, a PowerShell header table or the TypeScript spool drain fails the matching front-door test. With the guard removed, the cross-origin `GET /handoff` returns 200, consumes the baton and moves the active-project pointer (the pre-fix behaviour); with the guard treating `same-origin` as foreign, the web UI control gets 403; with the `Sec-Fetch-Dest` check removed, the same-origin `document` `GET /handoff` returns 200 and the unit guard test lets a same-origin image through; with the host layer removed, a rebound `/hook` returns 202; a permissive `CorsLayer` fails the preflight assertion; reverting `is_safe_image_target` to the pre-fix rule fails the markdown test on `/handoff?…`, dropping the percent-decoding fails it on `%2e%2e/`, and emptying the route list fails it on a root-mounted `handoff`. To reproduce the bite on the 415 layer, remove the guard and make `/hook` read a raw body instead of `Json`: a `text/plain` hook then returns 202 and the test fails. Residual, closed by setting a bearer token: a browser that sends no fetch metadata even to a loopback host (Safari before 16.4) sends no `Sec-Fetch-*` header and no `Origin` on an image `GET` or a link click, so such a request to a loopback host still reaches `/handoff` (loopback keeps accepting marker-less legacy hooks) and the other, read-only `GET` routes. On a non-loopback host the marker requirement closes `/handoff` for every browser. A plain-HTTP proxy that rewrites `Host` to its loopback upstream and adds no forwarding header (nginx's default `proxy_pass`) looks exactly like a local client, so in front of an unauthenticated server it must add `X-Forwarded-For` or keep `proxy_set_header Host $host`, or the server must sit behind TLS or use a bearer token (`security.md`, `https-via-proxy.md`). Browsers that send fetch metadata no longer have the earlier link residuals: a link opened from another app (`Sec-Fetch-Site: none`) and a link clicked in a stored page (`same-origin` navigation) both carry a non-`empty` destination and are refused. With auth on, the bearer token and the session CSRF token are the gate and this layer is a no-op |
| 12d | The web UI and `/api/v1` cannot write, and render stored text inert | `crates/ai-memory-web/clippy.toml` `disallowed-methods`: every `Wiki` write and destructive method (`write_page`, `write_page_if`, `apply_batch`, the delete/evict/purge/restore/move/reindex/remove-dir helpers, `commit_all`, `approve_auto_improve_proposal`) and the `writer()` / `git()` accessors are lint errors in the crate, so the `Wiki` held by `WebState` stays read-only under `cargo clippy -D warnings`; only the integration-test module carries the `allow`, for fixtures. Templates are askama with HTML auto-escaping; the history diff (`templates/history.html`) and the session timeline (`templates/session.html`) print page lines, observation titles and bodies escaped, with no `|safe`, and no captured value is interpolated into a script | `ai-memory-web` `history_replay.rs` `session_timeline_renders_captured_markup_inert` (a `<script>` title and body plus `"><img onerror>` and `' onmouseover='` payloads, checked to survive ingest first, render escaped) and `history_diff_renders_page_markup_inert` (the same payloads in a page version's diff lines); `mount.rs` `web_surfaces_refuse_to_be_framed` covers the history, timeline and history-API routes (200 with both anti-framing headers) | STRONG. Bite checks: a `Wiki::write_page` and a `Wiki::delete_page` call added to `routes/history.rs` fail `cargo clippy -p ai-memory-web --all-targets -- -D warnings` with `use of a disallowed method`; `|safe` on the observation body or a diff line fails the matching inert-render test. The lint is per crate: a write reached through another crate's helper is outside it, which review and the `/api/v1` "zero writer calls" rule still cover |