@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 CHANGED
@@ -2,11 +2,146 @@
2
2
 
3
3
  All notable changes to `@bymax-one/nest-notification` will be documented in this file.
4
4
 
5
- The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
- and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
+
7
+ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while this API is
8
+ pre-stable: breaking changes ship in minor and patch releases by explicit `@bymax-one` policy, so a
9
+ version number carries no compatibility information. The **Apply to a derived backend** note, on
10
+ the entries that carry one, is the compatibility contract — read it, not the number.
7
11
 
8
12
  ## [Unreleased]
9
13
 
14
+ ## [1.4.9] - 2026-11-14
15
+
16
+ ### Fixed
17
+
18
+ - **A backing service that is unavailable is answered with 503, not 500.** When the OTP store
19
+ could not be reached, the error of the Redis client went straight to the HTTP layer as an
20
+ unclassified 500, and a failed email send was always 502, whether the provider refused the message or
21
+ could not be reached at all. `OtpService` now wraps its store, and a refused connection, a closed
22
+ client, a timed-out command, an exhausted retry limit, a replica that cannot write or serve
23
+ (`READONLY`, `LOADING`, `MASTERDOWN`), or a cluster that is down or asks for a retry
24
+ (`CLUSTERDOWN`, `TRYAGAIN`) becomes
25
+ `notification.otp_storage_unavailable` (503) with the original error as the log-safe `cause`;
26
+ every other failure of a store, a defect included, passes through unchanged. A failed email send
27
+ keeps `notification.email_send_failed` and answers 503 when the provider could not be reached or
28
+ timed out (a refused connection, a DNS failure, a timeout, or Resend answering 5xx), 502 when it
29
+ answered and refused. The reference providers carry the client's error code onto the error they
30
+ throw, so the status is read from a code and not from the provider's words.
31
+
32
+ ### Security
33
+
34
+ - **A Resend send no longer waits for as long as the platform allows.** `ResendEmailProvider` set no
35
+ timeout of its own, so an endpoint that never answered, or sent headers and stalled the body,
36
+ held the request for as long as the platform allowed. Every send now
37
+ fails at `timeoutMs` (default `15000`, an integer from `1` to `2147483647`; a larger value would
38
+ make Node abort at once), covering the request and the response body, with the fixed reason
39
+ `Resend request timed out after <n> ms`. The SDK is given the abort signal and the call is also
40
+ raced against it, so an older SDK that ignores the signal is bounded too. A timed-out send may
41
+ still have been delivered; the library does not retry.
42
+
43
+ - **An SMTP failure no longer carries the credentials in their base64 form.** The provider removed
44
+ the configured user and password from a relay's error text, but only as written. A relay or a
45
+ client library that quotes the AUTH exchange shows `AUTH PLAIN <token>` or the two LOGIN lines in
46
+ base64, which a literal match cannot see, so they reached the thrown message and the log line.
47
+ The base64 forms of the user, of the password and of the AUTH PLAIN token (an empty authorization
48
+ identity, the user, the password, as nodemailer sends it) are now removed from both, and from the
49
+ error thrown while the transport is built. A short credential over-redacts a message, as it
50
+ already did.
51
+
52
+ - **An SMTP send no longer waits for as long as a trickling relay allows.** The other timeouts
53
+ each bound a phase or an idle socket, so a relay that kept sending bytes could hold a send past
54
+ all of them. `SmtpEmailProvider` now bounds the whole call with `sendTimeoutMs` (default `60000`,
55
+ an integer from `1` to `2147483647`) and fails with the code `ETIMEDOUT`, which the service
56
+ answers with 503. The thrown text is `SMTP send failed: SMTP send timed out after <n> ms`, or the
57
+ fixed `SMTP send failed` when the message body carries a credential. Nodemailer cannot abort a
58
+ send in flight, so a timed-out send may still have been delivered. The connection is left open:
59
+ `socketTimeout` reaps it once the relay goes idle, and a relay that keeps sending holds it until
60
+ the relay ends the connection or the process exits. The library does not retry.
61
+
62
+ - **A failed send no longer blocks the event loop on a large or repeated body.** When a provider
63
+ or relay rejected a send and quoted the message, the echo detector extended every occurrence of
64
+ every window of the error text, which is quadratic in a repeated run, and paid that cost again for
65
+ the plain-text body. The detector now finds the same excerpts in time linear in the error text and
66
+ the body together, and returns the same excerpts. An error text longer than 64 KiB is scrubbed whole instead of examined piece by piece, because the detector's memory grows with it.
67
+ - **`sendTemplate()` refuses an oversized recipient list before it renders the template.**
68
+
69
+ - **`consumeOnVerify` accepts a code once.** `verify()` read the entry, compared it, and deleted it
70
+ in separate steps, so several verifications of the right code running together each returned
71
+ `valid: true`, and a host that creates a session or resets a password on `valid` acted once per
72
+ winner. With `consumeOnVerify: true` the entry is now removed by
73
+ one atomic compare-and-delete in the storage, `IOtpStorage.deleteIfCode`, and exactly one verification wins; the others return `not_found`. The method is given the
74
+ stored value the service read, never the guess, and a code regenerated in between is left alone.
75
+ With `consumeOnVerify: false` several verifications can still each return `valid: true` until the
76
+ host calls `consume()`, which the README now states.
77
+
78
+ - **An OTP is delivered to exactly one mailbox.** The recipient string went to the transport as an
79
+ address list, so `victim@x.com, attacker@evil.example` delivered the code to both, and a list of
80
+ any length made the endpoint send from the host's domain to any number of addresses. With email
81
+ delivery, `OtpService.generate()` and `resend()` now refuse, before a cooldown or a code exists,
82
+ a recipient that is not one plain address (a list, a display name, an angle address, a comment, a
83
+ quoted local part, an IP literal, whitespace or a control character inside it, or more than 254
84
+ characters) with `notification.email_invalid_recipient`. The refusal never echoes the value.
85
+ Internationalized addresses are accepted. Manual delivery is unchanged.
86
+ - **A message addresses at most `email.maxRecipients` mailboxes (default `50`).** `to`, `cc` and
87
+ `bcc` count together, after a `,` or `;` splits a string, and a larger message is refused with
88
+ `notification.email_invalid_recipient` before the provider is called.
89
+
90
+ #### Apply to a derived backend
91
+
92
+ `NOTIFICATION_ERROR_CODES` and `NOTIFICATION_ERROR_DEFINITIONS` gain `OTP_STORAGE_UNAVAILABLE`
93
+ (`notification.otp_storage_unavailable`, 503): a frontend that maps
94
+ every code adds it. A custom `IEmailProvider` that wants its unreachable or timed-out failures
95
+ answered with 503 sets a `code` such as `ECONNREFUSED`, `ETIMEDOUT` or `EUNAVAILABLE` on the error
96
+ it throws; without one the failure stays 502.
97
+
98
+ `ResendEmailProviderOptions` gains the optional `timeoutMs`. A backend that builds a
99
+ `ResendEmailProvider` needs no change; one that substitutes its own Resend client accepts a second
100
+ argument, `{ signal }`, on `emails.send` and may honour it.
101
+
102
+ `SmtpEmailProviderOptions` gains the optional `sendTimeoutMs`. A backend that builds an
103
+ `SmtpEmailProvider` needs no change. **A timed-out send, from `SmtpEmailProvider` and from
104
+ `ResendEmailProvider` alike, may still have been delivered**, so a job that retries a failed send
105
+ can deliver the same message twice. Make the job idempotent, or pass an idempotency key where the
106
+ provider accepts one. The library does not retry.
107
+
108
+ A custom `IOtpStorage` needs no change for the 503: `OtpService` wraps it, and a failure whose
109
+ error carries a network `code` the service recognises (`ECONNREFUSED` and `ETIMEDOUT` are two of
110
+ them), or whose text is one it recognises, is answered with 503, with the storage's own error as
111
+ the `cause`. A failure with any other code or text keeps passing through as before.
112
+
113
+ `IOtpStorage` gains the optional `deleteIfCode(tenantId, recipient, purpose, expectedStored)`, and
114
+ the service constructor throws when `otp.consumeOnVerify` is `true` and the storage lacks it: a
115
+ derived backend with a custom storage implements it (an atomic delete that fires only while the
116
+ stored code equals `expectedStored`, returning whether it removed the entry) or sets
117
+ `consumeOnVerify` to `false`. The `./testing` contract covers it. The bundled `InMemoryOtpStorage` and
118
+ `RedisOtpStorage` implement it, so a backend that uses them needs no change. A storage that
119
+ implements it gives `consumeOnVerify: true` exactly one winning verification; with
120
+ `consumeOnVerify` left `false` the storage needs no change.
121
+
122
+ `EmailChannelOptions` gains the optional `maxRecipients`, and `ResolvedEmailOptions` gains the
123
+ required `maxRecipients`. A backend that builds resolved options by hand adds `maxRecipients: 50`.
124
+ A caller that sent one message to more than 50 recipients, or whose OTP recipient was not one plain
125
+ address, now receives `email_invalid_recipient`; raise `maxRecipients` for a legitimate fan-out.
126
+
127
+ ## [1.4.8] - 2026-11-12
128
+
129
+ ### Documentation
130
+
131
+ - The README is shorter and says only what a consumer needs. It drops a sentence of project
132
+ history and guidance about another library's provider, defines the `otp_code` template once,
133
+ groups the email rows of the Configuration table, and gives Errors its own section with the
134
+ provider-text guidance condensed. A new section lists what the library does not do.
135
+ - The `SmtpEmailProvider` option table, the TLS rationale and the header-injection guard moved to
136
+ [`docs/smtp-provider.md`](https://github.com/bymaxone/nest-notification/blob/main/docs/smtp-provider.md);
137
+ the README keeps a short section and the link.
138
+ - Wording fixes: audit failures are swallowed by default (`audit.swallowErrors`), not
139
+ never; the OTP verify codes are reserved; and the Supply chain row no longer claims a scan on
140
+ every push.
141
+ - A Tech Stack badge row sits between the Security Table and Testing & Quality.
142
+
143
+ `dist/` is unchanged from 1.4.7: no source, declaration or behaviour change.
144
+
10
145
  ## [1.4.7] - 2026-11-07
11
146
 
12
147
  ### Added
@@ -1041,7 +1176,9 @@ rejected at startup rather than failing on the first send.
1041
1176
 
1042
1177
  [1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
1043
1178
  [1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
1044
- [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.7...HEAD
1179
+ [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.9...HEAD
1180
+ [1.4.9]: https://github.com/bymaxone/nest-notification/compare/v1.4.8...v1.4.9
1181
+ [1.4.8]: https://github.com/bymaxone/nest-notification/compare/v1.4.7...v1.4.8
1045
1182
  [1.4.7]: https://github.com/bymaxone/nest-notification/compare/v1.4.6...v1.4.7
1046
1183
  [1.4.6]: https://github.com/bymaxone/nest-notification/compare/v1.4.5...v1.4.6
1047
1184
  [1.4.5]: https://github.com/bymaxone/nest-notification/compare/v1.4.4...v1.4.5