@voult/core 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `@voult/core` are documented here.
 
+## 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):
+
+- **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:

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.2.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",
   "types": "./src/index.d.ts",
@@ -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,

package/src/handler.js

@@ -1,6 +1,7 @@
 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';
 
@@ -104,7 +105,7 @@ const defaultNotFound = () => Response.json(
  * @param {VoultConfig} config  A normalized config (`resolveConfig` / `loadConfigFromEnv`).
  */
 export function createVoultHandler(config) {
-  const routes = [...authRoutes, ...oauthRoutes()].map(compile);
+  const routes = [...authRoutes, ...passwordlessRoutes, ...oauthRoutes()].map(compile);
 
   /**
    * @param {Request} request

package/src/index.d.ts

@@ -88,6 +88,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

@@ -3,6 +3,7 @@
 export { createVoultHandler } from './handler.js';
 export { loadConfigFromEnv, resolveConfig } from './config.js';
 export { normalizeVoultError } 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

@@ -50,7 +50,7 @@ export function safeReturnTo(value, fallback) {
  * @param {string} path
  * @param {Record<string, string | undefined>} [params]
  */
-function appLocation(config, path, params = {}) {
+export function appLocation(config, path, params = {}) {
   const query = new URLSearchParams(
     Object.entries(params).filter(([, value]) => value != null && value !== '')
   ).toString();
@@ -69,14 +69,14 @@ export function oauthCallbackUrl(ctx) {
   return ctx.config.oauthCallbackUrl || `${ctx.url.protocol}//${ctx.url.host}${ctx.basePath}/oauth/callback`;
 }
 
-function redirectWithError(config, code, description) {
+export function redirectWithError(config, code, description) {
   return redirect(appLocation(config, config.oauth.errorPath, {
     voult_error: code,
     voult_error_description: description,
   }));
 }
 
-function errorCode(err) {
+export function errorCode(err) {
   return err?.apiCode || err?.code || 'OAUTH_FAILED';
 }
 
@@ -100,6 +100,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);

package/src/passwordless.js

@@ -0,0 +1,94 @@
+import {
+  createPasskeyLoginOptions,
+  createPasskeyRegistrationOptions,
+  deletePasskey,
+  listPasskeys,
+  signInWithEmailLink,
+  updatePasskey,
+  verifyEmailLink,
+  verifyPasskeyLogin,
+  verifyPasskeyRegistration,
+} from '@voult/sdk';
+import { appLocation, errorCode, oauthCallbackUrl, redirectWithError, 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';
+
+// Passkeys and magic links: sign-ins without a password.
+//   Passkeys: the page runs the WebAuthn ceremony (@simplewebauthn/browser or navigator.credentials)
+//   with the options from here, then posts the browser's credential back.
+//   Magic links: Voult emails a link to GET /magic-link/verify on this server, which sets the
+//   session and redirects like the OAuth callback.
+
+/**
+ * @typedef {import('./handler.js').Context} Context
+ * @typedef {import('./handler.js').Route} Route
+ */
+
+/**
+ * The URL magic links open: next to the OAuth callback, so the one callback URL on the app's
+ * allowlist covers it too (Voult accepts any page on an allowlisted callback's origin).
+ * @param {Context} ctx
+ */
+function magicLinkUrl(ctx) {
+  const url = new URL(oauthCallbackUrl(ctx));
+  url.pathname = url.pathname.endsWith('/oauth/callback')
+    ? url.pathname.replace(/\/oauth\/callback$/, '/magic-link/verify')
+    : `${ctx.basePath}/magic-link/verify`;
+  url.search = '';
+  return url;
+}
+
+/** @type {Route[]} */
+export const passwordlessRoutes = [
+  ['POST', '/passkeys/register/options', authenticated(async (ctx) => (
+    json(await createPasskeyRegistrationOptions({ deviceName: ctx.body.deviceName }, ctx.client))
+  ))],
+  ['POST', '/passkeys/register/verify', authenticated(async (ctx) => (
+    json(await verifyPasskeyRegistration(ctx.body.credential, { deviceName: ctx.body.deviceName }, ctx.client))
+  ))],
+  ['GET', '/passkeys', authenticated(async (ctx) => json(await listPasskeys(ctx.client)))],
+  ['PATCH', '/passkeys/:id', authenticated(async (ctx) => (
+    json(await updatePasskey(ctx.params.id, ctx.body.deviceName, ctx.client))
+  ))],
+  ['DELETE', '/passkeys/:id', authenticated(async (ctx) => json(await deletePasskey(ctx.params.id, ctx.client)))],
+
+  // 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))
+  )],
+  ['POST', '/passkeys/login/verify', async (ctx) => authResult(ctx, await verifyPasskeyLogin(ctx.body.credential, 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.
+  ['POST', '/magic-link', async (ctx) => {
+    const url = magicLinkUrl(ctx);
+    const returnTo = safeReturnTo(ctx.body.returnTo, '');
+    if (returnTo) url.searchParams.set('returnTo', returnTo);
+    try {
+      await signInWithEmailLink(ctx.body.email, { redirectUri: url.href }, ctx.client);
+    } catch (err) {
+      if (err?.status !== 404) throw err;
+    }
+    return json({ sent: true });
+  }],
+
+  // ponytail: a GET that spends a one-time token: mail scanners that open links can use it up first.
+  // Upgrade path: a confirm page that POSTs, if users report "link expired" on first click.
+  ['GET', '/magic-link/verify', async (ctx) => {
+    const { config } = ctx;
+    let result;
+    try {
+      result = await verifyEmailLink(ctx.query('token'), ctx.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, safeReturnTo(ctx.query('returnTo'), config.oauth.successPath)));
+  }],
+];

package/src/routes.js

@@ -1,7 +1,16 @@
 import {
   AuthenticationError,
+  ENDPOINTS,
+  deleteUser,
+  disableMfa,
+  enableMfa,
   getCurrentUser,
+  getLinkedOAuthProviders,
   getMfaStatus,
+  regenerateMfaBackupCodes,
+  revokeSession,
+  setupMfa,
+  unlinkOAuthProvider,
   refreshSession,
   resetPassword,
   sendPasswordResetEmail,
@@ -15,7 +24,14 @@ import {
   verifyMfaLogin,
 } from '@voult/sdk';
 import { normalizeVoultError } from './errors.js';
-import { COOKIE_MFA_PENDING, MFA_PENDING_MAX_AGE_MS, clearCookie, setCookie, toPublicAuthResult } from './session.js';
+import {
+  COOKIE_MFA_PENDING,
+  MFA_PENDING_MAX_AGE_MS,
+  clearCookie,
+  clearSessionCookies,
+  setCookie,
+  toPublicAuthResult,
+} from './session.js';
 
 /**
  * @typedef {import('./handler.js').Context} Context
@@ -44,7 +60,7 @@ export function authenticated(handler) {
 }
 
 /** @param {Context} ctx @param {object} result */
-function authResult(ctx, result) {
+export 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') {
@@ -53,6 +69,23 @@ function authResult(ctx, result) {
   return json(toPublicAuthResult(result, ctx.config));
 }
 
+/** The session is over on this device (account disabled, own session revoked): drop it and its cookies. */
+function endLocalSession(ctx) {
+  ctx.client.clearSession();
+  ctx.cookies.push(...clearSessionCookies(ctx.config));
+}
+
+/**
+ * The user's sessions, with `isCurrent` on this browser's. The API marks it when it sees the
+ * refresh token, which only this server holds (never the page).
+ * @param {Context} ctx
+ */
+async function listSessions(ctx) {
+  const headers = ctx.client.refreshToken ? { 'X-Refresh-Token': ctx.client.refreshToken } : {};
+  const response = await ctx.client.get(ENDPOINTS.SESSIONS, { requireAuth: true, headers });
+  return { sessions: response.sessions ?? [] };
+}
+
 /** @type {Route[]} */
 export const authRoutes = [
   ['GET', '/session', async (ctx) => {
@@ -131,4 +164,41 @@ export const authRoutes = [
   }],
 
   ['GET', '/mfa/status', authenticated(async (ctx) => json(await getMfaStatus(ctx.client)))],
+
+  // MFA enrolment: setup returns the secret, QR code and backup codes; enable confirms with a code.
+  ['POST', '/mfa/setup', authenticated(async (ctx) => json(await setupMfa(ctx.client)))],
+  ['POST', '/mfa/enable', authenticated(async (ctx) => json(await enableMfa(ctx.body.code, ctx.client)))],
+  // `password` is optional so accounts created with Google/GitHub (no password) can turn MFA off.
+  ['POST', '/mfa/disable', authenticated(async (ctx) => (
+    json(await disableMfa(ctx.body.password, ctx.body.code, ctx.client))
+  ))],
+  ['POST', '/mfa/backup-codes', authenticated(async (ctx) => (
+    json(await regenerateMfaBackupCodes(ctx.body.code, ctx.client))
+  ))],
+  // Abandon a sign-in waiting for its MFA code (there's no session yet, so /logout can't).
+  ['POST', '/mfa/cancel', async (ctx) => {
+    ctx.cookies.push(clearCookie(ctx.config, COOKIE_MFA_PENDING));
+    return json({ success: true });
+  }],
+
+  ['GET', '/sessions', authenticated(async (ctx) => json(await listSessions(ctx)))],
+  ['DELETE', '/sessions/:id', authenticated(async (ctx) => {
+    const { sessions } = await listSessions(ctx);
+    const current = sessions.some((session) => String(session.id) === ctx.params.id && session.isCurrent);
+    const result = await revokeSession(ctx.params.id, ctx.client);
+    if (current) endLocalSession(ctx);
+    return json({ ...result, current });
+  })],
+
+  ['GET', '/oauth/linked', authenticated(async (ctx) => json(await getLinkedOAuthProviders(ctx.client)))],
+  ['DELETE', '/oauth/linked/:provider', authenticated(async (ctx) => (
+    json(await unlinkOAuthProvider(ctx.params.provider, ctx.client))
+  ))],
+
+  // 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);
+    endLocalSession(ctx);
+    return json(result);
+  })],
 ];