dsh-perm-gate 0.2.0 → 0.2.1-beta.3

package/lib/events.js

@@ -2,22 +2,236 @@
  * Gate decision events for dsh-perm-gate: a JSONL audit feed the browser half
  * polls so every automatic allow / ask / deny is visible in the conversation UI.
  *
+ * This module also owns the review-page data plane demonstrated by
+ * dsh-approval-gate: a per-event snapshot of the files a decision touched (the
+ * pre-change content), a line-level diff against the current content, and the
+ * revert / snapshot-management routes the approval-history view drives.
+ *
  * Pure append-only logging: every I/O error is swallowed (events are best-effort
  * and must never influence gating), and the id sequence resumes from the file on
  * first use so restarts never reuse an id the client has already seen.
  */
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 const REASON_MAX = 200;
+const JUSTIFICATION_MAX = 400;
+const FILES_MAX = 8;
+// Snapshot bounds: one file ≤256KB, ≤5 files per event.
+const SNAPSHOT_MAX_BYTES = 256 * 1024;
+const SNAPSHOT_MAX_FILES = 5;
+/** Text-file probe: binary payloads and oversized files are not snapshotted. */
+const SNAPSHOT_BINARY_RE = /[\x00-\x08\x0e-\x1f]/;
+function isSnapshotText(buf) {
+    if (buf.length > SNAPSHOT_MAX_BYTES)
+        return false;
+    const head = buf.subarray(0, Math.min(buf.length, 8192));
+    return !SNAPSHOT_BINARY_RE.test(head.toString('latin1'));
+}
+/** Read one file as snapshot text; null when unreadable, binary, or oversized. */
+export function readSnapshotFile(absPath) {
+    try {
+        const buf = readFileSync(absPath);
+        return isSnapshotText(buf) ? buf.toString('utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Device/pseudo files carry no reviewable content — never snapshotted. */
+function isDevicePath(absPath) {
+    return /^(\/dev\/|\/proc\/|\/sys\/)/.test(absPath)
+        || /^[A-Za-z]:[\\/](?:nul|con|prn|aux|com\d|lpt\d)$/i.test(absPath);
+}
+/**
+ * Resolve a path from a decision into an absolute path: `~` expands to home,
+ * absolute paths pass through, relative paths try the session cwd, the process
+ * cwd, then home (first existing wins; otherwise the first candidate).
+ */
+export function resolveAbsPath(p, baseDir) {
+    const raw = String(p ?? '');
+    if (raw === '')
+        return raw;
+    if (raw.startsWith('~'))
+        return join(homedir(), raw.slice(1));
+    if (raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw) || raw.startsWith('\\\\'))
+        return raw;
+    const candidates = [baseDir, process.cwd(), homedir()].filter((b) => typeof b === 'string' && b !== '');
+    const seen = new Set();
+    for (const b of candidates) {
+        const abs = join(b, raw);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        if (existsSync(abs))
+            return abs;
+    }
+    return join(candidates[0] ?? process.cwd(), raw);
+}
+/** Write the pre-change snapshot of every file one event touched. */
+export function saveEventSnapshots(dir, eventId, files, baseDir, sessionId, now = Date.now) {
+    if (files.length === 0)
+        return;
+    const snapshots = [];
+    const seen = new Set();
+    for (const f of files) {
+        if (snapshots.length >= SNAPSHOT_MAX_FILES)
+            break;
+        const abs = resolveAbsPath(f, baseDir);
+        if (abs === '' || seen.has(abs) || isDevicePath(abs))
+            continue;
+        seen.add(abs);
+        const content = readSnapshotFile(abs);
+        // Missing, binary, oversized, or empty content has no diff meaning.
+        if (content === null || content === '')
+            continue;
+        snapshots.push({ path: abs, content, ts: new Date(now()).toISOString() });
+    }
+    if (snapshots.length === 0)
+        return;
+    try {
+        mkdirSync(dir, { recursive: true });
+        const body = {
+            eventId,
+            sessionId: String(sessionId ?? ''),
+            cwd: baseDir ?? process.cwd(),
+            snapshots,
+        };
+        writeFileSync(join(dir, `${eventId}.json`), JSON.stringify(body, null, 2), 'utf8');
+    }
+    catch {
+        // snapshot persistence is best-effort; the event itself is already logged
+    }
+}
+/** Load one event's snapshots ([] when absent or corrupt). */
+export function loadEventSnapshots(dir, eventId) {
+    try {
+        const data = JSON.parse(readFileSync(join(dir, `${eventId}.json`), 'utf8'));
+        return Array.isArray(data.snapshots) ? data.snapshots : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether one snapshot file belongs to a session (no sessionId = legacy, never matches a filter). */
+function snapshotMatchesSession(absPath, sessionId) {
+    if (sessionId === '')
+        return true;
+    try {
+        const data = JSON.parse(readFileSync(absPath, 'utf8'));
+        return String(data.sessionId ?? '') === String(sessionId);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Line-level diff with context: a greedy in-order LCS approximation (each `a`
+ * line matches the next unused equal `b` line), then change windows of ±`CTX`
+ * context lines clustered into hunks. Ported from dsh-approval-gate so both
+ * review pages render identical diffs.
+ */
+export function diffLines(before, after, contextLines = 5) {
+    const CTX = Number.isInteger(contextLines) && contextLines >= 0 ? contextLines : 5;
+    const a = String(before ?? '').split('\n');
+    const b = String(after ?? '').split('\n');
+    const bPos = new Map();
+    for (let j = 0; j < b.length; j += 1) {
+        const list = bPos.get(b[j]);
+        if (list === undefined)
+            bPos.set(b[j], [j]);
+        else
+            list.push(j);
+    }
+    const aMatch = new Array(a.length).fill(-1);
+    const bUsed = new Array(b.length).fill(false);
+    let limit = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        const q = bPos.get(a[i]);
+        if (q === undefined)
+            continue;
+        for (const pos of q) {
+            if (pos >= limit && !bUsed[pos]) {
+                aMatch[i] = pos;
+                bUsed[pos] = true;
+                limit = pos + 1;
+                break;
+            }
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && aMatch[i] >= 0) {
+            const target = aMatch[i];
+            while (j < target) {
+                ops.push({ type: 'add', bNo: j + 1, text: b[j] });
+                j += 1;
+            }
+            ops.push({ type: 'same', aNo: i + 1, bNo: target + 1, text: a[i] });
+            j = target + 1;
+            i += 1;
+        }
+        else if (i < a.length) {
+            ops.push({ type: 'del', aNo: i + 1, text: a[i] });
+            i += 1;
+        }
+        else {
+            ops.push({ type: 'add', bNo: j + 1, text: b[j] });
+            j += 1;
+        }
+    }
+    const show = new Array(ops.length).fill(false);
+    for (let idx = 0; idx < ops.length; idx += 1) {
+        if (ops[idx].type === 'same')
+            continue;
+        for (let k = Math.max(0, idx - CTX); k <= Math.min(ops.length - 1, idx + CTX); k += 1)
+            show[k] = true;
+    }
+    const hunks = [];
+    let hiddenBefore = 0;
+    let pending = [];
+    let started = false;
+    for (let idx = 0; idx < ops.length; idx += 1) {
+        if (show[idx]) {
+            started = true;
+            pending.push(ops[idx]);
+        }
+        else {
+            if (started && pending.length > 0) {
+                hunks.push({ hiddenBefore, lines: pending });
+                pending = [];
+                started = false;
+            }
+            hiddenBefore += 1;
+        }
+    }
+    if (pending.length > 0 && started)
+        hunks.push({ hiddenBefore, lines: pending });
+    if (hunks.length > 0)
+        hunks[0] = { hiddenBefore: 0, lines: hunks[0].lines };
+    const added = ops.filter((o) => o.type === 'add').length;
+    const removed = ops.filter((o) => o.type === 'del').length;
+    return {
+        hunks,
+        stats: { added, removed, contextLines: Math.max(a.length, b.length) - (added + removed) },
+        changedLines: ops.filter((o) => o.type !== 'same').slice(0, 500),
+    };
+}
 export class EventLog {
     filePath;
     now;
+    snapshotsDir;
     seq = -1; // lazily restored from the file on first append
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
-    filePath, now = Date.now) {
+    filePath, now = Date.now, 
+    /** Snapshot directory; `undefined` disables diff/revert support. */
+    snapshotsDir = undefined) {
         this.filePath = filePath;
         this.now = now;
+        this.snapshotsDir = snapshotsDir;
     }
     /** Append one event; returns it, or undefined when recording is disabled/failed. */
     append(input) {
@@ -25,6 +239,9 @@ export class EventLog {
             return undefined;
         try {
             const id = this.nextId();
+            const files = input.files === undefined || input.files.length === 0
+                ? undefined
+                : input.files.slice(0, FILES_MAX);
             const ev = {
                 id,
                 ts: new Date(this.now()).toISOString(),
@@ -33,9 +250,22 @@ export class EventLog {
                 kind: input.kind,
                 ...(input.risk === undefined ? {} : { risk: input.risk }),
                 reason: String(input.reason).slice(0, REASON_MAX),
+                ...(input.verdict === undefined ? {} : { verdict: input.verdict }),
+                ...(input.justification === undefined ? {} : { justification: String(input.justification).slice(0, JUSTIFICATION_MAX) }),
+                ...(input.mode === undefined ? {} : { mode: input.mode }),
+                ...(input.category === undefined ? {} : { category: input.category }),
+                ...(files === undefined ? {} : { files }),
+                ...(input.learningCount === undefined ? {} : { learningCount: input.learningCount }),
+                ...(input.threshold === undefined ? {} : { threshold: input.threshold }),
             };
             mkdirSync(dirname(this.filePath), { recursive: true });
             appendFileSync(this.filePath, JSON.stringify(ev) + '\n', 'utf8');
+            // `auto`/`ask` are both "before the change lands" moments (an approved ask
+            // executes right after): snapshot the files so the review page can diff
+            // and revert them later.
+            if ((ev.kind === 'auto' || ev.kind === 'ask') && this.snapshotsDir !== undefined && files !== undefined) {
+                saveEventSnapshots(this.snapshotsDir, ev.id, files, input.baseDir, ev.sessionId, this.now);
+            }
             return ev;
         }
         catch {
@@ -73,6 +303,10 @@ export class EventLog {
         }
         return out;
     }
+    /** One event by id (undefined when absent). */
+    byId(id) {
+        return this.query().find((ev) => ev.id === id);
+    }
     nextId() {
         if (this.seq < 0) {
             this.seq = 0;
@@ -85,19 +319,53 @@ export class EventLog {
         return this.seq;
     }
 }
+function routeServer(server) {
+    if (typeof server !== 'object' || server === null)
+        return undefined;
+    const candidate = server;
+    return typeof candidate.register === 'function' ? server : undefined;
+}
+function json(res, code, body) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
+    res.end(JSON.stringify(body));
+}
+function readBody(req, limit = 1024 * 1024) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on?.('data', (chunk) => {
+            body += String(chunk);
+            if (body.length > limit)
+                reject(new Error('payload too large'));
+        });
+        req.on?.('error', (err) => reject(err instanceof Error ? err : new Error(String(err))));
+        req.on?.('end', () => {
+            try {
+                resolve(body === '' ? {} : JSON.parse(body));
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    });
+}
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
+export const LEARNING_ROUTE = '/api/dsh-perm-gate/learning';
+export const HEALTH_ROUTE = '/api/dsh-perm-gate/health';
+export const RECEIVER_ROUTE = '/api/dsh-perm-gate/receiver';
+export const DIFF_ROUTE = '/api/dsh-perm-gate/diff';
+export const REVERT_ROUTE = '/api/dsh-perm-gate/revert';
+export const SNAPSHOTS_STATS_ROUTE = '/api/dsh-perm-gate/snapshots-stats';
+export const SNAPSHOTS_CLEAR_ROUTE = '/api/dsh-perm-gate/snapshots-clear';
 /**
  * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
  * service. Returns whether the route was registered (false when the service is
  * unavailable — the host keeps running, only the HTTP API is missing).
  */
 export function registerEventsRoute(server, log) {
-    if (typeof server !== 'object' || server === null)
-        return false;
-    const candidate = server;
-    if (typeof candidate.register !== 'function')
-        return false;
-    candidate.register({
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
         kind: 'exact',
         path: EVENTS_ROUTE,
         handler: (rawReq, rawRes) => {
@@ -120,10 +388,307 @@ export function registerEventsRoute(server, log) {
             catch {
                 // unparseable URL: answer with the unfiltered tail
             }
-            const events = log.query({ sessionId, since });
-            res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
-            res.end(JSON.stringify({ events }));
+            json(res, 200, { events: log.query({ sessionId, since }) });
+        },
+    });
+}
+/**
+ * Register the review-page routes:
+ * `GET  /diff?eventId=&path=`        → before/after line diff for one file
+ * `POST /revert`                     → deliver a revert instruction into the session
+ * `GET  /snapshots-stats?sessionId=` → snapshot count/bytes/ids/file map
+ * `POST /snapshots-clear`            → drop snapshots (session-scoped or all)
+ */
+export function registerReviewRoutes(server, deps) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return [];
+    const { log, snapshotsDir, send, audit } = deps;
+    const offs = [];
+    offs.push(ws.register({
+        kind: 'exact',
+        path: DIFF_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            try {
+                if (req.method !== 'GET' && req.method !== 'HEAD') {
+                    json(res, 405, { ok: false, error: 'method not allowed' });
+                    return;
+                }
+                if (snapshotsDir === undefined) {
+                    json(res, 404, { ok: false, error: '快照目录未配置' });
+                    return;
+                }
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const eventId = Number.parseInt(url.searchParams.get('eventId') ?? '', 10);
+                const path = url.searchParams.get('path') ?? '';
+                if (!Number.isInteger(eventId) || path === '') {
+                    json(res, 400, { ok: false, error: 'eventId/path 必填' });
+                    return;
+                }
+                const snaps = loadEventSnapshots(snapshotsDir, eventId);
+                // The client sends the raw path recorded on the event (absolute,
+                // relative, or a bare name): align it against the snapshot's absolute
+                // path, falling back to a suffix/basename match.
+                const base = resolveAbsPath(path);
+                const baseName = path.split(/[\\/]/).pop() ?? '';
+                const snap = snaps.find((s) => s.path === base || s.path === path)
+                    ?? snaps.find((s) => s.path.endsWith('/' + path)
+                        || (baseName !== '' && (s.path.endsWith('/' + baseName) || s.path.endsWith('\\' + baseName))));
+                if (snap === undefined) {
+                    json(res, 404, { ok: false, error: '该事件没有此文件的快照' });
+                    return;
+                }
+                const after = readSnapshotFile(snap.path);
+                const result = diffLines(snap.content, after);
+                json(res, 200, {
+                    ok: true,
+                    path,
+                    eventId,
+                    beforeExists: true,
+                    afterExists: after !== null,
+                    changedLines: result.changedLines,
+                    hunks: result.hunks,
+                    stats: result.stats,
+                });
+            }
+            catch (e) {
+                json(res, 400, { ok: false, error: String(e?.message ?? e) });
+            }
+        },
+    }));
+    offs.push(ws.register({
+        kind: 'exact',
+        path: REVERT_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const body = await readBody(req);
+                    const sessionId = String(body.sessionId ?? '');
+                    const eventId = Number.parseInt(String(body.eventId ?? ''), 10);
+                    if (sessionId === '' || !Number.isInteger(eventId)) {
+                        json(res, 400, { ok: false, error: 'sessionId/eventId 必填' });
+                        return;
+                    }
+                    const event = log.byId(eventId);
+                    if (event === undefined) {
+                        json(res, 404, { ok: false, error: '未找到该事件' });
+                        return;
+                    }
+                    const files = (event.files ?? []).map((f) => '`' + f + '`').join('、');
+                    const snaps = snapshotsDir === undefined ? [] : loadEventSnapshots(snapshotsDir, eventId);
+                    const snapHint = snaps.length > 0
+                        ? '改动前的文件内容快照保存在 ' + snapshotsDir + '（按事件 ID 命名），可参考恢复；请确认改动内容后执行撤销。'
+                        : '注意：该事件已无可用快照（可能已被清除），请基于当前文件内容判断如何恢复原状；无法确定时请先说明再操作。';
+                    const content = '请撤销以下自动放行操作带来的文件改动（恢复为审批前的状态）：\n'
+                        + '- 操作：' + (event.justification ?? event.reason ?? '(无说明)') + '\n'
+                        + '- 涉及文件：' + (files !== '' ? files : '(未知)') + '\n'
+                        + '- 判定：' + (event.verdict ?? event.kind) + '（自动放行）\n'
+                        + '- 事件时间：' + event.ts + '\n'
+                        + snapHint;
+                    const result = await send(sessionId, content);
+                    audit?.(`REVERT  event=${eventId} session=${sessionId} via=${result.via ?? 'none'}`);
+                    json(res, result.ok ? 200 : 500, result);
+                }
+                catch (e) {
+                    json(res, 400, { ok: false, error: String(e?.message ?? e) });
+                }
+            })();
+        },
+    }));
+    offs.push(ws.register({
+        kind: 'exact',
+        path: SNAPSHOTS_STATS_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            try {
+                if (snapshotsDir === undefined) {
+                    json(res, 200, { ok: true, count: 0, bytes: 0, ids: [], files: {}, sessionId: null });
+                    return;
+                }
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const filterSession = url.searchParams.get('sessionId') ?? '';
+                let count = 0;
+                let bytes = 0;
+                const ids = [];
+                const files = {};
+                for (const name of readdirSafe(snapshotsDir)) {
+                    if (!name.endsWith('.json'))
+                        continue;
+                    const abs = join(snapshotsDir, name);
+                    if (filterSession !== '' && !snapshotMatchesSession(abs, filterSession))
+                        continue;
+                    const id = name.slice(0, -'.json'.length);
+                    count += 1;
+                    ids.push(id);
+                    bytes += statSize(abs);
+                    try {
+                        const data = JSON.parse(readFileSync(abs, 'utf8'));
+                        if (Array.isArray(data.snapshots)) {
+                            files[id] = data.snapshots.map((s) => String(s?.path ?? '')).filter((p) => p !== '');
+                        }
+                    }
+                    catch {
+                        // corrupt snapshot file: still counted, no file map
+                    }
+                }
+                json(res, 200, { ok: true, count, bytes, ids, files, sessionId: filterSession !== '' ? filterSession : null });
+            }
+            catch (e) {
+                json(res, 400, { ok: false, error: String(e?.message ?? e) });
+            }
+        },
+    }));
+    offs.push(ws.register({
+        kind: 'exact',
+        path: SNAPSHOTS_CLEAR_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const body = await readBody(req);
+                    const filterSession = String(body.sessionId ?? '');
+                    let removed = 0;
+                    if (snapshotsDir !== undefined) {
+                        for (const name of readdirSafe(snapshotsDir)) {
+                            if (!name.endsWith('.json'))
+                                continue;
+                            const abs = join(snapshotsDir, name);
+                            if (filterSession !== '' && !snapshotMatchesSession(abs, filterSession))
+                                continue;
+                            try {
+                                rmSync(abs, { force: true });
+                                removed += 1;
+                            }
+                            catch {
+                                // skip unremovable entry
+                            }
+                        }
+                    }
+                    audit?.(`CONFIG  snapshots-clear session=${filterSession !== '' ? filterSession : '*'} removed=${removed}`);
+                    json(res, 200, { ok: true, removed, sessionId: filterSession !== '' ? filterSession : null });
+                }
+                catch (e) {
+                    json(res, 400, { ok: false, error: String(e?.message ?? e) });
+                }
+            })();
+        },
+    }));
+    return offs;
+}
+function readdirSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function statSize(absPath) {
+    try {
+        return statSync(absPath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Register `GET /api/dsh-perm-gate/receiver` — the receiver projection for the
+ * settings card: the effective provider/model plus (host mode) the live
+ * provider/model-group catalog from the DSH `llm` service.
+ */
+export function registerReceiverRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: RECEIVER_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET' && req.method !== 'HEAD') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            provider.info().then((info) => json(res, 200, { ok: true, ...info }), (e) => json(res, 500, { ok: false, error: String(e?.message ?? e) }));
+        },
+    });
+}
+/**
+ * Register `POST /api/dsh-perm-gate/health` — runs one minimal completion
+ * through the currently configured llmAssist receiver and returns
+ * `{ ok, ms, detail }` (the settings card's health test).
+ */
+export function registerHealthRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: HEALTH_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            provider.check().then((result) => json(res, 200, { ...result, ok: true }), (e) => json(res, 500, { ok: false, error: String(e?.message ?? e) }));
+        },
+    });
+}
+/**
+ * Register the learning-store routes on the webServer service:
+ * `GET  /api/dsh-perm-gate/learning` → the store snapshot + live threshold,
+ * `POST /api/dsh-perm-gate/learning` → `{ key, fp? }` terminates one key's
+ * learning or drops one sedimented sample. Returns whether registered.
+ */
+export function registerLearningRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: LEARNING_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method === 'GET' || req.method === 'HEAD') {
+                json(res, 200, { ok: true, threshold: provider.threshold(), ...provider.snapshot() });
+                return;
+            }
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const parsed = await readBody(req);
+                    if (typeof parsed.key !== 'string' || parsed.key === '') {
+                        json(res, 400, { ok: false, error: 'missing key' });
+                        return;
+                    }
+                    provider.reset(parsed.key, typeof parsed.fp === 'string' && parsed.fp !== '' ? parsed.fp : undefined);
+                    json(res, 200, { ok: true });
+                }
+                catch (e) {
+                    json(res, 400, { ok: false, error: String(e?.message ?? e) });
+                }
+            })();
         },
     });
-    return true;
 }