@arkstack/encryption 0.18.0

package/dist/index.js

@@ -0,0 +1,1213 @@
+//#region src/support/codec.ts
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const HEX_PATTERN = /^[0-9a-f]*$/i;
+/**
+* Runtime agnostic binary/text conversion helpers.
+*
+* Everything here is implemented against `Uint8Array`, `TextEncoder` and
+* `TextDecoder` so the exact same code path runs in Node, Deno, Bun, browsers
+* and workers. No `Buffer`, no `node:crypto`.
+*/
+var Codec = class {
+	static encoder = new TextEncoder();
+	static decoder = new TextDecoder();
+	/**
+	* Encode a UTF-8 string to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static encodeUtf8(value) {
+		return this.encoder.encode(value);
+	}
+	/**
+	* Decode bytes back to a UTF-8 string.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static decodeUtf8(bytes) {
+		return this.decoder.decode(bytes);
+	}
+	/**
+	* Encode bytes as standard (padded) base64.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static encodeBase64(bytes) {
+		let binary = "";
+		for (let index = 0; index < bytes.length; index += 1) binary += String.fromCharCode(bytes[index]);
+		if (typeof globalThis.btoa === "function") return globalThis.btoa(binary);
+		return this.fallbackEncodeBase64(bytes);
+	}
+	/**
+	* Decode standard (padded or unpadded) base64 to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static decodeBase64(value) {
+		const normalized = value.replace(/\s+/g, "");
+		if (typeof globalThis.atob === "function") {
+			const binary = globalThis.atob(this.pad(normalized));
+			const bytes = new Uint8Array(binary.length);
+			for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+			return bytes;
+		}
+		return this.fallbackDecodeBase64(this.pad(normalized));
+	}
+	/**
+	* Encode bytes as unpadded base64url, the wire format used by every
+	* Arkstack encryption payload.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static encodeBase64Url(bytes) {
+		return this.encodeBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+	}
+	/**
+	* Decode a base64url string to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static decodeBase64Url(value) {
+		return this.decodeBase64(value.replace(/-/g, "+").replace(/_/g, "/"));
+	}
+	/**
+	* Encode bytes as lowercase hex.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static encodeHex(bytes) {
+		let hex = "";
+		for (let index = 0; index < bytes.length; index += 1) hex += bytes[index].toString(16).padStart(2, "0");
+		return hex;
+	}
+	/**
+	* Decode a hex string to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static decodeHex(value) {
+		if (value.length % 2 !== 0 || !HEX_PATTERN.test(value)) throw new TypeError("Invalid hex string");
+		const bytes = new Uint8Array(value.length / 2);
+		for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+		return bytes;
+	}
+	/**
+	* Concatenate byte sequences into a single buffer.
+	*
+	* @param parts
+	* @returns
+	*/
+	static concat(...parts) {
+		const total = parts.reduce((size, part) => size + part.length, 0);
+		const output = new Uint8Array(total);
+		let offset = 0;
+		for (const part of parts) {
+			output.set(part, offset);
+			offset += part.length;
+		}
+		return output;
+	}
+	/**
+	* Compare two byte sequences without leaking their contents through timing.
+	*
+	* The length check is intentionally not constant time; key and digest
+	* lengths are public information.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static equals(left, right) {
+		if (left.length !== right.length) return false;
+		let difference = 0;
+		for (let index = 0; index < left.length; index += 1) difference |= left[index] ^ right[index];
+		return difference === 0;
+	}
+	/**
+	* Normalize a `Uint8Array`, `ArrayBuffer` or `ArrayBufferView` to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static toBytes(value) {
+		if (value instanceof Uint8Array) return value;
+		if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+		return new Uint8Array(value);
+	}
+	/**
+	* Restore base64 padding stripped by the base64url encoding.
+	*
+	* @param value
+	* @returns
+	*/
+	static pad(value) {
+		const remainder = value.length % 4;
+		return remainder === 0 ? value : value + "=".repeat(4 - remainder);
+	}
+	/**
+	* Pure JS base64 encoder used when `btoa` is unavailable.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static fallbackEncodeBase64(bytes) {
+		let output = "";
+		for (let index = 0; index < bytes.length; index += 3) {
+			const chunk = bytes[index] << 16 | (bytes[index + 1] ?? 0) << 8 | (bytes[index + 2] ?? 0);
+			const available = bytes.length - index;
+			output += BASE64_ALPHABET[chunk >> 18 & 63];
+			output += BASE64_ALPHABET[chunk >> 12 & 63];
+			output += available > 1 ? BASE64_ALPHABET[chunk >> 6 & 63] : "=";
+			output += available > 2 ? BASE64_ALPHABET[chunk & 63] : "=";
+		}
+		return output;
+	}
+	/**
+	* Pure JS base64 decoder used when `atob` is unavailable.
+	*
+	* @param value
+	* @returns
+	*/
+	static fallbackDecodeBase64(value) {
+		const clean = value.replace(/=+$/, "");
+		const bytes = new Uint8Array(clean.length * 3 >> 2);
+		let buffer = 0;
+		let bits = 0;
+		let offset = 0;
+		for (const character of clean) {
+			const index = BASE64_ALPHABET.indexOf(character);
+			if (index < 0) throw new TypeError("Invalid base64 string");
+			buffer = buffer << 6 | index;
+			bits += 6;
+			if (bits >= 8) {
+				bits -= 8;
+				bytes[offset++] = buffer >> bits & 255;
+			}
+		}
+		return bytes;
+	}
+};
+//#endregion
+//#region src/support/subtle.ts
+/**
+* Resolve the ambient Web Crypto implementation.
+*
+* Node exposes it as `globalThis.crypto` from v19 (and behind
+* `node:crypto`'s `webcrypto` export from v15), browsers and workers expose it
+* on `window`/`self`. Secure contexts are required in browsers, hence the
+* explicit error message.
+*
+* @returns
+*/
+const webCrypto = () => {
+	const candidate = globalThis.crypto;
+	if (!candidate?.subtle) throw new Error("The Web Crypto API is unavailable. @arkstack/encryption requires Node 19+ (or Node 18 with `globalThis.crypto` enabled) and a secure context (https or localhost) in browsers.");
+	return candidate;
+};
+/**
+* Resolve `crypto.subtle`.
+*
+* @returns
+*/
+const subtle = () => webCrypto().subtle;
+/**
+* Fill a buffer with cryptographically secure random bytes.
+*
+* @param length
+* @returns
+*/
+const randomBytes = (length) => {
+	if (!Number.isInteger(length) || length < 1) throw new RangeError("Random byte length must be a positive integer");
+	return webCrypto().getRandomValues(new Uint8Array(length));
+};
+/**
+* SHA digest helper returning bytes instead of an `ArrayBuffer`.
+*
+* @param data
+* @param algorithm
+* @returns
+*/
+const digest = async (data, algorithm = "SHA-256") => {
+	return new Uint8Array(await subtle().digest(algorithm, data));
+};
+//#endregion
+//#region src/EncryptionKey.ts
+const DEFAULT_ITERATIONS = 21e4;
+const DEFAULT_LENGTH = 32;
+/**
+* A symmetric key, held as raw bytes and convertible to every representation
+* the rest of the library (and the wire) needs.
+*
+* Keys are values: two keys with the same bytes are equal regardless of how
+* they were produced, and comparison is constant time.
+*/
+var EncryptionKey = class EncryptionKey {
+	bytes;
+	/**
+	* @param bytes Raw key material.
+	*/
+	constructor(bytes) {
+		this.bytes = bytes;
+		if (bytes.length === 0) throw new RangeError("An encryption key cannot be empty");
+	}
+	/**
+	* Generate a random key.
+	*
+	* @param length Key length in bytes, defaults to 32 (AES-256).
+	* @returns
+	*/
+	static generate(length = DEFAULT_LENGTH) {
+		return new EncryptionKey(randomBytes(length));
+	}
+	/**
+	* Derive a key from an arbitrary secret by hashing it with SHA-256.
+	*
+	* This mirrors how Arkstack turns `APP_KEY` into a cipher key, so a value
+	* encrypted on the server with the app key can be decrypted in the browser
+	* from the same secret.
+	*
+	* @param secret
+	* @returns
+	*/
+	static async fromSecret(secret) {
+		return new EncryptionKey(await digest(Codec.encodeUtf8(secret)));
+	}
+	/**
+	* Restore a key from its base64url representation.
+	*
+	* @param value
+	* @returns
+	*/
+	static fromBase64Url(value) {
+		return new EncryptionKey(Codec.decodeBase64Url(value));
+	}
+	/**
+	* Restore a key from its hex representation.
+	*
+	* @param value
+	* @returns
+	*/
+	static fromHex(value) {
+		return new EncryptionKey(Codec.decodeHex(value));
+	}
+	/**
+	* Stretch a password into a key using PBKDF2-HMAC-SHA256.
+	*
+	* Prefer this over {@link fromSecret} for anything a human typed; the
+	* returned salt and iteration count must be stored alongside the
+	* ciphertext to reproduce the key later.
+	*
+	* @param password
+	* @param options
+	* @returns
+	*/
+	static async derive(password, options = {}) {
+		const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+		const length = options.length ?? DEFAULT_LENGTH;
+		const salt = typeof options.salt === "string" ? Codec.decodeBase64Url(options.salt) : options.salt ?? randomBytes(16);
+		const material = await subtle().importKey("raw", Codec.encodeUtf8(password), "PBKDF2", false, ["deriveBits"]);
+		const bits = await subtle().deriveBits({
+			name: "PBKDF2",
+			salt,
+			iterations,
+			hash: "SHA-256"
+		}, material, length * 8);
+		return {
+			key: new EncryptionKey(new Uint8Array(bits)),
+			salt: Codec.encodeBase64Url(salt),
+			iterations
+		};
+	}
+	/**
+	* Expand shared secret material into a key using HKDF-SHA256.
+	*
+	* Used internally by the ECDH channel and sealed box helpers, and exposed
+	* because deriving sub-keys from one root key is a common need.
+	*
+	* @param material
+	* @param salt
+	* @param info
+	* @param length
+	* @returns
+	*/
+	static async expand(material, salt, info, length = DEFAULT_LENGTH) {
+		const base = await subtle().importKey("raw", material, "HKDF", false, ["deriveBits"]);
+		const bits = await subtle().deriveBits({
+			name: "HKDF",
+			hash: "SHA-256",
+			salt,
+			info: Codec.encodeUtf8(info)
+		}, base, length * 8);
+		return new EncryptionKey(new Uint8Array(bits));
+	}
+	/**
+	* Coerce any accepted key representation into an `EncryptionKey`.
+	*
+	* A string of exactly `length` bytes once base64url decoded is treated as
+	* raw key material; anything else is treated as a passphrase and hashed.
+	*
+	* @param input
+	* @param length Expected key length in bytes.
+	* @returns
+	*/
+	static async resolve(input, length = DEFAULT_LENGTH) {
+		if (input instanceof EncryptionKey) return input;
+		if (input instanceof Uint8Array) return new EncryptionKey(input);
+		if (typeof input === "string") {
+			if (/^[A-Za-z0-9_-]+$/.test(input)) try {
+				const decoded = Codec.decodeBase64Url(input);
+				if (decoded.length === length) return new EncryptionKey(decoded);
+			} catch {}
+			return await this.fromSecret(input);
+		}
+		const exported = await subtle().exportKey("raw", input);
+		return new EncryptionKey(new Uint8Array(exported));
+	}
+	/**
+	* Constant time comparison of two keys, in any representation that does not
+	* require asynchronous work.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static compare(left, right) {
+		return Codec.equals(this.materialize(left), this.materialize(right));
+	}
+	/**
+	* Import this key into Web Crypto for the given algorithm.
+	*
+	* @param algorithm
+	* @param usages
+	* @returns
+	*/
+	async cryptoKey(algorithm = { name: "AES-GCM" }, usages = ["encrypt", "decrypt"]) {
+		return await subtle().importKey("raw", this.bytes, algorithm, false, usages);
+	}
+	/**
+	* A stable, shareable digest of this key. Safe to log or display; it does
+	* not reveal the key itself.
+	*
+	* @param options
+	* @returns
+	*/
+	async fingerprint(options = {}) {
+		const bytes = (await digest(this.bytes)).slice(0, options.length ?? 32);
+		const rendered = options.encoding === "base64url" ? Codec.encodeBase64Url(bytes) : Codec.encodeHex(bytes);
+		if (!options.group) return rendered;
+		return rendered.match(new RegExp(`.{1,${options.group}}`, "g"))?.join(" ") ?? rendered;
+	}
+	/**
+	* Constant time comparison against another key.
+	*
+	* @param other
+	* @returns
+	*/
+	equals(other) {
+		return EncryptionKey.compare(this, other);
+	}
+	/**
+	* Key length in bytes.
+	*
+	* @returns
+	*/
+	get length() {
+		return this.bytes.length;
+	}
+	/**
+	* Base64url representation, the format used to persist and transport keys.
+	*
+	* @returns
+	*/
+	toBase64Url() {
+		return Codec.encodeBase64Url(this.bytes);
+	}
+	/**
+	* Hex representation.
+	*
+	* @returns
+	*/
+	toHex() {
+		return Codec.encodeHex(this.bytes);
+	}
+	/**
+	* Base64url representation.
+	*
+	* @returns
+	*/
+	toString() {
+		return this.toBase64Url();
+	}
+	/**
+	* Keep keys out of accidental `JSON.stringify` output of surrounding
+	* objects by requiring an explicit `toBase64Url()` call.
+	*
+	* @returns
+	*/
+	toJSON() {
+		return "[EncryptionKey]";
+	}
+	/**
+	* Reduce a comparable key representation to bytes.
+	*
+	* @param value
+	* @returns
+	*/
+	static materialize(value) {
+		if (value instanceof EncryptionKey) return value.bytes;
+		if (value instanceof Uint8Array) return value;
+		return Codec.decodeBase64Url(value);
+	}
+};
+//#endregion
+//#region src/Cipher.ts
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const PAYLOAD_PATTERN = /^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+:[A-Za-z0-9_-]*$/;
+/**
+* AES-256-GCM symmetric encryption built on the Web Crypto API.
+*
+* Payloads are colon delimited base64url triples — `<iv>:<authTag>:<ciphertext>`
+* — which is byte for byte the format Arkstack has always written. A value
+* encrypted by a Node server decrypts in the browser and vice versa, provided
+* both sides hold the same key.
+*/
+var Cipher = class Cipher {
+	key;
+	/** Initialisation vector length in bytes. */
+	static ivLength = IV_LENGTH;
+	/** GCM authentication tag length in bytes. */
+	static tagLength = TAG_LENGTH;
+	/**
+	* @param key The symmetric key this cipher operates with.
+	*/
+	constructor(key) {
+		this.key = key;
+	}
+	/**
+	* Build a cipher from any accepted key representation.
+	*
+	* @param key
+	* @returns
+	*/
+	static async from(key) {
+		return new Cipher(await EncryptionKey.resolve(key));
+	}
+	/**
+	* Build a cipher backed by a freshly generated random key.
+	*
+	* @returns
+	*/
+	static create() {
+		return new Cipher(EncryptionKey.generate());
+	}
+	/**
+	* Encrypt a string.
+	*
+	* @param value
+	* @param key
+	* @param options
+	* @returns
+	*/
+	static async encrypt(value, key, options = {}) {
+		return await (await this.from(key)).encrypt(value, options);
+	}
+	/**
+	* Decrypt a payload produced by {@link encrypt}.
+	*
+	* @param payload
+	* @param key
+	* @param options
+	* @returns
+	*/
+	static async decrypt(payload, key, options = {}) {
+		return await (await this.from(key)).decrypt(payload, options);
+	}
+	/**
+	* Whether a string is shaped like a cipher payload. A cheap structural
+	* check, not an authenticity check.
+	*
+	* @param value
+	* @returns
+	*/
+	static looksLikePayload(value) {
+		return typeof value === "string" && PAYLOAD_PATTERN.test(value);
+	}
+	/**
+	* Encrypt a UTF-8 string.
+	*
+	* @param value
+	* @param options
+	* @returns
+	*/
+	async encrypt(value, options = {}) {
+		return await this.encryptBytes(Codec.encodeUtf8(value), options);
+	}
+	/**
+	* Decrypt a payload back into a UTF-8 string.
+	*
+	* @param payload
+	* @param options
+	* @returns
+	*/
+	async decrypt(payload, options = {}) {
+		return Codec.decodeUtf8(await this.decryptBytes(payload, options));
+	}
+	/**
+	* Encrypt arbitrary bytes.
+	*
+	* @param bytes
+	* @param options
+	* @returns
+	*/
+	async encryptBytes(bytes, options = {}) {
+		const iv = randomBytes(IV_LENGTH);
+		const sealed = new Uint8Array(await subtle().encrypt(this.parameters(iv, options), await this.cryptoKey(), bytes));
+		const boundary = sealed.length - TAG_LENGTH;
+		return [
+			iv,
+			sealed.slice(boundary),
+			sealed.slice(0, boundary)
+		].map((part) => Codec.encodeBase64Url(part)).join(":");
+	}
+	/**
+	* Decrypt a payload back into raw bytes.
+	*
+	* @param payload
+	* @param options
+	* @returns
+	*/
+	async decryptBytes(payload, options = {}) {
+		const [iv, authTag, ciphertext] = payload.split(":");
+		if (!iv || !authTag || ciphertext === void 0) throw new Error("Invalid encrypted payload format");
+		const sealed = Codec.concat(Codec.decodeBase64Url(ciphertext), Codec.decodeBase64Url(authTag));
+		try {
+			const plaintext = await subtle().decrypt(this.parameters(Codec.decodeBase64Url(iv), options), await this.cryptoKey(), sealed);
+			return new Uint8Array(plaintext);
+		} catch {
+			throw new Error("Unable to decrypt payload: the key is wrong or the ciphertext was tampered with");
+		}
+	}
+	/**
+	* Import the key once per cipher instance.
+	*
+	* @returns
+	*/
+	async cryptoKey() {
+		this.imported ??= this.key.cryptoKey({ name: "AES-GCM" }, ["encrypt", "decrypt"]);
+		return await this.imported;
+	}
+	/**
+	* Build the AES-GCM parameters for a single operation.
+	*
+	* @param iv
+	* @param options
+	* @returns
+	*/
+	parameters(iv, options) {
+		const aad = typeof options.aad === "string" ? Codec.encodeUtf8(options.aad) : options.aad;
+		return {
+			name: "AES-GCM",
+			iv,
+			tagLength: 128,
+			...aad ? { additionalData: aad } : {}
+		};
+	}
+	imported;
+};
+//#endregion
+//#region src/KeyPair.ts
+const ALGORITHM = {
+	name: "ECDH",
+	namedCurve: "P-256"
+};
+/**
+* An ECDH P-256 key pair — the identity half of end-to-end encryption.
+*
+* P-256 is the curve every mainstream Web Crypto implementation supports, so a
+* key pair generated in Node imports cleanly in the browser and vice versa.
+* Keys serialise to base64url DER (SPKI for public, PKCS#8 for private), which
+* survives JSON, headers, query strings and database columns unchanged.
+*/
+var KeyPair = class KeyPair {
+	publicKey;
+	privateKey;
+	/**
+	* @param publicKey
+	* @param privateKey Absent for peer key pairs, where only the public half is known.
+	*/
+	constructor(publicKey, privateKey) {
+		this.publicKey = publicKey;
+		this.privateKey = privateKey;
+	}
+	/**
+	* Generate a new key pair.
+	*
+	* @returns
+	*/
+	static async generate() {
+		const pair = await subtle().generateKey(ALGORITHM, true, ["deriveBits"]);
+		return new KeyPair(pair.publicKey, pair.privateKey);
+	}
+	/**
+	* Restore a key pair from its serialised form.
+	*
+	* @param serialized
+	* @returns
+	*/
+	static async import(serialized) {
+		return new KeyPair(await this.importPublicKey(serialized.publicKey), await this.importPrivateKey(serialized.privateKey));
+	}
+	/**
+	* Restore a full key pair from the private half alone; the public key is
+	* recovered from the private key's curve point.
+	*
+	* @param privateKey
+	* @returns
+	*/
+	static async fromPrivateKey(privateKey) {
+		const imported = typeof privateKey === "string" ? await this.importPrivateKey(privateKey) : privateKey;
+		const jwk = await subtle().exportKey("jwk", imported);
+		delete jwk.d;
+		jwk.key_ops = [];
+		const publicKey = await subtle().importKey("jwk", jwk, ALGORITHM, true, []);
+		return new KeyPair(publicKey, imported);
+	}
+	/**
+	* Wrap a peer's public key. The result can verify fingerprints and receive
+	* sealed messages, but cannot derive shared secrets on its own.
+	*
+	* @param publicKey
+	* @returns
+	*/
+	static async fromPublicKey(publicKey) {
+		return new KeyPair(typeof publicKey === "string" ? await this.importPublicKey(publicKey) : publicKey);
+	}
+	/**
+	* Import a base64url SPKI public key.
+	*
+	* @param publicKey
+	* @returns
+	*/
+	static async importPublicKey(publicKey) {
+		return await subtle().importKey("spki", Codec.decodeBase64Url(publicKey), ALGORITHM, true, []);
+	}
+	/**
+	* Import a base64url PKCS#8 private key.
+	*
+	* @param privateKey
+	* @returns
+	*/
+	static async importPrivateKey(privateKey) {
+		return await subtle().importKey("pkcs8", Codec.decodeBase64Url(privateKey), ALGORITHM, true, ["deriveBits"]);
+	}
+	/**
+	* Export a public key to its base64url SPKI form.
+	*
+	* @param publicKey
+	* @returns
+	*/
+	static async exportPublicKey(publicKey) {
+		return Codec.encodeBase64Url(new Uint8Array(await subtle().exportKey("spki", publicKey)));
+	}
+	/**
+	* Derive raw ECDH shared bits between a private key and a peer public key.
+	*
+	* The result is the raw curve point and must be stretched with a KDF before
+	* use as a cipher key — {@link SecureChannel} does that for you.
+	*
+	* @param privateKey
+	* @param peerPublicKey
+	* @param length Output length in bits, defaults to the P-256 field size.
+	* @returns
+	*/
+	static async sharedBits(privateKey, peerPublicKey, length = 256) {
+		const bits = await subtle().deriveBits({
+			name: "ECDH",
+			public: peerPublicKey
+		}, privateKey, length);
+		return new Uint8Array(bits);
+	}
+	/**
+	* A human comparable digest of a public key. Two peers reading the same
+	* fingerprint aloud are holding the same key.
+	*
+	* @param publicKey
+	* @param options
+	* @returns
+	*/
+	static async fingerprintOf(publicKey, options = {}) {
+		const exported = typeof publicKey === "string" ? publicKey : await this.exportPublicKey(publicKey);
+		return await new EncryptionKey(Codec.decodeBase64Url(exported)).fingerprint({
+			group: 8,
+			...options
+		});
+	}
+	/**
+	* The digest of both participants' public keys, ordered deterministically
+	* so each side computes the same value. Rendered as five digit groups in
+	* the style of a messaging app's safety number.
+	*
+	* @param first
+	* @param second
+	* @param groups How many five digit groups to render, defaults to 12.
+	* @returns
+	*/
+	static async safetyNumber(first, second, groups = 12) {
+		const bytes = await digest(Codec.encodeUtf8(this.order(first, second).join("|")));
+		const blocks = [];
+		for (let index = 0; index < groups; index += 1) {
+			const offset = index * 3 % (bytes.length - 3);
+			const chunk = bytes[offset] << 16 | bytes[offset + 1] << 8 | bytes[offset + 2];
+			blocks.push(String(chunk % 1e5).padStart(5, "0"));
+		}
+		return blocks.join(" ");
+	}
+	/**
+	* Order two public keys deterministically so both peers derive identical
+	* salts and safety numbers regardless of who initiated.
+	*
+	* @param first
+	* @param second
+	* @returns
+	*/
+	static order(first, second) {
+		return first <= second ? [first, second] : [second, first];
+	}
+	/**
+	* Whether the private half is available.
+	*
+	* @returns
+	*/
+	get isComplete() {
+		return this.privateKey !== void 0;
+	}
+	/**
+	* Serialise both halves. Throws when the private key is missing.
+	*
+	* @returns
+	*/
+	async export() {
+		if (!this.privateKey) throw new Error("Cannot export a key pair without its private key");
+		return {
+			publicKey: await this.exportPublicKey(),
+			privateKey: Codec.encodeBase64Url(new Uint8Array(await subtle().exportKey("pkcs8", this.privateKey)))
+		};
+	}
+	/**
+	* The base64url SPKI public key, safe to publish.
+	*
+	* @returns
+	*/
+	async exportPublicKey() {
+		return await KeyPair.exportPublicKey(this.publicKey);
+	}
+	/**
+	* Derive the raw ECDH shared bits with a peer.
+	*
+	* @param peerPublicKey
+	* @returns
+	*/
+	async sharedBits(peerPublicKey) {
+		if (!this.privateKey) throw new Error("Cannot derive a shared secret without a private key");
+		return await KeyPair.sharedBits(this.privateKey, await KeyPair.resolvePublic(peerPublicKey));
+	}
+	/**
+	* A comparable digest of this key pair's public key.
+	*
+	* @param options
+	* @returns
+	*/
+	async fingerprint(options = {}) {
+		return await KeyPair.fingerprintOf(this.publicKey, options);
+	}
+	/**
+	* Normalise anything that can stand in for a public key.
+	*
+	* @param value
+	* @returns
+	*/
+	static async resolvePublic(value) {
+		if (value instanceof KeyPair) return value.publicKey;
+		return typeof value === "string" ? await this.importPublicKey(value) : value;
+	}
+};
+//#endregion
+//#region src/Keys.ts
+/**
+* Key generation and comparison helpers.
+*
+* Generating keys is easy to get wrong quietly and comparing them is easy to
+* get wrong dangerously, so both live here: every comparison in this class runs
+* in constant time, and every generator draws from the platform CSPRNG.
+*/
+var Keys = class {
+	/**
+	* Generate a random symmetric key.
+	*
+	* @param length Key length in bytes, defaults to 32 (AES-256).
+	* @returns
+	*/
+	static generate(length = 32) {
+		return EncryptionKey.generate(length);
+	}
+	/**
+	* Generate a random symmetric key as a base64url string, ready to store in
+	* an environment variable or a database column.
+	*
+	* @param length
+	* @returns
+	*/
+	static generateString(length = 32) {
+		return this.generate(length).toBase64Url();
+	}
+	/**
+	* Generate a random, URL safe token. Not a key — use it for invites,
+	* one-time links and other opaque identifiers.
+	*
+	* @param bytes
+	* @returns
+	*/
+	static token(bytes = 32) {
+		return Codec.encodeBase64Url(randomBytes(bytes));
+	}
+	/**
+	* Generate an end-to-end encryption identity: an ECDH key pair whose public
+	* half is published and whose private half never leaves its owner.
+	*
+	* @returns
+	*/
+	static async generatePair() {
+		return await KeyPair.generate();
+	}
+	/**
+	* Generate an identity and return it already serialised for storage or
+	* transport.
+	*
+	* @returns
+	*/
+	static async generateSerializedPair() {
+		return await (await KeyPair.generate()).export();
+	}
+	/**
+	* Hash an arbitrary secret into a key with SHA-256, the same way Arkstack
+	* turns `APP_KEY` into a cipher key.
+	*
+	* @param secret
+	* @returns
+	*/
+	static async fromSecret(secret) {
+		return await EncryptionKey.fromSecret(secret);
+	}
+	/**
+	* Stretch a user supplied password into a key with PBKDF2-HMAC-SHA256.
+	*
+	* @param password
+	* @param options
+	* @returns
+	*/
+	static async derive(password, options = {}) {
+		return await EncryptionKey.derive(password, options);
+	}
+	/**
+	* Constant time comparison of two keys already in key form.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static compare(left, right) {
+		try {
+			return EncryptionKey.compare(left, right);
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Constant time comparison that first resolves both sides through the same
+	* rules the ciphers use, so a passphrase can be checked against the key it
+	* produces.
+	*
+	* @param left
+	* @param right
+	* @param length Expected key length in bytes.
+	* @returns
+	*/
+	static async matches(left, right, length = 32) {
+		try {
+			return EncryptionKey.compare(await EncryptionKey.resolve(left, length), await EncryptionKey.resolve(right, length));
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* A displayable digest of a symmetric key.
+	*
+	* @param key
+	* @param options
+	* @returns
+	*/
+	static async fingerprint(key, options = {}) {
+		return await (await EncryptionKey.resolve(key)).fingerprint({
+			length: 16,
+			group: 8,
+			...options
+		});
+	}
+	/**
+	* A displayable digest of a public key, for comparing identities.
+	*
+	* @param publicKey
+	* @param options
+	* @returns
+	*/
+	static async fingerprintPublicKey(publicKey, options = {}) {
+		return await KeyPair.fingerprintOf(publicKey, {
+			length: 16,
+			group: 8,
+			...options
+		});
+	}
+	/**
+	* The safety number for a conversation between two public keys. Both peers
+	* compute the same string; showing it side by side proves no third party
+	* substituted a key in transit.
+	*
+	* @param first
+	* @param second
+	* @param groups
+	* @returns
+	*/
+	static async safetyNumber(first, second, groups = 12) {
+		return await KeyPair.safetyNumber(first, second, groups);
+	}
+	/**
+	* Confirm a safety number a user read out or scanned, in constant time.
+	*
+	* @param first
+	* @param second
+	* @param expected
+	* @returns
+	*/
+	static async confirmSafetyNumber(first, second, expected) {
+		const normalize = (value) => Codec.encodeUtf8(value.replace(/\s+/g, ""));
+		return Codec.equals(normalize(await this.safetyNumber(first, second)), normalize(expected));
+	}
+	/**
+	* Whether two public keys refer to the same identity.
+	*
+	* @param left
+	* @param right
+	* @returns
+	*/
+	static async samePublicKey(left, right) {
+		const exported = async (value) => {
+			if (typeof value === "string") return value;
+			return await KeyPair.exportPublicKey(await KeyPair.resolvePublic(value));
+		};
+		return Codec.equals(Codec.decodeBase64Url(await exported(left)), Codec.decodeBase64Url(await exported(right)));
+	}
+};
+//#endregion
+//#region src/SecureChannel.ts
+const CONTEXT$1 = "arkstack/e2ee/v1";
+/**
+* A two party end-to-end encrypted channel.
+*
+* Each side combines its own private key with the other side's public key over
+* ECDH, stretches the result with HKDF-SHA256, and ends up holding the exact
+* same AES-256-GCM key without that key ever crossing the wire. Messages
+* encrypted by either peer — in Node or in a browser — decrypt on the other.
+*
+* ```ts
+* const alice = await KeyPair.generate()
+* const bob = await KeyPair.generate()
+*
+* const outbound = await SecureChannel.between(alice, await bob.exportPublicKey())
+* const inbound = await SecureChannel.between(bob, await alice.exportPublicKey())
+*
+* await inbound.decrypt(await outbound.encrypt('hey')) // 'hey'
+* ```
+*/
+var SecureChannel = class SecureChannel {
+	cipher;
+	localPublicKey;
+	remotePublicKey;
+	/**
+	* @param cipher          The cipher bound to the derived shared key.
+	* @param localPublicKey  This side's public key, base64url.
+	* @param remotePublicKey The peer's public key, base64url.
+	*/
+	constructor(cipher, localPublicKey, remotePublicKey) {
+		this.cipher = cipher;
+		this.localPublicKey = localPublicKey;
+		this.remotePublicKey = remotePublicKey;
+	}
+	/**
+	* Open a channel between a local key pair (or private key) and a peer's
+	* public key.
+	*
+	* @param local
+	* @param peerPublicKey
+	* @param options
+	* @returns
+	*/
+	static async between(local, peerPublicKey, options = {}) {
+		const pair = local instanceof KeyPair ? local : await KeyPair.fromPrivateKey(local);
+		if (!pair.isComplete) throw new Error("A secure channel requires the local private key");
+		const remote = await KeyPair.resolvePublic(peerPublicKey);
+		const localPublicKey = await pair.exportPublicKey();
+		const remotePublicKey = await KeyPair.exportPublicKey(remote);
+		const key = await EncryptionKey.expand(await pair.sharedBits(remote), await this.salt(localPublicKey, remotePublicKey), options.info ? `${CONTEXT$1}:${options.info}` : CONTEXT$1);
+		return new SecureChannel(new Cipher(key), localPublicKey, remotePublicKey);
+	}
+	/**
+	* The HKDF salt for a pair of participants: a digest over both public keys
+	* in a deterministic order, so both sides compute the same value.
+	*
+	* @param first
+	* @param second
+	* @returns
+	*/
+	static async salt(first, second) {
+		return await digest(Codec.encodeUtf8(KeyPair.order(first, second).join("|")));
+	}
+	/**
+	* The shared key both peers derived. Persist it only if you intend to skip
+	* the handshake later; it is as sensitive as the messages themselves.
+	*
+	* @returns
+	*/
+	get key() {
+		return this.cipher.key;
+	}
+	/**
+	* Encrypt a message for the peer.
+	*
+	* @param message
+	* @param options
+	* @returns
+	*/
+	async encrypt(message, options = {}) {
+		return await this.cipher.encrypt(message, options);
+	}
+	/**
+	* Decrypt a message from the peer.
+	*
+	* @param payload
+	* @param options
+	* @returns
+	*/
+	async decrypt(payload, options = {}) {
+		return await this.cipher.decrypt(payload, options);
+	}
+	/**
+	* Fingerprint of the derived shared key. Identical on both sides, and the
+	* cheapest way to assert two peers really did agree on the same secret.
+	*
+	* @param options
+	* @returns
+	*/
+	async fingerprint(options = {}) {
+		return await this.key.fingerprint({
+			length: 16,
+			group: 8,
+			...options
+		});
+	}
+	/**
+	* The conversation's safety number: show it to both participants so they
+	* can confirm out of band that nobody is sitting in the middle.
+	*
+	* @param groups
+	* @returns
+	*/
+	async safetyNumber(groups = 12) {
+		return await KeyPair.safetyNumber(this.localPublicKey, this.remotePublicKey, groups);
+	}
+};
+//#endregion
+//#region src/SealedBox.ts
+const PREFIX = "ark1";
+const CONTEXT = "arkstack/sealed/v1";
+/**
+* Anonymous encryption to a public key.
+*
+* The sender needs no identity of their own: a throwaway key pair is generated
+* per message, agreed with the recipient's public key over ECDH, and its public
+* half is carried in the payload so the recipient can reproduce the secret.
+* Only the holder of the matching private key can open the result — including
+* the sender, who cannot decrypt their own message afterwards.
+*
+* Payloads look like `ark1:<ephemeralPublicKey>:<iv>:<authTag>:<ciphertext>`.
+*/
+var SealedBox = class {
+	/** Payload discriminator. */
+	static prefix = PREFIX;
+	/**
+	* Encrypt a message to a recipient's public key.
+	*
+	* @param message
+	* @param recipientPublicKey
+	* @param options
+	* @returns
+	*/
+	static async seal(message, recipientPublicKey, options = {}) {
+		const ephemeral = await KeyPair.generate();
+		const recipient = await KeyPair.resolvePublic(recipientPublicKey);
+		const ephemeralPublicKey = await ephemeral.exportPublicKey();
+		const key = await this.derive(ephemeral, recipient, ephemeralPublicKey, await KeyPair.exportPublicKey(recipient));
+		return [
+			PREFIX,
+			ephemeralPublicKey,
+			await new Cipher(key).encrypt(message, options)
+		].join(":");
+	}
+	/**
+	* Open a sealed payload with the recipient's private key.
+	*
+	* @param payload
+	* @param recipientPrivateKey
+	* @param options
+	* @returns
+	*/
+	static async open(payload, recipientPrivateKey, options = {}) {
+		const [prefix, ephemeralPublicKey, ...rest] = payload.split(":");
+		if (prefix !== PREFIX || !ephemeralPublicKey || rest.length !== 3) throw new Error("Invalid sealed payload format");
+		const recipient = recipientPrivateKey instanceof KeyPair ? recipientPrivateKey : await KeyPair.fromPrivateKey(recipientPrivateKey);
+		if (!recipient.isComplete) throw new Error("Opening a sealed payload requires the recipient private key");
+		return await new Cipher(await this.derive(recipient, await KeyPair.importPublicKey(ephemeralPublicKey), ephemeralPublicKey, await recipient.exportPublicKey())).decrypt(rest.join(":"), options);
+	}
+	/**
+	* Whether a string is shaped like a sealed payload.
+	*
+	* @param value
+	* @returns
+	*/
+	static looksLikePayload(value) {
+		return typeof value === "string" && value.startsWith(`${PREFIX}:`) && value.split(":").length === 5;
+	}
+	/**
+	* Derive the one-off message key. Both sides feed the same ordered pair of
+	* public keys into the salt, so sender and recipient agree.
+	*
+	* @param owner              The side holding a private key.
+	* @param peer               The other side's public key.
+	* @param ephemeralPublicKey
+	* @param recipientPublicKey
+	* @returns
+	*/
+	static async derive(owner, peer, ephemeralPublicKey, recipientPublicKey) {
+		return await EncryptionKey.expand(await owner.sharedBits(peer), await SecureChannel.salt(ephemeralPublicKey, recipientPublicKey), CONTEXT);
+	}
+};
+//#endregion
+export { Cipher, Codec, EncryptionKey, KeyPair, Keys, SealedBox, SecureChannel, digest, randomBytes, subtle, webCrypto };