ai-memory/docs/users.md

# Multi-user attribution

> **Status:** Introduced in v0.8; human password login, web sessions, and
> native `aim_` API credentials are the current shipped contract.

ai-memory is **single-tenant wiki data** with **optional multi-user
attribution**. Every authenticated request sees the same wiki pages —
there is no per-page RBAC or group permission model. Operational handoffs and
open-session recovery are owner-scoped so one operator cannot accidentally
consume or finalize another's live context. What multi-user mode also adds is
*who-did-this*: every write
attributes to a named user, audit-log rows carry that identity, and the
web UI can show "Last edited by Alice Smith" instead of the anonymous
default. Every `/admin/*` endpoint stays root-only once the deployment has a
DB user or trusted-proxy identities, including read-only
status/search/read-page helpers.

Hook session identifiers are also owner-bound. A hook authenticated as one
operator cannot reuse another operator's UUID to append events or trigger a
summary/handoff/end transition. Shared legacy sessions remain available to all
callers. Cross-owner recovery is limited to root's explicit
`finalize-session --all-owners` path.

Authenticated clients sharing one server must emit a distinct agent-run id for
each run and forward that same id on their MCP requests when using session-aware
auto-scope. Legacy sessions whose stored owner is `NULL` remain shared.

If you run ai-memory alone, you can skip this page — your install
keeps working unchanged.

## When to enable it

You probably want multi-user mode when:

- More than one human shares a single ai-memory server (a household,
  a small team's homelab).
- You want the audit log to record *who* made each write (e.g. to
  trace `Codex` writes vs `Claude Code` writes vs hand-rolled CLI
  calls).
- You're planning to use the admission webhook chain —
  webhooks receive the actor identity in their payload.

You probably **don't** need it when:

- You're the sole human user of your install. Single-user mode (no user rows)
  remains compatible whether or not `init` has generated `[auth].token_pepper`.
- You need permissions / access control. v1 of ai-memory does
  not implement RBAC by design (see
  [`design-decisions.md`](design-decisions.md) §13). Attribution
  records *who* did a write; it does not gate *whether* they
  could.

## The four resolution rungs

Every HTTP request is resolved to one of four authentication tiers:

| Rung | Trigger | What the request gets |
|---|---|---|
| **0 — Anonymous** | No `[auth].bearer_token` set. | Allowed, no identity. Same as pre-multi-user defaults. |
| **1 — Root** | Bearer matches `[auth].bearer_token`. | Allowed as **root**. When `[auth].root_username` is set, writes attribute to that name; otherwise attribution stays anonymous. |
| **1b — Proxy-asserted user** | Bearer matches the distinct `[auth].actor_proxy_bearer_token`. | Identity is taken from trusted `X-Memory-Actor-*` headers. The request is a **user** unless its OIDC issuer/subject pair exactly matches the configured root pair. Missing or malformed identity is rejected. |
| **2 — DB user** | Bearer doesn't match root, matches an active `api_credentials.token_hash` (SHA-256 of the secret + `[auth].token_pepper`). Native keys use the `aim_` prefix. | Allowed as **that user** for normal read/write APIs. Native keys always resolve as `AuthLevel::User`, even when the owning identity is `role=root`. All `/admin/*` endpoints are root-only in multi-user mode. The audit log records the username/email/name. |
| **3 — 401** | Bearer present but matches nothing. | Rejected. Closes the bypass — unknown bearers can't slip through as anonymous. |

The rungs are sticky: a request is matched at the first credential that
applies, never escalates. Startup rejects equal root and proxy credentials;
root and proxy credentials take precedence over any accidental DB-token
collision.

Human password login is **not** a bearer rung. A browser session cookie never
authenticates `/mcp`, `/hook`, `/handoff`, or `/workstream/*`, and a password
never authenticates as `Authorization: Bearer`.

## Human login (password + web session)

The console signs in with username and password. The engine issues an
`HttpOnly` `ai_memory_session` cookie (`ams_` secret, hash only in SQLite)
plus a separate CSRF cookie that the SPA must send on cookie-authenticated
`POST`/`PUT`/`PATCH`/`DELETE`. Machine Bearers skip CSRF.

| Endpoint | Class | Notes |
|---|---|---|
| `POST /auth/login` | public | Rate-limited. Returns the `/auth/me` snapshot plus `Set-Cookie`. |
| `GET /auth/me` | session | Identity, `role`, `must_change_password`, capabilities. Anonymous only in zero-config loopback. |
| `POST /auth/password` | session + CSRF | Changes password, revokes other sessions, rotates this one. |
| `POST /auth/logout` | session + CSRF | Revokes the session and expires cookies. |
| `POST /auth/recovery` | public | Break-glass for the configured `root_username`. Never issues a session. |

Passwords are Argon2id PHC strings, 12–1024 UTF-8 bytes, hashed off the writer
actor. The last enabled root with a password cannot be disabled or demoted.

Greenfield bootstrap consumes `AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORD` once
(`human_auth_state.bootstrap_completed`). Later restarts ignore it — unset the
env var. Lost root uses `AI_MEMORY_AUTH__RECOVERY_TOKEN` (at least 32
characters), compared constant-time and never stored in SQLite. Public
recovery failures — wrong token, recovery unset, or password policy —
share one 401 `{"error":"invalid credentials"}` body. `Config::load()`
rejects equality among the initial password, recovery token, root bearer,
and actor-proxy bearer without logging the values. Operator runbook:
[Human password bootstrap and recovery](install.md#human-password-bootstrap-and-recovery).

`/admin/*` and `/api/v1/*` accept a machine Bearer **or** a web session.
Custom SPA HTML at `/web` is public static; the builtin wiki browser stays
behind auth. With human auth active and no session, a browser GET to the
builtin wiki redirects to `{web_slug}/login` (HTML form → `POST /auth/login`);
`must_change_password` redirects to `{web_slug}/change-password`. JSON clients
and `/api/v1` still receive JSON 401/403. Once human auth becomes active, the
engine expires the deprecated `ai_memory_auth` compatibility cookie.

## Trusted proxy identity

A deployment that terminates SSO validates the end user's credential, then
authenticates upstream with a proxy-only bearer and describes the human in
`X-Memory-Actor-*` headers. Those headers are **ignored by default** on root
and DB-user requests because anything that can reach the port could otherwise
claim any identity.

Configure a distinct proxy credential:

```toml
[auth]
bearer_token = "<root-token>"                    # direct administration
actor_proxy_bearer_token = "<different-token>"  # SSO proxy only
secure_cookie = true                              # required beyond loopback

# Optional stable identity for the root human behind an OIDC proxy.
root_issuer = "https://idp.example"
root_subject = "<root-subject>"
```

- The proxy token **is** the switch. A blank value counts as unset. It must
  differ from `bearer_token`, and `serve` refuses startup otherwise or when the
  root bearer is absent.
- Only set it when the server is reachable *only* through that proxy.
- `secure_cookie` is independent of proxy identity. Human auth requires it on
  every non-loopback listener; ai-memory treats it as the explicit signal that
  a trusted reverse proxy terminates HTTPS for `/web` and never trusts
  forwarded protocol headers to infer that fact. Direct HTTP browsers will not
  send a Secure cookie.
- **The proxy MUST strip client-supplied `X-Memory-Actor-*` headers before
  setting its own.** Use a directive that *replaces* the header rather than
  appending to it (nginx `proxy_set_header`, Traefik `customRequestHeaders`) —
  with an appending ingress the client's value arrives first and would be the
  one read. Repeated headers and comma-folded values are rejected with `400`
  rather than resolved to one identity.
- Every proxy request must assert `X-Memory-Actor-User`, or both
  `X-Memory-Actor-Issuer` and `X-Memory-Actor-Sub`. The OIDC fields are a pair:
  the standard guarantees subject uniqueness only within an issuer. A partial
  pair or a request that names nobody is rejected with `400`.
- Proxy callers are users by default. A username-only assertion can never
  become root, including one equal to `root_username`, because an OIDC display
  username is not a stable unique identifier. Proxied root access requires an
  exact match with `root_issuer` plus `root_subject`.
- Origin health checks or maintenance calls that need root should use the root
  bearer, not the proxy bearer. Raw actor headers on the root rung are ignored.
- **A proxied non-root end-user is not subject to per-project `restricted`
  grants.** The proxy branch authenticates the request as `AuthLevel::User`
  with an `ActorContext`, but — unlike a database user — never maps it to a
  database `UserId`/`AuthorizedViewer`: grants are keyed on `UserId`, and a
  proxied identity has none to key on. A missing `AuthorizedViewer` reads as
  "no per-project check applies" (the same as root, or an install with no
  database users at all), so a `restricted` project is readable by any
  proxied user with no grant. This is by design, not a gap: in a trusted-proxy
  deployment the proxy itself is the authorization boundary. If you need
  per-project `restricted` enforcement for individual end users, issue them
  database-user tokens (see above) instead of relying on the proxy headers.

## Identity keys

Identity-sensitive routing uses a *qualified* identity, never a bare string.
`ActorContext::identity_key()` resolves a request to the OIDC
`(issuer, subject)` pair when both are present, or to `user:<name>` for a
username-only identity. The namespaces are disjoint, and identical subjects
from different issuers stay different.

The OIDC pair outranks `user` because OIDC defines `(iss, sub)` as the stable
identifier and explicitly forbids relying on `preferred_username` for
uniqueness. Configure the proxy to forward both values from day one. Adding a
display username later then preserves the same identity; moving from a
username-only assertion to the OIDC pair deliberately changes it once.

## Ownership of handoffs and sessions

Handoffs and sessions record the operator they belong to (`owner_user` /
`actor_user`, holding the qualified `IdentityKey::storage_key()` TEXT). On a
shared server this stops one operator's pending handoff from being delivered
to — and consumed by — the next session to start, whoever it belongs to.

- A `NULL` owner means **shared with the project**: every row written before
  ownership existed, and anything written without an authenticated actor, stays
  visible to everyone.
- **An owner is only stamped where the deployment distinguishes operators.**
  Single-operator servers are unaffected even when they name their operator via
  `[auth].root_username`: with no `users` rows and no proxy bearer there is
  nobody to separate, and stamping the one name would separate that operator's
  *transports* instead — HTTP requests carry the name, while the stdio /
  in-process MCP transport and the local CLI carry no actor at all and would
  stop seeing what the HTTP side wrote. Reads are deliberately **not** gated the
  same way, so a row stamped while the deployment did distinguish operators
  stays readable by that operator afterwards.
- The owner is the qualified identity the request names —
  `ActorContext::identity_key()`, so the issuer-qualified OIDC key when a
  complete issuer/subject pair is asserted and `user:<name>` otherwise. It is
  the same rule that decides the auth tier, so the proxy path gets real
  per-operator isolation rather than one shared bucket.
- `memory_handoff_begin` takes `shared: true` to publish a baton deliberately.
- `memory_handoff_list` / `memory_handoff_accept` / `memory_handoff_cancel` take `any_owner: true` to
  act on somebody else's baton; that opt-out requires admin authority in
  multi-user mode.
- `ai-memory finalize-session --all-owners` does the same for sessions, and
  `GET /admin/open-sessions?all_owners=true` is the underlying switch.
  `--session-id <uuid>` / `session_id=<uuid>` narrows the same owner-scoped
  lookup to one exact open session; it cannot be combined with `--all` /
  `all=true`.
- `GET /admin/sessions/by-agent` reports how many sessions each agent CLI
  opened in a scope. It follows the same rule: the caller's own sessions
  plus the unowned ones, with `all_owners=true` to see every operator's. Pass
  the required `workspace` and `project` query parameters and optionally
  `since_days=N`; zero or omission means all history. Results use the stable
  shape `{"by_agent":[{"agent":"codex","sessions":3}]}`, ordered by count
  descending and then agent name. An unknown scope returns 404 without creating
  it. Like every `/admin/*` route, this endpoint is root-only when the
  deployment distinguishes operators.
- The read-only handoff listing (`GET
  /api/v1/workspaces/{ws}/projects/{p}/handoffs`) serves its prompt-derived
  fields — `summary`, `open_questions`, `next_steps` — to a caller the server
  can name (their own rows plus the shared ones) and to the root operator, who
  reads every page body through the wiki API anyway. A caller an authenticating
  server can place as neither gets the metadata with `redacted: true`. A server
  with no auth configured is unaffected: it already serves every page body
  unauthenticated. The default listing remains own plus shared; root may request
  the explicit recovery view with `?all_owners=true`, while user and anonymous
  tiers receive `403`.
- Handoff lifecycle events raise admission ops (`handoff_begin`,
  `handoff_accept`, `handoff_cancel`), so an admission webhook can observe or —
  with `failure_policy = "reject"` — refuse them. Only reject-policy hooks are
  awaited on these ops; observers are notified after the operation is durable.

"Multi-user mode" here means *the deployment distinguishes operators*: either
`users` rows exist, or `[auth].actor_proxy_bearer_token` is configured. A trusted
proxy never writes a `users` row, so counting only rows would leave every
proxied caller on the single-operator escape hatch that waves admin through.
One question, every gate: the MCP admin tools, the `/admin/*` route layer, and
the ownership stamped on handoffs and sessions all ask it.

## MCP client activity

`GET /admin/activity/by-client` reports server-wide MCP tool calls rather than
lifecycle sessions or project-owned data. Stateful HTTP and stdio use the
sanitized MCP `clientInfo.name`; stateless requests fall back to an
authenticated proxy's actor-agent label and then `unknown`. Results have the
stable shape
`{"by_client":[{"client":"claude-code","reads":12,"writes":3}]}` and are
ordered by total calls, then client name.

`since_days=N` includes every UTC day bucket intersecting that lookback; zero
or omission means all history. Calls flush on a one-minute background interval
even if no later request arrives, and retry failed batches once per interval;
process exit can lose the current interval. Each UTC day stores at most 128
distinct labels and folds additional labels into `other`. The endpoint takes
no workspace or project because many MCP-only clients do not provide reliable
per-call scope. Like every `/admin/*` route, it is root-only when the deployment
distinguishes operators.

## Per-operator memory slots

The "absent means shared" rule extends to memory slots, so a single-operator
server behaves exactly as it always has. `_slots/current-focus.md` is injected
into every operator's context; `_slots/<segment>/current-focus.md` is injected
only into the operator whose `path_segment()` is `<segment>` (`u-alice`,
`uh-<uuid>` for a mixed-case, trailing-period, or otherwise path-hostile
username, or `o-<uuid>` for a complete OIDC issuer/subject pair). What the
feature scopes is injection, not access: a slot is an ordinary wiki page, so
exact reads and searches remain project-wide like every other page. Every slot
written before this is unnamespaced, therefore shared.

`[slots] per_user` (default off) is the switch for the whole regime. With it
ON:

- session briefs and consolidation prompts show you the shared slots plus your
  own — including the pointer list of recently touched pages, so another
  operator's slot path and title stay out of your brief too;
- the engine namespaces the slots it writes: a consolidation run that targets
  the shared slot lands in the session operator's own namespace instead, and a
  path the model aims at somebody else's namespace is skipped rather than
  written or re-homed — that path comes from the model, and
  anything reaching your observations can dictate it;
- a `memory_write_page` call naming the SHARED slot is namespaced into your
  own prefix, exactly as the engine would (the response reports the path the
  page actually got), and writing into another operator's namespace is refused
  (admins may still curate any namespace, the shared slot included).

With it OFF a nested slot path means nothing in particular — every slot goes
into every brief, exactly as before the feature existed — so turning it back
off makes personal slots visible to everyone again rather than stranding them.

The `<segment>` is derived from the qualified identity on this server: a short,
lowercase, path-safe ASCII username stays readable, while a mixed-case,
trailing-period, or otherwise path-hostile username or complete OIDC
issuer/subject pair becomes a bounded deterministic identifier. Restricting
readable segments to lowercase without trailing periods prevents distinct
identities from producing pathnames that compare alike on supported
case-insensitive filesystems. The OIDC pair
outranks the username; see "Identity keys" above. Every named operator owns a
working namespace, and long or path-hostile values never fall back onto the
shared slot. One consequence of qualified segments is worth stating: a nested
path written before the feature
(`_slots/backend/…`) spells a segment no qualified identity can produce, so
with the flag ON it belongs to nobody and reaches no brief until the flag is
turned back off or an admin re-homes it.

Before the case-insensitive namespace fix, a mixed-case username such as
`Alice` used the readable segment `u-Alice`, and a username ending in a period
kept that period; both now use deterministic `uh-<uuid>` segments. ai-memory
cannot safely move the old directory automatically because a case-insensitive
filesystem may already have combined it with another identity. Administrators
upgrading a shared deployment with `[slots] per_user = true` must inspect any
affected `u-…` slot directories and re-home confirmed content into the owning
operator's new namespace. Preserve the old pages until ownership is
established; do not infer it from filename casing alone.

One gap is deliberate and documented rather than closed: `ai-memory bootstrap`
writes pages at paths the model picks from the repository's own README, docs
and code, with no operator to attribute them to, so a repo carrying injected
instructions can make it write a `_slots/…` page. It is an admin-only
operation on a repository the admin chose to ingest, and the behaviour is the
same with the flag off; review `bootstrap.md` — it lists every path written.

## Other per-operator state

Beyond attribution, some engine state is recorded per operator. "Absent means
shared" is the rule throughout — a row with no recorded operator behaves
exactly as it did before the column existed — so a single-operator server
keeps its historical behaviour:

- **Auto-improvement proposals.** Each records the operator who staged it (the
  qualified identity key — username or complete OIDC issuer/subject pair — so
  proxy-asserted humans count too, and it shows up on the proposal detail),
  and the "one
  pending proposal per page" rule applies per operator, so operators stop
  blocking each other. Only where the deployment distinguishes operators,
  though: elsewhere proposals stay unattributed and the original one-per-page
  rule holds unchanged. A scheduled run has no caller and stages unattributed;
  the telemetry report and the curator describe the project rather than a
  person and stay unattributed too, so they neither block nor are blocked by
  any named operator's pending proposal for the same page.

  A proposal that does collide with one already pending is skipped on its own
  — the run's other proposals still stage — and every staging surface reports
  the skip with the target path and the reason (the `skipped` list in the MCP
  and `/admin` responses, the CLI output, and the scheduler's log), so a run
  of N-1 proposals is never silently indistinguishable from a clean run of
  N-1.
- **Page reinforcement.** The first reinforced read by each identified
  operator is recorded per page alongside the existing shared access counter.
  `[decay] breadth_weight` (default `0.0`) optionally lets a
  page reinforced by many different people outrank one read repeatedly by a
  single person — the forget sweep reads the per-page count of distinct
  operators and feeds it into the retention score. At the default, and for
  pages with fewer than two distinct readers at any weight, retention scores
  are unchanged.

## Implementation contract

Request identity and authorization are separate:

- `ActorContext` carries who made the request and is used for attribution,
  frontmatter, audit payloads, and active-project keys.
- `AuthLevel` carries what auth tier the middleware resolved.
- `AuthLevel::authorize(Capability::...)` is the shared permission check for
  admin routes, user-management routes, normal read/write surfaces, and the
  admission-chain skip header.

Handlers should not compare usernames, infer root from `ActorContext`, or add
ad hoc root-only branches. PRs that touch auth behavior should cover root,
DB-user, and anonymous callers, including the single-user compatibility mode
where `[auth].token_pepper` is absent.

## Quick start

> Prerequisite: a fresh `ai-memory init`. Pre-v0.8 installs need
> the [migration step](#migrating-an-existing-single-user-install)
> below before any of these commands work.

### 1. Set the root identity

Edit your `config.toml` (typically `<data_dir>/config.toml` or
`/etc/ai-memory/config.toml`) and uncomment the `root_*` lines in
the `[auth]` block:

```toml
[auth]
bearer_token = "<your-existing-token-or-a-fresh-one>"
token_pepper = "<auto-generated-by-ai-memory-init>"

root_username = "boss"            # required for root attribution
root_email    = "boss@example.com" # optional, surfaced in UIs
root_name     = "Boss"             # optional, surfaced in UIs
```

`token_pepper` was auto-generated by `ai-memory init`; **do not
change it after issuing native API keys** — rotating the pepper invalidates
every `aim_` credential. The pepper makes copied
`api_credentials.token_hash` rows useless to an offline attacker; human
passwords and sessions do not use it.

`init` creates the pepper before any keys exist. Human users and web
sessions can operate without a machine-root bearer; native API-key lookup
still requires the original pepper. If `api_credentials` contains rows and
the pepper is missing or blank, `serve` refuses startup before applying
human bootstrap. Restore the original pepper from configuration backup
rather than deleting identities or keys.

### 2. Add another human

Each `ai-memory user add-human` creates a person with a temporary password,
printed **exactly once**. The new user must change it on next login.
This does **not** issue an API key.

```console
$ AI_MEMORY_AUTH_TOKEN=<root-token> \
  ai-memory user add-human --username alice --email alice@home --name "Alice Smith"

✓ created user 'alice'
  name:  Alice Smith
  email: alice@home
  role:  user

Store this temporary password now — it will NOT be shown again.
The user must change it on next login.

xK7mPq...<temp password>
```

stderr carries the human chrome; stdout is the bare password so you can
pipe it. Use `--role root` to create a second recoverable root.

### 3. List users

```console
$ AI_MEMORY_AUTH_TOKEN=<root-token> ai-memory user list

USERNAME  NAME         ROLE  STATUS
alice     Alice Smith  user  must-change
bob       -            user  active
carol     -            user  disabled
dave      -            user  active
erin      -            user  expired
```

An `active` row without a password can be a deprecated 1.x compatibility-token
identity. Grant human login with `user reset-password`; that does not reveal or
rotate the machine secret. The list never surfaces passwords, hashes, or API
secrets.

### 4. Disable human login (without losing attribution history)

`ai-memory user disable <username>` stamps `disabled_at` and revokes web
sessions. Historical `author_id` references keep resolving. Native API
credentials stay valid — revoke those separately with `api-key revoke`.

```console
$ ai-memory user disable alice
Disable human login for user 'alice'? (y/N) y
✓ disabled user 'alice'
```

Pass `--yes` to skip the prompt (CI / scripts). Re-enable with
`ai-memory user enable alice`. The last enabled root with a password
cannot be disabled or demoted.

### 5. Issue, rotate, or revoke a native API key

Machine clients use `aim_` credentials, not passwords:

```console
$ ai-memory api-key add --username alice --label codex-laptop
✓ created API key '…' (codex-laptop)

Store this token now — it will NOT be shown again.

aim_mYi3pq...<secret>
```

```console
$ ai-memory api-key rotate <id>
$ ai-memory api-key revoke <id>
```

Rotation 401s the previous plaintext immediately. A revoked secret does
not come back; issue a new key instead. Native keys authenticate as
`AuthLevel::User` even when attached to a `role=root` identity —
root automation still uses `[auth].bearer_token`. External `amk_` keys
stay in `mcp-auth`; they are not listed here.

#### Where the token is stored

`install-hooks --apply --auth-token …` writes the bearer to two files inside
the data dir, both `0600` (the data dir itself is `0700`):

| file | read by |
|---|---|
| `<data_dir>/auth-token` | the native `ai-memory hook` command |
| `<data_dir>/auth-header` | the shell hooks, via `curl -H @<file>` |

`ai-memory uninstall` deletes both files when it removes the hooks (a full
uninstall or `--only hooks`); `--only mcp`, `--only instructions` and `--only
skills` keep them for the hooks still installed.

It is deliberately **not** written into the agent's own config any more. Before
#552 it went onto the hook's command line — `--auth-token <token>` for native
hooks, an `AI_MEMORY_AUTH_TOKEN=` shell prefix for the script hooks — which put
it in the agent's config file *and* in `/proc/<pid>/cmdline` for the lifetime of
every hook and every `curl`, readable by any local user, on every tool call.
The second file exists for exactly that reason: building the header inline
would put the credential straight back on a command line.

An explicit `--auth-token` on a hook command, or `AI_MEMORY_AUTH_TOKEN` in the
environment, still takes precedence — so configs written before this keep
working unchanged. Re-run `install-hooks --apply` to move an existing install
onto the stored form.

#### What rotation does to already-spooled hook events

A lifecycle hook that cannot reach the server writes the event to the local
spool **together with the bearer it was holding at the time**. Rotating a token
therefore strands every spooled event captured under the old one: each is
rejected with `401` on the next drain.

Since #542 the drain recovers them. Re-run `install-hooks --apply` with the new
token, and the next drain retries any `401`ed entry with the current bearer —
the hook that spawns the drain hands it down in the child's environment. The
retry is bounded: it only runs for an entry the server has already rejected,
only for a static bearer (an OIDC token is re-resolved and refreshed every pass
anyway), and only when the current token actually differs from the one that
just failed.

Until you re-run `install-hooks`, the hooks still hold the old token and there
is nothing newer to retry with — those events stay queued and age out on the
normal retry budget rather than blocking the rest of the spool (#493).

## Running for a team

Everything above concerns *who* a request is, which is the identity half. The
other half is *which project* it lands in, and it matters most once more than
one person shares a server.

**Knowledge is shared; batons are owned.** A page written in a project is
readable by every operator in that project — `pages.author_id` records who
wrote it and is never a read filter. That is the point of a shared server: what
one person learns, the next person retrieves. Handoffs are the opposite: a
handoff carries an owner, and only that operator receives it.

**Concurrent edits supersede rather than collide.** Two people editing the same
page produce a version chain, not a conflict; the later write becomes latest and
the earlier one stays reachable. There is no merge, and none is claimed — but
nothing is destroyed either.

**Isolation of the "current project" pointer is automatic** since v1.39. Unscoped
calls (the normal case — the MCP tools default to the current project) resolve
through a pointer keyed by the caller's identity and session, so two operators,
or one operator with two harnesses, do not overwrite each other. Confirm what a
server is running with the startup line:

```
active-project isolation mode mode=PerActor session_ttl_secs=3600 max_entries=4096
```

If that says `Single` on a shared server, unscoped reads **and writes** from
concurrent sessions share one last-write-wins slot. See
[auto-scope.md](auto-scope.md).

## Backward compatibility

If you're upgrading a machine-bearer-only install:

- **No immediate action is required.** Existing
  `[auth].bearer_token` authentication continues to work as before.
  Configure human bootstrap/recovery only when enabling password login.
- Migration V52 extends the existing `users` table with human role/password
  state and creates `web_sessions`; V53 copies every valid legacy
  `users.token_hash` into `api_credentials` without changing its digest or
  owner id.
- Deprecated 1.x `user add`, `user expire`, `user revive`, and
  `user rotate-token` commands remain available for compatibility. They manage
  the migrated `legacy-user-token` credential; new automation should use
  `api-key` commands, and new people should use `user add-human`.
  The V53 mirror triggers are load-bearing for those shims and remain until the
  shims are removed in 2.0.
- Before any human password or completed bootstrap exists, GET-only browser
  routes continue to accept the root bearer through HTTP Basic and the
  HttpOnly `ai_memory_auth` cookie. Human activation disables that path
  immediately, without a restart. Machine routes remain Bearer-only.
- Native API credentials require `[auth].token_pepper`. Human user creation,
  password reset, disable/enable, and session login do not create or depend
  on API keys.
- In human mode, `/admin/*` is available to a root web session or the
  machine-root bearer. Native `aim_` credentials always remain
  `AuthLevel::User` and receive **403** on root-only operations.

### Migrating an existing single-user install

`ai-memory init` is idempotent and won't overwrite a config it
finds. To populate `token_pepper` without losing your current
config:

1. **Back up the existing config** (`cp config.toml config.toml.bak`).
2. **Generate a pepper**: `ai-memory generate-auth-token 32` — this
   prints a hex string of the same shape `init` would have
   generated.
3. **Add the `[auth]` block** to your `config.toml`:

   ```toml
   [auth]
   # ... your existing settings (bearer_token, etc.) ...
   token_pepper = "<paste-the-generated-pepper-here>"
   root_username = "boss"     # optional; enables root-token attribution
   root_email    = "boss@..." # optional
   root_name     = "Boss"     # optional
   ```

4. Restart `ai-memory serve`. The new fields are picked up; existing
   behaviour is unchanged.

You can defer steps 3-4 indefinitely — `bearer_token` alone keeps
working as it always has.

## How credentials are stored

**Passwords** are Argon2id PHC strings on `users.password_hash` with a
random per-password salt. They never land in `api_credentials` and are
never compared as Bearer.

**Native API keys** (`aim_` + 43 URL-safe characters from 32 CSPRNG
bytes) store `SHA-256(token || ":" || token_pepper)` in
`api_credentials.token_hash`. The per-server `token_pepper` makes a
DB-only theft (a copied SQLite file) useless offline. Constant-time
comparison on the hash avoids timing leaks on the lookup path.
Argon2id is the wrong KDF here: 256-bit CSPRNG secrets are not
brute-forceable, and a per-hash salt would force O(N) scans on every
auth request. See `crates/ai-memory-store/src/api_credentials.rs`.

**Web sessions** hash a 256-bit `ams_` secret with SHA-256 (no pepper)
into `web_sessions`. The cookie is `HttpOnly`, `SameSite=Strict`,
`Path=/`. CSRF is a separate cookie compared to the session's CSRF
hash.

Brownfield `users.token_hash` values were copied losslessly into
`api_credentials` (same 32-byte digest, label `legacy-user-token`).
Runtime lookup no longer reads the old columns.

## Where attribution shows up

| Surface | Status |
|---|---|
| Auth middleware injects `Extension<ActorContext>` on every request | ✓ P1.3 |
| All `/admin/*` routes gate on `Extension<AuthLevel>::Root` in multi-user mode | ✓ P1.4 |
| `ai-memory user add-human/list/reset-password/disable/enable/patch`, deprecated `user add/expire/revive/rotate-token`, and `ai-memory api-key add/list/rotate/revoke` | ✓ |
| `pages.author_id` populated, frontmatter `last_modified_by` block | ✓ P1.6 |
| `/api/v1` page responses include `author: { username, name?, email? }` | ✓ P1.7 |
| ETag invalidation on author change (so caches refresh attribution) | ✓ P1.7 |
| `install-hooks --as-user <name>` metadata + flag validation | ✓ P1.8 |
| Web UI shows author on the page view | ✓ shipped |
| Attributed mutation audit rows carry `audit_log.author_id` | ✓ shipped |

Commit ids for each milestone are recorded in `CHANGELOG.md`.

## Wiring agent hooks to a specific user

After `ai-memory api-key add` prints a native secret, point that user's
agent install at it via `install-hooks`:

```console
$ ai-memory api-key add --username alice --label claude-hooks
✓ created API key '…' (claude-hooks)

aim_XGq...<secret>    # stdout only

$ ai-memory install-hooks --apply --agent claude-code \
    --as-user alice --auth-token aim_XGq...<secret>
[ai-memory] hooks installing for user: alice
✓ staged 5 hook script(s) → ...
```

`--as-user` is **metadata only**: it labels the install for the
operator's records and prints a confirmation line so you can verify
which identity the next session's writes will attribute to. The
actual token wired into the hook env block is whatever you pass via
`--auth-token`. Mismatching the two (e.g. `--as-user alice
--auth-token <bob's token>`) is permitted at the CLI layer; the
server will resolve to bob at runtime. The flag is there to keep the
operator honest, not to enforce.

Without `--as-user`, hooks install the same way they always have —
the bearer authenticates, attribution flows from the token's owner
(root user or DB user) at write time.

## Per-project access

Authentication says *who* is asking; each project's **access mode** decides
what they may reach (#708):

| Mode | Who reaches the project |
|---|---|
| `open` (default) | Every authenticated user — what every project was before access modes existed. |
| `restricted` | The root operator, the user who created it, and users holding a grant on it. |

Every existing project is `open` after upgrading, so nothing changes until an
operator restricts one:

```sh
ai-memory project access --workspace acme --project checkout-api --mode restricted
ai-memory user grant --user alice --workspace acme --project checkout-api --level write
```

Both are root-only. Restricting prints the users who have written to the
project, hold no grant and did not create it — the people it now refuses — so you can grant the
ones who should keep access; nothing is granted automatically.

- **Grants** are `read` or `write`, per project; `write` includes `read`.
  There is no per-project administrator: granting, revoking and restricting
  are the root operator's, like every other administrative act.
  `ai-memory user grant | revoke` manages them; `ai-memory user grants
  [--user NAME]` and `ai-memory project grants --workspace W --project P` list
  them (REST: `POST /admin/users/{name}/grant|revoke`,
  `GET /admin/users/{name}/grants`, `GET /admin/projects/grants`). A user holds one level
  per project; revoking deletes the grant, and purging a project or deleting
  its workspace takes its grants with it. Every grant, level change and revoke
  is recorded in the audit log (`grant_access` / `revoke_access`, with who did
  it), so "who could reach this, and since when" stays answerable.
- **Cross-project messages** respect access too: delivering into a restricted
  project's inbox needs `write` on it (otherwise the mailbox would be a way
  around its grants), and so do popping its inbox and cancelling its outbox,
  which change its queues. Listing them needs `read`.
- **Whoever creates a project** is recorded as its creator
  (`projects.created_by`) and keeps full access if it is later restricted,
  without holding a grant. Projects created before this existed, or by the
  root token, have no recorded creator.
- **New projects** are `open` unless `[auth] new_projects_restricted = true`
  (`AI_MEMORY_AUTH__NEW_PROJECTS_RESTRICTED=true`), which makes every project created from then on start `restricted`. The
  reserved `scratch` project and the global preferences scope always start
  open, and the global scope can never be restricted: it is shared by
  construction.
- **Gates entry, never rows.** Access decides which projects a user reaches;
  inside a project pages stay shared exactly as before (see below).
- **Refusals are explicit.** A user outside a restricted project gets a 403
  naming it and the level needed, never an empty result; search, listings and the graph leave it
  out rather than hinting at it. A hook capture into a project the user may
  not write is dropped and counted (`dropped_unauthorized` in status), not
  retried.
- **No database users, no checks.** A single-operator install, and the root
  bearer token, are never subject to access modes.

## Limitations


- **No per-page RBAC *within* a project.** This one is deliberate and separate
  from the above: pages are shared inside a project because multi-session and
  multi-user collaboration is a core capability. `pages.author_id` is
  attribution, never a read filter.
- **Native keys are not passwords.** `user add-human` never issues an `aim_`
  secret; `api-key add` never issues a login session. The deprecated `user add`
  command is the exception: it issues one compatibility token backed by the
  reserved `legacy-user-token` credential. Disable/reset of a human leaves API
  credentials untouched, and revoke/rotate of a native key leaves the
  password/session untouched. One identity may hold several native keys with
  distinct labels.
- **Root token is single.** `[auth].bearer_token` is the programmatic
  admin credential for `/admin/*`. A native key attached to a
  `role=root` identity still authenticates as `AuthLevel::User`. Human
  roots operate the console with a web session after password login.
- **OIDC is request authentication, not page authorization.** Native hooks and
  thin-client CLI commands can send a per-developer OIDC bearer for an external
  OIDC-aware gateway/bridge. Native ai-memory server auth still uses static root
  bearer / native `aim_` keys / web sessions, and `/admin/*` stays root-only unless a gateway
  translates accepted OIDC auth into upstream auth that ai-memory accepts.
  ai-memory still has one shared wiki per server and no
  per-page RBAC. Per-project access applies to the database user a gateway
  authenticates as, like any other. The Keycloak/OIDC `sid` claim is also not an ai-memory agent
  session id; session auto-scope needs the lifecycle-hook session id or explicit
  `workspace` + `project` / `scopes`.