Add sendEmail: boolean to mailbox challenges

Author: thobson

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-06-16
+
+### Added
+
+- `@passlock/server` mailbox challenge creation now accepts `sendEmail: true` to request Passlock-managed delivery for one-time-code emails. Omitting `sendEmail`, or passing `sendEmail: false`, preserves the existing generate-only behavior and keeps returning the generated `code` and rendered `message` for custom delivery.
+- 
+- `@passlock/server` and the `POST /v2/:tenancyId/challenges` REST API now accept an optional recipient `name` when creating mailbox challenges. The name is used for email delivery only and does not affect challenge scope, lookup, invalidation, or verification.
+
 ## [2.8.0] - 2026-06-15
 
 ### Added

examples/sveltekit/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@passlock/sveltekit-example",
-	"version": "2.8.0",
+	"version": "2.9.0",
 	"private": true,
 	"description": "SvelteKit app making full use of passkeys along with email based one time login codes",
 	"type": "module",

examples/sveltekit/src/lib/server/cookies.ts

@@ -7,8 +7,7 @@ import { SESSION_MAX_INACTIVE_MS } from './session';
  * specific browser session.
  *
  * The cookie stores the Passlock challenge id and secret. The user receives
- * the code separately by email, so both pieces are required to complete the
- * flow.
+ * the code separately, so both pieces are required to complete the flow.
  */
 
 // Signup and login share the same cookie because they are mutually exclusive

examples/sveltekit/src/lib/server/email/EmailChanged.svelte

@@ -8,9 +8,10 @@ email one-time-code flows:
 - email-change verification
 
 All three flows use Passlock mailbox challenges. The app creates a challenge,
-emails the one-time code to the user, stores the challenge id and secret in an
-HTTP-only cookie, and then verifies the submitted code against Passlock before
-applying the local state change.
+asks Passlock to send the one-time code in production, stores the challenge id
+and secret in an HTTP-only cookie, and then verifies the submitted code against
+Passlock before applying the local state change. In development, the app does
+not ask Passlock to send email and logs the code to the dev server console.
 
 ## End-to-end flow
 
@@ -20,8 +21,9 @@ The overall flow is the same for signup, login, and email change:
    directory.
 2. The helper creates a Passlock mailbox challenge with a `purpose`, optional
    `userId`, and flow-specific `metadata`.
-3. The route sends the returned `code` by email and stores `{ challengeId,
-secret }` in a short-lived HTTP-only cookie.
+3. The shared creation helper passes `sendEmail: true` only in production, logs
+   the returned `code` only in development, and the route stores
+   `{ challengeId, secret }` in a short-lived HTTP-only cookie.
 4. The verify-code page reloads the pending challenge from that cookie using
    `getPendingChallengeContext(...)`.
 5. When the user submits the 6-digit code, the action combines:
@@ -46,7 +48,8 @@ Key responsibilities:
 
 - `getPasslockMailboxChallenge(...)` loads an existing challenge from Passlock.
 - `createPasslockMailboxChallenge(...)` creates a challenge and normalises the
-  rate-limit result.
+  rate-limit result. It opts in to Passlock email delivery in production, while
+  keeping development and tests generate-only.
 - `verifyPasslockMailboxChallenge(...)` verifies a challenge and returns either
   `MailboxChallengeVerified` or a typed verification error.
 - `validateMailboxChallenge(...)` applies app-level checks after loading or
@@ -109,8 +112,7 @@ Login uses only the shared base metadata:
 Important types:
 
 - `LoginChallenge`: the validated local view of a login challenge
-- `CreatedLoginChallenge`: creation result used to send the email and set the
-  pending cookie
+- `CreatedLoginChallenge`: creation result used to set the pending cookie
 - `ConsumedChallenge`: shared success result with the resolved local
   `SessionUser`
 
@@ -125,8 +127,7 @@ Important types:
 
 - `EmailChangeChallenge`: validated local challenge including the bound numeric
   `userId`
-- `CreatedEmailChangeChallenge`: creation result used to send the email and set
-  the pending cookie
+- `CreatedEmailChangeChallenge`: creation result used to set the pending cookie
 - `EmailChangeSuccess`: success result after the local email address has been
   updated
 
@@ -164,7 +165,7 @@ Passlock already gives each challenge its own expiration window, but this sample
 adds a separate `processExpiresAt` value inside challenge metadata.
 
 That extra timestamp lets the app expire the whole local flow, not just the
-emailed code. In practice that means:
+one-time code. In practice that means:
 
 - signup details can expire even if the Passlock code itself still exists
 - login/email-change routes can reject stale pending flows consistently after a
@@ -180,7 +181,7 @@ The resend endpoints reuse the same primitives:
   `getPendingChallengeContext(...)`
 - they create a fresh challenge with the relevant `createOrRefresh*Challenge`
   helper
-- they send a new email and replace the pending cookie using
+- they create a fresh challenge and replace the pending cookie using
   `resendMailboxChallenge(...)`
 
 This keeps the resend routes thin while leaving all mailbox-specific validation

examples/sveltekit/src/lib/server/email/fake.ts

@@ -38,11 +38,6 @@ export type CreatedEmailChangeChallenge = {
 	_tag: 'CreatedChallenge';
 	challenge: EmailChangeChallenge;
 	secret: string;
-	code: string;
-	message: {
-		html: string;
-		text: string;
-	};
 };
 
 /**
@@ -51,7 +46,6 @@ export type CreatedEmailChangeChallenge = {
 export type EmailChangeSuccess = {
 	_tag: 'EmailChangeSuccess';
 	user: SessionUser;
-	oldEmail: string;
 };
 
 type EmailChangeMetadata = v.InferOutput<typeof BaseMetadataSchema>;
@@ -119,9 +113,7 @@ export const createOrRefreshEmailChallenge = async (input: {
 			userId: account.userId,
 			processExpiresAt
 		},
-		secret: challenge.secret,
-		code: challenge.code,
-		message: challenge.message
+		secret: challenge.secret
 	};
 };
 
@@ -158,12 +150,6 @@ export const consumeEmailChallenge = async (input: {
 		return createInvalidChallengeError('Challenge does not belong to the signed-in user');
 	}
 
-	const currentAccount = await getUserById(input.userId);
-	if (!currentAccount) {
-		console.error('Unable to load signed-in account', { userId: input.userId });
-		kitError(500, 'Unable to load signed-in account');
-	}
-
 	const existingAccount = await getUserByEmail(challenge.email);
 	if (existingAccount && existingAccount.userId !== input.userId) {
 		return { _tag: '@error/DuplicateUser', email: challenge.email };
@@ -180,7 +166,6 @@ export const consumeEmailChallenge = async (input: {
 
 	return {
 		_tag: 'EmailChangeSuccess',
-		user: updatedUser,
-		oldEmail: currentAccount.email
+		user: updatedUser
 	};
 };

examples/sveltekit/src/lib/server/email/index.ts

@@ -28,11 +28,6 @@ export type CreatedLoginChallenge = {
 	_tag: 'CreatedChallenge';
 	challenge: LoginChallenge;
 	secret: string;
-	code: string;
-	message: {
-		html: string;
-		text: string;
-	};
 };
 
 type LoginMetadata = v.InferOutput<typeof BaseMetadataSchema>;
@@ -86,9 +81,7 @@ export const createOrRefreshLoginChallenge = async (
 			email: challenge.email,
 			processExpiresAt
 		},
-		secret: challenge.secret,
-		code: challenge.code,
-		message: challenge.message
+		secret: challenge.secret
 	};
 };