@memberjunction/server 6.2.0-edge.6 → 6.2.0-edge.7

package/src/auth/__tests__/loginEmailResolution.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { DescribeUserEmailMap, EmailsMatch, ResolveUserLookupEmail } from '../loginEmailResolution.js';
+
+describe('ResolveUserLookupEmail', () => {
+  it('looks a login up by its email claim when no map is set', () => {
+    expect(ResolveUserLookupEmail({ email: 'b@two.example', preferredUsername: 'b@two.example' }, undefined)).toEqual({
+      TokenEmail: 'b@two.example',
+      LookupEmail: 'b@two.example',
+      Remapped: false,
+    });
+  });
+
+  it('applies a USER_EMAIL_MAP entry and reports the rewrite', () => {
+    const result = ResolveUserLookupEmail({ email: 'b@two.example' }, { 'b@two.example': 'a@one.example' });
+    expect(result).toEqual({ TokenEmail: 'b@two.example', LookupEmail: 'a@one.example', Remapped: true });
+  });
+
+  it('keeps the map key match exact (case-sensitive), as before', () => {
+    const result = ResolveUserLookupEmail({ email: 'B@two.example' }, { 'b@two.example': 'a@one.example' });
+    expect(result.LookupEmail).toBe('B@two.example');
+    expect(result.Remapped).toBe(false);
+  });
+
+  it('does not count an entry that only changes case as a remap', () => {
+    const result = ResolveUserLookupEmail({ email: 'b@two.example' }, { 'b@two.example': 'B@Two.example' });
+    expect(result.LookupEmail).toBe('B@Two.example');
+    expect(result.Remapped).toBe(false);
+  });
+
+  it('falls back to the preferred username and never remaps it', () => {
+    const result = ResolveUserLookupEmail({ preferredUsername: 'b@two.example' }, { 'b@two.example': 'a@one.example' });
+    expect(result).toEqual({ TokenEmail: 'b@two.example', LookupEmail: 'b@two.example', Remapped: false });
+  });
+
+  it('returns no identity when the token has neither claim', () => {
+    expect(ResolveUserLookupEmail({}, undefined)).toEqual({ TokenEmail: undefined, LookupEmail: undefined, Remapped: false });
+  });
+});
+
+describe('EmailsMatch', () => {
+  it('ignores case and surrounding whitespace, like the User lookup', () => {
+    expect(EmailsMatch(' A@One.example ', 'a@one.example')).toBe(true);
+  });
+
+  it('treats a missing side as no match', () => {
+    expect(EmailsMatch(undefined, 'a@one.example')).toBe(false);
+    expect(EmailsMatch('a@one.example', '')).toBe(false);
+  });
+});
+
+describe('DescribeUserEmailMap', () => {
+  it('returns null when no map is configured', () => {
+    expect(DescribeUserEmailMap(undefined)).toBeNull();
+    expect(DescribeUserEmailMap({})).toBeNull();
+  });
+
+  it('returns null when every entry maps an address to itself', () => {
+    expect(DescribeUserEmailMap({ 'a@one.example': 'A@one.example' })).toBeNull();
+  });
+
+  it('lists every entry that sends a login to another record', () => {
+    const warning = DescribeUserEmailMap({ 'b@two.example': 'a@one.example', 'c@three.example': 'a@one.example' });
+    expect(warning).toContain('2 login email(s)');
+    expect(warning).toContain('b@two.example -> a@one.example');
+    expect(warning).toContain('c@three.example -> a@one.example');
+  });
+});

package/src/auth/loginEmailResolution.ts

@@ -0,0 +1,67 @@
+/**
+ * Which email a verified login is matched to a User record by, and whether that differs from the
+ * identity the token carries.
+ *
+ * The server links a login to a User row by email alone. `USER_EMAIL_MAP` can rewrite that email
+ * before the lookup, which makes a login run as a different person's record. That is a legitimate
+ * development aid, but it is silent, so a misconfigured map on a shared machine looks exactly like
+ * an authentication bug. These helpers keep the token's identity next to the one actually used, so
+ * the session audit and the server log can say when the two differ.
+ */
+
+/** The identity fields of a verified token that the lookup can use. */
+export interface LoginIdentityClaims {
+  email?: string; // case-violation-ok-legacy-back-compat: mirrors the provider's extracted user info shape
+  preferredUsername?: string; // case-violation-ok-legacy-back-compat: mirrors the provider's extracted user info shape
+}
+
+/** The email the token carries and the email the User lookup will use. */
+export interface LoginEmailResolution {
+  /** The identity from the verified token: its email claim, or its preferred username when it has none. */
+  TokenEmail: string | undefined;
+  /** The email the User record is looked up by, after any `USER_EMAIL_MAP` rewrite. */
+  LookupEmail: string | undefined;
+  /** True when `USER_EMAIL_MAP` replaced the token's email with a different one. */
+  Remapped: boolean;
+}
+
+/**
+ * Resolves the lookup email for a verified token. The map applies only to the email claim, with an
+ * exact (case-sensitive) key match, as it always has; a preferred username is never remapped.
+ *
+ * Named without "login"/"auth"/"verify": CodeQL treats calls with those words as authentication
+ * actions and reports the `if (!token)` guard above this call in GetUserPayload as a user-controlled
+ * bypass. This is a plain lookup, not an authentication step.
+ */
+export function ResolveUserLookupEmail(claims: LoginIdentityClaims, emailMap: Record<string, string> | undefined): LoginEmailResolution {
+  if (!claims.email) {
+    return { TokenEmail: claims.preferredUsername, LookupEmail: claims.preferredUsername, Remapped: false };
+  }
+  const mapped = emailMap?.[claims.email];
+  const lookupEmail = mapped ?? claims.email;
+  return { TokenEmail: claims.email, LookupEmail: lookupEmail, Remapped: mapped !== undefined && !EmailsMatch(mapped, claims.email) };
+}
+
+/** Case-insensitive, whitespace-trimmed comparison, matching how the User lookup compares emails. */
+export function EmailsMatch(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b) {
+    return false;
+  }
+  return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+
+/**
+ * The startup warning for a configured `USER_EMAIL_MAP`, or null when the map is absent or rewrites
+ * nothing. Lists every entry so whoever starts the server can see whose record each login will use.
+ */
+export function DescribeUserEmailMap(emailMap: Record<string, string> | undefined): string | null {
+  const entries = Object.entries(emailMap ?? {}).filter(([from, to]) => !EmailsMatch(from, to));
+  if (entries.length === 0) {
+    return null;
+  }
+  const lines = entries.map(([from, to]) => `  ${from} -> ${to}`).join('\n');
+  return (
+    `[Auth] USER_EMAIL_MAP is set: ${entries.length} login email(s) will be matched to a different user's record. ` +
+    `A login with the first address runs as the user with the second. Remove the setting unless this is intended.\n${lines}`
+  );
+}

package/src/auth/magicLink/MagicLinkKeys.ts

@@ -10,11 +10,28 @@
  */
 
 import { BaseSingleton } from '@memberjunction/global';
-import { LogStatusEx } from '@memberjunction/core';
+import { LogStatusEx, LogWarning } from '@memberjunction/core';
 import { createPrivateKey, createPublicKey, generateKeyPairSync, createHash, type KeyObject } from 'node:crypto';
 import jwt from 'jsonwebtoken';
 import type { MagicLinkJWTClaims } from './types.js';
 
+/**
+ * True when the process is NOT running with `NODE_ENV=production`. This is the same
+ * production/local-dev line MJServer already uses to forbid local dev auth in production.
+ */
+export function IsMagicLinkLocalDevEnvironment(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.NODE_ENV?.trim().toLowerCase() !== 'production';
+}
+
+/** Warning logged when a non-local-dev server falls back to an ephemeral keypair. */
+export const EPHEMERAL_MAGIC_LINK_KEY_WARNING =
+  '[MagicLink] No rsaPrivateKey configured and NODE_ENV=production — generated an EPHEMERAL RS256 keypair. ' +
+  'Magic-link session tokens signed with it will stop validating when this process restarts, and they will not ' +
+  'validate on any other MJAPI instance behind the same load balancer, because each process generates its own key. ' +
+  'To fix, generate one RSA private key (e.g. `openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048`) and set it ' +
+  'as magicLink.rsaPrivateKey in mj.config.cjs or as MJ_MAGIC_LINK_PRIVATE_KEY (raw or base64-encoded PEM), ' +
+  'using the same key on every instance.';
+
 /** A single JSON Web Key plus the metadata jwks-rsa needs to match it. */
 interface PublishedJWK extends JsonWebKey {
   kid: string;
@@ -34,6 +51,7 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
   private publicKey?: KeyObject;
   private _kid = '';
   private _initialized = false;
+  private _isEphemeral = false;
 
   // Public to satisfy BaseSingleton.getInstance's `this: new () => T` constraint
   // (matches the AuthProviderFactory singleton pattern).
@@ -49,6 +67,15 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
     return this._initialized;
   }
 
+  /**
+   * True when no private key was configured and the keypair was generated for this process
+   * only. Tokens signed with an ephemeral key do not survive a restart and do not validate on
+   * other instances. Downstream code should ask this rather than reading the raw config value.
+   */
+  public get IsEphemeral(): boolean {
+    return this._isEphemeral;
+  }
+
   public get Kid(): string {
     return this._kid;
   }
@@ -56,8 +83,11 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
   /**
    * Initializes the keypair from a provided PEM (raw or base64-encoded) or, if
    * none is supplied, generates an ephemeral 2048-bit RSA keypair. Idempotent.
+   *
+   * @param env - process environment used to decide whether the ephemeral fallback is a local-dev
+   *   default (verbose-only notice) or a production misconfiguration (warning). Defaults to `process.env`.
    */
-  public Initialize(privateKeyPem?: string): void {
+  public Initialize(privateKeyPem?: string, env: NodeJS.ProcessEnv = process.env): void {
     if (this._initialized) {
       return;
     }
@@ -69,17 +99,8 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
     } else {
       const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
       priv = privateKey;
-      // Verbose-only: on dev boxes with no configured key this fires on EVERY boot, and the
-      // ephemeral fallback is the designed behavior there — not a condition worth a log line in
-      // the default startup output. Deployments that care set the key; operators diagnosing
-      // magic-link session loss can re-run with verbose logging.
-      LogStatusEx({
-        message:
-          '[MagicLink] No rsaPrivateKey configured — generated an EPHEMERAL RS256 keypair. ' +
-          'Outstanding magic-link sessions will be invalidated on restart. Set magicLink.rsaPrivateKey ' +
-          '(or MJ_MAGIC_LINK_PRIVATE_KEY) for stable production keys.',
-        verboseOnly: true
-      });
+      this._isEphemeral = true;
+      this.reportEphemeralKey(env);
     }
 
     this.privateKeyPem = priv.export({ type: 'pkcs8', format: 'pem' }) as string;
@@ -92,11 +113,103 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
    * Signs a set of magic-link (or local-dev) claims and returns the compact JWT.
    * `iat`/`exp` are expected to already be set on the claims.
    */
-  public Sign(claims: MagicLinkJWTClaims | Record<string, unknown>): string {
+  public Sign<T extends object>(claims: T): string {
     this.ensureInitialized();
     return jwt.sign(claims, this.privateKeyPem, { algorithm: 'RS256', keyid: this._kid });
   }
 
+  /**
+   * Verifies a magic-link session JWT signed by this key manager (`RS256`, `mj_magic_link === true`).
+   * Returns `null` if invalid, expired, or forged.
+   */
+  public VerifySessionToken(
+    token: string,
+    options?: { issuer?: string; audience?: string },
+  ): MagicLinkJWTClaims | null {
+    this.ensureInitialized();
+    try {
+      const publicPem = this.publicKey!.export({ type: 'spki', format: 'pem' }) as string;
+      const verifyOptions: jwt.VerifyOptions = { algorithms: ['RS256'] };
+      if (options?.issuer) {
+        verifyOptions.issuer = options.issuer;
+      }
+      if (options?.audience) {
+        verifyOptions.audience = options.audience;
+      }
+      const decoded = jwt.verify(token, publicPem, verifyOptions);
+      if (!decoded || typeof decoded !== 'object') {
+        return null;
+      }
+      const claims = decoded as MagicLinkJWTClaims;
+      if (claims.mj_magic_link !== true || typeof claims.sub !== 'string') {
+        return null;
+      }
+      return claims;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Signs a redirect binding JWT (`mj_purpose = 'magic-link-redirect'`) that cryptographically
+   * binds a validated `redirectUrl` to a specific invite's `tokenHash`.
+   *
+   * Note: Expiration is intentionally omitted from the redirect binding JWT because the database
+   * invite row's `ExpiresAt` (enforced atomically during `RedeemInvite`) is the authoritative,
+   * mutable expiration — allowing `UpdateInviteExpiry()` to extend an invite without invalidating
+   * an already-delivered `&rt=` parameter.
+   */
+  public SignRedirectBinding(tokenHash: string, redirectUrl: string, _expiresAtEpochSeconds?: number): string {
+    this.ensureInitialized();
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return jwt.sign(
+      {
+        mj_purpose: 'magic-link-redirect',
+        mj_th: tokenHash,
+        mj_redirect: redirectUrl,
+        iat: nowSeconds,
+      },
+      this.privateKeyPem,
+      { algorithm: 'RS256', keyid: this._kid },
+    );
+  }
+
+  /**
+   * Verifies a redirect binding JWT produced by {@link SignRedirectBinding} and ensures it matches
+   * `expectedTokenHash` (preventing cross-invite substitution) and carries a valid `http(s)` URL.
+   * Ignores JWT `exp` so bindings minted before an `UpdateInviteExpiry()` extension remain valid
+   * while the underlying invite row is valid. Returns the bound URL or `null`.
+   */
+  public VerifyRedirectBinding(bindingToken: string, expectedTokenHash: string): string | null {
+    this.ensureInitialized();
+    try {
+      const publicPem = this.publicKey!.export({ type: 'spki', format: 'pem' }) as string;
+      const decoded = jwt.verify(bindingToken, publicPem, {
+        algorithms: ['RS256'],
+        ignoreExpiration: true,
+      });
+      if (!decoded || typeof decoded !== 'object') {
+        return null;
+      }
+      const record = decoded as { mj_purpose?: string; mj_th?: string; mj_redirect?: string };
+      if (
+        record.mj_purpose !== 'magic-link-redirect' ||
+        record.mj_th !== expectedTokenHash ||
+        typeof record.mj_redirect !== 'string' ||
+        !record.mj_redirect
+      ) {
+        return null;
+      }
+      const parsed = new URL(record.mj_redirect);
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return null;
+      }
+      return record.mj_redirect;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Returns the JWKS document (public key set) for the JWKS endpoint.
    */
@@ -106,6 +219,25 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
     return { keys: [{ ...jwk, kid: this._kid, use: 'sig', alg: 'RS256' }] };
   }
 
+  /**
+   * Local dev (NODE_ENV not 'production'): the ephemeral fallback is the designed behavior and
+   * fires on every boot, so the notice stays verbose-only. Otherwise it is a data-loss-on-restart
+   * misconfiguration, so it is a warning in the default output.
+   */
+  private reportEphemeralKey(env: NodeJS.ProcessEnv): void {
+    if (!IsMagicLinkLocalDevEnvironment(env)) {
+      LogWarning(EPHEMERAL_MAGIC_LINK_KEY_WARNING);
+      return;
+    }
+    LogStatusEx({
+      message:
+        '[MagicLink] No rsaPrivateKey configured — generated an EPHEMERAL RS256 keypair. ' +
+        'Outstanding magic-link sessions will be invalidated on restart. Set magicLink.rsaPrivateKey ' +
+        '(or MJ_MAGIC_LINK_PRIVATE_KEY) for stable production keys.',
+      verboseOnly: true
+    });
+  }
+
   private ensureInitialized(): void {
     if (!this._initialized) {
       throw new Error('MagicLinkKeyManager not initialized — call Initialize() during server startup.');

package/src/auth/magicLink/MagicLinkRouter.ts

@@ -32,6 +32,7 @@ export const MAGIC_LINK_JWKS_PATH = `${MAGIC_LINK_MOUNT_PATH}/jwks.json`;
 export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfig): {
   publicRouter: Router;
   authenticatedRouter: Router;
+  service: MagicLinkService;
 } {
   // Initialize the signing keypair once.
   MagicLinkKeyManager.Instance.Initialize(config.rsaPrivateKey);
@@ -64,10 +65,27 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     res.status(200).json(MagicLinkKeyManager.Instance.GetJWKS());
   });
 
-  // Sends a completed redemption result: browser flow → 302 into Explorer with
+  // Sends a completed redemption result: browser flow → 302 into a verified per-invite
+  // RedirectUrl (when cryptographically bound + origin-allowed) or Explorer with
   // the session token in the URL fragment (never sent to a server, so it stays
   // out of access/proxy logs); API flow → JSON with an appropriate status.
-  const sendRedeemResult = (res: Response, result: RedeemMagicLinkResult, wantsJson: boolean): void => {
+  const sendRedeemResult = (
+    res: Response,
+    result: RedeemMagicLinkResult,
+    wantsJson: boolean,
+    verifiedRedirectUrl?: string,
+  ): void => {
+    if (verifiedRedirectUrl && !wantsJson) {
+      const baseWithoutHash = verifiedRedirectUrl.split('#')[0];
+      if (result.success && result.token) {
+        res.redirect(302, `${baseWithoutHash}#token=${encodeURIComponent(result.token)}`);
+      } else {
+        const sep = baseWithoutHash.includes('?') ? '&' : '?';
+        res.redirect(302, `${baseWithoutHash}${sep}mlError=${encodeURIComponent(result.errorCode ?? 'invalid')}`);
+      }
+      return;
+    }
+
     const explorerUrl = config.explorerUrl?.replace(/\/$/, '');
     if (explorerUrl && !wantsJson) {
       if (result.success && result.token) {
@@ -102,6 +120,7 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
   // the actual redemption happens only on POST (below), gated by a user click.
   publicRouter.get('/redeem', redeemLimiter, (req: Request, res: Response) => {
     const token = typeof req.query.token === 'string' ? req.query.token : '';
+    const rt = typeof req.query.rt === 'string' ? req.query.rt : undefined;
     if (!token) {
       res.status(400).json({ success: false, error: 'Missing token.' });
       return;
@@ -114,16 +133,19 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     res
       .status(200)
       .type('html')
-      .send(BuildRedeemLandingHtml(token, ApiRoute(`${MAGIC_LINK_MOUNT_PATH}/redeem`)));
+      .send(BuildRedeemLandingHtml(token, ApiRoute(`${MAGIC_LINK_MOUNT_PATH}/redeem`), rt));
   });
 
   // POST /redeem performs the actual (side-effectful) redemption. Token arrives
   // from the interstitial form body, an API client's JSON body, or the query.
   publicRouter.post('/redeem', redeemLimiter, urlencoded({ extended: false }), json(), async (req: Request, res: Response) => {
-    const body = (req.body ?? {}) as { token?: string };
+    const body = (req.body ?? {}) as { token?: string; rt?: string };
     const token =
       (typeof body.token === 'string' && body.token) ||
       (typeof req.query.token === 'string' ? req.query.token : '');
+    const rt =
+      (typeof body.rt === 'string' && body.rt) ||
+      (typeof req.query.rt === 'string' ? req.query.rt : undefined);
     const wantsJson = req.query.format === 'json' || req.is('application/json') === 'application/json';
 
     if (!token) {
@@ -131,6 +153,8 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
       return;
     }
 
+    const verifiedRedirectUrl = service.ResolveVerifiedRedirectUrl(token, rt);
+
     // Forensic context for the redemption audit trail. `req.ip` honors the app's
     // trust-proxy setting; headers are best-effort and may be absent for API clients.
     const result = await service.RedeemInvite(token, {
@@ -138,7 +162,7 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
       userAgent: req.get('user-agent') ?? undefined,
       origin: req.get('origin') ?? undefined,
     });
-    sendRedeemResult(res, result, wantsJson);
+    sendRedeemResult(res, result, wantsJson, verifiedRedirectUrl);
   });
 
   // ── Authenticated (invite creation) ───────────────────────────────────────
@@ -166,6 +190,8 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
         MaxUses: body.MaxUses,
         firstName: body.firstName,
         lastName: body.lastName,
+        RedirectUrl: body.RedirectUrl,
+        SendEmail: body.SendEmail,
       },
       creatingUser,
     );
@@ -175,13 +201,14 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     res.status(status).json(result);
   });
 
-  return { publicRouter, authenticatedRouter };
+  return { publicRouter, authenticatedRouter, service };
 }
 
 /** @deprecated Use {@link CreateMagicLinkHandler}. */
 export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfig): {
   publicRouter: Router;
   authenticatedRouter: Router;
+  service: MagicLinkService;
 } {
   return CreateMagicLinkHandler(publicUrl, config);
 }