mikser-io-auth 0.5.0

package/test/identity.test.js

@@ -0,0 +1,238 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import bcrypt from 'bcryptjs'
+
+import { parseHtpasswd, parseHtgroup, verifyPassword, createIdentityStore } from '../lib/htpasswd.js'
+
+describe('parseHtpasswd', () => {
+    it('reads user:hash, skipping comments and blank lines', () => {
+        const users = parseHtpasswd('# a comment\n\nalice:$2a$10$abc\nbob:{SHA}xyz\n')
+        assert.deepEqual([...users.keys()], ['alice', 'bob'])
+        assert.equal(users.get('alice'), '$2a$10$abc')
+    })
+
+    it('splits on the FIRST colon only, so a hash keeps any it contains', () => {
+        const users = parseHtpasswd('alice:$apr1$a:b$c\n')
+        assert.equal(users.get('alice'), '$apr1$a:b$c')
+    })
+
+    it('ignores malformed lines rather than throwing', () => {
+        const users = parseHtpasswd('nocolon\n:noname\nalice:hash\n')
+        assert.deepEqual([...users.keys()], ['alice'])
+    })
+})
+
+describe('parseHtgroup', () => {
+    it('reads "group: members", split on any whitespace', () => {
+        const groups = parseHtgroup('editors: alice   bob\nviewers: carol\n')
+        assert.deepEqual([...groups.get('editors')], ['alice', 'bob'])
+        assert.deepEqual([...groups.get('viewers')], ['carol'])
+    })
+
+    it('accumulates a group repeated across lines, as Apache does', () => {
+        const groups = parseHtgroup('editors: alice\neditors: bob\n')
+        assert.deepEqual([...groups.get('editors')], ['alice', 'bob'])
+    })
+
+    it('tolerates an empty group', () => {
+        const groups = parseHtgroup('empty:\n')
+        assert.deepEqual([...groups.get('empty')], [])
+    })
+})
+
+describe('verifyPassword', () => {
+    it('accepts bcrypt, including the $2y$ prefix htpasswd -B emits', () => {
+        const hash = bcrypt.hashSync('s3cret', 10)
+        assert.equal(verifyPassword(hash, 's3cret'), true)
+        assert.equal(verifyPassword(hash, 'wrong'), false)
+        assert.equal(verifyPassword(hash.replace(/^\$2[ab]\$/, '$2y$'), 's3cret'), true)
+    })
+
+    it('matches openssl for $apr1$, empty password included', () => {
+        // Generated with: openssl passwd -apr1 -salt Xy3Zq8Lm <password>
+        assert.equal(verifyPassword('$apr1$Xy3Zq8Lm$.f38Fzaj.hL2hlw7nUzyU0', 'secret'), true)
+        assert.equal(verifyPassword('$apr1$Xy3Zq8Lm$S/NLPnpu5C6dtylCJZrAE.', 'password'), true)
+        assert.equal(verifyPassword('$apr1$Xy3Zq8Lm$6AX7I0yPbQ0CvK/8r.ZfL0', ''), true)
+        assert.equal(verifyPassword('$apr1$Xy3Zq8Lm$QxwZvfxeHTo8vpjS3o5fy1', 'a-much-longer-passphrase-here'), true)
+        assert.equal(verifyPassword('$apr1$Xy3Zq8Lm$.f38Fzaj.hL2hlw7nUzyU0', 'secre'), false)
+    })
+
+    it('accepts {SHA}', () => {
+        assert.equal(verifyPassword('{SHA}/vNB+F2HQ559kaLUZbmHHvZrXpg=', 's3cret'), true)
+        assert.equal(verifyPassword('{SHA}/vNB+F2HQ559kaLUZbmHHvZrXpg=', 'nope'), false)
+    })
+
+    it('refuses DES-crypt and MD5-crypt rather than half-supporting them', () => {
+        assert.equal(verifyPassword('abJnggxhB/yWI', 's3cret'), false)
+        assert.equal(verifyPassword('$1$salt$dGVzdA', 's3cret'), false)
+    })
+
+    it('never throws on junk', () => {
+        assert.equal(verifyPassword(null, 'x'), false)
+        assert.equal(verifyPassword('', 'x'), false)
+        assert.equal(verifyPassword('$2a$notavalidhash', 'x'), false)
+        assert.equal(verifyPassword('$2a$10$abc', 12345), false)
+    })
+})
+
+describe('createIdentityStore', () => {
+    let dir, usersFile, groupsFile
+
+    before(async () => {
+        dir = await mkdtemp(path.join(tmpdir(), 'mikser-auth-'))
+        usersFile  = path.join(dir, 'users.htpasswd')
+        groupsFile = path.join(dir, 'groups.htgroup')
+        await writeFile(usersFile, [
+            `alice:${bcrypt.hashSync('alice-pw', 10)}`,
+            `bob:${bcrypt.hashSync('bob-pw', 10)}`,
+            `carol:${bcrypt.hashSync('carol-pw', 10)}`,
+        ].join('\n') + '\n')
+        await writeFile(groupsFile, 'editors: alice bob\nadmins: alice\n')
+    })
+
+    after(async () => { await rm(dir, { recursive: true, force: true }) })
+
+    const store = () => createIdentityStore({
+        usersFile, groupsFile,
+        groups: { editors: ['api:update', 'mcp:use'], admins: ['api:delete'] },
+    })
+
+    it('authenticates and unions capabilities across every group', async () => {
+        const p = await store().authenticate('alice', 'alice-pw')
+        assert.equal(p.subject, 'alice')
+        assert.deepEqual(p.groups.sort(), ['admins', 'editors'])
+        assert.deepEqual(p.capabilities.sort(), ['api:delete', 'api:update', 'mcp:use'])
+    })
+
+    it('gives a user only their own groups capabilities', async () => {
+        const p = await store().authenticate('bob', 'bob-pw')
+        assert.deepEqual(p.capabilities.sort(), ['api:update', 'mcp:use'])
+    })
+
+    it('authenticates a user in no group, with no capabilities', async () => {
+        const p = await store().authenticate('carol', 'carol-pw')
+        assert.equal(p.subject, 'carol')
+        assert.deepEqual(p.capabilities, [])
+    })
+
+    it('rejects a wrong password and an unknown user identically', async () => {
+        assert.equal(await store().authenticate('alice', 'nope'), null)
+        assert.equal(await store().authenticate('nobody', 'nope'), null)
+    })
+
+    it('ignores a group naming a user who does not exist', async () => {
+        const s = createIdentityStore({
+            usersFile, groupsFile,
+            groups: { ghosts: ['api:delete'] },
+        })
+        const p = await s.authenticate('alice', 'alice-pw')
+        assert.deepEqual(p.capabilities, [])
+    })
+
+    it('picks up an edit to the users file without a restart', async () => {
+        const s = store()
+        assert.equal(await s.authenticate('dave', 'dave-pw'), null)
+        await writeFile(usersFile, `dave:${bcrypt.hashSync('dave-pw', 10)}\n`, { flag: 'a' })
+        // mtime granularity can collapse two writes in the same millisecond.
+        await new Promise(r => setTimeout(r, 12))
+        await s.reload()
+        const p = await s.authenticate('dave', 'dave-pw')
+        assert.equal(p?.subject, 'dave')
+    })
+
+    it('refuses everyone when the users file is missing, without throwing', async () => {
+        const s = createIdentityStore({ usersFile: path.join(dir, 'nope.htpasswd') })
+        assert.equal(await s.authenticate('alice', 'alice-pw'), null)
+    })
+
+    it('works with no groups file at all, leaving the user unscoped', async () => {
+        // No capability map configured → null, "not capability-scoped",
+        // the same thing a bare static token reports. [] would mean "no
+        // verbs at all", which would refuse everything to everyone in the
+        // simplest possible setup.
+        const s = createIdentityStore({ usersFile })
+        const p = await s.authenticate('alice', 'alice-pw')
+        assert.equal(p.subject, 'alice')
+        assert.equal(p.capabilities, null)
+    })
+
+    it('still reports [] for an ungranted user once a capability map exists', async () => {
+        const s = createIdentityStore({ usersFile, groupsFile, groups: { nobody: ['api:list'] } })
+        const p = await s.authenticate('alice', 'alice-pw')
+        assert.deepEqual(p.capabilities, [])
+    })
+})
+
+describe('group → row scope (principal-bound scope)', () => {
+    let dir, usersFile, groupsFile
+
+    before(async () => {
+        dir = await mkdtemp(path.join(tmpdir(), 'mikser-auth-scope-'))
+        usersFile  = path.join(dir, 'users.htpasswd')
+        groupsFile = path.join(dir, 'groups.htgroup')
+        await writeFile(usersFile, ['alice', 'bob', 'carol', 'dan'].map(
+            u => `${u}:${bcrypt.hashSync(`${u}-pw`, 10)}`).join('\n') + '\n')
+        await writeFile(groupsFile, [
+            'web-editors: alice dan',
+            'franchise-editors: bob dan',
+            'staff: carol',            // a group with capabilities but no scope
+        ].join('\n') + '\n')
+    })
+
+    after(async () => { await rm(dir, { recursive: true, force: true }) })
+
+    const store = () => createIdentityStore({
+        usersFile, groupsFile,
+        groups: {
+            'web-editors':       ['api:list', 'api:update'],
+            'franchise-editors': ['api:list', 'api:update'],
+            'staff':             ['api:list'],
+        },
+        scopes: {
+            'web-editors':       { 'meta.href': { $regex: '^/web' } },
+            'franchise-editors': { 'meta.href': { $regex: '^/franchise' } },
+        },
+    })
+
+    it('gives a single-group user that group\'s filter verbatim', async () => {
+        const p = await store().authenticate('alice', 'alice-pw')
+        assert.deepEqual(p.scope, { 'meta.href': { $regex: '^/web' } })
+    })
+
+    it('unions across groups with $or — more groups means MORE reach, not less', async () => {
+        // Intersecting would make every extra group make a user less able,
+        // which is never what an operator means by adding one.
+        const p = await store().authenticate('dan', 'dan-pw')
+        assert.deepEqual(p.scope, {
+            $or: [
+                { 'meta.href': { $regex: '^/web' } },
+                { 'meta.href': { $regex: '^/franchise' } },
+            ],
+        })
+    })
+
+    it('leaves a user in no scoped group unscoped — the endpoint is their only limit', async () => {
+        const p = await store().authenticate('carol', 'carol-pw')
+        assert.equal(p.scope, null)
+        assert.deepEqual(p.capabilities, ['api:list'])
+    })
+
+    it('is null when no scopes are configured at all', async () => {
+        const s = createIdentityStore({ usersFile, groupsFile, groups: { 'web-editors': ['api:list'] } })
+        assert.equal((await s.authenticate('alice', 'alice-pw')).scope, null)
+    })
+
+    it('picks up a group-membership edit without a restart', async () => {
+        const s = store()
+        assert.equal((await s.authenticate('carol', 'carol-pw')).scope, null)
+        await writeFile(groupsFile, 'web-editors: carol\n', { flag: 'a' })
+        await new Promise(r => setTimeout(r, 12))
+        await s.reload()
+        assert.deepEqual((await s.authenticate('carol', 'carol-pw')).scope,
+                         { 'meta.href': { $regex: '^/web' } })
+    })
+})

package/test/seam.test.js

@@ -0,0 +1,164 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import bcrypt from 'bcryptjs'
+
+// The point of this file: prove these verifiers satisfy the engine's
+// contract (ADR-0012) by driving them through the engine's own authorize(),
+// rather than asserting against a local re-implementation of the rule.
+import { authorize, resolveAuth } from 'mikser-io'
+
+import { createIdentityStore } from '../lib/htpasswd.js'
+import { loadOrCreateKey } from '../lib/keys.js'
+import { issueToken, createTokenVerifier } from '../lib/tokens.js'
+import { basic, jwt } from '../lib/verifiers.js'
+
+const ISSUER = 'https://cms.example.com'
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64')
+const req = (header, ip = '203.0.113.9') => ({ headers: header ? { authorization: header } : {}, ip })
+
+let dir, store, key
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-auth-s-'))
+    const usersFile  = path.join(dir, 'users.htpasswd')
+    const groupsFile = path.join(dir, 'groups.htgroup')
+    await writeFile(usersFile, `alice:${bcrypt.hashSync('alice-pw', 10)}\n`)
+    await writeFile(groupsFile, 'editors: alice\n')
+    store = createIdentityStore({ usersFile, groupsFile, groups: { editors: ['api:update'] } })
+    key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+})
+
+after(async () => { await rm(dir, { recursive: true, force: true }) })
+
+describe('verifiers satisfy the engine seam', () => {
+    it('resolveAuth passes a verifier through untouched', () => {
+        const v = basic({ store })
+        assert.equal(resolveAuth(v), v)
+    })
+
+    it('basic: valid credentials authorize from anywhere', async () => {
+        const out = await authorize(req(`Basic ${b64('alice:alice-pw')}`), basic({ store }))
+        assert.equal(out.ok, true)
+        assert.deepEqual(out.principal.capabilities, ['api:update'])
+    })
+
+    it('basic: a wrong password is 401 even from loopback with trustLoopback on', async () => {
+        const out = await authorize(
+            req(`Basic ${b64('alice:nope')}`, '127.0.0.1'),
+            basic({ store }),
+            { trustLoopback: true },
+        )
+        assert.equal(out.ok, false)
+        assert.equal(out.status, 401)
+        assert.equal(out.reason, 'invalid')
+    })
+
+    it('basic: no credential is "missing", which loopback policy may still rescue', async () => {
+        const v = basic({ store })
+        assert.equal((await authorize(req(null, '127.0.0.1'), v)).reason, 'missing')
+        assert.equal((await authorize(req(null, '127.0.0.1'), v, { trustLoopback: true })).ok, true)
+    })
+
+    it('jwt: a token minted from the files authorizes, carrying its scope', async () => {
+        const principal = await store.authenticate('alice', 'alice-pw')
+        const token = await issueToken({
+            key, issuer: ISSUER, audience: ISSUER,
+            subject: principal.subject, capabilities: principal.capabilities,
+        })
+        const v = jwt({ verifyToken: createTokenVerifier({ key, issuer: ISSUER, audience: ISSUER }), issuer: ISSUER })
+        const out = await authorize(req(`Bearer ${token}`), v)
+        assert.equal(out.ok, true)
+        assert.equal(out.principal.subject, 'alice')
+        assert.deepEqual(out.principal.capabilities, ['api:update'])
+    })
+
+    it('jwt: an OAuth-gated surface gets no loopback bypass by default', async () => {
+        const v = jwt({ verifyToken: createTokenVerifier({ key, issuer: ISSUER, audience: ISSUER }), issuer: ISSUER })
+        const out = await authorize(req(null, '127.0.0.1'), v)
+        assert.equal(out.ok, false)
+        assert.equal(out.status, 401)
+    })
+
+    it('scope is never taken from the client — it comes from the files', async () => {
+        // A user whose group grants api:update cannot obtain api:delete by
+        // asking for it; the only input to the token's scope is the store.
+        const principal = await store.authenticate('alice', 'alice-pw')
+        assert.deepEqual(principal.capabilities, ['api:update'])
+        const token = await issueToken({
+            key, issuer: ISSUER, audience: ISSUER,
+            subject: principal.subject, capabilities: principal.capabilities,
+        })
+        const v = jwt({
+            verifyToken: createTokenVerifier({ key, issuer: ISSUER, audience: ISSUER }),
+            issuer: ISSUER,
+            requiredCapability: 'api:delete',
+        })
+        assert.equal((await authorize(req(`Bearer ${token}`), v)).ok, false)
+    })
+})
+
+describe('the plugin is itself a verifier — one line at the call site', () => {
+    // The config burden this removes: every gated endpoint used to have to
+    // pick .basic() or .jwt() when the honest answer is "whichever the
+    // caller has".
+    it('resolveAuth takes it unchanged, despite being a function', async () => {
+        const { auth } = await import('../index.js')
+        const identity = auth({})
+        assert.equal(typeof identity, 'function', 'still the plugin')
+        assert.equal(resolveAuth(identity), identity, 'and also the verifier')
+    })
+
+    it('reports "nothing presented" with no credential, so loopback policy still applies', async () => {
+        const { auth } = await import('../index.js')
+        assert.equal(await auth({}).verify(req(null)), null)
+    })
+
+    it('routes each scheme to the verifier that owns it', async () => {
+        // Basic and Bearer never collide: each verifier reports "not mine"
+        // for the other's scheme, so the composite reaches the right one
+        // rather than the first one.
+        const { basic, jwt } = await import('../lib/verifiers.js')
+        const composite = (await import('mikser-io')).anyOf(
+            basic({ store }),
+            jwt({ verifyToken: createTokenVerifier({ key, issuer: ISSUER, audience: ISSUER }), issuer: ISSUER }),
+        )
+        const viaBasic = await composite.verify(req(`Basic ${b64('alice:alice-pw')}`))
+        assert.equal(viaBasic.subject, 'alice')
+
+        const token = await issueToken({
+            key, issuer: ISSUER, audience: ISSUER, subject: 'alice', capabilities: ['api:update'],
+        })
+        const viaBearer = await composite.verify(req(`Bearer ${token}`))
+        assert.equal(viaBearer.subject, 'alice')
+        assert.deepEqual(viaBearer.capabilities, ['api:update'])
+    })
+})
+
+describe('the simplest possible setup', () => {
+    it('with no capability map, an authenticated user behaves like a static token', async () => {
+        // capabilities: null means "not capability-scoped" — the endpoint's
+        // own `operations` list is the only limit, exactly as for a bare
+        // token. Returning [] here would authenticate people and then refuse
+        // them everything, making the capability map effectively mandatory.
+        const { hasCapability } = await import('mikser-io')
+        const bare = createIdentityStore({ usersFile: path.join(dir, 'users.htpasswd') })
+        const p = await bare.authenticate('alice', 'alice-pw')
+        assert.equal(p.capabilities, null)
+        assert.equal(hasCapability(p, 'api:delete'), true)
+    })
+
+    it('once a capability map exists, an ungranted user is refused rather than unscoped', async () => {
+        const { hasCapability } = await import('mikser-io')
+        const scoped = createIdentityStore({
+            usersFile:  path.join(dir, 'users.htpasswd'),
+            groupsFile: path.join(dir, 'groups.htgroup'),
+            groups:     { someone_else: ['api:delete'] },
+        })
+        const p = await scoped.authenticate('alice', 'alice-pw')
+        assert.deepEqual(p.capabilities, [])
+        assert.equal(hasCapability(p, 'api:delete'), false)
+    })
+})

package/test/verifiers.test.js

@@ -0,0 +1,202 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm, readFile, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import bcrypt from 'bcryptjs'
+
+import { createIdentityStore } from '../lib/htpasswd.js'
+import { loadOrCreateKey, jwks } from '../lib/keys.js'
+import { issueToken, createTokenVerifier } from '../lib/tokens.js'
+import { basic, jwt } from '../lib/verifiers.js'
+
+const req = (header) => ({ headers: header ? { authorization: header } : {} })
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64')
+
+let dir, store, key
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-auth-v-'))
+    const usersFile  = path.join(dir, 'users.htpasswd')
+    const groupsFile = path.join(dir, 'groups.htgroup')
+    await writeFile(usersFile, `alice:${bcrypt.hashSync('alice-pw', 10)}\n`)
+    await writeFile(groupsFile, 'editors: alice\n')
+    store = createIdentityStore({ usersFile, groupsFile, groups: { editors: ['api:update', 'mcp:use'] } })
+    key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+})
+
+after(async () => { await rm(dir, { recursive: true, force: true }) })
+
+describe('basic verifier', () => {
+    it('accepts valid credentials and carries the capabilities through', async () => {
+        const p = await basic({ store }).verify(req(`Basic ${b64('alice:alice-pw')}`))
+        assert.equal(p.subject, 'alice')
+        assert.deepEqual(p.capabilities.sort(), ['api:update', 'mcp:use'])
+    })
+
+    it('returns null when nothing is presented, so loopback policy can still apply', async () => {
+        assert.equal(await basic({ store }).verify(req(null)), null)
+    })
+
+    it('rejects a wrong password', async () => {
+        assert.equal(await basic({ store }).verify(req(`Basic ${b64('alice:nope')}`)), false)
+    })
+
+    it('treats a Bearer on a Basic endpoint as rejected, not as absent', async () => {
+        // If this returned null it would fall through to a loopback bypass —
+        // a presented-but-unusable credential must never do that.
+        assert.equal(await basic({ store }).verify(req('Bearer something')), false)
+    })
+
+    it('survives malformed base64 and a missing colon', async () => {
+        assert.equal(await basic({ store }).verify(req('Basic !!!not-base64!!!')), false)
+        assert.equal(await basic({ store }).verify(req(`Basic ${b64('nocolon')}`)), false)
+    })
+
+    it('handles a password containing a colon', async () => {
+        const usersFile = path.join(dir, 'colon.htpasswd')
+        await writeFile(usersFile, `dave:${bcrypt.hashSync('pa:ss:word', 10)}\n`)
+        const s = createIdentityStore({ usersFile })
+        assert.equal((await basic({ store: s }).verify(req(`Basic ${b64('dave:pa:ss:word')}`))).subject, 'dave')
+    })
+
+    it('challenges with a realm and UTF-8 charset', () => {
+        const res = { headers: {}, set(k, v) { this.headers[k] = v } }
+        basic({ store, realm: 'cms' }).challenge({}, res)
+        assert.equal(res.headers['WWW-Authenticate'], 'Basic realm="cms", charset="UTF-8"')
+    })
+})
+
+describe('key file', () => {
+    it('is stable across loads — a restart must not invalidate live tokens', async () => {
+        const keyFile = path.join(dir, 'stable.key')
+        const a = await loadOrCreateKey({ keyFile })
+        const b = await loadOrCreateKey({ keyFile })
+        assert.equal(a.kid, b.kid)
+        assert.deepEqual(a.publicJwk, b.publicJwk)
+    })
+
+    it('is written 0600 — it is a signing key sitting in a content folder', async () => {
+        const keyFile = path.join(dir, 'perms.key')
+        await loadOrCreateKey({ keyFile })
+        assert.equal((await stat(keyFile)).mode & 0o777, 0o600)
+    })
+
+    it('fails loudly on a corrupt key file rather than silently rotating', async () => {
+        const keyFile = path.join(dir, 'corrupt.key')
+        await writeFile(keyFile, 'not json at all')
+        await assert.rejects(() => loadOrCreateKey({ keyFile }), /unreadable or not JSON/)
+    })
+
+    it('publishes only the public half', async () => {
+        const doc = jwks({ publicJwk: key.publicJwk })
+        assert.equal(doc.keys.length, 1)
+        assert.equal(doc.keys[0].d, undefined)
+        assert.ok(doc.keys[0].kid)
+    })
+
+    it('refuses to publish a JWKS carrying a private component', async () => {
+        const stored = JSON.parse(await readFile(path.join(dir, 'auth.key'), 'utf8'))
+        assert.throws(() => jwks({ publicJwk: stored.privateJwk }), /private component/)
+    })
+})
+
+describe('jwt verifier', () => {
+    const issuer = 'https://cms.example.com'
+    const mint = (over = {}) => issueToken({
+        key, issuer, audience: issuer, subject: 'alice',
+        capabilities: ['api:update', 'mcp:use'], ...over,
+    })
+    const verifier = (over = {}) => jwt({
+        verifyToken: createTokenVerifier({ key, issuer, audience: issuer }),
+        issuer, ...over,
+    })
+
+    it('round-trips a token and recovers subject + capabilities', async () => {
+        const p = await verifier().verify(req(`Bearer ${await mint()}`))
+        assert.equal(p.subject, 'alice')
+        assert.deepEqual(p.capabilities, ['api:update', 'mcp:use'])
+    })
+
+    it('returns null with no header, false for a non-Bearer scheme', async () => {
+        assert.equal(await verifier().verify(req(null)), null)
+        assert.equal(await verifier().verify(req(`Basic ${b64('alice:alice-pw')}`)), false)
+    })
+
+    it('rejects garbage and an expired token as false, never as a throw', async () => {
+        assert.equal(await verifier().verify(req('Bearer not.a.jwt')), false)
+        const expired = await mint({ ttl: '-1s' })
+        assert.equal(await verifier().verify(req(`Bearer ${expired}`)), false)
+    })
+
+    it('rejects a token minted for a different audience', async () => {
+        const other = await mint({ audience: 'https://elsewhere.example.com' })
+        assert.equal(await verifier().verify(req(`Bearer ${other}`)), false)
+    })
+
+    it('rejects a token signed by a different key', async () => {
+        const foreign = await loadOrCreateKey({ keyFile: path.join(dir, 'foreign.key') })
+        const token = await issueToken({ key: foreign, issuer, audience: issuer, subject: 'mallory' })
+        assert.equal(await verifier().verify(req(`Bearer ${token}`)), false)
+    })
+
+    it('enforces requiredCapability', async () => {
+        const v = verifier({ requiredCapability: 'api:delete' })
+        assert.equal(await v.verify(req(`Bearer ${await mint()}`)), false)
+        const ok = await mint({ capabilities: ['api:delete'] })
+        assert.equal((await v.verify(req(`Bearer ${ok}`))).subject, 'alice')
+    })
+
+    it('advertises the issuer for RFC 9728 discovery', () => {
+        const v = verifier({ scopes: ['mcp:use'] })
+        assert.deepEqual(v.authorizationServers, [issuer])
+        assert.deepEqual(v.scopesSupported, ['mcp:use'])
+    })
+})
+
+describe('row scope survives the JWT round trip', () => {
+    const issuer = 'https://cms.example.com'
+    const ROWS = { 'meta.href': { $regex: '^/web' } }
+
+    it('travels as a private claim, not as OAuth `scope`', async () => {
+        const token = await issueToken({
+            key, issuer, audience: issuer, subject: 'alice',
+            capabilities: ['api:list'], scope: ROWS,
+        })
+        const [, payload] = token.split('.')
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString())
+        // OAuth's `scope` is the capability list — a client library parses it
+        // as one, so the row filter must not be in there.
+        assert.equal(claims.scope, 'api:list')
+        assert.deepEqual(claims.mks_scope, ROWS)
+    })
+
+    it('is recovered by the verifier and reaches the principal', async () => {
+        const token = await issueToken({
+            key, issuer, audience: issuer, subject: 'alice',
+            capabilities: ['api:list'], scope: ROWS,
+        })
+        const v = jwt({ verifyToken: createTokenVerifier({ key, issuer, audience: issuer }), issuer })
+        const p = await v.verify(req(`Bearer ${token}`))
+        assert.deepEqual(p.scope, ROWS)
+    })
+
+    it('is null when the user has none', async () => {
+        const token = await issueToken({ key, issuer, audience: issuer, subject: 'carol', capabilities: [] })
+        const v = jwt({ verifyToken: createTokenVerifier({ key, issuer, audience: issuer }), issuer })
+        assert.equal((await v.verify(req(`Bearer ${token}`))).scope, null)
+    })
+
+    it('cannot be widened by a client — the token is signed', async () => {
+        const token = await issueToken({
+            key, issuer, audience: issuer, subject: 'alice',
+            capabilities: ['api:list'], scope: ROWS,
+        })
+        const [head, payload, sig] = token.split('.')
+        const tampered = JSON.parse(Buffer.from(payload, 'base64url').toString())
+        tampered.mks_scope = {}                      // "show me everything"
+        const forged = [head, Buffer.from(JSON.stringify(tampered)).toString('base64url'), sig].join('.')
+        const v = jwt({ verifyToken: createTokenVerifier({ key, issuer, audience: issuer }), issuer })
+        assert.equal(await v.verify(req(`Bearer ${forged}`)), false)
+    })
+})