mikser-io-auth 0.7.0 → 0.8.0

package/README.md

@@ -227,6 +227,44 @@ keeps them: a registered client and its refresh token exist only because a
 human completed a sign-in once, and they are not something the working folder
 can rebuild.
 
+### Minted tokens
+
+`auth()` publishes a minting surface at `runtime.options.auth`, so another
+plugin can hand out a credential **narrower than the caller's own** without
+importing this package:
+
+```js
+runtime.options.auth.mint({
+    subject:      principal.subject,
+    capabilities: principal.capabilities,   // what they already hold
+    request:      ['webdav:media', 'webdav:media:write'],
+    ttlSec:       300,
+    purpose:      'webdav:media (write)',
+})
+```
+
+The scopes are the **intersection** of `request` and `capabilities`. This can
+only ever narrow: there is no argument that widens anyone's reach, and asking
+for a scope the caller does not hold is refused with the missing one named
+rather than trimmed silently. A caller whose `capabilities` are `null` — a
+static token, not capability-scoped — is refused outright, because it cannot
+delegate what it cannot enumerate.
+
+A minted token carries a **`jti`** and is recorded in `mikser_auth_minted`, which
+makes it revokable before it expires — the one thing an ordinary JWT is not, and
+the thing that matters for a credential handed to a machine that logs its own
+output. `revokeMinted(jti)` kills one; `listMinted(subject)` is the audit view.
+Every mint is logged with subject, purpose, scopes and ttl.
+
+Verification **fails closed**: a token with a `jti` whose row is missing, or
+whose checker was never wired, is rejected. Losing the record must revoke, never
+un-revoke. Session tokens carry no `jti`, so they never touch this table and
+gain no new failure mode.
+
+Minted tokens are **not refreshable**. Expiry is the revocation mechanism, so
+they are deliberately short and a caller mints again rather than renewing one
+that has been sitting in a transcript.
+
 ### When an access token expires
 
 Access tokens are short (`ttl`, default `1h`) and refresh tokens are long, so

package/index.js

@@ -81,7 +81,20 @@ export function auth(options = {}) {
         reload:          ()     => ready().store.reload(),
     }
 
+    // Captured on first invocation so the surfaces defined below — which are
+    // built at config time, before any hook runs — can reach the engine.
+    let engine = null
+
     const plugin = ({ runtime, onLoad, onLoaded, useLogger }) => {
+        engine = runtime
+        // Published here rather than after the factory, because `runtime` is
+        // only in scope once the plugin has been invoked. mikser-io-webdav
+        // mints through this without importing this package.
+        runtime.options.auth = {
+            mint:         (...args) => plugin.mint(...args),
+            revokeMinted: (jti) => plugin.revokeMinted(jti),
+            listMinted:   (subject) => plugin.listMinted(subject),
+        }
         onLoad(async () => {
             const logger = useLogger()
             const workingFolder = runtime.options.workingFolder
@@ -103,6 +116,10 @@ export function auth(options = {}) {
                     key: signingKey,
                     issuer:   issuer ?? runtime.options.url,
                     audience: audience ?? runtime.options.url,
+                    // Minted tokens are revokable; session tokens carry no jti
+                    // and never reach this, so it costs a lookup only for the
+                    // credentials that need one.
+                    mintedTokenUsable: grants.mintedTokenUsable,
                 }),
                 logger,
             }
@@ -233,6 +250,57 @@ export function auth(options = {}) {
 
     plugin.store = lazyStore
 
+    // Mint a token narrower than the caller's own, for one job.
+    //
+    // Everything about this is deliberately small. The scopes are whatever the
+    // caller asks for INTERSECTED with what they already hold — this can never
+    // widen anyone's reach, only narrow it, which is the property that makes it
+    // safe to expose to an agent at all. It is short-lived, it is revokable by
+    // jti, and it is not refreshable: expiry IS the revocation mechanism, so a
+    // caller whose transfer outlives it mints another rather than renewing one
+    // that has been sitting in a transcript.
+    //
+    // Returns `{ token, jti, scopes, expiresAt, ttl }`, or throws with the
+    // missing scope named when the caller is asking for more than it holds.
+    plugin.mint = async ({ subject, capabilities: held, request, ttlSec, purpose, audience: aud }) => {
+        const { key } = ready()
+        const wanted = [...new Set(request ?? [])]
+        if (!wanted.length) throw new Error('mint: no scopes requested')
+        // `capabilities: null` means "not capability-scoped" — a static token.
+        // Such a caller cannot delegate what it cannot enumerate, so refuse
+        // rather than mint something unbounded.
+        if (!Array.isArray(held)) {
+            throw new Error('mint: the caller holds no enumerable capabilities, so nothing can be delegated from them')
+        }
+        const missing = wanted.filter(scope => !held.includes(scope))
+        if (missing.length) {
+            const err = new Error(`mint refused: you do not hold ${missing.join(', ')}`)
+            err.missing = missing
+            throw err
+        }
+        const jti = opaqueToken()
+        const token = await issueToken({
+            key,
+            issuer:   issuer ?? engine?.options?.url,
+            audience: aud ?? audience ?? engine?.options?.url,
+            subject,
+            capabilities: wanted,
+            ttl: `${ttlSec}s`,
+            jti,
+        })
+        const { expiresAt } = grants.recordMintedToken({ jti, subject, purpose, scopes: wanted, ttlSec })
+        // Every mint is logged: who, what for, how wide, how long. A
+        // credential handed to a machine that no one can account for later is
+        // the thing that makes short expiry necessary in the first place.
+        engine?.engine?.logger?.info?.('auth: minted %ds token for %j — %s [%s]',
+            ttlSec, subject, purpose ?? 'unspecified', wanted.join(' '))
+        return { token, jti, scopes: wanted, ttl: ttlSec, expiresAt: new Date(expiresAt).toISOString() }
+    }
+
+    plugin.revokeMinted = (jti) => grants.revokeMintedToken(jti)
+    plugin.listMinted   = (subject) => grants.listMintedTokens(subject)
+
+
     // The plugin IS a verifier, accepting either credential:
     //
     //     api({ endpoints: { admin: { auth: identity } } })

package/lib/grants.js

@@ -38,6 +38,27 @@ registerSchema('auth', `
     CREATE INDEX IF NOT EXISTS idx_mikser_auth_refresh_subject
         ON mikser_auth_refresh (subject);
 
+    -- Short-lived tokens minted for one narrow job — a WebDAV upload, say —
+    -- rather than for a session. A JWT is normally unrevokable before its
+    -- expiry, which is exactly the property you do not want in a credential
+    -- handed to something that logs its own output. So a minted token carries
+    -- a jti and is only usable while its row here says so.
+    --
+    -- The verifier FAILS CLOSED on a missing row: no row, not usable. That
+    -- makes this table load-bearing for validity rather than merely advisory,
+    -- which is the safe direction — losing it revokes, it never un-revokes.
+    CREATE TABLE IF NOT EXISTS mikser_auth_minted (
+        jti        TEXT PRIMARY KEY,
+        subject    TEXT NOT NULL,
+        purpose    TEXT,
+        scopes     TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        revoked_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_mikser_auth_minted_subject
+        ON mikser_auth_minted (subject);
+
     -- Self-registered clients (RFC 7591). Config-declared clients are NOT
     -- here: they live in config, are not prunable, and always win a lookup.
     -- Keeping the two apart is what makes pruning safe — an operator's
@@ -129,7 +150,51 @@ export function sweepExpired() {
     const now = Date.now()
     const codes = db().prepare('DELETE FROM mikser_auth_codes WHERE expires_at < ?').run(now - 60_000).changes
     const refresh = db().prepare('DELETE FROM mikser_auth_refresh WHERE expires_at < ?').run(now).changes
-    return { codes, refresh }
+    // A minted row past its expiry can no longer authorise anything — the JWT
+    // has expired on its own — so keeping it buys nothing. Swept a minute late
+    // so a token expiring mid-request is rejected by the clock rather than by
+    // a missing row, which reads as revoked and is a different answer.
+    const minted = db().prepare('DELETE FROM mikser_auth_minted WHERE expires_at < ?').run(now - 60_000).changes
+    return { codes, refresh, minted }
+}
+
+// ── minted tokens ───────────────────────────────────────────────────────
+
+export function recordMintedToken({ jti, subject, purpose, scopes, ttlSec }) {
+    const now = Date.now()
+    db().prepare(`
+        INSERT INTO mikser_auth_minted (jti, subject, purpose, scopes, created_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+    `).run(jti, subject, purpose ?? null, scopes.join(' '), now, now + ttlSec * 1000)
+    return { jti, expiresAt: now + ttlSec * 1000 }
+}
+
+// Is this jti still usable? Missing means NO — see the schema comment.
+export function mintedTokenUsable(jti) {
+    const row = db().prepare('SELECT revoked_at, expires_at FROM mikser_auth_minted WHERE jti = ?').get(jti)
+    if (!row) return false
+    if (row.revoked_at) return false
+    return row.expires_at > Date.now()
+}
+
+export function revokeMintedToken(jti) {
+    return db()
+        .prepare('UPDATE mikser_auth_minted SET revoked_at = ? WHERE jti = ? AND revoked_at IS NULL')
+        .run(Date.now(), jti).changes > 0
+}
+
+export function listMintedTokens(subject) {
+    const rows = subject
+        ? db().prepare('SELECT * FROM mikser_auth_minted WHERE subject = ? ORDER BY created_at DESC').all(subject)
+        : db().prepare('SELECT * FROM mikser_auth_minted ORDER BY created_at DESC').all()
+    return rows.map(r => ({
+        jti: r.jti, subject: r.subject, purpose: r.purpose,
+        scopes: r.scopes.split(' '),
+        createdAt: new Date(r.created_at).toISOString(),
+        expiresAt: new Date(r.expires_at).toISOString(),
+        revokedAt: r.revoked_at ? new Date(r.revoked_at).toISOString() : null,
+        usable: !r.revoked_at && r.expires_at > Date.now(),
+    }))
 }
 
 // ── self-registered clients ─────────────────────────────────────────────

package/lib/tokens.js

@@ -8,12 +8,12 @@ import { ALG } from './keys.js'
 // asked for at /authorize. Enforcement downstream is scope-only with no
 // per-request re-read, which is safe precisely because a client cannot
 // influence what goes in.
-export async function issueToken({ key, issuer, audience, subject, capabilities = [], scope = null, ttl = '1h' }) {
+export async function issueToken({ key, issuer, audience, subject, capabilities = [], scope = null, ttl = '1h', jti = null }) {
     // `scope` is already taken: in OAuth it is the space-separated capability
     // list, and a client library will parse it as one. The row filter travels
     // as a private claim so the two never collide. It is signed, so a client
     // cannot widen its own reach by editing it.
-    return new SignJWT({
+    const signer = new SignJWT({
         scope: capabilities.join(' '),
         ...(scope ? { mks_scope: scope } : {}),
     })
@@ -23,12 +23,17 @@ export async function issueToken({ key, issuer, audience, subject, capabilities
         .setAudience(audience)
         .setSubject(subject)
         .setExpirationTime(ttl)
-        .sign(key.privateKey)
+    // A jti makes the token REVOKABLE. A session token has none and is
+    // unrevokable before expiry, which is fine for an hour a human owns; a
+    // token minted for a machine and returned in output that gets logged needs
+    // to be killable before its clock runs out.
+    if (jti) signer.setJti(jti)
+    return signer.sign(key.privateKey)
 }
 
 // Verify a token minted by this server. `audience` is checked because a
 // token issued for one endpoint must not be replayable against another.
-export function createTokenVerifier({ key, issuer, audience }) {
+export function createTokenVerifier({ key, issuer, audience, mintedTokenUsable }) {
     const keySet = createLocalJWKSet({ keys: [key.publicJwk] })
     return async function verifyToken(token) {
         const { payload } = await jwtVerify(token, keySet, {
@@ -36,6 +41,17 @@ export function createTokenVerifier({ key, issuer, audience }) {
             audience,
             algorithms: [ALG],
         })
+        // A token carrying a jti was minted for one narrow job and is only
+        // usable while the server still says so. FAIL CLOSED: no checker
+        // wired, or no row, means not usable — losing the record must revoke,
+        // never un-revoke.
+        if (payload.jti) {
+            if (typeof mintedTokenUsable !== 'function' || !mintedTokenUsable(payload.jti)) {
+                const err = new Error('This token has been revoked or is no longer on record')
+                err.code = 'ERR_JWT_REVOKED'
+                throw err
+            }
+        }
         return {
             subject:      payload.sub,
             capabilities: payload.scope ? payload.scope.split(' ') : [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Authentication for mikser-io: an OAuth 2.1 authorization server (self-registering clients, authorization code + PKCE, refresh rotation) and HTTP Basic / JWT verifiers over Apache-format htpasswd and htgroup files in the working folder. Implements the ADR-0012 verifier contract, so it plugs in wherever a static token does — api, mcp, forms.",
   "main": "index.js",
   "type": "module",

package/test/authorize.test.js

@@ -683,3 +683,127 @@ describe('unattended renewal is granted out loud, not just made possible', () =>
         assert.ok(second.scope.split(' ').includes('offline_access'))
     })
 })
+
+// A token narrower than the caller's own, for one job.
+//
+// The property that makes this safe to expose to an agent at all: it can only
+// ever NARROW. There is no argument that widens anyone's reach, and asking for
+// more than you hold is refused rather than trimmed silently.
+describe('minted tokens', () => {
+    let identity
+    before(async () => {
+        // The plugin object is the verifier and carries the minting surface.
+        identity = runtime.options.auth
+        assert.ok(identity?.mint, 'the auth plugin must publish a minting surface')
+    })
+
+    const claimsOf = (token) =>
+        JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString())
+
+    it('mints only what the caller already holds', async () => {
+        const m = await identity.mint({
+            subject: 'alice', capabilities: ['api:list', 'api:update'],
+            request: ['api:list'], ttlSec: 60, purpose: 'test',
+        })
+        assert.deepEqual(claimsOf(m.token).scope.split(' '), ['api:list'])
+        assert.ok(m.jti, 'a minted token must carry a jti, or it cannot be revoked')
+    })
+
+    it('refuses to mint a scope the caller lacks, and names it', async () => {
+        await assert.rejects(
+            () => identity.mint({
+                subject: 'alice', capabilities: ['api:list'],
+                request: ['api:list', 'api:delete'], ttlSec: 60,
+            }),
+            (err) => {
+                assert.match(err.message, /api:delete/)
+                assert.deepEqual(err.missing, ['api:delete'])
+                return true
+            })
+    })
+
+    it('refuses a caller whose capabilities are not enumerable', async () => {
+        // `capabilities: null` is a static token — not capability-scoped. It
+        // cannot delegate what it cannot enumerate, and minting something
+        // unbounded from it would be the opposite of the point.
+        await assert.rejects(
+            () => identity.mint({ subject: 'x', capabilities: null, request: ['api:list'], ttlSec: 60 }),
+            /no enumerable capabilities/)
+    })
+
+    it('works against a real gated resource, and STOPS the moment it is revoked', async () => {
+        // Through the actual gate, not through the verifier in isolation: what
+        // matters is whether a request carrying it gets in.
+        const m = await identity.mint({
+            subject: 'alice', capabilities: ['api:list'], request: ['api:list'], ttlSec: 300,
+        })
+        const hit = () => fetch(url('/resource'), { headers: { authorization: `Bearer ${m.token}` } })
+
+        assert.equal((await hit()).status, 200, 'a fresh minted token must be accepted')
+
+        // A JWT is normally unrevokable before expiry, which is exactly the
+        // property you do not want in a credential handed to something that
+        // logs its own output.
+        assert.equal(identity.revokeMinted(m.jti), true)
+        assert.equal((await hit()).status, 401, 'revocation must take effect immediately')
+        assert.equal(identity.revokeMinted(m.jti), false, 'revoking twice reports nothing changed')
+    })
+
+    it('FAILS CLOSED when the record is gone', async () => {
+        // Losing the table must revoke, never un-revoke. If a missing row read
+        // as "fine", wiping the cache would silently un-revoke every token
+        // anyone had killed.
+        const { createTokenVerifier } = await import('../lib/tokens.js')
+        const { loadOrCreateKey } = await import('../lib/keys.js')
+        const { issueToken } = await import('../lib/tokens.js')
+        const key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+        const orphan = await issueToken({
+            key, issuer: runtime.options.url, audience: runtime.options.url,
+            subject: 'alice', capabilities: ['api:list'], ttl: '300s', jti: 'never-recorded',
+        })
+        const verify = createTokenVerifier({
+            key, issuer: runtime.options.url, audience: runtime.options.url,
+            mintedTokenUsable: () => false,
+        })
+        await assert.rejects(() => verify(orphan), /revoked or is no longer on record/)
+    })
+
+    it('fails closed when no checker is wired at all', async () => {
+        const { createTokenVerifier, issueToken } = await import('../lib/tokens.js')
+        const { loadOrCreateKey } = await import('../lib/keys.js')
+        const key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+        const token = await issueToken({
+            key, issuer: runtime.options.url, audience: runtime.options.url,
+            subject: 'alice', capabilities: ['api:list'], ttl: '300s', jti: 'anything',
+        })
+        // No mintedTokenUsable passed — a deployment that forgot to wire it
+        // must not accept revokable tokens as if they were unrevokable.
+        const verify = createTokenVerifier({ key, issuer: runtime.options.url, audience: runtime.options.url })
+        await assert.rejects(() => verify(token), /revoked or is no longer on record/)
+    })
+
+    it('leaves a SESSION token alone — no jti, no lookup, no new failure mode', async () => {
+        // Adding revocation must not make ordinary sign-in depend on a table.
+        const { verifier, challenge } = pkcePair()
+        const res = await signIn(challenge, { username: 'alice', password: 'alice-pw' })
+        const code = new URL(res.headers.get('location')).searchParams.get('code')
+        const { access_token } = await (await token({
+            grant_type: 'authorization_code', code, redirect_uri: REDIRECT,
+            client_id: CLIENT, code_verifier: verifier,
+        })).json()
+        assert.equal(claimsOf(access_token).jti, undefined, 'a session token carries no jti')
+        const res2 = await fetch(url('/resource'), { headers: { authorization: `Bearer ${access_token}` } })
+        assert.equal(res2.status, 200)
+    })
+
+    it('lists what has been minted, for an operator to audit or revoke', async () => {
+        const m = await identity.mint({
+            subject: 'carol', capabilities: ['api:list'], request: ['api:list'],
+            ttlSec: 60, purpose: 'audit-probe',
+        })
+        const listed = identity.listMinted('carol').find(x => x.jti === m.jti)
+        assert.equal(listed.purpose, 'audit-probe')
+        assert.deepEqual(listed.scopes, ['api:list'])
+        assert.equal(listed.usable, true)
+    })
+})