mikser-io-auth 0.5.0

package/README.md

@@ -0,0 +1,249 @@
+# mikser-io-auth
+
+> Authentication for mikser — HTTP Basic and JWT over Apache-format
+> `htpasswd` / `htgroup` files in the working folder.
+
+## What it is
+
+Mikser's engine ships an authentication *seam* (ADR-0012): a verifier
+contract, a constant-time static-token verifier, and the loopback policy
+that used to be hand-copied into every plugin that mounted a route. It ships
+no identity — no users, no groups, no login.
+
+This package is the identity half. It plugs in wherever a static token
+plugs in, because it implements the same contract:
+
+```js
+{ name, async verify(req), challenge?(req, res) }
+```
+
+**Design choices, and why:**
+
+- **Users and groups are files, not a database.** `users.htpasswd` and
+  `groups.htgroup` sit in the working folder next to the content they
+  govern. That is ADR-0002 applied to identity: reviewable in a pull
+  request, diffable, deployable by copying a directory, editable with
+  `htpasswd(1)` — a tool that predates every framework this project will
+  outlive. The format is not ours to version or migrate.
+
+- **The files are provisioned, never written at runtime.** No signup, no
+  password reset, no "create user" tool. A build tool has operators, not
+  members. The moment mikser writes an htpasswd file it has a locking
+  problem and a database it won't admit to. Edits *are* picked up without a
+  restart — the files are re-read when their mtime moves.
+
+- **bcrypt is the format worth trusting.** `$apr1$` and `{SHA}` are
+  supported because `htpasswd` emits them and an operator's existing file
+  should keep working; both are weak. DES-crypt and MD5-crypt are refused
+  outright rather than half-supported — silently rejecting is safer than a
+  subtly wrong implementation that accepts something. Use `htpasswd -B`.
+
+- **The signing key is a file, not a boot-time secret.** Regenerating a key
+  on boot silently invalidates every live token whenever the process
+  cycles, which presents as an intermittent auth bug and is miserable to
+  diagnose. `auth.key` is written `0600` on first run and reused after.
+
+- **Scope is computed from the files, never from the request.** A client
+  cannot ask for capabilities it doesn't hold. Downstream enforcement is
+  scope-only with no per-request re-read, which is safe *because* of this
+  invariant — it is the load-bearing piece, not optional hardening.
+
+- **Basic for people, JWT for clients.** HTTP Basic is browser-native and
+  needs no flow, which makes it right for `api` / `forms` / `decap`. MCP
+  clients expect Bearer and a discovery document, so they get JWT.
+
+## Use
+
+The whole thing, minimally:
+
+```js
+import { auth } from 'mikser-io-auth'
+import { api }  from 'mikser-io'
+import { mcp }  from 'mikser-io-mcp'
+
+const identity = auth()
+
+export default async () => ({
+    plugins: [
+        identity,
+        api({ endpoints: { admin:  { auth: identity } } }),
+        mcp({ endpoints: { remote: { auth: identity } } }),
+    ],
+})
+```
+
+That is a working setup. `htpasswd -B -c users.htpasswd alice` and you can
+sign in; an agent can self-register and connect. Everything below is
+optional and narrows what you already have.
+
+`identity` is both the plugin and the verifier, so `auth: identity` accepts
+whichever credential the caller has — Basic from a browser, Bearer from an
+agent. Use `identity.basic()` or `identity.jwt()` only to deliberately
+exclude one.
+
+With no capability map configured, an authenticated user is **unscoped**:
+the endpoint's own `operations` list is the only limit, exactly as for a
+static token. Add capabilities when you want them to mean something:
+
+```js
+const identity = auth({
+    // paths are relative to the working folder; these are the defaults
+    users:  'users.htpasswd',
+    groups: 'groups.htgroup',
+    key:    'auth.key',
+
+    // groups → capabilities. The files stay pure identity; this decides
+    // what a group is allowed to do. Once this exists, a user whose groups
+    // grant nothing can do nothing.
+    capabilities: {
+        editors: ['api:update', 'mcp:use'],
+        admins:  ['api:update', 'api:delete', 'mcp:use'],
+    },
+
+    // groups → rows, ANDed with the endpoint's own query
+    scopes: {
+        editors: { 'meta.href': { $regex: '^/web' } },
+    },
+
+    issuer: 'https://cms.example.com',
+})
+```
+
+The sign-in page names the deployment from mikser's own external URL
+(`runtime.options.url`), falling back to the host you connected to. It is
+not a config option — the host in the address bar is the most honest name
+there is, because it *is* the thing in front of you and so cannot name a
+different deployment.
+
+`auth()` returns a value that is both the lifecycle plugin and the factory
+for the verifiers — because config is evaluated before the runtime exists,
+so a verifier has to be nameable at config time while its store can only be
+opened once the working folder is known. Verifiers resolve their store
+lazily; plugin order doesn't matter, and forgetting to add `identity` to
+`plugins:` fails with a message saying so.
+
+### The files
+
+```
+<workingFolder>/
+    users.htpasswd      alice:$2y$10$…          htpasswd -B -c users.htpasswd alice
+    groups.htgroup      editors: alice bob
+    auth.key            {"kid":…,"privateJwk":…}   generated on first run, 0600
+```
+
+Keep `auth.key` out of version control — losing it invalidates every issued
+token; leaking it lets anyone mint one.
+
+### Endpoints
+
+Mounted at `base` (default `/auth`) when mikser runs with `--server`:
+
+| | |
+| --- | --- |
+| `GET /auth/authorize` | the sign-in page |
+| `POST /auth/authorize` | verify against `users.htpasswd`, redirect back with a code |
+| `POST /auth/token` | `authorization_code`, `refresh_token`, or `password` |
+| `POST /auth/register` | RFC 7591 self-registration — the only way a client exists |
+| `GET /auth/jwks.json` | the public half of the signing key |
+| `GET /auth/.well-known/oauth-authorization-server` | RFC 8414 metadata |
+| `GET /auth/logo.svg` | the mark on the sign-in page |
+
+For a script or CLI, skip the browser entirely:
+
+```bash
+curl -u alice:alice-pw -X POST https://cms.example.com/auth/token
+```
+
+### Clients — there is no client config
+
+Agents register themselves (RFC 7591). There is no list to maintain, no
+per-agent redirect to write down, and no way to declare one.
+
+A `clients:` map sounds harmless and isn't: it makes the set of agents that
+can connect equal to the set somebody thought to write down, so every new
+agent becomes a config change and a deploy. And an agent whose UI takes a
+URL and nothing else has no field to type a `client_id` into — it registers
+or it cannot connect at all.
+
+Tune the bounds if you need to:
+
+```js
+auth({ dcr: { maxPerIp: 5, windowMs: 3600_000, maxClients: 1000 } })
+```
+
+Public clients either way: PKCE (S256) required, no `client_secret`, because
+a browser or a native agent cannot keep one.
+
+`POST /auth/register` is **unauthenticated by necessity** — you need a
+`client_id` before you can authenticate, so a token requirement would make the
+endpoint useless to the only callers that need it. That is safe because a
+registered client can do nothing on its own: it holds no tokens and represents
+no person, and cannot act until someone signs in on the page, where what they
+can do comes from their groups rather than from anything the client asked for.
+What is at risk is table volume, not access — hence `maxPerIp` (in-process,
+counts every request including rejected ones) and `maxClients` (a row count,
+the bound that survives a restart).
+
+Registration names are attacker-controlled, so they are length-capped and
+HTML-escaped where they render.
+
+Every registration mints a **new** `client_id` — RFC 7591 has no get-or-create
+— so a reinstall or a second machine leaves another row behind. Registrations
+nobody ever signed in with are pruned after `pruneClientsAfterDays` (30).
+
+### Redirect URIs
+
+Matched exactly, with one exception: RFC 8252 §7.3 requires the **port of a
+loopback URI to be ignored**, because a native client binds an ephemeral port
+it cannot know in advance. Every MCP client that opens a browser depends on
+this. Scheme, host, path, query and fragment still match exactly.
+
+A self-registering client is held to a stricter rule than an operator writing
+config, because nobody reviewed it: `https` anywhere, `http` only on loopback,
+and never a fragment.
+
+### The sign-in page
+
+Deliberately identical to WhiteBox's — same layout, type scale, tokens and
+pending state — because mikser and WhiteBox are the same company's products
+and someone who administers both should not have to wonder which one they are
+looking at. The mark is the only difference, and `logo:` overrides it.
+
+The page names two things, and the second is the one that matters: **which**
+deployment (`appName`), and **who** is asking for access (the client). Without
+the second, signing in to your own site and handing an agent your permissions
+look identical.
+
+### Grants
+
+Authorization codes (60s, single-use) and refresh tokens (30d, rotated on
+every use) live in the engine's sqlite (ADR-0009), under `mikser_auth_*`.
+Identity stays in files; this is session bookkeeping.
+
+The engine wipes that database when its schema stamp changes, so **upgrading
+mikser signs everyone out**. Codes are irrelevant at 60 seconds; re-issuing
+refresh tokens after an engine upgrade is the price of not inventing a second
+persistence story.
+
+## Not implemented
+
+Deliberately out of scope: self-service registration, password reset, invites,
+and any cross-plugin permission catalog. A build server has operators, not
+members.
+
+## Auth on a mikser endpoint
+
+Reachability is unchanged from the engine's rule, with one difference that
+matters:
+
+| config | behaviour |
+| --- | --- |
+| nothing | loopback only, unless `allowRemote` |
+| `token: '…'` | valid token from anywhere; loopback still reaches it *without* the token |
+| `auth: identity.basic()` | the verifier gates every request — **no loopback bypass** |
+| `auth: identity.jwt()` | same, plus RFC 9728 discovery on MCP endpoints |
+
+A static token keeps the internet out, not the developer running the build.
+A real verifier gets no bypass: if you wired it up, an unauthenticated
+loopback caller — another process on a shared box, an SSRF hop — is exactly
+what you were buying protection from.

package/assets/logo.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="123.751 38.751 148.498 148.498" role="img" aria-label="mikser">
+  <title>mikser</title>
+  <g style="isolation:isolate">
+    <g style="mix-blend-mode:multiply">
+      <circle cx="198" cy="92" r="46" fill="#0A0907"></circle>
+      <circle cx="222.249" cy="134" r="46" fill="#0A0907" opacity="0.85"></circle>
+      <circle cx="173.751" cy="134" r="46" fill="#FF3F00"></circle>
+    </g>
+  </g>
+</svg>

package/index.js

@@ -0,0 +1,232 @@
+import path from 'node:path'
+import { registerRoute, anyOf } from 'mikser-io'
+
+import { createIdentityStore, parseHtpasswd, parseHtgroup, verifyPassword } from './lib/htpasswd.js'
+import { loadOrCreateKey, jwks, ALG } from './lib/keys.js'
+import { issueToken, createTokenVerifier } from './lib/tokens.js'
+import { basic, jwt } from './lib/verifiers.js'
+import { redirectUriAllowed, validateRedirectUri, registerDynamicClient } from './lib/clients.js'
+import { challengeFromVerifier, verifyPkce, opaqueToken } from './lib/pkce.js'
+import { loginPage } from './lib/login-page.js'
+import { mountRoutes } from './lib/routes.js'
+import * as grants from './lib/grants.js'
+
+export { parseHtpasswd, parseHtgroup, verifyPassword, createIdentityStore }
+export { loadOrCreateKey, jwks, ALG }
+export { issueToken, createTokenVerifier }
+export { redirectUriAllowed, validateRedirectUri, registerDynamicClient }
+export { challengeFromVerifier, verifyPkce, opaqueToken }
+export { loginPage }
+export { grants }
+
+/**
+ * Authentication for mikser (ADR-0012).
+ *
+ * Returns a value that is BOTH the lifecycle plugin and the factory for the
+ * verifiers other plugins gate on — because config is evaluated before the
+ * runtime exists, and a verifier has to be nameable at config time while its
+ * store can only be opened once the working folder is known:
+ *
+ *     const identity = auth({
+ *         capabilities: { editors: ['api:update', 'mcp:use'] },
+ *         issuer: 'https://cms.example.com',
+ *     })
+ *
+ *     export default async () => ({
+ *         plugins: [
+ *             identity,
+ *             api({ endpoints: { admin: { auth: identity.basic() } } }),
+ *             mcp({ endpoints: { remote: { auth: identity.jwt() } } }),
+ *         ],
+ *     })
+ *
+ * Verifiers are created eagerly and resolve their store lazily, so the order
+ * of `plugins:` doesn't matter and a config-time typo still surfaces at boot.
+ */
+export function auth(options = {}) {
+    const {
+        users        = 'users.htpasswd',
+        groups       = 'groups.htgroup',
+        key          = 'auth.key',
+        capabilities = {},
+        scopes       = {},
+        issuer,
+        audience     = issuer,
+        base         = '/auth',
+        ttl          = '1h',
+        realm        = 'mikser',
+        dcr          = {},
+        pruneClientsAfterDays = 30,
+        logo,
+    } = options
+
+    // Filled in at onLoad, read by the verifiers at request time.
+    let state = null
+    const ready = () => {
+        if (!state) {
+            throw new Error(
+                'mikser-io-auth: a verifier was used before the auth plugin loaded. ' +
+                'Add the value returned by auth() to your `plugins:` array.'
+            )
+        }
+        return state
+    }
+
+    // A lazy façade over the store, so basic() can be constructed at config
+    // time and still read files that only exist once mikser has a working folder.
+    const lazyStore = {
+        authenticate:    (u, p) => ready().store.authenticate(u, p),
+        groupsOf:        (u)    => ready().store.groupsOf(u),
+        capabilitiesOf:  (u)    => ready().store.capabilitiesOf(u),
+        reload:          ()     => ready().store.reload(),
+    }
+
+    const plugin = ({ runtime, onLoad, onLoaded, useLogger }) => {
+        onLoad(async () => {
+            const logger = useLogger()
+            const workingFolder = runtime.options.workingFolder
+            const resolve = (f) => (path.isAbsolute(f) ? f : path.join(workingFolder, f))
+
+            const store = createIdentityStore({
+                usersFile:  resolve(users),
+                groupsFile: resolve(groups),
+                groups:     capabilities,
+                scopes,
+                logger,
+            })
+            const signingKey = await loadOrCreateKey({ keyFile: resolve(key), logger })
+
+            state = {
+                store,
+                key: signingKey,
+                verifyToken: createTokenVerifier({
+                    key: signingKey,
+                    issuer:   issuer ?? runtime.options.url,
+                    audience: audience ?? runtime.options.url,
+                }),
+                logger,
+            }
+        })
+
+        onLoaded(async () => {
+            const app = runtime.options.app
+            if (!app) return   // no server this run — verifiers still work in-process
+
+            const logger = useLogger()
+            // Express comes from the host, not from our own node_modules —
+            // same instance as runtime.options.app, same pattern as the
+            // forms plugin uses.
+            const { default: express } = await import('express').catch(() => {
+                throw new Error('mikser-io-auth: express is required — npm install express')
+            })
+            const router = express.Router()
+            router.use(express.urlencoded({ extended: false, limit: '8kb' }))
+            router.use(express.json({ limit: '8kb' }))
+
+            const originOf = (req) => issuer ?? `${req.protocol}://${req.get('host')}`
+
+            // What the sign-in page calls this deployment. Not a config
+            // option: mikser already knows its external URL, and failing
+            // that, the host in the address bar is the most honest name
+            // there is — it IS the thing you connected to, so it cannot
+            // name a different deployment than the one in front of you.
+            const nameOf = (req) => {
+                try {
+                    if (runtime.options.url) return new URL(runtime.options.url).host
+                } catch { /* not a URL — fall through */ }
+                return req.get('host')
+            }
+
+            mountRoutes(router, {
+                base,
+                nameOf,
+                logoUrl:  logo ?? `${base}/logo.svg`,
+                realm,
+                ttl,
+                ready,
+                issuerFor:   originOf,
+                audienceFor: (req) => audience ?? originOf(req),
+                dcr,
+                logger,
+            })
+
+            app.use(base, router)
+
+            // Codes are 60s and refresh tokens 30d; without a sweep the rows
+            // accumulate for the life of the database. Once at boot is enough
+            // for a build tool — the checks that matter (expiry, single use)
+            // are enforced on read, not by the sweep.
+            try {
+                const swept = grants.sweepExpired()
+                if (swept.codes || swept.refresh) {
+                    logger?.debug?.('auth: swept %d expired code(s), %d refresh token(s)',
+                        swept.codes, swept.refresh)
+                }
+                // Every registration mints a NEW client_id — there is no
+                // "get or create" in RFC 7591 — so a reinstall or a second
+                // machine leaves another row behind. Only ones nobody ever
+                // signed in with are dropped; a config-declared client is
+                // never touched, because it lives in config, not this table.
+                if (pruneClientsAfterDays) {
+                    const pruned = grants.pruneUnusedClients({
+                        olderThanMs: pruneClientsAfterDays * 24 * 60 * 60 * 1000,
+                    })
+                    if (pruned) logger?.info?.('auth: pruned %d unused client registration(s)', pruned)
+                }
+            } catch (err) {
+                logger?.debug?.('auth: could not sweep expired grants — %s', err.message)
+            }
+
+            registerRoute({
+                path:         base,
+                plugin:       'auth',
+                reachability: 'public',
+                streaming:    false,
+                label:        'Auth',
+                detail:       `(authorize, token, register, jwks; alg=${ALG})`,
+                authLabel:    'public',
+            })
+            logger?.info?.('Auth mounted at %s (users=%s, groups=%s)', base, users, groups)
+        })
+    }
+
+    // Verifier factories. Both close over the lazy store/state, so they can
+    // be handed to another plugin's `auth:` option at config time.
+    plugin.basic = (opts = {}) => basic({ store: lazyStore, realm, ...opts })
+
+    plugin.jwt = (opts = {}) => jwt({
+        verifyToken: (token) => ready().verifyToken(token),
+        issuer,
+        scopes: [...new Set(Object.values(capabilities).flat())],
+        ...opts,
+    })
+
+    plugin.store = lazyStore
+
+    // The plugin IS a verifier, accepting either credential:
+    //
+    //     api({ endpoints: { admin: { auth: identity } } })
+    //
+    // rather than making every call site pick basic() or jwt() when the
+    // honest answer is "whichever the caller has". A browser sends Basic, an
+    // agent sends its Bearer, and the two never collide — each verifier
+    // reports "not mine" for the other's scheme, so the composite reaches the
+    // right one. Reach for .basic() or .jwt() only to deliberately EXCLUDE
+    // one, which is rare.
+    const composite = anyOf(plugin.basic(), plugin.jwt())
+    plugin.verify    = (req) => composite.verify(req)
+    plugin.challenge = (req, res) => composite.challenge(req, res)
+    Object.defineProperties(plugin, {
+        // A function's own `name` is non-writable, so plain assignment
+        // throws in a module. defineProperty is the only way to give the
+        // verifier the name that shows up in route logs.
+        name:                 { value: 'auth', configurable: true },
+        authorizationServers: { get: () => composite.authorizationServers },
+        resource:             { get: () => composite.resource },
+        scopesSupported:      { get: () => composite.scopesSupported },
+    })
+
+    return plugin
+}
+
+export default auth

package/lib/clients.js

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto'
+
+// Clients register themselves (RFC 7591). There is no operator-maintained
+// list, and no way to declare one.
+//
+// The alternative was a `clients:` config map, which sounds harmless and
+// isn't: it makes the set of agents that can connect equal to the set
+// somebody thought to write down, so every new agent is a config change and
+// a deploy. Worse, an agent whose UI takes a URL and nothing else has no
+// field to type a client_id into — it registers or it cannot connect at all.
+// A server whose whole purpose is that agents connect to it should not ship
+// a default where they can't.
+//
+// Public clients only: PKCE is required and there is no client_secret,
+// because a browser or a native agent cannot keep one.
+
+const MAX_REDIRECT_URIS = 10
+const MAX_CLIENT_NAME   = 80
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost'])
+
+const isLoopbackUrl = (url) =>
+    url.hostname === '127.0.0.1' || url.hostname === '[::1]' || url.hostname === '::1' ||
+    url.hostname === 'localhost'
+
+// Exact match, with ONE exception: RFC 8252 §7.3 requires an authorization
+// server to ignore the port of a loopback redirect, because a native client
+// binds an ephemeral port it cannot know in advance. Every MCP client that
+// opens a browser depends on this. Everything else about the URI — scheme,
+// host, path, query, fragment — must still match exactly.
+export function redirectUriAllowed(client, redirectUri) {
+    if (!redirectUri) return false
+    if (client.redirectUris.includes(redirectUri)) return true
+
+    let asked
+    try { asked = new URL(redirectUri) } catch { return false }
+    if (!isLoopbackUrl(asked)) return false
+
+    return client.redirectUris.some(registered => {
+        let reg
+        try { reg = new URL(registered) } catch { return false }
+        return isLoopbackUrl(reg)
+            && reg.protocol === asked.protocol
+            && reg.hostname === asked.hostname
+            && reg.pathname === asked.pathname
+            && reg.search   === asked.search
+            && reg.hash     === asked.hash
+    })
+}
+
+// Throws with an RFC 7591 error code, which the route maps onto the body.
+export class RegistrationError extends Error {
+    constructor(code, description) {
+        super(description)
+        this.code = code
+    }
+}
+
+// What a self-registering client may ask to be redirected to. Stricter than
+// what an operator may write in config, because nobody reviewed this one.
+export function validateRedirectUri(value) {
+    if (typeof value !== 'string' || !value) return 'must be a string'
+    let url
+    try { url = new URL(value) } catch { return 'is not an absolute URI' }
+    if (url.hash) return 'must not contain a fragment'
+    if (url.protocol === 'https:') return null
+    if (url.protocol === 'http:') {
+        return LOOPBACK_HOSTS.has(url.hostname) ? null : 'must use https, except on loopback'
+    }
+    return `scheme ${url.protocol} is not allowed — use https, or http on loopback`
+}
+
+// Register a client that named itself.
+//
+// Unauthenticated by necessity: you need a client_id BEFORE you can
+// authenticate, so requiring a token here would make the endpoint useless to
+// the only callers that need it. That is safe because a registered client can
+// do NOTHING on its own — it holds no tokens and represents no person, and
+// cannot act until someone signs in on the page, where what they can do comes
+// from their groups rather than from anything the client asked for.
+//
+// What is at risk is table volume, not access. `maxClients` bounds it in the
+// durable place — a rate limiter lives in process memory and does not survive
+// a restart, while rows do.
+export function registerDynamicClient({ name, redirectUris, maxClients, store }) {
+    if (!Array.isArray(redirectUris) || !redirectUris.length) {
+        throw new RegistrationError('invalid_redirect_uri', 'redirect_uris must be a non-empty array')
+    }
+    if (redirectUris.length > MAX_REDIRECT_URIS) {
+        throw new RegistrationError('invalid_redirect_uri', `at most ${MAX_REDIRECT_URIS} redirect_uris`)
+    }
+    for (const uri of redirectUris) {
+        const problem = validateRedirectUri(uri)
+        if (problem) {
+            throw new RegistrationError('invalid_redirect_uri', `redirect_uri ${JSON.stringify(uri)} ${problem}`)
+        }
+    }
+
+    if (maxClients != null && store.countDynamicClients() >= maxClients) {
+        throw new RegistrationError('invalid_client_metadata',
+            'this server is not accepting new client registrations right now')
+    }
+
+    // The name is client-supplied and ends up on the sign-in page, so it is
+    // length-capped here and HTML-escaped at render. A client that sends no
+    // name gets a neutral one rather than a blank line where the agent's
+    // identity should be — which would make the page's whole point moot.
+    const clientName = (typeof name === 'string' && name.trim())
+        ? name.trim().slice(0, MAX_CLIENT_NAME)
+        : 'Unnamed client'
+
+    return store.insertDynamicClient({
+        clientId: randomUUID(),
+        name: clientName,
+        redirectUris,
+    })
+}