@vouchington/utils 0.4.0 → 0.5.0

package/README.md

@@ -9,6 +9,7 @@ import { createMoneyCatalog } from '@vouchington/utils/money'
 import { serializeCookie } from '@vouchington/utils/cookies'
 import { bestAcceptLanguageMatch } from '@vouchington/utils/language-tags'
 import { createMessageTranslator } from '@vouchington/utils/message-catalog'
+import { createReportInputParser } from '@vouchington/utils/moderation'
 ```
 
 ## Subpaths
@@ -35,6 +36,8 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
   formatting, text normalization, title casing, and word/sentence helpers.
 - `gtin`, `bigint-ids`, and `validation`: GTIN predicates, canonical positive PostgreSQL bigint IDs,
   and basic email/UUID predicates.
+- `moderation`: caller-configured report target, reason, identifier, note, and cross-field input
+  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
@@ -44,6 +47,10 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
 - `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.
 - `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.
+- `http-link-pagination`: fail-closed RFC 8288 next-link parsing with same-origin URL and
+  unambiguous cursor extraction.
 - `language-tags`: caller-configured locale normalization and strict `Accept-Language` parsing and
   best matching. HTTP ranges reject malformed syntax and quality parameters; explicit `q=0` ranges
   exclude a candidate when they tie for that candidate's most-specific matching range, so `en;q=0`

package/dist/http-body.d.mts

@@ -0,0 +1,18 @@
+export interface ReadResponseBodyOptions {
+    readonly response: Response;
+    readonly url: string;
+    readonly maxSizeBytes: number;
+    readonly signal?: AbortSignal;
+}
+export declare class MissingResponseBodyError extends Error {
+    readonly url: string;
+    constructor(url: string);
+}
+export declare class ResponseBodyTooLargeError extends Error {
+    readonly url: string;
+    readonly sizeBytes: number;
+    readonly maxSizeBytes: number;
+    constructor(url: string, sizeBytes: number, maxSizeBytes: number);
+}
+export declare function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }: ReadResponseBodyOptions): Promise<Buffer>;
+export declare function readResponseBody(options: ReadResponseBodyOptions): Promise<string>;

package/dist/http-body.mjs

@@ -0,0 +1,86 @@
+export class MissingResponseBodyError extends Error {
+    url;
+    constructor(url) {
+        super(`HTTP response from ${url} has no body`);
+        this.name = 'MissingResponseBodyError';
+        this.url = url;
+    }
+}
+export class ResponseBodyTooLargeError extends Error {
+    url;
+    sizeBytes;
+    maxSizeBytes;
+    constructor(url, sizeBytes, maxSizeBytes) {
+        super(`HTTP response from ${url} exceeded ${maxSizeBytes} bytes (read ${sizeBytes})`);
+        this.name = 'ResponseBodyTooLargeError';
+        this.url = url;
+        this.sizeBytes = sizeBytes;
+        this.maxSizeBytes = maxSizeBytes;
+    }
+}
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    if (signal.reason !== undefined)
+        return new Error(String(signal.reason));
+    return new Error('HTTP response body read aborted');
+}
+function validateMaxSize(maxSizeBytes) {
+    if (!Number.isSafeInteger(maxSizeBytes) || maxSizeBytes < 0) {
+        throw new RangeError('maxSizeBytes must be a non-negative safe integer');
+    }
+}
+export async function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }) {
+    validateMaxSize(maxSizeBytes);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new MissingResponseBodyError(url);
+    let abortListener;
+    let abortPromise;
+    if (signal) {
+        abortPromise = new Promise((_resolve, reject) => {
+            abortListener = () => {
+                const reason = abortReason(signal);
+                void reader.cancel(reason).catch(() => undefined);
+                reject(reason);
+            };
+            if (signal.aborted)
+                abortListener();
+            else
+                signal.addEventListener('abort', abortListener, { once: true });
+        });
+        void abortPromise.catch(() => undefined);
+    }
+    const chunks = [];
+    let totalSize = 0;
+    try {
+        for (;;) {
+            const result = await (abortPromise
+                ? Promise.race([reader.read(), abortPromise])
+                : reader.read());
+            if (signal?.aborted)
+                throw abortReason(signal);
+            if (result.done)
+                return Buffer.concat(chunks, totalSize);
+            totalSize += result.value.byteLength;
+            if (totalSize > maxSizeBytes) {
+                const error = new ResponseBodyTooLargeError(url, totalSize, maxSizeBytes);
+                await reader.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            chunks.push(result.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        if (signal && abortListener)
+            signal.removeEventListener('abort', abortListener);
+        reader.releaseLock();
+    }
+}
+export async function readResponseBody(options) {
+    return (await readResponseBodyAsBuffer(options)).toString('utf8');
+}

package/dist/http-link-pagination.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export declare function nextPageUrlFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL): URL | null;
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export declare function nextPageCursorFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL, cursorParameter?: string): string | null;
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export declare function validatePaginationRequestUrl(requestUrl: string | URL): URL;

package/dist/http-link-pagination.mjs

@@ -0,0 +1,141 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export function nextPageUrlFromLinkHeader(linkHeader, requestUrl) {
+    const baseUrl = validatePaginationRequestUrl(requestUrl);
+    if (linkHeader == null)
+        return null;
+    const links = parseLinkHeader(linkHeader);
+    if (!links)
+        return null;
+    const nextLinks = links.filter((link) => link.relations.includes('next'));
+    if (nextLinks.length !== 1)
+        return null;
+    let nextUrl;
+    try {
+        nextUrl = new URL(nextLinks[0].target, baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (nextUrl.origin !== baseUrl.origin ||
+        nextUrl.username !== '' ||
+        nextUrl.password !== '' ||
+        nextUrl.hash !== '') {
+        return null;
+    }
+    return nextUrl;
+}
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export function nextPageCursorFromLinkHeader(linkHeader, requestUrl, cursorParameter = 'page') {
+    const nextUrl = nextPageUrlFromLinkHeader(linkHeader, requestUrl);
+    if (!nextUrl)
+        return null;
+    const values = nextUrl.searchParams.getAll(cursorParameter);
+    return values.length === 1 && values[0] !== '' ? values[0] : null;
+}
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export function validatePaginationRequestUrl(requestUrl) {
+    let url;
+    try {
+        url = new URL(requestUrl);
+    }
+    catch {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '') {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    return url;
+}
+function parseLinkHeader(header) {
+    const links = [];
+    let index = 0;
+    while (index < header.length) {
+        index = skipWhitespace(header, index);
+        if (header[index] !== '<')
+            return null;
+        const targetEnd = header.indexOf('>', index + 1);
+        if (targetEnd === -1)
+            return null;
+        const target = header.slice(index + 1, targetEnd);
+        if (target === '')
+            return null;
+        index = targetEnd + 1;
+        const relations = [];
+        while (true) {
+            index = skipWhitespace(header, index);
+            if (index === header.length || header[index] === ',')
+                break;
+            if (header[index] !== ';')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const name = readToken(header, index);
+            if (!name)
+                return null;
+            index = name.end;
+            index = skipWhitespace(header, index);
+            if (header[index] !== '=')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const value = readParameterValue(header, index);
+            if (!value)
+                return null;
+            index = value.end;
+            if (name.value.toLowerCase() === 'rel') {
+                relations.push(...value.value.toLowerCase().split(/\s+/).filter(Boolean));
+            }
+        }
+        links.push({ target, relations });
+        if (index === header.length)
+            return links;
+        index += 1;
+        if (index === header.length)
+            return null;
+    }
+    return null;
+}
+function skipWhitespace(value, index) {
+    while (value[index] === ' ' || value[index] === '\t')
+        index += 1;
+    return index;
+}
+function readToken(value, index) {
+    const start = index;
+    while (index < value.length && isTokenCharacter(value[index]))
+        index += 1;
+    return index === start ? null : { value: value.slice(start, index), end: index };
+}
+function isTokenCharacter(value) {
+    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]$/.test(value);
+}
+function readParameterValue(value, index) {
+    if (value[index] !== '"')
+        return readToken(value, index);
+    let parsed = '';
+    index += 1;
+    while (index < value.length) {
+        const character = value[index];
+        if (character === '"')
+            return { value: parsed, end: index + 1 };
+        if (character === '\\') {
+            const escaped = value[index + 1];
+            if (!escaped)
+                return null;
+            parsed += escaped;
+            index += 2;
+            continue;
+        }
+        parsed += character;
+        index += 1;
+    }
+    return null;
+}

package/dist/moderation.d.mts

@@ -0,0 +1,34 @@
+interface ReportTarget<TType extends string, TId> {
+    type: TType;
+    id: TId;
+}
+interface ReportDraft<TType extends string, TId, TReason extends string> {
+    target: ReportTarget<TType, TId>;
+    reason: TReason;
+    note: string | null;
+}
+export interface ReportInputConfig<TType extends string, TId, TReason extends string> {
+    targetTypes: readonly TType[];
+    reasons: readonly TReason[];
+    parseTargetId(value: string): TId | null;
+    maxNoteLength: number;
+    validate?(draft: ReportDraft<TType, TId, TReason>): void;
+}
+interface RawReportInput {
+    targetType?: unknown;
+    targetId?: unknown;
+    reason?: unknown;
+    note?: unknown;
+}
+export interface ReportInputParser<TType extends string, TId, TReason extends string> {
+    parse(raw: RawReportInput): ReportDraft<TType, TId, TReason>;
+    readonly targetTypes: readonly TType[];
+    readonly reasons: readonly TReason[];
+}
+export type ReportValidationCode = 'invalid_target_type' | 'invalid_target_identifier' | 'invalid_reason' | 'invalid_note' | 'note_too_long';
+export declare class ReportValidationError extends Error {
+    readonly code: ReportValidationCode;
+    constructor(code: ReportValidationCode, message: string);
+}
+export declare function createReportInputParser<TType extends string, TId, TReason extends string>(config: ReportInputConfig<TType, TId, TReason>): ReportInputParser<TType, TId, TReason>;
+export {};

package/dist/moderation.mjs

@@ -0,0 +1,49 @@
+export class ReportValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ReportValidationError';
+        this.code = code;
+    }
+}
+export function createReportInputParser(config) {
+    const targetTypes = readonlyCatalog(config.targetTypes, 'targetTypes');
+    const reasons = readonlyCatalog(config.reasons, 'reasons');
+    if (!Number.isSafeInteger(config.maxNoteLength) || config.maxNoteLength < 0)
+        throw new TypeError('maxNoteLength must be a non-negative safe integer');
+    return {
+        targetTypes,
+        reasons,
+        parse(raw) {
+            const targetType = enumValue(raw.targetType, targetTypes, 'invalid_target_type', 'target type');
+            if (typeof raw.targetId !== 'string')
+                invalid('invalid_target_identifier', 'target identifier');
+            const targetId = config.parseTargetId(raw.targetId);
+            if (targetId === null)
+                invalid('invalid_target_identifier', 'target identifier');
+            const reason = enumValue(raw.reason, reasons, 'invalid_reason', 'reason');
+            if (raw.note !== undefined && raw.note !== null && typeof raw.note !== 'string')
+                invalid('invalid_note', 'note');
+            if (typeof raw.note === 'string' && raw.note.length > config.maxNoteLength)
+                throw new ReportValidationError('note_too_long', 'Note is too long');
+            const note = typeof raw.note === 'string' ? raw.note.trim() || null : null;
+            const draft = { target: { type: targetType, id: targetId }, reason, note };
+            config.validate?.(draft);
+            return draft;
+        },
+    };
+}
+function readonlyCatalog(values, name) {
+    if (values.length === 0 ||
+        values.some((value) => typeof value !== 'string' || value.length === 0))
+        throw new TypeError(`${name} must contain non-empty strings`);
+    return Object.freeze([...new Set(values)]);
+}
+function enumValue(value, catalog, code, name) {
+    if (typeof value !== 'string' || !catalog.includes(value))
+        invalid(code, name);
+    return value;
+}
+function invalid(code, name) {
+    throw new ReportValidationError(code, `Invalid ${name}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -130,6 +130,11 @@
       "import": "./dist/validation.mjs",
       "default": "./dist/validation.mjs"
     },
+    "./moderation": {
+      "types": "./dist/moderation.d.mts",
+      "import": "./dist/moderation.mjs",
+      "default": "./dist/moderation.mjs"
+    },
     "./async": {
       "types": "./dist/async.d.mts",
       "import": "./dist/async.mjs",
@@ -154,6 +159,16 @@
       "types": "./dist/fetch-ports.d.mts",
       "import": "./dist/fetch-ports.mjs",
       "default": "./dist/fetch-ports.mjs"
+    },
+    "./http-body": {
+      "types": "./dist/http-body.d.mts",
+      "import": "./dist/http-body.mjs",
+      "default": "./dist/http-body.mjs"
+    },
+    "./http-link-pagination": {
+      "types": "./dist/http-link-pagination.d.mts",
+      "import": "./dist/http-link-pagination.mjs",
+      "default": "./dist/http-link-pagination.mjs"
     }
   },
   "publishConfig": {