@voult/core 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@voult/core` are documented here.
 
+## 0.3.1
+
+- New route `POST /user/password` (`{ password }`): a user who signed up with Google or GitHub adds a password, so email + password sign-in works too. Checked against the password rule before Voult is called.
+- New route `GET /user/activity?limit=20&skip=0`: the signed-in user's own audit log (sign-ins, MFA and password changes, …), newest first.
+- `@voult/express` and `@voult/next` get both with a fresh install (they depend on `^0.3.0`).
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voult/core",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",
@@ -37,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';

package/src/index.js

@@ -2,7 +2,7 @@
 // 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,

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() {
@@ -155,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.
@@ -197,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) {

package/src/routes.js

@@ -9,6 +9,7 @@ import {
   getMfaStatus,
   regenerateMfaBackupCodes,
   revokeSession,
+  setPassword,
   setupMfa,
   unlinkOAuthProvider,
   refreshSession,
@@ -195,6 +196,16 @@ export const authRoutes = [
     json(await unlinkOAuthProvider(ctx.params.provider, ctx.client))
   ))],
 
+  // Signed up with Google/GitHub only: add a password, so email + password sign-in works too.
+  ['POST', '/user/password', authenticated(async (ctx) => json(await setPassword(ctx.body.password, ctx.client)))],
+
+  // The user's own activity (sign-ins, MFA and password changes, …), newest first. ?limit=&skip=
+  // (No SDK function for it yet, so the client calls the API path directly.)
+  ['GET', '/user/activity', authenticated(async (ctx) => json(await ctx.client.get('/api/audit-logs/me', {
+    requireAuth: true,
+    params: { limit: ctx.query('limit') ?? '20', skip: ctx.query('skip') ?? '0' },
+  })))],
+
   // Voult disables the account (it can be re-enabled), and this browser is signed out.
   ['DELETE', '/user/me', authenticated(async (ctx) => {
     const result = await deleteUser(ctx.client);