@bymax-one/nest-cache 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.2.3] - 2026-10-30
+
+### Changed
+
+- `JsonSerializer.deserialize` throws `DESERIALIZATION_FAILED` with `details` of a fixed `error` text and the
+  `length` of the stored value. `details.preview` and the parser's own message, which quoted the start of the
+  input, are gone. The error code is unchanged; a consumer that read `details.preview` must stop.
+- **Apply to a consumer.** Do not read `details.preview` or `details.error` to debug a decoding
+  failure. Log the error on the server by its code, `cache.deserialization_failed`; the call site already
+  knows the prefix and id it asked for. Use `details.length` when you need a size signal. A backend that
+  sent `details` to its clients needs no other change: the response no longer carries any part of the
+  stored value.
+- Apart from that, nothing you execute changes.
+
+### Documentation
+
+- `README.md`, `docs/technical_specification.md` and the contributor documents state that
+  `KeyBuilder` validates `prefix` and `id` only for emptiness. A separator inside either
+  collides (`build('a', 'b:c')` and `build('a:b', 'c')` both give `app:a:b:c`), and a glob
+  metacharacter in `prefix` widens `keys()` and `scan()` within the namespace. Behaviour is
+  unchanged. Keys are unambiguous only for a single-character separator that appears in neither field; encoding each field with `encodeURIComponent` provides that for a separator it escapes and never emits, such as the default `':'`.
+- Contributor and security documents match the current tooling: pnpm 11, the admin
+  read-only check in the verification chain, mutation testing after merge and weekly, and
+  how dependency advisories are handled.
+
+### Security
+
+- **A non-JSON stored value no longer appears in the exception body.** `CacheException` extends
+  `HttpException`, so a default Nest filter sends `details` to the HTTP client. A cached value that was
+  not JSON (written by another writer, or by another serializer) leaked up to 100 characters of itself
+  through `details.preview`, and the start of it through `details.error`. It could carry PII or a token.
+  Only a malformed entry triggers it; a valid JSON value never does.
+- Dependency advisories in development-only transitive dependencies are fixed by raising the
+  `overrides` floors in `pnpm-workspace.yaml`. None of them ships: the package
+  publishes with `"dependencies": {}`, so no consumer was exposed to these advisories.
+- `GHSA-gcqx-w48m-w2h4` (`deepmerge`, reached only through `jest-config`) has no patched
+  release. It is suppressed in `osv-scanner.toml` until 2027-01-27 and nowhere else.
+
+### Internal
+
+- Development dependencies updated within their ranges; GitHub Actions bumped.
+
 ## [1.2.2] - 2026-09-04
 
 ### Changed
@@ -350,6 +394,8 @@ type or export moved.
 - Published with npm OIDC provenance — no long-lived tokens
 - Zero direct runtime dependencies (`dependencies: {}`) — `ioredis` and NestJS via peer deps
 
+[Unreleased]: https://github.com/bymaxone/nest-cache/compare/v1.2.3...HEAD
+[1.2.3]: https://github.com/bymaxone/nest-cache/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/bymaxone/nest-cache/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-cache/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-cache/compare/v1.1.0...v1.2.0

package/README.md

@@ -47,7 +47,7 @@ so you control exact versions and the supply-chain surface stays minimal.
 - **🧬 Typed get/set** — `get<T>` / `set<T>` go through a pluggable `ISerializer` (JSON by default). Deserialization **fails closed** — a malformed payload throws `CacheException`, never a half-decoded value.
 - **📡 Batteries included** — Pub/Sub on namespaced channels and a Lua script manager (`EVALSHA` + `NOSCRIPT` fallback) ship in the box, on top of the full string/hash/set/numeric command surface.
 - **♻️ Lifecycle done right** — singleton connection with `OnModuleInit` / `OnModuleDestroy`, bounded retry strategy, `READONLY`-failover reconnect, and a graceful `quit()` with shutdown timeout.
-- **🔌 Bring your own observability** — connection events surface through an `events.onEvent` callback; plug in [`@bymax-one/nest-logger`](https://github.com/bymaxone/nest-logger) or your metrics layer. No observability peer deps forced on you.
+- **🔌 Bring your own observability** — connection events and Pub/Sub handler failures surface through an `events.onEvent` callback; plug in [`@bymax-one/nest-logger`](https://github.com/bymaxone/nest-logger) or your metrics layer. No observability peer deps forced on you.
 
 ```
 pnpm add @bymax-one/nest-cache ioredis
@@ -69,21 +69,21 @@ pnpm add @bymax-one/nest-cache ioredis
 - ✅ **Automatic namespacing** — the key builder enforces tenant/feature isolation; no manual string concatenation
 - ✅ **Namespaced channels** — Pub/Sub channels are composed through the same builder as keys
 - ✅ **Surgical flush** — `flushNamespace()` scans only `{namespace}:*`, never another namespace's keys
-- ✅ **Validated at bootstrap** — an empty namespace, or one containing the key separator, fails module initialization
+- ✅ **Validated at bootstrap** — an empty namespace, an empty key separator, or a namespace containing the key separator or a Redis glob metacharacter (`*`, `?`, `[`, `\`) fails module initialization
 
 ### ⚙️ Reliability & Topology
 
 - ✅ **Multi-topology** — standalone, Sentinel, and Cluster modes from the same options shape
 - ✅ **Managed lifecycle** — singleton connection via `OnModuleInit` / `OnModuleDestroy`, graceful `quit()` with a shutdown timeout
 - ✅ **Bounded retries** — `maxRetriesPerRequest` and a reconnect policy that triggers on `READONLY` replica failover
-- ✅ **Connection events** — `connect` / `ready` / `error` / `close` / `reconnecting` / `end` surfaced via `events.onEvent`
+- ✅ **Connection events** — `connect` / `ready` / `error` / `close` / `reconnecting` / `end` surfaced via `events.onEvent`, which also receives Pub/Sub handler and deserialization failures as `'error'` with `reason: 'handler_error'`
 - ✅ **Health checks** — `isHealthy()` / `ping()` / `info()` for readiness and liveness endpoints
 
 ### 🛡️ Safety
 
 - ✅ **Fail-closed serialization** — malformed payloads raise `CacheException(DESERIALIZATION_FAILED)`, never a partial value
 - ✅ **Production flush guard** — `flushNamespace()` is blocked under `NODE_ENV=production` unless explicitly allowed
-- ✅ **Secrets never echoed** — connection URLs and cached values are kept out of error `details`; previews are truncated
+- ✅ **Secrets never echoed** — connection URLs and cached values are kept out of error `details`; no part of a stored value is ever echoed
 - ✅ **Script bodies are registered, not interpolated** — call sites pass a name plus keys/args, never Lua source
 
 ### 🧩 Developer Experience
@@ -248,18 +248,25 @@ Keys resolve to `app:user-profile:<userId>` — namespaced automatically.
 
 ## ⚙️ Configuration
 
-| Option              | Type                                      | Default          | Description                                                        |
-| ------------------- | ----------------------------------------- | ---------------- | ------------------------------------------------------------------ |
-| `mode`              | `'standalone' \| 'sentinel' \| 'cluster'` | `'standalone'`   | Redis topology                                                     |
-| `connection.url`    | `string`                                  | —                | `redis://` / `rediss://` URL (overrides discrete host/port fields) |
-| `connection.tls`    | `tls.ConnectionOptions`                   | —                | TLS options for `rediss://`                                        |
-| `namespace`         | `string`                                  | `'app'`          | Key prefix for tenant/feature isolation                            |
-| `serializer`        | `ISerializer`                             | `JsonSerializer` | Value encoding/decoding (plug MsgPack, CBOR, etc.)                 |
-| `events.onEvent`    | `(event, data) => void`                   | —                | Connection-event hook (plug a logger or metrics)                   |
-| `scripts`           | `IScriptDefinition[]`                     | `[]`             | Lua scripts to preload on init                                     |
-| `shutdownTimeoutMs` | `number`                                  | `5000`           | Graceful `quit()` timeout before forced `disconnect()`             |
-
-Both `forRoot(options)` (synchronous) and `forRootAsync({ useFactory, inject, imports })` are supported. The module registers globally by default — pass `isGlobal: false` to scope it to the importing module.
+| Option                   | Type                                      | Default          | Description                                                                                                                                                                                |
+| ------------------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mode`                   | `'standalone' \| 'sentinel' \| 'cluster'` | `'standalone'`   | Redis topology                                                                                                                                                                             |
+| `connection.url`         | `string`                                  | —                | `redis://` / `rediss://` URL (overrides discrete host/port fields)                                                                                                                         |
+| `connection.tls`         | `tls.ConnectionOptions`                   | —                | TLS options for `rediss://`                                                                                                                                                                |
+| `namespace`              | `string`                                  | `'app'`          | Key prefix for tenant/feature isolation                                                                                                                                                    |
+| `serializer`             | `ISerializer`                             | `JsonSerializer` | Value encoding/decoding (plug MsgPack, CBOR, etc.)                                                                                                                                         |
+| `events.onEvent`         | `(event, data) => void`                   | —                | Lifecycle and Pub/Sub failure hook (plug a logger or metrics); receives connection events, and `'error'` with `reason: 'handler_error'` when a subscriber handler or deserialization fails |
+| `scripts`                | `IScriptDefinition[]`                     | —                | Lua scripts to preload on init                                                                                                                                                             |
+| `shutdownTimeoutMs`      | `number`                                  | `5000`           | Graceful `quit()` timeout before forced `disconnect()` (minimum `100`)                                                                                                                     |
+| `keySeparator`           | `string`                                  | `':'`            | Separator between namespace, prefix and id segments                                                                                                                                        |
+| `allowFlushInProduction` | `boolean`                                 | `false`          | Allows `flushNamespace()` when `NODE_ENV=production`                                                                                                                                       |
+| `isGlobal`               | `boolean`                                 | `true`           | Register the module globally                                                                                                                                                               |
+| `sentinel`               | `{ sentinels, name, ... }`                | —                | Sentinel connection block; required when `mode: 'sentinel'`                                                                                                                                |
+| `cluster`                | `{ nodes, options? }`                     | —                | Cluster connection block; required when `mode: 'cluster'`                                                                                                                                  |
+
+`connection` also accepts `host`, `port`, `password`, `db`, `username`, `lazyConnect`, `connectTimeout` (minimum `100`), `commandTimeout`, `maxRetriesPerRequest`, `enableReadyCheck`, `enableOfflineQueue`, `retryStrategy`, `reconnectOnError`, `keepAlive`, `noDelay` and `family`; `url` takes precedence over the discrete fields.
+
+Both `forRoot(options)` (synchronous) and `forRootAsync({ useFactory, inject, imports })` are supported. The module registers globally by default — pass `isGlobal: false` to scope it to the importing module. With `forRootAsync`, `isGlobal` is read at the call site (`forRootAsync({ isGlobal, ... })`); a value returned from `useFactory` has no effect.
 
 ---
 
@@ -271,6 +278,26 @@ keeps tenants and features isolated and makes `flushNamespace()` surgical. Reach
 `getClient()` to set raw, un-namespaced keys is supported as an escape hatch but documented as an
 anti-pattern.
 
+`prefix` and `id` are supplied by the caller and the library validates them only for emptiness
+(`INVALID_KEY`); it does **not** reject the separator or glob characters inside them. Two
+consequences follow:
+
+- **Separator collision.** `build('a', 'b:c')` and `build('a:b', 'c')` both produce `app:a:b:c`, so
+  two different `(prefix, id)` pairs address the same key.
+- **Glob widening.** `keys(prefix, pattern)` and `scan(prefix, pattern)` pass the composed key to
+  Redis as a match pattern, so a glob metacharacter (`*`, `?`, `[`, `\`) in `prefix` can match keys
+  outside that prefix, still within the namespace. Single-key commands (`get`, `set`, `del`, ...)
+  treat the key literally and are not affected; `flushNamespace()` uses only the validated namespace.
+
+This is documentation only; behavior is unchanged. When a `prefix` or `id` comes from untrusted
+input, encode each field, for example `cache.get(encodeURIComponent(prefix), encodeURIComponent(id))`.
+Keys are unambiguous only when `keySeparator` is a single character that appears in neither `prefix`
+nor `id`. Per-field encoding guarantees that for a separator `encodeURIComponent` escapes and never
+emits: the default `':'` qualifies; `%` and `- _ . ! ~ * ' ( )` do not, so for them reject the
+separator in the fields. A multi-character separator can straddle a field boundary (with `'aa'`,
+`('ba', 'c')` and `('b', 'ac')` build the same key), so keep a single character. A `prefix` used with
+`keys()` / `scan()` must also avoid glob characters (`*`, `?`, `[`, `\`).
+
 ---
 
 ## 📡 Pub/Sub
@@ -575,7 +602,7 @@ A cache sits between your application and every value it has ever computed, so t
 
 ### Namespace isolation is structural
 
-Every key and every Pub/Sub channel is composed through `KeyBuilder`, which prepends `{namespace}{separator}` before the command reaches Redis. `CacheService.get('user-profile', '42')` can only ever read `app:user-profile:42` — there is no code path through the typed API that emits a bare key.
+Every key and every Pub/Sub channel is composed through `KeyBuilder`, which prepends `{namespace}{separator}` before the command reaches Redis. With fixed literals, `CacheService.get('user-profile', '42')` reads `app:user-profile:42` — there is no code path through the typed API that emits a bare key. The namespace is the isolation boundary; the library does not constrain `prefix` and `id` beyond non-emptiness.
 
 The namespace itself is validated at module bootstrap, not at call time:
 
@@ -583,10 +610,14 @@ The namespace itself is validated at module bootstrap, not at call time:
 | --------------------------------------- | ---------------------------------------------------------------- |
 | Empty or whitespace-only namespace      | `CacheException(INVALID_NAMESPACE)` — the module fails to start  |
 | Namespace containing the key separator  | `CacheException(INVALID_NAMESPACE)` — prevents prefix collisions |
+| Empty key separator                     | `CacheException(INVALID_NAMESPACE)` — the module fails to start  |
+| Namespace containing `*`, `?`, `[`, `\` | `CacheException(INVALID_NAMESPACE)` — see the glob section below |
 | Empty `prefix` or `id` at the call site | `CacheException(INVALID_KEY)` — no key is sent to Redis          |
 
 A namespace containing the separator is rejected because `namespace: 'a:b'` and `namespace: 'a'` with prefix `b` would resolve to the same keyspace — a tenant boundary that reads as isolated but is not.
 
+The same collision exists below the namespace and is **not** enforced by the library: `prefix` and `id` are validated only for emptiness, so `build('a', 'b:c')` and `build('a:b', 'c')` both give `app:a:b:c`, and a glob metacharacter in `prefix` widens `keys()` / `scan()` within the namespace. Behavior is unchanged; keys are unambiguous only for a single-character `keySeparator` that appears in neither `prefix` nor `id`: encode untrusted values per field with `encodeURIComponent` only when the separator is one it escapes and never emits (the default `':'` is; `%` and `- _ . ! ~ * ' ( )` are not), otherwise reject the separator in them; a multi-character separator can straddle a field boundary, so keep a single character; reject glob characters in `prefix`.
+
 ### Deserialization fails closed
 
 `JsonSerializer.deserialize` throws `CacheException(DESERIALIZATION_FAILED)` on any payload that is not valid JSON. It never returns `undefined`, never returns a partial object, and never lets a corrupted entry masquerade as a valid `T`. The same contract is required of any custom `ISerializer` — fail-closed is the invariant, not the default implementation's private choice.
@@ -599,7 +630,7 @@ Error `details` are built to be safe to log:
 
 - A malformed `connection.url` throws `CONNECTION_FAILED` with `reason: 'invalid connection.url'` — the URL is omitted, because it may embed a password.
 - `SERIALIZATION_FAILED` carries the encoder's message, never the value being encoded.
-- `DESERIALIZATION_FAILED` carries a `preview` of the raw payload truncated to **100 characters** with an ellipsis — enough to debug a codec mismatch, bounded so a cached record full of PII is not copied into a log line.
+- `DESERIALIZATION_FAILED` carries a fixed `error` text and the `length` of the stored value, and nothing from its content — not a preview, not the parser's message, which quotes the start of its input. The exception is an `HttpException`, so a default Nest filter sends `details` to the HTTP client; a cached record holding PII or a token must never reach it.
 
 ### Destructive operations are guarded in production
 
@@ -624,6 +655,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 - `namespace` is distinct per tenant or per application — it is the isolation boundary, and a shared value makes every other guarantee moot
 - `allowFlushInProduction` stays unset; if it is on, the reason belongs in a security review
 - `getClient()` and `pipeline()` call sites are audited — they are the only paths that bypass namespacing
+- `prefix` and `id` that derive from untrusted input are encoded per field (`encodeURIComponent`) — the library checks them only for emptiness, so a separator inside either collides keys and a glob character in `prefix` widens `keys()` / `scan()`; keys are unambiguous only for a single-character `keySeparator` absent from both fields; per-field `encodeURIComponent` provides that only for a separator it escapes and never emits (the default `':'`; not `%` or `- _ . ! ~ * ' ( )`), otherwise the separator must be rejected, and a multi-character separator cannot be made safe that way; glob characters in `prefix` must be rejected
 - Connection credentials come from the environment (`config.getOrThrow('REDIS_URL')`), never from a URL literal in module options in source control
 - `rediss://` (or an explicit `connection.tls`) is used for any Redis reachable off-host
 - Values that must not be readable by whoever can read Redis are encrypted by the application (or a custom `ISerializer`) before they are cached — the library stores what you hand it
@@ -636,22 +668,22 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 
 ## 🛡️ Security Table
 
-| Layer                 | Implementation                                                                                                              |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Tenant Isolation      | Every key and channel composed by `KeyBuilder` as `{namespace}{sep}{prefix}{sep}{id}` — no bare-key path in the API         |
-| Namespace Validation  | Empty, separator-containing, or glob-metacharacter namespace rejected at bootstrap (`INVALID_NAMESPACE`)                    |
-| Admin Scope Allowlist | Scopes declared at wiring, validated and frozen; a caller names a scope by id and can never supply a match pattern          |
-| Admin Read-Only       | The `/admin` subpath issues no mutating command — enforced by the `check:admin-readonly` build gate, not by convention      |
-| Key Validation        | Empty `prefix` / `id` rejected before the command is issued (`INVALID_KEY`)                                                 |
-| Deserialization       | Fails closed — `DESERIALIZATION_FAILED`; never a partial or wrongly-typed value                                             |
-| Serialization         | Top-level `undefined` / function / symbol rejected; the value is never echoed into `details`                                |
-| Error Payloads        | Connection URLs omitted (may embed credentials); raw payload previews truncated to 100 characters                           |
-| Destructive Ops       | `flushNamespace()` blocked under `NODE_ENV=production` unless `allowFlushInProduction`; `SCAN` + `UNLINK`, namespace-scoped |
-| Lua Execution         | Scripts registered by name; call sites pass keys/args only — request input never reaches a script body                      |
-| Cluster Safety        | `scan` / `flushNamespace` / `getClient` throw `UNSUPPORTED_IN_CLUSTER` instead of acting on a single node                   |
-| Transport             | `rediss://` sets TLS on the client; explicit `connection.tls` supported for custom CA / mTLS                                |
-| Connection Resilience | Bounded `maxRetriesPerRequest`, `READONLY`-failover reconnect, graceful `quit()` with a shutdown timeout                    |
-| Supply Chain          | `"dependencies": {}` — no transitive runtime packages of the library's own choosing; published with npm provenance          |
+| Layer                 | Implementation                                                                                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tenant Isolation      | Every key and channel composed by `KeyBuilder` as `{namespace}{sep}{prefix}{sep}{id}` — no bare-key path in the API                                              |
+| Namespace Validation  | Empty, separator-containing, or glob-metacharacter namespace rejected at bootstrap (`INVALID_NAMESPACE`)                                                         |
+| Admin Scope Allowlist | Scopes declared at wiring, validated and frozen; a caller names a scope by id and can never supply a match pattern                                               |
+| Admin Read-Only       | The `/admin` subpath issues no mutating command — enforced by the `check:admin-readonly` build gate, not by convention                                           |
+| Key Validation        | Empty `prefix` / `id` rejected before the command is issued (`INVALID_KEY`); emptiness only — separators and glob characters in `prefix` / `id` are not rejected |
+| Deserialization       | Fails closed — `DESERIALIZATION_FAILED`; never a partial or wrongly-typed value                                                                                  |
+| Serialization         | Top-level `undefined` / function / symbol rejected; the value is never echoed into `details`                                                                     |
+| Error Payloads        | Connection URLs omitted (may embed credentials); a stored value is never echoed (a fixed text and its length only)                                               |
+| Destructive Ops       | `flushNamespace()` blocked under `NODE_ENV=production` unless `allowFlushInProduction`; `SCAN` + `UNLINK`, namespace-scoped                                      |
+| Lua Execution         | Scripts registered by name; call sites pass keys/args only — request input never reaches a script body                                                           |
+| Cluster Safety        | `scan` / `flushNamespace` / `getClient` throw `UNSUPPORTED_IN_CLUSTER` instead of acting on a single node                                                        |
+| Transport             | `rediss://` sets TLS on the client; explicit `connection.tls` supported for custom CA / mTLS                                                                     |
+| Connection Resilience | Bounded `maxRetriesPerRequest`, `READONLY`-failover reconnect, graceful `quit()` with a shutdown timeout                                                         |
+| Supply Chain          | `"dependencies": {}` — no transitive runtime packages of the library's own choosing; published with npm provenance                                               |
 
 > [!IMPORTANT]
 > The namespace is the isolation boundary. Anything reached through `getClient()` or `pipeline()` sits outside it — those call sites are where cross-tenant reads get introduced.
@@ -666,7 +698,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 [![Node.js](https://img.shields.io/badge/Node.js-24-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![Jest](https://img.shields.io/badge/Jest-30-C21325?style=flat-square&logo=jest)](https://jestjs.io)
 [![Stryker](https://img.shields.io/badge/Stryker-Mutation_Testing-red?style=flat-square)](https://stryker-mutator.io)
-[![pnpm](https://img.shields.io/badge/pnpm-10-F69220?style=flat-square&logo=pnpm&logoColor=white)](https://pnpm.io)
+[![pnpm](https://img.shields.io/badge/pnpm-11-F69220?style=flat-square&logo=pnpm&logoColor=white)](https://pnpm.io)
 [![tsup](https://img.shields.io/badge/tsup-8-orange?style=flat-square)](https://tsup.egoist.dev)
 
 ---
@@ -676,7 +708,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 A cache is consulted on the hot path of every request that touches it, so the suite is held to a bar beyond "it runs" — every behavior is pinned so that a regression **fails a test**.
 
 - ✅ **100% line coverage** — statements, branches, functions, and lines, enforced by `jest.coverage.config.ts` as a pre-publish gate, not a target
-- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 100` and `ignoreStatic: false`; 441 killed, 6 timed out, **0 survived**, and [documented in full](./docs/mutation_testing_results.md)
+- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 100` and `ignoreStatic: false`, **0 survived**, and [documented in full](./docs/mutation_testing_results.md)
 - ✅ **One documented equivalent** — the production source carries a single `// Stryker disable` directive, on `configurable: false` of the withheld connection accessor, genuinely equivalent because the resolved options are frozen on the way out (freezing already makes every property non-configurable); `check:mutants` proves it parses and carries its reason, so the score is an accounting rather than a number
 - ✅ **No real Redis in unit tests** — `ioredis-mock` throughout; e2e tests exercise the wired module through `@nestjs/testing` and Testcontainers against a real Redis for connection lifecycle, Pub/Sub, and Lua scripts
 - ✅ **Published-package smoke test** — `scripts/dogfood-smoke-test.mjs` validates exports, tarball shape, and a consumer install before tagging
@@ -685,7 +717,7 @@ A cache is consulted on the hot path of every request that touches it, so the su
 pnpm test          # unit tests (Jest)
 pnpm test:e2e      # end-to-end tests (@nestjs/testing + Testcontainers)
 pnpm test:cov:all  # full coverage gate (100% statements/branches/functions/lines)
-pnpm mutation      # Stryker mutation testing (95% break gate)
+pnpm mutation      # Stryker mutation testing (100% break gate)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 ```
@@ -732,23 +764,27 @@ pnpm lint          # ESLint
 
 All errors are instances of `CacheException` and carry a stable `code` string from `CACHE_ERROR_CODES`:
 
-| Code                                 | HTTP | When thrown                                                     |
-| ------------------------------------ | ---- | --------------------------------------------------------------- |
-| `cache.connection_failed`            | 500  | Cannot connect after retries                                    |
-| `cache.command_timeout`              | 504  | Command exceeded `commandTimeout`                               |
-| `cache.connection_lost`              | 503  | Connection dropped during an in-flight operation                |
-| `cache.deserialization_failed`       | 500  | Malformed payload in `get<T>`                                   |
-| `cache.serialization_failed`         | 500  | Unserializable value in `set<T>`                                |
-| `cache.invalid_key`                  | 400  | Empty prefix or id passed to `build` / `applyNamespace`         |
-| `cache.invalid_namespace`            | 500  | Empty or separator-containing namespace                         |
-| `cache.script_not_registered`        | 500  | `eval(name)` before `register(name)`                            |
-| `cache.script_execution_failed`      | 500  | Lua runtime error or NOSCRIPT retry failure                     |
-| `cache.script_registry_missing`      | 500  | `eval` called when no `ScriptManagerService` is wired           |
-| `cache.flush_disabled_in_production` | 403  | `flushNamespace()` in prod without `allowFlushInProduction`     |
-| `cache.unsupported_in_cluster`       | 500  | `scan`, `flushNamespace`, or `getClient` called in cluster mode |
-| `cache.cluster_misconfigured`        | 500  | `mode: 'cluster'` without `cluster.nodes`                       |
-| `cache.sentinel_misconfigured`       | 500  | `mode: 'sentinel'` without `sentinel.sentinels`/`name`          |
-| `cache.shutdown_timeout`             | 500  | `quit()` exceeded `shutdownTimeoutMs`                           |
+| Code                                 | HTTP | When thrown                                                                                                                               |
+| ------------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `cache.connection_failed`            | 500  | Cannot connect after retries; also bootstrap validation of `connection` and timeouts                                                      |
+| `cache.command_timeout`              | 504  | Reserved; not currently thrown by the library                                                                                             |
+| `cache.connection_lost`              | 503  | Reserved; not currently thrown by the library                                                                                             |
+| `cache.deserialization_failed`       | 500  | Malformed payload in `get<T>`                                                                                                             |
+| `cache.serialization_failed`         | 500  | Unserializable value in `set<T>`                                                                                                          |
+| `cache.invalid_key`                  | 400  | Empty prefix or id (`build`), or empty key (`applyNamespace`)                                                                             |
+| `cache.invalid_namespace`            | 500  | Empty or whitespace-only namespace, empty `keySeparator`, namespace containing the separator or a glob metacharacter (`*`, `?`, `[`, `\`) |
+| `cache.script_not_registered`        | 500  | `eval(name)` before `register(name)`                                                                                                      |
+| `cache.script_execution_failed`      | 500  | Lua runtime error or NOSCRIPT retry failure                                                                                               |
+| `cache.script_registry_missing`      | 500  | `eval` called when no `ScriptManagerService` is wired                                                                                     |
+| `cache.flush_disabled_in_production` | 403  | `flushNamespace()` in prod without `allowFlushInProduction`                                                                               |
+| `cache.unsupported_in_cluster`       | 500  | `scan`, `flushNamespace`, or `getClient` called in cluster mode                                                                           |
+| `cache.cluster_misconfigured`        | 500  | `mode: 'cluster'` without `cluster.nodes`                                                                                                 |
+| `cache.sentinel_misconfigured`       | 500  | `mode: 'sentinel'` without `sentinel.sentinels`/`name`                                                                                    |
+| `cache.shutdown_timeout`             | 500  | `quit()` exceeded `shutdownTimeoutMs`                                                                                                     |
+| `cache.invalid_scope`                | 500  | `/admin` scope allowlist invalid at wiring                                                                                                |
+| `cache.scope_not_found`              | 500  | `/admin` call named an undeclared scope id                                                                                                |
+| `cache.scope_not_readable`           | 500  | Reserved; not currently thrown (unreadable scopes return `withheld`)                                                                      |
+| `cache.key_not_in_scope`             | 500  | `/admin` call named a key outside the named scope                                                                                         |
 
 Full catalog and HTTP status mapping: [`docs/technical_specification.md §12`](./docs/technical_specification.md).
 
@@ -775,7 +811,7 @@ See §13 of the [technical specification](./docs/technical_specification.md) for
 Contributions are welcome. Development follows the Bymax coding standards:
 
 - TypeScript strict (`noImplicitAny`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`)
-- TDD with a 100% coverage gate and a 95% mutation break threshold
+- TDD with a 100% coverage gate and a 100% mutation break threshold
 - Conventional Commits enforced by commitlint + husky
 - No direct dependencies — peer deps only
 - All boolean identifiers prefixed with `is / has / should / can`
@@ -801,7 +837,7 @@ pnpm typecheck
 Run the full gate before opening a PR:
 
 ```bash
-pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size
+pnpm typecheck && pnpm lint && pnpm check:admin-readonly && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:exports
 ```
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for the full process.

package/dist/server/index.cjs

@@ -711,7 +711,7 @@ exports.KeyBuilder = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(BYMAX_CACHE_OPTIONS))
 ], exports.KeyBuilder);
-var MAX_PREVIEW_LENGTH = 100;
+var DESERIALIZATION_ERROR = "stored value is not valid JSON";
 var extractErrorMessage = (err) => err instanceof Error ? err.message : String(err);
 exports.JsonSerializer = class JsonSerializer {
   /**
@@ -753,17 +753,17 @@ exports.JsonSerializer = class JsonSerializer {
    * @param raw - The JSON string to decode.
    * @returns The decoded value, typed as `T`.
    * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-   *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-   *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-   *   leaking a large payload that may contain PII.
+   *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+   *   part of the stored value is echoed, as it may carry PII or a credential
+   *   (CLAUDE.md §4).
    */
   deserialize(raw) {
     try {
       return JSON.parse(raw);
-    } catch (err) {
+    } catch {
       throw new CacheException(CACHE_ERROR_CODES.DESERIALIZATION_FAILED, {
-        error: extractErrorMessage(err),
-        preview: raw.length > MAX_PREVIEW_LENGTH ? `${raw.substring(0, MAX_PREVIEW_LENGTH)}...` : raw
+        error: DESERIALIZATION_ERROR,
+        length: raw.length
       });
     }
   }

package/dist/server/index.d.cts

@@ -971,9 +971,9 @@ declare class JsonSerializer implements ISerializer {
      * @param raw - The JSON string to decode.
      * @returns The decoded value, typed as `T`.
      * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-     *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-     *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-     *   leaking a large payload that may contain PII.
+     *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+     *   part of the stored value is echoed, as it may carry PII or a credential
+     *   (CLAUDE.md §4).
      */
     deserialize<T>(raw: string): T;
 }

package/dist/server/index.d.ts

@@ -971,9 +971,9 @@ declare class JsonSerializer implements ISerializer {
      * @param raw - The JSON string to decode.
      * @returns The decoded value, typed as `T`.
      * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-     *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-     *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-     *   leaking a large payload that may contain PII.
+     *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+     *   part of the stored value is echoed, as it may carry PII or a credential
+     *   (CLAUDE.md §4).
      */
     deserialize<T>(raw: string): T;
 }

package/dist/server/index.mjs

@@ -709,7 +709,7 @@ KeyBuilder = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS))
 ], KeyBuilder);
-var MAX_PREVIEW_LENGTH = 100;
+var DESERIALIZATION_ERROR = "stored value is not valid JSON";
 var extractErrorMessage = (err) => err instanceof Error ? err.message : String(err);
 var JsonSerializer = class {
   /**
@@ -751,17 +751,17 @@ var JsonSerializer = class {
    * @param raw - The JSON string to decode.
    * @returns The decoded value, typed as `T`.
    * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-   *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-   *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-   *   leaking a large payload that may contain PII.
+   *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+   *   part of the stored value is echoed, as it may carry PII or a credential
+   *   (CLAUDE.md §4).
    */
   deserialize(raw) {
     try {
       return JSON.parse(raw);
-    } catch (err) {
+    } catch {
       throw new CacheException(CACHE_ERROR_CODES.DESERIALIZATION_FAILED, {
-        error: extractErrorMessage(err),
-        preview: raw.length > MAX_PREVIEW_LENGTH ? `${raw.substring(0, MAX_PREVIEW_LENGTH)}...` : raw
+        error: DESERIALIZATION_ERROR,
+        length: raw.length
       });
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-cache",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Typed Redis cache for NestJS based on ioredis 6, with namespace strategy, Pub/Sub and Lua script management.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",