@irvinebroque/http-rfc-utils 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,222 @@
+# http-rfc-utils
+
+RFC-aligned HTTP utilities for APIs: ETags, conditional requests, caching, link headers, content negotiation, pagination, CORS, and Problem Details.
+
+## Installation
+
+```bash
+npm install http-rfc-utils
+```
+
+## Supported RFCs
+
+- [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html), Sections 5.6.7, 8.8.2-8.8.3.2, 10.2.3, 12.4.2, 12.5.3-12.5.5, 13.1.1-13.1.5, 13.2.2, 14.1.2-14.4, 15.4.5, 15.5.13, 15.5.17 (HTTP semantics)
+- [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html), Sections 1.2.2, 5.2, 5.2.2 (Cache-Control)
+- [RFC 5861](https://www.rfc-editor.org/rfc/rfc5861.html), Section 3 (Cache-Control extensions)
+- [RFC 8246](https://www.rfc-editor.org/rfc/rfc8246.html), Section 2 (Immutable Cache-Control extension)
+- [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html), Sections 3.1-3.4, 6 (Web Linking)
+- [RFC 9264](https://www.rfc-editor.org/rfc/rfc9264.html), Sections 4.1-4.2, 6 (Linkset media types)
+- [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html), Sections 2-4, 7 (api-catalog well-known URI and link relation)
+- [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html), Sections 5.3.1-5.3.2 (Accept header) — obsoleted by RFC 9110
+- [RFC 7240](https://www.rfc-editor.org/rfc/rfc7240.html), Sections 2-3 (Prefer)
+- [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239.html), Section 4 (Forwarded header)
+- [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265.html), Sections 4.1.1, 4.2.1, 5.1.1, 5.1.3-5.1.4, 5.2-5.4 (Cookies)
+- [RFC 6266](https://www.rfc-editor.org/rfc/rfc6266.html), Sections 4-4.3 (Content-Disposition)
+- [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187.html), Section 3.2 (Header parameter encoding)
+- [RFC 6797](https://www.rfc-editor.org/rfc/rfc6797.html), Sections 6.1-6.1.2 (Strict-Transport-Security)
+- [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.html), Sections 2-2.1 (Basic authentication)
+- [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750.html), Sections 2.1, 3 (Bearer tokens)
+- [RFC 7616](https://www.rfc-editor.org/rfc/rfc7616.html), Sections 3.3-3.5 (Digest authentication)
+- [RFC 4647](https://www.rfc-editor.org/rfc/rfc4647.html), Section 3 (Language tag matching)
+- [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941.html), Sections 3-4 (Structured Field Values)
+- [RFC 8942](https://www.rfc-editor.org/rfc/rfc8942.html), Sections 2.2, 3.1-3.2, 4.2 (Client Hints)
+- [RFC 9211](https://www.rfc-editor.org/rfc/rfc9211.html), Sections 2-2.8 (Cache-Status)
+- [RFC 9209](https://www.rfc-editor.org/rfc/rfc9209.html), Sections 2-2.4 (Proxy-Status)
+- [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html), Sections 2-5 (Digest Fields)
+- [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html), Sections 3.1-3.2, 4.1 (Problem Details)
+- [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901.html), Sections 3-7 (JSON Pointer)
+- [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html), Sections 2.1-2.7 (JSONPath)
+- [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html), Section 5.6 (timestamps)
+- [RFC 850](https://www.rfc-editor.org/rfc/rfc850.html), Section 2 (legacy HTTP-date format, obsolete)
+- [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html), Sections 3, 6 (Sunset header)
+- [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html), Sections 2, 3.1, 3.2.2, 5.2.4, 6.2 (URI Generic Syntax)
+- [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html), Sections 1.2, 2-3 (URI Template)
+- [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html), Sections 2-4 (HTTP Message Signatures)
+- Fetch/CORS specs (CORS headers)
+
+## RFC References
+
+Use these RFCs as the source of truth for HTTP behavior and field formats:
+
+- [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html) - Sections 5.6.7, 8.8.2-8.8.3.2, 10.2.3, 12.4.2, 12.5.3-12.5.5, 13.1.1-13.1.5, 13.2.2, 14.1.2-14.4, 15.4.5, 15.5.13, 15.5.17
+- [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) - Sections 1.2.2, 5.2, 5.2.2
+- [RFC 5861](https://www.rfc-editor.org/rfc/rfc5861.html) - Section 3 (stale-while-revalidate, stale-if-error)
+- [RFC 8246](https://www.rfc-editor.org/rfc/rfc8246.html) - Section 2 (immutable)
+- [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html) - Sections 3.1-3.4, 6
+- [RFC 9264](https://www.rfc-editor.org/rfc/rfc9264.html) - Sections 4.1-4.2, 6
+- [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html) - Sections 2-4, 7
+- [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html) - Sections 5.3.1-5.3.2 (obsoleted by RFC 9110)
+- [RFC 7240](https://www.rfc-editor.org/rfc/rfc7240.html) - Sections 2-3
+- [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239.html) - Section 4
+- [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265.html) - Sections 4.1.1, 4.2.1, 5.1.1, 5.1.3-5.1.4, 5.2-5.4
+- [RFC 6266](https://www.rfc-editor.org/rfc/rfc6266.html) - Sections 4-4.3
+- [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187.html) - Section 3.2
+- [RFC 6797](https://www.rfc-editor.org/rfc/rfc6797.html) - Sections 6.1-6.1.2
+- [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.html) - Sections 2-2.1
+- [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750.html) - Sections 2.1, 3
+- [RFC 7616](https://www.rfc-editor.org/rfc/rfc7616.html) - Sections 3.3-3.5
+- [RFC 4647](https://www.rfc-editor.org/rfc/rfc4647.html) - Section 3 (basic filtering)
+- [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941.html) - Sections 3-4
+- [RFC 8942](https://www.rfc-editor.org/rfc/rfc8942.html) - Sections 2.2, 3.1-3.2, 4.2
+- [RFC 9211](https://www.rfc-editor.org/rfc/rfc9211.html) - Sections 2-2.8
+- [RFC 9209](https://www.rfc-editor.org/rfc/rfc9209.html) - Sections 2-2.4
+- [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html) - Sections 2-5
+- [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) - Sections 3.1-3.2, 4.1
+- [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901.html) - Sections 3-7
+- [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html) - Sections 2.1-2.7
+- [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) - Section 5.6
+- [RFC 850](https://www.rfc-editor.org/rfc/rfc850.html) - Section 2
+- [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html) - Sections 3, 6
+- [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html) - Sections 2, 3.1, 3.2.2, 5.2.4, 6.2
+- [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) - Sections 1.2, 2-3
+- [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) - Sections 2-4
+
+## Requirements
+
+- Node.js 25 or later
+
+## RFC Map
+
+| Module | RFCs | Exports | Usage |
+| --- | --- | --- | --- |
+| `src/etag.ts` | RFC 9110 §§8.8.3-8.8.3.2, 13.1.1-13.1.2 | `generateETag`, `generateETagAsync`, `parseETag`, `formatETag`, `compareETags`, `compareETagStrings`, `ETag` | Generate ETags for representations; parse/compare `If-Match` and `If-None-Match`. |
+| `src/conditional.ts` | RFC 9110 §§13.1.1-13.1.4, 13.2.2, 15.4.5, 15.5.13 | `evaluatePreconditions`, `handleConditionalRequest`, `parseIfNoneMatch`, `parseIfMatch`, `evaluateIfMatch`, `evaluateIfNoneMatch`, `evaluateIfModifiedSince`, `evaluateIfUnmodifiedSince` | Evaluate conditional request headers and decide `304/412`. |
+| `src/datetime.ts` | RFC 3339 §5.6; RFC 9110 §5.6.7; RFC 850 §2 | `toRFC3339`, `parseRFC3339`, `formatHTTPDate`, `parseHTTPDate`, `isExpired`, `secondsUntil` | Format JSON timestamps and HTTP date headers. |
+| `src/cache.ts` | RFC 9111 §§1.2.2, 5.2, 5.2.2; RFC 5861 §3; RFC 8246 §2 | `cacheControl`, `getCacheHeaders`, `parseCacheControl`, `CachePresets` | Build/parse `Cache-Control`, add `ETag` + `Last-Modified`. |
+| `src/range.ts` | RFC 9110 §§13.1.5, 14.1.2-14.4, 15.5.17 | `parseRange`, `formatContentRange`, `parseContentRange`, `acceptRanges`, `evaluateRange` | Parse and evaluate Range requests; build `Content-Range`. |
+| `src/prefer.ts` | RFC 7240 §§2-3 | `parsePrefer`, `formatPrefer`, `formatPreferenceApplied` | Parse `Prefer` and emit `Preference-Applied`. |
+| `src/forwarded.ts` | RFC 7239 §4 | `parseForwarded`, `formatForwarded` | Parse and format `Forwarded` header values. |
+| `src/ext-value.ts` | RFC 8187 §3.2 | `decodeExtValue`, `encodeExtValue`, `needsExtendedEncoding`, `isAttrChar` | Decode/encode RFC 8187 ext-value for `title*`, `filename*`, etc. |
+| `src/content-disposition.ts` | RFC 6266 §§4-4.3; RFC 8187 §3.2 | `parseContentDisposition`, `formatContentDisposition`, `formatHeaderParam` | Parse/format `Content-Disposition` with `filename*` support. |
+| `src/cookie.ts` | RFC 6265 §§4.1.1, 4.2.1, 5.1.1, 5.1.3-5.1.4, 5.2-5.4 | `parseCookie`, `formatCookie`, `parseSetCookie`, `formatSetCookie`, `parseCookieDate`, `domainMatches`, `defaultPath`, `pathMatches`, `buildCookieHeader` | Parse/format cookies and build Cookie headers. |
+| `src/auth.ts` | RFC 7617 §§2-2.1; RFC 6750 §§2.1, 3; RFC 7616 §§3.3-3.5 | `parseAuthorization`, `formatAuthorization`, `parseWWWAuthenticate`, `formatWWWAuthenticate`, `parseBasicAuthorization`, `formatBasicAuthorization`, `parseBasicChallenge`, `formatBasicChallenge`, `parseBearerAuthorization`, `formatBearerAuthorization`, `parseBearerChallenge`, `formatBearerChallenge`, `parseDigestChallenge`, `formatDigestChallenge`, `parseDigestAuthorization`, `formatDigestAuthorization`, `parseDigestAuthenticationInfo`, `formatDigestAuthenticationInfo`, `computeDigestResponse`, `computeA1`, `computeA2`, `hashDigestUsername`, `DIGEST_AUTH_ALGORITHMS` | Parse/format Basic, Bearer, and Digest auth headers; compute Digest response values. |
+| `src/hsts.ts` | RFC 6797 §§6.1-6.1.2, 8.1 | `parseStrictTransportSecurity`, `formatStrictTransportSecurity` | Parse and format `Strict-Transport-Security`. |
+| `src/language.ts` | RFC 9110 §§12.4.2, 12.5.4; RFC 4647 §3 | `parseAcceptLanguage`, `negotiateLanguage` | Parse and negotiate `Accept-Language` with basic filtering. |
+| `src/encoding.ts` | RFC 9110 §§12.4.2, 12.4.3, 12.5.3 | `parseAcceptEncoding`, `negotiateEncoding` | Parse and negotiate `Accept-Encoding` values. |
+| `src/headers.ts` | RFC 9110 §§10.2.3, 12.5.5; RFC 8594 §3 | `parseRetryAfter`, `formatRetryAfter`, `mergeVary`, `parseSunset`, `formatSunset`, `isSunsetImminent` | Retry-After parsing/formatting, Vary merging, and Sunset header. |
+| `src/structured-fields.ts` | RFC 8941 §§3-4 | `parseSfList`, `parseSfDict`, `parseSfItem`, `serializeSfList`, `serializeSfDict`, `serializeSfItem` | Structured field parsing and serialization. |
+| `src/client-hints.ts` | RFC 8942 §§2.2, 3.1-3.2, 4.2 | `parseAcceptCH`, `formatAcceptCH`, `filterClientHints`, `mergeClientHintsVary` | Accept-CH parsing and Vary helper for Client Hints. |
+| `src/cache-status.ts` | RFC 9211 §§2-2.8 | `parseCacheStatus`, `formatCacheStatus` | Parse and format Cache-Status responses. |
+| `src/proxy-status.ts` | RFC 9209 §§2-2.4 | `parseProxyStatus`, `formatProxyStatus`, `isProxyErrorType`, `PROXY_ERROR_TYPES` | Parse and format Proxy-Status responses; validate error types. |
+| `src/digest.ts` | RFC 9530 §§2-5 | `parseContentDigest`, `parseReprDigest`, `parseWantContentDigest`, `parseWantReprDigest`, `formatContentDigest`, `formatReprDigest`, `formatWantContentDigest`, `formatWantReprDigest`, `generateDigest`, `verifyDigest`, `DIGEST_ALGORITHMS`, `isActiveAlgorithm`, `isDeprecatedAlgorithm` | Parse/format Content-Digest, Repr-Digest, and Want-* preference headers; generate and verify SHA-256/SHA-512 digests. |
+| `src/link.ts` | RFC 8288 §§3-3.5, 6; RFC 8187 §3.2; RFC 9264 §6 | `formatLink`, `formatLinkHeader`, `parseLinkHeader`, `buildLinkHeader`, `quoteIfNeeded`, `unquote`, `LinkRelation` | Assemble and parse `Link` headers with `title*` (RFC 8187) and multiple `hreflang` support. |
+| `src/linkset.ts` | RFC 9264 §§4.1-4.2, 6; RFC 9727 §§2-4, 7 | `parseLinkset`, `parseLinksetJson`, `formatLinkset`, `formatLinksetJson`, `linksetToJson`, `jsonToLinkset`, `isValidLinkset`, `linksetToLinks`, `linksToLinkset`, `createApiCatalog`, `parseApiCatalog`, `isApiCatalog`, `LINKSET_MEDIA_TYPE`, `API_CATALOG_PROFILE`, `API_CATALOG_PATH` | Parse/format linkset documents; create/parse API catalogs per RFC 9727. |
+| `src/negotiate.ts` | RFC 7231 §§5.3.1-5.3.2 | `parseAccept`, `negotiate`, `getResponseFormat`, `toCSV`, `MEDIA_TYPES`, `MIME_TO_FORMAT` | Negotiate response media types and build CSV. |
+| `src/response.ts` | RFC 9110 §§8.8.2-8.8.3; RFC 9111 §5.2.2; RFC 8288 §3; RFC 6266 §4 | `optionsResponse`, `headResponse`, `jsonResponse`, `csvResponse`, `redirectResponse`, `simpleJsonResponse`, `noContentResponse`, `textResponse` | Opinionated response helpers (CORS + cache + pagination). |
+| `src/pagination.ts` | RFC 8288 §§3, 3.3 + API conventions | `parsePaginationParams`, `decodeCursor`, `encodeCursor`, `buildPaginationLinks`, `lastPageOffset`, `isFirstPage`, `isLastPage` | Cursor/offset parsing and pagination links. |
+| `src/problem.ts` | RFC 9457 §§3.1-3.2, 4.1 | `createProblem`, `problemResponse`, `Problems` | Return structured error responses. |
+| `src/json-pointer.ts` | RFC 6901 §§3-7 | `parseJsonPointer`, `formatJsonPointer`, `evaluateJsonPointer`, `toUriFragment`, `fromUriFragment`, `isValidJsonPointer` | Parse, format, and evaluate JSON Pointers; URI fragment encoding. |
+| `src/jsonpath.ts` | RFC 9535 §§2.1-2.7 | `parseJsonPath`, `queryJsonPath`, `queryJsonPathNodes`, `isValidJsonPath`, `formatNormalizedPath`, `compileJsonPath` | Parse and execute JSONPath queries; return values or nodes with normalized paths. |
+| `src/uri.ts` | RFC 3986 §§2, 3.1, 3.2.2, 5.2.4, 6.2 | `percentEncode`, `percentDecode`, `normalizeUri`, `removeDotSegments`, `compareUris`, `isUnreserved`, `isReserved` | URI percent-encoding, normalization, and comparison. |
+| `src/uri-template.ts` | RFC 6570 §§1.2, 2-3 | `parseUriTemplate`, `expandUriTemplate`, `isValidUriTemplate`, `getTemplateVariables`, `compileUriTemplate` | Parse and expand URI Templates with support for all Level 4 operators and modifiers. |
+| `src/http-signatures.ts` | RFC 9421 §§2-4 | `parseSignatureInput`, `formatSignatureInput`, `parseSignature`, `formatSignature`, `parseComponentIdentifier`, `formatComponentIdentifier`, `canonicalizeFieldValue`, `binaryWrapFieldValues`, `deriveComponentValue`, `createSignatureBase`, `isDerivedComponent`, `DERIVED_COMPONENTS` | Parse/format Signature-Input and Signature fields; create signature base strings for HTTP message signatures. |
+| `src/cors.ts` | Fetch/CORS specs | `defaultCorsHeaders`, `buildCorsHeaders`, `buildCorsHeadersForOrigin`, `buildPreflightHeaders`, `isOriginAllowed`, `corsHeaders` | Build CORS headers for single or multiple origins. |
+
+## Recipes
+
+### Conditional GET with ETag + Last-Modified
+
+1. Generate an ETag (`generateETag` or `generateETagAsync`).
+2. Determine `lastModified`.
+3. Call `evaluatePreconditions(request, currentETag, lastModified)`.
+4. If `proceed === false`, return `304` or `412` with the provided headers.
+5. Otherwise return your response with `ETag` and `Last-Modified`.
+
+```ts
+import { evaluatePreconditions } from 'http-rfc-utils';
+
+const result = evaluatePreconditions(request, currentETag, lastModified);
+
+if (!result.proceed) {
+    return new Response(null, {
+        status: result.status,
+        headers: result.headers,
+    });
+}
+```
+
+### Cache-Control for API responses
+
+1. Pick `CachePresets` or custom `CacheOptions`.
+2. Use `cacheControl` or `getCacheHeaders`.
+3. Combine with `jsonResponse`/`simpleJsonResponse`.
+
+```ts
+import { cacheControl, CachePresets } from 'http-rfc-utils';
+
+const headers = {
+    'Cache-Control': cacheControl(CachePresets.revalidate),
+};
+```
+
+### Accept negotiation + CSV
+
+1. `negotiate(request, ['application/json', 'text/csv'])`.
+2. If CSV, `toCSV(data)` and `csvResponse`.
+3. Otherwise `jsonResponse`.
+
+### Link header parsing
+
+```ts
+import { parseLinkHeader } from 'http-rfc-utils';
+
+const links = parseLinkHeader(response.headers.get('Link') ?? '');
+```
+
+## API Summary
+
+- `etag`: generate/parse/compare validators; async uses `crypto.subtle` for hashing.
+- `conditional`: RFC 9110 precondition evaluation with correct precedence.
+- `datetime`: RFC 3339 timestamps and RFC 9110 HTTP dates.
+- `cache`: Cache-Control builder/parser plus combined cache headers.
+- `link`: RFC 8288 Link formatter/parser; handles quoted commas and escapes.
+- `linkset`: RFC 9264 linkset document parser/formatter; RFC 9727 API catalog creation/parsing.
+- `negotiate`: Accept parsing + media type negotiation; `toCSV` helper.
+- `language`: Accept-Language parsing + basic filtering negotiation.
+- `encoding`: Accept-Encoding parsing + negotiation.
+- `range`: Range parsing + evaluation helpers.
+- `prefer`: Prefer parsing + Preference-Applied formatting.
+- `forwarded`: Forwarded header parsing + formatting.
+- `content-disposition`: Content-Disposition parsing + formatting with RFC 8187 ext-value utilities.
+- `cookie`: Cookie/Set-Cookie parsing, matching helpers, and Cookie header generation.
+- `auth`: Basic, Bearer, and Digest Authorization + WWW-Authenticate parsing/formatting; Digest response computation.
+- `hsts`: Strict-Transport-Security parsing/formatting.
+- `headers`: Retry-After parsing/formatting, Vary merging, and Sunset header.
+- `structured-fields`: Structured Field Values parsing + serialization.
+- `client-hints`: Accept-CH parsing and Vary helper for Client Hints.
+- `cache-status`: Cache-Status parsing and formatting.
+- `proxy-status`: Proxy-Status parsing and formatting; error type validation.
+- `digest`: RFC 9530 Content-Digest and Repr-Digest parsing/formatting; Want-* preferences; SHA-256/SHA-512 generation and verification.
+- `response`: opinionated helpers for API responses with CORS + caching.
+- `pagination`: cursor/limit parsing and Link header pagination.
+- `problem`: RFC 9457 Problem Details responses.
+- `json-pointer`: RFC 6901 JSON Pointer parsing, formatting, and evaluation.
+- `jsonpath`: RFC 9535 JSONPath query parsing and execution with filters, slices, and built-in functions.
+- `uri`: RFC 3986 URI percent-encoding, normalization, and comparison.
+- `uri-template`: RFC 6570 URI Template parsing and expansion; all Level 4 operators and modifiers.
+- `http-signatures`: RFC 9421 HTTP Message Signatures; Signature-Input/Signature field parsing; signature base creation.
+- `cors`: permissive defaults plus origin-aware header builder.
+
+## Notes
+
+- `jsonResponse` returns `{ data, meta }`; use `simpleJsonResponse` for raw payloads.
+- `csvResponse` only serializes data rows; pagination metadata remains in headers.
+- `generateETagAsync` accepts `ArrayBuffer`/`ArrayBufferView` and hashes bytes directly.
+- `generateETag` and `generateETagAsync` rely on `JSON.stringify` for non-binary objects; property order affects the resulting ETag.
+- For multiple CORS origins, use `buildCorsHeadersForOrigin(requestOrigin, options)` and include `Vary: Origin`.
+
+## Testing
+
+```bash
+npm test
+```

package/dist/auth.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Authorization and WWW-Authenticate utilities for Basic, Bearer, and Digest.
+ * RFC 7617 §2, §2.1; RFC 6750 §2.1, §3; RFC 7616 §3.3-3.5.
+ * @see https://www.rfc-editor.org/rfc/rfc7617.html#section-2
+ * @see https://www.rfc-editor.org/rfc/rfc7616.html
+ */
+import type { AuthChallenge, AuthCredentials, BasicChallenge, BasicCredentials, BearerChallenge, DigestAuthAlgorithm, DigestAuthenticationInfo, DigestAuthQop, DigestChallenge, DigestComputeOptions, DigestCredentials } from './types.js';
+/**
+ * Parse Authorization header into scheme + token68 or auth-params.
+ */
+export declare function parseAuthorization(header: string): AuthCredentials | null;
+/**
+ * Format Authorization header from credentials.
+ */
+export declare function formatAuthorization(credentials: AuthCredentials): string;
+/**
+ * Parse WWW-Authenticate header into challenges.
+ */
+export declare function parseWWWAuthenticate(header: string): AuthChallenge[];
+/**
+ * Format WWW-Authenticate header from challenges.
+ */
+export declare function formatWWWAuthenticate(challenges: AuthChallenge[]): string;
+/**
+ * Parse Basic Authorization header.
+ */
+export declare function parseBasicAuthorization(header: string, options?: {
+    encoding?: 'utf-8' | 'latin1';
+}): BasicCredentials | null;
+/**
+ * Format Basic Authorization header.
+ */
+export declare function formatBasicAuthorization(username: string, password: string, options?: {
+    encoding?: 'utf-8' | 'latin1';
+}): string | null;
+/**
+ * Parse Basic WWW-Authenticate challenge.
+ */
+export declare function parseBasicChallenge(header: string): BasicChallenge | null;
+/**
+ * Format Basic WWW-Authenticate challenge.
+ */
+export declare function formatBasicChallenge(realm: string, options?: {
+    charset?: 'UTF-8';
+}): string;
+/**
+ * Parse Bearer Authorization header.
+ */
+export declare function parseBearerAuthorization(header: string): string | null;
+/**
+ * Format Bearer Authorization header.
+ */
+export declare function formatBearerAuthorization(token: string): string | null;
+/**
+ * Parse Bearer WWW-Authenticate challenge.
+ */
+export declare function parseBearerChallenge(header: string): BearerChallenge | null;
+/**
+ * Format Bearer WWW-Authenticate challenge.
+ */
+export declare function formatBearerChallenge(params: BearerChallenge): string;
+/**
+ * Supported Digest authentication algorithms.
+ * RFC 7616 §3.3: SHA-256 MUST be supported; MD5 for backward compatibility.
+ */
+export declare const DIGEST_AUTH_ALGORITHMS: DigestAuthAlgorithm[];
+/**
+ * Parse Digest WWW-Authenticate challenge.
+ * RFC 7616 §3.3.
+ */
+export declare function parseDigestChallenge(challenge: AuthChallenge): DigestChallenge | null;
+/**
+ * Format Digest WWW-Authenticate challenge.
+ * RFC 7616 §3.3.
+ */
+export declare function formatDigestChallenge(challenge: DigestChallenge): string;
+/**
+ * Parse Digest Authorization credentials.
+ * RFC 7616 §3.4.
+ */
+export declare function parseDigestAuthorization(credentials: AuthCredentials): DigestCredentials | null;
+/**
+ * Format Digest Authorization credentials.
+ * RFC 7616 §3.4.
+ */
+export declare function formatDigestAuthorization(credentials: DigestCredentials): string;
+/**
+ * Parse Authentication-Info header.
+ * RFC 7616 §3.5.
+ */
+export declare function parseDigestAuthenticationInfo(value: string): DigestAuthenticationInfo | null;
+/**
+ * Format Authentication-Info header.
+ * RFC 7616 §3.5.
+ */
+export declare function formatDigestAuthenticationInfo(info: DigestAuthenticationInfo): string;
+/**
+ * Compute A1 value for Digest authentication.
+ * RFC 7616 §3.4.2.
+ *
+ * @param username - Username
+ * @param realm - Realm
+ * @param password - Password
+ * @param algorithm - Algorithm (session algorithms require nonce and cnonce)
+ * @param nonce - Server nonce (required for -sess algorithms)
+ * @param cnonce - Client nonce (required for -sess algorithms)
+ * @returns A1 hash value (hex string)
+ */
+export declare function computeA1(username: string, realm: string, password: string, algorithm?: DigestAuthAlgorithm, nonce?: string, cnonce?: string): Promise<string>;
+/**
+ * Compute A2 value for Digest authentication.
+ * RFC 7616 §3.4.3.
+ *
+ * @param method - HTTP method
+ * @param uri - Request URI
+ * @param qop - Quality of protection (optional)
+ * @param entityBody - Entity body for auth-int (optional)
+ * @returns A2 string value
+ */
+export declare function computeA2(method: string, uri: string, qop?: DigestAuthQop, _entityBody?: Uint8Array): string;
+/**
+ * Compute the Digest response value.
+ * RFC 7616 §3.4.1.
+ *
+ * @param options - Computation options
+ * @returns Response hash value (hex string)
+ */
+export declare function computeDigestResponse(options: DigestComputeOptions): Promise<string>;
+/**
+ * Hash a username for userhash support.
+ * RFC 7616 §3.4.4.
+ *
+ * @param username - Username to hash
+ * @param realm - Realm
+ * @param algorithm - Algorithm to use
+ * @returns Hashed username (hex string)
+ */
+export declare function hashDigestUsername(username: string, realm: string, algorithm?: DigestAuthAlgorithm): Promise<string>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}