@vouchington/edge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+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

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @vouchington/edge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Builders for Cloudflare Workers. The package exports functions, not a worker: the route table,
+CSP origins, analytics and Sentry DSNs, origin hosts, and cache rules are injected by the
+application.
+
+```ts
+import {
+  addSecurityHeaders,
+  buildCsp,
+  buildOriginRequest,
+  createBasicAuthGate,
+  createSentryTunnel,
+  fetchOriginResponse,
+  rewritePlaceholderNonce,
+} from '@vouchington/edge'
+```
+
+## Builders
+
+- Security headers: `addSecurityHeaders`, `buildSecurityHeaders`, `buildHsts`. The edge overwrites
+  origin values and preserves repeated `set-cookie` headers.
+- CSP: `buildCsp` starts from strict defaults and takes injected `sources`, `directives`, a nonce, and
+  an asset origin. `serializeCsp` rejects sources that could inject another directive.
+  `normalizeAssetOrigin` and `parseOriginAllowlist` validate configuration values.
+- Nonce rewriting: `rewritePlaceholderNonce` streams HTML and swaps a cache placeholder nonce for a
+  per-request nonce without buffering the document. It handles chunk boundaries and can drop
+  injected `<meta name>` tags.
+- Basic auth: `createBasicAuthGate` with timing-safe credential matching, rotation lists, a
+  fail-closed malformed-list rule, and an injected exemption matcher
+  (`createBasicAuthExemptMatcher`).
+- Proxying: `buildOriginRequest` retargets a request, strips client-supplied forwarding headers, owns
+  the request id and shared secret, and keeps redirects manual. `fetchOriginResponse` retries GET and
+  HEAD once after a dropped socket and maps failures to a no-store 502.
+- Cache helpers: `bypassPolicy`, `cachedPolicy`, `buildCacheControlHeader`, `isCacheableResponse`,
+  `parseSafeCacheVary`, `mergeClientVary`, `normalizeCacheUrl`, `finalizeCachedOriginResponse`,
+  `stripDispatchOnlyHeaders`, and `purgeCacheTags`. The route-to-policy decision stays in the app.
+- Environment checks: `createEnvWarner` (warn once per isolate), `warnIfSecretMisconfigured`,
+  `warnIfProductionValueInvalid`, `warnIfAssetOriginInvalid`, `warnIfDsnInvalid`, `isProductionMode`.
+- Client info and cookies: `applyClientInfoHeaders` with injected header names, `replaceCookies`,
+  `stripCookies`. Cookie parsing comes from `@vouchington/utils/cookies`.
+- Sentry tunnel: `createSentryTunnel` forwards envelopes only to injected trusted DSNs, caps the body,
+  and logs bounded diagnostics via `@vouchington/utils/sentry-envelope`.
+
+`@cloudflare/workers-types` is an optional peer dependency used for the `cache.purge` context type.

package/dist/basic-auth-credentials.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Compares every same-length credential with a byte-level XOR loop. Iterating the whole set avoids
+ * revealing which credential matched. Length remains observable from the request header itself.
+ */
+export declare function timingSafeCredentialMatch(input: string, credentials: ReadonlySet<string>): boolean;
+export type BasicAuthCredentialList = {
+    status: 'absent';
+} | {
+    status: 'configured';
+    source: string;
+    credentials: Set<string>;
+    hasMalformedEntries: boolean;
+};
+export type RequiredBasicAuthDecision = 'authorized' | 'misconfigured' | 'unauthorized';
+/**
+ * Parses comma-separated `user:password` pairs (several entries support rotation). Usernames and
+ * passwords must not contain commas and whitespace is significant. Parsed lists are memoized.
+ */
+export declare function readBasicAuthCredentialList(envValue: string | undefined): BasicAuthCredentialList;
+/** True when an `Authorization: Basic …` value decodes to one of `credentials`. */
+export declare function basicAuthorizationMatches(authorization: string | null, credentials: ReadonlySet<string>): boolean;
+/** Fail-closed decision for routes that require Basic auth: absent or malformed config is an error. */
+export declare function requiredBasicAuthDecision(authorization: string | null, envValue: string | undefined): RequiredBasicAuthDecision;

package/dist/basic-auth-credentials.mjs

@@ -0,0 +1,75 @@
+const encoder = new TextEncoder();
+const MAX_CACHED_LISTS = 16;
+/**
+ * Compares every same-length credential with a byte-level XOR loop. Iterating the whole set avoids
+ * revealing which credential matched. Length remains observable from the request header itself.
+ */
+export function timingSafeCredentialMatch(input, credentials) {
+    const inputBytes = encoder.encode(input);
+    let matched = false;
+    for (const credential of credentials) {
+        const credentialBytes = encoder.encode(credential);
+        if (inputBytes.length !== credentialBytes.length)
+            continue;
+        let diff = 0;
+        for (let i = 0; i < inputBytes.length; i++) {
+            diff |= inputBytes[i] ^ credentialBytes[i];
+        }
+        if (diff === 0)
+            matched = true;
+    }
+    return matched;
+}
+const credentialListCache = new Map();
+/**
+ * Parses comma-separated `user:password` pairs (several entries support rotation). Usernames and
+ * passwords must not contain commas and whitespace is significant. Parsed lists are memoized.
+ */
+export function readBasicAuthCredentialList(envValue) {
+    if (!envValue || envValue.trim() === '')
+        return { status: 'absent' };
+    const cached = credentialListCache.get(envValue);
+    if (cached !== undefined)
+        return cached;
+    const credentials = new Set();
+    let hasMalformedEntries = false;
+    for (const entry of envValue.split(',')) {
+        const colonIndex = entry.indexOf(':');
+        if (entry === '' || colonIndex <= 0 || colonIndex === entry.length - 1) {
+            hasMalformedEntries = true;
+            continue;
+        }
+        credentials.add(entry);
+    }
+    const result = {
+        status: 'configured',
+        source: envValue,
+        credentials,
+        hasMalformedEntries,
+    };
+    if (credentialListCache.size >= MAX_CACHED_LISTS)
+        credentialListCache.clear();
+    credentialListCache.set(envValue, result);
+    return result;
+}
+/** True when an `Authorization: Basic …` value decodes to one of `credentials`. */
+export function basicAuthorizationMatches(authorization, credentials) {
+    const match = authorization?.match(/^Basic\s+([A-Za-z0-9+/]+={0,2})$/i);
+    if (!match)
+        return false;
+    try {
+        const decoded = Uint8Array.from(atob(match[1]), (character) => character.charCodeAt(0));
+        return timingSafeCredentialMatch(new TextDecoder().decode(decoded), credentials);
+    }
+    catch {
+        return false;
+    }
+}
+/** Fail-closed decision for routes that require Basic auth: absent or malformed config is an error. */
+export function requiredBasicAuthDecision(authorization, envValue) {
+    const list = readBasicAuthCredentialList(envValue);
+    if (list.status === 'absent' || list.hasMalformedEntries || list.credentials.size === 0) {
+        return 'misconfigured';
+    }
+    return basicAuthorizationMatches(authorization, list.credentials) ? 'authorized' : 'unauthorized';
+}

package/dist/basic-auth.d.mts

@@ -0,0 +1,29 @@
+export type BasicAuthExemptMatcher = (method: string, pathname: string) => boolean;
+/**
+ * Builds a matcher from an injected `{ path: [methods] }` table. Paths compare lowercased with one
+ * trailing slash removed; methods compare uppercased. `extra` handles patterned paths.
+ */
+export declare function createBasicAuthExemptMatcher(methodsByPath: Readonly<Record<string, readonly string[]>>, extra?: BasicAuthExemptMatcher): BasicAuthExemptMatcher;
+export type BasicAuthGateOptions = {
+    /** Comma-separated `user:password` list; unset or blank disables the gate. */
+    credentials: string | undefined;
+    realm: string;
+    isExempt?: BasicAuthExemptMatcher;
+    /**
+     * Header carrying Basic credentials when `authorization` holds a Bearer token for another
+     * layer. Only honored in that Bearer-plus-secondary combination.
+     */
+    secondaryAuthorizationHeader?: string;
+    warn?: (message: string) => void;
+};
+export type BasicAuthGate = {
+    /** True when the gate is enabled and the request is not exempt. */
+    appliesTo: (request: Request) => boolean;
+    /** A 401 challenge, or null to pass the request through. */
+    check: (request: Request) => Response | null;
+};
+/**
+ * Staging-style Basic auth gate. A non-empty list with any malformed entry stays enabled and
+ * rejects every request (fail closed), warning once per gate.
+ */
+export declare function createBasicAuthGate(options: BasicAuthGateOptions): BasicAuthGate;

package/dist/basic-auth.mjs

@@ -0,0 +1,60 @@
+import { readBasicAuthCredentialList, basicAuthorizationMatches, } from './basic-auth-credentials.mjs';
+import { edgeErrorResponse } from './error-response.mjs';
+/**
+ * Builds a matcher from an injected `{ path: [methods] }` table. Paths compare lowercased with one
+ * trailing slash removed; methods compare uppercased. `extra` handles patterned paths.
+ */
+export function createBasicAuthExemptMatcher(methodsByPath, extra) {
+    const table = new Map(Object.entries(methodsByPath).map(([path, methods]) => [
+        path.toLowerCase(),
+        new Set(methods.map((method) => method.toUpperCase())),
+    ]));
+    return (method, pathname) => {
+        const trimmed = pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
+        const path = trimmed.toLowerCase();
+        return table.get(path)?.has(method.toUpperCase()) === true || extra?.(method, path) === true;
+    };
+}
+/**
+ * Staging-style Basic auth gate. A non-empty list with any malformed entry stays enabled and
+ * rejects every request (fail closed), warning once per gate.
+ */
+export function createBasicAuthGate(options) {
+    if (/["\\\r\n]/u.test(options.realm))
+        throw new Error('Invalid Basic auth realm');
+    const warn = options.warn ?? console.warn;
+    let warned = false;
+    const credentials = () => {
+        const list = readBasicAuthCredentialList(options.credentials);
+        if (list.status === 'absent')
+            return null;
+        if (!list.hasMalformedEntries)
+            return list.credentials;
+        if (!warned) {
+            warned = true;
+            warn('[Basic Auth] Rejecting malformed credential list (username and password must both be non-empty)');
+        }
+        return new Set();
+    };
+    const exempt = (request) => options.isExempt?.(request.method, new URL(request.url).pathname) === true;
+    return {
+        appliesTo: (request) => credentials() !== null && !exempt(request),
+        check(request) {
+            const allowed = credentials();
+            if (!allowed || exempt(request))
+                return null;
+            const primary = request.headers.get('authorization');
+            const secondary = options.secondaryAuthorizationHeader
+                ? request.headers.get(options.secondaryAuthorizationHeader)
+                : null;
+            const ordinaryBasic = primary !== null && /^Basic\s/i.test(primary) && secondary === null;
+            const dualBearer = primary !== null && /^Bearer\s+\S+$/i.test(primary) && secondary !== null;
+            const candidate = ordinaryBasic ? primary : dualBearer ? secondary : null;
+            if (basicAuthorizationMatches(candidate, allowed))
+                return null;
+            return edgeErrorResponse(401, 'Authentication required', 'UNAUTHORIZED', {
+                'www-authenticate': `Basic realm="${options.realm}", charset="UTF-8"`,
+            });
+        },
+    };
+}

package/dist/cache-policy.d.mts

@@ -0,0 +1,41 @@
+export type CacheMode = 'cache' | 'bypass';
+export type CachePolicy<Audience extends string = string> = {
+    mode: CacheMode;
+    /** Which audience a cached response targets; null on bypass. Partition cache keys by it. */
+    audience: Audience | null;
+    /** True when a bypassed response must not stay browser or intermediary cacheable. */
+    forceNoStore: boolean;
+    ttlSeconds: number;
+    staleWhileRevalidateSeconds: number;
+    stripCookieNames: ReadonlySet<string>;
+    stripAllCookies: boolean;
+};
+/** Pass the request to the origin untouched by any cache. */
+export declare function bypassPolicy<Audience extends string = string>(options?: {
+    forceNoStore?: boolean;
+    stripCookieNames?: ReadonlySet<string>;
+}): CachePolicy<Audience>;
+/** Serve an audience's response from the shared cache; cookies are stripped by default. */
+export declare function cachedPolicy<Audience extends string>(audience: Audience, ttlSeconds: number, options?: {
+    stripCookieNames?: ReadonlySet<string>;
+    stripAllCookies?: boolean;
+}): CachePolicy<Audience>;
+/** Parses a positive TTL from configuration, flooring it; anything else yields `fallback`. */
+export declare function toPositiveNumber(raw: string | undefined, fallback: number): number;
+/** Parses a comma-separated path list and merges it into `defaults` (never replaces them). */
+export declare function parsePathSet(raw: string | undefined, defaults?: Iterable<string>): Set<string>;
+/** Case-insensitive match of an exact path or any path below a prefix. */
+export declare function matchesPathPrefix(pathname: string, prefixes: readonly string[]): boolean;
+export declare function canUseCache(request: Request, mode: CacheMode): boolean;
+/** React Server Component fetch signal: `_rsc` param, `text/x-component` accept, or `rsc: 1`. */
+export declare function isRscRequest(request: Request, url: URL): boolean;
+export type CacheControlOptions = {
+    /** Multiplier applied to the TTL for `stale-while-revalidate`. Defaults to 2. */
+    staleWhileRevalidateFactor?: number;
+    /** Bound on serving stale content during origin errors. Defaults to one day. */
+    staleIfErrorSeconds?: number;
+};
+/** `cache-control` for a response whose only cache layer is the platform cache. */
+export declare function buildCacheControlHeader(ttlSeconds: number, options?: CacheControlOptions): string;
+/** A 2xx response without `set-cookie` or a private/no-store/no-cache directive. */
+export declare function isCacheableResponse(response: Response): boolean;

package/dist/cache-policy.mjs

@@ -0,0 +1,74 @@
+const EMPTY_SET = new Set();
+/** Pass the request to the origin untouched by any cache. */
+export function bypassPolicy(options = {}) {
+    return {
+        mode: 'bypass',
+        audience: null,
+        forceNoStore: options.forceNoStore ?? false,
+        ttlSeconds: 0,
+        staleWhileRevalidateSeconds: 0,
+        stripCookieNames: options.stripCookieNames ?? EMPTY_SET,
+        stripAllCookies: false,
+    };
+}
+/** Serve an audience's response from the shared cache; cookies are stripped by default. */
+export function cachedPolicy(audience, ttlSeconds, options = {}) {
+    return {
+        mode: 'cache',
+        audience,
+        forceNoStore: false,
+        ttlSeconds,
+        staleWhileRevalidateSeconds: ttlSeconds * 2,
+        stripCookieNames: options.stripCookieNames ?? EMPTY_SET,
+        stripAllCookies: options.stripAllCookies ?? true,
+    };
+}
+/** Parses a positive TTL from configuration, flooring it; anything else yields `fallback`. */
+export function toPositiveNumber(raw, fallback) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+/** Parses a comma-separated path list and merges it into `defaults` (never replaces them). */
+export function parsePathSet(raw, defaults = []) {
+    const extra = (raw ?? '')
+        .split(',')
+        .map((path) => path.trim())
+        .filter(Boolean);
+    return new Set([...defaults, ...extra]);
+}
+/** Case-insensitive match of an exact path or any path below a prefix. */
+export function matchesPathPrefix(pathname, prefixes) {
+    const normalized = pathname.toLowerCase();
+    return prefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
+}
+export function canUseCache(request, mode) {
+    return mode === 'cache' && request.method === 'GET';
+}
+/** React Server Component fetch signal: `_rsc` param, `text/x-component` accept, or `rsc: 1`. */
+export function isRscRequest(request, url) {
+    return (url.searchParams.has('_rsc') ||
+        (request.headers.get('accept') ?? '').toLowerCase().includes('text/x-component') ||
+        request.headers.get('rsc') === '1');
+}
+/** `cache-control` for a response whose only cache layer is the platform cache. */
+export function buildCacheControlHeader(ttlSeconds, options = {}) {
+    const factor = options.staleWhileRevalidateFactor ?? 2;
+    const staleIfError = options.staleIfErrorSeconds ?? 86_400;
+    return `public, max-age=${ttlSeconds}, stale-while-revalidate=${ttlSeconds * factor}, stale-if-error=${staleIfError}`;
+}
+function hasDisqualifyingCacheControl(headers) {
+    return (headers.get('cache-control') ?? '')
+        .split(',')
+        .map((part) => part.trim().toLowerCase())
+        .some((directive) => directive === 'private' || directive === 'no-store' || directive === 'no-cache');
+}
+/** A 2xx response without `set-cookie` or a private/no-store/no-cache directive. */
+export function isCacheableResponse(response) {
+    if (response.status < 200 || response.status >= 300)
+        return false;
+    if (hasDisqualifyingCacheControl(response.headers))
+        return false;
+    return !response.headers.has('set-cookie');
+}

package/dist/cache-url.d.mts

@@ -0,0 +1,9 @@
+/** Marketing and ad click-id parameters that never change response content. */
+export declare const DEFAULT_NO_VARY_SEARCH_PARAM_NAMES: readonly string[];
+/**
+ * Builds the canonical URL used as a platform-cache key: drops parameters that do not change the
+ * response, then sorts the rest so key order never fragments the cache.
+ */
+export declare function normalizeCacheUrl(rawUrl: string, options?: {
+    stripParams?: Iterable<string>;
+}): string;

package/dist/cache-url.mjs

@@ -0,0 +1,34 @@
+/** Marketing and ad click-id parameters that never change response content. */
+export const DEFAULT_NO_VARY_SEARCH_PARAM_NAMES = [
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_term',
+    'utm_content',
+    'gclid',
+    'gbraid',
+    'wbraid',
+    'dclid',
+    'fbclid',
+    'msclkid',
+    'ttclid',
+    'twclid',
+    'srsltid',
+    'igshid',
+    'igsh',
+    '_gl',
+    'mc_cid',
+    'mc_eid',
+];
+/**
+ * Builds the canonical URL used as a platform-cache key: drops parameters that do not change the
+ * response, then sorts the rest so key order never fragments the cache.
+ */
+export function normalizeCacheUrl(rawUrl, options = {}) {
+    const url = new URL(rawUrl);
+    for (const name of options.stripParams ?? DEFAULT_NO_VARY_SEARCH_PARAM_NAMES) {
+        url.searchParams.delete(name);
+    }
+    url.searchParams.sort();
+    return url.toString();
+}

package/dist/cache-vary.d.mts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_SAFE_CACHE_VARY_TOKENS: readonly string[];
+/**
+ * Returns canonical safe tokens, or null when the `Vary` value must not enter a shared cache
+ * (any token outside `allowed`, including `*`). Tokens compare case-insensitively.
+ */
+export declare function parseSafeCacheVary(value: string | null, allowed?: readonly string[]): string[] | null;
+/** Merges additions into a client-facing `Vary` value without respelling existing tokens. */
+export declare function mergeClientVary(existing: string | null, additions: readonly string[]): string | null;

package/dist/cache-vary.mjs

@@ -0,0 +1,46 @@
+export const DEFAULT_SAFE_CACHE_VARY_TOKENS = [
+    'Cookie',
+    'Authorization',
+    'Accept-Encoding',
+    'Accept-Language',
+];
+/**
+ * Returns canonical safe tokens, or null when the `Vary` value must not enter a shared cache
+ * (any token outside `allowed`, including `*`). Tokens compare case-insensitively.
+ */
+export function parseSafeCacheVary(value, allowed = DEFAULT_SAFE_CACHE_VARY_TOKENS) {
+    if (value === null)
+        return [];
+    const canonicalByKey = new Map(allowed.map((token) => [token.toLowerCase(), token]));
+    const tokens = [];
+    const seen = new Set();
+    for (const rawToken of value.split(',')) {
+        const key = rawToken.trim().toLowerCase();
+        if (!key)
+            continue;
+        const canonical = canonicalByKey.get(key);
+        if (!canonical)
+            return null;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        tokens.push(canonical);
+    }
+    return tokens;
+}
+/** Merges additions into a client-facing `Vary` value without respelling existing tokens. */
+export function mergeClientVary(existing, additions) {
+    const existingTokens = existing?.split(',').map((token) => token.trim()) ?? [];
+    if (existingTokens.some((token) => token === '*'))
+        return '*';
+    const merged = existingTokens.filter(Boolean);
+    const seen = new Set(merged.map((token) => token.toLowerCase()));
+    for (const token of additions) {
+        const key = token.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(token);
+    }
+    return merged.length > 0 ? merged.join(', ') : null;
+}

package/dist/cached-origin.d.mts

@@ -0,0 +1,42 @@
+import type { CacheContext } from '@cloudflare/workers-types';
+import { type CacheControlOptions } from './cache-policy.mts';
+/** Per-request headers that must not be frozen into bytes replayed to other clients. */
+export declare const SHARED_CACHE_VOLATILE_HEADERS: readonly string[];
+/** Copies headers for a shared cache entry, removing request-specific ones. */
+export declare function stripCacheHeaders(headers: Headers, volatile?: readonly string[]): Headers;
+export type FinalizeCachedOriginOptions = {
+    ttlSeconds: number;
+    /** Cache tags for the entry; used for purging. */
+    tags: readonly string[];
+    /**
+     * Header that carries the origin's `Vary` tokens inside the cache. The platform cache ignores
+     * `vary`, so the application re-reads this header on HIT to apply client-facing `Vary`.
+     */
+    internalVaryHeader: string;
+    /** `Vary` tokens that are safe to cache. Any other token makes the response uncacheable. */
+    safeVaryTokens?: readonly string[];
+    cacheControl?: CacheControlOptions;
+    /** Appended to `tags` when it returns true for the origin's own `Cache-Tag` value. */
+    isValidOriginTag?: (tag: string) => boolean;
+};
+/**
+ * Prepares an origin response for the shared cache: uncacheable responses get `private, no-store`;
+ * cacheable ones lose `set-cookie` and volatile headers and gain `cache-control`, the internal
+ * vary header, and `Cache-Tag`.
+ */
+export declare function finalizeCachedOriginResponse(originResponse: Response, options: FinalizeCachedOriginOptions): Response;
+/**
+ * Removes dispatch-only signals before building an origin request. A dispatch IP header is
+ * restored as `cf-connecting-ip` so downstream forwarding keeps the client address.
+ */
+export declare function stripDispatchOnlyHeaders(request: Request, options: {
+    dropHeaders: readonly string[];
+    ipHeader?: string;
+}): Request;
+/**
+ * Purges tags from the cache namespace of the current entrypoint. Throws when the execution
+ * context has no cache API, because a silent no-op would leave stale content serving.
+ */
+export declare function purgeCacheTags(context: {
+    cache?: CacheContext;
+}, tags: string[]): Promise<import("@cloudflare/workers-types").CachePurgeResult>;

package/dist/cached-origin.mjs

@@ -0,0 +1,74 @@
+import { buildCacheControlHeader, isCacheableResponse, } from './cache-policy.mjs';
+import { DEFAULT_SAFE_CACHE_VARY_TOKENS, parseSafeCacheVary } from './cache-vary.mjs';
+import { copyHeaders, withHeaders } from './headers.mjs';
+const PRIVATE_NO_STORE = { 'cache-control': 'private, no-store' };
+/** Per-request headers that must not be frozen into bytes replayed to other clients. */
+export const SHARED_CACHE_VOLATILE_HEADERS = [
+    'content-security-policy',
+    'content-security-policy-report-only',
+];
+/** Copies headers for a shared cache entry, removing request-specific ones. */
+export function stripCacheHeaders(headers, volatile = SHARED_CACHE_VOLATILE_HEADERS) {
+    const copied = copyHeaders(headers);
+    for (const name of volatile)
+        copied.delete(name);
+    return copied;
+}
+/**
+ * Prepares an origin response for the shared cache: uncacheable responses get `private, no-store`;
+ * cacheable ones lose `set-cookie` and volatile headers and gain `cache-control`, the internal
+ * vary header, and `Cache-Tag`.
+ */
+export function finalizeCachedOriginResponse(originResponse, options) {
+    if (!isCacheableResponse(originResponse))
+        return withHeaders(originResponse, PRIVATE_NO_STORE);
+    const varyTokens = parseSafeCacheVary(originResponse.headers.get('vary'), options.safeVaryTokens ?? DEFAULT_SAFE_CACHE_VARY_TOKENS);
+    const headers = stripCacheHeaders(originResponse.headers);
+    headers.delete(options.internalVaryHeader);
+    headers.delete('set-cookie');
+    const rebuild = () => new Response(originResponse.body, {
+        status: originResponse.status,
+        statusText: originResponse.statusText,
+        headers,
+    });
+    if (varyTokens === null) {
+        headers.set('cache-control', PRIVATE_NO_STORE['cache-control']);
+        return rebuild();
+    }
+    headers.delete('vary');
+    if (varyTokens.length > 0)
+        headers.set(options.internalVaryHeader, varyTokens.join(', '));
+    headers.set('cache-control', buildCacheControlHeader(options.ttlSeconds, options.cacheControl));
+    const tags = [...options.tags];
+    const originTag = originResponse.headers.get('Cache-Tag');
+    if (originTag && options.isValidOriginTag?.(originTag) && !tags.includes(originTag)) {
+        tags.push(originTag);
+    }
+    headers.set('Cache-Tag', tags.join(','));
+    return rebuild();
+}
+/**
+ * Removes dispatch-only signals before building an origin request. A dispatch IP header is
+ * restored as `cf-connecting-ip` so downstream forwarding keeps the client address.
+ */
+export function stripDispatchOnlyHeaders(request, options) {
+    const headers = new Headers(request.headers);
+    const ip = options.ipHeader ? headers.get(options.ipHeader) : null;
+    for (const name of options.dropHeaders)
+        headers.delete(name);
+    if (options.ipHeader)
+        headers.delete(options.ipHeader);
+    if (ip)
+        headers.set('cf-connecting-ip', ip);
+    return new Request(request, { headers });
+}
+/**
+ * Purges tags from the cache namespace of the current entrypoint. Throws when the execution
+ * context has no cache API, because a silent no-op would leave stale content serving.
+ */
+export async function purgeCacheTags(context, tags) {
+    if (!context.cache) {
+        throw new Error('Workers Cache purge API unavailable on this execution context');
+    }
+    return context.cache.purge({ tags });
+}

package/dist/client-info.d.mts

@@ -0,0 +1,33 @@
+export type WebBrowserRequest = {
+    method: string;
+    /** The request URL's origin. */
+    requestOrigin: string;
+};
+export declare function hasBrowserFetchMetadata(headers: Headers): boolean;
+/**
+ * Browser evidence that a request came from the web app on this origin, or from a top-level
+ * navigation. Forgeable by non-browser callers, so it only classifies telemetry.
+ */
+export declare function isWebBrowserRequest(headers: Headers, request: WebBrowserRequest): boolean;
+export type ClientInfoPolicy = {
+    /** Header the edge owns to mark synthetic traffic such as bots or cache fills. */
+    requestKindHeader: string;
+    /** Every header a client may use to describe itself; cleared when the edge cannot vouch. */
+    clientInfoHeaderNames: readonly string[];
+    /** Header whose `value` identifies the web client; used to drop forged web claims. */
+    webClientHeader: {
+        name: string;
+        value: string;
+    };
+    /** Headers set when browser evidence confirms the web client. */
+    webClientHeaders: Readonly<Record<string, string>>;
+};
+export type ClientInfoOptions = WebBrowserRequest & {
+    requestKind?: string;
+};
+/**
+ * Normalizes client-identification headers before forwarding. Synthetic traffic gets only the
+ * request-kind header; browser-evidenced traffic gets the injected web headers; anything else
+ * keeps non-web client headers and loses forged web claims.
+ */
+export declare function applyClientInfoHeaders(headers: Headers, policy: ClientInfoPolicy, options: ClientInfoOptions): void;