@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/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
|
-
|
|
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.
|
|
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
|