feat: add Dashboard navigation as presentation configuration
Phase 6D pass 1. The shell's navigation was a flat list of module ids, which is not a usable experience — and the obvious fix carries an obvious trap. Letting a module declare its folder, or modelling "Media" as something Livestream and Video belong to, turns a rendering preference into architecture: a folder becomes an owner, membership starts to look like a dependency, and the flat module graph acquires a hierarchy nobody decided on. So the rule comes first: a Dashboard group is a label on a rendering bucket. No manifest, no version, no artifact, no API, no lifecycle; nothing depends on it. Livestream depends on Video because it calls Video's functionality, and that orders startup. Livestream is shown under Media, and that orders nothing. No parent module, child module, owning module, or group-derived dependency appears anywhere in the contracts. No manifest change and no version 5. `manifest.name` has been required since version 1 and already is the module's product identity, so the shell renders "Livestream" instead of `livestream` with nothing added. `suggestedGroup` is deliberately deferred rather than shipped: it would force a hard manifest-version cutover for a hint, and its only correct semantics needs initialization logic that risks a suggestion overwriting an administrator's decision. Defaulting and ownership are different things. Two Core tables (migration 0003) hold groups and placements — server-side, because a church configures its Dashboard rather than one browser; platform-global, because no organization model exists to scope them to. `group_id` is `on delete set null`, so deleting a group ungroups its modules and a dangling reference is impossible. `module_id` carries no foreign key, because modules are packages rather than rows, so a placement for an uninstalled module is retained and restores its position on reinstall. `resolveDashboardNavigation` is a pure function of configuration plus the mountable set: an unplaced module is ungrouped and visible with no initialization write, an absent module renders nothing, empty groups are kept, and ordering is total with the module id as final tie-break. `GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of the host-neutral module UI inventory rather than merged into it — each generic descriptor is embedded untouched, so a standalone host never inherits Dashboard semantics. Reading needs the permission the inventory already needs; organizing needs the new platform permission `core.dashboard.navigation.manage` through a narrow, idempotent, closed-validation mutation contract. No editor UI. The flatness rule is executable: a test discovers real fixtures with a genuine dependency, arranges them four ways including both in one folder and the dependency inverted in presentation, and asserts discovery order, dependency declarations, and the module set stay byte-identical. The end-to-end test organizes a real installation through the real API, mounts a module from inside a group, moves it, and asserts the navigation entry is byte-identical across the move and still mounts the same artifact. The shell's client for the generic inventory became dead code and was removed rather than kept speculatively; the endpoint itself is unchanged. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
ac5b2b7f6c
commit
bd34c9c714
@@ -77,6 +77,8 @@ No real values are shown here — configure per environment and never commit the
|
||||
| `GET\|POST /api/v1/grants*` | Ekklesia | Explicit authorization grant management, gated by `core.authorization.grants.manage`. Listing is bounded keyset pagination; creation is unscoped-only and conflicts (`409`) on an equivalent effective grant; revocation clears every unrevoked equivalent. See [Authorization](authorization.md#explicit-grant-http-api). |
|
||||
| `/api/v1/modules/<module-id>/*` | Installed modules | Every route an installed module registered during its `register` hook, gated by that route's own declared permission. See [Module HTTP routes](#module-http-routes). |
|
||||
| `GET /api/v1/module-ui` | Ekklesia | The browser host's module UI inventory: which module UIs may be mounted, where to fetch each, where each module's API lives, and the viewer's granted permissions for it. Requires `core.modules.ui.read` (baseline `authenticated`). See [Module UI inventory](#module-ui-inventory). |
|
||||
| `GET /api/v1/dashboard/navigation` | Ekklesia | The resolved Dashboard navigation: the same mountable modules, grouped, labelled, and ordered as this installation has configured them. Requires `core.modules.ui.read`. See [Dashboard navigation](#dashboard-navigation). |
|
||||
| `PUT\|DELETE /api/v1/dashboard/navigation/{groups,placements}/*` | Ekklesia | Organize the Dashboard: create/rename/order/delete a group, and place a module. Requires `core.dashboard.navigation.manage` (baseline `restricted`) and a trusted `Origin`. See [Dashboard navigation](#dashboard-navigation). |
|
||||
| `GET /api/v1/module-ui/<module-id>/<version>` | Ekklesia | Publishes an installed module's validated `entrypoints.ui` artifact at a browser-loadable URL. No authentication; only the declared artifact, never another file. See [Module UI asset publication](#module-ui-asset-publication). |
|
||||
|
||||
Better Auth's handler is unreachable outside `/api/auth/*`; every other unmatched path returns a
|
||||
@@ -452,6 +454,94 @@ are mounted under `/api/v1/modules/<module-id>`, in the module runtime's publish
|
||||
registry: installing, removing, or editing a module's routes takes effect only on the next API
|
||||
restart. Removing a module makes its former routes return the ordinary `404 {"code":"NOT_FOUND"}`.
|
||||
|
||||
## Dashboard navigation
|
||||
|
||||
```text
|
||||
GET /api/v1/dashboard/navigation
|
||||
PUT /api/v1/dashboard/navigation/groups/<group-id> { "label": "Media", "order": 10 }
|
||||
DELETE /api/v1/dashboard/navigation/groups/<group-id>
|
||||
PUT /api/v1/dashboard/navigation/placements/<module-id> { "groupId": "media"|null, "order": 10 }
|
||||
```
|
||||
|
||||
How this installation presents its mountable modules
|
||||
([ADR 0027](../architecture/decisions/0027-dashboard-navigation-and-flat-modules.md)).
|
||||
|
||||
```json
|
||||
{
|
||||
"groups": [
|
||||
{
|
||||
"id": "media",
|
||||
"label": "Media",
|
||||
"order": 10,
|
||||
"modules": [
|
||||
{
|
||||
"name": "Livestream",
|
||||
"module": {
|
||||
"id": "livestream",
|
||||
"version": "1.0.0",
|
||||
"ui": { "url": "/api/v1/module-ui/livestream/1.0.0" },
|
||||
"api": { "baseUrl": "/api/v1/modules/livestream" },
|
||||
"permissions": ["livestream.streams.read"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"ungrouped": []
|
||||
}
|
||||
```
|
||||
|
||||
### Navigation versus inventory
|
||||
|
||||
They are deliberately separate, and this route is layered **on top of** the inventory rather than
|
||||
merged into it:
|
||||
|
||||
- `GET /api/v1/module-ui` answers *what may be mounted*, host-neutrally. A standalone host consumes
|
||||
it and never learns Ekklesia has folders. It carries no display name, group, or order.
|
||||
- `GET /api/v1/dashboard/navigation` answers *how this Dashboard presents those modules*, and
|
||||
**embeds** each generic descriptor untouched under `module`.
|
||||
|
||||
Both compose that descriptor through one shared function, so they cannot disagree about what exists
|
||||
or about any URL.
|
||||
|
||||
### Grouping is presentation, never module structure
|
||||
|
||||
A group is a label on a rendering bucket. It is **not a module**: it has no manifest, version,
|
||||
artifact, API, permission, or lifecycle, and nothing depends on it. Placing Livestream and Video in
|
||||
one folder creates no relationship between them, and moving a module changes a single presentation
|
||||
row — never its artifact, API root, permissions, dependencies, or startup order. Real technical
|
||||
dependencies remain the module dependency contract's job and are the only relationship modules have.
|
||||
|
||||
### Resolution rules
|
||||
|
||||
- A module with **no placement is ungrouped and visible** — installing it is enough, with no
|
||||
initialization write and no manual database edit.
|
||||
- A stored placement for a module that is **not installed renders nothing and is retained**, so
|
||||
uninstall-and-reinstall preserves an arrangement.
|
||||
- **Empty groups are kept** (hiding one would look like deletion), and a placement naming a missing
|
||||
group renders as ungrouped rather than disappearing.
|
||||
- Deleting a group **ungroups its modules** through the schema's `on delete set null`; a dangling
|
||||
reference is impossible.
|
||||
- Ordering is total: groups by `(order, id)`, modules by `(configured, order, id)` — placed modules
|
||||
in the administrator's order, then never-configured ones by id, with the identifier always the
|
||||
final tie-break, so colliding order values are still deterministic.
|
||||
|
||||
### Authority
|
||||
|
||||
Reading requires `core.modules.ui.read` — the same permission the inventory requires, because this
|
||||
response contains it and serves the same audience. Organizing requires
|
||||
`core.dashboard.navigation.manage` (baseline `restricted`), a **platform** permission and never a
|
||||
module's, plus an exact trusted `Origin` and a bounded body. Holding it grants no module authority:
|
||||
every module route stays enforced against its own declared permission, and no arrangement of folders
|
||||
changes an authorization decision.
|
||||
|
||||
Group ids are opaque, stable, lowercase kebab-case keys, never displayed and never re-derived from a
|
||||
label — so renaming a group cannot re-organize the Dashboard. Bodies are closed: any key beyond the
|
||||
declared ones makes the whole request invalid rather than being silently dropped. Configuration is
|
||||
platform-global; Ekklesia has no organization or tenant model to scope it to yet.
|
||||
|
||||
Responses are per-principal, so `Cache-Control: no-store` and `Vary: Origin, Cookie`.
|
||||
|
||||
## Module UI inventory
|
||||
|
||||
```text
|
||||
|
||||
@@ -152,6 +152,22 @@ shell owns the container, the loading state, and every error, so a failing modul
|
||||
rather than the shell. None of that is containment: once imported, a module UI is ordinary same-realm
|
||||
JavaScript, exactly as described above.
|
||||
|
||||
### Dashboard arrangement is not an access control
|
||||
|
||||
Dashboard groups and placements are presentation configuration
|
||||
([ADR 0027](../architecture/decisions/0027-dashboard-navigation-and-flat-modules.md)). Organizing the
|
||||
Dashboard requires the platform permission `core.dashboard.navigation.manage` (baseline
|
||||
`restricted`), and holding it **grants no module authority whatsoever**: moving a module into a
|
||||
folder changes one presentation row, and every module route stays enforced against its own declared
|
||||
permission exactly as before. Nothing in the navigation configuration is read by discovery,
|
||||
dependency resolution, module startup, or the authorization evaluator.
|
||||
|
||||
Navigation is also not a way to hide anything. A module absent from a viewer's navigation is a
|
||||
rendering decision, never a restriction — server authorization remains the only thing that decides
|
||||
what a request may do. Reading navigation requires the same `core.modules.ui.read` the module UI
|
||||
inventory requires, so it discloses the same installed-module enumeration and nothing more; it
|
||||
carries no filesystem path, package root, or manifest internal.
|
||||
|
||||
### Client-side permission checks are not a security boundary
|
||||
|
||||
A host may tell a module UI what permissions it believes the viewer holds
|
||||
|
||||
Reference in New Issue
Block a user