Policy decisions

policy is the one layer that decides who may do what and what data, hosts and models an app may reach. You ask a question and get allow or deny, the reasons and an id.

You ask it in your own code when a decision is sensitive, such as exporting data or acting across a border. Every decision runs in process and is written to the audit log.

What runs today is the built-in engine that access also uses: roles, owner rules, named rules, relations and the three modes. policy.decide() and policy.explain() are thin calls over it, and you configure it under access: in main.yaml. Policies as code in policies/, the Cedar and OPA engines, layers, policy.test(), policy.rollout() and policy.decideRemote() are planned for 0.2 (spec policy) and are marked below. Do not write them yet.

policy:
  engine: cedar
  placement: server
  dir: policies/
  mode: observe                # the default for new policies

import { policy } from "mainsdk";

const d = policy.decide({
  subject: { type: "user", id: user.id },
  action: { name: "export.data" },
  resource: { type: "report", id: report.id },
  context: { country: "IN" },
});
if (d.decision === "deny") console.log(policy.explain(d.id));

import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { policy } from "mainsdk";

createTestApp({ yaml: "schema: 1\nproject: prj_test\naccess:\n  roles:\n    analyst: [reports.read]\n" });

const d = policy.decide({
  subject: { id: "u_1", roles: ["analyst"] },
  action: "export.data",
  resource: { type: "report", id: "r_1" },
});
assert.equal(d.allow, false);
assert.equal(policy.explain(d.id)?.decision.reasons[0], "no role or owner rule grants export.data");

policy:
  driver: builtin

Quick start

access:
  mode: enforce        # enforce | warn | observe
  roles:
    admin: ["*"]
    analyst: [reports.read]

import { auth, policy } from "mainsdk";

declare function startExport(reportId: string): Promise<Response>; // your own export job

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const session = await auth.require(req);

  const d = policy.decide({                       // synchronous, in process
    subject: { type: "user", id: session.user, roles: ["analyst"] },
    action: { name: "export.data" },
    resource: { type: "report", id },
    context: { purpose: "audit" },
  });
  if (!d.allow) {
    return Response.json({ reasons: d.reasons, decisionId: d.id }, { status: 403 });
  }
  return startExport(id);
}

With no matching rule the decision is deny, with the reason no role or owner rule grants export.data. A decision is { id, decision, allow, mode, policyVersion, reasons }. In a real app the roles come from the tenant membership when you leave roles out.

Check d.allow, not d.decision. In observe and warn mode decision can be "deny" while allow is true, so the request goes ahead and the would-be denial is logged.

Configuration

Today the keys live under access:. See permissions for all of them.

access:
  roles:
    admin: ["*"]                  # every action
    analyst: [reports.read]
  owner: [read, update]           # on a resource whose owner is the subject
  when:
    export.data: [audit-only]     # named rules that must also hold
  mode: enforce                   # enforce | warn | observe

The policy version is a short hash of this section, and every decision carries it.

Planned for 0.2, not in the code yet: a policy: section with engine (cedar or opa), placement (server, edge or browser), dir: policies/ for policies kept in git, and layers where org, repo, market and Fleet policies apply in order and a lower layer only tightens.

What you get

• An allow or deny for each question, with the reasons, the mode and the policy version.
• A decision id that policy.explain() turns back into the rule that decided.
• In-process, deterministic decisions with no network round trip, each written to the audit log.
• Deny by default when no rule permits, and a denial across tenants before any rule runs.

Examples

Explain a denial

Every decision has an id. policy.explain(id) returns the decision and the request that produced it, or null for an id it does not hold. It keeps the last 10,000 decisions of the process.

import { auth, policy } from "mainsdk";

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  await auth.require(req, { role: "admin" });
  const found = policy.explain(id);
  return found ? Response.json(found) : new Response(null, { status: 404 });
}

The reasons name the rule: role admin grants *, owner of report may read, no role or owner rule grants export.data, cross-tenant, or the API key does not have this scope.

Shadow a new rule, then enforce it

Set access.mode: observe. The request is allowed and the would-be decision is logged with mode: "observe". Move to warn, then enforce, once the log looks right.

import { auth, policy } from "mainsdk";

declare function createTransfer(body: { accountId: string; amount: number }): Promise<unknown>; // your own transfer code

export async function POST(req: Request) {
  const session = await auth.require(req);
  const body = (await req.json()) as { accountId: string; amount: number };

  const d = policy.decide({
    subject: { type: "user", id: session.user, roles: ["member"] },
    action: { name: "transfers.create" },
    resource: { type: "account", id: body.accountId, amount: body.amount },
  });
  if (!d.allow) return Response.json({ reasons: d.reasons }, { status: 403 });   // only enforce blocks
  return Response.json(await createTransfer(body));
}

Planned

These are in the spec and the catalog, and none of them is in the code yet.

• Policies as code. Cedar files in policies/, a built-in TypeScript Cedar evaluator and an OPA driver for compiled Rego, with a content-hashed policy version and the last good set kept when a new one fails to load.
• Layers. Org, repo, market and Fleet policies, where a lower layer only tightens. A repo policy that weakens an org one fails to load with MAIN-POLICY-0004.
• policy.test() and mainsdk test policy to unit-test policies and replay recorded decisions.
• policy.rollout() to stage a change (shadow, then 5%, 25%, 100%) with automatic rollback.
• policy.decideRemote() for decisions in the browser or at the edge.

Questions the spec still lists as open: how rollout state is kept across instances, how DecisionInput maps to Cedar entities beyond context, and what counts as weakening beyond deny-to-allow.

Errors and checks

A denied decision is a value, not an error: policy.decide() does not throw. Code that turns a denial into an error uses access.require(), which throws a MainError with status 403.

The policy-loading codes are planned with the policy files: MAIN-POLICY-0004 (a lower layer weakens a higher one) and MAIN-POLICY-0009 (a new set fails to load and the last good set stays in force; see fail static).

Swapping drivers

Today there is one engine, the built-in one. The engine choice (cedar or opa) arrives with the policy: section, and the policy.decide() and policy.explain() calls will stay the same.

Testing

createTestApp builds the app from a main.yaml string, so a test states its own rules.

import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { policy } from "mainsdk";

createTestApp({ yaml: "schema: 1\nproject: prj_test\naccess:\n  roles:\n    analyst: [reports.read]\n" });

const d = policy.decide({
  subject: { id: "u_1", roles: ["analyst"] },
  action: "export.data",
  resource: { type: "report", id: "r_1" },
});
assert.equal(d.allow, false);
assert.equal(policy.explain(d.id)?.decision.reasons[0], "no role or owner rule grants export.data");

policyTest and mainsdk test policy arrive with policy files.

Security and privacy

• Deny when no rule permits. A named rule that is not registered denies.
• Decisions run in process and are deterministic, with no network round trip.
• Every decision is written to the audit log with the decision id, policy version and mode.
• A decision across tenants is denied before any rule runs, and an API key never widens what the rules allow.

Everything on this page runs in your app and is free; see free and Cloud for what the plans add.

FAQ

Does a decision ever wait on the network? No. The built-in engine evaluates in process. MainSDK Cloud is never in the request path.

How is this different from access? access is the permissions interface for your app's records: access.check(), access.require(), relations and rules. policy is the same engine seen as the layer for every decision MainSDK makes, and it is where Cedar, layers and rollout will land.

Can my repo loosen an org rule for one case? Layers are planned. Exceptions with an owner and an expiry will live in main.yaml; see main.yaml.

Next

• Permissions: roles, rules and relations.
• Network permissions: rules for the hosts an app may reach.
• Fail static: why the last good policy stays in force.
• Try a policy in the playground: mainsdk policy play and the browser page; codes MAIN-PLAY-0001 to 0005 are in check codes.