feat: declare module permissions

Establishes the one canonical PermissionDeclaration contract
(packages/contracts/src/authorization.ts) — id/baseline/description,
strict, unknown-property-rejecting — consumed by both Core's
authorization registry and module manifests, replacing Core's
previously separate interface.

Bumps the canonical module manifest to manifestVersion 3: permissions
become complete declarations instead of bare identifier strings, with
manifest-owned namespace and duplicate-id enforcement. Version 2 and
bare string-array permissions are rejected outright; there is no
compatibility adapter.

Adds composePlatformPermissionRegistry (core/src/modules/permissions.ts),
a pure, synchronous composer that builds one platform permission
registry from Core's own declarations plus every already-discovered
module's, in deterministic order, reusing createPermissionRegistry
and rejecting any module-contributed permission in the reserved
core.* namespace. core/src/authorization remains independent of
core/src/modules; only the module integration layer depends on
authorization.

Updates the module template, module-development docs, authorization
docs, and existing manifest fixtures for manifestVersion 3. Does not
wire the combined registry into apps/api — that is pass 2.

core/tests/authorization-permissions.test.ts

@@ -2,6 +2,7 @@ import { parsePermissionId } from "@ekklesia/contracts";
 import { describe, expect, it } from "vitest";
 import {
   CORE_AUTHORIZATION_GRANTS_MANAGE,
+  CORE_PERMISSION_DECLARATIONS,
   CORE_PERMISSION_REGISTRY,
   createPermissionRegistry,
   PermissionRegistryError,
@@ -92,3 +93,21 @@ describe("CORE_PERMISSION_REGISTRY", () => {
     expect(CORE_PERMISSION_REGISTRY.declarations).toHaveLength(1);
   });
 });
+
+describe("CORE_PERMISSION_DECLARATIONS", () => {
+  it("is Core's own declaration list, exported separately from the registry in deeply immutable form", () => {
+    expect(CORE_PERMISSION_DECLARATIONS).toEqual([
+      {
+        baseline: "restricted",
+        description: "Create, list, and revoke another user's explicit authorization grants.",
+        id: CORE_AUTHORIZATION_GRANTS_MANAGE,
+      },
+    ]);
+    expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS)).toBe(true);
+    expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS[0])).toBe(true);
+  });
+
+  it("matches exactly what CORE_PERMISSION_REGISTRY exposes as its own declarations, so a composer building on top of it never diverges from what Core itself registers", () => {
+    expect(CORE_PERMISSION_DECLARATIONS).toEqual(CORE_PERMISSION_REGISTRY.declarations);
+  });
+});

core/tests/core-migration-discovery.test.ts

@@ -91,7 +91,7 @@ async function createModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        manifestVersion: 2,
+        manifestVersion: 3,
         id,
         name: `${id} module`,
         version: "0.1.0",

core/tests/doctor.test.ts

@@ -39,7 +39,7 @@ function discoveredModule(id: string, version = "0.1.0"): DiscoveredModule {
       },
       entrypoints: { server: "./dist/server.js" },
       id,
-      manifestVersion: 2,
+      manifestVersion: 3,
       name: `${id} module`,
       permissions: [],
       storage: { buckets: [] },

core/tests/module-discovery.test.ts

@@ -31,7 +31,7 @@ async function createModulesDirectory(): Promise<string> {
 
 function manifestFor(id: string): Record<string, unknown> {
   return {
-    manifestVersion: 2,
+    manifestVersion: 3,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -40,7 +40,9 @@ function manifestFor(id: string): Record<string, unknown> {
       moduleSdk: "^0.1.0",
     },
     capabilities: [{ id: `${id}.records`, version: "1.0.0" }],
-    permissions: [`${id}.records.read`],
+    permissions: [
+      { id: `${id}.records.read`, baseline: "restricted", description: "Read records." },
+    ],
     entrypoints: {
       server: "./dist/server/index.js",
     },
@@ -151,6 +153,16 @@ describe("module discovery", () => {
     expect(Object.isFrozen(modules[1]?.manifest)).toBe(true);
     const mutableBuckets = modules[1]?.manifest.storage.buckets as unknown as Array<{ id: string }>;
     expect(() => mutableBuckets.push({ id: "tampered" })).toThrow(TypeError);
+
+    expect(modules[1]?.manifest.permissions).toEqual([
+      { id: "calendar.records.read", baseline: "restricted", description: "Read records." },
+    ]);
+    expect(Object.isFrozen(modules[1]?.manifest.permissions)).toBe(true);
+    expect(Object.isFrozen(modules[1]?.manifest.permissions[0])).toBe(true);
+    const mutablePermissions = modules[1]?.manifest.permissions as unknown as Array<{
+      id: string;
+    }>;
+    expect(() => mutablePermissions.push({ id: "tampered" })).toThrow(TypeError);
   });
 
   it("aggregates malformed packages and manifests without partial discovery", async () => {
@@ -215,7 +227,9 @@ describe("module discovery", () => {
         ...manifestFor("one"),
         id: "shared",
         capabilities: [{ id: "shared.records", version: "1.0.0" }],
-        permissions: ["shared.records.read"],
+        permissions: [
+          { id: "shared.records.read", baseline: "restricted", description: "Read records." },
+        ],
       },
       packageJson: {
         name: "@test/duplicate",
@@ -229,7 +243,9 @@ describe("module discovery", () => {
         ...manifestFor("two"),
         id: "shared",
         capabilities: [{ id: "shared.records", version: "1.0.0" }],
-        permissions: ["shared.records.read"],
+        permissions: [
+          { id: "shared.records.read", baseline: "restricted", description: "Read records." },
+        ],
       },
       packageJson: {
         name: "@test/duplicate",

core/tests/module-migration-discovery.test.ts

@@ -65,7 +65,7 @@ function manifestFor(
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 2,
+    manifestVersion: 3,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-permissions.test.ts

@@ -0,0 +1,223 @@
+import { type PermissionBaseline, parseModuleManifest } from "@ekklesia/contracts";
+import { describe, expect, it } from "vitest";
+import {
+  CORE_AUTHORIZATION_GRANTS_MANAGE,
+  CORE_PERMISSION_DECLARATIONS,
+  PermissionRegistryError,
+} from "../src/authorization/index.js";
+import type { DiscoveredModule } from "../src/modules/discovery.js";
+import {
+  composePlatformPermissionRegistry,
+  ModulePermissionCompositionError,
+} from "../src/modules/permissions.js";
+
+interface PermissionInput {
+  readonly id: string;
+  readonly baseline: PermissionBaseline;
+  readonly description: string;
+}
+
+/** A minimal, in-memory `DiscoveredModule` double — no filesystem, no real discovery. The manifest
+ * is still built through `parseModuleManifest`, so a fixture that would not actually pass manifest
+ * validation cannot silently misrepresent what real discovery would ever produce. Only `manifest`
+ * is read by `composePlatformPermissionRegistry`; the rest exist only to satisfy the type. */
+function fakeModule(id: string, permissions: readonly PermissionInput[] = []): DiscoveredModule {
+  const manifest = parseModuleManifest({
+    manifestVersion: 3,
+    id,
+    name: `${id} module`,
+    version: "0.1.0",
+    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    permissions,
+    entrypoints: {
+      // Deliberately a path nothing will ever resolve, proving composition never imports or
+      // otherwise touches a module's server entrypoint.
+      server: "./dist/does-not-exist/index.js",
+    },
+  });
+  return {
+    directory: `/modules/${id}`,
+    entrypoints: { server: `/modules/${id}/dist/does-not-exist/index.js` },
+    manifest,
+    manifestPath: `/modules/${id}/ekklesia.module.json`,
+    packageName: `@test/${id}`,
+  };
+}
+
+describe("composePlatformPermissionRegistry", () => {
+  it("composes a Core-only registry when no modules are supplied", () => {
+    const registry = composePlatformPermissionRegistry([]);
+
+    expect(registry.declarations).toEqual(CORE_PERMISSION_DECLARATIONS);
+    expect(registry.has(CORE_AUTHORIZATION_GRANTS_MANAGE)).toBe(true);
+  });
+
+  it("composes Core and multiple discovered modules' declarations into one registry", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+    const people = fakeModule("people", [
+      { id: "people.directory.read", baseline: "authenticated", description: "Read directory." },
+    ]);
+
+    const registry = composePlatformPermissionRegistry([calendar, people]);
+
+    expect(registry.has(CORE_AUTHORIZATION_GRANTS_MANAGE)).toBe(true);
+    expect(registry.has("calendar.events.read")).toBe(true);
+    expect(registry.has("people.directory.read")).toBe(true);
+    expect(registry.declarations).toHaveLength(3);
+  });
+
+  it("preserves deterministic order: Core first, then modules in the supplied order, then declarations in manifest order", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+      { id: "calendar.events.write", baseline: "restricted", description: "Write events." },
+    ]);
+    const people = fakeModule("people", [
+      { id: "people.directory.read", baseline: "authenticated", description: "Read directory." },
+    ]);
+
+    const registry = composePlatformPermissionRegistry([calendar, people]);
+
+    expect(registry.declarations.map((declaration) => declaration.id)).toEqual([
+      CORE_AUTHORIZATION_GRANTS_MANAGE,
+      "calendar.events.read",
+      "calendar.events.write",
+      "people.directory.read",
+    ]);
+  });
+
+  it.each([
+    "public",
+    "authenticated",
+    "restricted",
+  ] as const)("preserves the exact %s baseline and description of a module declaration", (baseline) => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline, description: "Read calendar events." },
+    ]);
+
+    const registry = composePlatformPermissionRegistry([calendar]);
+
+    expect(registry.get("calendar.events.read")).toEqual({
+      id: "calendar.events.read",
+      baseline,
+      description: "Read calendar events.",
+    });
+  });
+
+  it("still fails closed for a permission no module or Core ever declared", () => {
+    const registry = composePlatformPermissionRegistry([]);
+
+    expect(registry.has("calendar.events.read")).toBe(false);
+    expect(registry.get("calendar.events.read")).toBeUndefined();
+  });
+
+  it("fails composition on an exact duplicate permission id supplied by two module entries", () => {
+    // A permission id must start with its own module's id, so a genuine cross-module collision is
+    // only reachable if the supplied list itself contains the same module id twice — real
+    // discovery already guarantees module-id uniqueness (`MODULE_ID_DUPLICATE`), but composition
+    // re-derives duplicate detection from the flat declaration list regardless, rather than
+    // trusting that upstream guarantee alone.
+    const first = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+    const second = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "public", description: "Also read events." },
+    ]);
+
+    expect(() => composePlatformPermissionRegistry([first, second])).toThrow(
+      PermissionRegistryError,
+    );
+  });
+
+  it("rejects a module contributing a permission in the reserved core.* namespace, without leaking a module path", () => {
+    // Only a module whose own id is literally "core" can produce a "core."-prefixed permission
+    // that still passes the manifest's own module-namespace check — this proves composition
+    // catches that case rather than trusting the manifest's self-consistency alone.
+    const impostor = fakeModule("core", [
+      { id: "core.rogue.permission", baseline: "restricted", description: "Not really Core's." },
+    ]);
+
+    let captured: unknown;
+    try {
+      composePlatformPermissionRegistry([impostor]);
+    } catch (error) {
+      captured = error;
+    }
+
+    expect(captured).toBeInstanceOf(ModulePermissionCompositionError);
+    expect(captured).toMatchObject({
+      code: "MODULE_PERMISSION_RESERVED_NAMESPACE",
+      moduleId: "core",
+      permissionId: "core.rogue.permission",
+    });
+    const publicText = String(captured);
+    expect(publicText).not.toContain("/modules/core");
+    expect(publicText).not.toContain("ekklesia.module.json");
+  });
+
+  it("rejects a reserved-namespace collision even when it would not otherwise duplicate an existing id", () => {
+    const impostor = fakeModule("core", [
+      {
+        id: "core.authorization.grants.manage",
+        baseline: "restricted",
+        description: "Attempting to shadow Core's own permission.",
+      },
+    ]);
+
+    expect(() => composePlatformPermissionRegistry([impostor])).toThrow(
+      ModulePermissionCompositionError,
+    );
+  });
+
+  it("removes a module's permissions from the resulting registry once that module is absent from the supplied list", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+
+    const withCalendar = composePlatformPermissionRegistry([calendar]);
+    expect(withCalendar.has("calendar.events.read")).toBe(true);
+
+    const withoutCalendar = composePlatformPermissionRegistry([]);
+    expect(withoutCalendar.has("calendar.events.read")).toBe(false);
+  });
+
+  it("performs no I/O: composition is synchronous and never imports a module's entrypoint", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+
+    // A synchronous return (not a Promise) from a fixture whose entrypoint deliberately resolves
+    // to nothing on disk is direct evidence no filesystem or module-code operation occurred.
+    const result = composePlatformPermissionRegistry([calendar]);
+    expect(result).not.toBeInstanceOf(Promise);
+    expect(result.has("calendar.events.read")).toBe(true);
+  });
+
+  it("does not mutate the supplied module list or Core's own declaration list", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+    const modules = Object.freeze([calendar]);
+    const coreDeclarationsBefore = [...CORE_PERMISSION_DECLARATIONS];
+
+    composePlatformPermissionRegistry(modules);
+
+    expect(modules).toEqual([calendar]);
+    expect(CORE_PERMISSION_DECLARATIONS).toEqual(coreDeclarationsBefore);
+  });
+
+  it("returns a registry and declarations that remain immutable, including module-contributed ones", () => {
+    const calendar = fakeModule("calendar", [
+      { id: "calendar.events.read", baseline: "restricted", description: "Read events." },
+    ]);
+
+    const registry = composePlatformPermissionRegistry([calendar]);
+
+    expect(Object.isFrozen(registry)).toBe(true);
+    expect(Object.isFrozen(registry.declarations)).toBe(true);
+    for (const declaration of registry.declarations) {
+      expect(Object.isFrozen(declaration)).toBe(true);
+    }
+  });
+});

core/tests/module-runtime.test.ts

@@ -43,7 +43,7 @@ function manifestFor(
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 2,
+    manifestVersion: 3,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-schema-discovery.test.ts

@@ -41,7 +41,7 @@ function manifestFor(
   options: { dependencies?: Record<string, unknown>; schema?: string | false } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 2,
+    manifestVersion: 3,
     id,
     name: `${id} module`,
     version: "0.1.0",