mikser-io-drive 11.2.2 → 11.3.0

package/README.md

@@ -149,6 +149,47 @@ 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`:

package/index.js

@@ -5,6 +5,7 @@ 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 }
 
@@ -46,6 +47,7 @@ export const writeCapability = (name) => `drive:${name}:write`
  *             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,
  *     })
@@ -66,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
@@ -123,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`)
@@ -209,7 +227,7 @@ 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
@@ -250,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,
@@ -318,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/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.2.2",
+  "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/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')
+    })
+})