Skip to content

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

TypeScript
6.0 KB
Raw Blame
/**
 * The web PIN on a server (S25.8, docs/deploy-vps.md). Without the desktop app there is no native
 * dialog, so the web page confirms connector changes and sending actions with a PIN the user sets
 * on first use. Only a salted scrypt hash is kept, in `<data>/web-pin.json` (mode 0600, in a folder
 * the engine's user cannot list), compared in constant time. After {@link PIN_ATTEMPTS} wrong tries
 * in a row it is locked for {@link PIN_LOCK_MS}; the count and the lock are in the same file, so a
 * restart does not reset them. Checks run one at a time, so tries sent together still count one by
 * one. The PIN reaches the daemon over the WebSocket and goes nowhere else: not to the engine, not
 * to a log. Forgotten PIN: remove the file on the server (docs/deploy-vps.md), then set a new one.
 */
import { randomBytes, type ScryptOptions, scrypt, timingSafeEqual } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { PIN_PATTERN, type PinStatus } from "@gentle-dot/protocol";
import { writePrivateFile } from "./private-file.ts";

export const PIN_FILE = "web-pin.json";
/** Wrong tries in a row before the PIN locks. */
export const PIN_ATTEMPTS = 5;
/** How long it stays locked. */
export const PIN_LOCK_MS = 15 * 60_000;

const SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 } as const;
const HASH_BYTES = 32;

export type PinOutcome =
	| { ok: true }
	| {
			ok: false;
			code: "pin_required" | "pin_wrong" | "pin_locked" | "pin_invalid" | "pin_exists";
			message: string;
	  };

interface Saved {
	version: 1;
	kdf: "scrypt";
	N: number;
	r: number;
	p: number;
	salt: string;
	hash: string;
	failures: number;
	lockedUntil: number;
}

const DAMAGED: PinOutcome = {
	ok: false,
	code: "pin_locked",
	message:
		"The PIN file on the server is damaged. Remove it on the server to set a new PIN (see the deploy guide).",
};

function derive(pin: string, salt: Buffer, options: ScryptOptions & { N: number }): Promise<Buffer> {
	return new Promise((resolve, reject) =>
		scrypt(pin, salt, HASH_BYTES, options, (error, key) => (error ? reject(error) : resolve(key))),
	);
}

export class PinGate {
	private readonly file: string;
	private readonly now: () => number;
	/** Every set and check, one after the other. */
	private queue: Promise<unknown> = Promise.resolve();

	constructor(options: { file: string; now?: () => number }) {
		this.file = options.file;
		this.now = options.now ?? Date.now;
	}

	status(): PinStatus {
		const saved = this.load();
		if (saved === undefined) return { set: false };
		if (saved === "damaged" || saved.lockedUntil > this.now()) return { set: true, locked: true };
		return { set: true };
	}

	/** Sets the PIN when there is none yet; never replaces one. */
	set(pin: string): Promise<PinOutcome> {
		return this.serial(async () => {
			if (!PIN_PATTERN.test(pin)) return { ok: false, code: "pin_invalid", message: "Use 6 to 12 digits." };
			const saved = this.load();
			if (saved === "damaged") return DAMAGED;
			if (saved !== undefined)
				return { ok: false, code: "pin_exists", message: "A PIN is already set for this assistant." };
			const salt = randomBytes(16);
			const hash = await derive(pin, salt, SCRYPT);
			const { N, r, p } = SCRYPT;
			this.save({
				version: 1,
				kdf: "scrypt",
				N,
				r,
				p,
				salt: salt.toString("base64"),
				hash: hash.toString("base64"),
				failures: 0,
				lockedUntil: 0,
			});
			return { ok: true };
		});
	}

	/** Checks the PIN; a wrong one counts towards the lock. */
	verify(pin: string): Promise<PinOutcome> {
		return this.serial(async () => {
			const saved = this.load();
			if (saved === "damaged") return DAMAGED;
			if (saved === undefined) return { ok: false, code: "pin_required", message: "Set a PIN first." };
			if (saved.lockedUntil > this.now()) return this.locked(saved);
			const expected = Buffer.from(saved.hash, "base64");
			const given = PIN_PATTERN.test(pin)
				? await derive(pin, Buffer.from(saved.salt, "base64"), {
						N: saved.N,
						r: saved.r,
						p: saved.p,
						maxmem: SCRYPT.maxmem,
					})
				: Buffer.alloc(expected.length);
			if (given.length === expected.length && timingSafeEqual(given, expected) && PIN_PATTERN.test(pin)) {
				if (saved.failures !== 0 || saved.lockedUntil !== 0)
					this.save({ ...saved, failures: 0, lockedUntil: 0 });
				return { ok: true };
			}
			const failures = saved.failures + 1;
			if (failures >= PIN_ATTEMPTS) {
				const lockedUntil = this.now() + PIN_LOCK_MS;
				this.save({ ...saved, failures: 0, lockedUntil });
				return this.locked({ ...saved, lockedUntil });
			}
			this.save({ ...saved, failures, lockedUntil: 0 });
			const left = PIN_ATTEMPTS - failures;
			return {
				ok: false,
				code: "pin_wrong",
				message: `Wrong PIN. ${left} ${left === 1 ? "try" : "tries"} left before it locks for ${PIN_LOCK_MS / 60_000} minutes.`,
			};
		});
	}

	private locked(saved: Saved): PinOutcome {
		const minutes = Math.max(1, Math.ceil((saved.lockedUntil - this.now()) / 60_000));
		return {
			ok: false,
			code: "pin_locked",
			message: `Too many wrong PINs. Try again in ${minutes} ${minutes === 1 ? "minute" : "minutes"}.`,
		};
	}

	private serial<T>(run: () => Promise<T>): Promise<T> {
		const next = this.queue.then(run, run);
		this.queue = next.catch(() => undefined);
		return next;
	}

	/** The saved PIN, undefined when none was set, or `damaged` when the file cannot be trusted. */
	private load(): Saved | undefined | "damaged" {
		if (!existsSync(this.file)) return undefined;
		try {
			const saved = JSON.parse(readFileSync(this.file, "utf8")) as Partial<Saved>;
			const numbers = [saved.N, saved.r, saved.p, saved.failures, saved.lockedUntil];
			if (
				saved.version === 1 &&
				saved.kdf === "scrypt" &&
				numbers.every((n) => Number.isSafeInteger(n) && (n as number) >= 0) &&
				typeof saved.salt === "string" &&
				typeof saved.hash === "string" &&
				Buffer.from(saved.hash, "base64").length === HASH_BYTES
			)
				return saved as Saved;
		} catch {}
		return "damaged";
	}

	private save(saved: Saved): void {
		writePrivateFile(this.file, `${JSON.stringify(saved)}\n`);
	}
}