mikser-io 9.3.1 → 9.12.0

package/docs/configuration.md

@@ -58,7 +58,10 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `trace` | `-t, --trace` | boolean | `false` | Enable trace-level logging (very verbose). |
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |
 | `server` | `-s, --server [port]` | number\|boolean | — | When set, the engine creates a shared Express app on `runtime.options.app` and listens on the given port (default `3001`) after all plugins have mounted their routes. Plugins like `api` attach to it instead of starting their own server. The `outputFolder` is also served as a static catch-all route at `/` (plugin routes match first; anything that doesn't match falls through to the rendered output). Requires `express` to be installed. |
+| `junk` | — | array\|false | built-in list | OS and file-manager litter, filtered out of both the scan and the watcher. The dot-prefixed files (`.DS_Store`, `._*`) were already invisible — globby defaults to `dot: false` and the watcher ignores leading dots — but the Windows ones are **not** dotfiles: `Thumbs.db` and `desktop.ini` were measurably scanned *and* watched, and became entities. The list is deliberately conservative (OS/file-manager artifacts and application lock files only, no `*.tmp`, `*.bak` or editor backups), because a filter that silently drops content is worse than the litter it prevents. `false` disables it; an array replaces it. See `isJunkPath` / `JUNK_IGNORE` in `src/utils.js`. Plugins that write metadata next to content add their own patterns with `registerJunk({ ignore, match })` — the engine provides the mechanism and the plugin the knowledge of what its files are called (`mikser-io-webdav` registers `*.nephelemeta`). Plugin registrations survive an array override, since narrowing the OS list is not a request to start importing a library's sidecars. |
+| — (plugin) | — | object | — | `sources({ styles: { folder: 'styles', extensions: ['css'] } })` registers build inputs as catalog entities, one collection per key. A sidecar can then read them with `findEntities()`, whose queries land in the render's `refClosure` — so editing, adding or removing a part re-renders the bundle and nothing else. Reading the same files with `fs` instead works for one build and silently breaks watch, because the engine has no dependency on a file it never saw. Nothing is linked into `outputFolder`: these are inputs, not output. Named `sources` rather than `inputs` because `entity.inputs` already means something adjacent — bytes an output depends on without being entities at all. |
 | `cors` / `no-cors` | `--cors` / `--no-cors` | boolean | — | Toggle CORS on the engine's shared Express app. See `src/server.js` for the extensible header arrays plugins push onto. |
+| `server.requestTimeout` | — | number | node default (`300000`) | Milliseconds a single request may take, set on the underlying `http.Server`. Node's 5-minute default is effectively an **upload size limit expressed in seconds** — a large file over a slow link is indistinguishable from a stalled request, so it is cut off and the caller sees a truncated write rather than a readable error. Only reachable from the `http.Server`, which the engine owns, so a plugin that mounts an upload surface (`mikser-io-webdav`, `forms` with large attachments) cannot raise it for itself. `0` disables the cap: reasonable on a trusted-network build server, bad facing the internet, where it removes the only bound on how long a client can hold a connection open doing nothing. `headersTimeout` is clamped to stay at or below it. The server is also exposed as `runtime.options.httpServer`. |
 | `url` | `-u, --url <url>` | string | — | Public URL where this mikser is reachable (e.g. `https://blog.me.com`). Validated, trailing slash stripped, stamped on `runtime.options.url`. Read by webhook-capable plugins for push-vs-poll gating (`url.startsWith('https://')`); used by anything that surfaces absolute URLs externally — MCP preview URLs returned to agents, forms share links, email tracking pixels. Plugins that just need internal URLs keep using `runtime.options.port`. |
 
 ## Engine Substrate

package/docs/decisions/0012-auth-seam-in-core-identity-in-plugins.md

@@ -0,0 +1,194 @@
+# 12. Authentication is an engine seam; identity providers are plugins
+
+## Status
+
+Accepted
+
+## Context
+
+Mikser already authenticates requests. It does so in at least three places, by copy-paste, and the copies have drifted.
+
+The rule every copy claims to implement — call it the *uniform rule* — is:
+
+- token presented and valid → allow from anywhere
+- token presented and invalid → reject
+- token absent → require loopback, unless `allowRemote`
+
+`src/plugins/api.js` and `mikser-io-mcp` implement that. `mikser-io-forms` does not, despite a comment saying it does:
+
+| | token set, none presented | loopback denial | wrong token |
+| --- | --- | --- | --- |
+| `api.js` | falls back to loopback | `403` | `401` |
+| `mikser-io-mcp` | falls back to loopback | `403` (JSON-RPC `-32001`) | `401` |
+| `mikser-io-forms` | **rejects — no fallback** | **`401`** | `401` |
+
+Neither behaviour is obviously wrong. Forms is arguably the safer reading. The problem is that nobody chose: three authors wrote the same paragraph of comments and three different policies, and no test can catch it because there is nothing shared to test.
+
+The engine already exports the *primitive* (`isLoopback`) but not the *policy*. `src/utils.js` says so out loud: "For more nuanced policies (token gate + loopback fallback), plugins usually inline the check using `isLoopback()` directly." That was an accurate description of the status quo and is now the thing to fix.
+
+Three further consequences follow from having no seam:
+
+- **Token comparison is `presented !== expectedAuth`** — a plain string compare, not constant-time. Correct in every copy, and correct nowhere in particular.
+- **There is no way to add a second credential type.** Supporting OAuth for remote MCP (the MCP spec's `WWW-Authenticate` + RFC 9728 challenge, which nothing in the tree implements today) currently means editing every plugin that mounts a route.
+- **`registerRoute({ reachability })` already carries the vocabulary** — `'loopback' | 'token' | 'public'` — but each plugin recomputes it from its own config by hand, so the facade's view of exposure is only as accurate as the least careful copy.
+
+Separately, and deliberately kept separate: outbound credentials (`GOOGLE_APPLICATION_CREDENTIALS`, `GH_TOKEN`, `DIRECTUS_TOKEN`) are each read ad hoc by their provider. That is a different problem with a different answer — see *Decision*, point 5.
+
+## Decision
+
+**1. The engine gains an authentication seam. It gains no identity model.**
+
+A *verifier* is a provider-agnostic descriptor:
+
+```js
+{
+    name: 'bearer',
+    async verify(req) {},         // → null (no credential) | false (bad) | { subject, capabilities }
+    challenge? (res) {},          // optional: emit WWW-Authenticate for this scheme
+    authorizationServers?: [],    // optional: OAuth discovery metadata
+    resource?, scopesSupported?,  // consumed by mikser-io-mcp for RFC 9728
+}
+```
+
+Core ships exactly one verifier — `bearer({ token })`, constant-time via `crypto.timingSafeEqual` — plus:
+
+```js
+resolveAuth(config)                   // string | fn | verifier | { token } | [ … ] → verifier | null
+anyOf(...verifiers)                   // accept ANY of several credentials
+authorize(req, verifier, opts)        // the uniform rule, transport-agnostic
+requireAuth(verifier, opts)           // express middleware over authorize()
+reachabilityOf({ auth, token, allowRemote })         // → 'loopback' | 'token' | 'public'
+hasCapability(principal, capability)  // endpoint ceiling ∩ principal grant
+```
+
+**Several credentials on one surface.** A deployment reaches for this almost
+immediately: a handful of long-lived machine tokens (one per caller, so a leak
+scopes its own blast radius) alongside a human's OAuth token on the same routes.
+`anyOf` lives in the engine rather than in userland because the last project that
+hand-rolled it shipped a silent auth *bypass* — a composed verifier the resolver
+didn't recognise degraded to a pass-through `next()` and merely warned. The
+failure mode of getting this wrong is not "denied", it is "wide open".
+
+The three-valued merge is the whole subtlety: any verifier accepting wins; all
+reporting "nothing presented" yields `null` so loopback policy may still apply;
+**any** reporting "presented and wrong" yields `false`, which never falls back to
+loopback. A caller who presented a credential has identified itself and must be
+judged on it.
+
+`verify()` returning a principal is the primitive; `requireAuth()` is the Express convenience built on it. Both are exported, because MCP must render its denial as a JSON-RPC error body rather than an HTTP JSON body and therefore cannot use a generic middleware.
+
+Core takes no position on who a subject is, where it came from, or how it was proven. It knows only: a credential was presented or it wasn't, it verified or it didn't, and what capabilities it carries.
+
+**2. The uniform rule becomes one implementation.**
+
+The three copies are replaced by `requireAuth()`. `api.js`'s semantics win — loopback fallback, `403` for reachability denial, `401` for a bad credential — because two of three already implement it and because `403` is the honest code when the caller's *origin* is the problem rather than their credential. Forms changes behaviour; that is a deliberate, documented break, not an accident.
+
+**3. Identity providers are plugins, on the same contract.**
+
+An OAuth verifier — and, if wanted, a self-hosted authorization server — ships as `mikser-io-auth`, exporting a verifier that `resolveAuth()` accepts wherever a token string is accepted today:
+
+```js
+api({ endpoints: { admin: { auth: oauth({ issuer, audience }) } } })
+```
+
+This mirrors what WhiteBox already proved out: a seam in `server/src/auth.js`, a first-party authorization server in `server-plugin-oauth`, and an external provider in `whitebox-pro-auth-auth0` — all three interchangeable at the same seam. The one place mikser deliberately diverges is the user store: WhiteBox keeps users in Postgres because WhiteBox is a running product with members; mikser keeps them in files because mikser is a build tool with operators (see point 4).
+
+**4. Capabilities ride the credential, not a user.**
+
+`operations: ['list', 'update', 'delete', 'render']` is already a capability set; today it is bound to an *endpoint*. It becomes the verifier's output instead, so a static token is simply an identity whose capability set is fixed by config, and an OAuth token is one whose capability set is minted at login. Route gating (`allow(op)`) is unchanged and stays where it is.
+
+**Where identity is stored: Apache-format files in the working folder.**
+
+Mikser does not grow a user table. Users and groups live as `htpasswd` and `htgroup` files alongside the content they govern:
+
+```
+<workingFolder>/
+    users.htpasswd     alice:$2y$10$…            (bcrypt, apr1, or sha1)
+    groups.htgroup     editors: alice bob
+```
+
+This is ADR-0002 applied to identity rather than content, and it buys the same things files buy everywhere else in mikser: reviewable in a pull request, diffable, deployable by copying a directory, editable with `htpasswd(1)` — a tool that predates every framework this project will outlive. It also means the *format* is not ours to design, version, or migrate.
+
+Groups map to capabilities in config, so the files stay pure identity and the product decides what a group can do:
+
+```js
+auth({ groups: { editors: ['api:update', 'mcp:use'], viewers: ['api:list'] } })
+```
+
+The obvious objection is that a file cannot be written safely by a running server under concurrent requests. That is a real constraint and it is also the point: this is a store you *provision*, not one the product mutates at runtime. Self-service signup, password reset, and invite flows are explicitly not in scope — a build tool has operators, not members.
+
+**Row scope rides the credential too, opaquely.**
+
+Capabilities are verbs (`api:delete`); they cannot express *which rows exist for
+you*. A principal may therefore carry a `scope` — a value the **engine never
+inspects**. Only the plugin whose surface issued the credential knows what it
+means; for `api`/`vector`/`data` it is a sift filter, `$and`-ed with the
+endpoint's own `query`. Keeping it opaque is what stops the engine from growing
+an opinion about content.
+
+Always `$and`, never `$or`: a credential may narrow what an endpoint exposes,
+never widen it. Groups map to scopes the same way they map to capabilities, and
+membership in several groups unions with `$or` — more groups must mean more
+reach, or adding one would make a user less able.
+
+Two consequences fell out of this and are load-bearing:
+
+- **A principal-scoped response is never written to the query cache.** The cache
+  mirrors the request URL into the output folder, where nginx `try_files` serves
+  it without reaching the process. One caller's scoped rows would be handed to
+  every later caller of the same URL, unauthenticated. The key is
+  endpoint+querystring by design (it must match what nginx sees) so it cannot be
+  salted with the principal — the only safe answer is not to write.
+- **A principal scope must be a sift object, never a function.** An object is
+  pushed into the WHERE clause; a function is applied post-fetch, the form that
+  pinned a production box at 111% CPU on 1,367 entities. A function is refused
+  rather than silently accepted.
+
+The aggregated cross-plugin permission *catalog* WhiteBox uses stays **out of scope**. If it lands, it must be assembled during engine infrastructure setup, before any plugin hook runs (ADR-0005), or plugin load order becomes observable.
+
+**5. Outbound credentials stay a convention, not core.**
+
+A provider reading `process.env.GH_TOKEN` creates no god-plugin and forces no coordination — by the ADR-0006 bar it does not earn engine code. What it needs is a documented convention (`MIKSER_<PLUGIN>_<NAME>`, config-over-env precedence, redaction in logs), which is a docs change and a lint, not a subsystem.
+
+## Why this clears ADR-0006
+
+1. **Substrate, not domain.** The engine says *how* a credential is proven; plugins say *what* they gate. Core never learns what a route does.
+2. **Strengthens ADR-0004.** Today's "shared" policy is shared by duplication — the exact failure that ADR is written against. This is a consolidation of a concern mikser already has, not a new one it is claiming.
+3. **The plugin alternative is a god-plugin.** An auth plugin would have to know every other plugin's routes to gate them — the "express plugin" failure mode by name.
+4. **Plugins compose independently.** A plugin calls `resolveAuth(options.auth)` and mounts the result. No ordering, no coordination, no collision. This is the test the *catalog* fails, which is why the catalog is deferred.
+5. **Cadence.** The seam is ~80 lines whose shape has been stable in WhiteBox across its lifetime. OAuth is not stable — the MCP auth spec, RFC 9728 adoption, and the DCR debate all move monthly. Test 5 is what forces the split: **seam in core, OAuth in a plugin.**
+
+## Consequences
+
+**Easier.** One auth policy, one place, one test suite. Adding OAuth becomes a plugin nobody else has to know about. `reachability` is computed by the engine, so the facade's exposure map stops being a per-plugin promise. Constant-time comparison happens once, correctly.
+
+**Harder.** Every route-mounting plugin gets a coordinated release: core first, then a mechanical edit in `api`, `mcp`, `forms`, `decap`, `vector`. Forms changes behaviour for anyone who configured a token *and* relied on loopback bypassing it. The engine takes on a security-sensitive surface, where being wrong is worse than being absent — which is the argument for keeping it at 80 lines that do one thing.
+
+**Staging.** Core seam ships first and is purely additive; the existing inline checks keep working untouched. Plugins migrate one at a time. `mikser-io-auth` is independent of both and needed only when a remote MCP endpoint has to satisfy a spec-compliant client.
+
+## Examples
+
+- `src/auth.js` — the seam. `src/plugins/api.js` — the reference caller: auth, the
+  operation ceiling intersected with the principal's grant, and the per-request
+  scope combination. Note that every route lists `auth` **before** `allow(op)`;
+  the old order ran the capability check against an undefined principal, which
+  passes every check — a silent bypass, not a failure.
+- `mikser-io-mcp/index.js` `mountEndpoint()` — why `authorize()` exists separately
+  from `requireAuth()`: MCP answers in JSON-RPC, so it shapes its own denials.
+- `mikser-io-forms/index.js` — the drift that motivated this, now migrated. Its
+  behaviour changed: a token-gated form endpoint accepts loopback without the
+  token, and reachability denial answers 403 rather than 401, matching the others.
+- `mikser-io-auth` — identity: htpasswd/htgroup, bcrypt, an ES256 key file, and
+  the Basic and JWT verifiers.
+- `src/utils.js` `isLoopback` / `loopbackOnly` — the primitive that was already shared, and the comment that documented the missing half.
+- WhiteBox `server/src/auth.js` + `server-plugin-oauth` + `whitebox-pro-auth-auth0` — the same split, already load-bearing in production.
+
+## Watch for drift
+
+The failure mode is the engine growing an opinion about *identity*. Drift looks like: a users table; a `role` field; a login route in core; a permission catalog added "while we're here"; the seam accepting a provider-specific option so one integration is easier.
+
+For the identity files specifically, drift looks like the product writing to them — a signup route, a password-reset endpoint, a "create user" tool. The moment mikser writes an htpasswd file at runtime it has a concurrency problem, a locking problem, and a database it refuses to admit it has.
+
+The counter-question is always the same: could `mikser-io-auth` be uninstalled, leaving a working token-and-loopback engine behind? If not, the concern crossed the seam.
+
+The second, quieter drift is a plugin inlining its own check again because the seam didn't quite fit. That's a signal the seam is wrong, not a licence — the fix is to change `requireAuth()`, not to route around it.

package/docs/decisions/README.md

@@ -37,3 +37,4 @@ Decisions don't expire. They get **superseded** when we learn enough to change t
 | [0009](./0009-database-engine-substrate.md) | Sqlite is the engine's persistence substrate. Single `runtime/mikser.sqlite` file holds catalog/refs/manifest/journal as `mikser_entities` / `mikser_refs` / `mikser_snapshots` / `mikser_journal` tables. Plugins register schemas via `registerSchema(name, sql)` + `useDatabase()`. Sift→SQL translator with indexed pushdown, LRU cache for `findById`, worker-side read-only sqlite for sync template helpers, chunked journal walks + `iterateEntities` streaming, `useJournal` auto-persist (mutate the yielded entity; no explicit `updateEntry` needed), `--resume` after interrupted cycles. Replaces `Map<id, entity>` + NDJSON across every engine subsystem. | Accepted |
 | [0010](./0010-plugin-bundles-and-inline-options.md) | Plugin bundles + factory-call form + inline options. Plugins are imported by name and called as factories; `plugins: []` carries factory returns, never strings. Lifecycle plugins are `(options) => (core) => void`; renderers return `{name, options, load?, render?}`; postprocessors return `{name, options, output?, setup?, postprocess, teardown?}`. Per-plugin config moved off `runtime.config.<plugin>` — it arrives as the factory arg and is passed as `config` to `load`/`render`/`setup`/`postprocess`. | Accepted |
 | [0011](./0011-served-entities-expose-deployed-urls.md) | File and resource entities expose deployed URLs. References to served files (image/video/PDF) are `$`-keyed **served paths** (`/img/X.jpg`, `/media/clip.mp4` — the path content authors, = the entity's `meta.url`), resolving through a new `refFilter` `{ 'meta.url': … }` clause backed by an indexed `meta_url` column (schema 9.0.1 → 9.0.2). No collection-prefixed ids leak into content. (Id-refs were tried and rejected — gpoint references content by served path and its `/media/**` `resources()` library means the entity only exists because content references `/media/…`.) The `files`/`resources` plugins stamp `meta.url`, the `assets` plugin stamps `meta.presets` — so expanding a ref yields the served entity's URL set instead of a string to reconstruct. Base-relative in the live catalog (host-agnostic; consumer holds `base`), absolute in static renders (baked from `runtime.options.url`, so logic-less consumers — email, RSS, foreign apps — read a whole URL); `lookupUrl` render helper resolves a ref to `meta.url` or a named preset. SDK collapses `assetUrl(source, preset, {ext})` into one `url(ref)` join + a dev-mode SPA-fallback detector. *("Served entity" — file/resource/preset — avoids colliding with the `assets` plugin's own "asset reference" term.)* | Accepted (proven against gpoint) |
+| [0012](./0012-auth-seam-in-core-identity-in-plugins.md) | Authentication is an engine seam; identity providers are plugins. Core ships a provider-agnostic verifier contract (`{ name, verify(req), challenge? }`), a constant-time `bearer()`, `resolveAuth()`, `authorize()`/`requireAuth()` and `reachabilityOf()` — replacing the same token+loopback rule hand-copied into `api`, `mcp` and `forms`, where it had already drifted into three behaviours. A configured verifier gates every request (no loopback bypass, WhiteBox posture); a plain `token:` keeps the trusted-local-host model. OAuth, RFC 9728 discovery and identity ship as `mikser-io-auth`; users and groups are Apache-format `htpasswd`/`htgroup` files in the working folder (ADR-0002), never written at runtime. Credentials compose (`anyOf`) and may carry an opaque row `scope` the engine never inspects, `$and`-ed with the endpoint's own query; scoped responses are never cached. No user table, no roles, no permission catalog in core. | Accepted |

package/index.js

@@ -1,6 +1,7 @@
 export { default as runtime } from './src/runtime.js'
 export * as constants from './src/constants.js'
 export * from './src/utils.js'
+export * from './src/auth.js'
 export * from './src/lifecycle.js'
 export * from './src/database/index.js'
 export * from './src/journal.js'
@@ -23,6 +24,7 @@ export * from './src/routes.js'
 // for the v9 plugin shape.
 export { api }           from './src/plugins/api.js'
 export { assets }        from './src/plugins/assets.js'
+export { sources }       from './src/plugins/sources.js'
 export { commands }      from './src/plugins/commands.js'
 export { data }          from './src/plugins/data.js'
 export { documents }     from './src/plugins/documents.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.3.1",
+  "version": "9.12.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {
@@ -64,8 +64,10 @@
     "@ai-sdk/openai": "^3.0.71",
     "fluent-ffmpeg": "^2.1.3",
     "mikser-io-decap": "file:../mikser-io-decap",
+    "mikser-io-layouts": "file:../mikser-io-layouts",
     "mikser-io-post-mjml": "file:../mikser-io-post-mjml",
     "mikser-io-post-pdf": "file:../mikser-io-post-pdf",
+    "mikser-io-provider-gdrive": "file:../mikser-io-provider-gdrive",
     "mikser-io-render-eta": "file:../mikser-io-render-eta",
     "mikser-io-render-liquid": "file:../mikser-io-render-liquid",
     "mikser-io-render-markdown": "file:../mikser-io-render-markdown",

package/src/auth.js

@@ -0,0 +1,229 @@
+import crypto from 'node:crypto'
+import { isLoopback } from './utils.js'
+
+// Authentication seam (ADR-0012).
+//
+// The engine says HOW a credential is proven. Plugins say WHAT they gate.
+// Nothing here knows about users, sessions, roles, or OAuth — a verifier
+// that does is an external package (mikser-io-auth), plugged in at the
+// same seam a bare token string plugs into.
+//
+// A verifier is a provider-agnostic descriptor:
+//
+//   {
+//     name,                        // for logs: 'bearer', 'oauth', …
+//     async verify(req),           // → null (no credential presented)
+//                                  //   false (presented, rejected)
+//                                  //   { subject, capabilities?, scope? }
+//     challenge?(req, res),        // set WWW-Authenticate before a 401
+//     authorizationServers?, resource?, scopesSupported?,   // RFC 9728
+//   }
+//
+// A principal carries three things, and the engine understands only two:
+//
+//   subject       who this is — a string, for logs and audit
+//   capabilities  which verbs they hold, or null for "not verb-scoped"
+//   scope         which ROWS they may see — an OPAQUE value the engine
+//                 never inspects. The plugin that issued the credential's
+//                 surface is the only thing that knows what it means (for
+//                 api/vector/data it's a sift filter ANDed with the
+//                 endpoint's own `query`). Keeping it opaque here is what
+//                 stops the engine from growing an opinion about content.
+//
+// `verify()` is the primitive; requireAuth() is the Express convenience
+// built on it. Both are exported because a surface whose denials aren't
+// HTTP-shaped (MCP answers in JSON-RPC) needs the primitive directly.
+
+// The static long-lived token verifier — mikser's default and, for a build
+// tool driven by config files, usually the only one anybody needs.
+export function bearer({ token, name = 'bearer', subject = 'token', capabilities = null, scope = null } = {}) {
+    if (!token) throw new Error('bearer({ token }) requires a token')
+    const expected = Buffer.from(`Bearer ${token}`, 'utf8')
+
+    return {
+        name,
+        capabilitiesDeclared: capabilities,
+        async verify(req) {
+            const header = req.headers?.authorization ?? req.get?.('authorization')
+            if (!header) return null
+            const presented = Buffer.from(header, 'utf8')
+            // timingSafeEqual throws on a length mismatch, so the length
+            // check has to come first — it leaks length, which a Bearer
+            // header already does structurally.
+            const ok = presented.length === expected.length &&
+                       crypto.timingSafeEqual(presented, expected)
+            return ok ? { subject, capabilities, scope } : false
+        },
+        challenge(req, res) {
+            res.set('WWW-Authenticate', 'Bearer')
+        },
+    }
+}
+
+// Normalize whatever a plugin's `auth:` option holds into a verifier, or
+// null for "nothing configured". Accepts:
+//
+//   undefined / null       → null
+//   'sekrit'               → bearer({ token })
+//   { token: 'sekrit' }    → bearer({ token })      (the ep.token shape)
+//   { verify: async fn }   → used as-is (mikser-io-auth, custom verifiers)
+//   async (req) => {…}     → wrapped as a bare verify function
+//
+// Returning null rather than throwing is deliberate: "no auth configured"
+// is a legitimate, common state for a build tool running on localhost.
+// What it MEANS is the caller's decision — see requireAuth's allowRemote.
+export function resolveAuth(config) {
+    if (!config) return null
+    // An array is "any of these credentials will do" — several machine
+    // tokens, or machine tokens alongside a human's OAuth token. See anyOf().
+    if (Array.isArray(config)) {
+        const verifiers = config.map(resolveAuth).filter(Boolean)
+        if (!verifiers.length) return null
+        return verifiers.length === 1 ? verifiers[0] : anyOf(...verifiers)
+    }
+    if (typeof config === 'string') return bearer({ token: config })
+    // An object carrying verify() wins BEFORE the bare-function branch: a
+    // verifier may itself be a callable (mikser-io-auth's auth() is both the
+    // plugin and the verifier), and treating that as a raw verify function
+    // would call the plugin with a request.
+    if (typeof config.verify === 'function') return config
+    if (typeof config === 'function') return { name: 'custom', verify: config }
+    if (config.token) return bearer({ token: config.token })
+    return null
+}
+
+// How exposed is a surface? The vocabulary registerRoute() already uses.
+// Computed here so a facade's view of exposure stops being a per-plugin
+// promise (three plugins, three hand-rolled copies — see ADR-0012).
+export function reachabilityOf({ auth, token, allowRemote } = {}) {
+    if (auth || token) return 'token'
+    return allowRemote ? 'public' : 'loopback'
+}
+
+// The uniform rule, in one place.
+//
+//   verifier configured:
+//     credential valid              → allow, from anywhere
+//     credential presented, invalid → 401
+//     credential absent             → 401 (loopback does NOT bypass a
+//                                     configured verifier — same posture
+//                                     as WhiteBox), unless trustLoopback
+//   no verifier:
+//     loopback, or allowRemote      → allow
+//     otherwise                     → 403
+//
+// `trustLoopback: true` restores the older mikser behaviour where a
+// token-gated endpoint stayed open to localhost. It exists so the api and
+// mcp plugins can keep their documented semantics for a plain `token:`
+// while a real verifier gets the stricter default.
+export async function authorize(req, verifier, { allowRemote = false, trustLoopback = false } = {}) {
+    const local = isLoopback(req.ip)
+
+    if (verifier) {
+        const result = await verifier.verify(req)
+        if (result) return { ok: true, principal: result }
+        if (result === false) {
+            return { ok: false, status: 401, reason: 'invalid',
+                     error: 'Invalid credential' }
+        }
+        // Nothing presented.
+        if (trustLoopback && local) return { ok: true, principal: { subject: 'loopback' } }
+        return { ok: false, status: 401, reason: 'missing',
+                 error: 'Authentication required' }
+    }
+
+    if (allowRemote || local) return { ok: true, principal: { subject: 'anonymous' } }
+    return {
+        ok: false, status: 403, reason: 'reachability',
+        error: 'Endpoint accepts loopback connections only — configure a token or set allowRemote: true to enable remote access',
+    }
+}
+
+// Express flavour of the same rule.
+export function requireAuth(verifier, options = {}) {
+    return async (req, res, next) => {
+        let outcome
+        try {
+            outcome = await authorize(req, verifier, options)
+        } catch (err) {
+            options.logger?.error?.('auth: verifier threw — %s', err.message)
+            return res.status(500).json({ error: 'Authentication failed' })
+        }
+        if (outcome.ok) {
+            req.principal = outcome.principal
+            return next()
+        }
+        if (outcome.status === 401) verifier?.challenge?.(req, res)
+        res.status(outcome.status).json({ error: outcome.error })
+    }
+}
+
+// Accept ANY of several credentials on one surface.
+//
+// This is the shape a real deployment reaches for almost immediately: a
+// handful of long-lived machine tokens (one per caller, so a leaked token
+// scopes the blast radius) plus a human's OAuth token on the same routes.
+// It lives here rather than in userland because the last project that
+// hand-rolled it shipped a silent auth BYPASS — a composed verifier that
+// the resolver didn't recognise degraded to a pass-through `next()` and
+// merely warned. The failure mode of getting this wrong is not "denied",
+// it is "wide open", so it belongs in one tested place.
+//
+// The three-valued merge is the whole subtlety:
+//
+//   any verifier accepts        → accept (first wins)
+//   all say "nothing presented" → null   (loopback policy may still apply)
+//   any says "presented, bad"   → false  (NEVER falls back to loopback —
+//                                  a caller who presented a credential has
+//                                  identified itself and must be judged)
+export function anyOf(...verifiers) {
+    const list = verifiers.filter(Boolean)
+    if (!list.length) return null
+    if (list.length === 1) return list[0]
+
+    // Preserve discovery metadata so an MCP client can still find the
+    // authorization server through the composite. First verifier that
+    // advertises one wins; a static token has nothing to advertise.
+    const discovering = list.find(v => v.authorizationServers?.length)
+
+    return {
+        name: `anyOf(${list.map(v => v.name ?? '?').join(',')})`,
+        authorizationServers: discovering?.authorizationServers,
+        resource:             discovering?.resource,
+        scopesSupported:      [...new Set(list.flatMap(v => v.scopesSupported ?? []))],
+
+        async verify(req) {
+            let rejected = false
+            for (const verifier of list) {
+                const result = await verifier.verify(req)
+                if (result) return result
+                if (result === false) rejected = true
+            }
+            return rejected ? false : null
+        },
+
+        // Challenge with the verifier that can actually be satisfied
+        // interactively — pointing a browser at "Bearer" when the real
+        // option is OAuth discovery helps nobody.
+        challenge(req, res) {
+            const chooser = discovering ?? list.find(v => v.challenge)
+            chooser?.challenge?.(req, res)
+        },
+    }
+}
+
+// Does this principal hold a capability?
+//
+// `capabilities: null` means "this credential is not capability-scoped" —
+// a bare static token with nothing declared, which is every endpoint that
+// worked before ADR-0012. Such a credential passes any capability check,
+// because the endpoint's own `operations` list is what bounds it. A
+// credential that DOES declare capabilities is bound by them as well, so
+// a request's reach is the INTERSECTION of the endpoint's ceiling and the
+// principal's grant — never the union.
+export function hasCapability(principal, capability) {
+    if (!capability) return true
+    const caps = principal?.capabilities
+    if (caps == null) return true
+    return caps.includes(capability)
+}

package/src/config.js

@@ -1,12 +1,34 @@
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
+import { checksum } from './utils.js'
 import path from 'node:path'
 
 onLoad(async () => {
     const logger = useLogger()
     const configFile = path.resolve(runtime.options.config)
     logger.info('Config: %s', configFile)
+
+    // Stamp the config so a change to it can invalidate the derived cache.
+    //
+    // Without this, editing mikser.config.js invalidated NOTHING: flipping
+    // an option that changes every page's destination reported "36 unchanged"
+    // and left the previous output in place. The config was genuinely read —
+    // --force applied it immediately — it simply took part in no
+    // invalidation, so the only symptom was output that did not match the
+    // config, with nothing saying so.
+    //
+    // The file's bytes only. A config that imports other modules will not
+    // notice a change in those, which is a real limit worth knowing rather
+    // than a reason to hash the whole module graph.
+    try {
+        runtime.options.configChecksum = await checksum(configFile)
+    } catch {
+        // No config file is a legitimate state (defaults all the way down);
+        // absent stamp means "nothing to compare", not "changed".
+        runtime.options.configChecksum = null
+    }
+
     try {
         const config = await import(configFile)
         if (typeof config.default == 'function') {

package/src/database/index.js

@@ -247,10 +247,38 @@ export function createSqliteDatabase({
         handle = new Database(dbPath)
         setupConnection()
 
-        const recorded = handle.prepare('SELECT value FROM mikser_meta WHERE key = ?')
-            .get('schema_version')?.value
+        const stmtMeta = handle.prepare('SELECT value FROM mikser_meta WHERE key = ?')
+        const recorded = stmtMeta.get('schema_version')?.value
+
+        // A config change invalidates the cache for the same reason a version
+        // change does: the derived state was computed under different rules.
+        //
+        // Before this, editing mikser.config.js invalidated nothing — flipping
+        // an option that changes every page's destination reported "36
+        // unchanged" and left the previous output in place. The config was
+        // read; it simply took part in no invalidation, so the only symptom
+        // was output that did not match the config and nothing saying so.
+        //
+        // Treated exactly like a version mismatch rather than something
+        // narrower: a config edit can change how sources are PARSED (a mapper
+        // transform, documents() options) as well as how they are rendered,
+        // so invalidating only the render manifest would still leave stale
+        // entities. Per ADR-0002 the files are the source of truth, so
+        // rebuilding is always safe — just slower.
+        const recordedConfig = stmtMeta.get('config_checksum')?.value
+        const currentConfig = runtime.options.configChecksum ?? null
+        const configChanged = Boolean(recordedConfig && currentConfig && recordedConfig !== currentConfig)
+
         let upgradedFromVersion = null
-        if (recorded && recorded !== version) {
+        if (configChanged && !(recorded && recorded !== version)) {
+            logger?.warn(
+                'Config changed since the last run. Wiping the cache and rebuilding from sources ' +
+                '(files are the source of truth — no source data is affected). Note this tracks the ' +
+                'bytes of %s only: a change in a module it imports is not seen.',
+                runtime.options.config,
+            )
+        }
+        if ((recorded && recorded !== version) || configChanged) {
             // Schema mismatch on upgrade or downgrade. Per ADR-0002 the
             // files on disk are the source of truth and this database
             // is a derived cache, so the right behavior is to wipe the
@@ -261,10 +289,12 @@ export function createSqliteDatabase({
             // expect a cold-start rebuild on this run. No data loss
             // beyond the cache itself; everything in mikser.sqlite is
             // recoverable from the working folder.
-            logger?.warn(
-                'Database schema mismatch: stored=%s, current=%s. Wiping the cache and rebuilding from sources (files are the source of truth — no source data is affected).',
-                recorded, version,
-            )
+            if (recorded && recorded !== version) {
+                logger?.warn(
+                    'Database schema mismatch: stored=%s, current=%s. Wiping the cache and rebuilding from sources (files are the source of truth — no source data is affected).',
+                    recorded, version,
+                )
+            }
             handle.close()
             handle = null
 
@@ -277,12 +307,16 @@ export function createSqliteDatabase({
                 }
             }
 
-            upgradedFromVersion = recorded
+            // Non-null marks the provisioning context as firstRun/upgraded,
+            // which is the right shape for a config change too: what the
+            // provisioners see is an empty-state database either way.
+            upgradedFromVersion = recorded ?? 'config'
             handle = new Database(dbPath)
             setupConnection()
         }
-        handle.prepare('INSERT OR REPLACE INTO mikser_meta (key, value) VALUES (?, ?)')
-            .run('schema_version', version)
+        const stmtStamp = handle.prepare('INSERT OR REPLACE INTO mikser_meta (key, value) VALUES (?, ?)')
+        stmtStamp.run('schema_version', version)
+        if (currentConfig) stmtStamp.run('config_checksum', currentConfig)
 
         // Build provisioning context. firstRun is true when the file
         // didn't exist before this open OR when the schema mismatch

package/src/manager.js

@@ -4,6 +4,7 @@ import cron from 'node-cron'
 import { onProcess, onFinalized } from './lifecycle.js'
 import { useLogger } from './engine.js'
 import { ACTION } from './constants.js'
+import { junkFilter } from './utils.js'
 
 const tasks = []
 
@@ -67,7 +68,13 @@ export async function deletedHook(name, context) {
     }
 }
 
-export function watch(name, folder, options = { interval: 1000, binaryInterval: 3000, ignored: /[\/\\]\./, ignoreInitial: true }) {
+// Dot-prefixed anything, plus the OS/file-manager litter that is NOT
+// dot-prefixed — Thumbs.db and desktop.ini were measurably being watched.
+// A function rather than a regex because chokidar 4+ dropped glob support in
+// `ignored` and a function is the one form that has stayed stable.
+const ignoreJunk = (filePath) => /[/\\]\./.test(filePath) || junkFilter()(filePath)
+
+export function watch(name, folder, options = { interval: 1000, binaryInterval: 3000, ignored: ignoreJunk, ignoreInitial: true }) {
     if (runtime.options.watch !== true) return
 
     chokidar.watch(folder, options)