bazis 0.128.0 → 0.130.0

package/core/access/Access.module.ts

@@ -0,0 +1,36 @@
+import { Module, singleton } from "../di";
+import { AccessCatalog } from "./catalog/AccessCatalog";
+import { IAccessCatalog } from "./catalog/IAccessCatalog.service";
+import { definePermissions } from "./catalog/permissions";
+import { Access } from "./check/Access";
+import { accessConfig } from "./check/accessConfig";
+import { IAccess } from "./check/IAccess.service";
+import { AccessPolicy } from "./contracts/AccessPolicy";
+import { AccessCatalogController } from "./http/AccessCatalog.controller";
+import { RolesAccessPolicy } from "./roles/RolesAccessPolicy";
+
+const accessPermissions = definePermissions({
+  "access.catalog.read": {
+    title: { en: "See the permissions catalog", ru: "Видеть каталог прав" },
+  },
+});
+
+/**
+ * Access as a layer of the framework (ACCESS-001, [passport](MODULE.md)):
+ * the catalog of the modules' permissions, checks and list filters by the
+ * grants of the application's `AccessPolicy`, the default rights system by
+ * `@Module({ roles })`, and the catalog over HTTP. An application replaces the
+ * rights system by registering its own `AccessPolicy`.
+ */
+@Module({
+  config: [accessConfig],
+  permissions: accessPermissions,
+  providers: [
+    singleton(IAccessCatalog, AccessCatalog),
+    singleton(AccessPolicy, RolesAccessPolicy),
+    singleton(IAccess, Access),
+  ],
+  controllers: [AccessCatalogController],
+  exports: [IAccessCatalog, IAccess, AccessPolicy],
+})
+export class AccessModule {}

package/core/access/catalog/AccessCatalog.ts

@@ -0,0 +1,73 @@
+import type { Class } from "../../di";
+import type { ServiceProvider } from "../../di/ServiceProvider";
+import type { References } from "../contracts/References";
+import type { RolePermission } from "../roles/roles";
+import { IAccessCatalog } from "./IAccessCatalog.service";
+import { declarationsOf } from "./moduleFields";
+import type { PermissionSpec } from "./permissions";
+
+/** A permission of `@Module({ permissions })` with the module that declares it. */
+export interface OwnedPermission {
+  readonly key: string;
+  readonly spec: PermissionSpec;
+  readonly module: string;
+}
+
+/** A reference kind of `@Module({ references })`. */
+export interface OwnedReferenceKind {
+  readonly kind: string;
+  readonly type: Class<References>;
+  readonly module: string;
+}
+
+/** A role of `@Module({ roles })`: `"all"` or its permissions as grants. */
+export interface DeclaredRole {
+  readonly name: string;
+  readonly permissions: "all" | readonly RolePermission[];
+  readonly module: string;
+}
+
+/** The catalog read from the container's module contributions. */
+export class AccessCatalog extends IAccessCatalog {
+  private readonly byKey: ReadonlyMap<string, OwnedPermission>;
+  private readonly byKind: ReadonlyMap<string, OwnedReferenceKind>;
+  private readonly byName: ReadonlyMap<string, DeclaredRole>;
+
+  constructor(services: ServiceProvider) {
+    super();
+    const { permissions, kinds, roles } = declarationsOf(services);
+    this.byKey = new Map([...permissions].sort((a, b) => a.key.localeCompare(b.key)).map((item) => [item.key, item]));
+    this.byKind = new Map([...kinds].sort((a, b) => a.kind.localeCompare(b.kind)).map((item) => [item.kind, item]));
+    this.byName = new Map(roles.map((item) => [item.name, item]));
+  }
+
+  permissions(): readonly OwnedPermission[] {
+    return [...this.byKey.values()];
+  }
+
+  permission(key: string): OwnedPermission | undefined {
+    return this.byKey.get(key);
+  }
+
+  require(key: string): OwnedPermission {
+    const permission = this.byKey.get(key);
+    if (permission === undefined) throw new TypeError(`Permission "${key}" is not declared: add it to definePermissions(...) of a module's permissions.`);
+    return permission;
+  }
+
+  referenceKinds(): readonly OwnedReferenceKind[] {
+    return [...this.byKind.values()];
+  }
+
+  referenceKind(kind: string): OwnedReferenceKind | undefined {
+    return this.byKind.get(kind);
+  }
+
+  roles(): readonly DeclaredRole[] {
+    return [...this.byName.values()];
+  }
+
+  role(name: string): DeclaredRole | undefined {
+    return this.byName.get(name);
+  }
+}

package/core/access/catalog/IAccessCatalog.service.ts

@@ -0,0 +1,17 @@
+import type { DeclaredRole, OwnedPermission, OwnedReferenceKind } from "./AccessCatalog";
+
+/**
+ * What the application's modules declared about access: permissions, reference
+ * kinds and default roles (ACCESS-001 §3, §6, §8). Checked when the application
+ * is built.
+ */
+export abstract class IAccessCatalog {
+  abstract permissions(): readonly OwnedPermission[];
+  abstract permission(key: string): OwnedPermission | undefined;
+  /** The permission or an error: asking for an undeclared one is a bug of the caller. */
+  abstract require(key: string): OwnedPermission;
+  abstract referenceKinds(): readonly OwnedReferenceKind[];
+  abstract referenceKind(kind: string): OwnedReferenceKind | undefined;
+  abstract roles(): readonly DeclaredRole[];
+  abstract role(name: string): DeclaredRole | undefined;
+}

package/core/access/catalog/moduleFields.ts

@@ -0,0 +1,153 @@
+import {
+  createModuleOwnedMetadataChannel,
+  registerModuleOwnedContributionValidator,
+  registerModuleOwnedProviderContributor,
+  DiContainer,
+  type BazisModuleMetadata,
+  type Class,
+  type ServiceProvider,
+} from "../../di";
+import { grantProblem } from "../check/conditions";
+import { AccessSetupError } from "../contracts/errors";
+import type { References } from "../contracts/References";
+import { isDeclaredRoles, rolePermission, type RoleDeclarations, type RolePermission } from "../roles/roles";
+import { IAccess } from "../check/IAccess.service";
+import type { DeclaredRole, OwnedPermission, OwnedReferenceKind } from "./AccessCatalog";
+import { isDeclaredPermissions, isReferenceKind, lookupsOf, permissionProblems, type PermissionDeclarations, type PermissionSpec } from "./permissions";
+
+interface PermissionPayload { readonly key: string; readonly spec: PermissionSpec }
+interface ReferencePayload { readonly kind: string; readonly type: Class<References> }
+interface RolePayload { readonly name: string; readonly permissions: "all" | readonly RolePermission[] }
+
+const PERMISSION_CHANNEL = createModuleOwnedMetadataChannel<PermissionPayload>("access.permission/v1");
+const REFERENCE_CHANNEL = createModuleOwnedMetadataChannel<ReferencePayload>("access.reference/v1");
+const ROLE_CHANNEL = createModuleOwnedMetadataChannel<RolePayload>("access.role/v1");
+
+/** The values of `in`/`notIn` a role may list; the run-time limit is `access.maxInList`. */
+const STARTUP_MAX_IN_LIST = 1000;
+const ROLE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+
+// Internal imports must not depend on the public barrel having augmented DI's metadata interface.
+interface AccessModuleFields {
+  readonly permissions?: unknown;
+  readonly references?: unknown;
+  readonly roles?: unknown;
+}
+
+registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context) => {
+  const fields = metadata as BazisModuleMetadata & AccessModuleFields;
+  if (fields.permissions === undefined && fields.references === undefined && fields.roles === undefined) return;
+  const module = moduleName(metadata);
+  if (fields.permissions !== undefined) {
+    if (!isDeclaredPermissions(fields.permissions)) throw new AccessSetupError(`${module}: permissions must be a definePermissions(...) result.`);
+    const problems = Object.entries(fields.permissions).flatMap(([key, spec]) => permissionProblems(key, spec));
+    if (problems.length > 0) throw setupError(module, "permissions", problems);
+    for (const [key, spec] of Object.entries(fields.permissions)) context.addMetadata(PERMISSION_CHANNEL, { key, spec });
+  }
+  if (fields.references !== undefined) {
+    const references = fields.references;
+    if (typeof references !== "object" || references === null || Array.isArray(references)) throw new AccessSetupError(`${module}: references must map a reference kind to a References class.`);
+    const problems: string[] = [];
+    for (const [kind, type] of Object.entries(references)) {
+      if (!isReferenceKind(kind)) problems.push(`reference kind "${kind}" must look like "<module>.<kind>" in lower case`);
+      if (typeof type !== "function") problems.push(`reference kind "${kind}" must name a References class`);
+    }
+    if (problems.length > 0) throw setupError(module, "references", problems);
+    for (const [kind, type] of Object.entries(references)) context.addMetadata(REFERENCE_CHANNEL, { kind, type: type as Class<References> });
+  }
+  if (fields.roles !== undefined) {
+    if (!isDeclaredRoles(fields.roles)) throw new AccessSetupError(`${module}: roles must be a defineRoles(...) result.`);
+    const problems: string[] = [];
+    for (const [name, permissions] of Object.entries(fields.roles as RoleDeclarations)) {
+      if (!ROLE.test(name)) problems.push(`role "${name}" must be a name of letters, digits, _, . and -`);
+      if (permissions !== "all" && !Array.isArray(permissions)) problems.push(`role "${name}" must be "all" or a list of permissions`);
+    }
+    if (problems.length > 0) throw setupError(module, "roles", problems);
+    for (const [name, permissions] of Object.entries(fields.roles as RoleDeclarations)) {
+      context.addMetadata(ROLE_CHANNEL, { name, permissions: permissions === "all" ? "all" : permissions.map(rolePermission) });
+    }
+  }
+});
+
+registerModuleOwnedContributionValidator((snapshot) => {
+  const permissions = snapshot.getMetadataContributions(PERMISSION_CHANNEL);
+  const references = snapshot.getMetadataContributions(REFERENCE_CHANNEL);
+  const roles = snapshot.getMetadataContributions(ROLE_CHANNEL);
+  const first = permissions[0] ?? references[0] ?? roles[0];
+  if (first === undefined) return;
+  if (snapshot.countProviders(IAccess) === 0) {
+    throw new AccessSetupError(`${first.ownerName} declares access (permissions, references or roles), but the application does not import AccessModule (bazis/core/access).`);
+  }
+
+  const owners = new Map<string, string>();
+  const specs = new Map<string, PermissionSpec>();
+  for (const { payload, ownerName } of permissions) {
+    const other = owners.get(payload.key);
+    if (other !== undefined) throw new AccessSetupError(`Permission "${payload.key}" is declared twice: in ${other} and in ${ownerName}.`);
+    owners.set(payload.key, ownerName);
+    specs.set(payload.key, payload.spec);
+  }
+
+  const kinds = new Map<string, string>();
+  for (const { payload, ownerName } of references) {
+    const other = kinds.get(payload.kind);
+    if (other !== undefined) throw new AccessSetupError(`Reference kind "${payload.kind}" is declared twice: in ${other} and in ${ownerName}.`);
+    kinds.set(payload.kind, ownerName);
+    if (snapshot.countProviders(payload.type) === 0) throw new AccessSetupError(`${ownerName}: ${payload.type.name} of reference kind "${payload.kind}" is not registered: add it to the module's providers.`);
+  }
+
+  for (const { payload, ownerName } of permissions) {
+    for (const [name, attribute] of Object.entries(payload.spec.on ?? {})) {
+      if (attribute.ref !== undefined && !kinds.has(attribute.ref)) {
+        throw new AccessSetupError(`${ownerName}: permission "${payload.key}", attribute "${name}" refers to kind "${attribute.ref}", which no module declares in references.`);
+      }
+    }
+    for (const lookup of lookupsOf(payload.spec)) {
+      if (snapshot.countProviders(lookup) === 0) throw new AccessSetupError(`${ownerName}: ${lookup.name} of permission "${payload.key}" is not registered: add it to the module's providers.`);
+    }
+  }
+
+  const names = new Map<string, string>();
+  for (const { payload, ownerName } of roles) {
+    const other = names.get(payload.name);
+    if (other !== undefined) throw new AccessSetupError(`Role "${payload.name}" is declared twice: in ${other} and in ${ownerName}.`);
+    names.set(payload.name, ownerName);
+    if (payload.permissions === "all") continue;
+    for (const { permission, grant } of payload.permissions) {
+      const spec = specs.get(permission);
+      if (spec === undefined) throw new AccessSetupError(`${ownerName}: role "${payload.name}" names permission "${permission}", which no module declares.`);
+      const problem = grantProblem(spec, grant, STARTUP_MAX_IN_LIST);
+      if (problem !== undefined) throw new AccessSetupError(`${ownerName}: role "${payload.name}", permission "${permission}": ${problem}.`);
+    }
+  }
+});
+
+/** What the modules of the application's container declared. */
+export function declarationsOf(services: ServiceProvider): { permissions: OwnedPermission[]; kinds: OwnedReferenceKind[]; roles: DeclaredRole[] } {
+  if (!(services instanceof DiContainer)) throw new AccessSetupError("Access declarations require the framework DiContainer.");
+  const permissions: OwnedPermission[] = services.getModuleOwnedMetadataContributions(PERMISSION_CHANNEL).map(({ payload, ownerName }) => ({ ...payload, module: ownerName }));
+  const kinds: OwnedReferenceKind[] = services.getModuleOwnedMetadataContributions(REFERENCE_CHANNEL).map(({ payload, ownerName }) => ({ ...payload, module: ownerName }));
+  const roles: DeclaredRole[] = services.getModuleOwnedMetadataContributions(ROLE_CHANNEL).map(({ payload, ownerName }) => ({ ...payload, module: ownerName }));
+  return { permissions, kinds, roles };
+}
+
+function setupError(module: string, field: string, problems: readonly string[]): AccessSetupError {
+  return new AccessSetupError(`${module}: ${field} ${problems.length === 1 ? "has an error" : "have errors"}:\n${problems.map((line) => `  - ${line}`).join("\n")}`);
+}
+
+function moduleName(metadata: BazisModuleMetadata): string {
+  return typeof metadata === "function" ? (metadata as { name: string }).name || "<anonymous module>" : "<module>";
+}
+
+// Augment the declaring file, not the "../../di" re-export: re-export targets
+// depend on program file order and silently stop merging in some projects.
+declare module "../../di/module/types/BazisModule" {
+  interface BazisModuleMetadata {
+    /** What the module lets the administrator allow, from `definePermissions` (ACCESS-001 §3). */
+    readonly permissions?: PermissionDeclarations;
+    /** Reference kinds the module owns: kind → its `References` class, registered in `providers` (ACCESS-001 §6). */
+    readonly references?: Readonly<Record<string, Class<References>>>;
+    /** Roles of the default rights system, from `defineRoles` (ACCESS-001 §8). */
+    readonly roles?: RoleDeclarations;
+  }
+}

package/core/access/catalog/permissions.ts

@@ -0,0 +1,127 @@
+import type { Class } from "../../di";
+import type { AttributeLookup } from "../contracts/AttributeLookup";
+import type { LocalizedText } from "../contracts/types";
+
+/** An attribute of the object of a permission: what a condition may test (ACCESS-001 §3). */
+export interface AttributeSpec {
+  /** A reference kind (`"workflow.process"`): the administrator picks values from it. */
+  readonly ref?: string;
+  /** A plain value instead of a reference. */
+  readonly type?: "string" | "number" | "boolean";
+  /** The column of the listed rows; by default the attribute's name. */
+  readonly column?: string;
+  /** For an attribute that is not a column: turns its condition into a column condition. */
+  readonly lookup?: Class<AttributeLookup>;
+}
+
+/**
+ * Where the partition of an object comes from: a column of the row, a lookup
+ * (several partitions are possible), the request (the caller passes it), or
+ * nowhere — the permission has no partition.
+ */
+export type ScopeSource =
+  | "none"
+  | "request"
+  | { readonly column: string }
+  | { readonly lookup: Class<AttributeLookup> };
+
+export interface PermissionSpec {
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText;
+  /** By default `"none"`. */
+  readonly scope?: ScopeSource;
+  readonly on?: Readonly<Record<string, AttributeSpec>>;
+  /** The owner column: makes `{ own: true }` possible. */
+  readonly owner?: string;
+  /** Grants may carry field lists. */
+  readonly fields?: boolean;
+}
+
+export type PermissionDeclarations = Readonly<Record<string, PermissionSpec>>;
+
+const DECLARED = new WeakSet<object>();
+
+/**
+ * Declares what a module lets the administrator allow or deny (ACCESS-001 §3);
+ * the result goes to `@Module({ permissions })`. Only describes: the checks run
+ * when the application is built.
+ *
+ * ```ts
+ * export const orderPermissions = definePermissions({
+ *   "orders.read": { title: "See orders", scope: { column: "shopId" }, owner: "customerId" },
+ * });
+ * ```
+ */
+export function definePermissions<const T extends PermissionDeclarations>(permissions: T): T {
+  const frozen = deepFreeze({ ...permissions });
+  DECLARED.add(frozen);
+  return frozen;
+}
+
+export function isDeclaredPermissions(value: unknown): value is PermissionDeclarations {
+  return typeof value === "object" && value !== null && DECLARED.has(value);
+}
+
+const KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
+const NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+/** Words of conditions; `scope` is the partition. */
+const RESERVED = new Set(["all", "any", "not", "own", "scope"]);
+
+/** The problems of one permission, before the reference kinds are known. */
+export function permissionProblems(key: string, spec: PermissionSpec): string[] {
+  const problems: string[] = [];
+  const at = `permission "${key}"`;
+  if (!KEY.test(key) || key.length > 128) problems.push(`${at}: the key must look like "<module>.<object>.<action>" in lower case`);
+  if (!isText(spec.title, 200)) problems.push(`${at}: title must be a non-empty text up to 200 characters`);
+  if (spec.description !== undefined && !isText(spec.description, 2000)) problems.push(`${at}: description must be a non-empty text up to 2000 characters`);
+  const scope = spec.scope;
+  if (scope !== undefined && scope !== "none" && scope !== "request") {
+    const column = (scope as { column?: unknown }).column;
+    const lookup = (scope as { lookup?: unknown }).lookup;
+    if ((column === undefined) === (lookup === undefined)) problems.push(`${at}: scope must be "none", "request", { column } or { lookup }`);
+    else if (column !== undefined && !isName(column)) problems.push(`${at}: scope.column must be a column name`);
+    else if (lookup !== undefined && typeof lookup !== "function") problems.push(`${at}: scope.lookup must be an AttributeLookup class`);
+  }
+  for (const [name, attribute] of Object.entries(spec.on ?? {})) {
+    if (!NAME.test(name)) problems.push(`${at}: attribute "${name}" must be a name of letters, digits and _`);
+    else if (RESERVED.has(name)) problems.push(`${at}: attribute "${name}" is a reserved word of conditions`);
+    if ((attribute.ref === undefined) === (attribute.type === undefined)) problems.push(`${at}: attribute "${name}" needs exactly one of ref and type`);
+    if (attribute.ref !== undefined && !KEY.test(attribute.ref)) problems.push(`${at}: attribute "${name}": ref must be a reference kind like "<module>.<kind>"`);
+    if (attribute.type !== undefined && !["string", "number", "boolean"].includes(attribute.type)) problems.push(`${at}: attribute "${name}": type must be string, number or boolean`);
+    if (attribute.column !== undefined && attribute.lookup !== undefined) problems.push(`${at}: attribute "${name}" has both column and lookup`);
+    if (attribute.column !== undefined && !isName(attribute.column)) problems.push(`${at}: attribute "${name}": column must be a column name`);
+    if (attribute.lookup !== undefined && typeof attribute.lookup !== "function") problems.push(`${at}: attribute "${name}": lookup must be an AttributeLookup class`);
+  }
+  if (spec.owner !== undefined && !isName(spec.owner)) problems.push(`${at}: owner must be a column name`);
+  if (spec.fields !== undefined && typeof spec.fields !== "boolean") problems.push(`${at}: fields must be true or false`);
+  return problems;
+}
+
+/** The lookup classes a permission needs registered. */
+export function lookupsOf(spec: PermissionSpec): Class<AttributeLookup>[] {
+  const lookups: Class<AttributeLookup>[] = [];
+  if (typeof spec.scope === "object" && "lookup" in spec.scope) lookups.push(spec.scope.lookup);
+  for (const attribute of Object.values(spec.on ?? {})) if (attribute.lookup !== undefined) lookups.push(attribute.lookup);
+  return lookups;
+}
+
+export function isReferenceKind(value: string): boolean {
+  return KEY.test(value) && value.length <= 128;
+}
+
+function isText(value: unknown, max: number): boolean {
+  if (typeof value === "string") return value.trim() !== "" && value.length <= max;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const entries = Object.entries(value);
+  return entries.length > 0 && entries.every(([language, text]) => /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/.test(language) && typeof text === "string" && text.trim() !== "" && text.length <= max);
+}
+
+function isName(value: unknown): value is string {
+  return typeof value === "string" && NAME.test(value);
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value)) if (typeof item === "object") deepFreeze(item);
+  return Object.freeze(value);
+}

package/core/access/check/Access.ts

@@ -0,0 +1,191 @@
+import type { Class, ServiceResolver } from "../../di";
+import { UnauthorizedError, type AuthorizeContext } from "../../http";
+import { LOGGER, type ConfigView } from "../../kernel";
+import type { AccessConfig } from "./accessConfig";
+import type { IAccessCatalog } from "../catalog/IAccessCatalog.service";
+import type { PermissionSpec } from "../catalog/permissions";
+import { AccessPolicy, type ScopePrincipals } from "../contracts/AccessPolicy";
+import type { AttributeLookup } from "../contracts/AttributeLookup";
+import type { AccessObject, AccessSubject, Condition, Grant, Grants, Scope } from "../contracts/types";
+import { evaluate, grantProblem } from "./conditions";
+import { buildFilter, type AccessFilter } from "./filter";
+import { IAccess } from "./IAccess.service";
+
+const SUBJECT_STATE = "access:subject";
+
+/** The fields the subject may read and write on an object. */
+export interface FieldAccess {
+  readonly read: "all" | readonly string[];
+  readonly write: "all" | readonly string[];
+}
+
+/**
+ * Asks the application's `AccessPolicy` for grants and applies them itself.
+ * The subject of a request is cached on it. The policy and the lookups are
+ * resolved in the given scope: an application may register them scoped.
+ */
+export class Access extends IAccess {
+  constructor(private readonly catalog: IAccessCatalog, private readonly config: ConfigView<AccessConfig>) {
+    super();
+  }
+
+  policy(scope: ServiceResolver): AccessPolicy {
+    return scope.resolve(AccessPolicy);
+  }
+
+  async subject(ctx: AuthorizeContext): Promise<AccessSubject | undefined> {
+    return (await this.cached(ctx))?.subject;
+  }
+
+  async for(ctx: AuthorizeContext): Promise<SubjectAccess> {
+    const access = await this.cached(ctx);
+    if (access === undefined) throw new UnauthorizedError();
+    return access;
+  }
+
+  as(subject: AccessSubject, scope: ServiceResolver): SubjectAccess {
+    return new SubjectAccess(subject, this.policy(scope), this.catalog, this.config.get("maxInList"), scope);
+  }
+
+  private async cached(ctx: AuthorizeContext): Promise<SubjectAccess | undefined> {
+    if (ctx.state.has(SUBJECT_STATE)) return ctx.state.get(SUBJECT_STATE) as SubjectAccess | undefined;
+    const subject = await this.policy(ctx.services).subject(ctx);
+    const access = subject === undefined ? undefined : this.as(subject, ctx.services);
+    ctx.state.set(SUBJECT_STATE, access);
+    return access;
+  }
+}
+
+/** What one subject may do; grants are asked once per permission. */
+export class SubjectAccess {
+  private readonly grantCache = new Map<string, Promise<Grants>>();
+  private owners: Promise<readonly string[]> | undefined;
+
+  constructor(
+    readonly subject: AccessSubject,
+    private readonly policy: AccessPolicy,
+    private readonly catalog: IAccessCatalog,
+    private readonly maxInList: number,
+    private readonly scope: ServiceResolver,
+  ) {}
+
+  /** The grants of the permission; a grant the permission cannot use is dropped with a warning. */
+  grants(permission: string): Promise<Grants> {
+    let grants = this.grantCache.get(permission);
+    if (grants === undefined) {
+      grants = this.load(permission);
+      this.grantCache.set(permission, grants);
+    }
+    return grants;
+  }
+
+  /**
+   * Whether the subject may do `permission` on `object`. Without an object —
+   * whether it has the permission anywhere (a route before the object is known).
+   */
+  async can(permission: string, object?: AccessObject): Promise<boolean> {
+    const spec = this.catalog.require(permission).spec;
+    const grants = await this.grants(permission);
+    if (grants === "all") return true;
+    if (object === undefined) return grants.length > 0;
+    return (await this.matching(permission, spec, grants, object)).length > 0;
+  }
+
+  /** Which rows of a list the subject may see; `scope` — the partition of the request for `scope: "request"`. */
+  async filter(permission: string, options: { readonly scope?: Scope } = {}): Promise<AccessFilter> {
+    const spec = this.catalog.require(permission).spec;
+    const grants = await this.grants(permission);
+    return await buildFilter({
+      permission,
+      spec,
+      grants,
+      ownerIds: grants === "all" || !usesOwn(grants) ? [] : await this.ownerIds(),
+      requestScope: options.scope,
+      maxInList: this.maxInList,
+      lookup: (type: Class<AttributeLookup>) => this.scope.resolve(type),
+    });
+  }
+
+  /** The fields of `object` the subject may read and write (ACCESS-001 §4.4). */
+  async fields(permission: string, object: AccessObject): Promise<FieldAccess> {
+    const spec = this.catalog.require(permission).spec;
+    const grants = await this.grants(permission);
+    if (grants === "all") return { read: "all", write: "all" };
+    const matching = await this.matching(permission, spec, grants, object);
+    return { read: union(matching, "read"), write: union(matching, "write") };
+  }
+
+  /** Whom the subject is in each partition, for tasks. */
+  principals(scopes: readonly Scope[]): Promise<readonly ScopePrincipals[]> {
+    return this.policy.principals(this.subject, scopes);
+  }
+
+  /** The owner column values that mean this subject. */
+  ownerIds(): Promise<readonly string[]> {
+    this.owners ??= Promise.resolve(this.policy.ownerIds(this.subject));
+    return this.owners;
+  }
+
+  private async load(permission: string): Promise<Grants> {
+    const spec = this.catalog.require(permission).spec;
+    const grants = await this.policy.grants(this.subject, permission);
+    if (grants === "all") return "all";
+    if (!Array.isArray(grants)) {
+      this.warn(permission, "the rights system must answer \"all\" or a list of grants");
+      return [];
+    }
+    return grants.filter((grant) => {
+      const problem = grantProblem(spec, grant, this.maxInList);
+      if (problem !== undefined) this.warn(permission, problem);
+      return problem === undefined;
+    });
+  }
+
+  private async matching(permission: string, spec: PermissionSpec, grants: readonly Grant[], object: AccessObject): Promise<Grant[]> {
+    const scopes = objectScopes(permission, spec, object);
+    const owners = usesOwn(grants) ? await this.ownerIds() : [];
+    return grants.filter((grant) => {
+      if (grant.scopes !== "all" && !scopes.some((scope) => (grant.scopes as readonly Scope[]).includes(scope))) return false;
+      return grant.where === undefined || evaluate(grant.where, object, spec, owners) === true;
+    });
+  }
+
+  private warn(permission: string, problem: string): void {
+    this.scope.tryResolve(LOGGER)?.warn("access grant dropped", { permission, subject: this.subject.sub, problem });
+  }
+}
+
+function objectScopes(permission: string, spec: PermissionSpec, object: AccessObject): readonly Scope[] {
+  if ((spec.scope ?? "none") === "none") return [null];
+  const scope = object.scope;
+  if (scope === undefined) throw new TypeError(`can("${permission}") needs the object's partition: pass { scope }.`);
+  return Array.isArray(scope) ? scope : [scope as Scope];
+}
+
+function usesOwn(grants: readonly Grant[]): boolean {
+  return grants.some((grant) => grant.where !== undefined && hasOwn(grant.where));
+}
+
+function hasOwn(condition: Condition): boolean {
+  if ("own" in condition) return condition.own === true;
+  if ("not" in condition && typeof condition.not === "object" && condition.not !== null) return hasOwn(condition.not as Condition);
+  const list = "all" in condition ? condition.all : "any" in condition ? condition.any : undefined;
+  return Array.isArray(list) && (list as readonly Condition[]).some(hasOwn);
+}
+
+function union(grants: readonly Grant[], side: "read" | "write"): "all" | readonly string[] {
+  const fields = new Set<string>();
+  for (const grant of grants) {
+    const list = grant.fields?.[side];
+    if (list === undefined || list === "all") return "all";
+    for (const field of list) fields.add(field);
+  }
+  return [...fields];
+}
+
+/** The record with only the fields of `read`. */
+export function maskFields<T extends Record<string, unknown>>(record: T, read: "all" | readonly string[]): Partial<T> {
+  if (read === "all") return record;
+  const allowed = new Set(read);
+  return Object.fromEntries(Object.entries(record).filter(([field]) => allowed.has(field))) as Partial<T>;
+}

package/core/access/check/IAccess.service.ts

@@ -0,0 +1,20 @@
+import type { ServiceResolver } from "../../di";
+import type { AuthorizeContext } from "../../http";
+import type { AccessPolicy } from "../contracts/AccessPolicy";
+import type { AccessSubject } from "../contracts/types";
+import type { SubjectAccess } from "./Access";
+
+/**
+ * Checks of access (ACCESS-001 §5): `for(ctx)` — the subject of a request,
+ * `as(subject, scope)` — without HTTP (services, agents, background work).
+ */
+export abstract class IAccess {
+  /** The application's rights system in this scope. */
+  abstract policy(scope: ServiceResolver): AccessPolicy;
+  /** Who makes the request, or `undefined`. */
+  abstract subject(ctx: AuthorizeContext): Promise<AccessSubject | undefined>;
+  /** Access of the request's subject; without one — 401. */
+  abstract for(ctx: AuthorizeContext): Promise<SubjectAccess>;
+  /** Access of a known subject; `scope` — where to resolve the policy and the lookups. */
+  abstract as(subject: AccessSubject, scope: ServiceResolver): SubjectAccess;
+}

package/core/access/check/accessConfig.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "../../kernel";
+
+/** Settings of access (ACCESS-001), `access.*` in the configuration. */
+export interface AccessConfig {
+  /** The claim with the account kind: `sub` becomes `<kind>:<subject>`; empty — no kind. */
+  kindClaim: string;
+  /** The claim with the roles of the default rights system, separated by spaces or commas. */
+  roleClaim: string;
+  /** Values of one list condition and of a lookup result. */
+  maxInList: number;
+}
+
+export const accessConfig = defineConfig<AccessConfig>("access", {
+  default: { kindClaim: "", roleClaim: "role", maxInList: 1000 },
+  validate: {
+    maxInList: (value) => Number.isSafeInteger(value) && value >= 1 && value <= 100_000 ? undefined : "must be an integer 1–100000",
+  },
+});

package/core/access/check/can.ts

@@ -0,0 +1,21 @@
+import type { AuthorizeCheck, AuthorizeContext } from "../../http";
+import type { AccessObject } from "../contracts/types";
+import { IAccess } from "./IAccess.service";
+
+/**
+ * A route check by a permission (ACCESS-001 §5): 401 without a subject, 403
+ * without the right. `objectOf` gives the object from the request; without it
+ * the route needs the permission anywhere, and the handler checks the object
+ * once it has loaded it.
+ *
+ * ```ts
+ * @Authorize(can("orders.create", (ctx) => ({ scope: ctx.header("x-shop") ?? null })))
+ * @Post() create(ctx: HttpContext) { … }
+ * ```
+ */
+export function can(permission: string, objectOf?: (ctx: AuthorizeContext) => AccessObject | Promise<AccessObject>): AuthorizeCheck {
+  return async (ctx) => {
+    const access = await ctx.services.resolve(IAccess).for(ctx);
+    return await access.can(permission, objectOf === undefined ? undefined : await objectOf(ctx));
+  };
+}