@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 CHANGED
@@ -5,6 +5,259 @@ All notable changes to `@bymax-one/nest-notification` will be documented in this
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [1.4.2] - 2026-10-31
11
+
12
+ ### Security
13
+
14
+ - **Two spellings of one mailbox are one OTP state.** `OtpService` keyed its state on the recipient
15
+ byte for byte, so `Jane@Acme.com`, `jane@acme.com` and ` jane@acme.com` each had their own resend
16
+ cooldown and their own attempt counter: with `defaultMaxAttempts: 3`, five spellings accepted 15
17
+ wrong guesses and five codes could be minted back to back, and a user who typed another case than
18
+ the one the code was issued for was told it did not exist. The service now keys on the recipient
19
+ with surrounding whitespace trimmed and an email address (a value containing `@`) lower-cased, in
20
+ all five methods and in the audit entry. The message is still delivered to the address exactly as
21
+ supplied, because RFC 5321 §2.4 requires a sender to preserve the local-part's case; only the key
22
+ is folded. A recipient that is not an email is only trimmed.
23
+ - **`EmailService` refuses a tenant that identifies nobody.** `send` and `sendTemplate` accepted an
24
+ empty or whitespace-only `tenantId` and recorded any string in the audit entry verbatim. They now
25
+ refuse it with `notification.invalid_scope_identifier`, as `OtpService` already did.
26
+ - **A control character in a tenant is refused in both services, and in a recipient by `OtpService`.** A newline in an
27
+ identifier reaches the consumer's audit sink and log lines verbatim and forges a second record;
28
+ no legitimate identifier contains one. The refusal never echoes the value.
29
+ - **An OTP code can be stored as a keyed digest instead of in plaintext.** `OtpEntry.code` held the
30
+ code itself, so anyone able to read Redis saw every live code. The new optional
31
+ `otp.codeSecret` (a string of at least 32 UTF-8 bytes, validated at startup, kept with the
32
+ application and not in the store) makes `OtpService` store `hmac-sha256:v1:<hex>`, an HMAC-SHA-256
33
+ of the code, and compare a guess in constant time. It is defence in depth: NIST SP 800-63B-4
34
+ requires hashing for look-up secrets and a separately stored key for password verifiers, and
35
+ says nothing about an out-of-band code. A plain hash would not do, since a six-digit code is
36
+ recovered by trying a million values. Without the option nothing changes except one startup
37
+ warning that codes are stored in plaintext. The delivered email still carries the plaintext
38
+ code, the audit entry carries neither form, and the secret is not a property of the resolved
39
+ options.
40
+ - **Failed verifications now survive a re-issue.** NIST SP 800-63B-4 §3.1.3.2 says generating a new
41
+ authentication secret "SHALL NOT reset the failed authentication count", yet every new code got a
42
+ fresh `defaultMaxAttempts`: with 3 attempts, three wrong guesses, a re-issue after the cooldown
43
+ and three more were all accepted, so the limit only bounded guesses per cooldown. A
44
+ `(tenant, recipient, purpose)` now has a failure counter in the storage: every verification attempt against a
45
+ live code adds one and restarts its lifetime to the purpose's code lifetime, `verify()` counts each attempt before
46
+ comparing the code and refuses once the count passes the ceiling whichever code is live, and a successful verification or `consume()` clears it.
47
+ `RedisOtpStorage` keeps it under `{namespace}:otp_fail:{purpose}:{hash}` with one atomic script.
48
+ A custom `IOtpStorage` opts in with three optional methods, `getFailures`, `recordFailure` and
49
+ `clearFailures`; one without them behaves as before and the module logs one
50
+ `BYMAX_NOTIFICATION_OTP_FAILURES_NOT_CARRIED` warning at startup. The executable contract in
51
+ `./testing` checks the three methods when they are present and passes trivially when they are
52
+ absent.
53
+ - **New error code `notification.otp_manual_delivery_unavailable`** (400; 24 codes, up from 23).
54
+ `generate()` never returns the code, so a manual delivery reads it back from the store, and a
55
+ store that holds a digest has nothing to hand over. With `otp.codeSecret` set, a manual
56
+ delivery (`deliverVia: 'manual'`, or the default when no email channel is configured) is refused
57
+ before the cooldown is taken or anything is stored, instead of succeeding with a code nobody can
58
+ deliver.
59
+
60
+ ### ⚠️ Apply before upgrading
61
+
62
+ - **`otp.codeSecret` is opt-in and loses no live code.** An entry stored in plaintext before the
63
+ secret was set still verifies until it expires. Changing the secret, removing it, or
64
+ downgrading below this version leaves the stored digests unverifiable (`invalid_code`): those
65
+ codes must be requested again. A custom `IOtpStorage` is unaffected, since `OtpEntry.code` is an
66
+ opaque string. Set the secret from a secret store, not from the place the Redis credentials come
67
+ from, or a reader of Redis gets both.
68
+ - **A recipient at the failure ceiling stays locked out until the counter lapses.** With a
69
+ storage that carries failures (the bundled ones), a recipient at the ceiling gets
70
+ `{ valid: false, reason: 'max_attempts' }` for any code, a freshly issued one included, until the
71
+ counter has not been touched for the purpose's code lifetime. Someone who sends wrong
72
+ guesses for another person's address can keep that address locked out; rate-limit the OTP
73
+ endpoints by IP in your controller, as the security checklist says.
74
+ - **If you implement `IOtpStorage` yourself,** add `getFailures`, `recordFailure` and `clearFailures`
75
+ and re-run the contract from `@bymax-one/nest-notification/testing`. Until you do, a re-issued
76
+ code gets a fresh attempt budget and the startup warning says so. Redis users: the new key
77
+ `{namespace}:otp_fail:*` is created on the first wrong guess; nothing is migrated.
78
+ - **One extra storage write in `verify()`.** The stored failure count is the only thing that
79
+ outlives a code, so `verify()` increments it before comparing the code, while a code is live (one atomic script on Redis)
80
+ and refuses once the number passes the ceiling; a code is issued with its own full attempt count and
81
+ the lockout ends exactly when the counter lapses. Storages without the failure methods skip the
82
+ write. A refused verification now reports `max_attempts` where it used to report `not_found` after
83
+ the code was spent.
84
+ - **`otp.codeSecret` and manual delivery do not combine.** Where a flow delivers the code itself
85
+ (`deliverVia: 'manual'`, or no email channel), leave the secret unset or move that flow to email
86
+ delivery; a development setup that reads the code from the store keeps `codeSecret` unset.
87
+ - **A module with the OTP channel and no `otp.codeSecret` logs one warning at startup** (from
88
+ `forRoot` and `forRootAsync`). Set the option, or filter the log line
89
+ `BYMAX_NOTIFICATION_PLAINTEXT_OTP_CODES` if plaintext storage is a decision you have made.
90
+ - **A live OTP issued to a recipient with uppercase letters or surrounding whitespace is re-keyed.**
91
+ The code was stored under the old key, so verifying it after the upgrade reports `not_found`
92
+ until the user asks for a new code. The window is the code's TTL (10 minutes by default).
93
+ - **`getEmail()`, `getOtp()` and `dispatch` refuse a configured-but-unusable channel with 501.** Code
94
+ that branched on `notification.email_provider_not_configured` (500) from a `dispatch` or from a
95
+ send made through `getEmail()` now sees `notification.channel_disabled` (501) there; a send made
96
+ on an injected `EmailService` still raises the former.
97
+ - **The fourteen unused optional peers are gone from `package.json`.** If a tool of yours reads this
98
+ package's peer list to decide what to install (a template, a bootstrap script), install the SDK
99
+ of the adapter you write yourself: `handlebars` for a Handlebars renderer, `@sendgrid/mail` for
100
+ a SendGrid provider, and so on. The package no longer lists them.
101
+ - **A caller that passed a blank `tenantId` to `EmailService` now gets a 400.** Pass the tenant the
102
+ email belongs to.
103
+
104
+ ### Changed
105
+
106
+ - **`RedisLike` accepts an ioredis client as the documentation shows.** `set` was declared as a
107
+ variadic `(key, value, ...args)`, which no overload of ioredis 6's `set` satisfies, so
108
+ `new RedisOtpStorage({ redisClient: new Redis(url) })`, the production example in the README, did
109
+ not compile under `strict`. It now declares the two forms the storage calls: the cooldown lock
110
+ (`EX`, seconds, `NX`) and the in-place rewrite that keeps the expiry (`KEEPTTL`, `XX`). A client
111
+ or double you wrote with a variadic `set` still satisfies it. Nothing changes at runtime.
112
+ - **A channel that is configured but unusable is refused the way `getEnabledChannels()` omits it.**
113
+ When the email provider or the OTP storage reports `isConfigured() === false` (a Resend client
114
+ without its key, an SMTP relay without a host), `getEnabledChannels()` already left the channel
115
+ out, yet `getEmail()` and `getOtp()` still returned the service and the first send failed later.
116
+ They now throw `notification.channel_disabled` (501) with `details.reason`
117
+ (`provider_not_configured` or `storage_not_configured`), and a `dispatch` to that channel is
118
+ refused the same way. The module also logs one `BYMAX_NOTIFICATION_CHANNEL_NOT_USABLE` warning
119
+ per such channel at startup, from `forRoot` and `forRootAsync`. Failing the boot instead is not
120
+ done: an application that starts without its secrets (a preview, a CI job) keeps starting.
121
+ - **Fourteen optional peer dependencies the package never loads are removed.** `package.json`
122
+ declared `@sendgrid/mail`, `@aws-sdk/client-ses`, `@aws-sdk/client-sns`,
123
+ `@aws-sdk/client-dynamodb`, `mailgun.js`, `twilio`, `firebase-admin`, `handlebars`,
124
+ `@react-email/render`, `mjml`, `class-validator`, `class-transformer`, `express` and
125
+ `@types/express` as optional peers, but no source file imports any of them: they were the
126
+ libraries the documentation's adapter examples use. What remains is what the package loads:
127
+ `@nestjs/common`, `@nestjs/core`, `reflect-metadata` and `rxjs` (required), `ioredis`, `resend`,
128
+ `nodemailer` and `react` (optional). Removing an optional peer cannot break an installation; it
129
+ stops advertising a range for packages the library has no code for, and it stops a scan of your
130
+ dependency tree from attributing their advisories to this package. An adapter you write for one
131
+ of those providers keeps depending on its SDK in your application.
132
+
133
+ ### Documentation
134
+
135
+ - **README: three statements corrected against the code.** The subpath diagram drew `react`
136
+ depending on `shared`; `react` imports only `react`, and `server` is the subpath that builds on
137
+ `shared`. The Architecture section said an unconfigured channel is a startup error; it is not —
138
+ `getEnabledChannels()` lists the wired channels, and `getEmail()` / `getOtp()` throw
139
+ `CHANNEL_DISABLED` for one that is not. The SMTP `requireTls` default now reads "`true` unless
140
+ implicit TLS or loopback", which is what the provider does on port 465.
141
+ - **README: the multi-tenant snippet imports what it calls.** The `tenantIdResolver` example called
142
+ `BymaxNotificationModule.forRoot` after importing only a type, so pasted as written it did not
143
+ compile.
144
+ - **README: every error code, who raises it, and which are reserved.** A table lists every code with
145
+ its HTTP status and the component that throws it. The codes the library never throws are marked
146
+ reserved: the four OTP verify outcomes (`verify()` returns the reason instead),
147
+ `email_invalid_recipient` (the recipient is not validated), and the SMS and push codes.
148
+ - **README: the options and members that were only in the technical specification.**
149
+ `consumeOnVerify`, `defaultFromName`, `defaultReplyTo` and `defaultTags` join the Configuration
150
+ table; the `DefaultTemplateRenderer` options, the `EmailService.send` and `OtpService.generate`
151
+ inputs, the `useOtpInput` and `useOtpCountdown` options, the injection tokens,
152
+ `InMemoryOtpStorage.size()` and the `otpStorageContract` usage example are documented.
153
+
154
+ ### Tests
155
+
156
+ - **The README's option-default tables are held to the code.** Two specs parse the Configuration
157
+ table and the SMTP option table and assert every stated default, every "required" marker, the
158
+ OTP length range and the SMTP port, TLS and timeout rules against the resolved options and the
159
+ transport the provider builds, so a drifted cell fails the suite instead of reaching npm.
160
+ - **`check:published` compiles every README snippet against the built types.** It now runs the
161
+ TypeScript API, so a parse error in one snippet no longer hides the semantic errors in the
162
+ others; compiles snippets that do not import the package too; and types the names
163
+ the prose introduces in `scripts/readme-prelude.d.ts`, so a wrong method, option or destructured
164
+ field is an error instead of a call through `any`.
165
+ - **The error table and the renderer options are held to the code.** One spec compares the README
166
+ error table with the catalog and with the source: a code is reserved exactly when no file
167
+ constructs a `NotificationException` with it. Another builds a `DefaultTemplateRenderer` without
168
+ each option and checks the documented default.
169
+ - **`RedisOtpStorage` is exercised against a real Redis on every pull request.** A `Real Redis e2e`
170
+ job starts `redis:8-alpine` with testcontainers and runs the executable `otpStorageContract`,
171
+ 200 concurrent `recordFailure` calls, the hashed `otp_fail` key with its lifetime, and the
172
+ `OtpService` flows (lockout across a re-issue, parallel guesses, a success clearing the counter).
173
+ The unit suite keeps its in-process double; `pnpm test:e2e:redis` runs the same suite locally with
174
+ Docker.
175
+ - **A test guess cannot equal a generated code.** Specs that guessed `000000` against a code the
176
+ service had just generated failed about once in a million runs; they now guess `ABCDEF`, which
177
+ no numeric code can equal.
178
+
179
+ ## [1.4.1] - 2026-10-30
180
+
181
+ ### Security
182
+
183
+ - **Peer ranges raised past published advisories.** `nodemailer` `^9.0.1` → `^10.1.4` (13
184
+ advisories, the highest severity "high", fixed from 10.1.4) and `handlebars` `^4.7.9` →
185
+ `^4.7.10` (3 advisories, the highest "critical", fixed in 4.7.10). A declared peer range states
186
+ which versions this package supports, so the floor no longer admits a version with a known
187
+ advisory. See the note below for what a `nodemailer` 9 consumer has to do.
188
+ - **`OtpService` refuses a blank scope before it reaches the storage.** `generate`, `resend`,
189
+ `verify`, `consume` and `getStatus` now throw `NotificationException` with code
190
+ `INVALID_SCOPE_IDENTIFIER` when `tenantId` or `recipient` is empty, whitespace-only or not a
191
+ string. `details` carries `{ boundary: 'OtpService', parameter, reason }` and never the value.
192
+ When the OTP channel is not configured, `generate`, `resend`, `verify` and `consume` still throw
193
+ `OTP_STORAGE_NOT_CONFIGURED` first; `getStatus` has no such check and validates the scope first.
194
+ - **Reference storages** (`InMemoryOtpStorage`, `RedisOtpStorage`): no change, they already
195
+ threw through `hashTenantRecipient`.
196
+ - **A custom `IOtpStorage` that accepted a blank tenant or recipient:** those calls now throw
197
+ instead of reaching the adapter. Before, such an adapter could share one scope between every
198
+ caller that sent a blank value.
199
+ - **`otpStorageContract` checks the tenant/recipient boundary with a second delimiter.** The
200
+ entry-key and cooldown-key cases now also use a pair that collides when the key is built by
201
+ joining the raw values around `::`. A storage that did so passed the contract before and now
202
+ fails it.
203
+
204
+ ### ⚠️ Apply before upgrading
205
+
206
+ - **A consumer on `nodemailer` 9.** The optional peer range of `nodemailer` moves from `^9.0.1` to `^10.1.4`, so a consumer on
207
+ `nodemailer` 9 has to upgrade to 10.1.4 or later. The only breaking change between the two
208
+ majors is that `nodemailer` 10 requires Node.js 20 or newer ([its changelog](https://github.com/nodemailer/nodemailer/blob/master/CHANGELOG.md),
209
+ 10.0.0); this package already requires Node.js 24. `SmtpEmailProvider` works with both the ESM and
210
+ CommonJS builds of `nodemailer` 10. No 9.x release fixes these advisories: 9.1.1 is the last 9.x and
211
+ still falls inside the vulnerable range of nine of them.
212
+ - **A consumer that brings `handlebars`.** The optional peer range moves from `^4.7.9` to
213
+ `^4.7.10`, so a consumer that uses `handlebars` for a template renderer has to be on 4.7.10 or
214
+ later. This package never imports `handlebars` itself; the range states which versions are
215
+ supported when you provide it.
216
+ - **A consumer with a custom `IOtpStorage`.** `OtpService` now refuses a blank, whitespace-only or
217
+ non-string `tenantId` or `recipient` with `INVALID_SCOPE_IDENTIFIER` before it calls your
218
+ storage. If your callers can pass such a value, validate it before the call, because those calls
219
+ used to reach the adapter. The reference storages already refused them.
220
+
221
+ ### Changed
222
+
223
+ - **The published `dist/` changes in this release; it is not a documentation-only release.**
224
+ `OtpService` gains the scope validation above, `otpStorageContract` gains the second boundary
225
+ pair, and the declaration files carry new doc comments on `NotificationAuditInterceptor` and on
226
+ `GlobalOptions.tenantIdResolver`, plus the export-statement form described next.
227
+ - **Bundler `tsup` 9.** The published JavaScript (`.mjs` and `.cjs`, every subpath) is byte-identical
228
+ to what `tsup` 8 produced from the same source. The declaration files (`.d.ts`, `.d.cts`) differ
229
+ only in how the export list is written: values in one `export { }`, types in a separate
230
+ `export type { }`. Nothing about the exported names or their types changes.
231
+ - Development and CI tooling only, with no effect on the published package: pnpm override floors
232
+ raised; the dev dependency group refreshed; `osv-scanner.toml` time-boxes the advisory
233
+ (`deepmerge`) that has no patched release.
234
+
235
+ ### Documentation
236
+
237
+ - **What the audit interceptor does with a tenant id that identifies nobody (behaviour since 1.4.0).**
238
+ `NotificationAuditInterceptor` refuses a tenant id that is not a string, is empty, or is
239
+ whitespace-only, on every path that produces it: the value `tenantIdResolver` returns, the
240
+ payload's `tenantId` when no resolver is configured, and the payload's `tenantId` when a resolver
241
+ is configured but there is no HTTP request. The 1.4.0 entry only named an empty value from the
242
+ resolver. The refusal does not reach the caller: with `audit.swallowErrors: true` (the default) it
243
+ is swallowed and no audit entry is written; with `false` it surfaces as `AUDIT_LOG_FAILED` with a
244
+ sanitized copy of the refusal as its `cause`. A payload whose `tenantId` is not a string is
245
+ ignored instead: the argument is not recognised as a dispatch, so there is no entry and no error.
246
+ - **README corrections a consumer reads.**
247
+ - `NoOpEmailProvider` logs a masked recipient only, never the subject or the body. The README
248
+ said it logged the subject and the recipient.
249
+ - The module is described as running on Resend or SMTP out of the box, or on any provider you
250
+ implement. The README named SendGrid as if it were bundled.
251
+ - The package has four subpaths, including `./testing`. One README line said three.
252
+ - The multi-tenant example is a header-based resolver, not a JWT claim, and the README now says
253
+ what the audit interceptor does with a tenant id that identifies nobody.
254
+ - The bundle-budget table lists the `testing` budget. The fixed test count and the stale
255
+ error-code count in the exports table (it said 22) are gone.
256
+ - Vulnerability reporting points to GitHub Private Vulnerability Reporting, with email as the
257
+ fallback.
258
+ - Documents that are not part of the package (SECURITY, CONTRIBUTING, CLAUDE.md, AGENTS.md, the
259
+ specification and guides under `docs/`) were brought in line with the code as well.
260
+
8
261
  ## [1.4.0] - 2026-09-04
9
262
 
10
263
  > ### ⚠️ Read before deploying — the version number does not warn you
@@ -688,7 +941,9 @@ rejected at startup rather than failing on the first send.
688
941
 
689
942
  [1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
690
943
  [1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
691
- [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.0...HEAD
944
+ [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.2...HEAD
945
+ [1.4.2]: https://github.com/bymaxone/nest-notification/compare/v1.4.1...v1.4.2
946
+ [1.4.1]: https://github.com/bymaxone/nest-notification/compare/v1.4.0...v1.4.1
692
947
  [1.4.0]: https://github.com/bymaxone/nest-notification/compare/v1.3.1...v1.4.0
693
948
  [1.3.1]: https://github.com/bymaxone/nest-notification/compare/v1.3.0...v1.3.1
694
949
  [1.3.0]: https://github.com/bymaxone/nest-notification/compare/v1.2.2...v1.3.0