partial-content 1.0.0

package/SECURITY.md

@@ -0,0 +1,92 @@
+# Security Policy
+
+## Supported versions
+
+The latest published minor release receives security fixes.
+
+## Reporting a vulnerability
+
+Email **oss@nordvec.com** with the details. Please include:
+
+- The affected module (`partial-content`, a store adapter, or a framework adapter)
+- A minimal reproduction (a failing request/response pair is ideal)
+- The impact you believe it has (header injection, cache poisoning, path traversal, byte-splicing, DoS)
+
+You will receive an acknowledgement within 72 hours. Please do not open a
+public issue for undisclosed vulnerabilities.
+
+## Threat model (what this library defends against)
+
+`partial-content` sits between attacker-controlled request headers and
+storage-backend metadata. Defenses under test:
+
+- **Header injection (CWE-113) and header-write crashes:** every
+  metadata-derived or caller-per-request response header value (ETag,
+  Last-Modified, Content-Type, digest, Cache-Control, and the signed-URL
+  `Location`) is stripped of ALL bytes outside RFC 9110 field-value grammar
+  -- not just CRLF, but every control byte that Node `writeHead`, undici
+  `Headers`, and Workers reject by throwing, so a poisoned backend value can
+  neither inject nor crash the process. ETag values are additionally held to
+  `etagc` grammar (interior DQUOTE removed) so a backend hash can never emit
+  a structurally-broken entity-tag. Content-Disposition filenames AND the
+  disposition type are fully sanitized (controls, bidi overrides, path
+  components; the type is coerced to `inline`/`attachment`).
+- **Path traversal / null bytes:** the fs adapter resolves keys against a
+  fixed root and rejects `..`, absolute paths (including Windows cross-drive
+  `D:\...` keys), and `\0`. On Windows it also rejects reserved device names
+  (`NUL`, `CON`, `COM1`, ...) and alternate-data-stream keys (`file::$DATA`),
+  neither of which resolves to a file under the root.
+- **Cache poisoning / byte splicing:** strong-validator enforcement for
+  `If-Match` and `If-Range`, exact-match If-Range dates, pinned reads with
+  one re-validation, and truthful Content-Range derived from the backend's
+  actual response.
+- **Range-amplification DoS (CWE-400):** multi-range requests are served as
+  `multipart/byteranges`, but overlapping and adjacent ranges are coalesced
+  first, and a request whose coalesced parts exceed `maxRanges` (default 50)
+  or already cover the whole representation degrades to a single full 200.
+  A client cannot force a large or redundant multipart response by sending
+  many tiny or overlapping ranges (the mitigation in Go `net/http.ServeContent`
+  and nginx `max_ranges`). The multipart `Content-Length` is computed exactly,
+  never chunked, so the response size is known and bounded up front.
+- **MIME sniffing / encoding-sniffing XSS:** `X-Content-Type-Options: nosniff`
+  on every success + error response (the `200`/`206`/`404`/`502`/`503` bodies
+  and the bodyless `412`/`416` denials; `304`/`302` carry none), `charset=utf-8`
+  enforcement on textual types, `text/html`
+  deliberately absent from the built-in MIME map. Note that `svg` IS in the
+  map (`image/svg+xml`) and SVG is active content: served `inline` from your
+  own origin it can run same-origin script. For untrusted uploads, serve SVG
+  as `attachment` (per-MIME `disposition` hook) or add a sandboxing CSP via
+  `securityHeaders`.
+- **Parser robustness:** the range/Content-Range/disposition parsers are
+  covered by seeded randomized invariant tests (never throw; bounds always
+  valid; output always header-safe).
+- **Transparent-compression corruption:** the http adapter requests
+  `Accept-Encoding: identity` and refuses (fails loudly) any response that
+  still carries a non-identity `Content-Encoding`, so a decompressed body can
+  never be served under compressed-size headers.
+- **Conditional-date strictness:** client-supplied `If-Modified-Since`,
+  `If-Unmodified-Since`, and `If-Range` dates are honored only in the three
+  RFC 9110 HTTP-date formats; anything else (including ISO 8601) is ignored,
+  as the spec mandates.
+
+## Server-side request forgery (httpStore)
+
+`partial-content/http` fetches whatever your `url(key)` returns; the origin
+is part of YOUR trust boundary:
+
+- **Never interpolate untrusted input into `url()` unencoded.** A key like
+  `../other-bucket/secret` changes the fetched path. Encode path segments or
+  validate keys before they reach the store.
+- **Redirects error by default** (`redirect: "error"`). A serving layer whose
+  `url()` may carry untrusted keys must not let a compromised or misconfigured
+  origin bounce the store to internal endpoints such as cloud metadata IPs, so
+  a 3xx is refused unless you opt in. Object-storage origins answer GET/HEAD
+  with a direct 200, so the default costs nothing there. Set `redirect: "follow"`
+  for origins that legitimately redirect, and pair it with a validating `fetch`
+  when keys are untrusted.
+- **Network-level SSRF defenses are deliberately not built in** (DNS pinning
+  and IP allowlists are deployment-specific). Supply them via the `fetch`
+  option, which every request goes through.
+
+Out of scope: authentication/authorization (gate access before calling the
+handler) and rate limiting (deploy-level concern).

package/dist/azure.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Azure Blob Storage ObjectStore adapter for partial-content.
+ *
+ * Wraps `@azure/storage-blob` to implement the {@link ObjectStore} interface.
+ *
+ * @example
+ * ```typescript
+ * import { BlobServiceClient } from "@azure/storage-blob";
+ * import { azureStore } from "partial-content/azure";
+ *
+ * const client = BlobServiceClient.fromConnectionString(connectionString);
+ * const store = azureStore({
+ *   containerClient: client.getContainerClient("documents"),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, type ObjectStore } from "./index.js";
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+/**
+ * Minimal Azure ContainerClient interface.
+ *
+ * Declared locally to avoid a hard dependency on `@azure/storage-blob`.
+ * Users who import `partial-content/azure` will have it installed as an
+ * optional peer dependency.
+ */
+interface AzureContainerClient {
+    getBlobClient(blobName: string): AzureBlobClient;
+}
+interface AzureBlobClient {
+    getProperties(options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<AzureBlobProperties>;
+    download(offset?: number, count?: number, options?: {
+        conditions?: {
+            ifMatch?: string;
+        };
+        abortSignal?: AbortSignal;
+    }): Promise<AzureBlobDownloadResponse>;
+}
+interface AzureBlobProperties {
+    contentLength?: number;
+    etag?: string;
+    lastModified?: Date;
+}
+interface AzureBlobDownloadResponse {
+    readableStreamBody?: NodeJS.ReadableStream & AsyncIterable<Buffer> & {
+        destroy?: () => void;
+    };
+    blobBody?: Promise<Blob>;
+    contentLength?: number;
+    /** Present on ranged downloads: "bytes 5-9/20". Carries the total size. */
+    contentRange?: string;
+    etag?: string;
+    lastModified?: Date;
+}
+export interface AzureStoreOptions {
+    /** Pre-configured Azure ContainerClient. */
+    containerClient: AzureContainerClient;
+}
+/**
+ * Create an {@link ObjectStore} backed by an Azure Blob Storage container.
+ *
+ * @example
+ * ```typescript
+ * import { BlobServiceClient } from "@azure/storage-blob";
+ * import { azureStore } from "partial-content/azure";
+ *
+ * const blobService = BlobServiceClient.fromConnectionString(conn);
+ * const store = azureStore({
+ *   containerClient: blobService.getContainerClient("documents"),
+ * });
+ *
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export declare function azureStore(opts: AzureStoreOptions): ObjectStore;
+//# sourceMappingURL=azure.d.ts.map

package/dist/azure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure.d.ts","sourceRoot":"","sources":["../src/azure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EAOrB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AAI1E;;;;;;GAMG;AACH,UAAU,oBAAoB;IAC5B,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAAC;CAClD;AAED,UAAU,eAAe;IACvB,aAAa,CAAC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrF,QAAQ,CACN,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GACzE,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACvC;AAED,UAAU,mBAAmB;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,UAAU,yBAAyB;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAID,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,eAAe,EAAE,oBAAoB,CAAC;CACvC;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,CA2G/D"}

package/dist/azure.js

@@ -0,0 +1,251 @@
+/**
+ * Azure Blob Storage ObjectStore adapter for partial-content.
+ *
+ * Wraps `@azure/storage-blob` to implement the {@link ObjectStore} interface.
+ *
+ * @example
+ * ```typescript
+ * import { BlobServiceClient } from "@azure/storage-blob";
+ * import { azureStore } from "partial-content/azure";
+ *
+ * const client = BlobServiceClient.fromConnectionString(connectionString);
+ * const store = azureStore({
+ *   containerClient: client.getContainerClient("documents"),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, classifyStoreRead, nodeStreamToWeb, guardStreamLength, resolveServedRange, parseRetryAfterSeconds, isOpenEndedRange, } from "./index.js";
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create an {@link ObjectStore} backed by an Azure Blob Storage container.
+ *
+ * @example
+ * ```typescript
+ * import { BlobServiceClient } from "@azure/storage-blob";
+ * import { azureStore } from "partial-content/azure";
+ *
+ * const blobService = BlobServiceClient.fromConnectionString(conn);
+ * const store = azureStore({
+ *   containerClient: blobService.getContainerClient("documents"),
+ * });
+ *
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export function azureStore(opts) {
+    const { containerClient } = opts;
+    return {
+        supportsRange: true,
+        // 206 bounds/total come from Azure's actual contentRange: the
+        // orchestrator may skip the validating HEAD for plain range requests.
+        authoritativeRange: true,
+        async headObject(key, opts) {
+            opts?.signal?.throwIfAborted();
+            // Forward the signal so a client disconnect during the request/header
+            // phase cancels the Azure call (the pre-check only covers already-aborted;
+            // the body phase is covered by nodeStreamToWeb's signal wiring).
+            const props = await classifyStoreRead(key, () => containerClient.getBlobClient(key).getProperties({ abortSignal: opts?.signal }), azureClassifiers);
+            if (props.contentLength == null) {
+                throw new Error(`Azure getProperties returned no contentLength for ${key}`);
+            }
+            return {
+                contentLength: props.contentLength,
+                etag: props.etag,
+                lastModified: props.lastModified?.toUTCString(),
+            };
+        },
+        async getObject(key, opts) {
+            const { range, signal, ifMatch } = opts ?? {};
+            signal?.throwIfAborted();
+            // Single round-trip: download() carries everything needed. For ranged
+            // reads the response's Content-Range ("bytes 5-9/20") supplies the
+            // total size; for full reads contentLength IS the total. One response
+            // also means one representation -- no metadata/body race to guard.
+            const offset = range ? range.start : 0;
+            // An open-ended fast-path range (OPEN_ENDED sentinel end) reads to the
+            // end of the blob: leave count undefined so download() streams the
+            // tail rather than requesting ~9e15 bytes.
+            const count = range && !isOpenEndedRange(range)
+                ? (range.end - range.start + 1)
+                : undefined;
+            const response = await classifyStoreRead(key, () => containerClient.getBlobClient(key).download(offset, count, {
+                // Pin the read to the validated representation: Azure rejects
+                // with 412 ConditionNotMet if the blob changed since HEAD.
+                ...(ifMatch ? { conditions: { ifMatch } } : {}),
+                // Forward the signal so the request/header phase is cancellable too.
+                abortSignal: signal,
+            }), azureClassifiers);
+            if (response.contentLength == null) {
+                destroyAzureDownload(response);
+                throw new Error(`Azure download returned no contentLength for ${key}`);
+            }
+            const contentLength = response.contentLength;
+            const resolved = response.contentRange
+                ? resolveServedRange(response.contentRange)
+                : null;
+            // A Content-Range Azure emits but the resolver cannot parse means the
+            // byte accounting is untrustworthy: release the live socket and fail
+            // loudly rather than guess.
+            if (response.contentRange && !resolved) {
+                destroyAzureDownload(response);
+                throw new Error(`Azure returned unparseable Content-Range for ${key}: ${response.contentRange}`);
+            }
+            // For a full read (no Content-Range) contentLength IS the total; a ranged
+            // read carries the resolver's honest total (undefined for `bytes a-b/*`).
+            const totalSize = resolved ? resolved.totalSize : contentLength;
+            // Azure SDK returns different body types depending on the environment
+            let webStream;
+            if (response.readableStreamBody) {
+                // Node.js environment: use shared stream conversion
+                const nodeStream = response.readableStreamBody;
+                // nodeStreamToWeb auto-detects the stream's destroy() capability.
+                // expectedBytes guards a graceful short-read: the Azure SDK can end
+                // readableStreamBody cleanly when its in-stream retries are exhausted
+                // mid-download, which would otherwise under-run the committed
+                // Content-Length undetected.
+                webStream = nodeStreamToWeb(nodeStream, { signal, expectedBytes: contentLength });
+            }
+            else if (response.blobBody) {
+                // Browser environment: guard the buffered blob's byte count against the
+                // committed length for parity with the Node path's expectedBytes check.
+                const blob = await response.blobBody;
+                webStream = guardStreamLength(blob.stream(), contentLength);
+            }
+            else {
+                throw new Error(`Azure download returned no body for ${key}`);
+            }
+            return {
+                body: webStream,
+                contentLength,
+                totalSize,
+                // The bounds Azure ACTUALLY served, from its response Content-Range.
+                range: resolved ? resolved.served : undefined,
+                etag: response.etag,
+                lastModified: response.lastModified?.toUTCString(),
+            };
+        },
+    };
+}
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+/**
+ * Azure `RestError`'s numeric HTTP status, when present. This is the
+ * AUTHORITATIVE classification signal: when a numeric `statusCode` exists, the
+ * classifiers key off it exactly and never fall through to message heuristics,
+ * so a `503 ServerBusy` whose message text happens to contain "412" (a request
+ * id or timestamp digit run) can never be misread as a 412. A present-but-
+ * non-numeric status returns `undefined` so the code/message fallback still runs.
+ */
+function azureStatusCode(err) {
+    if (typeof err === "object" && err !== null && "statusCode" in err) {
+        const s = err.statusCode;
+        if (typeof s === "number")
+            return s;
+    }
+    return undefined;
+}
+/**
+ * Azure `RestError`'s stable error code (`BlobNotFound`, `ConditionNotMet`,
+ * `ServerBusy`, ...). Matched exactly, so unlike a message substring it cannot
+ * collide with arbitrary text in the error message.
+ */
+function azureErrorCode(err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        const c = err.code;
+        if (typeof c === "string")
+            return c;
+    }
+    return undefined;
+}
+function isAzureNotFound(err) {
+    const status = azureStatusCode(err);
+    if (status !== undefined)
+        return status === 404;
+    if (azureErrorCode(err) === "BlobNotFound")
+        return true;
+    return err instanceof Error && err.name === "RestError" && err.message.includes("BlobNotFound");
+}
+/**
+ * Release Azure's live download socket before bailing out on a malformed
+ * response. `download()` resolves once headers arrive with an OPEN
+ * `readableStreamBody`; throwing before that stream is handed to
+ * `nodeStreamToWeb` would leak the socket (and its connection-pool slot)
+ * until GC. The browser `blobBody` path buffers in memory and needs no
+ * teardown.
+ */
+function destroyAzureDownload(response) {
+    response.readableStreamBody?.destroy?.();
+}
+/**
+ * Check if an Azure error is a failed ifMatch condition (blob changed).
+ * The SDK surfaces this as a RestError with statusCode 412 (ConditionNotMet).
+ * A numeric status is authoritative; the `code`/message fallback only runs for
+ * status-less shapes, so a throttle carrying "412" in its message text is never
+ * misreported as a precondition failure.
+ */
+function isAzurePreconditionFailed(err) {
+    const status = azureStatusCode(err);
+    if (status !== undefined)
+        return status === 412;
+    if (azureErrorCode(err) === "ConditionNotMet")
+        return true;
+    return err instanceof Error && err.name === "RestError" && err.message.includes("ConditionNotMet");
+}
+/**
+ * The back-off Azure advises on a throttle, parsed from the `Retry-After`
+ * response header (whole seconds; the HTTP-date form is ignored). Surfaced so
+ * the 503 echoes it and shared caches wait the advised interval.
+ */
+function azureRetryAfterSeconds(err) {
+    const headers = err
+        .response?.headers;
+    // The classifier runs on arbitrary (S3-compatible/proxy) error shapes, so
+    // harden the structural access: optional-call guards only null/undefined, but
+    // a truthy non-function `.get` would throw, and a throwing `.get` propagates
+    // -- either way the thrown error would replace the throttle and turn a 429/503
+    // into a 502. Gate on the type and swallow a throwing getter.
+    const get = headers?.get;
+    if (typeof get !== "function")
+        return undefined;
+    let raw;
+    try {
+        raw = get.call(headers, "retry-after");
+    }
+    catch {
+        return undefined;
+    }
+    return parseRetryAfterSeconds(raw);
+}
+/**
+ * Whether an Azure error is a transient throttle/overload the client should
+ * retry (mapped to a 503, not a 502). Azure's retryable transients are
+ * `ServerBusy` (HTTP 503) and `OperationTimedOut` (HTTP **500**), so they are
+ * matched by ERROR CODE first: keying only off the numeric status would demote
+ * `OperationTimedOut` to a non-retryable 502 (500 is neither 429 nor 503). A
+ * numeric 429/503 still catches throttles that arrive without a code, and the
+ * message fallback (gated on a status-less shape) preserves the classifier's
+ * exclusivity -- a 503 whose message merely contains "412" is classified by
+ * code/status, never by substring. Returns the advised `Retry-After` when set.
+ */
+function isAzureThrottled(err) {
+    const code = azureErrorCode(err);
+    const status = azureStatusCode(err);
+    const throttled = code === "ServerBusy" || code === "OperationTimedOut"
+        || status === 429 || status === 503
+        || (status === undefined && err instanceof Error && err.name === "RestError"
+            && (err.message.includes("ServerBusy") || err.message.includes("OperationTimedOut")));
+    if (!throttled)
+        return false;
+    const retryAfterSeconds = azureRetryAfterSeconds(err);
+    return retryAfterSeconds !== undefined ? { retryAfterSeconds } : true;
+}
+/** The ordered error-classification set shared by getProperties and download. */
+const azureClassifiers = {
+    notFound: isAzureNotFound,
+    changed: isAzurePreconditionFailed,
+    throttled: isAzureThrottled,
+};
+//# sourceMappingURL=azure.js.map

package/dist/azure.js.map

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

package/dist/content-disposition.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Content-Disposition header builder (RFC 6266 + RFC 8187).
+ *
+ * Builds Content-Disposition headers for HTTP responses that serve files.
+ * Handles both inline (in-app preview) and attachment (download) dispositions
+ * with proper RFC compliance for non-ASCII filenames.
+ *
+ * Security: Prevents CRLF header injection, path traversal, bidi override
+ * spoofing, and control character injection in filenames from untrusted
+ * sources (integration APIs, user uploads).
+ *
+ * Emits dual filename parameters for cross-browser compatibility:
+ *   - `filename="ascii-safe.pdf"` for legacy browsers
+ *   - `filename*=UTF-8''%C3%85rlig.pdf` for modern browsers (RFC 8187)
+ */
+export interface ContentDispositionOptions {
+    /**
+     * Disposition type.
+     * - `"attachment"`: Force download (safe default for untrusted content)
+     * - `"inline"`: Render in browser (only for previewable types: PDF, image, video, audio)
+     * @default "attachment"
+     */
+    type?: "attachment" | "inline";
+    /**
+     * Fallback filename when input is null, undefined, or empty after sanitization.
+     * @default "document"
+     */
+    fallback?: string;
+}
+/**
+ * Build a Content-Disposition header value with RFC compliance and
+ * security sanitization.
+ *
+ * Accepts untrusted filenames from integration APIs, user uploads, and
+ * database records. Sanitizes for:
+ *   - CRLF injection (strips \r, \n, and all control characters)
+ *   - Path traversal (strips ../ and ..\\ sequences)
+ *   - Basename extraction (strips directory paths)
+ *   - Bidi override stripping (prevents RLO filename spoofing)
+ *   - Double-quote and backslash escaping (RFC 2616 quoted-pair)
+ *
+ * Emits dual filename parameters for cross-browser compatibility:
+ *   - `filename="ascii-safe.pdf"` for legacy browsers (IE, old Safari)
+ *   - `filename*=UTF-8''%C3%85rlig.pdf` for modern browsers (RFC 8187)
+ *
+ * Token optimization: Simple ASCII filenames like `plans.pdf` are emitted
+ * unquoted (`filename=plans.pdf`).
+ *
+ * @param filename - Raw filename from untrusted source (upload, API, DB)
+ * @param options - Disposition type and fallback configuration
+ * @returns Complete Content-Disposition header value string
+ *
+ * @example
+ * // Simple ASCII attachment
+ * buildContentDisposition("report.pdf")
+ * // => 'attachment; filename=report.pdf'
+ *
+ * @example
+ * // Non-ASCII filename (Danish)
+ * buildContentDisposition("Årlig_Rapport.pdf")
+ * // => 'attachment; filename="?rlig_Rapport.pdf"; filename*=UTF-8\'\'%C3%85rlig_Rapport.pdf'
+ *
+ * @example
+ * // Inline disposition for preview
+ * buildContentDisposition("slides.pdf", { type: "inline" })
+ * // => 'inline; filename=slides.pdf'
+ *
+ * @example
+ * // Null input with custom fallback
+ * buildContentDisposition(null, { fallback: "export.csv" })
+ * // => 'attachment; filename=export.csv'
+ */
+export declare function buildContentDisposition(filename: string | null | undefined, options?: ContentDispositionOptions): string;
+//# sourceMappingURL=content-disposition.d.ts.map

package/dist/content-disposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-disposition.d.ts","sourceRoot":"","sources":["../src/content-disposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,yBAAyB;IACtC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AA2DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE,yBAAyB,GACpC,MAAM,CAkBR"}