@bymax-one/nest-notification 1.4.0 → 1.4.2
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 +256 -1
- package/README.md +188 -66
- package/dist/react/index.d.cts +2 -1
- package/dist/react/index.d.ts +2 -1
- package/dist/server/index.cjs +401 -60
- package/dist/server/index.d.cts +223 -7
- package/dist/server/index.d.ts +223 -7
- package/dist/server/index.mjs +402 -61
- package/dist/shared/index.cjs +1 -0
- package/dist/shared/index.d.cts +4 -2
- package/dist/shared/index.d.ts +4 -2
- package/dist/shared/index.mjs +1 -0
- package/dist/testing/index.cjs +234 -41
- package/dist/testing/index.d.cts +38 -8
- package/dist/testing/index.d.ts +38 -8
- package/dist/testing/index.mjs +234 -41
- package/package.json +6 -59
package/dist/server/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ModuleMetadata, FactoryProvider, DynamicModule, NestInterceptor, ExecutionContext, CallHandler, HttpStatus, HttpException } from '@nestjs/common';
|
|
1
|
+
import { ModuleMetadata, FactoryProvider, DynamicModule, OnModuleInit, NestInterceptor, ExecutionContext, CallHandler, HttpStatus, HttpException } from '@nestjs/common';
|
|
2
2
|
import { Observable } from 'rxjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
@@ -338,6 +338,28 @@ interface IOtpStorage {
|
|
|
338
338
|
* cancelled flow can restart immediately).
|
|
339
339
|
*/
|
|
340
340
|
clearCooldown(tenantId: string, recipient: string, purpose: string): Promise<void>;
|
|
341
|
+
/**
|
|
342
|
+
* Optional. Verification attempts counted for `(tenant, recipient, purpose)`, or `0`.
|
|
343
|
+
*
|
|
344
|
+
* Together with {@link IOtpStorage.recordFailure} and {@link IOtpStorage.clearFailures} this
|
|
345
|
+
* makes the failed-attempt count outlive a code: NIST SP 800-63B-4 §3.1.3.2 says generating a
|
|
346
|
+
* new authentication secret "SHALL NOT reset the failed authentication count". `OtpService`
|
|
347
|
+
* counts each verification attempt against a live code with `recordFailure` before comparing it and refuses
|
|
348
|
+
* once the number it returns passes the attempt ceiling; this method is the read side of the
|
|
349
|
+
* same counter. A storage that omits the three keeps a fresh budget per code, and a warning at
|
|
350
|
+
* startup names the deviation.
|
|
351
|
+
*/
|
|
352
|
+
getFailures?(tenantId: string, recipient: string, purpose: string): Promise<number>;
|
|
353
|
+
/**
|
|
354
|
+
* Optional. Atomically adds one verification attempt and (re)sets the counter's lifetime to
|
|
355
|
+
* `ttlSeconds`, returning the new count. A counter that is not touched for `ttlSeconds`
|
|
356
|
+
* lapses, which starts the count again from zero.
|
|
357
|
+
*
|
|
358
|
+
* MUST be atomic (Redis: `INCR` and `EXPIRE` in one script).
|
|
359
|
+
*/
|
|
360
|
+
recordFailure?(tenantId: string, recipient: string, purpose: string, ttlSeconds: number): Promise<number>;
|
|
361
|
+
/** Optional. Removes the failure counter. Idempotent. Called on success and on `consume()`. */
|
|
362
|
+
clearFailures?(tenantId: string, recipient: string, purpose: string): Promise<void>;
|
|
341
363
|
/** Whether the storage is configured and ready. Used during module initialization. */
|
|
342
364
|
isConfigured(): boolean;
|
|
343
365
|
/** Storage name (e.g. `'redis'`, `'memory'`, `'dynamodb'`). */
|
|
@@ -483,6 +505,10 @@ interface GlobalOptions {
|
|
|
483
505
|
* Resolves the tenant id from the request. When provided, the module prefers
|
|
484
506
|
* this source over a tenant id passed in the body/argument — preventing tenant
|
|
485
507
|
* spoofing.
|
|
508
|
+
*
|
|
509
|
+
* What it returns must identify a tenant: a value that is not a string, is empty or
|
|
510
|
+
* is whitespace-only is refused by the audit interceptor rather than recorded (see
|
|
511
|
+
* `audit.swallowErrors` for what the caller then sees).
|
|
486
512
|
*/
|
|
487
513
|
tenantIdResolver?: (req: NotificationRequest) => string | Promise<string>;
|
|
488
514
|
}
|
|
@@ -534,6 +560,15 @@ interface OtpChannelOptions {
|
|
|
534
560
|
resendCooldownSeconds?: number;
|
|
535
561
|
/** When `true`, `verify()` consumes (deletes) the OTP on success. Default: `false`. */
|
|
536
562
|
consumeOnVerify?: boolean;
|
|
563
|
+
/**
|
|
564
|
+
* Secret under which a code is stored as an HMAC-SHA-256 digest instead of in plaintext.
|
|
565
|
+
* At least 32 UTF-8 bytes, kept with the application and never in the store, so a reader
|
|
566
|
+
* of the store alone cannot recover or test a code. Omitted: codes are stored in plaintext
|
|
567
|
+
* and a warning is logged at startup. A plaintext entry written while no secret was set
|
|
568
|
+
* verifies until it expires; changing or removing the secret makes a stored digest
|
|
569
|
+
* unverifiable, so those codes must be requested again.
|
|
570
|
+
*/
|
|
571
|
+
codeSecret?: string;
|
|
537
572
|
/** Per-purpose overrides of the defaults above. */
|
|
538
573
|
perPurpose?: Record<string, Partial<OtpPurposeConfig>>;
|
|
539
574
|
}
|
|
@@ -639,6 +674,11 @@ interface BymaxNotificationModuleAsyncOptions {
|
|
|
639
674
|
*/
|
|
640
675
|
declare class BymaxNotificationModule {
|
|
641
676
|
private static readonly logger;
|
|
677
|
+
/**
|
|
678
|
+
* Logs one warning when the OTP channel stores codes in plaintext, i.e. `otp.codeSecret`
|
|
679
|
+
* is not configured. A reader of the store would see every live code.
|
|
680
|
+
*/
|
|
681
|
+
private static warnPlaintextCodes;
|
|
642
682
|
/**
|
|
643
683
|
* Registers the module synchronously from static options.
|
|
644
684
|
*
|
|
@@ -727,6 +767,12 @@ interface ResolvedOtpOptions {
|
|
|
727
767
|
defaultMaxAttempts: number;
|
|
728
768
|
resendCooldownSeconds: number;
|
|
729
769
|
consumeOnVerify: boolean;
|
|
770
|
+
/**
|
|
771
|
+
* Turns a plaintext code into the value that is stored; present only when `codeSecret`
|
|
772
|
+
* is configured. A function rather than the secret, so the secret is not a property of
|
|
773
|
+
* an object that is injected under a public token and can be logged or serialized.
|
|
774
|
+
*/
|
|
775
|
+
digestCode?: (code: string) => string;
|
|
730
776
|
/** Per-purpose overrides, each fully resolved against the OTP defaults. */
|
|
731
777
|
perPurpose: Record<string, OtpPurposeConfig>;
|
|
732
778
|
/** Effective config for a purpose: the resolved `perPurpose[purpose]`, or the OTP defaults. */
|
|
@@ -854,7 +900,8 @@ declare class EmailService {
|
|
|
854
900
|
*
|
|
855
901
|
* @param input - The message envelope and rendered body.
|
|
856
902
|
* @returns The provider's message id.
|
|
857
|
-
* @throws NotificationException `EMAIL_PROVIDER_NOT_CONFIGURED`, `
|
|
903
|
+
* @throws NotificationException `EMAIL_PROVIDER_NOT_CONFIGURED`, `INVALID_SCOPE_IDENTIFIER`
|
|
904
|
+
* (a blank tenant or one with a control character), `EMAIL_ATTACHMENTS_TOO_LARGE`,
|
|
858
905
|
* `EMAIL_SEND_FAILED`, or `AUDIT_LOG_FAILED` (only when `audit.swallowErrors` is `false`).
|
|
859
906
|
*/
|
|
860
907
|
send(input: EmailSendInput): Promise<{
|
|
@@ -999,11 +1046,13 @@ interface OtpStatusResult {
|
|
|
999
1046
|
validated?: boolean;
|
|
1000
1047
|
}
|
|
1001
1048
|
/** OTP generation, verification, consumption, and status. */
|
|
1002
|
-
declare class OtpService {
|
|
1049
|
+
declare class OtpService implements OnModuleInit {
|
|
1003
1050
|
private readonly options;
|
|
1004
1051
|
private readonly storage;
|
|
1005
1052
|
private readonly auditLog;
|
|
1006
1053
|
private readonly emailService?;
|
|
1054
|
+
private readonly logger;
|
|
1055
|
+
private warnedFailuresNotCarried;
|
|
1007
1056
|
/**
|
|
1008
1057
|
* @param options - The resolved, frozen module options.
|
|
1009
1058
|
* @param storage - The configured OTP storage.
|
|
@@ -1066,6 +1115,45 @@ declare class OtpService {
|
|
|
1066
1115
|
* error is re-thrown after the lock is released.
|
|
1067
1116
|
*/
|
|
1068
1117
|
private persistAndDeliver;
|
|
1118
|
+
/**
|
|
1119
|
+
* Releases the cooldown and the orphan entry after a failed persist or delivery, audits the
|
|
1120
|
+
* failure, and returns what the caller must throw.
|
|
1121
|
+
*
|
|
1122
|
+
* A failed cleanup supersedes the delivery error — the cooldown/OTP may now be orphaned,
|
|
1123
|
+
* which the caller must see — and it must NOT bypass the scrub below. The delivery error is
|
|
1124
|
+
* preserved as its cause when the cleanup error can verifiably carry one; a hostile trap
|
|
1125
|
+
* inside the attachment is contained by the helper.
|
|
1126
|
+
*
|
|
1127
|
+
* The scrub runs BEFORE the audit write and the rethrow, so neither the entry's
|
|
1128
|
+
* `errorMessage` nor the outgoing chain can carry the plaintext code. An Error chain is
|
|
1129
|
+
* scrubbed (in place, or via redacted copies when a node resists mutation); ANY other
|
|
1130
|
+
* rejection (string, object from a custom storage, number) is flattened to a redacted
|
|
1131
|
+
* string, because a raw object could carry the code in its properties and a primitive
|
|
1132
|
+
* cannot be mutated.
|
|
1133
|
+
*/
|
|
1134
|
+
private failedOutgoing;
|
|
1135
|
+
/**
|
|
1136
|
+
* Warns once when the storage cannot carry failed attempts across a re-issue, naming the
|
|
1137
|
+
* deviation from NIST SP 800-63B-4 §3.1.3.2 and the methods that remove it.
|
|
1138
|
+
*/
|
|
1139
|
+
onModuleInit(): void;
|
|
1140
|
+
/**
|
|
1141
|
+
* Counts one verification attempt against the recipient. Returns `undefined` when the storage
|
|
1142
|
+
* does not carry failures, and `null` when no code is live: a verification with no code guesses
|
|
1143
|
+
* at nothing, so it spends no budget, and the caller must answer `not_found` instead of going on
|
|
1144
|
+
* to consume an attempt from a code issued in the meantime, which would then go uncounted.
|
|
1145
|
+
*/
|
|
1146
|
+
private countAttempt;
|
|
1147
|
+
/** How a generated code reaches the recipient: by email when asked or when an email channel exists. */
|
|
1148
|
+
private deliveryOf;
|
|
1149
|
+
/**
|
|
1150
|
+
* Refuses a manual delivery while codes are stored as digests, before the cooldown is taken
|
|
1151
|
+
* or anything is stored. `generate` never returns the code and a digest cannot be handed to
|
|
1152
|
+
* a person, so the call would otherwise succeed with nothing deliverable.
|
|
1153
|
+
*
|
|
1154
|
+
* @throws NotificationException `OTP_MANUAL_DELIVERY_UNAVAILABLE`.
|
|
1155
|
+
*/
|
|
1156
|
+
private assertDeliverable;
|
|
1069
1157
|
/** Delivers the code by email when requested; throws on failure (release is handled by the caller). */
|
|
1070
1158
|
private deliverOtp;
|
|
1071
1159
|
/** Clears the cooldown and deletes the OTP — used to undo a failed delivery. */
|
|
@@ -1074,6 +1162,33 @@ declare class OtpService {
|
|
|
1074
1162
|
private buildOtpEmail;
|
|
1075
1163
|
/** Finalizes a correct verification: consume-and-clear, or mark `validated`. */
|
|
1076
1164
|
private finalizeVerifySuccess;
|
|
1165
|
+
/**
|
|
1166
|
+
* Refuses a tenant id or recipient that identifies nobody, before any storage call.
|
|
1167
|
+
*
|
|
1168
|
+
* The reference storage already refuses these through `hashTenantRecipient`, but a
|
|
1169
|
+
* consumer-supplied {@link IOtpStorage} is not required to, and a blank scope would
|
|
1170
|
+
* then be shared by every caller that sent one.
|
|
1171
|
+
*
|
|
1172
|
+
* @throws NotificationException `INVALID_SCOPE_IDENTIFIER` when either is blank.
|
|
1173
|
+
*/
|
|
1174
|
+
private assertScope;
|
|
1175
|
+
/**
|
|
1176
|
+
* Returns the input with its recipient replaced by the value the OTP state is keyed on.
|
|
1177
|
+
*
|
|
1178
|
+
* Every storage call and audit entry takes the result, so two spellings of one mailbox
|
|
1179
|
+
* share a cooldown and an attempt counter. Delivery takes the original input: the
|
|
1180
|
+
* message is addressed exactly as the caller wrote it.
|
|
1181
|
+
*/
|
|
1182
|
+
private keyed;
|
|
1183
|
+
/**
|
|
1184
|
+
* Compares a guessed code with the stored value in constant time.
|
|
1185
|
+
*
|
|
1186
|
+
* A stored digest is recomputed from the guess. A digest that cannot be recomputed (no
|
|
1187
|
+
* secret configured, or a different one) never matches, and the digest string itself is
|
|
1188
|
+
* not accepted as a code. A stored value that is not a digest is a plaintext code written
|
|
1189
|
+
* while no secret was set; it is compared directly and ages out with its TTL.
|
|
1190
|
+
*/
|
|
1191
|
+
private matchesStoredCode;
|
|
1077
1192
|
/** Returns the resolved OTP options or throws `OTP_STORAGE_NOT_CONFIGURED`. */
|
|
1078
1193
|
private requireOtpOptions;
|
|
1079
1194
|
/** Builds an OTP audit entry with the recipient masked and never the code. */
|
|
@@ -1144,9 +1259,10 @@ type DispatchResult = {
|
|
|
1144
1259
|
result: OtpGenerateResult | OtpVerifyResult | void;
|
|
1145
1260
|
};
|
|
1146
1261
|
/** Uniform façade over the configured channel services. */
|
|
1147
|
-
declare class NotificationService {
|
|
1262
|
+
declare class NotificationService implements OnModuleInit {
|
|
1148
1263
|
private readonly emailService?;
|
|
1149
1264
|
private readonly otpService?;
|
|
1265
|
+
private readonly logger;
|
|
1150
1266
|
/**
|
|
1151
1267
|
* @param emailService - The email service, present only when the email channel is configured.
|
|
1152
1268
|
* @param otpService - The OTP service, present only when the OTP channel is configured.
|
|
@@ -1181,6 +1297,15 @@ declare class NotificationService {
|
|
|
1181
1297
|
* @throws NotificationException `CHANNEL_DISABLED` when OTP is not configured.
|
|
1182
1298
|
*/
|
|
1183
1299
|
getOtp(): OtpService;
|
|
1300
|
+
/**
|
|
1301
|
+
* Warns once per channel that is configured but cannot be used, because its provider or
|
|
1302
|
+
* storage reports `isConfigured() === false`. Such a channel is absent from
|
|
1303
|
+
* {@link NotificationService.getEnabledChannels} and refused by the accessors; without this
|
|
1304
|
+
* line the first sign of it would be a failed send.
|
|
1305
|
+
*/
|
|
1306
|
+
onModuleInit(): void;
|
|
1307
|
+
/** Logs the not-usable warning for one channel. */
|
|
1308
|
+
private warnNotUsable;
|
|
1184
1309
|
/** Routes an email dispatch to `sendTemplate` (template) or `send` (raw body). */
|
|
1185
1310
|
private dispatchEmail;
|
|
1186
1311
|
/** Routes an OTP dispatch by `action`, defaulting to `generate`. */
|
|
@@ -1204,6 +1329,10 @@ declare class NotificationService {
|
|
|
1204
1329
|
* tenant id is taken from `global.tenantIdResolver(request)` when configured,
|
|
1205
1330
|
* which OVERRIDES any `tenantId` carried in the dispatch payload — closing the
|
|
1206
1331
|
* tenant-spoofing vector where a caller forges another tenant's id in the body.
|
|
1332
|
+
* A tenant id that is not a string, is empty or is whitespace-only is refused on every
|
|
1333
|
+
* path that produces it (the resolver, the payload with no resolver, the payload when
|
|
1334
|
+
* there is no HTTP request) instead of being recorded; a dispatch-shaped argument whose
|
|
1335
|
+
* payload `tenantId` is not a string is not recognised as a dispatch and is skipped.
|
|
1207
1336
|
*
|
|
1208
1337
|
* The entry NEVER carries the dispatched payload (an OTP `verify` payload holds a
|
|
1209
1338
|
* guessed code) — only the channel, the masked recipient, the purpose/template,
|
|
@@ -1991,6 +2120,36 @@ declare class InMemoryOtpStorage implements IOtpStorage {
|
|
|
1991
2120
|
private readonly store;
|
|
1992
2121
|
/** Cooldown expiries (epoch ms) keyed by the same composite key. */
|
|
1993
2122
|
private readonly cooldowns;
|
|
2123
|
+
/** Failed-verification counters and their expiry (epoch ms), keyed the same way. */
|
|
2124
|
+
private readonly failures;
|
|
2125
|
+
/**
|
|
2126
|
+
* Failed verifications recorded for the scope, or `0` once the counter has lapsed.
|
|
2127
|
+
*
|
|
2128
|
+
* @param tenantId - Tenant isolation scope.
|
|
2129
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2130
|
+
* @param purpose - OTP purpose.
|
|
2131
|
+
* @returns The count.
|
|
2132
|
+
*/
|
|
2133
|
+
getFailures(tenantId: string, recipient: string, purpose: string): Promise<number>;
|
|
2134
|
+
/**
|
|
2135
|
+
* Adds one failed verification and restarts the counter's lifetime. Synchronous
|
|
2136
|
+
* read-modify-write, so concurrent calls each see a distinct count.
|
|
2137
|
+
*
|
|
2138
|
+
* @param tenantId - Tenant isolation scope.
|
|
2139
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2140
|
+
* @param purpose - OTP purpose.
|
|
2141
|
+
* @param ttlSeconds - How long the counter lives without another failure.
|
|
2142
|
+
* @returns The new count.
|
|
2143
|
+
*/
|
|
2144
|
+
recordFailure(tenantId: string, recipient: string, purpose: string, ttlSeconds: number): Promise<number>;
|
|
2145
|
+
/**
|
|
2146
|
+
* Removes the failure counter. Idempotent.
|
|
2147
|
+
*
|
|
2148
|
+
* @param tenantId - Tenant isolation scope.
|
|
2149
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2150
|
+
* @param purpose - OTP purpose.
|
|
2151
|
+
*/
|
|
2152
|
+
clearFailures(tenantId: string, recipient: string, purpose: string): Promise<void>;
|
|
1994
2153
|
/** Always ready — there is nothing to configure.
|
|
1995
2154
|
*
|
|
1996
2155
|
* @returns `true`.
|
|
@@ -2079,6 +2238,8 @@ declare class InMemoryOtpStorage implements IOtpStorage {
|
|
|
2079
2238
|
* @returns The number of stored OTP entries and active cooldowns.
|
|
2080
2239
|
*/
|
|
2081
2240
|
size(): InMemoryStorageSize;
|
|
2241
|
+
/** The unexpired failure count for a key, dropping a lapsed counter. Synchronous. */
|
|
2242
|
+
private liveFailures;
|
|
2082
2243
|
/**
|
|
2083
2244
|
* Collapses the `(tenantId, recipient, purpose)` tuple into one map key.
|
|
2084
2245
|
*
|
|
@@ -2116,7 +2277,10 @@ declare class InMemoryOtpStorage implements IOtpStorage {
|
|
|
2116
2277
|
/** The slim Redis surface {@link RedisOtpStorage} relies on (ioredis is structurally compatible). */
|
|
2117
2278
|
interface RedisLike {
|
|
2118
2279
|
get(key: string): Promise<string | null>;
|
|
2119
|
-
|
|
2280
|
+
/** The cooldown lock: `SET key value EX seconds NX`. */
|
|
2281
|
+
set(key: string, value: string, expiry: 'EX', seconds: number, condition: 'NX'): Promise<'OK' | null>;
|
|
2282
|
+
/** An in-place rewrite that keeps the expiry: `SET key value KEEPTTL XX`. */
|
|
2283
|
+
set(key: string, value: string, keepTtl: 'KEEPTTL', condition: 'XX'): Promise<'OK' | null>;
|
|
2120
2284
|
setex(key: string, ttlSeconds: number, value: string): Promise<'OK'>;
|
|
2121
2285
|
del(...keys: string[]): Promise<number>;
|
|
2122
2286
|
ttl(key: string): Promise<number>;
|
|
@@ -2147,6 +2311,12 @@ declare class RedisOtpStorage implements IOtpStorage {
|
|
|
2147
2311
|
* `PTTL` is read inside the script to preserve the original expiry on rewrite.
|
|
2148
2312
|
*/
|
|
2149
2313
|
private static readonly CONSUME_ATTEMPT_LUA;
|
|
2314
|
+
/**
|
|
2315
|
+
* Atomic failure-counter primitive: one `INCR` and the lifetime refresh in a single script, so
|
|
2316
|
+
* concurrent failures each receive a distinct count and the counter never outlives its window
|
|
2317
|
+
* by a gap between the two commands.
|
|
2318
|
+
*/
|
|
2319
|
+
private static readonly RECORD_FAILURE_LUA;
|
|
2150
2320
|
/** Whether a Redis client was supplied.
|
|
2151
2321
|
*
|
|
2152
2322
|
* @returns `true` when a client is present.
|
|
@@ -2229,8 +2399,37 @@ declare class RedisOtpStorage implements IOtpStorage {
|
|
|
2229
2399
|
* @param purpose - OTP purpose.
|
|
2230
2400
|
*/
|
|
2231
2401
|
clearCooldown(tenantId: string, recipient: string, purpose: string): Promise<void>;
|
|
2402
|
+
/**
|
|
2403
|
+
* Failed verifications recorded for the scope.
|
|
2404
|
+
*
|
|
2405
|
+
* @param tenantId - Tenant isolation scope.
|
|
2406
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2407
|
+
* @param purpose - OTP purpose.
|
|
2408
|
+
* @returns The count, or `0` when there is no counter.
|
|
2409
|
+
*/
|
|
2410
|
+
getFailures(tenantId: string, recipient: string, purpose: string): Promise<number>;
|
|
2411
|
+
/**
|
|
2412
|
+
* Adds one failed verification and restarts the counter's lifetime, atomically.
|
|
2413
|
+
*
|
|
2414
|
+
* @param tenantId - Tenant isolation scope.
|
|
2415
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2416
|
+
* @param purpose - OTP purpose.
|
|
2417
|
+
* @param ttlSeconds - How long the counter lives without another failure.
|
|
2418
|
+
* @returns The new count.
|
|
2419
|
+
*/
|
|
2420
|
+
recordFailure(tenantId: string, recipient: string, purpose: string, ttlSeconds: number): Promise<number>;
|
|
2421
|
+
/**
|
|
2422
|
+
* Removes the failure counter. Idempotent.
|
|
2423
|
+
*
|
|
2424
|
+
* @param tenantId - Tenant isolation scope.
|
|
2425
|
+
* @param recipient - Pre-normalized recipient identifier.
|
|
2426
|
+
* @param purpose - OTP purpose.
|
|
2427
|
+
*/
|
|
2428
|
+
clearFailures(tenantId: string, recipient: string, purpose: string): Promise<void>;
|
|
2232
2429
|
/** Builds the OTP entry key: `{namespace}:otp:{purpose}:{hashTenantRecipient(...)}`. */
|
|
2233
2430
|
private otpKey;
|
|
2431
|
+
/** Builds the failure-counter key: `{namespace}:otp_fail:{purpose}:{hashTenantRecipient(...)}`. */
|
|
2432
|
+
private failureKey;
|
|
2234
2433
|
/** Builds the cooldown key: `{namespace}:otp_cd:{purpose}:{hashTenantRecipient(...)}`. */
|
|
2235
2434
|
private cooldownKey;
|
|
2236
2435
|
}
|
|
@@ -2379,7 +2578,7 @@ declare function formatCooldown(remainingSeconds: number): string;
|
|
|
2379
2578
|
* Stable error-code identifiers, keyed by their symbolic name.
|
|
2380
2579
|
*
|
|
2381
2580
|
* Values are namespaced under `notification.*` and never change once published —
|
|
2382
|
-
* consumers branch on them to localize messages. The
|
|
2581
|
+
* consumers branch on them to localize messages. The 24 entries cover the email,
|
|
2383
2582
|
* template, OTP, SMS, push, audit, channel-config and scoping failure surfaces.
|
|
2384
2583
|
*/
|
|
2385
2584
|
declare const NOTIFICATION_ERROR_CODES: {
|
|
@@ -2393,6 +2592,7 @@ declare const NOTIFICATION_ERROR_CODES: {
|
|
|
2393
2592
|
readonly TEMPLATE_RENDER_FAILED: "notification.template_render_failed";
|
|
2394
2593
|
readonly OTP_STORAGE_NOT_CONFIGURED: "notification.otp_storage_not_configured";
|
|
2395
2594
|
readonly OTP_EMAIL_DELIVERY_NOT_CONFIGURED: "notification.otp_email_delivery_not_configured";
|
|
2595
|
+
readonly OTP_MANUAL_DELIVERY_UNAVAILABLE: "notification.otp_manual_delivery_unavailable";
|
|
2396
2596
|
readonly OTP_COOLDOWN_ACTIVE: "notification.otp_cooldown_active";
|
|
2397
2597
|
readonly OTP_NOT_FOUND: "notification.otp_not_found";
|
|
2398
2598
|
readonly OTP_EXPIRED: "notification.otp_expired";
|
|
@@ -2455,6 +2655,7 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
|
|
|
2455
2655
|
readonly status: HttpStatus.PAYLOAD_TOO_LARGE;
|
|
2456
2656
|
readonly message: "Email attachments exceed size limit";
|
|
2457
2657
|
};
|
|
2658
|
+
/** Reserved: `to` is not validated, so the library never throws this code. */
|
|
2458
2659
|
readonly EMAIL_INVALID_RECIPIENT: {
|
|
2459
2660
|
readonly code: "notification.email_invalid_recipient";
|
|
2460
2661
|
readonly status: HttpStatus.BAD_REQUEST;
|
|
@@ -2485,26 +2686,35 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
|
|
|
2485
2686
|
readonly status: HttpStatus.INTERNAL_SERVER_ERROR;
|
|
2486
2687
|
readonly message: "OTP email delivery requested but email channel not configured";
|
|
2487
2688
|
};
|
|
2689
|
+
readonly OTP_MANUAL_DELIVERY_UNAVAILABLE: {
|
|
2690
|
+
readonly code: "notification.otp_manual_delivery_unavailable";
|
|
2691
|
+
readonly status: HttpStatus.BAD_REQUEST;
|
|
2692
|
+
readonly message: "OTP manual delivery is unavailable while otp.codeSecret is set";
|
|
2693
|
+
};
|
|
2488
2694
|
readonly OTP_COOLDOWN_ACTIVE: {
|
|
2489
2695
|
readonly code: "notification.otp_cooldown_active";
|
|
2490
2696
|
readonly status: HttpStatus.TOO_MANY_REQUESTS;
|
|
2491
2697
|
readonly message: "Resend cooldown is active";
|
|
2492
2698
|
};
|
|
2699
|
+
/** Reserved: `verify()` returns `{ valid: false, reason: 'not_found' }` instead of throwing. */
|
|
2493
2700
|
readonly OTP_NOT_FOUND: {
|
|
2494
2701
|
readonly code: "notification.otp_not_found";
|
|
2495
2702
|
readonly status: HttpStatus.NOT_FOUND;
|
|
2496
2703
|
readonly message: "OTP not found or expired";
|
|
2497
2704
|
};
|
|
2705
|
+
/** Reserved: an expired code is reported as `not_found`. */
|
|
2498
2706
|
readonly OTP_EXPIRED: {
|
|
2499
2707
|
readonly code: "notification.otp_expired";
|
|
2500
2708
|
readonly status: HttpStatus.GONE;
|
|
2501
2709
|
readonly message: "OTP code expired";
|
|
2502
2710
|
};
|
|
2711
|
+
/** Reserved: `verify()` returns `{ valid: false, reason: 'max_attempts' }` instead of throwing. */
|
|
2503
2712
|
readonly OTP_MAX_ATTEMPTS_EXCEEDED: {
|
|
2504
2713
|
readonly code: "notification.otp_max_attempts_exceeded";
|
|
2505
2714
|
readonly status: HttpStatus.TOO_MANY_REQUESTS;
|
|
2506
2715
|
readonly message: "Maximum OTP attempts exceeded";
|
|
2507
2716
|
};
|
|
2717
|
+
/** Reserved: `verify()` returns `{ valid: false, reason: 'invalid_code' }` instead of throwing. */
|
|
2508
2718
|
readonly OTP_INVALID_CODE: {
|
|
2509
2719
|
readonly code: "notification.otp_invalid_code";
|
|
2510
2720
|
readonly status: HttpStatus.UNAUTHORIZED;
|
|
@@ -2515,26 +2725,31 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
|
|
|
2515
2725
|
readonly status: HttpStatus.BAD_REQUEST;
|
|
2516
2726
|
readonly message: "Invalid OTP length config";
|
|
2517
2727
|
};
|
|
2728
|
+
/** Reserved: the SMS channel is not implemented. */
|
|
2518
2729
|
readonly SMS_PROVIDER_NOT_CONFIGURED: {
|
|
2519
2730
|
readonly code: "notification.sms_provider_not_configured";
|
|
2520
2731
|
readonly status: HttpStatus.INTERNAL_SERVER_ERROR;
|
|
2521
2732
|
readonly message: "SMS provider not configured";
|
|
2522
2733
|
};
|
|
2734
|
+
/** Reserved: the SMS channel is not implemented. */
|
|
2523
2735
|
readonly SMS_SEND_FAILED: {
|
|
2524
2736
|
readonly code: "notification.sms_send_failed";
|
|
2525
2737
|
readonly status: HttpStatus.BAD_GATEWAY;
|
|
2526
2738
|
readonly message: "Failed to send SMS";
|
|
2527
2739
|
};
|
|
2740
|
+
/** Reserved: the SMS channel is not implemented. */
|
|
2528
2741
|
readonly SMS_INVALID_RECIPIENT: {
|
|
2529
2742
|
readonly code: "notification.sms_invalid_recipient";
|
|
2530
2743
|
readonly status: HttpStatus.BAD_REQUEST;
|
|
2531
2744
|
readonly message: "Invalid phone number";
|
|
2532
2745
|
};
|
|
2746
|
+
/** Reserved: the push channel is not implemented. */
|
|
2533
2747
|
readonly PUSH_PROVIDER_NOT_CONFIGURED: {
|
|
2534
2748
|
readonly code: "notification.push_provider_not_configured";
|
|
2535
2749
|
readonly status: HttpStatus.INTERNAL_SERVER_ERROR;
|
|
2536
2750
|
readonly message: "Push provider not configured";
|
|
2537
2751
|
};
|
|
2752
|
+
/** Reserved: the push channel is not implemented. */
|
|
2538
2753
|
readonly PUSH_SEND_FAILED: {
|
|
2539
2754
|
readonly code: "notification.push_send_failed";
|
|
2540
2755
|
readonly status: HttpStatus.BAD_GATEWAY;
|
|
@@ -2687,4 +2902,5 @@ declare const DEFAULT_TTLS: {
|
|
|
2687
2902
|
readonly OTP_GENERIC_SECONDS: 600;
|
|
2688
2903
|
};
|
|
2689
2904
|
|
|
2690
|
-
export {
|
|
2905
|
+
export { BYMAX_NOTIFICATION_EMAIL_PROVIDER, BYMAX_NOTIFICATION_LOG_REPOSITORY, BYMAX_NOTIFICATION_OPTIONS, BYMAX_NOTIFICATION_OTP_STORAGE, BYMAX_NOTIFICATION_PUSH_PROVIDER, BYMAX_NOTIFICATION_SMS_PROVIDER, BYMAX_NOTIFICATION_TEMPLATE_RENDERER, BymaxNotificationModule, CANONICAL_EMAIL_TEMPLATES, DEFAULT_TTLS, DefaultTemplateRenderer, EmailService, InMemoryOtpStorage, NOTIFICATION_ERROR_CODES, NOTIFICATION_ERROR_DEFINITIONS, NOTIFICATION_PURPOSES, NoOpEmailProvider, NoOpNotificationLogRepository, NotificationAuditInterceptor, NotificationException, NotificationService, OtpService, RedisOtpStorage, ResendEmailProvider, SmtpEmailProvider, cooldownExpiresAt, formatCooldown, generateOtpCode, hashTenantRecipient, safeCompare, toRetryAfterHeader };
|
|
2906
|
+
export type { AuditOptions, BymaxNotificationModuleAsyncOptions, BymaxNotificationModuleOptions, BymaxNotificationModuleOptionsFactory, CanonicalEmailTemplate, CanonicalNotificationPurpose, ConsumeAttemptResult, DefaultTemplateRendererOptions, DispatchInput, DispatchResult, EmailAttachment, EmailChannelOptions, EmailDispatchPayload, EmailSendInput, EmailSendOptions, EmailSendResult, EmailSendTemplateInput, GlobalOptions, IEmailProvider, IEmailTemplateRenderer, INotificationLogRepository, IOtpStorage, IPushProvider, ISmsProvider, InMemoryStorageSize, MissingVariableMode, NotificationChannel, NotificationErrorCode, NotificationErrorDefinition, NotificationErrorKey, NotificationErrorResponse, NotificationExceptionOptions, NotificationLogEntry, NotificationLogVerb, NotificationRequest, OtpChannelOptions, OtpConsumeInput, OtpDispatchPayload, OtpEntry, OtpGenerateInput, OtpGenerateResult, OtpPurpose, OtpPurposeConfig, OtpStatusInput, OtpStatusResult, OtpVerifyInput, OtpVerifyResult, PushChannelOptions, PushSendOptions, PushSendResult, RedisLike, RedisOtpStorageOptions, RenderedEmail, ResendEmailProviderOptions, ResolvedAuditOptions, ResolvedEmailOptions, ResolvedGlobalOptions, ResolvedNotificationOptions, ResolvedOtpOptions, SmsChannelOptions, SmsSendOptions, SmsSendResult, SmtpCredentials, SmtpEmailProviderOptions, SmtpTlsOptions, TemplateDefinition };
|