Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

7.1 KB
Raw Blame
/**
 * Self-backup blob format: encode/decode the single encrypted artifact.
 *
 * Layout:
 *   MAGIC(4) | version(u16) | memory(u32) | passes(u32) | parallelism(u32) |
 *   salt(16) | nonce(12) | ciphertext(...) | tag(16)
 *
 * The header is plaintext by design: salt and KDF params only let you re-derive
 * the key from the password, they don't reveal it.
 *
 * This module imports ONLY node:crypto. No appPaths, no configService, so it stays
 * unit-testable with zero mocks, and the CLI restore path can import it without
 * pulling in the app module graph.
 */

import * as nodeCrypto from 'node:crypto';
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

/**
 * argon2id landed in Node core in v24 and is present in every runtime we ship
 * (verified by probe across the pkg-bundled Node 24 builds). `@types/node@22`, which is
 * this repo's pin, does not declare it yet, so bind a local signature rather
 * than bumping the global type package for a single function.
 */
type Argon2SyncFn = (
	algorithm: 'argon2id' | 'argon2i' | 'argon2d',
	options: {
		message: Buffer;
		nonce: Buffer;
		parallelism: number;
		tagLength: number;
		memory: number;
		passes: number;
		secret?: Buffer;
		associatedData?: Buffer;
	}
) => Buffer;

const argon2Sync = (nodeCrypto as unknown as { argon2Sync?: Argon2SyncFn }).argon2Sync;

export const MAGIC = 'PLBK';
export const FORMAT_VERSION = 1;

const MAGIC_LEN = 4;
const VERSION_LEN = 2;
const KDF_PARAMS_LEN = 12; // memory(4) + passes(4) + parallelism(4)
const SALT_LEN = 16;
const NONCE_LEN = 12;
const TAG_LEN = 16;

export const HEADER_LEN = MAGIC_LEN + VERSION_LEN + KDF_PARAMS_LEN + SALT_LEN + NONCE_LEN;

export interface KdfParams {
	/** Memory cost in KiB. */
	memory: number;
	/** Iterations. */
	passes: number;
	/** Lanes. */
	parallelism: number;
}

export const ARGON2_DEFAULTS: KdfParams = { memory: 65536, passes: 3, parallelism: 1 };

/**
 * Bounds on the KDF params we are willing to honour from a blob header.
 */
export const KDF_LIMITS = {
	/** 1 GiB, expressed in KiB to match `memory`. */
	maxMemory: 1024 * 1024,
	/** argon2's own floor is 8 KiB per lane. */
	minMemory: 8,
	maxPasses: 10,
	maxParallelism: 4,
};

function assertSaneKdfParams(kdf: KdfParams): void {
	const inRange = (value: number, min: number, max: number) =>
		Number.isInteger(value) && value >= min && value <= max;

	if (!inRange(kdf.memory, KDF_LIMITS.minMemory, KDF_LIMITS.maxMemory)) {
		throw new BlobDecryptError(
			`Blob header asks for an unreasonable KDF memory cost (${kdf.memory} KiB). ` +
				'The file is corrupt or was not written by Pluton.'
		);
	}
	if (!inRange(kdf.passes, 1, KDF_LIMITS.maxPasses)) {
		throw new BlobDecryptError(
			`Blob header asks for an unreasonable KDF pass count (${kdf.passes}). ` +
				'The file is corrupt or was not written by Pluton.'
		);
	}
	if (!inRange(kdf.parallelism, 1, KDF_LIMITS.maxParallelism)) {
		throw new BlobDecryptError(
			`Blob header asks for an unreasonable KDF parallelism (${kdf.parallelism}). ` +
				'The file is corrupt or was not written by Pluton.'
		);
	}
}

export interface ParsedHeader {
	version: number;
	kdf: KdfParams;
	salt: Buffer;
	nonce: Buffer;
	bodyOffset: number;
}

/** Thrown when a blob cannot be opened: bad magic, unknown version, wrong key, or tampering. */
export class BlobDecryptError extends Error {
	constructor(message: string) {
		super(message);
		this.name = 'BlobDecryptError';
	}
}

export function encodeHeader(kdf: KdfParams, salt: Buffer, nonce: Buffer): Buffer {
	if (salt.length !== SALT_LEN) {
		throw new Error(`salt must be ${SALT_LEN} bytes, got ${salt.length}`);
	}
	if (nonce.length !== NONCE_LEN) {
		throw new Error(`nonce must be ${NONCE_LEN} bytes, got ${nonce.length}`);
	}

	const header = Buffer.alloc(HEADER_LEN);
	let offset = 0;
	header.write(MAGIC, offset, MAGIC_LEN, 'ascii');
	offset += MAGIC_LEN;
	header.writeUInt16BE(FORMAT_VERSION, offset);
	offset += VERSION_LEN;
	header.writeUInt32BE(kdf.memory, offset);
	offset += 4;
	header.writeUInt32BE(kdf.passes, offset);
	offset += 4;
	header.writeUInt32BE(kdf.parallelism, offset);
	offset += 4;
	salt.copy(header, offset);
	offset += SALT_LEN;
	nonce.copy(header, offset);

	return header;
}

export function parseHeader(buf: Buffer): ParsedHeader {
	if (buf.length < HEADER_LEN + TAG_LEN) {
		throw new BlobDecryptError('Not a Pluton backup blob: file is too small.');
	}

	let offset = 0;
	const magic = buf.toString('ascii', 0, MAGIC_LEN);
	if (magic !== MAGIC) {
		throw new BlobDecryptError(
			`Not a Pluton backup blob: expected magic '${MAGIC}', found '${magic}'.`
		);
	}
	offset += MAGIC_LEN;

	const version = buf.readUInt16BE(offset);
	offset += VERSION_LEN;
	if (version !== FORMAT_VERSION) {
		throw new BlobDecryptError(
			`Unsupported blob format version ${version}. This Pluton understands version ${FORMAT_VERSION}. ` +
				'The blob was probably written by a newer Pluton.'
		);
	}

	const memory = buf.readUInt32BE(offset);
	offset += 4;
	const passes = buf.readUInt32BE(offset);
	offset += 4;
	const parallelism = buf.readUInt32BE(offset);
	offset += 4;

	const salt = buf.subarray(offset, offset + SALT_LEN);
	offset += SALT_LEN;
	const nonce = buf.subarray(offset, offset + NONCE_LEN);
	offset += NONCE_LEN;

	const kdf: KdfParams = { memory, passes, parallelism };
	// Checked before deriveKey() can act on them: these came off an unauthenticated header.
	assertSaneKdfParams(kdf);

	return { version, kdf, salt, nonce, bodyOffset: offset };
}

/**
 * Derive a 32-byte AES key from the user's ENCRYPTION_KEY.
 */
export function deriveKey(
	password: string,
	salt: Buffer,
	kdf: KdfParams = ARGON2_DEFAULTS
): Buffer {
	if (!argon2Sync) {
		throw new Error(
			'This Node runtime has no crypto.argon2Sync (added in Node 24). ' +
				'Pluton self-backup requires it to derive the blob encryption key.'
		);
	}
	return Buffer.from(
		argon2Sync('argon2id', {
			message: Buffer.from(password, 'utf-8'),
			nonce: salt,
			parallelism: kdf.parallelism,
			tagLength: 32,
			memory: kdf.memory,
			passes: kdf.passes,
		})
	);
}

export function sealBlob(tar: Buffer, password: string, kdf: KdfParams = ARGON2_DEFAULTS): Buffer {
	const salt = randomBytes(SALT_LEN);
	const nonce = randomBytes(NONCE_LEN);
	const key = deriveKey(password, salt, kdf);

	const cipher = createCipheriv('aes-256-gcm', key, nonce);
	const ciphertext = Buffer.concat([cipher.update(tar), cipher.final()]);
	const tag = cipher.getAuthTag();

	return Buffer.concat([encodeHeader(kdf, salt, nonce), ciphertext, tag]);
}

export function openBlob(blob: Buffer, password: string): Buffer {
	const { kdf, salt, nonce, bodyOffset } = parseHeader(blob);

	const tag = blob.subarray(blob.length - TAG_LEN);
	const ciphertext = blob.subarray(bodyOffset, blob.length - TAG_LEN);

	const key = deriveKey(password, salt, kdf);
	const decipher = createDecipheriv('aes-256-gcm', key, nonce);
	// setAuthTag before final() so a wrong key throws instead of yielding garbage.
	decipher.setAuthTag(tag);

	try {
		return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
	} catch {
		throw new BlobDecryptError(
			'Could not decrypt the blob. The encryption key is wrong, or the file is corrupt.'
		);
	}
}