@bymax-one/nest-notification 1.4.8 → 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.
@@ -18,6 +18,7 @@ var NOTIFICATION_ERROR_CODES = {
18
18
  OTP_EXPIRED: "notification.otp_expired",
19
19
  OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded",
20
20
  OTP_INVALID_CODE: "notification.otp_invalid_code",
21
+ OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable",
21
22
  OTP_INVALID_LENGTH: "notification.otp_invalid_length",
22
23
  SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured",
23
24
  SMS_SEND_FAILED: "notification.sms_send_failed",
@@ -27,8 +28,10 @@ var NOTIFICATION_ERROR_CODES = {
27
28
  AUDIT_LOG_FAILED: "notification.audit_log_failed",
28
29
  CHANNEL_DISABLED: "notification.channel_disabled",
29
30
  /**
30
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
31
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
31
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
32
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
33
+ * control character, or, for a purpose, longer than 64 characters or made of
34
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
32
35
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
33
36
  * than a value that cannot scope anything.
34
37
  */
@@ -94,6 +94,7 @@ declare const NOTIFICATION_ERROR_CODES: {
94
94
  readonly OTP_EXPIRED: "notification.otp_expired";
95
95
  readonly OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded";
96
96
  readonly OTP_INVALID_CODE: "notification.otp_invalid_code";
97
+ readonly OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable";
97
98
  readonly OTP_INVALID_LENGTH: "notification.otp_invalid_length";
98
99
  readonly SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured";
99
100
  readonly SMS_SEND_FAILED: "notification.sms_send_failed";
@@ -103,8 +104,10 @@ declare const NOTIFICATION_ERROR_CODES: {
103
104
  readonly AUDIT_LOG_FAILED: "notification.audit_log_failed";
104
105
  readonly CHANNEL_DISABLED: "notification.channel_disabled";
105
106
  /**
106
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
107
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
107
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
108
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
109
+ * control character, or, for a purpose, longer than 64 characters or made of
110
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
108
111
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
109
112
  * than a value that cannot scope anything.
110
113
  */
@@ -94,6 +94,7 @@ declare const NOTIFICATION_ERROR_CODES: {
94
94
  readonly OTP_EXPIRED: "notification.otp_expired";
95
95
  readonly OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded";
96
96
  readonly OTP_INVALID_CODE: "notification.otp_invalid_code";
97
+ readonly OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable";
97
98
  readonly OTP_INVALID_LENGTH: "notification.otp_invalid_length";
98
99
  readonly SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured";
99
100
  readonly SMS_SEND_FAILED: "notification.sms_send_failed";
@@ -103,8 +104,10 @@ declare const NOTIFICATION_ERROR_CODES: {
103
104
  readonly AUDIT_LOG_FAILED: "notification.audit_log_failed";
104
105
  readonly CHANNEL_DISABLED: "notification.channel_disabled";
105
106
  /**
106
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
107
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
107
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
108
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
109
+ * control character, or, for a purpose, longer than 64 characters or made of
110
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
108
111
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
109
112
  * than a value that cannot scope anything.
110
113
  */
@@ -16,6 +16,7 @@ var NOTIFICATION_ERROR_CODES = {
16
16
  OTP_EXPIRED: "notification.otp_expired",
17
17
  OTP_MAX_ATTEMPTS_EXCEEDED: "notification.otp_max_attempts_exceeded",
18
18
  OTP_INVALID_CODE: "notification.otp_invalid_code",
19
+ OTP_STORAGE_UNAVAILABLE: "notification.otp_storage_unavailable",
19
20
  OTP_INVALID_LENGTH: "notification.otp_invalid_length",
20
21
  SMS_PROVIDER_NOT_CONFIGURED: "notification.sms_provider_not_configured",
21
22
  SMS_SEND_FAILED: "notification.sms_send_failed",
@@ -25,8 +26,10 @@ var NOTIFICATION_ERROR_CODES = {
25
26
  AUDIT_LOG_FAILED: "notification.audit_log_failed",
26
27
  CHANNEL_DISABLED: "notification.channel_disabled",
27
28
  /**
28
- * A `tenantId` or `recipient` that identifies nobody reached a scoping
29
- * boundary — empty, whitespace-only, or not a string at all. Distinct from
29
+ * A `tenantId`, `recipient` or `purpose` that cannot scope an OTP reached a
30
+ * scoping boundary: empty, whitespace-only, not a string at all, carrying a
31
+ * control character, or, for a purpose, longer than 64 characters or made of
32
+ * anything but `A-Z a-z 0-9 : _ -`. Distinct from
30
33
  * {@link EMAIL_INVALID_RECIPIENT}, which is about a malformed address rather
31
34
  * than a value that cannot scope anything.
32
35
  */
@@ -17,6 +17,79 @@ function wait(ms) {
17
17
  });
18
18
  }
19
19
 
20
+ // src/testing/otp-storage-contract.consume.ts
21
+ var STORED = "stored-value-1";
22
+ var REGENERATED = "stored-value-2";
23
+ function entryOf(code) {
24
+ return { code, expiresAt: Date.now() + 6e4, attempts: 0, maxAttempts: 5 };
25
+ }
26
+ function deleteIfCodeCase({ scope, withStorage }) {
27
+ return {
28
+ name: "deleteIfCode removes only the stored value it is given (optional)",
29
+ run: () => withStorage(async (storage) => {
30
+ if (storage.deleteIfCode === void 0) {
31
+ return;
32
+ }
33
+ await storage.set(scope.tenantA, scope.recipient, scope.purpose, entryOf(STORED));
34
+ const other = await storage.deleteIfCode(
35
+ scope.tenantA,
36
+ scope.recipient,
37
+ scope.purpose,
38
+ REGENERATED
39
+ );
40
+ const kept = await storage.get(scope.tenantA, scope.recipient, scope.purpose);
41
+ const match = await storage.deleteIfCode(
42
+ scope.tenantA,
43
+ scope.recipient,
44
+ scope.purpose,
45
+ STORED
46
+ );
47
+ const gone = await storage.get(scope.tenantA, scope.recipient, scope.purpose);
48
+ const absent = await storage.deleteIfCode(
49
+ scope.tenantA,
50
+ scope.recipient,
51
+ scope.purpose,
52
+ STORED
53
+ );
54
+ check(
55
+ other === false && kept?.code === STORED,
56
+ "deleteIfCode removed an entry whose stored value differs from the one it was given, so a code regenerated after the read is destroyed by the verification that read the old one"
57
+ );
58
+ check(
59
+ match === true && gone === null,
60
+ "deleteIfCode did not remove the entry whose stored value it was given"
61
+ );
62
+ check(absent === false, "deleteIfCode reported true for an entry that was not there");
63
+ })
64
+ };
65
+ }
66
+ function deleteIfCodeAtomicCase({
67
+ scope,
68
+ withStorage
69
+ }) {
70
+ return {
71
+ name: "deleteIfCode is ATOMIC under concurrency (optional)",
72
+ run: () => withStorage(async (storage) => {
73
+ if (storage.deleteIfCode === void 0) {
74
+ return;
75
+ }
76
+ const { deleteIfCode } = storage;
77
+ await storage.set(scope.tenantA, scope.recipient, scope.purpose, entryOf(STORED));
78
+ const results = await Promise.all(
79
+ Array.from(
80
+ { length: RACERS },
81
+ () => deleteIfCode.call(storage, scope.tenantA, scope.recipient, scope.purpose, STORED)
82
+ )
83
+ );
84
+ const winners = results.filter(Boolean).length;
85
+ check(
86
+ winners === 1,
87
+ `${String(winners)} of ${String(RACERS)} concurrent deleteIfCode calls reported removing the same entry \u2014 the comparison and the delete are not one indivisible operation, so a one-time code is accepted more than once`
88
+ );
89
+ })
90
+ };
91
+ }
92
+
20
93
  // src/testing/otp-storage-contract.failures.ts
21
94
  function hasFailureMethods(storage) {
22
95
  return storage.getFailures !== void 0 && storage.recordFailure !== void 0 && storage.clearFailures !== void 0;
@@ -211,13 +284,14 @@ var ANY_CODE = "111111";
211
284
  var OTHER_CODE = "222222";
212
285
  function makeScope() {
213
286
  const run = crypto.randomUUID();
287
+ const purposeRun = run.replaceAll("-", "").slice(0, 12);
214
288
  return {
215
289
  tenantA: `${KEY_PREFIX}_${run}_${TENANT_A}`,
216
290
  tenantB: `${KEY_PREFIX}_${run}_${TENANT_B}`,
217
291
  recipient: `${run}_${RECIPIENT_LOCAL}`,
218
292
  absentRecipient: `${run}_${ABSENT_LOCAL}`,
219
- purpose: `${KEY_PREFIX}_${run}_${PURPOSE_MAIN}`,
220
- otherPurpose: `${KEY_PREFIX}_${run}_${PURPOSE_OTHER}`,
293
+ purpose: `${KEY_PREFIX}_${purposeRun}_${PURPOSE_MAIN}`,
294
+ otherPurpose: `${KEY_PREFIX}_${purposeRun}_${PURPOSE_OTHER}`,
221
295
  // Same characters, two different (tenant, recipient) splits. A key built by
222
296
  // joining the raw values around `:` maps both onto one string, and so does one
223
297
  // built around `::`, which the single-colon pair alone does not expose.
@@ -631,7 +705,9 @@ var CASE_BUILDERS = [
631
705
  failureBoundaryCase,
632
706
  failureClearCase,
633
707
  failureTtlCase,
634
- failureAtomicCase
708
+ failureAtomicCase,
709
+ deleteIfCodeCase,
710
+ deleteIfCodeAtomicCase
635
711
  ];
636
712
  function otpStorageContract(factory, options = {}) {
637
713
  const scope = makeScope();
@@ -87,6 +87,27 @@ interface IOtpStorage {
87
87
  update(tenantId: string, recipient: string, purpose: string, entry: OtpEntry): Promise<void>;
88
88
  /** Removes the OTP entry. Idempotent. */
89
89
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
90
+ /**
91
+ * Atomic compare-and-delete: removes the entry only when the value it still stores equals
92
+ * `expectedStored`, and reports whether this call removed it. Of N concurrent calls for one
93
+ * stored value, exactly one returns `true`.
94
+ *
95
+ * `expectedStored` is the exact STORED `code` the service read from the entry (the keyed
96
+ * digest when `otp.codeSecret` is set), never the guess a user typed: no plaintext guess
97
+ * reaches the storage. The service has already compared the guess in constant time; this
98
+ * only makes the one-time property hold when several verifications of the right code run
99
+ * at once. A code regenerated in between stores a different value, so it is left alone and
100
+ * the call returns `false`.
101
+ *
102
+ * Required when `otp.consumeOnVerify` is `true`: the service refuses to start without it,
103
+ * so a storage that cannot do this atomically never silently keeps the race.
104
+ *
105
+ * MUST be atomic.
106
+ *
107
+ * @param expectedStored - The stored code value the caller read.
108
+ * @returns `true` when this call deleted the entry, `false` when it was absent or changed.
109
+ */
110
+ deleteIfCode?(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
90
111
  /**
91
112
  * Atomic cooldown acquire for `(tenant, recipient, purpose)`. Sets the cooldown
92
113
  * key only if it does not already exist (Redis: `SET NX EX`). Returns `true`
@@ -87,6 +87,27 @@ interface IOtpStorage {
87
87
  update(tenantId: string, recipient: string, purpose: string, entry: OtpEntry): Promise<void>;
88
88
  /** Removes the OTP entry. Idempotent. */
89
89
  delete(tenantId: string, recipient: string, purpose: string): Promise<void>;
90
+ /**
91
+ * Atomic compare-and-delete: removes the entry only when the value it still stores equals
92
+ * `expectedStored`, and reports whether this call removed it. Of N concurrent calls for one
93
+ * stored value, exactly one returns `true`.
94
+ *
95
+ * `expectedStored` is the exact STORED `code` the service read from the entry (the keyed
96
+ * digest when `otp.codeSecret` is set), never the guess a user typed: no plaintext guess
97
+ * reaches the storage. The service has already compared the guess in constant time; this
98
+ * only makes the one-time property hold when several verifications of the right code run
99
+ * at once. A code regenerated in between stores a different value, so it is left alone and
100
+ * the call returns `false`.
101
+ *
102
+ * Required when `otp.consumeOnVerify` is `true`: the service refuses to start without it,
103
+ * so a storage that cannot do this atomically never silently keeps the race.
104
+ *
105
+ * MUST be atomic.
106
+ *
107
+ * @param expectedStored - The stored code value the caller read.
108
+ * @returns `true` when this call deleted the entry, `false` when it was absent or changed.
109
+ */
110
+ deleteIfCode?(tenantId: string, recipient: string, purpose: string, expectedStored: string): Promise<boolean>;
90
111
  /**
91
112
  * Atomic cooldown acquire for `(tenant, recipient, purpose)`. Sets the cooldown
92
113
  * key only if it does not already exist (Redis: `SET NX EX`). Returns `true`
@@ -15,6 +15,79 @@ function wait(ms) {
15
15
  });
16
16
  }
17
17
 
18
+ // src/testing/otp-storage-contract.consume.ts
19
+ var STORED = "stored-value-1";
20
+ var REGENERATED = "stored-value-2";
21
+ function entryOf(code) {
22
+ return { code, expiresAt: Date.now() + 6e4, attempts: 0, maxAttempts: 5 };
23
+ }
24
+ function deleteIfCodeCase({ scope, withStorage }) {
25
+ return {
26
+ name: "deleteIfCode removes only the stored value it is given (optional)",
27
+ run: () => withStorage(async (storage) => {
28
+ if (storage.deleteIfCode === void 0) {
29
+ return;
30
+ }
31
+ await storage.set(scope.tenantA, scope.recipient, scope.purpose, entryOf(STORED));
32
+ const other = await storage.deleteIfCode(
33
+ scope.tenantA,
34
+ scope.recipient,
35
+ scope.purpose,
36
+ REGENERATED
37
+ );
38
+ const kept = await storage.get(scope.tenantA, scope.recipient, scope.purpose);
39
+ const match = await storage.deleteIfCode(
40
+ scope.tenantA,
41
+ scope.recipient,
42
+ scope.purpose,
43
+ STORED
44
+ );
45
+ const gone = await storage.get(scope.tenantA, scope.recipient, scope.purpose);
46
+ const absent = await storage.deleteIfCode(
47
+ scope.tenantA,
48
+ scope.recipient,
49
+ scope.purpose,
50
+ STORED
51
+ );
52
+ check(
53
+ other === false && kept?.code === STORED,
54
+ "deleteIfCode removed an entry whose stored value differs from the one it was given, so a code regenerated after the read is destroyed by the verification that read the old one"
55
+ );
56
+ check(
57
+ match === true && gone === null,
58
+ "deleteIfCode did not remove the entry whose stored value it was given"
59
+ );
60
+ check(absent === false, "deleteIfCode reported true for an entry that was not there");
61
+ })
62
+ };
63
+ }
64
+ function deleteIfCodeAtomicCase({
65
+ scope,
66
+ withStorage
67
+ }) {
68
+ return {
69
+ name: "deleteIfCode is ATOMIC under concurrency (optional)",
70
+ run: () => withStorage(async (storage) => {
71
+ if (storage.deleteIfCode === void 0) {
72
+ return;
73
+ }
74
+ const { deleteIfCode } = storage;
75
+ await storage.set(scope.tenantA, scope.recipient, scope.purpose, entryOf(STORED));
76
+ const results = await Promise.all(
77
+ Array.from(
78
+ { length: RACERS },
79
+ () => deleteIfCode.call(storage, scope.tenantA, scope.recipient, scope.purpose, STORED)
80
+ )
81
+ );
82
+ const winners = results.filter(Boolean).length;
83
+ check(
84
+ winners === 1,
85
+ `${String(winners)} of ${String(RACERS)} concurrent deleteIfCode calls reported removing the same entry \u2014 the comparison and the delete are not one indivisible operation, so a one-time code is accepted more than once`
86
+ );
87
+ })
88
+ };
89
+ }
90
+
18
91
  // src/testing/otp-storage-contract.failures.ts
19
92
  function hasFailureMethods(storage) {
20
93
  return storage.getFailures !== void 0 && storage.recordFailure !== void 0 && storage.clearFailures !== void 0;
@@ -209,13 +282,14 @@ var ANY_CODE = "111111";
209
282
  var OTHER_CODE = "222222";
210
283
  function makeScope() {
211
284
  const run = randomUUID();
285
+ const purposeRun = run.replaceAll("-", "").slice(0, 12);
212
286
  return {
213
287
  tenantA: `${KEY_PREFIX}_${run}_${TENANT_A}`,
214
288
  tenantB: `${KEY_PREFIX}_${run}_${TENANT_B}`,
215
289
  recipient: `${run}_${RECIPIENT_LOCAL}`,
216
290
  absentRecipient: `${run}_${ABSENT_LOCAL}`,
217
- purpose: `${KEY_PREFIX}_${run}_${PURPOSE_MAIN}`,
218
- otherPurpose: `${KEY_PREFIX}_${run}_${PURPOSE_OTHER}`,
291
+ purpose: `${KEY_PREFIX}_${purposeRun}_${PURPOSE_MAIN}`,
292
+ otherPurpose: `${KEY_PREFIX}_${purposeRun}_${PURPOSE_OTHER}`,
219
293
  // Same characters, two different (tenant, recipient) splits. A key built by
220
294
  // joining the raw values around `:` maps both onto one string, and so does one
221
295
  // built around `::`, which the single-colon pair alone does not expose.
@@ -629,7 +703,9 @@ var CASE_BUILDERS = [
629
703
  failureBoundaryCase,
630
704
  failureClearCase,
631
705
  failureTtlCase,
632
- failureAtomicCase
706
+ failureAtomicCase,
707
+ deleteIfCodeCase,
708
+ deleteIfCodeAtomicCase
633
709
  ];
634
710
  function otpStorageContract(factory, options = {}) {
635
711
  const scope = makeScope();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-notification",
3
- "version": "1.4.8",
3
+ "version": "1.4.10",
4
4
  "description": "Multi-channel notification library for NestJS — email, OTP, SMS, push — with pluggable providers and storage, multi-tenant by design, zero runtime dependencies.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",
@@ -154,7 +154,7 @@
154
154
  "eslint": "^10.9.1",
155
155
  "eslint-config-prettier": "^10.1.8",
156
156
  "eslint-import-resolver-typescript": "^4.4.4",
157
- "eslint-plugin-import-x": "^4.17.1",
157
+ "eslint-plugin-import-x": "^4.18.1",
158
158
  "eslint-plugin-prettier": "^5.5.5",
159
159
  "eslint-plugin-security": "^4.0.0",
160
160
  "globals": "^17.6.0",