@memberjunction/server 6.2.0-edge.0 → 6.2.0-edge.2

package/src/auth/index.ts

@@ -14,7 +14,7 @@ export * from './scopeLimitedPrincipal.js';
 export * from './actingContextResolver.js';
 export * from './AuthProviderEngine.js';
 export * from './AuthProviderCatalogRouter.js';
-export { initializeAuthProviders, initializeAuthProvidersFromMetadata, refreshAuthProviders, validateAuthProvidersRegistered } from './initializeProviders.js';
+export { InitializeAuthProviders, initializeAuthProviders, InitializeAuthProvidersFromMetadata, initializeAuthProvidersFromMetadata, RefreshAuthProviders, refreshAuthProviders, ValidateAuthProvidersRegistered, validateAuthProvidersRegistered } from './initializeProviders.js';
 
 // This is a hard-coded forever constant due to internal migrations
 
@@ -58,7 +58,7 @@ const refreshUserCache = async () => {
  * the same domain with different audiences/client IDs), all unique audiences
  * are aggregated into an array. jwt.verify() natively accepts string | string[].
  */
-export const getValidationOptions = (issuer: string): { audience: string | string[]; jwksUri: string } | undefined => {
+export const GetValidationOptions = (issuer: string): { audience: string | string[]; jwksUri: string } | undefined => {
   const factory = AuthProviderFactory.Instance;
   const providers = factory.getAllByIssuer(issuer);
 
@@ -75,16 +75,19 @@ export const getValidationOptions = (issuer: string): { audience: string | strin
   };
 };
 
+/** @deprecated Use {@link GetValidationOptions}. */
+export const getValidationOptions = GetValidationOptions;
+
 /**
  * Backward compatible validationOptions object
  * @deprecated Use getValidationOptions() or AuthProviderRegistry instead
  */
 export const validationOptions: Record<string, { audience: string | string[]; jwksUri: string }> = new Proxy({}, {
   get: (target, prop: string) => {
-    return getValidationOptions(prop);
+    return GetValidationOptions(prop);
   },
   has: (target, prop: string) => {
-    return getValidationOptions(prop) !== undefined;
+    return GetValidationOptions(prop) !== undefined;
   },
   ownKeys: () => {
     const factory = AuthProviderFactory.Instance;
@@ -93,31 +96,31 @@ export const validationOptions: Record<string, { audience: string | string[]; jw
 });
 
 export class UserPayload {
-  aio?: string;
-  aud?: string;
-  exp?: number;
-  iat?: number;
-  iss?: string;
-  name?: string;
-  nbf?: number;
-  nonce?: string;
-  oid?: string;
-  preferred_username?: string;
-  rh?: string;
-  sub?: string;
-  tid?: string;
-  uti?: string;
-  ver?: string;
-  email?: string;
-  given_name?: string;
-  family_name?: string;
+  aio?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  aud?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  exp?: number;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  iat?: number;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  iss?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  name?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  nbf?: number;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  nonce?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  oid?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  preferred_username?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  rh?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  sub?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  tid?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  uti?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  ver?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  email?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  given_name?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
+  family_name?: string;  // case-violation-ok-legacy-back-compat: an accessor cannot be optional, so a stub would turn this into a required member
   [key: string]: unknown; // Allow additional claims
 }
 
 /**
  * Gets signing keys for JWT validation
  */
-export const getSigningKeys = (issuer: string) => (header: JwtHeader, cb: SigningKeyCallback) => {
+export const GetSigningKeys = (issuer: string) => (header: JwtHeader, cb: SigningKeyCallback) => {
   const factory = AuthProviderFactory.Instance;
   
   // Initialize providers if not already done
@@ -138,10 +141,13 @@ export const getSigningKeys = (issuer: string) => (header: JwtHeader, cb: Signin
   provider.getSigningKey(header, cb);
 };
 
+/** @deprecated Use {@link GetSigningKeys}. */
+export const getSigningKeys = GetSigningKeys;
+
 /**
  * Extracts user information from JWT payload using the appropriate provider
  */
-export const extractUserInfoFromPayload = (payload: JwtPayload): {
+export const ExtractUserInfoFromPayload = (payload: JwtPayload): {
   email?: string;
   firstName?: string;
   lastName?: string;
@@ -181,20 +187,26 @@ export const extractUserInfoFromPayload = (payload: JwtPayload): {
   return provider.extractUserInfo(payload);
 };
 
-export const getSystemUser = async (dataSource?: sql.ConnectionPool, attemptCacheUpdateIfNeeded: boolean = true): Promise<UserInfo> => {
+/** @deprecated Use {@link ExtractUserInfoFromPayload}. */
+export const extractUserInfoFromPayload = ExtractUserInfoFromPayload;
+
+export const GetSystemUser = async (dataSource?: sql.ConnectionPool, attemptCacheUpdateIfNeeded: boolean = true): Promise<UserInfo> => {
   const systemUser = UserCache.Instance.GetSystemUser();
   if (!systemUser) {
     if (dataSource && attemptCacheUpdateIfNeeded) {
       console.warn(`System user not found in cache. Updating cache in attempt to find the user...`);
 
       await refreshUserCache();
-      return getSystemUser(dataSource, false); // try one more time but do not update cache next time if not found
+      return GetSystemUser(dataSource, false); // try one more time but do not update cache next time if not found
     }
     throw new Error(`System user ID '${UserCache.Instance.SYSTEM_USER_ID}' not found in database`);
   }
   return systemUser;
 };
 
+/** @deprecated Use {@link GetSystemUser}. */
+export const getSystemUser = GetSystemUser;
+
 /**
  * Extracts the lowercased domain portion of an email address.
  *
@@ -231,7 +243,7 @@ const isDomainAuthorized = (domain: string): boolean =>
  *        authorization runs against the verified JWT's email domain instead. Retained for audit
  *        logging and for the recursive retry call.
  */
-export const verifyUserRecord = async (
+export const VerifyUserRecord = async (
   email?: string,
   firstName?: string,
   lastName?: string,
@@ -311,12 +323,15 @@ export const verifyUserRecord = async (
 
       await refreshUserCache();
 
-      return verifyUserRecord(email, firstName, lastName, requestDomain, dataSource, false); // try one more time but do not update cache next time if not found
+      return VerifyUserRecord(email, firstName, lastName, requestDomain, dataSource, false); // try one more time but do not update cache next time if not found
     }
   }
 
   return user;
 };
 
+/** @deprecated Use {@link VerifyUserRecord}. */
+export const verifyUserRecord = VerifyUserRecord;
+
 // Initialize providers on module load
 initializeAuthProviders();

package/src/auth/initializeProviders.ts

@@ -14,7 +14,7 @@ import { AuthProviderEngine } from './AuthProviderEngine.js';
  * {@link initializeAuthProvidersFromMetadata}, which runs later in startup once a database
  * connection and a system user exist.
  */
-export function initializeAuthProviders(): void {
+export function InitializeAuthProviders(): void {
   const factory = AuthProviderFactory.Instance;
 
   // Clear any existing providers
@@ -60,6 +60,11 @@ export function initializeAuthProviders(): void {
   // authProviders array at this point, and erroring here would cry wolf on every boot.
 }
 
+/** @deprecated Use {@link InitializeAuthProviders}. */
+export function initializeAuthProviders(): void {
+  return InitializeAuthProviders();
+}
+
 /**
  * Layers the metadata provider catalog on top of the config-declared providers.
  *
@@ -74,7 +79,7 @@ export function initializeAuthProviders(): void {
  *
  * @returns the number of providers registered from metadata.
  */
-export async function initializeAuthProvidersFromMetadata(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
+export async function InitializeAuthProvidersFromMetadata(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
   try {
     await AuthProviderEngine.Instance.Config(false, contextUser, provider);
     const count = await AuthProviderEngine.Instance.RegisterAll(contextUser);
@@ -89,6 +94,11 @@ export async function initializeAuthProvidersFromMetadata(contextUser?: UserInfo
   }
 }
 
+/** @deprecated Use {@link InitializeAuthProvidersFromMetadata}. */
+export async function initializeAuthProvidersFromMetadata(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
+  return InitializeAuthProvidersFromMetadata(contextUser, provider);
+}
+
 /**
  * Rebuilds the provider registry from scratch: config-declared providers first, then the
  * metadata catalog layered on top — the same two-source order as startup.
@@ -119,7 +129,7 @@ export async function initializeAuthProvidersFromMetadata(contextUser?: UserInfo
  *
  * @returns the number of providers registered from metadata after the refresh.
  */
-export async function refreshAuthProviders(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
+export async function RefreshAuthProviders(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
   await AuthProviderEngine.Instance.Config(true, contextUser, provider);
 
   // Probe the reloaded catalog BEFORE clearing anything: reading Providers throws
@@ -127,7 +137,7 @@ export async function refreshAuthProviders(contextUser?: UserInfo, provider?: IM
   // failure must abort the refresh while the registry is still intact.
   const pendingRows = AuthProviderEngine.Instance.Providers.length;
 
-  initializeAuthProviders();
+  InitializeAuthProviders();
   const count = await AuthProviderEngine.Instance.RegisterAll(contextUser);
   LogStatus(
     `[Auth] Provider registry refreshed — ${count} of ${pendingRows} metadata provider(s) registered on top of the config-declared set.`
@@ -135,6 +145,11 @@ export async function refreshAuthProviders(contextUser?: UserInfo, provider?: IM
   return count;
 }
 
+/** @deprecated Use {@link RefreshAuthProviders}. */
+export async function refreshAuthProviders(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number> {
+  return RefreshAuthProviders(contextUser, provider);
+}
+
 /**
  * Reports whether any provider is registered, from either source, and logs a diagnostic when none
  * is.
@@ -142,7 +157,7 @@ export async function refreshAuthProviders(contextUser?: UserInfo, provider?: IM
  * Split out from {@link initializeAuthProviders} because "no providers" is only genuinely wrong
  * once BOTH sources have had their turn.
  */
-export function validateAuthProvidersRegistered(): boolean {
+export function ValidateAuthProvidersRegistered(): boolean {
   const hasProviders = AuthProviderFactory.Instance.hasProviders();
   if (!hasProviders) {
     LogError(
@@ -152,3 +167,8 @@ export function validateAuthProvidersRegistered(): boolean {
   }
   return hasProviders;
 }
+
+/** @deprecated Use {@link ValidateAuthProvidersRegistered}. */
+export function validateAuthProvidersRegistered(): boolean {
+  return ValidateAuthProvidersRegistered();
+}

package/src/auth/magicLink/MagicLinkRouter.ts

@@ -15,7 +15,7 @@ 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 { BuildRedeemLandingHtml } from './redeemLanding.js';
 import type { CreateMagicLinkInviteParams, RedeemMagicLinkResult } from './types.js';
 
 /** The mount path for both routers (`/magic-link`). */
@@ -28,7 +28,7 @@ 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): {
+export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfig): {
   publicRouter: Router;
   authenticatedRouter: Router;
 } {
@@ -113,7 +113,7 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     res
       .status(200)
       .type('html')
-      .send(buildRedeemLandingHtml(token, `${MAGIC_LINK_MOUNT_PATH}/redeem`));
+      .send(BuildRedeemLandingHtml(token, `${MAGIC_LINK_MOUNT_PATH}/redeem`));
   });
 
   // POST /redeem performs the actual (side-effectful) redemption. Token arrives
@@ -151,7 +151,7 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     }
 
     const body = (req.body ?? {}) as Partial<CreateMagicLinkInviteParams>;
-    if (!body.email || !body.applicationId) {
+    if (!body.email || !body.ApplicationId) {
       res.status(400).json({ success: false, error: 'email and applicationId are required.' });
       return;
     }
@@ -159,10 +159,10 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     const result = await service.CreateInvite(
       {
         email: body.email,
-        applicationId: body.applicationId,
-        roleId: body.roleId,
-        expiresInHours: body.expiresInHours,
-        maxUses: body.maxUses,
+        ApplicationId: body.ApplicationId,
+        RoleId: body.RoleId,
+        ExpiresInHours: body.ExpiresInHours,
+        MaxUses: body.MaxUses,
         firstName: body.firstName,
         lastName: body.lastName,
       },
@@ -177,6 +177,14 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
   return { publicRouter, authenticatedRouter };
 }
 
+/** @deprecated Use {@link CreateMagicLinkHandler}. */
+export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfig): {
+  publicRouter: Router;
+  authenticatedRouter: Router;
+} {
+  return CreateMagicLinkHandler(publicUrl, config);
+}
+
 /**
  * A minimal PUBLIC router that serves ONLY the JWKS endpoint (the magic-link
  * signing key's public half). Mount this when the full magic-link flow is
@@ -186,7 +194,7 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
  * request 401s. Assumes the key is already initialized (the widget handler does
  * this via `MagicLinkKeyManager.Instance.Initialize` at startup).
  */
-export function createMagicLinkJwksRouter(): Router {
+export function CreateMagicLinkJwksRouter(): Router {
   const router = Router();
   router.get('/jwks.json', (_req: Request, res: Response) => {
     res.status(200).json(MagicLinkKeyManager.Instance.GetJWKS());
@@ -194,6 +202,11 @@ export function createMagicLinkJwksRouter(): Router {
   return router;
 }
 
+/** @deprecated Use {@link CreateMagicLinkJwksRouter}. */
+export function createMagicLinkJwksRouter(): Router {
+  return CreateMagicLinkJwksRouter();
+}
+
 /**
  * Registers the `magic-link` auth provider so MJServer's issuer-driven JWT
  * validation accepts MJ-issued session tokens. Issuer = public URL, JWKS URL =
@@ -202,7 +215,7 @@ export function createMagicLinkJwksRouter(): Router {
  * 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 {
+export function RegisterMagicLinkAuthProvider(publicUrl: string, config: MagicLinkConfig): void {
   const base = publicUrl.replace(/\/$/, '');
   const providerConfig: AuthProviderConfig = {
     name: 'magic-link',
@@ -224,3 +237,8 @@ export function registerMagicLinkAuthProvider(publicUrl: string, config: MagicLi
     LogError(`[MagicLink] Failed to register auth provider: ${e instanceof Error ? e.message : String(e)}`);
   }
 }
+
+/** @deprecated Use {@link RegisterMagicLinkAuthProvider}. */
+export function registerMagicLinkAuthProvider(publicUrl: string, config: MagicLinkConfig): void {
+  return RegisterMagicLinkAuthProvider(publicUrl, config);
+}

package/src/auth/magicLink/MagicLinkService.ts

@@ -35,7 +35,7 @@ import { CommunicationEngine } from '@memberjunction/communication-engine';
 import { Message } from '@memberjunction/communication-types';
 import { configInfo, type MagicLinkConfig } from '../../config.js';
 import { MagicLinkKeyManager } from './MagicLinkKeys.js';
-import { generateRawToken, generateSessionId, hashToken, evaluateInvite, buildSessionClaims, buildConsumeInviteSQL, canIssueInvites, isRoleGrantable, MAGIC_LINK_TOKEN_PREFIX } from './magicLinkCore.js';
+import { GenerateRawToken, GenerateSessionId, HashToken, EvaluateInvite, BuildSessionClaims, BuildConsumeInvitePostgresSQL, CanIssueInvites, IsRoleGrantable, MAGIC_LINK_TOKEN_PREFIX } from './magicLinkCore.js';
 import type {
   CreateMagicLinkInviteParams,
   CreateMagicLinkInviteResult,
@@ -48,6 +48,21 @@ const REDEMPTION_ENTITY = 'MJ: Magic Link Redemptions';
 /** Shared Anonymous principal — seeded by the Phase-4 migration; must match that UUID. */
 const ANONYMOUS_USER_ID = '273910DF-28F1-45C1-A8F8-6E9AD8E5F008';
 
+/** Outcome of the atomic single-use consume — see {@link MagicLinkService.consumeInvite}. */
+type ConsumeOutcome = 'won' | 'lost' | 'failed';
+
+/**
+ * The SQL Server guarded single-use procedure (migration V202609291627__v6.2.x__MagicLink_Consume_Invite_Sproc).
+ * A procedure, not raw DML, because on SQL Server MJ grants its runtime roles EXECUTE on procedures
+ * and SELECT on views — never DML on base tables — so on any host whose MJAPI login is not db_owner
+ * a raw UPDATE is refused (#4753). Ownership chaining lets the procedure update the table on the
+ * caller's behalf. PostgreSQL has no counterpart function; see {@link BuildConsumeInvitePostgresSQL}.
+ */
+const CONSUME_INVITE_PROC = 'spConsumeMagicLinkInvite';
+
+/** MagicLinkInvite base table (core schema) — the PostgreSQL consume updates it directly. */
+const INVITE_TABLE = 'MagicLinkInvite';
+
 /** Outcome of provisioning a redeeming user. */
 interface ProvisionResult {
   success: boolean;
@@ -90,11 +105,11 @@ export class MagicLinkService {
       // external user already holding a restricted magic-link session — could
       // issue invites and escalate.
       const callerRoleNames = (creatingUser.UserRoles ?? []).map((r) => r.Role).filter((n): n is string => !!n);
-      if (!canIssueInvites(creatingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
+      if (!CanIssueInvites(creatingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
         return { success: false, errorCode: 'forbidden', error: 'Not authorized to issue magic-link invites.' };
       }
 
-      const roleId = params.roleId ?? this.resolveRestrictedRoleId(md);
+      const roleId = params.RoleId ?? this.resolveRestrictedRoleId(md);
       if (!roleId) {
         return { success: false, error: `Restricted role '${this.config.restrictedRoleName}' not found and no roleId supplied.` };
       }
@@ -106,7 +121,7 @@ export class MagicLinkService {
       if (!roleToGrant) {
         return { success: false, errorCode: 'invalid_role', error: `Role '${roleId}' not found.` };
       }
-      if (!isRoleGrantable(roleToGrant.Name, this.config.restrictedRoleName, this.config.grantableRoleNames)) {
+      if (!IsRoleGrantable(roleToGrant.Name, this.config.restrictedRoleName, this.config.grantableRoleNames)) {
         return {
           success: false,
           errorCode: 'invalid_role',
@@ -114,23 +129,23 @@ export class MagicLinkService {
         };
       }
 
-      const app = md.Applications.find((a) => UUIDsEqual(a.ID, params.applicationId));
+      const app = md.Applications.find((a) => UUIDsEqual(a.ID, params.ApplicationId));
       if (!app) {
-        return { success: false, error: `Application '${params.applicationId}' not found.` };
+        return { success: false, error: `Application '${params.ApplicationId}' not found.` };
       }
 
-      const rawToken = generateRawToken();
-      const expiresInHours = params.expiresInHours ?? this.config.defaultExpiresInHours;
+      const rawToken = GenerateRawToken();
+      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 = HashToken(rawToken);
       invite.Email = params.email;
-      invite.ApplicationID = params.applicationId;
+      invite.ApplicationID = params.ApplicationId;
       invite.RoleID = roleId;
       invite.ExpiresAt = expiresAt;
-      invite.MaxUses = params.maxUses ?? 1;
+      invite.MaxUses = params.MaxUses ?? 1;
       invite.UseCount = 0;
       invite.CreatedByUserID = creatingUser.ID;
       invite.Status = 'Active';
@@ -143,7 +158,7 @@ export class MagicLinkService {
       // the single ApplicationID/RoleID. Additive — the columns stay authoritative for
       // redemption today; this populates the child tables for the eventual switch to
       // multi-scope reads. Best-effort so a child-row hiccup never fails issuance.
-      await this.writeInviteScopeChildRows(invite.ID, params.applicationId, roleId, creatingUser, md);
+      await this.writeInviteScopeChildRows(invite.ID, params.ApplicationId, roleId, creatingUser, md);
 
       const redemptionUrl = this.buildRedemptionUrl(rawToken);
 
@@ -173,9 +188,9 @@ export class MagicLinkService {
    * session JWT. Runs in the public (pre-auth) path, so it uses the global
    * provider and a configured provisioning context user.
    *
-   * Single-use is enforced by a compare-and-swap UPDATE ({@link consumeInvite})
-   * BEFORE the token is minted — two concurrent redemptions of a single-use
-   * link race on the same row and exactly one wins. The consume is the gate:
+   * Single-use is enforced by the guarded UPDATE inside the `spConsumeMagicLinkInvite`
+   * procedure ({@link consumeInvite}) BEFORE the token is minted — two concurrent
+   * redemptions of a single-use link race on the same row and exactly one wins. The consume is the gate:
    * if a later step fails, the use is already burned (fail-closed). That is the
    * correct trade-off for a single-use credential — burning a token on a server
    * error is recoverable (re-issue); allowing replay is not.
@@ -208,7 +223,7 @@ export class MagicLinkService {
       const md = Metadata.Provider; // global-provider-ok: server-side magic-link service; runs under the server's single default provider
       const provider = md as DatabaseProviderBase;
 
-      const tokenHash = hashToken(rawToken);
+      const tokenHash = HashToken(rawToken);
       const rv = new RunView();
       const found = await rv.RunView<MJMagicLinkInviteEntity>(
         {
@@ -231,7 +246,7 @@ export class MagicLinkService {
 
       // Fast, friendly pre-check (returns a precise reason). NOT the authority —
       // the atomic consume below is what actually enforces single-use.
-      const eligibility = evaluateInvite(invite, Date.now());
+      const eligibility = EvaluateInvite(invite, Date.now());
       if (!eligibility.ok) {
         return done({ success: false, errorCode: eligibility.errorCode, error: `Invite is ${eligibility.errorCode}.` });
       }
@@ -252,14 +267,18 @@ export class MagicLinkService {
         return done({ success: false, errorCode: 'server_error', error: 'Invite role not found.' });
       }
 
-      // Atomic consume BEFORE minting. If we lose the race (0 rows updated), the
-      // invite was concurrently consumed/expired — re-evaluate the now-stale
-      // in-memory copy only to surface a precise code; default to 'consumed'.
-      if (!(await this.consumeInvite(invite, provider, contextUser))) {
+      // Atomic consume BEFORE minting. A statement that never ran (permissions,
+      // missing procedure, connection) is a server fault, not a lost race — report
+      // it as such so operators aren't sent hunting a double-redeem (#4753).
+      const consume = await this.consumeInvite(invite, provider, contextUser);
+      if (consume === 'failed') {
+        return done({ success: false, errorCode: 'server_error', error: 'Could not redeem the invite due to a server error.' });
+      }
+      if (consume === 'lost') {
         // Lost the race or the invite expired between the pre-check and the
         // consume. The in-memory copy still looks eligible if only the DB-side
         // use count changed, so default that case to 'consumed'.
-        const recheck = evaluateInvite(invite, Date.now());
+        const recheck = EvaluateInvite(invite, Date.now());
         return done({ success: false, errorCode: recheck.ok ? 'consumed' : recheck.errorCode, error: 'Invite already redeemed or expired.' });
       }
 
@@ -273,7 +292,7 @@ export class MagicLinkService {
 
       const nowSeconds = Math.floor(Date.now() / 1000);
       const isAnon = invite.IdentityMode === 'anonymous';
-      const claims = buildSessionClaims({
+      const claims = BuildSessionClaims({
         issuer: this.publicUrl,
         audience: this.config.audience,
         inviteId: invite.ID,
@@ -286,7 +305,7 @@ export class MagicLinkService {
         anonymous: isAnon,
         // Per-session id for anon forensics (correlates one session's activity since all
         // anon redemptions share the Anonymous principal). Carried into the redemption audit row.
-        sessionId: isAnon ? generateSessionId() : undefined,
+        sessionId: isAnon ? GenerateSessionId() : undefined,
         // Resource-share scope (Phase 5): the single shared resource this link grants.
         resourceId: invite.ResourceID ?? undefined,
         nowSeconds,
@@ -639,39 +658,39 @@ export class MagicLinkService {
   }
 
   /**
-   * Atomically consumes one use of the invite via a compare-and-swap UPDATE.
-   * The WHERE clause re-checks every eligibility condition (Active, not
-   * exhausted, not expired) at the DB level, so the increment and the guard are
-   * a single atomic operation. Returns true ONLY when this call updated the row
-   * (won the race); concurrent redemptions of a single-use link see 0 rows.
+   * Atomically consumes one use of the invite with a single guarded UPDATE that re-checks every
+   * eligibility condition (Active, not exhausted, not expired) at the DB level, so the increment and
+   * the guard are one atomic operation. Concurrent redemptions of a single-use link race on the row
+   * and exactly one gets the row back.
    *
-   * Dialect-aware: SQL Server uses an `OUTPUT`-into-table-variable win-detect;
-   * PostgreSQL uses `UPDATE … WHERE … RETURNING` (the WHERE guard is itself the
-   * atomic single-use gate). The platform is read from the provider itself
-   * (`PlatformKey`), not from process env, so this is correct even under a
-   * non-default per-connection provider. The invite ID always binds as a
-   * parameter (`@p0` / `$1`), never interpolated.
+   * The statement differs per platform because the grants do:
+   * - **SQL Server** calls {@link CONSUME_INVITE_PROC} (`EXEC … @ID=@p0`). Runtime roles have
+   *   EXECUTE on procedures but no DML on base tables (#4753).
+   * - **PostgreSQL** runs {@link BuildConsumeInvitePostgresSQL}'s `UPDATE … RETURNING` directly.
+   *   Runtime roles hold table DML there, and no PG counterpart of the procedure exists.
+   * The ID is always a bound parameter.
    *
-   * Fail-closed: any DB error returns false and the redemption is rejected.
+   * Returns `'won'` (this call consumed a use), `'lost'` (the guard matched nothing: consumed,
+   * revoked or expired concurrently) or `'failed'` (the statement never ran — permissions, a missing
+   * procedure, a connection error). `'failed'` is kept distinct from `'lost'` on purpose: collapsing
+   * them is what made #4753's permission error surface to users as "already redeemed".
    */
-  private async consumeInvite(invite: MJMagicLinkInviteEntity, provider: DatabaseProviderBase, contextUser: UserInfo): Promise<boolean> {
+  private async consumeInvite(invite: MJMagicLinkInviteEntity, provider: DatabaseProviderBase, contextUser: UserInfo): Promise<ConsumeOutcome> {
+    const isPg = provider.PlatformKey === 'postgresql';
+    const statement = isPg ? `PostgreSQL guarded UPDATE on ${INVITE_TABLE}` : CONSUME_INVITE_PROC;
     try {
-      const entityInfo = provider.EntityByName(INVITE_ENTITY);
-      if (!entityInfo) {
-        LogError(`[MagicLink] Entity metadata for '${INVITE_ENTITY}' not found; cannot consume invite.`);
-        return false;
-      }
-      const isPg = provider.PlatformKey === 'postgresql';
-      // PG identifiers are auto-quoted by PostgreSQLDataProvider.ExecuteSQL, so
-      // pass the bare `schema.table`; SQL Server takes the bracket-quoted form.
-      const table = isPg ? `${entityInfo.SchemaName}.${entityInfo.BaseTable}` : `[${entityInfo.SchemaName}].[${entityInfo.BaseTable}]`;
-      // OUTPUT/RETURNING yields one row iff the WHERE matched — the atomic single-use gate.
-      const sql = buildConsumeInviteSQL(table, isPg ? 'postgresql' : 'sqlserver');
-      const rows = await provider.ExecuteSQL<{ ID: string }>(sql, [invite.ID], { isMutation: true }, contextUser);
-      return Array.isArray(rows) && rows.length === 1;
+      const sql = isPg
+        ? BuildConsumeInvitePostgresSQL(`${provider.MJCoreSchemaName}.${INVITE_TABLE}`)
+        : provider.Dialect.ProcedureCallSyntax(provider.MJCoreSchemaName, CONSUME_INVITE_PROC, [`@ID=${provider.BuildParameterPlaceholder(0)}`]);
+      const rows = await provider.ExecuteSQL<{ ID: string }>(sql, [invite.ID], { isMutation: true, description: `MagicLink ${statement}` }, contextUser);
+      if (!Array.isArray(rows)) {
+        LogError(`[MagicLink] ${statement} returned no result set for invite ${invite.ID}; treating the consume as failed.`);
+        return 'failed';
+      }
+      return rows.length === 1 ? 'won' : 'lost';
     } catch (e) {
-      LogError(`[MagicLink] Atomic consume failed for invite ${invite.ID}: ${e instanceof Error ? e.message : String(e)}`);
-      return false;
+      LogError(`[MagicLink] ${statement} FAILED for invite ${invite.ID} — the statement never ran, so this is NOT a lost race: ${e instanceof Error ? e.message : String(e)}`);
+      return 'failed';
     }
   }
 

package/src/auth/magicLink/index.ts

@@ -1,18 +1,18 @@
 export * from './types.js';
 export {
-  generateRawToken,
-  hashToken,
-  evaluateInvite,
-  buildSessionClaims,
+  GenerateRawToken, generateRawToken,
+  HashToken, hashToken,
+  EvaluateInvite, evaluateInvite,
+  BuildSessionClaims, buildSessionClaims,
   MAGIC_LINK_TOKEN_PREFIX,
   type InviteEvaluationInput,
 } from './magicLinkCore.js';
 export { MagicLinkKeyManager } from './MagicLinkKeys.js';
 export { MagicLinkService } from './MagicLinkService.js';
 export {
-  createMagicLinkHandler,
-  createMagicLinkJwksRouter,
-  registerMagicLinkAuthProvider,
+  CreateMagicLinkHandler, createMagicLinkHandler,
+  CreateMagicLinkJwksRouter, createMagicLinkJwksRouter,
+  RegisterMagicLinkAuthProvider, registerMagicLinkAuthProvider,
   MAGIC_LINK_MOUNT_PATH,
   MAGIC_LINK_JWKS_PATH,
 } from './MagicLinkRouter.js';