@michaelthielemann/kestrel 1.2.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+Kestrel
+Copyright 2026 Michael Thielemann
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this software except in compliance with the License. You may obtain a copy of
+the License in the LICENSE file distributed with this software, or at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This product is provided free of charge and is developed and made available
+outside of any commercial activity. It comes with NO WARRANTY and no commercial
+support; see sections 7 and 8 of the License.

package/README.md

@@ -0,0 +1,234 @@
+# Kestrel
+
+A slim, **static-site-generator CMS**: a generic collection-driven CRUD core with a schema-driven admin
+editor. You declare collections and fields in TypeScript; Kestrel derives the database, a typed CRUD API,
+and a full admin UI from those definitions, and renders published content to static HTML via
+`nuxt generate` — there is **no live public SSR**.
+
+Built on **Nuxt 4 layers + Drizzle/SQLite + Zod**. The whole CMS is a stack of swappable Nuxt layers, so
+a consumer extends it (`extends: ['@michaelthielemann/kestrel']`) and drops in their own collection/field/block definitions.
+
+## What Kestrel is — and isn't
+
+Kestrel is a **CMS engine**, not a finished website. It ships the admin UI, the schema/CRUD/render
+engines, and two toggleable built-in collections (`pages` + the `media` library); **you** define your
+content model and bring the public components and layout that render it.
+
+It is for a private editing origin that publishes **static HTML** (a local dir or S3), served by any
+static host. It is deliberately **not**:
+
+- **No live public SSR** — published pages are static (`nuxt generate` or the runtime incremental
+  publisher); there is no per-request rendering of the public site.
+- **Single-user** — one admin (session + CSRF). No roles, capabilities, or multi-user.
+- **SQLite only** — one database, single instance. (A Postgres `Dialect` seam exists; no impl is active.)
+- **No public data API** — only published *page-like* records have a read surface (mirroring the static
+  output); everything else stays behind the admin guard. No per-request rate limiting / live API.
+- **No runtime redirect engine** — handle redirects at the edge (NGINX / CDN).
+- **No per-file access control on uploads.** The admin guard protects the media *library* — listing,
+  editing, deleting — but not the bytes. With `media.driver: 'local'` the files are served from the app
+  origin by Nitro's static handler, which runs ahead of every middleware, so anyone who knows a URL can
+  fetch it; the optional IP allow-list does not cover them either (see
+  [configuration.md](./docs/configuration.md#ip-allow-list--optional)). That is the intended model — the
+  editing origin is meant to be non-public, and published media is public by definition. If you deploy
+  Kestrel as a general-purpose CMS whose uploads must stay private, restrict them at the reverse proxy or
+  serve media from a private S3 bucket; the app will not do it for you.
+
+## Features
+
+- **Collection-driven** — declare collections + fields in TypeScript; Kestrel derives the SQLite tables, a
+  typed CRUD REST API, and the full admin UI. The schema **migrates itself** (additive in dev; explicit
+  `db:migrate` in prod).
+- **Field types** — text, textarea, rich-text, number, boolean, choice (select / buttons / checkboxes),
+  date / time, media, relation (single / many), link (internal / external / email / tel), repeater
+  (nestable), JSON — plus per-field `condition` visibility rules.
+- **Page-like collections** — give a collection a `path`, SEO meta, and block or flat content; published
+  records render to static HTML and join the sitemap. **Singletons** for settings / navigation.
+- **Block page-builder** — a 3-pane editor (tree · live preview · fields) with nestable block slots; each
+  block is a single `app/blocks/*.vue` SFC (schema via field-factory `defineProps` + the display template).
+- **Media library** — upload (magic-byte sniff + SVG sanitize), local or S3 storage, responsive WebP
+  derivatives + thumbhash, folders, and a full-screen asset viewer.
+- **Multilingual content** — optional per-record translations, an editor locale flow, locale-prefixed
+  routing, hreflang alternates in the sitemap.
+- **Static output** — `nuxt generate` (full rebuild) or a runtime **incremental publisher** (re-renders
+  only the pages a write affects), to a local dir or S3; emits `sitemap.xml`, `robots.txt`, and
+  **`llms.txt`** (an [llmstxt.org](https://llmstxt.org) site map so AI agents grasp the site). A live
+  in-dashboard preview renders straight from the origin.
+- **Reference integrity** — writes invalidate exactly the affected static pages; dead-reference warnings;
+  required + globally-unique page slugs per locale.
+
+## Quickstart (consumer)
+
+```bash
+pnpm add @michaelthielemann/kestrel
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@michaelthielemann/kestrel'],
+  kestrel: {
+    db: '.data/site.sqlite',
+    siteUrl: 'https://example.com',
+    siteName: 'Example',                // used in the generated llms.txt
+    locales: ['en', 'de'],
+    media: { uploadDir: '.data/uploads' },
+    // collections: { pages: false },   // drop a built-in to define your own with that name
+  },
+})
+```
+
+```ts
+// server/collections/products.ts — auto-discovered; the table is created on next boot
+export default defineCollection({
+  name: 'products',
+  mode: 'multi',
+  fields: { title: { type: 'text', required: true }, price: { type: 'number' }, image: { type: 'media' } },
+})
+```
+
+Set the auth env (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`), start the app, and manage
+content at `/admin`. You bring your own **public layout** and **block SFCs**
+(`app/blocks/Hero.vue` — one file for schema + display — is the `hero` block). Full guide:
+**[consuming-kestrel.md](docs/consuming-kestrel.md)**.
+
+## Documentation
+
+Start with the **[architecture guide](docs/architecture.md)** — a per-layer map (what each layer owns,
+where to start reading, the cross-layer seams, the gotchas). Then the per-topic docs:
+
+| Doc | Covers |
+|-----|--------|
+| [architecture.md](docs/architecture.md) | **Start here** — the layer model, boot order, cross-cutting seams, per-layer guide |
+| [consuming-kestrel.md](docs/consuming-kestrel.md) | Using Kestrel in your own app: defining collections/fields/blocks, auto-discovery, the schema lifecycle |
+| [configuration.md](docs/configuration.md) | The single config source (`kestrel.config.ts`), every `KESTREL_*` env var, the auth/session env split |
+| [block-editing.md](docs/block-editing.md) | The block content model + the 3-pane block editor (tree · preview · fields) |
+| [media-uploads.md](docs/media-uploads.md) | Ingest security, storage drivers (local/S3), responsive-image derivation |
+| [multilingual.md](docs/multilingual.md) | Content locales, the editor locale flow, locale-prefixed routing |
+| [static-output.md](docs/static-output.md) | `nuxt generate` + the runtime incremental publisher, the live editor preview, `sitemap.xml` / `robots.txt` / `llms.txt`, the optional S3 deploy |
+| [reference-integrity.md](docs/reference-integrity.md) | How writes invalidate the static site precisely, dead-reference warnings (a dead link renders `#`, and the editor is warned), and required/unique page slugs |
+| [architecture-decisions.md](docs/architecture-decisions.md) | ADRs (the collection-derived schema engine, reference integrity, the auth/password choice) |
+
+## Layout
+
+The CMS is split into Nuxt layers under `layers/`:
+
+- **`core`** — the collection/field model, the generic CRUD engine + REST API, def→JSON serialization,
+  the runtime schema-migration engine, config resolution, and the populate registry.
+- **`fields`** — turns a definition into Drizzle tables + Zod schemas (the field-type registry).
+- **`ui`** — the admin design system: schema-driven field widgets, generic primitives, tokens, i18n.
+- **`auth`** — single-user authentication (session cookie, scrypt password, login, CSRF).
+- **`access`** — authorization: a default-deny guard over the entire `/api/` surface + policy/grant registry.
+- **`collections`** — the toggleable built-in `pages` collection + the plugin that registers every
+  discovered collection/block. (Demo content — `posts`/`settings`, the `hero`/`prose` blocks, and a layout —
+  lives in the repo root, dev-only, and is **not** shipped in the package.)
+- **`media`** — uploads, pluggable storage, image derivation, the media library + asset viewer.
+- **`admin`** — the editor SPA: collection list, record editor, the 3-pane block editor.
+- **`public`** — the SSG render path: the catch-all page, `BlockRenderer`, sitemap / robots / llms.txt, deploy.
+
+`playground/` is a small consuming example.
+
+## Development
+
+Requires Node + [pnpm](https://pnpm.io).
+
+```bash
+pnpm install
+pnpm dev            # dev server (admin at /admin)
+pnpm build          # production build
+pnpm generate       # render the static public site to .output/public
+
+pnpm test           # node + happy-dom unit tests
+pnpm test:nuxt      # Nuxt-environment component tests
+pnpm test:e2e       # end-to-end tests (real dev server)
+
+pnpm db:generate    # drizzle-kit: generate a migration
+pnpm db:migrate     # drizzle-kit: apply migrations
+pnpm hash-password  # produce a KESTREL_ADMIN_PASSWORD_HASH
+```
+
+In dev, the schema auto-syncs from the collection definitions (additive changes only); production applies
+schema changes explicitly via the `db:migrate` task. See
+[architecture-decisions.md](docs/architecture-decisions.md) for the rationale.
+
+### Publishing the static site
+
+Two ways to produce the static output:
+
+- **One-shot:** `pnpm generate` → `.output/public` (the classic full rebuild).
+- **Runtime publisher (default):** a **production** run (`pnpm build && pnpm preview`, or
+  `node .output/server/index.mjs`) publishes on boot and incrementally re-publishes the affected pages on
+  every content write, into `output.dir` (default `.data/published`). Serve that dir with any static
+  server, e.g. `npx serve .data/published`.
+
+The runtime publisher is **intentionally disabled in `pnpm dev`** (a dev render would write un-hashed Vite
+HTML), so the static files only appear on a production run. In dev you instead get the **live preview**:
+public pages render straight from the running server, and an authenticated admin can open an unpublished
+page at its real URL (the "open in new tab" button in the editor). See
+[static-output.md](docs/static-output.md) for the full picture.
+
+### Simulate a production deploy locally
+
+A real deployment is **two processes**: the private CMS server that *renders* the static files, and a
+public static host that *serves* them. Rehearse that split on one machine:
+
+```bash
+# 1. Auth secrets live in .env (pnpm preview loads it). At minimum:
+#      KESTREL_SESSION_SECRET=<≥32 bytes, e.g. `openssl rand -hex 32`>
+#      KESTREL_ADMIN_PASSWORD_HASH=<from `pnpm hash-password <your-password>`>
+#    Leave KESTREL_SECURE_COOKIES at its default — see the note below.
+
+pnpm build
+pnpm preview                 # built Nitro server, NODE_ENV=production → admin at http://localhost:3000/admin
+                             #   boot-publish writes .data/published; editing in /admin re-publishes affected pages
+
+# in a SECOND terminal — serve the generated site like a CDN would:
+npx serve .data/published    # the public static site, exactly as it ships
+```
+
+`pnpm preview` runs the build under `NODE_ENV=production` and **loads `.env`** (running
+`node .output/server/index.mjs` directly does **not** — export the vars yourself if you go that route).
+Note the split: the **auth** vars below are read per request, so exporting them works either way, but the
+non-auth `KESTREL_*` settings are baked in during `pnpm build` — in front of an already-built server they
+are ignored, and you override them with Nuxt's runtime names instead (`NUXT_KESTREL_DB_PATH`,
+`NUXT_KESTREL_SITE_URL`, …; see [configuration.md](docs/configuration.md)).
+Production mode makes the auth guards strict, so for a working local login:
+
+- `KESTREL_SESSION_SECRET` is **required and ≥32 bytes** (dev uses a random per-process secret); the
+  check runs per-request, not at boot, so a deploy that forgets it still starts and binds the port —
+  every `/api/*` request then answers **500** until the secret is set.
+- `KESTREL_ADMIN_PASSWORD_HASH` must be set, or `POST /api/auth/login` answers **503** (“admin login is
+  not configured”) rather than a wrong-password 401.
+- **Keep `KESTREL_SECURE_COOKIES` at its default (`true`).** `=false` is *refused* in production
+  (`KESTREL_SECURE_COOKIES=false is not allowed in production`); you don't need it — the session cookie is
+  `Secure`/`__Host-`, and browsers accept those over plain `http://localhost`, so login works without HTTPS.
+
+Watch the CMS terminal: boot prints `[kestrel] boot publish: N route(s) written, …`, and each save logs
+the routes it re-rendered. Env reference → [configuration.md](docs/configuration.md); publishing internals
+→ [static-output.md](docs/static-output.md).
+
+## Configuration
+
+Non-auth settings live in `kestrel.config.ts` (`satisfies KestrelConfig`); each setting follows
+`KESTREL_* env → config → default`, resolved at build/dev start and frozen into `runtimeConfig` (a prebuilt
+server is retuned with the `NUXT_*` runtimeConfig names, not `KESTREL_*`). Auth/session secrets are
+**env-only** and read per request (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`, …). Full reference:
+[configuration.md](docs/configuration.md).
+
+## Security
+
+Report vulnerabilities privately — see [SECURITY.md](SECURITY.md), which also lists the documented design
+decisions that are explicitly out of scope (uploads are not access-controlled; the editing origin is
+assumed to be non-public).
+
+## Licence
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). You may use, modify and distribute
+Kestrel, including commercially and in closed-source work, as long as you keep the copyright notice and
+the licence, state significant changes you make to the files, and pass the NOTICE along. The licence
+grants patent rights but **no trademark rights**: the name "Kestrel" and the project's branding are not
+covered, so a fork needs its own name.
+
+Kestrel is provided free of charge, developed and published outside any commercial activity, **with no
+warranty and no commercial support** (see sections 7 and 8 of the licence). If you need guarantees for a
+production deployment, the honest answer is to read the code, run the test suite, and decide for yourself
+— that is what the licence terms mean in practice.

package/kestrel.config.ts

@@ -0,0 +1,28 @@
+import type { KestrelConfig } from './layers/core/server/utils/kestrel-config'
+
+/**
+ * Central Kestrel configuration (everything except auth/session, which stays env-only because secrets
+ * don't belong in committed config). This one file is the single source: it flows into `nuxt.config`'s
+ * `kestrel: { … }`, into `drizzle.config` (so `drizzle-kit` uses the same DB), and into the server at
+ * runtime. Precedence per setting: the matching `KESTREL_*` env var → a value here → a built-in default.
+ *
+ * This instance's non-auth config lives here (not in `.env`) so `nuxt.config`, `drizzle-kit` and the
+ * runtime server all derive the SAME values from one place — in particular the same SQLite file, so
+ * `pnpm dev`, `pnpm build` and a migration never drift onto different DBs (they set no `KESTREL_*`, so
+ * this file wins). `.env` keeps only the auth/session secrets. An explicit `KESTREL_*` env var OVERRIDES
+ * this file — the escape-hatch for a per-environment value or an isolated test (the e2e suite sets
+ * `KESTREL_DB` / `KESTREL_MEDIA_LOCAL_DIR` / `KESTREL_SITE_URL` per run). The static-publish `output`
+ * target is left to its defaults (local `.data/published`, auto-publish on).
+ */
+export default {
+  db: '.data/dev.sqlite',
+  siteUrl: 'http://localhost:3000',
+  locales: ['en', 'de'],
+  primaryLocale: 'en',
+  media: {
+    driver: 'local',
+    uploadDir: '.data/uploads',
+    baseUrl: '/uploads',
+    maxBytes: 26214400, // 25 MiB
+  },
+} satisfies KestrelConfig

package/layers/access/nuxt.config.ts

@@ -0,0 +1,5 @@
+// Authorization (authz) layer — the access guard, policy, CSRF + (later) the grant registry. Split out of
+// `auth` (which keeps authentication: session/password/login). Composes AFTER `auth`: the guard verifies the
+// session (via auth's `verifySession`/`sessionSettings`) to derive the request principal, then evaluates the
+// policy. Keeping authz separate is the seam a future User&Roles extension plugs into.
+export default defineNuxtConfig({})

package/layers/access/server/middleware/00.ip-allowlist.ts

@@ -0,0 +1,67 @@
+// Stage-level IP gate: the ENFORCEMENT of an allow-list Kestrel provides; the list itself is consumer
+// config (env `KESTREL_IP_ALLOWLIST`, typically only on non-public DEV/EDIT stages). Runs before the API
+// access-guard (00. sort prefix) and covers every route this app defines — the admin UI, public preview,
+// and API. It does NOT cover assets Nitro serves itself ahead of this stack (`/_nuxt/**`, and `/uploads`
+// when `media.driver: 'local'`) — the `00.` prefix only orders files within this layer, while Nitro's own
+// static handler is unconditionally unshifted to the front of the whole handler list. `off` when no list
+// is set → zero cost on PROD/local.
+function loadConfig() {
+  const listRaw = process.env.KESTREL_IP_ALLOWLIST
+  const mode = allowlistMode(process.env.KESTREL_IP_ALLOWLIST_MODE, listRaw)
+  // Named per-token, not just a "0 valid CIDRs" count — a mixed list (one good entry, one IPv6 CIDR this
+  // IPv4-only parser can never match) would otherwise silently under-enforce with no diagnostic at all.
+  const cidrs = parseAllowlist(listRaw, (token) => {
+    console.warn(`[ip-allowlist] dropping unparseable/unsupported allow-list entry "${token}" (IPv4/CIDR only)`)
+  })
+  if (mode !== 'off' && cidrs.length === 0) {
+    console.warn('[ip-allowlist] KESTREL_IP_ALLOWLIST is set but parsed to 0 valid CIDRs — enforce mode will block ALL traffic')
+  }
+  return { mode, cidrs }
+}
+
+// Env is fixed for the process lifetime → parse the (up to a few hundred) CIDRs once, not per request.
+let configured: ReturnType<typeof loadConfig> | undefined
+
+// A listener that never shows the gate a usable client address blocks everything, which looks like an
+// outage rather than a misconfiguration unless we say once what to set.
+let warnedUnresolvable = false
+
+export default defineEventHandler((event) => {
+  configured ??= loadConfig()
+  const { mode, cidrs } = configured
+  if (mode === 'off') return
+
+  // The runtime publisher renders the public site via a nested in-process $fetch (renderer principal), and
+  // build-time prerender the same. Neither is an external client — exempt them or publishing 403s itself.
+  if (import.meta.prerender === true || isRendererContext()) return
+
+  // Nitro's other in-process sub-requests (the SSR page's own `$fetch`, the preview) run through this
+  // stack on a mocked socket with no peer, so they could never match a CIDR — gating them would 403 the
+  // very pages the gate protects. They are recognised by the async context of the request that spawned
+  // them: a missing peer alone is NOT a pass, or a listener that reports none for anybody (a unix domain
+  // socket) would turn the gate into a silent no-op.
+  if (isStageGatePassedContext() && !event.node?.req?.socket?.remoteAddress) return
+
+  const ip = clientIp(event)
+  if (ipAllowed(ip, cidrs)) {
+    // The in-process sub-requests this one spawns inherit the decision (see above).
+    markStageGatePassed()
+    return
+  }
+
+  if (ipv4ToInt(ip) === null && !warnedUnresolvable) {
+    warnedUnresolvable = true
+    console.warn(`[ip-allowlist] cannot resolve an IPv4 client address (got "${ip}") — such requests are blocked in enforce mode; set KESTREL_TRUST_PROXY when a reverse proxy fronts this listener`)
+  }
+
+  if (mode === 'log') {
+    // Calibration mode: never block, just surface what the gate WOULD reject so the operator can confirm
+    // the resolved client IP + KESTREL_TRUST_PROXY depth before switching to enforce.
+    console.warn(`[ip-allowlist] would block ${ip} — ${event.method} ${event.path} (xff=${getRequestHeader(event, 'x-forwarded-for') ?? '-'})`)
+    // Nothing is blocked in this mode, so the report is about the external request, not the in-process
+    // renders it goes on to spawn.
+    markStageGatePassed()
+    return
+  }
+  throw createError({ statusCode: 403, statusMessage: 'Forbidden' })
+})

package/layers/access/server/middleware/access-guard.ts

@@ -0,0 +1,30 @@
+export default defineEventHandler((event) => {
+  if (!event.path.startsWith('/api/')) return // default-deny applies to the API only
+  const settings = sessionSettings()
+  const decision = evaluateAccess({
+    method: getMethod(event),
+    path: event.path,
+    csrf: {
+      secFetchSite: getRequestHeader(event, 'sec-fetch-site'),
+      origin: getRequestHeader(event, 'origin'),
+      referer: getRequestHeader(event, 'referer'),
+      host: getRequestHeader(event, 'host'),
+    },
+    cookie: getCookie(event, settings.cookieName),
+    secret: settings.secret,
+    nowMs: Date.now(),
+    // The renderer principal is granted to build-time prerender AND to the runtime publisher's render
+    // (an in-process ALS context, not a forgeable header) — both render the public site via /api/route.
+    isPrerender: import.meta.prerender === true || isRendererContext(),
+    // Registry-contributed grants (opt-in layers, e.g. a public proofing back-channel) consulted on top of
+    // the hardcoded policy. Empty by default → guard behaviour unchanged.
+  }, publicReadableResources(), registeredGrants())
+  if (!decision.allow) {
+    throw createError({ statusCode: decision.status, statusMessage: decision.message })
+  }
+  event.context.principal = decision.principal
+  event.context.readScope = decision.readScope
+  // Sliding-expiry: any authenticated API activity refreshes the session so it stays alive while in use and
+  // auto-expires after `maxAge` of inactivity (idle logout). No-op for anonymous/public requests.
+  refreshAuthSession(event)
+})

package/layers/access/server/types.d.ts

@@ -0,0 +1,8 @@
+import type { Principal } from './utils/policy'
+
+declare module 'h3' {
+  interface H3EventContext {
+    principal?: Principal
+    readScope?: 'published' | 'all'
+  }
+}

package/layers/access/server/utils/csrf.ts

@@ -0,0 +1,39 @@
+export interface CsrfHeaders {
+  secFetchSite?: string | null
+  origin?: string | null
+  referer?: string | null
+  host?: string | null
+}
+
+function hostOf(url: string | null | undefined): string | null {
+  if (!url) return null
+  try {
+    return new URL(url).host
+  } catch {
+    return null
+  }
+}
+
+export function isCrossSiteWrite(h: CsrfHeaders): boolean {
+  if (h.secFetchSite) {
+    return !(h.secFetchSite === 'same-origin' || h.secFetchSite === 'none')
+  }
+  // hostOf() lowercases per the URL spec; the raw Host header does not, so normalize both
+  // sides — host comparison is case-insensitive (RFC 3986).
+  const host = (h.host ?? '').toLowerCase()
+  // The literal opaque origin `null` (a browser signal from a sandboxed iframe, a data: URL, or some
+  // redirect chains) is unparseable by new URL, so it must NOT fall through to the all-absent "allow"
+  // path — per spec it is cross-origin. Treat it as cross-site.
+  if (h.origin === 'null') return true
+  const originHost = hostOf(h.origin)
+  if (originHost !== null) return originHost !== host
+  const refererHost = hostOf(h.referer)
+  if (refererHost !== null) return refererHost !== host
+  // A write carrying NONE of Sec-Fetch-Site / Origin / Referer is treated as same-site (allowed). A
+  // browser ALWAYS attaches Origin and/or Sec-Fetch-Site to a cross-origin state-changing request, so
+  // the all-absent case can only come from a NON-browser client (the test harness, a server-to-server
+  // import, automation) — which carries no ambient cookies and therefore cannot mount CSRF. The real
+  // defenses are SameSite=Strict on the session cookie + the Origin/Referer checks above; failing closed
+  // here adds no protection and breaks legitimate authenticated API clients.
+  return false
+}