mikser-io-drive 11.1.0 → 11.3.0

package/.github/workflows/publish.yml

@@ -23,6 +23,15 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    # A hung test must not cost six hours.
+    #
+    # Without this the job runs to GitHub's own limit, reporting nothing:
+    # a flaky teardown in one suite sat on `npm test` for seventeen
+    # minutes before anyone looked, and would have sat there all day.
+    # The longest suite in the family is a couple of minutes including
+    # install, so fifteen is generous and still fails while someone is
+    # still watching.
+    timeout-minutes: 15
     permissions:
       contents: read
       # The whole mechanism. Without it npm has nothing to verify.

package/README.md

@@ -149,6 +149,78 @@ 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.
 
+## A domain of its own, and what Windows needs
+
+Explorer cannot map a share that lives at `<base>/<name>` on a site whose `/` is
+a static site. The Microsoft WebDAV redirector establishes its session against
+the **server root** before it touches the path: it asks `/`, gets the site's
+answer, and stops — the mount being correct makes no difference. Measured on a
+live host, `OPTIONS /drive/SkinCheck/` answered `DAV: 1, 3, 2` while
+`dir \\host@SSL\DavWWWRoot\drive\SkinCheck\` still failed, and it failed at
+the root.
+
+Give the drive a domain and `/` is the drive:
+
+```js
+drive({
+    host: 'drive.example.com',
+    auth: identity,
+    endpoints: {
+        SkinCheck: { folder: 'skincheck' },
+        Reports:   { folder: 'reports' },
+    },
+})
+```
+
+`\\drive.example.com@SSL\` now mounts, and `/` is a collection whose children
+are the endpoints **that caller may read** — filtered by the same
+`drive:<name>` capability that guards the endpoint itself, so two people
+mapping the same drive see different folders in it. Entering one lands on that
+endpoint's own server with its own authenticator; the root is a listing, not a
+proxy.
+
+`OPTIONS /` is answered without credentials, because that is what the
+redirector asks before it has any to offer — it discloses that a DAV server is
+here and nothing about what is in it. The listing is the gated part.
+
+Scoped to the Host header, and that is not optional: mounted at `/` for every
+host, a drive would shadow every page on the site. Requests for any other host
+fall straight through.
+
+The `<base>/<name>` surface is unchanged and still answers on every host. This
+adds a way in; it does not move the old one.
+
+## What the folder is called
+
+The endpoint key is the name, and the mount reports it as `displayname`:
+
+```js
+drive({
+    endpoints: {
+        SkinCheck:  { folder: 'skincheck' },              // shows as "SkinCheck"
+        reports:    { folder: 'data', displayName: 'Q3 reports' },
+    },
+})
+```
+
+Without it the label is whatever the client derives from the URL, and that is
+not controllable: Express matches routes case-insensitively, so
+`/drive/SkinCheck` and `/drive/skincheck` reach the same mount and the casing
+shown is whichever the client asked for first — an endpoint renamed to
+`SkinCheck` kept reading `skincheck` in Explorer, and remapping did not change
+it. `@nephele/adapter-file-system` does not implement `displayname` (it is
+commented out of its live-property list with a TODO), so a PROPFIND for it
+answered `404 The displayname property was not found` and the client had nothing
+to go on.
+
+The default is the **key**, not `summary`: `displayname` is a name — RFC 4918
+§15.2, "suitable for presentation to a user" — and the key is already the URL
+segment and what the mount log prints. `summary` is a sentence and reads badly
+as a folder label. `displayName` overrides the key where it is not presentable.
+
+Only the mount root is named. Everything below it is a real file or directory
+whose name the client reads from the path.
+
 ## When a client refuses and the server is right
 
 WebDAV clients cache their **discovery** verdict — not the file listing, the

package/index.js

@@ -4,6 +4,8 @@ import { registerRoute, resolveAuth, reachabilityOf, registerJunk, registerCapab
 import { MikserAuthenticator } from './lib/authenticator.js'
 import { registerFileTools } from './lib/files.js'
 import { withStagedWrites, stageWrites } from './lib/staged-writes.js'
+import { withDisplayName } from './lib/display-name.js'
+import { rootListing } from './lib/root-listing.js'
 
 export { MikserAuthenticator, withStagedWrites, stageWrites }
 
@@ -43,6 +45,9 @@ export const writeCapability = (name) => `drive:${name}:write`
  *             content: { folder: 'documents' },
  *             media:   { folder: 'files/media' },
  *             data:    { folder: 'data', readOnly: true },
+ *             Reports: { folder: 'reports' },            // shows as "Reports"
+ *             q3:      { folder: 'q3', displayName: 'Q3 reports' },
+ *             share:   { folder: 'share', host: 'drive.example.com' },
  *         },
  *         auth: identity,
  *     })
@@ -63,6 +68,19 @@ export function drive(options = {}) {
     const {
         base      = '/drive',
         endpoints = {},
+        // A domain of its own. On it, `/` is the drive: a collection listing
+        // the endpoints the caller may read, with each endpoint mounted
+        // beneath it at `/<name>`.
+        //
+        // The Microsoft WebDAV redirector establishes its session against the
+        // SERVER ROOT before it touches the path, so a share at
+        // `<base>/<name>` on a site whose `/` is a static site is one Explorer
+        // may never reach. Given a host, `\\drive.example.com@SSL\` is the
+        // mount and the public site is untouched.
+        //
+        // The `<base>/<name>` surface is unchanged and still answers on every
+        // host — this adds a way in, it does not move the old one.
+        host,
         auth,
         realm     = 'mikser',
         // Nephele defaults both to 'meta-files', which writes sidecars INTO
@@ -120,6 +138,9 @@ export function drive(options = {}) {
                     'terminate TLS in front of mikser.', runtime.options.url)
             }
 
+            // What the drive's own root will list, if it has a host.
+            const rootEntries = []
+
             for (const [name, ep] of Object.entries(endpoints)) {
                 if (!ep.folder) {
                     throw new Error(`drive: endpoint ${JSON.stringify(name)} declares no folder`)
@@ -206,20 +227,40 @@ export function drive(options = {}) {
                 // property is found and bound on either path.
                 fsAdapter.getOptionsResponseCacheControl = async () => 'no-cache'
 
-                app.use(mountPath, nepheleServer({
+                const mountServer = 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),
-                        }),
+                    // The mount answers to its own name.
+                    //
+                    // `displayname` is what a client labels the folder with,
+                    // and the adapter does not implement it — so the label was
+                    // whatever each client derived from the URL, which is not
+                    // controllable: Express matches routes case-insensitively,
+                    // so an endpoint renamed to `SkinCheck` went on reading
+                    // `skincheck` in Explorer, from a casing the client had
+                    // cached.
+                    //
+                    // Defaults to the endpoint KEY rather than `summary`.
+                    // displayname is a NAME — RFC 4918 §15.2, "suitable for
+                    // presentation to a user" — and the key is already the URL
+                    // segment and the mount log label, so nothing new has to
+                    // be written down. `summary` is a sentence, which reads
+                    // badly as a folder label. `displayName` overrides it for
+                    // a key that is not presentable.
+                    adapter: withDisplayName(
+                        (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),
+                            }),
+                        ep.displayName ?? name,
+                    ),
                     authenticator,
                     // `readOnly: true` is a hard cap — "nobody writes here",
                     // which is a different statement from "you may not write
@@ -227,7 +268,24 @@ export function drive(options = {}) {
                     // in the authenticator, because Nephele resolves plugins
                     // BEFORE it authenticates and the hook cannot see the user.
                     plugins: readOnly ? [new ReadOnlyPlugin()] : [],
-                }))
+                })
+
+                app.use(mountPath, mountServer)
+
+                // The same server, reached from the drive's own domain.
+                // Scoped to the Host header, and that is not optional: mounted
+                // at `/<name>` for every host, it would shadow a real page.
+                if (host) {
+                    app.use(`/${name}`, (req, res, next) =>
+                        (req.hostname === host ? mountServer(req, res, next) : next()))
+                    // Named for the client with the same rule the mount uses,
+                    // so the listing and the folder agree.
+                    rootEntries.push({
+                        name,
+                        displayName: ep.displayName ?? name,
+                        capability:  readCapability(name),
+                    })
+                }
 
                 registerRoute({
                     path:         mountPath,
@@ -295,6 +353,37 @@ export function drive(options = {}) {
                 })
             }
 
+            // The drive's own root, last: it answers only for `/`, and only
+            // on its host, so it has to sit behind the endpoint mounts rather
+            // than in front of them.
+            if (host) {
+                app.use((req, res, next) =>
+                    (req.hostname === host
+                        ? rootListing({
+                            entries:  rootEntries,
+                            rootName: options.displayName ?? host,
+                            auth: {
+                                verifier:      resolveAuth(auth),
+                                allowRemote:   true,
+                                trustLoopback: !auth,
+                                realm,
+                            },
+                            logger,
+                        })(req, res, next)
+                        : next()))
+
+                registerRoute({
+                    path:         '/',
+                    host,
+                    plugin:       'drive',
+                    reachability: reachabilityOf({ auth: resolveAuth(auth), allowRemote: true }),
+                    methods:      ['OPTIONS', 'PROPFIND'],
+                    cors:         false,
+                    label:        'WebDAV root',
+                    detail:       `(${names.length} endpoint${names.length === 1 ? '' : 's'})`,
+                })
+            }
+
             logger.info('WebDAV mounted at %s (%s)', base, names.join(', '))
 
             // File operations over MCP, for an agent with no route to the

package/lib/display-name.js

@@ -0,0 +1,95 @@
+// The mount's own name, served as `displayname` on its root collection.
+//
+// A WebDAV client shows a folder label. WebDAV has a property for it —
+// RFC 4918 §15.2, "a name for the resource suitable for presentation to a
+// user" — and @nephele/adapter-file-system does not implement it: the name is
+// commented out of its live-property list with a TODO, so a PROPFIND for it
+// answers 404 and the client falls back to guessing from the URL.
+//
+// Guessing from the URL is not controllable. Express matches routes
+// case-insensitively, so `/drive/SkinCheck`, `/drive/skincheck` and
+// `/drive/SKINCHECK` all reach the same mount, and the casing a client ends up
+// displaying is whichever one it happened to ask for first. An endpoint
+// renamed to `SkinCheck` went on reading `skincheck` in Explorer.
+//
+// The name is already written down — it is the ENDPOINTS key, the URL segment
+// and the mount log label — so the site can just answer the question instead.
+//
+// Applied to the root collection only. Every other resource is a real file or
+// directory whose name the client reads from the path, and which the author
+// did not choose in mikser's config.
+
+// The root of a mount. `Resource.path` is relative to the adapter root with a
+// trailing separator stripped, so the mount's own collection is the empty one.
+const isMountRoot = (resource) => resource?.path === ''
+
+// A Properties facade that answers one more question than the one it wraps.
+//
+// PROPFIND reaches properties through the BY-USER variants — listByUser,
+// getAllByUser, getByUser — and the adapter's versions delegate to the plain
+// ones on `this`. A Proxy binds methods to the TARGET, so wrapping only the
+// plain three would leave PROPFIND reading straight past this. Both sets are
+// wrapped, which is why the property actually appears.
+function withDisplayNameProperty(properties, displayName) {
+    const answer = (name, fallback) =>
+        name === 'displayname' ? Promise.resolve(displayName) : fallback()
+    const including = async (listing) => {
+        const names = await listing()
+        return names.includes('displayname') ? names : ['displayname', ...names]
+    }
+
+    return new Proxy(properties, {
+        get(target, prop, receiver) {
+            switch (prop) {
+                case 'get':         return (name) => answer(name, () => target.get(name))
+                case 'getByUser':   return (name, user) => answer(name, () => target.getByUser(name, user))
+                case 'list':        return () => including(() => target.list())
+                case 'listByUser':  return (user) => including(() => target.listByUser(user))
+                case 'listLive':    return () => including(() => target.listLive())
+                case 'listLiveByUser': return (user) => including(() => target.listLiveByUser(user))
+                case 'getAll':      return async () => ({ ...(await target.getAll()), displayname: displayName })
+                case 'getAllByUser': return async (user) => ({ ...(await target.getAllByUser(user)), displayname: displayName })
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}
+
+function withDisplayNameResource(resource, displayName) {
+    return new Proxy(resource, {
+        get(target, prop, receiver) {
+            if (prop === 'getProperties') {
+                return async () => withDisplayNameProperty(await target.getProperties(), displayName)
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}
+
+/**
+ * Decorate an adapter so its root collection reports `displayName`.
+ *
+ * Same shape as withStagedWrites, and composes with it: both wrap the three
+ * methods that hand back a resource, and each passes everything else through.
+ *
+ * @param {object} adapter      a nephele adapter
+ * @param {string} displayName  what a client should call this mount
+ */
+export function withDisplayName(adapter, displayName) {
+    if (!displayName) return adapter
+    const wrap = (method) => async (...args) => {
+        const resource = await adapter[method](...args)
+        return isMountRoot(resource) ? withDisplayNameResource(resource, displayName) : resource
+    }
+    return new Proxy(adapter, {
+        get(target, prop, receiver) {
+            if (prop === 'getResource' || prop === 'newResource' || prop === 'newCollection') {
+                return wrap(prop)
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}

package/lib/root-listing.js

@@ -0,0 +1,120 @@
+// The drive's own root: a collection whose children are the endpoints you may
+// read.
+//
+// Only reachable on a dedicated host (`drive({ host: … })`), and that is the
+// point of it. The Microsoft WebDAV redirector establishes its session against
+// the SERVER ROOT before it touches the path, so a share at `<base>/<name>` on
+// a site whose `/` is a static site is one Explorer may never reach — it asks
+// `/`, gets a static site's answer, and stops. Given a domain of its own, `/`
+// is the drive, and a listing there is what makes several endpoints reachable
+// through one mount.
+//
+// Deliberately NOT Nephele's multi-mount virtual root, for the reasons in this
+// plugin's header: no virtual-adapter dependency, and no fake directory tree
+// whose names have to be kept in step with the mount keys. The children here
+// ARE the mount keys, and entering one lands on that endpoint's own Nephele
+// server with its own authenticator — so per-endpoint auth stays exactly where
+// it was rather than hanging off a shared root.
+
+import { authorize, hasCapability } from 'mikser-io'
+
+const escape = (text) => String(text)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+const collection = (href, displayName) =>
+    `  <D:response>\n`
+    + `    <D:href>${escape(href)}</D:href>\n`
+    + `    <D:propstat>\n`
+    + `      <D:prop>\n`
+    + `        <D:resourcetype><D:collection/></D:resourcetype>\n`
+    + `        <D:displayname>${escape(displayName)}</D:displayname>\n`
+    + `      </D:prop>\n`
+    + `      <D:status>HTTP/1.1 200 OK</D:status>\n`
+    + `    </D:propstat>\n`
+    + `  </D:response>`
+
+/**
+ * Middleware serving OPTIONS and PROPFIND for the host root.
+ *
+ * @param {object} input
+ * @param {Array}  input.entries   [{ name, displayName, capability }]
+ * @param {string} input.rootName  what the root collection calls itself
+ * @param {object} input.auth      { verifier, allowRemote, trustLoopback, realm }
+ * @param {object} input.logger
+ */
+export function rootListing({ entries, rootName, auth, logger }) {
+    return async (req, res, next) => {
+        // Only the root itself. Everything below is a real endpoint mount.
+        if (req.path !== '/') return next()
+
+        if (req.method === 'OPTIONS') {
+            // Answered WITHOUT authentication, on purpose: this is discovery,
+            // and it is what the redirector asks before it has credentials to
+            // offer. It discloses that a WebDAV server is here and nothing
+            // about what is in it — the listing below is the gated part.
+            //
+            // Class 1 only. This collection supports reading its own children
+            // and nothing else; the endpoints inside it advertise their own
+            // classes, including locking.
+            res.set('DAV', '1')
+            res.set('MS-Author-Via', 'DAV')
+            res.set('Allow', 'OPTIONS, PROPFIND')
+            // No caching of a discovery answer — the same rule as the mounts,
+            // and for the same reason: a client that cached a refusal keeps it.
+            res.set('Cache-Control', 'no-cache')
+            return res.status(200).end()
+        }
+
+        if (req.method !== 'PROPFIND') return next()
+
+        let outcome
+        try {
+            outcome = await authorize(req, auth.verifier, {
+                allowRemote:   auth.allowRemote,
+                trustLoopback: auth.trustLoopback,
+            })
+        } catch (err) {
+            logger?.error?.('drive: verifier threw at the root — %s', err.message)
+            return res.status(401)
+                .set('WWW-Authenticate', `Basic realm="${auth.realm}", charset="UTF-8"`)
+                .end()
+        }
+
+        if (!outcome.ok) {
+            // Basic, because it is the only scheme Explorer and Finder speak,
+            // and without the challenge a DAV client never prompts.
+            if (outcome.status === 401) {
+                return res.status(401)
+                    .set('WWW-Authenticate', `Basic realm="${auth.realm}", charset="UTF-8"`)
+                    .end()
+            }
+            return res.status(403).end()
+        }
+
+        // What this user may read. A `capability: null` entry is not
+        // capability-scoped — no map configured, or a bare static token —
+        // which passes, the same rule every other surface applies.
+        const visible = entries.filter(entry =>
+            !entry.capability || hasCapability(outcome.principal, entry.capability))
+
+        // Depth 0 describes the collection itself; anything else lists the
+        // children. Depth: infinity is answered as 1 rather than refused:
+        // there is exactly one level here, so they are the same answer.
+        const depth = String(req.get('depth') ?? 'infinity')
+        const responses = [collection('/', rootName)]
+        if (depth !== '0') {
+            for (const entry of visible) {
+                responses.push(collection(`/${entry.name}/`, entry.displayName))
+            }
+        }
+
+        logger?.debug?.('drive: root listing for %j — %d of %d endpoint(s)',
+            outcome.principal?.subject, visible.length, entries.length)
+
+        res.status(207)
+            .set('Content-Type', 'application/xml; charset=utf-8')
+            .set('DAV', '1')
+            .send(`<?xml version="1.0" encoding="utf-8"?>\n`
+                + `<D:multistatus xmlns:D="DAV:">\n${responses.join('\n')}\n</D:multistatus>\n`)
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-drive",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "WebDAV for mikser-io. Exposes working-folder directories as WebDAV endpoints via Nephele, authenticated through mikser-io-auth's htpasswd identity — so content can be edited from Finder, Explorer or any DAV client and the build picks the change up.",
   "main": "index.js",
   "type": "module",
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-drive#readme",
   "peerDependencies": {
-    "mikser-io": "^11.2.0",
+    "mikser-io": "^11.7.0",
     "zod": "^4.0.0"
   },
   "dependencies": {
@@ -41,7 +41,7 @@
     "bcryptjs": "^3.0.0",
     "express": "^5.2.1",
     "globby": "^15.0.0",
-    "mikser-io": "^11.2.0",
+    "mikser-io": "^11.7.0",
     "mikser-io-auth": "^11.0.1",
     "mikser-io-mcp": "^11.0.1",
     "webdav": "^5.10.0",

package/test/atomic-writes.test.js

@@ -51,6 +51,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/derived.test.js

@@ -156,7 +156,27 @@ before(async (t) => {
 })
 
 after(async () => {
-    server?.kill()
+    // WAIT for it to die, and escalate. `kill()` only sends the signal; the
+    // child's stdout/stderr are pipes we hold, so until it actually exits
+    // those handles keep THIS process alive and the run never ends. Every
+    // test passes and then node sits there — on CI that was fifteen minutes
+    // of nothing, ended by the job timeout and "Terminate orphan process".
+    //
+    // mikser handles SIGTERM itself (instance.js: close(); process.exit(0)),
+    // so the graceful path is the normal one; SIGKILL is the floor for when
+    // close() does not come back.
+    if (server && server.exitCode === null && server.signalCode === null) {
+        const exited = new Promise(resolve => server.once('exit', resolve))
+        server.kill()
+        const inTime = await Promise.race([
+            exited.then(() => true),
+            new Promise(resolve => setTimeout(() => resolve(false), 5000)),
+        ])
+        if (!inTime) {
+            server.kill('SIGKILL')
+            await exited
+        }
+    }
     if (dir) await rm(dir, { recursive: true, force: true })
 })
 

package/test/drive.test.js

@@ -77,6 +77,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/protocol.test.js

@@ -56,6 +56,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })
@@ -263,3 +276,58 @@ describe('known nephele non-compliance, pinned', () => {
         assert.equal(res.status, 500, 'if this becomes 400, nephele fixed it')
     })
 })
+
+describe('the mount answers to its own name', () => {
+    // A client labels the folder from `displayname`, and
+    // @nephele/adapter-file-system does not implement it — the name is
+    // commented out of its live-property list with a TODO — so a PROPFIND for
+    // it answered 404 and the client fell back to guessing from the URL.
+    //
+    // Guessing is not controllable: Express matches routes case-insensitively,
+    // so `/drive/SkinCheck` and `/drive/skincheck` reach the same mount and the
+    // casing shown is whichever the client asked for first. An endpoint renamed
+    // to `SkinCheck` went on reading `skincheck` in Explorer.
+    const propfind = (ep, body) => fetch(`http://127.0.0.1:${port}/drive/${ep}/`, {
+        method: 'PROPFIND',
+        headers: { authorization: AUTH, 'content-type': 'text/xml', depth: '0' },
+        body,
+    })
+    const NAMED = '<propfind xmlns="DAV:"><prop><displayname/></prop></propfind>'
+    const ALLPROP = '<propfind xmlns="DAV:"><allprop/></propfind>'
+
+    it('reports the endpoint key as displayname, asked for by name', async () => {
+        const res = await propfind('emulated', NAMED)
+        const xml = await res.text()
+        assert.equal(res.status, 207, xml)
+        assert.match(xml, /<[^>]*displayname[^>]*>emulated</,
+            `displayname must carry the endpoint key — got:\n${xml}`)
+        assert.doesNotMatch(xml, /displayname property was not found/, xml)
+    })
+
+    it('includes it in allprop, which is how a client usually asks', async () => {
+        // PROPFIND reaches properties through the BY-USER variants, and the
+        // adapter's delegate to the plain ones on `this` — so a decorator that
+        // wrapped only the plain three would be read straight past. This is the
+        // case that catches that.
+        const xml = await (await propfind('emulated', ALLPROP)).text()
+        assert.match(xml, /<[^>]*displayname[^>]*>emulated</, `allprop must include it — got:\n${xml}`)
+    })
+
+    it('names each endpoint separately, since each is its own mount', async () => {
+        const xml = await (await propfind('readonly', NAMED)).text()
+        assert.match(xml, /<[^>]*displayname[^>]*>readonly</, xml)
+    })
+
+    it('leaves the files inside it alone', async () => {
+        // Only the mount ROOT is named in config. Everything below is a real
+        // file whose name the client reads from the path.
+        const res = await fetch(`http://127.0.0.1:${port}/drive/emulated/page.md`, {
+            method: 'PROPFIND',
+            headers: { authorization: AUTH, 'content-type': 'text/xml', depth: '0' },
+            body: NAMED,
+        })
+        const xml = await res.text()
+        assert.doesNotMatch(xml, /<[^>]*displayname[^>]*>emulated</,
+            `a file must not inherit the mount's name — got:\n${xml}`)
+    })
+})

package/test/real-client.test.js

@@ -67,6 +67,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/root-listing.test.js

@@ -0,0 +1,181 @@
+// The drive's own root, on a domain of its own.
+//
+// The Microsoft WebDAV redirector establishes its session against the SERVER
+// ROOT before it touches the path. A share at `<base>/<name>` on a site whose
+// `/` is a static site is therefore one Explorer may never reach: it asks `/`,
+// gets a static site's answer, and stops — the leaf being correct makes no
+// difference. Measured on a live host: OPTIONS on the mount answered
+// `DAV: 1, 3, 2` while `dir \\host@SSL\DavWWWRoot\drive\SkinCheck\` still
+// failed, and it failed at the root.
+//
+// `drive({ host })` gives the drive a domain where `/` is the drive itself: a
+// collection whose children are the endpoints the caller may read. Each child
+// is the real mount, so entering one lands on that endpoint's own Nephele
+// server with its own authenticator — no virtual adapter, and no fake
+// directory tree to keep in step with the mount keys.
+//
+// Host-scoped, and that is not optional: mounted at `/` for every host, a
+// drive shadows every page on the site.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import bcrypt from 'bcryptjs'
+import http from 'node:http'
+
+import { runtime } from 'mikser-io'
+import { auth } from 'mikser-io-auth'
+import { drive } from '../index.js'
+
+const HOST = 'drive.example.test'
+let server, port, dir
+
+const as = (user) => 'Basic ' + Buffer.from(`${user}:${user}-pw`).toString('base64')
+
+// Raw http, not fetch.
+//
+// The Host header IS the test here — it is what decides whether this request
+// is for the drive's domain — and fetch() silently drops it: `Host` is a
+// forbidden header in undici, so every request went out as 127.0.0.1 and the
+// host gate correctly refused all of them. The first version of this file
+// failed for that reason and the code was fine.
+function request(method, urlPath, { host = HOST, headers = {} } = {}) {
+    return new Promise((resolve, reject) => {
+        const req = http.request(
+            { host: '127.0.0.1', port, path: urlPath, method, headers: { Host: host, ...headers } },
+            (res) => {
+                let body = ''
+                res.on('data', (chunk) => { body += chunk })
+                res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body }))
+            })
+        req.on('error', reject)
+        req.end()
+    })
+}
+const propfind = (opts = {}) =>
+    request('PROPFIND', '/', { ...opts, headers: { depth: '1', ...(opts.headers ?? {}) } })
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-drive-root-'))
+    for (const folder of ['documents', 'reports', 'media', 'runtime']) {
+        await mkdir(path.join(dir, folder), { recursive: true })
+    }
+    await writeFile(path.join(dir, 'documents/page.md'), '# hello\n')
+    await writeFile(path.join(dir, 'users.htpasswd'), ['alice', 'bob', 'carol']
+        .map(u => `${u}:${bcrypt.hashSync(`${u}-pw`, 10)}`).join('\n') + '\n')
+    await writeFile(path.join(dir, 'groups.htgroup'),
+        'editors: alice\nreviewers: bob\nowners: carol\n')
+
+    const { default: express } = await import('express')
+    const app = express()
+    runtime.options = { ...runtime.options, app, workingFolder: dir, runtimeFolder: path.join(dir, 'runtime') }
+    runtime.config = { ...runtime.config }
+    runtime.engine = { ...runtime.engine, logger: { info(){}, warn(){}, error(){}, debug(){}, trace(){}, fatal(){} } }
+
+    const identity = auth({
+        capabilities: {
+            editors:   ['drive:SkinCheck'],          // alice: one endpoint
+            reviewers: ['drive:Reports'],            // bob: a different one
+            owners:    ['*'],                        // carol: all of them
+        },
+    })
+    const plugin = drive({
+        host: HOST,
+        auth: identity,
+        endpoints: {
+            SkinCheck: { folder: 'documents' },
+            Reports:   { folder: 'reports' },
+            Media:     { folder: 'media', displayName: 'Media library' },
+        },
+    })
+
+    const load = [], loaded = []
+    const core = {
+        runtime,
+        onLoad:    (cb) => load.push(cb),
+        onLoaded:  (cb) => loaded.push(cb),
+        useLogger: () => ({ info(){}, warn(){}, error(){}, debug(){}, trace(){} }),
+    }
+    identity(core)
+    plugin(core)
+    for (const cb of load)   await cb()
+    for (const cb of loaded) await cb()
+
+    server = await new Promise(resolve => { const s = app.listen(0, () => resolve(s)) })
+    port = server.address().port
+})
+
+after(async () => {
+    server?.closeAllConnections?.()
+    await new Promise(r => server?.close(r))
+    await rm(dir, { recursive: true, force: true })
+})
+
+describe('the drive root on its own host', () => {
+    it('announces itself as WebDAV, which is what the redirector asks first', async () => {
+        // Answered without credentials on purpose: this is discovery, and it
+        // is what the redirector asks BEFORE it has anything to offer. It
+        // discloses that a DAV server is here and nothing about what is in it.
+        const res = await request('OPTIONS', '/')
+        assert.equal(res.status, 200)
+        assert.match(res.headers.dav ?? '', /\b1\b/, 'the root must claim class 1')
+        assert.match(res.headers.allow ?? '', /PROPFIND/)
+        assert.equal(res.headers['cache-control'], 'no-cache',
+            'a discovery answer that can be cached is one a client keeps refusing')
+    })
+
+    it('challenges an anonymous listing, so a DAV client prompts', async () => {
+        const res = await propfind()
+        assert.equal(res.status, 401)
+        assert.match(res.headers['www-authenticate'] ?? '', /^Basic /,
+            'Basic is the only scheme Explorer and Finder speak')
+    })
+
+    it('lists only the endpoints the user may read', async () => {
+        const xml = (await propfind({ headers: { authorization: as('alice') } })).body
+        assert.match(xml, /<D:href>\/SkinCheck\/<\/D:href>/, xml)
+        assert.doesNotMatch(xml, /Reports/, 'bob\'s endpoint is not alice\'s to see')
+        assert.doesNotMatch(xml, /Media/, 'nor one nobody granted her')
+    })
+
+    it('shows a different user a different drive', async () => {
+        const xml = (await propfind({ headers: { authorization: as('bob') } })).body
+        assert.match(xml, /<D:href>\/Reports\/<\/D:href>/, xml)
+        assert.doesNotMatch(xml, /SkinCheck/, xml)
+    })
+
+    it('gives a wildcard holder everything, under its display name', async () => {
+        const xml = (await propfind({ headers: { authorization: as('carol') } })).body
+        for (const name of ['SkinCheck', 'Reports', 'Media']) {
+            assert.match(xml, new RegExp(`<D:href>/${name}/</D:href>`), `${name} missing:\n${xml}`)
+        }
+        assert.match(xml, /<D:displayname>Media library<\/D:displayname>/,
+            'the listing uses the same name the mount reports')
+    })
+
+    it('describes only itself at Depth 0', async () => {
+        const xml = (await propfind({ headers: { authorization: as('carol'), depth: '0' } })).body
+        assert.match(xml, /<D:href>\/<\/D:href>/)
+        assert.doesNotMatch(xml, /SkinCheck/, 'Depth 0 is the collection, not its children')
+    })
+
+    it('leaves every other host alone', async () => {
+        // The whole safety of mounting at `/`. Without the Host gate a drive
+        // shadows every page on the site.
+        for (const method of ['OPTIONS', 'PROPFIND']) {
+            const res = await request(method, '/', { host: 'www.example.test', headers: { depth: '1' } })
+            assert.notEqual(res.status, 207, `${method} answered for the wrong host`)
+            assert.equal(res.headers.dav, undefined, `${method} advertised DAV to the wrong host`)
+        }
+    })
+
+    it('serves the endpoint itself beneath the root', async () => {
+        const res = await request('PROPFIND', '/SkinCheck/', {
+            headers: { depth: '1', authorization: as('alice') },
+        })
+        assert.equal(res.status, 207, res.body)
+        assert.match(res.body, /page\.md/, 'entering an endpoint reaches its real files')
+    })
+})