bazis 0.128.0 → 0.130.0

package/core/access/check/conditions.ts

@@ -0,0 +1,132 @@
+import type { PermissionSpec } from "../catalog/permissions";
+import type { AccessValue, Condition, Grant, Scope, ValueTest } from "../contracts/types";
+
+export const MAX_DEPTH = 8;
+export const MAX_NODES = 200;
+
+/** Why a grant cannot be used for the permission, or `undefined` (ACCESS-001 §4.2). */
+export function grantProblem(spec: PermissionSpec, grant: Grant, maxInList: number): string | undefined {
+  if (typeof grant !== "object" || grant === null) return "a grant must be an object";
+  if (grant.scopes !== "all" && (!Array.isArray(grant.scopes) || !grant.scopes.every(isScope))) return 'scopes must be "all" or a list of strings and null';
+  if (grant.fields !== undefined) {
+    if (spec.fields !== true) return "the permission has no field lists";
+    for (const side of ["read", "write"] as const) {
+      const list = grant.fields[side];
+      if (list !== undefined && list !== "all" && !(Array.isArray(list) && list.every((field) => typeof field === "string"))) return `fields.${side} must be "all" or a list of field names`;
+    }
+  }
+  if (grant.where === undefined) return undefined;
+  const counter = { nodes: 0 };
+  return conditionProblem(spec, grant.where, 1, counter, maxInList);
+}
+
+function conditionProblem(spec: PermissionSpec, condition: Condition, depth: number, counter: { nodes: number }, maxInList: number): string | undefined {
+  if (depth > MAX_DEPTH) return `the condition is deeper than ${MAX_DEPTH}`;
+  if (++counter.nodes > MAX_NODES) return `the condition has more than ${MAX_NODES} nodes`;
+  if (typeof condition !== "object" || condition === null || Array.isArray(condition)) return "a condition must be an object";
+  const keys = Object.keys(condition);
+  if (keys.length !== 1) return `a condition must have exactly one key, got ${keys.length === 0 ? "none" : keys.join(", ")}`;
+  const key = keys[0]!;
+  const value = (condition as Record<string, unknown>)[key];
+  if (key === "all" || key === "any") {
+    if (!Array.isArray(value) || value.length === 0) return `${key} must be a non-empty list`;
+    for (const inner of value) {
+      const problem = conditionProblem(spec, inner as Condition, depth + 1, counter, maxInList);
+      if (problem !== undefined) return problem;
+    }
+    return undefined;
+  }
+  if (key === "not") return conditionProblem(spec, value as Condition, depth + 1, counter, maxInList);
+  if (key === "own") {
+    if (value !== true) return "own must be true";
+    return spec.owner === undefined ? "the permission declares no owner, own cannot be used" : undefined;
+  }
+  if (spec.on?.[key] === undefined) return `unknown attribute "${key}"`;
+  return testProblem(key, value, maxInList);
+}
+
+function testProblem(attribute: string, test: unknown, maxInList: number): string | undefined {
+  if (typeof test !== "object" || test === null || Array.isArray(test)) return `the test of "${attribute}" must be an object`;
+  const keys = Object.keys(test);
+  if (keys.length !== 1) return `the test of "${attribute}" must have exactly one of eq, in, notIn, isNull`;
+  const [op] = keys;
+  const value = (test as Record<string, unknown>)[op!];
+  switch (op) {
+    case "eq":
+      return isValue(value) && value !== null ? undefined : `${attribute}.eq must be a string, number or boolean (an empty value is tested with isNull)`;
+    case "in":
+    case "notIn":
+      if (!Array.isArray(value) || !value.every((item) => isValue(item) && item !== null)) return `${attribute}.${op} must be a list of strings, numbers or booleans (an empty value is tested with isNull)`;
+      return value.length > maxInList ? `${attribute}.${op} has more than ${maxInList} values` : undefined;
+    case "isNull":
+      return typeof value === "boolean" ? undefined : `${attribute}.isNull must be true or false`;
+    default:
+      return `unknown test "${op}" of "${attribute}"`;
+  }
+}
+
+/**
+ * The value of a condition on an object, in SQL's three-valued logic so that a
+ * check and a list filter agree: an attribute the object does not carry, or a
+ * `null` compared with a value, is unknown; unknown at the top denies.
+ */
+export function evaluate(condition: Condition, object: Readonly<Record<string, unknown>>, spec: PermissionSpec, ownerIds: readonly string[]): boolean | undefined {
+  if ("all" in condition && Array.isArray(condition.all)) {
+    let result: boolean | undefined = true;
+    for (const inner of condition.all as readonly Condition[]) {
+      const value = evaluate(inner, object, spec, ownerIds);
+      if (value === false) return false;
+      if (value === undefined) result = undefined;
+    }
+    return result;
+  }
+  if ("any" in condition && Array.isArray(condition.any)) {
+    let result: boolean | undefined = false;
+    for (const inner of condition.any as readonly Condition[]) {
+      const value = evaluate(inner, object, spec, ownerIds);
+      if (value === true) return true;
+      if (value === undefined) result = undefined;
+    }
+    return result;
+  }
+  if ("not" in condition && isCondition(condition.not)) {
+    const value = evaluate(condition.not, object, spec, ownerIds);
+    return value === undefined ? undefined : !value;
+  }
+  if ("own" in condition && condition.own === true) {
+    const owner = object[spec.owner!];
+    if (owner === undefined) return undefined;
+    if (owner === null) return false;
+    return ownerIds.includes(String(owner));
+  }
+  const [attribute, test] = Object.entries(condition)[0] as [string, ValueTest];
+  return testValue(object[attribute], test);
+}
+
+function testValue(raw: unknown, test: ValueTest): boolean | undefined {
+  if (raw === undefined) return undefined;
+  if ("isNull" in test) return (raw === null) === test.isNull;
+  if (raw === null) return undefined;
+  if ("eq" in test) return same(raw, test.eq);
+  const found = ("in" in test ? test.in : test.notIn).some((value) => same(raw, value));
+  return "in" in test ? found : !found;
+}
+
+/** Ids come as numbers from one side and as strings from the other. */
+function same(raw: unknown, value: AccessValue): boolean {
+  if (typeof raw === typeof value) return raw === value;
+  if ((typeof raw === "number" || typeof raw === "string") && (typeof value === "number" || typeof value === "string")) return String(raw) === String(value);
+  return false;
+}
+
+export function isValue(value: unknown): value is AccessValue {
+  return value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value));
+}
+
+function isScope(value: unknown): value is Scope {
+  return value === null || typeof value === "string";
+}
+
+function isCondition(value: unknown): value is Condition {
+  return typeof value === "object" && value !== null;
+}

package/core/access/check/filter.ts

@@ -0,0 +1,132 @@
+import { Operand, type Predicate } from "../../../library/orm";
+import type { Class } from "../../di";
+import type { PermissionSpec } from "../catalog/permissions";
+import type { AttributeLookup } from "../contracts/AttributeLookup";
+import { AccessFilterTooLargeError } from "../contracts/errors";
+import type { AccessValue, Condition, Grant, Scope, ValueTest } from "../contracts/types";
+
+/** A condition on the columns of the listed rows. */
+export type ColumnCondition =
+  | { readonly all: readonly ColumnCondition[] }
+  | { readonly any: readonly ColumnCondition[] }
+  | { readonly not: ColumnCondition }
+  | { readonly column: string; readonly in: readonly AccessValue[] }
+  | { readonly column: string; readonly isNull: boolean };
+
+/** Which rows of a list the subject may see (ACCESS-001 §4.3). */
+export type AccessFilter =
+  | { readonly kind: "all" }
+  | { readonly kind: "none" }
+  | { readonly kind: "where"; readonly where: ColumnCondition };
+
+type Built = ColumnCondition | boolean;
+
+export interface FilterInput {
+  readonly permission: string;
+  readonly spec: PermissionSpec;
+  readonly grants: "all" | readonly Grant[];
+  readonly ownerIds: readonly string[];
+  /** The partition of the request for a permission with `scope: "request"`. */
+  readonly requestScope: Scope | undefined;
+  readonly maxInList: number;
+  readonly lookup: (type: Class<AttributeLookup>) => AttributeLookup;
+}
+
+export async function buildFilter(input: FilterInput): Promise<AccessFilter> {
+  if (input.grants === "all") return { kind: "all" };
+  if (input.spec.scope === "request" && input.requestScope === undefined) {
+    throw new TypeError(`The list filter of "${input.permission}" needs the partition of the request: filter(permission, { scope }).`);
+  }
+  const parts: Built[] = [];
+  for (const grant of input.grants) {
+    const scope = await scopeCondition(input, grant);
+    parts.push(scope === false ? false : and([scope, grant.where === undefined ? true : await whereCondition(input, grant.where)]));
+  }
+  const result = or(parts);
+  return result === true ? { kind: "all" } : result === false ? { kind: "none" } : { kind: "where", where: result };
+}
+
+async function scopeCondition(input: FilterInput, grant: Grant): Promise<Built> {
+  const source = input.spec.scope ?? "none";
+  if (grant.scopes === "all") return true;
+  if (source === "none") return grant.scopes.includes(null);
+  if (source === "request") return grant.scopes.includes(input.requestScope!);
+  if ("column" in source) return inColumn(source.column, grant.scopes);
+  return await fromLookup(input, source.lookup, grant.scopes);
+}
+
+async function whereCondition(input: FilterInput, condition: Condition): Promise<Built> {
+  if ("all" in condition && Array.isArray(condition.all)) return and(await Promise.all((condition.all as readonly Condition[]).map((inner) => whereCondition(input, inner))));
+  if ("any" in condition && Array.isArray(condition.any)) return or(await Promise.all((condition.any as readonly Condition[]).map((inner) => whereCondition(input, inner))));
+  if ("not" in condition && typeof condition.not === "object" && condition.not !== null) return not(await whereCondition(input, condition.not as Condition));
+  if ("own" in condition && condition.own === true) return inColumn(input.spec.owner!, input.ownerIds);
+  const [name, test] = Object.entries(condition)[0] as [string, ValueTest];
+  const attribute = input.spec.on![name]!;
+  if (attribute.lookup !== undefined) {
+    const lookup = attribute.lookup;
+    if ("isNull" in test) return test.isNull ? await fromLookup(input, lookup, [null]) : not(await fromLookup(input, lookup, [null]));
+    if ("eq" in test) return await fromLookup(input, lookup, [test.eq]);
+    if ("in" in test) return await fromLookup(input, lookup, test.in);
+    return not(await fromLookup(input, lookup, test.notIn));
+  }
+  const column = attribute.column ?? name;
+  if ("isNull" in test) return { column, isNull: test.isNull };
+  if ("eq" in test) return { column, in: [test.eq] };
+  if ("in" in test) return test.in.length === 0 ? false : { column, in: test.in };
+  return test.notIn.length === 0 ? { column, isNull: false } : not({ column, in: test.notIn });
+}
+
+async function fromLookup(input: FilterInput, type: Class<AttributeLookup>, values: readonly AccessValue[]): Promise<Built> {
+  const found = await input.lookup(type).toColumn(values);
+  if (found.in.length > input.maxInList) {
+    throw new AccessFilterTooLargeError(`The list filter of "${input.permission}": ${type.name} gave ${found.in.length} values of "${found.column}", more than access.maxInList (${input.maxInList}).`);
+  }
+  return inColumn(found.column, found.in);
+}
+
+/** `column in values`; `null` among them means an empty column. */
+function inColumn(column: string, values: readonly AccessValue[]): Built {
+  const known = values.filter((value) => value !== null);
+  return or([known.length === 0 ? false : { column, in: known }, values.includes(null) ? { column, isNull: true } : false]);
+}
+
+function and(parts: readonly Built[]): Built {
+  if (parts.includes(false)) return false;
+  const rest = parts.filter((part): part is ColumnCondition => part !== true);
+  return rest.length === 0 ? true : rest.length === 1 ? rest[0]! : { all: rest };
+}
+
+function or(parts: readonly Built[]): Built {
+  if (parts.includes(true)) return true;
+  const rest = parts.filter((part): part is ColumnCondition => part !== false);
+  return rest.length === 0 ? false : rest.length === 1 ? rest[0]! : { any: rest };
+}
+
+function not(part: Built): Built {
+  return typeof part === "boolean" ? !part : { not: part };
+}
+
+/**
+ * The filter as an ORM condition: `"all"` — no restriction, `"none"` — no rows
+ * at all (answer an empty page without a query).
+ *
+ * ```ts
+ * const where = grantsToWhere(await access.filter("orders.read"));
+ * if (where === "none") return { items: [], total: 0 };
+ * let query = db.orders.asNoTracking();
+ * if (where !== "all") query = query.where(() => where);
+ * ```
+ */
+export function grantsToWhere(filter: AccessFilter): Predicate | "all" | "none" {
+  if (filter.kind !== "where") return filter.kind;
+  return toPredicate(filter.where);
+}
+
+function toPredicate(condition: ColumnCondition): Predicate {
+  if ("all" in condition) return condition.all.map(toPredicate).reduce((left, right) => left.and(right));
+  if ("any" in condition) return condition.any.map(toPredicate).reduce((left, right) => left.or(right));
+  if ("not" in condition) return toPredicate(condition.not).not();
+  const column = new Operand(condition.column);
+  if ("isNull" in condition) return condition.isNull ? column.isNull() : column.isNotNull();
+  return condition.in.length === 1 ? column.eq(condition.in[0]) : column.in(condition.in);
+}

package/core/access/contracts/AccessPolicy.ts

@@ -0,0 +1,29 @@
+import type { AuthorizeContext } from "../../http";
+import type { AccessSubject, Grants, Scope } from "./types";
+
+/**
+ * The rights system of the application (ACCESS-001 §4.1): a CMS roles module,
+ * `bazis/identity`, or the roles of `@Module({ roles })` by default
+ * (`RolesAccessPolicy`). It answers with data — grants — and the framework
+ * checks objects and filters lists by them itself. The application replaces
+ * the default in its module: `singleton(AccessPolicy, AppAccessPolicy)` (or
+ * `scoped`, when it needs a DbContext).
+ */
+export abstract class AccessPolicy {
+  /** Who makes the request: usually reads the principal the application's route check put into `ctx.state`. */
+  abstract subject(ctx: AuthorizeContext): AccessSubject | undefined | Promise<AccessSubject | undefined>;
+
+  /** What the subject is given by the permission. */
+  abstract grants(subject: AccessSubject, permission: string): Grants | Promise<Grants>;
+
+  /** The owner column values that mean "me" for `{ own: true }`: usually the bare account id. */
+  abstract ownerIds(subject: AccessSubject): readonly string[] | Promise<readonly string[]>;
+
+  /** Whom the subject is in each partition, for tasks: `user:<id>`, `role:<code>`, kinds of the application. */
+  abstract principals(subject: AccessSubject, scopes: readonly Scope[]): Promise<readonly ScopePrincipals[]>;
+}
+
+export interface ScopePrincipals {
+  readonly scope: Scope;
+  readonly principals: readonly string[];
+}

package/core/access/contracts/AttributeLookup.ts

@@ -0,0 +1,17 @@
+import type { AccessValue } from "./types";
+
+/**
+ * Turns a condition on an attribute that is not a column of the listed rows
+ * into a condition on a column (ACCESS-001 §3): `folder in [Sales]` →
+ * `processKey in [keys of the folder's processes]`. A class of the declaring
+ * module, registered in its `providers`; it is resolved in the request scope.
+ */
+export abstract class AttributeLookup {
+  /** The column and its values equivalent to "the attribute is one of `values`" (`null` — the attribute is empty). */
+  abstract toColumn(values: readonly AccessValue[]): Promise<LookupColumn> | LookupColumn;
+}
+
+export interface LookupColumn {
+  readonly column: string;
+  readonly in: readonly AccessValue[];
+}

package/core/access/contracts/References.ts

@@ -0,0 +1,33 @@
+import type { LocalizedText, Scope } from "./types";
+
+/**
+ * Values of a reference kind (ACCESS-001 §6): what the administrator picks in a
+ * condition («which tables», «which processes») and what a process checks for
+ * `x-ref`. A module declares the kinds it owns in `@Module({ references })`;
+ * the class is registered in its `providers` and resolved in the request scope.
+ */
+export abstract class References {
+  /** Which of `ids` exist. */
+  abstract exists(ids: readonly string[], context: ReferenceContext): Promise<ReadonlySet<string>>;
+
+  /** Titles of `ids`; unknown ones are left out. */
+  abstract describe(ids: readonly string[], context: ReferenceContext): Promise<readonly ReferenceItem[]>;
+
+  /** Values whose title or id contains `text` (empty — all), page by page. */
+  abstract search(text: string, context: ReferenceContext, page: ReferencePage): Promise<readonly ReferenceItem[]>;
+}
+
+export interface ReferenceItem {
+  readonly id: string;
+  readonly title: LocalizedText;
+}
+
+export interface ReferenceContext {
+  readonly scope: Scope;
+  readonly language?: string;
+}
+
+export interface ReferencePage {
+  readonly limit: number;
+  readonly offset: number;
+}

package/core/access/contracts/errors.ts

@@ -0,0 +1,13 @@
+/** A problem of declared permissions, references or roles; the application reports it as a configuration error. */
+export class AccessSetupError extends Error {
+  override readonly name = "AccessSetupError";
+}
+
+/**
+ * A list filter that cannot be built: a lookup gave more values than
+ * `access.maxInList` (ACCESS-001 §4.3). The request fails with 500.
+ */
+export class AccessFilterTooLargeError extends Error {
+  override readonly name = "AccessFilterTooLargeError";
+  readonly code = "access_filter_too_large";
+}

package/core/access/contracts/types.ts

@@ -0,0 +1,66 @@
+/** A text for people: one string, or a text per language (`{ ru: "…", en: "…" }`). */
+export type LocalizedText = string | Readonly<Record<string, string>>;
+
+/** A value an attribute of an object can have in a condition. */
+export type AccessValue = string | number | boolean | null;
+
+/** A partition of the application (a CMS space, a tenant); `null` — no partition. */
+export type Scope = string | null;
+
+/** A test of one attribute. */
+export type ValueTest =
+  | { readonly eq: AccessValue }
+  | { readonly in: readonly AccessValue[] }
+  | { readonly notIn: readonly AccessValue[] }
+  | { readonly isNull: boolean };
+
+/**
+ * A condition of a grant (ACCESS-001 §4.2): a tree over the attributes the
+ * permission declares in `on`. `{ own: true }` — the object belongs to the
+ * subject. Values are final: the rights system substitutes "my organization"
+ * and the like itself.
+ */
+export type Condition =
+  | { readonly all: readonly Condition[] }
+  | { readonly any: readonly Condition[] }
+  | { readonly not: Condition }
+  | { readonly own: true }
+  | { readonly [attribute: string]: ValueTest };
+
+/** Field lists of a grant for a permission with `fields: true`. */
+export interface GrantFields {
+  readonly read?: readonly string[] | "all";
+  readonly write?: readonly string[] | "all";
+}
+
+/** What a subject is given by one permission: in these partitions, on these conditions. */
+export interface Grant {
+  readonly scopes: "all" | readonly Scope[];
+  readonly where?: Condition;
+  readonly fields?: GrantFields;
+}
+
+/** `"all"` — everything without conditions (a superuser); `[]` — nothing. Grants add up with "or". */
+export type Grants = "all" | readonly Grant[];
+
+/**
+ * Who acts: `sub` is `"<account kind>:<id>"` so that accounts of different
+ * tables with one id do not merge; `act` — on whose behalf (an organization).
+ * A rights system may add its own fields: the framework hands the same object
+ * back to it.
+ */
+export interface AccessSubject {
+  readonly sub: string;
+  readonly act?: string;
+}
+
+/**
+ * What is checked: the attribute values of the object, its partition (one or
+ * several) under `scope`, and the owner column under the name the permission
+ * declares in `owner`. Without an object `can` answers whether the subject has
+ * the permission anywhere.
+ */
+export interface AccessObject {
+  readonly scope?: Scope | readonly Scope[];
+  readonly [attribute: string]: unknown;
+}

package/core/access/generated/deps.ts

@@ -0,0 +1,14 @@
+// This file is auto-generated by `bun run di:generate` (framework.packs of bazis.config.json).
+// Do not edit manually.
+import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
+import { ServiceProvider } from "../../di/ServiceProvider";
+import { AccessCatalog } from "../catalog/AccessCatalog";
+import { IAccessCatalog } from "../catalog/IAccessCatalog.service";
+import { Access } from "../check/Access";
+import { RolesAccessPolicy } from "../roles/RolesAccessPolicy";
+
+registerFrameworkClassDeps([
+  [Access, [IAccessCatalog, "Config:access"]],
+  [AccessCatalog, [ServiceProvider]],
+  [RolesAccessPolicy, [IAccessCatalog, "Config:access"]],
+]);

package/core/access/http/AccessCatalog.controller.ts

@@ -0,0 +1,51 @@
+import { contextOnlyController } from "../../http/Routing/contextOnlyControllers";
+import { Authorize, BadRequestError, Controller, Get, NotFoundError, type HttpContext } from "../../http";
+import { IAccessCatalog } from "../catalog/IAccessCatalog.service";
+import { can } from "../check/can";
+import type { Scope } from "../contracts/types";
+
+/**
+ * The catalog for the administrator's screens of the rights system
+ * (ACCESS-001 §7): what can be allowed, and the values to pick in conditions.
+ * Read only: roles live in the rights system.
+ */
+@Controller("access")
+export class AccessCatalogController {
+  @Get("catalog")
+  @Authorize(can("access.catalog.read"))
+  catalogList(ctx: HttpContext) {
+    return {
+      data: ctx.services.resolve(IAccessCatalog).permissions().map(({ key, spec, module }) => ({
+        key,
+        module,
+        title: spec.title,
+        ...(spec.description === undefined ? {} : { description: spec.description }),
+        scope: typeof spec.scope === "object" ? ("column" in spec.scope ? "column" : "lookup") : spec.scope ?? "none",
+        attributes: Object.entries(spec.on ?? {}).map(([name, attribute]) => ({ name, ...(attribute.ref === undefined ? { type: attribute.type } : { ref: attribute.ref }) })),
+        own: spec.owner !== undefined,
+        fields: spec.fields === true,
+      })),
+    };
+  }
+
+  @Get("references/:kind")
+  @Authorize(can("access.catalog.read"))
+  async references(ctx: HttpContext) {
+    const kind = ctx.services.resolve(IAccessCatalog).referenceKind(String(ctx.params.kind ?? ""));
+    if (kind === undefined) throw new NotFoundError();
+    const limit = integer(ctx.query("limit"), "limit", 50, 1, 200);
+    const offset = integer(ctx.query("offset"), "offset", 0, 0, 1_000_000);
+    const scope: Scope = ctx.query("scope") ?? null;
+    const items = await ctx.services.resolve(kind.type).search(ctx.query("search") ?? "", { scope }, { limit, offset });
+    return { data: items };
+  }
+}
+
+contextOnlyController(AccessCatalogController);
+
+function integer(raw: string | undefined, name: string, fallback: number, min: number, max: number): number {
+  if (raw === undefined || raw === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new BadRequestError(`${name} must be an integer ${min}–${max}`);
+  return value;
+}

package/core/access/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Access as a layer of the framework (ACCESS-001): modules declare
+ * permissions, the application's rights system answers with grants, the
+ * framework checks objects and filters lists by them.
+ */
+import "./catalog/moduleFields";
+import "./generated/deps";
+
+export { AccessModule } from "./Access.module";
+export { definePermissions, type AttributeSpec, type PermissionDeclarations, type PermissionSpec, type ScopeSource } from "./catalog/permissions";
+export { IAccessCatalog } from "./catalog/IAccessCatalog.service";
+export type { DeclaredRole, OwnedPermission, OwnedReferenceKind } from "./catalog/AccessCatalog";
+export { IAccess } from "./check/IAccess.service";
+export { SubjectAccess, maskFields, type FieldAccess } from "./check/Access";
+export { accessConfig } from "./check/accessConfig";
+export { can } from "./check/can";
+export { grantsToWhere, type AccessFilter, type ColumnCondition } from "./check/filter";
+export { AccessPolicy, type ScopePrincipals } from "./contracts/AccessPolicy";
+export { AttributeLookup, type LookupColumn } from "./contracts/AttributeLookup";
+export { References, type ReferenceContext, type ReferenceItem, type ReferencePage } from "./contracts/References";
+export { AccessFilterTooLargeError, AccessSetupError } from "./contracts/errors";
+export type {
+  AccessObject,
+  AccessSubject,
+  AccessValue,
+  Condition,
+  Grant,
+  GrantFields,
+  Grants,
+  LocalizedText,
+  Scope,
+  ValueTest,
+} from "./contracts/types";
+export { defineRoles, type RoleDeclarations, type RoleGrant } from "./roles/roles";
+export { RolesAccessPolicy, type RoleSubject } from "./roles/RolesAccessPolicy";

package/core/access/roles/RolesAccessPolicy.ts

@@ -0,0 +1,64 @@
+import type { ConfigView } from "../../kernel";
+import { PRINCIPAL_STATE_KEY, type AuthorizeContext, type RequestPrincipal } from "../../http";
+import type { IAccessCatalog } from "../catalog/IAccessCatalog.service";
+import type { AccessConfig } from "../check/accessConfig";
+import { AccessPolicy, type ScopePrincipals } from "../contracts/AccessPolicy";
+import type { AccessSubject, Grant, Grants, Scope } from "../contracts/types";
+
+/** The subject of the default rights system: the account id and its roles from the token. */
+export interface RoleSubject extends AccessSubject {
+  readonly id: string;
+  readonly roles: readonly string[];
+}
+
+/**
+ * The default `AccessPolicy` (ACCESS-001 §8); an application replaces it by
+ * registering its own: `singleton(AccessPolicy, AppAccessPolicy)`. The principal of the route check is the subject, its roles come from the
+ * `access.roleClaim` claim, their permissions from `@Module({ roles })`. A role
+ * nobody declared gives nothing; without roles everything is denied. A step
+ * until `bazis/identity`.
+ */
+export class RolesAccessPolicy extends AccessPolicy {
+  constructor(private readonly catalog: IAccessCatalog, private readonly config: ConfigView<AccessConfig>) {
+    super();
+  }
+
+  subject(ctx: AuthorizeContext): RoleSubject | undefined {
+    const principal = ctx.state.get(PRINCIPAL_STATE_KEY) as RequestPrincipal | undefined;
+    const id = principal?.subject;
+    if (id === undefined || id === "") return undefined;
+    const kindClaim = this.config.get("kindClaim");
+    const kind = kindClaim === "" ? undefined : principal!.findFirst?.(kindClaim);
+    const roles = (principal!.findFirst?.(this.config.get("roleClaim")) ?? "").split(/[\s,]+/).filter((role) => role !== "");
+    return { sub: kind === undefined || kind === "" ? id : `${kind}:${id}`, id, roles };
+  }
+
+  grants(subject: AccessSubject, permission: string): Grants {
+    const grants: Grant[] = [];
+    for (const name of rolesOf(subject)) {
+      const role = this.catalog.role(name);
+      if (role === undefined) continue;
+      if (role.permissions === "all") return "all";
+      for (const item of role.permissions) if (item.permission === permission) grants.push(item.grant);
+    }
+    return grants;
+  }
+
+  ownerIds(subject: AccessSubject): readonly string[] {
+    return [idOf(subject)];
+  }
+
+  async principals(subject: AccessSubject, scopes: readonly Scope[]): Promise<readonly ScopePrincipals[]> {
+    const principals = [`user:${idOf(subject)}`, ...rolesOf(subject).map((role) => `role:${role}`)];
+    return scopes.map((scope) => ({ scope, principals }));
+  }
+}
+
+function rolesOf(subject: AccessSubject): readonly string[] {
+  const roles = (subject as Partial<RoleSubject>).roles;
+  return Array.isArray(roles) ? roles : [];
+}
+
+function idOf(subject: AccessSubject): string {
+  return (subject as Partial<RoleSubject>).id ?? subject.sub;
+}

package/core/access/roles/roles.ts

@@ -0,0 +1,62 @@
+import type { Condition, Grant, GrantFields, Scope } from "../contracts/types";
+
+/**
+ * A permission of a role: its key, `"<key>:own"` for «only one's own», or a
+ * grant with conditions.
+ */
+export type RoleGrant =
+  | string
+  | {
+      readonly permission: string;
+      readonly scopes?: "all" | readonly Scope[];
+      readonly where?: Condition;
+      readonly fields?: GrantFields;
+    };
+
+/** Role → `"all"` (everything) or its permissions. */
+export type RoleDeclarations = Readonly<Record<string, "all" | readonly RoleGrant[]>>;
+
+const DECLARED = new WeakSet<object>();
+
+/**
+ * Roles of the default rights system (ACCESS-001 §8), for an application
+ * without its own one: the subject's roles come from the token, their
+ * permissions from here. The result goes to `@Module({ roles })`.
+ *
+ * ```ts
+ * export const appRoles = defineRoles({
+ *   admin: "all",
+ *   manager: ["workflow.instances.start", "workflow.instances.read"],
+ *   user: ["workflow.instances.read:own", "workflow.tasks.work"],
+ * });
+ * ```
+ */
+export function defineRoles<const T extends RoleDeclarations>(roles: T): T {
+  const frozen = Object.freeze({ ...roles });
+  DECLARED.add(frozen);
+  return frozen;
+}
+
+export function isDeclaredRoles(value: unknown): value is RoleDeclarations {
+  return typeof value === "object" && value !== null && DECLARED.has(value);
+}
+
+/** One permission of a role as a grant. */
+export interface RolePermission {
+  readonly permission: string;
+  readonly grant: Grant;
+}
+
+/** `"orders.read:own"` → `orders.read` with `{ own: true }`. */
+export function rolePermission(item: RoleGrant): RolePermission {
+  if (typeof item === "string") {
+    if (item.endsWith(":own")) return { permission: item.slice(0, -4), grant: { scopes: "all", where: { own: true } } };
+    return { permission: item, grant: { scopes: "all" } };
+  }
+  const grant: Grant = {
+    scopes: item.scopes ?? "all",
+    ...(item.where === undefined ? {} : { where: item.where }),
+    ...(item.fields === undefined ? {} : { fields: item.fields }),
+  };
+  return { permission: item.permission, grant };
+}