fix(login): answer a decoy under external delivery with nothing to mail (#322)

Under external delivery the decoy responders for an OTP send and a magic
link request fabricated a delivery block for shape parity, addressed to the
decoy's synthetic @example.invalid email. The SDK mailed it, the domain
never resolves, and the adopter's provider retried for fourteen hours and
then bounced it against the adopter's sending identity. Every sign-in
attempt for an unknown address was a guaranteed bounce on traffic the
adopter does not control.

The block is only readable with a service token, so omitting it discloses
nothing to a stranger, and the SDK already sends nothing when it is absent.
The magic link responder still runs the redirect check for its refusal and
discards the URL. decoyOtpFor had no other reason to exist and is removed.

Closes #321

Co-authored-by: Brandon Corbett <Bccorb@users.noreply.github.com>

Author: Bccorb

.changeset/decoy-external-delivery.md

@@ -0,0 +1,18 @@
+---
+'seamless-auth-api': patch
+---
+
+A decoy continuation under external delivery no longer hands the SDK a message to send.
+
+When an adopter runs external delivery, the decoy responders for an OTP send and a magic
+link request answered with a `delivery` block like a real account's, addressed to the
+decoy's synthetic `@example.invalid` email. The SDK mailed it, the domain never resolves,
+and the adopter's mail provider retried for hours and then bounced it against the
+adopter's sending identity. Every sign-in attempt for an unknown address was a guaranteed
+bounce, fourteen hours later, on traffic the adopter does not control (#321).
+
+The responders now omit the block. It is only readable by a caller holding a service
+token, so a stranger sees the same answer as before, and the SDK's `deliverAuthMessage`
+already sends nothing when the block is absent. `decoyOtpFor` had no other reason to
+exist and is removed. `docs/security-posture.md` says why parity at the SDK's edge was
+not worth a bounce per probe.

docs/security-posture.md

@@ -165,11 +165,22 @@ key there means a coordinated release across both SDKs for an operational tuning
   understand what happened. Accepted, unchanged.
 - **A malformed identifier** answers `400`. This does not depend on whether any account
   exists, so it is not an enumeration signal.
-- **External delivery mode** returns a fabricated code and the decoy's synthetic address
-  rather than the identifier the caller supplied, so a caller comparing the two can tell.
-  That mode requires a valid internal service token, which makes the caller a trusted
-  backend that can enumerate through the admin API anyway. Accepted, and the reason it is
-  acceptable is the service token, not the fabrication.
+- **External delivery mode** answers a real OTP or magic link request with a `delivery`
+  block, the address and the code for the SDK to send, and answers a decoy with none. A
+  caller that can read the block can tell. That mode requires a valid internal service
+  token, which makes the caller a trusted backend that can enumerate through the admin
+  API anyway. Accepted, and the reason it is acceptable is the service token.
+
+  The block used to be fabricated for a decoy instead, for shape parity. It was addressed
+  to the decoy's synthetic `@example.invalid` email, and the SDK mailed it, because
+  mailing whatever it is handed is the SDK's job in that mode. The domain never resolves,
+  so every probe of an unknown identifier became a message the adopter's mail provider
+  retried for hours and then bounced against the adopter's sending identity (#321).
+  Parity at the SDK's edge is what the fabrication bought, and it is not worth a bounce
+  per probe: a decoy skipping the send answers faster than a real account, but that is
+  the same difference direct delivery already carries on these endpoints, where the real
+  handler's send is in-process and the decoy's is not.
+
 - **A deleted or revoked account** mid-flow is answered as a decoy rather than with a
   distinguishable `401`. That is the intended behaviour, and it means such a user sees a
   continuation that quietly never succeeds rather than a clear rejection.

src/controllers/decoyResponders.ts

@@ -8,15 +8,10 @@ import { generateAuthenticationOptions } from '@simplewebauthn/server';
 import { Request, Response } from 'express';
 
 import { getSystemConfig } from '../config/getSystemConfig.js';
-import { canReturnExternalDelivery } from '../lib/externalDelivery.js';
 import { signEphemeralToken } from '../lib/token.js';
 import { buildPrfAuthenticationExtensions } from '../lib/webauthnPrf.js';
 import { AuthEventService } from '../services/authEventService.js';
-import {
-  decoyCredentialIdFor,
-  decoyOtpFor,
-  decoyPrincipalForSubject,
-} from '../services/decoyPrincipal.js';
+import { decoyCredentialIdFor, decoyPrincipalForSubject } from '../services/decoyPrincipal.js';
 import {
   getLoginPolicy,
   isLoginMethodEnabled,
@@ -45,6 +40,12 @@ import { hashDeviceFingerprint } from '../utils/utils.js';
  *   records is the exception, and it is the one every request already writes.
  * - **No real handler.** `defineRoute` dispatches here instead of the controller, so the
  *   stand-in principal never reaches code that could persist it.
+ * - **No delivery block.** In external delivery mode a real send answers with the
+ *   address and the code for the SDK to mail. A decoy never does, whatever the header
+ *   says. The block is only readable by a caller holding a service token, so omitting it
+ *   discloses nothing to a stranger, and the alternative is the SDK mailing a synthetic
+ *   `@example.invalid` address for real: every one bounces, against the adopter's
+ *   sending reputation, fourteen hours after the probe.
  *
  * Policy-dependent branches are reproduced rather than skipped. A deployment with
  * `email_otp` disabled answers `403 login_method_disabled` for every identifier, so a
@@ -102,7 +103,6 @@ async function rejectDisabledMethod(method: LoginMethod, req: Request, res: Resp
 async function respondOtpSent(req: Request, res: Response, kind: 'otp_email' | 'otp_sms') {
   const authReq = req as AuthenticatedRequest;
   const subject = decoySubject(req);
-  const useExternalDelivery = await canReturnExternalDelivery(req);
 
   await logDecoy(req, `otp:${kind}`);
 
@@ -115,19 +115,7 @@ async function respondOtpSent(req: Request, res: Response, kind: 'otp_email' | '
 
   const token = await signEphemeralToken(subject, authReq.attemptId);
 
-  return res.status(200).json({
-    message: 'success',
-    token,
-    ...(useExternalDelivery
-      ? {
-          delivery: {
-            kind,
-            to: kind === 'otp_email' ? authReq.user.email : authReq.user.phone,
-            token: decoyOtpFor(subject),
-          },
-        }
-      : {}),
-  });
+  return res.status(200).json({ message: 'success', token });
 }
 
 export const decoySendEmailOtp = (req: Request, res: Response) =>
@@ -187,22 +175,19 @@ export const decoyRequestMagicLink = async (req: Request, res: Response) => {
     return;
   }
 
-  const authReq = req as AuthenticatedRequest;
-  const useExternalDelivery = await canReturnExternalDelivery(req);
-
   await logDecoy(req, 'magic_link:request');
 
-  const rawToken = decoyCredentialIdFor(decoySubject(req));
-
   // Both checks below answer 400 for a real account before anything is stored, and both
   // are reachable by choice: a caller picks the redirect it sends, and omitting a
   // User-Agent header is enough to trip the second. A decoy that skipped them would
   // answer 200 where a real account answers 400, which is a working oracle for the price
-  // of one deliberately bad request.
-  let magicLinkUrl: string;
-
+  // of one deliberately bad request. The URL the first one builds goes nowhere, since
+  // nothing is mailed; the call is made for its refusal.
   try {
-    magicLinkUrl = await resolveMagicLinkUrl(rawToken, req.query.redirectUri as string | undefined);
+    await resolveMagicLinkUrl(
+      decoyCredentialIdFor(decoySubject(req)),
+      req.query.redirectUri as string | undefined,
+    );
   } catch (error) {
     if (error instanceof MagicLinkRedirectNotAllowedError) {
       return res.status(400).json({ error: 'Redirect URI is not allowed' });
@@ -217,19 +202,7 @@ export const decoyRequestMagicLink = async (req: Request, res: Response) => {
     return res.status(400).json({ error: 'Invalid device data' });
   }
 
-  return res.json({
-    message: 'If an account exists, a login link has been sent.',
-    ...(useExternalDelivery
-      ? {
-          delivery: {
-            kind: 'magic_link_email',
-            to: authReq.user.email,
-            token: rawToken,
-            magicLinkUrl,
-          },
-        }
-      : {}),
-  });
+  return res.json({ message: 'If an account exists, a login link has been sent.' });
 };
 
 /**

src/services/decoyPrincipal.ts

@@ -33,7 +33,6 @@ import { User } from '../models/users.js';
 const DECOY_SUBJECT_INFO = 'seamless-auth/decoy-subject';
 const DECOY_EMAIL_INFO = 'seamless-auth/decoy-email';
 const DECOY_PHONE_INFO = 'seamless-auth/decoy-phone';
-const DECOY_OTP_INFO = 'seamless-auth/decoy-otp';
 const DECOY_CREDENTIAL_INFO = 'seamless-auth/decoy-credential';
 const DECOY_SHAPE_INFO = 'seamless-auth/decoy-shape';
 
@@ -116,15 +115,6 @@ function decoyPhoneFor(subject: string) {
   return `+1555${digits.toString().padStart(7, '0')}`;
 }
 
-/**
- * The code a decoy's OTP "is". Nothing ever compares against it, since a decoy
- * verification always fails, but external delivery mode returns the generated code in
- * the response body and a decoy has to put something of the right shape there.
- */
-export function decoyOtpFor(subject: string) {
-  return (derive(DECOY_OTP_INFO, subject).readUInt32BE(0) % 1_000_000).toString().padStart(6, '0');
-}
-
 /**
  * A credential id for the fabricated allow-list a decoy's WebAuthn challenge offers.
  * Base64url of 32 bytes, matching what a real credential id looks like on the wire.

tests/integration/authentication/decoyContinuation.spec.ts

@@ -57,6 +57,7 @@ import { signEphemeralToken } from '../../../src/lib/token.js';
 import { WebAuthnChallenge } from '../../../src/models/webauthnChallenges.js';
 import { generateEmailOTP, generatePhoneOTP } from '../../../src/utils/otp.js';
 import { hashDeviceFingerprint } from '../../../src/utils/utils.js';
+import { mintInternalServiceToken } from '../../factories/serviceTokenFactory.js';
 
 let app: Application;
 
@@ -121,6 +122,25 @@ describe('decoy continuation: OTP', () => {
     expect(generatePhoneOTP).not.toHaveBeenCalled();
   });
 
+  it.each([['/otp/generate-email-otp'], ['/otp/generate-login-email-otp']])(
+    'hands the SDK nothing to mail for %s under external delivery',
+    async (path) => {
+      // A real send in this mode answers with the address and the code for the SDK to
+      // mail. A decoy's address is `@example.invalid`, so a block here would be a real
+      // message the SDK sends and SES bounces fourteen hours later, against the
+      // adopter's identity. The block is only readable with a service token, so leaving
+      // it out discloses nothing to a stranger.
+      const res = await request(app)
+        .get(path)
+        .set('x-seamless-auth-delivery-mode', 'external')
+        .set('x-seamless-service-token', await mintInternalServiceToken());
+
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ message: 'success', token: 'decoy-token' });
+      expect(res.body).not.toHaveProperty('delivery');
+    },
+  );
+
   it.each([
     ['/otp/verify-email-otp'],
     ['/otp/verify-phone-otp'],
@@ -156,6 +176,17 @@ describe('decoy continuation: magic link', () => {
     expect(res.body.message).toBe('If an account exists, a login link has been sent.');
   });
 
+  it('hands the SDK nothing to mail under external delivery', async () => {
+    const res = await request(app)
+      .get('/magic-link')
+      .set('x-seamless-auth-delivery-mode', 'external')
+      .set('x-seamless-service-token', await mintInternalServiceToken());
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ message: 'If an account exists, a login link has been sent.' });
+    expect(res.body).not.toHaveProperty('delivery');
+  });
+
   it('polls as an unclicked link forever', async () => {
     const res = await request(app).get('/magic-link/check');
 

tests/unit/services/decoyPrincipal.spec.ts

@@ -2,7 +2,6 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
   decoyCredentialIdFor,
-  decoyOtpFor,
   decoyPrincipalForSubject,
   decoySubjectFor,
 } from '../../../src/services/decoyPrincipal.js';
@@ -121,13 +120,6 @@ describe('decoy principal', () => {
 });
 
 describe('fabricated secrets', () => {
-  it('produces a six digit OTP', () => {
-    const subject = decoySubjectFor('nobody@example.com', 'email');
-
-    expect(decoyOtpFor(subject)).toMatch(/^\d{6}$/);
-    expect(decoyOtpFor(subject)).toBe(decoyOtpFor(subject));
-  });
-
   it('produces a credential id shaped like a real one', () => {
     const subject = decoySubjectFor('nobody@example.com', 'email');