@vouchington/edge 0.0.0-stage → 0.1.0

package/dist/proxy.d.mts

@@ -0,0 +1,34 @@
+/** Client-supplied forwarding and method-override headers an origin must never trust. */
+export declare const CLIENT_SUPPLIED_PROXY_HEADERS_TO_STRIP: readonly ['cf-connecting-ip', 'forwarded', 'true-client-ip', 'via', 'x-forwarded-for', 'x-forwarded-port', 'x-forwarded-prefix', 'x-forwarded-scheme', 'x-forwarded-server', 'x-forwarded-ssl', 'x-forwarded-uri', 'x-http-method', 'x-http-method-override', 'x-method-override', 'x-original-url', 'x-real-ip', 'x-rewrite-url'];
+/** Next.js internal headers that external clients must never send (middleware and cache CVEs). */
+export declare const NEXTJS_INTERNAL_HEADERS_TO_STRIP: readonly ['x-middleware-subrequest', 'x-middleware-subrequest-id', 'x-nextjs-data', 'x-now-route-matches', 'next-resume', 'next-action-nonce'];
+export type OriginRequestOptions = {
+    /** Absolute origin URL; only its protocol and host replace the request's. */
+    origin: string;
+    /** Cookie names removed before forwarding. */
+    stripCookieNames?: ReadonlySet<string>;
+    stripAllCookies?: boolean;
+    /** Path and query merged over the request URL (override query params win). */
+    pathOverride?: string | null;
+    requestId?: string;
+    requestIdHeader?: string;
+    /** Shared secret proving the request came through the Worker. Any client copy is removed. */
+    sharedSecret?: {
+        header: string;
+        value: string | undefined;
+    };
+    /** Keep a non-Basic `authorization` header (for example Bearer). Dropped by default. */
+    preserveNonBasicAuthorization?: boolean;
+    /** Keep a Basic `authorization` header. Dropped by default. */
+    preserveBasicAuthorization?: boolean;
+    /** Force `accept-encoding: identity`, required when the response enters a shared cache. */
+    forceIdentityEncoding?: boolean;
+    /** Hostnames that also get identity encoding (local development). */
+    identityEncodingHostnames?: readonly string[];
+    /** Extra headers deleted from the client request, for example identity or control headers. */
+    stripHeaders?: Iterable<string>;
+    /** Headers set last, after every strip. */
+    setHeaders?: Readonly<Record<string, string>>;
+};
+/** Builds the sanitized request forwarded to an origin. Redirects stay manual. */
+export declare function buildOriginRequest(request: Request, options: OriginRequestOptions): Request;

package/dist/proxy.mjs

@@ -0,0 +1,92 @@
+import { stripCookies } from './cookies.mjs';
+import { deleteHeaders } from './headers.mjs';
+const METHOD_WITHOUT_BODY = new Set(['GET', 'HEAD']);
+/** Client-supplied forwarding and method-override headers an origin must never trust. */
+export const CLIENT_SUPPLIED_PROXY_HEADERS_TO_STRIP = [
+    'cf-connecting-ip',
+    'forwarded',
+    'true-client-ip',
+    'via',
+    'x-forwarded-for',
+    'x-forwarded-port',
+    'x-forwarded-prefix',
+    'x-forwarded-scheme',
+    'x-forwarded-server',
+    'x-forwarded-ssl',
+    'x-forwarded-uri',
+    'x-http-method',
+    'x-http-method-override',
+    'x-method-override',
+    'x-original-url',
+    'x-real-ip',
+    'x-rewrite-url',
+];
+/** Next.js internal headers that external clients must never send (middleware and cache CVEs). */
+export const NEXTJS_INTERNAL_HEADERS_TO_STRIP = [
+    'x-middleware-subrequest',
+    'x-middleware-subrequest-id',
+    'x-nextjs-data',
+    'x-now-route-matches',
+    'next-resume',
+    'next-action-nonce',
+];
+/** Builds the sanitized request forwarded to an origin. Redirects stay manual. */
+export function buildOriginRequest(request, options) {
+    const original = new URL(request.url);
+    const originUrl = new URL(options.origin);
+    const url = new URL(request.url);
+    url.protocol = originUrl.protocol;
+    url.host = originUrl.host;
+    if (options.pathOverride) {
+        const override = new URL(options.pathOverride, url);
+        const merged = new URLSearchParams(url.search);
+        override.searchParams.forEach((value, key) => merged.set(key, value));
+        url.pathname = override.pathname;
+        url.search = merged.toString();
+    }
+    const headers = new Headers(request.headers);
+    const cookie = options.stripAllCookies
+        ? null
+        : stripCookies(headers.get('cookie'), options.stripCookieNames ?? []);
+    if (cookie)
+        headers.set('cookie', cookie);
+    else
+        headers.delete('cookie');
+    deleteHeaders(headers, CLIENT_SUPPLIED_PROXY_HEADERS_TO_STRIP);
+    deleteHeaders(headers, options.stripHeaders ?? []);
+    const requestIdHeader = options.requestIdHeader ?? 'x-request-id';
+    headers.delete(requestIdHeader);
+    if (options.sharedSecret)
+        headers.delete(options.sharedSecret.header);
+    const isBasic = /^basic\s/i.test(headers.get('authorization') ?? '');
+    if (isBasic ? !options.preserveBasicAuthorization : !options.preserveNonBasicAuthorization) {
+        headers.delete('authorization');
+    }
+    headers.set('x-forwarded-host', original.host);
+    headers.set('x-forwarded-proto', original.protocol.replace(':', ''));
+    const clientIp = request.headers.get('cf-connecting-ip');
+    if (clientIp)
+        headers.set('x-forwarded-for', clientIp);
+    const identityHosts = options.identityEncodingHostnames ?? ['localhost', '127.0.0.1'];
+    if (options.forceIdentityEncoding || identityHosts.includes(originUrl.hostname)) {
+        headers.set('accept-encoding', 'identity');
+    }
+    if (options.sharedSecret?.value)
+        headers.set(options.sharedSecret.header, options.sharedSecret.value);
+    if (options.requestId)
+        headers.set(requestIdHeader, options.requestId);
+    for (const [name, value] of Object.entries(options.setHeaders ?? {}))
+        headers.set(name, value);
+    const init = {
+        method: request.method,
+        headers,
+        // 'follow' would resolve redirects inside the Worker and hide them from the client.
+        redirect: 'manual',
+    };
+    if (!METHOD_WITHOUT_BODY.has(request.method)) {
+        init.body = request.body;
+        // Required by undici for streaming bodies; the Workers runtime ignores it.
+        init.duplex = 'half';
+    }
+    return new Request(url, init);
+}

package/dist/security-headers.d.mts

@@ -0,0 +1,25 @@
+export declare const DEFAULT_PERMISSIONS_POLICY: string;
+export declare const BASE_SECURITY_HEADERS: Readonly<Record<string, string>>;
+/** HSTS value. `preload` is effectively irreversible, so callers opt in explicitly. */
+export declare function buildHsts(includePreload?: boolean): string;
+export type SecurityHeadersOptions = {
+    /** Adds `strict-transport-security` when true. */
+    production?: boolean;
+    hstsPreload?: boolean;
+    /** Final `content-security-policy` value; omitted for API-style responses. */
+    csp?: string;
+    openerPolicy?: 'same-origin-allow-popups' | 'same-origin' | 'unsafe-none';
+    /**
+     * Honor an origin `referrer-policy: no-referrer` (only that value, only more restrictive).
+     * The caller decides which routes carry URL credentials.
+     */
+    preserveOriginNoReferrer?: boolean;
+    /** Replaces the base header set. Defaults to {@link BASE_SECURITY_HEADERS}. */
+    baseHeaders?: Readonly<Record<string, string>>;
+    /** Applied last, so callers can override any computed header. */
+    overrides?: Readonly<Record<string, string>>;
+};
+/** Returns the edge-authoritative security header set for one response. */
+export declare function buildSecurityHeaders(response: Response, options?: SecurityHeadersOptions): Record<string, string>;
+/** Overwrites response headers with {@link buildSecurityHeaders}, preserving `set-cookie`. */
+export declare function addSecurityHeaders(response: Response, options?: SecurityHeadersOptions): Response;

package/dist/security-headers.mjs

@@ -0,0 +1,68 @@
+import { withHeaders } from './headers.mjs';
+export const DEFAULT_PERMISSIONS_POLICY = [
+    'accelerometer',
+    'attribution-reporting',
+    'bluetooth',
+    'browsing-topics',
+    'camera',
+    'display-capture',
+    'gamepad',
+    'geolocation',
+    'gyroscope',
+    'hid',
+    'idle-detection',
+    'interest-cohort',
+    'join-ad-interest-group',
+    'local-fonts',
+    'magnetometer',
+    'microphone',
+    'midi',
+    'payment',
+    'run-ad-auction',
+    'screen-wake-lock',
+    'serial',
+    'speaker-selection',
+    'sync-xhr',
+    'usb',
+    'web-share',
+    'xr-spatial-tracking',
+]
+    .map((feature) => `${feature}=()`)
+    .join(', ');
+export const BASE_SECURITY_HEADERS = {
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'SAMEORIGIN',
+    'x-xss-protection': '0',
+    'referrer-policy': 'strict-origin-when-cross-origin',
+    'permissions-policy': DEFAULT_PERMISSIONS_POLICY,
+    'origin-agent-cluster': '?1',
+    'cross-origin-opener-policy': 'same-origin-allow-popups',
+    'cross-origin-resource-policy': 'same-origin',
+};
+/** HSTS value. `preload` is effectively irreversible, so callers opt in explicitly. */
+export function buildHsts(includePreload = false) {
+    return `max-age=63072000; includeSubDomains${includePreload ? '; preload' : ''}`;
+}
+/** Returns the edge-authoritative security header set for one response. */
+export function buildSecurityHeaders(response, options = {}) {
+    const headers = { ...(options.baseHeaders ?? BASE_SECURITY_HEADERS) };
+    if (options.production)
+        headers['strict-transport-security'] = buildHsts(options.hstsPreload);
+    if (options.csp)
+        headers['content-security-policy'] = options.csp;
+    if (options.openerPolicy)
+        headers['cross-origin-opener-policy'] = options.openerPolicy;
+    // Headers.get() comma-joins repeats, so match any token; that can only tighten the policy.
+    if (options.preserveOriginNoReferrer &&
+        response.headers
+            .get('referrer-policy')
+            ?.split(',')
+            .some((value) => value.trim().toLowerCase() === 'no-referrer')) {
+        headers['referrer-policy'] = 'no-referrer';
+    }
+    return { ...headers, ...options.overrides };
+}
+/** Overwrites response headers with {@link buildSecurityHeaders}, preserving `set-cookie`. */
+export function addSecurityHeaders(response, options = {}) {
+    return withHeaders(response, buildSecurityHeaders(response, options));
+}

package/dist/sentry-dsn.d.mts

@@ -0,0 +1,13 @@
+export type SentryDsnConfig = {
+    /** Canonical DSN URL. */
+    dsn: string;
+    envelopeUrl: string;
+    origin: string;
+    projectId: string;
+};
+/**
+ * Parses an `https://<public-key>@<host>/<project>` DSN into canonical parts. Rejects passwords,
+ * query, hash, non-numeric projects, and non-canonical paths so an envelope DSN can be compared to
+ * a configured one without accepting lookalike spellings. Returns undefined for invalid values.
+ */
+export declare function parseSentryDsn(raw: string | undefined): SentryDsnConfig | undefined;

package/dist/sentry-dsn.mjs

@@ -0,0 +1,38 @@
+/**
+ * Parses an `https://<public-key>@<host>/<project>` DSN into canonical parts. Rejects passwords,
+ * query, hash, non-numeric projects, and non-canonical paths so an envelope DSN can be compared to
+ * a configured one without accepting lookalike spellings. Returns undefined for invalid values.
+ */
+export function parseSentryDsn(raw) {
+    const value = raw?.trim();
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        const segments = url.pathname.split('/').filter(Boolean);
+        const projectId = segments.at(-1);
+        if (url.protocol !== 'https:' ||
+            !url.username ||
+            !/^[A-Za-z0-9_]+$/u.test(url.username) ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            !projectId ||
+            !/^\d+$/u.test(projectId)) {
+            return undefined;
+        }
+        const prefix = segments.slice(0, -1).join('/');
+        const base = prefix ? `${prefix}/` : '';
+        if (url.pathname !== `/${base}${projectId}`)
+            return undefined;
+        return {
+            dsn: url.toString(),
+            envelopeUrl: new URL(`/${base}api/${projectId}/envelope/`, url.origin).toString(),
+            origin: url.origin,
+            projectId,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/sentry-tunnel-diagnostics.d.mts

@@ -0,0 +1,17 @@
+export type SentryTunnelRejectReason = 'content_length_too_large' | 'body_too_large' | 'body_read_error' | 'invalid_envelope_header' | 'missing_dsn' | 'invalid_dsn' | 'configuration_unavailable' | 'dsn_not_allowed';
+export type SentryTunnelDiagnosticDetails = {
+    envelopeItemCount?: number;
+    envelopeItemTypes?: string[];
+    errorName?: string;
+    errorCauseName?: string;
+    errorCode?: string;
+    limitBytes?: number;
+    projectId?: string;
+};
+export type SentryTunnelLog = {
+    warn: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function logSentryTunnelRejection(log: SentryTunnelLog, request: Request, status: number, reason: SentryTunnelRejectReason, details?: SentryTunnelDiagnosticDetails): void;
+export declare function logSentryTunnelForwardFailure(log: SentryTunnelLog, request: Request, projectId: string, error: unknown, details?: SentryTunnelDiagnosticDetails): void;
+export declare function logSentryTunnelUpstreamResponse(log: SentryTunnelLog, request: Request, projectId: string, status: number, details?: SentryTunnelDiagnosticDetails): void;

package/dist/sentry-tunnel-diagnostics.mjs

@@ -0,0 +1,73 @@
+const ERROR_CODE_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/u;
+function requestDiagnostics(request) {
+    const rawLength = request.headers.get('content-length');
+    const length = rawLength === null ? undefined : Number(rawLength);
+    const ray = request.cf?.ray ?? request.headers.get('cf-ray');
+    return {
+        method: request.method,
+        requestPath: new URL(request.url).pathname,
+        ...(ray ? { cfRay: ray } : {}),
+        ...(typeof length === 'number' && Number.isFinite(length)
+            ? { contentLengthBytes: length }
+            : {}),
+    };
+}
+export function logSentryTunnelRejection(log, request, status, reason, details = {}) {
+    log.warn(JSON.stringify({
+        message: 'sentry_tunnel_rejected',
+        reason,
+        status,
+        ...requestDiagnostics(request),
+        ...details,
+    }));
+}
+export function logSentryTunnelForwardFailure(log, request, projectId, error, details = {}) {
+    log.error(JSON.stringify({
+        message: 'sentry_tunnel_forward_failed',
+        reason: 'sentry_fetch_error',
+        status: 502,
+        ...requestDiagnostics(request),
+        projectId,
+        ...details,
+        ...errorDiagnostics(error),
+    }));
+}
+export function logSentryTunnelUpstreamResponse(log, request, projectId, status, details = {}) {
+    log.warn(JSON.stringify({
+        message: 'sentry_tunnel_upstream_response',
+        reason: 'sentry_upstream_non_2xx',
+        status,
+        ...requestDiagnostics(request),
+        projectId,
+        ...details,
+    }));
+}
+/** Only error names and bounded codes are logged; messages may carry request data. */
+function errorDiagnostics(error) {
+    const details = { errorName: errorName(error) ?? typeof error };
+    const code = safeErrorCode(error);
+    if (code !== undefined)
+        details.errorCode = code;
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (cause !== undefined && cause !== null) {
+        const causeName = errorName(cause);
+        if (causeName !== undefined)
+            details.errorCauseName = causeName;
+        const causeCode = safeErrorCode(cause);
+        if (details.errorCode === undefined && causeCode !== undefined)
+            details.errorCode = causeCode;
+    }
+    return details;
+}
+function errorName(error) {
+    return error instanceof Error && typeof error.name === 'string' ? error.name : undefined;
+}
+function safeErrorCode(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const code = error.code;
+    if (typeof code !== 'string' && typeof code !== 'number')
+        return undefined;
+    const normalized = String(code);
+    return ERROR_CODE_PATTERN.test(normalized) ? normalized : undefined;
+}

package/dist/sentry-tunnel.d.mts

@@ -0,0 +1,17 @@
+import { type SentryTunnelLog } from './sentry-tunnel-diagnostics.mts';
+export type SentryTunnelOptions = {
+    /** Raw DSNs the tunnel may forward to. Invalid and missing entries are ignored. */
+    trustedDsns: readonly (string | undefined)[];
+    /** Envelope size cap. Defaults to 1,000,000 bytes. */
+    maxBytes?: number;
+    /** Distinct item types recorded in failure diagnostics. Defaults to 8. */
+    maxItemTypes?: number;
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    log?: SentryTunnelLog;
+};
+/**
+ * Builds a handler that proxies browser Sentry envelopes to trusted DSNs, bypassing ad-blockers.
+ * The DSN in each envelope header must match a trusted DSN exactly. Upstream responses are not
+ * forwarded; only the status is, so Sentry rate-limit headers never reach browsers.
+ */
+export declare function createSentryTunnel(options: SentryTunnelOptions): (request: Request) => Promise<Response>;

package/dist/sentry-tunnel.mjs

@@ -0,0 +1,104 @@
+import { getSentryEnvelopeDiagnostics } from '@vouchington/utils/sentry-envelope';
+import { edgeErrorResponse, withFailureNoStoreHeaders } from './error-response.mjs';
+import { parseSentryDsn } from './sentry-dsn.mjs';
+import { logSentryTunnelForwardFailure, logSentryTunnelRejection, logSentryTunnelUpstreamResponse, } from './sentry-tunnel-diagnostics.mjs';
+async function readEnvelopeWithLimit(request, maxBytes) {
+    if (!request.body)
+        return { kind: 'ok', envelope: '' };
+    try {
+        const reader = request.body.getReader();
+        const decoder = new TextDecoder();
+        const chunks = [];
+        let bytesRead = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                chunks.push(decoder.decode());
+                return { kind: 'ok', envelope: chunks.join('') };
+            }
+            bytesRead += value.byteLength;
+            if (bytesRead > maxBytes) {
+                reader.cancel().catch(() => { });
+                return { kind: 'too-large' };
+            }
+            chunks.push(decoder.decode(value, { stream: true }));
+        }
+    }
+    catch {
+        return { kind: 'read-error' };
+    }
+}
+/**
+ * Builds a handler that proxies browser Sentry envelopes to trusted DSNs, bypassing ad-blockers.
+ * The DSN in each envelope header must match a trusted DSN exactly. Upstream responses are not
+ * forwarded; only the status is, so Sentry rate-limit headers never reach browsers.
+ */
+export function createSentryTunnel(options) {
+    const maxBytes = options.maxBytes ?? 1_000_000;
+    const maxItemTypes = options.maxItemTypes ?? 8;
+    const log = options.log ?? console;
+    const send = options.fetch ?? fetch;
+    const trusted = options.trustedDsns
+        .map(parseSentryDsn)
+        .filter((dsn) => dsn !== undefined);
+    const diagnostics = (envelope) => getSentryEnvelopeDiagnostics(envelope, { maxBytes, maxItemTypes });
+    return async function handleSentryTunnel(request) {
+        const reject = (status, message, code, reason, details) => {
+            logSentryTunnelRejection(log, request, status, reason, details);
+            return edgeErrorResponse(status, message, code);
+        };
+        if (trusted.length === 0) {
+            return reject(503, 'Service Unavailable', 'SERVICE_UNAVAILABLE', 'configuration_unavailable');
+        }
+        const contentLength = request.headers.get('content-length');
+        if (contentLength !== null && Number(contentLength) > maxBytes) {
+            return reject(413, 'Payload Too Large', 'INVALID_INPUT', 'content_length_too_large', {
+                limitBytes: maxBytes,
+            });
+        }
+        const read = await readEnvelopeWithLimit(request, maxBytes);
+        if (read.kind === 'too-large') {
+            return reject(413, 'Payload Too Large', 'INVALID_INPUT', 'body_too_large', {
+                limitBytes: maxBytes,
+            });
+        }
+        if (read.kind === 'read-error') {
+            return reject(400, 'Bad Request', 'INVALID_INPUT', 'body_read_error');
+        }
+        const { envelope } = read;
+        let header;
+        try {
+            header = JSON.parse(envelope.split('\n')[0]);
+        }
+        catch {
+            return reject(400, 'Invalid envelope header', 'INVALID_INPUT', 'invalid_envelope_header');
+        }
+        const dsn = typeof header === 'object' && header !== null
+            ? header.dsn
+            : undefined;
+        if (typeof dsn !== 'string')
+            return reject(400, 'Missing DSN', 'INVALID_INPUT', 'missing_dsn');
+        const envelopeDsn = parseSentryDsn(dsn);
+        if (!envelopeDsn)
+            return reject(400, 'Invalid DSN', 'INVALID_INPUT', 'invalid_dsn');
+        const target = trusted.find((candidate) => candidate.dsn === envelopeDsn.dsn);
+        if (!target)
+            return reject(403, 'Forbidden', 'FORBIDDEN', 'dsn_not_allowed');
+        let upstream;
+        try {
+            upstream = await send(target.envelopeUrl, {
+                method: 'POST',
+                body: envelope,
+                headers: { 'content-type': 'application/x-sentry-envelope' },
+            });
+        }
+        catch (error) {
+            logSentryTunnelForwardFailure(log, request, target.projectId, error, diagnostics(envelope));
+            return edgeErrorResponse(502, 'Bad Gateway', 'BAD_GATEWAY');
+        }
+        if (upstream.status < 200 || upstream.status >= 300) {
+            logSentryTunnelUpstreamResponse(log, request, target.projectId, upstream.status, diagnostics(envelope));
+        }
+        return withFailureNoStoreHeaders(new Response(null, { status: upstream.status }));
+    };
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@vouchington/edge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cloudflare Worker builders: security headers, CSP, basic auth, origin proxying, cache policy, and a Sentry tunnel.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/edge#readme",
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/edge"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@vouchington/utils": "^0.6.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261016.1"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^5.20261016.1"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}