Skip to main content

Quickstart

This page gets one Ninka authorization check running end to end.

You will install Ninka, scaffold a workspace, inspect the sample Tegata, compile it, and call the generated Consumer Projection from application code. For the product model and responsibility boundaries, start with the Introduction.

1. Install​

npm install ninka-authz

Node.js 20 or later is required. Install ninka-authz as a runtime dependency because the generated TypeScript Consumer Projection imports ninka-authz/runtime.

2. Scaffold​

npx ninka-authz init

init creates a ninka/ workspace and, unless --bare is used, a sample policy. When a Tegata is present, init also runs the compile pipeline. In a normal TypeScript project the generated Consumer Projection is written to src/generated/ninka.ts by default.

3. Read the sample Tegata​

init already created ninka/invoice-access.tegata.json. Open it. This is the authorization specification a human reviews and the same document shape you use for your own policies.

{
  "tegata": "0.1",
  "policy": { "id": "invoice-access", "description": "Invoice access" },
  "rules": [
    {
      "id": "allow-employee-view-invoice",
      "effect": "allow",
      "subject": { "roles": ["employee"] },
      "actions": ["view"],
      "resource": { "type": "invoice" }
    }
  ]
}

Each policy normally lives at ninka/<policy-id>.tegata.json. See Tegata Schema for the full document shape and evaluation semantics.

init also created ninka/vocabulary.json. It declares the project terms that the sample policy is allowed to use. When you introduce a new role, action, resource type, or governed attribute, update the vocabulary as well. See Vocabulary.

4. Compile​

npx ninka-authz compile

Ninka validates the Tegata and writes the source-derived Rego and metadata. When the OPA toolchain is available, it also builds the WASM execution bundle, runs generated validation against that build, and writes the Consumer Projection.

Use npx ninka-authz build in CI or another environment where producing a complete execution bundle is mandatory. Unlike plain compile, build fails when it cannot publish the required bundle.

5. Enforce the decision in your application​

Import the generated projection and select the policy by the reference name derived from its Tegata id:

import { createNinka, policies } from "@/src/generated/ninka";

const authz = await createNinka();

const allowed = authz.check(policies.invoiceAccess, {
  subject: {
    properties: {
      roles: session.user.roles,
      user_id: session.user.id,
    },
  },
  action: { name: "view" },
  resource: {
    type: "invoice",
    properties: {
      amount: invoice.amount,
      submitted_by: invoice.submittedBy,
    },
  },
});

if (!allowed) {
  return new Response("Forbidden", { status: 403 });
}

createNinka() verifies the embedded execution bundle when the runtime is created. policies.invoiceAccess carries the policy id, specification hash, and generated TypeScript input contract used by check().

Your application still decides when to call check(), which concrete resource it is authorizing, how to construct the input, and how to handle a deny. See TypeScript Runtime API. For .NET, see .NET Runtime API.

6. Inspect the policy​

npx ninka-authz docs

The generated Authorization Reference lets you inspect the current policies, rules, audit information, input requirements, validation examples, and compiled state. When a verified WASM bundle is available, Try it evaluates concrete inputs in the browser.

The Reference is read-only: it does not compile or modify the project and does not record human approval. See Authorization Reference.

7. Verify generated state in CI​

npx ninka-authz verify

verify reproduces and compares the generated state for the current Tegata and toolchain contract. With the pinned OPA toolchain available, it also checks the execution bundle and required WASM validation/rebuild obligations. If that toolchain cannot be obtained at all, the CLI reports the affected obligations explicitly as not checked rather than treating them as matched.

verify checks files on disk; it does not inspect Git tracking state.

See CLI Reference for the exact checks, flags, skip behavior, output paths, and failure semantics. See Authorization Compiler for why those checks are separated from human review.

Next steps​