hanzio 1.1.0 → 2.0.0

package/src/crypto/sealer.ts

@@ -0,0 +1,168 @@
+import {
+	type BytesLike,
+	decodeBase64Url,
+	encodeBase64Url,
+	toBytes,
+	utf8Decode,
+	utf8Encode
+} from './encoding'
+import { getSubtleCrypto, randomBytes } from './hash'
+
+export type SealerOptions = {
+	/** High-entropy secret (e.g. `APP_SECRET`). The AES key is derived from it with HKDF-SHA-256. */
+	secret: string | BytesLike
+	/** HKDF salt. Default: empty */
+	salt?: string
+	/** HKDF info; use a distinct value per purpose. Default: `'hanzio.sealer.aes-256-gcm.v1'` */
+	info?: string
+}
+
+export type Sealer = {
+	seal(plaintext: string): Promise<string>
+	open(sealed: string): Promise<string>
+	sealJson(value: unknown): Promise<string>
+	openJson<T = unknown>(sealed: string): Promise<T>
+}
+
+export type SealerErrorCode =
+	| 'malformed'
+	| 'unsupported_version'
+	| 'decrypt_failed'
+
+const ERROR_MESSAGES: Record<SealerErrorCode, string> = {
+	malformed: 'Malformed sealed value',
+	unsupported_version: 'Unsupported sealed value version',
+	decrypt_failed: 'Could not open sealed value: wrong key or tampered data'
+}
+
+export class SealerError extends Error {
+	readonly code: SealerErrorCode
+
+	constructor(code: SealerErrorCode) {
+		super(ERROR_MESSAGES[code])
+		this.name = 'SealerError'
+		this.code = code
+	}
+}
+
+const PREFIX = 'enc:v1:'
+const IV_BYTES = 12
+const TAG_BYTES = 16
+const DEFAULT_INFO = 'hanzio.sealer.aes-256-gcm.v1'
+
+/**
+ * AES-256-GCM sealing with a random 96-bit IV per value. Envelope:
+ * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`.
+ */
+export function createSealer(options: SealerOptions): Sealer {
+	const { secret, salt = '', info = DEFAULT_INFO } = options
+	const secretBytes = toBytes(secret)
+	if (secretBytes.length === 0) {
+		throw new TypeError('Sealer secret must not be empty')
+	}
+
+	let keyPromise: Promise<CryptoKey> | undefined
+	const getKey = () => {
+		if (!keyPromise) {
+			keyPromise = deriveKey(secretBytes, salt, info)
+			keyPromise.catch(() => {
+				keyPromise = undefined
+			})
+		}
+		return keyPromise
+	}
+
+	const seal = async (plaintext: string): Promise<string> => {
+		const iv = randomBytes(IV_BYTES)
+		const encrypted = new Uint8Array(
+			await getSubtleCrypto().encrypt(
+				{ name: 'AES-GCM', iv },
+				await getKey(),
+				utf8Encode(plaintext)
+			)
+		)
+		const tagStart = encrypted.length - TAG_BYTES
+		return `${PREFIX}${encodeBase64Url(iv)}.${encodeBase64Url(encrypted.subarray(tagStart))}.${encodeBase64Url(encrypted.subarray(0, tagStart))}`
+	}
+
+	const open = async (sealed: string): Promise<string> => {
+		if (typeof sealed !== 'string' || !sealed.startsWith(PREFIX)) {
+			const isOtherVersion =
+				typeof sealed === 'string' && /^enc:v\d+:/.test(sealed)
+			throw new SealerError(
+				isOtherVersion ? 'unsupported_version' : 'malformed'
+			)
+		}
+
+		const parts = sealed.slice(PREFIX.length).split('.')
+		let iv: Uint8Array<ArrayBuffer>
+		let tag: Uint8Array
+		let ciphertext: Uint8Array
+		try {
+			if (parts.length !== 3) throw new Error()
+			iv = decodeBase64Url(parts[0] as string)
+			tag = decodeBase64Url(parts[1] as string)
+			ciphertext = decodeBase64Url(parts[2] as string)
+		} catch (_error) {
+			throw new SealerError('malformed')
+		}
+		if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+			throw new SealerError('malformed')
+		}
+
+		const encrypted = new Uint8Array(ciphertext.length + TAG_BYTES)
+		encrypted.set(ciphertext)
+		encrypted.set(tag, ciphertext.length)
+
+		const key = await getKey()
+		let plaintext: ArrayBuffer
+		try {
+			plaintext = await getSubtleCrypto().decrypt(
+				{ name: 'AES-GCM', iv },
+				key,
+				encrypted
+			)
+		} catch (_error) {
+			throw new SealerError('decrypt_failed')
+		}
+		return utf8Decode(plaintext)
+	}
+
+	return {
+		seal,
+		open,
+		async sealJson(value) {
+			const json = JSON.stringify(value)
+			if (json === undefined) {
+				throw new TypeError('sealJson value is not JSON-serializable')
+			}
+			return seal(json)
+		},
+		async openJson<T = unknown>(sealed: string) {
+			return JSON.parse(await open(sealed)) as T
+		}
+	}
+}
+
+async function deriveKey(
+	secret: Uint8Array<ArrayBuffer>,
+	salt: string,
+	info: string
+): Promise<CryptoKey> {
+	const subtle = getSubtleCrypto()
+	const baseKey = await subtle.importKey('raw', secret, 'HKDF', false, [
+		'deriveKey'
+	])
+	return subtle.deriveKey(
+		{
+			name: 'HKDF',
+			hash: 'SHA-256',
+			salt: utf8Encode(salt),
+			info: utf8Encode(info)
+		},
+		baseKey,
+		{ name: 'AES-GCM', length: 256 },
+		false,
+		['encrypt', 'decrypt']
+	)
+}

package/src/crypto/webhook.ts

@@ -0,0 +1,86 @@
+import { decodeBase64 } from './encoding'
+import { hmacSign, safeEqual } from './hash'
+
+export type VerifySvixSignatureOptions = {
+	/** Signing secret, `whsec_<base64>` (the prefix is optional). */
+	secret: string
+	/** The raw request body, exactly as received. */
+	payload: string
+	headers: Headers | Record<string, string | undefined>
+	/** Max age/skew of the timestamp header, in seconds. Default: 300 */
+	toleranceSec?: number
+	/** Current time in milliseconds. Default: `Date.now()` */
+	now?: number
+}
+
+const TIMESTAMP = /^\d+$/
+
+/**
+ * Verifies a Svix / Standard Webhooks signature (Resend, Clerk, …): base64
+ * HMAC-SHA256 over `${id}.${timestamp}.${payload}`, keyed by the base64 body
+ * of the `whsec_` secret. Reads `svix-*` headers, falling back to `webhook-*`.
+ * Every `v1,` entry in the space-separated signature header is checked, so
+ * secret rotation works. Returns `false` for missing/stale headers or a bad
+ * signature; throws on an invalid secret.
+ */
+export async function verifySvixSignature(
+	options: VerifySvixSignatureOptions
+): Promise<boolean> {
+	const {
+		secret,
+		payload,
+		headers,
+		toleranceSec = 300,
+		now = Date.now()
+	} = options
+
+	let key: Uint8Array
+	try {
+		key = decodeBase64(secret.startsWith('whsec_') ? secret.slice(6) : secret)
+	} catch (_error) {
+		throw new TypeError('Invalid webhook secret: expected whsec_<base64>')
+	}
+	if (key.length === 0) throw new TypeError('Webhook secret must not be empty')
+
+	const id = getHeader(headers, 'id')
+	const timestamp = getHeader(headers, 'timestamp')
+	const signatureHeader = getHeader(headers, 'signature')
+	if (!id || !timestamp || !signatureHeader) return false
+
+	if (!TIMESTAMP.test(timestamp)) return false
+	if (Math.abs(now / 1000 - Number(timestamp)) > toleranceSec) return false
+
+	const expected = await hmacSign(key, `${id}.${timestamp}.${payload}`, {
+		encoding: 'base64'
+	})
+
+	return signatureHeader.split(' ').some((entry) => {
+		const comma = entry.indexOf(',')
+		if (comma === -1 || entry.slice(0, comma) !== 'v1') return false
+		return safeEqual(entry.slice(comma + 1), expected)
+	})
+}
+
+function getHeader(
+	headers: VerifySvixSignatureOptions['headers'],
+	name: 'id' | 'timestamp' | 'signature'
+): string | undefined {
+	for (const prefix of ['svix-', 'webhook-']) {
+		const value = readHeader(headers, prefix + name)
+		if (value) return value
+	}
+	return undefined
+}
+
+function readHeader(
+	headers: VerifySvixSignatureOptions['headers'],
+	name: string
+): string | undefined {
+	if (typeof headers.get === 'function') {
+		return (headers as Headers).get(name) ?? undefined
+	}
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === name) return value
+	}
+	return undefined
+}

package/src/date/index.ts

@@ -1,54 +1,129 @@
+export type PeriodType = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY'
+
+const MONTHS_PER_PERIOD = { MONTHLY: 1, QUARTERLY: 3, YEARLY: 12 } as const
+
+function ymd(date: Date, utc = false): [number, number, number] {
+	return utc
+		? [date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()]
+		: [date.getFullYear(), date.getMonth(), date.getDate()]
+}
+
+/** Midnight at the start of the given (overflow-normalized) calendar day. */
+function startOfDay(y: number, m: number, d: number, utc = false): Date {
+	return utc ? new Date(Date.UTC(y, m, d)) : new Date(y, m, d)
+}
+
+/**
+ * Add `n` periods to `date`, keeping its time of day (wall-clock time in local
+ * mode, so DST shifts don't move it). Month-based adds clamp the day of month:
+ * Jan 31 + 1 month → Feb 28 (or 29).
+ */
+export function addPeriod(
+	date: Date,
+	type: PeriodType,
+	n: number,
+	options: { utc?: boolean } = {}
+): Date {
+	const { utc = false } = options
+	let [y, m, d] = ymd(date, utc)
+	if (type === 'DAILY' || type === 'WEEKLY') {
+		d += n * (type === 'WEEKLY' ? 7 : 1)
+	} else {
+		m += n * MONTHS_PER_PERIOD[type]
+		d = Math.min(d, new Date(Date.UTC(y, m + 1, 0)).getUTCDate())
+	}
+	const out = new Date(date)
+	if (utc) out.setUTCFullYear(y, m, d)
+	else out.setFullYear(y, m, d)
+	return out
+}
+
+/**
+ * Calendar period containing `referenceDate`, shifted by `offset` periods
+ * (`-1` = previous, `1` = next).
+ *
+ * `start` is midnight on the first day and `end` is midnight at the **start**
+ * of the last day, so the range is inclusive for date-only comparisons. For
+ * timestamps use `timestamp < addPeriod(end, 'DAILY', 1)` as the exclusive bound.
+ *
+ * Uses the local timezone unless `utc: true`. Weeks start on Monday (ISO)
+ * unless `weekStartsOn: 0` (Sunday).
+ */
+export function getPeriod(
+	type: PeriodType,
+	referenceDate: Date = new Date(),
+	offset = 0,
+	options: { utc?: boolean; weekStartsOn?: 0 | 1 } = {}
+): { start: Date; end: Date } {
+	const { utc = false, weekStartsOn = 1 } = options
+	const [y, m, d] = ymd(referenceDate, utc)
+	const weekday = utc ? referenceDate.getUTCDay() : referenceDate.getDay()
+	const anchor = {
+		DAILY: () => startOfDay(y, m, d, utc),
+		WEEKLY: () => startOfDay(y, m, d - ((weekday - weekStartsOn + 7) % 7), utc),
+		MONTHLY: () => startOfDay(y, m, 1, utc),
+		QUARTERLY: () => startOfDay(y, m - (m % 3), 1, utc),
+		YEARLY: () => startOfDay(y, 0, 1, utc)
+	}[type]()
+	const [ey, em, ed] = ymd(addPeriod(anchor, type, offset + 1, { utc }), utc)
+	return {
+		start: addPeriod(anchor, type, offset, { utc }),
+		end: startOfDay(ey, em, ed - 1, utc)
+	}
+}
+
 /**
  * Calculate the previous period date range for a given period type.
+ * Same as `getPeriod(periodType, referenceDate, -1)`.
  */
 export function getPreviousReportPeriod(
-	periodType: 'MONTHLY' | 'QUARTERLY' | 'YEARLY',
+	periodType: PeriodType,
 	referenceDate: Date = new Date()
 ): { start: Date; end: Date } {
-	const month = referenceDate.getMonth()
-	const year = referenceDate.getFullYear()
-
-	switch (periodType) {
-		case 'MONTHLY': {
-			const prevMonth = month === 0 ? 11 : month - 1
-			const prevYear = month === 0 ? year - 1 : year
-			return {
-				start: new Date(prevYear, prevMonth, 1),
-				end: new Date(year, month, 0)
-			}
-		}
-		case 'QUARTERLY': {
-			const qStart = Math.floor(month / 3) * 3
-			const prevQStart = qStart === 0 ? 9 : qStart - 3
-			const prevQYear = qStart === 0 ? year - 1 : year
-			return {
-				start: new Date(prevQYear, prevQStart, 1),
-				end: new Date(prevQYear, prevQStart + 3, 0)
-			}
-		}
-		case 'YEARLY': {
-			return {
-				start: new Date(year - 1, 0, 1),
-				end: new Date(year - 1, 11, 31)
-			}
-		}
-	}
+	return getPeriod(periodType, referenceDate, -1)
+}
+
+export type FormatPeriodLabelOptions = {
+	includeDay?: boolean
+	/** Default `'en-GB'`. */
+	locale?: string
+	/** Joins the two formatted dates. Default `' — '`. Ignored when `collapse` is set. */
+	separator?: string
+	/**
+	 * Use `Intl.DateTimeFormat#formatRange`, which drops repeated parts and uses
+	 * the locale's range dash: "January – March 2025" instead of
+	 * "January 2025 — March 2025".
+	 */
+	collapse?: boolean
+	/** IANA time zone, e.g. `'UTC'` for periods from `getPeriod(..., { utc: true })`. */
+	timeZone?: string
 }
 
 /**
  * Format a date range as a human-readable period label.
+ * The third argument is either `includeDay` or an options object.
  */
 export function formatPeriodLabel(
 	start: Date | string,
 	end: Date | string,
-	includeDay = false
+	options: boolean | FormatPeriodLabelOptions = false
 ): string {
+	const {
+		includeDay = false,
+		locale = 'en-GB',
+		separator = ' — ',
+		collapse = false,
+		timeZone
+	} = typeof options === 'boolean' ? { includeDay: options } : options
 	const s = start instanceof Date ? start : new Date(start)
 	const e = end instanceof Date ? end : new Date(end)
-	const opts: Intl.DateTimeFormatOptions = {
+	const format = new Intl.DateTimeFormat(locale, {
 		year: 'numeric',
 		month: 'long',
-		...(includeDay && { day: 'numeric' })
-	}
-	return `${s.toLocaleDateString('en-GB', opts)} — ${e.toLocaleDateString('en-GB', opts)}`
+		...(includeDay && { day: 'numeric' }),
+		timeZone
+	})
+	return collapse
+		? format.formatRange(s, e)
+		: `${format.format(s)}${separator}${format.format(e)}`
 }

package/src/emitter/index.ts

@@ -0,0 +1,82 @@
+export type Listener<P> = (payload: P) => void
+
+/** Payload is optional for events typed `void` or `undefined`. */
+export type EmitArgs<P> = undefined extends P ? [payload?: P] : [payload: P]
+
+export type Emitter<Events extends Record<string, unknown>> = {
+	/** Adds a listener; returns an unsubscribe function. */
+	on<K extends keyof Events>(
+		event: K,
+		listener: Listener<Events[K]>
+	): () => void
+	/** Like `on`, but removed before its first call. */
+	once<K extends keyof Events>(
+		event: K,
+		listener: Listener<Events[K]>
+	): () => void
+	off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void
+	/**
+	 * Calls every listener, even if some throw, then rethrows the error (or an
+	 * `AggregateError` if several threw). Listeners added during an emit wait
+	 * for the next one; listeners removed during an emit are skipped.
+	 */
+	emit<K extends keyof Events>(event: K, ...args: EmitArgs<Events[K]>): void
+	/** Removes all listeners for `event`, or for every event. */
+	clear(event?: keyof Events): void
+	listenerCount(event: keyof Events): number
+}
+
+/** Typed event emitter. Adding the same listener twice keeps one entry. */
+export function createEmitter<
+	Events extends Record<string, unknown>
+>(): Emitter<Events> {
+	// listener -> registered with `once`
+	const listeners = new Map<keyof Events, Map<Listener<unknown>, boolean>>()
+
+	const add = (
+		event: keyof Events,
+		listener: Listener<never>,
+		once: boolean
+	) => {
+		const map = listeners.get(event) ?? new Map()
+		listeners.set(event, map)
+		map.set(listener as Listener<unknown>, once)
+		return () => {
+			map.delete(listener as Listener<unknown>)
+		}
+	}
+
+	return {
+		on: (event, listener) => add(event, listener, false),
+		once: (event, listener) => add(event, listener, true),
+		off(event, listener) {
+			listeners.get(event)?.delete(listener as Listener<unknown>)
+		},
+		emit(event, ...[payload]) {
+			const map = listeners.get(event)
+			if (!map) return
+			const errors: unknown[] = []
+			for (const [listener, once] of [...map]) {
+				if (!map.has(listener)) continue
+				if (once) map.delete(listener)
+				try {
+					listener(payload)
+				} catch (error) {
+					errors.push(error)
+				}
+			}
+			if (errors.length === 1) throw errors[0]
+			if (errors.length > 1) {
+				throw new AggregateError(
+					errors,
+					`${errors.length} listeners threw for "${String(event)}"`
+				)
+			}
+		},
+		clear(event) {
+			if (event === undefined) listeners.clear()
+			else listeners.delete(event)
+		},
+		listenerCount: (event) => listeners.get(event)?.size ?? 0
+	}
+}

package/src/error/index.ts

@@ -0,0 +1,63 @@
+/** Thrown by `must` and `invariant` when no custom error is given. */
+export class InvariantError extends Error {
+	override name = 'InvariantError'
+}
+
+/** An error's message: Error → `message`, string → itself, `{ message: string }` → that, else `String(error)`. */
+export function getErrorMessage(error: unknown, fallback = ''): string {
+	let message: string
+	if (typeof error === 'string') message = error
+	else if (
+		typeof error === 'object' &&
+		error !== null &&
+		'message' in error &&
+		typeof error.message === 'string'
+	)
+		message = error.message
+	else {
+		try {
+			message = String(error)
+		} catch {
+			// e.g. Object.create(null) has no toString
+			message = ''
+		}
+	}
+	return message || fallback
+}
+
+/** Returns Errors unchanged, wraps anything else; a `prefix` always wraps as `${prefix}: ${message}` with `cause`. */
+export function toError(error: unknown, prefix?: string): Error {
+	if (error instanceof Error && !prefix) return error
+	const message = getErrorMessage(error)
+	return new Error(prefix ? `${prefix}: ${message}` : message, {
+		cause: error
+	})
+}
+
+function fail(
+	message: string | (() => Error) | undefined,
+	fallback: string
+): never {
+	throw typeof message === 'function'
+		? message()
+		: new InvariantError(message ?? fallback)
+}
+
+/** Returns `value`, throwing when it is null or undefined. Pass a function to throw your own error. */
+export function must<T>(
+	value: T,
+	message?: string | (() => Error)
+): NonNullable<T> {
+	if (value === null || value === undefined) {
+		fail(message, 'Expected value to be defined')
+	}
+	return value
+}
+
+/** Throws when `condition` is falsy. Pass a function to throw your own error. */
+export function invariant(
+	condition: unknown,
+	message?: string | (() => Error)
+): asserts condition {
+	if (!condition) fail(message, 'Invariant failed')
+}