@bymax-one/nest-notification 1.4.7 → 1.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -319,6 +319,27 @@ interface IOtpStorage {
319
319
  update(tenantId: string, recipient: string, purpose: string, entry: OtpEntry): Promise<void>;
320
320
  /** Removes the OTP entry. Idempotent. */
321
321
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
322
+ /**
323
+ * Atomic compare-and-delete: removes the entry only when the value it still stores equals
324
+ * `expectedStored`, and reports whether this call removed it. Of N concurrent calls for one
325
+ * stored value, exactly one returns `true`.
326
+ *
327
+ * `expectedStored` is the exact STORED `code` the service read from the entry (the keyed
328
+ * digest when `otp.codeSecret` is set), never the guess a user typed: no plaintext guess
329
+ * reaches the storage. The service has already compared the guess in constant time; this
330
+ * only makes the one-time property hold when several verifications of the right code run
331
+ * at once. A code regenerated in between stores a different value, so it is left alone and
332
+ * the call returns `false`.
333
+ *
334
+ * Required when `otp.consumeOnVerify` is `true`: the service refuses to start without it,
335
+ * so a storage that cannot do this atomically never silently keeps the race.
336
+ *
337
+ * MUST be atomic.
338
+ *
339
+ * @param expectedStored - The stored code value the caller read.
340
+ * @returns `true` when this call deleted the entry, `false` when it was absent or changed.
341
+ */
342
+ deleteIfCode?(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
322
343
  /**
323
344
  * Atomic cooldown acquire for `(tenant, recipient, purpose)`. Sets the cooldown
324
345
  * key only if it does not already exist (Redis: `SET NX EX`). Returns `true`
@@ -543,6 +564,12 @@ interface EmailChannelOptions {
543
564
  * Default: `10_485_760` (10 MiB).
544
565
  */
545
566
  maxAttachmentBytes?: number;
567
+ /**
568
+ * Maximum recipients of one message: `to`, `cc` and `bcc` together, counted after splitting
569
+ * each string on `,` and `;` the way the transport does. `EmailService` refuses a larger
570
+ * message with `EMAIL_INVALID_RECIPIENT` before the provider is called. Default: `50`.
571
+ */
572
+ maxRecipients?: number;
546
573
  }
547
574
  /** OTP channel configuration. Omitted when the OTP channel is not used. */
548
575
  interface OtpChannelOptions {
@@ -758,6 +785,7 @@ interface ResolvedEmailOptions {
758
785
  value: string;
759
786
  }>;
760
787
  maxAttachmentBytes: number;
788
+ maxRecipients: number;
761
789
  }
762
790
  /** Resolved OTP section — present only when the OTP channel is configured. */
763
791
  interface ResolvedOtpOptions {
@@ -902,6 +930,7 @@ declare class EmailService {
902
930
  * @returns The provider's message id.
903
931
  * @throws NotificationException `EMAIL_PROVIDER_NOT_CONFIGURED`, `INVALID_SCOPE_IDENTIFIER`
904
932
  * (a blank tenant or one with a control character), `EMAIL_ATTACHMENTS_TOO_LARGE`,
933
+ * `EMAIL_INVALID_RECIPIENT` (more recipients than `maxRecipients`),
905
934
  * `EMAIL_SEND_FAILED`, or `AUDIT_LOG_FAILED` (only when `audit.swallowErrors` is `false`).
906
935
  */
907
936
  send(input: EmailSendInput): Promise<{
@@ -939,6 +968,11 @@ declare class EmailService {
939
968
  }>;
940
969
  /** Returns the resolved email options or throws when the channel is not configured. */
941
970
  private requireEmailOptions;
971
+ /**
972
+ * Throws `EMAIL_INVALID_RECIPIENT` when to, cc and bcc together address more mailboxes than
973
+ * the channel allows. The refusal names the limit and never an address.
974
+ */
975
+ private guardRecipientCount;
942
976
  /** Throws `EMAIL_ATTACHMENTS_TOO_LARGE` when the attachments exceed the byte budget. */
943
977
  private guardAttachmentSize;
944
978
  /** Applies channel defaults and concatenates default + caller tags. */
@@ -1048,18 +1082,19 @@ interface OtpStatusResult {
1048
1082
  /** OTP generation, verification, consumption, and status. */
1049
1083
  declare class OtpService implements OnModuleInit {
1050
1084
  private readonly options;
1051
- private readonly storage;
1052
1085
  private readonly auditLog;
1053
1086
  private readonly emailService?;
1054
1087
  private readonly logger;
1055
1088
  private warnedFailuresNotCarried;
1089
+ /** The store every operation goes through: an outage of it answers 503. */
1090
+ private readonly storage;
1056
1091
  /**
1057
1092
  * @param options - The resolved, frozen module options.
1058
1093
  * @param storage - The configured OTP storage.
1059
1094
  * @param auditLog - The audit-log repository (no-op when none configured).
1060
1095
  * @param emailService - The email service; present only when the email channel is configured.
1061
1096
  */
1062
- constructor(options: ResolvedNotificationOptions, storage: IOtpStorage, auditLog: INotificationLogRepository, emailService?: EmailService | undefined);
1097
+ constructor(options: ResolvedNotificationOptions, store: IOtpStorage, auditLog: INotificationLogRepository, emailService?: EmailService | undefined);
1063
1098
  /**
1064
1099
  * Whether the OTP channel is configured and its storage is ready.
1065
1100
  *
@@ -1155,12 +1190,34 @@ declare class OtpService implements OnModuleInit {
1155
1190
  * @throws NotificationException `OTP_MANUAL_DELIVERY_UNAVAILABLE`.
1156
1191
  */
1157
1192
  private assertDeliverable;
1193
+ /**
1194
+ * Refuses, before any state exists, an email delivery to a string that is not exactly one
1195
+ * mailbox: the code goes to every address the string names. A manual delivery is the
1196
+ * caller's own, so a phone number or a device id stays a valid recipient.
1197
+ *
1198
+ * @throws NotificationException `EMAIL_INVALID_RECIPIENT`.
1199
+ */
1200
+ private assertMailbox;
1158
1201
  /** Delivers the code by email when requested; throws on failure (release is handled by the caller). */
1159
1202
  private deliverOtp;
1160
1203
  /** Clears the cooldown and deletes the OTP — used to undo a failed delivery. */
1161
1204
  private releaseOtp;
1162
1205
  /** Builds the OTP email payload with the auto-injected `{ code, expiresInMinutes, purpose }`. */
1163
1206
  private buildOtpEmail;
1207
+ /** Audits and returns the `not_found` verdict: no live code, or it was consumed by another call. */
1208
+ private rejectNotFound;
1209
+ /** Audits and returns the `max_attempts` verdict. */
1210
+ private rejectMaxAttempts;
1211
+ /**
1212
+ * With `consumeOnVerify`, removes the entry atomically while it still stores the value this
1213
+ * verification read, and reports whether another verification got there first. The one-time
1214
+ * property is decided here, not by a delete that follows: of N concurrent verifications of the
1215
+ * right code exactly one removes the entry. `storedCode` is the STORED value (the digest when
1216
+ * keyed), never the guess.
1217
+ *
1218
+ * @returns `true` when a concurrent verification consumed the code or it was regenerated.
1219
+ */
1220
+ private lostConsume;
1164
1221
  /** Finalizes a correct verification: consume-and-clear, or mark `validated`. */
1165
1222
  private finalizeVerifySuccess;
1166
1223
  /**
@@ -1670,6 +1727,13 @@ declare class DefaultTemplateRenderer implements IEmailTemplateRenderer {
1670
1727
  interface ResendEmailProviderOptions {
1671
1728
  /** Resend API key. When absent the provider is not configured and `send()` throws. */
1672
1729
  apiKey?: string;
1730
+ /**
1731
+ * Longest one `send()` may take, in milliseconds, from the request to the end of the response
1732
+ * body. An integer from `1` to `2147483647`; default `15000`. A send that exceeds it fails with
1733
+ * `EMAIL_SEND_FAILED`. The message may still have been accepted by Resend: only the answer is
1734
+ * missing, so the failure does not say the message was not sent.
1735
+ */
1736
+ timeoutMs?: number;
1673
1737
  }
1674
1738
  /**
1675
1739
  * Reference {@link IEmailProvider} on top of Resend.
@@ -1851,6 +1915,15 @@ interface SmtpEmailProviderOptions {
1851
1915
  greetingTimeout?: number;
1852
1916
  /** Idle-socket timeout in milliseconds. Defaults to `20000`. */
1853
1917
  socketTimeout?: number;
1918
+ /**
1919
+ * Longest one `send()` may take, in milliseconds, from the call to the transport's answer. An
1920
+ * integer from `1` to `2147483647`; default `60000`. The three timeouts above bound a phase or an
1921
+ * idle socket, so a relay that keeps trickling bytes could hold a send past all of them; this
1922
+ * bounds the whole call. A send that exceeds it fails with `EMAIL_SEND_FAILED` (HTTP 503). The
1923
+ * relay may still accept the message: only the answer is missing, so the failure does not say the
1924
+ * message was not sent. The connection is left open: `socketTimeout` reaps it once the relay goes idle; a relay that keeps sending holds it until the relay ends the connection or the process exits.
1925
+ */
1926
+ sendTimeoutMs?: number;
1854
1927
  }
1855
1928
  /**
1856
1929
  * Reference {@link IEmailProvider} speaking SMTP.
@@ -1885,6 +1958,7 @@ declare class SmtpEmailProvider implements IEmailProvider {
1885
1958
  /**
1886
1959
  * @param options - Adapter options; `host` is required to actually send, and
1887
1960
  * `credentials` must be complete whenever supplied at all.
1961
+ * @throws Error When `sendTimeoutMs` is not an integer from `1` to `2147483647`.
1888
1962
  */
1889
1963
  constructor(options?: SmtpEmailProviderOptions);
1890
1964
  /**
@@ -1924,6 +1998,19 @@ declare class SmtpEmailProvider implements IEmailProvider {
1924
1998
  * @throws Error When the transport rejects the message.
1925
1999
  */
1926
2000
  private dispatch;
2001
+ /** Builds the error this adapter throws for a transport failure, logging the scrubbed reason. */
2002
+ private failure;
2003
+ /**
2004
+ * The failure of a send whose body carries a credential: none of the relay's own words may reach a
2005
+ * log line or a thrown message — redaction removes the shapes it predicts and a re-encoded echo
2006
+ * defeats it. Only the reply codes a fixed grammar can express are published, and they are the
2007
+ * same whatever the body held.
2008
+ *
2009
+ * Filtered HERE, not only in EmailService: this adapter is public, and its own warn line would
2010
+ * otherwise write a code that contains the caller's declared secret — an OTP of `55` sits inside a
2011
+ * `550` reply.
2012
+ */
2013
+ private withheldFailure;
1927
2014
  /**
1928
2015
  * Removes the credentials, the caller's declared secrets and any echoed body
1929
2016
  * excerpt from a transport error's text — the credential scrub alone cannot
@@ -1941,7 +2028,15 @@ declare class SmtpEmailProvider implements IEmailProvider {
1941
2028
  * @returns The message with every known-secret value replaced.
1942
2029
  */
1943
2030
  private scrubTransportError;
1944
- /** The configured credentials that qualify as secret material, if any. */
2031
+ /**
2032
+ * The configured credentials that qualify as secret material, if any, and the base64 forms the
2033
+ * AUTH exchange carries them in: the user and the password as AUTH LOGIN sends them, and the
2034
+ * AUTH PLAIN token, which has an empty authorization identity. A relay that quotes the exchange
2035
+ * shows those, and a literal match cannot see them. The token is its own value: base64 groups
2036
+ * three bytes, so the token's bytes usually sit at another alignment than the user's or the
2037
+ * password's, and then neither of their encodings appears inside it. It cannot be derived from
2038
+ * them.
2039
+ */
1945
2040
  private credentialValues;
1946
2041
  /**
1947
2042
  * Replaces every occurrence of either configured credential with a placeholder.
@@ -2202,6 +2297,17 @@ declare class InMemoryOtpStorage implements IOtpStorage {
2202
2297
  * @param purpose - OTP purpose.
2203
2298
  */
2204
2299
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
2300
+ /**
2301
+ * Deletes the entry only when it still stores `expectedStored`. Synchronous inside the
2302
+ * method, so of N concurrent callers exactly one sees the value and removes it.
2303
+ *
2304
+ * @param tenantId - Tenant isolation scope.
2305
+ * @param recipient - Pre-normalized recipient identifier.
2306
+ * @param purpose - OTP purpose.
2307
+ * @param expectedStored - The stored code value the caller read.
2308
+ * @returns `true` when this call removed the entry.
2309
+ */
2310
+ deleteIfCode(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
2205
2311
  /**
2206
2312
  * Acquires the cooldown lock only when one is not already active.
2207
2313
  *
@@ -2312,6 +2418,11 @@ declare class RedisOtpStorage implements IOtpStorage {
2312
2418
  * `PTTL` is read inside the script to preserve the original expiry on rewrite.
2313
2419
  */
2314
2420
  private static readonly CONSUME_ATTEMPT_LUA;
2421
+ /**
2422
+ * Atomic compare-and-delete: reads the entry, and deletes it only when its stored `code` equals
2423
+ * the value the caller read, so of N concurrent verifications exactly one removes it.
2424
+ */
2425
+ private static readonly DELETE_IF_CODE_LUA;
2315
2426
  /**
2316
2427
  * Atomic failure-counter primitive: one `INCR` and the lifetime refresh in a single script, so
2317
2428
  * concurrent failures each receive a distinct count and the counter never outlives its window
@@ -2368,6 +2479,16 @@ declare class RedisOtpStorage implements IOtpStorage {
2368
2479
  * @param purpose - OTP purpose.
2369
2480
  */
2370
2481
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
2482
+ /**
2483
+ * Deletes the entry only when it still stores `expectedStored`, in one script.
2484
+ *
2485
+ * @param tenantId - Tenant isolation scope.
2486
+ * @param recipient - Pre-normalized recipient identifier.
2487
+ * @param purpose - OTP purpose.
2488
+ * @param expectedStored - The stored code value the caller read (the digest, when keyed).
2489
+ * @returns `true` when this call removed the entry.
2490
+ */
2491
+ deleteIfCode(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
2371
2492
  /**
2372
2493
  * Atomic cooldown acquire with `SET … NX EX` — only the first concurrent caller wins.
2373
2494
  *
@@ -2599,6 +2720,7 @@ declare const NOTIFICATION_ERROR_CODES: {
2599
2720
  readonly OTP_EXPIRED: "notification.otp_expired";
2600
2721
  readonly OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded";
2601
2722
  readonly OTP_INVALID_CODE: "notification.otp_invalid_code";
2723
+ readonly OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable";
2602
2724
  readonly OTP_INVALID_LENGTH: "notification.otp_invalid_length";
2603
2725
  readonly SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured";
2604
2726
  readonly SMS_SEND_FAILED: "notification.sms_send_failed";
@@ -2656,7 +2778,7 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2656
2778
  readonly status: HttpStatus.PAYLOAD_TOO_LARGE;
2657
2779
  readonly message: "Email attachments exceed size limit";
2658
2780
  };
2659
- /** Reserved: `to` is not validated, so the library never throws this code. */
2781
+ /** Raised for an OTP recipient that is not one mailbox, and for a message over `maxRecipients`. */
2660
2782
  readonly EMAIL_INVALID_RECIPIENT: {
2661
2783
  readonly code: "notification.email_invalid_recipient";
2662
2784
  readonly status: HttpStatus.BAD_REQUEST;
@@ -2715,6 +2837,12 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2715
2837
  readonly status: HttpStatus.TOO_MANY_REQUESTS;
2716
2838
  readonly message: "Maximum OTP attempts exceeded";
2717
2839
  };
2840
+ /** Raised when the OTP store cannot be reached, is closed, or timed out: the caller may retry. */
2841
+ readonly OTP_STORAGE_UNAVAILABLE: {
2842
+ readonly code: "notification.otp_storage_unavailable";
2843
+ readonly status: HttpStatus.SERVICE_UNAVAILABLE;
2844
+ readonly message: "OTP storage unavailable";
2845
+ };
2718
2846
  /** Reserved: `verify()` returns `{ valid: false, reason: 'invalid_code' }` instead of throwing. */
2719
2847
  readonly OTP_INVALID_CODE: {
2720
2848
  readonly code: "notification.otp_invalid_code";
@@ -319,6 +319,27 @@ interface IOtpStorage {
319
319
  update(tenantId: string, recipient: string, purpose: string, entry: OtpEntry): Promise<void>;
320
320
  /** Removes the OTP entry. Idempotent. */
321
321
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
322
+ /**
323
+ * Atomic compare-and-delete: removes the entry only when the value it still stores equals
324
+ * `expectedStored`, and reports whether this call removed it. Of N concurrent calls for one
325
+ * stored value, exactly one returns `true`.
326
+ *
327
+ * `expectedStored` is the exact STORED `code` the service read from the entry (the keyed
328
+ * digest when `otp.codeSecret` is set), never the guess a user typed: no plaintext guess
329
+ * reaches the storage. The service has already compared the guess in constant time; this
330
+ * only makes the one-time property hold when several verifications of the right code run
331
+ * at once. A code regenerated in between stores a different value, so it is left alone and
332
+ * the call returns `false`.
333
+ *
334
+ * Required when `otp.consumeOnVerify` is `true`: the service refuses to start without it,
335
+ * so a storage that cannot do this atomically never silently keeps the race.
336
+ *
337
+ * MUST be atomic.
338
+ *
339
+ * @param expectedStored - The stored code value the caller read.
340
+ * @returns `true` when this call deleted the entry, `false` when it was absent or changed.
341
+ */
342
+ deleteIfCode?(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
322
343
  /**
323
344
  * Atomic cooldown acquire for `(tenant, recipient, purpose)`. Sets the cooldown
324
345
  * key only if it does not already exist (Redis: `SET NX EX`). Returns `true`
@@ -543,6 +564,12 @@ interface EmailChannelOptions {
543
564
  * Default: `10_485_760` (10 MiB).
544
565
  */
545
566
  maxAttachmentBytes?: number;
567
+ /**
568
+ * Maximum recipients of one message: `to`, `cc` and `bcc` together, counted after splitting
569
+ * each string on `,` and `;` the way the transport does. `EmailService` refuses a larger
570
+ * message with `EMAIL_INVALID_RECIPIENT` before the provider is called. Default: `50`.
571
+ */
572
+ maxRecipients?: number;
546
573
  }
547
574
  /** OTP channel configuration. Omitted when the OTP channel is not used. */
548
575
  interface OtpChannelOptions {
@@ -758,6 +785,7 @@ interface ResolvedEmailOptions {
758
785
  value: string;
759
786
  }>;
760
787
  maxAttachmentBytes: number;
788
+ maxRecipients: number;
761
789
  }
762
790
  /** Resolved OTP section — present only when the OTP channel is configured. */
763
791
  interface ResolvedOtpOptions {
@@ -902,6 +930,7 @@ declare class EmailService {
902
930
  * @returns The provider's message id.
903
931
  * @throws NotificationException `EMAIL_PROVIDER_NOT_CONFIGURED`, `INVALID_SCOPE_IDENTIFIER`
904
932
  * (a blank tenant or one with a control character), `EMAIL_ATTACHMENTS_TOO_LARGE`,
933
+ * `EMAIL_INVALID_RECIPIENT` (more recipients than `maxRecipients`),
905
934
  * `EMAIL_SEND_FAILED`, or `AUDIT_LOG_FAILED` (only when `audit.swallowErrors` is `false`).
906
935
  */
907
936
  send(input: EmailSendInput): Promise<{
@@ -939,6 +968,11 @@ declare class EmailService {
939
968
  }>;
940
969
  /** Returns the resolved email options or throws when the channel is not configured. */
941
970
  private requireEmailOptions;
971
+ /**
972
+ * Throws `EMAIL_INVALID_RECIPIENT` when to, cc and bcc together address more mailboxes than
973
+ * the channel allows. The refusal names the limit and never an address.
974
+ */
975
+ private guardRecipientCount;
942
976
  /** Throws `EMAIL_ATTACHMENTS_TOO_LARGE` when the attachments exceed the byte budget. */
943
977
  private guardAttachmentSize;
944
978
  /** Applies channel defaults and concatenates default + caller tags. */
@@ -1048,18 +1082,19 @@ interface OtpStatusResult {
1048
1082
  /** OTP generation, verification, consumption, and status. */
1049
1083
  declare class OtpService implements OnModuleInit {
1050
1084
  private readonly options;
1051
- private readonly storage;
1052
1085
  private readonly auditLog;
1053
1086
  private readonly emailService?;
1054
1087
  private readonly logger;
1055
1088
  private warnedFailuresNotCarried;
1089
+ /** The store every operation goes through: an outage of it answers 503. */
1090
+ private readonly storage;
1056
1091
  /**
1057
1092
  * @param options - The resolved, frozen module options.
1058
1093
  * @param storage - The configured OTP storage.
1059
1094
  * @param auditLog - The audit-log repository (no-op when none configured).
1060
1095
  * @param emailService - The email service; present only when the email channel is configured.
1061
1096
  */
1062
- constructor(options: ResolvedNotificationOptions, storage: IOtpStorage, auditLog: INotificationLogRepository, emailService?: EmailService | undefined);
1097
+ constructor(options: ResolvedNotificationOptions, store: IOtpStorage, auditLog: INotificationLogRepository, emailService?: EmailService | undefined);
1063
1098
  /**
1064
1099
  * Whether the OTP channel is configured and its storage is ready.
1065
1100
  *
@@ -1155,12 +1190,34 @@ declare class OtpService implements OnModuleInit {
1155
1190
  * @throws NotificationException `OTP_MANUAL_DELIVERY_UNAVAILABLE`.
1156
1191
  */
1157
1192
  private assertDeliverable;
1193
+ /**
1194
+ * Refuses, before any state exists, an email delivery to a string that is not exactly one
1195
+ * mailbox: the code goes to every address the string names. A manual delivery is the
1196
+ * caller's own, so a phone number or a device id stays a valid recipient.
1197
+ *
1198
+ * @throws NotificationException `EMAIL_INVALID_RECIPIENT`.
1199
+ */
1200
+ private assertMailbox;
1158
1201
  /** Delivers the code by email when requested; throws on failure (release is handled by the caller). */
1159
1202
  private deliverOtp;
1160
1203
  /** Clears the cooldown and deletes the OTP — used to undo a failed delivery. */
1161
1204
  private releaseOtp;
1162
1205
  /** Builds the OTP email payload with the auto-injected `{ code, expiresInMinutes, purpose }`. */
1163
1206
  private buildOtpEmail;
1207
+ /** Audits and returns the `not_found` verdict: no live code, or it was consumed by another call. */
1208
+ private rejectNotFound;
1209
+ /** Audits and returns the `max_attempts` verdict. */
1210
+ private rejectMaxAttempts;
1211
+ /**
1212
+ * With `consumeOnVerify`, removes the entry atomically while it still stores the value this
1213
+ * verification read, and reports whether another verification got there first. The one-time
1214
+ * property is decided here, not by a delete that follows: of N concurrent verifications of the
1215
+ * right code exactly one removes the entry. `storedCode` is the STORED value (the digest when
1216
+ * keyed), never the guess.
1217
+ *
1218
+ * @returns `true` when a concurrent verification consumed the code or it was regenerated.
1219
+ */
1220
+ private lostConsume;
1164
1221
  /** Finalizes a correct verification: consume-and-clear, or mark `validated`. */
1165
1222
  private finalizeVerifySuccess;
1166
1223
  /**
@@ -1670,6 +1727,13 @@ declare class DefaultTemplateRenderer implements IEmailTemplateRenderer {
1670
1727
  interface ResendEmailProviderOptions {
1671
1728
  /** Resend API key. When absent the provider is not configured and `send()` throws. */
1672
1729
  apiKey?: string;
1730
+ /**
1731
+ * Longest one `send()` may take, in milliseconds, from the request to the end of the response
1732
+ * body. An integer from `1` to `2147483647`; default `15000`. A send that exceeds it fails with
1733
+ * `EMAIL_SEND_FAILED`. The message may still have been accepted by Resend: only the answer is
1734
+ * missing, so the failure does not say the message was not sent.
1735
+ */
1736
+ timeoutMs?: number;
1673
1737
  }
1674
1738
  /**
1675
1739
  * Reference {@link IEmailProvider} on top of Resend.
@@ -1851,6 +1915,15 @@ interface SmtpEmailProviderOptions {
1851
1915
  greetingTimeout?: number;
1852
1916
  /** Idle-socket timeout in milliseconds. Defaults to `20000`. */
1853
1917
  socketTimeout?: number;
1918
+ /**
1919
+ * Longest one `send()` may take, in milliseconds, from the call to the transport's answer. An
1920
+ * integer from `1` to `2147483647`; default `60000`. The three timeouts above bound a phase or an
1921
+ * idle socket, so a relay that keeps trickling bytes could hold a send past all of them; this
1922
+ * bounds the whole call. A send that exceeds it fails with `EMAIL_SEND_FAILED` (HTTP 503). The
1923
+ * relay may still accept the message: only the answer is missing, so the failure does not say the
1924
+ * message was not sent. The connection is left open: `socketTimeout` reaps it once the relay goes idle; a relay that keeps sending holds it until the relay ends the connection or the process exits.
1925
+ */
1926
+ sendTimeoutMs?: number;
1854
1927
  }
1855
1928
  /**
1856
1929
  * Reference {@link IEmailProvider} speaking SMTP.
@@ -1885,6 +1958,7 @@ declare class SmtpEmailProvider implements IEmailProvider {
1885
1958
  /**
1886
1959
  * @param options - Adapter options; `host` is required to actually send, and
1887
1960
  * `credentials` must be complete whenever supplied at all.
1961
+ * @throws Error When `sendTimeoutMs` is not an integer from `1` to `2147483647`.
1888
1962
  */
1889
1963
  constructor(options?: SmtpEmailProviderOptions);
1890
1964
  /**
@@ -1924,6 +1998,19 @@ declare class SmtpEmailProvider implements IEmailProvider {
1924
1998
  * @throws Error When the transport rejects the message.
1925
1999
  */
1926
2000
  private dispatch;
2001
+ /** Builds the error this adapter throws for a transport failure, logging the scrubbed reason. */
2002
+ private failure;
2003
+ /**
2004
+ * The failure of a send whose body carries a credential: none of the relay's own words may reach a
2005
+ * log line or a thrown message — redaction removes the shapes it predicts and a re-encoded echo
2006
+ * defeats it. Only the reply codes a fixed grammar can express are published, and they are the
2007
+ * same whatever the body held.
2008
+ *
2009
+ * Filtered HERE, not only in EmailService: this adapter is public, and its own warn line would
2010
+ * otherwise write a code that contains the caller's declared secret — an OTP of `55` sits inside a
2011
+ * `550` reply.
2012
+ */
2013
+ private withheldFailure;
1927
2014
  /**
1928
2015
  * Removes the credentials, the caller's declared secrets and any echoed body
1929
2016
  * excerpt from a transport error's text — the credential scrub alone cannot
@@ -1941,7 +2028,15 @@ declare class SmtpEmailProvider implements IEmailProvider {
1941
2028
  * @returns The message with every known-secret value replaced.
1942
2029
  */
1943
2030
  private scrubTransportError;
1944
- /** The configured credentials that qualify as secret material, if any. */
2031
+ /**
2032
+ * The configured credentials that qualify as secret material, if any, and the base64 forms the
2033
+ * AUTH exchange carries them in: the user and the password as AUTH LOGIN sends them, and the
2034
+ * AUTH PLAIN token, which has an empty authorization identity. A relay that quotes the exchange
2035
+ * shows those, and a literal match cannot see them. The token is its own value: base64 groups
2036
+ * three bytes, so the token's bytes usually sit at another alignment than the user's or the
2037
+ * password's, and then neither of their encodings appears inside it. It cannot be derived from
2038
+ * them.
2039
+ */
1945
2040
  private credentialValues;
1946
2041
  /**
1947
2042
  * Replaces every occurrence of either configured credential with a placeholder.
@@ -2202,6 +2297,17 @@ declare class InMemoryOtpStorage implements IOtpStorage {
2202
2297
  * @param purpose - OTP purpose.
2203
2298
  */
2204
2299
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
2300
+ /**
2301
+ * Deletes the entry only when it still stores `expectedStored`. Synchronous inside the
2302
+ * method, so of N concurrent callers exactly one sees the value and removes it.
2303
+ *
2304
+ * @param tenantId - Tenant isolation scope.
2305
+ * @param recipient - Pre-normalized recipient identifier.
2306
+ * @param purpose - OTP purpose.
2307
+ * @param expectedStored - The stored code value the caller read.
2308
+ * @returns `true` when this call removed the entry.
2309
+ */
2310
+ deleteIfCode(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
2205
2311
  /**
2206
2312
  * Acquires the cooldown lock only when one is not already active.
2207
2313
  *
@@ -2312,6 +2418,11 @@ declare class RedisOtpStorage implements IOtpStorage {
2312
2418
  * `PTTL` is read inside the script to preserve the original expiry on rewrite.
2313
2419
  */
2314
2420
  private static readonly CONSUME_ATTEMPT_LUA;
2421
+ /**
2422
+ * Atomic compare-and-delete: reads the entry, and deletes it only when its stored `code` equals
2423
+ * the value the caller read, so of N concurrent verifications exactly one removes it.
2424
+ */
2425
+ private static readonly DELETE_IF_CODE_LUA;
2315
2426
  /**
2316
2427
  * Atomic failure-counter primitive: one `INCR` and the lifetime refresh in a single script, so
2317
2428
  * concurrent failures each receive a distinct count and the counter never outlives its window
@@ -2368,6 +2479,16 @@ declare class RedisOtpStorage implements IOtpStorage {
2368
2479
  * @param purpose - OTP purpose.
2369
2480
  */
2370
2481
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
2482
+ /**
2483
+ * Deletes the entry only when it still stores `expectedStored`, in one script.
2484
+ *
2485
+ * @param tenantId - Tenant isolation scope.
2486
+ * @param recipient - Pre-normalized recipient identifier.
2487
+ * @param purpose - OTP purpose.
2488
+ * @param expectedStored - The stored code value the caller read (the digest, when keyed).
2489
+ * @returns `true` when this call removed the entry.
2490
+ */
2491
+ deleteIfCode(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
2371
2492
  /**
2372
2493
  * Atomic cooldown acquire with `SET … NX EX` — only the first concurrent caller wins.
2373
2494
  *
@@ -2599,6 +2720,7 @@ declare const NOTIFICATION_ERROR_CODES: {
2599
2720
  readonly OTP_EXPIRED: "notification.otp_expired";
2600
2721
  readonly OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded";
2601
2722
  readonly OTP_INVALID_CODE: "notification.otp_invalid_code";
2723
+ readonly OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable";
2602
2724
  readonly OTP_INVALID_LENGTH: "notification.otp_invalid_length";
2603
2725
  readonly SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured";
2604
2726
  readonly SMS_SEND_FAILED: "notification.sms_send_failed";
@@ -2656,7 +2778,7 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2656
2778
  readonly status: HttpStatus.PAYLOAD_TOO_LARGE;
2657
2779
  readonly message: "Email attachments exceed size limit";
2658
2780
  };
2659
- /** Reserved: `to` is not validated, so the library never throws this code. */
2781
+ /** Raised for an OTP recipient that is not one mailbox, and for a message over `maxRecipients`. */
2660
2782
  readonly EMAIL_INVALID_RECIPIENT: {
2661
2783
  readonly code: "notification.email_invalid_recipient";
2662
2784
  readonly status: HttpStatus.BAD_REQUEST;
@@ -2715,6 +2837,12 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2715
2837
  readonly status: HttpStatus.TOO_MANY_REQUESTS;
2716
2838
  readonly message: "Maximum OTP attempts exceeded";
2717
2839
  };
2840
+ /** Raised when the OTP store cannot be reached, is closed, or timed out: the caller may retry. */
2841
+ readonly OTP_STORAGE_UNAVAILABLE: {
2842
+ readonly code: "notification.otp_storage_unavailable";
2843
+ readonly status: HttpStatus.SERVICE_UNAVAILABLE;
2844
+ readonly message: "OTP storage unavailable";
2845
+ };
2718
2846
  /** Reserved: `verify()` returns `{ valid: false, reason: 'invalid_code' }` instead of throwing. */
2719
2847
  readonly OTP_INVALID_CODE: {
2720
2848
  readonly code: "notification.otp_invalid_code";