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]>

surfaces/shell/src/module-context.ts

@@ -0,0 +1,104 @@
+import type {
+  ModuleUiApiClient,
+  ModuleUiHostContext,
+  ModuleUiPrincipal,
+} from "@ekklesia/module-ui-sdk";
+import {
+  type EkklesiaHostConfig,
+  type HostModuleUiDescriptor,
+  HostProtocolError,
+  resolveApiUrl,
+} from "./host-protocol.js";
+
+const ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/u;
+
+/**
+ * Turns the relative path a module UI asks for into the real Ekklesia URL, and refuses anything
+ * that is not the module's own API.
+ *
+ * `context.api.request("records")` becomes `<origin>/api/v1/modules/<module-id>/records`. The
+ * `/api/v1/modules/<module-id>` half is **not** written here: it arrives from the server in the
+ * inventory descriptor (`apiBaseUrl`), so Ekklesia's module mount prefix is spelled in exactly one
+ * place in the whole repository (`moduleApiBaseUrl`, `apps/api/src/module-http-routes.ts`). The
+ * browser is a consumer of that URL, never a second author of it.
+ *
+ * Containment is enforced with the URL parser rather than string inspection, because the parser is
+ * what a real `fetch` would use: `"../calendar/records"` normalizes to another module's API, and a
+ * check that only looked at the input string would miss it. Anything that resolves outside this
+ * module's own root — a traversal, a protocol-relative `//host`, an absolute URL, an encoded
+ * separator — is refused with `MODULE_API_PATH_INVALID`.
+ *
+ * This is a portability boundary, not a security one. Module UI is trusted same-realm code (ADR
+ * 0022) and could call `fetch` directly; refusing here is what keeps a module honest about
+ * addressing only its own backend, so the same artifact still runs under a standalone host. Server
+ * authorization is unaffected either way: every module route stays behind `requirePermission`.
+ */
+function createModuleApiClient(
+  config: EkklesiaHostConfig,
+  descriptor: HostModuleUiDescriptor,
+): ModuleUiApiClient {
+  const performRequest = config.fetch ?? fetch;
+  const moduleRoot = new URL(resolveApiUrl(config, descriptor.apiBaseUrl));
+
+  return Object.freeze({
+    async request(path: string, init?: RequestInit): Promise<Response> {
+      if (ABSOLUTE_URL_PATTERN.test(path) || path.startsWith("//")) {
+        throw new HostProtocolError("MODULE_API_PATH_INVALID");
+      }
+      const relative = path.replace(/^\/+/u, "");
+      const target = new URL(
+        relative === "" ? moduleRoot.pathname : `${moduleRoot.pathname}/${relative}`,
+        moduleRoot,
+      );
+      const contained =
+        target.origin === moduleRoot.origin &&
+        (target.pathname === moduleRoot.pathname ||
+          target.pathname.startsWith(`${moduleRoot.pathname}/`));
+      if (!contained) {
+        throw new HostProtocolError("MODULE_API_PATH_INVALID");
+      }
+      // The module's own `init` is forwarded whole — method, headers, body, signal — and only
+      // `credentials` is imposed, because session handling is the host's job and a module UI never
+      // sees or supplies a token (ADR 0022). A module cannot opt out of it.
+      return performRequest(target.href, { ...init, credentials: "include" });
+    },
+  });
+}
+
+export interface CreateModuleUiContextOptions {
+  readonly config: EkklesiaHostConfig;
+  readonly descriptor: HostModuleUiDescriptor;
+  readonly principal: ModuleUiPrincipal;
+}
+
+/**
+ * Builds the `ModuleUiHostContext` (ADR 0022) Ekklesia hands a module UI at mount time.
+ *
+ * All four members come from server-derived data: the module id and API root from the inventory
+ * descriptor, the principal from `/api/v1/principal`, and the permission hints from the server's own
+ * evaluation of that module's declared permissions against that principal. Nothing is guessed,
+ * defaulted to `true`, or inferred from a client-side role name.
+ *
+ * The permission set is the module's own and only the module's own. A module UI cannot use this to
+ * discover what the viewer may do elsewhere in the platform, and `has` returning `true` is a
+ * statement about what the server said a moment ago — a hint for hiding a control, never a
+ * substitute for the server check that actually decides.
+ */
+export function createModuleUiContext(options: CreateModuleUiContextOptions): ModuleUiHostContext {
+  const granted = new Set(options.descriptor.permissions);
+  return Object.freeze({
+    api: createModuleApiClient(options.config, options.descriptor),
+    moduleId: options.descriptor.id,
+    permissions: Object.freeze({ has: (permissionId: string) => granted.has(permissionId) }),
+    principal: options.principal,
+  });
+}
+
+/** The absolute URL the generic loader should import this module's artifact from — the descriptor's
+ * server-produced path resolved against the configured API origin, and nothing more. */
+export function moduleUiSourceUrl(
+  config: EkklesiaHostConfig,
+  descriptor: HostModuleUiDescriptor,
+): string {
+  return resolveApiUrl(config, descriptor.uiUrl);
+}