API reference

function hydratePolicy<
  Sub = Subject,
  R = AnyObjects,
  Keys extends string = string,
>(matrix: Matrix, options?: AccessOptions): Access<Sub, R, Keys>;

function parseMatrix<
  Sub = Subject,
  R = AnyObjects,
  Keys extends string = string,
>(matrix: Matrix, options?: AccessOptions): Access<Sub, R, Keys>;

function policy<
  Sub,
  Objects,
  Vocabs extends Partial<Record<keyof Objects, string>> = Record<never, never>,
>(
  options?: PolicyOptions,
): Policy<Sub, Objects, Vocabs, Record<never, never>, never>;

interface Policy<
  Sub,
  Objects,
  Vocabs extends Partial<Record<keyof Objects, string>>,
  R,
  Keys extends string = string,
> {
  for<K extends keyof Objects & string, Act extends string = string>(
    key: K,
    build: (
      p: Actions<Sub, Objects[K], never, VocabularyOf<Vocabs, K>>,
    ) => Actions<Sub, Objects[K], Act, VocabularyOf<Vocabs, K>> | void,
  ): Policy<
    Sub,
    Objects,
    Vocabs,
    R & Record<K, Objects[K]>,
    Keys | PermissionKeys<K, Act>
  >;
  readonly matrix: Readonly<Matrix>;
  build(options?: AccessOptions): Access<Sub, R, Keys>;
}

type PolicyOptions = Pick<Matrix, 'version' | 'schema'>;

interface AccessOptions {
  version?: string | number;
  closed?: boolean;
  fetchedAt?: Instant;
  maxStale?: number;
}

interface Access<Sub = Subject, R = AnyObjects, Keys extends string = string> {
  readonly matrix: Readonly<Matrix>;
  readonly version: string | number | undefined;
  readonly schema: MatrixSchema | undefined;
 
  can(subject, key, action, object?, now?): Decision;
  canMany(subject, key, action, objects, now?): Decision[];
  canFields(subject, key, action, object, axis, proposed?, now?): FieldDecision;
  capabilities(subject, now?): Record<Keys, Decision>;
  authorize(subject, options?: { now?: Instant }): Authorized<R, Keys>;
  object(key): BoundKind<Sub, R[K], ActionOf<Keys, K>>;
  readsObject(key, action): boolean;
}

interface Authorized<R = AnyObjects, Keys extends string = string> {
  can<K extends keyof R & string>(
    key: K,
    action: ActionOf<Keys, K>,
    object?: Partial<R[K]>,
  ): Decision;
  canMany<K extends keyof R & string>(
    key: K,
    action: ActionOf<Keys, K>,
    objects: readonly Partial<R[K]>[],
  ): Decision[];
  canFields<K extends keyof R & string>(
    key: K,
    action: ActionOf<Keys, K>,
    object: Partial<R[K]>,
    axis: 'read' | 'write',
    proposed?: Partial<R[K]>,
  ): FieldDecision;
  capabilities(): Record<Keys, Decision>;
}

interface BoundKind<Sub, Obj, Act extends string = string> {
  can(
    subject: Sub,
    action: Act,
    object?: Partial<Obj>,
    now?: Instant,
  ): Decision;
  canMany(
    subject: Sub,
    action: Act,
    objects: readonly Partial<Obj>[],
    now?: Instant,
  ): Decision[];
  canFields(
    subject: Sub,
    action: Act,
    object: Partial<Obj>,
    axis: 'read' | 'write',
    proposed?: Partial<Obj>,
    now?: Instant,
  ): FieldDecision;
  readsObject(action: Act): boolean;
}

type KeysOf<A> = A extends Access<never, never, infer Keys> ? Keys : never;

type ActionOf<Keys extends string, K extends string> = [Keys] extends [never]
  ? string
  : string extends Keys
    ? string
    : [Extract<Keys, `${K}.${string}`>] extends [never]
      ? string
      : Keys extends `${K}.${infer Act}`
        ? Act
        : never;

const CRUD_ACTIONS: readonly ['create', 'read', 'update', 'delete'];

function pickAllowedFields<T extends Record<string, unknown>>(
  decision: FieldDecision,
  proposed: T,
): Partial<T>;

function serialize<Sub, R, Keys>(
  access: Access<Sub, R, Keys>,
  mode: 'full',
): Matrix;
function serialize<Sub, R, Keys>(
  access: Access<Sub, R, Keys>,
  mode: 'reduced',
  options?: SerializeOptions<Keys>,
): Matrix;

type SerializeMode = 'full' | 'reduced';

interface SerializeOptions<Keys extends string = string> {
  readonly vetoable?: readonly Keys[];
}

function federatedPolicies(
  policies: Readonly<Record<string, Access<Subject, AnyObjects, never>>>,
): FederatedAccess;

interface FederatedAccess {
  can(
    subject: Subject,
    key: string,
    action: string,
    object?: Record<string, unknown>,
    now?: Instant,
  ): Decision;
  capabilities(subject: Subject, now?: Instant): Record<string, Decision>;
  get(origin: string): Access | undefined;
}

function applyDenyOverlay(
  matrix: Matrix,
  overlay: DenyOverlay,
  options: DenyOverlayOptions,
): Matrix;

type DenyOverlay = Readonly<Record<string, readonly Rule[]>>;

interface DenyOverlayOptions {
  readonly vetoable: readonly string[];
}

interface Matrix {
  readonly version?: string | number;
  readonly maxStale?: number; // how long a holder may keep deciding on it
  readonly schema?: MatrixSchema;
  readonly permissions: readonly Permission[];
}

interface Permission {
  key: string; // exactly `${object}.${action}`
  object: ObjectKey;
  action: string; // whatever the producer wrote
  rules?: readonly Rule[]; // allows, OR-ed
  denyRules?: readonly Rule[]; // denies, OR-ed; a matched deny wins
  fields?: FieldRules;
  visibility?: 'public' | 'internal'; // absent is internal
}

interface Rule {
  id?: string; // what a decision reports as `rule`; defaults to `#0`, `#1`, …
  when?: readonly Condition[]; // AND-ed
}

type Condition =
  | { field: 'now'; op: 'before' | 'after'; value: Instant }
  | {
      field: string;
      op: 'eq' | 'ne' | 'in' | 'not-in' | 'contains';
      path?: string; // the `eq`/`ne` form only
      value?: unknown;
    };

interface FieldRules {
  fields?: readonly string[]; // ['*', '!status'] or ['body', 'title']
  [field: string]: readonly string[] | FieldConfig | undefined;
}

type FieldConfig =
  | { targets: readonly unknown[] }
  | { transitions: Record<string, readonly unknown[]> };

interface MatrixSchema {
  readonly subject?: ObjectSchema;
  readonly objects?: Readonly<Record<ObjectKey, ObjectSchema>>;
}

interface ObjectSchema {
  readonly fields?: Readonly<Record<string, FieldType>>;
  readonly relations?: Readonly<Record<string, ObjectKey>>;
}

type FieldType =
  | BaseFieldType
  | `${BaseFieldType}[]`
  | `${BaseFieldType}?`
  | `${BaseFieldType}[]?`;

type BaseFieldType = 'string' | 'number' | 'boolean' | 'instant';

type Instant = string | number | Date;

interface Decision {
  key: string;
  allowed: boolean;
  reason: Reason;
  rule?: string;
  missing?: readonly string[];
}

type Reason =
  | 'allow'
  | 'no-rule-matched'
  | 'denied'
  | 'unknown-action'
  | 'unevaluable'
  | 'unusable-clock'
  | 'stale-contract';

interface FieldDecision {
  allowed: boolean; // the action is allowed AND every decided field is
  action: Decision; // the action alone
  fields: Record<string, FieldState>;
  reasons: Record<string, FieldReason>;
}

type FieldState = 'allowed' | 'denied' | 'unevaluable';

type FieldReason =
  | 'allow'
  | 'not-listed'
  | 'targets-failed'
  | 'transition-failed'
  | 'missing-field'
  | 'proposed-required';

interface EvaluationContext {
  subject: Record<string, unknown>;
  object?: Record<string, unknown>;
  now?: Instant;
}

type Subject = Record<string, unknown>;

type AnyObjects = Record<string, Record<string, unknown>>;

type ObjectKey = string;

interface Actions<
  Sub,
  Obj,
  Act extends string = string,
  Vocab extends string = string,
> extends Ops<Sub, Obj> {
  allow<A extends Vocab>(
    action: A,
    ...conditions: Cond[]
  ): Actions<Sub, Obj, Act | A, Vocab>;
  deny<A extends Vocab>(
    action: A,
    ...conditions: Cond[]
  ): Actions<Sub, Obj, Act | A, Vocab>;
  allowEach<A extends Vocab>(
    actions: readonly A[],
    ...conditions: Cond[]
  ): Actions<Sub, Obj, Act | A, Vocab>;
  denyEach<A extends Vocab>(
    actions: readonly A[],
    ...conditions: Cond[]
  ): Actions<Sub, Obj, Act | A, Vocab>;
  fields(rules: readonly string[] | FieldRules): Actions<Sub, Obj, Act, Vocab>;
  visibility(visibility: Visibility): Actions<Sub, Obj, Act, Vocab>;
}

type Action = (typeof CRUD_ACTIONS)[number];

type VocabularyOf<Vocabs, K extends string> = K extends keyof Vocabs
  ? Vocabs[K] extends string
    ? Vocabs[K]
    : Action
  : Action;

type Visibility = NonNullable<Permission['visibility']>;

type PermissionKeys<K extends string, Act extends string> = string extends Act
  ? string
  : `${K}.${Act}`;

interface Ops<Sub, Obj> {
  eq<A extends string, B>(
    field: Valid<A, Sub, Obj>,
    operand: Operand<B, Sub, Obj>,
  ): Cond;
  ne<A extends string, B>(
    field: Valid<A, Sub, Obj>,
    operand: Operand<B, Sub, Obj>,
  ): Cond;
  in<A extends string>(
    field: Valid<A, Sub, Obj>,
    values: readonly unknown[],
  ): Cond;
  notIn<A extends string>(
    field: Valid<A, Sub, Obj>,
    values: readonly unknown[],
  ): Cond;
  contains<A extends string>(field: Valid<A, Sub, Obj>, value: unknown): Cond;
  before(field: 'now', instant: Instant): Cond;
  after(field: 'now', instant: Instant): Cond;
  and(...conditions: Cond[]): Cond;
  or(...conditions: Cond[]): Cond;
  readonly always: Cond;
}

interface Cond {
  readonly node: Node;
}

type Operand<B, Sub, Obj> = B extends
  `subject.${string}` | `object.${string}` | 'now'
  ? Valid<B & string, Sub, Obj>
  : B;

type Paths<T, P extends string> = {
  [K in keyof T & string]: `${P}.${K}`;
}[keyof T & string];

type Valid<S extends string, Sub, Obj> = S extends
  Paths<Sub, 'subject'> | Paths<Obj, 'object'> | 'now'
  ? S
  : `unknown path '${S}' on this resource`;

class AclConfigError extends Error {}

class InvalidMatrixError extends AclConfigError {}

class InvalidSchemaError extends AclConfigError {
  readonly where: string; // schema.objects.question.fields.status
}

class InvalidPermissionError extends AclConfigError {
  readonly key: string;
  readonly field: string;
}

class InvalidRuleError extends AclConfigError {
  readonly key: string;
  readonly field: string; // rules[2]
}

class InvalidConditionError extends AclConfigError {
  readonly key: string;
  readonly field: string;
  readonly where: string;
}

class KeyMismatchError extends AclConfigError {
  readonly key: string;
  readonly object: string;
  readonly action: string;
}

class DuplicatePermissionError extends AclConfigError {
  readonly key: string;
}

class UnknownFieldError extends AclConfigError {
  readonly key: string;
  readonly field: string;
  readonly where: string;
}

class FieldTypeMismatchError extends AclConfigError {
  readonly key: string;
  readonly field: string;
  readonly where: string;
}

class BangInAllowListError extends AclConfigError {}

class DenyWithoutBaselineError extends AclConfigError {}

class TargetsTransitionsConflictError extends AclConfigError {}

class UnknownObjectKeyError extends AclConfigError {
  readonly key: ObjectKey;
}

class UnknownPermissionError extends AclConfigError {
  readonly key: string;
}

class OriginCollisionError extends AclConfigError {
  readonly key: string;
  readonly origins: readonly [string, string];
}

class UnvetoablePermissionError extends AclConfigError {
  readonly key: string;
}

class MissingVetoSchemaError extends AclConfigError {
  readonly key: string;
  readonly object: ObjectKey;
}

class UnpublishedVetoableError extends AclConfigError {
  readonly key: string;
}

class MissingFreshnessBudgetError extends AclConfigError {}

class InvalidFreshnessError extends AclConfigError {
  readonly field: string;
}

class ActionNotAllowedError extends Error {
  readonly key: string;
  readonly reason: Reason;
}