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]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
7a76ff6f26
commit
616c1d4834
@@ -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();
|
||||
}
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user