@crvouga/atlas 0.3.0 → 0.5.0

package/dist/server/src/app.js

@@ -0,0 +1,419 @@
+/**
+ * @module The Atlas server application
+ *
+ * `createAtlasServer` is the whole of a project's Atlas as one `fetch` handler: the API results are uploaded to, the live
+ * report every viewer is shown, the gate, the server-sent event stream, the specs and runs the viewer reads, the viewer
+ * itself, and the server's own description (`/api/openapi.json`, `/llms.txt`). What it knows lives in its backends (by
+ * default a folder on its own disk), so replacing it loses nothing. Every error leaves as an RFC 9457 problem document; every
+ * route is described in `openapi.ts` (a test holds the two together).
+ *
+ * @see docs/server.md
+ */
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { brotliCompress, constants as zlibConstants, gzip } from 'node:zlib';
+import { Hono } from 'hono';
+import { UNTRUSTED_HEADERS } from '../../reports/src/attachment-response.js';
+import { combineBackends, summarize } from '../../reports/src/compose.js';
+import { combineEvidence } from '../../reports/src/layer-merge.js';
+import { layerCatalogKey } from '../../reports/src/layer-store.js';
+import { createLayersApp } from '../../reports/src/layers-route.js';
+import { publishChecks } from '../../reports/src/publish-checks.js';
+import { reportStatus } from '../../reports/src/report-status.js';
+import { ReportIndex } from '../../reports/src/report-index.js';
+import { listRunSummaries, readRunFile } from '../../reports/src/run-bundle.js';
+import { latestSpecSet, readSpecBody } from '../../reports/src/spec-set.js';
+import { llmsTxt } from './llms.js';
+import { openApiDocument } from './openapi.js';
+import { asProblem, problemResponse } from './problem.js';
+import { Refusal } from './validate.js';
+import { createAuth } from './auth.js';
+import { EventHub } from './events.js';
+import { readLimited, storeApi } from './store-api.js';
+const gzipAsync = promisify(gzip);
+const brotliAsync = promisify(brotliCompress);
+const TYPES = {
+    html: 'text/html; charset=utf-8', js: 'text/javascript; charset=utf-8', mjs: 'text/javascript; charset=utf-8', css: 'text/css; charset=utf-8', json: 'application/json', map: 'application/json',
+    svg: 'image/svg+xml', png: 'image/png', webp: 'image/webp', ico: 'image/x-icon', woff2: 'font/woff2', woff: 'font/woff', txt: 'text/plain; charset=utf-8', wasm: 'application/wasm'
+};
+const typeOf = (file) => TYPES[file.split('.').at(-1)?.toLowerCase() ?? ''] ?? 'application/octet-stream';
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml)|image\/svg)/;
+const MiB = 1024 * 1024;
+/**
+ * The whole of a project's Atlas on one process: the API that results are uploaded to, the live report every
+ * viewer is shown, and the viewer itself. All of it is under one host, `/api` for the API and `/` for the page.
+ * What it knows lives in its backends (by default a folder on its own disk), so replacing it loses nothing.
+ */
+export function createAtlasServer(options) {
+    const now = options.now ?? Date.now;
+    const backends = options.backends;
+    const writeBackend = backends.find(backend => backend.id === options.write);
+    if (!writeBackend)
+        throw new Error(`The write backend "${options.write}" is not among the backends (${backends.map(backend => backend.id).join(', ')})`);
+    const stores = backends.map(backend => backend.store);
+    const auth = createAuth(options.tokens ?? [], options.anonymousRead ?? false);
+    const limits = { object: (options.limits?.maxObjectMiB ?? 256) * MiB, json: (options.limits?.maxJsonMiB ?? 32) * MiB };
+    const index = new ReportIndex(backends, { now, ...(options.include ? { include: options.include } : {}) });
+    const events = new EventHub({ maxSubscribers: options.limits?.maxStreams ?? 500, heartbeatMs: options.heartbeatMs ?? 15_000 });
+    const compressed = new Map();
+    const assets = new Map();
+    // Spec sets and runs change rarely: answer from memory, look again in the background, and look at once when
+    // something that could change them was uploaded. `invalidate()` resolves when the fresh answer is in place, so
+    // viewers are told to read again only when there is something new to read.
+    function cached(load, ttlMs = 10_000) {
+        let value;
+        let at = 0;
+        let started = 0;
+        let applied = 0;
+        const reload = async () => {
+            const mine = ++started;
+            at = now();
+            try {
+                const result = await load();
+                // Loads can finish out of order: only the newest one started may replace what is held.
+                if (mine > applied) {
+                    applied = mine;
+                    value = Promise.resolve(result);
+                }
+            }
+            catch { /* what is held stays */ }
+        };
+        const read = (() => {
+            if (!value) {
+                const mine = ++started;
+                at = now();
+                value = load();
+                value.then(() => { applied = Math.max(applied, mine); }, () => { value = undefined; });
+            }
+            else if (now() - at > ttlMs) {
+                at = now();
+                void reload();
+            }
+            return value;
+        });
+        read.invalidate = reload;
+        return read;
+    }
+    const specSets = new Map();
+    const specs = cached(() => latestSpecSet(stores, options.outlineBranch, specSets));
+    const lastRuns = new Map();
+    const runCatalog = stores.map(() => new Map());
+    const runs = cached(async () => {
+        const lists = await Promise.all(stores.map(async (store, i) => {
+            try {
+                const rows = await listRunSummaries(store, 100, runCatalog[i]);
+                lastRuns.set(i, rows);
+                return rows;
+            }
+            catch {
+                return lastRuns.get(i) ?? [];
+            }
+        }));
+        const byId = new Map(lists.flat().map(run => [run.id, run]));
+        return [...byId.values()].sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt) || (a.id < b.id ? -1 : 1));
+    });
+    const outline = async () => {
+        const found = await specs();
+        if (!found)
+            return { specs: [], sha: null, changedFiles: [], readSpec: async () => null };
+        const entries = found.set.files.map(({ path: file, domain, kind, title, fingerprint }) => ({ path: file, domain, kind, title, fingerprint }));
+        return { specs: entries, sha: found.set.sha, changedFiles: [], readSpec: async (file) => {
+                const entry = found.set.files.find(item => item.path === file);
+                return entry ? readSpecBody(found.store, entry.digest) : null;
+            } };
+    };
+    const layers = createLayersApp({
+        store: null, backends: backends.map(backend => ({ id: backend.id, label: backend.label ?? backend.id, store: backend.store })),
+        clock: { now }, timers: { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: handle => clearTimeout(handle), setInterval: (fn, ms) => setInterval(fn, ms), clearInterval: handle => clearInterval(handle) },
+        outline,
+        ...(options.include ? { include: options.include } : {})
+    });
+    // What every viewer is told when the report changes: small, and enough to say what arrived.
+    const summaryOf = (change) => ({
+        version: change.version,
+        totalLayers: change.totalLayers,
+        added: change.added.slice(0, 20).map(layer => ({ id: layer.id, producer: layer.producer, environment: layer.environment, branch: layer.branch, sha: layer.sha, recordedAtMs: layer.recordedAtMs, counts: layer.counts, ...(layer.freshness ? { freshness: layer.freshness } : {}) })),
+        addedTotal: change.added.length
+    });
+    const stopListening = index.onChange(change => events.publish('report', summaryOf(change)));
+    /**
+     * A response, compressed when the client accepts it and it is worth it. What is the same for everyone (a page,
+     * a script, one version of the report) is compressed once, however many ask at the same moment, and kept; `slow`
+     * asks for the smallest form, which is worth waiting for only when it is made once and sent to every visitor:
+     * the viewer's own files, which are kept for as long as the server runs.
+     */
+    async function body(c, data, contentType, headers, cacheKey, slow = false) {
+        const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const accepts = c.req.header('accept-encoding') ?? '';
+        const encoding = COMPRESSIBLE.test(contentType) && bytes.length > 1024 ? (slow && /\bbr\b/.test(accepts) ? 'br' : /\bgzip\b/.test(accepts) ? 'gzip' : null) : null;
+        let out = bytes;
+        if (encoding) {
+            const key = cacheKey ? `${encoding}|${cacheKey}|${bytes.length}` : null;
+            const kept = slow ? assets : compressed;
+            let packing = key ? kept.get(key) : undefined;
+            if (!packing) {
+                packing = (encoding === 'br'
+                    ? brotliAsync(bytes, { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11, [zlibConstants.BROTLI_PARAM_SIZE_HINT]: bytes.length } })
+                    : gzipAsync(bytes)).then(packed => new Uint8Array(packed));
+                if (key) {
+                    if (kept.size >= (slow ? 512 : 64))
+                        kept.delete(kept.keys().next().value);
+                    kept.set(key, packing);
+                    packing.catch(() => kept.delete(key));
+                }
+            }
+            out = await packing;
+        }
+        return new Response(out, { headers: { 'content-type': contentType, vary: 'accept-encoding', ...(encoding ? { 'content-encoding': encoding } : {}), ...headers } });
+    }
+    const app = new Hono();
+    const unauthorized = (verdict) => problemResponse(verdict.status, verdict.message, verdict.status === 401 ? { 'www-authenticate': 'Basic realm="Atlas", charset="UTF-8"' } : {});
+    // Everything but the probes and the store protocol (which checks for itself) needs at least a reader.
+    app.use('*', async (c, next) => {
+        const started = now();
+        const pathname = new URL(c.req.url).pathname;
+        const open = pathname === '/healthz' || pathname === '/readyz' || pathname === '/llms.txt' || pathname === '/api/openapi.json' || pathname.startsWith('/api/store');
+        if (!open) {
+            const verdict = auth.check(c.req.raw, 'read');
+            if (!verdict.ok) {
+                c.res = unauthorized(verdict);
+            }
+            else
+                await next();
+        }
+        else
+            await next();
+        // Every error, whichever handler made it, leaves as a problem document.
+        if (c.res.status >= 400)
+            c.res = await asProblem(c.res);
+        if (pathname !== '/healthz' && pathname !== '/readyz')
+            options.log?.({ at: new Date(started).toISOString(), method: c.req.method, path: pathname, status: c.res.status, ms: now() - started });
+    });
+    app.get('/healthz', c => c.json({ ok: true }));
+    // What an agent handed only this server's address reads first: how to use it, and the machine-readable API.
+    app.get('/llms.txt', c => {
+        const forwarded = c.req.header('x-forwarded-host');
+        const origin = forwarded ? `${c.req.header('x-forwarded-proto') ?? 'https'}://${forwarded}` : new URL(c.req.url).origin;
+        return c.text(llmsTxt({ url: origin, open: auth.open, write: options.write }), 200, { 'cache-control': 'no-cache' });
+    });
+    app.get('/api/openapi.json', c => {
+        const forwarded = c.req.header('x-forwarded-host');
+        const serverUrl = forwarded ? `${c.req.header('x-forwarded-proto') ?? 'https'}://${forwarded}` : undefined;
+        return c.json(openApiDocument(serverUrl ? { serverUrl } : {}), 200, { 'cache-control': 'no-cache' });
+    });
+    app.get('/readyz', c => {
+        const snapshot = index.snapshot();
+        const up = snapshot.backends.some(backend => backend.available);
+        return c.json({ ready: index.ready && up, ...index.stats(), backends: snapshot.backends.map(({ id, available }) => ({ id, available })) }, index.ready && up ? 200 : 503);
+    });
+    // Who is asking, and what this server is: for the viewer's header, and for `atlas report doctor`.
+    app.get('/api/server', c => {
+        const identity = auth.identify(c.req.raw);
+        const snapshot = index.snapshot();
+        return c.json({
+            name: 'atlas', version: options.version ?? null, role: identity?.role ?? 'read', open: auth.open,
+            write: options.write, ready: index.ready, viewers: events.count, time: now(),
+            backends: snapshot.backends.map(({ id, label, available }) => ({ id, label, available, write: id === options.write })),
+            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true }
+        });
+    });
+    // Live updates: told when the report changes, and when specs or runs do.
+    app.get('/api/events', c => events.stream(c.req.raw, () => ({ version: index.snapshot().version, ready: index.ready, time: now() })));
+    // The report as it stands: one request, only what wins. Everything else about a layer is history.
+    app.get('/api/reports/evidence/effective', async (c) => {
+        if (!index.ready)
+            return c.json({ error: 'Atlas is still reading its backends; try again in a moment.' }, 503, { 'retry-after': '1' });
+        const { version, text } = index.json();
+        const etag = `"${version}"`;
+        const headers = { etag, 'cache-control': 'no-cache' };
+        if (c.req.header('if-none-match') === etag)
+            return new Response(null, { status: 304, headers });
+        // A viewer that holds a recent report is sent what changed since, not all of it again.
+        const since = c.req.query('since');
+        const delta = since ? index.delta(since) : null;
+        if (delta)
+            return body(c, delta.text, 'application/json', headers);
+        return body(c, text, 'application/json', headers, `effective|${version}`);
+    });
+    app.route('/api/reports', layers);
+    // Upload: the store protocol, and a simple JSON way in for anything that can make a request.
+    app.route('/api/store', storeApi({
+        store: writeBackend.store, auth, maxObjectBytes: limits.object,
+        onStored: async (key, kind, layer) => {
+            if (kind === 'layer-catalog')
+                await index.accept(writeBackend.id, key, layer);
+            else if (kind === 'spec-catalog') {
+                await specs.invalidate();
+                events.publish('atlas:change', { scope: 'specs', files: [], runIds: [] });
+            }
+            else if (kind === 'run-catalog') {
+                await runs.invalidate();
+                events.publish('atlas:change', { scope: 'runs', files: [], runIds: [/-([\w.-]+)\.json$/.exec(key)?.[1] ?? ''].filter(Boolean) });
+            }
+        }
+    }));
+    app.post('/api/checks', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return unauthorized(verdict);
+        try {
+            const bytes = await readLimited(c.req.raw, limits.json);
+            let input;
+            try {
+                input = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                throw new Refusal(422, 'The body is not JSON');
+            }
+            // Anything that can make a request can report: the time defaults to now, and the rest is the layer format.
+            const layer = await publishChecks(writeBackend.store, { recordedAtMs: now(), ...input });
+            await index.accept(writeBackend.id, layerCatalogKey(layer.recordedAtMs, layer.id), layer);
+            return c.json({ ok: true, id: layer.id, checks: layer.parts[0]?.checks.length ?? 0 }, 201);
+        }
+        catch (error) {
+            if (error instanceof Refusal)
+                return c.json({ error: error.message }, error.status);
+            if (error instanceof Error && /^publishChecks:/.test(error.message))
+                return c.json({ error: error.message }, 422);
+            throw error;
+        }
+    });
+    // The gate: does the report pass? Computed here, from what the server already holds.
+    const filtered = new Map();
+    const verdicts = new Map();
+    app.get('/api/status', async (c) => {
+        if (!index.ready)
+            return c.json({ error: 'Atlas is still reading its backends; try again in a moment.' }, 503, { 'retry-after': '1' });
+        const branches = c.req.queries('branch') ?? [];
+        const ignoreModified = c.req.query('ignoreModified') === '1';
+        const required = (c.req.query('requireEnvironments') ?? '').split(',').map(name => name.trim()).filter(Boolean);
+        const requireAllSpecs = c.req.query('requireAllSpecs') === '1';
+        const snapshot = index.snapshot();
+        const found = await outline();
+        // The gate is a function of the report and the specs, so it is worked out once for each pair, however often CI asks.
+        const asked = `${snapshot.version}|${(await specs())?.set.id ?? ''}|${[...branches].sort().join(',')}|${ignoreModified}|${required.join(',')}|${requireAllSpecs}`;
+        if (!verdicts.has(asked)) {
+            if (verdicts.size >= 16)
+                verdicts.delete(verdicts.keys().next().value);
+            verdicts.set(asked, (async () => {
+                let report;
+                if (!branches.length && !ignoreModified) {
+                    const combined = combineEvidence(found, snapshot.layers);
+                    report = { combined, layers: snapshot.layers.map(entry => entry.layer), backends: snapshot.backends, notices: snapshot.notices, summary: summarize(combined) };
+                }
+                else {
+                    // Narrowing needs the history the live report has dropped: read it, once per version and filter.
+                    const key = `${snapshot.version}|${[...branches].sort().join(',')}|${ignoreModified}`;
+                    if (!filtered.has(key)) {
+                        if (filtered.size >= 8)
+                            filtered.delete(filtered.keys().next().value);
+                        filtered.set(key, combineBackends(backends, { outline: found, include: layer => (options.include?.(layer) ?? true) && (!branches.length || (layer.branch !== null && branches.includes(layer.branch))) && (!ignoreModified || layer.freshness === undefined) }));
+                    }
+                    report = await filtered.get(key);
+                }
+                const status = reportStatus(report, { requireEnvironments: required, requireAllSpecs });
+                return { text: JSON.stringify({ ...status, layers: snapshot.totalLayers }), ok: status.ok };
+            })());
+            verdicts.get(asked).catch(() => verdicts.delete(asked));
+        }
+        const { text, ok } = await verdicts.get(asked);
+        return body(c, text, 'application/json', { 'cache-control': 'no-cache', 'x-atlas-ok': String(ok) }, `status|${asked}`);
+    });
+    // The viewer's data directory: specs and runs, read from the backends.
+    app.get('/api/data/sources.json', c => c.json({ schemaVersion: 1, sources: [{ id: 'workspace', label: 'Atlas', type: 'http', baseUrl: './', eventsUrl: '../events', live: true }] }, 200, { 'cache-control': 'no-cache' }));
+    app.get('/api/data/specs/index.json', async (c) => {
+        const found = await specs();
+        return c.json({ schemaVersion: 1, generatedAt: new Date(now()).toISOString(), ref: found?.set.sha ?? null, files: (found?.set.files ?? []).map(file => file.path.replace(/^specs\//, '')) }, 200, { 'cache-control': 'no-cache' });
+    });
+    app.get('/api/data/specs/*', async (c) => {
+        let file;
+        try {
+            file = decodeURIComponent(new URL(c.req.url).pathname.slice('/api/data/specs/'.length));
+        }
+        catch {
+            return c.notFound();
+        }
+        const found = await specs();
+        const entry = found?.set.files.find(item => item.path === `specs/${file}`);
+        const text = found && entry ? await readSpecBody(found.store, entry.digest) : null;
+        if (text === null)
+            return c.notFound();
+        // The address is the spec's path, which a later set can fill with other text: revalidate, by content.
+        const etag = `"${entry.digest}"`;
+        if (c.req.header('if-none-match') === etag)
+            return new Response(null, { status: 304, headers: { etag, 'cache-control': 'no-cache' } });
+        return body(c, text, 'text/plain; charset=utf-8', { 'cache-control': 'no-cache', etag }, entry.digest);
+    });
+    app.get('/api/data/runs/index.json', async (c) => c.json({ generatedAt: new Date(now()).toISOString(), runs: await runs() }, 200, { 'cache-control': 'no-cache' }));
+    app.get('/api/data/runs/:id/*', async (c) => {
+        const id = c.req.param('id');
+        let rel;
+        try {
+            rel = decodeURIComponent(new URL(c.req.url).pathname.slice(`/api/data/runs/${id}/`.length));
+        }
+        catch {
+            return c.notFound();
+        }
+        for (const store of stores) {
+            const stored = await readRunFile(store, id, rel).catch(() => null);
+            if (stored)
+                return new Response(stored.body, { headers: { 'content-type': stored.contentType, ...UNTRUSTED_HEADERS, 'cache-control': 'public, max-age=31536000, immutable' } });
+        }
+        return c.notFound();
+    });
+    // Everything else under /api is for reading: a write to it is a wrong method, not a missing page.
+    app.on(['POST', 'PUT', 'PATCH', 'DELETE'], '/api/*', c => c.json({ error: 'Method not allowed' }, 405, { allow: 'GET, HEAD' }));
+    // The viewer, with this server's address book written into its page.
+    if (options.site) {
+        const root = path.resolve(options.site);
+        const config = JSON.stringify({ api: './api', reportsUrl: './api/reports', dataUrl: './api/data/', eventsUrl: './api/events', effective: true, ...(options.page ?? {}) });
+        app.get('*', async (c) => {
+            const pathname = new URL(c.req.url).pathname;
+            // An API path that nothing answered is an error, not a page.
+            if (pathname.startsWith('/api/'))
+                return c.json({ error: 'Not found' }, 404);
+            let relative;
+            try {
+                relative = decodeURIComponent(pathname).replace(/^\/+/, '');
+            }
+            catch {
+                return c.notFound();
+            }
+            if (relative.split('/').some(part => part === '..' || part.includes('\\')))
+                return c.notFound();
+            let file = path.join(root, relative || 'index.html');
+            let info = await stat(file).catch(() => null);
+            if (info?.isDirectory()) {
+                file = path.join(file, 'index.html');
+                info = await stat(file).catch(() => null);
+            }
+            if (!info && !path.extname(relative)) {
+                file = path.join(root, 'index.html');
+                info = await stat(file).catch(() => null);
+            }
+            if (!info?.isFile())
+                return c.notFound();
+            const isIndex = path.basename(file) === 'index.html';
+            let data = new Uint8Array(await readFile(file));
+            if (isIndex)
+                data = new TextDecoder().decode(data).replace('</head>', `<script>window.__ATLAS_CONFIG__=${config}</script></head>`);
+            const hashed = /(^|\/)assets\//.test(relative);
+            return body(c, data, typeOf(file), { 'cache-control': hashed ? 'public, max-age=31536000, immutable' : 'no-cache' }, `${file}|${info.mtimeMs}`, true);
+        });
+    }
+    // An API path that nothing answered is an error a client can read, whether or not a viewer is served.
+    app.notFound(c => (new URL(c.req.url).pathname.startsWith('/api/') ? c.json({ error: 'Not found' }, 404) : c.text('404 Not Found', 404)));
+    app.onError((error, c) => {
+        options.log?.({ at: new Date(now()).toISOString(), level: 'error', path: new URL(c.req.url).pathname, error: error instanceof Error ? error.message : String(error) });
+        return c.json({ error: 'Something went wrong on the server. It has been logged.' }, 500);
+    });
+    return {
+        fetch: async (request) => app.fetch(request),
+        routes: app.routes.map(({ method, path }) => ({ method, path })),
+        index,
+        events,
+        ready: index.start(options.refreshMs ?? 10_000),
+        close: () => { stopListening(); index.stop(); events.close(); }
+    };
+}

package/dist/server/src/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module Authentication and roles
+ *
+ * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
+ * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
+ * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.
+ */
+import type { ServerRole } from '../../schema/src/server-config.js';
+import type { ResolvedToken } from './config.js';
+/** Who a request is: the token's `name` (never the token), its `role`, and how it was presented (`bearer`, `basic`, or `none` for an open server or an anonymous reader). */
+export type Identity = {
+    readonly name: string;
+    readonly role: ServerRole;
+    /** `bearer` for a token in a header, `basic` for the browser's sign-in box, `none` for a server with no tokens. */
+    readonly via: 'bearer' | 'basic' | 'none';
+};
+/** The answer to "may this request do that": allowed with the identity, or refused with the status to answer (`401` no or unknown token, `403` a known token that may not) and a message that says what to do. */
+export type Verdict = {
+    readonly ok: true;
+    readonly identity: Identity;
+} | {
+    readonly ok: false;
+    readonly status: 401 | 403;
+    readonly message: string;
+};
+/**
+ * Who is asking, and may they. A server with no tokens is open (and refuses to listen beyond this machine
+ * unless told it may). With tokens, every request must carry one, except where `anonymousRead` lets anyone look.
+ *
+ * Changing anything needs a token in an `Authorization: Bearer` header, never the browser's sign-in box: the
+ * browser sends that box's credentials on its own to any page that asks, which would let another site upload
+ * with them.
+ */
+export declare function createAuth(tokens: readonly ResolvedToken[], anonymousRead: boolean): {
+    identify: (request: Request) => Identity | null;
+    check: (request: Request, need: ServerRole) => Verdict;
+    open: boolean;
+};
+/** The authentication of one server: `identify` (who is this), `check` (may they, for a needed role) and `open` (the server has no tokens). */
+export type Auth = ReturnType<typeof createAuth>;

package/dist/server/src/auth.js

@@ -0,0 +1,59 @@
+/**
+ * @module Authentication and roles
+ *
+ * Who is asking, and may they. Tokens have a role (`read` < `publish` < `admin`) and are compared in constant time. Reading
+ * accepts a Bearer token or the browser's sign-in box (any user name, the token as the password); changing anything needs
+ * the Bearer header, because a browser sends the sign-in box's credentials to any page that asks, which would let another
+ * site upload with them. A server with no tokens is open, and refuses to listen beyond this machine unless told it may.
+ */
+import { timingSafeEqual } from 'node:crypto';
+const RANK = { read: 1, publish: 2, admin: 3 };
+function same(a, b) {
+    const left = Buffer.from(a), right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/**
+ * Who is asking, and may they. A server with no tokens is open (and refuses to listen beyond this machine
+ * unless told it may). With tokens, every request must carry one, except where `anonymousRead` lets anyone look.
+ *
+ * Changing anything needs a token in an `Authorization: Bearer` header, never the browser's sign-in box: the
+ * browser sends that box's credentials on its own to any page that asks, which would let another site upload
+ * with them.
+ */
+export function createAuth(tokens, anonymousRead) {
+    function identify(request) {
+        if (!tokens.length)
+            return { name: 'open', role: 'admin', via: 'none' };
+        const header = request.headers.get('authorization') ?? '';
+        const lower = header.toLowerCase();
+        let presented = null;
+        let via = 'bearer';
+        if (lower.startsWith('bearer '))
+            presented = header.slice(7).trim();
+        else if (lower.startsWith('basic ')) {
+            const decoded = Buffer.from(header.slice(6), 'base64').toString('utf8');
+            presented = decoded.slice(decoded.indexOf(':') + 1);
+            via = 'basic';
+        }
+        if (presented) {
+            const found = tokens.find(token => same(token.token, presented));
+            if (found)
+                return { name: found.name, role: found.role, via };
+        }
+        return anonymousRead ? { name: 'anonymous', role: 'read', via: 'none' } : null;
+    }
+    function check(request, need) {
+        const identity = identify(request);
+        if (!identity)
+            return { ok: false, status: 401, message: 'A token is needed. Send it as Authorization: Bearer <token>, or sign in with it as the password.' };
+        // Someone who showed no token is asked for one; someone whose token is too small is told so.
+        if (identity.name === 'anonymous' && need !== 'read')
+            return { ok: false, status: 401, message: 'A token is needed to upload. Send it as Authorization: Bearer <token>.' };
+        if (RANK[identity.role] < RANK[need])
+            return { ok: false, status: 403, message: `This token is "${identity.role}" and this needs "${need}".` };
+        if (need !== 'read' && identity.via === 'basic')
+            return { ok: false, status: 403, message: 'Uploading needs the token in an Authorization: Bearer header.' };
+        return { ok: true, identity };
+    }
+    return { identify, check, open: tokens.length === 0 };
+}

package/dist/server/src/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module Server configuration
+ *
+ * Loads how the server runs: `atlas.server.json`, then environment variables, then flags, each overriding the last, checked
+ * against `ServerConfigSchema` and resolved (paths made absolute, backends named, tokens read). Every mistake is a
+ * `ConfigError` that says what to change, and a server that would listen beyond this machine with no tokens refuses to
+ * start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is generated from it and a test proves
+ * each row.
+ *
+ * @see docs/server.md#configuration
+ */
+import { type ServerConfig, type ServerRole } from '../../schema/src/server-config.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** A token as the server holds it: the `name` it is shown under in logs, its `role`, and the secret `token`. */
+export type ResolvedToken = {
+    readonly name: string;
+    readonly role: ServerRole;
+    readonly token: string;
+};
+/** A backend as configured: its `id`, the `label` people see, and the `url` (a folder, `s3://…`, or another server) to open. */
+export type BackendSpec = {
+    readonly id: string;
+    readonly label: string;
+    readonly url: string;
+};
+/** The configuration the server runs with: the file, then the environment, then the flags, checked and resolved. */
+export type ResolvedServerConfig = Omit<ServerConfig, 'backends' | 'auth' | 'write'> & {
+    /** The folder that is the default backend, absolute. */
+    readonly data: string;
+    /** Every backend, the data folder first. All are read; uploads go to `writeId`. */
+    readonly backends: readonly BackendSpec[];
+    readonly writeId: string;
+    readonly tokens: readonly ResolvedToken[];
+    readonly anonymousRead: boolean;
+    readonly insecure: boolean;
+    /** Where the config came from, for the first line of the log. */
+    readonly configFile: string | null;
+};
+/** A configuration that cannot be used. The message says what to change; `atlas serve` prints it and exits 2. */
+export declare class ConfigError extends Error {
+}
+/** Every flag `atlas serve` accepts, with its `--`. */
+export declare const SERVER_FLAGS: readonly string[];
+/** One setting of the server as an operator meets it: the config key, the flag, the environment variables, and what it does. */
+export type ServerSetting = {
+    /** What it sets, in words. */
+    readonly summary: string;
+    /** The key in `atlas.server.json` (dotted for nested keys). */
+    readonly key: string;
+    /** The command-line flag, with its value placeholder, or null when there is none. */
+    readonly flag: string | null;
+    /** The environment variables, the first that is set wins; empty when there are none. */
+    readonly env: readonly string[];
+    /** What it is when nothing sets it. */
+    readonly default: string;
+    /**
+     * How the documentation is held to the code: giving `value` through the environment variable (or the flag) must make
+     * `read` of the resolved configuration equal `expected`. A test runs every setting's example both ways.
+     */
+    readonly example: {
+        readonly value: string;
+        readonly read: (config: ResolvedServerConfig) => unknown;
+        readonly expected: unknown;
+    };
+};
+/**
+ * Every setting that can be given by flag or environment, documented once. `docs/server.md` renders its table from
+ * this list, and a test proves each row: its example, through the flag and through the environment, changes the
+ * configuration as the row says. A setting added to the loader without a row here is therefore not documented in the
+ * table; one documented here that the loader ignores fails the test.
+ */
+export declare const SERVER_SETTINGS: readonly ServerSetting[];
+/** The text `atlas serve --help` prints. Also the source of the `atlas serve` section of `docs/reference/cli.md`. */
+export declare const SERVER_USAGE = "atlas serve: the Atlas server\n\n  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]\n              [--store <url|id=url>]... [--write <id>] [--site <dir>]\n              [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]\n              [--anonymous-read] [--insecure] [--no-log]\n\n  One process serves the viewer and the API. Test results are uploaded to it from anywhere (laptops, CI) and it\n  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more\n  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.\n\n  Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or \"auth.tokens\" in the config) are required\n  to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).\n";
+/**
+ * Read the file named by `--config`/`ATLAS_CONFIG`, or `atlas.server.json` in the folder if there is one, lay the
+ * environment and then the flags over it, and check the result. Every problem is a {@link ConfigError} that says
+ * what to change.
+ */
+export declare function loadServerConfig(argv: readonly string[], env: Env, cwd: string, read?: (file: string) => string): ResolvedServerConfig;
+/** A server that anyone on the network can upload to must say who may. */
+export declare function assertSafeToListen(config: Pick<ResolvedServerConfig, 'host' | 'tokens' | 'insecure'>): void;
+export {};