omnigraph/docs/user
Andrew Altshuler a275306a15
policy: CLI policy injection — local writes go through engine enforce (MR-722) (#104)
Closes the CLI side of the policy chassis fan-out. Before this commit,
CLI direct-engine writes bypassed Cedar entirely because the CLI never
called `Omnigraph::with_policy(...)` for non-`policy validate|test|explain`
subcommands. After this commit, every CLI direct-engine writer
(change, load, ingest, branch create/delete/merge, schema apply) opens
the engine via a new `open_local_db_with_policy(uri, &config)` helper
that installs the configured `PolicyEngine` when `policy.file` is set,
and threads the resolved actor through to the `_as` writer methods.

Actor identity resolution:

- New top-level `--as <ACTOR>` global flag on the CLI overrides config.
- New `cli.actor` field in `omnigraph.yaml` provides a default actor.
- Precedence: `--as` > `cli.actor` > None.
- When policy is configured and neither is set, the engine-layer
  footgun guard fires and the write is denied — silent bypass via
  "I forgot the actor" is exactly what the guard prevents.
- Remote HTTP writes ignore both — bearer-token-resolved server-side.

Helpers added in main.rs:

- `open_local_db_with_policy(uri, &config) -> Result<Omnigraph>` —
  opens the DB and installs the PolicyEngine when configured. Without
  policy this is identical to a bare `Omnigraph::open`.
- `resolve_cli_actor(cli_as, &config) -> Option<&str>` — implements
  the flag > config > None precedence.

Engine: added `load_file_as` to the loader as the actor-aware mirror of
`load_file`, so CLI file-path loads flow through the same enforce gate
as in-memory `load_as` calls.

Test rewrite: `local_cli_policy_tooling_is_end_to_end_while_local_writes_stay_unenforced`
was the explicit assertion of the pre-chassis hole. Renamed and split:

- `local_cli_policy_tooling_is_end_to_end` — sanity for the read-only
  policy CLI surfaces (validate/test/explain), unchanged behavior.
- `local_cli_change_enforces_engine_layer_policy` — the new assertion:
  policy installed + no actor → footgun-guard denial; `--as act-bruno`
  on protected main → Cedar denial; `--as act-ragnor` (admins-write
  rule) on main → permit, write committed.

POLICY_E2E_YAML gains an `admins-write` rule so the permit case has
a non-trivial actor to exercise.

docs/user/policy.md updated with `cli.actor` + `--as <ACTOR>` usage.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-18 04:06:21 +03:00
..
audit.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
branches-commits.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
changes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
cli-reference.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
cli.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
constants.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
deployment.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
embeddings.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
errors.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
index.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
indexes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
install.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
maintenance.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
policy.md policy: CLI policy injection — local writes go through engine enforce (MR-722) (#104) 2026-05-18 04:06:21 +03:00
query-language.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
schema-language.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
schema-lint.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
server.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
storage.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
transactions.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00