feat: define module database access

Introduce ModuleDatabase (a typed, restricted Drizzle query surface) and the frozen ModuleRuntimeServices boundary in @ekklesia/contracts, and thread the same services object through Core's module start/stop lifecycle hooks and apps/api's authorized module HTTP handler context. apps/api builds the facade via a new core/src/modules/database.ts view (createModuleDatabaseView) over the one existing shared PostgreSQL pool, alongside the identity and authorization views, and wires it into startApi's fixed startup order ahead of Identity/Authorization construction. Registration stays database-free; a module reaches its database only through an authorized start, stop, or HTTP handler invocation.
2026-07-25 20:57:32 -05:00
parent 9c9ede0418
commit 0e308eb9ad
17 changed files with 702 additions and 51 deletions
@@ -1,4 +1,9 @@
-import { ANONYMOUS_PRINCIPAL, createAuthenticatedPrincipal } from "@ekklesia/contracts";
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  type ModuleDatabase,
+  type ModuleRuntimeServices,
+} from "@ekklesia/contracts";
 import {
  type AuthorizationEvaluator,
  type AuthorizationStore,
@@ -21,6 +26,22 @@ function fakeRuntime(overrides: Partial<EkklesiaIdentityRuntime> = {}): Ekklesia
  };
 }

+/** A small typed fake `ModuleRuntimeServices` — these tests exercise `createApiApp`'s own wiring,
+ * never real database behavior, so no PostgreSQL is required. */
+function fakeModuleServices(): ModuleRuntimeServices {
+  const database = Object.freeze({
+    delete: vi.fn(),
+    execute: vi.fn(),
+    insert: vi.fn(),
+    select: vi.fn(),
+    selectDistinct: vi.fn(),
+    selectDistinctOn: vi.fn(),
+    transaction: vi.fn(),
+    update: vi.fn(),
+  }) as unknown as ModuleDatabase;
+  return Object.freeze({ database });
+}
+
 /** A fully stubbed authorization dependency, denying everything by default — tests that need a
 * specific decision or store behavior override the relevant method explicitly. The registry
 * defaults to Core's own (containing `core.authorization.grants.manage`, exactly what the
@@ -53,6 +74,7 @@ describe("Ekklesia API Hono application", () => {
    const runtime = fakeRuntime();
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -69,6 +91,7 @@ describe("Ekklesia API Hono application", () => {
    const runtime = fakeRuntime();
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -86,6 +109,7 @@ describe("Ekklesia API Hono application", () => {
    });
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -105,6 +129,7 @@ describe("Ekklesia API Hono application", () => {
    });
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -126,6 +151,7 @@ describe("Ekklesia API Hono application", () => {
    });
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -147,6 +173,7 @@ describe("Ekklesia API Hono application", () => {
    });
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -165,6 +192,7 @@ describe("Ekklesia API Hono application", () => {
    });
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime,
      trustedOrigins: [trustedOrigin],
@@ -182,6 +210,7 @@ describe("Ekklesia API Hono application", () => {
  it("has deterministic 404 behavior for an unknown route", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -196,6 +225,7 @@ describe("Ekklesia API Hono application", () => {
  it("reflects an allowed origin in Access-Control-Allow-Origin with credentials support", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -212,6 +242,7 @@ describe("Ekklesia API Hono application", () => {
  it("never returns Access-Control-Allow-Origin for a disallowed origin", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -227,6 +258,7 @@ describe("Ekklesia API Hono application", () => {
  it("supports requests with no Origin header at all (native/server clients)", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -240,6 +272,7 @@ describe("Ekklesia API Hono application", () => {
  it("handles preflight OPTIONS requests deterministically for an allowed origin", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -260,6 +293,7 @@ describe("Ekklesia API Hono application", () => {
  it("never wildcards Access-Control-Allow-Origin", async () => {
    const app = createApiApp({
      moduleRoutes: Object.freeze([]),
+      moduleServices: fakeModuleServices(),
      authorization: fakeAuthorization({}),
      runtime: fakeRuntime(),
      trustedOrigins: [trustedOrigin],
@@ -283,6 +317,7 @@ describe("Ekklesia API Hono application", () => {
      const evaluatorAuthorize = vi.fn().mockResolvedValue({ allowed: false });
      const app = createApiApp({
        moduleRoutes: Object.freeze([]),
+        moduleServices: fakeModuleServices(),
        authorization: fakeAuthorization({ evaluator: { authorize: evaluatorAuthorize } }),
        runtime: fakeRuntime(),
        trustedOrigins: [trustedOrigin],
@@ -309,6 +344,7 @@ describe("Ekklesia API Hono application", () => {
      };
      const app = createApiApp({
        moduleRoutes: Object.freeze([]),
+        moduleServices: fakeModuleServices(),
        authorization: fakeAuthorization({
          evaluator: { authorize: evaluatorAuthorize },
          registry: emptyRegistry,
@@ -326,6 +362,7 @@ describe("Ekklesia API Hono application", () => {
    it("applies the same CORS policy to /api/v1/grants as the rest of /api/v1/*", async () => {
      const app = createApiApp({
        moduleRoutes: Object.freeze([]),
+        moduleServices: fakeModuleServices(),
        authorization: fakeAuthorization({}),
        runtime: fakeRuntime(),
        trustedOrigins: [trustedOrigin],
@@ -111,6 +111,19 @@ function createEventRecorder(): { events: string[]; expression: string } {
  return { events, expression: `globalThis[Symbol.for(${JSON.stringify(key)})]` };
 }

+/** Same globalThis-symbol technique as `createEventRecorder`, but captures an actual object
+ * reference (such as `context.services.database`) rather than a string label, so a test can prove
+ * two values pushed from different, independently dynamically-imported invocations (a module's own
+ * `start` hook and one of its HTTP handlers) are the exact same object. */
+function createReferenceRecorder(): { values: unknown[]; expression: string } {
+  const key = `ekklesia.api.lifecycle.test.ref.${eventSymbols.length}.${Date.now()}.${Math.random()}`;
+  const symbol = Symbol.for(key);
+  const values: unknown[] = [];
+  (globalThis as unknown as Record<PropertyKey, unknown>)[symbol] = values;
+  eventSymbols.push(symbol);
+  return { values, expression: `globalThis[Symbol.for(${JSON.stringify(key)})]` };
+}
+
 interface WorkingFixtureModuleOptions {
  /** Declares one `GET /ping` route against `<id>.ping.read` when true. */
  readonly withRoute?: boolean;
@@ -659,6 +672,47 @@ describe("Ekklesia API module runtime startup and shutdown", () => {
    await running.shutdown();
  });

+  it("gives a module's HTTP handler the exact same database facade object its own start hook received", async () => {
+    const modulesDirectory = await createTemporaryModulesDirectory();
+    const refs = createReferenceRecorder();
+    await createFixtureModule(modulesDirectory, "db-identity", {
+      permissions: [{ baseline: "public", description: "Ping.", id: "db-identity.ping.read" }],
+    });
+    await writeFile(
+      path.join(modulesDirectory, "db-identity", "dist/server/index.js"),
+      `export default {
+        id: "db-identity",
+        version: "0.1.0",
+        register({ http }) {
+          http.route({
+            method: "GET",
+            path: "/ping",
+            permission: "db-identity.ping.read",
+            handler: async (_request, context) => {
+              ${refs.expression}.push(context.services.database);
+              return new Response(null, { status: 204 });
+            },
+          });
+        },
+        start(context) {
+          ${refs.expression}.push(context.services.database);
+        }
+      };`,
+    );
+    mockPoolAndAuth();
+    mockSuccessfulServe();
+
+    const running = await startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory });
+    const response = await running.app.request("/api/v1/modules/db-identity/ping");
+
+    expect(response.status).toBe(204);
+    expect(refs.values).toHaveLength(2);
+    expect(refs.values[0]).toBeDefined();
+    expect(refs.values[0]).toBe(refs.values[1]);
+
+    await running.shutdown();
+  });
+
  it("closes the pool exactly once and binds no server when a module's entrypoint fails to load", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    await createFixtureModule(modulesDirectory, "broken-export");
@@ -789,6 +843,31 @@ describe("Ekklesia API module runtime startup and shutdown", () => {
    expect(recorder.events).toEqual(["server:close", "ordered:stop", "pool:end"]);
  });

+  it("gives a module's stop hook the exact same database facade object its start hook received, while the pool is still open", async () => {
+    const modulesDirectory = await createTemporaryModulesDirectory();
+    const refs = createReferenceRecorder();
+    await createFixtureModule(modulesDirectory, "db-stop-identity");
+    await writeFile(
+      path.join(modulesDirectory, "db-stop-identity", "dist/server/index.js"),
+      `export default {
+        id: "db-stop-identity",
+        version: "0.1.0",
+        start(context) { ${refs.expression}.push(context.services.database); },
+        stop(context) { ${refs.expression}.push(context.services.database); }
+      };`,
+    );
+    const { poolEnd } = mockPoolAndAuth();
+    mockSuccessfulServe();
+
+    const running = await startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory });
+    await running.shutdown();
+
+    expect(refs.values).toHaveLength(2);
+    expect(refs.values[0]).toBeDefined();
+    expect(refs.values[0]).toBe(refs.values[1]);
+    expect(poolEnd).toHaveBeenCalledTimes(1);
+  });
+
  it("still runs pool cleanup and lets the shutdown rejection surface when the module runtime fails to stop", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    const recorder = createEventRecorder();
@@ -1,8 +1,10 @@
 import {
  ANONYMOUS_PRINCIPAL,
  createAuthenticatedPrincipal,
+  type ModuleDatabase,
  type ModuleRouteHandler,
  type ModuleRouteHandlerContext,
+  type ModuleRuntimeServices,
  parsePermissionId,
  type PermissionId,
  type RegisteredModuleHttpRoute,
@@ -51,24 +53,56 @@ function moduleRoute(fields: RegisteredModuleHttpRoute): RegisteredModuleHttpRou
  return Object.freeze({ ...fields });
 }

+/** A small typed fake `ModuleRuntimeServices` — these tests exercise route mounting,
+ * authorization, and response sanitization, never real database behavior, so no PostgreSQL is
+ * required. Each `database` method stays a distinct spy so a test can assert none of them were
+ * ever called (denied, trusted-origin-rejected, and `OPTIONS` requests never reach a handler). */
+function fakeModuleServices(): ModuleRuntimeServices {
+  const database = Object.freeze({
+    delete: vi.fn(),
+    execute: vi.fn(),
+    insert: vi.fn(),
+    select: vi.fn(),
+    selectDistinct: vi.fn(),
+    selectDistinctOn: vi.fn(),
+    transaction: vi.fn(),
+    update: vi.fn(),
+  }) as unknown as ModuleDatabase;
+  return Object.freeze({ database });
+}
+
+function expectDatabaseFakeUntouched(services: ModuleRuntimeServices): void {
+  expect(vi.mocked(services.database.select)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.selectDistinct)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.selectDistinctOn)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.insert)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.update)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.delete)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.execute)).not.toHaveBeenCalled();
+  expect(vi.mocked(services.database.transaction)).not.toHaveBeenCalled();
+}
+
 function buildModuleApp(options: {
  readonly evaluator?: AuthorizationEvaluator;
  readonly registry: PermissionRegistry;
  readonly routes: readonly RegisteredModuleHttpRoute[];
  readonly runtime?: EkklesiaIdentityRuntime;
+  readonly services?: ModuleRuntimeServices;
  readonly trustedOrigins?: readonly string[];
 }) {
  const evaluator = options.evaluator ?? {
    authorize: vi.fn().mockResolvedValue({ allowed: true }),
  };
  const runtime = options.runtime ?? fakeRuntime();
+  const services = options.services ?? fakeModuleServices();
  const app = createApiApp({
    authorization: { evaluator, registry: options.registry, store: fakeStore() },
    moduleRoutes: options.routes,
+    moduleServices: services,
    runtime,
    trustedOrigins: options.trustedOrigins ?? [trustedOrigin],
  });
-  return { app, evaluator, runtime };
+  return { app, evaluator, runtime, services };
 }

 function permissionRegistry(
@@ -262,6 +296,7 @@ describe("module route handler adaptation", () => {
    const runtime = fakeRuntime({
      resolvePrincipal: vi.fn().mockResolvedValue(createAuthenticatedPrincipal("user_1")),
    });
+    const services = fakeModuleServices();
    const { app } = buildModuleApp({
      registry: permissionRegistry([{ id: readPermission, baseline: "public" }]),
      routes: [
@@ -274,6 +309,7 @@ describe("module route handler adaptation", () => {
        }),
      ],
      runtime,
+      services,
    });

    const response = await app.request("/api/v1/modules/calendar/events/evt-1/rsvp?notify=true", {
@@ -288,13 +324,25 @@ describe("module route handler adaptation", () => {
    expect(body.url).toContain("/api/v1/modules/calendar/events/evt-1/rsvp?notify=true");
    expect(capturedRequest).toBeInstanceOf(Request);
    expect(capturedRequest?.headers.get("x-custom")).toBe("abc");
-    expect(capturedContext).toEqual({
+    // Exactly moduleId, params, principal, services — never a Hono Context, authorization store,
+    // or configuration reaches a module handler.
+    expect(Object.keys(capturedContext ?? {}).sort()).toEqual([
+      "moduleId",
+      "params",
+      "principal",
+      "services",
+    ]);
+    expect(capturedContext).toMatchObject({
      moduleId: "calendar",
      params: { eventId: "evt-1" },
      principal: { kind: "authenticated", userId: "user_1" },
    });
+    // Reference-identical to the exact services object the caller passed in — never a fresh one
+    // built per request.
+    expect(capturedContext?.services).toBe(services);
    expect(Object.isFrozen(capturedContext)).toBe(true);
    expect(Object.isFrozen(capturedContext?.params)).toBe(true);
+    expect(Object.isFrozen(capturedContext?.services)).toBe(true);
  });

  it("gives static and root routes a frozen, empty params object", async () => {
@@ -394,12 +442,12 @@ describe("module route authorization", () => {
    );
  });

-  it("does not invoke the handler when authorization denies", async () => {
+  it("does not invoke the handler or touch the module database when authorization denies", async () => {
    const handler = vi.fn<ModuleRouteHandler>(async () => Response.json({ ok: true }));
    const evaluator: AuthorizationEvaluator = {
      authorize: vi.fn().mockResolvedValue({ allowed: false }),
    };
-    const { app } = buildModuleApp({
+    const { app, services } = buildModuleApp({
      evaluator,
      registry: permissionRegistry([{ id: readPermission, baseline: "restricted" }]),
      routes: [
@@ -417,6 +465,7 @@ describe("module route authorization", () => {
    expect(response.status).toBe(403);
    expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
    expect(handler).not.toHaveBeenCalled();
+    expectDatabaseFakeUntouched(services);
  });

  it("does not invoke the handler when principal resolution fails", async () => {
@@ -518,7 +567,7 @@ describe("module route trusted-origin enforcement", () => {
      authorize: vi.fn().mockResolvedValue({ allowed: true }),
    };
    const methods = ["POST", "PUT", "PATCH", "DELETE"] as const;
-    const { app } = buildModuleApp({
+    const { app, services } = buildModuleApp({
      evaluator,
      registry: permissionRegistry([{ id: writePermission, baseline: "public" }]),
      routes: methods.map((method) =>
@@ -545,6 +594,7 @@ describe("module route trusted-origin enforcement", () => {
    }
    expect(handler).not.toHaveBeenCalled();
    expect(evaluator.authorize).not.toHaveBeenCalled();
+    expectDatabaseFakeUntouched(services);
  });

  it("allows a trusted-origin state-changing request through to the handler", async () => {
@@ -647,12 +697,12 @@ describe("module route CORS", () => {
    expect(tokens.filter((token) => token.toLowerCase() === "origin")).toHaveLength(1);
  });

-  it("never invokes authorization or the handler for an OPTIONS preflight", async () => {
+  it("never invokes authorization, the handler, or the module database for an OPTIONS preflight", async () => {
    const handler = vi.fn<ModuleRouteHandler>(async () => Response.json({ ok: true }));
    const evaluator: AuthorizationEvaluator = {
      authorize: vi.fn().mockResolvedValue({ allowed: true }),
    };
-    const { app } = buildModuleApp({
+    const { app, services } = buildModuleApp({
      evaluator,
      registry: permissionRegistry([{ id: writePermission, baseline: "public" }]),
      routes: [
@@ -673,6 +723,7 @@ describe("module route CORS", () => {

    expect(handler).not.toHaveBeenCalled();
    expect(evaluator.authorize).not.toHaveBeenCalled();
+    expectDatabaseFakeUntouched(services);
  });

  it("never reflects an untrusted origin for a module route", async () => {