@vouchington/utils 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @vouchington/utils
+
+Dependency-free utilities for Node.js 24 applications. This package deliberately has no root
+export: import the capability you use from an explicit subpath.
+
+```ts
+import { createTokenSecrets } from '@vouchington/utils/token-secrets'
+import { createMoneyCatalog } from '@vouchington/utils/money'
+import { serializeCookie } from '@vouchington/utils/cookies'
+```
+
+## Subpaths
+
+- `token-secrets`: Node-only (`node:crypto`) purpose-bound HMAC and AES-256-GCM encryption.
+  `createTokenSecrets({ hashSecret, encryptionKeys })` throws for invalid keys or ciphertext.
+- `deploy-environment`: `getDeployEnvironment(source)` classifies explicit environment inputs without
+  throwing.
+- `url-signing`: Node-only HMAC SHA-256 `signPathWithKey(path, key)` and verification; invalid keys
+  throw and invalid signatures return `false`.
+- `request-client-info`: `createClientInfoParser(config)` validates caller-selected headers,
+  families, platforms, compatibility, and versions.
+- `money`: `createMoneyCatalog(currencies, scale)` supplies exact integer parsing and validation for
+  the caller's catalog.
+- `env-contract`: `groupEnvContracts()` and `normalizeEnvContractGroups()` produce delimiter-safe
+  metadata keys and surface/sensitivity lookups.
+- `cookies`: `serializeCookie(name, value, attributes)` validates cookie grammar and requires the
+  caller to supply every policy attribute. `SameSite=None` requires `Secure`.
+
+```ts
+const money = createMoneyCatalog([{ code: 'credit', minorUnitExponent: 2 }] as const, 6)
+money.parseMajorUnitsToMoney('12.34', 'credit')
+```
+
+Applications supply all product identifiers, environment names, header names, policy, and catalogs.

package/dist/cookies.d.mts

@@ -0,0 +1,8 @@
+export type CookieAttributes = {
+    httpOnly: boolean;
+    maxAge: number;
+    path: string;
+    sameSite: 'lax' | 'none' | 'strict';
+    secure: boolean;
+};
+export declare function serializeCookie(name: string, value: string, attributes: CookieAttributes): string;

package/dist/cookies.mjs

@@ -0,0 +1,32 @@
+const COOKIE_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const COOKIE_VALUE_PATTERN = /^[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*$/;
+const COOKIE_PATH_PATTERN = /^[\x20-\x3a\x3c-\x7e]+$/;
+const SAME_SITE_VALUES = new Set(['lax', 'none', 'strict']);
+export function serializeCookie(name, value, attributes) {
+    if (!COOKIE_NAME_PATTERN.test(name))
+        throw new Error('Invalid cookie name');
+    if (!COOKIE_VALUE_PATTERN.test(value))
+        throw new Error(`Invalid cookie value for ${name}`);
+    if (!Number.isSafeInteger(attributes.maxAge) || attributes.maxAge < 0)
+        throw new Error('Cookie Max-Age must be a non-negative safe integer');
+    if (!COOKIE_PATH_PATTERN.test(attributes.path) || !attributes.path.startsWith('/'))
+        throw new Error('Cookie Path must be an ASCII absolute path without semicolons');
+    if (!SAME_SITE_VALUES.has(attributes.sameSite))
+        throw new Error('Invalid cookie SameSite value');
+    if (typeof attributes.httpOnly !== 'boolean' || typeof attributes.secure !== 'boolean')
+        throw new Error('Cookie HttpOnly and Secure attributes must be boolean');
+    if (attributes.sameSite === 'none' && !attributes.secure)
+        throw new Error('SameSite=None cookies must be Secure');
+    const sameSite = `${attributes.sameSite[0].toUpperCase()}${attributes.sameSite.slice(1)}`;
+    const parts = [
+        `${name}=${value}`,
+        `Max-Age=${attributes.maxAge}`,
+        `Path=${attributes.path}`,
+        `SameSite=${sameSite}`,
+    ];
+    if (attributes.httpOnly)
+        parts.push('HttpOnly');
+    if (attributes.secure)
+        parts.push('Secure');
+    return parts.join('; ');
+}

package/dist/deploy-environment.d.mts

@@ -0,0 +1,8 @@
+export type DeployEnvironment = 'development' | 'test' | 'staging' | 'production';
+export type DeployEnvironmentSource = {
+    ENVIRONMENT?: string | undefined;
+    NODE_ENV?: string | undefined;
+};
+export declare function getDeployEnvironment(source?: DeployEnvironmentSource): DeployEnvironment;
+export declare function isDeployedEnvironment(source?: DeployEnvironmentSource): boolean;
+export declare function isProductionEnvironment(source?: DeployEnvironmentSource): boolean;

package/dist/deploy-environment.mjs

@@ -0,0 +1,17 @@
+const known = new Set(['development', 'test', 'staging', 'production']);
+export function getDeployEnvironment(source = process.env) {
+    return normalize(source.ENVIRONMENT) ?? normalize(source.NODE_ENV) ?? 'development';
+}
+export function isDeployedEnvironment(source = process.env) {
+    const environment = getDeployEnvironment(source);
+    return environment === 'staging' || environment === 'production';
+}
+export function isProductionEnvironment(source = process.env) {
+    return getDeployEnvironment(source) === 'production';
+}
+function normalize(value) {
+    const trimmed = value?.trim();
+    return trimmed && known.has(trimmed)
+        ? trimmed
+        : undefined;
+}

package/dist/env-contract.d.mts

@@ -0,0 +1,19 @@
+export type EnvVarSensitivity = 'internal' | 'public' | 'secret';
+export type EnvVarContract<Source extends string = string, Surface extends string = string> = {
+    key: string;
+    name: string;
+    sensitivity: EnvVarSensitivity;
+    sourceOfTruth: Source;
+    surfaces: readonly Surface[];
+};
+export type EnvVarContractGroup<Source extends string = string, Surface extends string = string> = {
+    sourceOfTruth: Source;
+    surfaces: readonly Surface[];
+    sensitivity: EnvVarSensitivity;
+    names: readonly string[];
+};
+export declare function groupEnvContracts<Source extends string, Surface extends string>(sourceOfTruth: Source, sensitivity: EnvVarSensitivity, surfaces: readonly Surface[], names: readonly string[]): EnvVarContractGroup<Source, Surface>;
+export declare function normalizeEnvContractGroups<Source extends string, Surface extends string>(groups: readonly EnvVarContractGroup<Source, Surface>[]): readonly EnvVarContract<Source, Surface>[];
+export declare function envNamesForSurface<Source extends string, Surface extends string>(contract: readonly EnvVarContract<Source, Surface>[], surface: Surface): readonly string[];
+export declare function envContractsByName<Source extends string, Surface extends string>(contract: readonly EnvVarContract<Source, Surface>[]): ReadonlyMap<string, readonly EnvVarContract<Source, Surface>[]>;
+export declare function envNamesBySensitivity<Source extends string, Surface extends string>(contract: readonly EnvVarContract<Source, Surface>[], sensitivity: EnvVarSensitivity): readonly string[];

package/dist/env-contract.mjs

@@ -0,0 +1,45 @@
+export function groupEnvContracts(sourceOfTruth, sensitivity, surfaces, names) {
+    validatePart(sourceOfTruth, 'source');
+    for (const surface of surfaces)
+        validatePart(surface, 'surface');
+    for (const name of names)
+        validatePart(name, 'name');
+    return { sourceOfTruth, sensitivity, surfaces: [...surfaces], names: [...names] };
+}
+export function normalizeEnvContractGroups(groups) {
+    const contract = groups.flatMap((group) => {
+        validatePart(group.sourceOfTruth, 'source');
+        for (const surface of group.surfaces)
+            validatePart(surface, 'surface');
+        for (const name of group.names)
+            validatePart(name, 'name');
+        return group.names.map((name) => ({
+            key: `${group.sourceOfTruth}:${group.surfaces.join('+')}:${name}`,
+            name,
+            sensitivity: group.sensitivity,
+            sourceOfTruth: group.sourceOfTruth,
+            surfaces: Object.freeze([...group.surfaces]),
+        }));
+    });
+    if (new Set(contract.map((entry) => entry.key)).size !== contract.length)
+        throw new Error('Environment contract keys must be unique');
+    return contract;
+}
+function validatePart(value, label) {
+    if (!value || /[:+]/.test(value))
+        throw new TypeError(`Environment contract ${label} cannot contain ':' or '+'`);
+}
+export function envNamesForSurface(contract, surface) {
+    return contract.filter((entry) => entry.surfaces.includes(surface)).map((entry) => entry.name);
+}
+export function envContractsByName(contract) {
+    const grouped = new Map();
+    for (const entry of contract)
+        grouped.set(entry.name, [...(grouped.get(entry.name) ?? []), entry]);
+    return new Map([...grouped].map(([name, entries]) => [name, Object.freeze(entries)]));
+}
+export function envNamesBySensitivity(contract, sensitivity) {
+    return [
+        ...new Set(contract.filter((entry) => entry.sensitivity === sensitivity).map((entry) => entry.name)),
+    ].toSorted();
+}

package/dist/money.d.mts

@@ -0,0 +1,37 @@
+export declare const MAX_MONEY_AMOUNT: number;
+export type Currency<Code extends string = string> = {
+    code: Code;
+    minorUnitExponent: number;
+};
+export type Money<Code extends string = string> = {
+    amount: number;
+    currency: Code;
+};
+export type ScaledMoney<Code extends string = string> = Money<Code> & {
+    scale: number;
+};
+export type ScaledMoneyAggregate<Code extends string = string> = {
+    amount: string;
+    currency: Code;
+    scale: number;
+};
+export type MoneyRange<Code extends string = string> = {
+    minimum: Money<Code>;
+    maximum: Money<Code> | null;
+};
+export declare function createMoneyCatalog<const Currencies extends readonly Currency[]>(entries: Currencies, scale: number): {
+    currencies: readonly Readonly<{
+        code: string;
+        minorUnitExponent: number;
+    }>[];
+    scale: number;
+    isCurrencyCode: (value: unknown) => value is Currencies[number]["code"];
+    getCurrency: (code: Currencies[number]["code"]) => Currency<Currencies[number]["code"]>;
+    isMoney: (value: unknown) => value is Money<Currencies[number]["code"]>;
+    isScaledMoney: (value: unknown) => value is ScaledMoney<Currencies[number]["code"]>;
+    isScaledMoneyAggregate: (value: unknown) => value is ScaledMoneyAggregate<Currencies[number]["code"]>;
+    isMoneyRange: (value: unknown) => value is MoneyRange<Currencies[number]["code"]>;
+    parseMajorUnitsToMoney: (value: string, currency: Currencies[number]["code"]) => Money<Currencies[number]["code"]>;
+    parseMajorUnitsToScaledMoney: (value: string, currency: Currencies[number]["code"]) => ScaledMoney<Currencies[number]["code"]>;
+};
+export declare function parsePostgresMoneyAmount(value: string): number;

package/dist/money.mjs

@@ -0,0 +1,122 @@
+export const MAX_MONEY_AMOUNT = Number.MAX_SAFE_INTEGER;
+export function createMoneyCatalog(entries, scale) {
+    validateScale(scale);
+    for (const currency of entries)
+        validateCurrency(currency, scale);
+    const copiedEntries = entries.map((currency) => Object.freeze({ ...currency }));
+    const currencies = new Map(copiedEntries.map((currency) => [currency.code, currency]));
+    if (currencies.size !== entries.length)
+        throw new Error('Currency codes must be unique');
+    return {
+        currencies: Object.freeze(copiedEntries),
+        scale,
+        isCurrencyCode: (value) => typeof value === 'string' && currencies.has(value),
+        getCurrency: (code) => currencies.get(code) ?? invalidCurrency(code),
+        isMoney: (value) => isMoneyValue(value, currencies),
+        isScaledMoney: (value) => isScaledMoneyValue(value, currencies, scale),
+        isScaledMoneyAggregate: (value) => isScaledAggregateValue(value, currencies, scale),
+        isMoneyRange: (value) => isMoneyRangeValue(value, currencies),
+        parseMajorUnitsToMoney: (value, currency) => ({
+            amount: parseMajorUnits(value, (currencies.get(currency) ?? invalidCurrency(currency)).minorUnitExponent),
+            currency,
+        }),
+        parseMajorUnitsToScaledMoney: (value, currency) => ({
+            amount: parseMajorUnits(value, currencies.has(currency) ? scale : invalidCurrency(currency)),
+            currency,
+            scale,
+        }),
+    };
+}
+export function parsePostgresMoneyAmount(value) {
+    if (!isCanonicalInteger(value))
+        throw new TypeError('Stored money amount must be a canonical non-negative integer');
+    const amount = BigInt(value);
+    if (amount > BigInt(MAX_MONEY_AMOUNT))
+        throw new RangeError('Stored money amount exceeds the maximum JSON-safe integer');
+    return Number(amount);
+}
+function validateScale(scale) {
+    if (!Number.isInteger(scale) || scale < 0 || scale > 15)
+        throw new RangeError('Scale must be 0 through 15');
+}
+function validateCurrency(currency, scale) {
+    if (!currency.code ||
+        !Number.isInteger(currency.minorUnitExponent) ||
+        currency.minorUnitExponent < 0 ||
+        currency.minorUnitExponent > scale)
+        throw new TypeError('Currencies require a non-empty code and an integer exponent within scale');
+}
+function invalidCurrency(code) {
+    throw new TypeError(`Unknown currency: ${code}`);
+}
+function isMoneyValue(value, currencies) {
+    const fields = fieldsOf(value, ['amount', 'currency']);
+    return fields !== null && isAmount(fields.amount) && hasCurrency(currencies, fields.currency);
+}
+function isScaledMoneyValue(value, currencies, scale) {
+    const fields = fieldsOf(value, ['amount', 'currency', 'scale']);
+    return (fields !== null &&
+        isAmount(fields.amount) &&
+        hasCurrency(currencies, fields.currency) &&
+        fields.scale === scale);
+}
+function isScaledAggregateValue(value, currencies, scale) {
+    const fields = fieldsOf(value, ['amount', 'currency', 'scale']);
+    return (fields !== null &&
+        isCanonicalInteger(fields.amount) &&
+        hasCurrency(currencies, fields.currency) &&
+        fields.scale === scale);
+}
+function isMoneyRangeValue(value, currencies) {
+    const fields = fieldsOf(value, ['minimum', 'maximum']);
+    return (fields !== null &&
+        isMoneyValue(fields.minimum, currencies) &&
+        (fields.maximum === null ||
+            (isMoneyValue(fields.maximum, currencies) &&
+                fields.maximum.currency === fields.minimum.currency &&
+                fields.maximum.amount > fields.minimum.amount)));
+}
+function hasCurrency(currencies, value) {
+    return typeof value === 'string' && currencies.has(value);
+}
+function parseMajorUnits(value, scale) {
+    const match = /^(0|[1-9]\d*)(?:\.(\d+))?$/.exec(value);
+    if (!match)
+        throw new TypeError('Money must be a non-negative plain decimal string');
+    const fractional = match[2] ?? '';
+    if (fractional.length > scale)
+        throw new RangeError(`Money supports at most ${scale} decimal places`);
+    const amount = BigInt(match[1]) * 10n ** BigInt(scale) + BigInt(fractional.padEnd(scale, '0'));
+    if (amount > BigInt(MAX_MONEY_AMOUNT))
+        throw new RangeError('Money exceeds the maximum JSON-safe integer amount');
+    return Number(amount);
+}
+function isAmount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isCanonicalInteger(value) {
+    return typeof value === 'string' && /^(0|[1-9]\d*)$/.test(value);
+}
+function fieldsOf(value, expected) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return null;
+        const keys = Reflect.ownKeys(value);
+        if (keys.length !== expected.length || !expected.every((key) => Object.hasOwn(value, key)))
+            return null;
+        const fields = {};
+        for (const key of expected) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor))
+                return null;
+            fields[key] = descriptor.value;
+        }
+        return fields;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/request-client-info.d.mts

@@ -0,0 +1,26 @@
+export type HeaderValue = string | readonly string[] | undefined;
+export type ClientInfoHeaders = {
+    client: string;
+    platform: string;
+    appVersion: string;
+    sdkVersion?: string;
+};
+export type ClientInfoConfiguration<Client extends string, Platform extends string> = {
+    headers: ClientInfoHeaders;
+    clients: readonly Client[];
+    platforms: readonly Platform[];
+    compatiblePlatforms: Readonly<Record<Client, readonly Platform[]>>;
+    versionPattern?: RegExp;
+};
+export type ClientHeaders<Client extends string, Platform extends string> = {
+    client: Client;
+    platform: Platform;
+    appVersion: string;
+    sdkVersion?: string;
+};
+export declare class ClientInfoValidationError extends Error {
+    readonly code = "INVALID_CLIENT_INFO";
+    readonly status = 400;
+    constructor(message: string);
+}
+export declare function createClientInfoParser<Client extends string, Platform extends string>(configuration: ClientInfoConfiguration<Client, Platform>): (headers: Record<string, HeaderValue>) => ClientHeaders<Client, Platform>;

package/dist/request-client-info.mjs

@@ -0,0 +1,57 @@
+export class ClientInfoValidationError extends Error {
+    code = 'INVALID_CLIENT_INFO';
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = 'ClientInfoValidationError';
+    }
+}
+export function createClientInfoParser(configuration) {
+    const clients = new Set(configuration.clients);
+    const platforms = new Set(configuration.platforms);
+    const compatiblePlatforms = new Map();
+    for (const client of clients) {
+        const compatible = configuration.compatiblePlatforms[client];
+        if (!Array.isArray(compatible))
+            throw new TypeError(`Client ${client} requires compatible platforms`);
+        if (compatible.some((platform) => !platforms.has(platform)))
+            throw new TypeError(`Client ${client} has an unknown compatible platform`);
+        compatiblePlatforms.set(client, new Set(compatible));
+    }
+    const versionPattern = configuration.versionPattern ?? /^[\x20-\x7e]{1,64}$/;
+    if (versionPattern.global || versionPattern.sticky)
+        throw new TypeError('Version patterns cannot be global or sticky');
+    return (headers) => {
+        const client = requiredEnum(headers[configuration.headers.client], configuration.headers.client, clients);
+        const platform = requiredEnum(headers[configuration.headers.platform], configuration.headers.platform, platforms);
+        const appVersion = requiredVersion(headers[configuration.headers.appVersion], configuration.headers.appVersion, true, versionPattern);
+        const sdkVersion = configuration.headers.sdkVersion
+            ? requiredVersion(headers[configuration.headers.sdkVersion], configuration.headers.sdkVersion, false, versionPattern)
+            : undefined;
+        if (!compatiblePlatforms.get(client).has(platform))
+            throw new ClientInfoValidationError(`${client} and ${platform} are incompatible`);
+        return { client, platform, appVersion, ...(sdkVersion === undefined ? {} : { sdkVersion }) };
+    };
+}
+function requiredEnum(value, name, allowed) {
+    const single = requireSingle(value, name, true);
+    if (!allowed.has(single))
+        throw new ClientInfoValidationError(`${name} is invalid`);
+    return single;
+}
+function requiredVersion(value, name, required, pattern) {
+    const single = requireSingle(value, name, required);
+    if (single !== undefined && !pattern.test(single))
+        throw new ClientInfoValidationError(`${name} is invalid`);
+    return single;
+}
+function requireSingle(value, name, required) {
+    if (typeof value !== 'string' && value !== undefined)
+        throw new ClientInfoValidationError(`${name} must occur exactly once`);
+    if (value === undefined || value === '') {
+        if (required)
+            throw new ClientInfoValidationError(`${name} is required`);
+        return undefined;
+    }
+    return value;
+}

package/dist/token-secrets.d.mts

@@ -0,0 +1,14 @@
+export type EncryptionKey = {
+    id: string;
+    key: Buffer;
+};
+export type TokenSecrets = {
+    hashToken(purpose: string, token: string): string;
+    encryptSecret(plaintext: string, purpose: string): string;
+    decryptSecret(ciphertext: string, purpose: string): string;
+};
+export declare function parseEncryptionKeys(value: string): EncryptionKey[];
+export declare function createTokenSecrets(options: {
+    hashSecret: string;
+    encryptionKeys: readonly EncryptionKey[];
+}): TokenSecrets;

package/dist/token-secrets.mjs

@@ -0,0 +1,102 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
+const KEY_FORMAT = 'v1';
+export function parseEncryptionKeys(value) {
+    return value
+        .split(',')
+        .map((part) => part.trim())
+        .map(parseEncryptionKey);
+}
+export function createTokenSecrets(options) {
+    if (!options.hashSecret.trim())
+        throw new Error('Hash secret must not be empty');
+    const hashSecret = options.hashSecret;
+    if (options.encryptionKeys.length === 0)
+        throw new Error('Encryption keys must contain at least one key');
+    for (const key of options.encryptionKeys) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key.id) || key.key.length !== 32)
+            throw new Error('Encryption keys must have a non-empty id and 32 bytes');
+    }
+    const copiedKeys = options.encryptionKeys.map((key) => ({
+        id: key.id,
+        key: Buffer.from(key.key),
+    }));
+    const keys = new Map(copiedKeys.map((key) => [key.id, key]));
+    if (keys.size !== options.encryptionKeys.length)
+        throw new Error('Encryption key ids must be unique');
+    const primary = copiedKeys[0];
+    return {
+        hashToken: (purpose, token) => createHmac('sha256', hashSecret)
+            .update(purpose)
+            .update('\0')
+            .update(token)
+            .digest('hex')
+            .toUpperCase(),
+        encryptSecret: (plaintext, purpose) => encrypt(plaintext, purpose, primary),
+        decryptSecret: (ciphertext, purpose) => decrypt(ciphertext, purpose, keys),
+    };
+}
+function parseEncryptionKey(part) {
+    const separator = part.indexOf(':');
+    const id = separator < 0 ? '' : part.slice(0, separator).trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new Error('Encryption key entries must use a non-empty safe key id');
+    const raw = part.slice(separator + 1).trim();
+    const value = raw.startsWith('raw32:')
+        ? raw.slice(6).trim()
+        : raw.startsWith('base64url:')
+            ? raw.slice(10).trim()
+            : raw;
+    if (!value)
+        throw new Error('Encryption key entries must contain key material');
+    if (!raw.startsWith('raw32:') &&
+        (!/^[A-Za-z0-9_-]+$/.test(value) ||
+            Buffer.from(value, 'base64url').toString('base64url') !== value))
+        throw new Error('Encryption key material must be canonical base64url');
+    const key = raw.startsWith('raw32:') ? Buffer.from(value) : Buffer.from(value, 'base64url');
+    if (key.length !== 32)
+        throw new Error(`Encryption key ${id} must be 32 bytes`);
+    return { id, key };
+}
+function encrypt(plaintext, purpose, key) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key.key, iv);
+    cipher.setAAD(Buffer.from(purpose));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return [
+        KEY_FORMAT,
+        key.id,
+        iv.toString('base64url'),
+        cipher.getAuthTag().toString('base64url'),
+        ciphertext.toString('base64url'),
+    ].join(':');
+}
+function decrypt(value, purpose, keys) {
+    const [format, id, iv, tag, ciphertext, extra] = value.split(':');
+    if (format !== KEY_FORMAT ||
+        !id ||
+        !iv ||
+        !tag ||
+        ciphertext === undefined ||
+        extra !== undefined)
+        throw new Error('Invalid encrypted secret format');
+    const key = keys.get(id);
+    if (!key)
+        throw new Error(`Encryption key ${id} is not configured`);
+    const ivBytes = decodeCanonicalBase64Url(iv);
+    const tagBytes = decodeCanonicalBase64Url(tag);
+    const ciphertextBytes = decodeCanonicalBase64Url(ciphertext);
+    if (ivBytes.length !== 12 || tagBytes.length !== 16)
+        throw new Error('Invalid encrypted secret format');
+    const decipher = createDecipheriv('aes-256-gcm', key.key, ivBytes);
+    decipher.setAAD(Buffer.from(purpose));
+    decipher.setAuthTag(tagBytes);
+    return Buffer.concat([decipher.update(ciphertextBytes), decipher.final()]).toString();
+}
+function decodeCanonicalBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value))
+        throw new Error('Invalid encrypted secret format');
+    const decoded = Buffer.from(value, 'base64url');
+    if (decoded.toString('base64url') !== value)
+        throw new Error('Invalid encrypted secret format');
+    return decoded;
+}

package/dist/url-signing.d.mts

@@ -0,0 +1,2 @@
+export declare function signPathWithKey(path: string, keyHex: string): string;
+export declare function verifyPathWithKey(path: string, signature: string, keyHex: string): boolean;

package/dist/url-signing.mjs

@@ -0,0 +1,12 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export function signPathWithKey(path, keyHex) {
+    if (!/^[\da-f]{64}$/i.test(keyHex))
+        throw new Error('Signing keys must be 64 hexadecimal characters');
+    return createHmac('sha256', Buffer.from(keyHex, 'hex')).update(path).digest('hex');
+}
+export function verifyPathWithKey(path, signature, keyHex) {
+    const expected = signPathWithKey(path, keyHex);
+    if (expected.length !== signature.length || !/^[\da-f]+$/i.test(signature))
+        return false;
+    return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@vouchington/utils",
+  "version": "0.0.0",
+  "description": "Dependency-free runtime utilities for Vouchington-style applications.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    "./token-secrets": {
+      "types": "./dist/token-secrets.d.mts",
+      "import": "./dist/token-secrets.mjs",
+      "default": "./dist/token-secrets.mjs"
+    },
+    "./deploy-environment": {
+      "types": "./dist/deploy-environment.d.mts",
+      "import": "./dist/deploy-environment.mjs",
+      "default": "./dist/deploy-environment.mjs"
+    },
+    "./url-signing": {
+      "types": "./dist/url-signing.d.mts",
+      "import": "./dist/url-signing.mjs",
+      "default": "./dist/url-signing.mjs"
+    },
+    "./request-client-info": {
+      "types": "./dist/request-client-info.d.mts",
+      "import": "./dist/request-client-info.mjs",
+      "default": "./dist/request-client-info.mjs"
+    },
+    "./money": {
+      "types": "./dist/money.d.mts",
+      "import": "./dist/money.mjs",
+      "default": "./dist/money.mjs"
+    },
+    "./env-contract": {
+      "types": "./dist/env-contract.d.mts",
+      "import": "./dist/env-contract.mjs",
+      "default": "./dist/env-contract.mjs"
+    },
+    "./cookies": {
+      "types": "./dist/cookies.d.mts",
+      "import": "./dist/cookies.mjs",
+      "default": "./dist/cookies.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}