@lovrozagar/honey 0.1.0

package/src/context.ts

@@ -0,0 +1,210 @@
+import { isNodeOutbound } from "./honey-response.ts";
+import type { SSEOptions, SSEStream, TypedResponse } from "./response.ts";
+import { HoneyRes } from "./response.ts";
+import type { PendingTap } from "./types.ts";
+import { EMPTY_OBJ } from "./types.ts";
+import { parseCookies } from "./validation.ts";
+
+/**
+ * Per-request res with lazy lastEventId — only reads the header when SSE is actually called.
+ * All non-SSE methods (json/text/html/etc) are inherited from HoneyRes with zero overhead.
+ */
+class ContextRes extends HoneyRes {
+	private _req: Request;
+	private _lastEventId: string | undefined | false = false;
+
+	constructor(req: Request) {
+		super(isNodeOutbound(req));
+		this._req = req;
+	}
+
+	override sse(
+		callback: (stream: SSEStream) => Promise<void>,
+		opts?: SSEOptions,
+	): TypedResponse<"text/event-stream", "ok"> {
+		if (this._lastEventId === false) {
+			this._lastEventId = this._req.headers.get("last-event-id") ?? undefined;
+		}
+		return super.sse(callback, {
+			...opts,
+			lastEventId: opts?.lastEventId ?? this._lastEventId,
+		});
+	}
+}
+function parseSearch(ctx: HoneyContext): void {
+	const url = ctx._lzUrlFn ? ctx._lzUrlFn() : new URL(ctx.req.url);
+	const first: Record<string, string> = {};
+	const all: Record<string, string[]> = {};
+	for (const [key, value] of url.searchParams) {
+		if (first[key] === undefined) {
+			first[key] = value;
+			all[key] = [value];
+		} else {
+			const values = all[key];
+			if (values) {
+				values.push(value);
+			}
+		}
+	}
+	ctx._lzSearch = first;
+	ctx._lzSearchAll = all;
+}
+
+function bgSwallow(p: Promise<unknown>) {
+	p.catch(noop);
+}
+function noop() {}
+
+/**
+ * HoneyContext uses `declare` for properties set after construction and
+ * class-level getters for lazy-computed properties. No Object.defineProperty
+ * on the hot path — V8 optimizes class shapes via hidden classes.
+ *
+ * `declare` fields have no private brand, so Omit<HoneyContext, "res">
+ * works structurally for ApplyOutput type narrowing.
+ */
+export class HoneyContext<TEnv = Record<string, unknown>> {
+	readonly background: (p: Promise<unknown>) => void;
+	readonly env: TEnv;
+	readonly params: Record<string, string>;
+	readonly req: Request;
+	readonly res: HoneyRes;
+
+	/* set after construction — declare keeps them off the private brand */
+	declare readonly cookies: Record<string, string>;
+	declare readonly errors: Record<string, (...args: never[]) => unknown>;
+	declare readonly executionCtx:
+		| { waitUntil?: (p: Promise<unknown>) => void }
+		| undefined;
+	declare readonly headers: Record<string, string>;
+	declare readonly meta: Record<string, unknown>;
+	declare readonly path: string;
+	declare readonly realtime: { publish(topic: string, data: unknown): void };
+	declare readonly routePattern: string;
+	declare readonly search: Record<string, string>;
+	declare readonly searchAll: Record<string, string[]>;
+
+	/* backing state for lazy getters — stored directly on instance to avoid extra object allocation */
+	/** @internal */ _lzCookies: Record<string, string> | null;
+	/** @internal */ _lzHeaders: Record<string, string> | null;
+	/** @internal */ _lzSearch: Record<string, string> | null;
+	/** @internal */ _lzSearchAll: Record<string, string[]> | null;
+	/** @internal */ _lzUrlFn: (() => URL) | null;
+
+	/* error propagation — lets handler errors flow back through middleware chain */
+	/** @internal */ _errorToResponse:
+		| ((thrown: unknown) => Promise<Response>)
+		| null;
+	/** @internal */ _isErrorResponse: boolean;
+
+	/* tap side-effects — queued by c.tap(), drained after handler */
+	/** @internal */ _pendingTaps: PendingTap[] | null;
+
+	constructor(opts: {
+		env: TEnv;
+		executionCtx?: { waitUntil?: (p: Promise<unknown>) => void };
+		meta?: Record<string, unknown>;
+		params: Record<string, string>;
+		path?: string;
+		req: Request;
+		routePattern?: string;
+		urlFn?: () => URL;
+	}) {
+		this.req = opts.req;
+		this.env = opts.env;
+		this.params = opts.params;
+		this.res = new ContextRes(opts.req);
+
+		/* direct assignment — no defineProperty */
+		(this as Record<string, unknown>)["executionCtx"] = opts.executionCtx;
+		(this as Record<string, unknown>)["path"] = opts.path ?? "";
+		(this as Record<string, unknown>)["routePattern"] = opts.routePattern ?? "";
+		(this as Record<string, unknown>)["meta"] = opts.meta ?? EMPTY_OBJ;
+
+		/* invoke through executionCtx so `this` binds to the owning object — workerd's native ExecutionContext.waitUntil throws "Illegal invocation" when called detached */
+		const executionCtx = opts.executionCtx;
+		const waitUntil = executionCtx?.waitUntil;
+		this.background = waitUntil
+			? (p: Promise<unknown>) => {
+					waitUntil.call(executionCtx, p);
+				}
+			: bgSwallow;
+
+		/* lazy getter backing — flat on instance, no extra object */
+		this._lzCookies = null;
+		this._lzHeaders = null;
+		this._lzSearch = null;
+		this._lzSearchAll = null;
+		this._lzUrlFn = opts.urlFn ?? null;
+
+		/* error propagation */
+		this._errorToResponse = null;
+		this._isErrorResponse = false;
+
+		/* taps */
+		this._pendingTaps = null;
+	}
+
+	/** @internal */
+	_setErrors(errors: Record<string, (...args: never[]) => unknown>): void {
+		(this as { errors: typeof errors }).errors = errors;
+	}
+
+	/** Queue a side-effect to fire after handler returns successfully */
+	tap(key: string, payload: unknown): void {
+		if (this._pendingTaps === null) {
+			this._pendingTaps = [{ key, payload }];
+		} else {
+			this._pendingTaps.push({ key, payload });
+		}
+	}
+
+	/* lazy getters on prototype — V8 hidden class optimized, no per-instance defineProperty */
+
+	static {
+		Object.defineProperty(HoneyContext.prototype, "cookies", {
+			configurable: true,
+			enumerable: true,
+			get(this: HoneyContext): Record<string, string> {
+				if (this._lzCookies === null) {
+					this._lzCookies = parseCookies(this.req.headers.get("cookie") ?? "");
+				}
+				return this._lzCookies;
+			},
+		});
+		Object.defineProperty(HoneyContext.prototype, "headers", {
+			configurable: true,
+			enumerable: true,
+			get(this: HoneyContext): Record<string, string> {
+				if (this._lzHeaders === null) {
+					const h: Record<string, string> = {};
+					this.req.headers.forEach((value, key) => {
+						h[key] = value;
+					});
+					this._lzHeaders = h;
+				}
+				return this._lzHeaders;
+			},
+		});
+		Object.defineProperty(HoneyContext.prototype, "search", {
+			configurable: true,
+			enumerable: true,
+			get(this: HoneyContext): Record<string, string> {
+				if (this._lzSearch === null) {
+					parseSearch(this);
+				}
+				return this._lzSearch as Record<string, string>;
+			},
+		});
+		Object.defineProperty(HoneyContext.prototype, "searchAll", {
+			configurable: true,
+			enumerable: true,
+			get(this: HoneyContext): Record<string, string[]> {
+				if (this._lzSearchAll === null) {
+					parseSearch(this);
+				}
+				return this._lzSearchAll as Record<string, string[]>;
+			},
+		});
+	}
+}

package/src/cookie-sign.ts

@@ -0,0 +1,58 @@
+const encoder = new TextEncoder()
+
+function importKey(secret: string): Promise<CryptoKey> {
+	return crypto.subtle.importKey(
+		"raw",
+		encoder.encode(secret),
+		{ hash: "SHA-256", name: "HMAC" },
+		false,
+		["sign", "verify"],
+	)
+}
+
+function toBase64Url(buffer: ArrayBuffer): string {
+	const bytes = new Uint8Array(buffer)
+	let binary = ""
+	for (let i = 0; i < bytes.length; i++) {
+		binary += String.fromCharCode(bytes[i])
+	}
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+function fromBase64Url(str: string): Uint8Array {
+	const padded = str.replace(/-/g, "+").replace(/_/g, "/")
+	const binary = atob(padded)
+	const bytes = new Uint8Array(binary.length)
+	for (let i = 0; i < binary.length; i++) {
+		bytes[i] = binary.charCodeAt(i)
+	}
+	return bytes
+}
+
+export async function sign(value: string, secret: string): Promise<string> {
+	const key = await importKey(secret)
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(value))
+	return `${value}.${toBase64Url(signature)}`
+}
+
+export async function verify(signed: string, secrets: string[]): Promise<string | null> {
+	if (signed.length === 0) return null
+	const lastDot = signed.lastIndexOf(".")
+	if (lastDot === -1) return null
+
+	const value = signed.slice(0, lastDot)
+	const sig = fromBase64Url(signed.slice(lastDot + 1))
+
+	for (const secret of secrets) {
+		const key = await importKey(secret)
+		const valid = await crypto.subtle.verify(
+			"HMAC",
+			key,
+			sig.buffer as ArrayBuffer,
+			encoder.encode(value),
+		)
+		if (valid) return value
+	}
+
+	return null
+}

package/src/cookie.ts

@@ -0,0 +1,89 @@
+export type CookieOptions = {
+	domain?: string
+	expires?: Date
+	httpOnly?: boolean
+	maxAge?: number
+	path?: string
+	sameSite?: "lax" | "none" | "strict"
+	secure?: boolean
+	value: string
+}
+
+/**
+ * Percent-encode characters outside the RFC 6265 cookie-octet range.
+ * Cookie-octets: 0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E
+ */
+function encodeCookieValue(value: string): string {
+	let encoded = ""
+	for (const ch of value) {
+		const c = ch.codePointAt(0) ?? 0
+		if (
+			c === 0x21 ||
+			(c >= 0x23 && c <= 0x2b) ||
+			(c >= 0x2d && c <= 0x3a) ||
+			(c >= 0x3c && c <= 0x5b) ||
+			(c >= 0x5d && c <= 0x7e)
+		) {
+			encoded += ch
+		} else {
+			encoded += encodeURIComponent(ch)
+		}
+	}
+	return encoded
+}
+
+const validCookieNameRe = /^[\w!#$%&'*.^`|~+-]+$/
+
+export function serializeCookie(name: string, opts: CookieOptions): string {
+	if (!validCookieNameRe.test(name)) {
+		throw new Error(`Invalid cookie name: ${JSON.stringify(name)}`)
+	}
+
+	let secure = opts.secure
+	let path = opts.path
+
+	if (name.startsWith("__Host-")) {
+		if (!opts.secure) throw new Error("__Host- cookies require secure: true")
+		if (opts.domain) throw new Error("__Host- cookies must not set domain")
+		if (opts.path !== "/" && opts.path !== undefined) {
+			throw new Error("__Host- cookies must have path: '/'")
+		}
+		secure = true
+		path = path ?? "/"
+	} else if (name.startsWith("__Secure-")) {
+		if (!opts.secure) throw new Error("__Secure- cookies require secure: true")
+		secure = true
+	}
+
+	if (opts.sameSite === "none" && !secure) {
+		throw new Error("SameSite=None cookies require secure: true")
+	}
+
+	if (opts.domain && /[;\r\n]/.test(opts.domain)) {
+		throw new Error("Cookie domain contains invalid characters")
+	}
+	if (path && /[;\r\n]/.test(path)) {
+		throw new Error("Cookie path contains invalid characters")
+	}
+
+	let cookie = `${name}=${encodeCookieValue(opts.value)}`
+	if (opts.domain) cookie += `; Domain=${opts.domain}`
+	if (path) cookie += `; Path=${path}`
+	if (opts.maxAge !== undefined) {
+		if (!Number.isFinite(opts.maxAge) || opts.maxAge < 0) {
+			throw new Error(`Invalid cookie Max-Age: ${opts.maxAge}`)
+		}
+		cookie += `; Max-Age=${Math.floor(opts.maxAge)}`
+	}
+	if (opts.expires) {
+		if (Number.isNaN(opts.expires.getTime())) {
+			throw new Error("Invalid cookie Expires: date is invalid")
+		}
+		cookie += `; Expires=${opts.expires.toUTCString()}`
+	}
+	if (opts.httpOnly) cookie += "; HttpOnly"
+	if (secure) cookie += "; Secure"
+	if (opts.sameSite)
+		cookie += `; SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`
+	return cookie
+}

package/src/cors.ts

@@ -0,0 +1,96 @@
+import { replaceResponse } from "./honey-response.ts"
+import type { MiddlewareFn } from "./middleware.ts"
+
+export type CORSOptions = {
+	credentials?: boolean
+	exposeHeaders?: string[]
+	headers?: string[]
+	maxAge?: number
+	methods?: string[]
+	origin?: "*" | ((origin: string) => boolean) | string | string[]
+}
+
+const DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]
+const DEFAULT_MAX_AGE = 86400
+
+function matchOrigin(origin: string, config: CORSOptions["origin"]): string | null {
+	if (config === undefined || config === "*") return "*"
+	if (typeof config === "string") return config === origin ? origin : null
+	if (Array.isArray(config)) return config.includes(origin) ? origin : null
+	if (typeof config === "function") return config(origin) ? origin : null
+	return null
+}
+
+export function cors(options?: CORSOptions): MiddlewareFn<{ req: Request }, {}> {
+	const opts = options ?? {}
+
+	/* credentials + wildcard is a CORS spec violation — auto-narrow to echo origin */
+	const credentialWildcard =
+		opts.credentials === true && (opts.origin === undefined || opts.origin === "*")
+
+	const mw: MiddlewareFn<{ req: Request }, {}> = async (ctx, next) => {
+		const req = ctx.req
+		const requestOrigin = req.headers.get("origin")
+
+		/* no origin → not a CORS request */
+		if (requestOrigin === null) {
+			return next()
+		}
+
+		const allowedOrigin = credentialWildcard
+			? requestOrigin
+			: matchOrigin(requestOrigin, opts.origin)
+
+		/* origin not allowed */
+		if (allowedOrigin === null) {
+			return next()
+		}
+
+		const isPreflight = req.method === "OPTIONS" && req.headers.has("access-control-request-method")
+
+		/* Vary: Origin whenever response depends on the request origin (non-wildcard) */
+		const needsVary = allowedOrigin !== "*"
+
+		if (isPreflight) {
+			const corsHeaders = new Headers()
+			corsHeaders.set("access-control-allow-origin", allowedOrigin)
+			corsHeaders.set("access-control-allow-methods", (opts.methods ?? DEFAULT_METHODS).join(", "))
+			if (opts.headers && opts.headers.length > 0) {
+				corsHeaders.set("access-control-allow-headers", opts.headers.join(", "))
+			} else {
+				const requested = req.headers.get("access-control-request-headers")
+				if (requested) {
+					corsHeaders.set("access-control-allow-headers", requested)
+				}
+			}
+			corsHeaders.set("access-control-max-age", String(opts.maxAge ?? DEFAULT_MAX_AGE))
+			if (opts.credentials) {
+				corsHeaders.set("access-control-allow-credentials", "true")
+			}
+			if (needsVary) {
+				corsHeaders.set("vary", "Origin")
+			}
+			return new Response(null, { headers: corsHeaders, status: 204 })
+		}
+
+		/* simple/actual request */
+		const response = await next()
+		const headers = new Headers(response.headers)
+		headers.set("access-control-allow-origin", allowedOrigin)
+		if (opts.credentials) {
+			headers.set("access-control-allow-credentials", "true")
+		}
+		if (opts.exposeHeaders && opts.exposeHeaders.length > 0) {
+			headers.set("access-control-expose-headers", opts.exposeHeaders.join(", "))
+		}
+		if (needsVary) {
+			headers.append("vary", "Origin")
+		}
+		return replaceResponse(response, {
+			headers,
+			status: response.status,
+		})
+	}
+
+	return mw
+}

package/src/crypto.ts

@@ -0,0 +1,19 @@
+const encoder = new TextEncoder()
+
+let cachedKey: CryptoKey | null = null
+
+async function getKey(): Promise<CryptoKey> {
+	if (cachedKey === null) {
+		cachedKey = await crypto.subtle.generateKey({ hash: "SHA-256", name: "HMAC" }, false, [
+			"sign",
+			"verify",
+		])
+	}
+	return cachedKey
+}
+
+export async function timingSafeEqual(a: string, b: string): Promise<boolean> {
+	const key = await getKey()
+	const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(a))
+	return crypto.subtle.verify("HMAC", key, sig, encoder.encode(b))
+}

package/src/csrf.ts

@@ -0,0 +1,54 @@
+import { HoneyError } from "./error.ts"
+import type { MiddlewareFn } from "./middleware.ts"
+import { EK, SK } from "./types.ts"
+
+type CSRFOptions = {
+	origin?: ((origin: string) => boolean) | string | string[]
+}
+
+const safeMethodRe = /^(GET|HEAD|OPTIONS)$/
+const formContentTypeRe =
+	/^\b(application\/x-www-form-urlencoded|multipart\/form-data|text\/plain)\b/i
+
+function matchOrigin(origin: string, config: CSRFOptions["origin"]): boolean {
+	if (config === undefined) return false
+	if (typeof config === "string") return config === origin
+	if (Array.isArray(config)) return config.includes(origin)
+	return config(origin)
+}
+
+export function csrf(options?: CSRFOptions): MiddlewareFn<{ req: Request }, {}> {
+	const opts = options ?? {}
+
+	const mw: MiddlewareFn<{ req: Request }, {}> = (ctx, next) => {
+		const req = ctx.req
+
+		if (safeMethodRe.test(req.method)) {
+			return next()
+		}
+
+		const contentType = req.headers.get("content-type")
+		if (contentType === null || !formContentTypeRe.test(contentType)) {
+			return next()
+		}
+
+		/* check Sec-Fetch-Site first (modern browsers, unforgeable) */
+		const secFetchSite = req.headers.get("sec-fetch-site")
+		if (secFetchSite === "same-origin") {
+			return next()
+		}
+
+		/* fall back to Origin header */
+		const origin = req.headers.get("origin")
+		if (origin !== null && matchOrigin(origin, opts.origin)) {
+			return next()
+		}
+
+		throw new HoneyError({
+			errorKey: EK.forbidden,
+			status: SK.forbidden,
+		})
+	}
+
+	return mw
+}