@furystack/rest-service 14.0.0 → 14.1.1

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## [14.1.1] - 2026-06-05
+
+### 👷 CI
+
+- Raised the minimum supported Node.js to `>=24.0.0` (Node 24 LTS) in `engines`, dropping Node 22.
+
+### ⬆️ Dependencies
+
+- Bumped dev `ws` to `^8.21.0` and dev `vitest` to `^4.1.8`. No source changes — dev-tooling bump only.
+- Released alongside the distributed task management work to keep `@furystack/*` workspace dependency ranges current. No functional or API changes to this package.
+
+## [14.1.0] - 2026-05-21
+
+### ⬆️ Dependencies
+
+- Bump `ajv` to `^8.20.0`.
+- Bump dev `vitest` to `^4.1.5`.
+- Adds `@furystack/cross-node-bus` as a runtime dependency. Resolves to the in-process default bus unless an adapter is bound.
+- Bumped `@furystack/cache` to its new major version. The removed `obsoleteRange` / `removeRange` APIs are not used by `@furystack/rest-service`, so no source changes were required. See the `@furystack/cache` changelog for the migration if you import the cache directly alongside this package.
+- Added `@furystack/cache` as a runtime dependency (`workspace:^`). Used internally by `UserResolutionCache`; not part of `@furystack/rest-service`'s public API surface.
+- Bumped `ws` from `^8.20.0` to `^8.20.1` (dev dependency used in tests).
+- Bumped `@types/node` to `^25.9.1` and `vitest` to `^4.1.7`. Dev-tooling only.
+
+### 📚 Documentation
+
+- Rewrote JSDoc across the public API — built-in actions (`getCurrentUser`, `isAuthenticated`, `logout`, `passwordLoginAction`, `errorAction`, `notFoundAction`), `authenticate`, `authorize`, `validate`, `HttpAuthenticationSettings`, `HttpUserContext`, the login response strategy, and the request-action implementation — to follow the new value-test guidance: dropped restate-the-type narration, kept intent / trade-offs / constraints around session handling, validation, and error mapping.
+- Expanded `UserResolutionCache` JSDoc to cross-link `invalidateByUser` and document the multi-node trade-off.
+
+### ✨ Features
+
+### `IdentityEventBus` — cross-node identity invalidation
+
+A typed wrapper over `@furystack/cross-node-bus` that bridges the per-process `UserResolutionCache` to a shared bus, so logouts, role flips, password resets and account deletions invalidate cached identities on every node — not just the one that originated the change. Collapses the staleness window from `userCacheTtlMs` (default 30 s) to bus latency (single-digit ms with Redis pub/sub).
+
+```typescript
+import { IdentityEventBus } from '@furystack/rest-service'
+
+const bus = injector.get(IdentityEventBus)
+await bus.publish({ type: 'userRolesChanged', username: 'alice' })
+// → invalidates every cached entry that resolved to alice on this node
+//   AND every sibling node, synchronously locally and at bus speed remotely.
+```
+
+Supported event variants (`IdentityEvent`):
+
+- `userLoggedOut` / `sessionInvalidated` — drop the cache entry for a single session id.
+- `userRolesChanged` / `userDeleted` / `passwordChanged` — drop every cached entry that resolved to the named user, regardless of which session originally populated it.
+
+**Self-delivery contract:** `publish()` applies the matching local invalidation and fires local subscribers synchronously **before** awaiting the bus broadcast. Sibling nodes receive the message via a `subscribeRemoteOnly` bridge — own publishes never round-trip through the transport, so duplicate work is impossible.
+
+`HttpUserContext.cookieLogout` now broadcasts `userLoggedOut` on the bus instead of dropping the local cache directly. Apps that have not bound a transport adapter run against the in-process default `CrossNodeBus` and behave exactly as before.
+
+### `UserResolutionCache.invalidateByUser(username)`
+
+Drops every cached entry that resolved to `username`, backed by the cache's reverse tag index — no per-call O(n) scan. Use after role / password / account-state changes that must take effect immediately on the next request, instead of waiting for the TTL window to elapse.
+
+```typescript
+const userCache = injector.get(UserResolutionCache)
+userCache.invalidateByUser('alice')
+```
+
+For multi-node deployments, prefer publishing the corresponding `IdentityEvent` on `IdentityEventBus` — it calls `invalidateByUser` locally and on every sibling.
+
+### `identity-cache-keys` exports
+
+New module exporting the cache-key / cache-tag shapes shared by the cookie-auth provider, `UserResolutionCache`, and `IdentityEventBus`:
+
+- `SessionCacheKey` (type) — `` `cookie:${string}` ``.
+- `UserCacheTag` (type) — `` `user:${string}` ``.
+- `sessionCacheKey(sessionId)` — builds the cookie-auth cache key.
+- `userCacheTag(username)` — builds the user-resolution cache tag.
+
+Centralising these strings means the local-vs-replicated invalidation paths cannot drift.
+
+### Short-TTL user-resolution cache for `HttpUserContext`
+
+`HttpUserContext.getCurrentUser` now consults a singleton `UserResolutionCache` before walking the configured authentication providers. Successful resolutions are cached per-process under a key produced by the matching provider (e.g. session id for cookie auth) and expire after `HttpAuthenticationSettings.userCacheTtlMs` (default **30 000 ms**, capacity **10 000** entries).
+
+This bounds cross-instance staleness for out-of-band identity changes — session invalidation on a sibling node, role mutation in storage, etc. — while sharply cutting the auth-store load on chatty clients (every authenticated request used to walk the provider chain on every call).
+
+**New configuration on `HttpAuthenticationSettings`:**
+
+| Field               | Default | Effect                                                        |
+| ------------------- | ------- | ------------------------------------------------------------- |
+| `userCacheTtlMs`    | `30000` | TTL for cached `User` entries. `0` disables caching entirely. |
+| `userCacheCapacity` | `10000` | LRU capacity ceiling.                                         |
+
+### Cache-key contract on `AuthenticationProvider`
+
+Added an optional `getCacheKey?(request): string | null` method to `AuthenticationProvider`. Providers that opt in produce stable per-identity keys consumed by the user-resolution cache; providers that omit it (or return `null`) cause the request to bypass the cache.
+
+Built-in providers:
+
+- **`createCookieAuthProvider`** — keys requests by `cookie:${sessionId}`. Cache hits skip both the session-store and user-store lookups.
+- **`createBasicAuthProvider`** — intentionally does **not** opt in. Caching by username would skip password verification on every cache hit.
+- **`createJwtAuthProvider`** (in `@furystack/auth-jwt`) — also intentionally does **not** opt in. See the `@furystack/auth-jwt` changelog for the rationale (token expiry / revocation must be re-checked per request).
+
+### `UserResolutionCache` token
+
+Exported a new singleton DI token. Consumers can call `injector.get(UserResolutionCache).invalidate(cacheKey)` to drop a specific entry (e.g. after an out-of-band role mutation), or `invalidateAll()` to flush every entry.
+
+`HttpUserContext.cookieLogout` automatically invalidates the local cache entry for the logged-out session, so the very next request on the same node re-authenticates immediately. Sibling nodes still rely on TTL expiry.
+
+**Example — invalidate after an admin mutates roles in storage:**
+
+```typescript
+import { UserResolutionCache, UserDataSet } from '@furystack/rest-service'
+
+await injector.get(UserDataSet).update(injector, 'alice', { roles: ['admin'] })
+injector.get(UserResolutionCache).invalidate(`cookie:${sessionId}`)
+```
+
+### ♻️ Refactoring
+
+### `HttpUserContext` no longer maintains a per-request `WeakMap`
+
+The previous `WeakMap<headers, Promise<User>>` cache (per-`HttpUserContext`-instance) has been removed in favor of the shared `UserResolutionCache`. With the request-scoped HUC, the WeakMap was effectively single-shot per request anyway. Anonymous-style requests (no provider yields a key) now bypass the cache entirely instead of being dedup-cached for the lifetime of the HUC instance.
+
 ## [14.0.0] - 2026-04-25
 
 ### 💥 Breaking Changes

package/esm/actions/error-action.d.ts

@@ -1,7 +1,12 @@
 import type { RequestAction } from '../request-action-implementation.js';
 /**
- * Action for unhandled (500) errors
- * Returns a serialized error instance in JSON format.
+ * Default error handler. Maps thrown errors to HTTP responses:
+ *
+ * - {@link SchemaValidationError} → 400 with `{ message, errors }`
+ * - {@link RequestError} → its `responseCode` with `{ message }`
+ * - {@link AuthorizationError} → 403 with `{ message }`
+ * - other `Error` → 500 with `{ message }`
+ * - non-Error throwables → 500 with a generic message
  */
 export declare const ErrorAction: RequestAction<{
     body: unknown;

package/esm/actions/error-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-action.d.ts","sourceRoot":"","sources":["../../src/actions/error-action.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAIxE;;;GAGG;AAEH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IACtC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5B,CAoBA,CAAA"}
+{"version":3,"file":"error-action.d.ts","sourceRoot":"","sources":["../../src/actions/error-action.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAIxE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IACtC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5B,CAoBA,CAAA"}

package/esm/actions/error-action.js

@@ -3,8 +3,13 @@ import { AuthorizationError } from '@furystack/core';
 import { JsonResult } from '../request-action-implementation.js';
 import { SchemaValidationError } from '../schema-validator/schema-validation-error.js';
 /**
- * Action for unhandled (500) errors
- * Returns a serialized error instance in JSON format.
+ * Default error handler. Maps thrown errors to HTTP responses:
+ *
+ * - {@link SchemaValidationError} → 400 with `{ message, errors }`
+ * - {@link RequestError} → its `responseCode` with `{ message }`
+ * - {@link AuthorizationError} → 403 with `{ message }`
+ * - other `Error` → 500 with `{ message }`
+ * - non-Error throwables → 500 with a generic message
  */
 export const ErrorAction = async ({ getBody }) => {
     const body = await getBody();

package/esm/actions/error-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-action.js","sourceRoot":"","sources":["../../src/actions/error-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAA;AAEtF;;;GAGG;AAEH,MAAM,CAAC,MAAM,WAAW,GAGnB,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACzB,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAA;IAE5B,IAAI,IAAI,YAAY,qBAAqB,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAA;IACxE,CAAC;IAED,IAAI,IAAI,YAAY,YAAY,EAAE,CAAC;QACjC,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;IACjE,CAAC;IAED,IAAI,IAAI,YAAY,kBAAkB,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAA;IACnD,CAAC;IAED,IAAI,IAAI,YAAY,KAAK,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,8BAA8B,EAAE,EAAE,GAAG,CAAC,CAAA;AACrE,CAAC,CAAA"}
+{"version":3,"file":"error-action.js","sourceRoot":"","sources":["../../src/actions/error-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAA;AAEtF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAGnB,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACzB,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAA;IAE5B,IAAI,IAAI,YAAY,qBAAqB,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAA;IACxE,CAAC;IAED,IAAI,IAAI,YAAY,YAAY,EAAE,CAAC;QACjC,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;IACjE,CAAC;IAED,IAAI,IAAI,YAAY,kBAAkB,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAA;IACnD,CAAC;IAED,IAAI,IAAI,YAAY,KAAK,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,8BAA8B,EAAE,EAAE,GAAG,CAAC,CAAA;AACrE,CAAC,CAAA"}

package/esm/actions/get-current-user.d.ts

@@ -1,9 +1,6 @@
 import type { User } from '@furystack/core';
 import type { RequestAction } from '../request-action-implementation.js';
-/**
- * Action that returns the current authenticated user
- * @param injector The injector from the current stack
- */
+/** Returns the current authenticated user; 401 if no user is bound. */
 export declare const GetCurrentUser: RequestAction<{
     result: User;
 }>;

package/esm/actions/get-current-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-current-user.d.ts","sourceRoot":"","sources":["../../src/actions/get-current-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAG3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IACzC,MAAM,EAAE,IAAI,CAAA;CACb,CAGC,CAAA"}
+{"version":3,"file":"get-current-user.d.ts","sourceRoot":"","sources":["../../src/actions/get-current-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAG3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE,uEAAuE;AACvE,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IACzC,MAAM,EAAE,IAAI,CAAA;CACb,CAGC,CAAA"}

package/esm/actions/get-current-user.js

@@ -1,10 +1,7 @@
 import { getCurrentUser } from '@furystack/core';
 import { Authenticate } from '../authenticate.js';
 import { JsonResult } from '../request-action-implementation.js';
-/**
- * Action that returns the current authenticated user
- * @param injector The injector from the current stack
- */
+/** Returns the current authenticated user; 401 if no user is bound. */
 export const GetCurrentUser = Authenticate()(async ({ injector }) => {
     const user = await getCurrentUser(injector);
     return JsonResult(user);

package/esm/actions/get-current-user.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-current-user.js","sourceRoot":"","sources":["../../src/actions/get-current-user.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAEtB,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;IACzC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC3C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"get-current-user.js","sourceRoot":"","sources":["../../src/actions/get-current-user.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAEtB,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;IACzC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC3C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC,CAAC,CAAA"}

package/esm/actions/is-authenticated.d.ts

@@ -1,9 +1,8 @@
 import type { RequestAction } from '../request-action-implementation.js';
 /**
- * Action that returns if the current user is authenticated
- * @param options The options for the Custom Action
- * @param options.injector The Injector from the current context
- * @returns A standard authentication result
+ * Returns `{ isAuthenticated: boolean }`. Unauthenticated callers receive
+ * a 200 with `false` rather than a 401 — use this when the client needs to
+ * branch on auth state without triggering a re-login flow.
  */
 export declare const IsAuthenticated: RequestAction<{
     result: {

package/esm/actions/is-authenticated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-authenticated.d.ts","sourceRoot":"","sources":["../../src/actions/is-authenticated.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE;QAAE,eAAe,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAGnF,CAAA"}
+{"version":3,"file":"is-authenticated.d.ts","sourceRoot":"","sources":["../../src/actions/is-authenticated.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE;QAAE,eAAe,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAGnF,CAAA"}

package/esm/actions/is-authenticated.js

@@ -1,10 +1,9 @@
 import { isAuthenticated } from '@furystack/core';
 import { JsonResult } from '../request-action-implementation.js';
 /**
- * Action that returns if the current user is authenticated
- * @param options The options for the Custom Action
- * @param options.injector The Injector from the current context
- * @returns A standard authentication result
+ * Returns `{ isAuthenticated: boolean }`. Unauthenticated callers receive
+ * a 200 with `false` rather than a 401 — use this when the client needs to
+ * branch on auth state without triggering a re-login flow.
  */
 export const IsAuthenticated = async ({ injector }) => {
     const isAuthenticatedResult = await isAuthenticated(injector);

package/esm/actions/is-authenticated.js.map

@@ -1 +1 @@
-{"version":3,"file":"is-authenticated.js","sourceRoot":"","sources":["../../src/actions/is-authenticated.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAA4D,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;IAC7G,MAAM,qBAAqB,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC7D,OAAO,UAAU,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE,CAAC,CAAA;AAC/D,CAAC,CAAA"}
+{"version":3,"file":"is-authenticated.js","sourceRoot":"","sources":["../../src/actions/is-authenticated.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAA4D,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;IAC7G,MAAM,qBAAqB,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC7D,OAAO,UAAU,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE,CAAC,CAAA;AAC/D,CAAC,CAAA"}

package/esm/actions/logout.d.ts

@@ -1,11 +1,7 @@
 import type { RequestAction } from '../request-action-implementation.js';
 /**
- * Action that logs out the current user
- * @param root0 The Options object
- * @param root0.injector The injector from the context
- * @param root0.request The current Request object
- * @param root0.response The Response object
- * @returns An empty result that indicates the success
+ * Logs out via {@link HttpUserContext.cookieLogout} — clears the session
+ * cookie and removes the session row from the session DataSet.
  */
 export declare const LogoutAction: RequestAction<{
     result: unknown;

package/esm/actions/logout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../src/actions/logout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAG3D,CAAA"}
+{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../src/actions/logout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAG3D,CAAA"}

package/esm/actions/logout.js

@@ -1,12 +1,8 @@
 import { HttpUserContext } from '../http-user-context.js';
 import { EmptyResult } from '../request-action-implementation.js';
 /**
- * Action that logs out the current user
- * @param root0 The Options object
- * @param root0.injector The injector from the context
- * @param root0.request The current Request object
- * @param root0.response The Response object
- * @returns An empty result that indicates the success
+ * Logs out via {@link HttpUserContext.cookieLogout} — clears the session
+ * cookie and removes the session row from the session DataSet.
  */
 export const LogoutAction = async ({ injector, request, response }) => {
     await injector.get(HttpUserContext).cookieLogout(request, response);

package/esm/actions/logout.js.map

@@ -1 +1 @@
-{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../src/actions/logout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AAEjE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAuC,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE;IACxG,MAAM,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACnE,OAAO,WAAW,EAAE,CAAA;AACtB,CAAC,CAAA"}
+{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../src/actions/logout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAuC,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE;IACxG,MAAM,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACnE,OAAO,WAAW,EAAE,CAAA;AACtB,CAAC,CAAA"}

package/esm/actions/not-found-action.d.ts

@@ -1,7 +1,5 @@
 import type { RequestAction } from '../request-action-implementation.js';
-/**
- * @returns The standard Not Found action result
- */
+/** Default `404` action. Returns `{ error: 'Content not found' }`. */
 export declare const NotFoundAction: RequestAction<{
     result: {
         error: string;

package/esm/actions/not-found-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"not-found-action.d.ts","sourceRoot":"","sources":["../../src/actions/not-found-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAOvE,CAAA"}
+{"version":3,"file":"not-found-action.d.ts","sourceRoot":"","sources":["../../src/actions/not-found-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAGxE,sEAAsE;AACtE,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAOvE,CAAA"}

package/esm/actions/not-found-action.js

@@ -1,7 +1,5 @@
 import { JsonResult } from '../request-action-implementation.js';
-/**
- * @returns The standard Not Found action result
- */
+/** Default `404` action. Returns `{ error: 'Content not found' }`. */
 export const NotFoundAction = async () => {
     return JsonResult({
         error: 'Content not found',

package/esm/actions/not-found-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"not-found-action.js","sourceRoot":"","sources":["../../src/actions/not-found-action.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiD,KAAK,IAAI,EAAE;IACrF,OAAO,UAAU,CACf;QACE,KAAK,EAAE,mBAAmB;KAC3B,EACD,GAAG,CACJ,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"not-found-action.js","sourceRoot":"","sources":["../../src/actions/not-found-action.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AAEhE,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAiD,KAAK,IAAI,EAAE;IACrF,OAAO,UAAU,CACf;QACE,KAAK,EAAE,mBAAmB;KAC3B,EACD,GAAG,CACJ,CAAA;AACH,CAAC,CAAA"}

package/esm/actions/password-login-action.d.ts

@@ -1,18 +1,11 @@
 import type { LoginResponseStrategy } from '../login-response-strategy.js';
 import type { RequestAction } from '../request-action-implementation.js';
 /**
- * Creates a login {@link RequestAction} that authenticates a user by
- * username + password, then delegates session/token creation to the
- * provided {@link LoginResponseStrategy}.
- *
- * The return type is inferred from the strategy:
- * - Cookie strategy -> `ActionResult<User>`
- * - JWT strategy   -> `ActionResult<{ accessToken: string; refreshToken: string }>`
- *
- * A random delay (0-1 s) is added on failure to mitigate timing attacks.
- *
- * @param strategy The login response strategy that produces the session/token result
- * @returns A `RequestAction` that can be wired into a REST API route
+ * Username + password login action. Authenticates via {@link HttpUserContext},
+ * then delegates session/token creation to `strategy`. The result type is
+ * inferred from the strategy (e.g. `User` for cookies, `{ accessToken,
+ * refreshToken }` for JWT). Adds a 0–1 s random delay on failure to mitigate
+ * timing attacks; rethrows as `RequestError(400)`.
  */
 export declare const createPasswordLoginAction: <TResult>(strategy: LoginResponseStrategy<TResult>) => RequestAction<{
     result: TResult;

package/esm/actions/password-login-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"password-login-action.d.ts","sourceRoot":"","sources":["../../src/actions/password-login-action.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAExE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,EAC/C,UAAU,qBAAqB,CAAC,OAAO,CAAC,KACvC,aAAa,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAWjF,CAAA"}
+{"version":3,"file":"password-login-action.d.ts","sourceRoot":"","sources":["../../src/actions/password-login-action.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,EAC/C,UAAU,qBAAqB,CAAC,OAAO,CAAC,KACvC,aAAa,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAWjF,CAAA"}

package/esm/actions/password-login-action.js

@@ -2,18 +2,11 @@ import { RequestError } from '@furystack/rest';
 import { sleepAsync } from '@furystack/utils';
 import { HttpUserContext } from '../http-user-context.js';
 /**
- * Creates a login {@link RequestAction} that authenticates a user by
- * username + password, then delegates session/token creation to the
- * provided {@link LoginResponseStrategy}.
- *
- * The return type is inferred from the strategy:
- * - Cookie strategy -> `ActionResult<User>`
- * - JWT strategy   -> `ActionResult<{ accessToken: string; refreshToken: string }>`
- *
- * A random delay (0-1 s) is added on failure to mitigate timing attacks.
- *
- * @param strategy The login response strategy that produces the session/token result
- * @returns A `RequestAction` that can be wired into a REST API route
+ * Username + password login action. Authenticates via {@link HttpUserContext},
+ * then delegates session/token creation to `strategy`. The result type is
+ * inferred from the strategy (e.g. `User` for cookies, `{ accessToken,
+ * refreshToken }` for JWT). Adds a 0–1 s random delay on failure to mitigate
+ * timing attacks; rethrows as `RequestError(400)`.
  */
 export const createPasswordLoginAction = (strategy) => {
     return async ({ injector, getBody }) => {

package/esm/actions/password-login-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"password-login-action.js","sourceRoot":"","sources":["../../src/actions/password-login-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAIzD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAAwC,EAC0C,EAAE;IACpF,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAA;QAC5B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC/F,OAAO,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAA;YACtC,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,GAAG,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"password-login-action.js","sourceRoot":"","sources":["../../src/actions/password-login-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAIzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAAwC,EAC0C,EAAE;IACpF,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAA;QAC5B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC/F,OAAO,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAA;YACtC,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,GAAG,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC,CAAA;AACH,CAAC,CAAA"}

package/esm/authenticate.d.ts

@@ -1,20 +1,14 @@
 import type { RequestAction } from './request-action-implementation.js';
 /**
- * Higher-order function that wraps a request action to require authentication.
- * If the user is not authenticated, returns a 401 Unauthorized response.
- * Includes a random delay on unauthorized requests to mitigate timing attacks.
+ * Wraps a {@link RequestAction} to require authentication. Unauthenticated
+ * requests return `401 Unauthorized` (with `WWW-Authenticate: Basic` when
+ * the chain includes Basic Auth). Adds a 0–1 s random delay on rejection to
+ * mitigate timing attacks.
  *
- * @returns A function that wraps the provided action with authentication check
  * @example
  * ```ts
- * // Wrap an endpoint to require authentication
- * const protectedEndpoint = Authenticate()(myEndpoint)
- *
- * // Or use directly in API definition
  * api: {
- *   GET: {
- *     '/users': Authenticate()(getUsersEndpoint)
- *   }
+ *   GET: { '/users': Authenticate()(getUsersEndpoint) },
  * }
  * ```
  */

package/esm/authenticate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authenticate.d.ts","sourceRoot":"","sources":["../src/authenticate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,aAAa,EAAwB,MAAM,oCAAoC,CAAA;AAG3G;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,SAEtB,CAAC,SAAS;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,aAAa,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAqBzE,CAAA"}
+{"version":3,"file":"authenticate.d.ts","sourceRoot":"","sources":["../src/authenticate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,aAAa,EAAwB,MAAM,oCAAoC,CAAA;AAG3G;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,SAEtB,CAAC,SAAS;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,aAAa,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAqBzE,CAAA"}

package/esm/authenticate.js

@@ -3,21 +3,15 @@ import { sleepAsync } from '@furystack/utils';
 import { HttpUserContext } from './http-user-context.js';
 import { JsonResult } from './request-action-implementation.js';
 /**
- * Higher-order function that wraps a request action to require authentication.
- * If the user is not authenticated, returns a 401 Unauthorized response.
- * Includes a random delay on unauthorized requests to mitigate timing attacks.
+ * Wraps a {@link RequestAction} to require authentication. Unauthenticated
+ * requests return `401 Unauthorized` (with `WWW-Authenticate: Basic` when
+ * the chain includes Basic Auth). Adds a 0–1 s random delay on rejection to
+ * mitigate timing attacks.
  *
- * @returns A function that wraps the provided action with authentication check
  * @example
  * ```ts
- * // Wrap an endpoint to require authentication
- * const protectedEndpoint = Authenticate()(myEndpoint)
- *
- * // Or use directly in API definition
  * api: {
- *   GET: {
- *     '/users': Authenticate()(getUsersEndpoint)
- *   }
+ *   GET: { '/users': Authenticate()(getUsersEndpoint) },
  * }
  * ```
  */

package/esm/authenticate.js.map

@@ -1 +1 @@
-{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../src/authenticate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,GAAG,EAAE,CACL,CAAgC,MAAwB,EAAoB,EAAE;IAC5E,MAAM,OAAO,GAAG,KAAK,EAAE,IAA6B,EAA4B,EAAE;QAChF,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;QACzB,MAAM,aAAa,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;QACrD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAA;YACtC,MAAM,YAAY,GAAG,QAAQ;iBAC1B,GAAG,CAAC,eAAe,CAAC;iBACpB,cAAc,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAA;YAC9E,OAAO,UAAU,CACf,EAAE,KAAK,EAAE,cAAc,EAAE,EACzB,GAAG,EACH,YAAY,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CACtB,CAAA;QACjC,CAAC;QACD,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAoB,CAAA;IAChD,CAAC,CAAA;IAED,OAAO,CAAC,eAAe,GAAG,IAAI,CAAA;IAE9B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../src/authenticate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,GAAG,EAAE,CACL,CAAgC,MAAwB,EAAoB,EAAE;IAC5E,MAAM,OAAO,GAAG,KAAK,EAAE,IAA6B,EAA4B,EAAE;QAChF,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;QACzB,MAAM,aAAa,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;QACrD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAA;YACtC,MAAM,YAAY,GAAG,QAAQ;iBAC1B,GAAG,CAAC,eAAe,CAAC;iBACpB,cAAc,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAA;YAC9E,OAAO,UAAU,CACf,EAAE,KAAK,EAAE,cAAc,EAAE,EACzB,GAAG,EACH,YAAY,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CACtB,CAAA;QACjC,CAAC;QACD,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAoB,CAAA;IAChD,CAAC,CAAA;IAED,OAAO,CAAC,eAAe,GAAG,IAAI,CAAA;IAE9B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/esm/authentication-providers/authentication-provider.d.ts

@@ -21,5 +21,22 @@ export type AuthenticationProvider = {
      */
     readonly name: string;
     authenticate: (request: Pick<IncomingMessage, 'headers'>) => Promise<User | null>;
+    /**
+     * Optional cache-key resolver consulted by the user-resolution cache before
+     * the provider chain is walked.
+     *
+     * Returns a stable, opaque string identifying the authenticated principal
+     * for the given request, or `null` when this provider does not apply to
+     * the request (or refuses to participate in caching — e.g. Basic Auth,
+     * which must verify the password on every request).
+     *
+     * The first non-null key returned by the configured providers is used as
+     * the cache key. Keys returned by different providers must not collide;
+     * built-in providers prefix their keys (`cookie:`, `jwt:`).
+     *
+     * If no provider returns a key, the request bypasses the cache entirely
+     * and the provider chain is walked on every call.
+     */
+    readonly getCacheKey?: (request: Pick<IncomingMessage, 'headers'>) => string | null;
 };
 //# sourceMappingURL=authentication-provider.d.ts.map

package/esm/authentication-providers/authentication-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authentication-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/authentication-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;CAClF,CAAA"}
+{"version":3,"file":"authentication-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/authentication-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;IACjF;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;CACpF,CAAA"}

package/esm/authentication-providers/basic-auth-provider.d.ts

@@ -2,6 +2,13 @@ import type { User } from '@furystack/core';
 import type { AuthenticationProvider } from './authentication-provider.js';
 /**
  * Creates an authentication provider for HTTP Basic Authentication.
+ *
+ * **Caching note:** this provider intentionally does **not** implement
+ * `getCacheKey`. Caching authenticated users by username would bypass
+ * password verification on every cache hit — the cache cannot revalidate the
+ * password without re-running the authenticator. Basic Auth requests
+ * therefore always walk the provider chain, which is also where the password
+ * is verified.
  * @param authenticateUser Callback that verifies credentials and returns a User or throws
  */
 export declare const createBasicAuthProvider: (authenticateUser: (username: string, password: string) => Promise<User>) => AuthenticationProvider;

package/esm/authentication-providers/basic-auth-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basic-auth-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/basic-auth-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAE1E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KACtE,sBAWD,CAAA"}
+{"version":3,"file":"basic-auth-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/basic-auth-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAClC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KACtE,sBAWD,CAAA"}

package/esm/authentication-providers/basic-auth-provider.js

@@ -1,5 +1,12 @@
 /**
  * Creates an authentication provider for HTTP Basic Authentication.
+ *
+ * **Caching note:** this provider intentionally does **not** implement
+ * `getCacheKey`. Caching authenticated users by username would bypass
+ * password verification on every cache hit — the cache cannot revalidate the
+ * password without re-running the authenticator. Basic Auth requests
+ * therefore always walk the provider chain, which is also where the password
+ * is verified.
  * @param authenticateUser Callback that verifies credentials and returns a User or throws
  */
 export const createBasicAuthProvider = (authenticateUser) => ({

package/esm/authentication-providers/basic-auth-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"basic-auth-provider.js","sourceRoot":"","sources":["../../src/authentication-providers/basic-auth-provider.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,gBAAuE,EAC/C,EAAE,CAAC,CAAC;IAC5B,IAAI,EAAE,YAAY;IAClB,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAA;QAChD,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAA;QAClD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;QAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;QAC9C,OAAO,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACnD,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"basic-auth-provider.js","sourceRoot":"","sources":["../../src/authentication-providers/basic-auth-provider.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,gBAAuE,EAC/C,EAAE,CAAC,CAAC;IAC5B,IAAI,EAAE,YAAY;IAClB,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAA;QAChD,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAA;QAClD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;QAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;QAC9C,OAAO,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACnD,CAAC;CACF,CAAC,CAAA"}

package/esm/authentication-providers/cookie-auth-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-auth-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/cookie-auth-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAG1E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,YAAY,MAAM,EAClB,gBAAgB,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,EACrE,eAAe,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KACjD,sBASD,CAAA"}
+{"version":3,"file":"cookie-auth-provider.d.ts","sourceRoot":"","sources":["../../src/authentication-providers/cookie-auth-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAG1E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,YAAY,MAAM,EAClB,gBAAgB,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,EACrE,eAAe,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KACjD,sBAgBD,CAAA"}

package/esm/authentication-providers/cookie-auth-provider.js

@@ -1,4 +1,5 @@
 import { UnauthenticatedError } from '@furystack/security';
+import { sessionCacheKey } from '../identity-cache-keys.js';
 import { extractSessionIdFromCookies } from './helpers.js';
 /**
  * Creates an authentication provider for cookie-based session authentication.
@@ -17,5 +18,12 @@ export const createCookieAuthProvider = (cookieName, getSessionById, getUserByNa
             throw new UnauthenticatedError();
         return await getUserByName(session.username);
     },
+    // The session id alone uniquely identifies the principal — caching by it is
+    // safe because session invalidation (logout, expiry) drops the session row,
+    // and the TTL on the user-resolution cache bounds staleness across nodes.
+    getCacheKey: (request) => {
+        const sessionId = extractSessionIdFromCookies(request, cookieName);
+        return sessionId ? sessionCacheKey(sessionId) : null;
+    },
 });
 //# sourceMappingURL=cookie-auth-provider.js.map

package/esm/authentication-providers/cookie-auth-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-auth-provider.js","sourceRoot":"","sources":["../../src/authentication-providers/cookie-auth-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAG1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,UAAkB,EAClB,cAAqE,EACrE,aAAkD,EAC1B,EAAE,CAAC,CAAC;IAC5B,IAAI,EAAE,aAAa;IACnB,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAClE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAA;QAC3B,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,oBAAoB,EAAE,CAAA;QAC9C,OAAO,MAAM,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9C,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"cookie-auth-provider.js","sourceRoot":"","sources":["../../src/authentication-providers/cookie-auth-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAwB,MAAM,2BAA2B,CAAA;AAGjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,UAAkB,EAClB,cAAqE,EACrE,aAAkD,EAC1B,EAAE,CAAC,CAAC;IAC5B,IAAI,EAAE,aAAa;IACnB,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAClE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAA;QAC3B,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,oBAAoB,EAAE,CAAA;QAC9C,OAAO,MAAM,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9C,CAAC;IACD,4EAA4E;IAC5E,4EAA4E;IAC5E,0EAA0E;IAC1E,WAAW,EAAE,CAAC,OAAO,EAA0B,EAAE;QAC/C,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAClE,OAAO,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACtD,CAAC;CACF,CAAC,CAAA"}

package/esm/authorize.d.ts

@@ -1,22 +1,10 @@
 import type { RequestAction } from './request-action-implementation.js';
 /**
- * Higher-order function that wraps a request action to require specific roles.
- * If the user does not have the required roles, throws an AuthorizationError.
- * Includes a random delay on unauthorized requests to mitigate timing attacks.
- *
- * @param roles - The roles required to access the endpoint
- * @returns A function that wraps the provided action with authorization check
- * @example
- * ```ts
- * // Require 'admin' role
- * const adminEndpoint = Authorize('admin')(myEndpoint)
- *
- * // Require multiple roles (user must have ALL specified roles)
- * const superAdminEndpoint = Authorize('admin', 'superuser')(myEndpoint)
- *
- * // Chain with Authenticate for authentication + authorization
- * const protectedEndpoint = Authenticate()(Authorize('admin')(myEndpoint))
- * ```
+ * Wraps a {@link RequestAction} to require **all** specified roles. Throws
+ * {@link AuthorizationError} (translated to 403 by `ErrorAction`) when any
+ * role is missing. Adds a 0–1 s random delay on rejection to mitigate
+ * timing attacks. Compose with {@link Authenticate} to require both:
+ * `Authenticate()(Authorize('admin')(myEndpoint))`.
  */
 export declare const Authorize: (...roles: string[]) => <T extends {
     result: unknown;

package/esm/authorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgB,aAAa,EAAwB,MAAM,oCAAoC,CAAA;AAE3G;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS,GACnB,GAAG,OAAO,MAAM,EAAE,MAClB,CAAC,SAAS;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,aAAa,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAazE,CAAA"}
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,aAAa,EAAwB,MAAM,oCAAoC,CAAA;AAE3G;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACnB,GAAG,OAAO,MAAM,EAAE,MAClB,CAAC,SAAS;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,aAAa,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAazE,CAAA"}