@ionite/redis 0.0.22-beta.20260728.2 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ionite/redis",
-  "version": "0.0.22-beta.20260728.2",
+  "version": "0.0.22",
   "description": "redis (node-redis) adapter and Redis stores for ionite. Includes createRedisAdapter (v6) and createRedisAdapterV4 (v4). Install this; redis is included.",
   "private": false,
   "author": "ionite",
@@ -24,7 +24,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@ionite/redis-core": "0.0.22-beta.20260728.2",
+    "@ionite/redis-core": "^0.0.22",
     "redis": "^6.1.0"
   },
   "peerDependencies": {

package/README.md

@@ -1,127 +0,0 @@
-# @ionite/redis
-
-redis (node-redis) adapter and Redis stores for ionite. Includes **createRedisAdapter** (v6, default), **createRedisAdapterV4** (v4), and **`ionRedis(...)`** for secret-backed reactive Redis connections. Install this package; redis is included. You do not need to install `@ionite/redis-core` separately.
-
-## Installation
-
-```bash
-bun add @ionite/redis
-```
-
-## Secret-backed reactive Redis
-
-Use **`ionRedis(source, path, options?)`** when Redis connection details arrive from the default config-backed secret client or a named `ion.secrets` provider and may rotate over time.
-
-```ts
-import { ionite, envConfig } from '@ionite/server';
-import { createValidators } from '@ionite/zod';
-import {
-  ionRedis,
-  RedisAccessIndex,
-  RedisAccessAssignmentStore,
-  RedisAccessCatalogStore,
-  RedisSessionStore,
-  RedisUserStore,
-} from '@ionite/redis';
-
-export const ion = ionite(envConfig(), {
-  validators: createValidators(),
-});
-
-const redis = ionRedis(ion.secret, `${process.env.ION_VAULT_PATH}/redis`);
-ion.setStores({
-  sessionStore: new RedisSessionStore({ redis }),
-  userStore: new RedisUserStore({ redis }),
-  accessStore: new RedisAccessAssignmentStore({ redis }),
-  accessIndex: new RedisAccessIndex({ redis }),
-  catalogStore: new RedisAccessCatalogStore({ redis }),
-});
-```
-
-Notes:
-
-- The first argument is a stable `SecretsSource` handle (for example `ion.secret` or `ion.secrets.redis`) and the second is the **secret path**. By default the log label is **`redis`**; override that with `{ sourceName }` when needed.
-- The secret payload should be a node-redis client options object. A top-level **`url`** or **`redisUrl`** field is the simplest shape.
-- The adapter subscribes with async get-then-watch semantics and defaults to fail-fast: a missing Redis secret rejects `ready()` and store operations instead of waiting silently forever. Pass `{ subscription: { mode: 'wait', timeout: 30_000 } }` only when waiting for the secret to appear is intentional.
-- The adapter is source-bound at creation time. Store operations wait for the first configured connection, so you can construct stores synchronously and use `ready()` only when you want an explicit startup or health-check barrier. If the named source is replaced during a config change, the adapter creates the next Redis client first and keeps the old client when refresh fails.
-
-## Shared env-based adapter
-
-Use **`getSharedRedisAdapter()`** when you only want one process-wide adapter from `REDIS_URL` without secret reactivity:
-
-```ts
-import { closeSharedRedisAdapter, getSharedRedisAdapter } from '@ionite/redis';
-
-const redis = await getSharedRedisAdapter();
-// On shutdown (tests, short-lived workers), close the singleton so the connection does not leak:
-await closeSharedRedisAdapter();
-```
-
-For **createRedisAdapterV4** only, also install redis v4:
-
-```bash
-bun add @ionite/redis redis@^4
-```
-
-## Usage (v5, default)
-
-```ts
-import { createClient } from 'redis';
-import {
-  createRedisAdapter,
-  RedisAccessIndex,
-  RedisAccessAssignmentStore,
-  RedisAccessCatalogStore,
-  RedisUserStore,
-  RedisSessionStore,
-  RedisMagicLinkStore,
-  RedisWorkloadTokenStore,
-  RedisTenantStore,
-} from '@ionite/redis';
-
-const client = createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:3503' });
-await client.connect();
-const redis = createRedisAdapter(client);
-
-const userStore = new RedisUserStore({ redis });
-const sessionStore = new RedisSessionStore({ redis });
-const magicLinkStore = new RedisMagicLinkStore({ redis });
-const workloadTokenStore = new RedisWorkloadTokenStore({ redis });
-const accessStore = new RedisAccessAssignmentStore({ redis });
-const accessIndex = new RedisAccessIndex({ redis });
-const catalogStore = new RedisAccessCatalogStore({ redis });
-const tenantStore = new RedisTenantStore({ redis });
-```
-
-## Usage (v4)
-
-If you still use redis (node-redis) v4, install `redis@^4` and use **createRedisAdapterV4**:
-
-```ts
-import { createClient } from 'redis';
-import {
-  createRedisAdapterV4,
-  RedisUserStore,
-  RedisSessionStore,
-  // ...
-} from '@ionite/redis';
-
-const client = createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:3503' });
-await client.connect();
-const redis = createRedisAdapterV4(client);
-// ... same store setup
-```
-
-Prefer **createRedisAdapter** (v5) when you can upgrade.
-
-Pass these stores into `ionite` (from `@ionite/server`) the same way you would in-memory stores. `keyPrefix` is **required** in store options (no implicit default; use a distinct per-tenant prefix); `logger` is optional (see `@ionite/redis-core` for the adapter interface and key layout). Use one shared `RedisSessionStore` namespace for opaque browser auth sessions so `SessionStore.get(sid)` can resolve the session without tenant-specific lookup context.
-
-**Adapter capabilities & key encoding.** `createRedisAdapter` (v4/v6 — one implementation, `createRedisAdapterV4` is a named alias) implements the full `RedisAdapter`: atomic `getdel` (`GETDEL`, **Redis 6.2+**, for single-winner magic-link consume) and server-side `runScript` (`EVAL`, for create-if-absent / unique-index claim / multi-key txn / session compare-and-set). `list()` returns records in a stable, deterministic (lexicographic id) order via `SMEMBERS` + `MGET` — no sorted-set support is needed. `ionRedis(...)` forwards `getdel` and `runScript` from the active client, so those atomic paths apply over secret-backed reactive connections too. Externally-sourced id segments are hash-encoded before they enter a key (§10.2), so a hostile or `:`-bearing id can never split a key or collide with a structural index segment — see `@ionite/redis-core` for the scheme.
-
-`RedisAccessAssignmentStore` persists granted `AccessChange` **roots** (with deterministic id, optional resource scope, provenance, and status) for SDK-owned SCIM access mutation routing and OAA full sync — one row per **direct** grant (for example `alice → role:editor`), not per permission. Fast authorization checks read **`RedisAccessIndex`** instead — the derived closure materialized from roots + the catalog — exposing `has(...)`, `hasGroup(...)`, `hasRole(...)`, `hasPermission(...)`, `hasAny(...)`, and `hasAll(...)`. Because the index already accounts for group -> role -> permission expansion, nested groups/roles, and `applyToSubResources` inheritance, these checks reflect effective access, not just direct edges. **Example:** grant Alice roles `editor` and `reviewer` that both include permission `read`; AccessAssignmentStore holds two roots, AccessIndex holds both roles and all permissions (with `read` attributed to each root). Revoke `editor`: remove that root and its index rows by `rootId` — Alice keeps `read` via the reviewer root. The index also implements the subject-disabled marker (`setSubjectDisabled`/`isSubjectDisabled`, set by inbound SCIM `active: false`): while set, every `has*` denies with `metadata.reason: 'subject_disabled'`; it is stored independently of edges, so `clear`/reconcile never wipes it.
-
-`RedisAccessCatalogStore` persists **SCIM/IAM-sourced** Authz Catalog entries (rows the IAM tool authors via SCIM Group create, or definitions with a genuine store lifecycle) under namespaced stores: `groups`, `roles`, and `permissions`. Use it as `FrameworkConfig.authz.catalogStore` or `FrameworkStores.catalogStore` so SCIM Groups aggregation and OAA full sync can translate SDK-native catalog entries without app code writing SCIM extension objects. Code-authored definitions belong in the code-declared catalog instead (`defineCatalog(...)` -> `FrameworkConfig.authz.catalog`), consumed in memory on the read path — never seeded here. `set(entity)` returns a ready-aware catalog entry synchronously (no top-level `await`) and writes to Redis in the background; await `entry.ready()` for a durability guarantee or check `entry.isReady()`.
-
-`RedisResourceStore` is a Redis-backed writable `ResourceProvider` for apps whose resources are not already in their own database. Wire it as `FrameworkConfig.authz.resources` / `FrameworkStores.resources`; `set(resource)` / `delete(id)` persist and emit the `changed` signal (driving adjacency-cache invalidation, reconcile, and incremental OAA projection), and the optional `deriveEntitlements`/`resolveEntitlement` pair derives requestable per-resource entitlement Groups on demand. Apps with their own resource tables should implement `ResourceProvider` over them directly instead.
-
-`RedisTenantStore` keeps user-to-tenant membership sets so tenant-directory lookups do not scan every tenant. It then materializes the matching candidate tenants and applies `ListOptions` (stable-order paging + filter) in memory. That is appropriate when each user or discovery lookup maps to a bounded tenant set; use a SQL/search-backed custom `TenantStore` when directories need high-cardinality paging or arbitrary indexed sort/filter behavior.