mikser-io 9.3.0 → 9.7.0

package/docs/configuration.md

@@ -58,7 +58,9 @@ 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. |
 | `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'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.3.0",
+  "version": "9.7.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/catalog.js

@@ -319,6 +319,28 @@ onPersist(async () => {
 })
 
 onFinalize(async () => {
+    // Second drain, and the one that closes the cycle.
+    //
+    // onPersist runs BEFORE render, so the drain above only ever sees what
+    // the load and process phases journalled. Everything a render or a
+    // postprocess journals lands after it — and onFinalized's clearJournal()
+    // then throws those entries away unread. The manifest never had this
+    // problem because it drains at onFinalize; the catalog simply had a
+    // shorter view of the same journal.
+    //
+    // The visible symptom was pruning that silently did nothing: a render
+    // asking for `catalog: false` journals its DELETE once the render
+    // resolves, which is past persist, so the row stayed. gpoint's cms
+    // accumulated 1,134 scratch entities carrying 86 MB of render payload,
+    // took its public endpoint from 70ms to 8-15s, and blanked the site.
+    //
+    // Draining again here rather than moving the persist drain: the phases
+    // before render still need their mutations committed at persist (the
+    // render reads the catalog), and journal consumers are named and
+    // independent, so a second pass only ever picks up what the first could
+    // not have seen.
+    await applyJournalMutations()
+
     // Checkpoint the WAL so the main file size stays representative
     // and external tools (mikser --verify on a separate run, debug
     // scripts) see committed state. PASSIVE never blocks readers or

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)

package/src/manifest.js

@@ -61,8 +61,6 @@ import { filterKey } from './track.js'
 import { findById } from './catalog.js'
 import { useDatabase, registerSchema } from './database/index.js'
 
-export { inputHashOf } from './utils.js'
-
 // Schema registration. Applied at db.open(). PRIMARY KEY (id,
 // destination) — leading id column means `WHERE id = ?` queries use the
 // PK index, no separate id index needed. Parent index is for pagination
@@ -542,11 +540,27 @@ onFinalize(async () => {
     const m = sharedManifest
 
     // 2a. Stage file unlinks for deleted entities + their children.
+    const deleted = new Set(deletedIds)
     const filesToUnlink = []
+    const staged = new Set()
+    const stageUnlink = (destination) => {
+        if (!destination || staged.has(destination)) return
+        staged.add(destination)
+        filesToUnlink.push({ destination, reason: 'Entity deleted' })
+    }
     for (const id of deletedIds) {
-        const rows = m._stmtSelectByIdOrParent.all(id, id)
-        for (const row of rows) {
-            filesToUnlink.push({ destination: row.destination, reason: 'Entity deleted' })
+        for (const row of m._stmtSelectByIdOrParent.all(id, id)) {
+            stageUnlink(row.destination)
+        }
+    }
+    // Recorded snapshots only describe PRIOR cycles. An entity rendered and
+    // deleted within the same cycle has no row to look its destination up in —
+    // on a first build there is no row at all — so the file it just wrote would
+    // survive both the entity and its snapshot. Take the destination from this
+    // cycle's render entries instead.
+    for (const { entity } of renderedEntries) {
+        if (deleted.has(entity.id) || (entity.parent && deleted.has(entity.parent))) {
+            stageUnlink(entity.destination)
         }
     }
 
@@ -581,8 +595,20 @@ onFinalize(async () => {
     }
 
     // 2e. Hash the rendered output files (async).
+    //
+    // An id can appear in BOTH drains within one cycle — rendered, then
+    // deleted. A render that opts out of the catalog journals its DELETE the
+    // moment it resolves, so the RENDER and the DELETE sit in the same
+    // journal. 3a below drops the snapshot and 3c would insert it straight
+    // back, undoing the delete inside its own transaction. The DELETE wins:
+    // the entity is gone, so nothing may go on describing it. Skipping here
+    // rather than in 3c also saves hashing an output that was just unlinked.
+    //
+    // `parent` is checked too, mirroring _stmtDeleteByIdOrParent — a deleted
+    // parent takes its paginated children's snapshots with it.
     const recordedSnapshots = []
     for (const { entity, deps } of renderedEntries) {
+        if (deleted.has(entity.id) || (entity.parent && deleted.has(entity.parent))) continue
         const outputHash = await hashOutputFile(entity.destination)
         recordedSnapshots.push(buildSnapshot(entity, deps, outputHash))
     }

package/src/plugins/api.js

@@ -3,6 +3,7 @@ import { access, writeFile, mkdir, rm } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import _ from 'lodash'
 import sift from 'sift'
+import { resolveAuth, requireAuth, hasCapability, reachabilityOf } from '../auth.js'
 import { useRenderer } from '../render.js'
 import { mimeForEntity, isLoopback, ExpandError, useCollection } from '../utils.js'
 import { registerRoute } from '../routes.js'
@@ -447,6 +448,55 @@ export function api(options = {}) {
                 ? ep.query
                 : null
 
+            // Principal-bound scope (ADR-0012). A credential may carry its
+            // OWN row filter — "gpoint-web sees only /web" — which is ANDed
+            // with the endpoint's, never ORed: a credential can narrow what
+            // an endpoint exposes, never widen it. That direction is the
+            // whole safety property, so the combination is $and and there is
+            // no code path that produces anything else.
+            //
+            // Both halves stay sift OBJECTS so queryEntities can push them
+            // into the WHERE clause. A function scope is applied post-fetch
+            // — the form that pinned a box at 111% CPU on 1,367 entities —
+            // so a principal scope is REQUIRED to be an object, and a
+            // function endpoint scope keeps its post-fetch path while the
+            // principal's half still pushes down.
+            const scopeFor = (req) => {
+                const principal = req.principal?.scope
+                if (!principal) return { query, matchesScope, principalScoped: false }
+                if (typeof principal !== 'object' || Array.isArray(principal)) {
+                    throw new Error(
+                        'api: a principal scope must be a sift filter object — ' +
+                        'a function cannot be pushed into the query and would be ' +
+                        'applied to every row the caller matched'
+                    )
+                }
+                // queryEntities takes ONE scope, so the two halves have to
+                // become one value of a form it understands:
+                //
+                //   object endpoint scope → { $and: [ … ] }, fully pushed
+                //     into the WHERE clause. The form to prefer, and the
+                //     one gpoint uses.
+                //   function endpoint scope → one combined function, applied
+                //     post-fetch. No pushdown, but that endpoint already
+                //     chose post-fetch; the principal's half just narrows it
+                //     further. Returning the object here instead would
+                //     SILENTLY DROP the endpoint's own filter.
+                const principalMatches = sift(principal)
+                const merged = typeof query === 'function'
+                    ? (entity) => query(entity) && principalMatches(entity)
+                    : query
+                        ? { $and: [query, principal] }
+                        : principal
+                return {
+                    query: merged,
+                    matchesScope: matchesScope
+                        ? (entity) => matchesScope(entity) && principalMatches(entity)
+                        : principalMatches,
+                    principalScoped: true,
+                }
+            }
+
             // The same scope as a PREDICATE. Two paths hold one entity in
             // hand and have no query to push a filter into — admitting a
             // POST /render body, and the graph-subscription filter — so
@@ -537,31 +587,39 @@ export function api(options = {}) {
             // require the token everywhere, run mikser bound to a
             // non-loopback interface only (or behind a proxy that
             // doesn't forward loopback origin).
-            const expectedAuth = ep.token ? `Bearer ${ep.token}` : null
-            const auth = (req, res, next) => {
-                const presented = req.headers.authorization
-                if (expectedAuth && presented && presented !== expectedAuth) {
-                    return res.status(401).json({ error: 'Unauthorized' })
-                }
-                if (presented === expectedAuth && expectedAuth) {
-                    return next()   // valid token from anywhere
-                }
-                if (ep.allowRemote || isLoopback(req.ip)) {
-                    return next()
-                }
-                res.status(403).json({
-                    error: expectedAuth
-                        ? 'Token required from non-loopback sources'
-                        : 'Endpoint accepts loopback connections only — configure a token or set allowRemote: true to enable remote access',
-                })
-            }
-
+            // The uniform rule now lives in the engine (ADR-0012), so this
+            // endpoint, mcp's and forms' cannot drift apart again. `auth`
+            // takes any verifier — a list of them, HTTP Basic, OAuth — while
+            // `token` keeps the trusted-local-host model it always had.
+            const verifier      = resolveAuth(ep.auth ?? ep.token)
+            const trustLoopback = !ep.auth && !!ep.token
+            const auth = requireAuth(verifier, { allowRemote: ep.allowRemote, trustLoopback, logger })
+
+            // ORDER IS LOAD-BEARING: every route lists `auth` BEFORE
+            // `allow(op)`. The capability half reads req.principal, which
+            // only exists once auth has run — with the old order it read
+            // undefined, and an undefined principal passes every check.
+            // That is a silent bypass, not a failure, so it stays written
+            // down rather than remembered.
+            //
+            // Reach is the INTERSECTION of two independent limits: what the
+            // endpoint exposes, and what the caller's credential carries. A
+            // credential declaring `api:delete` still cannot delete on an
+            // endpoint whose `operations` omits it, and a bare token (which
+            // declares nothing, capabilities === null) is bounded by the
+            // endpoint alone — which is exactly how every endpoint behaved
+            // before this existed.
             const allow = (op) => (req, res, next) => {
                 if (!allowedOps.has(op)) {
                     return res.status(403).json({
                         error: `Operation '${op}' is not allowed on endpoint '${name}'`,
                     })
                 }
+                if (!hasCapability(req.principal, `api:${op}`)) {
+                    return res.status(403).json({
+                        error: `Your credential does not carry 'api:${op}'`,
+                    })
+                }
                 next()
             }
 
@@ -572,7 +630,7 @@ export function api(options = {}) {
             // per endpoint so per-endpoint renderTimeout overrides land.
             const { render } = useRenderer(runtime, { defaultTimeout: renderTimeout })
 
-            router.get('/entities', allow('list'), auth, async (req, res) => {
+            router.get('/entities', auth, allow('list'), async (req, res) => {
                 const t0 = Date.now()
                 try {
                     const parsed = parseQueryString(req.query)
@@ -599,7 +657,7 @@ export function api(options = {}) {
                         skip,
                         limit,
                         expand: parsed.expand,
-                        scope: query,
+                        scope: scopeFor(req).query,
                     }))
 
                     const page = Math.floor(skip / limit) + 1
@@ -618,7 +676,20 @@ export function api(options = {}) {
                     // nginx's `try_files` sees, no hashing on either
                     // side. See the caching docs for the nginx config
                     // that wires the failover.
-                    if (cacheEnabled && runtime.options.outputFolder) {
+                    // NEVER cache a principal-scoped response. The cache
+                    // mirrors the request URL into the OUTPUT folder, where
+                    // nginx try_files serves it without ever reaching this
+                    // process — so one caller's scoped rows would be handed
+                    // to every later caller of the same URL, unauthenticated.
+                    // The cache key is endpoint+querystring by design (it has
+                    // to match what nginx sees), so it cannot be salted with
+                    // the principal; the only safe answer is not to write.
+                    if (cacheEnabled && scopeFor(req).principalScoped) {
+                        logger.debug(
+                            'Api[%s] response not cached — caller %j carries its own scope',
+                            name, req.principal?.subject ?? 'unknown')
+                    }
+                    if (cacheEnabled && !scopeFor(req).principalScoped && runtime.options.outputFolder) {
                         const url = req.originalUrl || req.url || ''
                         const qIdx = url.indexOf('?')
                         const rawQueryString = qIdx >= 0 ? url.slice(qIdx + 1) : ''
@@ -704,7 +775,7 @@ export function api(options = {}) {
             // POST /entities/query — body-based query for anything that
             // doesn't fit cleanly in a URL: $and/$or, nested operators,
             // regex, projections, etc. Same shape as a Mongo find.
-            router.post('/entities/query', allow('list'), auth, async (req, res) => {
+            router.post('/entities/query', auth, allow('list'), async (req, res) => {
                 const t0 = Date.now()
                 try {
                     const { filter = {}, sort, fields, expand, page: rawPage = 1, limit: rawLimit, skip: rawSkip } = req.body ?? {}
@@ -716,7 +787,7 @@ export function api(options = {}) {
                         fields: resolveFields(fields),
                         skip, limit,
                         expand,
-                        scope: query,
+                        scope: scopeFor(req).query,
                     })
 
                     const page = Math.floor(skip / limit) + 1
@@ -759,7 +830,7 @@ export function api(options = {}) {
             // whose onChange writes SSE frames to `res`. subscribe()
             // throws on invalid input; we wrap it so the error becomes a
             // 400 BEFORE SSE headers are sent.
-            router.get('/entities/subscribe', allow('subscribe'), auth, (req, res) => {
+            router.get('/entities/subscribe', auth, allow('subscribe'), (req, res) => {
                 let filterFn = null
                 let expand = null
                 try {
@@ -782,7 +853,7 @@ export function api(options = {}) {
                 let sub
                 try {
                     sub = subscribe({
-                        scope:  query,
+                        scope:  scopeFor(req).query,
                         filter: filterFn,
                         expand,
                         onChange: ({ operation, entity, causedBy }) => {
@@ -828,7 +899,7 @@ export function api(options = {}) {
                 )
             })
 
-            router.put('/entities', allow('update'), auth, async (req, res) => {
+            router.put('/entities', auth, allow('update'), async (req, res) => {
                 try {
                     const { collection, relativePath, content = '' } = req.body
                     await useCollection(runtime, collection).write(relativePath, content)
@@ -839,7 +910,7 @@ export function api(options = {}) {
                 }
             })
 
-            router.delete('/entities', allow('delete'), auth, async (req, res) => {
+            router.delete('/entities', auth, allow('delete'), async (req, res) => {
                 try {
                     const { collection, relativePath } = req.body
                     await useCollection(runtime, collection).remove(relativePath)
@@ -850,7 +921,7 @@ export function api(options = {}) {
                 }
             })
 
-            router.post('/render', allow('render'), auth, async (req, res) => {
+            router.post('/render', auth, allow('render'), async (req, res) => {
                 // Hoisted so the catch can name WHICH entity failed. A
                 // render that throws before this is assigned is itself the
                 // finding — it means the body never parsed.
@@ -868,7 +939,8 @@ export function api(options = {}) {
                     renderId = entityShape.id
                     // When the endpoint declares a scope, reject anything
                     // outside it BEFORE pushing through the renderer.
-                    if (matchesScope && !matchesScope(entityShape)) {
+                    const { matchesScope: inScope } = scopeFor(req)
+                    if (inScope && !inScope(entityShape)) {
                         return res.status(403).json({ error: 'Entity is outside this endpoint\'s scope' })
                     }
                     const { output, entity } = await render(entityShape, options)

package/src/server.js

@@ -175,7 +175,7 @@ export function setupServer() {
             runtime.options.app.use(express.static(runtime.options.outputFolder))
 
             await new Promise(resolve => {
-                runtime.options.app.listen(runtime.options.port, () => {
+                const httpServer = runtime.options.app.listen(runtime.options.port, () => {
                     // Public URL wins for operator-clickable log lines —
                     // a reverse-proxy/tunnel/ngrok setup binds locally but
                     // is reached externally at runtime.options.url. Fall
@@ -184,6 +184,36 @@ export function setupServer() {
                     logger.info('Server listening: %s', externalUrl)
                     resolve()
                 })
+
+                // Node caps a single request at 5 minutes (requestTimeout,
+                // default 300_000ms), which is not a timeout in the usual
+                // sense here — it is an upload size limit expressed in
+                // seconds. A large file over a slow link is indistinguishable
+                // from a stalled request, so it gets cut off, and the caller
+                // sees a truncated write rather than an error it can read.
+                //
+                // Only reachable from the http.Server, which the engine owns
+                // — a plugin that mounts an upload surface (webdav, forms with
+                // large attachments) cannot raise it for itself. Hence a
+                // config knob here rather than in the plugin.
+                //
+                // `0` disables the cap entirely. That is a deliberate choice
+                // for a trusted-network build server and a bad one facing the
+                // internet, where it removes the only bound on how long a
+                // client can hold a connection open doing nothing.
+                const requestTimeout = runtime.config.server?.requestTimeout
+                if (requestTimeout != null) {
+                    httpServer.requestTimeout = requestTimeout
+                    // headersTimeout must not exceed requestTimeout, or Node
+                    // warns and the shorter one silently wins. Keep it at the
+                    // smaller of its default and the new request timeout.
+                    if (requestTimeout !== 0) {
+                        httpServer.headersTimeout = Math.min(httpServer.headersTimeout, requestTimeout)
+                    }
+                    logger.info('Server request timeout: %s',
+                        requestTimeout === 0 ? 'disabled' : `${requestTimeout}ms`)
+                }
+                runtime.options.httpServer = httpServer
             })
         })
     })

package/src/source.js

@@ -43,7 +43,7 @@ import { globby } from 'globby'
 import pMap from 'p-map'
 import runtime from './runtime.js'
 import { ACTION } from './constants.js'
-import { checksum as fileChecksum } from './utils.js'
+import { checksum as fileChecksum, junkIgnore } from './utils.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { useDatabase } from './database/index.js'
 
@@ -358,7 +358,11 @@ export function useSource(core, options) {
             cwd: absFolder,
             absolute: true,
             onlyFiles: true,
-            ignore,
+            // OS and file-manager litter first, so a plugin's own `ignore`
+            // adds to it rather than having to restate it. globby's
+            // dot: false default already hid the macOS ones; Thumbs.db and
+            // desktop.ini are not dotfiles and were being scanned.
+            ignore: [...junkIgnore(), ...ignore],
         })
         if (phase === 'import') trackProgress(progressLabel, files.length)
         const scanStats = { emitted: 0, skipped: 0, deleted: 0 }

package/src/subscriptions.js

@@ -35,6 +35,7 @@ import { onFinalize } from './lifecycle.js'
 import { useJournal } from './journal.js'
 import { OPERATION } from './constants.js'
 import { assertExpand, queryEntities } from './catalog.js'
+import sift from 'sift'
 
 // Per-module subscription registry. The dispatcher walks this Set
 // every onFinalize. A Set (not a Map) because subscriptions are keyed
@@ -50,10 +51,34 @@ const opNames = {
     [OPERATION.DELETE]: 'delete',
 }
 
+// A scope may be a predicate OR a sift object, and this is the ONE place that
+// difference is resolved.
+//
+// An endpoint declares its scope once and it then reaches several consumers:
+// queryEntities merges a sift object into the WHERE clause, while a dispatch
+// holding a single entity can only test it. Every consumer that reached for
+// `scope(entity)` therefore worked with the function form and threw
+// `TypeError: scope is not a function` with the object one — which took a
+// production render endpoint down and, because it needed a live subscription to
+// fire at all, reproduced in nothing smaller than production.
+//
+// Compiling here rather than at each call site is the point: a call site that
+// has to remember is a call site that will forget, and the next consumer added
+// inherits the fix instead of the bug.
+function toPredicate(scope) {
+    if (scope == null) return null
+    if (typeof scope === 'function') return scope
+    if (typeof scope === 'object') return sift(scope)
+    throw new Error('subscribe: scope must be a function or a sift filter object')
+}
+
 export function subscribe({ filter, scope, expand, onChange, signal } = {}) {
     if (typeof onChange !== 'function') {
         throw new Error('subscribe: onChange must be a function')
     }
+    // Normalised before it is stored, so both the journal-walk dispatch and the
+    // graph dispatch below see a predicate and neither has to care.
+    scope = toPredicate(scope)
 
     // Reject bad expand at registration. A misconfigured subscriber
     // can otherwise open a session that's expensive to re-dispatch on

package/src/utils.js

@@ -846,4 +846,111 @@ export function useCollection(runtime, name) {
             await unlink(uri)
         },
     }
-}
+}
+
+// ── operating-system and file-manager litter ────────────────────────────
+//
+// Exposing a source folder over a network filesystem (mikser-io-webdav) or
+// simply opening it in a file manager drops metadata files into it. Every one
+// of them would otherwise become an entity, render a page, and appear in a
+// catalog.
+//
+// The dot-prefixed ones were already handled by accident: globby defaults to
+// `dot: false` and the watcher ignores /[\/\\]\./ — so .DS_Store and ._*
+// never got through. The Windows ones are NOT dotfiles, and measurably did:
+// Thumbs.db and desktop.ini were both scanned AND watched. That asymmetry is
+// the reason this list is explicit rather than a rule about leading dots.
+//
+// Deliberately conservative: OS and file-manager artifacts only. No *.tmp,
+// no *.bak, no editor backups — anything a person might plausibly have meant
+// to write stays out, because a filter that silently drops content is worse
+// than the litter it prevents.
+const JUNK_NAMES = new Set([
+    '.DS_Store',                            // macOS Finder, every folder it opens
+    '.localized',                           // macOS localised folder marker
+    '.VolumeIcon.icns',
+    '.com.apple.timemachine.donotpresent',
+    'Icon\r',                               // macOS custom folder icon (trailing CR)
+    'Thumbs.db',                            // Windows Explorer thumbnail cache
+    'ehthumbs.db',
+    'ehthumbs_vista.db',
+    'desktop.ini',                          // Windows folder customisation
+])
+
+const JUNK_DIRS = new Set([
+    '.Spotlight-V100', '.Trashes', '.fseventsd', '.TemporaryItems',
+    '.DocumentRevisions-V100', '.AppleDouble', '.AppleDB', '.AppleDesktop',
+    '$RECYCLE.BIN', 'System Volume Information',
+])
+
+const JUNK_PATTERNS = [
+    /^\._/,              // macOS AppleDouble resource fork
+    /^~\$/,              // Microsoft Office lock/owner file (~$report.docx)
+    /^\.~lock\..*#$/,    // LibreOffice lock file
+]
+
+// Is this path OS/file-manager litter? Matches on the basename, and on any
+// directory segment for the folder-shaped ones — litter inside .Trashes is
+// still litter whatever it is called.
+export function isJunkPath(filePath) {
+    if (typeof filePath !== 'string' || !filePath) return false
+    const segments = filePath.split(/[/\\]/)
+    const name = segments[segments.length - 1]
+    if (!name) return false
+    if (JUNK_NAMES.has(name)) return true
+    if (JUNK_PATTERNS.some(re => re.test(name))) return true
+    return segments.slice(0, -1).some(segment => JUNK_DIRS.has(segment))
+}
+
+// The same list as globby ignore patterns, for the scan side.
+export const JUNK_IGNORE = [
+    ...[...JUNK_NAMES].map(name => `**/${name}`),
+    ...[...JUNK_DIRS].map(dir => `**/${dir}/**`),
+    '**/._*',
+    '**/~$*',
+    '**/.~lock.*#',
+]
+
+// Plugins contribute their own artifacts.
+//
+// The built-in list is OS and file-manager litter, and it stays that way —
+// the engine has no business knowing what a particular library's sidecar file
+// is called. What it can provide is the mechanism: a plugin that writes
+// metadata next to content says so, and both the scan and the watcher honour
+// it. (mikser-io-webdav registers `*.nephelemeta` for exactly this reason:
+// the collection-level file is dot-prefixed and was already invisible, while
+// the per-file one — `page.md.nephelemeta` — is not, and was measurably
+// becoming an entity.)
+const registered = { ignore: [], match: [] }
+
+export function registerJunk({ ignore = [], match } = {}) {
+    registered.ignore.push(...(Array.isArray(ignore) ? ignore : [ignore]))
+    for (const m of (Array.isArray(match) ? match : match ? [match] : [])) {
+        if (m instanceof RegExp) registered.match.push((name) => m.test(name))
+        else if (typeof m === 'function') registered.match.push(m)
+        else throw new Error('registerJunk: `match` must be a RegExp or a function')
+    }
+}
+
+// `junk: false` in config turns the filter off entirely; an array replaces
+// the built-in list. Plugin registrations survive an array override — an
+// operator narrowing the OS list did not ask to start importing a library's
+// sidecar files.
+export function junkIgnore() {
+    const configured = runtime.config?.junk
+    if (configured === false) return []
+    if (Array.isArray(configured)) return [...configured, ...registered.ignore]
+    return [...JUNK_IGNORE, ...registered.ignore]
+}
+
+export function junkFilter() {
+    const configured = runtime.config?.junk
+    if (configured === false) return () => false
+    if (!registered.match.length) return isJunkPath
+    return (filePath) => {
+        if (isJunkPath(filePath)) return true
+        if (typeof filePath !== 'string') return false
+        const name = filePath.split(/[/\\]/).pop()
+        return registered.match.some(test => test(name))
+    }
+}