@vouchington/utils 0.5.3 → 0.6.0

package/README.md

@@ -29,19 +29,25 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   `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`.
+- `url-signing`: Node-only HMAC SHA-256 path signing (`signPathWithKey`, `signPath`,
+  `verifyPathSignature` with rotation, `signExpiringPath`/`verifyExpiringPath` with an injectable
+  clock), `parseSigningKeys`, `buildSignedProxyUrl` (caller-owned origin, route prefix, query, and
+  skip predicate), `createProtectedHostPolicy`, `matchRouteSegment`, and `authorizeDependencyStates`.
+  Prefixes, hosts, and keys are injected; verification fails closed with no keys unless
+  `allowUnsignedWhenNoKeys` is set.
 - `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. `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
+- `env-contract`: `groupEnvContracts()`, `normalizeEnvContractGroups()`, and `envContractManifest()` 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`.
+- `content-identity-cache`: `ContentAndIdentityCache` memoizes by object identity (WeakMap fast
+  path) with a content-key fallback; the content key is a thunk and entries are never evicted.
 - `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.
@@ -68,6 +74,11 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 - `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.
+- `api-errors`: the house JSON error envelope (`message`, optional `code`, `request_id`, `stack`),
+  status/message/code extraction helpers, and `buildApiErrorEnvelope`, which redacts 5xx details
+  unless the caller sets `exposeDetails`. Callers own serialization, logging, and environment policy.
+- `api-response-contract`: identity markers (`apiResponse`, `apiRequest`, `apiQuery`, ...) and
+  response-variant types read by a static contract extractor; no runtime effect.
 - `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
@@ -85,9 +96,12 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   descriptors. Catalog segments cannot contain dots because dots delimit nested keys. Plural values
   and configured number parameters must be finite numbers; callers own catalog content, locale
   choice, and number formatting.
-- `observability`: SDK-free URL, request, event, and span scrubbing plus a bounded spike-window
-  tracker. Callers provide credential headers and environment or spike policy; this package has no
-  product defaults.
+- `observability`: SDK-free (structural types only) URL, request, breadcrumb, event, and span
+  scrubbing plus a bounded spike-window tracker. All scrubbers are copy-on-write: unchanged input is
+  returned by identity. Callers provide `credentialHeaders`, an optional `redactUrl` hook (applied
+  after query and fragment stripping, for path-borne credentials), and an opt-in `dropRequestBody`.
+  URL-only and credential-only passes are exported separately, and `composeBeforeSend` accepts
+  either `ScrubOptions` or a final scrubber function. This package has no product defaults.
 
 ```ts
 const money = createMoneyCatalog([{ code: 'credit', minorUnitExponent: 2 }] as const, 6)

package/dist/api-errors.d.mts

@@ -0,0 +1,29 @@
+/** House JSON error envelope. `code`, `request_id`, and `stack` are omitted when absent. */
+export interface ApiErrorEnvelope {
+    readonly message: string;
+    readonly code?: string;
+    readonly request_id?: string;
+    readonly stack?: string;
+}
+export interface BuildApiErrorEnvelopeOptions {
+    /** Request correlation id echoed as `request_id`. */
+    readonly requestId?: string | null;
+    /** When false, 5xx errors are redacted to the status text and stacks are omitted. */
+    readonly exposeDetails: boolean;
+}
+export declare function getErrorStatus(error: unknown): number;
+/** Stamps `status` on 5xx errors so loggers and reporters classify them consistently. */
+export declare function normalizeErrorForLogging(error: Error): Error;
+export declare function getErrorResponseMessage(error: unknown, status: number): string;
+export declare function getErrorResponseCode(error: unknown, status: number): string | undefined;
+export declare function getErrorResponseStack(error: unknown): string | undefined;
+export declare function getStatusMessage(status: number): string;
+/**
+ * Builds the house error envelope. With `exposeDetails: false`, 5xx errors collapse to the HTTP
+ * status text with code `INTERNAL_ERROR` and never leak messages or stacks; 4xx messages and
+ * codes are still returned. Callers own serialization, logging, and environment policy.
+ */
+export declare function buildApiErrorEnvelope(error: unknown, options: BuildApiErrorEnvelopeOptions): {
+    readonly status: number;
+    readonly body: ApiErrorEnvelope;
+};

package/dist/api-errors.mjs

@@ -0,0 +1,80 @@
+import { STATUS_CODES } from 'node:http';
+export function getErrorStatus(error) {
+    if (!isObjectLike(error))
+        return 500;
+    return getValidHttpStatus(error.status) ?? getValidHttpStatus(error.statusCode) ?? 500;
+}
+/** Stamps `status` on 5xx errors so loggers and reporters classify them consistently. */
+export function normalizeErrorForLogging(error) {
+    const status = getErrorStatus(error);
+    if (status >= 500)
+        Object.assign(error, { status });
+    return error;
+}
+export function getErrorResponseMessage(error, status) {
+    if (error instanceof Error)
+        return error.message;
+    if (isObjectLike(error) && error.message !== undefined && error.message !== null) {
+        return safeString(error.message) ?? getStatusMessage(status);
+    }
+    if (isObjectLike(error) || error === null || error === undefined)
+        return getStatusMessage(status);
+    // Only primitives reach here, and String() cannot throw for them.
+    return String(error);
+}
+export function getErrorResponseCode(error, status) {
+    if (isObjectLike(error) && typeof error.code === 'string')
+        return error.code;
+    return status >= 500 ? 'INTERNAL_ERROR' : undefined;
+}
+export function getErrorResponseStack(error) {
+    if (isObjectLike(error) && typeof error.stack === 'string')
+        return error.stack;
+    return undefined;
+}
+export function getStatusMessage(status) {
+    return STATUS_CODES[status] ?? 'Internal Server Error';
+}
+/**
+ * Builds the house error envelope. With `exposeDetails: false`, 5xx errors collapse to the HTTP
+ * status text with code `INTERNAL_ERROR` and never leak messages or stacks; 4xx messages and
+ * codes are still returned. Callers own serialization, logging, and environment policy.
+ */
+export function buildApiErrorEnvelope(error, options) {
+    const status = getErrorStatus(error);
+    const requestId = options.requestId ? { request_id: options.requestId } : {};
+    if (!options.exposeDetails && status >= 500) {
+        return {
+            status,
+            body: { message: getStatusMessage(status), code: 'INTERNAL_ERROR', ...requestId },
+        };
+    }
+    const code = getErrorResponseCode(error, status);
+    const stack = options.exposeDetails ? getErrorResponseStack(error) : undefined;
+    return {
+        status,
+        body: {
+            message: getErrorResponseMessage(error, status),
+            ...(code ? { code } : {}),
+            ...requestId,
+            ...(stack ? { stack } : {}),
+        },
+    };
+}
+function getValidHttpStatus(status) {
+    if (typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599) {
+        return status;
+    }
+    return undefined;
+}
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/api-response-contract.d.mts

@@ -0,0 +1,62 @@
+/** Compiler-discovered variants carried by an opaque response without reading its body. */
+export type ApiHttpResponseVariant = {
+    status: number;
+    bodyKind: 'content';
+    mediaType: string;
+    body: unknown;
+} | {
+    status: number;
+    bodyKind: 'none';
+};
+export type ApiHttpResponse<TVariants extends ApiHttpResponseVariant> = Response & {
+    readonly apiHttpResponseVariants?: TVariants;
+};
+/** Adds JSON Schema array constraints to a statically extracted API request contract. */
+export type ApiArrayContract<TItem, _TMinItems extends number, _TMaxItems extends number, _TUniqueItems extends boolean> = TItem[];
+export interface ApiHeader {
+    description?: string;
+    format?: 'uuid';
+    required?: boolean;
+    type: 'integer' | 'string';
+}
+export interface ApiHeaderContract {
+    request?: Readonly<Record<string, ApiHeader>>;
+    responses?: Readonly<Record<number, {
+        description?: string;
+        errors?: readonly {
+            code: string;
+            message: string;
+        }[];
+        headers?: Readonly<Record<string, ApiHeader>>;
+    }>>;
+}
+/** A named event and its canonical payload, before SSE wire framing. */
+export interface ApiSseEvent<TName extends string = string, TData = unknown> {
+    event: TName;
+    data: TData;
+}
+/** Marks an HTTP response body as a shared API fixture contract. */
+export declare function apiResponse<const TKey extends string, TBody>(_key: TKey, body: TBody): TBody;
+/** Marks a request body as a shared API fixture contract. */
+export declare function apiRequest<const TKey extends string, TBody>(_key: TKey, body: TBody): TBody;
+/** Marks a fixture-backed response that intentionally has no response body. */
+export declare function apiNoContent<const TKey extends string>(_key: TKey): void;
+/** Documents a helper-emitted fixed-status bodyless response for OpenAPI discovery only. */
+export declare function apiOpenApiNoContent<const TKey extends string>(_key: TKey, _status: number): void;
+/** Documents a fixed-media raw response for OpenAPI discovery without changing the payload. */
+export declare function apiOpenApiRawResponse<const TKey extends string, TBody>(_key: TKey, _mediaType: string, body: TBody): TBody;
+/** Marks a request schema without constructing a runtime body. */
+export declare function apiRequestContract<const TKey extends string, TBody>(_key: TKey): TBody | undefined;
+/** Marks a route that intentionally reads no meaningful request body. */
+export declare function apiNoRequestBody<const TKey extends string>(_key: TKey): void;
+/**
+ * Marks the query contract for one operation. Sources are opaque here; applications that need
+ * compile-time carrier validation re-declare this with their own constrained signature.
+ */
+export declare function apiQuery<const TKey extends string, const TSources extends readonly unknown[]>(_key: TKey, ..._sources: TSources): void;
+/** Marks request and response headers for OpenAPI discovery (documentation only). */
+export declare function apiHeaders<const TKey extends string>(_key: TKey, _contract: ApiHeaderContract): void;
+/** Formats an SSE frame and exposes its payload to the compiler. */
+export declare function apiSseFrame<const TKey extends string, const TEvent extends ApiSseEvent>(_key: TKey, event: TEvent): string;
+/** Annotates SDK response variants while preserving status, headers, bytes and body ownership. */
+export declare function apiOpenApiHttpResponse<const TKey extends string, TVariants extends ApiHttpResponseVariant>(_key: TKey, response: ApiHttpResponse<TVariants>): ApiHttpResponse<TVariants>;

package/dist/api-response-contract.mjs

@@ -0,0 +1,51 @@
+/*
+ * Identity markers read by a static (TypeScript compiler) contract extractor. None of them change
+ * the runtime payload; the string key names the operation in the extracted contract.
+ */
+/** Marks an HTTP response body as a shared API fixture contract. */
+export function apiResponse(_key, body) {
+    return body;
+}
+/** Marks a request body as a shared API fixture contract. */
+export function apiRequest(_key, body) {
+    return body;
+}
+/** Marks a fixture-backed response that intentionally has no response body. */
+export function apiNoContent(_key) {
+    return undefined;
+}
+/** Documents a helper-emitted fixed-status bodyless response for OpenAPI discovery only. */
+export function apiOpenApiNoContent(_key, _status) {
+    return undefined;
+}
+/** Documents a fixed-media raw response for OpenAPI discovery without changing the payload. */
+export function apiOpenApiRawResponse(_key, _mediaType, body) {
+    return body;
+}
+/** Marks a request schema without constructing a runtime body. */
+export function apiRequestContract(_key) {
+    return undefined;
+}
+/** Marks a route that intentionally reads no meaningful request body. */
+export function apiNoRequestBody(_key) {
+    return undefined;
+}
+/**
+ * Marks the query contract for one operation. Sources are opaque here; applications that need
+ * compile-time carrier validation re-declare this with their own constrained signature.
+ */
+export function apiQuery(_key, ..._sources) {
+    return undefined;
+}
+/** Marks request and response headers for OpenAPI discovery (documentation only). */
+export function apiHeaders(_key, _contract) {
+    return undefined;
+}
+/** Formats an SSE frame and exposes its payload to the compiler. */
+export function apiSseFrame(_key, event) {
+    return `event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`;
+}
+/** Annotates SDK response variants while preserving status, headers, bytes and body ownership. */
+export function apiOpenApiHttpResponse(_key, response) {
+    return response;
+}

package/dist/content-identity-cache.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Two-level memoizing cache: a WeakMap fast path keyed on an object's identity (for example a
+ * binding stable for a process or isolate lifetime) over a Map keyed on a secondary value, falling
+ * through to a content-keyed Map. `getContentKey` is a thunk so an identity hit skips deriving it.
+ * Entries are never evicted, so callers must pass a small, bounded set of key-material combinations.
+ */
+export declare class ContentAndIdentityCache<TIdentityKey extends object, TSubKey, TValue> {
+    private readonly byContent;
+    private readonly byIdentity;
+    getOrCompute(identityKey: TIdentityKey | undefined, subKey: TSubKey, getContentKey: () => string, compute: () => TValue): TValue;
+}

package/dist/content-identity-cache.mjs

@@ -0,0 +1,26 @@
+/**
+ * Two-level memoizing cache: a WeakMap fast path keyed on an object's identity (for example a
+ * binding stable for a process or isolate lifetime) over a Map keyed on a secondary value, falling
+ * through to a content-keyed Map. `getContentKey` is a thunk so an identity hit skips deriving it.
+ * Entries are never evicted, so callers must pass a small, bounded set of key-material combinations.
+ */
+export class ContentAndIdentityCache {
+    byContent = new Map();
+    byIdentity = new WeakMap();
+    getOrCompute(identityKey, subKey, getContentKey, compute) {
+        const identityMap = identityKey && this.byIdentity.get(identityKey);
+        if (identityMap?.has(subKey))
+            return identityMap.get(subKey);
+        const contentKey = getContentKey();
+        const value = this.byContent.has(contentKey)
+            ? this.byContent.get(contentKey)
+            : compute();
+        this.byContent.set(contentKey, value);
+        if (identityKey) {
+            const map = identityMap || new Map();
+            map.set(subKey, value);
+            this.byIdentity.set(identityKey, map);
+        }
+        return value;
+    }
+}

package/dist/env-contract.d.mts

@@ -17,3 +17,11 @@ export declare function normalizeEnvContractGroups<Source extends string, Surfac
 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[];
+export type EnvContractManifestEntry<Source extends string = string, Surface extends string = string> = {
+    name: string;
+    contractKey: string;
+    sourceOfTruth: Source;
+    sensitivity: EnvVarSensitivity;
+    runtimeSurfaces: Surface[];
+};
+export declare function envContractManifest<Source extends string, Surface extends string>(contract: readonly EnvVarContract<Source, Surface>[]): EnvContractManifestEntry<Source, Surface>[];

package/dist/env-contract.mjs

@@ -43,3 +43,12 @@ export function envNamesBySensitivity(contract, sensitivity) {
         ...new Set(contract.filter((entry) => entry.sensitivity === sensitivity).map((entry) => entry.name)),
     ].toSorted();
 }
+export function envContractManifest(contract) {
+    return contract.map((entry) => ({
+        name: entry.name,
+        contractKey: entry.key,
+        sourceOfTruth: entry.sourceOfTruth,
+        sensitivity: entry.sensitivity,
+        runtimeSurfaces: [...entry.surfaces],
+    }));
+}

package/dist/observability-body.d.mts

@@ -0,0 +1,5 @@
+export declare const REQUEST_BODY_SPAN_ATTRIBUTE = "http.request.body.data";
+/** Drop the request body attribute from span or breadcrumb data. */
+export declare function dropSpanRequestBody<T extends Record<string, unknown>>(data: T): T;
+/** Drop the body (`data`) from an event request. */
+export declare function dropRequestBody<T extends object>(request: T | undefined): T | undefined;

package/dist/observability-body.mjs

@@ -0,0 +1,10 @@
+import { DROP, transformRecord } from './observability-records.mjs';
+export const REQUEST_BODY_SPAN_ATTRIBUTE = 'http.request.body.data';
+/** Drop the request body attribute from span or breadcrumb data. */
+export function dropSpanRequestBody(data) {
+    return transformRecord(data, (key, value) => (key === REQUEST_BODY_SPAN_ATTRIBUTE ? DROP : value));
+}
+/** Drop the body (`data`) from an event request. */
+export function dropRequestBody(request) {
+    return request && transformRecord(request, (key, value) => (key === 'data' ? DROP : value));
+}

package/dist/observability-credentials.d.mts

@@ -0,0 +1,6 @@
+/** Replace the values of credential headers (case-insensitive exact names). */
+export declare function scrubCredentialHeaders(headers: Record<string, unknown>, credentialHeaders: readonly string[]): Record<string, unknown>;
+/** Replace credential header span attributes (hyphen or underscore spelling) and cookie attributes. */
+export declare function scrubSpanCredentialAttributes<T extends Record<string, unknown>>(data: T, credentialHeaders: readonly string[]): T;
+/** Replace credential headers and every cookie value on an event request. */
+export declare function scrubRequestCredentialFields<T extends object>(request: T | undefined, credentialHeaders: readonly string[]): T | undefined;

package/dist/observability-credentials.mjs

@@ -0,0 +1,30 @@
+import { SENSITIVE_VALUE, isRecord, transformRecord } from './observability-records.mjs';
+const COOKIE_ATTRIBUTE_PREFIX = 'http.request.header.cookie.';
+function lowerSet(names) {
+    return new Set(names.map((name) => name.toLowerCase()));
+}
+/** Replace the values of credential headers (case-insensitive exact names). */
+export function scrubCredentialHeaders(headers, credentialHeaders) {
+    const credentials = lowerSet(credentialHeaders);
+    return transformRecord(headers, (name, value) => credentials.has(name.toLowerCase()) ? SENSITIVE_VALUE : value);
+}
+/** Replace credential header span attributes (hyphen or underscore spelling) and cookie attributes. */
+export function scrubSpanCredentialAttributes(data, credentialHeaders) {
+    const keys = new Set([...lowerSet(credentialHeaders)].flatMap((name) => [
+        `http.request.header.${name}`,
+        `http.request.header.${name.replaceAll('-', '_')}`,
+    ]));
+    return transformRecord(data, (key, value) => keys.has(key) || key.startsWith(COOKIE_ATTRIBUTE_PREFIX) ? SENSITIVE_VALUE : value);
+}
+/** Replace credential headers and every cookie value on an event request. */
+export function scrubRequestCredentialFields(request, credentialHeaders) {
+    if (!request)
+        return request;
+    return transformRecord(request, (key, value) => {
+        if (key === 'headers' && isRecord(value))
+            return scrubCredentialHeaders(value, credentialHeaders);
+        return key === 'cookies' && isRecord(value)
+            ? transformRecord(value, () => SENSITIVE_VALUE)
+            : value;
+    });
+}

package/dist/observability-event.d.mts

@@ -0,0 +1,31 @@
+import { type UrlScrubOptions } from './observability-url.mts';
+export interface ScrubOptions extends UrlScrubOptions {
+    /** Header names (case-insensitive) whose values are replaced with the filtered marker. */
+    credentialHeaders: readonly string[];
+    /** Also drop `request.data` and the `http.request.body.data` attribute. Defaults to false. */
+    dropRequestBody?: boolean;
+}
+/** Structural subset of an SDK event; no SDK type is imported. */
+export interface ObservableEvent {
+    [key: string]: unknown;
+    breadcrumbs?: Array<{
+        data?: Record<string, unknown>;
+    }>;
+    request?: object;
+}
+export declare function scrubHeaders(headers: Record<string, unknown>, credentialHeaders: readonly string[], redactUrl?: (url: string) => string): Record<string, unknown>;
+export declare function scrubSpanAttributes<T extends Record<string, unknown>>(data: T, options: ScrubOptions): T;
+export declare function scrubRequest<T extends object>(request: T | undefined, options: ScrubOptions): T | undefined;
+/** Scrub each breadcrumb's `data`; the input array is returned when nothing changed. */
+export declare function scrubBreadcrumbs<T extends {
+    data?: Record<string, unknown>;
+}>(breadcrumbs: T[] | undefined, options: ScrubOptions): T[] | undefined;
+/** Scrub an event's request and breadcrumbs; the input event is returned when nothing changed. */
+export declare function scrubEvent<T extends ObservableEvent>(event: T, options: ScrubOptions): T;
+type BeforeSendResult<T> = T | null | PromiseLike<T | null>;
+/**
+ * Wrap an SDK `beforeSend` so its result (sync or async, including foreign-realm thenables) always
+ * passes through a final scrubber. Pass `ScrubOptions` to use {@link scrubEvent}, or a function.
+ */
+export declare function composeBeforeSend<T extends ObservableEvent, THint>(beforeSend: ((event: T, hint: THint) => BeforeSendResult<T>) | undefined, scrubber: ScrubOptions | ((event: T) => T)): (event: T, hint: THint) => BeforeSendResult<T>;
+export {};

package/dist/observability-event.mjs

@@ -0,0 +1,59 @@
+import { dropRequestBody, dropSpanRequestBody } from './observability-body.mjs';
+import { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mjs';
+import { scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, } from './observability-url.mjs';
+export function scrubHeaders(headers, credentialHeaders, redactUrl) {
+    const urlScrubbed = scrubHeaderUrls(headers, redactUrl ? { redactUrl } : {});
+    return scrubCredentialHeaders(urlScrubbed, credentialHeaders);
+}
+export function scrubSpanAttributes(data, options) {
+    const scrubbed = scrubSpanCredentialAttributes(scrubSpanUrlAttributes(data, options), options.credentialHeaders);
+    return options.dropRequestBody ? dropSpanRequestBody(scrubbed) : scrubbed;
+}
+export function scrubRequest(request, options) {
+    const scrubbed = scrubRequestCredentialFields(scrubRequestUrlFields(request, options), options.credentialHeaders);
+    return options.dropRequestBody ? dropRequestBody(scrubbed) : scrubbed;
+}
+/** Scrub each breadcrumb's `data`; the input array is returned when nothing changed. */
+export function scrubBreadcrumbs(breadcrumbs, options) {
+    if (!breadcrumbs?.length)
+        return breadcrumbs;
+    const result = breadcrumbs.map((breadcrumb) => {
+        if (typeof breadcrumb.data !== 'object' || breadcrumb.data === null)
+            return breadcrumb;
+        const data = scrubSpanAttributes(breadcrumb.data, options);
+        return data === breadcrumb.data ? breadcrumb : { ...breadcrumb, data };
+    });
+    return result.some((breadcrumb, index) => breadcrumb !== breadcrumbs[index])
+        ? result
+        : breadcrumbs;
+}
+/** Scrub an event's request and breadcrumbs; the input event is returned when nothing changed. */
+export function scrubEvent(event, options) {
+    const request = scrubRequest(event.request, options);
+    const breadcrumbs = scrubBreadcrumbs(event.breadcrumbs, options);
+    if (request === event.request && breadcrumbs === event.breadcrumbs)
+        return event;
+    return {
+        ...event,
+        ...(request === event.request ? {} : { request }),
+        ...(breadcrumbs === event.breadcrumbs ? {} : { breadcrumbs }),
+    };
+}
+function isPromiseLike(value) {
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function'))
+        return false;
+    return typeof value.then === 'function';
+}
+/**
+ * Wrap an SDK `beforeSend` so its result (sync or async, including foreign-realm thenables) always
+ * passes through a final scrubber. Pass `ScrubOptions` to use {@link scrubEvent}, or a function.
+ */
+export function composeBeforeSend(beforeSend, scrubber) {
+    const finalScrub = typeof scrubber === 'function' ? scrubber : (e) => scrubEvent(e, scrubber);
+    return (event, hint) => {
+        const result = beforeSend ? beforeSend(event, hint) : event;
+        if (isPromiseLike(result))
+            return Promise.resolve(result).then((next) => (next === null ? null : finalScrub(next)));
+        return result === null ? null : finalScrub(result);
+    };
+}

package/dist/observability-records.d.mts

@@ -0,0 +1,9 @@
+export declare const SENSITIVE_VALUE = "[Filtered]";
+/** Return from a {@link transformRecord} callback to omit the entry. */
+export declare const DROP: unique symbol;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Copy-on-write entry mapping: returns the input when no entry changed. Rebuilds with
+ * `Object.fromEntries` so keys such as `__proto__` stay own data properties.
+ */
+export declare function transformRecord<T extends object>(record: T, transform: (key: string, value: unknown) => unknown): T;

package/dist/observability-records.mjs

@@ -0,0 +1,26 @@
+export const SENSITIVE_VALUE = '[Filtered]';
+/** Return from a {@link transformRecord} callback to omit the entry. */
+export const DROP = Symbol('drop');
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Copy-on-write entry mapping: returns the input when no entry changed. Rebuilds with
+ * `Object.fromEntries` so keys such as `__proto__` stay own data properties.
+ */
+export function transformRecord(record, transform) {
+    let changed = false;
+    const entries = [];
+    for (const [key, value] of Object.entries(record)) {
+        const next = transform(key, value);
+        if (next === DROP) {
+            changed = true;
+        }
+        else {
+            if (!Object.is(next, value))
+                changed = true;
+            entries.push([key, next]);
+        }
+    }
+    return changed ? Object.fromEntries(entries) : record;
+}

package/dist/observability-url.d.mts

@@ -0,0 +1,19 @@
+export interface UrlScrubOptions {
+    /** Extra caller-owned redaction applied after the query string and fragment are stripped. */
+    redactUrl?: (url: string) => string;
+}
+/** Span, breadcrumb, and request attribute keys whose string value is a URL. */
+export declare const URL_ATTRIBUTE_KEYS: readonly string[];
+/** Attribute keys whose value is only a query string or fragment; they are dropped. */
+export declare const URL_COMPONENT_ATTRIBUTE_KEYS: readonly string[];
+/** Every attribute key the URL scrubber rewrites or drops. */
+export declare const SCRUBBED_URL_ATTRIBUTE_KEYS: readonly string[];
+export declare function stripUrlQueryAndFragment(value: string): string;
+/** Scrub a string or each string item of an array; other values and clean arrays pass through. */
+export declare function scrubUrlValue(value: unknown, options?: UrlScrubOptions): unknown;
+/** Strip query strings and fragments from URL attributes and drop query/fragment-only keys. */
+export declare function scrubSpanUrlAttributes<T extends Record<string, unknown>>(data: T, options?: UrlScrubOptions): T;
+/** Scrub the `referer`/`referrer` header values of a headers record. */
+export declare function scrubHeaderUrls(headers: Record<string, unknown>, options?: UrlScrubOptions): Record<string, unknown>;
+/** Drop `query_string`, strip `url`, and scrub URL-bearing headers on an event request. */
+export declare function scrubRequestUrlFields<T extends object>(request: T | undefined, options?: UrlScrubOptions): T | undefined;

package/dist/observability-url.mjs

@@ -0,0 +1,69 @@
+import { DROP, isRecord, transformRecord } from './observability-records.mjs';
+/** Span, breadcrumb, and request attribute keys whose string value is a URL. */
+export const URL_ATTRIBUTE_KEYS = Object.freeze([
+    'url',
+    'url.full',
+    'http.url',
+    'http.target',
+    'http.request.header.referer',
+    'http.request.header.referrer',
+]);
+/** Attribute keys whose value is only a query string or fragment; they are dropped. */
+export const URL_COMPONENT_ATTRIBUTE_KEYS = Object.freeze([
+    'url.query',
+    'http.query',
+    'url.fragment',
+    'http.fragment',
+]);
+/** Every attribute key the URL scrubber rewrites or drops. */
+export const SCRUBBED_URL_ATTRIBUTE_KEYS = Object.freeze([
+    ...URL_ATTRIBUTE_KEYS,
+    ...URL_COMPONENT_ATTRIBUTE_KEYS,
+]);
+export function stripUrlQueryAndFragment(value) {
+    const match = /[?#]/.exec(value);
+    return match ? value.slice(0, match.index) : value;
+}
+function scrubUrl(value, options) {
+    const stripped = stripUrlQueryAndFragment(value);
+    return options.redactUrl ? options.redactUrl(stripped) : stripped;
+}
+/** Scrub a string or each string item of an array; other values and clean arrays pass through. */
+export function scrubUrlValue(value, options = {}) {
+    if (typeof value === 'string')
+        return scrubUrl(value, options);
+    if (!Array.isArray(value))
+        return value;
+    const items = value.map((item) => typeof item === 'string' ? scrubUrl(item, options) : item);
+    return items.some((item, index) => !Object.is(item, value[index])) ? items : value;
+}
+function isUrlHeader(name) {
+    const lower = name.toLowerCase();
+    return lower === 'referer' || lower === 'referrer';
+}
+/** Strip query strings and fragments from URL attributes and drop query/fragment-only keys. */
+export function scrubSpanUrlAttributes(data, options = {}) {
+    return transformRecord(data, (key, value) => {
+        if (URL_COMPONENT_ATTRIBUTE_KEYS.includes(key))
+            return DROP;
+        return URL_ATTRIBUTE_KEYS.includes(key) && typeof value === 'string'
+            ? scrubUrl(value, options)
+            : value;
+    });
+}
+/** Scrub the `referer`/`referrer` header values of a headers record. */
+export function scrubHeaderUrls(headers, options = {}) {
+    return transformRecord(headers, (name, value) => isUrlHeader(name) ? scrubUrlValue(value, options) : value);
+}
+/** Drop `query_string`, strip `url`, and scrub URL-bearing headers on an event request. */
+export function scrubRequestUrlFields(request, options = {}) {
+    if (!request)
+        return request;
+    return transformRecord(request, (key, value) => {
+        if (key === 'query_string')
+            return DROP;
+        if (key === 'url' && typeof value === 'string')
+            return scrubUrl(value, options);
+        return key === 'headers' && isRecord(value) ? scrubHeaderUrls(value, options) : value;
+    });
+}

package/dist/observability.d.mts

@@ -1,19 +1,8 @@
-export declare const SENSITIVE_VALUE = "[Filtered]";
+export { SENSITIVE_VALUE } from './observability-records.mts';
 export { createSpikeWindowTracker, type SpikeWindowTracker } from './spike-window.mts';
-export interface ScrubOptions {
-    credentialHeaders: readonly string[];
-}
-export interface ObservableEvent {
-    [key: string]: unknown;
-    breadcrumbs?: Array<{
-        data?: Record<string, unknown>;
-    }>;
-    request?: object;
-}
-export declare function stripUrlQueryAndFragment(value: string): string;
-export declare function scrubHeaders(headers: Record<string, unknown>, credentialHeaders: readonly string[]): Record<string, unknown>;
-export declare function scrubSpanAttributes<T extends Record<string, unknown>>(data: T, options: ScrubOptions): T;
-export declare function scrubEvent<T extends ObservableEvent>(event: T, options: ScrubOptions): T;
-export declare function composeBeforeSend<T extends ObservableEvent, THint>(beforeSend: ((event: T, hint: THint) => T | null | Promise<T | null>) | undefined, options: ScrubOptions): (event: T, hint: THint) => T | null | Promise<T | null>;
+export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, type ObservableEvent, type ScrubOptions, } from './observability-event.mts';
+export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mts';
+export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, type UrlScrubOptions, } from './observability-url.mts';
+export { REQUEST_BODY_SPAN_ATTRIBUTE, dropRequestBody, dropSpanRequestBody, } from './observability-body.mts';
 export declare function isAllowedEnvironment(value: string | undefined, allowed: readonly string[]): boolean;
 export declare function shouldReportSpike(count: number, threshold: number): boolean;

package/dist/observability.mjs

@@ -1,121 +1,12 @@
-export const SENSITIVE_VALUE = '[Filtered]';
+export { SENSITIVE_VALUE } from './observability-records.mjs';
 export { createSpikeWindowTracker } from './spike-window.mjs';
-const URL_ATTRIBUTES = [
-    'url',
-    'url.full',
-    'http.url',
-    'http.target',
-    'http.request.header.referer',
-    'http.request.header.referrer',
-];
-const URL_COMPONENT_ATTRIBUTES = ['url.query', 'http.query', 'url.fragment', 'http.fragment'];
-export function stripUrlQueryAndFragment(value) {
-    const match = /[?#]/.exec(value);
-    return match ? value.slice(0, match.index) : value;
-}
-export function scrubHeaders(headers, credentialHeaders) {
-    const credentials = new Set(credentialHeaders.map((name) => name.toLowerCase()));
-    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
-        name,
-        credentials.has(name.toLowerCase())
-            ? SENSITIVE_VALUE
-            : isUrlHeader(name)
-                ? scrubUrlHeaderValue(value)
-                : value,
-    ]));
-}
-export function scrubSpanAttributes(data, options) {
-    const credentialKeys = new Set(options.credentialHeaders.flatMap((name) => {
-        const lower = name.toLowerCase();
-        return [`http.request.header.${lower}`, `http.request.header.${lower.replaceAll('-', '_')}`];
-    }));
-    const result = Object.entries(data).flatMap(([key, value]) => {
-        if (URL_COMPONENT_ATTRIBUTES.includes(key))
-            return [];
-        if (credentialKeys.has(key) || key.startsWith('http.request.header.cookie.'))
-            return [[key, SENSITIVE_VALUE]];
-        return [
-            [
-                key,
-                URL_ATTRIBUTES.includes(key) && typeof value === 'string'
-                    ? stripUrlQueryAndFragment(value)
-                    : value,
-            ],
-        ];
-    });
-    const changed = result.length !== Object.keys(data).length || result.some(([key, value]) => data[key] !== value);
-    return (changed ? Object.fromEntries(result) : data);
-}
-export function scrubEvent(event, options) {
-    const request = scrubRequest(event.request, options);
-    const breadcrumbs = event.breadcrumbs?.map((breadcrumb) => breadcrumb.data
-        ? { ...breadcrumb, data: scrubSpanAttributes(breadcrumb.data, options) }
-        : breadcrumb);
-    const changed = request !== event.request ||
-        breadcrumbs?.some((breadcrumb, index) => breadcrumb !== event.breadcrumbs?.[index]);
-    return changed
-        ? {
-            ...event,
-            ...(request === event.request ? {} : { request }),
-            ...(breadcrumbs === event.breadcrumbs ? {} : { breadcrumbs }),
-        }
-        : event;
-}
-export function composeBeforeSend(beforeSend, options) {
-    return (event, hint) => {
-        const result = beforeSend ? beforeSend(event, hint) : event;
-        if (isPromiseLike(result))
-            return Promise.resolve(result).then((next) => next === null ? null : scrubEvent(next, options));
-        return result === null ? null : scrubEvent(result, options);
-    };
-}
-function isPromiseLike(value) {
-    return value !== null && typeof value.then === 'function';
-}
+export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, } from './observability-event.mjs';
+export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mjs';
+export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, } from './observability-url.mjs';
+export { REQUEST_BODY_SPAN_ATTRIBUTE, dropRequestBody, dropSpanRequestBody, } from './observability-body.mjs';
 export function isAllowedEnvironment(value, allowed) {
     return value !== undefined && allowed.includes(value);
 }
 export function shouldReportSpike(count, threshold) {
     return Number.isFinite(count) && Number.isFinite(threshold) && count >= threshold;
 }
-function scrubRequest(request, options) {
-    if (!request)
-        return request;
-    const fields = request;
-    const headers = isRecord(fields.headers)
-        ? scrubHeaders(fields.headers, options.credentialHeaders)
-        : fields.headers;
-    const cookies = isRecord(fields.cookies)
-        ? Object.fromEntries(Object.keys(fields.cookies).map((name) => [name, SENSITIVE_VALUE]))
-        : fields.cookies;
-    const result = Object.entries(fields).flatMap(([key, value]) => key === 'query_string'
-        ? []
-        : [
-            [
-                key,
-                key === 'url' && typeof value === 'string'
-                    ? stripUrlQueryAndFragment(value)
-                    : key === 'headers'
-                        ? headers
-                        : key === 'cookies'
-                            ? cookies
-                            : value,
-            ],
-        ]);
-    const changed = result.length !== Object.keys(fields).length ||
-        result.some(([key, value]) => fields[key] !== value);
-    return (changed ? Object.fromEntries(result) : request);
-}
-function isUrlHeader(name) {
-    return ['referer', 'referrer'].includes(name.toLowerCase());
-}
-function scrubUrlHeaderValue(value) {
-    if (typeof value === 'string')
-        return stripUrlQueryAndFragment(value);
-    return Array.isArray(value)
-        ? value.map((item) => (typeof item === 'string' ? stripUrlQueryAndFragment(item) : item))
-        : value;
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/dist/url-signing-hosts.d.mts

@@ -0,0 +1,21 @@
+export type DependencyAuthorization = 'allow' | 'withheld' | 'unknown';
+/** Empty manifests have no dependency bytes. Any withheld or unknown dependency denies delivery. */
+export declare function authorizeDependencyStates(states: readonly DependencyAuthorization[]): 'allow' | 'deny';
+export declare function normalizeHostname(hostname: string): string;
+/** Hostname of a URL string or a bare host. Returns undefined when empty or unparsable. */
+export declare function hostnameOf(value: string): string | undefined;
+/** Route matcher: `<prefix><one non-empty segment>`. Returns the segment, or undefined. */
+export declare function matchRouteSegment(pathname: string, prefix: string): string | undefined;
+export type ProtectedHostPolicy = {
+    hosts: () => string[];
+    isProtected: (url: URL, extraHosts?: readonly string[]) => boolean;
+    blockedHosts: () => {
+        exact: string[];
+        suffixes: string[];
+    };
+};
+/**
+ * Protected-host policy. Each entry (URL or bare host) protects the host and all subdomains.
+ * The caller supplies the host list; nothing is read from the environment.
+ */
+export declare function createProtectedHostPolicy(entries: readonly string[]): ProtectedHostPolicy;

package/dist/url-signing-hosts.mjs

@@ -0,0 +1,57 @@
+/** Empty manifests have no dependency bytes. Any withheld or unknown dependency denies delivery. */
+export function authorizeDependencyStates(states) {
+    return states.every((state) => state === 'allow') ? 'allow' : 'deny';
+}
+export function normalizeHostname(hostname) {
+    return hostname.replace(/\.$/, '').toLowerCase();
+}
+/** Hostname of a URL string or a bare host. Returns undefined when empty or unparsable. */
+export function hostnameOf(value) {
+    if (value.includes('://')) {
+        try {
+            return normalizeHostname(new URL(value).hostname);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const host = value.trim();
+    return host ? normalizeHostname(host) : undefined;
+}
+/** Route matcher: `<prefix><one non-empty segment>`. Returns the segment, or undefined. */
+export function matchRouteSegment(pathname, prefix) {
+    if (!pathname.startsWith(prefix))
+        return undefined;
+    const rest = pathname.slice(prefix.length);
+    return rest && !rest.includes('/') ? rest : undefined;
+}
+/**
+ * Protected-host policy. Each entry (URL or bare host) protects the host and all subdomains.
+ * The caller supplies the host list; nothing is read from the environment.
+ */
+export function createProtectedHostPolicy(entries) {
+    const collect = (extra = []) => {
+        const hosts = new Set();
+        for (const entry of [...entries, ...extra]) {
+            const host = hostnameOf(entry);
+            if (host)
+                hosts.add(host);
+        }
+        return hosts;
+    };
+    return {
+        hosts: () => [...collect()],
+        isProtected(url, extraHosts) {
+            const host = normalizeHostname(url.hostname);
+            for (const protectedHost of collect(extraHosts)) {
+                if (host === protectedHost || host.endsWith(`.${protectedHost}`))
+                    return true;
+            }
+            return false;
+        },
+        blockedHosts() {
+            const hosts = [...collect()];
+            return { exact: hosts, suffixes: hosts.map((host) => `.${host}`) };
+        },
+    };
+}

package/dist/url-signing-keys.d.mts

@@ -0,0 +1,23 @@
+export declare function signPathWithKey(path: string, keyHex: string): string;
+export declare function verifyPathWithKey(path: string, signature: string, keyHex: string): boolean;
+/**
+ * Parse a comma-separated list of hex keys. Entries are trimmed; empty entries and
+ * case-insensitive placeholder entries are skipped.
+ */
+export declare function parseSigningKeys(value: string | undefined, options?: {
+    placeholder?: string;
+}): string[];
+/** Sign with the first usable key. Returns '' when no key is usable. */
+export declare function signPath(path: string, keys: readonly string[]): string;
+export type VerifyPathOptions = {
+    /** Accept any signature when no keys are configured (dev mode). Defaults to false. */
+    allowUnsignedWhenNoKeys?: boolean;
+};
+/** Verify against every key (for rotation). Invalid keys never match. */
+export declare function verifyPathSignature(path: string, signature: string, keys: readonly string[], options?: VerifyPathOptions): boolean;
+/** Sign a path bound to an expiry (epoch milliseconds). Returns '' when no key is usable. */
+export declare function signExpiringPath(path: string, expiresAtMs: number, keys: readonly string[]): string;
+/** Verify an expiring signature. Fails closed for unsafe expiry values and expired links. */
+export declare function verifyExpiringPath(path: string, expiresAtMs: number, signature: string, keys: readonly string[], options?: {
+    now?: number;
+}): boolean;

package/dist/url-signing-keys.mjs

@@ -0,0 +1,65 @@
+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'));
+}
+/**
+ * Parse a comma-separated list of hex keys. Entries are trimmed; empty entries and
+ * case-insensitive placeholder entries are skipped.
+ */
+export function parseSigningKeys(value, options = {}) {
+    if (!value)
+        return [];
+    const placeholder = (options.placeholder ?? 'PLACEHOLDER').toUpperCase();
+    return value.split(',').flatMap((entry) => {
+        const key = entry.trim();
+        return key && key.toUpperCase() !== placeholder ? [key] : [];
+    });
+}
+/** Sign with the first usable key. Returns '' when no key is usable. */
+export function signPath(path, keys) {
+    for (const key of keys) {
+        try {
+            return signPathWithKey(path, key);
+        }
+        catch {
+            // Invalid key: try the next one.
+        }
+    }
+    return '';
+}
+/** Verify against every key (for rotation). Invalid keys never match. */
+export function verifyPathSignature(path, signature, keys, options = {}) {
+    if (keys.length === 0)
+        return options.allowUnsignedWhenNoKeys === true;
+    return keys.some((key) => {
+        try {
+            return verifyPathWithKey(path, signature, key);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function expiringPayload(path, expiresAtMs) {
+    return `${expiresAtMs}\n${path}`;
+}
+/** Sign a path bound to an expiry (epoch milliseconds). Returns '' when no key is usable. */
+export function signExpiringPath(path, expiresAtMs, keys) {
+    return signPath(expiringPayload(path, expiresAtMs), keys);
+}
+/** Verify an expiring signature. Fails closed for unsafe expiry values and expired links. */
+export function verifyExpiringPath(path, expiresAtMs, signature, keys, options = {}) {
+    if (!Number.isSafeInteger(expiresAtMs))
+        return false;
+    if ((options.now ?? Date.now()) > expiresAtMs)
+        return false;
+    return verifyPathSignature(expiringPayload(path, expiresAtMs), signature, keys);
+}

package/dist/url-signing-proxy.d.mts

@@ -0,0 +1,19 @@
+export type BuildSignedProxyUrlOptions = {
+    /** Origin that serves the proxy route. */
+    origin: string;
+    /** Route prefix; the base64url target is appended, e.g. `/proxy/v1/`. */
+    pathPrefix: string;
+    /** Ordered query parameters; undefined values are skipped. The signature is appended last. */
+    query?: Record<string, string | number | undefined>;
+    signingKeys: readonly string[];
+    /** Return true to leave a URL unproxied (first-party hosts, legacy routes, ...). */
+    skip?: (url: URL) => boolean;
+    /** Name of the signature query parameter. Defaults to `sig`. */
+    signatureParam?: string;
+};
+/**
+ * Build a signed proxy URL for an external http(s) URL. Returns null for empty, relative,
+ * protocol-relative, non-http(s), already-proxied, or caller-skipped URLs. When no key is usable
+ * the URL is returned without a signature.
+ */
+export declare function buildSignedProxyUrl(externalUrl: string, options: BuildSignedProxyUrlOptions): string | null;

package/dist/url-signing-proxy.mjs

@@ -0,0 +1,36 @@
+import { signPath } from './url-signing-keys.mjs';
+/**
+ * Build a signed proxy URL for an external http(s) URL. Returns null for empty, relative,
+ * protocol-relative, non-http(s), already-proxied, or caller-skipped URLs. When no key is usable
+ * the URL is returned without a signature.
+ */
+export function buildSignedProxyUrl(externalUrl, options) {
+    const value = externalUrl.trim();
+    if (!value || value.startsWith('//'))
+        return null;
+    let target;
+    try {
+        target = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:')
+        return null;
+    const origin = new URL(options.origin).origin;
+    if (target.origin === origin && target.pathname.startsWith(options.pathPrefix))
+        return null;
+    if (options.skip?.(target))
+        return null;
+    const path = `${options.pathPrefix}${Buffer.from(value, 'utf8').toString('base64url')}`;
+    const params = new URLSearchParams();
+    for (const [name, entry] of Object.entries(options.query ?? {})) {
+        if (entry !== undefined)
+            params.append(name, String(entry));
+    }
+    const signature = signPath(path, options.signingKeys);
+    if (signature)
+        params.append(options.signatureParam ?? 'sig', signature);
+    const query = params.toString();
+    return `${origin}${path}${query ? `?${query}` : ''}`;
+}

package/dist/url-signing.d.mts

@@ -1,2 +1,3 @@
-export declare function signPathWithKey(path: string, keyHex: string): string;
-export declare function verifyPathWithKey(path: string, signature: string, keyHex: string): boolean;
+export { parseSigningKeys, signExpiringPath, signPath, signPathWithKey, verifyExpiringPath, verifyPathSignature, verifyPathWithKey, type VerifyPathOptions, } from './url-signing-keys.mts';
+export { authorizeDependencyStates, createProtectedHostPolicy, hostnameOf, matchRouteSegment, normalizeHostname, type DependencyAuthorization, type ProtectedHostPolicy, } from './url-signing-hosts.mts';
+export { buildSignedProxyUrl, type BuildSignedProxyUrlOptions } from './url-signing-proxy.mts';

package/dist/url-signing.mjs

@@ -1,12 +1,3 @@
-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'));
-}
+export { parseSigningKeys, signExpiringPath, signPath, signPathWithKey, verifyExpiringPath, verifyPathSignature, verifyPathWithKey, } from './url-signing-keys.mjs';
+export { authorizeDependencyStates, createProtectedHostPolicy, hostnameOf, matchRouteSegment, normalizeHostname, } from './url-signing-hosts.mjs';
+export { buildSignedProxyUrl } from './url-signing-proxy.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "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": {
+    "./api-errors": {
+      "types": "./dist/api-errors.d.mts",
+      "import": "./dist/api-errors.mjs",
+      "default": "./dist/api-errors.mjs"
+    },
+    "./api-response-contract": {
+      "types": "./dist/api-response-contract.d.mts",
+      "import": "./dist/api-response-contract.mjs",
+      "default": "./dist/api-response-contract.mjs"
+    },
     "./cache-tags": {
       "types": "./dist/cache-tags.d.mts",
       "import": "./dist/cache-tags.mjs",
@@ -70,6 +80,11 @@
       "import": "./dist/cookies.mjs",
       "default": "./dist/cookies.mjs"
     },
+    "./content-identity-cache": {
+      "types": "./dist/content-identity-cache.d.mts",
+      "import": "./dist/content-identity-cache.mjs",
+      "default": "./dist/content-identity-cache.mjs"
+    },
     "./collections": {
       "types": "./dist/collections.d.mts",
       "import": "./dist/collections.mjs",