ADR 0021 established that a module may own UI and added a statically
validated, never-executed `entrypoints.ui` path, but deliberately left
five questions open: what the artifact exports, what a host provides,
how one artifact runs under both Ekklesia and a standalone host, what
the browser-side trust model is, and how module UI avoids being welded
to a Dashboard that does not exist. This answers them.
React and TypeScript are the supported module UI authoring model. The
repository already leaned this way: `packages/typescript-config` ships a
`browser.json` preset and a `react-native.json` preset with
`"jsx": "react-jsx"`, and ADR 0002 names browser and React Native
configurations. One framework is supported; every other stays rejected.
React is deliberately not part of the contract. A module's compiled
artifact default-exports `defineModuleUi({ id, version, mount })`, and
`mount(container, context)` takes a DOM element and returns an unmount
function. `id` and `version` are build-artifact identity markers a host
verifies against the manifest, mirroring `defineModuleRuntime` exactly.
A host needs an element and a context, never a matching rendering
library, so a module's framework, a host's framework, and the platform
boundary between them stay independent.
The contract lives in a new `@ekklesia/module-ui-sdk` rather than in
`@ekklesia/module-sdk`, for a concrete reason: that package re-exports
all of `@ekklesia/contracts`, so routing module UI through it would drag
Zod, Drizzle, and semver into every browser bundle. The new package has
no runtime dependencies, and its one dependency on contracts is
type-only — the emitted `host-context.js` is `export {};`, and a test
pins that so it cannot regress.
The host context is four members: `moduleId`, `api`, `principal`, and
`permissions`. Navigation, theme, module configuration, organization
context, and diagnostics are deliberately absent; each needs a design
that does not exist. Module UI reaches its backend through
`api.request(path)` with a path relative to its own API root and never
constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private
deployment detail — a module that builds that URL is silently unhostable
anywhere else. One fixture artifact is mounted under two hosts with
different origins and URL shapes to prove it.
Client-side permission hints are presentation only, and both the docs
and a test say so plainly: a denied hint does not stop the module from
calling its API, because server-side `requirePermission` is the only
authority. Module UI is trusted code in the host's own browser realm —
no iframe, no sandbox — which matches the backend model rather than
overstating it, since a module's server half already holds the API's
database authority.
The boundary guard is narrowed precisely, not removed: `.tsx`, `react`,
and `react-dom` are un-denied and modules may depend on the new
`module-ui-sdk` role. `.jsx`, `.css`, every other framework,
`react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay
denied, layer rules are untouched, and an unsupported framework aliased
behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected
by its real target. Fixtures prove each case, including that module UI
source still cannot import Core.
Core, apps/api, and the manifest contract are untouched. Discovery still
validates the `entrypoints.ui` path and never evaluates it; hosts
perform their own dynamic import and validate the result with
`parseModuleUiExport`. No Dashboard shell, UI runtime, navigation,
grouping, standalone host, build or styling pipeline, installer,
hot-loading, or feature module is added.
Co-Authored-By: Claude Opus 5 <[email protected]>
Three advisory paths, closed with the narrowest scoped overrides rather than a
broad upgrade. Each raises exactly the one edge that resolved a vulnerable
version, and each pins an exact release.
PostCSS 8.5.17 (GHSA-r28c-9q8g-f849, high) was reached only through Vite, which
better-auth pulls in via Vitest, and Vite 8.1.4's own range still resolved the
vulnerable version. `vite>postcss` now resolves 8.5.24; one version in the tree.
esbuild 0.18.20 (GHSA-67mh-4wv8-2f99, moderate) was reached only through the
deprecated @esbuild-kit/core-utils, whose pinned range predates the fix. Scoped
to `@esbuild-kit/core-utils>esbuild` on purpose: drizzle-kit already resolved
esbuild 0.25.12 directly and tsx/vite resolve 0.28.1, so a global override would
have dragged those newer, unaffected versions backwards. The vulnerable version
is gone and 0.28.1 is preserved.
Lodash 4.17.21 (GHSA-r5fr-rjxr-66jc high, GHSA-f23m-r3pf-42rh and
GHSA-xxjr-mmjv-4gpg moderate) was reached only through the development-time
Better Auth `auth` CLI's Prisma parser. All three chevrotain packages pin lodash
to exactly 4.17.21, so no in-range release is patched, and the advisories
require >= 4.17.24 — a version the 4.17.x line never published. 4.18.1 is the
lowest fixed release; the override crosses chevrotain's exact pin for that
reason. Verified compatible before applying: 4.18.1 keeps the per-method
CommonJS subpath files chevrotain requires (`lodash/assign`, `lodash/isRegExp`,
and the rest), with the same `main` and no restrictive `exports` field.
Both `pnpm audit --prod` and the full `pnpm audit` now report no known
vulnerabilities, with no ignore, allowlist, or audit-level suppression.
Proven, not assumed: `pnpm install --frozen-lockfile` succeeds; the Better Auth
schema generator still matches the checked-in identity schema, which exercises
the very chevrotain/lodash path that was overridden; drizzle-kit loads the real
config and reports no schema changes against a scratch copy, leaving tracked
migration artifacts untouched; the three Core migrations keep their exact
checksums; and the whole unit and PostgreSQL integration suites stay green.
Co-Authored-By: Claude Opus 5 <[email protected]>
Adds Core-owned identity contracts, a Core-owned Better Auth database schema
(ekklesia_core_user/session/account/verification), a first-class Core-owned
migration source that coexists with module-owned migrations under the exact
existing migration system, and an explicit Better Auth construction boundary.
No authentication endpoint or sign-in UI is exposed yet (ADR 0010).
Co-Authored-By: Claude Sonnet 5 <[email protected]>
