@memberjunction/server 6.2.0-edge.3 → 6.2.0-edge.5

package/dist/realtimeSessions/verificationWorkflow.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @fileoverview The orchestration of mid-session identity verification, written against **ports** so the
+ * whole policy surface (every refusal, every limit, deadline extension, single use) is unit-testable
+ * without a database, a mail server or a PubSub.
+ *
+ * {@link RealtimeSessionVerificationWorkflow} owns the decisions and their order; the injected
+ * {@link VerificationPorts} own the side effects (read the session, write its `Config`, send the email,
+ * publish the event, write the audit row). `RealtimeSessionVerificationService` wires the real ports.
+ *
+ * ## Operations
+ *
+ * | Operation | Caller | What it does |
+ * |---|---|---|
+ * | {@link RealtimeSessionVerificationWorkflow.RequestVerification} | the session's own principal | validates, applies policy + limits, stores a pending verification, emails link + code |
+ * | {@link RealtimeSessionVerificationWorkflow.SubmitCode} | the session's own principal | redeems the typed code |
+ * | {@link RealtimeSessionVerificationWorkflow.RedeemLink} | anyone holding the emailed link (public route) | redeems the link token |
+ * | {@link RealtimeSessionVerificationWorkflow.GetStatus} | the session's own principal | reads the current state (the durable backstop for a missed event) |
+ *
+ * ## What a successful verification does — and does not do
+ *
+ * It records the verified identity on the session, **extends the session's deadline** when policy says
+ * to, publishes `identity.verified`, and writes an audit entry. It does **not** create an MJ user, swap
+ * the session's principal, or link a Person/User: the principal never changes, so ownership and
+ * row-level security are untouched. Linking the verified email to a record is an application decision,
+ * made by a server-side subscriber to the event.
+ *
+ * ## Concurrency
+ *
+ * Operations on one session are serialised in-process (a per-session mutex) so two simultaneous
+ * redemptions cannot both pass, and every write re-reads the session's current state first. Across
+ * *replicas* the database offers no compare-and-swap on `Config`, so strict single-use and attempt
+ * counting are exact per instance and best-effort across them: the worst a cross-replica race can do is
+ * let two simultaneous redemptions of the same valid secret both succeed (they converge on the same
+ * verified identity) or let a burst of parallel guesses count as one attempt. The per-session attempt
+ * rate limiter and the code's 6-digit space bound the latter.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import type { IdentityVerifiedEventPayload } from '@memberjunction/ai-core-plus';
+import { type IdentityVerificationPolicy } from './verificationPolicy.js';
+import { type VerifiedIdentity } from './verificationCore.js';
+/** Who is calling. A `principal` is an authenticated GraphQL caller; a `link` is the public verify route. */
+export type VerificationCaller = {
+    Kind: 'principal';
+    /** The authenticated user the server built from the caller's token — the source of truth for ownership. */
+    ContextUser: UserInfo;
+    /** The request-scoped provider. */
+    Provider: IMetadataProvider;
+    /** The caller's network address, for abuse limits only. */
+    ClientIp?: string;
+} | {
+    Kind: 'link';
+    ClientIp?: string;
+};
+/** The principal variant of {@link VerificationCaller}. */
+export type PrincipalCaller = Extract<VerificationCaller, {
+    Kind: 'principal';
+}>;
+/** A read of a session, reduced to what verification needs. */
+export interface SessionSnapshot {
+    AgentSessionID: string;
+    /** `AIAgentSession.UserID`. */
+    OwnerUserID: string;
+    /** `Conversation.ExternalID` (anonymous scope id), or null. */
+    ConversationExternalID: string | null;
+    Status: 'Active' | 'Idle' | 'Closed';
+    /** `AIAgentSession.Config` as stored. */
+    ConfigRaw: string | null;
+    /** When the session started, epoch ms. */
+    StartedAtMs: number;
+}
+/** A read-modify-write of a session's `Config`: given the CURRENT snapshot, decide what to write. */
+export type ConfigMutation<T> = (current: SessionSnapshot) => {
+    NextConfigRaw: string | null;
+    Outcome: T;
+};
+/** Result of {@link VerificationPorts.MutateSessionConfig}. */
+export interface ConfigMutationResult<T> {
+    /** The session as read just before the mutation; undefined when it could not be read. */
+    Session?: SessionSnapshot;
+    /** What the mutation returned; undefined when it never ran. */
+    Outcome?: T;
+    /** True when a write was requested AND succeeded. */
+    Persisted: boolean;
+    /** Why a requested write (or the read) failed. */
+    ErrorMessage?: string;
+}
+/** An email to send. */
+export interface OutboundEmail {
+    To: string;
+    Subject: string;
+    Text: string;
+    Html: string;
+}
+/** What the audit trail records for a completed verification. */
+export interface VerificationAuditEntry {
+    AgentSessionID: string;
+    OwnerUserID: string;
+    Email: string;
+    Method: VerifiedIdentity['Method'];
+    ClientIp?: string;
+    /** The session's deadline after verification, when it was extended. */
+    MaxSessionDeadlineIso?: string;
+}
+/** Settings the workflow reads (resolved from server config by the service). */
+export interface VerificationSettings {
+    /** Master switch. Must be false when no {@link VerificationSettings.CodeHashKey} is available. */
+    Enabled: boolean;
+    /**
+     * Server-only key the typed code is HMAC'd under before it is stored. It must never reach a client or a
+     * session row: the session owner can read their own `Config`, and without this key a six-digit code
+     * hash cannot be reversed offline. See `HashVerificationCode`.
+     */
+    CodeHashKey: string;
+    /** Base policy layer from server config. */
+    PolicyDefaults: IdentityVerificationPolicy;
+    /** Base URL for the emailed link, no trailing slash; undefined ⇒ the feature cannot send. */
+    PublicBaseUrl: string | undefined;
+    /** Limits applied in memory (0 disables a limit). */
+    RateLimits: {
+        SendWindowMs: number;
+        PerIpSends: number;
+        PerEmailDomainSends: number;
+        PerEmailSends: number;
+        CodeAttemptWindowMs: number;
+        PerSessionCodeAttempts: number;
+    };
+}
+/** Every side effect the workflow needs. */
+export interface VerificationPorts {
+    GetSettings(): VerificationSettings;
+    /** Current time, epoch ms. */
+    Now(): number;
+    /**
+     * Loads a session as the CALLER (so row-level security is the first gate). For a `link` caller there is
+     * no identity to load as, so the real port reads as the configured service principal.
+     */
+    LoadSession(agentSessionId: string, caller: VerificationCaller): Promise<SessionSnapshot | null>;
+    /** Re-reads the session fresh, runs `mutate` on it, and persists the returned `Config` (trusted write). */
+    MutateSessionConfig<T>(agentSessionId: string, caller: VerificationCaller, mutate: ConfigMutation<T>): Promise<ConfigMutationResult<T>>;
+    /** Sends an email. Must not throw; reports failure in the result. */
+    SendEmail(email: OutboundEmail): Promise<{
+        Success: boolean;
+        ErrorMessage?: string;
+    }>;
+    /** Publishes `identity.verified` to the session. Must not throw. */
+    PublishVerified(routing: {
+        AgentSessionID: string;
+        OwnerUserID: string;
+        ScopeKey: string | null;
+    }, payload: IdentityVerifiedEventPayload): {
+        Success: boolean;
+        ErrorMessage?: string;
+    };
+    /** Records the audit entry. Must not throw. */
+    WriteAudit(entry: VerificationAuditEntry): Promise<void>;
+}
+/** Machine-readable failure reasons. Stable: clients branch on these. */
+export type VerificationErrorCode = 'verification_unavailable' | 'invalid_input' | 'invalid_email' | 'session_not_found' | 'session_closed' | 'domain_blocked' | 'consumer_domain' | 'send_limit_reached' | 'rate_limited' | 'email_send_failed' | 'no_pending_verification' | 'code_expired' | 'invalid_code' | 'attempts_exhausted' | 'invalid_link' | 'persist_failed';
+/** Where a session stands. */
+export type VerificationStateName = 'unverified' | 'pending' | 'verified';
+/** Result of every workflow operation. */
+export interface VerificationOperationResult {
+    Success: boolean;
+    /** The session's verification state after the operation (best knowledge; `unverified` on early refusals). */
+    VerificationState: VerificationStateName;
+    ErrorCode?: VerificationErrorCode;
+    /** A message safe to show a person. */
+    Message?: string;
+    /** When the pending link/code expires (ISO). */
+    ExpiresAt?: string;
+    /** Verification emails this session may still trigger. */
+    SendsRemaining?: number;
+    /** Wrong code entries left before the pending verification is voided. */
+    AttemptsRemaining?: number;
+    /** Seconds to wait before retrying, when rate limited. */
+    RetryAfterSeconds?: number;
+    /** The verified address, once verified. */
+    VerifiedEmail?: string;
+    /** When verification completed (ISO). */
+    VerifiedAt?: string;
+    /** The session's deadline after verification, when it was extended (ISO). */
+    MaxSessionDeadlineIso?: string;
+}
+/**
+ * The decisions and their order. See the module header for the contract.
+ */
+export declare class RealtimeSessionVerificationWorkflow {
+    private readonly ports;
+    private readonly ipLimiter;
+    private readonly domainLimiter;
+    private readonly emailLimiter;
+    private readonly codeLimiter;
+    private readonly locks;
+    constructor(ports: VerificationPorts);
+    /** Whether the feature is switched on. */
+    get IsEnabled(): boolean;
+    /**
+     * Asks to verify `Email` for the caller's session: validates, applies policy and limits, stores a
+     * pending verification (hashes only) and emails a one-time link plus a typed code.
+     *
+     * Nothing is consumed unless the email is actually sent: a delivery failure rolls the stored state back.
+     */
+    RequestVerification(input: {
+        AgentSessionID: string;
+        Name: string;
+        Email: string;
+    }, caller: PrincipalCaller): Promise<VerificationOperationResult>;
+    /**
+     * Redeems the typed code for the caller's session. Wrong entries are counted against the pending
+     * verification and void it at `maxCodeAttempts`; submissions are also rate limited per session.
+     */
+    SubmitCode(input: {
+        AgentSessionID: string;
+        Code: string;
+    }, caller: PrincipalCaller): Promise<VerificationOperationResult>;
+    /**
+     * Redeems an emailed link token. The capability IS the token, so there is no principal; every
+     * failure — malformed, unknown, expired, used, voided — is the same result so the response cannot
+     * be used to learn anything about a session.
+     */
+    RedeemLink(token: string, caller: Extract<VerificationCaller, {
+        Kind: 'link';
+    }>): Promise<VerificationOperationResult>;
+    /**
+     * Reads the session's verification state. This is the **durable** counterpart of the
+     * `identity.verified` event: a subscriber that was disconnected when the event fired recovers by
+     * asking here.
+     */
+    GetStatus(input: {
+        AgentSessionID: string;
+    }, caller: PrincipalCaller): Promise<VerificationOperationResult>;
+    /** The policy and limit refusals of a request, in order; null when the request may proceed. */
+    private checkRequestRefusals;
+    /** Applies the per-IP, per-domain and per-address send limits; null when all admit the send. */
+    private checkSendRateLimits;
+    /** Stores the pending verification, emails it, and rolls the store back if the email cannot be sent. */
+    private issueAndSend;
+    /** Maps a failed/short-circuited store into a result; null when the pending verification was stored. */
+    private requestStoreRefusal;
+    /** Removes the pending verification (and the send it counted) if it is still the one we stored. */
+    private rollbackPending;
+    /**
+     * Shared by the code and link paths: re-read the session, decide the redemption on its CURRENT
+     * state, persist the resulting state (and the extended deadline on success), and on success
+     * publish the event and write the audit entry.
+     */
+    private redeem;
+    /** Success path: surface persistence failure, otherwise publish + audit and build the result. */
+    private completeVerification;
+    /** Maps a rejected redemption to a result (uniform for the link path). */
+    private refusalResult;
+    /**
+     * Loads the session as the caller and applies {@link AuthorizeSessionAccess}. Not-found and
+     * not-yours are the same result so a caller cannot enumerate other people's session ids; the real
+     * reason is logged server-side.
+     */
+    private authorize;
+    /** Serialises operations on one session within this process (see the module header). */
+    private withSessionLock;
+}
+//# sourceMappingURL=verificationWorkflow.d.ts.map

package/dist/realtimeSessions/verificationWorkflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verificationWorkflow.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/verificationWorkflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAuB,KAAK,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAElG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAGjF,OAAO,EAKH,KAAK,0BAA0B,EAElC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAWH,KAAK,gBAAgB,EACxB,MAAM,uBAAuB,CAAC;AAK/B,6GAA6G;AAC7G,MAAM,MAAM,kBAAkB,GACxB;IACI,IAAI,EAAE,WAAW,CAAC;IAClB,2GAA2G;IAC3G,WAAW,EAAE,QAAQ,CAAC;IACtB,mCAAmC;IACnC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC;AAEjF,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IACrC,yCAAyC;IACzC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,qGAAqG;AACrG,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,KAAK;IAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE3G,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACnC,yFAAyF;IACzF,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACjC,kGAAkG;IAClG,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,cAAc,EAAE,0BAA0B,CAAC;IAC3C,6FAA6F;IAC7F,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,qDAAqD;IACrD,UAAU,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,sBAAsB,EAAE,MAAM,CAAC;KAClC,CAAC;CACL;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAC9B,WAAW,IAAI,oBAAoB,CAAC;IACpC,8BAA8B;IAC9B,GAAG,IAAI,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACjG,2GAA2G;IAC3G,mBAAmB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxI,qEAAqE;IACrE,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,oEAAoE;IACpE,eAAe,CACX,OAAO,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EACjF,OAAO,EAAE,4BAA4B,GACtC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,+CAA+C;IAC/C,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAID,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAC3B,0BAA0B,GAC1B,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,oBAAoB,GACpB,cAAc,GACd,mBAAmB,GACnB,yBAAyB,GACzB,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,cAAc,GACd,gBAAgB,CAAC;AAEvB,8BAA8B;AAC9B,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1E,0CAA0C;AAC1C,MAAM,WAAW,2BAA2B;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,6GAA6G;IAC7G,iBAAiB,EAAE,qBAAqB,CAAC;IACzC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAoCD;;GAEG;AACH,qBAAa,mCAAmC;IAOhC,OAAO,CAAC,QAAQ,CAAC,KAAK;IANlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE7B,KAAK,EAAE,iBAAiB;IAQrD,0CAA0C;IAC1C,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;;;;OAKG;IACU,mBAAmB,CAC5B,KAAK,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC9D,MAAM,EAAE,eAAe,GACxB,OAAO,CAAC,2BAA2B,CAAC;IA4BvC;;;OAGG;IACU,UAAU,CACnB,KAAK,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAC/C,MAAM,EAAE,eAAe,GACxB,OAAO,CAAC,2BAA2B,CAAC;IA4BvC;;;;OAIG;IACU,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,kBAAkB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAanI;;;;OAIG;IACU,SAAS,CAAC,KAAK,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,2BAA2B,CAAC;IA0BxH,+FAA+F;IAC/F,OAAO,CAAC,oBAAoB;IAoB5B,gGAAgG;IAChG,OAAO,CAAC,mBAAmB;IAgB3B,wGAAwG;YAC1F,YAAY;IAmD1B,wGAAwG;IACxG,OAAO,CAAC,mBAAmB;IAe3B,mGAAmG;YACrF,eAAe;IAgB7B;;;;OAIG;YACW,MAAM;IAuCpB,iGAAiG;YACnF,oBAAoB;IA2ClC,0EAA0E;IAC1E,OAAO,CAAC,aAAa;IAwBrB;;;;OAIG;YACW,SAAS;IA2BvB,wFAAwF;YAC1E,eAAe;CAmBhC"}