@haneinfo/frontend-auth 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +32 -0
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,3 +6,35 @@ authorization scope to `createFrontendAuth()`.
6
6
 
7
7
  The returned session callback exposes the stable refresh error code but never bearer or refresh
8
8
  tokens. Server actions use `getAccessToken()` and `getKeycloakEndSessionUrl()` as needed.
9
+
10
+ Session readers follow `AUTH_URL` / `NEXTAUTH_URL` or the forwarded protocol, including Auth.js's
11
+ HTTPS default. Pass `useSecureCookies` and `cookies.sessionToken` to the factory when overriding
12
+ Auth.js cookie settings; both Auth.js and the token readers use those options.
13
+
14
+ ## Refresh-token rotation
15
+
16
+ The default cookie-backed mode keeps the existing behavior and supports providers that reuse their
17
+ refresh token. To use a provider that rotates refresh tokens, pass a `FrontendAuthTokenStore` to
18
+ `createFrontendAuth()`. The Auth.js JWT cookie then contains an opaque session id; access, refresh,
19
+ and ID tokens stay in the server-side store. Both `getAccessToken()` and the Auth.js JWT callback
20
+ refresh under the same store lock, so read-only Server Component renders can safely persist a new
21
+ refresh token without writing a cookie.
22
+
23
+ The application supplies the storage adapter because it owns the database or distributed cache.
24
+ Every application instance must use the same store. Its `runExclusive(sessionId, operation)` must
25
+ serialize the full read, provider call, and durable update for a session across processes. `update()`
26
+ must be durable before it returns; `create()` must not overwrite an existing id. Store token values
27
+ encrypted at rest, expire records at `sessionExpiresAt`, and make `delete()` idempotent. Auth.js uses
28
+ a 30-day JWT session lifetime in this factory, renewed by its JWT callback. Sign-out deletes the
29
+ stored record while holding the same lock.
30
+
31
+ When enabling the store for existing users, an Auth.js JWT callback migrates a legacy cookie into
32
+ the store and replaces its tokens with the opaque id. Until that callback has migrated an old
33
+ cookie, `getAccessToken()` returns a still-valid access token; it will not rotate an expired legacy
34
+ cookie because a read-only token reader cannot persist the required session id.
35
+
36
+ The store lock prevents concurrent refreshes from multiple app instances. A process can still fail
37
+ after the identity provider consumes a refresh token and before the rotated value is durably stored;
38
+ the local store and remote identity provider cannot commit atomically. Deployments should use an
39
+ identity-provider grace window when available and monitor refresh failures. The adapter must never
40
+ log token values.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@haneinfo/frontend-auth",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Shared server-side NextAuth integration for Haneinfo Apps",