@owlmeans/server-auth-session 0.1.18-rc.16 → 0.1.18-rc.18

package/README.md

@@ -1,32 +1,134 @@
 # @owlmeans/server-auth-session
 
-A bounded seven-day authority registry for OwlMeans bearer and OIDC sessions. It supplies an
-in-memory implementation for local/single-process applications and an atomic Redis implementation
-for multi-instance production deployments.
+An authorization-freshness registry for OwlMeans bearer and OIDC sessions: every issued session is
+registered under an opaque id with an absolute seven-day lifetime, and a profile's authority can be
+fenced, then refreshed or revoked, so the next bearer decision sees the change. It ships an
+in-memory manager for a single process and an atomic Redis manager for multi-instance deployments.
+A server uses it through `@owlmeans/server-auth`: `appendAuthService` already registers the memory
+manager when none is present, so an app touches this package directly only to install the Redis
+manager or to fence/refresh/revoke a profile after changing its permissions, role or status. It is
+not a browser-token store and holds no claims — tokens and their payloads stay with
+`@owlmeans/server-auth`.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-auth-session@^0.1.18-rc.16
+bun add @owlmeans/server-auth-session@^0.1.18-rc.18
 ```
 
+## Concepts
+
+- **Session** — an `AuthSessionRecord` addressed by an opaque `id`, of an `AuthSessionKind`
+  (`'bearer'`, `'oidc-access'`, `'oidc-refresh'`, `'oidc-provider-session'`), carrying the subject
+  version it was issued at and its absolute `expiresAt`.
+- **Subject** — the stable selector `{ entityId, profileId, clientId? }` shared by all sessions of
+  one profile (per client). `entityId` is storage-only — never the renameable `entitySlug`, and never
+  placed in an authentication envelope.
+- **Subject state** — `active`, `pending` (fenced while authority changes), `refresh` (claims
+  changed; re-issue required), `revoked`. Each completed transition increments the subject
+  `version`.
+- **Decision** — `AuthSessionDecision`: `{ state: 'active' | 'refresh', version, expiresAt }` or
+  `{ state: 'pending' | 'revoked' | 'missing' | 'expired' }`.
+- **Fence** — `fence(selector, operationId)` marks the subject pending; only `refresh` or `revoke`
+  with the same `operationId` completes it.
+
 ## Usage
 
-Register the memory manager before `appendAuthService` when a local application needs immediate
-revocation or claim-refresh decisions:
+### Use the Redis manager in a scaled deployment
+
+Register it before `appendAuthService`; both append helpers are idempotent by alias, so the first
+one registered wins.
 
 ```typescript
-import { appendMemoryAuthSessionManager } from '@owlmeans/server-auth-session'
 import { appendAuthService } from '@owlmeans/server-auth'
+import { appendRedisAuthSessionManager } from '@owlmeans/server-auth-session'
 
-appendMemoryAuthSessionManager(context)
+appendRedisAuthSessionManager(context)   // registers AUTH_SESSION_RESOURCE as a Redis resource when absent
 appendAuthService(context)
 ```
 
-Use `appendRedisAuthSessionManager` in a multi-instance deployment. The application must register
-its Redis resource first. Call `fence()` before changing a profile's authority, then `refresh()`
-to require fresh claims or `revoke()` to reject all affected sessions. Session expiry is absolute;
-neither manager extends it beyond seven days.
+`appendRedisAuthSessionManager(context, { resourceAlias?, dbAlias?, serviceAlias?, alias?, now? })`
+passes `dbAlias` / `serviceAlias` to `makeRedisResource`.
+
+### Change a profile's authority
+
+```typescript
+import { AUTH_SESSION_MANAGER } from '@owlmeans/server-auth-session'
+import type { AuthSessionManager } from '@owlmeans/server-auth-session'
+
+const sessions = context.service<AuthSessionManager>(AUTH_SESSION_MANAGER)
+const selector = { entityId, profileId, clientId }
+const operationId = crypto.randomUUID()
+
+await sessions.fence(selector, operationId)        // every session of the subject now answers 'pending'
+await profiles.update({ ...profile, role })        // the durable authority change
+await sessions.refresh(selector, operationId)      // sessions answer 'refresh' → claims are re-issued
+// or, on disable/removal:
+await sessions.revoke(selector, operationId)       // sessions answer 'revoked'
+```
+
+If the write or the completion fails, leave the subject pending — it is refused until a matching
+completion runs.
+
+### Register and inspect a session
+
+```typescript
+const issued = await sessions.register({ id: sessionId, kind: 'bearer', entityId, profileId, clientId })
+// { state: 'active', version, expiresAt } — expiresAt never exceeds now + AUTH_SESSION_TTL
+
+const decision = await sessions.inspect(sessionId)
+```
+
+### Test with a controllable clock
+
+```typescript
+import { makeMemoryAuthSessionManager } from '@owlmeans/server-auth-session'
+
+let now = 1_000
+const manager = makeMemoryAuthSessionManager({ now: () => now })
+await manager.init()
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `AuthSessionManager` | interface | `register(session)`, `inspect(id)`, `fence(selector, op)`, `refresh(selector, op) → version`, `revoke(selector, op) → version` |
+| `makeMemoryAuthSessionManager(options?)` | function | process-local manager; state is lost on restart |
+| `appendMemoryAuthSessionManager(context, options?)` | function | registers the memory manager unless the alias is taken |
+| `makeRedisAuthSessionManager(resourceAlias?, options?)` | function | Redis manager; atomic `SET NX` registration and Lua subject transitions |
+| `appendRedisAuthSessionManager(context, options?)` | function | registers the Redis resource (if absent) and the Redis manager (if absent) |
+| `AUTH_SESSION_TTL` | const | `7 * 24 * 60 * 60 * 1000` ms — absolute maximum, never extended |
+| `AUTH_SESSION_MANAGER` | const | `'auth-session-manager'` — service alias |
+| `AUTH_SESSION_RESOURCE` | const | `'auth-session-record'` — Redis resource alias |
+| `AuthSessionManagerOptions` | type | `{ alias?, now? }` |
+| `AuthSessionSelector`, `RegisterAuthSession` | types | `{ entityId, profileId, clientId? }`; selector + `id`, `kind`, `issuedAt?`, `expiresAt?` |
+| `AuthSessionRecord`, `AuthSessionSubject`, `AuthSessionStoredRecord` | types | stored shapes (`record: 'session' \| 'subject'`) |
+| `AuthSessionKind`, `AuthSessionState`, `AuthSessionDecision` | types | see Concepts |
+
+## Common pitfalls
+
+- Registering the Redis manager after `appendAuthService` has no effect — the memory manager
+  already holds `AUTH_SESSION_MANAGER`.
+- The memory manager forgets everything on restart; use it only where another authority decides
+  each request live, or in development and tests.
+- `register` clamps a caller-supplied `expiresAt` to `AUTH_SESSION_TTL`; re-registering after a
+  claim refresh keeps the original absolute expiry.
+- A `refresh` or `revoke` whose `operationId` differs from a pending fence does not complete it
+  (memory returns the unchanged version; Redis throws `auth-session:transition-conflict`).
+- A registry read or write failure is surfaced by `@owlmeans/server-auth` as `AuthUnavailable` (503) —
+  never treat it as a missing session or a logout.
+- Do not replace the Redis Lua transitions with a read-modify-save sequence; a concurrent fence
+  would be overwritten.
+
+## Related packages
+
+- [`@owlmeans/server-auth`](../server-auth) — issues sessions and consults this registry at every bearer decision
+- [`@owlmeans/redis-resource`](../redis-resource) — the Redis resource behind the scaled manager
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — identity profiles whose authority changes are fenced here
+- [`@owlmeans/context`](../context) — `createService` and the service lifecycle
+
+The `server-auth-session` skill states the fence/refresh/revoke rules for agents.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -36,7 +138,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.49
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-auth-session",
-  "version": "0.1.18-rc.16",
-  "generatedAt": "2026-10-05T21:03:06.367Z",
+  "version": "0.1.18-rc.18",
+  "generatedAt": "2026-10-08T21:27:54.285Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth-session",
-  "version": "0.1.18-rc.16",
+  "version": "0.1.18-rc.18",
   "license": "MIT",
   "description": "Short-lived OwlMeans session registry with memory and Redis implementations.",
   "type": "module",
@@ -22,9 +22,9 @@
   },
   "dependencies": {
     "@owlmeans/context": "^0.1.18-rc.34",
-    "@owlmeans/redis-resource": "^0.1.18-rc.44",
+    "@owlmeans/redis-resource": "^0.1.18-rc.46",
     "@owlmeans/resource": "^0.1.18-rc.40",
-    "@owlmeans/server-context": "^0.1.18-rc.43"
+    "@owlmeans/server-context": "^0.1.18-rc.44"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/tests/service.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service.spec.d.ts.map

package/tests/service.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.spec.d.ts","sourceRoot":"","sources":["service.spec.ts"],"names":[],"mappings":""}

package/tests/service.spec.js

@@ -0,0 +1,21 @@
+import { describe, expect, test } from 'bun:test';
+import { makeMemoryAuthSessionManager } from '../src/memory.js';
+describe('memory auth session manager', () => {
+    test('refreshes and revokes an existing seven-day session', async () => {
+        let now = 1_000;
+        const manager = makeMemoryAuthSessionManager({ now: () => now });
+        await manager.init();
+        const selector = { entityId: 'entity-1', profileId: 'profile-1', clientId: 'client-1' };
+        const issued = await manager.register({ ...selector, id: 'session-1', kind: 'bearer' });
+        expect(issued.state).toBe('active');
+        await manager.fence(selector, 'change-1');
+        expect((await manager.inspect('session-1')).state).toBe('pending');
+        await manager.refresh(selector, 'change-1');
+        expect((await manager.inspect('session-1')).state).toBe('refresh');
+        await manager.revoke(selector, 'change-2');
+        expect((await manager.inspect('session-1')).state).toBe('revoked');
+        now += 7 * 24 * 60 * 60 * 1000 + 1;
+        expect((await manager.inspect('session-1')).state).toBe('expired');
+    });
+});
+//# sourceMappingURL=service.spec.js.map

package/tests/service.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.spec.js","sourceRoot":"","sources":["service.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,QAAQ,CAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,IAAI,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACrE,IAAI,GAAG,GAAG,KAAK,CAAA;QACf,MAAM,OAAO,GAAG,4BAA4B,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;QAChE,MAAM,OAAO,CAAC,IAAI,EAAE,CAAA;QACpB,MAAM,QAAQ,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAA;QACvF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QACvF,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACnC,MAAM,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QACzC,MAAM,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAClE,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAC3C,MAAM,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAClE,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAC1C,MAAM,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAClE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,CAAC,CAAA;QAClC,MAAM,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}