Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
2.8 KB
Raw Blame
/**
 * The signature on `connectors.json` (S25.6, docs/design.md "Security"). The daemon signs every
 * write with HMAC-SHA256 under a random 32-byte key kept in the desktop app's secure store (id
 * {@link INTEGRITY_KEY_ID}), and at start, with the app, refuses a file whose signature does not
 * match: it was changed while Gentle Dot was closed. The key reaches the daemon over the app's
 * channel and stays in memory; it is never written to a file or a log.
 *
 * What is signed: the UTF-8 bytes of {@link MAC_DOMAIN} followed by the record without its `mac`
 * field in canonical JSON: no whitespace, every object's keys sorted by UTF-16 code unit (the
 * default `Array.prototype.sort`), arrays in their order, and strings, numbers, booleans, and null
 * as `JSON.stringify` writes them. The `mac` field is the lowercase hex digest.
 */
import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";

/** The secret id of the signing key in the app's store. */
export const INTEGRITY_KEY_ID = "integrity/connectors";

/** What every signed text starts with, so the key signs nothing else by accident. */
export const MAC_DOMAIN = "gentle-dot/connectors.json/v1\n";

const KEY_HEX = /^[0-9a-f]{64}$/;

/** A new signing key, as the hex text the app's store keeps. */
export function newIntegrityKey(): string {
	return randomBytes(32).toString("hex");
}

/** The key's bytes, or undefined when the stored text is not a key this daemon made. */
export function parseIntegrityKey(text: string | undefined): Buffer | undefined {
	return text !== undefined && KEY_HEX.test(text) ? Buffer.from(text, "hex") : undefined;
}

/** `value` as canonical JSON (see the module comment). */
export function canonicalJson(value: unknown): string {
	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item ?? null)).join(",")}]`;
	if (value !== null && typeof value === "object") {
		const record = value as Record<string, unknown>;
		const keys = Object.keys(record)
			.filter((key) => record[key] !== undefined)
			.sort();
		return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
	}
	return JSON.stringify(value) ?? "null";
}

/** The MAC of a record (its own `mac` field, if any, is left out). */
export function recordMac(key: Buffer, record: Record<string, unknown>): string {
	const { mac: _mac, ...rest } = record;
	return createHmac("sha256", key).update(MAC_DOMAIN).update(canonicalJson(rest)).digest("hex");
}

/** True when `record.mac` is the MAC of the rest under `key`; compared in constant time. */
export function macMatches(key: Buffer, record: Record<string, unknown>): boolean {
	const { mac } = record;
	if (typeof mac !== "string" || !/^[0-9a-f]{64}$/.test(mac)) return false;
	return timingSafeEqual(Buffer.from(mac, "hex"), Buffer.from(recordMac(key, record), "hex"));
}