@memberjunction/server 5.38.0 → 5.40.0

package/dist/auth/magicLink/MagicLinkService.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Imperative shell for magic links: invite creation, redemption,
+ * user provisioning, and session-token minting. The pure logic lives in
+ * `magicLinkCore.ts`; this module wires it to the DB, key manager, and
+ * communication engine.
+ *
+ * @module @memberjunction/server/auth/magicLink
+ */
+import { UserInfo, type IMetadataProvider } from '@memberjunction/core';
+import { type MagicLinkConfig } from '../../config.js';
+import type { CreateMagicLinkInviteParams, CreateMagicLinkInviteResult, RedeemMagicLinkResult, RedeemAuditContext } from './types.js';
+/**
+ * Magic-link service. One instance per server, constructed with the resolved
+ * public URL and the validated config.
+ */
+export declare class MagicLinkService {
+    private readonly publicUrl;
+    private readonly config;
+    constructor(publicUrl: string, config: MagicLinkConfig);
+    /**
+     * Creates a single-use, app-scoped invite, persists its hashed token, and
+     * (when a communication provider is configured) emails the link.
+     *
+     * @param params  invite parameters
+     * @param creatingUser  the authenticated internal user issuing the invite
+     * @param provider  the request's metadata provider; falls back to the global default
+     */
+    CreateInvite(params: CreateMagicLinkInviteParams, creatingUser: UserInfo, provider?: IMetadataProvider): Promise<CreateMagicLinkInviteResult>;
+    /**
+     * Redeems a raw token: validates the invite, atomically consumes one use,
+     * provisions/links the user with the restricted role + app, and mints a
+     * 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:
+     * 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.
+     */
+    RedeemInvite(rawToken: string, audit?: RedeemAuditContext): Promise<RedeemMagicLinkResult>;
+    /**
+     * Writes one MagicLinkRedemption audit row for a redemption attempt. Best-effort:
+     * a failure here is logged but never fails the redemption (the user already has,
+     * or has been denied, their session — losing an audit row must not change that).
+     *
+     * InviteID/ProvisionedUserID are null when the attempt didn't get far enough to
+     * resolve them (e.g. a malformed or unknown token — exactly the scan/brute-force
+     * signal we want recorded). IP/User-Agent/Origin are stored as supplied by the
+     * router per the deployment's audit policy.
+     */
+    private recordRedemption;
+    /**
+     * Writes the Phase-2 multi-scope child rows (one application + one role) that
+     * mirror the invite's single ApplicationID/RoleID. The columns remain the
+     * source of truth for redemption today; these rows pre-stage the data for the
+     * eventual switch to multi-scope reads, avoiding a breaking migration later.
+     * Best-effort: a child-write failure is logged but does not fail invite
+     * issuance (the columns alone keep the one-of-each flow working).
+     */
+    private writeInviteScopeChildRows;
+    /** Resolves the configured restricted role's ID, if present. */
+    private resolveRestrictedRoleId;
+    /** Builds the shareable redemption URL. */
+    private buildRedemptionUrl;
+    /**
+     * Provisions the redeeming user: finds them by email or creates them, then
+     * ensures the restricted role and the single app assignment exist.
+     */
+    private provisionUser;
+    /**
+     * Resolves the shared Anonymous principal for an anonymous-mode redemption. This
+     * principal is an ATTRIBUTION ANCHOR only — it holds no scenario roles and gets no
+     * UserRole/UserApplication rows here, so concurrent anon visitors can never accrete
+     * scope onto a shared identity. Their actual scope lives in the per-session JWT
+     * claims (mj_scopes) and is enforced claims-side. Fail-closed if the principal was
+     * never seeded (the Phase-4 migration is required).
+     */
+    private resolveAnonymousPrincipal;
+    /**
+     * True if an existing account is "protected" from magic-link provisioning: an
+     * Owner, or a user holding any role OUTSIDE the set of roles magic-link may
+     * legitimately grant. That allowed set is: the configured restricted role, the
+     * deployment's `grantableRoleNames`, AND the role THIS invite grants. So a prior
+     * magic-link guest holding only magic-link-grantable roles (e.g. the invite's own
+     * granted role) is NOT protected — re-redeeming a multi-use link is the intended
+     * flow. A user holding e.g. Developer/Admin is still protected and blocked.
+     *
+     * @param user  the existing account being re-provisioned
+     * @param invitedRoleName  the role name this invite grants
+     */
+    private isProtectedAccount;
+    /** Creates a new user with exactly the restricted role + single app, transactionally. */
+    private createScopedUser;
+    /** Idempotently ensures an existing user has the given role and app assignment. */
+    private ensureRoleAndApp;
+    /** Idempotently ensures the role has CanAccess to the application (Application Role). */
+    private ensureAppAccess;
+    /**
+     * 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.
+     *
+     * Fail-closed: any DB error returns false and the redemption is rejected.
+     */
+    private consumeInvite;
+    /** Pushes a freshly created user into the UserCache with its single role. */
+    private pushUserToCache;
+    /**
+     * True iff the invite's creator resolves to a still-active user. Used to
+     * fail-closed at redeem time so a deactivated/removed inviter's outstanding
+     * links stop working. A missing/blank CreatedByUserID is treated as inactive.
+     */
+    private isInviterActive;
+    /** Resolves the user whose context provisions magic-link users. */
+    private resolveProvisioningContextUser;
+    /** Sends the invite email via the configured communication provider. Best-effort. */
+    private sendInviteEmail;
+}
+//# sourceMappingURL=MagicLinkService.d.ts.map

package/dist/auth/magicLink/MagicLinkService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MagicLinkService.d.ts","sourceRoot":"","sources":["../../../src/auth/magicLink/MagicLinkService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,QAAQ,EAIR,KAAK,iBAAiB,EAEvB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAkBpB;;;GAGG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe;IAG1C;;;;;;;OAOG;IACU,YAAY,CACvB,MAAM,EAAE,2BAA2B,EACnC,YAAY,EAAE,QAAQ,EACtB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,2BAA2B,CAAC;IAsFvC;;;;;;;;;;;;OAYG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAmIvG;;;;;;;;;OASG;YACW,gBAAgB;IAoC9B;;;;;;;OAOG;YACW,yBAAyB;IA4BvC,gEAAgE;IAChE,OAAO,CAAC,uBAAuB;IAM/B,2CAA2C;IAC3C,OAAO,CAAC,kBAAkB;IAK1B;;;OAGG;YACW,aAAa;IAgD3B;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IASjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kBAAkB;IAY1B,yFAAyF;YAC3E,gBAAgB;IA2D9B,mFAAmF;YACrE,gBAAgB;IA4C9B,yFAAyF;YAC3E,eAAe;IA6B7B;;;;;;;;OAQG;YACW,aAAa;IAkB3B,6EAA6E;IAC7E,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAQvB,mEAAmE;IACnE,OAAO,CAAC,8BAA8B;IAYtC,qFAAqF;YACvE,eAAe;CA0B9B"}