@memberjunction/server 5.39.0 → 5.40.1

package/src/auth/magicLink/index.ts

@@ -0,0 +1,17 @@
+export * from './types.js';
+export {
+  generateRawToken,
+  hashToken,
+  evaluateInvite,
+  buildSessionClaims,
+  MAGIC_LINK_TOKEN_PREFIX,
+  type InviteEvaluationInput,
+} from './magicLinkCore.js';
+export { MagicLinkKeyManager } from './MagicLinkKeys.js';
+export { MagicLinkService } from './MagicLinkService.js';
+export {
+  createMagicLinkHandler,
+  registerMagicLinkAuthProvider,
+  MAGIC_LINK_MOUNT_PATH,
+  MAGIC_LINK_JWKS_PATH,
+} from './MagicLinkRouter.js';

package/src/auth/magicLink/magicLinkCore.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Pure functional core for magic links — no DB, no email, no MJ
+ * runtime imports. Everything here is deterministic given its inputs (modulo
+ * crypto randomness) and unit-testable with plain assertions.
+ *
+ * @module @memberjunction/server/auth/magicLink
+ */
+
+import { randomBytes, createHash } from 'node:crypto';
+import type { MagicLinkJWTClaims, MagicLinkScopeEntry, RedeemErrorCode } from './types.js';
+
+/** Token prefix, mirroring the API-key convention (`mj_sk_`). */
+export const MAGIC_LINK_TOKEN_PREFIX = 'mj_ml_';
+
+/** Generates a cryptographically random raw magic-link token. */
+export function generateRawToken(): string {
+  return MAGIC_LINK_TOKEN_PREFIX + randomBytes(32).toString('hex');
+}
+
+/** Generates an opaque per-session id (anonymous-session forensics correlation). */
+export function generateSessionId(): string {
+  return randomBytes(16).toString('base64url');
+}
+
+/**
+ * SHA-256 hash of a raw token, base64url-encoded — only the hash is ever
+ * persisted. base64url (43 chars) is shorter than hex (64 chars), URL-safe, and
+ * carries the full 256 bits. Both write (CreateInvite) and read (RedeemInvite)
+ * paths call this, so the encoding stays internally consistent.
+ */
+export function hashToken(rawToken: string): string {
+  return createHash('sha256').update(rawToken).digest('base64url');
+}
+
+/** Minimal shape of an invite needed for redemption eligibility. */
+export interface InviteEvaluationInput {
+  Status: string;
+  ExpiresAt: Date | string;
+  MaxUses: number;
+  UseCount: number;
+}
+
+/** Normalizes a role/name for case- and whitespace-insensitive comparison. */
+function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+/**
+ * Pure authorization check for WHO may issue magic-link invites.
+ *
+ * Owners are always allowed (Owner is MJ's superuser type). Otherwise the caller
+ * must be a member of one of `issuerRoleNames`. An empty `issuerRoleNames` means
+ * Owner-only — the secure default. This is what stops any authenticated user
+ * (including an external user already holding a restricted magic-link session)
+ * from minting invites.
+ */
+export function canIssueInvites(
+  userType: string | null | undefined,
+  userRoleNames: readonly string[],
+  issuerRoleNames: readonly string[],
+): boolean {
+  if (normalizeName(userType ?? '') === 'owner') {
+    return true;
+  }
+  const allowed = new Set(issuerRoleNames.map(normalizeName));
+  if (allowed.size === 0) {
+    return false;
+  }
+  return userRoleNames.some((r) => allowed.has(normalizeName(r)));
+}
+
+/**
+ * Pure check for WHAT role an invite may grant. The restricted role is always
+ * grantable; any other role must be explicitly listed in `grantableRoleNames`.
+ * Applied to every caller (Owners included) so a privileged role can never be
+ * attached to an external magic-link user unless the deployment opts in.
+ */
+export function isRoleGrantable(
+  roleName: string | null | undefined,
+  restrictedRoleName: string,
+  grantableRoleNames: readonly string[],
+): boolean {
+  const target = normalizeName(roleName ?? '');
+  if (!target) {
+    return false;
+  }
+  const allowed = new Set<string>([normalizeName(restrictedRoleName), ...grantableRoleNames.map(normalizeName)]);
+  return allowed.has(target);
+}
+
+/** Pure redemption-eligibility check. Returns ok + an error code when not. */
+export function evaluateInvite(invite: InviteEvaluationInput, nowMs: number): { ok: boolean; errorCode?: RedeemErrorCode } {
+  if (invite.Status === 'Revoked') {
+    return { ok: false, errorCode: 'revoked' };
+  }
+  const expiresMs = new Date(invite.ExpiresAt).getTime();
+  if (Number.isFinite(expiresMs) && expiresMs <= nowMs) {
+    return { ok: false, errorCode: 'expired' };
+  }
+  if (invite.Status === 'Consumed' || invite.UseCount >= invite.MaxUses) {
+    return { ok: false, errorCode: 'consumed' };
+  }
+  if (invite.Status !== 'Active') {
+    return { ok: false, errorCode: 'invalid' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Builds the atomic compare-and-swap UPDATE that consumes one use of an invite.
+ *
+ * The WHERE clause re-checks every eligibility condition at the DB level, so the
+ * increment and the guard are a single atomic operation: concurrent redemptions
+ * of a single-use link race on the row and exactly one matches (the matched row
+ * is returned via OUTPUT). This is what actually enforces single-use — the
+ * JS-side `evaluateInvite` is only a friendly pre-check.
+ *
+ * The invite ID MUST be bound as parameter `@p0` by the caller — it is never
+ * interpolated into the string, so this builder is injection-safe regardless of
+ * the ID's contents.
+ *
+ * OUTPUT goes `INTO` a table variable (not a bare OUTPUT): SQL Server forbids a
+ * bare OUTPUT clause on a table that has enabled triggers, and CodeGen adds an
+ * `__mj_UpdatedAt` trigger to every MJ table. The trailing SELECT returns exactly
+ * the matched row(s) so the caller can detect a win (exactly one row) regardless
+ * of trigger behavior.
+ *
+ * `qualifiedTable` is asserted to be a bracket-quoted `[schema].[table]` (word
+ * chars only) before interpolation. The caller derives it from `EntityInfo`
+ * (never user input), so this is defense-in-depth: even a future careless caller
+ * cannot turn this into an injection vector — a non-conforming table throws.
+ *
+ * @param qualifiedTable  bracket-quoted `[schema].[table]` for MagicLinkInvite
+ */
+const QUALIFIED_TABLE_PATTERN = /^\[\w+\]\.\[\w+\]$/;
+
+export function buildConsumeInviteSQL(qualifiedTable: string): string {
+  if (!QUALIFIED_TABLE_PATTERN.test(qualifiedTable)) {
+    throw new Error(`buildConsumeInviteSQL: refusing to build SQL for non-whitelisted table identifier '${qualifiedTable}'.`);
+  }
+  return (
+    `DECLARE @consumed TABLE (ID UNIQUEIDENTIFIER); ` +
+    `UPDATE ${qualifiedTable} ` +
+    `SET UseCount = UseCount + 1, ` +
+    `ConsumedAt = COALESCE(ConsumedAt, SYSUTCDATETIME()), ` +
+    `Status = CASE WHEN UseCount + 1 >= MaxUses THEN 'Consumed' ELSE Status END ` +
+    `OUTPUT INSERTED.ID INTO @consumed ` +
+    `WHERE ID = @p0 AND Status = 'Active' AND UseCount < MaxUses AND ExpiresAt > SYSUTCDATETIME(); ` +
+    `SELECT ID FROM @consumed;`
+  );
+}
+
+/**
+ * Pure scope-union: appends `next` to `prior` unless an entry from the same invite
+ * is already present (dedup by inviteId). This is how a session accumulates the union
+ * of scopes across multiple redeemed links — carried in the re-minted JWT, never as
+ * roles on a shared user, so anonymous sessions can't accrete into a superuser.
+ */
+export function unionScopes(prior: readonly MagicLinkScopeEntry[] | undefined, next: MagicLinkScopeEntry): MagicLinkScopeEntry[] {
+  const result = [...(prior ?? [])];
+  if (!result.some((s) => s.inviteId === next.inviteId)) {
+    result.push(next);
+  }
+  return result;
+}
+
+/** Builds the session-token claims (pure). */
+export function buildSessionClaims(args: {
+  issuer: string;
+  audience: string;
+  inviteId: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  applicationId: string;
+  roleName: string;
+  invitedByUserId?: string;
+  /** True for anonymous sessions — the server enforces scope from mj_scopes, not roles. */
+  anonymous?: boolean;
+  /** Opaque per-session id (anonymous forensics correlation). */
+  sessionId?: string;
+  /** Prior session's scope union to carry forward (multi-link anonymous sessions). */
+  priorScopes?: readonly MagicLinkScopeEntry[];
+  /** Resource-share/embed scope for this link's entry. */
+  resourceType?: string;
+  resourceId?: string;
+  nowSeconds: number;
+  ttlSeconds: number;
+}): MagicLinkJWTClaims {
+  const name = [args.firstName, args.lastName].filter(Boolean).join(' ') || undefined;
+  const scopeEntry: MagicLinkScopeEntry = {
+    inviteId: args.inviteId,
+    appId: args.applicationId,
+    role: args.roleName,
+    resourceType: args.resourceType,
+    resourceId: args.resourceId,
+  };
+  return {
+    iss: args.issuer,
+    aud: args.audience,
+    sub: `magic-link|${args.inviteId}`,
+    iat: args.nowSeconds,
+    exp: args.nowSeconds + args.ttlSeconds,
+    email: args.email,
+    given_name: args.firstName,
+    family_name: args.lastName,
+    name,
+    mj_app_id: args.applicationId,
+    mj_role: args.roleName,
+    mj_invited_by: args.invitedByUserId,
+    mj_scopes: unionScopes(args.priorScopes, scopeEntry),
+    mj_anon: args.anonymous ? true : undefined,
+    mj_sid: args.sessionId,
+    mj_magic_link: true,
+  };
+}

package/src/auth/magicLink/redeemLanding.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Pure HTML for the magic-link redemption interstitial. No DB, no
+ * MJ runtime imports — deterministic string in, string out.
+ * @module @memberjunction/server/auth/magicLink
+ */
+
+/** Minimal HTML-escape for safe interpolation into attribute/text content. */
+export function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Builds the redemption landing page served by `GET /magic-link/redeem`.
+ *
+ * GET must be SAFE: link prefetchers, email security scanners, and browser
+ * preconnect routinely fetch URLs, and a side-effectful GET would let them burn
+ * the single-use token before the human ever clicks. So GET renders this page
+ * and the actual redemption happens only when the user submits the form (POST).
+ * The "Continue" button is NOT auto-submitted — a bot that merely loads the page
+ * (even one that executes JS) does not consume the token; a human gesture does.
+ *
+ * @param token       the raw magic-link token (embedded in a hidden field)
+ * @param actionPath  the same-origin path the form POSTs to (e.g. `/magic-link/redeem`)
+ */
+export function buildRedeemLandingHtml(token: string, actionPath: string): string {
+  const t = escapeHtml(token);
+  const action = escapeHtml(actionPath);
+  // Hardcoded colors are intentional here — this is a standalone server-rendered
+  // HTML response, not Angular component CSS, so the design-token rule doesn't apply.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Sign in</title>
+<style>
+  body { font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; background:#f5f5f5; margin:0; display:flex; min-height:100vh; align-items:center; justify-content:center; }
+  .card { background:#fff; padding:2.5rem; border-radius:12px; box-shadow:0 1px 4px rgba(0,0,0,.12); max-width:24rem; text-align:center; }
+  h1 { font-size:1.25rem; margin:0 0 .5rem; color:#1f2937; }
+  p { color:#4b5563; margin:0 0 1.5rem; font-size:.95rem; }
+  button { background:#264FAF; color:#fff; border:0; border-radius:8px; padding:.75rem 1.5rem; font-size:1rem; cursor:pointer; width:100%; }
+  button:hover { background:#1e3f8c; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1>Sign in to continue</h1>
+    <p>Click below to securely sign in with your invitation link.</p>
+    <form method="POST" action="${action}">
+      <input type="hidden" name="token" value="${t}">
+      <button type="submit">Continue to sign in</button>
+    </form>
+  </div>
+</body>
+</html>`;
+}

package/src/auth/magicLink/types.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Types for the MemberJunction magic-link feature.
+ * @module @memberjunction/server/auth/magicLink
+ */
+
+/**
+ * One unit of scope a magic-link session holds. The union of these across all links
+ * a session has redeemed is the anonymous-session authorization boundary (enforced
+ * server-side against the claims, never via roles on the shared Anonymous principal).
+ */
+export interface MagicLinkScopeEntry {
+  /** The invite that granted this scope entry. */
+  inviteId: string;
+  /** The Application this entry grants access to. */
+  appId: string;
+  /** The role name this entry carries (email/app-session links). */
+  role?: string;
+  /** For resource-share/embed links: the shared resource's type + id. */
+  resourceType?: string;
+  resourceId?: string;
+}
+
+/**
+ * Claims carried by a MJ-issued magic-link session JWT.
+ * Identity claims (email/given_name/family_name) follow standard OIDC so the
+ * existing provider extraction works; the `mj_*` claims describe the scope.
+ */
+export interface MagicLinkJWTClaims {
+  /** Issuer — MJ's public URL; resolves to the registered `magic-link` auth provider. */
+  iss: string;
+  /** Audience — the configured magic-link audience (default `mj-magic-link`). */
+  aud: string;
+  /** Subject — `magic-link|<inviteId>`. */
+  sub: string;
+  /** Issued-at (epoch seconds). */
+  iat: number;
+  /** Expiry (epoch seconds). */
+  exp: number;
+  email: string;
+  given_name?: string;
+  family_name?: string;
+  name?: string;
+  /** The single Application this session is scoped to. */
+  mj_app_id: string;
+  /** The restricted role name assigned to this user (informational; enforcement is server-side via the role's entity permissions). */
+  mj_role: string;
+  /** UserID of the internal user who issued the invite (attribution/audit). Absent on links whose inviter could not be resolved. */
+  mj_invited_by?: string;
+  /**
+   * Per-session scope UNION (Phase 4+). Each entry is one redeemed link's grant.
+   * The server enforces anonymous sessions against THIS set (not the user's role
+   * set), which is why two anon visitors sharing the Anonymous principal can hold
+   * different scopes without accretion. For email sessions the singular mj_app_id/
+   * mj_role remain authoritative; this carries the union when links are stacked.
+   */
+  mj_scopes?: MagicLinkScopeEntry[];
+  /** True when this session resolves to the shared Anonymous principal (claims-based enforcement). */
+  mj_anon?: boolean;
+  /** Opaque per-session id — correlates one anonymous session's activity across audit rows without a real user. */
+  mj_sid?: string;
+  /** Marks the session as magic-link so the Explorer can confine the UI. */
+  mj_magic_link: true;
+}
+
+/** Parameters for creating a magic-link invite (POST /magic-link/create). */
+export interface CreateMagicLinkInviteParams {
+  /** Recipient email — becomes the provisioned user's email. */
+  email: string;
+  /** The Application the invite grants access to. */
+  applicationId: string;
+  /** Restricted role to assign. Defaults to the configured `restrictedRoleName`. */
+  roleId?: string;
+  /** Hours until the link expires. Defaults to config `defaultExpiresInHours`. */
+  expiresInHours?: number;
+  /** Maximum redemptions. Defaults to 1 (single-use). */
+  maxUses?: number;
+  /** Optional given/family name to seed the provisioned user. */
+  firstName?: string;
+  lastName?: string;
+}
+
+/** Result of creating an invite. */
+export interface CreateMagicLinkInviteResult {
+  success: boolean;
+  inviteId?: string;
+  /** Full redemption URL to share. */
+  redemptionUrl?: string;
+  /**
+   * The raw token, returned ONLY when no email provider is configured (so the
+   * caller can deliver the link out of band). Never returned once email send
+   * succeeds, and never persisted.
+   */
+  rawToken?: string;
+  /** Whether the invite email was dispatched. */
+  emailSent?: boolean;
+  /** ISO expiry timestamp. */
+  expiresAt?: string;
+  error?: string;
+  /**
+   * Set when the request was rejected for authorization reasons:
+   * `forbidden` — caller may not issue invites; `invalid_role` — the requested
+   * role is not grantable via magic-link. Drives the HTTP status in the router.
+   */
+  errorCode?: 'forbidden' | 'invalid_role';
+}
+
+/** Why a redemption failed. */
+export type RedeemErrorCode = 'not_found' | 'expired' | 'consumed' | 'revoked' | 'invalid' | 'provisioning_failed' | 'server_error';
+
+/**
+ * Per-request forensic context captured for the redemption audit trail
+ * (`MJ: Magic Link Redemptions`). Sourced from the HTTP request at the router;
+ * all fields optional because the API/JSON flow may omit them.
+ */
+export interface RedeemAuditContext {
+  ipAddress?: string;
+  userAgent?: string;
+  origin?: string;
+}
+
+/** Result of redeeming an invite. */
+export interface RedeemMagicLinkResult {
+  success: boolean;
+  /** The minted session JWT (RS256). */
+  token?: string;
+  /** ISO expiry of the session token. */
+  expiresAt?: string;
+  /** The Application the session is scoped to. */
+  applicationId?: string;
+  /** The Application's display name (used to deep-link the browser into that app). */
+  applicationName?: string;
+  /** The Application's URL path slug (preferred for deep-linking; falls back to name). */
+  applicationPath?: string;
+  email?: string;
+  error?: string;
+  errorCode?: RedeemErrorCode;
+}

package/src/config.ts

@@ -236,8 +236,69 @@ const feedbackSettingsSchema = z.object({
   github: feedbackGithubSettingsSchema.optional(),
 });
 
+const magicLinkSchema = z.object({
+  /** Master switch for the magic-link feature. When false, routes are not mounted and the auth provider is not registered. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /**
+   * PEM-encoded RS256 private key used to sign session JWTs. May be raw PEM or
+   * base64-encoded PEM. If omitted, an ephemeral keypair is generated at startup
+   * (dev only — restarting the server invalidates all outstanding sessions).
+   */
+  rsaPrivateKey: z.string().optional().default(process.env.MJ_MAGIC_LINK_PRIVATE_KEY || ''),
+  /** Hours an unredeemed invite link remains valid (hard expiry). Default 72. */
+  defaultExpiresInHours: z.coerce.number().optional().default(72),
+  /** Hours the minted session JWT remains valid after redemption. No refresh tokens. Default 8. */
+  sessionTokenTtlHours: z.coerce.number().optional().default(8),
+  /** Name of the restricted Role assigned to redeeming users when an invite does not specify one. */
+  restrictedRoleName: z.string().optional().default('Magic Link Baseline'),
+  /**
+   * Role names (besides Owner) whose members may issue invites via POST /create.
+   * Empty (default) means Owner-only — the secure default. The restricted role
+   * must never be listed here, or external users could mint their own invites.
+   */
+  inviteIssuerRoleNames: z.array(z.string()).optional().default([]),
+  /**
+   * Role names an invite may grant, IN ADDITION to restrictedRoleName (which is
+   * always allowed). A caller-supplied roleId is rejected unless its role name is
+   * the restricted role or appears here. This is the guard that stops a caller
+   * from attaching a privileged role (e.g. Owner) to an external magic-link user.
+   */
+  grantableRoleNames: z.array(z.string()).optional().default([]),
+  /** Email of the internal user whose context provisions magic-link users (falls back to userHandling.contextUserForNewUserCreation). */
+  contextUserForProvisioning: z.string().optional(),
+  /**
+   * Guard against bolting an external magic-link role/app onto an EXISTING account
+   * that is an Owner or already holds non-restricted ("real") roles. One mistyped
+   * recipient email is all it takes to hand a colleague an external role otherwise.
+   * `block` (default) refuses to provision onto such accounts; `warn` logs loudly
+   * and proceeds. Provisioning onto brand-new or already-external accounts is never
+   * affected.
+   */
+  provisioningGuard: z.enum(['block', 'warn']).optional().default('block'),
+  /** CommunicationEngine provider name used to deliver invite emails (e.g. 'SendGrid', 'Microsoft Graph'). When unset, emails are not sent and the redemption link is returned to the caller instead. */
+  communicationProvider: z.string().optional(),
+  /** From address for invite emails. */
+  fromAddress: z.string().optional(),
+  /** Audience claim for minted JWTs and the auto-registered magic-link auth provider. */
+  audience: z.string().optional().default('mj-magic-link'),
+  /** Rate-limit window (ms) for the public /redeem and authenticated /create endpoints. Default 60s. */
+  rateLimitWindowMs: z.coerce.number().optional().default(60_000),
+  /** Max /redeem attempts per IP per window. Default 20. */
+  redeemRateLimitMax: z.coerce.number().optional().default(20),
+  /** Max /create requests per IP per window. Default 30. */
+  createRateLimitMax: z.coerce.number().optional().default(30),
+  /**
+   * Base URL of the Explorer instance that redeems land in. When set, GET
+   * /magic-link/redeem 302-redirects the browser to `${explorerUrl}/#token=<jwt>`
+   * (Explorer's magic-link auth provider reads the fragment). When unset, redeem
+   * returns the token as JSON. Append `?format=json` to force JSON regardless.
+   */
+  explorerUrl: z.string().optional(),
+}).passthrough();
+
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
+  magicLink: magicLinkSchema.optional().default({}),
   databaseSettings: databaseSettingsInfoSchema,
   viewingSystem: viewingSystemInfoSchema.optional(),
   restApiOptions: restApiOptionsSchema.optional().default({}),
@@ -286,6 +347,7 @@ const configInfoSchema = z.object({
 });
 
 export type UserHandlingInfo = z.infer<typeof userHandlingInfoSchema>;
+export type MagicLinkConfig = z.infer<typeof magicLinkSchema>;
 export type DatabaseSettingsInfo = z.infer<typeof databaseSettingsInfoSchema>;
 export type ViewingSystemSettingsInfo = z.infer<typeof viewingSystemInfoSchema>;
 export type RESTApiOptions = z.infer<typeof restApiOptionsSchema>;