mikser-io-drive 0.9.0

package/test/drive.test.js

@@ -0,0 +1,233 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm, mkdir, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import bcrypt from 'bcryptjs'
+
+import { runtime } from 'mikser-io'
+import { auth } from 'mikser-io-auth'
+import { drive } from '../index.js'
+
+// A real Nephele server over a real directory, authenticated through a real
+// htpasswd file. WebDAV is almost entirely I/O and protocol; a mocked
+// version of it would prove nothing.
+let server, port, dir, content
+
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64')
+const as  = (user) => ({ authorization: `Basic ${b64(`${user}:${user}-pw`)}` })
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-drive-'))
+    content = path.join(dir, 'documents')
+    await mkdir(content, { recursive: true })
+    await mkdir(path.join(dir, 'runtime'), { recursive: true })
+    await writeFile(path.join(content, '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\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: {
+            // Capability names are derived from the endpoint name, so an
+            // endpoint you were never granted is invisible to you — which is
+            // why `editors` has to name `drive:locked` too.
+            editors:   ['drive:content', 'drive:content:write', 'drive:locked'],
+            reviewers: ['drive:content'],                          // read, no write
+        },
+    })
+
+    const plugin = drive({
+        endpoints: {
+            content: { folder: 'documents' },
+            locked:  { folder: 'documents', readOnly: true },
+        },
+        auth: identity,
+    })
+
+    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 () => {
+    await new Promise(r => server?.close(r))
+    await rm(dir, { recursive: true, force: true })
+})
+
+const dav = (method, p, { headers = {}, body } = {}) =>
+    fetch(`http://127.0.0.1:${port}${p}`, { method, headers, body })
+
+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"/)
+    })
+
+    it('refuses a wrong password', async () => {
+        const res = await dav('PROPFIND', '/drive/content/', {
+            headers: { depth: '0', authorization: `Basic ${b64('alice:wrong')}` },
+        })
+        assert.equal(res.status, 401)
+    })
+
+    it('lets a granted user list the collection', async () => {
+        const res = await dav('PROPFIND', '/drive/content/', { headers: { depth: '1', ...as('alice') } })
+        assert.equal(res.status, 207)
+        const xml = await res.text()
+        assert.match(xml, /page\.md/)
+    })
+
+    it('403s an authenticated user who lacks the endpoint capability', async () => {
+        // carol is in no group, so with a capability map configured she holds
+        // nothing — authenticated, but not for this endpoint.
+        const res = await dav('PROPFIND', '/drive/content/', { headers: { depth: '0', ...as('carol') } })
+        assert.equal(res.status, 403)
+    })
+})
+
+describe('read and write', () => {
+    it('GETs a file', async () => {
+        const res = await dav('GET', '/drive/content/page.md', { headers: as('alice') })
+        assert.equal(res.status, 200)
+        assert.equal(await res.text(), '# hello\n')
+    })
+
+    it('PUTs a file, and it lands in the working folder where the build will see it', async () => {
+        const res = await dav('PUT', '/drive/content/new.md', {
+            headers: { ...as('alice'), 'content-type': 'text/markdown' },
+            body: '# written over dav\n',
+        })
+        assert.ok([201, 204].includes(res.status), `unexpected ${res.status}`)
+        assert.equal(await readFile(path.join(content, 'new.md'), 'utf8'), '# written over dav\n')
+    })
+
+    it('DELETEs a file', async () => {
+        await dav('PUT', '/drive/content/gone.md', { headers: as('alice'), body: 'x' })
+        const res = await dav('DELETE', '/drive/content/gone.md', { headers: as('alice') })
+        assert.ok([200, 204].includes(res.status), `unexpected ${res.status}`)
+        await assert.rejects(() => readFile(path.join(content, 'gone.md')))
+    })
+})
+
+describe('write capability is per request, not per mount', () => {
+    it('a user with read but not write gets a read-only view of the SAME endpoint', async () => {
+        // bob is a reviewer: holds drive:content, not drive:content:write.
+        const list = await dav('PROPFIND', '/drive/content/', { headers: { depth: '0', ...as('bob') } })
+        assert.equal(list.status, 207, 'bob can read')
+
+        const write = await dav('PUT', '/drive/content/bob.md', { headers: as('bob'), body: 'nope' })
+        assert.ok(write.status >= 400, `bob should not write, got ${write.status}`)
+        await assert.rejects(() => readFile(path.join(content, 'bob.md')),
+                             'nothing should have been written')
+    })
+
+    it('and the same URL is writable for someone who holds the capability', async () => {
+        const write = await dav('PUT', '/drive/content/alice.md', { headers: as('alice'), body: 'yes' })
+        assert.ok([201, 204].includes(write.status))
+    })
+})
+
+describe('an endpoint you were not granted is refused outright', () => {
+    it('403s a user who holds no capability for it', async () => {
+        // bob is a reviewer: drive:content only, nothing for `locked`.
+        const res = await dav('PROPFIND', '/drive/locked/', { headers: { depth: '0', ...as('bob') } })
+        assert.equal(res.status, 403)
+    })
+})
+
+describe('readOnly is a hard cap', () => {
+    it('refuses a write even from a user who holds every capability', async () => {
+        // alice holds drive:content:write, but this endpoint is readOnly —
+        // "nobody writes here" is a different statement from "you may not".
+        const res = await dav('PUT', '/drive/locked/hard.md', { headers: as('alice'), body: 'x' })
+        assert.ok(res.status >= 400, `expected a refusal, got ${res.status}`)
+        await assert.rejects(() => readFile(path.join(content, 'hard.md')))
+    })
+
+    it('still allows reading', async () => {
+        const res = await dav('GET', '/drive/locked/page.md', { headers: as('alice') })
+        assert.equal(res.status, 200)
+    })
+})
+
+describe('no .nephelemeta sidecars in a watched source folder', () => {
+    it('a PROPPATCH reports success without writing meta files', async () => {
+        // The default 'meta-files' strategy would drop .nephelemeta into the
+        // documents folder, where mikser's sources would pick it up as an
+        // entity — and a rebuild that writes could trip the watcher again.
+        const res = await dav('PROPPATCH', '/drive/content/page.md', {
+            headers: { ...as('alice'), 'content-type': 'text/xml' },
+            body: `<?xml version="1.0" encoding="utf-8"?>
+<D:propertyupdate xmlns:D="DAV:"><D:set><D:prop><customprop xmlns="X:">v</customprop></D:prop></D:set></D:propertyupdate>`,
+        })
+        assert.ok(res.status < 500, `unexpected ${res.status}`)
+        const { readdir } = await import('node:fs/promises')
+        const files = await readdir(content)
+        assert.deepEqual(files.filter(f => f.includes('nephelemeta')), [],
+                         'no sidecar files may appear in a source folder')
+    })
+})
+
+describe('the write gate covers every mutating method', () => {
+    // A gate that only knew about PUT would leave MKCOL, MOVE, COPY and
+    // PROPPATCH wide open — each of which changes the working folder, which
+    // is what the build reads.
+    const cases = [
+        ['PUT',       '/drive/content/x.md',  { body: 'x' }],
+        ['DELETE',    '/drive/content/page.md', {}],
+        ['MKCOL',     '/drive/content/newdir/', {}],
+        ['MOVE',      '/drive/content/page.md', { headers: { destination: '/drive/content/moved.md' } }],
+        ['COPY',      '/drive/content/page.md', { headers: { destination: '/drive/content/copied.md' } }],
+        ['PROPPATCH', '/drive/content/page.md', {
+            headers: { 'content-type': 'text/xml' },
+            body: `<?xml version="1.0" encoding="utf-8"?>
+<D:propertyupdate xmlns:D="DAV:"><D:set><D:prop><p xmlns="X:">v</p></D:prop></D:set></D:propertyupdate>`,
+        }],
+        ['LOCK',      '/drive/content/page.md', {
+            headers: { 'content-type': 'text/xml' },
+            body: `<?xml version="1.0" encoding="utf-8"?>
+<D:lockinfo xmlns:D="DAV:"><D:lockscope><D:exclusive/></D:lockscope><D:locktype><D:write/></D:locktype></D:lockinfo>`,
+        }],
+    ]
+
+    for (const [method, url, opts] of cases) {
+        it(`refuses ${method} for a reader`, async () => {
+            const res = await dav(method, url, {
+                ...opts,
+                headers: { ...(opts.headers ?? {}), ...as('bob') },
+            })
+            assert.equal(res.status, 403, `${method} should be 403 for bob, got ${res.status}`)
+        })
+    }
+
+    it('and still lets a reader read', async () => {
+        assert.equal((await dav('GET', '/drive/content/page.md', { headers: as('bob') })).status, 200)
+        assert.equal((await dav('PROPFIND', '/drive/content/', { headers: { depth: '1', ...as('bob') } })).status, 207)
+        assert.equal((await dav('OPTIONS', '/drive/content/', { headers: as('bob') })).status < 300, true)
+    })
+})

package/test/files.test.js

@@ -0,0 +1,269 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, mkdir, writeFile, readFile, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { runtime } from 'mikser-io'
+import { registerFileTools } from '../lib/files.js'
+import { readCapability, writeCapability } from '../index.js'
+
+// These carry bytes through the tool, for a caller with no route to the host.
+// What a stored file BECOMES is the pipeline's business, and the whole point of
+// the response is reporting that rather than assuming it — so the parts that
+// depend on a catalog say so rather than being faked here.
+
+let dir, mcp, tools
+
+function fakeSubstrate(principal) {
+    const registry = new Map()
+    return {
+        principal: () => principal,
+        registerTool: (name, def, handler) => registry.set(name, handler),
+        call: (name, args) => registry.get(name)(args ?? {}),
+        names: () => [...registry.keys()],
+    }
+}
+
+const b64 = (s) => Buffer.from(s).toString('base64')
+// A 1x1 PNG, so the viewable path has something real to return.
+const PNG = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+    'base64')
+
+const body = (r) => JSON.parse(r.content.find(c => c.type === 'text').text)
+const call = (name, args) => mcp.call(name, args)
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-files-'))
+    await mkdir(path.join(dir, 'media'), { recursive: true })
+    await mkdir(path.join(dir, 'locked'), { recursive: true })
+    runtime.options = { ...runtime.options, workingFolder: dir, runtimeFolder: path.join(dir, 'runtime') }
+
+    mcp = fakeSubstrate({ subject: 'alice', capabilities: ['drive:media', 'drive:media:write'] })
+    registerFileTools({
+        runtime: { options: { ...runtime.options, mcp }, refs: runtime.refs },
+        endpoints: { media: { folder: 'media' }, locked: { folder: 'locked', readOnly: true } },
+        capabilityOf: readCapability, writeCapabilityOf: writeCapability,
+    })
+    tools = mcp.names()
+})
+
+after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+describe('registration', () => {
+    it('registers exactly the four file tools', () => {
+        assert.deepEqual(tools.sort(),
+            ['mikser_drive_add', 'mikser_drive_delete', 'mikser_drive_move', 'mikser_drive_read'])
+    })
+})
+
+describe('add', () => {
+    it('stores a batch in one call, under one cycle', async () => {
+        // Ten files, one cycleId — not one rebuild per file.
+        const files = Array.from({ length: 10 }, (_, i) =>
+            ({ name: `shot-${i}.png`, base64: PNG.toString('base64'), mime: 'image/png' }))
+        const r = body(await call('mikser_drive_add', { endpoint: 'media', folder: 'batch', files }))
+        assert.equal(r.stored, 10)
+        assert.equal(typeof r.cycleId, 'number')
+        for (const f of r.files) {
+            assert.equal(f.size, PNG.length)
+            assert.equal(f.mime, 'image/png')
+        }
+        assert.ok(await stat(path.join(dir, 'media/batch/shot-0.png')))
+        assert.ok(await stat(path.join(dir, 'media/batch/shot-9.png')))
+    })
+
+    it('refuses an existing file rather than replacing it silently', async () => {
+        const one = [{ name: 'once.txt', base64: b64('first') }]
+        assert.equal(body(await call('mikser_drive_add', { endpoint: 'media', files: one })).stored, 1)
+
+        const again = await call('mikser_drive_add',
+            { endpoint: 'media', files: [{ name: 'once.txt', base64: b64('second') }] })
+        assert.equal(again.isError, true)
+        assert.match(again.content[0].text, /already exist/)
+        assert.equal(await readFile(path.join(dir, 'media/once.txt'), 'utf8'), 'first',
+            'the original must be untouched')
+    })
+
+    it('replaces when told to, and says it replaced', async () => {
+        const r = body(await call('mikser_drive_add',
+            { endpoint: 'media', overwrite: true, files: [{ name: 'once.txt', base64: b64('third') }] }))
+        assert.equal(r.files[0].replaced, true)
+        assert.equal(await readFile(path.join(dir, 'media/once.txt'), 'utf8'), 'third')
+    })
+
+    it('writes NOTHING when any file in the batch is bad', async () => {
+        // Decoded and checked before a single write. A batch that fails halfway
+        // leaves the caller unable to say what landed.
+        const r = await call('mikser_drive_add', { endpoint: 'media', folder: 'atomic', files: [
+            { name: 'good.txt', base64: b64('fine') },
+            { name: 'bad.txt', base64: '' },
+        ] })
+        assert.equal(r.isError, true)
+        await assert.rejects(() => stat(path.join(dir, 'media/atomic/good.txt')))
+    })
+
+    it('refuses a name that would escape the folder', async () => {
+        for (const name of ['../escape.txt', 'a/../../escape.txt', '/abs.txt', '.hidden']) {
+            const r = await call('mikser_drive_add', { endpoint: 'media', files: [{ name, base64: b64('x') }] })
+            assert.equal(r.isError, true, `${name} must be refused`)
+        }
+        await assert.rejects(() => stat(path.join(dir, 'escape.txt')))
+    })
+
+    it('refuses a file over the per-file cap, and points somewhere useful', async () => {
+        const big = Buffer.alloc(3 * 1024 * 1024, 1).toString('base64')
+        const r = await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'big.bin', base64: big }] })
+        assert.equal(r.isError, true)
+        assert.match(r.content[0].text, /per-file cap/)
+        assert.match(r.content[0].text, /WebDAV mount/)
+        assert.match(r.content[0].text, /Nothing was written/)
+    })
+
+    it('refuses a readOnly endpoint, and names the real ones for a wrong guess', async () => {
+        const ro = await call('mikser_drive_add', { endpoint: 'locked', files: [{ name: 'x.txt', base64: b64('x') }] })
+        assert.equal(ro.isError, true)
+        assert.match(ro.content[0].text, /readOnly/)
+
+        const nope = await call('mikser_drive_add', { endpoint: 'nope', files: [{ name: 'x.txt', base64: b64('x') }] })
+        assert.equal(nope.isError, true)
+        assert.match(nope.content[0].text, /media, locked/)
+    })
+
+    it('dryRun reports the cost and writes nothing', async () => {
+        const r = body(await call('mikser_drive_add', { endpoint: 'media', dryRun: true, folder: 'dry', files: [
+            { name: 'a.txt', base64: b64('hello') },
+        ] }))
+        assert.equal(r.dryRun, true)
+        assert.equal(r.totalBytes, 5)
+        assert.equal(typeof r.approxTokens, 'number')
+        assert.equal(r.files[0].wouldOverwrite, false)
+        await assert.rejects(() => stat(path.join(dir, 'media/dry/a.txt')))
+    })
+})
+
+describe('read', () => {
+    it('returns an image as an image, with the facts beside it', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [
+            { name: 'look.png', base64: PNG.toString('base64'), mime: 'image/png' } ] })
+        const r = await call('mikser_drive_read', { path: 'media/look.png' })
+        const image = r.content.find(c => c.type === 'image')
+        assert.ok(image, 'a model must be able to look at it, not be refused')
+        assert.equal(image.mimeType, 'image/png')
+        assert.equal(body(r).size, PNG.length)
+    })
+
+    it('returns text as text', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'note.txt', base64: b64('readable') }] })
+        assert.equal(body(await call('mikser_drive_read', { path: 'media/note.txt' })).content, 'readable')
+    })
+
+    it('describes a binary it cannot show rather than returning garbage', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'font.woff2', base64: b64(' ') }] })
+        const r = body(await call('mikser_drive_read', { path: 'media/font.woff2' }))
+        assert.equal(r.viewed, false)
+        assert.equal(r.content, undefined)
+        assert.match(r.note, /convincing garbage/)
+    })
+
+    it('says so when there is nothing there', async () => {
+        const r = await call('mikser_drive_read', { path: 'media/absent.png' })
+        assert.equal(r.isError, true)
+    })
+})
+
+describe('delete', () => {
+    it('moves to trash rather than unlinking, and can be undone', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'bye.txt', base64: b64('content') }] })
+        const r = body(await call('mikser_drive_delete', { path: 'media/bye.txt' }))
+        assert.equal(r.removed, true)
+        await assert.rejects(() => stat(path.join(dir, 'media/bye.txt')), 'gone from the folder')
+        // Still on disk, so a wrong delete is a move back and not a restore.
+        assert.ok(await stat(path.join(dir, r.trash)))
+        assert.match(r.restore, /Move it back/)
+    })
+
+    it('puts trash OUTSIDE the served folder', async () => {
+        // Inside it, the file would be republished at a new URL and, where git
+        // sync is on, committed.
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'gone.txt', base64: b64('x') }] })
+        const r = body(await call('mikser_drive_delete', { path: 'media/gone.txt' }))
+        assert.equal(r.trash.startsWith('media/'), false, `trash must not be inside the endpoint: ${r.trash}`)
+    })
+
+    it('refuses a readOnly endpoint', async () => {
+        await writeFile(path.join(dir, 'locked/x.txt'), 'x')
+        const r = await call('mikser_drive_delete', { path: 'locked/x.txt' })
+        assert.equal(r.isError, true)
+        assert.match(r.content[0].text, /readOnly/)
+    })
+
+    it('dryRun removes nothing', async () => {
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'keep.txt', base64: b64('x') }] })
+        const r = body(await call('mikser_drive_delete', { path: 'media/keep.txt', dryRun: true }))
+        assert.equal(r.dryRun, true)
+        assert.ok(await stat(path.join(dir, 'media/keep.txt')))
+    })
+
+    it('always states what its reference check does NOT cover', async () => {
+        // An empty list means "nothing of the kind I look at", not "nothing".
+        await call('mikser_drive_add', { endpoint: 'media', files: [{ name: 'cov.txt', base64: b64('x') }] })
+        const r = body(await call('mikser_drive_delete', { path: 'media/cov.txt', dryRun: true }))
+        assert.match(r.coverage, /NOT body text/)
+    })
+})
+
+describe('move', () => {
+    const put = (name, text) => call('mikser_drive_add',
+        { endpoint: 'media', files: [{ name, base64: b64(text) }] })
+
+    it('moves a file that nothing references', async () => {
+        await put('loose.txt', 'x')
+        const r = body(await call('mikser_drive_move', { from: 'media/loose.txt', to: 'moved/loose.txt' }))
+        assert.equal(r.moved, true)
+        assert.ok(await stat(path.join(dir, 'media/moved/loose.txt')))
+        await assert.rejects(() => stat(path.join(dir, 'media/loose.txt')))
+    })
+
+    it('refuses to land on something that already exists', async () => {
+        await put('a.txt', 'a')
+        await put('b.txt', 'b')
+        const r = await call('mikser_drive_move', { from: 'media/a.txt', to: 'b.txt' })
+        assert.equal(r.isError, true)
+        assert.match(r.content[0].text, /already exists/)
+        // Neither file moved.
+        assert.equal(await readFile(path.join(dir, 'media/a.txt'), 'utf8'), 'a')
+        assert.equal(await readFile(path.join(dir, 'media/b.txt'), 'utf8'), 'b')
+    })
+
+    it('refuses a destination that would escape the endpoint', async () => {
+        await put('stay.txt', 'x')
+        const r = await call('mikser_drive_move', { from: 'media/stay.txt', to: '../../escaped.txt' })
+        assert.equal(r.isError, true)
+        assert.ok(await stat(path.join(dir, 'media/stay.txt')))
+    })
+
+    it('refuses a no-op move rather than pretending it did something', async () => {
+        await put('same.txt', 'x')
+        const r = await call('mikser_drive_move', { from: 'media/same.txt', to: 'same.txt' })
+        assert.equal(r.isError, true)
+        assert.match(r.content[0].text, /same path/)
+    })
+
+    it('states what its reference check does not cover', async () => {
+        await put('cover.txt', 'x')
+        const r = body(await call('mikser_drive_move',
+            { from: 'media/cover.txt', to: 'elsewhere.txt', dryRun: true }))
+        assert.equal(r.dryRun, true)
+        assert.match(r.coverage, /NOT body text/)
+        assert.ok(await stat(path.join(dir, 'media/cover.txt')), 'dryRun moves nothing')
+    })
+
+    it('refuses a readOnly endpoint', async () => {
+        await writeFile(path.join(dir, 'locked/ro.txt'), 'x')
+        const r = await call('mikser_drive_move', { from: 'locked/ro.txt', to: 'other.txt' })
+        assert.equal(r.isError, true)
+        assert.match(r.content[0].text, /readOnly/)
+    })
+})