@c9up/station 0.1.5

package/dist/StationProvider.js

@@ -0,0 +1,1144 @@
+/**
+ * StationProvider — Ream provider that wires Station's `ResourceRegistry`
+ * into the host container and mounts the list + show routes for every
+ * registered resource.
+ *
+ * Story 54.7 EXTENDS this provider with Warden integration (login
+ * surface + `/_assets/station/*` mount). The class shape and lifecycle
+ * stay; only `start()` grows.
+ *
+ * Mirror of `packages/aurora/src/AuroraProvider.ts` — register binds a
+ * singleton + sets the `services/main` proxy backing instance, start
+ * dynamically imports BOTH `@c9up/ream/services/router` AND `@c9up/atlas`
+ * inside try/catch so non-Ream hosts AND Station-without-Atlas consumers
+ * are silently tolerated. Once both modules resolve, the per-resource
+ * repository + column metadata is built ONCE (cached on the instance)
+ * and re-used by every request, then route registration runs OUTSIDE
+ * the catch — real bugs in route registration surface instead of being
+ * swallowed.
+ */
+import { ResourceRegistry } from "./ResourceRegistry.js";
+import { setStation } from "./services/main.js";
+// note: AuditEvent + ResourceAction are used by the CRUD handlers below;
+// the imports stay in one block for clarity.
+import { renderNotFoundPage } from "./views/errors/404.js";
+import { renderFormPage } from "./views/form.js";
+import { renderListPage } from "./views/list.js";
+import { renderLoginPage } from "./views/login.js";
+import { renderShowPage } from "./views/show.js";
+const MAX_PER_PAGE = 100;
+const DEFAULT_PER_PAGE = 25;
+const POSITIVE_INT_RE = /^[1-9][0-9]*$/;
+/** Process-scoped flags so we warn once per process, not once per request. */
+let authWarnEmitted = false;
+let perPageClampWarned = false;
+let seedPermsWarned = false;
+let missingAuditWarned = false;
+let csrfWarnEmitted = false;
+/** @internal Reset module-level flags between tests. */
+export function resetStationProviderFlags() {
+    authWarnEmitted = false;
+    perPageClampWarned = false;
+    seedPermsWarned = false;
+    missingAuditWarned = false;
+    csrfWarnEmitted = false;
+}
+const TIMESTAMP_PROPERTY_KEYS = new Set([
+    "createdAt",
+    "updatedAt",
+    "deletedAt",
+]);
+const TIMESTAMP_COLUMN_NAMES = new Set([
+    "created_at",
+    "updated_at",
+    "deleted_at",
+]);
+/**
+ * Mass-assignment guard. Only accepts keys that are:
+ *   1. A declared `@Column` propertyKey on the resource entity, AND
+ *   2. Not the primary key (DB-managed), AND
+ *   3. Not a framework-managed timestamp. Two signals, both honoured:
+ *      (a) the Lucid-style auto flag — `@column.dateTime({ autoCreate })` /
+ *          `{ autoUpdate }` (passed in via `autoManaged`); this is the
+ *          authoritative one and catches custom-named timestamp columns
+ *          (e.g. `registeredAt`) the name list below would miss, AND
+ *      (b) the conventional name fallback (created_at / updated_at /
+ *          deleted_at) for plain `@Column` timestamps declared without the
+ *          auto flag.
+ *
+ * The `_method` synthetic field from browser-form method-overrides is
+ * dropped automatically because it never matches a column propertyKey.
+ *
+ * Returning a fresh object — never the caller's reference — so a
+ * downstream mutation can't poison the audit snapshot.
+ */
+/** @internal Exported for unit tests — the mass-assignment + checkbox coercion guard. */
+export function filterWritableBody(body, columns, pkColumn, autoManaged) {
+    const writable = {};
+    const validKeys = new Set();
+    const booleanKeys = new Set();
+    for (const c of columns) {
+        if (c.propertyKey === pkColumn)
+            continue;
+        if (autoManaged.has(c.propertyKey))
+            continue;
+        if (TIMESTAMP_PROPERTY_KEYS.has(c.propertyKey))
+            continue;
+        const snake = c.propertyKey.replace(/([A-Z])/g, "_$1").toLowerCase();
+        if (TIMESTAMP_COLUMN_NAMES.has(snake))
+            continue;
+        validKeys.add(c.propertyKey);
+        if ((c.type ?? "").toString().toLowerCase() === "boolean") {
+            booleanKeys.add(c.propertyKey);
+        }
+    }
+    // Boolean columns render as checkboxes: an unchecked box submits NOTHING, so
+    // derive every boolean from presence/value. Otherwise an unchecked box can
+    // never clear a previously-true column on edit, and a checked box would store
+    // the raw string "1" instead of a real boolean.
+    for (const key of booleanKeys) {
+        writable[key] = isCheckedValue(body[key]);
+    }
+    for (const [key, value] of Object.entries(body)) {
+        if (!validKeys.has(key))
+            continue;
+        if (booleanKeys.has(key))
+            continue; // already derived above
+        writable[key] = value;
+    }
+    return writable;
+}
+/** A checkbox/boolean field is true only for its checked submissions. */
+function isCheckedValue(value) {
+    return value === true || value === "1" || value === "on" || value === "true";
+}
+/**
+ * Snapshot an entity's `@Column`-tracked fields for the audit before/
+ * after diff. Deep-cloned via `structuredClone` so a downstream sink
+ * that mutates the snapshot (e.g. "redact this field before logging")
+ * can't echo the change back into the live entity.
+ *
+ * Falls back to a per-key copy when the entity contains a non-
+ * clonable value (a function, a class instance with a non-clonable
+ * field). The fallback is shallow but warned ONCE per process so
+ * operators see it.
+ */
+function snapshotEntity(entity, columns) {
+    const out = {};
+    for (const c of columns)
+        out[c.propertyKey] = entity[c.propertyKey];
+    try {
+        return structuredClone(out);
+    }
+    catch (err) {
+        // structuredClone rejected a value (a function, a class instance with a
+        // non-cloneable field, …). Try a JSON deep-clone next, so the before/
+        // after audit snapshots still don't share mutable references with the
+        // live entity — a shared-ref shallow copy would let a later `setProp`
+        // mutation bleed back into the "before" image. Only if JSON also fails
+        // (bigint, circular) do we accept the shallow copy + warn.
+        try {
+            const cloned = JSON.parse(JSON.stringify(out));
+            if (isPlainRecord(cloned))
+                return cloned;
+        }
+        catch {
+            // fall through to the warned shallow copy
+        }
+        if (!auditCloneWarnEmitted) {
+            auditCloneWarnEmitted = true;
+            const detail = err instanceof Error ? err.message : String(err);
+            console.warn(`[station] structuredClone failed on an audit snapshot and the JSON fallback did not apply — using a shallow copy. A column value isn't cloneable: ${detail}. Snapshot mutations downstream MAY reach the live entity.`);
+        }
+        return out;
+    }
+}
+let auditCloneWarnEmitted = false;
+export default class StationProvider {
+    app;
+    #contexts = new Map();
+    #started = false;
+    // 54.7 auth state — populated when warden is wired AND
+    // StationConfig.requireAuth is true (default when warden is present).
+    #authManager;
+    #authConfig = {
+        requireAuth: false,
+        requireRole: undefined,
+        loginPath: "/admin/login",
+        cookieName: "station_auth",
+    };
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton(ResourceRegistry, () => {
+            const registry = new ResourceRegistry();
+            setStation(registry);
+            return registry;
+        });
+        this.app.container.singleton("station", () => this.app.container.resolve(ResourceRegistry));
+    }
+    async boot() {
+        // Force-resolve so `setStation` runs even if no preload touches the
+        // singleton. Mirrors AuroraProvider.boot().
+        this.app.container.resolve(ResourceRegistry);
+    }
+    async start() {
+        if (this.#started)
+            return;
+        const registry = this.app.container.resolve(ResourceRegistry);
+        const resources = registry.all();
+        if (resources.length === 0)
+            return;
+        // 54.7 — read the optional `station` config block. Defaults bake
+        // in `requireAuth: true` when @c9up/warden is detected later in
+        // Phase 1, so a host that just installs the peer gets the auth
+        // gate without any extra config.
+        const userConfig = this.app.config.get("station") ?? {};
+        // Phase 1 — lazy peer imports (router + atlas). A missing optional
+        // peer is a degraded-host signal: #loadPeers returns null → silent stop.
+        const peers = await this.#loadPeers();
+        if (!peers)
+            return;
+        const { router, atlas } = peers;
+        // Phase 1b — wire the warden auth gate (or warn-once when it stays open).
+        this.#configureAuth(userConfig);
+        // Phase 2 — build per-resource context ONCE. `#resolveDb()` is
+        // loud: if the host installed `@c9up/atlas` but didn't register
+        // `@c9up/atlas/provider` in `reamrc.ts`, AC11's "surface
+        // AtlasProvider misconfiguration" intent kicks in.
+        const db = this.#resolveDb();
+        for (const resource of resources) {
+            this.#contexts.set(resource, buildResourceContext(resource, db, atlas));
+        }
+        // 56.5 + 54.6 + CSRF boot-time warn-onces. We surface the "auth
+        // wired but no permissions seeded", "no audit sink", and "no CSRF
+        // check" gaps loud-and-once so a half-wired install can't ship to
+        // prod without operators noticing.
+        this.#warnSeedPermissionsOnce(resources);
+        this.#warnAuditGapsOnce(resources);
+        this.#warnCsrfGapOnce(resources);
+        // Phase 3 — route registration. The router proxy may still throw
+        // "Router accessed before initialization" on first property access
+        // (boot ordering hazard where the proxy module imported but
+        // Ignitor's `setRouter` never fired). That's another legitimate
+        // degraded-host shape — silent return. Anything else (slug
+        // collision, future validation) propagates.
+        try {
+            this.#registerAdminRoutes(router, resources);
+        }
+        catch (err) {
+            if (isRouterProxyUninit(err))
+                return;
+            throw err;
+        }
+        this.#started = true;
+    }
+    /**
+     * Phase 1 — resolve the host router from the container (Ream registers it as
+     * `'router'` in Ignitor) + lazy-import the optional `@c9up/atlas` peer.
+     *
+     * Reading the router from the container — instead of importing
+     * `@c9up/ream/services/router` — keeps station runtime-agnostic: a non-Ream
+     * host never registers `'router'` → null (a legitimate degraded-host signal).
+     * `@c9up/atlas` stays a genuine peer MODULE import (it ships agnostic
+     * classes, not a framework singleton); module-not-found → null, anything
+     * else re-throws.
+     */
+    async #loadPeers() {
+        if (!this.app.container.has("router"))
+            return null;
+        const router = this.app.container.resolve("router");
+        try {
+            const atlas = loadBearingCast(await import("@c9up/atlas"));
+            return { router, atlas };
+        }
+        catch (err) {
+            if (isModuleNotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Wire the warden auth gate from the `station` config block. When warden is
+     * not installed/bound the gate stays open and a one-time warning is emitted.
+     */
+    #configureAuth(userConfig) {
+        const wardenWanted = userConfig.requireAuth !== false;
+        if (wardenWanted) {
+            try {
+                this.#authManager =
+                    this.app.container.resolve("auth");
+                this.#authConfig = {
+                    requireAuth: true,
+                    requireRole: userConfig.requireRole,
+                    loginPath: userConfig.loginPath ?? "/admin/login",
+                    cookieName: userConfig.cookieName ?? "station_auth",
+                };
+            }
+            catch (cause) {
+                // Container has no working `auth` binding → warden not wired.
+                // If the host EXPLICITLY opted in (`requireAuth: true`), that is a
+                // misconfiguration, not the dev-preview path — fail closed rather
+                // than silently mounting an unauthenticated admin. When
+                // `requireAuth` was merely defaulted (undefined), fall through to
+                // the open-by-default mode and warn-once below.
+                if (userConfig.requireAuth === true) {
+                    throw new Error("[station] `station.requireAuth: true` is set but no working `auth` binding is registered (wire @c9up/warden's WardenProvider). Refusing to mount an unauthenticated admin.", { cause });
+                }
+            }
+        }
+        if (!this.#authConfig.requireAuth && !authWarnEmitted) {
+            authWarnEmitted = true;
+            console.warn("[station] Admin routes mounted without auth. Wire @c9up/warden (and set `station.requireAuth: true` if you opted out) and seed the per-action `<resource>.<action>` permissions in the Warden rights store BEFORE production. See https://ream.dev/modules/station#auth.");
+        }
+    }
+    /** Phase 3 — mount the login surface + per-resource CRUD routes. */
+    #registerAdminRoutes(router, resources) {
+        // 54.7 — mount login surface first when auth is required, so
+        // `/admin/login` is reachable even when the auth gate redirects every
+        // other path to it.
+        if (this.#authConfig.requireAuth && this.#authManager !== undefined) {
+            router.get("/admin/login", this.#buildLoginFormHandler());
+            router.post("/admin/login", this.#buildLoginPostHandler());
+            router.post("/admin/logout", this.#buildLogoutHandler());
+        }
+        const gate = (handler) => this.#authConfig.requireAuth ? this.#withAuth(handler) : handler;
+        // `/admin` index — send the operator to the first listable resource (or the
+        // login surface). Without it, the post-login redirect("/admin") lands on a 404.
+        router.get("/admin", gate(async (ctx) => {
+            const home = resources.find((r) => r.actions.includes("list"));
+            ctx.response.redirect(home ? `/admin/${home.name}` : "/admin/login");
+        }));
+        for (const resource of resources) {
+            const slug = resource.name;
+            if (resource.actions.includes("list")) {
+                router.get(`/admin/${slug}`, gate(this.#buildListHandler(resource)));
+            }
+            if (resource.actions.includes("create")) {
+                router.get(`/admin/${slug}/new`, gate(this.#buildNewFormHandler(resource)));
+                router.post(`/admin/${slug}`, gate(this.#buildCreateHandler(resource)));
+            }
+            if (resource.actions.includes("show")) {
+                router.get(`/admin/${slug}/:id`, gate(this.#buildShowHandler(resource)));
+            }
+            if (resource.actions.includes("edit")) {
+                router.get(`/admin/${slug}/:id/edit`, gate(this.#buildEditFormHandler(resource)));
+                router.put(`/admin/${slug}/:id`, gate(this.#buildUpdateHandler(resource)));
+                // Browser forms can't issue PUT — accept POST with `_method=PUT`
+                // from the auto-generated form (form.ts stamps the hidden input).
+                router.post(`/admin/${slug}/:id`, gate(this.#buildMethodOverrideHandler(resource)));
+            }
+            if (resource.actions.includes("destroy")) {
+                router.delete(`/admin/${slug}/:id`, gate(this.#buildDestroyHandler(resource)));
+            }
+        }
+    }
+    /**
+     * 56.5 — every admin action is now gated behind a
+     * `<resource>.<action>` permission resolved through @c9up/warden
+     * (`auth.hasPermission`). Warn ONCE at boot, only when the auth layer
+     * is wired, that the host must seed roles/grants in the Warden rights
+     * store — otherwise every admin request 403s with no hint. The old
+     * "missing policy entry" warning is gone with the 54.4 callback table.
+     */
+    #warnSeedPermissionsOnce(resources) {
+        if (seedPermsWarned)
+            return;
+        // Only meaningful once the Warden layer is wired — the dev-preview /
+        // no-warden path leaves the gate open, so there's nothing to seed.
+        if (this.#authManager === undefined)
+            return;
+        if (resources.length === 0)
+            return;
+        seedPermsWarned = true;
+        const example = resources[0];
+        console.warn(`[station] Admin actions are gated behind '<resource>.<action>' permissions resolved through @c9up/warden (e.g. '${example.name}.list', '${example.name}.create'). Seed roles/grants in the Warden rights store (store.defineRole('admin', ['${example.name}.list', '${example.name}.create', ...]) then assignRole) or every admin request will 403. See https://ream.dev/modules/station#authorization.`);
+    }
+    #warnCsrfGapOnce(resources) {
+        if (csrfWarnEmitted)
+            return;
+        const writeActions = [
+            "create",
+            "edit",
+            "destroy",
+        ];
+        const writeEnabled = resources.some((r) => r.actions.some((a) => writeActions.includes(a)));
+        if (!writeEnabled)
+            return;
+        csrfWarnEmitted = true;
+        console.warn("[station] Write-enabled resources are mounted but Station does NOT enforce CSRF at the handler level. Wire @c9up/blackhole (csrf: true) or an equivalent middleware in start/kernel.ts BEFORE production — a missing CSRF check on /admin/<resource>/:id POST allows cross-site form submission to mutate rows under any logged-in user's session.");
+    }
+    #warnAuditGapsOnce(resources) {
+        if (missingAuditWarned)
+            return;
+        const writeActions = [
+            "create",
+            "edit",
+            "destroy",
+        ];
+        const missing = resources.filter((r) => r.audit === undefined &&
+            r.actions.some((a) => writeActions.includes(a)));
+        if (missing.length === 0)
+            return;
+        missingAuditWarned = true;
+        console.warn(`[station] No audit sink configured for write-enabled resources: ${missing.map((r) => r.name).join(", ")}. Pass 'audit:' in defineResource() to persist mutations to your audit log.`);
+    }
+    async ready() { }
+    async shutdown() { }
+    #requireContext(resource) {
+        const ctx = this.#contexts.get(resource);
+        if (!ctx) {
+            throw new Error(`[station] No repository available for ${resource.entity.name}. Did you register @c9up/atlas/provider in reamrc.ts?`);
+        }
+        return ctx;
+    }
+    #buildListHandler(resource) {
+        return async (ctx) => {
+            const { repo, columns, pkColumn } = this.#requireContext(resource);
+            // 56.5: the list action is gated behind `<resource>.list` like
+            // every other action — resolved through the Warden `"auth"`
+            // layer. (Retro 2026-06-01: list previously skipped the gate
+            // entirely, leaking the index regardless of authorization.)
+            if (!(await authorizeAction(resource, "list", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const qs = ctx.request.qs();
+            const page = clampPositiveInt(qs.page, 1);
+            const perPageRaw = clampPositiveInt(qs.perPage, DEFAULT_PER_PAGE);
+            const perPage = Math.min(perPageRaw, MAX_PER_PAGE);
+            if (perPage < perPageRaw && !perPageClampWarned) {
+                perPageClampWarned = true;
+                console.warn(`[station] perPage clamped to ${MAX_PER_PAGE} (got ${perPageRaw}). Suppressing further warnings.`);
+            }
+            const total = await repo.query().count();
+            const lastPage = Math.max(1, Math.ceil(total / perPage));
+            if (page > lastPage && total > 0) {
+                // Never render an empty page when one exists — redirect to the
+                // last real page so the user lands on something useful.
+                ctx.response.redirect(`/admin/${resource.name}?page=${lastPage}&perPage=${perPage}`);
+                return;
+            }
+            const rows = await repo
+                .query()
+                .orderBy(pkColumn, "desc")
+                .forPage(page, perPage)
+                .exec();
+            const html = renderListPage({
+                resource,
+                rows,
+                columns,
+                pkColumn,
+                page,
+                perPage,
+                total,
+                lastPage,
+            });
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(html);
+        };
+    }
+    #buildShowHandler(resource) {
+        return async (ctx) => {
+            const { repo, columns, pkColumn } = this.#requireContext(resource);
+            // Authorize BEFORE the existence check so an unauthorized caller
+            // can't distinguish 404 (absent) from 403 (exists) — no row-existence
+            // oracle for a user without `<resource>.show`.
+            if (!(await authorizeAction(resource, "show", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const id = ctx.params.id ?? "";
+            const row = await repo.find(id);
+            if (row === null) {
+                ctx.response.status(404);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(renderNotFoundPage({ resource, id }));
+                return;
+            }
+            const html = renderShowPage({
+                resource,
+                row,
+                columns,
+                pkColumn,
+            });
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(html);
+        };
+    }
+    #buildNewFormHandler(resource) {
+        return async (ctx) => {
+            const { columns, pkColumn } = this.#requireContext(resource);
+            if (!(await authorizeAction(resource, "create", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const html = renderFormPage({
+                resource,
+                columns,
+                pkColumn,
+                hiddenInputs: csrfHiddenInputs(ctx),
+            });
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(html);
+        };
+    }
+    #buildCreateHandler(resource) {
+        return async (ctx) => {
+            const { repo, pkColumn, columns, autoManaged } = this.#requireContext(resource);
+            if (!(await authorizeAction(resource, "create", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const body = await readBody(ctx);
+            // Mass-assignment guard: only `@Column`-declared properties make
+            // it through to repo.create(). An attacker who POSTs
+            // `{ role: "admin" }` or `{ passwordHash: "x" }` against a
+            // resource that doesn't declare those columns has the keys
+            // silently dropped here. PK + framework timestamps are always
+            // excluded — they're decided by the DB / hooks, not the caller.
+            const filtered = filterWritableBody(body, columns, pkColumn, autoManaged);
+            const created = await repo.create(filtered);
+            await emitAudit(resource, {
+                action: "create",
+                resource: resource.name,
+                recordId: created[pkColumn],
+                userId: ctx.auth?.user?.id,
+                after: snapshotEntity(created, columns),
+                at: new Date(),
+            });
+            redirectToShow(ctx, resource, created[pkColumn]);
+        };
+    }
+    #buildEditFormHandler(resource) {
+        return async (ctx) => {
+            const { repo, columns, pkColumn } = this.#requireContext(resource);
+            // Authorize before the existence check (no 404-vs-403 oracle).
+            if (!(await authorizeAction(resource, "edit", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const id = ctx.params.id ?? "";
+            const row = await repo.find(id);
+            if (row === null) {
+                ctx.response.status(404);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(renderNotFoundPage({ resource, id }));
+                return;
+            }
+            const html = renderFormPage({
+                resource,
+                columns,
+                pkColumn,
+                row,
+                hiddenInputs: csrfHiddenInputs(ctx),
+            });
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(html);
+        };
+    }
+    #buildUpdateHandler(resource) {
+        return async (ctx) => {
+            const { repo, pkColumn, columns, autoManaged } = this.#requireContext(resource);
+            // Authorize before the existence check (no 404-vs-403 oracle).
+            if (!(await authorizeAction(resource, "edit", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const id = ctx.params.id ?? "";
+            const entity = await repo.find(id);
+            if (entity === null) {
+                ctx.response.status(404);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(renderNotFoundPage({ resource, id }));
+                return;
+            }
+            const body = await readBody(ctx);
+            // Snapshot BEFORE the mutation runs so the audit diff is
+            // meaningful (entity is a BaseEntity; its dirty-tracking
+            // would shadow the original values after setProp).
+            const beforeSnapshot = snapshotEntity(entity, columns);
+            // Mass-assignment guard: filterWritableBody drops every key
+            // that isn't an `@Column`-declared property, plus the PK and
+            // any framework timestamps (created_at / updated_at /
+            // deleted_at). An attacker who POSTs `{ role: "admin" }` to
+            // a resource without that column has the field silently
+            // dropped instead of overwriting the entity.
+            const writable = filterWritableBody(body, columns, pkColumn, autoManaged);
+            for (const [key, value] of Object.entries(writable)) {
+                entity.setProp(key, value);
+            }
+            await repo.save(entity);
+            const afterSnapshot = snapshotEntity(entity, columns);
+            await emitAudit(resource, {
+                action: "edit",
+                resource: resource.name,
+                recordId: entity[pkColumn],
+                userId: ctx.auth?.user?.id,
+                before: beforeSnapshot,
+                after: afterSnapshot,
+                at: new Date(),
+            });
+            redirectToShow(ctx, resource, entity[pkColumn]);
+        };
+    }
+    #buildMethodOverrideHandler(resource) {
+        // Browser forms can only emit GET / POST. The auto-generated edit
+        // form ships `<input type="hidden" name="_method" value="PUT">`
+        // so the POST /admin/:r/:id endpoint can route to the update
+        // handler. A POST without `_method=PUT` (or with `_method=DELETE`)
+        // dispatches accordingly.
+        const updateHandler = this.#buildUpdateHandler(resource);
+        const destroyHandler = this.#buildDestroyHandler(resource);
+        return async (ctx) => {
+            const body = await readBody(ctx);
+            const override = String(body._method ?? "").toUpperCase();
+            if (override === "PUT" || override === "PATCH") {
+                return updateHandler(ctx);
+            }
+            if (override === "DELETE") {
+                return destroyHandler(ctx);
+            }
+            // Unsupported override — refuse rather than silently downgrade
+            // to a no-op so misconfigured forms surface immediately.
+            ctx.response.status(405);
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(`<h1>405 Method Not Allowed</h1><p>POST /admin/${escapeMin(resource.name)}/:id requires <code>_method=PUT</code> or <code>_method=DELETE</code>.</p>`);
+        };
+    }
+    #buildDestroyHandler(resource) {
+        return async (ctx) => {
+            const { repo, pkColumn, columns } = this.#requireContext(resource);
+            // Authorize before the existence check (no 404-vs-403 oracle).
+            if (!(await authorizeAction(resource, "destroy", ctx, this.#authManager))) {
+                deny(ctx);
+                return;
+            }
+            const id = ctx.params.id ?? "";
+            const row = await repo.find(id);
+            if (row === null) {
+                ctx.response.status(404);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(renderNotFoundPage({ resource, id }));
+                return;
+            }
+            const before = snapshotEntity(row, columns);
+            await repo.delete(row);
+            await emitAudit(resource, {
+                action: "destroy",
+                resource: resource.name,
+                recordId: row[pkColumn],
+                userId: ctx.auth?.user?.id,
+                before,
+                at: new Date(),
+            });
+            ctx.response.redirect(`/admin/${encodeURIComponent(resource.name)}`);
+        };
+    }
+    #resolveDb() {
+        try {
+            return this.app.container.resolve("db");
+        }
+        catch (cause) {
+            throw new Error(`[station] No 'db' connection registered. Did you register @c9up/atlas/provider in reamrc.ts?`, { cause });
+        }
+    }
+    // ───────────────────────────────────────────────────────────────────────
+    // Story 54.7 — Warden integration
+    // ───────────────────────────────────────────────────────────────────────
+    /**
+     * Resolve the inbound auth token. Cookie wins over Authorization
+     * header because the cookie is what the login handler set; the
+     * Bearer fallback exists for API-style callers (curl / fetch with
+     * Authorization).
+     */
+    #readAuthToken(ctx) {
+        const cookieName = this.#authConfig.cookieName;
+        const fromCookie = ctx.request.cookie?.(cookieName);
+        if (typeof fromCookie === "string" && fromCookie.length > 0) {
+            return fromCookie;
+        }
+        const authHeader = ctx.request.header?.("authorization");
+        if (typeof authHeader === "string" && authHeader.length > 0) {
+            const trimmed = authHeader.trim();
+            if (trimmed.toLowerCase().startsWith("bearer ")) {
+                return trimmed.slice(7).trim();
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Decide whether to redirect (HTML browser flow) or 401-json (XHR /
+     * API flow). `Accept: application/json` OR `X-Requested-With:
+     * XMLHttpRequest` triggers the JSON shape; everything else gets the
+     * 302 to the login page.
+     */
+    #wantsJsonResponse(ctx) {
+        return wantsJsonResponse(ctx);
+    }
+    /**
+     * Wrap a CRUD handler with the auth gate. Reads token from cookie/
+     * header → `authManager.verify(token)` → on success populates
+     * `ctx.auth.user` (and `ctx.auth.roles` when present on the user
+     * record) and delegates. On failure: JSON callers get 401, HTML
+     * callers get a 302 to `loginPath`.
+     *
+     * Role check (`requireRole`) is applied AFTER auth: an authenticated
+     * user without the role gets 403 (or 403-json), never a redirect —
+     * a redirect to login wouldn't help them.
+     */
+    #withAuth(handler) {
+        return async (ctx) => {
+            const manager = this.#authManager;
+            if (manager === undefined) {
+                // Auth gate enabled but no manager wired — shouldn't happen
+                // because we only set requireAuth=true when the container
+                // resolved `auth`. Fail closed: treat as a 500.
+                ctx.response.status(500);
+                ctx.response.type("text/plain; charset=utf-8");
+                ctx.response.send("[station] auth gate enabled but AuthManager missing");
+                return;
+            }
+            const token = this.#readAuthToken(ctx);
+            if (token === undefined) {
+                if (this.#wantsJsonResponse(ctx)) {
+                    ctx.response.status(401);
+                    ctx.response.json({ error: "authentication required" });
+                    return;
+                }
+                ctx.response.redirect(this.#authConfig.loginPath);
+                return;
+            }
+            const result = await manager.verify(token);
+            if (!result.authenticated || result.user === undefined) {
+                // A strategy CRASH (the auth backend threw) is a server fault, not a
+                // failed/expired login — don't clear the cookie or bounce to /login
+                // as if the session died. Surface 503 so the real error isn't masked
+                // as a routine re-login (audit 2026-06-13).
+                if (result.strategyCrash) {
+                    ctx.response.status(503);
+                    if (this.#wantsJsonResponse(ctx)) {
+                        ctx.response.json({ error: "authentication service unavailable" });
+                    }
+                    else {
+                        ctx.response.type("text/html; charset=utf-8");
+                        ctx.response.send("<h1>503 Service Unavailable</h1><p>Authentication is temporarily unavailable. Please try again.</p>");
+                    }
+                    return;
+                }
+                // Clear the stale cookie regardless of response shape, so neither
+                // a browser refresh nor an XHR caller retries with the dead token.
+                ctx.response.clearCookie?.(this.#authConfig.cookieName, {
+                    path: "/",
+                });
+                if (this.#wantsJsonResponse(ctx)) {
+                    ctx.response.status(401);
+                    ctx.response.json({
+                        error: result.error ?? "invalid or expired session",
+                    });
+                    return;
+                }
+                ctx.response.redirect(this.#authConfig.loginPath);
+                return;
+            }
+            const user = result.user;
+            const rawRoles = user.roles;
+            // `userRoles` is still derived for view rendering (ctx.auth.roles
+            // below), but the GATE decision now comes from the Warden
+            // resolver via `auth.hasRole` — no parallel Station-local RBAC
+            // (D5/AC-E6). A forgotten `await` would make a truthy Promise
+            // pass the `!` test = silent allow, so the call is awaited.
+            const userRoles = Array.isArray(rawRoles)
+                ? rawRoles.filter((r) => typeof r === "string")
+                : [];
+            const required = this.#authConfig.requireRole;
+            if (required !== undefined) {
+                let roleOk;
+                try {
+                    // `=== true`: a non-boolean resolution must not pass. A throw
+                    // (rights-store outage) denies rather than 500-ing.
+                    roleOk = (await manager.hasRole(user, required, "global")) === true;
+                }
+                catch (err) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    console.error(`[station] role check threw for '${required}' — denying (fail-closed): ${detail}`);
+                    roleOk = false;
+                }
+                if (!roleOk) {
+                    if (this.#wantsJsonResponse(ctx)) {
+                        ctx.response.status(403);
+                        ctx.response.json({ error: "insufficient role" });
+                        return;
+                    }
+                    ctx.response.status(403);
+                    ctx.response.type("text/plain; charset=utf-8");
+                    ctx.response.send("Forbidden");
+                    return;
+                }
+            }
+            const existingAuth = ctx.auth ?? {};
+            ctx.auth = {
+                ...existingAuth,
+                user,
+                roles: userRoles.length > 0 ? userRoles : existingAuth.roles,
+            };
+            await handler(ctx);
+        };
+    }
+    /**
+     * `GET /admin/login` — render the sign-in form. If the caller is
+     * already authenticated, redirect to `/admin` to avoid bouncing them
+     * back through the form they don't need.
+     */
+    #buildLoginFormHandler() {
+        return async (ctx) => {
+            const manager = this.#authManager;
+            if (manager !== undefined) {
+                const token = this.#readAuthToken(ctx);
+                if (typeof token === "string" && token.length > 0) {
+                    const result = await manager.verify(token);
+                    if (result.authenticated) {
+                        ctx.response.redirect("/admin");
+                        return;
+                    }
+                }
+            }
+            const qs = ctx.request.qs();
+            const errorParam = qs.error;
+            const html = renderLoginPage({
+                action: this.#authConfig.loginPath,
+                error: typeof errorParam === "string" ? errorParam : undefined,
+                hiddenInputs: csrfHiddenInputs(ctx),
+            });
+            ctx.response.type("text/html; charset=utf-8");
+            ctx.response.send(html);
+        };
+    }
+    /**
+     * `POST /admin/login` — accept `{email, password}`, run them through
+     * `authManager.authenticate`, set the session cookie on success.
+     * Re-renders the form with an inline error on failure (preserves the
+     * submitted email so the user doesn't retype it).
+     */
+    #buildLoginPostHandler() {
+        return async (ctx) => {
+            const manager = this.#authManager;
+            if (manager === undefined) {
+                ctx.response.status(500);
+                ctx.response.type("text/plain; charset=utf-8");
+                ctx.response.send("[station] login posted but AuthManager missing");
+                return;
+            }
+            const body = await readBody(ctx);
+            const email = typeof body.email === "string" ? body.email.trim() : "";
+            const password = typeof body.password === "string" ? body.password : "";
+            if (email.length === 0 || password.length === 0) {
+                const html = renderLoginPage({
+                    action: this.#authConfig.loginPath,
+                    email,
+                    error: "Email and password are both required.",
+                    hiddenInputs: csrfHiddenInputs(ctx),
+                });
+                ctx.response.status(400);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(html);
+                return;
+            }
+            const result = await manager.authenticate({ email, password });
+            // Warden returns the issued token on `user.token`, not at the
+            // top level — reading `result.token` (which never exists) sent
+            // every valid login down the 401 branch.
+            const token = typeof result.user?.token === "string" ? result.user.token : undefined;
+            if (!result.authenticated || token === undefined) {
+                const html = renderLoginPage({
+                    action: this.#authConfig.loginPath,
+                    email,
+                    error: result.error ?? "Invalid email or password.",
+                    hiddenInputs: csrfHiddenInputs(ctx),
+                });
+                ctx.response.status(401);
+                ctx.response.type("text/html; charset=utf-8");
+                ctx.response.send(html);
+                return;
+            }
+            ctx.response.cookie?.(this.#authConfig.cookieName, token, {
+                httpOnly: true,
+                sameSite: "Lax",
+                secure: process.env.NODE_ENV === "production",
+                path: "/",
+            });
+            ctx.response.redirect("/admin");
+        };
+    }
+    /**
+     * `POST /admin/logout` — clear the session cookie and redirect to
+     * the login page. POST (not GET) so a crafted `<img src>` can't log
+     * someone out via CSRF.
+     */
+    #buildLogoutHandler() {
+        return async (ctx) => {
+            ctx.response.clearCookie?.(this.#authConfig.cookieName, {
+                path: "/",
+            });
+            ctx.response.redirect(this.#authConfig.loginPath);
+        };
+    }
+}
+/**
+ * Cross-package bridge — Station's `Resource.entity` is intentionally
+ * typed `new (...args: never[]) => unknown` so the package type-compiles
+ * without `@c9up/atlas` installed (peer is optional, memory
+ * `project_package_extraction`). At the route-mount boundary we hand
+ * the same constructor to Atlas's `BaseRepository`, whose signature is
+ * `new () => T extends BaseEntity`. The narrowing casts live in this
+ * single helper rather than at every call site (mirrors AC9-style
+ * single-load-bearing-site convention from 54.1).
+ */
+function buildResourceContext(resource, db, atlas) {
+    const entityCtor = loadBearingCast(resource.entity);
+    const conn = loadBearingCast(db);
+    const repo = loadBearingCast(new atlas.BaseRepository(entityCtor, conn));
+    const columns = atlas.getColumnMetadata(resource.entity);
+    const pkColumn = atlas.getPrimaryKey(resource.entity);
+    if (pkColumn === undefined) {
+        // Refusing to fall back to "id": a silently-wrong PK would leave the
+        // REAL primary key out of the mass-assignment exclusion (client could
+        // overwrite it) and mis-key the audit `recordId` + the post-write
+        // redirect. Surface the metadata gap loud at boot instead.
+        throw new Error(`[station] Could not resolve a primary key for ${resource.entity.name}. Declare an @PrimaryKey() column on the entity so atlas can report it.`);
+    }
+    const dateColumns = atlas.getDateColumnConfig(resource.entity);
+    const autoManaged = new Set(Object.entries(dateColumns)
+        .filter(([, cfg]) => cfg.autoCreate === true || cfg.autoUpdate === true)
+        .map(([prop]) => prop));
+    return { repo, columns, pkColumn, autoManaged };
+}
+/**
+ * SANCTIONED CROSS-PACKAGE NARROWING — the ONE production site in
+ * `@c9up/station` where `as T` is permitted. Memory `feedback_no_any_types`
+ * is honoured by funnelling every load-bearing narrow (dynamic peer
+ * imports, IoC-resolved `db`, atlas-agnostic `Resource.entity` handed to
+ * Atlas's `BaseRepository`) through this single function. Analogous to
+ * 54.1's AC9 exception (`{} as ResourceRegistry` in `services/main.ts`)
+ * and the test-side `tests/__helpers__/bypass-type-check.ts`. Every
+ * call site MUST carry a rationale comment explaining why static
+ * narrowing isn't expressible at the boundary. NEVER widen this helper
+ * beyond `unknown → T`.
+ */
+function loadBearingCast(value) {
+    return value;
+}
+/**
+ * Parse a query-string value as a positive integer with a fallback.
+ * Strict: only `^[1-9][0-9]*$` is accepted — empty, missing, leading
+ * zero, fractional (`1.7`), exponent (`1e3`), trailing garbage (`1abc`),
+ * negative, and non-numeric all fall back. Clamp range is [1, +∞).
+ */
+function clampPositiveInt(raw, fallback) {
+    if (typeof raw !== "string" || !POSITIVE_INT_RE.test(raw))
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 1 ? n : fallback;
+}
+/**
+ * Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`.
+ * Exported for the 54.8 agnostic-peer-missing unit test, which can't
+ * realistically simulate the dynamic-import failure path inside vitest's
+ * mock graph.
+ */
+export function isModuleNotFound(err) {
+    if (err === null || typeof err !== "object" || !("code" in err))
+        return false;
+    const { code } = err;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+/** Ream's router proxy throws this exact string before Ignitor wires it. */
+function isRouterProxyUninit(err) {
+    return (err instanceof Error &&
+        err.message.includes("Router accessed before initialization"));
+}
+/**
+ * 56.5 authorization gate. Returns true when the action is allowed.
+ * Station authorizes EXCLUSIVELY through Warden's unified layer: the
+ * decision is `auth.hasPermission(user, "<resource>.<action>", scope)`
+ * resolved via the container `"auth"` AuthManager (D1/D2). No
+ * Station-local RBAC computation, no token-payload read.
+ *
+ *   - `authManager === undefined` ⇒ OPEN (returns true). This is the
+ *     dev-preview / no-warden path — UNCHANGED from the legacy
+ *     `if (!authEnabled) return true`. That mode already emits the loud
+ *     "no auth — not for production" boot warning; this does NOT widen
+ *     any production path.
+ *   - A guest (no `ctx.auth.user`) ⇒ DENIED (fail-closed).
+ *   - Otherwise the answer is the resolver's — permission present ⇒
+ *     allow, absent ⇒ 403.
+ *
+ * Per-row ownership is NOT expressible here (D7): the coarse permission
+ * gate has no `row`. Ownership is a Warden Bouncer-policy concern,
+ * reachable through the fuller Bouncer path (a documented follow-up).
+ *
+ * The result MUST be awaited at every call site — a forgotten `await`
+ * yields a truthy Promise = silent ALLOW (AC10 probe 3).
+ */
+async function authorizeAction(resource, action, ctx, authManager, scope = "global") {
+    if (authManager === undefined)
+        return true;
+    const user = ctx.auth?.user;
+    // `=== undefined` alone is too narrow: a host whose middleware writes
+    // `ctx.auth = { user: null }` as a logged-out sentinel must still be
+    // denied. Fail closed on any nullish user.
+    if (user === undefined || user === null)
+        return false;
+    try {
+        // Coerce to a strict boolean: the duck-typed manager could resolve a
+        // truthy non-boolean, and `!truthy` would silently ALLOW. Anything
+        // not exactly `true` denies (fail-closed).
+        return ((await authManager.hasPermission(user, `${resource.name}.${action}`, scope)) === true);
+    }
+    catch (err) {
+        // A rights-store I/O failure (DB/Redis-backed resolver) must not pass
+        // the gate. Deny and surface it loud rather than 500-ing or allowing.
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error(`[station] authorization check threw for '${resource.name}.${action}' — denying (fail-closed): ${detail}`);
+        return false;
+    }
+}
+/** Content-negotiation: JSON for `Accept: application/json` or an XHR, else HTML. */
+function wantsJsonResponse(ctx) {
+    const accept = ctx.request.header?.("accept");
+    if (typeof accept === "string" && accept.includes("application/json")) {
+        return true;
+    }
+    const xrw = ctx.request.header?.("x-requested-with");
+    if (typeof xrw === "string" && xrw.toLowerCase() === "xmlhttprequest") {
+        return true;
+    }
+    return false;
+}
+function deny(ctx) {
+    ctx.response.status(403);
+    // Match the auth gate's content negotiation — a JSON / XHR caller used to get
+    // an HTML 403 body here, inconsistent with the gate (audit 2026-06-13).
+    if (wantsJsonResponse(ctx)) {
+        ctx.response.json({
+            error: "Forbidden",
+            message: "Your account does not have access to this resource action.",
+        });
+        return;
+    }
+    ctx.response.type("text/html; charset=utf-8");
+    ctx.response.send("<h1>403 Forbidden</h1><p>Your account does not have access to this resource action.</p>");
+}
+/**
+ * Memoise the parsed body per request (Adonis BodyParser semantics — the
+ * body is parsed once and stays re-readable). `#buildMethodOverrideHandler`
+ * reads it to inspect `_method`, then delegates to the update/destroy
+ * handler which reads it again; without this, a single-shot
+ * `ctx.request.body()` would return `{}` on the second read and the edit
+ * would silently no-op.
+ */
+const parsedBodyCache = new WeakMap();
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function readBody(ctx) {
+    const cached = parsedBodyCache.get(ctx);
+    if (cached !== undefined)
+        return cached;
+    const parsed = await parseBody(ctx);
+    parsedBodyCache.set(ctx, parsed);
+    return parsed;
+}
+async function parseBody(ctx) {
+    if (typeof ctx.request.body !== "function")
+        return {};
+    const raw = await ctx.request.body();
+    return isPlainRecord(raw) ? raw : {};
+}
+/**
+ * Read the CSRF token (when present) from `ctx.store` and shape it as
+ * a `hiddenInputs[]` entry for `renderFormPage`. The key `csrfToken`
+ * matches the @c9up/blackhole `csrfToken` convention so a fully-
+ * wired host stamps the token automatically; a host that doesn't wire
+ * CSRF returns no hidden input, and the form is unprotected (the
+ * boot-time warn-once already flagged this).
+ *
+ * The form field is named `_csrf` to match Adonis / Blackhole's
+ * default. Hosts using a different field name can override by writing
+ * their own hiddenInputs into ctx.store under a richer key, but for
+ * the common case this is the zero-config path.
+ */
+function csrfHiddenInputs(ctx) {
+    if (ctx.store === undefined)
+        return undefined;
+    const token = ctx.store.get("csrfToken");
+    if (typeof token !== "string" || token.length === 0)
+        return undefined;
+    return [{ name: "_csrf", value: token }];
+}
+function redirectToShow(ctx, resource, id) {
+    const slug = encodeURIComponent(resource.name);
+    const safeId = encodeURIComponent(String(id ?? ""));
+    // defineResource allows action subsets (e.g. [list, create, edit]), so the
+    // show route may not be mounted. Redirect to the most specific ENABLED view
+    // instead of blindly hitting show and 404-ing: show → edit → list → index.
+    if (resource.actions.includes("show")) {
+        ctx.response.redirect(`/admin/${slug}/${safeId}`);
+        return;
+    }
+    if (resource.actions.includes("edit")) {
+        ctx.response.redirect(`/admin/${slug}/${safeId}/edit`);
+        return;
+    }
+    if (resource.actions.includes("list")) {
+        ctx.response.redirect(`/admin/${slug}`);
+        return;
+    }
+    ctx.response.redirect("/admin");
+}
+/**
+ * 54.6 audit emission. The sink runs AFTER the write commits, so a
+ * failed mutation never produces a misleading audit row. Sink errors
+ * are logged to stderr but never re-thrown — an audit pipeline outage
+ * must not block the user-facing request.
+ */
+async function emitAudit(resource, event) {
+    if (resource.audit === undefined)
+        return;
+    try {
+        await resource.audit(event);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        // COMPLIANCE GAP: the mutation committed but its audit row was
+        // lost. Logged at error level (not warn) so monitoring surfaces
+        // it, and handed to the optional onAuditError hook so a
+        // compliance-serious host can alert / enqueue a retry. The hook
+        // is wrapped so a throwing handler can't crash the request.
+        console.error(`[station] COMPLIANCE GAP: audit sink for resource '${resource.name}' threw on ${event.action} (record ${String(event.recordId)}): ${detail}. The operation succeeded but the audit row was NOT recorded.`);
+        if (resource.onAuditError !== undefined) {
+            try {
+                resource.onAuditError(event, err);
+            }
+            catch (hookErr) {
+                const hookDetail = hookErr instanceof Error ? hookErr.message : String(hookErr);
+                console.error(`[station] onAuditError handler for resource '${resource.name}' itself threw: ${hookDetail}.`);
+            }
+        }
+    }
+}
+/**
+ * Tiny HTML-escape for the 405 error body — duplicated here rather
+ * than imported from views/escape.ts to keep the dependency surface
+ * of StationProvider minimal (views are otherwise only reached via
+ * the renderer modules).
+ */
+function escapeMin(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+//# sourceMappingURL=StationProvider.js.map