feat: mount discovered module UI in a minimal Ekklesia browser host

Phase 6C pass 2. Every link in the module UI chain existed except the one
that closes it: a module could be authored, built, validated, published at a
browser URL, and loaded by a generic loader — and nothing in Ekklesia did any
of it. There was no browser application at all.

Two pieces were missing. A browser could not discover what to mount, and it
must not work that out for itself.

GET /api/v1/module-ui is the inventory: per publishable module, its id and
version, the server-produced artifact URL, the server-produced root of the
module's own API, and the subset of that module's declared permissions the
caller holds. Five fields, each because building a ModuleUiHostContext needs
it — no filesystem paths, and no name/icon/folder/order, because navigation
metadata is a design that does not exist yet. Its module set is the ADR 0025
publication registry rather than a rescan, so the inventory and the artifact
route cannot disagree. It requires a new Core permission, core.modules.ui.read
(baseline authenticated), because it is precisely the enumeration the anonymous
artifact route deliberately withholds.

Both URLs are server-produced. moduleUiArtifactUrl already existed;
moduleApiBaseUrl is now exported and moduleRoutePath builds on it, so each URL
shape has exactly one author. Without it the shell would hardcode
/api/v1/modules/<id> — the prefix ADR 0022 forbids a module UI from spelling,
reappearing in the host instead.

surfaces/shell (@ekklesia/shell) is the repository's first surface: a small
React application built to static files by its own esbuild script. It resolves
the principal, fetches the inventory, builds the host context entirely from
server-derived data, and hands the artifact URL to @ekklesia/module-ui-host.
One frame per selection — keyed by module identity — defeats the stale-load
race; the host owns the container, the loading state, and every failure, so a
broken module costs its own panel rather than the shell.

The shell statically imports no module, and both levels are checked: no source
import may name a module, and the emitted bundle must contain exactly one
dynamic import (the loader's) with no module id, no /api/v1/modules, no eval,
and no blob URL. Permission hints come from Core's own evaluator and stay
presentation-only — the end-to-end test has a UI holding no grant call its API
anyway and still receive 403.

Surfaces may now depend only on browser-safe shared roles; @ekklesia/contracts
is deliberately excluded, since its barrel pulls Drizzle's types and Node's
globals into the browser — the hole ADR 0024 closed one layer down.

Not the Dashboard: no navigation, grouping, icons, ordering, design system, or
routing. The selector is a list of module ids.

Co-Authored-By: Claude Opus 5 <[email protected]>

apps/api/tests/api-http.integration.ts

@@ -2158,7 +2158,9 @@ describe.sequential("live API — installed module permission end-to-end", () =>
     expect(moduleCheck).toMatchObject({ status: "pass" });
     expect(moduleCheck?.details).toEqual(["calendar 0.1.0"]);
     expect(permissionsCheck).toMatchObject({
-      details: ["2 permissions registered"],
+      // Core's own two (`core.authorization.grants.manage`, `core.modules.ui.read`) plus the
+      // fixture module's one.
+      details: ["3 permissions registered"],
       status: "pass",
     });
     // Doctor and permission composition read only the manifest — the fixture's register/start

apps/api/tests/module-ui-host-e2e.test.ts

@@ -0,0 +1,405 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  type EkklesiaPrincipal,
+  type ModuleDatabase,
+  type ModuleRuntimeServices,
+  parseEkklesiaUserId,
+} from "@ekklesia/contracts";
+import {
+  type AuthorizationStore,
+  createAuthorizationEvaluator,
+} from "@ekklesia/core/authorization";
+import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
+import {
+  composePlatformPermissionRegistry,
+  createModuleUiPublicationRegistry,
+  discoverModules,
+  startDiscoveredModuleRuntime,
+} from "@ekklesia/core/modules";
+import { loadModuleUi } from "@ekklesia/module-ui-host";
+import {
+  bootstrapHost,
+  createModuleUiContext,
+  type EkklesiaHostConfig,
+  moduleUiSourceUrl,
+} from "@ekklesia/shell";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApiApp } from "../src/app.js";
+
+/**
+ * The whole chain, with nothing between the halves faked:
+ *
+ * ```text
+ * module fixture on disk -> discovery -> module runtime started -> publication registry
+ *   -> inventory endpoint -> the shell's own bootstrap -> server-produced artifact URL
+ *   -> the generic loader -> mount -> the module calls its own API relatively
+ *   -> the shell resolves it to /api/v1/modules/<id>/... -> server permission enforcement
+ * ```
+ *
+ * Every step runs real code. The module is discovered and *started* by Core's real runtime, its
+ * routes are mounted by the real `createApiApp`, its artifact is published by the real ADR 0025
+ * route, its descriptor comes from the real inventory endpoint, and the browser half is
+ * `@ekklesia/shell`'s own exported protocol — the same functions the React shell calls — rather
+ * than a reimplementation of them here.
+ *
+ * Two things are deliberately *not* faked-around and are worth naming. The shell's `fetch` is the
+ * Hono app's own `request`, so requests really traverse routing, CORS, authorization middleware, and
+ * handlers without needing a socket. And Node cannot `import()` an `http:` URL, so the artifact is
+ * fetched over that same in-process HTTP path and the **bytes it returned** are handed to the
+ * generic loader through a `data:` URL — a genuine module URL, the same separation ADR 0025 used.
+ * No test here reads the artifact off the filesystem and calls that a proof of publication.
+ */
+const viewerId = parseEkklesiaUserId("22222222-2222-4222-8222-222222222222");
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+/**
+ * A real, complete module: a manifest declaring a restricted permission and a UI entrypoint, a
+ * server entrypoint that registers a permission-gated route, and a compiled UI artifact that reads
+ * its host context and calls its own API relatively.
+ *
+ * The UI artifact is written as plain ESM rather than compiled from TSX here: ADR 0023's pipeline is
+ * already proven end to end by `templates/module`'s own tests, and what this test needs is a byte
+ * sequence whose journey through publication, inventory, and the loader can be asserted exactly.
+ */
+async function createFixtureModule(modulesDirectory: string): Promise<void> {
+  const moduleDirectory = path.join(modulesDirectory, "example");
+  await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
+  await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
+
+  await writeFile(
+    path.join(moduleDirectory, "package.json"),
+    JSON.stringify({
+      ekklesia: { layer: "module" },
+      name: "@test/module-example",
+      type: "module",
+      version: "0.1.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "ekklesia.module.json"),
+    JSON.stringify({
+      compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+      entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+      id: "example",
+      manifestVersion: 4,
+      name: "Example module",
+      permissions: [
+        {
+          baseline: "restricted",
+          description: "Read example records.",
+          id: "example.records.read",
+        },
+      ],
+      version: "0.1.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "dist/server/index.js"),
+    `export default {
+      id: "example",
+      version: "0.1.0",
+      register({ http }) {
+        http.route({
+          method: "GET",
+          path: "/records",
+          permission: "example.records.read",
+          maxBodyBytes: 0,
+          async handler() {
+            return Response.json([{ id: "a" }, { id: "b" }]);
+          },
+        });
+      },
+    };\n`,
+  );
+  // The module UI: host-neutral, asks for a relative path, and renders from the host context. It
+  // hardcodes no origin, no prefix, and no permission decision of its own.
+  await writeFile(
+    path.join(moduleDirectory, "dist/ui/index.js"),
+    `export default {
+  id: "example",
+  version: "0.1.0",
+  async mount(container, context) {
+    if (!context.permissions.has("example.records.read")) {
+      container.textContent = context.moduleId + ":denied";
+      return () => { container.textContent = ""; };
+    }
+    const response = await context.api.request("records");
+    const records = response.ok ? await response.json() : [];
+    container.textContent =
+      context.moduleId + ":" + response.status + ":" + records.length;
+    return () => { container.textContent = ""; };
+  },
+};\n`,
+  );
+}
+
+interface HarnessOptions {
+  readonly principal?: EkklesiaPrincipal;
+  readonly grants?: readonly string[];
+}
+
+interface Harness {
+  readonly config: EkklesiaHostConfig;
+  readonly moduleApiCalls: readonly string[];
+  stop(): Promise<void>;
+}
+
+/**
+ * Starts a real API over a real discovered-and-started module, and returns the `EkklesiaHostConfig`
+ * a browser would use — with `fetch` wired to the app itself.
+ */
+async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
+  const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-host-e2e-"));
+  temporaryDirectories.push(modulesDirectory);
+  await createFixtureModule(modulesDirectory);
+
+  const modules = await discoverModules({
+    moduleSdkVersion: "0.1.0",
+    modulesDirectory,
+    platformVersion: "0.1.0",
+  });
+  const services: ModuleRuntimeServices = Object.freeze({
+    database: Object.freeze({}) as unknown as ModuleDatabase,
+  });
+  // The module's real runtime: its server entrypoint is imported, registered, and started, and the
+  // route snapshot below is the one it actually published.
+  const moduleRuntime = await startDiscoveredModuleRuntime(modules, services);
+
+  const granted = new Set(options.grants ?? []);
+  const evaluator = createAuthorizationEvaluator({
+    grants: { hasActiveGrant: async (query) => granted.has(query.permission) },
+    platformOwners: { isPlatformOwner: async () => false },
+  });
+  const runtime: EkklesiaIdentityRuntime = {
+    handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
+    resolvePrincipal: vi.fn().mockResolvedValue(options.principal ?? ANONYMOUS_PRINCIPAL),
+  };
+  const store = {
+    createGrant: vi.fn(),
+    grantPlatformOwner: vi.fn(),
+    hasActiveGrant: vi.fn().mockResolvedValue(false),
+    isPlatformOwner: vi.fn().mockResolvedValue(false),
+    listGrantsForUser: vi.fn().mockResolvedValue({ grants: [] }),
+    revokeGrant: vi.fn(),
+    revokePlatformOwner: vi.fn(),
+  } as unknown as AuthorizationStore;
+
+  const app = createApiApp({
+    authorization: { evaluator, registry: composePlatformPermissionRegistry(modules), store },
+    moduleRoutes: moduleRuntime.routes,
+    moduleServices: services,
+    moduleUi: createModuleUiPublicationRegistry(modules),
+    runtime,
+    trustedOrigins: ["https://dashboard.example.test"],
+  });
+
+  const moduleApiCalls: string[] = [];
+  const hostFetch = (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    const url = new URL(String(input));
+    if (url.pathname.startsWith("/api/v1/modules/")) {
+      moduleApiCalls.push(`${init?.method ?? "GET"} ${url.pathname}${url.search}`);
+    }
+    return app.request(url.href, init);
+  }) as unknown as typeof fetch;
+
+  return {
+    config: { apiBaseUrl: "https://ekklesia.example.test", fetch: hostFetch },
+    moduleApiCalls,
+    stop: () => moduleRuntime.stop(),
+  };
+}
+
+/** Node cannot `import()` an `http:` URL, so the artifact is fetched over the real route and its
+ * exact bytes become a `data:` URL. The loader still performs a genuine dynamic import of a real
+ * module URL; only the transport differs, and the transport itself is asserted separately. */
+async function publishedArtifactUrl(harness: Harness, sourceUrl: string): Promise<string> {
+  const response = await (harness.config.fetch as typeof fetch)(sourceUrl);
+  expect(response.status).toBe(200);
+  expect(response.headers.get("content-type")).toBe("text/javascript; charset=utf-8");
+  const bytes = Buffer.from(await response.arrayBuffer());
+  return `data:text/javascript;base64,${bytes.toString("base64")}`;
+}
+
+/** The loader hands the container straight to the module and never inspects it, so a plain sink is
+ * enough and no DOM implementation is needed in this Node-environment suite. */
+function containerSink(): { textContent: string } {
+  return { textContent: "" };
+}
+
+type LoaderContainer = Parameters<typeof loadModuleUi>[0]["container"];
+
+describe("end to end: a discovered module's UI mounts in the Ekklesia host", () => {
+  it("bootstraps, publishes, loads, mounts, and reaches the module's own API", async () => {
+    const harness = await startHarness({
+      grants: ["example.records.read"],
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      // 1. The shell's own bootstrap: principal, then inventory.
+      const bootstrap = await bootstrapHost(harness.config);
+      expect(bootstrap.principal).toEqual({ kind: "authenticated", userId: viewerId });
+      expect(bootstrap.modules).toHaveLength(1);
+
+      const descriptor = bootstrap.modules[0];
+      if (!descriptor) {
+        throw new Error("the inventory returned no module");
+      }
+      // 2. The URLs came from the server, not from anything the browser composed.
+      expect(descriptor).toEqual({
+        apiBaseUrl: "/api/v1/modules/example",
+        id: "example",
+        permissions: ["example.records.read"],
+        uiUrl: "/api/v1/module-ui/example/0.1.0",
+        version: "0.1.0",
+      });
+
+      // 3. The artifact really is served by the real publication route at that URL.
+      const sourceUrl = moduleUiSourceUrl(harness.config, descriptor);
+      expect(sourceUrl).toBe("https://ekklesia.example.test/api/v1/module-ui/example/0.1.0");
+      const artifactUrl = await publishedArtifactUrl(harness, sourceUrl);
+
+      // 4. The generic loader mounts it with the context the shell built.
+      const container = containerSink();
+      const mounted = await loadModuleUi({
+        container: container as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor,
+          principal: bootstrap.principal,
+        }),
+        source: { moduleId: descriptor.id, url: artifactUrl, version: descriptor.version },
+      });
+
+      // 5. The module rendered, having reached its own backend through the host.
+      expect(container.textContent).toBe("example:200:2");
+      // 6. It asked for "records"; the host resolved that onto Ekklesia's module mount prefix.
+      expect(harness.moduleApiCalls).toEqual(["GET /api/v1/modules/example/records"]);
+
+      // 7. And it tears down cleanly.
+      await mounted.unmount();
+      expect(container.textContent).toBe("");
+      expect(mounted.mounted).toBe(false);
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("keeps server authorization authoritative when the UI ignores its own hint", async () => {
+    // Signed in, but holding no grant for the module's restricted permission.
+    const harness = await startHarness({
+      grants: [],
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      const bootstrap = await bootstrapHost(harness.config);
+      const descriptor = bootstrap.modules[0];
+      if (!descriptor) {
+        throw new Error("the inventory returned no module");
+      }
+
+      // The hint is honest about it...
+      expect(descriptor.permissions).toEqual([]);
+      const context = createModuleUiContext({
+        config: harness.config,
+        descriptor,
+        principal: bootstrap.principal,
+      });
+      expect(context.permissions.has("example.records.read")).toBe(false);
+
+      // ...and the hint is not what protects the route. Calling anyway — exactly what a buggy or
+      // hostile UI would do — is still refused by the server.
+      const response = await context.api.request("records");
+      expect(response.status).toBe(403);
+      expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
+      expect(harness.moduleApiCalls).toEqual(["GET /api/v1/modules/example/records"]);
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("renders the module's own denied state from the hint, without calling the API", async () => {
+    const harness = await startHarness({
+      grants: [],
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      const bootstrap = await bootstrapHost(harness.config);
+      const descriptor = bootstrap.modules[0];
+      if (!descriptor) {
+        throw new Error("the inventory returned no module");
+      }
+      const artifactUrl = await publishedArtifactUrl(
+        harness,
+        moduleUiSourceUrl(harness.config, descriptor),
+      );
+      const container = containerSink();
+
+      await loadModuleUi({
+        container: container as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor,
+          principal: bootstrap.principal,
+        }),
+        source: { moduleId: descriptor.id, url: artifactUrl, version: descriptor.version },
+      });
+
+      // Hiding a control is a usability improvement: the module simply did not ask.
+      expect(container.textContent).toBe("example:denied");
+      expect(harness.moduleApiCalls).toEqual([]);
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("gives an anonymous visitor no inventory and therefore nothing to mount", async () => {
+    const harness = await startHarness();
+    try {
+      const bootstrap = await bootstrapHost(harness.config);
+
+      expect(bootstrap.principal).toEqual({ kind: "anonymous" });
+      expect(bootstrap.modules).toEqual([]);
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("refuses a module UI that tries to address another module's API through the host", async () => {
+    const harness = await startHarness({
+      grants: ["example.records.read"],
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      const bootstrap = await bootstrapHost(harness.config);
+      const descriptor = bootstrap.modules[0];
+      if (!descriptor) {
+        throw new Error("the inventory returned no module");
+      }
+      const context = createModuleUiContext({
+        config: harness.config,
+        descriptor,
+        principal: bootstrap.principal,
+      });
+
+      await expect(context.api.request("../../grants?userId=someone")).rejects.toMatchObject({
+        code: "MODULE_API_PATH_INVALID",
+      });
+      // It never became a request at all.
+      expect(harness.moduleApiCalls).toEqual([]);
+    } finally {
+      await harness.stop();
+    }
+  });
+});

apps/api/tests/module-ui-inventory.test.ts

@@ -0,0 +1,500 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  type EkklesiaPrincipal,
+  type ModuleDatabase,
+  type ModuleRuntimeServices,
+  parseEkklesiaUserId,
+} from "@ekklesia/contracts";
+import {
+  type AuthorizationStore,
+  createAuthorizationEvaluator,
+  type PermissionRegistry,
+} from "@ekklesia/core/authorization";
+import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
+import {
+  composePlatformPermissionRegistry,
+  createModuleUiPublicationRegistry,
+  type DiscoveredModule,
+  discoverModules,
+} from "@ekklesia/core/modules";
+import type { Hono } from "hono";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApiApp } from "../src/app.js";
+import { moduleApiBaseUrl } from "../src/module-http-routes.js";
+import { MODULE_UI_INVENTORY_PATH } from "../src/module-ui-inventory.js";
+import { moduleUiArtifactUrl } from "../src/module-ui-routes.js";
+
+const trustedOrigin = "https://dashboard.example.test";
+const viewerId = parseEkklesiaUserId("11111111-1111-4111-8111-111111111111");
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+interface ModuleFixture {
+  readonly id: string;
+  readonly version?: string;
+  /** Omit for a backend-only module: the manifest then declares no `entrypoints.ui` at all. */
+  readonly withUi?: boolean;
+  readonly permissions?: ReadonlyArray<{
+    readonly id: string;
+    readonly baseline: "authenticated" | "public" | "restricted";
+  }>;
+}
+
+async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
+  const version = fixture.version ?? "0.1.0";
+  const moduleDirectory = path.join(modulesDirectory, fixture.id);
+  await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
+  await writeFile(
+    path.join(moduleDirectory, "package.json"),
+    JSON.stringify({
+      ekklesia: { layer: "module" },
+      name: `@test/module-${fixture.id}`,
+      type: "module",
+      version,
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "ekklesia.module.json"),
+    JSON.stringify({
+      compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+      entrypoints: {
+        server: "./dist/server/index.js",
+        ...(fixture.withUi ? { ui: "./dist/ui/index.js" } : {}),
+      },
+      id: fixture.id,
+      manifestVersion: 4,
+      name: `${fixture.id} module`,
+      permissions: (fixture.permissions ?? []).map((permission) => ({
+        ...permission,
+        description: `Test permission for ${fixture.id}.`,
+      })),
+      version,
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "dist/server/index.js"),
+    `export default { id: ${JSON.stringify(fixture.id)}, version: ${JSON.stringify(version)} };`,
+  );
+  if (fixture.withUi) {
+    await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
+    await writeFile(
+      path.join(moduleDirectory, "dist/ui/index.js"),
+      `export default { id: ${JSON.stringify(fixture.id)}, version: ${JSON.stringify(version)}, mount() {} };\n`,
+    );
+  }
+}
+
+interface InstallOptions {
+  readonly fixtures: readonly ModuleFixture[];
+  /** Anonymous by default, so every scenario has to opt in to being signed in. */
+  readonly principal?: EkklesiaPrincipal;
+  /** Permission ids the viewer holds an active grant for. Evaluated by Core's real evaluator, so
+   * baselines, the owner bypass, and deny-by-default all behave exactly as in production. */
+  readonly grants?: readonly string[];
+  readonly platformOwner?: boolean;
+  /** Makes the grant port fail, so the "a hint that could not be determined is never reported as
+   * denied" path can be exercised. */
+  readonly grantsUnavailable?: boolean;
+}
+
+interface Installation {
+  readonly app: Hono;
+  readonly modules: readonly DiscoveredModule[];
+  readonly modulesDirectory: string;
+  readonly permissionRegistry: PermissionRegistry;
+}
+
+/** A real installation: fixtures on disk, Core's real discovery, real permission composition, the
+ * real publication registry, the real authorization evaluator, and the real `createApiApp`. Only
+ * identity resolution and the two authorization ports are doubled, because neither needs PostgreSQL
+ * to answer the questions these tests ask. */
+async function install(options: InstallOptions): Promise<Installation> {
+  const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-api-ui-inventory-"));
+  temporaryDirectories.push(modulesDirectory);
+  for (const fixture of options.fixtures) {
+    await createModule(modulesDirectory, fixture);
+  }
+  const modules = await discoverModules({
+    moduleSdkVersion: "0.1.0",
+    modulesDirectory,
+    platformVersion: "0.1.0",
+  });
+
+  const granted = new Set(options.grants ?? []);
+  const evaluator = createAuthorizationEvaluator({
+    grants: {
+      hasActiveGrant: async (query) => {
+        if (options.grantsUnavailable) {
+          throw new Error("grant store unavailable");
+        }
+        return granted.has(query.permission);
+      },
+    },
+    platformOwners: { isPlatformOwner: async () => options.platformOwner === true },
+  });
+
+  const runtime: EkklesiaIdentityRuntime = {
+    handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
+    resolvePrincipal: vi.fn().mockResolvedValue(options.principal ?? ANONYMOUS_PRINCIPAL),
+  };
+  const store = {
+    createGrant: vi.fn(),
+    grantPlatformOwner: vi.fn(),
+    hasActiveGrant: vi.fn().mockResolvedValue(false),
+    isPlatformOwner: vi.fn().mockResolvedValue(false),
+    listGrantsForUser: vi.fn().mockResolvedValue({ grants: [] }),
+    revokeGrant: vi.fn(),
+    revokePlatformOwner: vi.fn(),
+  } as unknown as AuthorizationStore;
+  const services: ModuleRuntimeServices = Object.freeze({
+    database: Object.freeze({}) as unknown as ModuleDatabase,
+  });
+  const permissionRegistry = composePlatformPermissionRegistry(modules);
+
+  const app = createApiApp({
+    authorization: { evaluator, registry: permissionRegistry, store },
+    moduleRoutes: Object.freeze([]),
+    moduleServices: services,
+    moduleUi: createModuleUiPublicationRegistry(modules),
+    runtime,
+    trustedOrigins: [trustedOrigin],
+  });
+
+  return { app, modules, modulesDirectory, permissionRegistry };
+}
+
+function signedIn(): EkklesiaPrincipal {
+  return createAuthenticatedPrincipal(viewerId);
+}
+
+async function inventoryOf(app: Hono): Promise<{
+  readonly body: string;
+  readonly modules: ReadonlyArray<Record<string, unknown>>;
+  readonly response: Response;
+}> {
+  const response = await app.request(MODULE_UI_INVENTORY_PATH);
+  const body = await response.clone().text();
+  const parsed = (await response.json()) as { modules?: ReadonlyArray<Record<string, unknown>> };
+  return { body, modules: parsed.modules ?? [], response };
+}
+
+describe("module UI inventory — what it lists", () => {
+  it("describes a publishable module with exactly the fields a host needs", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", permissions: [], withUi: true }],
+      principal: signedIn(),
+    });
+
+    const { modules, response } = await inventoryOf(app);
+
+    expect(response.status).toBe(200);
+    expect(modules).toEqual([
+      {
+        api: { baseUrl: "/api/v1/modules/example" },
+        id: "example",
+        permissions: [],
+        ui: { url: "/api/v1/module-ui/example/0.1.0" },
+        version: "0.1.0",
+      },
+    ]);
+  });
+
+  it("builds both URLs with the server's own canonical helpers", async () => {
+    const { app, modules: discovered } = await install({
+      fixtures: [{ id: "example", version: "2.4.1", withUi: true }],
+      principal: signedIn(),
+    });
+    const module = discovered[0] as DiscoveredModule;
+
+    const { modules } = await inventoryOf(app);
+
+    // Not "looks like the right shape" — byte-identical to what the helpers produce, so a second
+    // hand-written template string anywhere would fail here.
+    expect(modules[0]?.ui).toEqual({
+      url: moduleUiArtifactUrl({ moduleId: module.manifest.id, version: module.manifest.version }),
+    });
+    expect(modules[0]?.api).toEqual({ baseUrl: moduleApiBaseUrl(module.manifest.id) });
+  });
+
+  it("omits a module that declares no UI entrypoint", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "calendar" }, { id: "example", withUi: true }],
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    expect(modules.map((module) => module.id)).toEqual(["example"]);
+  });
+
+  it("is empty, not an error, when no installed module provides a UI", async () => {
+    const { app } = await install({ fixtures: [{ id: "calendar" }], principal: signedIn() });
+
+    const { modules, response } = await inventoryOf(app);
+
+    expect(response.status).toBe(200);
+    expect(modules).toEqual([]);
+  });
+
+  it("orders modules deterministically, matching the publication registry", async () => {
+    const { app } = await install({
+      fixtures: [
+        { id: "signage", withUi: true },
+        { id: "announcements", withUi: true },
+        { id: "calendar", withUi: true },
+      ],
+      principal: signedIn(),
+    });
+
+    const first = await inventoryOf(app);
+    const second = await inventoryOf(app);
+
+    // Discovery order, which is sorted; the same on every request.
+    expect(first.modules.map((module) => module.id)).toEqual([
+      "announcements",
+      "calendar",
+      "signage",
+    ]);
+    expect(second.modules.map((module) => module.id)).toEqual(
+      first.modules.map((module) => module.id),
+    );
+  });
+
+  it("leaks no filesystem path, package root, or other manifest internal", async () => {
+    const {
+      app,
+      modules: discovered,
+      modulesDirectory,
+    } = await install({
+      fixtures: [{ id: "example", permissions: [], withUi: true }],
+      principal: signedIn(),
+    });
+    const artifactPath = (discovered[0] as DiscoveredModule).entrypoints.ui as string;
+
+    const { body, modules } = await inventoryOf(app);
+
+    expect(body).not.toContain(modulesDirectory);
+    expect(body).not.toContain(artifactPath);
+    expect(body).not.toContain(tmpdir());
+    expect(body).not.toContain("dist");
+    expect(body).not.toContain("@test/module-example");
+    expect(body).not.toContain("ekklesia.module.json");
+    // The exact key set, so a future field cannot be added without a deliberate decision here.
+    expect(Object.keys(modules[0] ?? {}).sort()).toEqual([
+      "api",
+      "id",
+      "permissions",
+      "ui",
+      "version",
+    ]);
+  });
+
+  it("carries no navigation or presentation metadata", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", withUi: true }],
+      principal: signedIn(),
+    });
+
+    const { body } = await inventoryOf(app);
+
+    // ADR 0021 keeps Dashboard grouping an administrator's configuration, never a module
+    // declaration. The manifest's own `name` and `description` must not leak into it by accident.
+    for (const field of ["name", "description", "icon", "category", "folder", "order", "group"]) {
+      expect(body, field).not.toContain(`"${field}"`);
+    }
+  });
+});
+
+describe("module UI inventory — authentication", () => {
+  it("refuses an anonymous caller", async () => {
+    const { app } = await install({ fixtures: [{ id: "example", withUi: true }] });
+
+    const response = await app.request(MODULE_UI_INVENTORY_PATH);
+
+    expect(response.status).toBe(403);
+    expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
+  });
+
+  it("tells an anonymous caller nothing about what is installed", async () => {
+    const { app } = await install({
+      fixtures: [
+        { id: "example", withUi: true },
+        { id: "calendar", withUi: true },
+      ],
+    });
+
+    const body = await (await app.request(MODULE_UI_INVENTORY_PATH)).text();
+
+    expect(body).not.toContain("example");
+    expect(body).not.toContain("calendar");
+  });
+
+  it("admits any signed-in user without needing an explicit grant", async () => {
+    // `core.modules.ui.read` is baseline `authenticated`, so being signed in is enough — a shell
+    // that rendered nothing until an operator granted every user a permission would be unusable.
+    const { app } = await install({
+      fixtures: [{ id: "example", withUi: true }],
+      grants: [],
+      principal: signedIn(),
+      platformOwner: false,
+    });
+
+    expect((await app.request(MODULE_UI_INVENTORY_PATH)).status).toBe(200);
+  });
+
+  it("is never cached and varies on the caller's identity", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", withUi: true }],
+      principal: signedIn(),
+    });
+
+    const response = await app.request(MODULE_UI_INVENTORY_PATH, {
+      headers: { origin: trustedOrigin },
+    });
+
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    const vary = response.headers.get("vary")?.toLowerCase() ?? "";
+    expect(vary).toContain("origin");
+    expect(vary).toContain("cookie");
+  });
+});
+
+describe("module UI inventory — permission hints", () => {
+  const readPermission = { baseline: "restricted" as const, id: "example.records.read" };
+  const writePermission = { baseline: "restricted" as const, id: "example.records.write" };
+
+  it("returns only the permissions the server actually granted this principal", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", permissions: [readPermission, writePermission], withUi: true }],
+      grants: ["example.records.read"],
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    expect(modules[0]?.permissions).toEqual(["example.records.read"]);
+  });
+
+  it("returns none of them for a signed-in user holding no grant", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", permissions: [readPermission, writePermission], withUi: true }],
+      grants: [],
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    // Never a default of true, and never the module's full declared surface.
+    expect(modules[0]?.permissions).toEqual([]);
+  });
+
+  it("honours a baseline that needs no grant at all", async () => {
+    const { app } = await install({
+      fixtures: [
+        {
+          id: "example",
+          permissions: [{ baseline: "authenticated", id: "example.records.list" }, readPermission],
+          withUi: true,
+        },
+      ],
+      grants: [],
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    expect(modules[0]?.permissions).toEqual(["example.records.list"]);
+  });
+
+  it("honours the platform-owner bypass, exactly like a real request would", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", permissions: [readPermission, writePermission], withUi: true }],
+      grants: [],
+      platformOwner: true,
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    expect(modules[0]?.permissions).toEqual(["example.records.read", "example.records.write"]);
+  });
+
+  it("scopes hints to each module's own declared permissions", async () => {
+    const { app } = await install({
+      fixtures: [
+        { id: "example", permissions: [readPermission], withUi: true },
+        {
+          id: "calendar",
+          permissions: [{ baseline: "restricted", id: "calendar.events.read" }],
+          withUi: true,
+        },
+      ],
+      grants: ["example.records.read", "calendar.events.read"],
+      principal: signedIn(),
+    });
+
+    const { modules } = await inventoryOf(app);
+
+    const byId = new Map(modules.map((module) => [module.id, module.permissions]));
+    // Neither module learns anything about the other's authorization state, and neither is told
+    // about Core's own permissions.
+    expect(byId.get("example")).toEqual(["example.records.read"]);
+    expect(byId.get("calendar")).toEqual(["calendar.events.read"]);
+    expect(JSON.stringify(modules)).not.toContain("core.authorization.grants.manage");
+    expect(JSON.stringify(modules)).not.toContain("core.modules.ui.read");
+  });
+
+  it("reports an evaluation outage as unavailable rather than as 'nothing granted'", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", permissions: [readPermission], withUi: true }],
+      grantsUnavailable: true,
+      principal: signedIn(),
+    });
+
+    const response = await app.request(MODULE_UI_INVENTORY_PATH);
+
+    // A hint that silently read "denied" during an outage would blank the UI and look like a
+    // permissions problem.
+    expect(response.status).toBe(503);
+    expect(await response.json()).toEqual({ code: "AUTHORIZATION_EVALUATION_FAILED" });
+  });
+});
+
+describe("module UI inventory — it is not a module management API", () => {
+  it("routes no method other than GET", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", withUi: true }],
+      principal: signedIn(),
+    });
+
+    for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
+      const response = await app.request(MODULE_UI_INVENTORY_PATH, { method });
+      expect(response.status, method).toBe(404);
+      expect(await response.json(), method).toEqual({ code: "NOT_FOUND" });
+    }
+  });
+
+  it("still refuses to serve an artifact under the collection path", async () => {
+    const { app } = await install({
+      fixtures: [{ id: "example", withUi: true }],
+      principal: signedIn(),
+    });
+
+    for (const suffix of ["/example", "/example/", "/example/0.1.0/index.js"]) {
+      const response = await app.request(`${MODULE_UI_INVENTORY_PATH}${suffix}`);
+      expect(response.status, suffix).toBe(404);
+    }
+  });
+});

apps/api/tests/module-ui-routes.test.ts

@@ -440,9 +440,10 @@ describe("module UI artifact publication — filesystem exposure", () => {
       // A trailing segment of any kind, including an empty one.
       `${base}/0.1.0/`,
       `${base}/0.1.0/anything`,
-      // Fewer segments than the route declares.
+      // Fewer segments than the route declares. The collection root itself is deliberately absent
+      // from this list: it is the authenticated inventory (ADR 0026) rather than a 404, and is
+      // asserted separately below.
       base,
-      MODULE_UI_ASSET_PREFIX,
     ];
 
     for (const url of unreachable) {
@@ -456,6 +457,21 @@ describe("module UI artifact publication — filesystem exposure", () => {
     }
   });
 
+  it("serves no artifact bytes from the collection root, which is the authenticated inventory", async () => {
+    const { app } = await installWithNeighbours();
+
+    // `/api/v1/module-ui` lists what a host may mount (ADR 0026) and requires
+    // `core.modules.ui.read`; this installation's caller is anonymous, so it is refused. Either way
+    // it never yields a byte of any artifact or neighbouring file.
+    const response = await app.request(MODULE_UI_ASSET_PREFIX);
+    const body = await response.text();
+
+    expect(response.status).toBe(403);
+    expect(body).not.toContain("mount");
+    expect(body).not.toContain("secret");
+    expect(body).not.toContain("internal");
+  });
+
   it("treats a traversal attempt as an ordinary failed lookup", async () => {
     const { app } = await installWithNeighbours();