zigmini 0.8.0-beta.6 → 0.9.0-beta.1

package/src/security-check.ts

@@ -0,0 +1,559 @@
+import { entropy, isAllowed, type AllowEntry, type Rule } from "../scripts/secret-rules.ts";
+import ruleConfig from "../scripts/secret-scan.rules.json";
+import allowConfig from "../scripts/secret-scan.allow.json";
+import { readVoiceSetting, writeVoiceSetting } from "./voice-setting.ts";
+import { isDeepStrictEqual } from "node:util";
+import { canonicalSecurityValue, SecurityRuntimeError, type HeldState, type SecurityApprover, type SecurityHoldRecord, type SecurityIntent, type SecurityReceipt } from "./security-allow.ts";
+import type { Store } from "./store.ts";
+export type { HeldState, AllowedValue } from "./security-allow.ts";
+
+// Improvement 165: every user text bound for the engine passes one security check first (work 779e5b0e).
+// The rules, the allow list and the matching helpers are the repository security check's own (scripts/secret-rules.ts,
+// scripts/secret-scan.rules.json, scripts/secret-scan.allow.json; docs/security-check.md). Detector expressions compile
+// once. Runtime approvals use the gateway-owned Store; unapproved originals stay in memory.
+
+export type SecurityRule = Rule;
+export type SecurityAllow = AllowEntry;
+/** One kind of finding and its count; the form that may reach logs. */
+export interface SecurityFinding { readonly kind: string; readonly label: string; readonly count: number }
+/** One matched value and where it is (1-based line and column of text `text`). Only the user's own screens get these. */
+export interface SecurityOccurrence {
+	readonly kind: string;
+	readonly label: string;
+	readonly value: string;
+	readonly text: number;
+	readonly line: number;
+	readonly column: number;
+	readonly canonicalValue?: string;
+	readonly ruleId?: string;
+	readonly start?: number;
+	readonly end?: number;
+}
+/** A message held back by the check until the user sends or drops it; kept in gateway memory only. */
+export interface HeldMessage extends HeldState {
+	readonly findings: readonly SecurityFinding[];
+	readonly occurrences: readonly SecurityOccurrence[];
+	/** The user's own text, so the screen can put it back into the composer when the message is dropped or lost. */
+	readonly draft?: string;
+}
+export type HeldDetail = HeldState & Partial<Pick<HeldMessage, "findings" | "occurrences" | "draft">>;
+export interface HeldContext {
+	readonly key?: string;
+	readonly snapshot?: unknown;
+	readonly originalDecisionId?: string;
+	readonly submissionId?: string;
+}
+export type HeldSend = (receipt: (ref: SecurityReceipt) => void) => Promise<void>;
+export interface MessageGuardOptions {
+	readonly store: Store;
+	readonly receiptTimeoutMs?: number;
+	readonly state?: (state: HeldState) => void;
+	readonly allowedUpdated?: (revision: number) => void;
+	readonly decisionUpdated?: () => void;
+}
+
+export const SECURITY_CHECK_PATH = "/api/settings/security-check";
+export const SECURITY_BLOCKED = "security_check_blocked";
+export const SECURITY_HELD_PATH = "/api/security-check/held";
+
+/** User-facing names of the finding kinds; rule ids without an entry fall back to "기타 보안 값". */
+const KIND_OF_RULE: Readonly<Record<string, string>> = {
+	"private-key": "private-key",
+	"ssh-public-key": "private-key",
+	"github-token": "token", "npm-token": "token", "anthropic-key": "token", "openai-key": "token", "notion-token": "token",
+	"slack-token": "token", "slack-webhook": "token", "aws-access-key": "token", "gcp-api-key": "token", "tailscale-key": "token",
+	"jwt": "token", "high-entropy-assignment": "token",
+	"credential-assignment": "credential", "authorization": "credential", "cookie-header": "credential",
+	"user-home-path": "home-path",
+	"ipv4": "internal-address", "ipv6-internal": "internal-address", "internal-host": "internal-address", "internal-url": "internal-address",
+	"email": "email", "phone-number": "phone",
+	"adb-device": "device-id", "device-serial": "device-id",
+};
+export const KIND_LABELS: Readonly<Record<string, string>> = {
+	"private-key": "비밀키",
+	"token": "토큰·API 키",
+	"credential": "비밀번호·인증·쿠키 값",
+	"home-path": "홈 폴더 경로",
+	"internal-address": "내부 IP·호스트",
+	"email": "이메일 주소",
+	"phone": "전화번호",
+	"device-id": "기기 식별값",
+	"other": "기타 보안 값",
+};
+
+interface Compiled { readonly id: string; readonly kind: string; readonly regex: RegExp; readonly group: number; readonly minEntropy?: number }
+
+/** The repository rules and allow list, as shipped in the package. */
+export function defaultChecker(): SecurityChecker {
+	return new SecurityChecker(ruleConfig.rules as Rule[], allowConfig.allow as AllowEntry[]);
+}
+
+/** Compiles every rule once; scan() reuses the compiled expressions for every message. */
+export class SecurityChecker {
+	private readonly rules: readonly Compiled[];
+
+	constructor(rules: readonly SecurityRule[], private readonly allow: readonly SecurityAllow[] = []) {
+		this.rules = rules.map((rule) => ({
+			id: rule.id,
+			kind: KIND_OF_RULE[rule.id] ?? "other",
+			regex: new RegExp(rule.pattern, `${(rule.flags ?? "").replace(/[gyd]/g, "")}dg`),
+			group: rule.group ?? 0,
+			...(rule.minEntropy === undefined ? {} : { minEntropy: rule.minEntropy }),
+		}));
+	}
+
+	/** Counts per kind over all texts, in KIND_LABELS order; empty when nothing matched. */
+	scan(texts: readonly string[]): SecurityFinding[] {
+		return countFindings(this.occurrences(texts));
+	}
+
+	/** Every matched value with its place, in text order then rule order. */
+	occurrences(texts: readonly string[]): SecurityOccurrence[] {
+		return this.detect(texts, false);
+	}
+
+	runtimeOccurrences(texts: readonly string[]): SecurityOccurrence[] {
+		return this.detect(texts, true);
+	}
+
+	private detect(texts: readonly string[], runtime: boolean): SecurityOccurrence[] {
+		const found: SecurityOccurrence[] = [];
+		for (const [index, text] of texts.entries()) {
+			if (!text) continue;
+			for (const rule of this.rules) {
+				const regex = rule.regex;
+				regex.lastIndex = 0;
+				let match: RegExpExecArray | null;
+				while ((match = regex.exec(text)) !== null) {
+					if (match[0].length === 0) regex.lastIndex += 1;
+					const value = match[rule.group];
+					if (!value) continue;
+					if (rule.minEntropy !== undefined && entropy(value) < rule.minEntropy) continue;
+					if (isAllowed(rule.id, value, this.allow)) continue;
+					const at = match.index + (rule.group === 0 ? 0 : match[0].indexOf(value));
+					const start = match.indices?.[rule.group]?.[0] ?? at;
+					const end = match.indices?.[rule.group]?.[1] ?? start + value.length;
+					const before = text.slice(0, at);
+					const line = before.split("\n").length;
+					found.push({ kind: rule.kind, label: KIND_LABELS[rule.kind]!, value, text: index, line, column: at - before.lastIndexOf("\n"),
+						...(runtime ? { ruleId: rule.id, start, end,
+							canonicalValue: canonicalSecurityValue(text, rule.id, start, end) } : {}),
+					});
+				}
+			}
+		}
+		return found;
+	}
+}
+
+export function countFindings(occurrences: readonly SecurityOccurrence[]): SecurityFinding[] {
+	const counts = new Map<string, number>();
+	for (const occurrence of occurrences) counts.set(occurrence.kind, (counts.get(occurrence.kind) ?? 0) + 1);
+	return Object.keys(KIND_LABELS).filter((kind) => counts.has(kind))
+		.map((kind) => ({ kind, label: KIND_LABELS[kind]!, count: counts.get(kind)! }));
+}
+
+/** "토큰·API 키 2건, 홈 폴더 경로 1건" */
+export function findingSummary(findings: readonly SecurityFinding[]): string {
+	return findings.map((finding) => `${finding.label} ${finding.count}건`).join(", ");
+}
+
+export function blockedMessage(findings: readonly SecurityFinding[]): string {
+	return `보안검사에 걸려 엔진에 보내지 않고 보류했습니다: ${findingSummary(findings)}.`;
+}
+
+/** Thrown for a held decision answer; `held` (with the values) goes only to the user's screen that sent it. */
+export class SecurityCheckError extends Error {
+	readonly code = SECURITY_BLOCKED;
+	constructor(readonly held: HeldMessage) {
+		super(blockedMessage(held.findings));
+	}
+}
+
+/**
+ * The on/off setting (default on) and the checker. The setting file uses the voice setting format ("off" means off,
+ * anything else or a missing file means on); it is read once at start and kept in memory, so a check reads no disk.
+ */
+export class MessageGuard {
+	private on: boolean;
+	private readonly held = new Map<string, { info: HeldMessage; send: HeldSend; snapshot: unknown }>();
+	private readonly memory = new Map<string, SecurityHoldRecord>();
+	private readonly flights = new Map<string, Promise<void>>();
+	private readonly failures = new Map<string, SecurityRuntimeError>();
+	private readonly alarms = new Map<string, ReturnType<typeof setTimeout>>();
+	private readonly waiters = new Map<string, Set<() => void>>();
+	private reconciling = false;
+	private readonly unsubscribe?: () => void;
+
+	/** `onHold` sends each new held entry (with its values) straight to the user's screens; never to omo or the store. */
+	constructor(private readonly checker: SecurityChecker, readonly file: string | null, private readonly onHold: (held: HeldMessage) => void = () => {}, private readonly options?: MessageGuardOptions) {
+		this.on = file === null ? true : readVoiceSetting(file);
+		if (options) {
+			for (const record of options.store.securityHolds()) {
+				this.memory.set(record.state.id, record);
+				if (record.state.status === "pending" || record.state.status === "processing") {
+					options.store.updateSecurityHold(record.state.id, record.dispatchReserved
+						? { status: "unconfirmed", errorCode: "dispatch_unknown" } : { status: "failed", errorCode: "payload_lost" });
+				}
+			}
+			this.unsubscribe = options.store.onSecurityReceipt(() => this.reconcile());
+			this.reconcile();
+		}
+	}
+
+	enabled(): boolean {
+		return this.on;
+	}
+
+	set(enabled: boolean): boolean {
+		if (this.file !== null) writeVoiceSetting(this.file, enabled);
+		this.on = enabled;
+		return enabled;
+	}
+
+	/** Matched values of the texts, or null when the check is off or nothing matched. */
+	check(texts: readonly string[]): SecurityOccurrence[] | null {
+		if (!this.on) return null;
+		const found = this.checker.runtimeOccurrences(texts);
+		if (found.length === 0) return null;
+		let allowed: Set<string>;
+		try { allowed = new Set(this.options?.store.securityAllowedValues().values.map((entry) => entry.value) ?? []); }
+		catch { throw new SecurityRuntimeError("allowlist_persist_failed"); }
+		if (found.length > 0 && found.every((occurrence) => allowed.has(occurrence.canonicalValue ?? occurrence.value))) return null;
+		return found.length > 0 ? found : null;
+	}
+
+	/** Called before filtering: an old source key never becomes a second transmission. */
+	existing(context: HeldContext): HeldDetail | null {
+		if (!context.key) return null;
+		let record: SecurityHoldRecord | null | undefined;
+		try { record = this.options ? this.options.store.securityHoldByKey(context.key) : [...this.memory.values()].find((r) => r.key === context.key); }
+		catch { throw new SecurityRuntimeError("state_persist_failed"); }
+		if (!record) return null;
+		const live = this.held.get(record.state.id);
+		if (live && !isDeepStrictEqual(live.snapshot, context.snapshot)) throw new SecurityRuntimeError("held_conflict", record.state);
+		if (live) this.onHold({ ...live.info, ...record.state });
+		else this.options?.state?.(record.state);
+		return this.detail(record.state.id);
+	}
+
+	/** Keeps the original and `send` in memory; the Store receives only the opaque hold record. */
+	hold(conv: string, source: HeldMessage["source"], occurrences: readonly SecurityOccurrence[], send: HeldSend, draft?: string, context: HeldContext = {}): HeldMessage {
+		const prior = this.existing(context);
+		if (prior) {
+			const live = this.held.get(prior.id);
+			if (live) return { ...live.info, ...prior };
+			throw new SecurityRuntimeError("held_conflict", prior);
+		}
+		const id = crypto.randomUUID();
+		const info: HeldMessage = {
+			id, decisionId: id, revision: 1, conv, source, createdAt: new Date().toISOString(),
+			originalDecisionId: context.originalDecisionId ?? null, status: "pending", submissionId: context.submissionId ?? null,
+			remembered: false, allowlistRevision: this.options?.store.securityAllowedValues().revision ?? 0, errorCode: null,
+			findings: countFindings(occurrences), occurrences: occurrences.map(({ ruleId: _rule, start: _start, end: _end, ...occurrence }) => occurrence),
+			...(draft === undefined ? {} : { draft }),
+		};
+		const record: SecurityHoldRecord = { state: this.state(info), key: context.key ?? null, intent: null, dispatchReserved: false, receipt: null };
+		try {
+			if (this.options) this.options.store.createSecurityHold(record);
+			this.memory.set(id, record);
+		} catch {
+			throw new SecurityRuntimeError("state_persist_failed");
+		}
+		this.held.set(info.id, { info, send, snapshot: structuredClone(context.snapshot) });
+		this.onHold(info);
+		this.changed(info.id);
+		return info;
+	}
+
+	/** Held when check() finds anything: throws SecurityCheckError with the held entry. */
+	holdOrPass(conv: string, source: HeldMessage["source"], texts: readonly string[], send: HeldSend, context: HeldContext = {}): void {
+		const prior = this.existing(context);
+		if (prior) {
+			const live = this.held.get(prior.id);
+			if (live) throw new SecurityCheckError({ ...live.info, ...prior });
+			throw new SecurityRuntimeError("held_conflict", prior);
+		}
+		const found = this.check(texts);
+		if (found) throw new SecurityCheckError(this.hold(conv, source, found, send, undefined, context));
+	}
+
+	list(): HeldMessage[] {
+		return [...this.held.values()].flatMap((entry) => {
+			const state = this.record(entry.info.id)?.state;
+			return state && (state.status === "pending" || state.status === "processing") ? [{ ...entry.info, ...state }] : [];
+		});
+	}
+
+	private state(info: HeldMessage): HeldState {
+		const { findings: _findings, occurrences: _occurrences, draft: _draft, ...state } = info;
+		return state;
+	}
+
+	private record(id: string): SecurityHoldRecord | null {
+		if (!this.options) return this.memory.get(id) ?? null;
+		try {
+			const record = this.options.store.securityHold(id);
+			if (record) this.memory.set(id, record);
+			return record;
+		} catch { throw new SecurityRuntimeError("state_persist_failed", this.memory.get(id)?.state); }
+	}
+
+	detail(id: string): HeldDetail | null {
+		this.reconcile();
+		const record = this.record(id);
+		if (!record) return null;
+		const live = this.held.get(id);
+		return live && (record.state.status === "pending" || record.state.status === "processing")
+			? { ...live.info, ...record.state } : record.state;
+	}
+
+	private changed(id: string): void {
+		const record = this.record(id);
+		if (!record) return;
+		this.options?.state?.(record.state);
+		this.options?.decisionUpdated?.();
+		if (!["pending", "processing"].includes(record.state.status)) {
+			if (record.state.status === "sent") this.failures.delete(id);
+			this.held.delete(id);
+			const alarm = this.alarms.get(id);
+			if (alarm) clearTimeout(alarm);
+			this.alarms.delete(id);
+			for (const resolve of this.waiters.get(id) ?? []) resolve();
+			this.waiters.delete(id);
+		}
+	}
+
+	private update(id: string, change: Parameters<Store["updateSecurityHold"]>[1], receipt?: SecurityReceipt, intent?: SecurityIntent): void {
+		if (this.options) this.memory.set(id, this.options.store.updateSecurityHold(id, change, receipt, intent));
+		else {
+			const record = this.record(id);
+			if (!record) return;
+			this.memory.set(id, { ...record, ...(receipt ? { receipt } : {}), state: { ...record.state, ...change, revision: record.state.revision + 1 } });
+		}
+		this.changed(id);
+	}
+
+	reconcile(): void {
+		if (!this.options || this.reconciling) return;
+		this.reconciling = true;
+		try {
+			for (const record of this.options.store.securityHolds()) {
+				if (!record.receipt || !["processing", "unconfirmed"].includes(record.state.status)) continue;
+				const status = this.options.store.securityReceipt(record.receipt);
+				if (status && status !== record.state.status) {
+					this.update(record.state.id, { status, errorCode: status === "sent" ? null : "dispatch_unknown" });
+				}
+			}
+		} finally { this.reconciling = false; }
+	}
+
+	async resolve(id: string, intent: SecurityIntent, approver: SecurityApprover): Promise<HeldState | null> {
+		this.reconcile();
+		const initial = this.record(id);
+		if (!initial) return null;
+		const previousFailure = this.failures.get(id);
+		if (previousFailure) throw previousFailure;
+		let claimed: { record: SecurityHoldRecord; fresh: boolean };
+		try {
+			if (this.options) claimed = this.options.store.claimSecurityHold(id, intent);
+			else {
+				if (initial.intent && !isDeepStrictEqual(initial.intent, intent)) throw new SecurityRuntimeError("held_conflict", initial.state);
+				if (!initial.intent && (initial.state.status !== "pending" ||
+					(intent.expectedRevision !== null && intent.expectedRevision !== initial.state.revision))) throw new SecurityRuntimeError("held_conflict", initial.state);
+				claimed = { record: initial, fresh: initial.intent === null };
+				if (claimed.fresh) {
+					const record = { ...initial, intent, state: { ...initial.state, status: intent.send ? "processing" as const : "cancelled" as const, revision: initial.state.revision + 1 } };
+					this.memory.set(id, record);
+					claimed = { record, fresh: true };
+				}
+			}
+		} catch (error) {
+			if (error instanceof SecurityRuntimeError) throw error;
+			this.failPersistence(id, "state_persist_failed", intent);
+		}
+		if (claimed.fresh) {
+			this.changed(id);
+			if (intent.send) {
+				const entry = this.held.get(id);
+				if (!entry) this.failPersistence(id, "state_persist_failed");
+				try {
+					if (this.options) {
+						const before = this.options.store.securityAllowedValues().revision;
+						const reserved = this.options.store.reserveSecurityDispatch(id, entry.info.occurrences, approver);
+						this.changed(id);
+						if (reserved.state.allowlistRevision !== before) this.options.allowedUpdated?.(reserved.state.allowlistRevision);
+					}
+				} catch {
+					this.failPersistence(id, intent.remember ? "allowlist_persist_failed" : "state_persist_failed");
+				}
+				const flight = this.dispatch(id).finally(() => this.flights.delete(id));
+				this.flights.set(id, flight);
+				// A storage outage may prevent even a terminal record. Retain the durable reservation, never replay.
+				void flight.catch(() => {
+					this.failures.set(id, new SecurityRuntimeError("state_persist_failed", this.memory.get(id)?.state));
+					for (const resolve of this.waiters.get(id) ?? []) resolve();
+					this.waiters.delete(id);
+				});
+			}
+		}
+		// New clients receive the durable claim immediately. Legacy waits only for receipt or its bound.
+		if (intent.expectedRevision === null && this.record(id)?.state.status === "processing") {
+			await new Promise<void>((resolve) => {
+				const set = this.waiters.get(id) ?? new Set<() => void>();
+				set.add(resolve);
+				this.waiters.set(id, set);
+				if (this.record(id)?.state.status !== "processing") { set.delete(resolve); resolve(); }
+			});
+		}
+		const failure = this.failures.get(id);
+		if (failure) throw failure;
+		return this.record(id)?.state ?? null;
+	}
+
+	private failPersistence(id: string, code: "state_persist_failed" | "allowlist_persist_failed", intent?: SecurityIntent): never {
+		this.failures.set(id, new SecurityRuntimeError(code, this.memory.get(id)?.state));
+		try { this.update(id, { status: "failed", errorCode: code }, undefined, intent); }
+		catch { throw new SecurityRuntimeError(code, this.memory.get(id)?.state); }
+		const failure = new SecurityRuntimeError(code, this.memory.get(id)?.state);
+		this.failures.set(id, failure);
+		throw failure;
+	}
+
+	private async dispatch(id: string): Promise<void> {
+		const entry = this.held.get(id);
+		if (!entry) { this.update(id, { status: "failed", errorCode: "payload_lost" }); return; }
+		const timer = setTimeout(() => {
+			try {
+				if (this.record(id)?.state.status === "processing") this.update(id, { status: "unconfirmed", errorCode: "dispatch_unknown" });
+			} catch {
+				this.failures.set(id, new SecurityRuntimeError("state_persist_failed"));
+				for (const resolve of this.waiters.get(id) ?? []) resolve();
+				this.waiters.delete(id);
+			}
+		}, this.options?.receiptTimeoutMs ?? 30_000);
+		timer.unref();
+		this.alarms.set(id, timer);
+		try {
+			await entry.send((receipt) => {
+				try { this.update(id, {}, receipt); }
+				catch { throw new SecurityRuntimeError("state_persist_failed", this.memory.get(id)?.state); }
+			});
+			if (!this.options) this.update(id, { status: "sent", errorCode: null });
+			else this.reconcile();
+		} catch (error) {
+			if (this.record(id)?.state.status === "sent") return;
+			if (error instanceof SecurityRuntimeError && error.code === "state_persist_failed") {
+				this.failPersistence(id, "state_persist_failed");
+			}
+			const conflict = error instanceof Error && ["decision_conflict", "submission_conflict", "decision_not_found", "invalid_decision_answer"].includes(error.message);
+			const unsent = error instanceof SecurityRuntimeError && error.code === "dispatch_failed";
+			this.update(id, { status: conflict || unsent ? "failed" : "unconfirmed", errorCode: conflict ? "original_decision_conflict" : unsent ? "dispatch_failed" : "dispatch_unknown" });
+		}
+	}
+
+	stop(): void {
+		this.unsubscribe?.();
+		for (const timer of this.alarms.values()) clearTimeout(timer);
+		this.alarms.clear();
+		this.held.clear();
+	}
+
+	/** Removes the entry; "sent" runs its send. null when the id is unknown (already decided, or lost by a restart). */
+	async decide(id: string, send: boolean): Promise<"sent" | "dropped" | null> {
+		if (!this.held.has(id)) return null;
+		const state = await this.resolve(id, { send, remember: false, expectedRevision: null, submissionId: null }, { client: "web", deviceId: null });
+		return state?.status === "sent" ? "sent" : state?.status === "cancelled" ? "dropped" : null;
+	}
+}
+
+/** GET (both ports) and PUT (trusted web port) of SECURITY_CHECK_PATH. */
+export async function handleSecurityCheckSetting(
+	req: Request,
+	trusted: boolean,
+	guard: Pick<MessageGuard, "enabled" | "set">,
+	publish: (enabled: boolean) => void,
+): Promise<Response | null> {
+	if (req.method === "GET") return Response.json({ enabled: guard.enabled() });
+	if (req.method !== "PUT") return null;
+	if (!trusted) return Response.json({ error: "forbidden" }, { status: 403 });
+	const body = (await req.json().catch(() => null)) as { enabled?: unknown } | null;
+	if (typeof body?.enabled !== "boolean") return Response.json({ error: "enabled_required" }, { status: 400 });
+	const enabled = guard.set(body.enabled);
+	publish(enabled);
+	return Response.json({ enabled });
+}
+
+/** GET SECURITY_HELD_PATH lists held messages; POST SECURITY_HELD_PATH/<id> {send} sends or drops one. */
+export async function handleHeld(
+	req: Request,
+	url: URL,
+	guard: Pick<MessageGuard, "list" | "detail" | "resolve">,
+	resolved: (id: string, outcome: "sent" | "dropped") => void,
+	approver: SecurityApprover = { client: "web", deviceId: null },
+): Promise<Response | null> {
+	const json = (value: unknown, status = 200) => Response.json(value, { status, headers: { "Cache-Control": "no-store" } });
+	if (url.pathname === SECURITY_HELD_PATH) {
+		try { return req.method === "GET" ? json({ held: guard.list() }) : null; }
+		catch { return json({ error: "state_persist_failed" }, 503); }
+	}
+	if (!url.pathname.startsWith(`${SECURITY_HELD_PATH}/`)) return null;
+	const id = decodeURIComponent(url.pathname.slice(SECURITY_HELD_PATH.length + 1));
+	if (req.method === "GET") {
+		try {
+			const detail = guard.detail(id);
+			return detail ? json(detail) : json({ error: "held_not_found" }, 404);
+		} catch { return json({ error: "state_persist_failed" }, 503); }
+	}
+	if (req.method !== "POST") return null;
+	const body: unknown = await req.json().catch(() => null);
+	if (typeof body !== "object" || body === null || !("send" in body) || typeof body.send !== "boolean") return json({ error: "invalid_held_request" }, 400);
+	const remember = "remember" in body ? body.remember : undefined;
+	if (body.send && remember !== undefined && typeof remember !== "boolean") return json({ error: "invalid_held_request" }, 400);
+	const hasRevision = "expectedRevision" in body;
+	const hasSubmission = "submissionId" in body;
+	const expectedRevision = hasRevision ? body.expectedRevision : null;
+	const submissionId = hasSubmission ? body.submissionId : null;
+	if (hasRevision !== hasSubmission ||
+		(hasRevision && (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 1)) ||
+		(hasSubmission && (typeof submissionId !== "string" || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(submissionId)))) return json({ error: "invalid_held_request" }, 400);
+	try {
+		const state = await guard.resolve(id, {
+			send: body.send, remember: body.send && remember === true,
+			expectedRevision: typeof expectedRevision === "number" ? expectedRevision : null,
+			submissionId: typeof submissionId === "string" ? submissionId : null,
+		}, approver);
+		if (!state) return json({ error: "held_not_found" }, 404);
+		const outcome = state.status === "sent" ? "sent" : state.status === "cancelled" ? "dropped" : null;
+		if (outcome) resolved(id, outcome);
+		if (state.errorCode === "allowlist_persist_failed" || state.errorCode === "state_persist_failed") return json({ error: state.errorCode, held: state }, 503);
+		if (state.errorCode === "dispatch_failed" || state.errorCode === "dispatch_unknown") return json({ error: state.errorCode, held: state }, 502);
+		return json({ ...state, ...(outcome ? { outcome } : {}) }, state.status === "processing" ? 202 : 200);
+	} catch (error) {
+		if (error instanceof SecurityRuntimeError) {
+			const status = error.code === "held_conflict" ? 409 : error.code.endsWith("persist_failed") ? 503 : 502;
+			return json({ error: error.code, ...(error.held ? { held: error.held } : {}) }, status);
+		}
+		return json({ error: "state_persist_failed" }, 503);
+	}
+}
+
+export const SECURITY_ALLOWED_PATH = `${SECURITY_CHECK_PATH}/allowed-values`;
+export async function handleSecurityAllowedValues(req: Request, url: URL, store: Store, publish: (revision: number) => void): Promise<Response | null> {
+	if (url.pathname !== SECURITY_ALLOWED_PATH && !url.pathname.startsWith(`${SECURITY_ALLOWED_PATH}/`)) return null;
+	const json = (value: unknown, status = 200) => Response.json(value, { status, headers: { "Cache-Control": "no-store" } });
+	try {
+		if (req.method === "GET" && url.pathname === SECURITY_ALLOWED_PATH) return json(store.securityAllowedValues());
+		if (req.method !== "DELETE") return null;
+		const body: unknown = await req.json().catch(() => null);
+		if (typeof body !== "object" || body === null || !("expectedRevision" in body) ||
+			typeof body.expectedRevision !== "number" || !Number.isSafeInteger(body.expectedRevision) || body.expectedRevision < 0) return json({ error: "invalid_held_request" }, 400);
+		const id = url.pathname === SECURITY_ALLOWED_PATH ? undefined : decodeURIComponent(url.pathname.slice(SECURITY_ALLOWED_PATH.length + 1));
+		const result = store.deleteSecurityAllowedValues(body.expectedRevision, id);
+		if (result.removed > 0) publish(result.revision);
+		return json(result);
+	} catch (error) {
+		if (error instanceof SecurityRuntimeError && error.code === "allowlist_conflict") return json({ error: error.code, revision: error.revision }, 409);
+		return json({ error: "allowlist_persist_failed" }, 503);
+	}
+}