mikser-io-drive 0.12.0 → 0.14.0

package/index.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-import { registerRoute, resolveAuth, reachabilityOf, registerJunk } from 'mikser-io'
+import { registerRoute, resolveAuth, reachabilityOf, registerJunk, registerCapability } from 'mikser-io'
 import { MikserAuthenticator } from './lib/authenticator.js'
 import { registerFileTools } from './lib/files.js'
 import { withStagedWrites, stageWrites } from './lib/staged-writes.js'
@@ -127,6 +127,25 @@ export function drive(options = {}) {
                 const root = resolve(ep.folder)
                 const mountPath = `${base}/${name}`
 
+                // Say what these capabilities protect, so a session can be
+                // told what it may reach in terms of the SITE rather than in
+                // terms of verbs. This is the only place that knows the folder
+                // behind an endpoint, and `summary` is the operator's own
+                // description of what lives there — both are what an agent
+                // needs to reason about where it is working.
+                registerCapability(readCapability(name), {
+                    plugin: 'drive',
+                    grants: 'read',
+                    resource: { kind: 'collection', name, folder: ep.folder, summary: ep.summary },
+                })
+                if (!(ep.readOnly === true)) {
+                    registerCapability(writeCapability(name), {
+                        plugin: 'drive',
+                        grants: 'write',
+                        resource: { kind: 'collection', name, folder: ep.folder, summary: ep.summary },
+                    })
+                }
+
                 // 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.

package/lib/files.js

@@ -30,7 +30,7 @@ import { lookup as mimeLookup } from 'mime-types'
 // Drive writes with fs directly rather than through a collection handle, so
 // it records its own paths. Without this a media replacement — the change most
 // worth taking back — falls into the unattributed sweep.
-import { looksTextual, recordChangeSetWrite } from 'mikser-io'
+import { looksTextual, recordChangeSetWrite, explainRefusal, actingRole } from 'mikser-io'
 import { readFile, writeFile, mkdir, rename, stat, unlink, open } from 'node:fs/promises'
 import {
     runtime, readEntity, findEntities, nextCycleId, whenCycleCompletes, checksum,
@@ -472,6 +472,25 @@ export function registerFileTools({ runtime: rt, endpoints, capabilityOf, writeC
             const found = await locate(pathish, endpoints, workingFolder())
             if (found.error) return fail(found.error)
 
+            // Reads are capability-gated, the same as the WebDAV mount, which
+            // has always checked `drive:<name>` before serving a byte. This
+            // tool did not, so the two surfaces disagreed about the same
+            // endpoint — and a `readOnly` list derived from capabilities was
+            // describing a rule only half the transports enforced.
+            //
+            // A credential that is not capability-scoped is unaffected: holds()
+            // returns true for it, and the endpoint's own gate still applies.
+            const principal = mcp.principal?.() ?? null
+            if (found.endpoint && !holds(principal, capabilityOf(found.endpoint))) {
+                return fail(explainRefusal({
+                    capability: capabilityOf(found.endpoint),
+                    role: actingRole(principal?.roles ?? [], rt.options?.roles?.catalogue ?? {}),
+                    target: pathish,
+                    catalogue: rt.options?.roles?.catalogue ?? {},
+                    summaries: rt.options?.roles?.summaries ?? {},
+                }))
+            }
+
             let info
             try {
                 info = await stat(found.file)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-drive",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -25,7 +25,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-drive#readme",
   "peerDependencies": {
-    "mikser-io": "^9.46.0",
+    "mikser-io": "^9.52.0",
     "zod": "^4.0.0"
   },
   "dependencies": {

package/test/files.test.js

@@ -438,3 +438,61 @@ describe('move', () => {
         assert.match(r.content[0].text, /readOnly/)
     })
 })
+
+// Reads are capability-gated, the same as the WebDAV mount.
+//
+// The mount has always checked `drive:<name>` before serving a byte; this tool
+// did not, so the two surfaces disagreed about the same endpoint and a
+// `readOnly` list derived from capabilities described a rule only half the
+// transports enforced.
+describe('read capability', () => {
+    const toolsFor = async (principal) => {
+        const substrate = fakeSubstrate(principal)
+        registerFileTools({
+            runtime: {
+                options: {
+                    ...runtime.options, mcp: substrate,
+                    roles: {
+                        catalogue: {
+                            editors: ['drive:media', 'drive:media:write', 'drive:secrets'],
+                            developers: ['drive:media', 'drive:media:write', 'drive:secrets', 'drive:secrets:write'],
+                        },
+                        summaries: { developers: 'Everything an editor has, plus the code.' },
+                    },
+                },
+                refs: runtime.refs,
+            },
+            endpoints: { media: { folder: 'media' }, secrets: { folder: 'locked' } },
+            capabilityOf: readCapability, writeCapabilityOf: writeCapability,
+        })
+        return substrate
+    }
+
+    it('serves a file the principal may read', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'readable.txt', base64: b64('hello') }] })
+        const substrate = await toolsFor({ subject: 'ed', roles: ['editors'],
+                                           capabilities: ['drive:media', 'drive:media:write'] })
+        const r = await substrate.call('mikser_drive_read', { path: 'media/readable.txt' })
+        assert.equal(JSON.parse(r.content.find(c => c.type === 'text').text).content, 'hello')
+    })
+
+    it('refuses one it may not, naming the role and who can', async () => {
+        const substrate = await toolsFor({ subject: 'ed', roles: ['editors'],
+                                           capabilities: ['drive:media', 'drive:media:write'] })
+        const r = await substrate.call('mikser_drive_read', { path: 'secrets/anything.txt' })
+        assert.equal(r.isError, true)
+        const message = r.content.find(c => c.type === 'text').text
+        assert.match(message, /Connected as editors/, 'the refusal names the acting role')
+        assert.match(message, /drive:secrets/, 'and the capability it lacks')
+        assert.match(message, /developers/, 'and who carries it')
+        assert.doesNotMatch(message, /request|escalat|retry/i, 'and never suggests obtaining it')
+    })
+
+    it('does not narrow a credential that is not capability-scoped', async () => {
+        // A static token or a loopback caller. The endpoint's own gate still
+        // applies; this must not guess a narrower answer.
+        const substrate = await toolsFor({ subject: 'static', capabilities: null })
+        const r = await substrate.call('mikser_drive_read', { path: 'media/readable.txt' })
+        assert.notEqual(r.isError, true)
+    })
+})