@voult/core 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@voult/core` are documented here.
+
+## 0.2.0
+
+The router now serves every end-user feature, so apps write no auth route handlers. New routes (below the mount path):
+
+- **Session required** (renews from the refresh cookie first, else `401` JSON): `POST /mfa/setup`, `POST /mfa/enable { code }`, `POST /mfa/disable { code, password? }` (no password needed for Google/GitHub accounts), `POST /mfa/backup-codes { code }`, `GET /sessions` (this browser's session has `isCurrent: true`), `DELETE /sessions/:id` (revoking your own session signs this browser out; the answer says `current: true`), `GET /oauth/linked`, `DELETE /oauth/linked/:provider`, `DELETE /user/me` (Voult disables the account; this browser is signed out), `POST /passkeys/register/options`, `POST /passkeys/register/verify`, `GET /passkeys`, `PATCH /passkeys/:id`, `DELETE /passkeys/:id`.
+- **Public:** `POST /mfa/cancel` (drop a sign-in waiting for its code), `POST /passkeys/login/options`, `POST /passkeys/login/verify` (sets the session, or the MFA-pending cookie, like password sign-in), `POST /magic-link { email, returnTo? }` (answers `{ sent: true }` whether or not the email has an account), `GET /magic-link/verify?token=` (sets the session or MFA-pending cookie and redirects like the OAuth callback: `returnTo`, `mfaPath`, or `errorPath?voult_error=…`).
+- Magic links point at `/magic-link/verify` next to the OAuth callback, so the one callback URL on the app's allowlist covers both.
+- Needs Voult API 1.2+ for `isCurrent` (older APIs: `isCurrent` is missing and revoking your own session doesn't sign this browser out) and for MFA on magic links.
+
+## 0.1.0
+
+First release. The Voult router as one function on the Fetch API, so adapters only translate requests:
+
+- `createVoultHandler(config)` → `handle(request, { basePath, notFound }) → Response`: every route `@voult/express` 0.2.1 served (session, password sign-up/sign-in, sign-out, refresh, profile, password reset, email verification, MFA, hosted OAuth with the browser-bound nonce), with session renewal from the refresh cookie.
+- Cookies are byte-compatible with Express + `cookie-parser` (`s:` + HMAC-SHA256 signatures), signed with WebCrypto.
+- No framework imports and no Node-only APIs in `src/` (a test checks), so it can run on Node 20+, Next.js route handlers and Edge runtimes.
+- For adapters: `resolveConfig`, `loadConfigFromEnv`, `getSessionFromRequest`, `restoreSession`, `renewSession`, `sessionCookies`, `normalizeVoultError`, and the cookie helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Olabode
+
+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 +1,26 @@
-Not released yet. See https://github.com/voult-dev/voult-sdk
+# @voult/core
+
+The [Voult](https://github.com/voult-dev/voult) auth router on the Fetch API: `Request → Response`.
+
+**You probably want an adapter instead:** [`@voult/express`](../express) for Express, `@voult/next` for Next.js (coming soon). They depend on this package; apps don't install it directly.
+
+## For adapter authors
+
+```js
+import { createVoultHandler, loadConfigFromEnv } from '@voult/core';
+
+const handle = createVoultHandler(loadConfigFromEnv());
+
+// Any Fetch API runtime: a Next.js route handler, a Worker, Bun, Deno, Node 20+.
+export async function fetch(request) {
+  return handle(request, { basePath: '/api/auth' });
+}
+```
+
+- `basePath`: where the routes are mounted. Requests outside it, or to paths with no route, get `notFound(request)` (default: 404 JSON; return `null` to fall through to your framework).
+- The OAuth callback URL is built from the request URL, so pass the URL the browser used (or set `VOULT_OAUTH_CALLBACK_URL`).
+- Cookies (httpOnly, `SameSite=Lax`, `Secure` in production) use the same names and signed format as Express + `cookie-parser`.
+
+`getSessionFromRequest(request, config)` gives you the request's `VoultClient` with its session restored, for server-side helpers like `getSession()`.
+
+`@voult/sdk` is a peer dependency. Node 20+ (needs `fetch` and WebCrypto).

package/package.json

@@ -1 +1,53 @@
-{ "name": "@voult/core", "version": "0.0.0", "description": "Placeholder: not released yet", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/voult-dev/voult-sdk.git" } }
+{
+  "name": "@voult/core",
+  "version": "0.2.0",
+  "description": "The Voult auth router on the Fetch API (Request \u2192 Response), shared by @voult/express and @voult/next",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "keywords": [
+    "voult",
+    "authentication",
+    "fetch",
+    "edge"
+  ],
+  "author": "Samuel Olabode",
+  "license": "MIT",
+  "peerDependencies": {
+    "@voult/sdk": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@voult/sdk": "*",
+    "cookie-signature": "^1.0.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voult-dev/voult-sdk.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/voult-dev/voult-sdk/issues"
+  },
+  "homepage": "https://github.com/voult-dev/voult-sdk/tree/main/packages/core#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.js

@@ -0,0 +1,226 @@
+import { DEFAULT_BASE_URL } from '@voult/sdk';
+
+/**
+ * @typedef {import('./index.js').VoultConfig} VoultExpressConfig
+ * @typedef {import('./index.js').LoadConfigFromEnvOptions} LoadConfigFromEnvOptions
+ * @typedef {import('./index.js').ResolveConfigOptions} CreateVoultRouterOptions
+ */
+
+// No `process` on the Edge: read it through globalThis.
+const processEnv = () => globalThis.process?.env ?? {};
+
+const ENV_FIELDS = {
+  baseURL: { canonical: 'VOULT_BASE_URL', aliases: ['BASE_URL'] },
+  clientId: { canonical: 'VOULT_CLIENT_ID', aliases: ['CLIENT_ID'] },
+  clientSecret: { canonical: 'VOULT_CLIENT_SECRET', aliases: ['CLIENT_SECRET'] },
+  sessionSecret: { canonical: 'VOULT_SESSION_SECRET', aliases: ['SESSION_SECRET'] },
+  appUrl: { canonical: 'VOULT_APP_URL', aliases: ['APP_URL'] },
+  sessionStrategy: { canonical: 'VOULT_SESSION_STRATEGY', aliases: [] },
+  oauthCallbackUrl: { canonical: 'VOULT_OAUTH_CALLBACK_URL', aliases: [] },
+};
+
+const warnedLegacyAliases = new Set();
+
+/**
+ * Read a config value from canonical env names, falling back to deprecated aliases.
+ * @param {NodeJS.Dict<string | undefined>} env
+ * @param {{ canonical: string, aliases: string[] }} field
+ * @returns {string | undefined}
+ */
+function readEnvValue(env, field) {
+  const canonicalValue = trimToUndefined(env[field.canonical]);
+  if (canonicalValue) {
+    return canonicalValue;
+  }
+
+  for (const alias of field.aliases) {
+    const aliasValue = trimToUndefined(env[alias]);
+    if (!aliasValue) {
+      continue;
+    }
+
+    if (!warnedLegacyAliases.has(alias)) {
+      warnedLegacyAliases.add(alias);
+      console.warn(
+        `[voult] ${alias} is deprecated; use ${field.canonical} instead. This alias will be removed in a future release.`
+      );
+    }
+
+    return aliasValue;
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function trimToUndefined(value) {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+// Each Voult instance serves its own developer dashboard at /dashboard.
+const dashboardUrl = (baseURL) => new URL('/dashboard', baseURL).href;
+
+/**
+ * @param {NodeJS.Dict<string | undefined>} env
+ * @returns {string}
+ */
+function resolveNodeEnv(env) {
+  return (
+    trimToUndefined(env.NODE_ENV) ??
+    trimToUndefined(processEnv().NODE_ENV) ??
+    'development'
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} envName
+ * @returns {string}
+ */
+function requireHttpUrl(value, envName) {
+  const raw = trimToUndefined(value);
+  if (!raw) {
+    return DEFAULT_BASE_URL;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    parsed = null;
+  }
+
+  if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+    throw new Error(
+      `[voult] Invalid ${envName} "${raw}". Set it to an absolute http(s) URL, for example https://api.voult.dev or https://staging.voult.dev.`
+    );
+  }
+
+  return raw;
+}
+
+const OAUTH_PATH_DEFAULTS = { successPath: '/', mfaPath: '/mfa', errorPath: '/login' };
+
+/**
+ * Where the hosted-OAuth callback sends the browser, relative to VOULT_APP_URL.
+ * @param {Partial<Record<keyof typeof OAUTH_PATH_DEFAULTS, string>> | undefined} oauth
+ */
+function normalizeOAuthPaths(oauth = {}) {
+  return Object.fromEntries(Object.entries(OAUTH_PATH_DEFAULTS).map(([key, fallback]) => {
+    const value = trimToUndefined(oauth[key]) ?? fallback;
+    if (!value.startsWith('/') || value.startsWith('//')) {
+      throw new Error(`[voult] oauth.${key} must be a path starting with "/" (got "${value}").`);
+    }
+    return [key, value];
+  }));
+}
+
+/**
+ * @param {VoultExpressConfig} config
+ * @param {NodeJS.Dict<string | undefined>} env
+ * @returns {VoultExpressConfig}
+ */
+function normalizeConfig(config, env) {
+  const clientId = trimToUndefined(config.clientId);
+  const clientSecret = trimToUndefined(config.clientSecret);
+  const sessionSecret = trimToUndefined(config.sessionSecret);
+  const requestedStrategy = trimToUndefined(config.session?.strategy)?.toLowerCase() ?? 'cookie';
+  if (requestedStrategy !== 'cookie' && requestedStrategy !== 'bearer') {
+    throw new Error(
+      `[voult] Invalid VOULT_SESSION_STRATEGY "${config.session.strategy}". Use "cookie" (default, httpOnly cookies) or "bearer" (tokens returned in JSON).`
+    );
+  }
+  const strategy = requestedStrategy;
+  const baseURL = requireHttpUrl(config.baseURL, 'VOULT_BASE_URL');
+
+  if (!clientId) {
+    throw new Error(
+      `[voult] Missing VOULT_CLIENT_ID. Create an App in the Voult dashboard (${dashboardUrl(baseURL)}), then copy the Client ID into your .env as VOULT_CLIENT_ID.`
+    );
+  }
+
+  if (!clientSecret) {
+    throw new Error(
+      `[voult] Missing VOULT_CLIENT_SECRET. Copy the Client Secret from your App in the Voult dashboard (${dashboardUrl(baseURL)}) into your .env as VOULT_CLIENT_SECRET. The secret is required for this Express BFF and must not be sent to the browser.`
+    );
+  }
+
+  const appUrl = trimToUndefined(config.appUrl)
+    ? requireHttpUrl(config.appUrl, 'VOULT_APP_URL')
+    : undefined;
+  const oauthCallbackUrl = trimToUndefined(config.oauthCallbackUrl)
+    ? requireHttpUrl(config.oauthCallbackUrl, 'VOULT_OAUTH_CALLBACK_URL')
+    : undefined;
+
+  if (strategy === 'cookie' && !sessionSecret && resolveNodeEnv(env) === 'production') {
+    throw new Error(
+      '[voult] Cookie sessions require VOULT_SESSION_SECRET in production. Add a long random value to your .env (openssl rand -hex 32). If the client stores tokens itself, set VOULT_SESSION_STRATEGY=bearer instead.'
+    );
+  }
+
+  return {
+    baseURL,
+    clientId,
+    clientSecret,
+    sessionSecret,
+    appUrl,
+    oauthCallbackUrl,
+    oauth: normalizeOAuthPaths(config.oauth),
+    session: { strategy },
+  };
+}
+
+/**
+ * Load BFF config from process env (or a provided env map).
+ * Canonical names are `VOULT_*`. Legacy aliases warn once per process.
+ *
+ * @param {LoadConfigFromEnvOptions} [options]
+ * @returns {VoultExpressConfig}
+ */
+export function loadConfigFromEnv(options = {}) {
+  const env = options.env ?? processEnv();
+  const overrides = options.overrides ?? {};
+
+  return normalizeConfig(
+    {
+      baseURL: overrides.baseURL ?? readEnvValue(env, ENV_FIELDS.baseURL),
+      clientId: overrides.clientId ?? readEnvValue(env, ENV_FIELDS.clientId),
+      clientSecret: overrides.clientSecret ?? readEnvValue(env, ENV_FIELDS.clientSecret),
+      sessionSecret: overrides.sessionSecret ?? readEnvValue(env, ENV_FIELDS.sessionSecret),
+      appUrl: overrides.appUrl ?? readEnvValue(env, ENV_FIELDS.appUrl),
+      oauthCallbackUrl: overrides.oauthCallbackUrl ?? readEnvValue(env, ENV_FIELDS.oauthCallbackUrl),
+      oauth: overrides.oauth,
+      session: {
+        strategy: overrides.session?.strategy ?? readEnvValue(env, ENV_FIELDS.sessionStrategy),
+      },
+    },
+    env
+  );
+}
+
+/**
+ * Resolve router/middleware options into a normalized config.
+ * @param {CreateVoultRouterOptions} [options]
+ * @returns {VoultExpressConfig}
+ */
+export function resolveConfig(options = {}) {
+  const env = options.env ?? processEnv();
+
+  // `oauth` paths may also be passed at the top level: createVoultRouter({ oauth: { ... } }).
+  if (options.config) {
+    return normalizeConfig({ ...options.config, oauth: options.oauth ?? options.config.oauth }, env);
+  }
+
+  return loadConfigFromEnv({
+    env,
+    overrides: options.oauth ? { ...options.overrides, oauth: options.oauth } : options.overrides,
+  });
+}

package/src/cookies.js

@@ -0,0 +1,107 @@
+// Cookies in exactly the format Express + cookie-parser use (so sessions survive the switch
+// between adapters), built on WebCrypto so the same code runs on Node and the Edge.
+//   signed value: `s:<value>.<base64 HMAC-SHA256(value), padding stripped>` (cookie-signature)
+//   Set-Cookie:   `name=<encoded>; Max-Age=; Path=; Expires=; HttpOnly; Secure; SameSite=`
+
+const encoder = new TextEncoder();
+const hmacKeys = new Map();
+
+function hmacKey(secret) {
+  if (!hmacKeys.has(secret)) {
+    hmacKeys.set(
+      secret,
+      globalThis.crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+    );
+  }
+  return hmacKeys.get(secret);
+}
+
+export function base64(bytes) {
+  let binary = '';
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** cookie-signature `sign()`: `<value>.<mac>` */
+export async function sign(value, secret) {
+  const mac = await globalThis.crypto.subtle.sign('HMAC', await hmacKey(secret), encoder.encode(value));
+  return `${value}.${base64(mac).replace(/=+$/, '')}`;
+}
+
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/** cookie-signature `unsign()`: the value, or `false` when the signature is wrong. */
+export async function unsign(signed, secret) {
+  const dot = signed.lastIndexOf('.');
+  if (dot < 0) return false;
+  const value = signed.slice(0, dot);
+  return safeEqual(await sign(value, secret), signed) ? value : false;
+}
+
+function decode(value) {
+  if (!value.includes('%')) return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/** Parse a `Cookie` header like the `cookie` package: first occurrence wins, quotes stripped. */
+export function parseCookieHeader(header) {
+  const cookies = Object.create(null);
+  for (const part of (header ?? '').split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name || Object.hasOwn(cookies, name)) continue;
+    let value = part.slice(eq + 1).trim();
+    if (value.length > 1 && value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+    cookies[name] = decode(value);
+  }
+  return cookies;
+}
+
+/**
+ * cookie-parser semantics: with a secret, `s:` values move to `signedCookies` (`false` when
+ * tampered with); everything else stays in `cookies`.
+ */
+export async function readCookieHeader(header, secret) {
+  const cookies = parseCookieHeader(header);
+  const signedCookies = Object.create(null);
+  if (secret) {
+    for (const [name, value] of Object.entries(cookies)) {
+      if (!value.startsWith('s:')) continue;
+      signedCookies[name] = await unsign(value.slice(2), secret);
+      delete cookies[name];
+    }
+  }
+  return { cookies, signedCookies };
+}
+
+/** Express `res.cookie()` output for an already-signed value. `maxAge` is in milliseconds. */
+export function serializeCookie(name, value, options = {}) {
+  let str = `${name}=${encodeURIComponent(value)}`;
+  let { expires } = options;
+  if (options.maxAge != null) {
+    expires = new Date(Date.now() + options.maxAge);
+    str += `; Max-Age=${Math.floor(options.maxAge / 1000)}`;
+  }
+  str += `; Path=${options.path ?? '/'}`;
+  if (expires) str += `; Expires=${expires.toUTCString()}`;
+  if (options.httpOnly) str += '; HttpOnly';
+  if (options.secure) str += '; Secure';
+  if (options.sameSite) str += `; SameSite=${options.sameSite[0].toUpperCase()}${options.sameSite.slice(1).toLowerCase()}`;
+  return str;
+}
+
+/** A Set-Cookie header for a `{ name, value, options }` cookie, signing it when `options.signed`. */
+export async function setCookieHeader({ name, value, options }, secret) {
+  const final = options.signed ? `s:${await sign(value, secret)}` : value;
+  return serializeCookie(name, final, options);
+}

package/src/errors.js

@@ -0,0 +1,29 @@
+import { VoultError } from '@voult/sdk';
+
+/**
+ * Normalize SDK and unexpected errors into a stable JSON shape.
+ * @param {unknown} err
+ */
+export function normalizeVoultError(err) {
+  if (err instanceof VoultError) {
+    const status = err.status ?? 500;
+    return {
+      error: {
+        code: err.code,
+        message: err.message,
+        status,
+        ...(err.field ? { field: err.field } : {}),
+        ...(err.fields ? { fields: err.fields } : {}),
+      },
+    };
+  }
+
+  const status = typeof err?.status === 'number' ? err.status : 500;
+  return {
+    error: {
+      code: err?.code || 'INTERNAL_ERROR',
+      message: err?.message || 'Internal server error',
+      status,
+    },
+  };
+}

package/src/handler.js

@@ -0,0 +1,158 @@
+import { setCookieHeader } from './cookies.js';
+import { normalizeVoultError } from './errors.js';
+import { oauthRoutes } from './oauth.js';
+import { passwordlessRoutes } from './passwordless.js';
+import { authRoutes, json } from './routes.js';
+import { getSessionFromRequest, renewSession, sessionCookies } from './session.js';
+
+/**
+ * @typedef {import('./index.js').VoultConfig} VoultConfig
+ * @typedef {import('./session.js').CookieToSet} CookieToSet
+ * @typedef {{ status: number, body?: unknown, location?: string }} Result
+ * @typedef {{
+ *   request: Request,
+ *   url: URL,
+ *   basePath: string,
+ *   params: Record<string, string>,
+ *   query: (name: string) => string | undefined,
+ *   body: Record<string, any>,
+ *   config: VoultConfig,
+ *   client: import('@voult/sdk').VoultClient,
+ *   incoming: { accessToken: string | null, refreshToken: string | null },
+ *   read: (name: string) => unknown,
+ *   cookies: CookieToSet[],
+ *   renew: () => Promise<void>,
+ * }} Context
+ * @typedef {[method: string, path: string, handler: (ctx: Context) => Promise<Result>]} Route
+ */
+
+const MAX_BODY_BYTES = 100 * 1024; // express.json()'s default limit
+
+/** Express-style route matching: `:param` segments, case-insensitive, optional trailing slash. */
+function compile([method, path, handler]) {
+  const keys = [];
+  const source = path.replace(/:(\w+)/g, (_, key) => {
+    keys.push(key);
+    return '([^/]+)';
+  });
+  return { method, pattern: new RegExp(`^${source}/?$`, 'i'), keys, handler };
+}
+
+function match(routes, method, path) {
+  for (const route of routes) {
+    if (route.method !== method) continue;
+    const found = route.pattern.exec(path);
+    if (found) {
+      const params = Object.fromEntries(route.keys.map((key, i) => [key, decodeURIComponent(found[i + 1])]));
+      return { handler: route.handler, params };
+    }
+  }
+  return null;
+}
+
+/** The request path below `basePath`, or null when the request isn't for this router. */
+function routePath(pathname, basePath) {
+  if (!basePath) return pathname;
+  if (pathname.toLowerCase() === basePath.toLowerCase()) return '/';
+  return pathname.toLowerCase().startsWith(`${basePath.toLowerCase()}/`) ? pathname.slice(basePath.length) : null;
+}
+
+/** JSON bodies only, like express.json(); anything else is `{}`. */
+async function readBody(request) {
+  if (request.method === 'GET' || request.method === 'HEAD') return {};
+  if (!/\bjson\b/i.test(request.headers.get('content-type') ?? '')) return {};
+  const text = await request.text();
+  if (new TextEncoder().encode(text).length > MAX_BODY_BYTES) {
+    throw Object.assign(new Error('Request body is too large'), { status: 413, code: 'PAYLOAD_TOO_LARGE' });
+  }
+  if (!text.trim()) return {};
+  try {
+    const body = JSON.parse(text);
+    return body && typeof body === 'object' ? body : {};
+  } catch {
+    throw Object.assign(new Error('Request body is not valid JSON'), { status: 400, code: 'INVALID_JSON' });
+  }
+}
+
+// Express's res.location() encoding (the `encodeurl` package): keep valid URL characters and
+// %-escapes, encode the rest, so a Location header is always valid ASCII.
+const ENCODE_CHARS = /(?:[^\x21\x23-\x3B\x3D\x3F-\x5F\x61-\x7A\x7C\x7E]|%(?:[^0-9A-Fa-f]|[0-9A-Fa-f][^0-9A-Fa-f]|$))+/g;
+const UNMATCHED_SURROGATES = /(^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]|[\uD800-\uDBFF]([^\uDC00-\uDFFF]|$)/g;
+const encodeLocation = (url) => String(url).replace(UNMATCHED_SURROGATES, '$1�$2').replace(ENCODE_CHARS, encodeURI);
+
+/** @param {Result} result @param {string[]} setCookies */
+function toResponse(result, setCookies) {
+  const headers = new Headers();
+  for (const cookie of setCookies) headers.append('Set-Cookie', cookie);
+  if (result.location !== undefined) {
+    headers.set('Location', encodeLocation(result.location));
+    return new Response(null, { status: result.status, headers });
+  }
+  headers.set('Content-Type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(result.body), { status: result.status, headers });
+}
+
+const defaultNotFound = () => Response.json(
+  { error: { code: 'NOT_FOUND', message: 'No such Voult route', status: 404 } },
+  { status: 404 }
+);
+
+/**
+ * The Voult router as one function: `handle(request, { basePath }) → Response`.
+ * Holds every auth route, the cookies, the OAuth nonce and session renewal; adapters only
+ * translate their framework's request/response to and from the Fetch API.
+ *
+ * @param {VoultConfig} config  A normalized config (`resolveConfig` / `loadConfigFromEnv`).
+ */
+export function createVoultHandler(config) {
+  const routes = [...authRoutes, ...passwordlessRoutes, ...oauthRoutes()].map(compile);
+
+  /**
+   * @param {Request} request
+   * @param {{ basePath?: string, notFound?: (request: Request) => Response | null }} [options]
+   *   basePath: where the router is mounted (`/api/auth`). notFound: answer for paths with no
+   *   route (default 404 JSON; return null to let the adapter fall through).
+   * @returns {Promise<Response | null>}
+   */
+  return async function handle(request, { basePath = '', notFound = defaultNotFound } = {}) {
+    const url = new URL(request.url);
+    const path = routePath(url.pathname, basePath.replace(/\/$/, ''));
+    const method = request.method === 'HEAD' ? 'GET' : request.method;
+    const found = path === null ? null : match(routes, method, path);
+    if (!found) return notFound(request);
+
+    /** @type {Context | undefined} */
+    let ctx;
+    /** @type {Result} */
+    let result;
+    try {
+      const body = await readBody(request);
+      const { client, incoming, read } = await getSessionFromRequest(request, config, { body });
+      ctx = {
+        request,
+        url,
+        basePath: basePath.replace(/\/$/, ''),
+        params: found.params,
+        query: (name) => url.searchParams.get(name) ?? undefined,
+        body,
+        config,
+        client,
+        incoming,
+        read,
+        cookies: [],
+        renew: async () => { ctx.cookies.push(...await renewSession(client, read, config)); },
+      };
+      result = await found.handler(ctx);
+    } catch (err) {
+      const payload = normalizeVoultError(err);
+      result = json(payload, payload.error.status);
+    }
+
+    // The handler's own cookies first, then the session as it stands now (like Express, where
+    // the session cookies are written as the response goes out).
+    const cookies = ctx ? [...ctx.cookies, ...sessionCookies(ctx.client, ctx.incoming, config)] : [];
+    const setCookies = await Promise.all(cookies.map((cookie) => setCookieHeader(cookie, config.sessionSecret)));
+    const response = toResponse(result, setCookies);
+    return request.method === 'HEAD' ? new Response(null, response) : response;
+  };
+}