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

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';

package/src/auth/magicLink/magicLinkCore.ts

@@ -13,25 +13,40 @@ import type { MagicLinkJWTClaims, MagicLinkScopeEntry, RedeemErrorCode } from '.
 export const MAGIC_LINK_TOKEN_PREFIX = 'mj_ml_';
 
 /** Generates a cryptographically random raw magic-link token. */
-export function generateRawToken(): string {
+export function GenerateRawToken(): string {
   return MAGIC_LINK_TOKEN_PREFIX + randomBytes(32).toString('hex');
 }
 
+/** @deprecated Use {@link GenerateRawToken}. */
+export function generateRawToken(): string {
+  return GenerateRawToken();
+}
+
 /** Generates an opaque per-session id (anonymous-session forensics correlation). */
-export function generateSessionId(): string {
+export function GenerateSessionId(): string {
   return randomBytes(16).toString('base64url');
 }
 
+/** @deprecated Use {@link GenerateSessionId}. */
+export function generateSessionId(): string {
+  return GenerateSessionId();
+}
+
 /**
  * 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 {
+export function HashToken(rawToken: string): string {
   return createHash('sha256').update(rawToken).digest('base64url');
 }
 
+/** @deprecated Use {@link HashToken}. */
+export function hashToken(rawToken: string): string {
+  return HashToken(rawToken);
+}
+
 /** Minimal shape of an invite needed for redemption eligibility. */
 export interface InviteEvaluationInput {
   Status: string;
@@ -54,7 +69,7 @@ function normalizeName(name: string): string {
  * (including an external user already holding a restricted magic-link session)
  * from minting invites.
  */
-export function canIssueInvites(
+export function CanIssueInvites(
   userType: string | null | undefined,
   userRoleNames: readonly string[],
   issuerRoleNames: readonly string[],
@@ -69,13 +84,22 @@ export function canIssueInvites(
   return userRoleNames.some((r) => allowed.has(normalizeName(r)));
 }
 
+/** @deprecated Use {@link CanIssueInvites}. */
+export function canIssueInvites(
+  userType: string | null | undefined,
+  userRoleNames: readonly string[],
+  issuerRoleNames: readonly string[],
+): boolean {
+  return CanIssueInvites(userType, userRoleNames, issuerRoleNames);
+}
+
 /**
  * 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(
+export function IsRoleGrantable(
   roleName: string | null | undefined,
   restrictedRoleName: string,
   grantableRoleNames: readonly string[],
@@ -88,8 +112,17 @@ export function isRoleGrantable(
   return allowed.has(target);
 }
 
+/** @deprecated Use {@link IsRoleGrantable}. */
+export function isRoleGrantable(
+  roleName: string | null | undefined,
+  restrictedRoleName: string,
+  grantableRoleNames: readonly string[],
+): boolean {
+  return IsRoleGrantable(roleName, restrictedRoleName, grantableRoleNames);
+}
+
 /** Pure redemption-eligibility check. Returns ok + an error code when not. */
-export function evaluateInvite(invite: InviteEvaluationInput, nowMs: number): { ok: boolean; errorCode?: RedeemErrorCode } {
+export function EvaluateInvite(invite: InviteEvaluationInput, nowMs: number): { ok: boolean; errorCode?: RedeemErrorCode } {
   if (invite.Status === 'Revoked') {
     return { ok: false, errorCode: 'revoked' };
   }
@@ -106,75 +139,43 @@ export function evaluateInvite(invite: InviteEvaluationInput, nowMs: number): {
   return { ok: true };
 }
 
-/** SQL dialect for {@link buildConsumeInviteSQL}. */
-export type ConsumeInviteDialect = 'sqlserver' | 'postgresql';
+/** @deprecated Use {@link EvaluateInvite}. */
+export function evaluateInvite(invite: InviteEvaluationInput, nowMs: number): { ok: boolean; errorCode?: RedeemErrorCode } {
+  return EvaluateInvite(invite, nowMs);
+}
 
-/** SQL Server table identifier — bracket-quoted `[schema].[table]` (word chars only). */
-const QUALIFIED_TABLE_PATTERN = /^\[\w+\]\.\[\w+\]$/;
 /** PostgreSQL table identifier — `schema.table` (word chars only); auto-quoted downstream. */
 const QUALIFIED_TABLE_PATTERN_PG = /^\w+\.\w+$/;
 
 /**
- * Builds the atomic compare-and-swap UPDATE that consumes one use of an invite,
- * in the given SQL dialect.
- *
- * 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. This is what
- * actually enforces single-use — the JS-side `evaluateInvite` is only a friendly
- * pre-check. The matched row's ID is returned to the caller (via `OUTPUT` on SQL
- * Server, `RETURNING` on PostgreSQL) so it can detect a win (exactly one row).
+ * Builds the PostgreSQL atomic compare-and-swap UPDATE that consumes one use of an invite.
  *
- * The invite ID MUST be bound as a parameter by the caller (`@p0` on SQL Server,
- * `$1` on PostgreSQL) — it is never interpolated into the string, so this builder
- * is injection-safe regardless of the ID's contents.
+ * PostgreSQL only. SQL Server consumes through the granted `spConsumeMagicLinkInvite` procedure,
+ * because its runtime roles are never granted table DML (#4753). PostgreSQL needs neither: its
+ * runtime roles hold INSERT/UPDATE/DELETE on every `__mj` table
+ * (V202605040300__v5.33.x__Unblock_PostgreSQL_End_To_End.pg-only.sql), and no PG counterpart of
+ * the procedure exists — the release-time converter leaves `CREATE PROCEDURE` unhandled.
  *
- * **SQL Server** — `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 the matched row(s) regardless of trigger behavior.
+ * The WHERE re-checks every eligibility condition (the same predicate as the procedure), so the
+ * increment and the guard are one atomic statement: concurrent redemptions of a single-use link
+ * serialize on the row lock and exactly one matches. `RETURNING ID` yields the row iff the guard
+ * matched. The invite ID MUST be bound by the caller as `$1` — it is never interpolated.
  *
- * **PostgreSQL** — the `UPDATE … WHERE` guard IS itself the atomic single-use
- * gate: the row is locked for the UPDATE's duration, so concurrent redemptions
- * serialize and only the first matching `Status='Active' AND UseCount < MaxUses`
- * wins; `RETURNING` yields the row iff the guard matched (equivalent to the SS
- * `OUTPUT`-into-table win-detect). PascalCase identifiers are auto-quoted by
- * `PostgreSQLDataProvider.ExecuteSQL`, so the table is passed unquoted (`schema.table`).
- *
- * `qualifiedTable` is asserted to match the dialect's whitelist pattern 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  `[schema].[table]` (sqlserver) or `schema.table` (postgresql) for MagicLinkInvite
- * @param dialect         target SQL dialect (defaults to `'sqlserver'`)
+ * `qualifiedTable` is `schema.table` unquoted (PostgreSQLDataProvider.ExecuteSQL auto-quotes the
+ * PascalCase identifiers) and is asserted against a whitelist before interpolation — the caller
+ * never passes user input, so this is defense-in-depth.
  */
-export function buildConsumeInviteSQL(qualifiedTable: string, dialect: ConsumeInviteDialect = 'sqlserver'): string {
-  if (dialect === 'postgresql') {
-    if (!QUALIFIED_TABLE_PATTERN_PG.test(qualifiedTable)) {
-      throw new Error(`buildConsumeInviteSQL: refusing to build SQL for non-whitelisted table identifier '${qualifiedTable}'.`);
-    }
-    return (
-      `UPDATE ${qualifiedTable} ` +
-      `SET UseCount = UseCount + 1, ` +
-      `ConsumedAt = COALESCE(ConsumedAt, (now() AT TIME ZONE 'utc')), ` +
-      `Status = CASE WHEN UseCount + 1 >= MaxUses THEN 'Consumed' ELSE Status END ` +
-      `WHERE ID = $1 AND Status = 'Active' AND UseCount < MaxUses AND ExpiresAt > (now() AT TIME ZONE 'utc') ` +
-      `RETURNING ID;`
-    );
-  }
-  if (!QUALIFIED_TABLE_PATTERN.test(qualifiedTable)) {
-    throw new Error(`buildConsumeInviteSQL: refusing to build SQL for non-whitelisted table identifier '${qualifiedTable}'.`);
+export function BuildConsumeInvitePostgresSQL(qualifiedTable: string): string {
+  if (!QUALIFIED_TABLE_PATTERN_PG.test(qualifiedTable)) {
+    throw new Error(`BuildConsumeInvitePostgresSQL: 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()), ` +
+    `ConsumedAt = COALESCE(ConsumedAt, (now() AT TIME ZONE 'utc')), ` +
     `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;`
+    `WHERE ID = $1 AND Status = 'Active' AND UseCount < MaxUses AND ExpiresAt > (now() AT TIME ZONE 'utc') ` +
+    `RETURNING ID;`
   );
 }
 
@@ -184,7 +185,7 @@ export function buildConsumeInviteSQL(qualifiedTable: string, dialect: ConsumeIn
  * 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[] {
+export function UnionScopes(prior: readonly MagicLinkScopeEntry[] | undefined, next: MagicLinkScopeEntry): MagicLinkScopeEntry[] {
   const result = [...(prior ?? [])];
   if (!result.some((s) => s.inviteId === next.inviteId)) {
     result.push(next);
@@ -192,8 +193,13 @@ export function unionScopes(prior: readonly MagicLinkScopeEntry[] | undefined, n
   return result;
 }
 
+/** @deprecated Use {@link UnionScopes}. */
+export function unionScopes(prior: readonly MagicLinkScopeEntry[] | undefined, next: MagicLinkScopeEntry): MagicLinkScopeEntry[] {
+  return UnionScopes(prior, next);
+}
+
 /** Builds the session-token claims (pure). */
-export function buildSessionClaims(args: {
+export function BuildSessionClaims(args: {
   issuer: string;
   audience: string;
   inviteId: string;
@@ -236,9 +242,35 @@ export function buildSessionClaims(args: {
     mj_app_id: args.applicationId,
     mj_role: args.roleName,
     mj_invited_by: args.invitedByUserId,
-    mj_scopes: unionScopes(args.priorScopes, scopeEntry),
+    mj_scopes: UnionScopes(args.priorScopes, scopeEntry),
     mj_anon: args.anonymous ? true : undefined,
     mj_sid: args.sessionId,
     mj_magic_link: true,
   };
 }
+
+/** @deprecated Use {@link BuildSessionClaims}. */
+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 {
+  return BuildSessionClaims(args);
+}

package/src/auth/magicLink/redeemLanding.ts

@@ -5,7 +5,7 @@
  */
 
 /** Minimal HTML-escape for safe interpolation into attribute/text content. */
-export function escapeHtml(s: string): string {
+export function EscapeHtml(s: string): string {
   return s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -14,6 +14,11 @@ export function escapeHtml(s: string): string {
     .replace(/'/g, '&#39;');
 }
 
+/** @deprecated Use {@link EscapeHtml}. */
+export function escapeHtml(s: string): string {
+  return EscapeHtml(s);
+}
+
 /**
  * Builds the redemption landing page served by `GET /magic-link/redeem`.
  *
@@ -27,9 +32,9 @@ export function escapeHtml(s: string): string {
  * @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);
+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>
@@ -60,3 +65,8 @@ export function buildRedeemLandingHtml(token: string, actionPath: string): strin
 </body>
 </html>`;
 }
+
+/** @deprecated Use {@link BuildRedeemLandingHtml}. */
+export function buildRedeemLandingHtml(token: string, actionPath: string): string {
+  return BuildRedeemLandingHtml(token, actionPath);
+}