@memberjunction/server 5.38.0 → 5.40.0

package/src/__tests__/subscriptionRedaction.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Middleware wiring test.
+ *
+ * Locks the assumption that `variablesLoggingMiddleware` correctly:
+ *   - Skips field resolvers (info.path.prev !== undefined)
+ *   - Short-circuits when logVariables=false
+ *   - Emits a redacted variables block when logVariables=true
+ *   - Respects @NoLog field-level marks via the input class lookup
+ *
+ * We invoke the middleware directly with a synthetic ResolverData rather than booting a real
+ * GraphQL execution — that would force two copies of `graphql` (CJS via type-graphql + ESM via
+ * the test runner) into the same realm and fail with "Cannot use GraphQLSchema from another
+ * module or realm." The wiring at schema-build time (which IS what we want to lock for future
+ * type-graphql upgrades) is exercised in the end-to-end verification described in the PRD;
+ * here we just lock the per-call redaction logic.
+ *
+ * `globalMiddlewares` covers `@Query`, `@Mutation`, and `@Subscription` resolvers identically
+ * — they all go through the same `applyMiddlewares` chain inside type-graphql. Asserting the
+ * middleware fires once for a representative root resolver covers all three.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('../config', () => ({
+  configInfo: {
+    loggingSettings: {
+      graphql: {
+        logVariables: true,
+      },
+    },
+  },
+}));
+vi.mock('../config.js', () => ({
+  configInfo: {
+    loggingSettings: {
+      graphql: {
+        logVariables: true,
+      },
+    },
+  },
+}));
+
+import { variablesLoggingMiddleware } from '../logging/variablesLoggingMiddleware.js';
+
+/**
+ * Build a synthetic GraphQLResolveInfo-shaped object that matches what type-graphql passes
+ * to a middleware at runtime. Only the subset we read is populated.
+ */
+function makeInfo(opts: {
+  fieldName: string;
+  argTypeName: string;
+  argName: string;
+  isFieldResolver?: boolean;
+}): unknown {
+  const fakeArg = {
+    name: opts.argName,
+    type: { name: opts.argTypeName },
+  };
+  const fakeField = {
+    args: [fakeArg],
+  };
+  const parentType = {
+    getFields: () => ({ [opts.fieldName]: fakeField }),
+  };
+  const path = opts.isFieldResolver
+    ? { prev: { prev: undefined, key: 'parent' }, key: opts.fieldName }
+    : { prev: undefined, key: opts.fieldName };
+  return {
+    fieldName: opts.fieldName,
+    parentType,
+    path,
+  };
+}
+
+// Stub `getNamedType` is unnecessary — middleware uses graphql's `getNamedType` against the
+// type we pass. Our `argTypeName` value is wrapped in a plain `{ name }` object below; we need
+// the middleware's `getNamedType` to read `.name` directly. The `graphql` library's
+// `getNamedType` unwraps NonNull/List wrappers; a plain `{ name }` object survives unwrapping
+// because none of those wrapper shapes are present.
+
+describe('variablesLoggingMiddleware', () => {
+  let dirSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    dirSpy = vi.spyOn(console, 'dir').mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    dirSpy.mockRestore();
+    warnSpy.mockRestore();
+  });
+
+  it('skips field resolvers (info.path.prev !== undefined) without logging', async () => {
+    const next = vi.fn(async () => 'next-result');
+    const result = await variablesLoggingMiddleware(
+      {
+        root: undefined,
+        args: { x: 1 },
+        context: {} as never,
+        info: makeInfo({
+          fieldName: 'nestedThing',
+          argTypeName: 'CreateMJCredentialInput',
+          argName: 'input',
+          isFieldResolver: true,
+        }) as never,
+      },
+      next,
+    );
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(result).toBe('next-result');
+    expect(dirSpy).not.toHaveBeenCalled();
+  });
+
+  it('emits a redacted variables block for a root resolver with an entity-bound CRUD input', async () => {
+    const next = vi.fn(async () => 'next-result');
+    const fakeProvider = {
+      Entities: [
+        { ClassName: 'MJCredential', EncryptedFields: [{ Name: 'Values' }] },
+      ],
+    };
+
+    await variablesLoggingMiddleware(
+      {
+        root: undefined,
+        args: { input: { ID: 'abc', Name: 'HubSpot', Values: 'FAKE_SECRET' } },
+        context: {
+          providers: [{ provider: fakeProvider, type: 'Read-Write' }],
+        } as never,
+        info: makeInfo({
+          fieldName: 'CreateMJCredential',
+          argTypeName: 'CreateMJCredentialInput',
+          argName: 'input',
+        }) as never,
+      },
+      next,
+    );
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(dirSpy).toHaveBeenCalledTimes(1);
+    const [logged] = dirSpy.mock.calls[0];
+    expect(logged).toEqual({
+      operation: 'CreateMJCredential',
+      args: {
+        input: {
+          ID: 'abc',
+          Name: 'HubSpot',
+          Values: '<redacted>',
+        },
+      },
+    });
+  });
+
+  it('logs a custom-resolver plaintext arg (no metadata redaction available for it)', async () => {
+    const next = vi.fn(async () => undefined);
+    // Populate Entities (non-empty) so the redactor does not fall into the bootstrap fail-closed branch.
+    // The String-typed arg doesn't match Create/Update<X>Input, so it falls through to shortenForLog.
+    const fakeProvider = {
+      Entities: [{ ClassName: 'SomeUnrelatedEntity', EncryptedFields: [] }],
+    };
+
+    await variablesLoggingMiddleware(
+      {
+        root: undefined,
+        args: { token: 'plaintext-leak' },
+        context: {
+          providers: [{ provider: fakeProvider, type: 'Read-Write' }],
+        } as never,
+        info: makeInfo({
+          fieldName: 'VoiceTestHubSpotCredential',
+          argTypeName: 'String',
+          argName: 'token',
+        }) as never,
+      },
+      next,
+    );
+
+    expect(dirSpy).toHaveBeenCalledTimes(1);
+    // Arg is logged as-is because String type doesn't match Create/Update<X>Input, so the
+    // redactor's fail-open branch passes the value through shortenForLog (plain string passthrough).
+    // This is the gap that @NoLog discipline plus the boot audit are designed to surface.
+    const [logged] = dirSpy.mock.calls[0];
+    expect(logged).toMatchObject({
+      operation: 'VoiceTestHubSpotCredential',
+      args: { token: 'plaintext-leak' },
+    });
+  });
+
+  it('fails closed (<metadata-not-ready>) when provider.Entities is empty', async () => {
+    const next = vi.fn(async () => undefined);
+    const fakeProvider = { Entities: [] };
+
+    await variablesLoggingMiddleware(
+      {
+        root: undefined,
+        args: { input: { Values: 'FAKE_SECRET' } },
+        context: {
+          providers: [{ provider: fakeProvider, type: 'Read-Write' }],
+        } as never,
+        info: makeInfo({
+          fieldName: 'CreateMJCredential',
+          argTypeName: 'CreateMJCredentialInput',
+          argName: 'input',
+        }) as never,
+      },
+      next,
+    );
+
+    expect(dirSpy).toHaveBeenCalledTimes(1);
+    const [logged] = dirSpy.mock.calls[0];
+    expect(logged).toEqual({
+      operation: 'CreateMJCredential',
+      args: { input: '<metadata-not-ready>' },
+    });
+  });
+});

package/src/apolloServer/index.ts

@@ -15,6 +15,63 @@ import { SQLServerDataProvider } from '@memberjunction/sqlserver-dataprovider';
  * @param servers - HTTP server and WebSocket cleanup disposable
  * @param additionalPlugins - Optional additional plugins to merge with built-in plugins
  */
+/**
+ * Apollo plugin: log every Integration* GraphQL operation to stdout as
+ * structured JSON.  Lets operators tailing the MJAPI log see exactly which
+ * resolver the wizard / Explorer hit on each press, with arg names (values
+ * redacted for credentials).  Diagnostic-only — no behavior change.
+ *
+ * Emits two events per operation:
+ *   {"event":"gql.integration.request","method":"...","fieldName":"...","argNames":[...]}
+ *   {"event":"gql.integration.response","method":"...","fieldName":"...","durationMs":N,"hasErrors":bool}
+ *
+ * Filter from the log:
+ *   tail -f /tmp/mjapi.log | grep '"event":"gql\.integration\.'
+ */
+const integrationOperationTracer: ApolloServerPlugin = {
+  async requestDidStart(requestCtx) {
+    // Off by default — the plugin stays registered but emits nothing unless the
+    // MJ_INTEGRATION_TRACE debug flag is explicitly set. Avoids logging on every
+    // request in normal operation.
+    if (process.env.MJ_INTEGRATION_TRACE !== 'true') return undefined;
+    const opName = requestCtx.request.operationName ?? 'anonymous';
+    const query = requestCtx.request.query ?? '';
+    // Lightweight match — fire only for operations that touch an Integration
+    // resolver field.  Avoid logging every Color / User / Task query.
+    if (!query.includes('Integration')) return undefined;
+    const startedAt = Date.now();
+    return {
+      async willSendResponse(rc) {
+        // Walk the fields the operation queried; only those starting with
+        // "Integration" matter.  Variables surfaced as keys only.
+        const op = rc.operation;
+        if (!op) return;
+        const integrationFields: string[] = [];
+        for (const sel of op.selectionSet.selections) {
+          if (sel.kind === 'Field' && sel.name.value.startsWith('Integration')) {
+            integrationFields.push(sel.name.value);
+          }
+        }
+        if (integrationFields.length === 0) return;
+        const argNames = Object.keys(rc.request.variables ?? {});
+        const durationMs = Date.now() - startedAt;
+        const hasErrors = !!(rc.response.body.kind === 'single' && rc.response.body.singleResult.errors?.length);
+        for (const field of integrationFields) {
+          console.log(JSON.stringify({
+            ts: new Date().toISOString(),
+            event: 'gql.integration.response',
+            operationName: opName,
+            method: field,
+            argNames,
+            durationMs,
+            hasErrors,
+          }));
+        }
+      },
+    };
+  },
+};
+
 const buildApolloServer = (
   configOverride: ApolloServerOptions<AppContext>,
   { httpServer, serverCleanup }: { httpServer: Server; serverCleanup: Disposable },
@@ -22,6 +79,7 @@ const buildApolloServer = (
 ) => {
   const builtInPlugins: ApolloServerPlugin[] = [
     ApolloServerPluginDrainHttpServer({ httpServer }),
+    integrationOperationTracer,
     {
       async serverWillStart() {
         return {

package/src/auth/index.ts

@@ -235,13 +235,13 @@ export const verifyUserRecord = async (
           // to init it, including passing in the role list for the user.
           const md: Metadata = new Metadata(); // global-provider-ok: JWT validation + role lookup runs BEFORE AppContext.providers is built — no per-request provider yet
 
-          const initData: MJUserEntityType & { UserRoles: { UserID: string; RoleName: string; RoleID: string }[] } = newUser.GetAll();
+          const initData: MJUserEntityType & { UserRoles: { UserID: string; Role: string; RoleID: string }[] } = newUser.GetAll();
 
           initData.UserRoles = configInfo.userHandling.newUserRoles.map((role) => {
             const roleInfo: RoleInfo | undefined = md.Roles.find((r) => r.Name === role);
             const roleID: string = roleInfo ? roleInfo.ID : '';
 
-            return { UserID: initData.ID, RoleName: role, RoleID: roleID };
+            return { UserID: initData.ID, Role: role, RoleID: roleID };
           });
 
           user = new UserInfo(Metadata.Provider, initData); // global-provider-ok: same JWT-validation context — no per-request provider yet

package/src/auth/magicLink/MagicLinkKeys.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview RS256 key manager for magic-link session JWTs.
+ *
+ * MJ signs magic-link session tokens with an RS256 private key and publishes the
+ * matching public key at a JWKS endpoint. Registering the `magic-link` auth
+ * provider with that JWKS URL lets MJServer's standard issuer-driven validation
+ * verify the tokens with no special-casing.
+ *
+ * @module @memberjunction/server/auth/magicLink
+ */
+
+import { BaseSingleton } from '@memberjunction/global';
+import { LogStatus } from '@memberjunction/core';
+import { createPrivateKey, createPublicKey, generateKeyPairSync, createHash, type KeyObject } from 'node:crypto';
+import jwt from 'jsonwebtoken';
+import type { MagicLinkJWTClaims } from './types.js';
+
+/** A single JSON Web Key plus the metadata jwks-rsa needs to match it. */
+interface PublishedJWK extends JsonWebKey {
+  kid: string;
+  use: 'sig';
+  alg: 'RS256';
+}
+
+/**
+ * Manages the RS256 keypair used to sign and publish magic-link session tokens.
+ * Singleton so the keypair (and therefore the `kid`) is stable for the process
+ * lifetime — restarting with an ephemeral key invalidates outstanding sessions,
+ * which is the intended dev behavior and an acceptable production key-rotation
+ * mechanism.
+ */
+export class MagicLinkKeyManager extends BaseSingleton<MagicLinkKeyManager> {
+  private privateKeyPem = '';
+  private publicKey?: KeyObject;
+  private _kid = '';
+  private _initialized = false;
+
+  // Public to satisfy BaseSingleton.getInstance's `this: new () => T` constraint
+  // (matches the AuthProviderFactory singleton pattern).
+  public constructor() {
+    super();
+  }
+
+  public static get Instance(): MagicLinkKeyManager {
+    return MagicLinkKeyManager.getInstance<MagicLinkKeyManager>();
+  }
+
+  public get IsInitialized(): boolean {
+    return this._initialized;
+  }
+
+  public get Kid(): string {
+    return this._kid;
+  }
+
+  /**
+   * Initializes the keypair from a provided PEM (raw or base64-encoded) or, if
+   * none is supplied, generates an ephemeral 2048-bit RSA keypair. Idempotent.
+   */
+  public Initialize(privateKeyPem?: string): void {
+    if (this._initialized) {
+      return;
+    }
+
+    let priv: KeyObject;
+    const supplied = privateKeyPem?.trim();
+    if (supplied) {
+      priv = createPrivateKey(this.normalizePem(supplied));
+    } else {
+      const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+      priv = privateKey;
+      LogStatus(
+        '[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.'
+      );
+    }
+
+    this.privateKeyPem = priv.export({ type: 'pkcs8', format: 'pem' }) as string;
+    this.publicKey = createPublicKey(priv);
+    this._kid = this.computeKid(this.publicKey);
+    this._initialized = true;
+  }
+
+  /**
+   * Signs a set of magic-link claims and returns the compact JWT.
+   * `iat`/`exp` are expected to already be set on the claims.
+   */
+  public Sign(claims: MagicLinkJWTClaims): string {
+    this.ensureInitialized();
+    return jwt.sign(claims, this.privateKeyPem, { algorithm: 'RS256', keyid: this._kid });
+  }
+
+  /**
+   * Returns the JWKS document (public key set) for the JWKS endpoint.
+   */
+  public GetJWKS(): { keys: PublishedJWK[] } {
+    this.ensureInitialized();
+    const jwk = this.publicKey!.export({ format: 'jwk' });
+    return { keys: [{ ...jwk, kid: this._kid, use: 'sig', alg: 'RS256' }] };
+  }
+
+  private ensureInitialized(): void {
+    if (!this._initialized) {
+      throw new Error('MagicLinkKeyManager not initialized — call Initialize() during server startup.');
+    }
+  }
+
+  /** Accepts raw PEM or base64-encoded PEM and returns raw PEM. */
+  private normalizePem(value: string): string {
+    if (value.includes('-----BEGIN')) {
+      return value;
+    }
+    return Buffer.from(value, 'base64').toString('utf8');
+  }
+
+  /** Stable key id derived from the public key (SHA-256 of DER, base64url, truncated). */
+  private computeKid(publicKey: KeyObject): string {
+    const pem = publicKey.export({ type: 'spki', format: 'pem' }) as string;
+    return createHash('sha256').update(pem).digest('base64url').slice(0, 16);
+  }
+}

package/src/auth/magicLink/MagicLinkRouter.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Express wiring + auth-provider registration for magic links.
+ *
+ * Mirrors the OAuth handler pattern: a public router (unauthenticated — JWKS +
+ * redeem) mounted BEFORE the unified auth middleware, and an authenticated
+ * router (invite creation) mounted AFTER it so `req.userPayload` is available.
+ *
+ * @module @memberjunction/server/auth/magicLink
+ */
+
+import { Router, json, urlencoded, type Request, type Response } from 'express';
+import { rateLimit } from 'express-rate-limit';
+import { LogError, LogStatus, type AuthProviderConfig } from '@memberjunction/core';
+import { AuthProviderFactory } from '@memberjunction/auth-providers';
+import { configInfo, type MagicLinkConfig } from '../../config.js';
+import { MagicLinkKeyManager } from './MagicLinkKeys.js';
+import { MagicLinkService } from './MagicLinkService.js';
+import { buildRedeemLandingHtml } from './redeemLanding.js';
+import type { CreateMagicLinkInviteParams, RedeemMagicLinkResult } from './types.js';
+
+/** The mount path for both routers (`/magic-link`). */
+export const MAGIC_LINK_MOUNT_PATH = '/magic-link';
+
+/** Path of the JWKS endpoint relative to the public URL. */
+export const MAGIC_LINK_JWKS_PATH = `${MAGIC_LINK_MOUNT_PATH}/jwks.json`;
+
+/**
+ * Builds the magic-link routers. The caller mounts `publicRouter` before the
+ * auth middleware and `authenticatedRouter` after it (both at MAGIC_LINK_MOUNT_PATH).
+ */
+export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfig): {
+  publicRouter: Router;
+  authenticatedRouter: Router;
+} {
+  // Initialize the signing keypair once.
+  MagicLinkKeyManager.Instance.Initialize(config.rsaPrivateKey);
+
+  const service = new MagicLinkService(publicUrl, config);
+
+  // Throttle the unauthenticated redemption endpoint and the authenticated
+  // create endpoint. /redeem is a public surface that does a DB lookup +
+  // (on a hit) user provisioning + token minting, so it must be rate-limited
+  // against guessing/enumeration/resource-exhaustion. Keyed by IP.
+  const redeemLimiter = rateLimit({
+    windowMs: config.rateLimitWindowMs,
+    limit: config.redeemRateLimitMax,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    message: { success: false, errorCode: 'invalid', error: 'Too many redemption attempts. Try again later.' },
+  });
+  const createLimiter = rateLimit({
+    windowMs: config.rateLimitWindowMs,
+    limit: config.createRateLimitMax,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    message: { success: false, error: 'Too many invite requests. Try again later.' },
+  });
+
+  // ── Public (unauthenticated) ──────────────────────────────────────────────
+  const publicRouter = Router();
+
+  publicRouter.get('/jwks.json', (_req: Request, res: Response) => {
+    res.status(200).json(MagicLinkKeyManager.Instance.GetJWKS());
+  });
+
+  // Sends a completed redemption result: browser flow → 302 into 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 explorerUrl = config.explorerUrl?.replace(/\/$/, '');
+    if (explorerUrl && !wantsJson) {
+      if (result.success && result.token) {
+        // Deep-link into the invited app's route (e.g. /app/data-explorer) rather
+        // than Explorer's root — root falls through to Explorer's default resource,
+        // which isn't the scoped app. Use the app's URL Path (what Explorer's
+        // GetAppByPath matches on); fall back to a name-slug only when Path is
+        // absent. Do NOT hand-roll a slug from the name when Path exists — the two
+        // can diverge and Explorer would fail to resolve the app.
+        const appSlug = result.applicationPath
+          ? result.applicationPath
+          : result.applicationName
+          ? result.applicationName.trim().toLowerCase().replace(/\s+/g, '-')
+          : '';
+        const path = appSlug ? `/app/${encodeURIComponent(appSlug)}` : '/';
+        res.redirect(302, `${explorerUrl}${path}#token=${encodeURIComponent(result.token)}`);
+      } else {
+        res.redirect(302, `${explorerUrl}/?mlError=${encodeURIComponent(result.errorCode ?? 'invalid')}`);
+      }
+      return;
+    }
+    // API/JSON flow.
+    // not_found / expired / consumed / revoked are client-side conditions (410 Gone);
+    // server_error / provisioning_failed are 500.
+    const status = result.success ? 200 : result.errorCode === 'server_error' || result.errorCode === 'provisioning_failed' ? 500 : 410;
+    res.status(status).json(result);
+  };
+
+  // GET /redeem is SAFE (no side effects). Link prefetchers and email security
+  // scanners routinely fetch URLs; a side-effectful GET would let them burn the
+  // single-use token before the human clicks. So GET renders an interstitial and
+  // 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 : '';
+    if (!token) {
+      res.status(400).json({ success: false, error: 'Missing token.' });
+      return;
+    }
+    // API callers must POST — GET never redeems.
+    if (req.query.format === 'json') {
+      res.status(405).json({ success: false, error: 'Redemption requires POST.', method: 'POST', path: `${MAGIC_LINK_MOUNT_PATH}/redeem` });
+      return;
+    }
+    res
+      .status(200)
+      .type('html')
+      .send(buildRedeemLandingHtml(token, `${MAGIC_LINK_MOUNT_PATH}/redeem`));
+  });
+
+  // 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 token =
+      (typeof body.token === 'string' && body.token) ||
+      (typeof req.query.token === 'string' ? req.query.token : '');
+    const wantsJson = req.query.format === 'json' || req.is('application/json') === 'application/json';
+
+    if (!token) {
+      res.status(400).json({ success: false, error: 'Missing token.' });
+      return;
+    }
+
+    // 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, {
+      ipAddress: req.ip,
+      userAgent: req.get('user-agent') ?? undefined,
+      origin: req.get('origin') ?? undefined,
+    });
+    sendRedeemResult(res, result, wantsJson);
+  });
+
+  // ── Authenticated (invite creation) ───────────────────────────────────────
+  const authenticatedRouter = Router();
+
+  authenticatedRouter.post('/create', createLimiter, json(), async (req: Request, res: Response) => {
+    const creatingUser = req.userPayload?.userRecord;
+    if (!creatingUser) {
+      res.status(401).json({ success: false, error: 'Authentication required.' });
+      return;
+    }
+
+    const body = (req.body ?? {}) as Partial<CreateMagicLinkInviteParams>;
+    if (!body.email || !body.applicationId) {
+      res.status(400).json({ success: false, error: 'email and applicationId are required.' });
+      return;
+    }
+
+    const result = await service.CreateInvite(
+      {
+        email: body.email,
+        applicationId: body.applicationId,
+        roleId: body.roleId,
+        expiresInHours: body.expiresInHours,
+        maxUses: body.maxUses,
+        firstName: body.firstName,
+        lastName: body.lastName,
+      },
+      creatingUser,
+    );
+    // forbidden → 403 (caller not allowed to issue invites); invalid_role and
+    // other validation failures → 400.
+    const status = result.success ? 200 : result.errorCode === 'forbidden' ? 403 : 400;
+    res.status(status).json(result);
+  });
+
+  return { publicRouter, authenticatedRouter };
+}
+
+/**
+ * Registers the `magic-link` auth provider so MJServer's issuer-driven JWT
+ * validation accepts MJ-issued session tokens. Issuer = public URL, JWKS URL =
+ * the public JWKS endpoint, audience = configured magic-link audience.
+ *
+ * Also appends the provider to `configInfo.authProviders` so a later
+ * `initializeAuthProviders()` (which clears + repopulates from config) keeps it.
+ */
+export function registerMagicLinkAuthProvider(publicUrl: string, config: MagicLinkConfig): void {
+  const base = publicUrl.replace(/\/$/, '');
+  const providerConfig: AuthProviderConfig = {
+    name: 'magic-link',
+    type: 'magic-link',
+    issuer: publicUrl,
+    audience: config.audience,
+    jwksUri: `${base}${MAGIC_LINK_JWKS_PATH}`,
+  };
+
+  try {
+    configInfo.authProviders = configInfo.authProviders ?? [];
+    if (!configInfo.authProviders.some((p) => p.type === 'magic-link')) {
+      configInfo.authProviders.push(providerConfig);
+    }
+    const factory = AuthProviderFactory.Instance;
+    factory.register(AuthProviderFactory.createProvider(providerConfig));
+    LogStatus(`[MagicLink] Registered auth provider (issuer: ${publicUrl}, jwks: ${providerConfig.jwksUri})`);
+  } catch (e) {
+    LogError(`[MagicLink] Failed to register auth provider: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}