@vouchington/utils 0.5.0 → 0.5.2

package/README.md

@@ -6,14 +6,21 @@ 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'
+import { parseCookies, serializeCookie } from '@vouchington/utils/cookies'
+import { buildSignatureHeaders, verifySignature } from '@vouchington/utils/http-signatures'
 import { bestAcceptLanguageMatch } from '@vouchington/utils/language-tags'
 import { createMessageTranslator } from '@vouchington/utils/message-catalog'
 import { createReportInputParser } from '@vouchington/utils/moderation'
+import { getSentryEnvelopeDiagnostics } from '@vouchington/utils/sentry-envelope'
+import { createScopeCatalog } from '@vouchington/utils/scopes'
 ```
 
 ## Subpaths
 
+- `sentry-envelope`: bounded UTF-8 envelope record scanning and safe item-type diagnostics.
+  Callers choose the byte and type-list limits; DSN, tunnel, request, and logging policy stay local.
+- `scopes`: caller-owned scope catalog validation, prerequisite expansion, audience and surface
+  filtering, and explicit coverage graph calculation. No default catalog or legacy grants are built in.
 - `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
@@ -23,11 +30,17 @@ import { createReportInputParser } from '@vouchington/utils/moderation'
 - `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.
+  the caller's catalog. `allocateProportionalAmount(amount, numerator, denominator, rounding)`
+  allocates an inclusive fraction with `down` or `up` integer rounding chosen explicitly by the
+  caller; it uses exact integer arithmetic rather than floating-point division.
 - `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`.
+  `parseCookies(header)` splits a `Cookie` request header into a name/value `Map`.
+- `http-signatures`: Node-only (`node:crypto`) Cavage-12 HTTP Signatures. Callers pass signed
+  headers, allowed algorithms, and `maxAgeSeconds` on both sign and verify. The package has no
+  default header set or product keyId policy.
 - `collections`, `async`, and `stable-json`: collection deduplication/merging, bounded async mapping,
   and deterministic JSON serialization.
 - `feature-flags`: base64 JSON feature-flag cookie parsing and serialization with caller-injected
@@ -40,12 +53,16 @@ import { createReportInputParser } from '@vouchington/utils/moderation'
   validation. Applications own catalogs, policy, error mapping, persistence, and HTTP behavior.
 - `query` and `query-string`: generic array/boolean/number parsing, bounded integer parsing, and
   query-string serialization. Cursor parsing intentionally belongs to `@vouchington/pagination`.
-- `slugs` and `urls`: ASCII-only slugification and URL/hostname primitives. URL hostname helpers
-  return `null` for invalid input; `normalizeAsciiHostname` names its ASCII-only contract directly,
-  while `normalizeHostname` also supports WHATWG IDN conversion. `matchesHostnamePattern` supports
-  exact and inclusive `*.` hostname patterns.
+- `slugs` and `urls`: ASCII-only slugification, the `isSlug` lowercase `[a-z0-9-]+` predicate
+  (leading, trailing, and consecutive hyphens are allowed), and URL/hostname primitives. URL hostname
+  helpers return `null` for invalid input; `normalizeAsciiHostname` names its ASCII-only contract
+  directly, while `normalizeHostname` also supports WHATWG IDN conversion.
+  `matchesHostnamePattern` supports exact and inclusive `*.` hostname patterns.
 - `hashtags`: caller-configured authored/key length and separator policy for canonical ASCII hashtag
-  keys. The package does not choose application limits or accepted input separators.
+  keys, plus `maskHashtagBearingUrls` to blank absolute URLs and fragment-bearing relative paths.
+  The package does not choose application limits or accepted input separators.
+- `utm`: `createUtmParser({ sourceAliases, fallbackSourceParam? })` lowercases and trims UTM fields
+  and resolves `utm_source` through caller-owned aliases. The package has no default shortcode map.
 - `fetch-ports`: the Fetch standard forbidden-port list and membership predicates.
 - `http-body`: bounded Fetch response-body reads with abort propagation and typed missing/oversize
   errors.

package/dist/cookies.d.mts

@@ -6,3 +6,4 @@ export type CookieAttributes = {
     secure: boolean;
 };
 export declare function serializeCookie(name: string, value: string, attributes: CookieAttributes): string;
+export declare function parseCookies(cookieHeader?: string | null): Map<string, string>;

package/dist/cookies.mjs

@@ -30,3 +30,19 @@ export function serializeCookie(name, value, attributes) {
         parts.push('Secure');
     return parts.join('; ');
 }
+const COOKIE_SPLIT_REGEX = /;\s*/;
+export function parseCookies(cookieHeader) {
+    const cookies = new Map();
+    if (!cookieHeader)
+        return cookies;
+    for (const part of cookieHeader.split(COOKIE_SPLIT_REGEX)) {
+        const separatorIndex = part.indexOf('=');
+        if (separatorIndex <= 0)
+            continue;
+        const name = part.slice(0, separatorIndex).trim();
+        const value = part.slice(separatorIndex + 1).trim();
+        if (name.length > 0)
+            cookies.set(name, value);
+    }
+    return cookies;
+}

package/dist/hashtags.d.mts

@@ -13,3 +13,8 @@ export interface HashtagNormalizer {
 }
 /** Creates an ASCII hashtag normalizer whose length and separator policy is caller-owned. */
 export declare function createHashtagNormalizer(options: HashtagNormalizerOptions): HashtagNormalizer;
+/**
+ * Blanks absolute URLs and relative paths that contain `#` so fragment text is
+ * not treated as a hashtag. Parentheses stay balanced for Wikipedia-style paths.
+ */
+export declare function maskHashtagBearingUrls(input: string): string;

package/dist/hashtags.mjs

@@ -42,3 +42,46 @@ function createSeparatorPattern(separators) {
 function escapeRegularExpression(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+const absoluteUrlPrefix = /(?:https?:\/\/|www\.)/gi;
+const urlBoundary = /[\s<>]/;
+/**
+ * Blanks absolute URLs and relative paths that contain `#` so fragment text is
+ * not treated as a hashtag. Parentheses stay balanced for Wikipedia-style paths.
+ */
+export function maskHashtagBearingUrls(input) {
+    const masked = input.split('');
+    for (const match of input.matchAll(absoluteUrlPrefix)) {
+        const start = match.index;
+        maskRange(masked, start, findUrlEnd(input, start));
+    }
+    for (let start = 0; start < input.length; start += 1) {
+        if (input[start] !== '/')
+            continue;
+        const end = findUrlEnd(input, start);
+        if (input.slice(start, end).includes('#'))
+            maskRange(masked, start, end);
+        start = end - 1;
+    }
+    return masked.join('');
+}
+function findUrlEnd(input, start) {
+    let parenthesisDepth = 0;
+    for (let index = start; index < input.length; index += 1) {
+        const character = input[index];
+        if (urlBoundary.test(character))
+            return index;
+        if (character === '(') {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ')') {
+            if (parenthesisDepth === 0)
+                return index;
+            parenthesisDepth -= 1;
+        }
+    }
+    return input.length;
+}
+function maskRange(masked, start, end) {
+    masked.fill(' ', start, end);
+}

package/dist/http-signatures-digest.d.mts

@@ -0,0 +1,3 @@
+export declare function computeDigest(body: string | Buffer): string;
+export declare function extractDigestHash(digestHeader: string): string;
+export declare function verifyDigest(body: string | Buffer, expectedDigestHeader: string): boolean;

package/dist/http-signatures-digest.mjs

@@ -0,0 +1,20 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+const DIGEST_HEADER_PATTERN = /^SHA-256=(.+)$/;
+export function computeDigest(body) {
+    const bodyBuffer = typeof body === 'string' ? Buffer.from(body, 'utf-8') : body;
+    const hash = createHash('sha256').update(bodyBuffer).digest('base64');
+    return `SHA-256=${hash}`;
+}
+export function extractDigestHash(digestHeader) {
+    const match = DIGEST_HEADER_PATTERN.exec(digestHeader);
+    if (!match?.[1])
+        throw new Error('Invalid Digest header format');
+    return match[1];
+}
+export function verifyDigest(body, expectedDigestHeader) {
+    const computed = Buffer.from(computeDigest(body));
+    const expected = Buffer.from(expectedDigestHeader);
+    if (computed.length !== expected.length)
+        return false;
+    return timingSafeEqual(computed, expected);
+}

package/dist/http-signatures-keys.d.mts

@@ -0,0 +1,7 @@
+export type RsaSha256KeyPair = {
+    publicKeyPem: string;
+    privateKeyPem: string;
+};
+export declare function generateRsaSha256KeyPair(): RsaSha256KeyPair;
+export declare function assertPublicKeyPem(pem: string): void;
+export declare function assertPrivateKeyPem(pem: string): void;

package/dist/http-signatures-keys.mjs

@@ -0,0 +1,27 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
+export function generateRsaSha256KeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    return { publicKeyPem: publicKey, privateKeyPem: privateKey };
+}
+export function assertPublicKeyPem(pem) {
+    if (pem.includes('PRIVATE'))
+        throw new Error('Invalid public key PEM format');
+    try {
+        createPublicKey(pem);
+    }
+    catch {
+        throw new Error('Invalid public key PEM format');
+    }
+}
+export function assertPrivateKeyPem(pem) {
+    try {
+        createPrivateKey(pem);
+    }
+    catch {
+        throw new Error('Invalid private key PEM format');
+    }
+}

package/dist/http-signatures-sign.d.mts

@@ -0,0 +1,17 @@
+export type SignatureHeaders = {
+    digest: string;
+    signature: string;
+    date: string;
+};
+export type BuildSignatureHeadersOptions = {
+    method: string;
+    url: string;
+    body: string | Buffer;
+    keyId: string;
+    privateKeyPem: string;
+    signedHeaders: readonly string[];
+    algorithm: string;
+    now?: Date;
+    additionalHeaders?: Record<string, string>;
+};
+export declare function buildSignatureHeaders(options: BuildSignatureHeadersOptions): SignatureHeaders;

package/dist/http-signatures-sign.mjs

@@ -0,0 +1,35 @@
+import { createPrivateKey, sign } from 'node:crypto';
+import { computeDigest } from './http-signatures-digest.mjs';
+import { assertPrivateKeyPem } from './http-signatures-keys.mjs';
+import { buildSigningString, isSha256SignatureAlgorithm } from './http-signatures-string.mjs';
+export function buildSignatureHeaders(options) {
+    if (options.signedHeaders.length === 0)
+        throw new Error('signedHeaders must not be empty');
+    if (!isSha256SignatureAlgorithm(options.algorithm)) {
+        throw new Error(`Unsupported signature algorithm: ${options.algorithm}`);
+    }
+    assertPrivateKeyPem(options.privateKeyPem);
+    const digest = computeDigest(options.body);
+    const date = (options.now ?? new Date()).toUTCString();
+    const url = new URL(options.url);
+    const host = url.host;
+    const path = url.pathname + url.search;
+    const signingString = buildSigningString(options.signedHeaders, {
+        method: options.method,
+        path,
+        host,
+        date,
+        digest,
+        additionalHeaders: options.additionalHeaders,
+    });
+    if (typeof signingString !== 'string')
+        throw new Error(signingString.error);
+    const signature = sign('sha256', Buffer.from(signingString), createPrivateKey(options.privateKeyPem)).toString('base64');
+    const signatureHeaderValue = [
+        `keyId="${options.keyId}"`,
+        `algorithm="${options.algorithm}"`,
+        `headers="${options.signedHeaders.map((name) => name.toLowerCase()).join(' ')}"`,
+        `signature="${signature}"`,
+    ].join(',');
+    return { digest, signature: signatureHeaderValue, date };
+}

package/dist/http-signatures-string.d.mts

@@ -0,0 +1,12 @@
+export type SigningHeaderValues = {
+    method: string;
+    path: string;
+    host: string;
+    date: string;
+    digest: string;
+    additionalHeaders?: Record<string, string> | undefined;
+};
+export declare function isSha256SignatureAlgorithm(algorithm: string): boolean;
+export declare function buildSigningString(headerNames: readonly string[], values: SigningHeaderValues): string | {
+    error: string;
+};

package/dist/http-signatures-string.mjs

@@ -0,0 +1,40 @@
+const SHA256_ALGORITHMS = new Set(['rsa-sha256', 'hs2019']);
+export function isSha256SignatureAlgorithm(algorithm) {
+    return SHA256_ALGORITHMS.has(algorithm);
+}
+function additionalHeaderValue(headers, name) {
+    if (!headers)
+        return undefined;
+    if (Object.hasOwn(headers, name))
+        return headers[name];
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return value;
+    }
+    return undefined;
+}
+function signingLineForHeader(name, values) {
+    const lower = name.toLowerCase();
+    if (lower === '(request-target)') {
+        return `(request-target): ${values.method.toLowerCase()} ${values.path}`;
+    }
+    if (lower === 'host')
+        return `host: ${values.host}`;
+    if (lower === 'date')
+        return `date: ${values.date}`;
+    if (lower === 'digest')
+        return `digest: ${values.digest}`;
+    const extra = additionalHeaderValue(values.additionalHeaders, name);
+    return extra === undefined ? undefined : `${lower}: ${extra}`;
+}
+export function buildSigningString(headerNames, values) {
+    const lines = [];
+    for (const name of headerNames) {
+        const line = signingLineForHeader(name, values);
+        if (line === undefined)
+            return { error: `Unknown signed header: ${name}` };
+        lines.push(line);
+    }
+    return lines.join('\n');
+}

package/dist/http-signatures-test-helpers.d.mts

@@ -0,0 +1,30 @@
+import type { VerifySignatureOptions } from './http-signatures-verify.mts';
+export declare const KEY_ID = "https://example.test/users/alice#main-key";
+export declare const BODY: string;
+export declare const FULL_HEADERS: readonly ['(request-target)', 'host', 'date', 'digest'];
+export declare const defaultVerifyPolicy: {
+    readonly requiredHeaders: readonly ["(request-target)", "host", "date", "digest"];
+    readonly allowedAlgorithms: readonly ["rsa-sha256", "hs2019"];
+    readonly maxAgeSeconds: 3600;
+};
+export declare const defaultSignPolicy: {
+    readonly signedHeaders: readonly ["(request-target)", "host", "date", "digest"];
+    readonly algorithm: 'rsa-sha256';
+};
+export declare function digestAndDate(body?: string | Buffer): {
+    digestHeader: string;
+    dateHeader: string;
+};
+export declare function verifyArgs(publicKeyPem: string, signatureHeader: string, extras?: Partial<VerifySignatureOptions>): VerifySignatureOptions;
+export declare function buildManualSignature(options: {
+    privateKeyPem: string;
+    dateHeader: string;
+    digestHeader: string;
+    headerNames: readonly string[];
+    additionalHeaders?: Record<string, string>;
+    keyId?: string;
+    algorithm?: string | null;
+    method?: string;
+    path?: string;
+    host?: string;
+}): string;

package/dist/http-signatures-test-helpers.mjs

@@ -0,0 +1,62 @@
+import { createPrivateKey, sign as cryptoSign } from 'node:crypto';
+import { computeDigest } from './http-signatures-digest.mjs';
+export const KEY_ID = 'https://example.test/users/alice#main-key';
+const METHOD = 'POST';
+const PATH = '/inbox';
+const HOST = 'mastodon.example';
+export const BODY = JSON.stringify({ type: 'Follow', object: 'https://example.test' });
+export const FULL_HEADERS = ['(request-target)', 'host', 'date', 'digest'];
+const ALLOWED_ALGORITHMS = ['rsa-sha256', 'hs2019'];
+const MAX_AGE_SECONDS = 3600;
+export const defaultVerifyPolicy = {
+    requiredHeaders: FULL_HEADERS,
+    allowedAlgorithms: ALLOWED_ALGORITHMS,
+    maxAgeSeconds: MAX_AGE_SECONDS,
+};
+export const defaultSignPolicy = {
+    signedHeaders: FULL_HEADERS,
+    algorithm: 'rsa-sha256',
+};
+export function digestAndDate(body = BODY) {
+    return { digestHeader: computeDigest(body), dateHeader: new Date().toUTCString() };
+}
+export function verifyArgs(publicKeyPem, signatureHeader, extras = {}) {
+    const { digestHeader, dateHeader } = digestAndDate(extras.body ?? BODY);
+    return {
+        method: METHOD,
+        path: PATH,
+        host: HOST,
+        body: BODY,
+        signatureHeader,
+        digestHeader,
+        dateHeader,
+        publicKeyPem,
+        ...defaultVerifyPolicy,
+        ...extras,
+    };
+}
+export function buildManualSignature(options) {
+    const headerNames = options.headerNames;
+    const signingString = headerNames
+        .map((name) => {
+        if (name === '(request-target)') {
+            return `(request-target): ${(options.method ?? METHOD).toLowerCase()} ${options.path ?? PATH}`;
+        }
+        if (name === 'host')
+            return `host: ${options.host ?? HOST}`;
+        if (name === 'date')
+            return `date: ${options.dateHeader}`;
+        if (name === 'digest')
+            return `digest: ${options.digestHeader}`;
+        return `${name}: ${options.additionalHeaders?.[name]}`;
+    })
+        .join('\n');
+    const signature = cryptoSign('sha256', Buffer.from(signingString), createPrivateKey(options.privateKeyPem)).toString('base64');
+    const headerParts = [`keyId="${options.keyId ?? KEY_ID}"`];
+    if (options.algorithm !== null) {
+        headerParts.push(`algorithm="${options.algorithm ?? 'rsa-sha256'}"`);
+    }
+    headerParts.push(`headers="${headerNames.join(' ')}"`);
+    headerParts.push(`signature="${signature}"`);
+    return headerParts.join(',');
+}

package/dist/http-signatures-verify.d.mts

@@ -0,0 +1,21 @@
+export type VerifySignatureOptions = {
+    method: string;
+    path: string;
+    host: string;
+    body: string | Buffer;
+    signatureHeader: string;
+    digestHeader: string;
+    dateHeader: string;
+    publicKeyPem: string;
+    requiredHeaders: readonly string[];
+    allowedAlgorithms: readonly string[];
+    maxAgeSeconds: number;
+    additionalHeaders?: Record<string, string>;
+    referenceTime?: Date;
+};
+export type SignatureVerificationResult = {
+    valid: boolean;
+    error?: string;
+};
+export declare function extractSignatureKeyId(signatureHeader: string): string | undefined;
+export declare function verifySignature(options: VerifySignatureOptions): SignatureVerificationResult;

package/dist/http-signatures-verify.mjs

@@ -0,0 +1,88 @@
+import { verify } from 'node:crypto';
+import { verifyDigest } from './http-signatures-digest.mjs';
+import { assertPublicKeyPem } from './http-signatures-keys.mjs';
+import { buildSigningString, isSha256SignatureAlgorithm } from './http-signatures-string.mjs';
+const SIGNATURE_VALUE_PATTERN = /signature="([^"]+)"/;
+const HEADERS_VALUE_PATTERN = /headers="([^"]+)"/;
+const ALGORITHM_VALUE_PATTERN = /algorithm="([^"]+)"/;
+const KEY_ID_VALUE_PATTERN = /keyId="([^"]+)"/;
+export function extractSignatureKeyId(signatureHeader) {
+    return KEY_ID_VALUE_PATTERN.exec(signatureHeader)?.[1];
+}
+function parseSignatureHeader(header) {
+    const signatureMatch = SIGNATURE_VALUE_PATTERN.exec(header);
+    const headersMatch = HEADERS_VALUE_PATTERN.exec(header);
+    if (!signatureMatch?.[1] || !headersMatch?.[1])
+        return null;
+    return {
+        signature: signatureMatch[1],
+        headers: headersMatch[1].split(' ').map((name) => name.toLowerCase()),
+        algorithm: ALGORITHM_VALUE_PATTERN.exec(header)?.[1] ?? null,
+    };
+}
+export function verifySignature(options) {
+    try {
+        return verifySignatureBody(options);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Signature verification exception: ${err.message}`,
+        };
+    }
+}
+function verifySignatureBody(options) {
+    assertPublicKeyPem(options.publicKeyPem);
+    const requestDate = new Date(options.dateHeader);
+    if (Number.isNaN(requestDate.getTime()))
+        return { valid: false, error: 'Invalid date header' };
+    const ageSeconds = ((options.referenceTime?.getTime() ?? Date.now()) - requestDate.getTime()) / 1000;
+    if (!Number.isFinite(options.maxAgeSeconds) || options.maxAgeSeconds < 0) {
+        return { valid: false, error: 'maxAgeSeconds must be a finite non-negative number' };
+    }
+    if (Math.abs(ageSeconds) > options.maxAgeSeconds) {
+        return {
+            valid: false,
+            error: `Date header too old: ${ageSeconds}s > ${options.maxAgeSeconds}s`,
+        };
+    }
+    if (!verifyDigest(options.body, options.digestHeader)) {
+        return { valid: false, error: 'Digest verification failed' };
+    }
+    const sigParts = parseSignatureHeader(options.signatureHeader);
+    if (!sigParts)
+        return { valid: false, error: 'Invalid signature header format' };
+    const { signature, headers, algorithm } = sigParts;
+    if (algorithm === null ||
+        !options.allowedAlgorithms.includes(algorithm) ||
+        !isSha256SignatureAlgorithm(algorithm)) {
+        return {
+            valid: false,
+            error: algorithm === null
+                ? 'Signature algorithm is required'
+                : `Unsupported signature algorithm: ${algorithm}`,
+        };
+    }
+    const covered = new Set(headers);
+    const missingRequired = options.requiredHeaders
+        .map((name) => name.toLowerCase())
+        .filter((name) => !covered.has(name));
+    if (missingRequired.length > 0) {
+        return {
+            valid: false,
+            error: `Signature must cover ${options.requiredHeaders.join(', ')} (missing: ${missingRequired.join(', ')})`,
+        };
+    }
+    const signingString = buildSigningString(headers, {
+        method: options.method,
+        path: options.path,
+        host: options.host,
+        date: options.dateHeader,
+        digest: options.digestHeader,
+        additionalHeaders: options.additionalHeaders,
+    });
+    if (typeof signingString !== 'string')
+        return { valid: false, error: signingString.error };
+    const isValid = verify('sha256', Buffer.from(signingString), options.publicKeyPem, Buffer.from(signature, 'base64'));
+    return isValid ? { valid: true } : { valid: false, error: 'Signature verification failed' };
+}

package/dist/http-signatures.d.mts

@@ -0,0 +1,4 @@
+export { computeDigest, extractDigestHash, verifyDigest } from './http-signatures-digest.mts';
+export { assertPrivateKeyPem, assertPublicKeyPem, generateRsaSha256KeyPair, type RsaSha256KeyPair, } from './http-signatures-keys.mts';
+export { buildSignatureHeaders, type BuildSignatureHeadersOptions, type SignatureHeaders, } from './http-signatures-sign.mts';
+export { extractSignatureKeyId, verifySignature, type SignatureVerificationResult, type VerifySignatureOptions, } from './http-signatures-verify.mts';

package/dist/http-signatures.mjs

@@ -0,0 +1,4 @@
+export { computeDigest, extractDigestHash, verifyDigest } from './http-signatures-digest.mjs';
+export { assertPrivateKeyPem, assertPublicKeyPem, generateRsaSha256KeyPair, } from './http-signatures-keys.mjs';
+export { buildSignatureHeaders, } from './http-signatures-sign.mjs';
+export { extractSignatureKeyId, verifySignature, } from './http-signatures-verify.mjs';

package/dist/money.d.mts

@@ -19,6 +19,15 @@ export type MoneyRange<Code extends string = string> = {
     minimum: Money<Code>;
     maximum: Money<Code> | null;
 };
+export type ProportionalRounding = 'down' | 'up';
+/**
+ * Allocates a non-negative integer amount by an inclusive fraction.
+ *
+ * The result is exact when `amount * numerator` divides by `denominator`; otherwise callers
+ * explicitly select integer rounding down or up. All arithmetic is performed with `bigint` so
+ * safe integer inputs never pass through floating-point division.
+ */
+export declare function allocateProportionalAmount(amount: number, numerator: number, denominator: number, rounding: ProportionalRounding): number;
 export declare function createMoneyCatalog<const Currencies extends readonly Currency[]>(entries: Currencies, scale: number): {
     currencies: readonly Readonly<{
         code: string;

package/dist/money.mjs

@@ -1,4 +1,24 @@
 export const MAX_MONEY_AMOUNT = Number.MAX_SAFE_INTEGER;
+/**
+ * Allocates a non-negative integer amount by an inclusive fraction.
+ *
+ * The result is exact when `amount * numerator` divides by `denominator`; otherwise callers
+ * explicitly select integer rounding down or up. All arithmetic is performed with `bigint` so
+ * safe integer inputs never pass through floating-point division.
+ */
+export function allocateProportionalAmount(amount, numerator, denominator, rounding) {
+    if (!isAmount(amount) || !isAmount(numerator) || !isAmount(denominator))
+        throw new TypeError('Proportional allocation requires non-negative safe integer inputs');
+    if (denominator === 0 || numerator > denominator)
+        throw new RangeError('Proportional allocation requires a fraction from zero through one');
+    if (rounding !== 'down' && rounding !== 'up')
+        throw new TypeError('Proportional allocation rounding must be down or up');
+    const product = BigInt(amount) * BigInt(numerator);
+    const divisor = BigInt(denominator);
+    const quotient = product / divisor;
+    const result = rounding === 'up' && product % divisor !== 0n ? quotient + 1n : quotient;
+    return Number(result);
+}
 export function createMoneyCatalog(entries, scale) {
     validateScale(scale);
     for (const currency of entries)

package/dist/scopes.d.mts

@@ -0,0 +1,29 @@
+export interface ScopeDefinition {
+    audience: string;
+    surfaces: readonly string[];
+    requires?: readonly string[];
+    covers?: readonly string[];
+}
+export type ScopeValidationCode = 'duplicate-scope' | 'empty-scope-set' | 'missing-prerequisite' | 'mixed-audiences' | 'unsupported-surface' | 'unknown-scope';
+export type ScopeValidationResult = {
+    valid: true;
+    scopes: string[];
+    audiences: string[];
+} | {
+    valid: false;
+    code: ScopeValidationCode;
+    scope?: string;
+    requiredScope?: string;
+};
+export interface ScopeCatalog {
+    hasScope(granted: readonly string[], required: string): boolean;
+    hasEveryScope(granted: readonly string[], required: readonly string[]): boolean;
+    expandPrerequisites(scopes: readonly string[]): string[];
+    listScopesForAudience(audience: string, surface: string): string[];
+    validateScopeSet(input: readonly string[], options: {
+        surface: string;
+        allowMixedAudiences: boolean;
+    }): ScopeValidationResult;
+}
+/** Compile a caller-owned scope graph; product grant and authorization decisions stay in callers. */
+export declare function createScopeCatalog(definitions: Record<string, ScopeDefinition>): ScopeCatalog;

package/dist/scopes.mjs

@@ -0,0 +1,122 @@
+/** Compile a caller-owned scope graph; product grant and authorization decisions stay in callers. */
+export function createScopeCatalog(definitions) {
+    const catalog = new Map();
+    for (const [scope, definition] of Object.entries(definitions)) {
+        if (!scope ||
+            !definition ||
+            typeof definition.audience !== 'string' ||
+            !definition.audience ||
+            !Array.isArray(definition.surfaces) ||
+            definition.surfaces.length === 0 ||
+            definition.surfaces.some((surface) => typeof surface !== 'string' || !surface)) {
+            throw new TypeError(`Invalid scope definition for ${scope}`);
+        }
+        for (const edges of [definition.requires, definition.covers]) {
+            if (edges !== undefined &&
+                (!Array.isArray(edges) || edges.some((edge) => typeof edge !== 'string' || !edge))) {
+                throw new TypeError(`Invalid scope edges for ${scope}`);
+            }
+        }
+        catalog.set(scope, {
+            audience: definition.audience,
+            surfaces: [...definition.surfaces],
+            requires: [...(definition.requires ?? [])],
+            covers: [...(definition.covers ?? [])],
+        });
+    }
+    for (const relation of ['requires', 'covers'])
+        assertAcyclic(catalog, relation);
+    function requireScope(scope) {
+        const definition = catalog.get(scope);
+        if (!definition)
+            throw new RangeError(`Unknown scope: ${scope}`);
+        return definition;
+    }
+    function expandPrerequisites(scopes) {
+        const expanded = new Set();
+        function visit(scope) {
+            if (expanded.has(scope))
+                return;
+            const definition = requireScope(scope);
+            expanded.add(scope);
+            for (const required of definition.requires)
+                visit(required);
+        }
+        for (const scope of scopes)
+            visit(scope);
+        return [...expanded].sort();
+    }
+    function covers(granted, required, visited) {
+        if (granted === required)
+            return true;
+        if (visited.has(granted))
+            return false;
+        visited.add(granted);
+        return requireScope(granted).covers.some((scope) => covers(scope, required, visited));
+    }
+    function hasScope(granted, required) {
+        requireScope(required);
+        return granted.some((scope) => covers(scope, required, new Set()));
+    }
+    return {
+        expandPrerequisites,
+        hasScope,
+        hasEveryScope(granted, required) {
+            return required.every((scope) => hasScope(granted, scope));
+        },
+        listScopesForAudience(audience, surface) {
+            return [...catalog]
+                .filter(([, definition]) => definition.audience === audience && definition.surfaces.includes(surface))
+                .map(([scope]) => scope)
+                .sort();
+        },
+        validateScopeSet(input, options) {
+            if (input.length === 0)
+                return { valid: false, code: 'empty-scope-set' };
+            const seen = new Set();
+            for (const scope of input) {
+                const definition = catalog.get(scope);
+                if (!definition)
+                    return { valid: false, code: 'unknown-scope', scope };
+                if (seen.has(scope))
+                    return { valid: false, code: 'duplicate-scope', scope };
+                if (!definition.surfaces.includes(options.surface)) {
+                    return { valid: false, code: 'unsupported-surface', scope };
+                }
+                seen.add(scope);
+            }
+            const scopes = [...seen].sort();
+            for (const scope of scopes) {
+                for (const requiredScope of requireScope(scope).requires) {
+                    if (!seen.has(requiredScope)) {
+                        return { valid: false, code: 'missing-prerequisite', scope, requiredScope };
+                    }
+                }
+            }
+            const audiences = [...new Set(scopes.map((scope) => requireScope(scope).audience))].sort();
+            if (!options.allowMixedAudiences && audiences.length > 1) {
+                return { valid: false, code: 'mixed-audiences' };
+            }
+            return { valid: true, scopes, audiences };
+        },
+    };
+}
+function assertAcyclic(catalog, relation) {
+    const done = new Set();
+    const active = new Set();
+    function visit(scope) {
+        if (!catalog.has(scope))
+            throw new RangeError(`Unknown ${relation} scope: ${scope}`);
+        if (active.has(scope))
+            throw new RangeError(`Scope ${relation} cycle at ${scope}`);
+        if (done.has(scope))
+            return;
+        active.add(scope);
+        for (const next of catalog.get(scope)[relation])
+            visit(next);
+        active.delete(scope);
+        done.add(scope);
+    }
+    for (const scope of catalog.keys())
+        visit(scope);
+}

package/dist/sentry-envelope.d.mts

@@ -0,0 +1,10 @@
+export interface SentryEnvelopeDiagnostics {
+    envelopeItemCount?: number;
+    envelopeItemTypes?: string[];
+}
+export interface SentryEnvelopeLimits {
+    maxBytes: number;
+    maxItemTypes: number;
+}
+/** Read bounded envelope item metadata without inspecting payload content. */
+export declare function getSentryEnvelopeDiagnostics(envelope: string, limits: SentryEnvelopeLimits): SentryEnvelopeDiagnostics;

package/dist/sentry-envelope.mjs

@@ -0,0 +1,82 @@
+const ITEM_TYPE_PATTERN = /^[a-z0-9_.-]{1,64}$/;
+/** Read bounded envelope item metadata without inspecting payload content. */
+export function getSentryEnvelopeDiagnostics(envelope, limits) {
+    if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 1) {
+        throw new RangeError('maxBytes must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(limits.maxItemTypes) || limits.maxItemTypes < 0) {
+        throw new RangeError('maxItemTypes must be a non-negative safe integer');
+    }
+    if (envelope.length > limits.maxBytes ||
+        new TextEncoder().encode(envelope).length > limits.maxBytes) {
+        throw new RangeError('Envelope exceeds maxBytes');
+    }
+    const firstLineEnd = envelope.indexOf('\n');
+    if (firstLineEnd === -1)
+        return {};
+    const itemTypes = [];
+    let itemCount = 0;
+    let cursor = firstLineEnd + 1;
+    while (cursor < envelope.length) {
+        if (envelope[cursor] === '\n') {
+            cursor += 1;
+            continue;
+        }
+        const itemHeaderEnd = envelope.indexOf('\n', cursor);
+        if (itemHeaderEnd === -1)
+            break;
+        const line = envelope.slice(cursor, itemHeaderEnd).replace(/\r$/, '');
+        cursor = itemHeaderEnd + 1;
+        if (!line)
+            continue;
+        let header;
+        try {
+            header = JSON.parse(line);
+        }
+        catch {
+            break;
+        }
+        if (!header || typeof header !== 'object' || Array.isArray(header))
+            break;
+        itemCount += 1;
+        const type = header.type;
+        if (typeof type === 'string' &&
+            ITEM_TYPE_PATTERN.test(type) &&
+            !itemTypes.includes(type) &&
+            itemTypes.length < limits.maxItemTypes) {
+            itemTypes.push(type);
+        }
+        const length = header.length;
+        if (typeof length === 'number' && Number.isSafeInteger(length) && length >= 0) {
+            const next = advanceByUtf8Bytes(envelope, cursor, length);
+            if (next === null)
+                break;
+            cursor = next;
+            if (envelope[cursor] === '\r' && envelope[cursor + 1] === '\n')
+                cursor += 2;
+            else if (envelope[cursor] === '\n')
+                cursor += 1;
+            continue;
+        }
+        const payloadEnd = envelope.indexOf('\n', cursor);
+        if (payloadEnd === -1)
+            break;
+        cursor = payloadEnd + 1;
+    }
+    return {
+        ...(itemCount > 0 ? { envelopeItemCount: itemCount } : {}),
+        ...(itemTypes.length > 0 ? { envelopeItemTypes: itemTypes } : {}),
+    };
+}
+function advanceByUtf8Bytes(envelope, cursor, length) {
+    let bytes = 0;
+    while (cursor < envelope.length && bytes < length) {
+        const point = envelope.codePointAt(cursor);
+        const size = point <= 0x7f ? 1 : point <= 0x7ff ? 2 : point <= 0xffff ? 3 : 4;
+        if (bytes + size > length)
+            return null;
+        bytes += size;
+        cursor += point > 0xffff ? 2 : 1;
+    }
+    return bytes === length ? cursor : null;
+}

package/dist/slugs.d.mts

@@ -1 +1,3 @@
 export declare function slugifyAscii(value: string): string;
+/** True for a non-empty string of lowercase ASCII letters, digits, and hyphens. */
+export declare function isSlug(value: string): boolean;

package/dist/slugs.mjs

@@ -7,3 +7,7 @@ export function slugifyAscii(value) {
         .replace(/-+/g, '-')
         .replace(/^-|-$/g, '');
 }
+/** True for a non-empty string of lowercase ASCII letters, digits, and hyphens. */
+export function isSlug(value) {
+    return value.length > 0 && /^[a-z0-9-]+$/.test(value);
+}

package/dist/utm.d.mts

@@ -0,0 +1,16 @@
+export interface UtmParserOptions {
+    sourceAliases: Readonly<Record<string, string>>;
+    fallbackSourceParam?: string;
+}
+export interface ExtractedUtmParams {
+    utmSource: string | null;
+    utmMedium: string | null;
+    utmCampaign: string | null;
+    utmContent: string | null;
+}
+export interface UtmParser {
+    resolveSource(value: string): string;
+    extractFromUrl(url: URL): ExtractedUtmParams;
+}
+/** Creates a UTM parser whose source aliases and fallback param are caller-owned. */
+export declare function createUtmParser(options: UtmParserOptions): UtmParser;

package/dist/utm.mjs

@@ -0,0 +1,28 @@
+/** Creates a UTM parser whose source aliases and fallback param are caller-owned. */
+export function createUtmParser(options) {
+    const sourceAliases = {};
+    for (const [key, value] of Object.entries(options.sourceAliases)) {
+        sourceAliases[key.toLowerCase().trim()] = value.toLowerCase().trim();
+    }
+    const fallbackSourceParam = options.fallbackSourceParam;
+    function resolveSource(value) {
+        const lower = value.toLowerCase().trim();
+        return sourceAliases[lower] ?? lower;
+    }
+    return {
+        resolveSource,
+        extractFromUrl(url) {
+            const rawSource = url.searchParams.get('utm_source');
+            const fallback = fallbackSourceParam === undefined ? null : url.searchParams.get(fallbackSourceParam);
+            const normalizedSource = rawSource ? resolveSource(rawSource) || null : null;
+            const normalizedFallback = fallback ? resolveSource(fallback) || null : null;
+            const utmSource = normalizedSource ?? normalizedFallback;
+            return {
+                utmSource,
+                utmMedium: url.searchParams.get('utm_medium')?.toLowerCase().trim() || null,
+                utmCampaign: url.searchParams.get('utm_campaign')?.toLowerCase().trim() || null,
+                utmContent: url.searchParams.get('utm_content')?.toLowerCase().trim() || null,
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -20,6 +20,16 @@
   ],
   "type": "module",
   "exports": {
+    "./sentry-envelope": {
+      "types": "./dist/sentry-envelope.d.mts",
+      "import": "./dist/sentry-envelope.mjs",
+      "default": "./dist/sentry-envelope.mjs"
+    },
+    "./scopes": {
+      "types": "./dist/scopes.d.mts",
+      "import": "./dist/scopes.mjs",
+      "default": "./dist/scopes.mjs"
+    },
     "./token-secrets": {
       "types": "./dist/token-secrets.d.mts",
       "import": "./dist/token-secrets.mjs",
@@ -155,6 +165,11 @@
       "import": "./dist/hashtags.mjs",
       "default": "./dist/hashtags.mjs"
     },
+    "./utm": {
+      "types": "./dist/utm.d.mts",
+      "import": "./dist/utm.mjs",
+      "default": "./dist/utm.mjs"
+    },
     "./fetch-ports": {
       "types": "./dist/fetch-ports.d.mts",
       "import": "./dist/fetch-ports.mjs",
@@ -169,16 +184,20 @@
       "types": "./dist/http-link-pagination.d.mts",
       "import": "./dist/http-link-pagination.mjs",
       "default": "./dist/http-link-pagination.mjs"
+    },
+    "./http-signatures": {
+      "types": "./dist/http-signatures.d.mts",
+      "import": "./dist/http-signatures.mjs",
+      "default": "./dist/http-signatures.mjs"
     }
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "prepack": "pnpm run build"
-  },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json"
   }
-}
+}