@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.
- package/CHANGELOG.md +140 -3
- package/README.md +185 -287
- package/dist/server/index.cjs +594 -112
- package/dist/server/index.d.cts +132 -4
- package/dist/server/index.d.ts +132 -4
- package/dist/server/index.mjs +594 -112
- package/dist/shared/index.cjs +1 -0
- package/dist/shared/index.d.cts +1 -0
- package/dist/shared/index.d.ts +1 -0
- package/dist/shared/index.mjs +1 -0
- package/dist/testing/index.cjs +76 -1
- package/dist/testing/index.d.cts +21 -0
- package/dist/testing/index.d.ts +21 -0
- package/dist/testing/index.mjs +76 -1
- package/package.json +3 -2
package/dist/server/index.d.cts
CHANGED
|
@@ -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,
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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";
|
package/dist/server/index.d.ts
CHANGED
|
@@ -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,
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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";
|