@bymax-one/nest-notification 1.2.1 → 1.2.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +83 -10
  2. package/README.md +27 -21
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,75 @@ 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.2.2] - 2026-08-15
9
+
10
+ ### Documentation
11
+
12
+ Code is unchanged: the built `dist/` is byte-identical to 1.2.1, verified by unpacking the
13
+ published tarball and diffing it against a fresh build. This release exists because the 1.2.1
14
+ security note ships inside the package, and two of its statements were wrong in the direction that
15
+ makes a reader feel safer than they are.
16
+
17
+ - **Corrected: where the declaration belongs.** The 1.2.1 note said `@bymax-one/nest-auth` never
18
+ calls `EmailService` itself, so the declaration belonged to "the consumer's own adapter". That
19
+ is false for the shipped wiring. Measured in the published `@bymax-one/nest-auth@1.4.3` bundle:
20
+ `DefaultAuthEmailProvider` is exported, sends through an `AuthEmailSink` whose own typings name
21
+ `EmailService.send` as the intended implementation, and `auditRedactValues` appears **zero**
22
+ times in the bundle. So wherever that bundled provider is the one bound — the wiring `nest-auth`
23
+ intends and the template uses — the call site is inside `nest-auth` rather than in consumer code,
24
+ and a derived backend that then binds a real SMTP or Resend provider inherits the exposed path
25
+ with **no call site of its own to declare at**. The remedy for that population sits in
26
+ `DefaultAuthEmailProvider`, which is the only place that knows both the code it rendered and the
27
+ call it is about to make. A consumer that implements `nest-auth`'s email port itself does own its
28
+ call site, and for that one the original advice held. Credit: the `bymax-one` template seat measured it from the
29
+ consumer's vantage point; `nest-auth` confirmed it against their own bundle.
30
+
31
+ - **Corrected: declared values are not a sufficient control.** The note called declaration "the
32
+ precise control" and the README called it "the only precise control". Both overstate it. A relay
33
+ quotes what it _transmitted_, not what it was handed, and a MIME body travels raw,
34
+ quoted-printable or base64. Measured through `EmailService.send` on this exact build: with the
35
+ code declared in `auditRedactValues`, an error quoting the **base64** of the body is returned
36
+ completely unredacted, and decoding the surviving text yields the OTP in cleartext. The declared
37
+ value cannot match (`123456` does not occur in `MTIzNDU2`) and echo detection cannot match
38
+ either, because it compares the error against the _rendered_ body it holds, not against the
39
+ encoding the relay chose. This is the ceiling of value-list redaction, not a defect in either
40
+ guard: **no list of values closes an encoding gap.**
41
+
42
+ What the guards are, accurately: defence in depth that removes the shapes they can predict.
43
+ Treat provider error text reaching a log as the thing to control, and declared values as
44
+ precision on top of that — not as the barrier.
45
+
46
+ - **Corrected: the README asserted and refuted the same guarantee.** The feature list said "Codes
47
+ are never logged … not into an error message" and the security section promised "every
48
+ occurrence of the code is scrubbed", while the paragraph added by this same patch documents an
49
+ encoded echo surviving both guards. The unconditional claims came first, which is the half a
50
+ skimming reader takes away. They now say what they actually cover: text **this library authors**,
51
+ and every **literal** occurrence — with a pointer to the ceiling for text a provider authors.
52
+ Found by applying a rule a consuming team derived after finding the identical drift in their own
53
+ changelog: a claim written to explain and a claim written to instruct drift apart inside one
54
+ author's head, because the explanation optimises for the point and the instruction for the cases.
55
+ Grep the narrative against the instructions whenever one document carries both. A second sweep
56
+ caught two more of the same shape — the security table's "Code Exposure" row and the
57
+ code-lifetime paragraph — which is the argument for sweeping by claim rather than by the wording
58
+ that happened to appear in the first one found.
59
+
60
+ - The residual risk this leaves is tracked for a behaviour change rather than another note, and
61
+ the shape of that change is open. What the measurements above establish is the direction: value
62
+ redaction is a **blacklist** — it must predict the form the secret takes, and it loses to any
63
+ form it did not predict. Publishing only what a fixed grammar can express — the SMTP basic
64
+ status and, when present, the RFC 3463 enhanced code — is a **whitelist**, and the property that
65
+ makes it safe is that its output is **independent of the secret**, not that its alphabet differs
66
+ from the secret's. The distinction is testable in three lines: the same relay reply publishes
67
+ `550 5.7.1` whether the code was `550571`, `123456` or absent entirely, so an observer learns
68
+ nothing about it. Punctuation-stripping `550 5.7.1` does yield `550571`, the shape of a live
69
+ six-digit code — a coincidence rather than a disclosure, but one with a real operational cost,
70
+ because a log rule alerting on digit runs fires on every such reply. Publishing the codes as
71
+ structured fields rather than interpolated into a message string keeps that cost from arising.
72
+ What stays genuinely open is how much diagnosis a general channel needs: for auth mail the
73
+ provider's prose is never diagnostic, which is why `@bymax-one/nest-auth` publishes none of it,
74
+ while for the same installation's receipts and marketing a `550` content rejection and a `550`
75
+ blocklisted sender call for opposite actions. Nothing here is decided.
76
+
8
77
  ## [1.2.1] - 2026-08-15
9
78
 
10
79
  ### Fixed
@@ -25,19 +94,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
25
94
  the UNDECLARED case fail safe for the measured scenario, since the library knows the body it
26
95
  just handed to the provider even when it does not know which part is secret. Limits, stated
27
96
  plainly: matching is raw and literal (a re-encoded echo is missed) and a bare secret quoted
28
- without surrounding content is shorter than the window and is not caught. Declared values
29
- remain the precise control.
97
+ without surrounding content is shorter than the window and is not caught. Declared values add
98
+ precision where the shape is predictable — but they are NOT a sufficient control either; see
99
+ the 1.2.2 entry for the measurement that shows an encoded echo defeating both.
30
100
  - Declared values travel to the provider as `EmailSendOptions.redactValues`, and
31
101
  `SmtpEmailProvider` scrubs them plus detected body echoes from its `warn` line and thrown
32
102
  message — closing the pre-existing `warn`-level half of the same leak.
33
103
 
34
- **Boundary that this release does NOT close, so the note cannot read as "done":** a
35
- consumer-issued secret is fully covered only when the caller declares it. `@bymax-one/nest-auth`
36
- never calls `EmailService` itself — it defines an email-provider port that the consumer's own
37
- adapter implements — so the declaration belongs to that adapter: whoever calls
38
- `EmailService.send`/`sendTemplate` with a secret should pass it in `auditRedactValues`. Until
39
- then, a bare code echoed WITHOUT surrounding body content remains exposed on that path — the
40
- echo guard needs 16+ contiguous characters of body context to trigger.
104
+ **Boundary that this release does NOT close, so the note cannot read as "done":** declaring a
105
+ consumer-issued secret in `auditRedactValues` removes it only where it appears in the raw,
106
+ literal shape it was declared in — it is not coverage of the secret as such — and a bare code
107
+ echoed WITHOUT surrounding body content is below the echo guard's 16-character window.
108
+ <!-- The two claims this paragraph originally made about WHERE that declaration belongs, and
109
+ about declaration being a sufficient control, were both wrong. See 1.2.2 for the correction and
110
+ the measurements. -->
111
+
112
+ **See the 1.2.2 entry above before relying on this paragraph.**
41
113
 
42
114
  - **Overlapping secrets can no longer leave a fragment behind after redaction.** `redactValues`
43
115
  used to replace value-by-value over its own output, so `['123', '1234']` over `1234` emitted
@@ -442,7 +514,8 @@ rejected at startup rather than failing on the first send.
442
514
 
443
515
  [1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
444
516
  [1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
445
- [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.2.1...HEAD
517
+ [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.2.2...HEAD
518
+ [1.2.2]: https://github.com/bymaxone/nest-notification/compare/v1.2.1...v1.2.2
446
519
  [1.2.1]: https://github.com/bymaxone/nest-notification/compare/v1.2.0...v1.2.1
447
520
  [1.2.0]: https://github.com/bymaxone/nest-notification/compare/v1.1.2...v1.2.0
448
521
  [1.1.2]: https://github.com/bymaxone/nest-notification/compare/v1.1.1...v1.1.2
package/README.md CHANGED
@@ -74,7 +74,7 @@ pnpm add @bymax-one/nest-notification
74
74
  - ✅ **SHA-256 storage keys** — `sha256(tenantId:recipient)`: no recipient PII in a key, no cross-tenant collision
75
75
  - ✅ **`tenantIdResolver`** — the audited tenant comes from a trusted source (a JWT claim, a subdomain, a gateway-checked header), not the payload
76
76
  - ✅ **Opt-in audit log** — a fire-and-forget `INotificationLogRepository` plus a `NotificationAuditInterceptor`; audit failures never break delivery
77
- - ✅ **Codes are never logged** — not to a logger, not to an audit entry, not into an error message, enforced by a regression test
77
+ - ✅ **This library never logs a code** — not to a logger, not to an audit entry, not into an error message it authors, enforced by a regression test. Text a **provider** authors is a separate problem with a documented ceiling: an error quoting the body in another encoding survives every guard, so control whether provider error text reaches your logs at all
78
78
 
79
79
  ### 🧩 Developer Experience
80
80
 
@@ -617,16 +617,20 @@ const tenantIdResolver = (req: NotificationRequest): string =>
617
617
  > [!NOTE]
618
618
  > The resolver governs what the audit interceptor trusts. Service methods still take an explicit `tenantId`: resolve the tenant in your controller and pass it down — there is no hidden override of a method argument.
619
619
 
620
- ### Codes are never written anywhere readable
620
+ ### The library never writes a code anywhere readable
621
+
622
+ Everything below is about text **this library authors**. Text a provider authors is a separate
623
+ problem with a documented ceiling — see [Errors](#errors) — and
624
+ the two must not be read as one guarantee.
621
625
 
622
626
  The library **never** writes a code to a sink that can be read back:
623
627
 
624
628
  - Not to the audit log — an entry is `{ verb, tenantId, recipient, purpose, providerName, … }`, never `code`.
625
629
  - Not to a console or logger line.
626
630
  - Not inside an `errorMessage`, which carries the message only — never a stack trace.
627
- - 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 occurrence of the code 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 is covered too: OTP delivery declares the code via `auditRedactValues`, and `EmailService` redacts it from the entry's `errorMessage`. 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.
631
+ - 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 is covered too: OTP delivery declares the code via `auditRedactValues`, and `EmailService` redacts it from the entry's `errorMessage`. 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.
628
632
 
629
- Codes exist only inside the OTP store, under a TTL, and in process memory for the duration of the request. `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`.
633
+ 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`.
630
634
 
631
635
  ### Attempt ceilings and cooldowns are atomic
632
636
 
@@ -647,22 +651,22 @@ When integrating `@bymax-one/nest-notification` in production, verify each of th
647
651
 
648
652
  ## 🛡️ Security Table
649
653
 
650
- | Layer | Implementation |
651
- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
652
- | Code Generation | `crypto.randomInt` per character over the configured alphabet — uniform at every position, no modulo bias |
653
- | Code Comparison | `crypto.timingSafeEqual` (constant-time), never `===` |
654
- | Storage Keys | `sha256(tenantId:recipient)` — no recipient PII, no cross-tenant collision |
655
- | Attempt Ceiling | Counter spent atomically inside the storage (Redis Lua) — never a service-side read-then-write |
656
- | Resend Cooldown | `SET NX EX` acquire, released only on delivery failure — two concurrent resends cannot both win |
657
- | Code Lifetime | TTL-bound in the store; expiry and absence are reported identically so neither leaks the other |
658
- | Code Exposure | Never logged, never audited, never in an error message or stack trace — asserted by a regression test |
659
- | Recipient PII | Absent from keys; optionally masked before it reaches the audit sink |
660
- | Provider Secrets | The Resend API key, the SMTP password and the Redis client live in private fields; serializing a provider omits them, and a failing SMTP session has its password scrubbed from the error |
661
- | Tenant Isolation | `tenantId` scopes every operation and is resolved from a trusted source, not the payload |
662
- | Template Injection | HTML body escaped on interpolation by the bundled renderer — closes stored XSS through a display name |
663
- | Attachment DoS | Total attachment size rejected against a budget before the provider is called |
664
- | Audit Failures | Fire-and-forget with `swallowErrors` — an audit outage never becomes a delivery outage |
665
- | Supply Chain | `"dependencies": {}`; published with npm provenance (OIDC), CodeQL and OpenSSF Scorecard on every push |
654
+ | Layer | Implementation |
655
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
656
+ | Code Generation | `crypto.randomInt` per character over the configured alphabet — uniform at every position, no modulo bias |
657
+ | Code Comparison | `crypto.timingSafeEqual` (constant-time), never `===` |
658
+ | Storage Keys | `sha256(tenantId:recipient)` — no recipient PII, no cross-tenant collision |
659
+ | Attempt Ceiling | Counter spent atomically inside the storage (Redis Lua) — never a service-side read-then-write |
660
+ | Resend Cooldown | `SET NX EX` acquire, released only on delivery failure — two concurrent resends cannot both win |
661
+ | Code Lifetime | TTL-bound in the store; expiry and absence are reported identically so neither leaks the other |
662
+ | Code Exposure | Never logged, audited, or placed in an error message or stack trace **by this library** — asserted by a regression test. Provider-authored text has a documented ceiling: see [Errors](#errors) |
663
+ | Recipient PII | Absent from keys; optionally masked before it reaches the audit sink |
664
+ | Provider Secrets | The Resend API key, the SMTP password and the Redis client live in private fields; serializing a provider omits them, and a failing SMTP session has its password scrubbed from the error |
665
+ | Tenant Isolation | `tenantId` scopes every operation and is resolved from a trusted source, not the payload |
666
+ | Template Injection | HTML body escaped on interpolation by the bundled renderer — closes stored XSS through a display name |
667
+ | Attachment DoS | Total attachment size rejected against a budget before the provider is called |
668
+ | Audit Failures | Fire-and-forget with `swallowErrors` — an audit outage never becomes a delivery outage |
669
+ | Supply Chain | `"dependencies": {}`; published with npm provenance (OIDC), CodeQL and OpenSSF Scorecard on every push |
666
670
 
667
671
  > [!IMPORTANT]
668
672
  > This package uses **zero external cryptographic dependencies**. All operations use Node.js native `node:crypto`, eliminating supply chain attack vectors for critical security code.
@@ -759,7 +763,9 @@ Error codes are namespaced (`notification.otp_invalid_code`, `notification.otp_c
759
763
 
760
764
  Failures raised by the library carry the underlying error as the native `Error.cause` — a provider's `connect ECONNREFUSED` sits on `exception.cause`, where cause-walking log serializers (e.g. pino's `err`) print it alongside the stable code. The cause is stored as a **log-safe copy**: `name`, `message`, `stack`, and the nested `cause` chain survive (depth-bounded); every other property is dropped, because SDK errors routinely retain the request payload (an axios-style `config.data`) and for an OTP email that payload contains the code. The cause never enters the HTTP response body either: `details` stays reserved for the structured, client-safe context shown above. To attach a cause in your own code, pass the options bag as the third constructor argument — `new NotificationException('EMAIL_SEND_FAILED', { providerName }, { cause: error })`; the positional `(key, details, status, message)` form keeps working.
761
765
 
762
- **If you send a secret through `EmailService` yourself — declare it.** 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; a bare secret echoed without surrounding content is below that window, so declaration remains the only precise control.
766
+ **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.
767
+
768
+ **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, 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.
763
769
 
764
770
  ### Reference adapters
765
771
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-notification",
3
- "version": "1.2.1",
3
+ "version": "1.2.2",
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",