@ionite/redis-core 0.0.22-beta.20260728.1 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ionite/redis-core",
-  "version": "0.0.22-beta.20260728.1",
+  "version": "0.0.22",
   "description": "Redis adapter interface and store implementations for ionite. Use with @ionite/redis (node-redis), @ionite/ioredis, or a custom RedisAdapter.",
   "private": false,
   "author": "ionite",
@@ -24,7 +24,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@ionite/core": "0.0.22-beta.20260728.1"
+    "@ionite/core": "^0.0.22"
   },
   "devDependencies": {
     "@types/node": "^26.1.0"

package/README.md

@@ -1,139 +0,0 @@
-# @ionite/redis-core
-
-Redis-backed store implementations for ionite: **UserStore**, **SessionStore**, **MagicLinkStore**, **WorkloadTokenStore**, **AccessCatalogStore** (group/role/permission/resource definitions), **AccessAssignmentStore** (granted roots), **AccessIndex** (derived closure for fast `has*` checks), and **TenantStore**. Drop-in replacements for the in-memory stores from `@ionite/server`, suitable for production when you need persistence and/or multi-instance sharing.
-
-This package provides the **stores**, the **RedisAdapter interface**, and the **driver-agnostic reactive helper** used by the package-specific `ionRedis(...)` wrappers. It does **not** include adapters for specific Redis clients.
-
-## When to use this package
-
-- **Custom adapter:** You implement the `RedisAdapter` interface yourself (e.g. for Bun.redis, Upstash, or a custom wrapper). Install `@ionite/redis-core` and pass your adapter to the store constructors.
-- **Custom reactive adapter:** You want the same secret-driven reconnect behavior as `@ionite/redis` / `@ionite/ioredis`, but for your own Redis client. Use `createReactiveRedis(...)` from this package.
-- **Pre-built client:** Use one of the adapter packages instead so you get the adapter and stores from a single import. You do **not** need to install `@ionite/redis-core`:
-  - **node-redis (v5 or v4)** → `@ionite/redis` (includes adapter and stores)
-  - **ioredis** → `@ionite/ioredis`
-
-## Installation (custom adapter only)
-
-```bash
-bun add @ionite/redis-core
-```
-
-## Adapter interface
-
-Stores accept a **RedisAdapter**. Implement this interface for your Redis client:
-
-- **Required:** `get`, `set`, `setex`, `del`, `sadd`, `srem`, `smembers`, `mget`
-- **List ordering:** `list()` returns records in a **stable, deterministic order** (ids sorted lexicographically via `SMEMBERS` + `MGET`), so offset pagination is coherent across pages. No sorted-set support is required; UI-style sorting is the caller's concern.
-- **Optional (atomic consume):** `getdel(key)` — when present, the magic-link store consumes a link atomically (Redis `GETDEL`, **Redis 6.2+**) so concurrent consumes yield exactly one winner; otherwise it falls back to a best-effort get-then-del. The bundled `@ionite/redis` and `@ionite/ioredis` adapters implement it natively, and `ionRedis(...)` forwards it from the active client.
-- **Optional (intra-store atomicity):** `runScript(script, keys, args)` — runs a server-side Lua script (the Redis `EVAL` command; **not** the JavaScript `eval()` sink — nothing is dynamically executed in your process). When present, the stores run create-if-absent, unique-index claim-or-fail, multi-key writes, and session compare-and-set read-modify-write as one all-or-nothing unit (§5.9, §8.2). When absent, the stores fall back to best-effort sequenced writes that still perform all checks before any write (fail-fast + idempotent replay); only write isolation differs. A genuine create/uniqueness collision throws a typed `StoreConflictError` (from `@ionite/core`); an identical replay is treated as success. Script bodies are static SDK-authored text and all dynamic values are passed via `keys`/`args` (referenced as `KEYS[i]`/`ARGV[j]`), so there is no Lua-injection vector. `ionRedis(...)` forwards `runScript` from the active client, so the atomic paths apply over secret-backed reactive connections too.
-- **Session updates (§8.2):** `SessionStore.update(...)` reads the record, shallow-merges the patch in JS (exact `JSON.stringify` semantics — arrays and large values of untouched fields are left byte-for-byte, no `cjson` round-trip), then compare-and-sets, retrying on contention before a final best-effort write. Concurrent partial updates cannot clobber each other. The session key TTL is derived from `session.expiresAt`: `create` uses `SET ... EX`, and `update`'s compare-and-set carries `EX` (or `KEEPTTL` when the merged record has no `expiresAt`), so expired and refresh-rotation-grace records are physically reaped by Redis with no read-path bookkeeping. The optional adapter `ttl(key)` method exposes the remaining TTL for diagnostics/validation.
-
-## Reactive helper
-
-`createReactiveRedis(...)` creates one stable `RedisAdapter` object that can swap its underlying connected client when a secret version changes. The package-specific `ionRedis(...)` wrappers use this helper internally.
-
-Use it when:
-
-- your Redis client is not node-redis or ioredis
-- the Redis connection details come from `ion.secrets`
-- you want one stable adapter that can be constructed before secrets arrive
-
-Your custom client factory returns `{ adapter, dispose? }`, and the helper handles source-bound async get-then-watch secret subscription, reconnect dedupe by secret version, source-handle swaps during a config change, operation-level waiting until the first client is ready, and `ready()` when you want an explicit startup barrier. Subscriptions default to fail-fast, so missing Redis secrets reject `ready()` and store operations instead of waiting silently forever; pass `subscription: { mode: 'wait', timeout?: number }` only when waiting for the secret to appear is intentional.
-
-## Options
-
-All store constructors take **RedisStoreOptions**:
-
-- **`redis`** (required): A `RedisAdapter` instance.
-- **`keyPrefix`** (**required**): Key prefix for all keys. There is no implicit default. In multi-tenant deployments each tenant MUST use a distinct prefix (e.g. `es:t:<tenantId>:`) so the global index sets (`user:ids`, `tenant:ids`, …) auto-namespace and never collide across tenants. An empty or missing prefix throws.
-- **`logger`** (optional): `Logger` from `@ionite/core` (default `defaultLogger`).
-
-`RedisTenantStore` also accepts:
-
-- **`ionCache`** (optional): an app-owned `TenantIonCache` (`{ fetch(id), delete(id) }`, structurally compatible with `LRUCache<string, Ionite>`). `getIon(id)` delegates to `ionCache.fetch(id)`; calling `getIon(...)` without an `ionCache` throws. `upsert`/`delete` call `ionCache.delete(id)` so a changed/removed record invalidates (and, via the cache's `dispose`, closes) the stale runtime. The SDK never caches tenant runtimes itself — the tenant *record* is a plain, non-sensitive Redis lookup; only the runtime (which reads sensitive RemoteConfig from the vault) is cached, and that cache is yours.
-- **Tenant config persistence:** Redis tenant stores persist tenant metadata, including an optional narrow `TenantConfigLocator` (`{ source?, path, ttl? }`) stored at `tenant.configLocator`. In your cache's `fetchMethod`, call `tenantConfigSource(tenant.configLocator, es)` (passing the root `es`) to materialize the runtime `ConfigSource` when a locator is present, and wire `dispose: (es) => ion.close()` so evicted runtimes are released. See the "Tenant runtime cache" section of the root README for the canonical `lru-cache` pattern.
-- **Cross-node staleness:** each node's `ionCache` is independent, so a record change on one node is visible on another only when that node's cache entry expires (TTL) or it mutates the tenant itself. Size the cache `ttl` to your acceptable record-staleness window; config *content* changes still propagate live via the ConfigSource subscription.
-- **Directory note:** the SDK no longer ships tenant-directory methods (`findTenants`/`findUserTenants`) or `/mine`/`/discovery` endpoints. If your app needs a "which tenants can this user switch to" surface, build it in app code (e.g. a SQL join plus the kept `discoverSessionRecords`) with your own auth and rate limiting.
-
-## Example (custom adapter)
-
-```ts
-import type { RedisAdapter } from '@ionite/redis-core';
-import {
-  RedisAccessIndex,
-  RedisAccessAssignmentStore,
-  RedisAccessCatalogStore,
-  RedisUserStore,
-  RedisSessionStore,
-} from '@ionite/redis-core';
-
-const myAdapter: RedisAdapter = {
-  async get(key) { /* ... */ return null; },
-  async set(key, value) { /* ... */ },
-  async setex(key, seconds, value) { /* ... */ },
-  async del(key) { /* ... */ },
-  async sadd(key, ...members) { /* ... */ },
-  async srem(key, ...members) { /* ... */ },
-  async smembers(key) { /* ... */ return []; },
-  async mget(keys) { /* ... */ return keys.map(() => null); },
-};
-
-const keyPrefix = 'es:t:acme:'; // required, distinct per tenant
-const userStore = new RedisUserStore({ redis: myAdapter, keyPrefix });
-const sessionStore = new RedisSessionStore({ redis: myAdapter, keyPrefix });
-const accessStore = new RedisAccessAssignmentStore({ redis: myAdapter, keyPrefix });
-const accessIndex = new RedisAccessIndex({ redis: myAdapter, keyPrefix });
-const catalogStore = new RedisAccessCatalogStore({ redis: myAdapter, keyPrefix });
-```
-
-## Key layout
-
-Keys are prefixed with the required `keyPrefix` (examples below use `es:`):
-
-- **User:** `es:user:{id}`, indexes, set `es:user:ids`.
-- **Session:** `es:session:{sid}` (with TTL derived from `session.expiresAt`). Opaque auth sessions are looked up by `sid` alone within a configured `SessionStore`; tenant identity and claims are stored in the session value, not in a tenant-specific session key namespace.
-- **Magic link:** `es:magic:{token}` (with TTL).
-- **Workload token:** `es:workload:token:{workload_id}` (with TTL).
-- **Group:** `es:group:{id}`, indexes, set `es:group:ids`.
-- **Authz Catalog:** `es:authz:{group|role|permission}:{id}` plus per-kind `ids` sets. `RedisAccessCatalogStore` stores SCIM/IAM-sourced groups, roles, and permissions for SCIM Groups aggregation and OAA full sync (code-authored definitions belong in the code-declared catalog — `defineCatalog(...)` -> `FrameworkConfig.authz.catalog` — and are never seeded here). `set(entity)` returns a ready-aware catalog entry synchronously and performs the Redis write in the background; `entry.ready()` resolves once the write lands (and re-surfaces a failed write) while `entry.isReady()` reports its status.
-- **Resources:** `es:authz:resource:{id}` plus an `ids` set. `RedisResourceStore` is a Redis-backed writable `ResourceProvider` (`FrameworkStores.resources`) for apps without their own resource tables: `set(resource)` / `delete(id)` persist and emit the `changed` signal, and the optional `deriveEntitlements`/`resolveEntitlement` pair derives requestable per-resource entitlement Groups on demand.
-- **Access roots:** `es:access:{id}` (id = `accessRootId`, scope-aware), subject/target indexes, set `es:access:ids`. `RedisAccessAssignmentStore` stores granted `AccessChange` roots (with provenance, status, and resource scope) for SCIM grant/revoke routing and OAA full sync.
-- **Access index (derived closure):** `es:idx:*` presence keys (`idx:has`, `idx:any`) for `MGET` checks, edge-roots sets (`idx:er`), triple sets (`idx:tr`), per-root/per-subject descriptor sets (`idx:root`, `idx:subj`), and a subject-disabled marker (`idx:disabled:{subject}`) that makes every `has*` deny with `metadata.reason: 'subject_disabled'` while it is set (independent of edge materialization, so `clear`/reconcile never wipes it). `RedisAccessIndex` stores root-attributed effective edges so `removeByRoot` is efficient and diamond grants survive partial revokes.
-- **Tenant:** `es:tenant:{id}` (record, id encoded per §10.2) plus the `es:tenant:ids` index set. There is no separate company index; `companyId` is a field on the tenant record, not a key namespace.
-
-## Key encoding (external ids)
-
-Externally-sourced id segments (SCIM `id`/`externalId`, `userName`, subject/target/resource ids, client ids, magic-link tokens, session ids, the IAM-delta id-map parts) are **encoded** before they are joined into a key (§10.2), so an id can never split a key on a stray `:` or collide with a structural index segment (a user whose id is literally `ids` cannot clobber the `user:ids` set). SDK-authored literal segments (`idx:has`, `user:ids`, `authz`, …) stay raw. The encoding is total, injective, and length-bounded:
-
-- **Safe, short ids** (`^[A-Za-z0-9_.@|-]{1,64}$`) → `=<id>` verbatim (readable: `es:user:=alice`).
-- **Everything else** (any `:`/`#`/control char, or length > 64) → `#<sha256(id) truncated to 128 bits, base64url>` (fixed length, collision-resistant).
-
-`#` and `=` never appear in a structural segment and neither branch emits a `:`, so the data and structural key namespaces are provably disjoint. `encodeKeyId(id)` is exported for Ops debugging (compute the stored key form of an id). This is a **greenfield** scheme with no migration from any prior key layout.
-
-## Redis access checks
-
-Fast authorization checks read the **`RedisAccessIndex`** (the derived closure), not the `RedisAccessAssignmentStore` roots. The index is materialized from roots + the catalog by the SDK SCIM orchestration (or `expandRoot` + `materialize`), so unlike a raw edge store these checks already account for group -> role -> permission expansion, nested groups/roles, and `applyToSubResources` sub-resource inheritance:
-
-- **`RedisAccessAssignmentStore`** — direct grants only (for example `alice → role:editor` and `alice → role:reviewer` are two roots).
-- **`RedisAccessIndex`** — effective access after expansion (both roles **and** every permission they confer; overlapping permissions such as `read` from both roles are stored with separate `rootId` attribution so revoking one role does not remove access still justified by the other).
-
-```ts
-await accessIndex.has(userId, 'permission', permissionId);
-await accessIndex.hasGroup(userId, groupId);
-await accessIndex.hasRole(userId, roleId);
-await accessIndex.hasPermission(userId, permissionId, resourceId /* optional scope */);
-await accessIndex.hasAny(userId, [
-  { targetType: 'role', target: 'admin' },
-  { targetType: 'permission', target: 'invoice:read' },
-]);
-await accessIndex.hasAll(userId, [
-  { targetType: 'role', target: 'finance' },
-  { targetType: 'permission', target: 'invoice:approve' },
-]);
-```
-
-Single checks read presence keys directly; resource-scoped checks also accept an application-wide grant. Bounded `hasAny(...)` and `hasAll(...)` issue per-target reads and log a warning when the requested target set is large. All checks return the shared `AuthzDecision` (`{ allow, matched? }`).
-
-## List ordering
-
-`list()` returns records in a **stable, deterministic order**: ids are read via `SMEMBERS` and sorted lexicographically before `MGET`, so offset pages (`start`/`limit`) are disjoint and complete across calls for an unchanged dataset. There is no caller-specified sort and no sorted-set requirement; UI-style sorting is the application's concern.