@voult/core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@voult/core` are documented here.
 
+## 0.3.0
+
+- **Breaking: error codes are the Voult API's.** A failed request now answers with the API's catalog code (`INVALID_CREDENTIALS`, `USER_EXISTS`, `WEAK_PASSWORD`, see ERRORS.md) instead of the SDK's category (`AUTHENTICATION_ERROR`, `CONFLICT_ERROR`, `VALIDATION_ERROR`). Errors raised by the router itself keep their codes (`AUTHENTICATION_ERROR` for "Authentication required", `INVALID_JSON`, `PAYLOAD_TOO_LARGE`). If you branch on `code`, switch to the catalog codes; branching on `status` is unaffected.
+- **Internal errors stay on the server.** 5xx, network failures and unexpected errors are logged in full (`console.error`, with the method and path) and reach the browser only as `{ code: 'INTERNAL_ERROR', message: 'Something went wrong. Please try again.' }`. 4xx messages (things the user can fix) are unchanged. The same applies to `?voult_error=` on the OAuth and magic-link error pages. New exports `publicError(err, { log, context })` and `GENERIC_ERROR_MESSAGE`.
+- Passkey routes send the page's origin (the browser's `Origin` header, else the request's own origin) so Voult API 1.4 can use the right passkey domain. Needs `@voult/sdk` 0.2.2.
+
+## 0.2.1
+
+- New route `GET /session/renew?returnTo=/path`: renews the session from the refresh cookie, saves the new cookies and redirects back (or to `errorPath?voult_error=SESSION_EXPIRED`). For pages rendered where cookies can't be written, such as Next.js Server Components: renewing there would rotate the refresh token without saving it, and Voult's reuse detection would then end the session.
+- New entry point `@voult/core/cookies` (signing and cookie parsing only, no `@voult/sdk`), for Edge middleware.
+- `parseUserCookie` and `safeReturnTo` are exported.
+
 ## 0.2.0
 
 The router now serves every end-user feature, so apps write no auth route handlers. New routes (below the mount path):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voult/core",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -10,6 +10,11 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
+    },
+    "./cookies": {
+      "types": "./src/index.d.ts",
+      "import": "./src/cookies.js",
+      "default": "./src/cookies.js"
     }
   },
   "sideEffects": false,
@@ -32,7 +37,7 @@
   "author": "Samuel Olabode",
   "license": "MIT",
   "peerDependencies": {
-    "@voult/sdk": ">=0.2.0"
+    "@voult/sdk": ">=0.2.2"
   },
   "devDependencies": {
     "@voult/sdk": "*",

package/src/errors.js

@@ -1,29 +1,40 @@
 import { VoultError } from '@voult/sdk';
 
+export const GENERIC_ERROR_MESSAGE = 'Something went wrong. Please try again.';
+
 /**
- * Normalize SDK and unexpected errors into a stable JSON shape.
+ * What the browser may see of an error. 4xx are things the user can fix (wrong password, email
+ * taken, locked, too many attempts): their message stays, and the code is the Voult API's own
+ * (`INVALID_CREDENTIALS`, as in ERRORS.md) when there is one. Everything else (5xx, network,
+ * bugs) is logged in full on the server and reaches the browser only as a generic message.
  * @param {unknown} err
+ * @param {{ log?: (...args: unknown[]) => void, context?: string }} [options]
+ * @returns {{ code: string, message: string, status: number, field?: string, fields?: unknown }}
  */
-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 } : {}),
-      },
-    };
+export function publicError(err, { log = console.error, context = '' } = {}) {
+  const isVoult = err instanceof VoultError;
+  const status = typeof err?.status === 'number' && err.status >= 400 ? err.status : 500;
+
+  if (status >= 500) {
+    log(`[voult]${context ? ` ${context}` : ''} failed:`, err);
+    return { code: 'INTERNAL_ERROR', message: GENERIC_ERROR_MESSAGE, status };
   }
 
-  const status = typeof err?.status === 'number' ? err.status : 500;
+  const apiCode = isVoult && err.apiCode && err.apiCode !== 'UNKNOWN_ERROR' ? err.apiCode : undefined;
   return {
-    error: {
-      code: err?.code || 'INTERNAL_ERROR',
-      message: err?.message || 'Internal server error',
-      status,
-    },
+    code: apiCode ?? err?.code ?? 'BAD_REQUEST',
+    message: err?.message || 'Request failed',
+    status,
+    ...(err?.field ? { field: err.field } : {}),
+    ...(err?.fields ? { fields: err.fields } : {}),
   };
 }
+
+/**
+ * The JSON body for an error: `{ error: { code, message, status } }` (see publicError).
+ * @param {unknown} err
+ * @param {{ log?: (...args: unknown[]) => void, context?: string }} [options]
+ */
+export function normalizeVoultError(err, options) {
+  return { error: publicError(err, options) };
+}

package/src/handler.js

@@ -144,7 +144,7 @@ export function createVoultHandler(config) {
       };
       result = await found.handler(ctx);
     } catch (err) {
-      const payload = normalizeVoultError(err);
+      const payload = normalizeVoultError(err, { context: `${request.method} ${url.pathname}` });
       result = json(payload, payload.error.status);
     }
 

package/src/index.d.ts

@@ -68,7 +68,12 @@ export type VoultHandler = (request: Request, options?: HandleOptions) => Promis
 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 interface PublicError { code: string; message: string; status: number; field?: string; fields?: unknown }
+export interface ErrorOptions { log?: (...args: unknown[]) => void; context?: string }
+export const GENERIC_ERROR_MESSAGE: string;
+/** 4xx: message kept, code = the Voult API's (ERRORS.md). 5xx/unexpected: logged on the server, generic for the browser. */
+export function publicError(err: unknown, options?: ErrorOptions): PublicError;
+export function normalizeVoultError(err: unknown, options?: ErrorOptions): { error: PublicError };
 
 export const COOKIE_ACCESS: 'voult_access';
 export const COOKIE_REFRESH: 'voult_refresh';
@@ -88,6 +93,9 @@ export function restoreSession(
   config: VoultConfig
 ): IncomingSession;
 export function sessionCookies(client: VoultClient, incoming: IncomingSession, config: VoultConfig): CookieToSet[];
+/** `value` when it's a same-site relative path (`/x`, not `//x` or `https://…`), else `fallback`. */
+export function safeReturnTo(value: unknown, fallback: string): string;
+export function parseUserCookie(value: unknown): Record<string, unknown> | null;
 export function renewSession(client: VoultClient, read: ReadCookie, config: VoultConfig): Promise<CookieToSet[]>;
 
 export function readCookieHeader(header: string | null | undefined, secret?: string): Promise<{

package/src/index.js

@@ -2,7 +2,8 @@
 // Apps install an adapter, not this package.
 export { createVoultHandler } from './handler.js';
 export { loadConfigFromEnv, resolveConfig } from './config.js';
-export { normalizeVoultError } from './errors.js';
+export { GENERIC_ERROR_MESSAGE, normalizeVoultError, publicError } from './errors.js';
+export { safeReturnTo } from './oauth.js';
 export {
   COOKIE_ACCESS,
   COOKIE_MFA_PENDING,
@@ -11,6 +12,7 @@ export {
   COOKIE_USER,
   createVoultClient,
   getSessionFromRequest,
+  parseUserCookie,
   renewSession,
   restoreSession,
   sessionCookies,

package/src/oauth.js

@@ -5,6 +5,7 @@ import {
   linkOAuthProvider,
 } from '@voult/sdk';
 import { base64 } from './cookies.js';
+import { publicError } from './errors.js';
 import { json, redirect } from './routes.js';
 import {
   COOKIE_MFA_PENDING,
@@ -76,8 +77,10 @@ export function redirectWithError(config, code, description) {
   }));
 }
 
-export function errorCode(err) {
-  return err?.apiCode || err?.code || 'OAUTH_FAILED';
+/** A failed step as `?voult_error=<code>&voult_error_description=<message>` (publicError rules). */
+export function redirectWithFailure(config, err, context) {
+  const { code, message } = publicError(err, { context });
+  return redirectWithError(config, code, message);
 }
 
 function newNonce() {
@@ -100,6 +103,19 @@ export function oauthRoutes() {
   let providersCache = { at: 0, value: null };
 
   return [
+    // For pages rendered where cookies can't be written (Next.js Server Components): renewing
+    // there would rotate the refresh token without saving it. They send the browser here
+    // instead; this renews, saves the new cookies and goes back.
+    ['GET', '/session/renew', async (ctx) => {
+      // The caller already knows the access token is stale (its cookie outlives the token).
+      ctx.client.accessToken = null;
+      await ctx.renew();
+      const back = safeReturnTo(ctx.query('returnTo'), ctx.config.oauth.successPath);
+      return ctx.client.accessToken
+        ? redirect(appLocation(ctx.config, back))
+        : redirectWithError(ctx.config, 'SESSION_EXPIRED', 'Please sign in again.');
+    }],
+
     ['GET', '/oauth/providers', async (ctx) => {
       if (!providersCache.value || Date.now() - providersCache.at > PROVIDERS_CACHE_MS) {
         const info = await getAppInfo(ctx.client);
@@ -142,7 +158,7 @@ export function oauthRoutes() {
           ? await linkOAuthProvider(provider, { redirectUri, state: nonce }, client)
           : await getOAuthAuthorizationUrl(provider, { intent, redirectUri, state: nonce }, client));
       } catch (err) {
-        return redirectWithError(config, errorCode(err), err.message);
+        return redirectWithFailure(config, err, 'OAuth');
       }
 
       // Ties the callback to this browser: Voult echoes `state`, we compare it to this cookie.
@@ -184,7 +200,7 @@ export function oauthRoutes() {
       try {
         result = await exchangeOAuthCode(voultCode, { redirectUri: saved.redirectUri }, client);
       } catch (err) {
-        return redirectWithError(config, errorCode(err), err.message);
+        return redirectWithFailure(config, err, 'OAuth');
       }
 
       if (result.mfaRequired) {

package/src/passwordless.js

@@ -9,7 +9,7 @@ import {
   verifyPasskeyLogin,
   verifyPasskeyRegistration,
 } from '@voult/sdk';
-import { appLocation, errorCode, oauthCallbackUrl, redirectWithError, safeReturnTo } from './oauth.js';
+import { appLocation, oauthCallbackUrl, redirectWithFailure, safeReturnTo } from './oauth.js';
 import { authResult, authenticated, json, redirect } from './routes.js';
 import { COOKIE_MFA_PENDING, MFA_PENDING_MAX_AGE_MS, setCookie } from './session.js';
 
@@ -38,13 +38,21 @@ function magicLinkUrl(ctx) {
   return url;
 }
 
+/**
+ * The page running the passkey ceremony: the browser's Origin header, else this request's own
+ * origin (same-origin setups). Voult picks the passkey domain (RP ID) from it, among the app's
+ * allowlisted origins.
+ * @param {Context} ctx
+ */
+const pageOrigin = (ctx) => ctx.request.headers.get('origin') ?? `${ctx.url.protocol}//${ctx.url.host}`;
+
 /** @type {Route[]} */
 export const passwordlessRoutes = [
   ['POST', '/passkeys/register/options', authenticated(async (ctx) => (
-    json(await createPasskeyRegistrationOptions({ deviceName: ctx.body.deviceName }, ctx.client))
+    json(await createPasskeyRegistrationOptions({ deviceName: ctx.body.deviceName, origin: pageOrigin(ctx) }, ctx.client))
   ))],
   ['POST', '/passkeys/register/verify', authenticated(async (ctx) => (
-    json(await verifyPasskeyRegistration(ctx.body.credential, { deviceName: ctx.body.deviceName }, ctx.client))
+    json(await verifyPasskeyRegistration(ctx.body.credential, { deviceName: ctx.body.deviceName, origin: pageOrigin(ctx) }, ctx.client))
   ))],
   ['GET', '/passkeys', authenticated(async (ctx) => json(await listPasskeys(ctx.client)))],
   ['PATCH', '/passkeys/:id', authenticated(async (ctx) => (
@@ -54,9 +62,9 @@ export const passwordlessRoutes = [
 
   // Public: sign in with a passkey. Sets the session (or the MFA-pending cookie) like password sign-in.
   ['POST', '/passkeys/login/options', async (ctx) => (
-    json(await createPasskeyLoginOptions(ctx.body.email ? { email: ctx.body.email } : {}, ctx.client))
+    json(await createPasskeyLoginOptions({ ...(ctx.body.email && { email: ctx.body.email }), origin: pageOrigin(ctx) }, ctx.client))
   )],
-  ['POST', '/passkeys/login/verify', async (ctx) => authResult(ctx, await verifyPasskeyLogin(ctx.body.credential, ctx.client))],
+  ['POST', '/passkeys/login/verify', async (ctx) => authResult(ctx, await verifyPasskeyLogin(ctx.body.credential, { origin: pageOrigin(ctx) }, ctx.client))],
 
   // Public. Answers the same whether or not the email has an account, so it can't be used to
   // find out who signed up. Mistakes in the request or the app's setup still come back as errors.
@@ -80,7 +88,7 @@ export const passwordlessRoutes = [
     try {
       result = await verifyEmailLink(ctx.query('token'), ctx.client);
     } catch (err) {
-      return redirectWithError(config, errorCode(err), err.message);
+      return redirectWithFailure(config, err, 'magic link');
     }
 
     if (result.mfaRequired) {