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

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;
@@ -89,14 +110,106 @@ export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
   }
 
   /**
-   * Signs a set of magic-link claims and returns the compact JWT.
+   * 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): 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);
 }

package/src/auth/magicLink/MagicLinkService.ts

@@ -37,9 +37,12 @@ import { configInfo, type MagicLinkConfig } from '../../config.js';
 import { CreateIsolatedProvider } from '../../isolatedProvider.js';
 import { MagicLinkKeyManager } from './MagicLinkKeys.js';
 import { GenerateRawToken, GenerateSessionId, HashToken, EvaluateInvite, BuildSessionClaims, BuildConsumeInvitePostgresSQL, CanIssueInvites, IsRoleGrantable, MAGIC_LINK_TOKEN_PREFIX } from './magicLinkCore.js';
+import type { IServerExtensionMagicLinkService } from '@memberjunction/server-extensions-core';
 import type {
   CreateMagicLinkInviteParams,
   CreateMagicLinkInviteResult,
+  ManageMagicLinkInviteResult,
+  MagicLinkJWTClaims,
   RedeemMagicLinkResult,
   RedeemAuditContext,
 } from './types.js';
@@ -75,11 +78,53 @@ interface ProvisionResult {
   error?: string;
 }
 
+/**
+ * Validates that a candidate `redirectUrl` is a well-formed `http:` or `https:` URL whose
+ * origin matches at least one concrete normalized entry in `allowedOrigins`.
+ * Wildcard `'*'` entries are explicitly ignored/rejected so session tokens can never be
+ * redirected to unvalidated origins.
+ */
+export function IsMagicLinkRedirectUrlAllowed(redirectUrl: string, allowedOrigins: readonly string[]): boolean {
+  const trimmed = redirectUrl.trim();
+  if (!trimmed) {
+    return false;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return false;
+  }
+  const normalizedTargetOrigin = parsed.origin.toLowerCase();
+  for (const rawAllowed of allowedOrigins) {
+    const candidate = (rawAllowed ?? '').trim();
+    if (!candidate || candidate === '*') {
+      continue;
+    }
+    try {
+      const allowedUrl = new URL(candidate);
+      if (allowedUrl.origin.toLowerCase() === normalizedTargetOrigin) {
+        return true;
+      }
+    } catch {
+      if (candidate.replace(/\/$/, '').toLowerCase() === normalizedTargetOrigin) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Magic-link service. One instance per server, constructed with the resolved
- * public URL and the validated config.
+ * public URL and the validated config. Implements {@link IServerExtensionMagicLinkService}
+ * so `BaseServerExtension` implementations can mint, revoke, extend, and verify invites
+ * via `context.services.GetMagicLinkService?.()`.
  */
-export class MagicLinkService {
+export class MagicLinkService implements IServerExtensionMagicLinkService {
   constructor(
     private readonly publicUrl: string,
     private readonly config: MagicLinkConfig,
@@ -87,7 +132,7 @@ export class MagicLinkService {
 
   /**
    * Creates a single-use, app-scoped invite, persists its hashed token, and
-   * (when a communication provider is configured) emails the link.
+   * (when a communication provider is configured and `params.SendEmail !== false`) emails the link.
    *
    * @param params  invite parameters
    * @param creatingUser  the authenticated internal user issuing the invite
@@ -110,6 +155,15 @@ export class MagicLinkService {
         return { success: false, errorCode: 'forbidden', error: 'Not authorized to issue magic-link invites.' };
       }
 
+      const validatedRedirectUrl = params.RedirectUrl?.trim() ? params.RedirectUrl.trim() : undefined;
+      if (validatedRedirectUrl && !IsMagicLinkRedirectUrlAllowed(validatedRedirectUrl, this.allowedRedirectOrigins())) {
+        return {
+          success: false,
+          errorCode: 'invalid_redirect_url',
+          error: `RedirectUrl '${validatedRedirectUrl}' is not permitted by the server's allowed frontend origins.`,
+        };
+      }
+
       const roleId = params.RoleId ?? this.resolveRestrictedRoleId(md);
       if (!roleId) {
         return { success: false, error: `Restricted role '${this.config.restrictedRoleName}' not found and no roleId supplied.` };
@@ -136,12 +190,13 @@ export class MagicLinkService {
       }
 
       const rawToken = GenerateRawToken();
+      const tokenHash = HashToken(rawToken);
       const expiresInHours = params.ExpiresInHours ?? this.config.defaultExpiresInHours;
       const expiresAt = new Date(Date.now() + expiresInHours * 3600 * 1000);
 
       const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, creatingUser);
       invite.NewRecord();
-      invite.TokenHash = HashToken(rawToken);
+      invite.TokenHash = tokenHash;
       invite.Email = params.email;
       invite.ApplicationID = params.ApplicationId;
       invite.RoleID = roleId;
@@ -161,10 +216,22 @@ export class MagicLinkService {
       // multi-scope reads. Best-effort so a child-row hiccup never fails issuance.
       await this.writeInviteScopeChildRows(invite.ID, params.ApplicationId, roleId, creatingUser, md);
 
-      const redemptionUrl = this.buildRedemptionUrl(rawToken);
+      let redirectBindingToken: string | undefined;
+      if (validatedRedirectUrl) {
+        if (!MagicLinkKeyManager.Instance.IsInitialized) {
+          MagicLinkKeyManager.Instance.Initialize(this.config.rsaPrivateKey);
+        }
+        redirectBindingToken = MagicLinkKeyManager.Instance.SignRedirectBinding(
+          tokenHash,
+          validatedRedirectUrl,
+          Math.floor(expiresAt.getTime() / 1000),
+        );
+      }
+
+      const redemptionUrl = this.buildRedemptionUrl(rawToken, redirectBindingToken);
 
       let emailSent = false;
-      if (this.config.communicationProvider) {
+      if (params.SendEmail !== false && this.config.communicationProvider) {
         emailSent = await this.sendInviteEmail(params.email, redemptionUrl, app.Name, creatingUser);
       }
 
@@ -172,7 +239,7 @@ export class MagicLinkService {
         success: true,
         inviteId: invite.ID,
         redemptionUrl,
-        // Surface the raw token only when we couldn't deliver it ourselves.
+        // Surface the raw token only when we couldn't (or were asked not to) deliver it ourselves.
         rawToken: emailSent ? undefined : rawToken,
         emailSent,
         expiresAt: expiresAt.toISOString(),
@@ -183,6 +250,158 @@ export class MagicLinkService {
     }
   }
 
+  /**
+   * Revokes an existing invite so subsequent redemptions fail with `'revoked'`.
+   * Requires the acting user to hold invite-issuance authority (`CanIssueInvites`).
+   */
+  public async RevokeInvite(
+    inviteId: string,
+    actingUser: UserInfo,
+    provider?: IMetadataProvider,
+  ): Promise<ManageMagicLinkInviteResult> {
+    try {
+      const callerRoleNames = (actingUser.UserRoles ?? []).map((r) => r.Role).filter((n): n is string => !!n);
+      if (!CanIssueInvites(actingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
+        return { success: false, errorCode: 'forbidden', error: 'Not authorized to revoke magic-link invites.' };
+      }
+      if (!inviteId?.trim()) {
+        return { success: false, errorCode: 'not_found', error: 'Invite ID is required.' };
+      }
+
+      const md = provider ?? Metadata.Provider;
+      const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, actingUser);
+      const loaded = await invite.Load(inviteId.trim());
+      if (!loaded) {
+        return { success: false, errorCode: 'not_found', error: `Invite '${inviteId}' not found.` };
+      }
+
+      if (invite.Status === 'Revoked') {
+        return {
+          success: true,
+          inviteId: invite.ID,
+          status: invite.Status,
+          expiresAt: invite.ExpiresAt.toISOString(),
+        };
+      }
+
+      invite.Status = 'Revoked';
+      if (!(await invite.Save())) {
+        return {
+          success: false,
+          errorCode: 'server_error',
+          error: `Failed to revoke invite: ${invite.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+        };
+      }
+
+      return {
+        success: true,
+        inviteId: invite.ID,
+        status: invite.Status,
+        expiresAt: invite.ExpiresAt.toISOString(),
+      };
+    } catch (e) {
+      LogError(e);
+      return { success: false, errorCode: 'server_error', error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  /**
+   * Updates the expiration timestamp of an existing non-revoked, non-consumed invite.
+   * Requires the acting user to hold invite-issuance authority (`CanIssueInvites`).
+   */
+  public async UpdateInviteExpiry(
+    inviteId: string,
+    expiresAt: Date,
+    actingUser: UserInfo,
+    provider?: IMetadataProvider,
+  ): Promise<ManageMagicLinkInviteResult> {
+    try {
+      const callerRoleNames = (actingUser.UserRoles ?? []).map((r) => r.Role).filter((n): n is string => !!n);
+      if (!CanIssueInvites(actingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
+        return { success: false, errorCode: 'forbidden', error: 'Not authorized to update magic-link invites.' };
+      }
+      if (!(expiresAt instanceof Date) || Number.isNaN(expiresAt.getTime())) {
+        return { success: false, errorCode: 'invalid_expiry', error: 'expiresAt must be a valid Date.' };
+      }
+      if (!inviteId?.trim()) {
+        return { success: false, errorCode: 'not_found', error: 'Invite ID is required.' };
+      }
+
+      const md = provider ?? Metadata.Provider;
+      const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, actingUser);
+      const loaded = await invite.Load(inviteId.trim());
+      if (!loaded) {
+        return { success: false, errorCode: 'not_found', error: `Invite '${inviteId}' not found.` };
+      }
+
+      if (invite.Status === 'Revoked' || invite.Status === 'Consumed') {
+        return {
+          success: false,
+          errorCode: 'invalid_state',
+          error: `Cannot update expiry on invite '${invite.ID}' because its status is '${invite.Status}'.`,
+        };
+      }
+
+      const nowMs = Date.now();
+      invite.ExpiresAt = expiresAt;
+      if (invite.Status === 'Expired' && expiresAt.getTime() > nowMs && invite.UseCount < invite.MaxUses) {
+        invite.Status = 'Active';
+      } else if (invite.Status === 'Active' && expiresAt.getTime() <= nowMs) {
+        invite.Status = 'Expired';
+      }
+
+      if (!(await invite.Save())) {
+        return {
+          success: false,
+          errorCode: 'server_error',
+          error: `Failed to update invite expiry: ${invite.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+        };
+      }
+
+      return {
+        success: true,
+        inviteId: invite.ID,
+        status: invite.Status,
+        expiresAt: invite.ExpiresAt.toISOString(),
+      };
+    } catch (e) {
+      LogError(e);
+      return { success: false, errorCode: 'server_error', error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  /**
+   * Verifies a magic-link session JWT against this service's configured issuer and audience.
+   */
+  public VerifySessionToken(token: string): MagicLinkJWTClaims | null {
+    if (!token || !MagicLinkKeyManager.Instance.IsInitialized) {
+      return null;
+    }
+    return MagicLinkKeyManager.Instance.VerifySessionToken(token, {
+      issuer: this.publicUrl,
+      audience: this.config.audience,
+    });
+  }
+
+  /**
+   * Verifies a signed redirect binding (`rt`) against the raw invite token's hash AND the host's
+   * allowed frontend origins. Returns the verified redirect URL, or `undefined` if absent/invalid.
+   */
+  public ResolveVerifiedRedirectUrl(rawToken: string, redirectBindingToken: string | undefined): string | undefined {
+    if (!rawToken || !redirectBindingToken || !MagicLinkKeyManager.Instance.IsInitialized) {
+      return undefined;
+    }
+    const tokenHash = HashToken(rawToken);
+    const boundUrl = MagicLinkKeyManager.Instance.VerifyRedirectBinding(redirectBindingToken, tokenHash);
+    if (!boundUrl) {
+      return undefined;
+    }
+    if (!IsMagicLinkRedirectUrlAllowed(boundUrl, this.allowedRedirectOrigins())) {
+      return undefined;
+    }
+    return boundUrl;
+  }
+
   /**
    * Redeems a raw token: validates the invite, atomically consumes one use,
    * provisions/links the user with the restricted role + app, and mints a
@@ -420,10 +639,31 @@ export class MagicLinkService {
     return role?.ID;
   }
 
-  /** Builds the shareable redemption URL. */
-  private buildRedemptionUrl(rawToken: string): string {
+  /** Builds the shareable redemption URL (including `&rt=...` when a per-invite RedirectUrl was signed). */
+  private buildRedemptionUrl(rawToken: string, redirectBindingToken?: string): string {
     const base = this.publicUrl.replace(/\/$/, '');
-    return `${base}/magic-link/redeem?token=${encodeURIComponent(rawToken)}`;
+    const rtParam = redirectBindingToken ? `&rt=${encodeURIComponent(redirectBindingToken)}` : '';
+    return `${base}/magic-link/redeem?token=${encodeURIComponent(rawToken)}${rtParam}`;
+  }
+
+  /**
+   * Collects concrete frontend origins a caller-supplied per-invite `RedirectUrl` is permitted
+   * to target (`explorerUrl`, `magicLink.allowedRedirectOrigins`, and non-wildcard `cors.allowedOrigins`).
+   */
+  private allowedRedirectOrigins(): string[] {
+    const origins: string[] = [];
+    const candidates: readonly (string | undefined)[] = [
+      this.config.explorerUrl ?? configInfo.magicLink?.explorerUrl,
+      ...(this.config.allowedRedirectOrigins ?? configInfo.magicLink?.allowedRedirectOrigins ?? []),
+      ...(configInfo.cors?.allowedOrigins ?? []),
+    ];
+    for (const raw of candidates) {
+      const trimmed = raw?.trim();
+      if (trimmed && trimmed !== '*') {
+        origins.push(trimmed);
+      }
+    }
+    return origins;
   }
 
   /**

package/src/auth/magicLink/index.ts

@@ -8,7 +8,7 @@ export {
   type InviteEvaluationInput,
 } from './magicLinkCore.js';
 export { MagicLinkKeyManager } from './MagicLinkKeys.js';
-export { MagicLinkService } from './MagicLinkService.js';
+export { MagicLinkService, IsMagicLinkRedirectUrlAllowed } from './MagicLinkService.js';
 export {
   CreateMagicLinkHandler, createMagicLinkHandler,
   CreateMagicLinkJwksRouter, createMagicLinkJwksRouter,