Authorization Reference
The Authorization Reference is a read-only view of a project's authorization specification and generated state. Use it to understand a policy, inspect its rules and recorded assumptions, examine generated validation examples, and try concrete inputs against the compiled bundle.
npx ninka-authz docs
What it is for
The Reference helps answer practical review questions:
- What does this policy allow or deny?
- Which roles, actions, resources, conditions, and relationships does it use?
- Which interpretation choices were recorded with the Tegata?
- Does the displayed specification still correspond to the generated artifacts?
- What does the compiled policy decide for a concrete input?
It is not an editor, authorization server, production dashboard, or hosted control plane. It does not modify Tegata, compile the project, record human approval, or sit in the application's decision path.
The Resources, Roles, and Actions views are indexes showing where terms appear. They are not calculations of global effective permissions.
LIVE: inspect the current project
npx ninka-authz docs
LIVE mode serves the current project on loopback. While the page is open, it follows relevant changes in the working tree. It does not compile those changes for you.
For each policy you can inspect:
- Overview — policy identity and artifact status;
- Rules — effects, subjects, actions, resources, conditions, and relationships;
- Source — the Tegata source;
- Audit — recorded source text and ambiguities;
- Try it — a form derived from the policy's input contract;
- Validation examples — generated examples that can be loaded into Try it.
STALE means the specification moved ahead of the compiled state
If a Tegata changes after the last compile, LIVE shows the new specification and marks the compiled state STALE. Interactive evaluation is disabled until you compile again.
Edit Tegata
↓
Reference shows the new specification
↓
compiled state is STALE
↓
Try it disabled
↓
npx ninka-authz compile
↓
specification and compiled state correspond again
The Reference will not evaluate old compiled bytes as though they represented the current Tegata.
Try a concrete authorization input
Try it builds a form from the generated input contract and evaluates the input against the compiled policy in the browser.
Use it to inspect concrete cases while reviewing a policy. Show evaluation input displays the object passed to the runtime, which is useful when comparing the policy with the input your application must construct.
ALLOW, DENY, and ERROR remain distinct. An integrity failure or runtime error is not presented as a deny decision.
Vocabulary values may appear as suggestions. Suggestions are not input validation: values outside the declared vocabulary can still be useful when checking deny behavior in Try it.
Inspect generated validation examples
The Reference exposes validation examples generated from the current Tegata. Loading one fills the Try it form so you can inspect the case and, when the form can represent it, evaluate it interactively.
These examples provide evidence about the current Tegata and compiled policy. They are not a regression oracle for a previous policy or another authorization system. See Test Authorization.
SNAPSHOT: export a publishable authorization state
npx ninka-authz docs -o ./reference
This exports a self-contained static Authorization Reference. It does not compile or modify the project, and it does not assert that a human approved the state. Export succeeds only when the project satisfies the artifact conditions required for a publishable snapshot; otherwise the command reports what must be fixed.
A snapshot can be served from ordinary static hosting. It needs no Ninka server or authorization backend because the captured bundle is evaluated in the browser.
Each snapshot records:
- the identity of the captured authorization state (
snapshot_hash); - the export time (
exported_at).
The identity answers “is this the same captured state?”; the timestamp answers “when was this snapshot exported?”. Neither field represents human approval.
An Authorization Reference contains security-design information such as roles, actions, conditions, relationships, and example inputs. Review the exposure boundary before publishing a snapshot outside your development environment.
LIVE vs SNAPSHOT
| LIVE | SNAPSHOT | |
|---|---|---|
| Source | current project | exported authorization state |
| Updates | follows relevant working-tree changes | immutable |
| Can show stale/invalid state | yes | no; export refuses an unpublishable state |
| Evaluation | compiled bundle in browser | captured bundle in browser |
| Compiles the project | no | no |
| Intended use | development and review | share or retain a captured state |
The mode badge tells you which source you are reading and its integrity state.
The trust boundary
The Reference is a view over Ninka's authorization artifacts, not another policy engine with independent semantics. Before evaluating, it relies on the artifact identities and bindings that protect runtime use of the compiled bundle. A stale or integrity-invalid state is reported rather than silently evaluated.
The detailed artifact chain, bundle bindings, hashes, and generated file formats belong to Generated Files. The compiler/build responsibility boundary is explained in Authorization Compiler.