@bymax-one/nest-notification 1.4.9 → 1.4.10

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.
@@ -1227,7 +1227,7 @@ declare class OtpService implements OnModuleInit {
1227
1227
  * consumer-supplied {@link IOtpStorage} is not required to, and a blank scope would
1228
1228
  * then be shared by every caller that sent one.
1229
1229
  *
1230
- * @throws NotificationException `INVALID_SCOPE_IDENTIFIER` when either is blank.
1230
+ * @throws NotificationException `INVALID_SCOPE_IDENTIFIER` when either is blank or the purpose is not a plain name.
1231
1231
  */
1232
1232
  private assertScope;
1233
1233
  /**
@@ -1463,7 +1463,12 @@ declare class NotificationAuditInterceptor implements NestInterceptor {
1463
1463
  private buildEntry;
1464
1464
  /** Extracts the (unmasked) recipient from the dispatch payload. */
1465
1465
  private extractRecipient;
1466
- /** Extracts the audit `purpose`: the OTP purpose, or the email template name. */
1466
+ /**
1467
+ * Extracts the audit `purpose`: the OTP purpose, or the email template name. The interceptor sees
1468
+ * the payload before the service refuses it and audits a refused call too, so an OTP purpose that
1469
+ * is not a plain name is left out of the entry: a control character in it would forge a log
1470
+ * record and its length is unbounded.
1471
+ */
1467
1472
  private extractPurpose;
1468
1473
  }
1469
1474
 
@@ -1688,13 +1693,18 @@ declare class DefaultTemplateRenderer implements IEmailTemplateRenderer {
1688
1693
  /** Replaces every `{{path}}` placeholder, escaping only when `escape` is `true`. */
1689
1694
  private interpolate;
1690
1695
  /**
1691
- * Builds a variable resolver for one render call. Lookups go through a `Map`
1692
- * built from own enumerable entries (never bracket indexing) so neither flat
1693
- * nor nested resolution can reach inherited/prototype keys.
1696
+ * Builds a variable resolver for one render call. A key resolves only when the object holds it as
1697
+ * an own enumerable property, so neither flat nor nested resolution can reach inherited or
1698
+ * prototype keys, and only the property that is named is read.
1694
1699
  */
1695
1700
  private buildResolver;
1696
1701
  /** Walks a dotted path through own enumerable keys, stopping at any non-object. */
1697
1702
  private resolveNested;
1703
+ /**
1704
+ * The value of `key` when `object` holds it as an own enumerable property, otherwise `undefined`.
1705
+ * Called through `Object.prototype` so an object without a prototype works too.
1706
+ */
1707
+ private ownValue;
1698
1708
  /**
1699
1709
  * Validates a registered template shape, throwing on the offending key. The
1700
1710
  * optional `text` body, when present, must be a string — a non-string `text`
@@ -2195,7 +2205,7 @@ declare class SmtpEmailProvider implements IEmailProvider {
2195
2205
  * @fileoverview In-memory `IOtpStorage` for development and unit tests.
2196
2206
  * @layer infrastructure
2197
2207
  *
2198
- * Backed by two native `Map`s. It is atomic by construction: `consumeAttempt`
2208
+ * Backed by native `Map`s. It is atomic by construction: `consumeAttempt`
2199
2209
  * performs its read → checks → increment → write with NO `await` in between, so
2200
2210
  * Node's single-threaded event loop cannot interleave two calls and overshoot
2201
2211
  * `maxAttempts`.
@@ -2204,10 +2214,11 @@ declare class SmtpEmailProvider implements IEmailProvider {
2204
2214
  * and are not shared across instances; use `RedisOtpStorage` there.
2205
2215
  */
2206
2216
 
2207
- /** Aggregate sizes of the two internal maps — exposed by the {@link InMemoryOtpStorage.size} helper. */
2217
+ /** Aggregate sizes of the three internal maps — exposed by the {@link InMemoryOtpStorage.size} helper. */
2208
2218
  interface InMemoryStorageSize {
2209
2219
  otps: number;
2210
2220
  cooldowns: number;
2221
+ failures: number;
2211
2222
  }
2212
2223
  /** Process-local `IOtpStorage` for dev/test. */
2213
2224
  declare class InMemoryOtpStorage implements IOtpStorage {
@@ -2336,13 +2347,14 @@ declare class InMemoryOtpStorage implements IOtpStorage {
2336
2347
  */
2337
2348
  clearCooldown(tenantId: string, recipient: string, purpose: string): Promise<void>;
2338
2349
  /**
2339
- * Test helper — wipes all entries and cooldowns. Not part of `IOtpStorage`.
2350
+ * Test helper — wipes all entries, cooldowns and failure counters. Not part of `IOtpStorage`.
2340
2351
  */
2341
2352
  clear(): void;
2342
2353
  /**
2343
- * Test helper — current map sizes. Not part of `IOtpStorage`.
2354
+ * Test helper — current map sizes. Not part of `IOtpStorage`. Like the cooldowns, a failure
2355
+ * counter that has lapsed stays counted until it is read or cleared.
2344
2356
  *
2345
- * @returns The number of stored OTP entries and active cooldowns.
2357
+ * @returns The number of stored OTP entries, cooldowns and failure counters.
2346
2358
  */
2347
2359
  size(): InMemoryStorageSize;
2348
2360
  /** The unexpired failure count for a key, dropping a lapsed counter. Synchronous. */
@@ -2730,8 +2742,10 @@ declare const NOTIFICATION_ERROR_CODES: {
2730
2742
  readonly AUDIT_LOG_FAILED: "notification.audit_log_failed";
2731
2743
  readonly CHANNEL_DISABLED: "notification.channel_disabled";
2732
2744
  /**
2733
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
2734
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
2745
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
2746
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
2747
+ * control character, or, for a purpose, longer than 64 characters or made of
2748
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
2735
2749
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
2736
2750
  * than a value that cannot scope anything.
2737
2751
  */
@@ -2897,7 +2911,7 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2897
2911
  readonly INVALID_SCOPE_IDENTIFIER: {
2898
2912
  readonly code: "notification.invalid_scope_identifier";
2899
2913
  readonly status: HttpStatus.BAD_REQUEST;
2900
- readonly message: "Tenant or recipient identifier does not identify anybody";
2914
+ readonly message: "A tenant, recipient or purpose identifier is not valid";
2901
2915
  };
2902
2916
  };
2903
2917
  /** The symbolic key of any entry in {@link NOTIFICATION_ERROR_DEFINITIONS}. */
@@ -1227,7 +1227,7 @@ declare class OtpService implements OnModuleInit {
1227
1227
  * consumer-supplied {@link IOtpStorage} is not required to, and a blank scope would
1228
1228
  * then be shared by every caller that sent one.
1229
1229
  *
1230
- * @throws NotificationException `INVALID_SCOPE_IDENTIFIER` when either is blank.
1230
+ * @throws NotificationException `INVALID_SCOPE_IDENTIFIER` when either is blank or the purpose is not a plain name.
1231
1231
  */
1232
1232
  private assertScope;
1233
1233
  /**
@@ -1463,7 +1463,12 @@ declare class NotificationAuditInterceptor implements NestInterceptor {
1463
1463
  private buildEntry;
1464
1464
  /** Extracts the (unmasked) recipient from the dispatch payload. */
1465
1465
  private extractRecipient;
1466
- /** Extracts the audit `purpose`: the OTP purpose, or the email template name. */
1466
+ /**
1467
+ * Extracts the audit `purpose`: the OTP purpose, or the email template name. The interceptor sees
1468
+ * the payload before the service refuses it and audits a refused call too, so an OTP purpose that
1469
+ * is not a plain name is left out of the entry: a control character in it would forge a log
1470
+ * record and its length is unbounded.
1471
+ */
1467
1472
  private extractPurpose;
1468
1473
  }
1469
1474
 
@@ -1688,13 +1693,18 @@ declare class DefaultTemplateRenderer implements IEmailTemplateRenderer {
1688
1693
  /** Replaces every `{{path}}` placeholder, escaping only when `escape` is `true`. */
1689
1694
  private interpolate;
1690
1695
  /**
1691
- * Builds a variable resolver for one render call. Lookups go through a `Map`
1692
- * built from own enumerable entries (never bracket indexing) so neither flat
1693
- * nor nested resolution can reach inherited/prototype keys.
1696
+ * Builds a variable resolver for one render call. A key resolves only when the object holds it as
1697
+ * an own enumerable property, so neither flat nor nested resolution can reach inherited or
1698
+ * prototype keys, and only the property that is named is read.
1694
1699
  */
1695
1700
  private buildResolver;
1696
1701
  /** Walks a dotted path through own enumerable keys, stopping at any non-object. */
1697
1702
  private resolveNested;
1703
+ /**
1704
+ * The value of `key` when `object` holds it as an own enumerable property, otherwise `undefined`.
1705
+ * Called through `Object.prototype` so an object without a prototype works too.
1706
+ */
1707
+ private ownValue;
1698
1708
  /**
1699
1709
  * Validates a registered template shape, throwing on the offending key. The
1700
1710
  * optional `text` body, when present, must be a string — a non-string `text`
@@ -2195,7 +2205,7 @@ declare class SmtpEmailProvider implements IEmailProvider {
2195
2205
  * @fileoverview In-memory `IOtpStorage` for development and unit tests.
2196
2206
  * @layer infrastructure
2197
2207
  *
2198
- * Backed by two native `Map`s. It is atomic by construction: `consumeAttempt`
2208
+ * Backed by native `Map`s. It is atomic by construction: `consumeAttempt`
2199
2209
  * performs its read → checks → increment → write with NO `await` in between, so
2200
2210
  * Node's single-threaded event loop cannot interleave two calls and overshoot
2201
2211
  * `maxAttempts`.
@@ -2204,10 +2214,11 @@ declare class SmtpEmailProvider implements IEmailProvider {
2204
2214
  * and are not shared across instances; use `RedisOtpStorage` there.
2205
2215
  */
2206
2216
 
2207
- /** Aggregate sizes of the two internal maps — exposed by the {@link InMemoryOtpStorage.size} helper. */
2217
+ /** Aggregate sizes of the three internal maps — exposed by the {@link InMemoryOtpStorage.size} helper. */
2208
2218
  interface InMemoryStorageSize {
2209
2219
  otps: number;
2210
2220
  cooldowns: number;
2221
+ failures: number;
2211
2222
  }
2212
2223
  /** Process-local `IOtpStorage` for dev/test. */
2213
2224
  declare class InMemoryOtpStorage implements IOtpStorage {
@@ -2336,13 +2347,14 @@ declare class InMemoryOtpStorage implements IOtpStorage {
2336
2347
  */
2337
2348
  clearCooldown(tenantId: string, recipient: string, purpose: string): Promise<void>;
2338
2349
  /**
2339
- * Test helper — wipes all entries and cooldowns. Not part of `IOtpStorage`.
2350
+ * Test helper — wipes all entries, cooldowns and failure counters. Not part of `IOtpStorage`.
2340
2351
  */
2341
2352
  clear(): void;
2342
2353
  /**
2343
- * Test helper — current map sizes. Not part of `IOtpStorage`.
2354
+ * Test helper — current map sizes. Not part of `IOtpStorage`. Like the cooldowns, a failure
2355
+ * counter that has lapsed stays counted until it is read or cleared.
2344
2356
  *
2345
- * @returns The number of stored OTP entries and active cooldowns.
2357
+ * @returns The number of stored OTP entries, cooldowns and failure counters.
2346
2358
  */
2347
2359
  size(): InMemoryStorageSize;
2348
2360
  /** The unexpired failure count for a key, dropping a lapsed counter. Synchronous. */
@@ -2730,8 +2742,10 @@ declare const NOTIFICATION_ERROR_CODES: {
2730
2742
  readonly AUDIT_LOG_FAILED: "notification.audit_log_failed";
2731
2743
  readonly CHANNEL_DISABLED: "notification.channel_disabled";
2732
2744
  /**
2733
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
2734
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
2745
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
2746
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
2747
+ * control character, or, for a purpose, longer than 64 characters or made of
2748
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
2735
2749
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
2736
2750
  * than a value that cannot scope anything.
2737
2751
  */
@@ -2897,7 +2911,7 @@ declare const NOTIFICATION_ERROR_DEFINITIONS: {
2897
2911
  readonly INVALID_SCOPE_IDENTIFIER: {
2898
2912
  readonly code: "notification.invalid_scope_identifier";
2899
2913
  readonly status: HttpStatus.BAD_REQUEST;
2900
- readonly message: "Tenant or recipient identifier does not identify anybody";
2914
+ readonly message: "A tenant, recipient or purpose identifier is not valid";
2901
2915
  };
2902
2916
  };
2903
2917
  /** The symbolic key of any entry in {@link NOTIFICATION_ERROR_DEFINITIONS}. */