okengine 0.5.0 → 0.6.0

package/src/plugins/index.ts

@@ -16,9 +16,14 @@ export {
 } from "./config-source.ts";
 export { cors, type CorsOptions } from "./cors.ts";
 export { csrf, type CsrfOptions } from "./csrf.ts";
-export { emailOtp, type EmailOtpOptions } from "./email-otp.ts";
+export { emailOtp, emailOtpCatalog, emailOtpTemplate, type EmailOtpOptions } from "./email-otp.ts";
 export { ipAllowlist, type IpAllowlistOptions } from "./ip-allowlist.ts";
-export { magicLink, type MagicLinkOptions } from "./magic-link.ts";
+export {
+  magicLink,
+  magicLinkCatalog,
+  magicLinkTemplate,
+  type MagicLinkOptions,
+} from "./magic-link.ts";
 export { maintenanceMode, type MaintenanceModeOptions } from "./maintenance-mode.ts";
 export {
   createPasskeyStore,
@@ -27,6 +32,14 @@ export {
   type PasskeyOptions,
   type PasskeyStore,
 } from "./passkey.ts";
+export {
+  b64urlDecode,
+  b64urlEncode,
+  buildAuthenticatorData,
+  signWebAuthnAssertion,
+  verifyWebAuthnCeremony,
+  type WebAuthnVerifyOptions,
+} from "./passkey-webauthn.ts";
 export {
   createPhoneStore,
   phoneNumber,
@@ -35,11 +48,11 @@ export {
 } from "./phone-number.ts";
 export {
   defaultCspDirectives,
-  securityHeaders,
+  headers,
   type CspOptions,
+  type HeadersOptions,
   type HstsOptions,
-  type SecurityHeadersOptions,
-} from "./security-headers.ts";
+} from "./headers.ts";
 export {
   createTwoFactorStore,
   twoFactor,
@@ -49,9 +62,18 @@ export {
   type TwoFactorStore,
 } from "./two-factor.ts";
 export {
+  assertUsernamePolicy,
   createUsernameStore,
+  DEFAULT_RESERVED_USERNAMES,
+  DEFAULT_USERNAME_ALLOWED_CHARS,
+  DEFAULT_USERNAME_MAX_LENGTH,
+  DEFAULT_USERNAME_MIN_LENGTH,
+  resolveUsernamePolicy,
   username,
+  UsernamePolicyError,
+  type ResolvedUsernamePolicy,
   type UsernamePluginOptions,
+  type UsernamePolicyOptions,
   type UsernameRow,
   type UsernameStore,
 } from "./username.ts";

package/src/plugins/magic-link.ts

@@ -1,8 +1,9 @@
 /**
  * Magic-link Gate auth method plugin.
  *
- * Delivery via Channel is optional in v1 — when {@link MagicLinkOptions.exposeDevToken}
- * is set, the request response includes `devToken` for tests / local DX.
+ * Delivers the one-time token via Channel (`fx.send` + `auth-magic-link`
+ * template). {@link MagicLinkOptions.exposeDevToken} remains available for
+ * local DX without Mailpit / SMTP.
  */
 
 import {
@@ -18,6 +19,7 @@ import {
   putVerification,
   type VerificationStore,
 } from "../auth/verification.ts";
+import { channel } from "../elements/channel.ts";
 import { plugin, type PluginDef } from "../kernel/plugin.ts";
 import {
   AuthFailed,
@@ -32,6 +34,35 @@ import {
 } from "./auth/shared.ts";
 
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_FROM = "OKE <no-reply@oke.local>";
+const DEFAULT_BASE_URL = "http://127.0.0.1:6530";
+
+/** Channel template for magic-link delivery. */
+export const magicLinkTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-magic-link", {
+  description: "Magic-link sign-in email",
+  schema: z.object({
+    email: z.string(),
+    token: z.string(),
+    link: z.string(),
+  }),
+  locales: ["en", "ar"],
+});
+
+/** Default EN/AR bodies for {@link magicLinkTemplate}. */
+export const magicLinkCatalog = {
+  "auth-magic-link": {
+    en: {
+      subject: "Your sign-in link",
+      text: "Sign in with this link:\n{{link}}\n\nOr enter this token:\n{{token}}\n",
+      html: '<p>Sign in with this link:</p><p><a href="{{link}}">{{link}}</a></p><p>Or enter this token:</p><p><code>{{token}}</code></p>',
+    },
+    ar: {
+      subject: "رابط تسجيل الدخول",
+      text: "سجّل الدخول عبر هذا الرابط:\n{{link}}\n\nأو أدخل هذا الرمز:\n{{token}}\n",
+      html: '<p dir="rtl">سجّل الدخول عبر هذا الرابط:</p><p dir="rtl"><a href="{{link}}">{{link}}</a></p><p dir="rtl">أو أدخل هذا الرمز:</p><p dir="rtl"><code>{{token}}</code></p>',
+    },
+  },
+} as const;
 
 /** Options for {@link magicLink}. */
 export interface MagicLinkOptions extends AuthMethodOptions {
@@ -43,6 +74,13 @@ export interface MagicLinkOptions extends AuthMethodOptions {
   readonly verifications?: VerificationStore;
   /** Return raw token in the request response (test / local). */
   readonly exposeDevToken?: boolean;
+  /**
+   * App origin used to build the magic link (default `OKE_APP_URL` or
+   * `http://127.0.0.1:6530`).
+   */
+  readonly baseUrl?: string;
+  /** Override the template `from` address. */
+  readonly from?: string;
 }
 
 /**
@@ -55,6 +93,19 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
   const identities = opts.identities ?? createIdentityStore();
   const verifications = opts.verifications ?? createVerificationStore();
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const baseUrl = (opts.baseUrl ?? process.env.OKE_APP_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const tmpl =
+    opts.from !== undefined
+      ? channel.email({ from: opts.from }).template("auth-magic-link", {
+          description: "Magic-link sign-in email",
+          schema: z.object({
+            email: z.string(),
+            token: z.string(),
+            link: z.string(),
+          }),
+          locales: ["en", "ar"],
+        })
+      : magicLinkTemplate;
 
   const request = flow({
     name: "auth.requestMagicLink",
@@ -66,7 +117,8 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
       devToken: z.string().optional(),
     }),
     errors: { AuthFailed, AuthRateLimited },
-    do: async (input) => {
+    effects: { sends: ["auth-magic-link"] },
+    do: async (input, fx) => {
       const email = normalizeEmail(input.email);
       if (!email.includes("@")) return fail("AuthFailed", { reason: "invalid_email" });
       const token = `ml_${crypto.randomUUID().replace(/-/g, "")}`;
@@ -80,6 +132,11 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
         consumedAt: null,
         attempts: 0,
       });
+      const link = `${baseUrl}/auth/magic-link/verify?token=${encodeURIComponent(token)}`;
+      await fx.send(tmpl, {
+        to: email,
+        data: { email, token, link },
+      });
       return {
         ok: true as const,
         ...(opts.exposeDevToken ? { devToken: token } : {}),
@@ -136,6 +193,9 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
 
   return plugin("magicLink", { version: "0.0.1", config: { method: "magic-link" } })
     .needs("auth")
+    .needs("channel")
+    .channelTemplate(tmpl)
+    .channelCatalog(magicLinkCatalog)
     .binding(bindPublicAuth("/magic-link/request", request, "otp"))
     .binding(bindPublicAuth("/magic-link/verify", verify, "otp"));
 }

package/src/plugins/passkey-webauthn.ts

@@ -0,0 +1,217 @@
+/**
+ * Minimal WebAuthn assertion / registration verifier (ES256 / P-256).
+ *
+ * Validates clientDataJSON (type · challenge · origin), authenticatorData
+ * (rpId hash · user-presence), and ECDSA signature over
+ * `authenticatorData || SHA-256(clientDataJSON)` against a stored SPKI public key.
+ */
+
+import { constantTimeEqual } from "../auth/constant-time.ts";
+
+/** Result of a failed WebAuthn verify. */
+export type WebAuthnVerifyFailure = {
+  readonly ok: false;
+  readonly reason: string;
+};
+
+/** Successful assertion verify (with updated sign counter). */
+export type WebAuthnVerifySuccess = {
+  readonly ok: true;
+  readonly signCount: number;
+};
+
+/** Options for {@link verifyWebAuthnCeremony}. */
+export interface WebAuthnVerifyOptions {
+  readonly expectedType: "webauthn.create" | "webauthn.get";
+  readonly expectedChallenge: string;
+  readonly expectedOrigins: readonly string[];
+  readonly rpId: string;
+  /** Base64url SPKI (SubjectPublicKeyInfo) of the credential public key. */
+  readonly publicKeySpkiB64url: string;
+  /** Base64url clientDataJSON bytes. */
+  readonly clientDataJSON: string;
+  /** Base64url authenticatorData bytes. */
+  readonly authenticatorData: string;
+  /** Base64url ECDSA P-1363 signature. */
+  readonly signature: string;
+  /** Previous stored sign counter (authenticate only). */
+  readonly previousSignCount?: number;
+}
+
+/**
+ * Verify a WebAuthn create/get ceremony payload.
+ *
+ * @param opts - Expected RP values + assertion fields
+ */
+export async function verifyWebAuthnCeremony(
+  opts: WebAuthnVerifyOptions,
+): Promise<WebAuthnVerifySuccess | WebAuthnVerifyFailure> {
+  let clientDataBytes: Uint8Array;
+  let authData: Uint8Array;
+  let signature: Uint8Array;
+  try {
+    clientDataBytes = b64urlDecode(opts.clientDataJSON);
+    authData = b64urlDecode(opts.authenticatorData);
+    signature = b64urlDecode(opts.signature);
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  if (authData.length < 37) return { ok: false, reason: "invalid_credentials" };
+
+  let clientData: { type?: unknown; challenge?: unknown; origin?: unknown };
+  try {
+    clientData = JSON.parse(new TextDecoder().decode(clientDataBytes)) as typeof clientData;
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  if (typeof clientData.type !== "string" || clientData.type !== opts.expectedType) {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (typeof clientData.challenge !== "string") {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (!constantTimeEqual(clientData.challenge, opts.expectedChallenge)) {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (typeof clientData.origin !== "string") {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (!opts.expectedOrigins.includes(clientData.origin)) {
+    return { ok: false, reason: "invalid_origin" };
+  }
+
+  const rpHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(opts.rpId)),
+  );
+  for (let i = 0; i < 32; i++) {
+    if (authData[i] !== rpHash[i]) return { ok: false, reason: "invalid_credentials" };
+  }
+
+  const flags = authData[32]!;
+  // User Present (bit 0) required.
+  if ((flags & 0x01) === 0) return { ok: false, reason: "invalid_credentials" };
+
+  const signCount =
+    ((authData[33]! << 24) | (authData[34]! << 16) | (authData[35]! << 8) | authData[36]!) >>> 0;
+
+  if (opts.previousSignCount !== undefined) {
+    // Spec: if both non-zero, authenticator count must strictly increase.
+    if (opts.previousSignCount > 0 && signCount > 0 && signCount <= opts.previousSignCount) {
+      return { ok: false, reason: "invalid_credentials" };
+    }
+  }
+
+  const clientDataHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", asBufferSource(clientDataBytes)),
+  );
+  const signed = new Uint8Array(authData.length + clientDataHash.length);
+  signed.set(authData, 0);
+  signed.set(clientDataHash, authData.length);
+
+  let key: CryptoKey;
+  try {
+    key = await crypto.subtle.importKey(
+      "spki",
+      asBufferSource(b64urlDecode(opts.publicKeySpkiB64url)),
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"],
+    );
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  const valid = await crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    asBufferSource(signature),
+    asBufferSource(signed),
+  );
+  if (!valid) return { ok: false, reason: "invalid_credentials" };
+
+  return { ok: true, signCount };
+}
+
+/**
+ * Encode bytes as unpadded base64url.
+ *
+ * @param bytes - Raw bytes
+ */
+export function b64urlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Decode unpadded base64url to bytes.
+ *
+ * @param input - Base64url string
+ */
+export function b64urlDecode(input: string): Uint8Array<ArrayBuffer> {
+  const pad = "=".repeat((4 - (input.length % 4)) % 4);
+  const b64 = (input + pad).replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Build minimal authenticatorData (rpIdHash · flags · signCount).
+ *
+ * @param rpId - Relying party id
+ * @param signCount - Counter
+ * @param flags - Flag byte (default UP=0x01)
+ */
+export async function buildAuthenticatorData(
+  rpId: string,
+  signCount: number,
+  flags = 0x01,
+): Promise<Uint8Array> {
+  const rpHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(rpId)),
+  );
+  const out = new Uint8Array(37);
+  out.set(rpHash, 0);
+  out[32] = flags;
+  out[33] = (signCount >>> 24) & 0xff;
+  out[34] = (signCount >>> 16) & 0xff;
+  out[35] = (signCount >>> 8) & 0xff;
+  out[36] = signCount & 0xff;
+  return out;
+}
+
+/**
+ * Sign `authenticatorData || SHA-256(clientDataJSON)` with an ECDSA P-256 key.
+ *
+ * @param privateKey - Signer
+ * @param authenticatorData - Auth data bytes
+ * @param clientDataJSON - Raw clientDataJSON bytes
+ */
+export async function signWebAuthnAssertion(
+  privateKey: CryptoKey,
+  authenticatorData: Uint8Array,
+  clientDataJSON: Uint8Array,
+): Promise<Uint8Array> {
+  const clientDataHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", asBufferSource(clientDataJSON)),
+  );
+  const signed = new Uint8Array(authenticatorData.length + clientDataHash.length);
+  signed.set(authenticatorData, 0);
+  signed.set(clientDataHash, authenticatorData.length);
+  return new Uint8Array(
+    await crypto.subtle.sign(
+      { name: "ECDSA", hash: "SHA-256" },
+      privateKey,
+      asBufferSource(signed),
+    ),
+  );
+}
+
+/** Fresh buffer for Web Crypto `BufferSource` typing. */
+function asBufferSource(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(bytes);
+}

package/src/plugins/passkey.ts

@@ -1,11 +1,12 @@
 /**
- * Passkey (WebAuthn-shaped) Gate auth method plugin — simplified v1 ceremony.
+ * Passkey (WebAuthn) Gate auth method plugin.
  *
- * Registration / authentication accept attestation-like payloads for tests
- * without a full WebAuthn library. Production should replace the ceremony
- * with a standards-compliant verifier.
+ * Registration and authentication verify clientDataJSON origin + challenge,
+ * authenticatorData rpId hash, and ECDSA P-256 signature against the stored
+ * SPKI public key. Presence-only authenticate is rejected.
  */
 
+import { constantTimeEqual } from "../auth/constant-time.ts";
 import {
   createVerificationStore,
   hashChallenge,
@@ -26,11 +27,13 @@ import {
   z,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
+import { verifyWebAuthnCeremony } from "./passkey-webauthn.ts";
 
-/** Stored passkey credential (simplified). */
+/** Stored passkey credential. */
 export interface PasskeyCredential {
   readonly credentialId: string;
   readonly userId: string;
+  /** Base64url SPKI public key (ECDSA P-256). */
   readonly publicKey: string;
   counter: number;
   readonly createdAt: number;
@@ -55,18 +58,34 @@ export interface PasskeyOptions extends AuthMethodOptions {
   readonly challenges?: VerificationStore;
   /** Relying party id (default `localhost`). */
   readonly rpId?: string;
+  /**
+   * Allowed `clientDataJSON.origin` values.
+   * Default: `http://localhost` and `https://localhost`.
+   */
+  readonly origins?: readonly string[];
 }
 
+const CeremonyIn = z.object({
+  credentialId: z.string().min(1),
+  publicKey: z.string().min(1).optional(),
+  userId: z.string().min(1).optional(),
+  challenge: z.string().min(1),
+  clientDataJSON: z.string().min(1),
+  authenticatorData: z.string().min(1),
+  signature: z.string().min(1),
+});
+
 /**
- * Passkey register / authenticate options + simplified ceremony (`oke_passkeys`).
+ * Passkey register / authenticate with cryptographic WebAuthn verify (`oke_passkeys`).
  *
- * @param opts - Stores / RP id
+ * @param opts - Stores / RP id / allowed origins
  */
 export function passkey(opts: PasskeyOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
   const passkeys = opts.passkeys ?? createPasskeyStore();
   const challenges = opts.challenges ?? createVerificationStore();
   const rpId = opts.rpId ?? "localhost";
+  const origins = opts.origins ?? ["http://localhost", "https://localhost"];
 
   const registerOptions = flow({
     name: "auth.passkeyRegisterOptions",
@@ -100,11 +119,9 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
     name: "auth.passkeyRegister",
     unit: "auth",
     plane: "user",
-    in: z.object({
-      credentialId: z.string().min(1),
+    in: CeremonyIn.extend({
       publicKey: z.string().min(1),
       userId: z.string().min(1),
-      challenge: z.string().optional(),
     }),
     out: z.object({ ok: z.literal(true) }),
     errors: { AuthFailed },
@@ -113,20 +130,28 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
       if (!sessionUser || sessionUser !== input.userId) {
         return fail("AuthFailed", { reason: "unauthenticated" });
       }
-      if (input.challenge) {
-        const hash = await hashChallenge(input.challenge);
-        const now = runtime.now();
-        let found = false;
-        for (const row of challenges.rows.values()) {
-          if (row.identifier !== `passkey-reg:${input.userId}`) continue;
-          if (row.consumedAt !== null || row.expiresAt <= now) continue;
-          if (row.value === hash) {
-            row.consumedAt = now;
-            found = true;
-            break;
-          }
-        }
-        if (!found) return fail("AuthFailed", { reason: "invalid_credentials" });
+      const consumed = await consumeChallenge(
+        challenges,
+        `passkey-reg:${input.userId}`,
+        input.challenge,
+        runtime.now(),
+      );
+      if (!consumed) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const verified = await verifyWebAuthnCeremony({
+        expectedType: "webauthn.create",
+        expectedChallenge: input.challenge,
+        expectedOrigins: origins,
+        rpId,
+        publicKeySpkiB64url: input.publicKey,
+        clientDataJSON: input.clientDataJSON,
+        authenticatorData: input.authenticatorData,
+        signature: input.signature,
+      });
+      if (!verified.ok) {
+        return fail("AuthFailed", {
+          reason: verified.reason === "invalid_origin" ? "invalid_origin" : "invalid_credentials",
+        });
       }
       if (passkeys.byCredentialId.has(input.credentialId)) {
         return fail("AuthFailed", { reason: "invalid_credentials" });
@@ -135,7 +160,7 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
         credentialId: input.credentialId,
         userId: input.userId,
         publicKey: input.publicKey,
-        counter: 0,
+        counter: verified.signCount,
         createdAt: runtime.now(),
       };
       passkeys.byCredentialId.set(cred.credentialId, cred);
@@ -170,7 +195,6 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
         consumedAt: null,
         attempts: 0,
       });
-      // Simplified: empty allow list when no email mapping (caller supplies credentialId).
       return { challenge, rpId, allowCredentials: [] as string[] };
     },
   });
@@ -179,19 +203,44 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
     name: "auth.passkeyAuthenticate",
     unit: "auth",
     plane: "user",
-    in: z.object({
-      credentialId: z.string().min(1),
-      userId: z.string().min(1),
+    in: CeremonyIn.extend({
+      challenge: z.string().min(1),
+      /** Challenge bucket key from authenticate options (default `anonymous`). */
+      email: z.string().optional(),
     }),
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
     do: async (input) => {
-      // Simplified v1: presence of stored credential + matching userId issues a session.
       const cred = passkeys.byCredentialId.get(input.credentialId);
-      if (!cred || cred.userId !== input.userId) {
-        return fail("AuthFailed", { reason: "invalid_credentials" });
+      if (!cred) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const bucket = input.email?.trim().toLowerCase() || "anonymous";
+      const consumed = await consumeChallenge(
+        challenges,
+        `passkey-auth:${bucket}`,
+        input.challenge,
+        runtime.now(),
+      );
+      if (!consumed) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const verified = await verifyWebAuthnCeremony({
+        expectedType: "webauthn.get",
+        expectedChallenge: input.challenge,
+        expectedOrigins: origins,
+        rpId,
+        publicKeySpkiB64url: cred.publicKey,
+        clientDataJSON: input.clientDataJSON,
+        authenticatorData: input.authenticatorData,
+        signature: input.signature,
+        previousSignCount: cred.counter,
+      });
+      if (!verified.ok) {
+        return fail("AuthFailed", {
+          reason: verified.reason === "invalid_origin" ? "invalid_origin" : "invalid_credentials",
+        });
       }
-      cred.counter += 1;
+      cred.counter = verified.signCount;
+
       const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
         id: cred.userId,
         plane: "user",
@@ -214,3 +263,20 @@ export function passkey(opts: PasskeyOptions = {}): PluginDef {
     .binding(bindPublicAuth("/passkey/authenticate/options", authenticateOptions, "otp"))
     .binding(bindPublicAuth("/passkey/authenticate", authenticate, "otp"));
 }
+
+async function consumeChallenge(
+  store: VerificationStore,
+  identifier: string,
+  challenge: string,
+  now: number,
+): Promise<boolean> {
+  const hash = await hashChallenge(challenge);
+  for (const row of store.rows.values()) {
+    if (row.identifier !== identifier) continue;
+    if (row.consumedAt !== null || row.expiresAt <= now) continue;
+    if (!constantTimeEqual(row.value, hash)) continue;
+    row.consumedAt = now;
+    return true;
+  }
+  return false;
+}

package/src/plugins/response-headers.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared response-header mutation for HTTP middleware plugins.
+ * Web `Headers` are immutable-in-place on a built `Response` — rebuild instead.
+ */
+
+/**
+ * Rebuild a response with headers mutated by `fn`.
+ *
+ * @param response - Original response
+ * @param fn - Header mutation
+ */
+export function withHeaders(response: Response, fn: (headers: Headers) => void): Response {
+  const headers = new Headers(response.headers);
+  fn(headers);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/**
+ * Set a header only when absent (or when `override` is on).
+ *
+ * @param headers - Mutable headers
+ * @param name - Header name
+ * @param value - Header value
+ * @param override - Replace an app-set value
+ */
+export function setUnlessPresent(
+  headers: Headers,
+  name: string,
+  value: string,
+  override: boolean,
+): void {
+  if (!override && headers.has(name)) return;
+  headers.set(name, value);
+}
+
+/**
+ * Append a token to `Vary` without duplicating it.
+ *
+ * @param headers - Mutable headers
+ * @param token - Vary token (e.g. `"origin"`)
+ */
+export function appendVary(headers: Headers, token: string): void {
+  const vary = headers.get("vary");
+  if (vary === null) {
+    headers.set("vary", token);
+    return;
+  }
+  const pattern = new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+  if (!pattern.test(vary)) headers.set("vary", `${vary}, ${token}`);
+}