What can throw?

import { AclConfigError, parseMatrix } from '@evanion/acl';
 
const malformed = { version: 'v1' } as never;
 
let base: Error | undefined;
try {
  parseMatrix(malformed);
} catch (error) {
  base = error as Error;
}
 
// Every class the package raises at construction extends this one, so a
// startup guard catches the set without naming each member.
base instanceof AclConfigError; // -> true
base instanceof Error; // -> true

import { validateAll } from '@evanion/acl';
 
// A draft from a policy editor with two faults, in two permissions.
const draft = {
  permissions: [
    {
      key: 'question.read',
      object: 'question',
      action: 'read',
      visibility: 'everyone',
    },
    {
      key: 'question.update',
      object: 'question',
      action: 'update',
      rules: [{ when: [{ field: 'subject.id', op: 'equals', value: 'a' }] }],
    },
  ],
} as never;
 
// validateAll never throws, and it reports both faults in one call.
const issues = validateAll(draft);
 
issues.length; // -> 2
issues[0]?.code; // -> 'InvalidPermissionError'
issues[0]?.path; // -> '/permissions/0/visibility'
issues[0]?.permissionKey; // -> 'question.read'
issues[1]?.code; // -> 'InvalidConditionError'
issues[1]?.path; // -> '/permissions/1/rules/0/when/0'
 
// A valid document returns an empty list.
validateAll({ permissions: [] }); // -> []

import { AclConfigError, ActionNotAllowedError } from '@evanion/acl';
import { pickAllowedFields, policy } from '@evanion/acl';
 
type Question = { askedBy: string; body: string };
 
const access = policy<{ id: string }, { question: Question }>()
  .for('question', (p) =>
    p.allow('update', p.eq('object.askedBy', 'subject.id')),
  )
  .build();
 
// Somebody else's question, so the action itself is refused.
const row = { askedBy: 'customer-92', body: 'In stock?' };
const proposed = { body: 'Is Wingspan in stock?' };
const decided = access.canFields(
  { id: 'customer-41' },
  'question',
  'update',
  row,
  'write',
  proposed,
);
 
decided.action.allowed; // -> false
 
let refusedWrite: Error | undefined;
try {
  pickAllowedFields(decided, proposed);
} catch (error) {
  refusedWrite = error as Error;
}
 
refusedWrite instanceof ActionNotAllowedError; // -> true
refusedWrite instanceof AclConfigError; // -> false

import { hydratePolicy, parseMatrix } from '@evanion/acl';
 
function raised(run: () => unknown): string | undefined {
  try {
    run();
  } catch (error) {
    return (error as Error).name;
  }
  return undefined;
}
 
const document = {
  version: 'v1',
  permissions: [
    {
      key: 'question.read',
      object: 'question',
      action: 'read',
      rules: [{ when: [] }],
    },
  ],
} as never;
 
const open = hydratePolicy(document);
const closed = parseMatrix(document);
 
// The document holds `question.read` and nothing else. A query naming anything
// else is typed `never` here, because a caller writing one has already left
// what the document declares.
const anyone = {} as never;
const question = 'question' as never;
const readAction = 'read' as never;
const noSuchAction = 'delete' as never;
const noSuchKind = 'coupon' as never;
 
raised(() => open.can(anyone, question, noSuchAction)); // -> 'UnknownPermissionError'
raised(() => open.can(anyone, noSuchKind, readAction)); // -> 'UnknownObjectKeyError'
 
const refused = closed.can(anyone, question, noSuchAction);
 
refused.allowed; // -> false
refused.reason; // -> 'unknown-action'

import { parseMatrix } from '@evanion/acl';
 
/** The error a call raises, by name, or `undefined` when it raises none. */
function raised(run: () => unknown): string | undefined {
  try {
    run();
  } catch (error) {
    return (error as Error).name;
  }
  return undefined;
}
 
const read = {
  key: 'question.read',
  object: 'question',
  action: 'read',
  rules: [{ when: [] }],
};
 
const noPermissions = { version: 'v1' } as never;
const objectVersion = { version: {}, permissions: [] } as never;
const wrongKey = {
  version: 'v1',
  permissions: [{ ...read, key: 'question.update' }],
} as never;
const twice = { version: 'v1', permissions: [read, read] } as never;
const noAction = {
  version: 'v1',
  permissions: [{ key: 'question.read', object: 'question' }],
} as never;
const whenIsString = {
  version: 'v1',
  permissions: [{ ...read, rules: [{ when: 'x' }] }],
} as never;
 
raised(() => parseMatrix(noPermissions)); // -> 'InvalidMatrixError'
raised(() => parseMatrix(objectVersion)); // -> 'InvalidMatrixError'
raised(() => parseMatrix(wrongKey)); // -> 'KeyMismatchError'
raised(() => parseMatrix(twice)); // -> 'DuplicatePermissionError'
raised(() => parseMatrix(noAction)); // -> 'InvalidPermissionError'
raised(() => parseMatrix(whenIsString)); // -> 'InvalidRuleError'
 
// Three conditions, one class. The message tells them apart.
const when = (condition: unknown) =>
  ({
    version: 'v1',
    permissions: [{ ...read, rules: [{ when: [condition] }] }],
  }) as never;
 
const unknownOp = when({ field: 'subject.id', op: 'nope', value: 1 });
const twoDots = when({ field: 'subject.a.b', op: 'eq', value: 1 });
const noScope = when({ field: 'user.id', op: 'eq', value: 1 });
 
raised(() => parseMatrix(unknownOp)); // -> 'InvalidConditionError'
raised(() => parseMatrix(twoDots)); // -> 'InvalidConditionError'
raised(() => parseMatrix(noScope)); // -> 'InvalidConditionError'

import { parseMatrix } from '@evanion/acl';
 
/** What an `InvalidConditionError` carries beside its message. */
type Located = Error & {
  key?: string;
  field?: string;
  where?: string;
};
 
const twoDots = {
  version: 'v1',
  permissions: [
    {
      key: 'question.read',
      object: 'question',
      action: 'read',
      rules: [{ when: [{ field: 'subject.a.b', op: 'eq', value: 1 }] }],
    },
  ],
} as never;
 
let caught: Located | undefined;
try {
  parseMatrix(twoDots);
} catch (error) {
  caught = error as Located;
}
 
caught?.name; // -> 'InvalidConditionError'
caught?.key; // -> 'question.read'
caught?.field; // -> 'subject.a.b'
caught?.where; // -> 'rules[0].when[0]'

import { parseMatrix } from '@evanion/acl';
 
function raised(run: () => unknown): string | undefined {
  try {
    run();
  } catch (error) {
    return (error as Error).name;
  }
  return undefined;
}
 
const read = {
  key: 'question.read',
  object: 'question',
  action: 'read',
  rules: [{ when: [] }],
};
const schema = { objects: { question: { fields: { status: 'string' } } } };
 
const unknownType = {
  version: 'v1',
  schema: { objects: { question: { fields: { status: 'nope' } } } },
  permissions: [read],
} as never;
 
const undeclaredField = {
  version: 'v1',
  schema,
  permissions: [
    {
      ...read,
      rules: [{ when: [{ field: 'object.pinned', op: 'eq', value: true }] }],
    },
  ],
} as never;
 
const containsOnString = {
  version: 'v1',
  schema,
  permissions: [
    {
      ...read,
      rules: [
        { when: [{ field: 'object.status', op: 'contains', value: 'open' }] },
      ],
    },
  ],
} as never;
 
raised(() => parseMatrix(unknownType)); // -> 'InvalidSchemaError'
raised(() => parseMatrix(undeclaredField)); // -> 'UnknownFieldError'
raised(() => parseMatrix(containsOnString)); // -> 'FieldTypeMismatchError'
 
const fields = (rules: unknown) =>
  ({ version: 'v1', permissions: [{ ...read, fields: rules }] }) as never;
 
const twoIntents = fields({ fields: ['*', '!address', 'address.city'] });
const bangNoBaseline = fields({ fields: ['!status'] });
const bothConfigs = fields({
  status: { targets: ['open'], transitions: { open: [] } },
});
 
raised(() => parseMatrix(twoIntents)); // -> 'InvalidPermissionError'
raised(() => parseMatrix(bangNoBaseline)); // -> 'DenyWithoutBaselineError'
raised(() => parseMatrix(bothConfigs)); // -> 'TargetsTransitionsConflictError'

import { parseMatrix } from '@evanion/acl';
 
function raised(run: () => unknown): string | undefined {
  try {
    run();
  } catch (error) {
    return (error as Error).name;
  }
  return undefined;
}
 
const read = {
  key: 'question.read',
  object: 'question',
  action: 'read',
  rules: [{ when: [] }],
};
const stateless = { version: 'v1', permissions: [read] } as never;
const bounded = { version: 'v1', maxStale: 1000, permissions: [read] } as never;
 
const reported = { fetchedAt: 0 };
const notAnInstant = { fetchedAt: 'nope' } as never;
 
raised(() => parseMatrix(stateless, reported)); // -> 'MissingFreshnessBudgetError'
raised(() => parseMatrix(bounded, notAnInstant)); // -> 'InvalidFreshnessError'

import { applyDenyOverlay, federatedPolicies } from '@evanion/acl';
import { parseMatrix, policy, serialize } from '@evanion/acl';
 
function raised(run: () => unknown): string | undefined {
  try {
    run();
  } catch (error) {
    return (error as Error).name;
  }
  return undefined;
}
 
const read = {
  key: 'question.read',
  object: 'question',
  action: 'read',
  rules: [{ when: [] }],
};
const plain = { version: 'v1', permissions: [read] } as never;
const declared = {
  version: 'v1',
  schema: { objects: { question: { fields: { locked: 'boolean' } } } },
  permissions: [read],
} as never;
 
const twoOrigins = { a: parseMatrix(plain), b: parseMatrix(plain) } as never;
const veto = { 'question.read': [{ when: [] }] };
const locked = { field: 'object.locked', op: 'eq' as const, value: true };
const lockedVeto = { 'question.read': [{ when: [locked] }] };
const noKeyOpened = { vetoable: [] };
const opened = { vetoable: ['question.read'] };
 
raised(() => federatedPolicies(twoOrigins)); // -> 'OriginCollisionError'
raised(() => applyDenyOverlay(plain, veto, noKeyOpened)); // -> 'UnvetoablePermissionError'
raised(() => applyDenyOverlay(plain, veto, opened)); // -> 'MissingVetoSchemaError'
raised(() => applyDenyOverlay(declared, lockedVeto, opened)); // -> undefined
 
const internalOnly = policy<{ id: string }, { question: { id: string } }>()
  .for('question', (p) => p.allow('read', p.always))
  .build();
const asContract = { vetoable: ['question.read'] } as never;
 
raised(() => serialize(internalOnly, 'reduced', asContract)); // -> 'UnpublishedVetoableError'