@bymax-one/nest-cache 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -4,6 +4,117 @@ 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).
 
+## [1.2.1] - 2026-08-21
+
+### Changed
+
+- **`RevealedValue`'s hash arm now names each entry `field`, not `name`**
+  (`{ field, value }`). Redis's own vocabulary for a hash is field/value —
+  `HSET key field value`, `HDEL key field`, and `HGETALL` returns field-value
+  pairs — so a generic `name` lost the domain term in the one place a reader
+  would check the shape against the server's documentation.
+
+  This is a **type-level breaking change** shipped as a patch, deliberately and
+  with the trade-off stated: `RevealedValue` was published in 1.2.0 roughly an
+  hour earlier, no consumer had wired it yet, and correcting a freshly published
+  name is cheaper than carrying a permanent vocabulary mismatch or maintaining
+  two names for one concept. A consumer that already destructured `name` gets a
+  compile error, not a silent behaviour change.
+
+  The library emits **one** name. Aliasing `field` and `name` together would have
+  been two names for one idea, which is the defect this corrects rather than a
+  softer way to ship it.
+
+## [1.2.0] - 2026-08-21
+
+### Security
+
+- **`validateOptions` now rejects a namespace containing a Redis glob metacharacter
+  (`*`, `?`, `[`, `\`).** The namespace is this library's isolation boundary and it was
+  composed unvalidated into `flushNamespace`'s destructive match pattern
+  (`{namespace}{separator}*`), so a metacharacter changed which keys `UNLINK` reached.
+  Measured against Redis 8.10.0, each one broke isolation differently: `*` and `?` **widen**
+  the pattern (namespace `ten*ant` matches every other tenant's keys, turning a scoped flush
+  into a cross-tenant delete); `\` **escapes** the next character (namespace `ten\ant`
+  matches `tenant:*` — a different keyspace — while sparing its own keys); and `[` opens a
+  character class that never closes, so the pattern matches **nothing** and `flushNamespace`
+  removes none of the namespace's keys while returning `0`, which reads as a successful flush.
+  Triggering it required a misconfigured namespace, so no default configuration was exposed;
+  the case to worry about is a namespace derived from input, such as multi-tenant wiring using
+  a tenant slug. `]` is deliberately still accepted — measured to be a literal that neither
+  widens nor silences the pattern.
+- An **empty `keySeparator`** now fails with its own message. It was already rejected, but by
+  coincidence: the next guard is `namespace.includes(separator)` and `'anything'.includes('')`
+  is `true` for every string, so it reported _"namespace contains key separator"_ — something
+  the consumer had not done.
+
+### Added
+
+- **New subpath `@bymax-one/nest-cache/admin`** — a privileged, read-only administration
+  surface: health, parsed `INFO` statistics, resolved configuration, keyspace listing, key
+  inspection and value reveal. Kept out of the main entry deliberately: importing it is a
+  greppable, reviewable act; a consumer who never wires it cannot resolve a reveal service
+  from DI by accident and does not pay for it in the main bundle.
+- `BymaxCacheAdminModule.forRoot()` / `.forRootAsync()`, `CacheStatusService`,
+  `CacheAdminService`, and the scope model (`CacheScope`, `validateScopes`, `findScope`,
+  `isKeyInScope`).
+- New error codes: `cache.invalid_scope`, `cache.scope_not_found`, `cache.scope_not_readable`,
+  `cache.key_not_in_scope`.
+- `ResolvedOptions` and `DEFAULT_REDIS_PORT` are now exported from the main entry. The former
+  is the shape stored under the already-exported `BYMAX_CACHE_OPTIONS` token, which previously
+  had no public type.
+- `pnpm check:admin-readonly` — a build gate that fails if the admin subpath declares a method
+  named after a mutating Redis command, sends a non-allowlisted command through the `call`
+  escape hatch, or imports `ioredis` as a value. Wired into `prepublishOnly`.
+
+### Administration surface — shapes chosen deliberately
+
+- **The application declares which keyspaces exist; the library validates and serves them.**
+  A cache library cannot know that another library writes at Redis root through
+  `getClient()`, and must not depend on that library to learn it.
+- **`isReadable: false` withholds the value only.** Listing, types, TTLs and sizes stay
+  available. A surface that renders an unreadable keyspace as empty tells an operator the
+  region holds nothing when it is full — the same defect as a blank log page during an outage.
+- **Scope patterns are restricted to a literal prefix with at most one trailing `*`.** A
+  caller names a key, so the library must decide whether that key belongs to the named scope.
+  Deciding that for arbitrary globs means reimplementing Redis's `stringmatchlen`, and a
+  matcher even slightly _more_ permissive than the server's is a silent cross-scope leak that
+  no happy-path test would show. With this shape, membership is exact by construction — and it
+  is checked differentially against a real server in the E2E suite.
+- **Health is three states and `latencyMs` cannot exist without a measurement.** The type is
+  a union, so a handler that caught a throwing ping and returned a confident status does not
+  compile. `mode` and `isScanSupported` sit outside the union: a cluster deployment that is
+  down should still report that scanning was never going to work.
+- **Every reading that would carry two meanings under one `null` is a union.**
+  `maxmemory` is `unbounded | limited | unreported` (Redis spells "no ceiling" as
+  `maxmemory:0`, which read literally draws a full saturation bar on the least constrained
+  server there is); `TTL` is `expiring | persistent | missing` (`-1` and `-2` are different
+  facts, and the key that expired mid-listing is the one an operator is watching);
+  `aofEnabled` is nullable, because `false` for an absent field is a durability claim made
+  without evidence.
+- **`connection.url` is never on the wire.** The config payload carries host, port and a TLS
+  flag; the URL and its password are never read into this subpath at all.
+- **Sampled figures are named `sampledCount` / `sampledBytes`.** They are sums over a capped
+  `SCAN`, not measurements of the keyspace. `isComplete` is the fact; the names are the guard,
+  because a caller reaching for one does not necessarily read the other.
+- **Pipeline batches are bounded in commands, not keys.** Redis is single-threaded, so a
+  pipeline converts a network cost into a server-blocking one — describing N keys is two or
+  three commands each, and one flush blocks every other client for the whole burst, on a
+  server someone is inspecting precisely because it is unwell. Sizing is opt-in for the same
+  reason.
+
+### Internal
+
+- Bundle-size budgets recalibrated: server `14.50` → `15.00` kB, admin added at `7.25` kB
+  against a measured `6.60` kB. The admin entry marks `@bymax-one/nest-cache` **external** —
+  bundling the server modules would give it its own copies of `CacheService` and the DI
+  tokens, so `@Inject(CacheService)` in an admin provider would name a different class object
+  than the one `BymaxCacheModule` registered and DI would fail at a consumer's runtime.
+- E2E coverage for the admin subpath against a real Redis, asserting all twenty-four `INFO`
+  field names the parser reads, real `MEMORY USAGE` sizing, and the differential scope-membership
+  check. `ioredis-mock` supports none of those three (measured), so a unit suite alone could not
+  have verified them.
+
 ## [1.1.0] - 2026-08-11
 
 ### Changed
@@ -190,6 +301,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
 
+[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
 [1.1.0]: https://github.com/bymaxone/nest-cache/compare/v1.0.6...v1.1.0
 [1.0.6]: https://github.com/bymaxone/nest-cache/compare/v1.0.5...v1.0.6
 [1.0.5]: https://github.com/bymaxone/nest-cache/compare/v1.0.4...v1.0.5

package/README.md

@@ -97,19 +97,22 @@ pnpm add @bymax-one/nest-cache ioredis
 
 ## 📦 Subpath Exports
 
-One package, two entry points — import only what your app needs:
+One package, three entry points — import only what your app needs:
 
 | Subpath    | Import                         | Purpose                                                                                                  |              Dependencies              |
 | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | :------------------------------------: |
 | **Server** | `@bymax-one/nest-cache`        | `BymaxCacheModule`, `CacheService`, `PubSubService`, `ScriptManagerService`, DI tokens, `CacheException` | NestJS 11, ioredis 6, reflect-metadata |
+| **Admin**  | `@bymax-one/nest-cache/admin`  | Read-only administration — health, `INFO` statistics, keyspace listing, key inspection, value reveal     | NestJS 11, ioredis 6, the server entry |
 | **Shared** | `@bymax-one/nest-cache/shared` | Types + constants — `CACHE_ERROR_CODES`, `CacheEventName`, config types                                  |                  None                  |
 
 ```
 shared (zero deps)
      ↑
-  server
+  server  ←  admin
 ```
 
+`/admin` is a **privileged** surface and is kept out of the main entry on purpose: importing it is a greppable, reviewable act, a consumer who never wires it cannot resolve a reveal service from DI by accident, and it never lands in the main bundle.
+
 The `/shared` subpath is safe to import in isomorphic code, test helpers, CLI scripts, or shared packages that must not pull in NestJS or ioredis.
 
 ---
@@ -386,6 +389,145 @@ export class HealthController {
 
 ---
 
+## 🔎 Administration surface (`/admin`)
+
+A read-only surface for an operator-facing console: is the cache answering, what is it doing, what is in it.
+
+```ts
+import { BymaxCacheModule } from '@bymax-one/nest-cache'
+import { BymaxCacheAdminModule } from '@bymax-one/nest-cache/admin'
+
+// `config` is a ConfigService reachable where the module is declared; see
+// Scenario 4 above for the forRootAsync form that injects it properly.
+@Module({
+  imports: [
+    BymaxCacheModule.forRoot({
+      connection: { url: config.getOrThrow<string>('REDIS_URL') },
+      namespace: 'my-app'
+    }),
+    BymaxCacheAdminModule.forRoot({
+      scopes: [
+        {
+          id: 'cache',
+          label: 'Application cache',
+          pattern: 'my-app:*',
+          isReadable: true,
+          origin: "the application's own namespace, written through the typed API"
+        },
+        {
+          id: 'auth',
+          label: 'Authentication',
+          pattern: 'auth:*',
+          isReadable: false,
+          origin:
+            'written by another library through the un-namespaced client, so it sits at Redis ' +
+            'root. Values are refused: this keyspace holds session records.'
+        }
+      ]
+    })
+  ]
+})
+export class AppModule {}
+```
+
+```ts
+constructor(
+  @Inject(CacheStatusService) private readonly status: CacheStatusService,
+  @Inject(CacheAdminService) private readonly admin: CacheAdminService
+) {}
+
+await this.status.health()   // { status: 'up', latencyMs: 3, mode, isScanSupported, degradedAboveMs }
+await this.status.stats()    // parsed INFO
+this.status.config()         // resolved wiring, connection URL withheld
+this.admin.listScopes()      // never touches the connection
+await this.admin.listKeys('cache', { includeSize: true })
+await this.admin.revealValue('auth', 'auth:sess:1')  // { status: 'withheld', origin }
+```
+
+### What the library owns, and what you own
+
+The library owns the **mechanism**: validating the allowlist, scanning against it, describing keys, withholding values. The application owns **which keyspaces exist**, the `origin` prose that explains them, the routes, and the guards. A cache library cannot know that another library writes at Redis root through `getClient()`, and making it depend on that library to find out would invert two packages to save an application from stating one thing about itself.
+
+### `isReadable: false` withholds the value — and nothing else
+
+Listing, types, TTLs and sizes stay available on an unreadable scope. Only the value is refused, and the refusal is returned _before_ the value is read.
+
+This is the easy thing to get wrong, because "unreadable" reads like "return nothing" — and the unreadable scope is typically the one that holds the most interesting keys. A surface that renders it as empty tells an operator the region holds nothing while it is full, which is the same defect as a blank log page during an outage: a reading meaning _"I may not tell you"_ drawn identically to one meaning _"there is nothing here"_.
+
+### Scope patterns: a literal prefix, optionally ending in `*`
+
+`auth:*`, `my-app:*` and exact keys are accepted. `app:*:v1`, `*`, `a?b` and `a[bc]` are refused at wiring.
+
+The restriction exists because a caller names a **key**, so the library must decide whether that key belongs to the named scope — otherwise a caller names the readable scope and passes a key from the credential-bearing one. Deciding that for arbitrary globs means reimplementing Redis's `stringmatchlen` — greedy `*` with backtracking, `[a-z]` classes, `^` negation, escapes, and the unterminated-class case where `ten[ant` matches nothing at all — and **a matcher even slightly more permissive than the server's is a silent cross-scope leak that no happy-path test would show.** With this shape, membership is exact by construction, and the E2E suite checks it differentially against a real server's own `KEYS`.
+
+Do not relax this to be helpful. Widening it later is compatible; a leak is not un-shippable.
+
+### Readings that would carry two meanings are unions, not nullables
+
+| Reading      | Type                                                      | Why                                                                                                                                                                                            |
+| ------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxmemory`  | `unbounded \| limited \| unreported`                      | Redis spells "no ceiling" as `maxmemory:0`; read as a literal ceiling it draws a full saturation bar on the least constrained server there is — and "unbounded" is not "the server didn't say" |
+| `TTL`        | `expiring \| persistent \| missing`                       | `-1` and `-2` are different facts, and the key that expired between the scan and the read is the one an operator is watching                                                                   |
+| `aofEnabled` | `boolean \| null`                                         | `false` for an absent field is a durability claim made without evidence                                                                                                                        |
+| health       | `{ up \| degraded, latencyMs } \| { down, reason, code }` | A latency exists if and only if the ping answered — expressed as `latencyMs: number \| null` that is a convention a future `catch` can break; as a union it does not compile                   |
+
+`mode`, `isScanSupported` and `degradedAboveMs` sit **outside** the health union: a cluster deployment that is down should still report that scanning was never going to work.
+
+### Reading a value: `revealed` / `withheld` / `missing`
+
+`revealValue()` answers with a discriminated union, not a nullable value, because **"I may not tell you" and "there is nothing here" are different answers** and rendering them identically is the defect this whole surface exists to avoid.
+
+```ts
+import type { CacheAdminService } from '@bymax-one/nest-cache/admin'
+
+async function describeValue(admin: CacheAdminService, scope: string, key: string) {
+  const result = await admin.revealValue(scope, key)
+
+  switch (result.status) {
+    case 'revealed':
+      // `result.type` is the Redis type; `result.value` is shaped by it.
+      return { type: result.type, value: result.value }
+    case 'withheld':
+      // The scope declares `isReadable: false`. `origin` explains why, verbatim.
+      // Listing, types, TTLs and sizes for this key remain available.
+      return { refusedBecause: result.origin }
+    case 'missing':
+      return { gone: true }
+  }
+}
+```
+
+A withheld value is **not an authorization failure**. The caller is allowed to ask; the deployment declared the keyspace unreadable at wiring, and no credential changes that — so serving it as `403` would tell a client that some other permission would unlock it, which is false.
+
+The revealed value is shaped by the key's type:
+
+| `value.kind`  | Shape                              | Notes                                                                                    |
+| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `string`      | `{ value: string }`                | Truncated to `revealStringLimit`                                                         |
+| `hash`        | `{ fields: { field, value }[] }`   | `field`, matching Redis's own vocabulary (`HSET key field value`)                        |
+| `members`     | `{ members: string[] }`            | **Sets and lists both.** The enclosing `type` says which — see the ordering caveat below |
+| `scored`      | `{ members: { member, score }[] }` | Sorted sets. `score` is a **string**: parsing to a number would round large integers     |
+| `unsupported` | `{ type: RedisKeyType }`           | Streams and module types — says so, rather than returning an empty value                 |
+
+Every arm except `unsupported` carries `isComplete`. It is deliberately **positive polarity**: an absent boolean reads as `false`, and under a name like `truncated` that default would be the _reassuring_ answer — a value silently claiming nothing was cut.
+
+> [!IMPORTANT]
+> **List order is meaningful; set order is not**, and both arrive in the same `members` array. Nothing in the type stops a renderer from sorting either one. Sorting a set for display is fine; sorting a list is a lie about the data — an `LPUSH` queue shown alphabetically misreports what pops next. Gate any client-side ordering on `type === 'set'`.
+
+### Costs the surface does not hide
+
+- **`sampledCount` / `sampledBytes`** are sums over a capped `SCAN`, not measurements of the keyspace. `isComplete` is the fact; the names are the guard.
+- **A page may carry slightly more than `scanLimit` entries.** `SCAN` returns whole batches and the cursor has already moved past them, so the limit stops the loop rather than trimming the result — trimming would drop keys no later page could reach.
+- **Sizing is opt-in** (`includeSize`), and every pipeline batch is bounded in **commands**, not keys. Redis is single-threaded, so a pipeline converts a network cost into a server-blocking one: one flush of N keys × 3 commands blocks every other client for the whole burst, on a server someone is inspecting precisely because it is unwell.
+- **`connection.url` is never on the wire.** The config payload carries host, port and a TLS flag; the URL is never read into the admin subpath at all.
+- **`mem_fragmentation_ratio` is reported raw.** On an instance holding very little, allocator and copy-on-write overhead dominate and the figure reads far above 1 without indicating a problem — 9.07 was measured on an instance holding 1.1 MiB. Turning it into a verdict is deployment policy.
+
+### Cluster
+
+Every scan-based operation throws `UNSUPPORTED_IN_CLUSTER`, inherited from `CacheService.getClient()` rather than restated. `isScanSupported` travels on the health payload so a console never has to re-derive that rule from `mode`.
+
+---
+
 ## 🏗️ Architecture
 
 The package runs **inside** your NestJS application as a dynamic module — not as a separate service:
@@ -467,6 +609,10 @@ Error `details` are built to be safe to log:
 
 Scripts are declared up front — through `options.scripts` or `ScriptManagerService.register(name, lua)` — and executed **by name**. A call site passes `eval(scriptName, keys, args)`; it has no way to pass a script body. Keys are namespaced before execution and arguments arrive as Redis `ARGV[]`, which Lua treats as data, so request input cannot become script source. Standalone and Sentinel use `EVALSHA` with a `NOSCRIPT` reload-and-retry; Cluster sends the full body via `EVAL`, because `EVALSHA` routes by key slot and a keyless reload would not reach the node that reported `NOSCRIPT`.
 
+### The namespace cannot widen a destructive pattern
+
+`validateOptions` rejects a namespace containing a Redis glob metacharacter (`*`, `?`, `[`, `\`). The namespace is composed into `flushNamespace()`'s match pattern, so a metacharacter there is not cosmetic — measured against Redis 8.10.0, `*` and `?` **widen** the pattern into other keyspaces, `\` **escapes** into a different one while sparing its own keys, and `[` opens a character class that never closes so the pattern matches **nothing** and the flush reports success having removed no keys. `]` is accepted: measured to be a literal that neither widens nor silences. This matters most when the namespace is derived from input — multi-tenant wiring using a tenant slug reads like isolation and would otherwise be one unsanitised character from a cross-tenant delete.
+
 ### Cluster mode refuses commands it cannot honor safely
 
 `scan()`, `flushNamespace()`, and `getClient()` throw `UNSUPPORTED_IN_CLUSTER` under `mode: 'cluster'` rather than silently operating on one node. A partial flush that reports success is worse than an error.
@@ -483,6 +629,8 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 - 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
 - Cached entries carry a TTL sized to your data-retention policy; namespacing bounds who can read an entry, not how long it exists
 - Custom `ISerializer` implementations throw on malformed input rather than returning a fallback value
+- If `/admin` is wired, its routes are behind the application's own authorization — the library validates scopes and withholds values, it does not authenticate anyone
+- Any admin scope whose keyspace holds credentials is declared `isReadable: false`, and the deployment understands that this withholds the **value only** — listing, types, TTLs and sizes stay visible by design
 
 ---
 
@@ -491,7 +639,9 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 | 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 or separator-containing namespace rejected at bootstrap (`INVALID_NAMESPACE`)                                         |
+| 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`                                |