Policy engine

One policy layer decides everything MainSDK decides: who may do what, which data may go where, which hosts and models an app may reach. The same engine and the same files run in your app, in CI and, later, from Fleet (ADR-0004).

flowchart LR
  subgraph callers["Every interface"]
    a["access"]
    n["network"]
    d["db"]
    ai["ai"]
  end
  callers --> dec["policy.decide()<br/>in process, deterministic"]
  files["policies/*.cedar<br/>or Rego via OPA driver"] --> dec
  cfg["Rules in main.yaml<br/>compiled to policies"] --> dec
  dec --> out{"allow or deny"}
  dec --> log[("Decision log<br/>id, policy version, layer, mode")]

The call every interface makes

policy.decide({
  subject:  { type: "user", id: "u_8f3" },
  action:   { name: "orders.update" },
  resource: { type: "order", id: "8812" },
  context:  { country: "in", org: "pinecart" },
}); // { id, decision: "deny", mode: "enforce", policyVersion, reasons: ["no matching permit"], layer: "repo" }

The input is shaped on the OpenID AuthZEN API: subject, action, resource, context. Rules that matter:

• Deny by default. With no matching permit, the decision is deny. An empty policies/ denies everything.
• In process. No network round trip per decision; under 1 ms at p99 with Cedar.
• Versioned. The policy version is a content hash of the loaded set, and every decision is logged with it.

Engines

policy:
  engine: cedar                      # cedar (built in) | opa
  placement: server                  # server (default) | edge | browser
  browser: { local: false }          # opt in: lazy-load the Cedar engine in the browser
  dir: policies/
  mode: enforce                      # default for new policies is observe

Observe, warn, enforce

Each policy runs in one of three modes, so adoption never breaks production:

Layers only tighten

flowchart LR
  org["Org<br/>main.org.yaml"] --> repo["Repo<br/>policies/"] --> ov["Market and segment overlays"] --> fleet["Fleet<br/>phase 4"]

A lower layer can never turn a higher layer's deny into an allow. A repo policy that would do so fails to load:

MAIN-POLICY-0004 repo layer weakens org: data.export

The error names both files.

Explain, test, roll out

• Explain. policy.explain(decisionId) returns the layer, file, line and policy id that decided, and the main.yaml line when the policy was compiled from config, for example from network.allow.
• Test. mainsdk test policy runs your policy unit tests and replays recorded decisions, listing each one a change would flip from allow to deny or back.
• Roll out. A change moves through stages and rolls back on its own:

policy.rollout("egress-v4", {
  stages: ["shadow", "5%", "25%", "100%"],
  rollbackIf: { denials: "+20%", errors: "+1%" },
});

Canary traffic is assigned by a stable hash of the subject, so a user stays in one bucket. Every stage change is audited. Still open: how rollout state is shared across many instances, since with no Cloud in the request path each instance counts its own denials and errors.

Placement

The browser is never the only place a deny is enforced for data or actions the server owns.

Fail static

If a new policy set fails to parse, validate or verify, the engine keeps the last good set and logs MAIN-POLICY-0009. It never falls back to no policy. Packs we deliver arrive signed through mainsdk sync (TUF from 0.4).

Later

Next

• Policy as code: modes, layers and writing your first policy.
• Request lifecycle: where the decision sits on a call.
• Security architecture: the threats the engine answers.