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

package/src/security/baseline.ts

@@ -0,0 +1,170 @@
+import { randomUUID } from "node:crypto";
+import {
+	chmodSync, closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync,
+	mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync,
+} from "node:fs";
+import { securityBaselinePaths, type Env, type RuntimePaths } from "../runtime/paths.ts";
+
+export const SCHEMA_VERSION = 1;
+
+export interface BaselineAllow {
+	readonly value: string;
+	readonly scopes: readonly ("transport" | "repo")[];
+}
+
+export interface BaselineFile {
+	readonly schemaVersion: typeof SCHEMA_VERSION;
+	readonly baselineId: string;
+	readonly revision: number;
+	readonly terms: readonly string[];
+	readonly home: string;
+	readonly user: string;
+	readonly allow: readonly BaselineAllow[];
+	readonly exportedAt: string;
+	readonly gatewayVersion: string;
+}
+
+export type BaselineError = "missing" | "unreadable" | "invalid" | "unsupported" | "empty" | "insecure";
+export type BaselineResult =
+	| { readonly ok: true; readonly file: BaselineFile }
+	| { readonly ok: false; readonly error: BaselineError };
+export type BaselineWriteResult =
+	| { readonly ok: true }
+	| { readonly ok: false; readonly error: "write_failed" };
+
+export interface BaselineFileSource {
+	readonly kind: "baseline";
+	readonly path: string;
+	readonly explicit: boolean;
+}
+export type BaselineSource =
+	| BaselineFileSource
+	| { readonly kind: "legacy-list"; readonly path: string }
+	| { readonly kind: "hash-only" }
+	| { readonly kind: "missing" };
+
+export function legacyListSource(path: string): Extract<BaselineSource, { kind: "legacy-list" }> {
+	return { kind: "legacy-list", path };
+}
+
+/** Only callers with an explicit CI policy or a hash-only test may select this source. */
+export function hashOnlySource(): Extract<BaselineSource, { kind: "hash-only" }> {
+	return { kind: "hash-only" };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Parse the file boundary, not the store's term policy. Errors never contain file contents. */
+export function parseBaseline(text: string): BaselineResult {
+	let input: unknown;
+	try { input = JSON.parse(text); }
+	catch (error) {
+		if (error instanceof SyntaxError) return { ok: false, error: "invalid" };
+		throw error;
+	}
+	if (!record(input) || !Number.isSafeInteger(input.schemaVersion)) return { ok: false, error: "invalid" };
+	if (input.schemaVersion !== SCHEMA_VERSION) return { ok: false, error: "unsupported" };
+	if (typeof input.baselineId !== "string" || input.baselineId.trim().length === 0
+		|| typeof input.revision !== "number" || !Number.isSafeInteger(input.revision) || input.revision < 0
+		|| !Array.isArray(input.terms) || !input.terms.every((term): term is string => typeof term === "string" && term.trim().length > 0)
+		|| typeof input.home !== "string" || input.home.length === 0 || typeof input.user !== "string"
+		|| !Array.isArray(input.allow)
+		|| typeof input.exportedAt !== "string" || !Number.isFinite(Date.parse(input.exportedAt))
+		|| typeof input.gatewayVersion !== "string" || input.gatewayVersion.length === 0) {
+		return { ok: false, error: "invalid" };
+	}
+	const allow: BaselineAllow[] = [];
+	for (const entry of input.allow) {
+		if (!record(entry) || typeof entry.value !== "string" || entry.value.trim().length === 0
+			|| !Array.isArray(entry.scopes)
+			|| !entry.scopes.every((scope): scope is "transport" | "repo" => scope === "transport" || scope === "repo")
+			|| !entry.scopes.includes("transport") || new Set(entry.scopes).size !== entry.scopes.length) {
+			return { ok: false, error: "invalid" };
+		}
+		allow.push({ value: entry.value, scopes: entry.scopes });
+	}
+	if (input.terms.length === 0) return { ok: false, error: "empty" };
+	return { ok: true, file: {
+		schemaVersion: input.schemaVersion, baselineId: input.baselineId, revision: input.revision,
+		terms: input.terms, home: input.home, user: input.user, allow,
+		exportedAt: input.exportedAt, gatewayVersion: input.gatewayVersion,
+	} };
+}
+
+/** lstat preserves dangling links and unreadable paths for validation instead of silently downgrading. */
+function present(path: string): boolean {
+	try { lstatSync(path); return true; }
+	catch (error) {
+		if (error instanceof Error && "code" in error) return error.code !== "ENOENT";
+		throw error;
+	}
+}
+
+export interface BaselineSourceOptions {
+	readonly baselineFlag?: string;
+	readonly env?: Env;
+	readonly paths?: Pick<RuntimePaths, "secrets">;
+}
+
+/** Selection only. Explicit missing paths stay selected; the caller validates exactly one source. */
+export function resolveBaselineSource(options: BaselineSourceOptions): BaselineSource {
+	const env = options.env ?? process.env;
+	const paths = securityBaselinePaths(env, options.paths);
+	if (options.baselineFlag !== undefined) return { kind: "baseline", path: options.baselineFlag, explicit: true };
+	if (env.ZGW_SECURITY_BASELINE_FILE !== undefined) return { kind: "baseline", path: env.ZGW_SECURITY_BASELINE_FILE, explicit: true };
+	if (present(paths.securityBaselineFile)) return { kind: "baseline", path: paths.securityBaselineFile, explicit: false };
+	if (env.ZIGMINI_PRIVATE_STRINGS !== undefined) return legacyListSource(env.ZIGMINI_PRIVATE_STRINGS);
+	if (present(paths.legacyPrivateStringsFile)) return legacyListSource(paths.legacyPrivateStringsFile);
+	return { kind: "missing" };
+}
+
+/** Only baseline JSON has this security contract; legacy-list and hash-only are separate consumers. */
+export function readBaseline(source: BaselineFileSource): BaselineResult {
+	if (source.path.trim().length === 0) return { ok: false, error: "invalid" };
+	try {
+		const entry = lstatSync(source.path);
+		if (entry.isSymbolicLink()) return { ok: false, error: "insecure" };
+		if (!entry.isFile()) return { ok: false, error: "unreadable" };
+		if ((entry.mode & 0o7777) !== 0o600 || entry.uid !== process.getuid?.()) return { ok: false, error: "insecure" };
+		const fd = openSync(source.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		try {
+			// Check the opened inode as well: replacement between lstat and open cannot bypass permissions or ownership.
+			const opened = fstatSync(fd);
+			if (!opened.isFile()) return { ok: false, error: "unreadable" };
+			if ((opened.mode & 0o7777) !== 0o600 || opened.uid !== process.getuid?.()) return { ok: false, error: "insecure" };
+			return parseBaseline(readFileSync(fd, "utf8"));
+		} finally { closeSync(fd); }
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error)) throw error;
+		if (error.code === "ENOENT") return { ok: false, error: "missing" };
+		if (error.code === "ELOOP") return { ok: false, error: "insecure" };
+		return { ok: false, error: "unreadable" };
+	}
+}
+
+/** Synchronous export: private temporary inode, flush, close, then same-directory atomic rename. */
+export function writeBaselineAtomic(path: string, file: BaselineFile): BaselineWriteResult {
+	// Runtime paths are macOS/POSIX paths; keeping the final slash also handles a file directly under /.
+	const directory = path.includes("/") ? path.slice(0, path.lastIndexOf("/") + 1) : ".";
+	try {
+		mkdirSync(directory, { recursive: true, mode: 0o700 });
+		chmodSync(directory, 0o700);
+		const temporary = `${directory}/.security-baseline-${randomUUID()}.tmp`;
+		const fd = openSync(temporary, "wx", 0o600);
+		try {
+			try {
+				// A restrictive umask may remove owner bits; it must never make the exported file unreadable.
+				fchmodSync(fd, 0o600);
+				writeFileSync(fd, `${JSON.stringify(file)}\n`, "utf8");
+				fsyncSync(fd);
+			} finally { closeSync(fd); }
+			renameSync(temporary, path);
+		} finally { rmSync(temporary, { force: true }); }
+		return { ok: true };
+	} catch (error) {
+		if (error instanceof Error) return { ok: false, error: "write_failed" };
+		throw error;
+	}
+}

package/src/security/dex-strings.ts

@@ -0,0 +1,242 @@
+/** Bounded string extraction, not a bytecode verifier. See AOSP dex-format string_data_item. */
+export class DexFormatError extends Error {
+	override readonly name = "DexFormatError";
+	constructor(readonly reason: string) { super(`private_scan_dex_${reason}`); }
+}
+
+export interface DexString {
+	readonly text: string;
+	/** A declared Kotlin getter's package in an exact compiler source trace, not a host value. */
+	readonly sourcePackage: string | null;
+}
+
+function stringData(bytes: Uint8Array, range: { readonly start: number; readonly end: number }): string {
+	let at = range.start;
+	const byte = () => {
+		if (at >= range.end) throw new DexFormatError("string_truncated");
+		const value = bytes[at++];
+		if (value === undefined) throw new DexFormatError("string_truncated");
+		return value;
+	};
+	let length = 0;
+	for (let shift = 0; ; shift += 7) {
+		const part = byte();
+		if (shift === 28 && part > 15) throw new DexFormatError("uleb");
+		length += (part & 127) * 2 ** shift;
+		if (part < 128) break;
+	}
+	if (length > range.end - at) throw new DexFormatError("string_length");
+	let text = "";
+	for (;;) {
+		const lead = byte();
+		if (lead === 0) break;
+		let unit = lead;
+		if (lead >= 128) {
+			if (lead < 0xc0 || lead >= 0xf0) throw new DexFormatError("mutf8");
+			const second = byte();
+			if ((second & 0xc0) !== 0x80) throw new DexFormatError("mutf8");
+			if (lead < 0xe0) {
+				unit = ((lead & 31) << 6) | (second & 63);
+				if (unit !== 0 && unit < 128) throw new DexFormatError("mutf8");
+			} else {
+				const third = byte();
+				if ((third & 0xc0) !== 0x80) throw new DexFormatError("mutf8");
+				unit = ((lead & 15) << 12) | ((second & 63) << 6) | (third & 63);
+				if (unit < 2048) throw new DexFormatError("mutf8");
+			}
+		}
+		text += String.fromCharCode(unit);
+	}
+	if (text.length !== length) throw new DexFormatError("string_length");
+	if (range.end - at > 3 || bytes.subarray(at, range.end).some((value) => value !== 0)) throw new DexFormatError("string_gap");
+	return text;
+}
+
+/** Magic selects the format, never a filename extension. Recognized malformed/unsupported DEX fails closed. */
+export function dexStrings(bytes: Uint8Array): readonly DexString[] | null {
+	if (bytes[0] !== 100 || bytes[1] !== 101 || bytes[2] !== 120 || bytes[3] !== 10) return null;
+	if (bytes.length < 112) throw new DexFormatError("header");
+	const magic = new TextDecoder().decode(bytes.subarray(0, 8));
+	if (!/^dex\n0(?:35|37|38|39|40)\0$/.test(magic)) throw new DexFormatError("version");
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const uint = (at: number) => view.getUint32(at, true);
+	if (uint(32) !== bytes.length || uint(36) !== 112 || uint(40) !== 0x12345678) throw new DexFormatError("header");
+	if (uint(44) !== 0 || uint(48) !== 0) throw new DexFormatError("linked");
+	const dataStart = uint(108);
+	if (dataStart < 112 || dataStart % 4 !== 0 || uint(104) !== bytes.length - dataStart) throw new DexFormatError("data");
+	const table = (at: number, width: number) => {
+		const count = uint(at);
+		const offset = uint(at + 4);
+		if (count === 0) {
+			if (offset !== 0) throw new DexFormatError("table");
+		} else if (offset < 112 || offset % 4 !== 0 || count > (dataStart - offset) / width) {
+			throw new DexFormatError("table");
+		}
+		return { count, offset };
+	};
+	const ids = table(56, 4);
+	const types = table(64, 4);
+	const protos = table(72, 12);
+	const fields = table(80, 8);
+	const methods = table(88, 8);
+	const classes = table(96, 32);
+	const map = uint(52);
+	if (map < dataStart || map % 4 !== 0 || map > bytes.length - 4) throw new DexFormatError("map");
+	const mapCount = uint(map);
+	if (mapCount > (bytes.length - map - 4) / 12) throw new DexFormatError("map");
+	let stringStart = 0;
+	let stringEnd = bytes.length;
+	let stringCount = 0;
+	let previous = -1;
+	let preceding: { end: number } | undefined;
+	const sections = new Map<number, { readonly count: number; readonly offset: number; end: number }>();
+	for (let i = 0; i < mapCount; i++) {
+		const at = map + 4 + i * 12;
+		const type = view.getUint16(at, true);
+		const offset = uint(at + 8);
+		const count = uint(at + 4);
+		if (sections.has(type) || offset <= previous || offset >= bytes.length || count === 0 || view.getUint16(at + 2, true) !== 0) throw new DexFormatError("map");
+		if (type >= 0x1000 && offset < dataStart) throw new DexFormatError("map_data");
+		if (preceding) preceding.end = offset;
+		const section = { count, offset, end: bytes.length };
+		sections.set(type, section);
+		preceding = section;
+		previous = offset;
+		if (stringStart > 0 && offset > stringStart && stringEnd === bytes.length) stringEnd = offset;
+		if (type === 0x2002) { stringStart = offset; stringCount = uint(at + 4); }
+	}
+	for (const [type, expected] of [
+		[0, { count: 1, offset: 0 }], [1, ids], [2, types], [3, protos],
+		[4, fields], [5, methods], [6, classes], [0x1000, { count: 1, offset: map }],
+	] as const) {
+		const section = sections.get(type);
+		if (expected.count === 0 ? section !== undefined : section?.count !== expected.count || section.offset !== expected.offset) throw new DexFormatError("map_header");
+	}
+	const mapEnd = sections.get(0x1000)?.end ?? 0;
+	if (map + 4 + mapCount * 12 > mapEnd) throw new DexFormatError("map");
+	// Without any strings no referenced data can be proved. Only the header and map
+	// may remain; do not silently discard an old string table or unclaimed payload.
+	if (ids.count === 0 && (sections.size !== 2 || dataStart !== 112 || map !== dataStart || mapEnd !== map + 4 + mapCount * 12)) throw new DexFormatError("empty_strings");
+	if (stringCount !== ids.count || (ids.count > 0 && stringStart < dataStart)) throw new DexFormatError("strings");
+	const offsets = Array.from({ length: ids.count }, (_, index) => ({ index, at: uint(ids.offset + index * 4) })).sort((a, b) => a.at - b.at);
+	const texts = new Map<number, string>();
+	for (const [position, item] of offsets.entries()) {
+		const end = offsets[position + 1]?.at ?? stringEnd;
+		if (position === 0 && item.at !== stringStart) throw new DexFormatError("string_offset");
+		if (item.at < stringStart || item.at >= end || end > stringEnd) throw new DexFormatError("string_offset");
+		texts.set(item.index, stringData(bytes, { start: item.at, end }));
+	}
+	const textAt = (index: number) => {
+		const text = texts.get(index);
+		if (text === undefined) throw new DexFormatError("string_index");
+		return text;
+	};
+	const descriptors = Array.from({ length: types.count }, (_, index) => textAt(uint(types.offset + index * 4)));
+	const shortType = (index: number) => {
+		const descriptor = descriptors[index];
+		if (descriptor === undefined) throw new DexFormatError("prototype_type");
+		return descriptor.startsWith("L") || descriptor.startsWith("[") ? "L" : descriptor;
+	};
+	const returns = Array.from({ length: protos.count }, (_, index) => {
+		const at = protos.offset + index * 12;
+		const result = shortType(uint(at + 4));
+		let shorty = result;
+		const parameters = uint(at + 8);
+		if (parameters !== 0) {
+			const section = sections.get(0x1001);
+			if (!section || parameters % 4 !== 0 || parameters < section.offset || parameters > section.end - 4) throw new DexFormatError("prototype_parameters");
+			const count = uint(parameters);
+			if (count > (section.end - parameters - 4) / 2) throw new DexFormatError("prototype_parameters");
+			for (let i = 0; i < count; i++) {
+				const type = shortType(view.getUint16(parameters + 4 + i * 2, true));
+				if (type === "V") throw new DexFormatError("prototype_type");
+				shorty += type;
+			}
+		}
+		if (!/^[VZBSCIJFDL][ZBSCIJFDL]*$/.test(shorty) || textAt(uint(at)) !== shorty) throw new DexFormatError("prototype_shorty");
+		return result;
+	});
+	const sources = new Map<number, { readonly packageName: string; readonly file: string }>();
+	const owners = new Map<number, number>();
+	const classData = sections.get(0x2000);
+	for (let i = 0; i < classes.count; i++) {
+		const at = classes.offset + i * 32;
+		const type = uint(at);
+		const descriptor = descriptors[type];
+		if (descriptor === undefined || !/^L[^.;[\]\s]+;$/.test(descriptor)) throw new DexFormatError("class");
+		const data = uint(at + 24);
+		if (data !== 0) {
+			if (!classData || data < classData.offset || data >= classData.end || owners.has(data)) throw new DexFormatError("class_data");
+			owners.set(data, type);
+		}
+		const sourceIndex = uint(at + 16);
+		if (sourceIndex === 0xffffffff) continue;
+		sources.set(type, { packageName: descriptor.slice(1, descriptor.lastIndexOf("/")).replaceAll("/", "."), file: textAt(sourceIndex) });
+	}
+	const references = Array.from({ length: methods.count }, (_, i) => {
+		const at = methods.offset + i * 8;
+		const type = view.getUint16(at, true);
+		if (type >= types.count) throw new DexFormatError("method");
+		const result = returns[view.getUint16(at + 2, true)];
+		if (result === undefined) throw new DexFormatError("method_prototype");
+		const name = textAt(uint(at + 4));
+		return { type, name, result };
+	});
+	const declared = new Set<string>();
+	if (classData) {
+		if (classData.count !== owners.size) throw new DexFormatError("class_data");
+		let cursor = classData.offset;
+		const uleb = () => {
+			let value = 0;
+			for (let shift = 0; ; shift += 7) {
+				const part = bytes[cursor++];
+				if (cursor > classData.end || part === undefined || (shift === 28 && part > 15)) throw new DexFormatError("class_data_uleb");
+				value += (part & 127) * 2 ** shift;
+				if (part < 128) return value;
+			}
+		};
+		for (let i = 0; i < classData.count; i++) {
+			const owner = owners.get(cursor);
+			if (owner === undefined) throw new DexFormatError("class_data");
+			const counts = [uleb(), uleb(), uleb(), uleb()];
+			const usedFields = new Set<number>(), usedMethods = new Set<number>();
+			for (const [group, count] of counts.entries()) {
+				const isMethod = group >= 2;
+				if (count > (isMethod ? methods.count : fields.count)) throw new DexFormatError("class_data_count");
+				let index = 0;
+				for (let entry = 0; entry < count; entry++) {
+					const delta = uleb();
+					index += delta;
+					const access = uleb();
+					const used = isMethod ? usedMethods : usedFields;
+					if ((entry > 0 && delta === 0) || used.has(index)) throw new DexFormatError("class_data_index");
+					used.add(index);
+					if (!isMethod) {
+						if (index >= fields.count || view.getUint16(fields.offset + index * 8, true) !== owner) throw new DexFormatError("field");
+						continue;
+					}
+					const method = references[index];
+					if (!method || method.type !== owner) throw new DexFormatError("method_owner");
+					const code = uleb();
+					const section = sections.get(0x2001);
+					const noCode = (access & (0x100 | 0x400)) !== 0;
+					if (noCode ? code !== 0 : !section || code % 4 !== 0 || code < section.offset || code > section.end - 16) throw new DexFormatError("method_code");
+					const source = sources.get(owner);
+					if (source && method.result !== "V") declared.add(`${source.packageName}\n${source.file}\n${method.name}`);
+				}
+			}
+		}
+		if (classData.end - cursor > 3 || bytes.subarray(cursor, classData.end).some((value) => value !== 0)) throw new DexFormatError("class_data_gap");
+	}
+	return Array.from({ length: ids.count }, (_, index) => {
+		const text = textAt(index);
+		// Compose compiler irTraceEventStart: "$kotlinFqName ($file:$line)".
+		// Shape alone is insufficient: require the same package, source file and JVM getter declaration.
+		const match = /^((?:[A-Za-z_$][A-Za-z0-9_$]*\.)+)<get-([A-Za-z_$][A-Za-z0-9_$]*)> \(([A-Za-z_$][A-Za-z0-9_$.]*\.kt):[0-9]+\)$/.exec(text);
+		const prefix = match?.[1], property = match?.[2], file = match?.[3];
+		const packageName = prefix?.slice(0, -1);
+		const getter = property === undefined ? "" : `get${property.slice(0, 1).toUpperCase()}${property.slice(1)}`;
+		const sourcePackage = packageName !== undefined && file !== undefined && declared.has(`${packageName}\n${file}\n${getter}`) ? packageName : null;
+		return { text, sourcePackage };
+	});
+}