mikser-io-drive 11.5.0 → 11.6.2

package/README.md

@@ -238,6 +238,23 @@ drive({ host: 'drive.example.com', anonymousDiscovery: true, … })
 
 That relaxes discovery only. `PROPFIND /` still requires credentials.
 
+### The Basic challenge follows your auth configuration
+
+The drive writes its own `WWW-Authenticate: Basic` header rather than
+delegating to the verifier — a composite verifier challenges with whichever
+member can be satisfied interactively, and where OAuth discovery is configured
+that is Bearer, which Explorer and Finder do not speak.
+
+The `charset="UTF-8"` parameter is not a decision this package makes. It reads
+`basicCharset` from the auth plugin, so a deployment sets it once:
+
+```js
+auth({ basicCharset: false })   // on by default
+```
+
+It briefly defaulted off on a theory about the Windows redirector that did not
+survive measurement. See the auth package's README.
+
 ### Compliance classes at the root
 
 The root advertises `DAV: 1, 2, 3` — the same classes as the endpoints
@@ -257,6 +274,45 @@ a LOCK nothing sends, since clients lock the files they edit and those live
 under the endpoints, which support locking for real. `Allow` stays truthful, so
 a client that asks what the root itself permits gets the right answer.
 
+### When Windows cannot keep the mount
+
+Everything above gets Explorer to mount the drive. Keeping it mounted across a
+restart is a separate problem, and on a machine that has to run unattended it
+is not solvable from this side.
+
+The redirector reads saved credentials from the **Domain Password** store.
+Basic credentials cannot be persisted there — [KB 2673544][kb] documents this
+as by design, because WinHTTP cannot retrieve a saved Basic credential — so
+"remember my credentials" quietly stores nothing the reconnect can use. It
+looks like a server fault and is not one. Measured against a live endpoint,
+a reconnect sent four requests, **none** of them carrying an `Authorization`
+header, and gave up; the credential was sitting in Credential Manager the whole
+time, in the `Generic` store that `cmdkey /generic:` writes and the redirector
+never reads. Apache `mod_dav` on the same host, with the same credential,
+failed identically — which is the useful part of the measurement.
+
+So for a machine that exports documents on its own, do not mount the drive.
+Have the application write to a local folder and push that folder up:
+
+```
+wscript rclone-outbox.vbs "C:\SkinCheck" SkinCheck:Janus 120
+```
+
+[`clients/windows/rclone-outbox.vbs`](clients/windows/rclone-outbox.vbs) is
+that loop — an [rclone][rclone] `move` on an interval, run by `wscript.exe` so
+no console window appears, and started by a shortcut in `shell:startup` so it
+needs no elevation and no Scheduled Task. rclone authenticates from its own
+config on every request and has no reconnect to lose, which is the whole reason
+it works where the mount does not.
+
+This trades a drive letter for a folder, and it is worth being clear about what
+that costs: nobody browses the server from the machine any more. In exchange an
+export can no longer fail because a mount dropped, and a server that is
+unreachable delays the upload instead of losing the document.
+
+[kb]: https://support.microsoft.com/help/2673544
+[rclone]: https://rclone.org/webdav/
+
 ## What the folder is called
 
 The endpoint key is the name, and the mount reports it as `displayname`:

package/clients/windows/rclone-outbox.vbs

@@ -0,0 +1,79 @@
+' rclone-outbox.vbs - hidden, looping uploader for a mikser-io-drive endpoint.
+'
+' Windows cannot mount this drive unattended. The WebDAV redirector reads its
+' credentials from the Domain Password store and refuses to persist Basic
+' credentials there at all (KB 2673544), so a mapped drive re-prompts after
+' every restart and an export silently lands on a dead letter. Measured against
+' a live endpoint: four redirector requests during a reconnect, none of them
+' carrying an Authorization header, while rclone authenticated on its first.
+'
+' So the export never touches the network. The exporting application writes to
+' a local folder and this moves the folder's contents up, which means an export
+' cannot fail because a mount dropped, and an unreachable server only delays
+' the upload instead of losing the file.
+'
+' This is a .vbs and not a .cmd because wscript.exe runs with no console at
+' all. A .cmd on a two-minute timer flashes a window on the desktop every two
+' minutes, and on a shared machine someone eventually turns it off. The other
+' way to run a console tool quietly is a Scheduled Task, which needs elevation
+' to register in the root task folder - this needs none: put a shortcut to it
+' in shell:startup and it begins with the session.
+'
+' Usage:
+'   wscript rclone-outbox.vbs <outbox folder> <rclone remote> [interval seconds]
+'
+' For example, against an endpoint declared as `SkinCheck: { folder: ... }`:
+'   wscript rclone-outbox.vbs "C:\SkinCheck" SkinCheck:Janus 120
+
+Option Explicit
+
+Dim shell, arguments, outbox, remote, interval, rclone, logFile, command
+
+Set shell = CreateObject("WScript.Shell")
+Set arguments = WScript.Arguments
+
+If arguments.Count < 2 Then
+    WScript.Echo "usage: wscript rclone-outbox.vbs <outbox folder> <remote> [interval seconds]"
+    WScript.Quit 1
+End If
+
+outbox = arguments(0)
+remote = arguments(1)
+If arguments.Count > 2 Then
+    interval = CLng(arguments(2))
+Else
+    interval = 120
+End If
+
+rclone = shell.ExpandEnvironmentStrings("%LOCALAPPDATA%\rclone\rclone.exe")
+logFile = shell.ExpandEnvironmentStrings("%LOCALAPPDATA%\rclone\outbox.log")
+
+' move, not copy: the server is the system of record, the same as the mapped
+' drive it replaces, and it keeps the exported documents off a shared desktop.
+' It also gives whoever works at the machine a correct indicator that needs no
+' explaining - an empty outbox means everything is up, and a failing upload
+' makes files visibly pile up instead of failing where nobody looks.
+'
+' --min-age keeps a file that is still being written out of the transfer. The
+' exporting application is long finished with it by the time it ages in, and a
+' half-written document uploaded and then deleted locally is unrecoverable.
+' --ignore-times because the server reports no modification-time support
+' (rclone prints a Precision of 100 years for it), which leaves size as the
+' only thing rclone can compare. A re-export under the same name and the same
+' size - a corrected document for the same patient and date - would otherwise
+' be treated as already uploaded, skipped, and deleted locally. Measured: a
+' 3.773 MiB export was removed with "There was nothing to transfer".
+'
+' It costs nothing here. move empties the outbox, so a document is offered
+' once and uploaded once; this only removes a skip decision that cannot be
+' made safely.
+command = """" & rclone & """ move """ & outbox & """ " & remote & _
+          " --min-age 1m --ignore-times --transfers 2" & _
+          " --log-level INFO --log-file """ & logFile & """"
+
+Do
+    ' 0 hides the window; True waits for the run to finish, so a slow upload
+    ' delays the next pass instead of overlapping with it.
+    shell.Run command, 0, True
+    WScript.Sleep interval * 1000
+Loop

package/index.js

@@ -68,6 +68,22 @@ export const writeCapability = (name) => `drive:${name}:write`
  * handler (server.js), so an endpoint at `/content` would silently shadow a
  * real page at /content/ in the built site.
  */
+// Does this deployment's auth want charset="UTF-8" on the Basic challenge?
+//
+// Asked of the auth plugin rather than configured here, so the decision is
+// made once per deployment. mikser-io-auth exposes `basicCharset` and
+// defaults it ON; anything else — a bare static token, no auth at all — has
+// no opinion, and falls back to the same default rather than to silence.
+//
+// Not delegated to the verifier's own `challenge()`, which would be the
+// tidier shape: a composite verifier challenges with whichever member can be
+// satisfied interactively, and where OAuth discovery is configured that is
+// Bearer. Explorer and Finder speak Basic and nothing else, so the scheme
+// here is not negotiable — only the parameter is.
+function basicCharsetOf(auth) {
+    return auth?.basicCharset ?? true
+}
+
 export function drive(options = {}) {
     const {
         base      = '/drive',
@@ -87,6 +103,10 @@ export function drive(options = {}) {
         host,
         auth,
         realm     = 'mikser',
+        // `charset="UTF-8"` on the Basic challenge, RFC 7617 §2.1, is not a
+        // knob of this package's own: it follows whatever the auth plugin was
+        // configured with, so a deployment decides it once. See
+        // basicChallenge in mikser-io for why the default is on.
         // 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
@@ -225,6 +245,7 @@ export function drive(options = {}) {
                     // ReadOnlyPlugin refuses every mutation regardless.
                     writeCapability: readOnly ? null : writeCapability(name),
                     realm,
+                    charset: basicCharsetOf(auth),
                     logger,
                 })
 
@@ -409,6 +430,7 @@ export function drive(options = {}) {
                                 allowRemote:   true,
                                 trustLoopback: !auth,
                                 realm,
+                                charset: basicCharsetOf(auth),
                             },
                             logger,
                             anonymousDiscovery,

package/lib/authenticator.js

@@ -1,5 +1,5 @@
 import { UnauthorizedError, ForbiddenError } from 'nephele'
-import { authorize } from 'mikser-io'
+import { authorize, basicChallenge } from 'mikser-io'
 // The one implementation of "does this principal hold it", including the
 // `*` wildcard — checked here rather than re-derived, because two gates in
 // this file and one in mikser-io-auth each had their own `.includes` and a
@@ -39,11 +39,15 @@ export class MikserAuthenticator {
     #capability
     #writeCapability
     #realm
+    // Whether the Basic challenge carries charset="UTF-8". Follows the
+    // deployment's auth configuration rather than being decided here — see
+    // basicChallenge in mikser-io.
+    #charset
     #logger
 
     constructor({
         verifier, trustLoopback = false, allowRemote = false,
-        capability, writeCapability, realm = 'mikser', logger,
+        capability, writeCapability, realm = 'mikser', charset = false, logger,
     } = {}) {
         this.#verifier        = verifier
         this.#trustLoopback   = trustLoopback
@@ -51,6 +55,7 @@ export class MikserAuthenticator {
         this.#capability      = capability
         this.#writeCapability = writeCapability
         this.#realm           = realm
+        this.#charset         = charset
         this.#logger          = logger
     }
 
@@ -72,7 +77,8 @@ export class MikserAuthenticator {
             // 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"`)
+                response.set('WWW-Authenticate',
+                    basicChallenge({ realm: this.#realm, charset: this.#charset }))
                 throw new UnauthorizedError(outcome.error)
             }
             // 403: the credential was never the problem — the caller's origin

package/lib/root-listing.js

@@ -16,7 +16,7 @@
 // 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'
+import { authorize, hasCapability, basicChallenge } from 'mikser-io'
 
 const escape = (text) => String(text)
     .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
@@ -128,7 +128,7 @@ export function rootListing({ entries, rootName, auth, logger, anonymousDiscover
         } 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"`)
+                .set('WWW-Authenticate', basicChallenge({ realm: auth.realm, charset: auth.charset }))
                 .end()
         }
 
@@ -137,7 +137,7 @@ export function rootListing({ entries, rootName, auth, logger, anonymousDiscover
             // 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"`)
+                    .set('WWW-Authenticate', basicChallenge({ realm: auth.realm, charset: auth.charset }))
                     .end()
             }
             // Authenticated and not permitted. NEVER 401 here: a client that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-drive",
-  "version": "11.5.0",
+  "version": "11.6.2",
   "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",
@@ -8,7 +8,7 @@
     "better-sqlite3": true
   },
   "scripts": {
-    "test": "node --no-warnings --test --test-reporter=spec 'test/**/*.test.js'"
+    "test": "node --no-warnings --test --test-timeout=120000 --test-reporter=spec 'test/**/*.test.js'"
   },
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-drive#readme",
   "peerDependencies": {
-    "mikser-io": "^11.7.0",
+    "mikser-io": "^11.11.1",
     "zod": "^4.0.0"
   },
   "dependencies": {
@@ -41,7 +41,7 @@
     "bcryptjs": "^3.0.0",
     "express": "^5.2.1",
     "globby": "^15.0.0",
-    "mikser-io": "^11.7.0",
+    "mikser-io": "^11.11.1",
     "mikser-io-auth": "^11.0.1",
     "mikser-io-mcp": "^11.0.1",
     "webdav": "^5.10.0",

package/test/derived.test.js

@@ -124,11 +124,17 @@ before(async (t) => {
         + '    ],\n'
         + '})\n')
 
+    // `detached` so this gets its own process GROUP, which is what the
+    // teardown kills. mikser under --watch --server runs render workers, and
+    // they inherit the pipes below: signalling the parent alone can leave a
+    // worker holding the write end open, which keeps THIS process's read
+    // handles alive and the test run never ends. Killing the group takes the
+    // whole tree.
     server = spawn(process.execPath, [
         path.join(dir, 'node_modules/mikser-io/app.js'),
         '--working-folder', dir, '--output-folder', 'out', '--runtime-folder', 'runtime',
         '--watch', '--server', String(PORT), '--url', `http://127.0.0.1:${PORT}`,
-    ], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] })
+    ], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
 
     // Kept so a server that never comes up says WHY. Throwing this away left
     // the failure as a bare ECONNREFUSED, which names the symptom and hides
@@ -155,6 +161,15 @@ before(async (t) => {
     await new Promise(r => setTimeout(r, 3000))
 })
 
+// Signal the whole process GROUP, not just the child.
+//
+// `detached: true` above put the server in its own group, so a negative pid
+// reaches it and everything it started. Falls back to the child alone if the
+// group is already gone, which is the ordinary case and not an error.
+function killTree(child, signal) {
+    try { process.kill(-child.pid, signal) } catch { try { child.kill(signal) } catch { /* already gone */ } }
+}
+
 after(async () => {
     // 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
@@ -167,16 +182,30 @@ after(async () => {
     // close() does not come back.
     if (server && server.exitCode === null && server.signalCode === null) {
         const exited = new Promise(resolve => server.once('exit', resolve))
-        server.kill()
+        killTree(server, 'SIGTERM')
         const inTime = await Promise.race([
             exited.then(() => true),
             new Promise(resolve => setTimeout(() => resolve(false), 5000)),
         ])
         if (!inTime) {
-            server.kill('SIGKILL')
-            await exited
+            killTree(server, 'SIGKILL')
+            // Bounded. `await exited` alone assumes the child is the only
+            // thing that can hold this up, and the whole failure being fixed
+            // here is that it is not.
+            await Promise.race([
+                exited,
+                new Promise(resolve => setTimeout(resolve, 5000)),
+            ])
         }
     }
+    // The pipes, explicitly, and this is the actual fix rather than belt and
+    // braces. A worker that inherited the write end keeps this side readable
+    // even once the server is gone, and a readable stream handle is enough to
+    // keep node alive: every test passes, nothing is left to run, and the
+    // process simply sits there. On CI that was fifteen minutes of silence
+    // ended by the job timeout and "Terminate orphan process", twice.
+    server?.stdout?.destroy()
+    server?.stderr?.destroy()
     if (dir) await rm(dir, { recursive: true, force: true })
 })
 

package/test/drive.test.js

@@ -101,8 +101,11 @@ describe('auth', () => {
     it('challenges an anonymous request with Basic, so a DAV client prompts', async () => {
         const res = await dav('PROPFIND', '/drive/content/', { headers: { depth: '0' } })
         assert.equal(res.status, 401)
-        assert.match(res.headers.get('www-authenticate'), /^Basic realm="mikser"/)
-        assert.match(res.headers.get('www-authenticate'), /charset="UTF-8"/)
+        // Exact bytes: the drive follows the deployment's auth configuration
+        // rather than hardcoding the parameter, and this fixture leaves it at
+        // the default. See basicChallenge in mikser-io.
+        assert.equal(res.headers.get('www-authenticate'),
+            'Basic realm="mikser", charset="UTF-8"')
     })
 
     it('refuses a wrong password', async () => {

package/test/root-denial.test.js

@@ -48,6 +48,27 @@ const insufficient = {
 // Presented a credential, rejected, no refinement — the ordinary 401.
 const invalid = { verify: async () => false }
 
+// A verifier that throws — a store that cannot be read, a hash library that
+// blew up. The root answers 401 rather than 500, because a client that can
+// retry with credentials is more use than a stack trace, and this branch has
+// its own `res.set` call that a mutation can change independently of the
+// ordinary one.
+const throwing = { verify: async () => { throw new Error('store unreadable') } }
+
+describe('when the verifier itself fails', () => {
+    for (const method of ['OPTIONS', 'PROPFIND']) {
+        it(`challenges with the configured bytes on ${method}`, async () => {
+            const res = fakeResponse()
+            await middleware(throwing)(request(method), res, () => {
+                assert.fail('the root must answer, not fall through')
+            })
+            assert.equal(res.statusCode, 401)
+            assert.equal(res.headers['www-authenticate'], 'Basic realm="mikser", charset="UTF-8"',
+                'the error path must emit what the happy path emits, not its own header')
+        })
+    }
+})
+
 describe('an authenticated caller who is not permitted', () => {
     for (const method of ['OPTIONS', 'PROPFIND']) {
         it(`gets 403 and no challenge on ${method}`, async () => {

package/test/root-listing.test.js

@@ -209,6 +209,21 @@ describe('the drive root on its own host', () => {
         assert.equal(res.status, 401)
     })
 
+    it('challenges with the exact bytes this deployment configured', async () => {
+        // Exact, because the parameter that is NOT here is the finding:
+        // `charset="UTF-8"` is advisory (RFC 7617 §2.1) and the Windows
+        // WebDAV redirector appears not to parse it — a mapped drive carrying
+        // it never reconnects from stored credentials. The root follows the
+        // auth plugin's choice rather than carrying a knob of its own, and
+        // this fixture leaves it at the default.
+        for (const method of ['OPTIONS', 'PROPFIND']) {
+            const res = await request(method, '/', { headers: { depth: '1' } })
+            assert.equal(res.status, 401, `${method} must challenge`)
+            assert.equal(res.headers['www-authenticate'], 'Basic realm="mikser", charset="UTF-8"',
+                `${method} must carry what this deployment's auth configured`)
+        }
+    })
+
     it('accepts a bearer-carrying client at the root', async () => {
         // rclone and curl carry a token rather than Basic. Challenging
         // OPTIONS must not turn them away — the verifier already accepts