zigmini 0.9.0-beta.3 → 1.0.0-beta.1

package/src/security/repo-scan.ts

@@ -0,0 +1,369 @@
+// Private string check for everything the npm package ships (privacy audit, work 25c2b26a).
+// Three sources, none of which holds a personal value in plain text inside this repository:
+//   1. scripts/private-strings.hashes.json: salted SHA-256 of the owner's names, accounts, domains and device ids.
+//      A text matches when one of its word candidates (see candidates()) hashes to a listed value.
+//   2. A plain list kept only on the release Mac (default ~/.zigmini-release/private-strings, or ZIGMINI_PRIVATE_STRINGS):
+//      one value per line, matched as a case-insensitive substring. It holds ids, tokens and addresses of that Mac.
+//   3. Generic patterns that need no personal value: MAC addresses, NAS volume paths and phone model numbers.
+//   4. Home folder paths (a macOS or Linux home followed by a user name). Write a home folder as ~ instead.
+// Binary files are read as their printable strings; a zip (the APK) is read entry by entry.
+// The same checks cover every file git tracks and every object reachable from HEAD, dev and the tags (bug 163), run by test:all.
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { inflateRawSync } from "node:zlib";
+import { dexStrings } from "./dex-strings.ts";
+import { findPrivate, HASH_SALT, machineTerms, normalizeTerm, PUBLIC_ACCOUNT, candidates, PATTERNS, HOME_PATH, NON_PERSONAL_HOMES } from "./terms.ts";
+import type { PrivateHit as TermHit, PrivateSet } from "./terms.ts";
+import { readBaseline, type BaselineAllow, type BaselineSource } from "./baseline.ts";
+import { canonicalSecurityValue } from "../security-allow.ts";
+import { compileRules, entropy, isAllowed, validateAllow, type Rule } from "../../scripts/secret-rules.ts";
+import ruleConfig from "../../scripts/secret-scan.rules.json";
+import allowConfig from "../../scripts/secret-scan.allow.json";
+export {
+	HASH_SALT, PATTERNS, HOME_PATH, NON_PERSONAL_HOMES, homePaths, tildeHome, normalizeTerm, hashTerm,
+	candidates, PUBLIC_ACCOUNT, findPrivate, machineTerms,
+} from "./terms.ts";
+export type { PrivateSet } from "./terms.ts";
+
+export const HASHES_FILE = join(process.cwd(), "scripts", "private-strings.hashes.json");
+const RULES = compileRules(ruleConfig.rules as readonly Rule[]).filter((rule) => rule.id !== "user-home-path")
+	.map((rule) => ({ ...rule, regex: new RegExp(rule.regex.source, `${rule.regex.flags}d`) }));
+const ALLOW = validateAllow(allowConfig.allow);
+const GRAPHEMES = new Intl.Segmenter("en", { granularity: "grapheme" });
+
+export interface PrivateOccurrence { readonly start: number; readonly end: number; readonly token: string }
+export interface PrivateHit extends TermHit { readonly occurrences?: readonly PrivateOccurrence[] }
+export interface PrivateFinding extends PrivateHit {
+	readonly file: string;
+	readonly line?: number;
+	/** Opaque archive-entry domain, independent of duplicate names and printable separators. */
+	readonly sourceId?: symbol;
+}
+export interface LoadedPrivateSet extends PrivateSet {
+	/** Report absent hashes separately from an empty, valid hash file. */
+	readonly hashCount: number | "absent";
+	readonly listTerms: number;
+	readonly allow: readonly BaselineAllow[];
+	readonly machine: { readonly home: string; readonly user: string };
+}
+
+/** Exact approved tokens own spans in one file; every occurrence of a finding must be covered. */
+export function applyRepoAllow(findings: readonly PrivateFinding[], allow: readonly BaselineAllow[], machine: { readonly home: string; readonly user: string }) {
+	const accounts = new Set(machineTerms(machine).terms.map(normalizeTerm));
+	const values = new Set(allow.filter((entry) => entry.scopes.includes("repo") && !accounts.has(normalizeTerm(entry.value)))
+		.map((entry) => normalizeTerm(entry.value)));
+	const spans = new Map<string | symbol, PrivateOccurrence[]>();
+	for (const hit of findings) for (const occurrence of hit.occurrences ?? []) {
+		if (values.has(normalizeTerm(occurrence.token))) {
+			const allowed = spans.get(hit.sourceId ?? hit.file) ?? [];
+			allowed.push(occurrence);
+			spans.set(hit.sourceId ?? hit.file, allowed);
+		}
+	}
+	const kept = findings.filter((hit) => {
+		if (hit.rule === "user-home-path" || accounts.has(normalizeTerm(hit.value)) || !hit.occurrences?.length) return true;
+		const allowedSpans = spans.get(hit.sourceId ?? hit.file) ?? [];
+		return !hit.occurrences.every((occurrence) => allowedSpans.some((span) => span.start <= occurrence.start && occurrence.end <= span.end));
+	});
+	return { kept, allowedRepo: findings.length - kept.length };
+}
+
+export class RepoScanError extends Error {
+	constructor(readonly code: string, readonly exitCode: 2 | 3 = 2) { super(code); }
+}
+
+/** Parse the repository-local exception boundary once; only exact object IDs are accepted. */
+export function parseObjectExceptions(text: string): ReadonlySet<string> {
+	let input: unknown;
+	try { input = JSON.parse(text); }
+	catch (error) {
+		if (error instanceof SyntaxError) throw new RepoScanError("private_scan_exceptions_invalid");
+		throw error;
+	}
+	if (typeof input !== "object" || input === null || !("description" in input) || typeof input.description !== "string"
+		|| !("objects" in input) || !Array.isArray(input.objects)
+		|| !input.objects.every((oid): oid is string => typeof oid === "string" && /^[0-9a-f]{40}$/.test(oid))) {
+		throw new RepoScanError("private_scan_exceptions_invalid");
+	}
+	return new Set(input.objects);
+}
+
+/** Keep offsets through the public-account replacement and Unicode normalization. */
+function mappedText(text: string, normalized: boolean) {
+	const starts: number[] = [], ends: number[] = [];
+	let masked = "", at = 0;
+	for (const match of text.matchAll(PUBLIC_ACCOUNT)) {
+		for (; at < match.index; at++) { masked += text[at]; starts.push(at); ends.push(at + 1); }
+		masked += " "; starts.push(match.index); ends.push(match.index + match[0].length);
+		at = match.index + match[0].length;
+	}
+	for (; at < text.length; at++) { masked += text[at]; starts.push(at); ends.push(at + 1); }
+	const mappedStarts: number[] = [], mappedEnds: number[] = [];
+	for (const { segment, index } of GRAPHEMES.segment(masked)) {
+		const transformed = (normalized ? segment.normalize("NFC") : segment).toLowerCase();
+		for (let i = 0; i < transformed.length; i++) {
+			mappedStarts.push(starts[index] ?? 0);
+			mappedEnds.push(ends[index + segment.length - 1] ?? text.length);
+		}
+	}
+	return { text: (normalized ? masked.normalize("NFC") : masked).toLowerCase(), starts: mappedStarts, ends: mappedEnds };
+}
+
+function termOccurrences(text: string, hit: TermHit): PrivateOccurrence[] {
+	const mapped = mappedText(text, hit.rule === "private-term");
+	const occurrences: PrivateOccurrence[] = [];
+	const ranges = hit.rule === "private-term"
+		? [...mapped.text.matchAll(/[a-z0-9\uac00-\ud7a3._@-]+/g)].filter((match) => candidates(match[0]).has(hit.value))
+			.map((match) => ({ start: match.index, end: match.index + match[0].length }))
+		: [{ start: 0, end: mapped.text.length }];
+	const publicRanges = [...text.matchAll(PUBLIC_ACCOUNT)].map((match) => ({ start: match.index, end: match.index + match[0].length }));
+	const tokenCharacter = (at: number) => /[A-Za-z0-9\uac00-\ud7a3._%+@-]/.test(text[at] ?? "")
+		&& !publicRanges.some((range) => at >= range.start && at < range.end);
+	for (const range of ranges) {
+		let at = mapped.text.indexOf(hit.value, range.start);
+		while (hit.value.length > 0 && at >= range.start && at + hit.value.length <= range.end) {
+			const start = mapped.starts[at], end = mapped.ends[at + hit.value.length - 1];
+			if (start !== undefined && end !== undefined) {
+				let from = start, to = end;
+				while (from > 0 && tokenCharacter(from - 1)) from--;
+				while (to < text.length && tokenCharacter(to)) to++;
+				occurrences.push({ start, end, token: text.slice(from, to) });
+			}
+			at = mapped.text.indexOf(hit.value, at + 1);
+		}
+	}
+	return occurrences;
+}
+
+/** Enrich existing detections without changing their order, values, or count. */
+function locatedPrivate(text: string, set: PrivateSet, binary: boolean, file?: string, body = text, offset = 0): PrivateHit[] {
+	const hits = findPrivate(text, set, binary, file);
+	if (hits.length === 0) return [];
+	const positions = new Map<string, PrivateOccurrence[][]>();
+	const remember = (rule: string, value: string, occurrence: PrivateOccurrence) => {
+		const key = JSON.stringify([rule, value]);
+		const list = positions.get(key) ?? [];
+		list.push([occurrence]); positions.set(key, list);
+	};
+	for (const { id, regex } of PATTERNS) for (const match of text.matchAll(regex)) {
+		remember(id, match[0], { start: match.index, end: match.index + match[0].length, token: match[0] });
+	}
+	for (const match of text.matchAll(HOME_PATH)) if (!NON_PERSONAL_HOMES.has(match[1] ?? "")) {
+		remember("user-home-path", match[0], { start: match.index, end: match.index + match[0].length, token: match[0] });
+	}
+	let lineOffset = 0;
+	for (const line of text.split("\n")) {
+		for (const rule of RULES) for (const match of line.matchAll(rule.regex)) {
+			const value = match[rule.group ?? 0], range = match.indices?.[rule.group ?? 0];
+			if (!value || !range || (rule.minEntropy !== undefined && entropy(value) < rule.minEntropy) || isAllowed(rule.id, value, ALLOW, file)) continue;
+			const start = lineOffset + range[0], end = lineOffset + range[1];
+			const token = canonicalSecurityValue(body, rule.id, offset + start, offset + end);
+			// The canonical value is a body substring enclosing this capture, not necessarily the first equal string.
+			const tokenStart = body.lastIndexOf(token, offset + start);
+			remember(rule.id, value, { start: tokenStart - offset, end: tokenStart + token.length - offset, token });
+		}
+		lineOffset += line.length + 1;
+	}
+	return hits.map((hit) => {
+		const occurrences = hit.rule === "private-list" || hit.rule === "private-term" ? termOccurrences(text, hit)
+			: positions.get(JSON.stringify([hit.rule, hit.value]))?.shift() ?? [];
+		return { ...hit, occurrences: occurrences.map((occurrence) => ({ ...occurrence, start: occurrence.start + offset, end: occurrence.end + offset })) };
+	});
+}
+
+/** Output limit of the git commands below (the whole repository history fits). */
+const GIT_OUTPUT_LIMIT = 2 ** 30;
+
+/** Printable runs (at least 4 characters) of a binary read as UTF-8 and as UTF-16LE at both byte alignments (Android resource tables use both encodings). */
+export function binaryStrings(bytes: Uint8Array): string[] {
+	const runs: string[] = [];
+	const utf16 = (from: number) => {
+		const size = bytes.length - from;
+		return new TextDecoder("utf-16le").decode(bytes.subarray(from, from + size - (size % 2)));
+	};
+	for (const decoded of [new TextDecoder("utf-8").decode(bytes), utf16(0), utf16(1)]) {
+		for (const run of decoded.split(/[^\x20-\x7e\uac00-\ud7a3]+/)) if (run.length >= 4) runs.push(run);
+	}
+	return runs;
+}
+
+export interface ZipEntry { readonly name: string; readonly data: Uint8Array }
+
+/** Entries of a zip archive (stored or deflated), read from its central directory. */
+export function zipEntries(bytes: Uint8Array): ZipEntry[] {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let end = -1;
+	for (let i = bytes.length - 22; i >= Math.max(0, bytes.length - 65_557); i--) {
+		if (view.getUint32(i, true) === 0x06054b50) { end = i; break; }
+	}
+	if (end < 0) throw new Error("private_scan_zip_invalid");
+	const count = view.getUint16(end + 10, true);
+	let at = view.getUint32(end + 16, true);
+	const entries: ZipEntry[] = [];
+	for (let n = 0; n < count; n++) {
+		if (view.getUint32(at, true) !== 0x02014b50) throw new Error("private_scan_zip_invalid");
+		const method = view.getUint16(at + 10, true);
+		const size = view.getUint32(at + 20, true);
+		const nameLength = view.getUint16(at + 28, true);
+		const local = view.getUint32(at + 42, true);
+		const name = new TextDecoder().decode(bytes.subarray(at + 46, at + 46 + nameLength));
+		const start = local + 30 + view.getUint16(local + 26, true) + view.getUint16(local + 28, true);
+		const raw = bytes.subarray(start, start + size);
+		if (method !== 0 && method !== 8) throw new RepoScanError("private_scan_zip_method");
+		entries.push({ name, data: method === 0 ? raw : new Uint8Array(inflateRawSync(raw)) });
+		at += 46 + nameLength + view.getUint16(at + 30, true) + view.getUint16(at + 32, true);
+	}
+	return entries;
+}
+
+function isBinary(bytes: Uint8Array): boolean {
+	const n = Math.min(bytes.length, 8000);
+	for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
+	return false;
+}
+
+function isZip(file: string, bytes: Uint8Array): boolean {
+	return /\.(?:apk|zip|jar|aar)$/i.test(file) && bytes[0] === 0x50 && bytes[1] === 0x4b;
+}
+
+/** Findings of one file: text line by line, a binary as its strings, a zip entry by entry (file "a.apk!classes.dex"). */
+export function scanBytes(file: string, bytes: Uint8Array, set: PrivateSet): PrivateFinding[] {
+	if (isZip(file, bytes)) return zipEntries(bytes).flatMap((entry) => {
+		const sourceId = Symbol();
+		return scanBytes(`${file}!${entry.name}`, entry.data, set).map((hit) => ({ ...hit, sourceId: hit.sourceId ?? sourceId }));
+	});
+	const dex = dexStrings(bytes);
+	if (dex !== null) {
+		const body = dex.map(({ text }) => text).join("\n");
+		let offset = 0;
+		return dex.flatMap(({ text, sourcePackage }) => {
+			// Only the proven source-package occurrence is metadata; private registrations and every other rule still apply.
+			const found = locatedPrivate(text, set, true, file, body, offset)
+				.filter((hit) => hit.rule !== "internal-host" || hit.value !== sourcePackage).map((hit) => ({ ...hit, file }));
+			offset += text.length + 1;
+			return found;
+		});
+	}
+	if (isBinary(bytes)) return locatedPrivate(binaryStrings(bytes).join("\n"), set, true, file).map((hit) => ({ ...hit, file }));
+	const findings: PrivateFinding[] = [];
+	const body = new TextDecoder().decode(bytes);
+	let offset = 0;
+	body.split("\n").forEach((text, index) => {
+		for (const hit of locatedPrivate(text, set, false, file, body, offset)) findings.push({ ...hit, file, line: index + 1 });
+		offset += text.length + 1;
+	});
+	return findings;
+}
+
+export function scanPrivateFiles(root: string, files: readonly string[], set: PrivateSet): PrivateFinding[] {
+	return files.flatMap((file) => scanBytes(file, readFileSync(join(root, file)), set));
+}
+
+/** Findings in every file git tracks in a checkout (the working copy; deleted files and symbolic links are skipped). */
+export function scanTracked(root: string, set: PrivateSet): PrivateFinding[] {
+	const files = execFileSync("git", ["-C", root, "ls-files", "-z"], { maxBuffer: GIT_OUTPUT_LIMIT }).toString().split("\0").filter((file) => file !== "");
+	return scanPrivateFiles(root, files.filter((file) => existsSync(join(root, file)) && !lstatSync(join(root, file)).isSymbolicLink()), set);
+}
+
+/** Refs whose objects the Git object check reads besides HEAD: the local dev, origin/dev and every tag. Other local and
+ * remote-tracking branches, PR refs and any other ref belong to other work and are not read (user decision "작업 브랜치 + dev"). */
+export const SCOPE_REF = /^refs\/(?:heads\/dev|remotes\/origin\/dev|tags\/.+)$/;
+
+/** The exact positive traversal inputs, also available to the security evidence command without reading object contents. */
+export function gitObjectScope(gitDir: string) {
+	const git = (args: string[]) => execFileSync("git", ["--git-dir", gitDir, ...args], { maxBuffer: GIT_OUTPUT_LIMIT }).toString();
+	const included: { readonly ref: string; readonly oid: string }[] = [];
+	const excluded: { readonly ref: string; readonly oid: string }[] = [];
+	for (const line of git(["for-each-ref", "--sort=refname", "--format=%(objectname) %(refname)"]).split("\n")) {
+		if (line === "") continue;
+		const [oid, ref] = line.split(" ");
+		if (!oid || !ref) throw new Error("private_scan_git_ref_invalid");
+		const inScope = SCOPE_REF.test(ref);
+		(inScope ? included : excluded).push({ ref, oid });
+	}
+	const sourceSha = git(["rev-parse", "--revs-only", "HEAD"]).trim() || null;
+	const roots = [...new Set([...included.map(({ oid }) => oid), ...(sourceSha ? [sourceSha] : [])])];
+	return { included, excluded, sourceSha, roots };
+}
+
+/** Findings in the in-scope ref names and every blob, commit and annotated tag reachable from HEAD or an in-scope ref. A commit
+ * or tag keeps its message but excludes identity header lines. A blob is named "blob <path>" by the first path that reaches it. */
+export function scanGitObjects(gitDir: string, set: PrivateSet, exceptions: ReadonlySet<string> = new Set()): PrivateFinding[] {
+	if ([...exceptions].some((oid) => !/^[0-9a-f]{40}$/.test(oid))) throw new RepoScanError("private_scan_exceptions_invalid");
+	const git = (args: string[], input?: string) => execFileSync("git", ["--git-dir", gitDir, ...args], { input, maxBuffer: GIT_OUTPUT_LIMIT });
+	const scope = gitObjectScope(gitDir);
+	const names = new Map<string, string>();
+	for (const line of git(["rev-list", "--objects", "--stdin"], `${scope.roots.join("\n")}\n`).toString().split("\n")) {
+		const [id, ...path] = line.split(" ");
+		if (line !== "") names.set(id!, path.join(" "));
+	}
+	const refs = scope.included.map(({ ref }) => ref);
+	const findings: PrivateFinding[] = refs.flatMap((ref) => locatedPrivate(ref, set, false).map((hit) => ({ ...hit, file: `ref ${ref}` })));
+	const ids = [...names.keys()].filter((id) => !exceptions.has(id));
+	const out = git(["cat-file", "--batch"], `${ids.join("\n")}\n`);
+	let at = 0;
+	for (const id of ids) {
+		const end = out.indexOf(10, at);
+		const [name, type, size] = out.subarray(at, end).toString().split(" ");
+		if (name !== id) throw new Error(`private_scan_git_batch:${id}`);
+		const body = out.subarray(end + 1, end + 1 + Number(size));
+		at = end + 1 + Number(size) + 1;
+		if (type === "tree") continue;
+		const label = type === "blob" ? `blob ${names.get(id)} ${id}` : `${type} ${id}`;
+		const content = type === "commit" || type === "tag" ? Buffer.from(body.toString().split("\n").map((line, index, lines) =>
+			index < lines.indexOf("") && /^(?:author|committer|tagger) /.test(line) ? " ".repeat(line.length) : line).join("\n")) : body;
+		const file = names.get(id) || label;
+		findings.push(...scanBytes(file, content, set).map((hit) => ({ ...hit, file: `${label}${hit.file.slice(file.length)}` })));
+	}
+	return findings;
+}
+
+/** Lines of a list file, trimmed and lower-cased; blank lines and # comments are skipped. */
+export function parseList(text: string): string[] {
+	return text.split("\n").map((line) => line.trim().toLowerCase()).filter((line) => line !== "" && !line.startsWith("#"));
+}
+
+export function loadPrivateSet(source: BaselineSource, hashesFile = HASHES_FILE, machine = { home: homedir(), user: userInfo().username }): LoadedPrivateSet {
+	let terms: readonly string[];
+	let allow: readonly BaselineAllow[] = [];
+	switch (source.kind) {
+		case "baseline": {
+			const result = readBaseline(source);
+			if (!result.ok) throw new RepoScanError(`private_scan_baseline_${result.error}`, result.error === "missing" || result.error === "empty" ? 3 : 2);
+			terms = result.file.terms;
+			allow = result.file.allow;
+			break;
+		}
+		case "legacy-list":
+			try { terms = parseList(readFileSync(source.path, "utf8")); }
+			catch (error) {
+				if (error instanceof Error && "code" in error) throw new RepoScanError(error.code === "ENOENT" ? "private_scan_baseline_missing" : "private_scan_baseline_unreadable", error.code === "ENOENT" ? 3 : 2);
+				throw error;
+			}
+			if (terms.length === 0) throw new RepoScanError("private_scan_baseline_empty", 3);
+			break;
+		case "hash-only": terms = []; break;
+		case "missing": throw new RepoScanError("private_scan_baseline_missing", 3);
+		default: {
+			const unreachable: never = source;
+			throw new RepoScanError(`private_scan_source_invalid:${unreachable}`);
+		}
+	}
+	let hashes: ReadonlySet<string> = new Set(), hashCount: number | "absent" = "absent";
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(hashesFile, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || !("salt" in parsed) || parsed.salt !== HASH_SALT
+			|| !("hashes" in parsed) || !Array.isArray(parsed.hashes)
+			|| !parsed.hashes.every((hash): hash is string => typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash))) {
+			throw new RepoScanError("private_scan_hashes_invalid");
+		}
+		hashes = new Set(parsed.hashes);
+		hashCount = hashes.size;
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw new RepoScanError("private_scan_hashes_invalid");
+	}
+	const automatic = machineTerms(machine).terms.filter((term) => !terms.includes(term));
+	return { hashes, terms: [...terms, ...automatic], hashCount, listTerms: terms.length, allow, machine: { ...machine } };
+}

package/src/security/revision-probe.ts

@@ -0,0 +1,144 @@
+import { request, type IncomingMessage } from "node:http";
+import type { ScanFreshness } from "../cli/scan.ts";
+import { runtimePaths, type Env } from "../runtime/paths.ts";
+import type { BaselineFile } from "./baseline.ts";
+
+type Revision = Pick<BaselineFile, "baselineId" | "revision">;
+export interface RevisionClock {
+	readonly now: () => number;
+	/** Schedule asynchronously and return cancellation for that alarm. */
+	readonly schedule: (callback: () => void, delayMs: number) => () => void;
+}
+export interface RevisionEvents {
+	readonly connect: () => void;
+	readonly response: (status: number | undefined, contentType: string | undefined) => void;
+	readonly data: (chunk: Buffer) => void;
+	readonly end: () => void;
+	readonly error: (code: string | undefined) => void;
+}
+export interface RevisionConnection {
+	readonly start: () => void;
+	readonly destroy: () => void;
+}
+/** Construct first; callbacks may run only after start(), as with node:http. */
+export type RevisionTransport = (port: number, events: RevisionEvents) => RevisionConnection;
+export interface RevisionProbeDeps {
+	readonly env?: Env;
+	readonly clock?: RevisionClock;
+	readonly transport?: RevisionTransport;
+}
+const CLOCK: RevisionClock = {
+	now: () => performance.now(),
+	schedule: (callback, delay) => {
+		const timer = setTimeout(callback, delay);
+		return () => clearTimeout(timer);
+	},
+};
+
+/** One fresh connection, no authentication, proxy, redirect or retry machinery. */
+export function nodeRevisionTransport(port: number, events: RevisionEvents): RevisionConnection {
+	let response: IncomingMessage | undefined;
+	const req = request({ hostname: "127.0.0.1", port, method: "GET", agent: false,
+		path: "/api/settings/security-check/baseline/revision", headers: { accept: "application/json" } });
+	req.once("socket", (socket) => { socket.once("connect", events.connect); });
+	req.once("response", (message) => {
+		response = message;
+		message.on("data", (chunk: Buffer) => events.data(chunk));
+		message.once("end", events.end);
+		message.once("error", () => events.error(undefined));
+		message.once("aborted", () => events.error(undefined));
+		events.response(message.statusCode, message.headers["content-type"]);
+	});
+	req.once("error", (error: NodeJS.ErrnoException) => events.error(error.code));
+	req.once("close", () => events.error(undefined));
+	req.once("upgrade", (_message, socket) => { socket.destroy(); events.error(undefined); });
+	return { start: () => { req.end(); }, destroy: () => { response?.destroy(); req.destroy(); } };
+}
+
+/** Parse only the two revision fields. Identity mismatch takes precedence over revision ordering. */
+export function classifyRevision(file: Revision | null, input: unknown): ScanFreshness {
+	if (typeof input !== "object" || input === null || Array.isArray(input)
+		|| !("baselineId" in input) || typeof input.baselineId !== "string" || input.baselineId.trim().length === 0
+		|| !("revision" in input) || typeof input.revision !== "number"
+		|| !Number.isSafeInteger(input.revision) || input.revision < 0) return "probe_failed";
+	if (file === null) return "legacy_unverifiable";
+	if (input.baselineId !== file.baselineId) return "mismatch";
+	if (input.revision > file.revision) return "stale";
+	if (input.revision < file.revision) return "mismatch";
+	return "verified";
+}
+
+/** The one-second monotonic budget includes connection, headers, body, decoding and validation. */
+export function probeRevision(baseline: { readonly file: Revision | null }, deps: RevisionProbeDeps = {}): Promise<ScanFreshness> {
+	const clock = deps.clock ?? CLOCK;
+	const started = clock.now();
+	return new Promise((resolve) => {
+		let connected = false, settled = false, bytes = 0;
+		let connection: RevisionConnection | undefined;
+		let cancel: (() => void) | undefined;
+		const chunks: Buffer[] = [];
+		const finish = (freshness: ScanFreshness) => {
+			if (settled) return;
+			settled = true;
+			cancel?.();
+			connection?.destroy();
+			chunks.length = 0;
+			resolve(freshness);
+		};
+		const expired = () => finish(connected ? "probe_failed" : "unchecked_offline");
+		const active = () => {
+			if (settled) return false;
+			if (clock.now() - started < 1000) return true;
+			expired();
+			return false;
+		};
+		const alarm = () => {
+			if (settled) return;
+			const remaining = 1000 - (clock.now() - started);
+			if (remaining > 0) cancel = clock.schedule(alarm, remaining);
+			else expired();
+		};
+		const events: RevisionEvents = {
+			connect: () => { if (active()) connected = true; },
+			response: (status, contentType) => {
+				if (!active()) return;
+				if (status !== 200 || !/^application\/json(?:\s*;|$)/i.test(contentType ?? "")) finish("probe_failed");
+			},
+			data: (chunk) => {
+				if (!active()) return;
+				bytes += chunk.byteLength;
+				if (bytes > 4096) { finish("probe_failed"); return; }
+				chunks.push(chunk);
+			},
+			end: () => {
+				if (!active()) return;
+				let freshness: ScanFreshness;
+				try {
+					const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks, bytes));
+					const input: unknown = JSON.parse(text);
+					freshness = classifyRevision(baseline.file, input);
+				} catch (error) {
+					if (!(error instanceof SyntaxError) && !(error instanceof TypeError)) throw error;
+					freshness = "probe_failed";
+				}
+				if (active()) finish(freshness);
+			},
+			error: (code) => {
+				if (!active()) return;
+				const offline = !connected && (code === "ECONNREFUSED" || code === "EHOSTUNREACH" || code === "ENETUNREACH");
+				finish(offline ? "unchecked_offline" : "probe_failed");
+			},
+		};
+		try {
+			const port = runtimePaths(deps.env ?? process.env).ports.web;
+			alarm();
+			if (!active()) return;
+			connection = (deps.transport ?? nodeRevisionTransport)(port, events);
+			if (!active()) return;
+			connection.start();
+		} catch (error) {
+			// Request construction is an I/O boundary; never expose private error text.
+			events.error(error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined);
+		}
+	});
+}

package/src/security/terms.ts

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { compileRules, scanLine, validateAllow } from "../../scripts/secret-rules.ts";
+import ruleConfig from "../../scripts/secret-scan.rules.json";
+import allowConfig from "../../scripts/secret-scan.allow.json";
+import type { Rule } from "../../scripts/secret-rules.ts";
+
+const EXPOSURE_RULES = compileRules(ruleConfig.rules as readonly Rule[]).filter((rule) => rule.id !== "user-home-path");
+const EXPOSURE_ALLOW = validateAllow(allowConfig.allow);
+
+export const HASH_SALT = "zigmini-private-strings-v1:";
+
+export interface PrivateSet {
+	readonly hashes: ReadonlySet<string>;
+	/** Lower-case plain values from the release Mac's list. */
+	readonly terms: readonly string[];
+}
+export interface PrivateHit { readonly rule: string; readonly value: string }
+
+export const PATTERNS: readonly { readonly id: string; readonly regex: RegExp }[] = [
+	// A run of exactly six colon-separated byte pairs; longer runs (certificate fingerprints) do not match.
+	{ id: "mac-address", regex: /(?<![0-9A-Fa-f:])(?:[0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}(?![0-9A-Fa-f:])/g },
+	{ id: "nas-volume-path", regex: /\/volume\d+\//g },
+	{ id: "phone-model", regex: /\bSM-[A-Z]\d{3}[A-Z]{0,2}\b/g },
+];
+
+/** A home folder path where a path starts (line start, space, quote, bracket, = , : | < > or file://), not a "home" folder
+ * inside another path such as ${dir}/home/x; group 1 is the user name. */
+export const HOME_PATH = /(?<=^|[\s"'`(\[{<>=,:|]|file:\/\/)\/(?:Users|home)\/([A-Za-z0-9_][A-Za-z0-9._-]*)/g;
+/** A loopback address names no person or machine, so a list value that is one is ignored (ws://127.0.0.1:18990 is the default bridge). */
+const LOOPBACK = /^(?:(?:wss?|https?):\/\/)?(?:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\]|::1)(?::\d+)?\/?$/;
+/** User names that are not a person: the shared macOS folder, the Docker image user, the Emscripten virtual user of the
+ * vendored ONNX runtime and placeholder names of tests. */
+export const NON_PERSONAL_HOMES: ReadonlySet<string> = new Set(["Shared", "bun", "web_user", "x", "me", "example", "someone", "somebody", "qa"]);
+
+/** Home folder paths of a text whose user name is not in NON_PERSONAL_HOMES. */
+export function homePaths(text: string): string[] {
+	return [...text.matchAll(HOME_PATH)].filter((match) => !NON_PERSONAL_HOMES.has(match[1]!)).map((match) => match[0]);
+}
+
+/** A path for a committed file: the home folder written as ~. */
+export function tildeHome(text: string, home = homedir()): string {
+	return home.length > 1 ? text.split(home).join("~") : text;
+}
+
+export function normalizeTerm(value: string): string {
+	return value.normalize("NFC").toLowerCase();
+}
+
+export function hashTerm(term: string): string {
+	return createHash("sha256").update(HASH_SALT + normalizeTerm(term)).digest("hex");
+}
+
+/** Automatic account terms; the home is only used to redact report paths, never as a substring term. */
+export function machineTerms({ home, user }: { readonly home: string; readonly user: string }): { readonly terms: readonly string[]; readonly home: string } {
+	const name = user.toLowerCase();
+	return { terms: name.length < 3 ? [] : [name], home };
+}
+
+/** Every piece of a text that a hashed value can equal: words, their @ . _ - parts, dotted suffixes and 2-4 syllable Hangul runs. */
+export function candidates(text: string): Set<string> {
+	const out = new Set<string>();
+	for (const token of text.normalize("NFC").toLowerCase().split(/[^a-z0-9\uac00-\ud7a3._@-]+/)) {
+		const word = token.replace(/^[._@-]+|[._@-]+$/g, "");
+		if (word.length < 2) continue;
+		out.add(word);
+		for (const part of word.split("@")) {
+			out.add(part);
+			const labels = part.split(".");
+			for (let i = 1; i < labels.length - 1; i++) out.add(labels.slice(i).join("."));
+			for (const piece of part.split(/[._-]/)) if (piece.length >= 2) out.add(piece);
+		}
+		for (const run of word.match(/[\uac00-\ud7a3]+/g) ?? []) {
+			for (let size = 2; size <= Math.min(4, run.length); size++) {
+				for (let i = 0; i + size <= run.length; i++) out.add(run.slice(i, i + size));
+			}
+		}
+	}
+	return out;
+}
+
+/** The public GitHub account of the repository: its name (also in github.com/owen-ever/...) and its noreply commit address.
+ * They are public, so they are removed before the private value checks. The name directly before an @ of another domain
+ * is kept, because that is a personal mail address. */
+export const PUBLIC_ACCOUNT = new RegExp(String.raw`(?<![A-Za-z0-9._%+-])(?:215776236\+${"owen-ever"}@users\.noreply\.github\.com(?![A-Za-z0-9.-])|owen-ever(?![A-Za-z0-9_@-]|\.[A-Za-z0-9-]))`, "gi");
+
+export function findPrivate(text: string, set: PrivateSet, binary = false, file?: string): PrivateHit[] {
+	const hits: PrivateHit[] = [];
+	const masked = text.replace(PUBLIC_ACCOUNT, " ");
+	for (const candidate of candidates(masked)) if (set.hashes.has(hashTerm(candidate))) hits.push({ rule: "private-term", value: candidate });
+	const lower = masked.toLowerCase();
+	for (const term of set.terms) if (lower.includes(term) && !LOOPBACK.test(term)) hits.push({ rule: "private-list", value: term });
+	if (!binary) for (const { id, regex } of PATTERNS) for (const match of text.matchAll(regex)) hits.push({ rule: id, value: match[0] });
+	for (const path of homePaths(text)) hits.push({ rule: "user-home-path", value: path });
+	for (const line of text.split("\n")) for (const { rule, value } of scanLine(line, EXPOSURE_RULES, EXPOSURE_ALLOW, file)) hits.push({ rule, value });
+	return hits;
+}

package/src/security-allow.ts

@@ -20,6 +20,7 @@ export interface SecurityApprover {
 	readonly deviceId: string | null;
 }
 export interface AllowedValue {
+	readonly scopes?: readonly ("transport" | "repo")[];
 	readonly id: string;
 	readonly value: string;
 	readonly kind: string;