@gomagentic/verdict-core

Domain types, wire contracts, VIR format, and runtime guards. Zero dependencies.

Part of Verdict — a serverless-first authorization engine. Policies (RBAC / ABAC / ReBAC) compile once and decide in microseconds, embedded in your app, behind a central PDP, or synced to the edge.

This is the foundation package. Every other @gomagentic/verdict-* package builds on it, so you usually install it transitively via @gomagentic/verdict-engine or @gomagentic/verdict-sdk. Install it directly when you only need the shared types and guards — for example in a service that constructs CheckRequests or inspects a Decision without linking the evaluator.

npm install @gomagentic/verdict-core

It runs unchanged on Cloudflare Workers, AWS Lambda, Bun, Deno, and Node. The package declares the cross-runtime Web globals it relies on (crypto, TextEncoder, …) via an ambient ./globals.js import, so canonicalization and signatures type-check the same everywhere.

What's in here

| Group | Exports | | |---|---|---| | Principal / resource / request | Principal, ResourceRef, CheckRequest, BatchCheckRequest, RequestContext, CheckOptions | Who acts, on what, for which actions | | Decision / effect | Decision, BatchDecision, ActionEffect, Effect, ReasonCode, Trace | The decision envelope every evaluator returns | | Values | AttributeValue, AttributeMap | JSON-safe ABAC attribute model + limits | | Policy | types/policy | Policy, rule, condition, and derived-role shapes | | Bundle | types/bundle | The immutable, content-hashed, versioned unit of deployment | | Tenant | types/tenant | Tenant scope and budgets | | Audit | types/audit | Audit record shape for the async pipeline | | VIR | vir/opcodes, vir/builtins, vir/format | Verdict Intermediate Representation: instruction set, builtins, and (de)serialization | | Canonicalization & signatures | canonical, signature | Deterministic byte encoding + Ed25519 signing/verification | | Guards & errors | guards, errors | Boundary validation and typed errors (ValidationError, ValidationIssue) |

Usage

Every guard rejects hostile input (prototype-pollution keys, non-serializable values, oversized batches) at the boundary; the decision helpers are default-deny by construction.

import {
  assertCheckRequest,
  allows,
  type CheckRequest,
  type Decision,
} from "@gomagentic/verdict-core";

// Validate untrusted input; throws ValidationError listing every issue.
const request: CheckRequest = assertCheckRequest({
  principal: { id: "u_42", roles: ["employee"], attr: { department: "eng" } },
  resource: { kind: "leave", id: "lv_9", attr: { ownerId: "u_42" } },
  actions: ["view", "approve"],
});

// ...hand `request` to the engine, get a Decision back...
declare const decision: Decision;

allows(decision, "approve"); // boolean — false unless an ALLOW effect matched

Non-throwing variants return ValidationIssue[] (validateCheckRequest, validatePrincipal, validateResource, validateActions), and allowsAll(decision) reports whether every requested action was allowed.

Documentation

• Getting started
• Domain model
• Evaluation engine (VIR)
• Architecture

License

Apache-2.0