bazis 0.139.0 → 0.140.1

package/core/access/Access.module.ts

@@ -2,6 +2,8 @@ import { Module, singleton } from "../di";
 import { AccessCatalog } from "./catalog/AccessCatalog";
 import { IAccessCatalog } from "./catalog/IAccessCatalog.service";
 import { definePermissions } from "./catalog/permissions";
+import { PermissionSourceLoader } from "./catalog/PermissionSourceLoader.background";
+import { PermissionSourcesService } from "./catalog/PermissionSources.service";
 import { Access } from "./check/Access";
 import { accessConfig } from "./check/accessConfig";
 import { IAccess } from "./check/IAccess.service";
@@ -20,17 +22,20 @@ export const accessPermissions = definePermissions({
  * 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`.
+ * rights system by registering its own `AccessPolicy`. Permissions that appear
+ * while the application runs come from `@Module({ permissionSources })`.
  */
 @Module({
   config: [accessConfig],
   permissions: accessPermissions,
   providers: [
+    singleton(PermissionSourcesService),
     singleton(IAccessCatalog, AccessCatalog),
     singleton(AccessPolicy, RolesAccessPolicy),
     singleton(IAccess, Access),
   ],
   controllers: [AccessCatalogController],
+  background: [PermissionSourceLoader],
   exports: [IAccessCatalog, IAccess, AccessPolicy],
 })
 export class AccessModule {}

package/core/access/catalog/AccessCatalog.ts

@@ -1,16 +1,23 @@
 import type { Class } from "../../di";
 import type { ServiceProvider } from "../../di/ServiceProvider";
+import type { ConfigView } from "../../kernel";
+import type { AccessConfig } from "../check/accessConfig";
+import { grantProblem } from "../check/conditions";
 import type { References } from "../contracts/References";
+import type { Grant } from "../contracts/types";
 import type { RolePermission } from "../roles/roles";
 import { IAccessCatalog } from "./IAccessCatalog.service";
 import { declarationsOf } from "./moduleFields";
 import type { PermissionSpec } from "./permissions";
+import type { PermissionSourcesService, PermissionSourceState } from "./PermissionSources.service";
 
-/** A permission of `@Module({ permissions })` with the module that declares it. */
+/** A permission with the module that declares it: in `@Module({ permissions })` or through a source. */
 export interface OwnedPermission {
   readonly key: string;
   readonly spec: PermissionSpec;
   readonly module: string;
+  /** The prefix of the source that gave the permission (ACCESS-001 §3.1); a declared one has none. */
+  readonly source?: string;
 }
 
 /** A reference kind of `@Module({ references })`. */
@@ -27,13 +34,16 @@ export interface DeclaredRole {
   readonly module: string;
 }
 
-/** The catalog read from the container's module contributions. */
+/** The catalog: the container's module contributions and the permissions of the sources. */
 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) {
+  /** The declared permissions and the ones of the sources as one sorted list, good for one revision of the sources. */
+  private merged: { readonly revision: number; readonly list: readonly OwnedPermission[] } | undefined;
+
+  constructor(services: ServiceProvider, private readonly sourced: PermissionSourcesService, private readonly config: ConfigView<AccessConfig>) {
     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]));
@@ -42,19 +52,64 @@ export class AccessCatalog extends IAccessCatalog {
   }
 
   permissions(): readonly OwnedPermission[] {
-    return [...this.byKey.values()];
+    const revision = this.sourced.revision;
+    if (this.merged?.revision !== revision) {
+      this.merged = { revision, list: [...this.byKey.values(), ...this.sourced.permissions()].sort((a, b) => a.key.localeCompare(b.key)) };
+    }
+    return [...this.merged.list];
   }
 
   permission(key: string): OwnedPermission | undefined {
-    return this.byKey.get(key);
+    return this.byKey.get(key) ?? this.sourced.permission(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.`);
+    const permission = this.permission(key);
+    if (permission === undefined) throw this.unknown(key);
     return permission;
   }
 
+  async find(key: string, options: { readonly verify?: boolean } = {}): Promise<OwnedPermission | undefined> {
+    const declared = this.byKey.get(key);
+    if (declared !== undefined) return declared;
+    if (this.sourced.prefixOf(key) === undefined) throw this.unknown(key);
+    const permission = this.sourced.permission(key);
+    if (permission !== undefined && options.verify !== true) return permission;
+    // A table another instance has just created, or a field it has just added, must not wait for the poll.
+    await this.sourced.verify(key);
+    return this.sourced.permission(key);
+  }
+
+  async grantProblem(permission: string, grant: Grant): Promise<string | undefined> {
+    const maxInList = this.config.get("maxInList");
+    const declared = this.byKey.get(permission);
+    if (declared !== undefined) return grantProblem(declared.spec, grant, maxInList);
+    if (this.sourced.prefixOf(permission) === undefined) return `permission "${permission}" is not declared`;
+    const problemNow = (): string | undefined => {
+      const found = this.sourced.permission(permission);
+      return found === undefined ? `permission "${permission}" does not exist` : grantProblem(found.spec, grant, maxInList);
+    };
+    await this.sourced.verify(permission);
+    const problem = problemNow();
+    // A rule is saved rarely, and a wrong refusal costs the administrator: ask the version once more, past the limit.
+    return problem !== undefined && await this.sourced.verify(permission, true) ? problemNow() : problem;
+  }
+
+  async changed(prefix: string, keys?: readonly string[]): Promise<void> {
+    await this.sourced.changed(prefix, keys);
+  }
+
+  sources(): readonly PermissionSourceState[] {
+    return this.sourced.state();
+  }
+
+  private unknown(key: string): TypeError {
+    const prefix = this.sourced.prefixOf(key);
+    return new TypeError(prefix === undefined
+      ? `Permission "${key}" is not declared: add it to definePermissions(...) of a module's permissions.`
+      : `Permission "${key}" does not exist: the permission source "${prefix}" does not give it now.`);
+  }
+
   referenceKinds(): readonly OwnedReferenceKind[] {
     return [...this.byKind.values()];
   }

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

@@ -1,15 +1,41 @@
+import type { Grant } from "../contracts/types";
 import type { DeclaredRole, OwnedPermission, OwnedReferenceKind } from "./AccessCatalog";
+import type { PermissionSourceState } from "./PermissionSources.service";
 
 /**
  * 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.
+ * kinds and default roles (ACCESS-001 §3, §6, §8), checked when the application
+ * is built, and the permissions of the sources (§3.1), read while it runs.
  */
 export abstract class IAccessCatalog {
+  /** The declared permissions and the ones the sources give now. */
   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;
+  /**
+   * The permission for a check. A key of a source that the source does not
+   * give now is `undefined` — nobody has it; before answering so the catalog
+   * compares the source's version (`verify` — even when the key is there: a
+   * grant named an attribute the catalog does not know). A key that is neither
+   * declared nor of a source is an error, like in {@link require}.
+   */
+  abstract find(key: string, options?: { readonly verify?: boolean }): Promise<OwnedPermission | undefined>;
+  /**
+   * Why the grant cannot be used for the permission now, or `undefined`: the
+   * checks a request runs (ACCESS-001 §4.2). A rights system calls it when it
+   * saves a rule and answers 422, instead of learning it from a warning in the
+   * log of a request.
+   */
+  abstract grantProblem(permission: string, grant: Grant): Promise<string | undefined>;
+  /**
+   * The data of the source of this prefix changed: read its permissions again
+   * now, all of them or only `keys`. Call it after the transaction is
+   * committed; other instances learn it from the source's version.
+   */
+  abstract changed(prefix: string, keys?: readonly string[]): Promise<void>;
+  /** The sources and what is known about them now. */
+  abstract sources(): readonly PermissionSourceState[];
   abstract referenceKinds(): readonly OwnedReferenceKind[];
   abstract referenceKind(kind: string): OwnedReferenceKind | undefined;
   abstract roles(): readonly DeclaredRole[];

package/core/access/catalog/PermissionSourceLoader.background.ts

@@ -0,0 +1,49 @@
+import type { HostedService, HostedServiceHealth } from "../../di";
+import type { PermissionSourcesService } from "./PermissionSources.service";
+
+/** After the infrastructure and the schema (phases below), before the HTTP host (phase 10). */
+const PHASE = 5;
+/** How often a failed source is tried again when the versions are not polled. */
+const RETRY_SECONDS = 5;
+/** A failure or two is a database that blinked; `/health` reports a source that keeps failing. */
+const UNHEALTHY_AFTER = 3;
+
+/**
+ * Reads the permission sources before the application takes requests and
+ * then asks their versions every `access.sourcePollSeconds` (ACCESS-001 §3.1).
+ * A source that fails does not stop the start: its permissions do not exist
+ * until a later reading succeeds, and `/health` says so. Without a poll
+ * (`sourcePollSeconds: 0`) only the sources that failed are tried again.
+ */
+export class PermissionSourceLoader implements HostedService {
+  readonly phase = PHASE;
+  readonly diagnosticName = "access:permission-sources";
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private polling: Promise<void> | undefined;
+
+  constructor(private readonly sources: PermissionSourcesService) {}
+
+  async start(): Promise<void> {
+    if (this.sources.count === 0) return;
+    await this.sources.load();
+    const poll = this.sources.pollSeconds;
+    this.timer = setInterval(() => {
+      // One question at a time: a slow source is not asked again before it answers.
+      this.polling ??= (poll > 0 ? this.sources.poll() : this.sources.retry()).catch(() => undefined).finally(() => { this.polling = undefined; });
+    }, (poll > 0 ? poll : RETRY_SECONDS) * 1000);
+    this.timer.unref?.();
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer !== undefined) clearInterval(this.timer);
+    this.timer = undefined;
+    await this.polling;
+  }
+
+  /** Unhealthy: a source without permissions at all, or one whose readings keep failing. */
+  checkHealth(): HostedServiceHealth {
+    const failed = this.sources.state().filter((source) => !source.loaded || source.failures >= UNHEALTHY_AFTER);
+    if (failed.length === 0) return { healthy: true };
+    return { healthy: false, details: failed.map((source) => `permission source "${source.prefix}": ${source.loaded ? "" : "not loaded: "}${source.error ?? "no reading yet"}`).join("; ") };
+  }
+}

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

@@ -0,0 +1,292 @@
+import type { Class, ServiceProvider } from "../../di";
+import { LOGGER, type ConfigView } from "../../kernel";
+import type { AccessConfig } from "../check/accessConfig";
+import type { PermissionSource } from "../contracts/PermissionSource";
+import type { OwnedPermission } from "./AccessCatalog";
+import { declarationsOf } from "./moduleFields";
+import { frozenSpec, lookupsOf, permissionProblems, underPrefix, type PermissionSpec } from "./permissions";
+
+/** A source of `@Module({ permissionSources })` with the module that declares it. */
+export interface OwnedPermissionSource {
+  readonly prefix: string;
+  readonly type: Class<PermissionSource>;
+  readonly module: string;
+}
+
+/** What is known about a source now: for `/health` and the administrator. */
+export interface PermissionSourceState {
+  readonly prefix: string;
+  readonly module: string;
+  /** Whether its permissions have been read at least once. */
+  readonly loaded: boolean;
+  /** The version of the data the permissions were read at. */
+  readonly version: string | undefined;
+  /** Why the last reading failed; the permissions read before it stay. */
+  readonly error: string | undefined;
+  /** Readings and version questions that failed in a row; `0` after a success. */
+  readonly failures: number;
+  readonly permissions: number;
+}
+
+interface Source extends OwnedPermissionSource {
+  permissions: ReadonlyMap<string, OwnedPermission>;
+  loaded: boolean;
+  version: string | undefined;
+  error: string | undefined;
+  failures: number;
+  /** When the version was last compared, for the limit of {@link PermissionSourcesService.verify}. */
+  verifiedAt: number;
+  /** Readings of one source go one after another. */
+  queue: Promise<unknown>;
+  /** A call that ran out of time and has not answered yet: no new call starts beside it. */
+  unanswered: Promise<void> | undefined;
+}
+
+/** How often a missing key or attribute may ask a source for its version. */
+const VERIFY_EVERY_MS = 1000;
+
+/**
+ * The permissions of the application's sources (ACCESS-001 §3.1): read before
+ * the application takes requests, read again when a source's version changes.
+ * A specification passes the checks of a declared one; a bad one is logged and
+ * the permission does not exist — closed, never open. A reading that fails
+ * leaves the permissions read before it. A source that does not answer in
+ * `access.sourceTimeoutSeconds` has failed: it holds neither the start nor a
+ * request.
+ */
+export class PermissionSourcesService {
+  private readonly sources: readonly Source[];
+  private readonly kinds: ReadonlySet<string>;
+  private changes = 0;
+
+  constructor(private readonly services: ServiceProvider, private readonly config: ConfigView<AccessConfig>) {
+    const { sources, kinds } = declarationsOf(services);
+    this.kinds = new Set(kinds.map((kind) => kind.kind));
+    this.sources = [...sources]
+      .sort((left, right) => left.prefix.localeCompare(right.prefix))
+      .map((source) => ({ ...source, permissions: new Map(), loaded: false, version: undefined, error: undefined, failures: 0, verifiedAt: 0, queue: Promise.resolve(), unanswered: undefined }));
+  }
+
+  /** The prefix of the source that owns the key, or `undefined` — the key is not of a source. */
+  prefixOf(key: string): string | undefined {
+    return this.sources.find((source) => underPrefix(key, source.prefix))?.prefix;
+  }
+
+  permission(key: string): OwnedPermission | undefined {
+    for (const source of this.sources) if (underPrefix(key, source.prefix)) return source.permissions.get(key);
+    return undefined;
+  }
+
+  permissions(): OwnedPermission[] {
+    return this.sources.flatMap((source) => [...source.permissions.values()]);
+  }
+
+  state(): readonly PermissionSourceState[] {
+    return this.sources.map(({ prefix, module, loaded, version, error, failures, permissions }) => ({ prefix, module, loaded, version, error, failures, permissions: permissions.size }));
+  }
+
+  /** Grows with every reading that changed the permissions: a list built from them is good until it does. */
+  get revision(): number {
+    return this.changes;
+  }
+
+  get count(): number {
+    return this.sources.length;
+  }
+
+  /** The seconds between two questions about the versions; `0` — never ask. */
+  get pollSeconds(): number {
+    return this.sources.length === 0 ? 0 : this.config.get("sourcePollSeconds");
+  }
+
+  /** Reads every source: at start, before the application takes requests. */
+  async load(): Promise<void> {
+    await Promise.all(this.sources.map((source) => this.enqueue(source, () => this.read(source))));
+  }
+
+  /** Asks every source for its version and reads again the ones that changed or have not been read. */
+  async poll(): Promise<void> {
+    await Promise.all(this.sources.map((source) => this.enqueue(source, () => this.compare(source))));
+  }
+
+  /** Tries again the sources whose last reading failed: without a poll nothing else would. */
+  async retry(): Promise<void> {
+    await Promise.all(this.sources
+      .filter((source) => !source.loaded || source.error !== undefined)
+      .map((source) => this.enqueue(source, () => this.compare(source))));
+  }
+
+  /**
+   * The source of the prefix changed. With `keys` only these permissions are
+   * read now; the version stays the old one, so the next comparison reads the
+   * whole prefix — another instance may have changed other keys meanwhile.
+   */
+  async changed(prefix: string, keys?: readonly string[]): Promise<void> {
+    const source = this.sources.find((item) => item.prefix === prefix);
+    if (source === undefined) throw new TypeError(`No permission source owns the prefix "${prefix}": name it in permissionSources of a module.`);
+    await this.enqueue(source, () => (keys === undefined || !source.loaded ? this.read(source) : this.readKeys(source, keys)));
+  }
+
+  /**
+   * Compares the version of the key's source before the catalog answers "no
+   * such permission" or drops a grant: a table another instance has just
+   * created must not wait for the poll. Not more often than once a second for
+   * a prefix, unless `force`. `true` — the permissions were read again.
+   */
+  async verify(key: string, force = false): Promise<boolean> {
+    const source = this.sources.find((item) => underPrefix(key, item.prefix));
+    if (source === undefined) return false;
+    return await this.enqueue(source, async () => {
+      // A clock set back gives a negative time: compare then, do not wait for the clock to catch up.
+      const since = Date.now() - source.verifiedAt;
+      if (!force && since >= 0 && since < VERIFY_EVERY_MS) return false;
+      return await this.compare(source);
+    });
+  }
+
+  private enqueue<T>(source: Source, work: () => Promise<T>): Promise<T> {
+    const result = source.queue.then(work);
+    source.queue = result.catch(() => undefined);
+    return result;
+  }
+
+  /** `true` — the version differed (or nothing was read yet) and the permissions were read again. */
+  private async compare(source: Source): Promise<boolean> {
+    source.verifiedAt = Date.now();
+    if (source.loaded) {
+      try {
+        const version = await this.use(source, async (instance) => versionOf(await instance.version()));
+        if (version === source.version) {
+          source.error = undefined;
+          source.failures = 0;
+          return false;
+        }
+      } catch (error) {
+        this.failed(source, error);
+        return false;
+      }
+    }
+    return await this.read(source);
+  }
+
+  private async read(source: Source): Promise<boolean> {
+    source.verifiedAt = Date.now();
+    try {
+      // The version first: data changed during the reading gives a newer version to the next comparison.
+      const { version, declarations } = await this.use(source, async (instance) => ({ version: versionOf(await instance.version()), declarations: await instance.load() }));
+      if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) throw new TypeError("load() must return an object: key → permission");
+      const permissions = new Map<string, OwnedPermission>();
+      for (const key of Object.keys(declarations).sort()) {
+        const permission = this.accept(source, key, declarations[key]!);
+        if (permission !== undefined) permissions.set(key, permission);
+      }
+      source.permissions = permissions;
+      source.version = version;
+      source.loaded = true;
+      source.error = undefined;
+      source.failures = 0;
+      this.changes += 1;
+      return true;
+    } catch (error) {
+      this.failed(source, error);
+      return false;
+    }
+  }
+
+  private async readKeys(source: Source, keys: readonly string[]): Promise<boolean> {
+    try {
+      const declarations = await this.use(source, async (instance) => await instance.load(keys));
+      if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) throw new TypeError("load(keys) must return an object: key → permission");
+      const permissions = new Map(source.permissions);
+      for (const key of keys) {
+        const spec = Object.hasOwn(declarations, key) ? declarations[key] : undefined;
+        const permission = spec === undefined ? undefined : this.accept(source, key, spec);
+        if (permission === undefined) permissions.delete(key);
+        else permissions.set(key, permission);
+      }
+      source.permissions = new Map([...permissions].sort(([left], [right]) => left.localeCompare(right)));
+      source.error = undefined;
+      source.failures = 0;
+      this.changes += 1;
+      return true;
+    } catch (error) {
+      this.failed(source, error);
+      return false;
+    }
+  }
+
+  /** The permission, or `undefined` with the problems logged: it does not exist then. */
+  private accept(source: Source, key: string, spec: PermissionSpec): OwnedPermission | undefined {
+    let problems: string[];
+    let accepted: OwnedPermission | undefined;
+    try {
+      problems = underPrefix(key, source.prefix) ? permissionProblems(key, spec) : [`permission "${key}": the key must start with "${source.prefix}."`];
+      if (problems.length === 0) {
+        for (const [name, attribute] of Object.entries(spec.on ?? {})) {
+          if (attribute.ref !== undefined && !this.kinds.has(attribute.ref)) problems.push(`permission "${key}": attribute "${name}" refers to kind "${attribute.ref}", which no module declares in references`);
+        }
+        for (const lookup of lookupsOf(spec)) {
+          if (!this.services.has(lookup)) problems.push(`permission "${key}": ${lookup.name} is not registered: add it to providers of ${source.module}`);
+        }
+      }
+      if (problems.length === 0) accepted = { key, spec: frozenSpec(spec), module: source.module, source: source.prefix };
+    } catch (error) {
+      // Data of any shape may come from a source: what cannot even be checked is one bad permission, not a failed reading.
+      problems = [`permission "${key}": cannot be checked: ${error instanceof Error ? error.message : String(error)}`];
+    }
+    if (accepted === undefined) this.services.tryResolve(LOGGER)?.error("access permission of a source rejected", { source: source.prefix, module: source.module, permission: key, problems });
+    return accepted;
+  }
+
+  /**
+   * One call of the source in a scope of its own, with a deadline. A call that
+   * ran out of time cannot be stopped: its scope is closed when it answers, and
+   * until then no new call starts, so a database that hangs is asked once.
+   */
+  private async use<T>(source: Source, work: (instance: PermissionSource) => Promise<T>): Promise<T> {
+    if (source.unanswered !== undefined) throw new Error("the previous call of the source has not answered yet");
+    const seconds = this.config.get("sourceTimeoutSeconds");
+    const scope = this.services.createScope();
+    const working = (async () => await work(scope.resolve(source.type)))();
+    const answered = working.then(() => undefined, () => undefined).then(async () => {
+      source.unanswered = undefined;
+      await scope.dispose().catch(() => undefined);
+    });
+    let late = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        late = true;
+        source.unanswered = answered;
+        reject(new Error(`the source did not answer in ${seconds} s (access.sourceTimeoutSeconds)`));
+      }, seconds * 1000);
+    });
+    try {
+      return await Promise.race([working, deadline]);
+    } finally {
+      clearTimeout(timer);
+      if (!late) await answered;
+    }
+  }
+
+  private failed(source: Source, error: unknown): void {
+    source.error = error instanceof Error ? error.message : String(error);
+    source.failures += 1;
+    this.services.tryResolve(LOGGER)?.error("access permission source failed", {
+      source: source.prefix,
+      module: source.module,
+      error: source.error,
+      state: source.loaded ? "the permissions read before stay" : "the source has no permissions",
+    });
+  }
+}
+
+/**
+ * A version is what the catalog compares to learn of a change: `undefined`,
+ * `null` or an empty string would look like a version that never changes.
+ */
+function versionOf(value: unknown): string {
+  if (typeof value === "string" && value !== "") return value;
+  if ((typeof value === "number" && Number.isFinite(value)) || typeof value === "bigint") return String(value);
+  throw new TypeError(`version() must return a non-empty string or a number, got ${value === null ? "null" : typeof value === "string" ? "an empty string" : typeof value}`);
+}

package/core/access/catalog/moduleFields.ts

@@ -11,19 +11,25 @@ import {
 } from "../../di";
 import { grantProblem } from "../check/conditions";
 import { AccessSetupError } from "../contracts/errors";
+import type { PermissionSource } from "../contracts/PermissionSource";
 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";
+import { isDeclaredPermissions, isReferenceKind, isSourcePrefix, lookupsOf, permissionProblems, underPrefix, type PermissionDeclarations, type PermissionSpec } from "./permissions";
+import type { OwnedPermissionSource } from "./PermissionSources.service";
 
 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[] }
+interface SourcePayload { readonly prefix: string; readonly type: Class<PermissionSource> }
 
 const PERMISSION_CHANNEL = createModuleOwnedMetadataChannel<PermissionPayload>("access.permission/v1");
 const REFERENCE_CHANNEL = createModuleOwnedMetadataChannel<ReferencePayload>("access.reference/v1");
 const ROLE_CHANNEL = createModuleOwnedMetadataChannel<RolePayload>("access.role/v1");
+const SOURCE_CHANNEL = createModuleOwnedMetadataChannel<SourcePayload>("access.permission-source/v1");
+/** The classes of `permissionSources`: the field registers them, like the classes of `references`. */
+const SOURCE_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly prefix: string }, object>("access.permission-source-class/v1");
 /** The classes of `references`: the field registers them, like `tools` and `controllers`. */
 const REFERENCE_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly kind: string }, object>("access.reference-class/v1");
 /** The `lookup` classes of `permissions`: the field registers them too. */
@@ -38,11 +44,12 @@ interface AccessModuleFields {
   readonly permissions?: unknown;
   readonly references?: unknown;
   readonly roles?: unknown;
+  readonly permissionSources?: unknown;
 }
 
 registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context) => {
   const fields = metadata as BazisModuleMetadata & AccessModuleFields;
-  if (fields.permissions === undefined && fields.references === undefined && fields.roles === undefined) return;
+  if (fields.permissions === undefined && fields.references === undefined && fields.roles === undefined && fields.permissionSources === undefined) return;
   const module = moduleName(metadata);
   if (fields.permissions !== undefined) {
     if (!isDeclaredPermissions(fields.permissions)) throw new AccessSetupError(`${module}: permissions must be a definePermissions(...) result.`);
@@ -84,6 +91,27 @@ registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context)
       }
     }
   }
+  if (fields.permissionSources !== undefined) {
+    const sources = fields.permissionSources;
+    if (typeof sources !== "object" || sources === null || Array.isArray(sources)) throw new AccessSetupError(`${module}: permissionSources must map a key prefix to a PermissionSource class.`);
+    const problems: string[] = [];
+    for (const [prefix, type] of Object.entries(sources)) {
+      if (!isSourcePrefix(prefix)) problems.push(`prefix "${prefix}" must be one or several key segments in lower case, like "data" or "dm.records"`);
+      if (typeof type !== "function") problems.push(`prefix "${prefix}" must name a PermissionSource class`);
+    }
+    if (problems.length > 0) throw setupError(module, "permissionSources", problems);
+    const registered = new Set<unknown>();
+    for (const [prefix, type] of Object.entries(sources)) {
+      context.addMetadata(SOURCE_CHANNEL, { prefix, type: type as Class<PermissionSource> });
+      if (registered.has(type)) continue;
+      registered.add(type);
+      try {
+        context.registerScoped(SOURCE_CLASS_CHANNEL, scoped(type as Class<object>), { prefix });
+      } catch {
+        // The module registered the class its own way: that registration stands.
+      }
+    }
+  }
   if (fields.roles !== undefined) {
     if (!isDeclaredRoles(fields.roles)) throw new AccessSetupError(`${module}: roles must be a defineRoles(...) result.`);
     const problems: string[] = [];
@@ -102,10 +130,11 @@ 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];
+  const sources = snapshot.getMetadataContributions(SOURCE_CHANNEL);
+  const first = permissions[0] ?? references[0] ?? roles[0] ?? sources[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).`);
+    throw new AccessSetupError(`${first.ownerName} declares access (permissions, references, roles or permission sources), but the application does not import AccessModule (bazis/core/access).`);
   }
 
   const owners = new Map<string, string>();
@@ -117,6 +146,24 @@ registerModuleOwnedContributionValidator((snapshot) => {
     specs.set(payload.key, payload.spec);
   }
 
+  // A source owns every key under its prefix: no declared key and no other source may be there.
+  const prefixes = new Map<string, string>();
+  for (const { payload, ownerName } of sources) {
+    for (const [other, otherOwner] of prefixes) {
+      if (other === payload.prefix) throw new AccessSetupError(`Permission source prefix "${payload.prefix}" is declared twice: in ${otherOwner} and in ${ownerName}.`);
+      if (underPrefix(other, payload.prefix) || underPrefix(payload.prefix, other)) {
+        throw new AccessSetupError(`Permission source prefixes "${other}" (${otherOwner}) and "${payload.prefix}" (${ownerName}) overlap: one lies under the other.`);
+      }
+    }
+    prefixes.set(payload.prefix, ownerName);
+    if (snapshot.countProviders(payload.type) === 0) throw new AccessSetupError(`${ownerName}: ${payload.type.name} of permission source "${payload.prefix}" is not registered.`);
+    for (const [key, keyOwner] of owners) {
+      if (key === payload.prefix || underPrefix(key, payload.prefix)) {
+        throw new AccessSetupError(`Permission "${key}" of ${keyOwner} lies under the prefix "${payload.prefix}" of a permission source of ${ownerName}: a source owns every key of its prefix.`);
+      }
+    }
+  }
+
   const kinds = new Map<string, string>();
   for (const { payload, ownerName } of references) {
     const other = kinds.get(payload.kind);
@@ -160,12 +207,13 @@ function importsExport(metadata: BazisModuleMetadata, type: unknown): boolean {
 }
 
 /** What the modules of the application's container declared. */
-export function declarationsOf(services: ServiceProvider): { permissions: OwnedPermission[]; kinds: OwnedReferenceKind[]; roles: DeclaredRole[] } {
+export function declarationsOf(services: ServiceProvider): { permissions: OwnedPermission[]; kinds: OwnedReferenceKind[]; roles: DeclaredRole[]; sources: OwnedPermissionSource[] } {
   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 };
+  const sources: OwnedPermissionSource[] = services.getModuleOwnedMetadataContributions(SOURCE_CHANNEL).map(({ payload, ownerName }) => ({ ...payload, module: ownerName }));
+  return { permissions, kinds, roles, sources };
 }
 
 function setupError(module: string, field: string, problems: readonly string[]): AccessSetupError {
@@ -186,5 +234,11 @@ declare module "../../di/module/types/BazisModule" {
     readonly references?: Readonly<Record<string, Class<References>>>;
     /** Roles of the default rights system, from `defineRoles` (ACCESS-001 §8). */
     readonly roles?: RoleDeclarations;
+    /**
+     * Permissions that appear while the application runs (ACCESS-001 §3.1):
+     * key prefix → its `PermissionSource` class. The field registers the class;
+     * the source owns every key under the prefix.
+     */
+    readonly permissionSources?: Readonly<Record<string, Class<PermissionSource>>>;
   }
 }