@bymax-one/nest-notification 1.3.0 → 1.3.1
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 +34 -1
- package/README.md +24 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,38 @@ 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
|
+
## [1.3.1] - 2026-08-18
|
|
9
|
+
|
|
10
|
+
### Documentation
|
|
11
|
+
|
|
12
|
+
Code is unchanged: the built `dist/` is byte-identical to 1.3.0, verified by unpacking the
|
|
13
|
+
published tarball and diffing it against a fresh build. This release exists because the README
|
|
14
|
+
ships inside the package and one of its security claims described the behaviour of 1.2.2.
|
|
15
|
+
|
|
16
|
+
- **Corrected: what the OTP path writes to its audit entry.** The README said OTP delivery
|
|
17
|
+
"declares the code via `auditRedactValues`, and `EmailService` redacts it from the entry's
|
|
18
|
+
`errorMessage`". That was true until 1.3.0, which made the OTP path set
|
|
19
|
+
`publishProviderText: false` — so the entry now records the fixed label
|
|
20
|
+
`[provider text withheld]` plus the structured reply codes, and the provider's own words never
|
|
21
|
+
reach it. The declaration remains, as precision for the paths that do publish text.
|
|
22
|
+
- **`publishProviderText` is now documented rather than mentioned in passing.** It appeared once,
|
|
23
|
+
inside a paragraph about the ceiling of redaction, despite being the feature 1.3.0 is named
|
|
24
|
+
after. It has its own section: what the failure carries, the structured fields it publishes, a
|
|
25
|
+
worked example, and the three properties worth knowing before relying on it — the codes are
|
|
26
|
+
independent of the secret, ambiguity resolves to silence, and a code colliding with a declared
|
|
27
|
+
value is dropped.
|
|
28
|
+
- **Documented: the two surfaces name the reply codes differently.** The audit entry carries
|
|
29
|
+
`deliveryStatus` / `deliveryEnhancedStatus`; the exception's `details` carries `status` /
|
|
30
|
+
`enhanced`. The README said they were "the same pair", which would have sent a consumer looking
|
|
31
|
+
for keys that are not there — and it contradicted the worked example three lines below it. Both
|
|
32
|
+
shapes are now named, and the example shows the audit entry alongside the exception. (The
|
|
33
|
+
inconsistency itself is API surface shipped in 1.3.0; unifying the names would be a breaking
|
|
34
|
+
change, so it stays a 1.4.0 question rather than something a patch quietly alters.)
|
|
35
|
+
- Internal docs caught up with the fourth subpath: the subpath tables in `CLAUDE.md` and
|
|
36
|
+
`docs/technical_specification.md` listed three, and `AGENTS.md` described neither the storage
|
|
37
|
+
contract nor the withholding flag. None of these ship, so they did not force this release; they
|
|
38
|
+
are here because the sweep that found the README claim found them too.
|
|
39
|
+
|
|
8
40
|
## [1.3.0] - 2026-08-17
|
|
9
41
|
|
|
10
42
|
### Added
|
|
@@ -573,7 +605,8 @@ rejected at startup rather than failing on the first send.
|
|
|
573
605
|
|
|
574
606
|
[1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
|
|
575
607
|
[1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
|
|
576
|
-
[Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.3.
|
|
608
|
+
[Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.3.1...HEAD
|
|
609
|
+
[1.3.1]: https://github.com/bymaxone/nest-notification/compare/v1.3.0...v1.3.1
|
|
577
610
|
[1.3.0]: https://github.com/bymaxone/nest-notification/compare/v1.2.2...v1.3.0
|
|
578
611
|
[1.2.2]: https://github.com/bymaxone/nest-notification/compare/v1.2.1...v1.2.2
|
|
579
612
|
[1.2.1]: https://github.com/bymaxone/nest-notification/compare/v1.2.0...v1.2.1
|
package/README.md
CHANGED
|
@@ -629,7 +629,7 @@ The library **never** writes a code to a sink that can be read back:
|
|
|
629
629
|
- Not to the audit log — an entry is `{ verb, tenantId, recipient, purpose, providerName, … }`, never `code`.
|
|
630
630
|
- Not to a console or logger line.
|
|
631
631
|
- Not inside an `errorMessage`, which carries the message only — never a stack trace.
|
|
632
|
-
- Not inside a rethrown delivery error: the renderer and the provider both receive the code (template `data`, rendered body), so on a failed delivery every **literal** occurrence of the code — the form it was issued in, which is the form this library's own text carries — is scrubbed to `[redacted]` across the outgoing error chain — message **and** stack at every link, cycle-safe with no depth limit — before the audit write and the rethrow, and a non-`Error` rejection is flattened to a redacted string. The email channel's own `failed` audit entry
|
|
632
|
+
- Not inside a rethrown delivery error: the renderer and the provider both receive the code (template `data`, rendered body), so on a failed delivery every **literal** occurrence of the code — the form it was issued in, which is the form this library's own text carries — is scrubbed to `[redacted]` across the outgoing error chain — message **and** stack at every link, cycle-safe with no depth limit — before the audit write and the rethrow, and a non-`Error` rejection is flattened to a redacted string. The email channel's own `failed` audit entry goes further than redaction: OTP delivery sets `publishProviderText: false`, so that entry records the fixed label `[provider text withheld]` plus the SMTP reply codes a fixed grammar can express — never the provider's own words. It also declares the code via `auditRedactValues`, which stays as precision for the paths that do publish text. Default V8 stack frames carry only function names and source locations, never argument values; the header line (`Error: <message>`) is where a code could ride a stack, and the scrub covers it.
|
|
633
633
|
|
|
634
634
|
Within this library, codes exist only inside the OTP store, under a TTL, and in process memory for the duration of the request — a provider that quotes the body back is outside that boundary, and its ceiling is documented under [Errors](#errors). `audit.maskRecipient` minimizes the recipient before it is persisted (`jane@acme.com` → `j***@acme.com`). A regression test asserts the invariant directly rather than trusting review: `JSON.stringify(auditEntry).includes(code) === false`.
|
|
635
635
|
|
|
@@ -766,6 +766,29 @@ Failures raised by the library carry the underlying error as the native `Error.c
|
|
|
766
766
|
|
|
767
767
|
**If you send a secret through `EmailService` yourself — declare it, and treat the provider's error text as untrusted anyway.** A relay or DLP filter that quotes the rejected content puts the rendered body (and any secret inside it) into the provider error, which rides the `cause` into your logs. Pass `auditRedactValues: [code]` on the send input: the value is scrubbed from the attached `cause`, from the failed-audit `errorMessage`, and — forwarded as `EmailSendOptions.redactValues` — from the provider's own error logging. As defense-in-depth for the undeclared case, any run of 16+ characters of the rendered body detected inside a provider error is redacted automatically.
|
|
768
768
|
|
|
769
|
+
**Withholding provider text — `publishProviderText: false`.** For a message whose body carries a credential, set it on the send input (`EmailService.send` or `sendTemplate`); the built-in OTP delivery already does. The failure then carries **no byte the provider wrote**: no `cause`, and the audit entry's `errorMessage` is the fixed label `[provider text withheld]`.
|
|
770
|
+
|
|
771
|
+
What it publishes instead is what a fixed grammar can express — the basic SMTP reply code and, when present, the RFC 3463 enhanced code — as structured fields. The two surfaces name them differently, so read the right keys: the audit entry carries `deliveryStatus` and `deliveryEnhancedStatus`, while the exception's `details` carries `status` and `enhanced`.
|
|
772
|
+
|
|
773
|
+
```ts
|
|
774
|
+
await emailService.send({
|
|
775
|
+
tenantId,
|
|
776
|
+
to: user.email,
|
|
777
|
+
subject: 'Your code',
|
|
778
|
+
html: rendered,
|
|
779
|
+
publishProviderText: false // this body carries a credential
|
|
780
|
+
})
|
|
781
|
+
// On failure: NotificationException('notification.email_send_failed')
|
|
782
|
+
// details → { providerName: 'smtp', status: 550, enhanced: '5.7.1' }
|
|
783
|
+
// cause → absent
|
|
784
|
+
// Audit entry: { verb: 'failed', errorMessage: '[provider text withheld]',
|
|
785
|
+
// deliveryStatus: 550, deliveryEnhancedStatus: '5.7.1', … }
|
|
786
|
+
```
|
|
787
|
+
|
|
788
|
+
Three properties worth knowing before you rely on it. The published codes are **independent of the secret** — the same reply publishes `550 5.7.1` whether the code was `550571`, `123456` or absent — which is why they are safe to log while the prose is not. **Ambiguity resolves to silence**: a text carrying two different replies publishes neither, so a cause chain cannot have `424` and `242` read as one value. And a code that would carry a **declared** secret is dropped, since this library's invariant is that a code's characters never reach an audit entry.
|
|
789
|
+
|
|
790
|
+
The default is `true`, and deliberately so: for a receipt or a marketing send the provider's message is often the only diagnosis available. The flag is **per send, never global** — one setting cannot serve an OTP path and a marketing path in the same application.
|
|
791
|
+
|
|
769
792
|
**Know the ceiling of both guards.** They remove the shapes they can predict, and a relay quotes what it _transmitted_, not what you handed it — a MIME body travels raw, quoted-printable or base64. A declared `123456` cannot match `MTIzNDU2`, and echo detection compares the error against the rendered body it holds, not against the encoding the relay chose; measured, an error quoting the base64 of the body survives both. No list of values closes an encoding gap. So control whether provider error text reaches your logs at all for secret-bearing sends — pass `publishProviderText: false` on the send input, which withholds every provider-authored byte and publishes only the SMTP reply codes a fixed grammar can express — and use declared values as precision on top of that rather than as the barrier. If you consume `@bymax-one/nest-auth` and bind its bundled `DefaultAuthEmailProvider`, that provider is the call site, so the declaration belongs there rather than in your application code; if you implement `nest-auth`'s email port yourself, your adapter is the call site and the declaration is yours to make.
|
|
770
793
|
|
|
771
794
|
### Reference adapters
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bymax-one/nest-notification",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.1",
|
|
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",
|