@voult/core 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@voult/core` are documented here.
+
+## 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.1.0",
+  "description": "The Voult auth router on the Fetch API (Request → 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,157 @@
+import { setCookieHeader } from './cookies.js';
+import { normalizeVoultError } from './errors.js';
+import { oauthRoutes } from './oauth.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, ...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;
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,100 @@
+/** The per-request `@voult/sdk` VoultClient (the parts adapters use). */
+export interface VoultClient {
+  accessToken: string | null;
+  refreshToken: string | null;
+  user: unknown;
+  isAuthenticated(): boolean;
+  getCurrentUser(): unknown;
+  setSession(user: unknown, accessToken: string, refreshToken?: string | null): void;
+  clearSession(): void;
+}
+
+export type SessionStrategy = 'cookie' | 'bearer';
+
+/** Where hosted OAuth sends the browser, relative to `appUrl`. Each must start with "/". */
+export interface VoultOAuthPaths {
+  /** Default `/`. After sign-in (unless `returnTo` was given) or linking. */
+  successPath?: string;
+  /** Default `/mfa`. User has MFA: prompt for a code and POST /mfa/verify { mfaToken }. */
+  mfaPath?: string;
+  /** Default `/login`. Receives `?voult_error=<CODE>&voult_error_description=<text>`. */
+  errorPath?: string;
+}
+
+export interface VoultConfig {
+  baseURL?: string;
+  clientId: string;
+  clientSecret: string;
+  sessionSecret?: string;
+  appUrl?: string;
+  /** Override the computed hosted-OAuth callback URL (e.g. behind a proxy). */
+  oauthCallbackUrl?: string;
+  oauth?: VoultOAuthPaths;
+  session?: { strategy?: SessionStrategy };
+}
+
+export interface LoadConfigFromEnvOptions {
+  env?: Record<string, string | undefined>;
+  overrides?: Partial<VoultConfig>;
+}
+
+export interface ResolveConfigOptions extends LoadConfigFromEnvOptions {
+  config?: VoultConfig;
+  oauth?: VoultOAuthPaths;
+}
+
+export interface CookieToSet {
+  name: string;
+  value: string;
+  options: Record<string, unknown>;
+}
+
+export type ReadCookie = (name: string) => unknown;
+
+export interface IncomingSession {
+  accessToken: string | null;
+  refreshToken: string | null;
+}
+
+export interface HandleOptions {
+  /** Where the router is mounted, e.g. `/api/auth`. */
+  basePath?: string;
+  /** Answer for paths with no route. Default: 404 JSON. Return null to fall through. */
+  notFound?: (request: Request) => Response | null;
+}
+
+export type VoultHandler = (request: Request, options?: HandleOptions) => Promise<Response | null>;
+
+export function createVoultHandler(config: VoultConfig): VoultHandler;
+export function loadConfigFromEnv(options?: LoadConfigFromEnvOptions): VoultConfig;
+export function resolveConfig(options?: ResolveConfigOptions): VoultConfig;
+export function normalizeVoultError(err: unknown): { error: { code: string; message: string; status: number; field?: string; fields?: unknown } };
+
+export const COOKIE_ACCESS: 'voult_access';
+export const COOKIE_REFRESH: 'voult_refresh';
+export const COOKIE_USER: 'voult_user';
+export const COOKIE_OAUTH: 'voult_oauth';
+export const COOKIE_MFA_PENDING: 'voult_mfa_pending';
+
+export function createVoultClient(config: VoultConfig): VoultClient;
+export function getSessionFromRequest(
+  request: Request,
+  config: VoultConfig,
+  options?: { body?: Record<string, unknown> }
+): Promise<{ client: VoultClient; incoming: IncomingSession; read: ReadCookie }>;
+export function restoreSession(
+  client: VoultClient,
+  incoming: { read: ReadCookie; authorization?: string | null; refreshToken?: unknown },
+  config: VoultConfig
+): IncomingSession;
+export function sessionCookies(client: VoultClient, incoming: IncomingSession, config: VoultConfig): CookieToSet[];
+export function renewSession(client: VoultClient, read: ReadCookie, config: VoultConfig): Promise<CookieToSet[]>;
+
+export function readCookieHeader(header: string | null | undefined, secret?: string): Promise<{
+  cookies: Record<string, string>;
+  signedCookies: Record<string, string | false>;
+}>;
+export function serializeCookie(name: string, value: string, options?: Record<string, unknown>): string;
+export function setCookieHeader(cookie: CookieToSet, secret?: string): Promise<string>;
+export function sign(value: string, secret: string): Promise<string>;
+export function unsign(signed: string, secret: string): Promise<string | false>;

package/src/index.js

@@ -0,0 +1,18 @@
+// @voult/core: the Voult router on the Fetch API, for adapters (@voult/express, @voult/next).
+// Apps install an adapter, not this package.
+export { createVoultHandler } from './handler.js';
+export { loadConfigFromEnv, resolveConfig } from './config.js';
+export { normalizeVoultError } from './errors.js';
+export {
+  COOKIE_ACCESS,
+  COOKIE_MFA_PENDING,
+  COOKIE_OAUTH,
+  COOKIE_REFRESH,
+  COOKIE_USER,
+  createVoultClient,
+  getSessionFromRequest,
+  renewSession,
+  restoreSession,
+  sessionCookies,
+} from './session.js';
+export { readCookieHeader, serializeCookie, setCookieHeader, sign, unsign } from './cookies.js';

package/src/oauth.js

@@ -0,0 +1,199 @@
+import {
+  exchangeOAuthCode,
+  getAppInfo,
+  getOAuthAuthorizationUrl,
+  linkOAuthProvider,
+} from '@voult/sdk';
+import { base64 } from './cookies.js';
+import { json, redirect } from './routes.js';
+import {
+  COOKIE_MFA_PENDING,
+  COOKIE_OAUTH,
+  MFA_PENDING_MAX_AGE_MS,
+  OAUTH_COOKIE_MAX_AGE_MS,
+  clearCookie,
+  setCookie,
+} from './session.js';
+
+// Hosted OAuth: provider credentials live in the Voult dashboard, never in this server's env.
+//   GET /oauth/providers          → which providers the app can use
+//   GET /oauth/:provider/start    → 302 to the provider (via Voult)
+//   GET /oauth/callback           → Voult sends the browser back here; we set the session
+
+/**
+ * @typedef {import('./handler.js').Context} Context
+ * @typedef {import('./handler.js').Route} Route
+ * @typedef {import('./index.js').VoultConfig} VoultConfig
+ */
+
+const PROVIDERS_CACHE_MS = 60 * 1000;
+const INTENTS = ['authenticate', 'login', 'register', 'link'];
+
+/**
+ * Only same-site relative paths, so `returnTo` can't send users to another site.
+ * @param {unknown} value
+ * @param {string} fallback
+ */
+export function safeReturnTo(value, fallback) {
+  return typeof value === 'string'
+    && value.length <= 2048
+    && value.startsWith('/')
+    && !value.startsWith('//')
+    && !value.includes('\\')
+    ? value
+    : fallback;
+}
+
+/**
+ * A browser URL on the integrator's frontend (VOULT_APP_URL), or same-origin when unset.
+ * @param {VoultConfig} config
+ * @param {string} path
+ * @param {Record<string, string | undefined>} [params]
+ */
+function appLocation(config, path, params = {}) {
+  const query = new URLSearchParams(
+    Object.entries(params).filter(([, value]) => value != null && value !== '')
+  ).toString();
+  const base = config.appUrl ? config.appUrl.replace(/\/$/, '') : '';
+  const joiner = path.includes('?') ? '&' : '?';
+  return `${base}${path}${query ? `${joiner}${query}` : ''}`;
+}
+
+/**
+ * The URL Voult sends the browser back to. Must be on the app's callback allowlist.
+ * Behind a proxy, let the adapter see the public URL (Express: `app.set('trust proxy', 1)`)
+ * or set VOULT_OAUTH_CALLBACK_URL.
+ * @param {Context} ctx
+ */
+export function oauthCallbackUrl(ctx) {
+  return ctx.config.oauthCallbackUrl || `${ctx.url.protocol}//${ctx.url.host}${ctx.basePath}/oauth/callback`;
+}
+
+function redirectWithError(config, code, description) {
+  return redirect(appLocation(config, config.oauth.errorPath, {
+    voult_error: code,
+    voult_error_description: description,
+  }));
+}
+
+function errorCode(err) {
+  return err?.apiCode || err?.code || 'OAUTH_FAILED';
+}
+
+function newNonce() {
+  return base64(globalThis.crypto.getRandomValues(new Uint8Array(24)))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function readOAuthCookie(ctx) {
+  const raw = ctx.read(COOKIE_OAUTH);
+  if (typeof raw !== 'string') return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** One provider cache per handler. @returns {Route[]} */
+export function oauthRoutes() {
+  let providersCache = { at: 0, value: null };
+
+  return [
+    ['GET', '/oauth/providers', async (ctx) => {
+      if (!providersCache.value || Date.now() - providersCache.at > PROVIDERS_CACHE_MS) {
+        const info = await getAppInfo(ctx.client);
+        const providers = Object.fromEntries(
+          Object.entries(info.providers || {}).map(([name, s]) => [name, Boolean(s.enabled && s.configured)])
+        );
+        providersCache = { at: Date.now(), value: { providers } };
+      }
+      return json(providersCache.value);
+    }],
+
+    ['GET', '/oauth/:provider/start', async (ctx) => {
+      const { config, client } = ctx;
+      if (config.session.strategy !== 'cookie') {
+        return json({
+          error: {
+            code: 'OAUTH_REQUIRES_COOKIE_SESSION',
+            message: 'Hosted OAuth sets the session in a cookie. Use VOULT_SESSION_STRATEGY=cookie, or call the @voult/sdk OAuth functions yourself.',
+            status: 400,
+          },
+        }, 400);
+      }
+
+      const provider = String(ctx.params.provider).toLowerCase();
+      const intent = ctx.query('intent') ?? 'authenticate';
+      if (!INTENTS.includes(intent)) {
+        return redirectWithError(config, 'INVALID_INTENT', `intent must be one of: ${INTENTS.join(', ')}`);
+      }
+      if (intent === 'link' && !client.accessToken) {
+        return redirectWithError(config, 'LOGIN_REQUIRED', 'Sign in before linking another account.');
+      }
+
+      const nonce = newNonce();
+      const redirectUri = oauthCallbackUrl(ctx);
+      const returnTo = safeReturnTo(ctx.query('returnTo'), config.oauth.successPath);
+
+      let authUrl;
+      try {
+        ({ authUrl } = intent === 'link'
+          ? await linkOAuthProvider(provider, { redirectUri, state: nonce }, client)
+          : await getOAuthAuthorizationUrl(provider, { intent, redirectUri, state: nonce }, client));
+      } catch (err) {
+        return redirectWithError(config, errorCode(err), err.message);
+      }
+
+      // Ties the callback to this browser: Voult echoes `state`, we compare it to this cookie.
+      ctx.cookies.push(setCookie(
+        config,
+        COOKIE_OAUTH,
+        JSON.stringify({ nonce, provider, intent, returnTo, redirectUri }),
+        { maxAge: OAUTH_COOKIE_MAX_AGE_MS }
+      ));
+      return redirect(authUrl);
+    }],
+
+    ['GET', '/oauth/callback', async (ctx) => {
+      const { config, client } = ctx;
+      const saved = readOAuthCookie(ctx);
+      ctx.cookies.push(clearCookie(config, COOKIE_OAUTH));
+
+      if (!saved?.nonce || ctx.query('state') !== saved.nonce) {
+        return redirectWithError(
+          config, 'INVALID_OAUTH_STATE',
+          'This sign-in expired or was started in another browser. Please try again.'
+        );
+      }
+
+      if (ctx.query('error')) {
+        return redirectWithError(config, ctx.query('error'), ctx.query('error_description'));
+      }
+
+      if (ctx.query('linked') === '1') {
+        return redirect(appLocation(config, saved.returnTo, { voult_linked: saved.provider }));
+      }
+
+      const voultCode = ctx.query('voult_code');
+      if (typeof voultCode !== 'string') {
+        return redirectWithError(config, 'MISSING_OAUTH_CODE', 'Voult did not return a sign-in code.');
+      }
+
+      let result;
+      try {
+        result = await exchangeOAuthCode(voultCode, { redirectUri: saved.redirectUri }, client);
+      } catch (err) {
+        return redirectWithError(config, errorCode(err), err.message);
+      }
+
+      if (result.mfaRequired) {
+        ctx.cookies.push(setCookie(config, COOKIE_MFA_PENDING, result.mfaPendingToken, { maxAge: MFA_PENDING_MAX_AGE_MS }));
+        return redirect(appLocation(config, config.oauth.mfaPath));
+      }
+
+      // The session cookies go out with this redirect (sessionCookies, in the handler).
+      return redirect(appLocation(config, saved.returnTo));
+    }],
+  ];
+}

package/src/routes.js

@@ -0,0 +1,134 @@
+import {
+  AuthenticationError,
+  getCurrentUser,
+  getMfaStatus,
+  refreshSession,
+  resetPassword,
+  sendPasswordResetEmail,
+  signInWithEmailAndPassword,
+  signInWithUsernameAndPassword,
+  signOut,
+  signUpWithEmailAndPassword,
+  signUpWithUsernameAndPassword,
+  updateProfile,
+  verifyEmail,
+  verifyMfaLogin,
+} from '@voult/sdk';
+import { normalizeVoultError } from './errors.js';
+import { COOKIE_MFA_PENDING, MFA_PENDING_MAX_AGE_MS, clearCookie, setCookie, toPublicAuthResult } from './session.js';
+
+/**
+ * @typedef {import('./handler.js').Context} Context
+ * @typedef {import('./handler.js').Route} Route
+ */
+
+/** @param {unknown} body @param {number} [status] */
+export const json = (body, status = 200) => ({ status, body });
+/** @param {string} location */
+export const redirect = (location) => ({ status: 302, location });
+
+/**
+ * Only signed-in users get through: renews an expired access cookie from the refresh cookie
+ * first, then answers 401 JSON.
+ * @param {(ctx: Context) => Promise<unknown>} handler
+ */
+export function authenticated(handler) {
+  return async (ctx) => {
+    await ctx.renew();
+    if (!ctx.client.accessToken) {
+      const payload = normalizeVoultError(new AuthenticationError('Authentication required'));
+      return json(payload, payload.error.status);
+    }
+    return handler(ctx);
+  };
+}
+
+/** @param {Context} ctx @param {object} result */
+function authResult(ctx, result) {
+  // Park the MFA pending token server-side too (as hosted OAuth does), so /mfa/verify needs only
+  // the code and a page reload doesn't lose the sign-in. The JSON still carries it for older clients.
+  if (result?.mfaRequired && result.mfaPendingToken && ctx.config.session.strategy === 'cookie') {
+    ctx.cookies.push(setCookie(ctx.config, COOKIE_MFA_PENDING, result.mfaPendingToken, { maxAge: MFA_PENDING_MAX_AGE_MS }));
+  }
+  return json(toPublicAuthResult(result, ctx.config));
+}
+
+/** @type {Route[]} */
+export const authRoutes = [
+  ['GET', '/session', async (ctx) => {
+    await ctx.renew();
+
+    if (!ctx.client.accessToken) {
+      // A sign-in that stopped at MFA: the page should show the code prompt.
+      const mfaPending = Boolean(ctx.read(COOKIE_MFA_PENDING));
+      return json({ authenticated: false, user: null, ...(mfaPending && { mfaPending: true }) });
+    }
+
+    const localUser = ctx.client.getCurrentUser();
+    if (localUser?.id || localUser?.email) {
+      return json({ authenticated: true, user: localUser });
+    }
+
+    try {
+      return json({ authenticated: true, user: await getCurrentUser(ctx.client) });
+    } catch {
+      return json({ authenticated: false, user: null });
+    }
+  }],
+
+  ['POST', '/register', async (ctx) => {
+    const { email, password, fullName, username } = ctx.body;
+    return authResult(ctx, await signUpWithEmailAndPassword(email, password, { fullName, username }, ctx.client));
+  }],
+
+  ['POST', '/username-register', async (ctx) => {
+    const { username, password, fullName, email } = ctx.body;
+    return authResult(ctx, await signUpWithUsernameAndPassword(username, password, { fullName, email }, ctx.client));
+  }],
+
+  ['POST', '/email-login', async (ctx) => {
+    const { email, password } = ctx.body;
+    return authResult(ctx, await signInWithEmailAndPassword(email, password, ctx.client));
+  }],
+
+  ['POST', '/username-login', async (ctx) => {
+    const { username, password } = ctx.body;
+    return authResult(ctx, await signInWithUsernameAndPassword(username, password, ctx.client));
+  }],
+
+  ['POST', '/logout', async (ctx) => json(await signOut(ctx.client))],
+
+  ['POST', '/sessions/refresh', async (ctx) => {
+    if (ctx.body.refreshToken) {
+      ctx.client.refreshToken = ctx.body.refreshToken;
+    }
+    return authResult(ctx, await refreshSession(ctx.client));
+  }],
+
+  ['GET', '/user/me', authenticated(async (ctx) => json({ user: await getCurrentUser(ctx.client) }))],
+
+  ['PATCH', '/user/me', authenticated(async (ctx) => json(await updateProfile(ctx.body, ctx.client)))],
+
+  ['POST', '/user/forgot-password', async (ctx) => json(await sendPasswordResetEmail(ctx.body.email, ctx.client))],
+
+  ['POST', '/user/reset-password', async (ctx) => {
+    const { token, appId } = ctx.body;
+    const newPassword = ctx.body.newPassword ?? ctx.body.password;
+    return json(await resetPassword(token, newPassword, { appId }, ctx.client));
+  }],
+
+  ['GET', '/user/verify-email', async (ctx) => (
+    json(await verifyEmail(ctx.query('token'), { appId: ctx.query('appId') }, ctx.client))
+  )],
+
+  ['POST', '/mfa/verify', async (ctx) => {
+    const { mfaToken } = ctx.body;
+    // Password sign-in hands the token to the page; hosted OAuth keeps it in a cookie.
+    const mfaPendingToken = ctx.body.mfaPendingToken ?? ctx.read(COOKIE_MFA_PENDING);
+    const result = await verifyMfaLogin(mfaPendingToken, mfaToken, ctx.client);
+    ctx.cookies.push(clearCookie(ctx.config, COOKIE_MFA_PENDING));
+    return authResult(ctx, result);
+  }],
+
+  ['GET', '/mfa/status', authenticated(async (ctx) => json(await getMfaStatus(ctx.client)))],
+];

package/src/session.js

@@ -0,0 +1,184 @@
+import { VoultClient, refreshSession } from '@voult/sdk';
+import { readCookieHeader } from './cookies.js';
+
+export const COOKIE_ACCESS = 'voult_access';
+export const COOKIE_REFRESH = 'voult_refresh';
+export const COOKIE_USER = 'voult_user';
+export const COOKIE_OAUTH = 'voult_oauth';
+export const COOKIE_MFA_PENDING = 'voult_mfa_pending';
+
+export const ACCESS_MAX_AGE_MS = 60 * 60 * 1000;
+export const REFRESH_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+export const MFA_PENDING_MAX_AGE_MS = 5 * 60 * 1000;
+export const OAUTH_COOKIE_MAX_AGE_MS = 10 * 60 * 1000; // matches Voult's signed state lifetime
+
+/**
+ * Cookies are described as `{ name, value, options }` and written by the adapter: core signs
+ * them with WebCrypto, @voult/express hands them to `res.cookie()`. Same bytes either way.
+ * @typedef {import('./index.js').VoultConfig} VoultConfig
+ * @typedef {{ name: string, value: string, options: Record<string, unknown> }} CookieToSet
+ * @typedef {(name: string) => unknown} ReadCookie
+ */
+
+/**
+ * @param {VoultConfig} config
+ * @param {{ maxAge?: number }} [overrides]
+ */
+export function cookieOptions(config, overrides = {}) {
+  return {
+    httpOnly: true,
+    signed: Boolean(config.sessionSecret),
+    sameSite: 'lax',
+    secure: globalThis.process?.env?.NODE_ENV === 'production',
+    path: '/',
+    ...overrides,
+  };
+}
+
+/** @returns {CookieToSet} */
+export function setCookie(config, name, value, overrides) {
+  return { name, value, options: cookieOptions(config, overrides) };
+}
+
+/** Express `res.clearCookie()`: an empty value that expired in 1970. @returns {CookieToSet} */
+export function clearCookie(config, name) {
+  return { name, value: '', options: { ...cookieOptions(config), expires: new Date(1) } };
+}
+
+/** @returns {CookieToSet[]} */
+export function clearSessionCookies(config) {
+  return [COOKIE_ACCESS, COOKIE_REFRESH, COOKIE_USER].map((name) => clearCookie(config, name));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {object | null}
+ */
+export function parseUserCookie(value) {
+  if (!value) return null;
+  if (typeof value === 'object') return value;
+  if (typeof value !== 'string') return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {VoultConfig} config */
+export function createVoultClient(config) {
+  return new VoultClient({ clientId: config.clientId, clientSecret: config.clientSecret, baseURL: config.baseURL });
+}
+
+/**
+ * Restore the SDK session from cookies (cookie strategy) or the Authorization header (bearer).
+ * Returns what came in, so the outgoing side knows whether there was a session to clear.
+ * @param {VoultClient} client
+ * @param {{ read: ReadCookie, authorization?: string | null, refreshToken?: unknown }} incoming
+ * @param {VoultConfig} config
+ */
+export function restoreSession(client, { read, authorization, refreshToken: bearerRefresh }, config) {
+  let accessToken;
+  let refreshToken;
+  let user = null;
+
+  if (config.session.strategy === 'cookie') {
+    accessToken = read(COOKIE_ACCESS);
+    refreshToken = read(COOKIE_REFRESH);
+    user = parseUserCookie(read(COOKIE_USER));
+  } else {
+    if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+      accessToken = authorization.slice('Bearer '.length).trim();
+    }
+    refreshToken = bearerRefresh;
+  }
+
+  if (typeof accessToken === 'string' && accessToken.length > 0) {
+    client.setSession(user || {}, accessToken, refreshToken || null);
+  }
+
+  return { accessToken: client.accessToken || null, refreshToken: client.refreshToken || null };
+}
+
+/**
+ * The cookies that persist the client's session when the response goes out: fresh tokens,
+ * or a clear when a session that came in is gone (sign-out). Cookie strategy only.
+ * @returns {CookieToSet[]}
+ */
+export function sessionCookies(client, incoming, config) {
+  if (config.session.strategy !== 'cookie' || !client) return [];
+
+  if (client.accessToken) {
+    return [
+      setCookie(config, COOKIE_ACCESS, client.accessToken, { maxAge: ACCESS_MAX_AGE_MS }),
+      ...(client.refreshToken ? [setCookie(config, COOKIE_REFRESH, client.refreshToken, { maxAge: REFRESH_MAX_AGE_MS })] : []),
+      ...(client.user ? [setCookie(config, COOKIE_USER, JSON.stringify(client.user), { maxAge: REFRESH_MAX_AGE_MS })] : []),
+    ];
+  }
+
+  return incoming?.accessToken ? clearSessionCookies(config) : [];
+}
+
+/**
+ * The access cookie lives 1h, the refresh cookie 30 days: when only the refresh cookie is
+ * left, get a new access token instead of treating the user as signed out. The new tokens go
+ * out with the response (sessionCookies). A dead refresh token clears the session cookies,
+ * which this returns.
+ * @param {VoultClient} client
+ * @param {ReadCookie} read
+ * @param {VoultConfig} config
+ * @returns {Promise<CookieToSet[]>}
+ */
+export async function renewSession(client, read, config) {
+  if (!client || client.accessToken || config?.session?.strategy !== 'cookie') return [];
+
+  const refreshToken = read(COOKIE_REFRESH);
+  if (typeof refreshToken !== 'string' || !refreshToken) return [];
+
+  client.refreshToken = refreshToken;
+  try {
+    await refreshSession(client);
+    // The SDK only counts a client as signed in with a user object: reuse the (30-day)
+    // user cookie, or {} so the caller can fetch /user/me.
+    client.user = client.user ?? parseUserCookie(read(COOKIE_USER)) ?? {};
+    return [];
+  } catch {
+    client.clearSession();
+    return clearSessionCookies(config);
+  }
+}
+
+/**
+ * Cookie strategy keeps tokens in httpOnly cookies; bearer returns them in JSON.
+ * @param {object} result
+ * @param {VoultConfig} config
+ */
+export function toPublicAuthResult(result, config) {
+  if (!result || result.mfaRequired || config.session.strategy !== 'cookie') return result;
+  const { accessToken, refreshToken, token, ...rest } = result;
+  return rest;
+}
+
+/**
+ * The Voult session behind a Fetch API `Request`: a fresh VoultClient with the cookie or bearer
+ * session restored. For adapters (`@voult/next`'s `getSession`, middleware) and the router.
+ * @param {Request} request
+ * @param {VoultConfig} config
+ * @param {{ body?: Record<string, unknown> }} [options]
+ */
+export async function getSessionFromRequest(request, config, { body } = {}) {
+  const { cookies, signedCookies } = config.session.strategy === 'cookie'
+    ? await readCookieHeader(request.headers.get('cookie'), config.sessionSecret)
+    : { cookies: {}, signedCookies: {} };
+  /** @type {ReadCookie} */
+  const read = (name) => signedCookies[name] ?? cookies[name];
+
+  const client = createVoultClient(config);
+  const incoming = restoreSession(client, {
+    read,
+    authorization: request.headers.get('authorization'),
+    refreshToken: body?.refreshToken || request.headers.get('x-refresh-token'),
+  }, config);
+
+  return { client, incoming, read };
+}