mikser-io-drive 0.9.0

package/README.md

@@ -0,0 +1,306 @@
+# mikser-io-drive
+
+> WebDAV over the working folder, authenticated through
+> [`mikser-io-auth`](https://github.com/almero-digital-marketing/mikser-io-auth).
+> Edit content from Finder, Explorer or any DAV client; the build picks the
+> change up.
+
+## What it is
+
+A [Nephele](https://github.com/sciactive/nephele) WebDAV server per endpoint,
+mounted on mikser's Express app, serving directories from the working folder.
+Because those directories are mikser *sources*, a `PUT` is a content change —
+the watcher sees it and the site rebuilds. That is the whole point, and also
+where the sharp edges are (see **Working-folder hazards**).
+
+**Design choices, and why:**
+
+- **One server per endpoint, at `<base>/<name>`.** The same shape as
+  `api`/`mcp`/`forms`. Nephele can multi-mount several adapters under one
+  server with a virtual root, and the URLs come out identical — but that
+  needs `@nephele/adapter-virtual`, keeps a fake directory tree in sync with
+  the mount keys, and puts per-endpoint auth behind a shared root. What is
+  given up is browsing the endpoint list over DAV, which `registerRoute`
+  already answers better.
+
+- **`base` is not optional.** Plugin routes match before mikser's static
+  handler, so an endpoint at `/content` would silently shadow a real
+  `/content/` page in the built site.
+
+- **Capabilities are derived from the endpoint name**, not configured.
+  `webdav:<name>` to mount and read it, `webdav:<name>:write` to write. A
+  group holding the first and not the second gets a read-only mount with no
+  flag involved.
+
+- **Sidecar meta-files are off by default**, and safe if you turn them on.
+  Nephele defaults `properties` and `locks` to `'meta-files'`, which writes
+  sidecars *into the folder being served*. The shape is not what it looks
+  like: a collection's is `.nephelemeta` (dot-prefixed, already invisible to
+  mikser), but a file's is `page.md.nephelemeta` — **not** dot-prefixed, and
+  measurably imported as its own entity. The plugin declares
+  `*.nephelemeta` to the engine via `registerJunk`, so either mode is safe.
+  `'emulate'` stays the default for a plainer reason: a content folder people
+  browse and commit should not fill up with sidecars.
+
+- **Writes are staged and renamed.** The adapter opens the destination with
+  `'w'` and streams into it, which was measured to expose a growing partial
+  file *and* destroy the previous contents on an interrupted upload. Writes go
+  to a sibling `.part` file and `rename(2)` on success. `atomicWrites: false`
+  restores the adapter's behaviour.
+
+- **Basic auth only, so HTTPS.** WebDAV clients speak Basic or Digest, and
+  Digest needs the plaintext password — impossible against bcrypt hashes. The
+  plugin warns when the configured URL is plain `http` and not loopback.
+
+## Use
+
+```js
+import { webdav } from 'mikser-io-drive'
+import { auth }   from 'mikser-io-auth'
+
+const identity = auth({
+    capabilities: {
+        editors:   ['webdav:content', 'webdav:content:write'],
+        reviewers: ['webdav:content'],          // read-only, by grant
+    },
+})
+
+export default async () => ({
+    plugins: [
+        identity,
+        webdav({
+            endpoints: {
+                content: { folder: 'documents' },
+                media:   { folder: 'files/media' },
+                data:    { folder: 'data', readOnly: true },
+            },
+            auth: identity,
+        }),
+    ],
+})
+```
+
+Mount `https://cms.example.com/webdav/content` in your file manager.
+
+With no `capabilities` map at all, an authenticated user is unscoped and every
+endpoint is fully writable — the ADR-0012 default, the same as a static token.
+Capabilities only start refusing things once you have said what they mean.
+
+### Endpoint options
+
+| | |
+| --- | --- |
+| `folder` | required; relative to the working folder, or absolute |
+| `readOnly` | hard cap — nobody writes here, whatever they hold |
+| `auth` / `token` | per-endpoint override of the plugin-level `auth` |
+| `allowRemote` | reachable without a credential (see the engine's rule) |
+| `properties` / `locks` | `'emulate'` (default), `'disallow'`, `'meta-files'` |
+
+`readOnly: true` and "you lack `webdav:<name>:write`" are different
+statements. The first is about the folder — a directory a build step owns, say
+— and the second is about the person.
+
+## Working-folder hazards
+
+These are properties of exposing live sources over a network filesystem, not
+bugs, but they will bite if nobody said them out loud.
+
+- **Expose sources, never the output folder.** DAV locks are advisory and
+  mikser does not honour them, so a locked file the renderer rewrites makes
+  the lock a lie.
+- **File-manager litter is filtered by the engine**, from mikser-io 9.6.0.
+  This was measured, and the earlier claim here was wrong in an instructive
+  way: the macOS files (`.DS_Store`, `._*`) were already invisible, because
+  globby defaults to `dot: false` and the watcher ignores leading dots. The
+  **Windows** ones are not dotfiles — `Thumbs.db` and `desktop.ini` were both
+  scanned *and* watched, and became entities. Core now filters a conservative
+  OS/file-manager list on both paths; `junk: false` in config turns it off.
+- **Upload size is bounded by the request timeout.** Node caps a request at 5
+  minutes, which for uploads is a size limit expressed in seconds. Raise it
+  with `server.requestTimeout` in `mikser.config.js` (mikser-io 9.5.0+).
+
+## Client compliance, measured
+
+Tested against [`webdav`](https://github.com/perry-mitchell/webdav-client), a
+third-party client that builds its own PROPFIND bodies and parses its own
+multistatus responses — so it disagrees where the implementation is wrong
+rather than where the tests are.
+
+Three protocol facts worth knowing, all asserted in `test/protocol.test.js`:
+
+| | |
+| --- | --- |
+| default (`emulate`) | `DAV: 1, 3, 2` — **class 2**, which macOS requires for a read-write mount |
+| `locks: 'disallow'` | drops class 2 and `LOCK` from `Allow`. **Finder will refuse a read-write mount.** A trap, because it is invisible until someone tries |
+| `emulate` vs `meta-files` | both return a valid `Lock-Token` header; `emulate` returns an empty `<lockdiscovery/>` where `meta-files` returns the full `<activelock>` |
+
+The last is the real cost of the default: clients read the header, so this is
+survivable, but a client that parses the body for the token finds nothing.
+Choose `meta-files` if you need real dead properties or real locking — with
+persisted locks a second `LOCK` on a held resource correctly answers `423`.
+
+One more, because it surprises people: **`LOCK` on a path that does not exist
+creates an empty file** (RFC 4918 §9.10.4). A client that locks before writing
+— Finder's Save As does — leaves an empty document behind even if the write
+never arrives.
+
+## litmus compliance
+
+Scored with [litmus](https://github.com/tolsen/litmus) 0.13, the WebDAV
+compliance suite from the neon project. Two endpoints, because the shipped
+default deliberately does not store what it is asked to store:
+
+| suite | `emulate` (default) | `meta-files` |
+| --- | --- | --- |
+| basic | **16/16** | **16/16** |
+| copymove | 11/13 | 11/13 |
+| props | 20/30 | **27/30** |
+| locks | 9/13 | **37/41** |
+| http | **4/4** | **4/4** |
+
+The `emulate` column is the trade working as intended: it reports success for
+dead properties and locks without storing them, so litmus reads them back and
+finds nothing. Choose `meta-files` if compliance matters more than a clean
+content folder.
+
+The `meta-files` column is the fair measure of the dependency, and it has four
+real gaps — all upstream in nephele, all pinned in `test/protocol.test.js` so
+an upgrade that fixes them fails loudly rather than changing behaviour quietly:
+
+- **`COPY`/`MOVE` with `Overwrite: F` returns `207`, not `412`** (RFC 4918
+  §9.8.5). The safe half holds — the destination is *not* clobbered — but the
+  client is told the operation succeeded. Measured with a real client:
+  `copyFile(src, dst, { overwrite: false })` **resolves**, and the destination
+  is unchanged. Scripts that copy-if-absent and then read the destination
+  expecting the source's content will be wrong.
+- **A malformed PROPFIND body answers `500`, not `400`.**
+- **`propget` loses a dead property in a foreign namespace.**
+- **`UNLOCK` accepts a bogus lock token**, so one client can release another's
+  lock. DAV locks are advisory here anyway — mikser's renderer does not honour
+  them — but it means locking is not a concurrency control you can lean on.
+
+Two warnings litmus raises that are worth knowing rather than fixing: `DELETE`
+with a fragment in the Request-URI removes the collection, and `COPY` into a
+non-existent collection answers `404` where `409` is specified.
+
+## Why writes are staged
+
+Measured, not assumed. `@nephele/adapter-file-system` writes like this:
+
+```js
+const handle = await fsp.open(this.absolutePath, 'w')   // truncates NOW
+input.pipe(handle.createWriteStream())
+```
+
+Against a 512KB upload delivered in eight slow chunks:
+
+| | adapter as-is | staged |
+| --- | --- | --- |
+| sizes seen at the destination mid-upload | `65536, 131072, … 524288` | never exists |
+| a 1600-byte file whose overwrite is interrupted | **196608 bytes of the new content** | 1600 bytes, unchanged |
+
+The first matters because these folders are mikser sources — the watcher can
+import a half-written file and render a truncated page. The second is data
+loss: not the old file, not an error, a corrupted file and no indication.
+
+Staging to a sibling `.part` file and renaming fixes both, because `rename(2)`
+within a directory is atomic — the file appears complete or not at all, and a
+failed upload never opens the original. A sibling rather than the OS temp
+directory, because rename is only atomic within one filesystem and `/tmp` is
+usually a different mount.
+
+Both rows above are asserted in `test/atomic-writes.test.js`.
+
+## Why Nephele, and not the alternative
+
+The Node WebDAV server field is two live projects. Both were scored with the
+same litmus suites, each on a fresh server:
+
+| suite | Nephele `1.0.0-alpha.67` | webdav-server `2.6.3` |
+| --- | --- | --- |
+| basic | **16/16** | 15/16 |
+| copymove | 11/13 | **12/13** |
+| props | **27/30** | 7/30 |
+| locks | **37/41** | 11/24 *(aborted)* |
+| http | 4/4 | 4/4 |
+
+`webdav-server` has more stars (282 vs 108), is Express-mountable, and has a
+path-based privilege manager that would map neatly onto per-folder access. It
+also woke up on 2026-08-04 after six and a half years of silence — dropping
+v1, adding unit tests — so it is reviving rather than dead. And it gets the
+`Overwrite: F` case right, which is Nephele's most client-visible gap.
+
+But 7/30 on properties and a `locks` run that aborts partway is a different
+class of problem from Nephele's four known gaps, and it carries 65 open issues
+against Nephele's zero. Nephele is also Apache-2.0 and load-bearing for its
+author's own product, which is the maintenance signal that matters most.
+
+Staying on Nephele. If its gaps ever become the binding constraint, the
+serious alternative is not another npm package — it is **Apache `mod_dav`**,
+the implementation litmus was written to test, which reads `htpasswd` and
+`htgroup` natively with `AuthUserFile` / `AuthGroupFile` / `Require group`.
+That would cost the Express integration, the capability model, per-request
+read-only, atomic staged writes and the route inventory — a separate process
+serving the same folder, with its own idea of who may do what. Worth it only
+if strict compliance outranks all of that.
+
+## Nephele is pre-1.0
+
+`nephele@1.0.0-alpha.67`. It implements RFC 4918 fully, but the version is
+what it says, so the dependency is pinned exactly. This is precisely the
+cadence argument in mikser's ADR-0006 for shipping as a plugin rather than in
+the engine.
+
+One thing worth knowing if you extend this: Nephele's conditional-plugins hook
+**cannot see the authenticated user.** `createServer` mounts `loadPlugins`
+before `authenticate`, so `response.locals.user` is always `undefined` there —
+including in the README example that tests it. Per-user decisions have to
+happen in the authenticator, which is where the write gate lives.
+
+## File operations for an agent
+
+Four tools carry bytes over the MCP connection itself, for a caller with no
+route to the host — a sandbox with no egress, a desktop client with no shell.
+
+```
+mikser_drive_add({ endpoint, files: [{ name, base64, mime }], folder?, overwrite?, dryRun? })
+mikser_drive_read({ path })
+mikser_drive_move({ from, to, rewriteRefs?, dryRun? })
+mikser_drive_delete({ path, force?, dryRun? })
+```
+
+Nothing here is media-specific. An endpoint is whatever the deployment
+configured, and what a stored file becomes is whatever that deployment's
+pipeline makes of it — the response reports what was actually stamped rather
+than assuming.
+
+**`add`** takes a whole batch in one call so a single build cycle picks it up:
+one `cycleId`, not one rebuild per file. Each file comes back with the
+`reference` to paste into a document — the served URL where the pipeline
+stamped one, the catalog id where it did not — and the derived variants any
+preset produced. It decodes and checks the whole batch before writing
+anything, so a bad file means nothing landed rather than half of it.
+
+**`read`** returns an image as an image you can look at, text as text, and
+anything else described. It reads the SOURCE; `mikser_read_output` reads what
+was built.
+
+**`move`** and **`delete`** refuse while anything still references the file,
+listing every (entity, field) that would break. `move` with `rewriteRefs: true`
+repoints them — reference strings here are plain rooted paths, so it rewrites
+the literal string and names every file it changed. `delete` moves to a trash
+folder under the runtime directory rather than unlinking, so a wrong delete is
+a move back.
+
+Both see values in entity meta, including inside arrays — not body text, and
+not links a layout builds at render time, which they say so an empty list is
+not read as "nothing at all".
+
+Bytes cost roughly 1.4 tokens each: ten typical images is cheap, a video is
+not. Per file 2MB, per batch 8MB; above that they refuse and point at a WebDAV
+mount, where the same folders are reachable with ordinary credentials and the
+bytes cost nothing.
+
+Page text stays on `mikser_update_entity`. These never write documents — a raw
+write there would lose the checksum guard, the blast-radius preview, the build
+report and the spec-locked advisory.

package/index.js

@@ -0,0 +1,219 @@
+import path from 'node:path'
+
+import { registerRoute, resolveAuth, reachabilityOf, registerJunk } from 'mikser-io'
+import { MikserAuthenticator } from './lib/authenticator.js'
+import { registerFileTools } from './lib/files.js'
+import { withStagedWrites, stageWrites } from './lib/staged-writes.js'
+
+export { MikserAuthenticator, withStagedWrites, stageWrites }
+
+// Nephele's own sidecar files, declared to the engine so neither the scan nor
+// the watcher imports them (mikser-io 9.7.0+).
+//
+// Measured, because the shape is not what it looks like. A collection's meta
+// file is `<dir>/.nephelemeta` — dot-prefixed, so it was already invisible
+// for the same accidental reason .DS_Store was. A file's is
+// `<dir>/page.md.nephelemeta`, which is NOT dot-prefixed and was both scanned
+// and watched: setting one dead property on one document produced a second
+// entity for the sidecar.
+//
+// Registered unconditionally rather than only when `meta-files` is selected,
+// so an operator who switches later is covered by the switch itself.
+registerJunk({ ignore: ['**/*.nephelemeta'], match: /\.nephelemeta$/ })
+
+// Capability names are derived from the endpoint name, not configured:
+//
+//   drive:<name>          may mount and read it
+//   drive:<name>:write    may also write to it
+//
+// so an endpoint declares nothing and the grant reads for itself:
+//
+//   capabilities: { editors: ['drive:content', 'drive:content:write'] }
+//
+// A group that holds the read capability and not the write one gets a
+// read-only mount, which is the common case and needs no flag.
+export const readCapability  = (name) => `drive:${name}`
+export const writeCapability = (name) => `drive:${name}:write`
+
+/**
+ * WebDAV endpoints over working-folder directories (ADR-0012 for auth).
+ *
+ *     drive({
+ *         endpoints: {
+ *             content: { folder: 'documents' },
+ *             media:   { folder: 'files/media' },
+ *             data:    { folder: 'data', readOnly: true },
+ *         },
+ *         auth: identity,
+ *     })
+ *
+ * One Nephele server per endpoint, mounted at `<base>/<name>` — the same
+ * shape as api/mcp/forms. Deliberately not Nephele's multi-mount with a
+ * virtual root: identical URLs, but no virtual-adapter dependency, no
+ * name-sync between a fake directory tree and the mount keys, and per-
+ * endpoint auth stays plain instead of hanging off a shared root. What is
+ * given up is browsing the endpoint list over DAV, which registerRoute
+ * already answers better.
+ *
+ * `base` is NOT optional to drop: plugin routes match before the static
+ * handler (server.js), so an endpoint at `/content` would silently shadow a
+ * real page at /content/ in the built site.
+ */
+export function drive(options = {}) {
+    const {
+        base      = '/drive',
+        endpoints = {},
+        auth,
+        realm     = 'mikser',
+        // Nephele defaults both to 'meta-files', which writes sidecars INTO
+        // the folder being served. The sidecars are filtered out of the
+        // catalog now (see registerJunk above), so the remaining reason to
+        // default to 'emulate' is a plain one: a content folder that people
+        // browse and commit should not fill up with page.md.nephelemeta
+        // files.
+        //
+        // The cost is measurable and small: 'emulate' returns a valid
+        // Lock-Token header but an EMPTY <lockdiscovery/> body, where
+        // 'meta-files' returns the full <activelock>. Clients read the
+        // header; one that parses the body for the token would not find it.
+        // Choose 'meta-files' if you need real dead properties or real
+        // locks, and accept the sidecars.
+        //
+        // Do NOT choose 'disallow' if macOS clients matter: it drops DAV
+        // compliance class 2 from the OPTIONS response, and Finder refuses a
+        // read-write mount without it.
+        properties = 'emulate',
+        locks      = 'emulate',
+    } = options
+
+    return ({ runtime, onLoaded, useLogger }) => {
+        const names = Object.keys(endpoints)
+        if (!names.length) return   // nothing configured → nothing mounted
+
+        onLoaded(async () => {
+            const logger = useLogger()
+            const app = runtime.options.app
+            if (!app) {
+                throw new Error(
+                    'drive plugin requires runtime.options.app — run mikser with --server, ' +
+                    'or pass { app: yourExpressInstance } to setup() before loading the plugin'
+                )
+            }
+
+            const { default: nepheleServer } = await import('nephele')
+            const { default: FileSystemAdapter } = await import('@nephele/adapter-file-system')
+            const { default: ReadOnlyPlugin } = await import('@nephele/plugin-read-only')
+
+            const workingFolder = runtime.options.workingFolder
+            const resolve = (folder) =>
+                path.isAbsolute(folder) ? folder : path.join(workingFolder, folder)
+
+            // Basic auth sends the password in a header, base64 and nothing
+            // more. Warn rather than refuse — a deployment behind a
+            // TLS-terminating proxy looks like plain http from here, and
+            // refusing to boot over a guess is the wrong trade.
+            if (auth && runtime.options.url?.startsWith('http://') &&
+                !/^http:\/\/(localhost|127\.|\[::1\])/.test(runtime.options.url)) {
+                logger.warn(
+                    'drive: %s is plain http and WebDAV clients authenticate with Basic — ' +
+                    'credentials travel base64-encoded, not encrypted. Serve over https, or ' +
+                    'terminate TLS in front of mikser.', runtime.options.url)
+            }
+
+            for (const [name, ep] of Object.entries(endpoints)) {
+                if (!ep.folder) {
+                    throw new Error(`drive: endpoint ${JSON.stringify(name)} declares no folder`)
+                }
+                const root = resolve(ep.folder)
+                const mountPath = `${base}/${name}`
+
+                // Same seam and the same one difference as api/mcp/forms: a
+                // plain token keeps the trusted-local-host model, a real
+                // verifier does not.
+                const verifier      = resolveAuth(ep.auth ?? auth ?? ep.token)
+                const trustLoopback = !(ep.auth ?? auth) && !!ep.token
+
+                const readOnly = ep.readOnly === true
+
+                const authenticator = new MikserAuthenticator({
+                    verifier,
+                    trustLoopback,
+                    allowRemote: ep.allowRemote,
+                    capability:  readCapability(name),
+                    // A readOnly endpoint needs no per-user write check —
+                    // ReadOnlyPlugin refuses every mutation regardless.
+                    writeCapability: readOnly ? null : writeCapability(name),
+                    realm,
+                    logger,
+                })
+
+                const fsAdapter = new FileSystemAdapter({
+                    root,
+                    properties: ep.properties ?? properties,
+                    locks:      ep.locks      ?? locks,
+                })
+
+                app.use(mountPath, nepheleServer({
+                    // Writes are staged to a sibling temp file and renamed.
+                    // The adapter writes straight to the destination with
+                    // open(path,'w'), which truncates immediately — so the
+                    // watcher can import a half-written file, and an
+                    // interrupted overwrite leaves the ORIGINAL destroyed.
+                    // Both measured; see lib/staged-writes.js.
+                    adapter: (ep.atomicWrites === false)
+                        ? fsAdapter
+                        : withStagedWrites(fsAdapter, {
+                            onFailure: (err, file) => logger.warn(
+                                'drive: upload of %s failed, original left intact — %s',
+                                path.basename(file), err.message),
+                        }),
+                    authenticator,
+                    // `readOnly: true` is a hard cap — "nobody writes here",
+                    // which is a different statement from "you may not write
+                    // here". The per-user version of that question is answered
+                    // in the authenticator, because Nephele resolves plugins
+                    // BEFORE it authenticates and the hook cannot see the user.
+                    plugins: readOnly ? [new ReadOnlyPlugin()] : [],
+                }))
+
+                registerRoute({
+                    path:         mountPath,
+                    plugin:       'drive',
+                    reachability: reachabilityOf({ auth: verifier, allowRemote: ep.allowRemote }),
+                    // WebDAV GET/PUT stream file bodies, so a facade must not
+                    // buffer this route.
+                    streaming:    true,
+                    label:        'WebDAV',
+                    detail:       `(${ep.folder}${readOnly ? ', read-only' : ''})`,
+                    authLabel:    verifier ? (verifier.name ?? 'auth')
+                                           : (ep.allowRemote ? 'public, REMOTE OPEN' : 'loopback-only'),
+                })
+            }
+
+            logger.info('WebDAV mounted at %s (%s)', base, names.join(', '))
+
+            // File operations over MCP, for an agent with no route to the
+            // host — a sandbox with no egress, a desktop client with no shell.
+            // Bytes ride the MCP connection that already works.
+            registerFileTools({
+                runtime, endpoints, logger,
+                capabilityOf: readCapability,
+                writeCapabilityOf: writeCapability,
+            })
+
+            // Uploads are bounded by the server request timeout. The engine
+            // raises it automatically because this registers streaming routes
+            // (see registerRoute above) — Node's 5-minute default is an upload
+            // size limit expressed in seconds, and a large file over a slow
+            // link is indistinguishable from a stalled request.
+            const configured = runtime.config?.server?.requestTimeout
+            logger.debug('drive: uploads bounded by the server request timeout — %s',
+                configured == null
+                    ? 'raised automatically for these streaming routes; override with config.server.requestTimeout'
+                    : configured === 0 ? 'disabled by config.server.requestTimeout'
+                    : `${configured}ms from config.server.requestTimeout`)
+        })
+    }
+}
+
+export default drive

package/lib/authenticator.js

@@ -0,0 +1,116 @@
+import { UnauthorizedError, ForbiddenError } from 'nephele'
+import { authorize } from 'mikser-io'
+
+// Bridges Nephele's Authenticator contract onto the engine's verifier seam
+// (ADR-0012), so WebDAV authenticates against the same htpasswd identity as
+// every other surface — one users file, one groups file, one set of
+// capabilities.
+//
+// Nephele's interface is two methods:
+//
+//   authenticate(request, response) → User   (throw to refuse)
+//   cleanAuthentication(request, response)
+//
+// Deliberately NOT @nephele/authenticator-htpasswd, which would re-read the
+// file itself: that loses the mtime reload, the timing-equalised unknown-user
+// path, and — the real reason — any knowledge of groups, so capabilities
+// could not gate anything.
+//
+// Deliberately NOT @nephele/authenticator-custom either. Its getUser/authBasic
+// pair is Basic-only by construction, while a verifier already understands
+// every credential the deployment accepts, Bearer included (rclone and curl
+// can send one; Finder cannot). Going through the seam means WebDAV gains
+// whatever the seam gains.
+// The WebDAV methods that change something. COPY and MOVE mutate the
+// destination (MOVE the source too), and LOCK exists in order to write.
+export const WRITE_METHODS = new Set([
+    'PUT', 'POST', 'DELETE', 'MKCOL', 'COPY', 'MOVE', 'PROPPATCH', 'LOCK', 'UNLOCK',
+])
+
+export class MikserAuthenticator {
+    #verifier
+    #trustLoopback
+    #allowRemote
+    #capability
+    #writeCapability
+    #realm
+    #logger
+
+    constructor({
+        verifier, trustLoopback = false, allowRemote = false,
+        capability, writeCapability, realm = 'mikser', logger,
+    } = {}) {
+        this.#verifier        = verifier
+        this.#trustLoopback   = trustLoopback
+        this.#allowRemote     = allowRemote
+        this.#capability      = capability
+        this.#writeCapability = writeCapability
+        this.#realm           = realm
+        this.#logger          = logger
+    }
+
+    async authenticate(request, response) {
+        let outcome
+        try {
+            outcome = await authorize(request, this.#verifier, {
+                allowRemote:   this.#allowRemote,
+                trustLoopback: this.#trustLoopback,
+            })
+        } catch (err) {
+            this.#logger?.error?.('drive: verifier threw — %s', err.message)
+            throw new UnauthorizedError('Authentication failed.')
+        }
+
+        if (!outcome.ok) {
+            // Nephele turns UnauthorizedError into a bare 401. A DAV client
+            // will not prompt for credentials without being told how, so the
+            // challenge has to be set here — and it must offer Basic, because
+            // that is the only scheme Finder and Explorer speak.
+            if (outcome.status === 401) {
+                response.set('WWW-Authenticate', `Basic realm="${this.#realm}", charset="UTF-8"`)
+                throw new UnauthorizedError(outcome.error)
+            }
+            // 403: the credential was never the problem — the caller's origin
+            // was. Challenging would invite a retry that cannot help.
+            throw new ForbiddenError(outcome.error)
+        }
+
+        const principal = outcome.principal
+
+        // Capability gate for this endpoint. `capabilities: null` means the
+        // credential is not capability-scoped (no map configured, or a bare
+        // static token), which passes — same rule as every other surface.
+        if (this.#capability && principal.capabilities != null &&
+            !principal.capabilities.includes(this.#capability)) {
+            this.#logger?.debug?.('drive: %j lacks %j', principal.subject, this.#capability)
+            throw new ForbiddenError(`Your credential does not carry '${this.#capability}'.`)
+        }
+
+        // Write gating happens HERE rather than through Nephele's conditional-
+        // plugins hook, because that hook cannot see the user: createServer
+        // mounts loadPlugins before authenticate, so response.locals.user is
+        // always undefined when the plugins function runs. (Nephele's own
+        // README example tests `response.locals.user == null` there, which
+        // therefore never means what it looks like it means.) The authenticator
+        // is the earliest place that holds both the principal and the method.
+        if (this.#writeCapability && WRITE_METHODS.has(request.method) &&
+            principal.capabilities != null &&
+            !principal.capabilities.includes(this.#writeCapability)) {
+            this.#logger?.debug?.('drive: %j may not %s — lacks %j',
+                principal.subject, request.method, this.#writeCapability)
+            throw new ForbiddenError(`Your credential does not carry '${this.#writeCapability}'.`)
+        }
+
+        // Nephele only requires `username`. The principal rides along for
+        // anything downstream that wants it.
+        return { username: principal.subject ?? 'anonymous', principal }
+    }
+
+    async cleanAuthentication() {
+        // Nothing to tear down: every request re-verifies, and there is no
+        // session to invalidate. A revoked htgroup line takes effect on the
+        // next request rather than needing anything torn down here.
+    }
+}
+
+export default MikserAuthenticator