@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.
- package/README.md +32 -0
- 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.
|