feat: integrate module authorization

Wires composePlatformPermissionRegistry into apps/api's production
startup: startApi() discovers every installed module, composes the one
immutable platform permission registry (Core's own declarations plus
every module's), and only then constructs the shared PostgreSQL pool,
Better Auth, and the HTTP server. A discovery or composition failure —
an invalid manifest, a reserved core.* namespace claim, or a duplicate
declaration — propagates before anything exists to close; there is no
Core-only registry fallback. apps/api/src/platform-permissions.ts
resolves the repository root from its own file location, never
process.cwd(), so package-scoped test runs discover the right modules/
directory.

createApiApp/createGrantsRoutes now require the composed registry as
an injected authorization option, replacing the previous hard-coded
CORE_PERMISSION_REGISTRY; requirePermission continues to work
identically for Core-owned and module-owned permissions, since it has
no concept of the distinction.

Extends pnpm doctor with a modules.permissions check (reusing the
already-discovered module list, distinguishing reserved-namespace from
generic-duplicate failures, never re-discovering modules) and pnpm
modules:validate to compose the same registry before a module is
considered installable.

Adds focused coverage: startup-ordering and failure-isolation tests in
apps/api/tests/lifecycle.test.ts, module-owned-declaration enforcement
tests in apps/api/tests/authorization-middleware.test.ts, Doctor
composition tests in core/tests/doctor.test.ts, and a live PostgreSQL
end-to-end scenario proving a real installed module's permission is
discoverable, grantable, and deniable once the module is absent again
after a restart, without ever executing its server entrypoint.

core/src/cli/validate-modules.ts

@@ -1,8 +1,11 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { PermissionRegistryError } from "../authorization/index.js";
 import {
+  composePlatformPermissionRegistry,
   discoverModuleSchemas,
   ModuleDiscoveryError,
+  ModulePermissionCompositionError,
   ModuleSchemaDiscoveryError,
 } from "../modules/index.js";
 
@@ -31,6 +34,12 @@ async function main(): Promise<void> {
   });
   const modules = schemaAggregate.discoveredModules;
 
+  // Reuses the modules discoverModuleSchemas already discovered — never rediscovers modules
+  // solely for permission composition. A manifest that passes structural validation but claims
+  // the reserved core.* namespace, or duplicates another declaration, fails validation here
+  // before this module is considered installable.
+  composePlatformPermissionRegistry(modules);
+
   if (modules.length === 0) {
     console.log("Module validation passed (0 modules installed).");
     return;
@@ -57,6 +66,10 @@ main().catch((error: unknown) => {
       const issuePath = issue.path ? ` (${issue.path})` : "";
       console.error(`[${issue.code}] ${issue.moduleId}${issuePath}: ${issue.message}`);
     }
+  } else if (error instanceof ModulePermissionCompositionError) {
+    console.error(`[${error.code}] ${error.message}`);
+  } else if (error instanceof PermissionRegistryError) {
+    console.error(`[${error.code}] ${error.message}`);
   } else {
     console.error(error instanceof Error ? error.message : String(error));
   }

core/src/diagnostics/doctor-report.ts

@@ -11,7 +11,7 @@ function section(title: string, checkIds: readonly DoctorCheckId[]): DoctorSecti
 
 const sections: readonly DoctorSection[] = Object.freeze([
   section("Platform", ["platform.runtime"]),
-  section("Modules", ["modules.discovery", "modules.dependencies"]),
+  section("Modules", ["modules.discovery", "modules.dependencies", "modules.permissions"]),
   section("Data definitions", ["schemas.discovery", "migrations.discovery"]),
   section("PostgreSQL", ["postgresql.connection", "postgresql.plan"]),
   section("Identity", ["identity.configuration"]),

core/src/diagnostics/doctor.ts

@@ -1,6 +1,12 @@
 import path from "node:path";
-import { isVersionCompatible, moduleIdSchema, semanticVersionSchema } from "@ekklesia/contracts";
+import {
+  isVersionCompatible,
+  moduleIdSchema,
+  permissionIdSchema,
+  semanticVersionSchema,
+} from "@ekklesia/contracts";
 import { getTableName } from "drizzle-orm";
+import { type PermissionRegistry, PermissionRegistryError } from "../authorization/index.js";
 import {
   type CreateIdentityConfigOptions,
   createIdentityConfig,
@@ -18,9 +24,11 @@ import {
   planModuleMigrations,
 } from "../migrations/index.js";
 import {
+  composePlatformPermissionRegistry,
   type DiscoveredModule,
   discoverModuleSchemas,
   discoverModules,
+  ModulePermissionCompositionError,
   type ModuleDiscoveryOptions,
   type ModuleMigrationAggregate,
   type ModuleSchemaAggregate,
@@ -30,6 +38,7 @@ export type DoctorCheckId =
   | "platform.runtime"
   | "modules.discovery"
   | "modules.dependencies"
+  | "modules.permissions"
   | "schemas.discovery"
   | "migrations.discovery"
   | "postgresql.connection"
@@ -68,6 +77,9 @@ export interface DoctorOptions {
 }
 
 export interface DoctorDependencies {
+  /** Synchronous, matching the real implementation: pure in-memory composition over an
+   * already-discovered module list, never re-discovering modules itself. */
+  readonly composePermissions: (modules: readonly DiscoveredModule[]) => PermissionRegistry;
   readonly createMigrationDatabase: (
     connectionString: string,
     options: PostgresMigrationDatabaseOptions,
@@ -101,6 +113,7 @@ async function discoverAllMigrationsForRuntime(
 }
 
 const productionDependencies: DoctorDependencies = Object.freeze({
+  composePermissions: composePlatformPermissionRegistry,
   createMigrationDatabase: createPostgresMigrationDatabase,
   discoverMigrations: discoverAllMigrationsForRuntime,
   discoverModules,
@@ -163,6 +176,57 @@ function safeMigrationReference(identity: string, checksum: string): string {
   return `${identity} · ${checksum.slice(0, 12)}`;
 }
 
+function safeModuleId(value: string): string {
+  if (!moduleIdSchema.safeParse(value).success) {
+    throw new TypeError("Unsafe module diagnostic value.");
+  }
+  return value;
+}
+
+function safePermissionId(value: string): string {
+  if (!permissionIdSchema.safeParse(value).success) {
+    throw new TypeError("Unsafe permission diagnostic value.");
+  }
+  return value;
+}
+
+/** Distinguishes the two composition-error families rather than describing a reserved `core.*`
+ * declaration as a generic duplicate. Never includes a module directory, manifest path, caught
+ * cause, or stack — only the module id and permission id the structured errors already carry,
+ * each re-validated before being interpolated (defense in depth against a future drift bug,
+ * matching `safeModuleDetails`/`safeMigrationReference` elsewhere in this file); if that
+ * re-validation itself fails, this falls back to a fixed generic detail rather than throwing. */
+function permissionCompositionFailure(error: unknown): DoctorCheck {
+  if (error instanceof ModulePermissionCompositionError) {
+    try {
+      const moduleId = safeModuleId(error.moduleId);
+      const permissionId = safePermissionId(error.permissionId);
+      return freezeCheck("modules.permissions", "failure", "Permission composition failed", [
+        `Module "${moduleId}" declared permission "${permissionId}" in the reserved core.* namespace.`,
+      ]);
+    } catch {
+      return freezeCheck("modules.permissions", "failure", "Permission composition failed", [
+        "A module declared a permission in the reserved core.* namespace.",
+      ]);
+    }
+  }
+  if (error instanceof PermissionRegistryError) {
+    try {
+      const permissionId = safePermissionId(error.permissionId);
+      return freezeCheck("modules.permissions", "failure", "Permission composition failed", [
+        `Permission "${permissionId}" is declared more than once.`,
+      ]);
+    } catch {
+      return freezeCheck("modules.permissions", "failure", "Permission composition failed", [
+        "A permission is declared more than once.",
+      ]);
+    }
+  }
+  return freezeCheck("modules.permissions", "failure", "Permission composition failed", [
+    "The installed permission declarations could not be composed safely.",
+  ]);
+}
+
 function moduleDiscoveryFailure(error: unknown): DoctorCheck {
   const details =
     error instanceof Error && error.name === "ModuleDiscoveryError"
@@ -386,6 +450,33 @@ export async function diagnoseEkklesia(
     ]);
   }
 
+  // Reuses the already-discovered module list above — never re-discovers modules solely for
+  // permission composition. Independent of the schema/migration checks below: a permission
+  // composition failure here (a reserved-namespace or duplicate declaration) does not skip those,
+  // since neither depends on the permission registry, only on discovery having succeeded.
+  let permissionsCheck: DoctorCheck;
+  if (!discoveredModules) {
+    permissionsCheck = freezeCheck(
+      "modules.permissions",
+      "skipped",
+      "Permission composition skipped",
+      ["Complete module discovery is required."],
+    );
+  } else {
+    try {
+      const registry = dependencies.composePermissions(discoveredModules);
+      const count = registry.declarations.length;
+      permissionsCheck = freezeCheck(
+        "modules.permissions",
+        "pass",
+        "Permission registry composed",
+        [`${count} ${plural(count, "permission")} registered`],
+      );
+    } catch (error) {
+      permissionsCheck = permissionCompositionFailure(error);
+    }
+  }
+
   let schemaCheck: DoctorCheck;
   let migrationCheck: DoctorCheck;
   let migrations: ModuleMigrationAggregate | undefined;
@@ -466,6 +557,7 @@ export async function diagnoseEkklesia(
     runtimeCheck,
     moduleCheck,
     dependencyCheck,
+    permissionsCheck,
     schemaCheck,
     migrationCheck,
     postgresConnectionCheck,

core/tests/doctor-report.test.ts

@@ -6,6 +6,7 @@ import {
 } from "../src/diagnostics/index.js";
 import type { MigrationDatabase } from "../src/migrations/index.js";
 import type { ModuleMigrationAggregate, ModuleSchemaAggregate } from "../src/modules/index.js";
+import { composePlatformPermissionRegistry } from "../src/modules/permissions.js";
 
 const originalNoColor = process.env.NO_COLOR;
 
@@ -36,6 +37,7 @@ function zeroMigrationAggregate(): ModuleMigrationAggregate {
 
 function noConfigurationDependencies(): DoctorDependencies {
   return {
+    composePermissions: composePlatformPermissionRegistry,
     createMigrationDatabase: () => {
       throw new Error("database must not be constructed");
     },
@@ -75,6 +77,8 @@ Modules
     0 modules installed
   ✓ Dependency graph valid
     Dependency order is empty.
+  ✓ Permission registry composed
+    1 permission registered
 
 Data definitions
   ✓ Schemas validated

core/tests/doctor.test.ts

@@ -1,5 +1,6 @@
-import type { ModuleManifest } from "@ekklesia/contracts";
+import { parsePermissionId, type ModuleManifest } from "@ekklesia/contracts";
 import { describe, expect, it, vi } from "vitest";
+import { createPermissionRegistry, PermissionRegistryError } from "../src/authorization/index.js";
 import {
   type DoctorCheck,
   type DoctorDependencies,
@@ -21,6 +22,7 @@ import type {
   ModuleMigrationAggregate,
   ModuleSchemaAggregate,
 } from "../src/modules/index.js";
+import { ModulePermissionCompositionError } from "../src/modules/permissions.js";
 
 const checksumA = "a".repeat(64);
 const checksumB = "b".repeat(64);
@@ -125,6 +127,11 @@ function plan(entries: MigrationPlanResult["entries"] = []): MigrationPlanResult
 
 function dependencies(overrides: Partial<DoctorDependencies> = {}): DoctorDependencies {
   return {
+    composePermissions: vi.fn((modules: readonly DiscoveredModule[]) =>
+      createPermissionRegistry(
+        modules.flatMap((discovered) => [...discovered.manifest.permissions]),
+      ),
+    ),
     createMigrationDatabase: vi.fn(() => emptyDatabase()),
     discoverMigrations: vi.fn(async () => migrationAggregate()),
     discoverModules: vi.fn(async () => Object.freeze([])),
@@ -196,6 +203,7 @@ describe("Ekklesia Doctor diagnostics", () => {
       "platform.runtime",
       "modules.discovery",
       "modules.dependencies",
+      "modules.permissions",
       "schemas.discovery",
       "migrations.discovery",
       "postgresql.connection",
@@ -205,6 +213,10 @@ describe("Ekklesia Doctor diagnostics", () => {
     ]);
     expect(check(report, "modules.discovery").details).toEqual(["people 0.1.0", "calendar 0.2.0"]);
     expect(check(report, "modules.dependencies").details).toEqual(["Order: people → calendar"]);
+    expect(check(report, "modules.permissions")).toMatchObject({
+      details: ["0 permissions registered"],
+      status: "pass",
+    });
     expect(check(report, "migrations.discovery").details).toEqual([
       "1 migration · checksums valid",
       "people:0000_initial · aaaaaaaaaaaa",
@@ -369,6 +381,7 @@ describe("Ekklesia Doctor diagnostics", () => {
     expect(check(report, "modules.discovery").status).toBe("failure");
     for (const id of [
       "modules.dependencies",
+      "modules.permissions",
       "schemas.discovery",
       "migrations.discovery",
       "postgresql.connection",
@@ -385,6 +398,114 @@ describe("Ekklesia Doctor diagnostics", () => {
     expect(JSON.stringify(report)).not.toContain("password");
   });
 
+  it("passes permission composition with a safe declaration count when modules are installed", async () => {
+    const calendar = discoveredModule("calendar");
+    const report = await diagnoseEkklesia(
+      options(),
+      dependencies({
+        composePermissions: vi.fn(() =>
+          createPermissionRegistry([
+            {
+              baseline: "restricted",
+              description: "Read calendar events.",
+              id: parsePermissionId("calendar.events.read"),
+            },
+          ]),
+        ),
+        discoverModules: vi.fn(async () => Object.freeze([calendar])),
+      }),
+    );
+
+    expect(check(report, "modules.permissions")).toMatchObject({
+      details: ["1 permission registered"],
+      status: "pass",
+    });
+  });
+
+  it("reuses the already-discovered module list rather than rediscovering modules for permission composition", async () => {
+    const calendar = discoveredModule("calendar");
+    const composePermissions = vi.fn(() => createPermissionRegistry([]));
+    const discoverModules = vi.fn(async () => Object.freeze([calendar]));
+    await diagnoseEkklesia(options(), dependencies({ composePermissions, discoverModules }));
+
+    expect(discoverModules).toHaveBeenCalledOnce();
+    expect(composePermissions).toHaveBeenCalledOnce();
+    expect(composePermissions).toHaveBeenCalledWith([calendar]);
+  });
+
+  it("fails permission composition when a module claims the reserved core.* namespace, distinctly from a generic duplicate", async () => {
+    const report = await diagnoseEkklesia(
+      options(),
+      dependencies({
+        composePermissions: vi.fn(() => {
+          throw new ModulePermissionCompositionError("core", "core.rogue.permission");
+        }),
+      }),
+    );
+
+    expect(check(report, "modules.permissions")).toMatchObject({
+      details: [
+        'Module "core" declared permission "core.rogue.permission" in the reserved core.* namespace.',
+      ],
+      status: "failure",
+    });
+    expect(report.result).toBe("not-ready");
+  });
+
+  it("fails permission composition on a generic duplicate declaration, distinctly from a reserved-namespace violation", async () => {
+    const report = await diagnoseEkklesia(
+      options(),
+      dependencies({
+        composePermissions: vi.fn(() => {
+          throw new PermissionRegistryError("calendar.events.read");
+        }),
+      }),
+    );
+
+    expect(check(report, "modules.permissions")).toMatchObject({
+      details: ['Permission "calendar.events.read" is declared more than once.'],
+      status: "failure",
+    });
+    expect(report.result).toBe("not-ready");
+  });
+
+  it("sanitizes an unexpected permission-composition exception to a fixed generic detail", async () => {
+    const hostile = "postgresql://admin:[email protected]/db /home/operator/.env";
+    const report = await diagnoseEkklesia(
+      options(),
+      dependencies({
+        composePermissions: vi.fn(() => {
+          throw new Error(hostile);
+        }),
+      }),
+    );
+
+    expect(check(report, "modules.permissions")).toMatchObject({
+      details: ["The installed permission declarations could not be composed safely."],
+      status: "failure",
+    });
+    expect(JSON.stringify(report)).not.toContain(hostile);
+  });
+
+  it("continues independent schema, migration, and PostgreSQL checks after permission composition fails", async () => {
+    const planMigrations = vi.fn(async () => plan());
+    const report = await diagnoseEkklesia(
+      options("postgresql://not-rendered.invalid/ekklesia"),
+      dependencies({
+        composePermissions: vi.fn(() => {
+          throw new PermissionRegistryError("calendar.events.read");
+        }),
+        planMigrations,
+      }),
+    );
+
+    expect(check(report, "modules.permissions").status).toBe("failure");
+    expect(check(report, "schemas.discovery").status).toBe("pass");
+    expect(check(report, "migrations.discovery").status).toBe("pass");
+    expect(check(report, "postgresql.connection").status).toBe("pass");
+    expect(planMigrations).toHaveBeenCalledOnce();
+  });
+
   it("continues independent migration and PostgreSQL checks after schema failure", async () => {
     const planMigrations = vi.fn(async () => plan());
     const report = await diagnoseEkklesia(