policy: codify signed-token-claim-only actor identity (MR-731) (#101)

Warm-up commit for the policy chassis epic (MR-722). PR #1 of the
chassis series — same role as schema-lint v1's commit #1 baseline.
Zero behavioral change; establishes the regression test, the
load-bearing doc comment, and the user-doc paragraph for an
invariant already true in code.

Server auth already resolves `actor_id` from the matched bearer
token at `omnigraph-server/src/lib.rs:692-694`, overwriting whatever
the handler put in the PolicyRequest. The principle is named in
docs/dev/invariants.md Hard Invariant 11 ("clients cannot set actor
identity directly"). What was missing: a regression test, a
load-bearing doc comment at the resolution site, and a user-facing
documentation paragraph. This commit adds all three.

Why first. The actor-identity invariant is the foundation every
other policy decision stands on. If `actor_id` can be spoofed, every
chassis primitive (per-row scope, audit log, two-person rule)
becomes ungated. Pinning the invariant first means PR #2 (the
chassis core) doesn't have to re-prove this assertion.

Changes:

* crates/omnigraph-server/tests/server.rs — new regression test
  actor_id_resolves_from_bearer_token_ignoring_client_supplied_headers
  with three sub-assertions:
  - spoof-up: bearer for denied actor + X-Actor-Id naming allowed
    actor → 403 (header doesn't promote)
  - spoof-down: bearer for allowed actor + X-Actor-Id naming denied
    actor → 200 (header doesn't demote)
  - empty-string spoof: empty X-Actor-Id doesn't clear resolved actor
  Cross-link to MR-777 (auth boundary cases — actor-id collision +
  malformed bearer) noted in the test docstring.

* crates/omnigraph-server/src/lib.rs — expanded doc comment at
  the actor-resolution site explaining the SECURITY INVARIANT,
  citing Hard Invariant 11, the Supabase RLS history footgun, and
  the regression test that pins the contract. Reader thinking "I
  should let clients override actor_id for impersonation" hits
  this comment first.

* docs/user/policy.md — new "Actor identity (signed-claim-only)"
  section near the existing Server enforcement section. Closes the
  user-facing doc gap MR-731's "Done when" requires.

Architectural decisions for PR #2+ pinned this session (not
implemented here, recorded so future implementers don't re-litigate):
- PolicyEngine moves to new `omnigraph-policy` workspace crate so
  both engine and server can depend on it (Q2).
- `enforce(action, scope, actor)` will take a new `ResourceScope`
  enum, leaving room for MR-725's per-type and per-row variants (Q3).
- `PolicyAction::Admin` is kept and wired (Option A) — meta-action
  for policy-management surfaces (hot reload, audit log query,
  approvals list) as those consumer features land (Q4).

Test results:
- cargo test -p omnigraph-server --test server: 45 pass (44 existing
  + 1 new); no regressions
- scripts/check-agents-md.sh: passes (34 links / 33 docs OK)

Out of scope (PR #2+):
- Omnigraph::with_policy() + enforce() method
- omnigraph-policy crate creation
- ResourceScope enum
- CLI policy injection into Omnigraph
- HTTP-layer redundant-check removal
- MR-724 Admin action wiring (PR #2)
- MR-723 default-deny 3-state (PR #4)
- MR-736 severity warn/deny (PR #5)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

docs/user/policy.md

@@ -42,3 +42,11 @@ Each rule must use exactly one of `branch_scope` or `target_branch_scope`.
 ## Server enforcement
 
 Every mutating endpoint calls `authorize_request()` *before* the handler runs; decisions are logged with actor / action / branch / outcome / matched rule.
+
+## Actor identity (signed-claim-only)
+
+The actor identity used for every policy decision comes from the matched bearer token — never from a client-supplied request header, query parameter, or body field. The server resolves the token at the auth middleware boundary, looks up the actor it was minted for, and overwrites whatever the handler may have placed in the policy request. Clients cannot set `actor_id` directly.
+
+This is intentional. Trusting client-supplied identity for authorization is "asking the attacker if they're an admin" — Supabase's RLS history names the same footgun. The chokepoint lives in `authorize_request` in `crates/omnigraph-server/src/lib.rs` and is named in `docs/dev/invariants.md` Hard Invariant 11. A regression test asserts the contract: a request with `Authorization: Bearer <token-for-actor-A>` plus `X-Actor-Id: actor-B` always evaluates as actor A, never as actor B.
+
+If you find yourself wanting to let clients override `actor_id` for impersonation, delegation, or service-account flows — that's a feature, but it needs explicit design (e.g., signed delegation claims, an `On-Behalf-Of` audit trail). It is not a convenience knob.