@eventuras/fides-auth-next 0.8.1 → 1.0.0-beta.1
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 +162 -108
- package/dist/auth.d.ts +101 -54
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +65 -75
- package/dist/auth.js.map +1 -1
- package/dist/cookie-store.d.ts +3 -5
- package/dist/cookie-store.d.ts.map +1 -1
- package/dist/cookie-store.js +3 -8
- package/dist/cookie-store.js.map +1 -1
- package/dist/index.d.ts +4 -21
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -18
- package/package.json +9 -43
- package/dist/cookies.d.ts +0 -132
- package/dist/cookies.d.ts.map +0 -1
- package/dist/cookies.js +0 -220
- package/dist/cookies.js.map +0 -1
- package/dist/heartbeat-handler.d.ts +0 -36
- package/dist/heartbeat-handler.d.ts.map +0 -1
- package/dist/heartbeat-handler.js +0 -40
- package/dist/heartbeat-handler.js.map +0 -1
- package/dist/oidc-callback.d.ts +0 -60
- package/dist/oidc-callback.d.ts.map +0 -1
- package/dist/oidc-callback.js +0 -45
- package/dist/oidc-callback.js.map +0 -1
- package/dist/oidc-login.d.ts +0 -37
- package/dist/oidc-login.d.ts.map +0 -1
- package/dist/oidc-login.js +0 -36
- package/dist/oidc-login.js.map +0 -1
- package/dist/oidc-logout.d.ts +0 -56
- package/dist/oidc-logout.d.ts.map +0 -1
- package/dist/oidc-logout.js +0 -47
- package/dist/oidc-logout.js.map +0 -1
- package/dist/request.d.ts +0 -11
- package/dist/request.d.ts.map +0 -1
- package/dist/request.js +0 -43
- package/dist/request.js.map +0 -1
- package/dist/store/index.d.ts +0 -103
- package/dist/store/index.d.ts.map +0 -1
- package/dist/store/index.js +0 -3
package/README.md
CHANGED
|
@@ -1,116 +1,195 @@
|
|
|
1
1
|
# @eventuras/fides-auth-next
|
|
2
2
|
|
|
3
|
-
Next.js
|
|
3
|
+
Next.js bindings for `@eventuras/fides-auth`. `createFidesAuth` here is the core
|
|
4
|
+
instance bound to `cookies()` from `next/headers`. It caches session reads per
|
|
5
|
+
render with React's `cache()`, and adds a refresh for `proxy.ts`.
|
|
4
6
|
|
|
5
7
|
## Installation
|
|
6
8
|
|
|
7
9
|
```bash
|
|
8
|
-
pnpm add @eventuras/fides-auth
|
|
10
|
+
pnpm add @eventuras/fides-auth @eventuras/fides-auth-next
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
`@eventuras/fides-auth`, `next` and `react` are peer dependencies, so the app
|
|
14
|
+
has one copy of core. Needs Node 22.
|
|
12
15
|
|
|
13
|
-
|
|
14
|
-
// 1. Create store
|
|
15
|
-
import {
|
|
16
|
-
createAuthStore,
|
|
17
|
-
createAuthStoreHooks,
|
|
18
|
-
} from "@eventuras/fides-auth-next/store";
|
|
19
|
-
|
|
20
|
-
export const authStore = createAuthStore({
|
|
21
|
-
checkAuthStatus: getAuthStatus,
|
|
22
|
-
config: { adminRole: "Admin" },
|
|
23
|
-
});
|
|
24
|
-
|
|
25
|
-
export const { useAuthStore, useAuthActions } = createAuthStoreHooks(authStore);
|
|
26
|
-
|
|
27
|
-
// 2. Initialize in app
|
|
28
|
-
useEffect(() => {
|
|
29
|
-
initializeAuth(authStore, getAuthStatus);
|
|
30
|
-
return startSessionMonitor(authStore, getAuthStatus, { interval: 30_000 });
|
|
31
|
-
}, []);
|
|
32
|
-
|
|
33
|
-
// 3. Use in components
|
|
34
|
-
const { isAuthenticated, user, isAdmin } = useAuthStore();
|
|
35
|
-
const { logout } = useAuthActions();
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## Features
|
|
16
|
+
## Setup
|
|
39
17
|
|
|
40
|
-
|
|
41
|
-
- **Cookie Helpers**: Server-side cookie operations
|
|
42
|
-
- **Session Management**: High-level session functions
|
|
43
|
-
- **OAuth**: Complete OAuth flow with PKCE and RP-initiated logout
|
|
44
|
-
- **TypeScript**: Full type safety
|
|
45
|
-
|
|
46
|
-
## Server Setup
|
|
47
|
-
|
|
48
|
-
Create one instance and import it where you need it. The library never reads
|
|
49
|
-
the environment, so pass the secret in:
|
|
18
|
+
Create one instance in a module of its own and import it where you need it:
|
|
50
19
|
|
|
51
20
|
```typescript
|
|
52
21
|
// lib/auth.ts
|
|
53
22
|
import { createFidesAuth } from "@eventuras/fides-auth-next";
|
|
54
23
|
|
|
55
24
|
export const auth = createFidesAuth({
|
|
25
|
+
oauthConfig: {
|
|
26
|
+
issuer: process.env.OIDC_ISSUER!,
|
|
27
|
+
clientId: process.env.OIDC_CLIENT_ID!,
|
|
28
|
+
clientSecret: process.env.OIDC_CLIENT_SECRET!,
|
|
29
|
+
redirectUri: "https://app.example.com/api/auth/callback",
|
|
30
|
+
scope: "openid profile email offline_access",
|
|
31
|
+
},
|
|
56
32
|
secret: process.env.SESSION_SECRET!, // openssl rand -hex 32
|
|
57
|
-
oauthConfig,
|
|
58
33
|
});
|
|
59
34
|
```
|
|
60
35
|
|
|
61
|
-
|
|
36
|
+
The library never reads the environment, so pass the values in. It checks the
|
|
37
|
+
secret and the redirect URI on first use, so `next build` can import the module
|
|
38
|
+
without them. A client with `clientAuth: 'none'` throws at once: the server side
|
|
39
|
+
of an app is a confidential client.
|
|
40
|
+
|
|
41
|
+
| Option | Default | |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| `sessionStore` | none | Keeps sessions in a store, with only a handle in the cookie. See below. |
|
|
44
|
+
| `storeFields` | none | `(session) => fields`. Plain fields to keep next to each stored session, e.g. your own user id. |
|
|
45
|
+
| `sessionDurationDays` | 30 | How long a session lasts from login. Refreshes don't extend it. |
|
|
46
|
+
| `applicationUrl` | the redirect URI's origin | The app's public origin, for the same-origin check and redirects. |
|
|
47
|
+
| `mapSession` | none | Changes the session built at login, e.g. to add `data`. |
|
|
48
|
+
| `rolesClaim` | `'roles'` | The ID token claim that holds the user's roles, at login and on every refresh that brings an ID token. |
|
|
49
|
+
| `validateReturnTo` | a path on this origin | Turns `?returnTo=` into a safe path, or null. |
|
|
50
|
+
| `defaultRedirectPath` | `'/'` | Where a login without a return path lands. |
|
|
51
|
+
| `postLogoutRedirectUri` | `applicationUrl` | Where the provider sends the user after logout. |
|
|
52
|
+
| `rateLimit` | none | `(request) => boolean`. The handlers answer 429 when it returns false. |
|
|
53
|
+
| `logger` | JSON lines on the console | A `FidesLoggerFactory`. |
|
|
54
|
+
| `onSessionEvent` | none | Gets every session event. See [session events](../fides-auth/docs/session-events.md). |
|
|
55
|
+
|
|
56
|
+
## Route handlers
|
|
62
57
|
|
|
63
58
|
```typescript
|
|
64
59
|
// app/api/auth/login/route.ts
|
|
65
60
|
export const GET = (request: Request) => auth.handleOidcLogin(request);
|
|
66
61
|
|
|
67
|
-
// app/api/auth/callback/
|
|
68
|
-
export const GET = (request: Request) =>
|
|
69
|
-
auth.handleOidcCallback(request, { applicationUrl: "https://app.example.com" });
|
|
62
|
+
// app/api/auth/callback/route.ts
|
|
63
|
+
export const GET = (request: Request) => auth.handleOidcCallback(request);
|
|
70
64
|
|
|
71
65
|
// app/api/auth/logout/route.ts
|
|
72
|
-
export const POST = (request: Request) =>
|
|
73
|
-
|
|
66
|
+
export const POST = (request: Request) => auth.handleOidcLogout(request);
|
|
67
|
+
|
|
68
|
+
// app/api/auth/session/route.ts
|
|
69
|
+
export const GET = (request: Request) => auth.handleSessionInfo(request);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The callback's path must be the redirect URI's. Login takes `?returnTo=/path`
|
|
73
|
+
and lands there with `?login=success`.
|
|
74
|
+
|
|
75
|
+
Logout answers only a `POST` from the app's own pages, so a form does it:
|
|
74
76
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
+
```tsx
|
|
78
|
+
<form method="post" action="/api/auth/logout">
|
|
79
|
+
<button>Log out</button>
|
|
80
|
+
</form>
|
|
77
81
|
```
|
|
78
82
|
|
|
79
|
-
|
|
83
|
+
`handleSessionInfo` answers whether there is a session, and whose. It never
|
|
84
|
+
refreshes and never returns tokens. `handleHeartbeat` is there for apps that tie
|
|
85
|
+
refreshes to user activity; it too answers only a same-origin `POST`.
|
|
86
|
+
|
|
87
|
+
## Reading the session
|
|
88
|
+
|
|
89
|
+
In Server Components, Server Actions and Route Handlers:
|
|
80
90
|
|
|
81
91
|
```typescript
|
|
82
|
-
const session = await auth.
|
|
83
|
-
const { reason } = await auth.
|
|
84
|
-
const
|
|
85
|
-
await auth.clearCurrentSession();
|
|
92
|
+
const session = await auth.readSession(); // Session | null
|
|
93
|
+
const { session, reason } = await auth.tryReadSession();
|
|
94
|
+
const tokens = await auth.getTokens(); // Tokens | null
|
|
86
95
|
```
|
|
87
96
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
97
|
+
`readSession` and `tryReadSession` share one read per render. A `Session` has
|
|
98
|
+
`user`, `scopes`, `data`, `idp`, `correlationId`, `createdAt` and `expiresAt`.
|
|
99
|
+
The tokens aren't on it: `getTokens` returns them, and `authorizedFetch` uses
|
|
100
|
+
them.
|
|
101
|
+
|
|
102
|
+
`createSession`, `updateSession`, `refreshSession` and `clearSession` write
|
|
103
|
+
cookies, so they work in Server Actions and Route Handlers.
|
|
104
|
+
|
|
105
|
+
## Keeping the session fresh
|
|
106
|
+
|
|
107
|
+
Nothing refreshes unless you ask, with `refreshSession` or `refreshInProxy`.
|
|
108
|
+
Reads and `authorizedFetch` never do, so they are safe anywhere.
|
|
109
|
+
|
|
110
|
+
A Server Component can't set cookies, so it can't save a refreshed session.
|
|
111
|
+
Refresh in the proxy instead, before the page renders:
|
|
92
112
|
|
|
93
113
|
```typescript
|
|
94
|
-
|
|
114
|
+
// proxy.ts
|
|
115
|
+
import type { NextRequest } from "next/server";
|
|
116
|
+
import { auth } from "@/lib/auth";
|
|
117
|
+
|
|
118
|
+
export function proxy(request: NextRequest) {
|
|
119
|
+
return auth.refreshInProxy(request);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export const config = {
|
|
123
|
+
matcher: ["/((?!api/auth|_next/static|_next/image|favicon.ico).*)"],
|
|
124
|
+
};
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`refreshInProxy` refreshes a session whose access token expires within 60
|
|
128
|
+
seconds; `ifExpiresWithin` changes that. The window never covers more than half
|
|
129
|
+
the token's lifetime, so a token shorter than the window isn't refreshed on
|
|
130
|
+
every request. It sets the new cookies on the response and on the request it
|
|
131
|
+
forwards, so the page renders with the refreshed session. A request without a
|
|
132
|
+
session cookie passes straight through, and a failed refresh leaves the session
|
|
133
|
+
as it is.
|
|
134
|
+
|
|
135
|
+
The proxy runs for every request a page makes, prefetches included. With cookie
|
|
136
|
+
sessions and a provider that rotates refresh tokens, a request sent before the
|
|
137
|
+
new cookies arrived refreshes with a spent token and fails with
|
|
138
|
+
`invalid_grant`; see
|
|
139
|
+
[Keeping the session fresh](../fides-auth/README.md#keeping-the-session-fresh)
|
|
140
|
+
in the core README. A `sessionStore` avoids it.
|
|
95
141
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
142
|
+
To send users without a session to the login, check the cookie first:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import { NextResponse, type NextRequest } from "next/server";
|
|
146
|
+
|
|
147
|
+
export function proxy(request: NextRequest) {
|
|
148
|
+
if (!request.cookies.has(auth.cookieNames.session)) {
|
|
149
|
+
return NextResponse.redirect(new URL("/api/auth/login", request.url));
|
|
150
|
+
}
|
|
151
|
+
return auth.refreshInProxy(request);
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
In a Server Action or Route Handler, refresh first if the access token is about
|
|
156
|
+
to expire. Without `ifExpiresWithin`, `refreshSession` refreshes at once:
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
await auth.refreshSession({ ifExpiresWithin: 60 });
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The result says whether it `refreshed`. On failure it gives a `reason`, and
|
|
163
|
+
`cause: "invalid_grant"` means the user must log in again.
|
|
164
|
+
|
|
165
|
+
## Calling APIs
|
|
166
|
+
|
|
167
|
+
`authorizedFetch` sends the access token to URLs under `allowedBase`. It never
|
|
168
|
+
refreshes, so it works the same in a Server Component, a Server Action and a
|
|
169
|
+
Route Handler:
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
const { data } = await auth.authorizedFetch("users/me", {
|
|
173
|
+
allowedBase: "https://api.example.com/v1/",
|
|
99
174
|
parse: (response) => response.json(),
|
|
100
175
|
});
|
|
101
|
-
|
|
102
|
-
// Server Component
|
|
103
|
-
const { data } = await auth.authorizedFetch(session, "users/me", { ...api, refresh: false });
|
|
104
176
|
```
|
|
105
177
|
|
|
106
|
-
|
|
107
|
-
|
|
178
|
+
A 401 throws an `AuthorizedFetchError` with the reason `http_error`. Pages get
|
|
179
|
+
fresh tokens from `refreshInProxy`; in a Server Action or Route Handler, call
|
|
180
|
+
`refreshSession({ ifExpiresWithin: 60 })` before the request.
|
|
181
|
+
|
|
182
|
+
The error says why, where it can. `accessTokenExpired` is true when the token
|
|
183
|
+
had passed its expiry by the server's clock. `bearerError` is the API's own
|
|
184
|
+
reason from its `WWW-Authenticate` header: `invalid_token` means a refresh may
|
|
185
|
+
help, and `insufficient_scope` means it won't.
|
|
108
186
|
|
|
109
187
|
## Server sessions
|
|
110
188
|
|
|
111
|
-
By default the session lives in
|
|
112
|
-
it on the server
|
|
113
|
-
|
|
189
|
+
By default the session lives in the `__Host-session` cookie, in up to three
|
|
190
|
+
chunks. Pass a `sessionStore` to keep it on the server. The browser then holds
|
|
191
|
+
only a random handle, and logout deletes the record.
|
|
192
|
+
[Cookie or store](../fides-auth/README.md#cookie-or-store) compares the two.
|
|
114
193
|
|
|
115
194
|
```typescript
|
|
116
195
|
// lib/auth.ts
|
|
@@ -122,57 +201,32 @@ const sessionStore: SessionStore = {
|
|
|
122
201
|
delete: (key) => db.sessions.remove(key),
|
|
123
202
|
};
|
|
124
203
|
|
|
125
|
-
export const auth = createFidesAuth({
|
|
126
|
-
secret: process.env.SESSION_SECRET!,
|
|
127
|
-
oauthConfig,
|
|
128
|
-
sessionStore,
|
|
129
|
-
});
|
|
204
|
+
export const auth = createFidesAuth({ oauthConfig, secret, sessionStore });
|
|
130
205
|
```
|
|
131
206
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
207
|
+
With a store that implements `findMatching`, `auth.endUserSessions({ sub })`
|
|
208
|
+
ends every session of one user, wherever they are signed in, and revokes their
|
|
209
|
+
refresh tokens.
|
|
135
210
|
|
|
136
211
|
Use a store that every instance shares, such as a database, and add `withLock`
|
|
137
212
|
when you run more than one instance. `createMemorySessionStore()` from
|
|
138
213
|
`@eventuras/fides-auth/server` is for tests. See
|
|
139
214
|
[Server-side sessions](../fides-auth/docs/server-sessions.md) for the store
|
|
140
|
-
contract
|
|
215
|
+
contract.
|
|
141
216
|
|
|
142
217
|
## Rate limiting
|
|
143
218
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
`X-Forwarded-For` header, which a client can send itself, and lets requests
|
|
147
|
-
without the header through.
|
|
148
|
-
|
|
149
|
-
For a limiter of your own, add `@eventuras/fides-auth` and call its handler from
|
|
150
|
-
`/server` with the Next cookie store and a `rateLimit` callback. Key it on
|
|
151
|
-
something the app trusts, such as the client address your own proxy sets. The
|
|
152
|
-
handler answers 429 when the callback returns `false`:
|
|
219
|
+
There is no default limiter. Pass `rateLimit`, keyed on something the app
|
|
220
|
+
trusts, such as the client address your own proxy sets:
|
|
153
221
|
|
|
154
222
|
```typescript
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
return handleOidcLogin(request, {
|
|
161
|
-
oauthConfig,
|
|
162
|
-
secret: process.env.SESSION_SECRET!,
|
|
163
|
-
cookies: await nextCookieStore(),
|
|
164
|
-
rateLimit: () => limiter.consume(clientKey(request)),
|
|
165
|
-
});
|
|
166
|
-
}
|
|
223
|
+
export const auth = createFidesAuth({
|
|
224
|
+
oauthConfig,
|
|
225
|
+
secret,
|
|
226
|
+
rateLimit: (request) => limiter.consume(clientKey(request)),
|
|
227
|
+
});
|
|
167
228
|
```
|
|
168
229
|
|
|
169
|
-
|
|
170
|
-
With a `sessionStore`, also pass those three
|
|
171
|
-
`persistence: serverPersistence({ store: sessionStore, secret })`, or they keep
|
|
172
|
-
the session in cookies. Build it once. It does not share refreshes with `auth`,
|
|
173
|
-
so give the store `withLock`.
|
|
174
|
-
|
|
175
|
-
## Documentation
|
|
230
|
+
## Upgrading from 0.x
|
|
176
231
|
|
|
177
|
-
|
|
178
|
-
- [Setup Guide](./SETUP_GUIDE.md) - Complete walkthrough
|
|
232
|
+
See [Upgrading to 1.0](../fides-auth/docs/migrating-to-1.0.md).
|
package/dist/auth.d.ts
CHANGED
|
@@ -1,76 +1,123 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* createFidesAuth for Next.js. The core instance takes a CookieStore on every
|
|
3
|
+
* call; this one gets it from `cookies()` in next/headers, caches session reads
|
|
4
|
+
* per render, and adds refreshInProxy for `proxy.ts`.
|
|
5
5
|
*/
|
|
6
|
-
import
|
|
7
|
-
import type {
|
|
8
|
-
import type
|
|
9
|
-
import {
|
|
10
|
-
import { type
|
|
11
|
-
|
|
12
|
-
export
|
|
13
|
-
export type { SessionStore, StoredSession };
|
|
14
|
-
export type { AuthorizedFetchErrorReason, AuthorizedFetchOptions, AuthorizedFetchResult };
|
|
15
|
-
export { AuthorizedFetchError };
|
|
16
|
-
export interface FidesAuthConfig {
|
|
17
|
-
/** Session encryption secret, e.g. 64 hex chars. Also seals the login transaction. */
|
|
18
|
-
secret: SessionSecret;
|
|
19
|
-
/** OAuth/OIDC configuration. */
|
|
20
|
-
oauthConfig: OAuthConfig;
|
|
6
|
+
import type { Session, TokenResponse, Tokens } from '@eventuras/fides-auth';
|
|
7
|
+
import type { OidcClient } from '@eventuras/fides-auth/oidc';
|
|
8
|
+
import { type FidesAuthConfig, type FidesAuthorizedFetchOptions, type FidesReadResult, type FidesRefreshResult, type RefreshSessionOptions } from '@eventuras/fides-auth/server';
|
|
9
|
+
import type { SessionClearedTrigger } from '@eventuras/fides-auth/session-events';
|
|
10
|
+
import { type NextRequest, NextResponse } from 'next/server';
|
|
11
|
+
/** Options for {@link FidesAuth.refreshInProxy}. */
|
|
12
|
+
export interface RefreshInProxyOptions {
|
|
21
13
|
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
14
|
+
* Refresh when the access token expires within this many seconds, or within
|
|
15
|
+
* half its lifetime if that is shorter.
|
|
16
|
+
* @default 60
|
|
24
17
|
*/
|
|
25
|
-
|
|
18
|
+
ifExpiresWithin?: number;
|
|
26
19
|
}
|
|
27
|
-
/**
|
|
28
|
-
type Bound<T> = Omit<T, 'oauthConfig' | 'secret' | 'persistence'>;
|
|
29
|
-
export type BoundAuthorizedFetchOptions<T = undefined> = Omit<AuthorizedFetchOptions<T>, 'refresh'> & {
|
|
30
|
-
/**
|
|
31
|
-
* `false` skips the refresh, so a 401 is an `http_error`. Use it in a Server Component:
|
|
32
|
-
* Next won't let it write cookies, and a refresh that can't be saved spends the refresh token.
|
|
33
|
-
*/
|
|
34
|
-
refresh?: false;
|
|
35
|
-
};
|
|
20
|
+
/** The core instance's members, bound to the request's cookies. */
|
|
36
21
|
export interface FidesAuth {
|
|
37
|
-
/**
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
|
|
43
|
-
/** Refreshes the session and, on failure, says why. Prefer it over `refreshCurrentSession`. */
|
|
44
|
-
tryRefreshCurrentSession(options?: CreateSessionOptions): Promise<RefreshSessionResult>;
|
|
45
|
-
/** Persists a new session. Returns the session cookie's value: the encrypted session, or the handle. */
|
|
46
|
-
createAndPersistSession(session: Session): Promise<string>;
|
|
47
|
-
/** Deletes the session cookies and, with a `sessionStore`, the record. `trigger` defaults to `logout`. */
|
|
48
|
-
clearCurrentSession(options?: ClearSessionOptions): Promise<void>;
|
|
22
|
+
/** `GET`, with an optional `?returnTo=`. Redirects to the provider. */
|
|
23
|
+
handleOidcLogin(request: Request, options?: {
|
|
24
|
+
authorizationParameters?: Record<string, string>;
|
|
25
|
+
}): Promise<Response>;
|
|
26
|
+
/** The provider's redirect back. Starts the session and redirects to the return path. */
|
|
27
|
+
handleOidcCallback(request: Request): Promise<Response>;
|
|
49
28
|
/**
|
|
50
|
-
* `
|
|
51
|
-
*
|
|
52
|
-
* only in Server Actions and Route Handlers; pass `refresh: false` in a Server Component.
|
|
29
|
+
* `POST`. Ends the session, revokes its refresh token where the provider has
|
|
30
|
+
* a revocation endpoint, and redirects to the provider's end-session endpoint.
|
|
53
31
|
*/
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
32
|
+
handleOidcLogout(request: Request, options?: {
|
|
33
|
+
state?: string;
|
|
34
|
+
logoutHint?: string;
|
|
35
|
+
}): Promise<Response>;
|
|
36
|
+
/** `POST`. Refreshes the session. 401 means it is over; 503 means the provider or the store failed. */
|
|
58
37
|
handleHeartbeat(request: Request): Promise<Response>;
|
|
38
|
+
/** `GET`. Whether there is a session, and whose. Never refreshes, never returns tokens. */
|
|
39
|
+
handleSessionInfo(request: Request): Promise<Response>;
|
|
40
|
+
/** The session, or null. Cached per render. */
|
|
41
|
+
readSession(): Promise<Session | null>;
|
|
42
|
+
/** The session, or why there is none. Cached per render, together with `readSession`. */
|
|
43
|
+
tryReadSession(): Promise<FidesReadResult>;
|
|
44
|
+
/** The session's tokens, or null without a session. The access token may have expired. */
|
|
45
|
+
getTokens(): Promise<Tokens | null>;
|
|
46
|
+
/**
|
|
47
|
+
* Refreshes the tokens, or with `ifExpiresWithin` only when the access token
|
|
48
|
+
* is about to expire. With cookie sessions this writes cookies, so it works
|
|
49
|
+
* only in Server Actions and Route Handlers; pages get theirs from
|
|
50
|
+
* `refreshInProxy`.
|
|
51
|
+
*/
|
|
52
|
+
refreshSession(options?: RefreshSessionOptions): Promise<FidesRefreshResult>;
|
|
53
|
+
/** Starts a session from a token response, for a login that doesn't go through the handlers. */
|
|
54
|
+
createSession(tokens: TokenResponse): Promise<Session>;
|
|
55
|
+
/** Changes the user or data. Null when there is no session. */
|
|
56
|
+
updateSession(update: (session: Session) => Session | Promise<Session>): Promise<Session | null>;
|
|
57
|
+
/**
|
|
58
|
+
* Ends the session and revokes its refresh token where the provider has a
|
|
59
|
+
* revocation endpoint. With a store, the record is deleted too. `trigger`
|
|
60
|
+
* defaults to `'logout'`.
|
|
61
|
+
*/
|
|
62
|
+
clearSession(options?: {
|
|
63
|
+
trigger?: SessionClearedTrigger;
|
|
64
|
+
}): Promise<void>;
|
|
65
|
+
/**
|
|
66
|
+
* Ends every session of one user, wherever they are signed in, and revokes
|
|
67
|
+
* their refresh tokens. `sub` is the provider's, from the ID token. Needs a
|
|
68
|
+
* `sessionStore` with `findMatching`.
|
|
69
|
+
*
|
|
70
|
+
* @returns How many sessions it ended.
|
|
71
|
+
*/
|
|
72
|
+
endUserSessions(user: {
|
|
73
|
+
sub: string;
|
|
74
|
+
iss?: string;
|
|
75
|
+
}, options?: {
|
|
76
|
+
trigger?: SessionClearedTrigger;
|
|
77
|
+
}): Promise<number>;
|
|
78
|
+
/**
|
|
79
|
+
* Calls an API with the session's access token. It never refreshes, so it is
|
|
80
|
+
* safe in a Server Component; a 401 is an `http_error`.
|
|
81
|
+
*/
|
|
82
|
+
authorizedFetch<T = undefined>(url: string | URL, options: FidesAuthorizedFetchOptions<T>): Promise<{
|
|
83
|
+
response: Response;
|
|
84
|
+
data: T;
|
|
85
|
+
}>;
|
|
86
|
+
/**
|
|
87
|
+
* For `proxy.ts`. Refreshes a session whose access token expires within
|
|
88
|
+
* `ifExpiresWithin` seconds, or within half its lifetime if that is shorter,
|
|
89
|
+
* before the page renders, since a Server Component can't save a refresh.
|
|
90
|
+
* Sets the new cookies on the response and on the request it forwards, so
|
|
91
|
+
* the page reads the refreshed session.
|
|
92
|
+
*
|
|
93
|
+
* A failed refresh leaves the session as it is. The next API call or
|
|
94
|
+
* heartbeat shows a session that is over; ending it here could undo a refresh
|
|
95
|
+
* that another instance completed with the same refresh token.
|
|
96
|
+
*/
|
|
97
|
+
refreshInProxy(request: NextRequest, options?: RefreshInProxyOptions): Promise<NextResponse>;
|
|
98
|
+
/** The session cookie's name, for a proxy that checks whether one is present. */
|
|
99
|
+
readonly cookieNames: {
|
|
100
|
+
session: string;
|
|
101
|
+
};
|
|
102
|
+
/** The instance's OIDC client, for protocol calls it doesn't wrap. */
|
|
103
|
+
readonly oidc: OidcClient;
|
|
59
104
|
}
|
|
60
105
|
/**
|
|
61
|
-
* Creates the app's auth
|
|
106
|
+
* Creates the app's auth instance. Call it once, in a module of its own, and
|
|
107
|
+
* import the result. It reads nothing from the environment: pass the secret and
|
|
108
|
+
* the provider config in.
|
|
62
109
|
*
|
|
63
110
|
* @example
|
|
64
111
|
* ```ts
|
|
65
112
|
* // lib/auth.ts
|
|
66
|
-
* export const auth = createFidesAuth({ secret: process.env.SESSION_SECRET
|
|
113
|
+
* export const auth = createFidesAuth({ oauthConfig, secret: process.env.SESSION_SECRET! });
|
|
67
114
|
*
|
|
68
115
|
* // app/api/auth/login/route.ts
|
|
69
116
|
* export const GET = (request: Request) => auth.handleOidcLogin(request);
|
|
70
117
|
*
|
|
71
|
-
* // A
|
|
72
|
-
* const session = await auth.
|
|
118
|
+
* // A Server Component
|
|
119
|
+
* const session = await auth.readSession();
|
|
73
120
|
* ```
|
|
74
121
|
*/
|
|
75
|
-
export declare function createFidesAuth(
|
|
122
|
+
export declare function createFidesAuth(config: FidesAuthConfig): FidesAuth;
|
|
76
123
|
//# sourceMappingURL=auth.d.ts.map
|
package/dist/auth.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,
|
|
1
|
+
{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
|