@lumoauth/nextjs 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +462 -2
- package/dist/index.d.mts +19 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +110 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +72 -0
- package/dist/index.mjs.map +1 -0
- package/dist/server.d.mts +232 -0
- package/dist/server.d.ts +232 -0
- package/dist/server.js +433 -0
- package/dist/server.js.map +1 -0
- package/dist/server.mjs +396 -0
- package/dist/server.mjs.map +1 -0
- package/package.json +67 -4
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
"use client";
|
|
3
|
+
|
|
4
|
+
// src/index.ts
|
|
5
|
+
import { LumoAuth } from "@lumoauth/react";
|
|
6
|
+
import { LumoAuthProvider as LumoAuthProvider2 } from "@lumoauth/react";
|
|
7
|
+
import { SignIn, SignUp, AuthCallback } from "@lumoauth/react";
|
|
8
|
+
import { UserButton, UserAvatar, UserProfile } from "@lumoauth/react";
|
|
9
|
+
import { Protect } from "@lumoauth/react";
|
|
10
|
+
import { SignedIn, SignedOut, RedirectToSignIn } from "@lumoauth/react";
|
|
11
|
+
import { SignInButton, SignUpButton, SignOutButton } from "@lumoauth/react";
|
|
12
|
+
import {
|
|
13
|
+
useAuth,
|
|
14
|
+
useUser,
|
|
15
|
+
useSignIn,
|
|
16
|
+
useSession,
|
|
17
|
+
useLumoAuth,
|
|
18
|
+
usePermission,
|
|
19
|
+
useZanzibar,
|
|
20
|
+
useAbac,
|
|
21
|
+
useMagicLink,
|
|
22
|
+
useEmailFirst
|
|
23
|
+
} from "@lumoauth/react";
|
|
24
|
+
|
|
25
|
+
// src/provider.tsx
|
|
26
|
+
import { useMemo } from "react";
|
|
27
|
+
import { LumoAuthProvider } from "@lumoauth/react";
|
|
28
|
+
import { cookieStorageAdapter } from "@lumoauth/client";
|
|
29
|
+
import { jsx } from "react/jsx-runtime";
|
|
30
|
+
function LumoAuthNextProvider({
|
|
31
|
+
basePath = "/api/auth",
|
|
32
|
+
children,
|
|
33
|
+
...rest
|
|
34
|
+
}) {
|
|
35
|
+
const storage = useMemo(
|
|
36
|
+
() => cookieStorageAdapter({
|
|
37
|
+
sessionEndpoint: `${basePath}/session`,
|
|
38
|
+
logoutEndpoint: `${basePath}/logout`
|
|
39
|
+
}),
|
|
40
|
+
[basePath]
|
|
41
|
+
);
|
|
42
|
+
return /* @__PURE__ */ jsx(LumoAuthProvider, { ...rest, storage, children });
|
|
43
|
+
}
|
|
44
|
+
export {
|
|
45
|
+
AuthCallback,
|
|
46
|
+
LumoAuth,
|
|
47
|
+
LumoAuthNextProvider,
|
|
48
|
+
LumoAuthProvider2 as LumoAuthProvider,
|
|
49
|
+
Protect,
|
|
50
|
+
RedirectToSignIn,
|
|
51
|
+
SignIn,
|
|
52
|
+
SignInButton,
|
|
53
|
+
SignOutButton,
|
|
54
|
+
SignUp,
|
|
55
|
+
SignUpButton,
|
|
56
|
+
SignedIn,
|
|
57
|
+
SignedOut,
|
|
58
|
+
UserAvatar,
|
|
59
|
+
UserButton,
|
|
60
|
+
UserProfile,
|
|
61
|
+
useAbac,
|
|
62
|
+
useAuth,
|
|
63
|
+
useEmailFirst,
|
|
64
|
+
useLumoAuth,
|
|
65
|
+
useMagicLink,
|
|
66
|
+
usePermission,
|
|
67
|
+
useSession,
|
|
68
|
+
useSignIn,
|
|
69
|
+
useUser,
|
|
70
|
+
useZanzibar
|
|
71
|
+
};
|
|
72
|
+
//# sourceMappingURL=index.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/provider.tsx"],"sourcesContent":["'use client';\n\n// @lumoauth/nextjs — client entry.\n//\n// Re-exports the React SDK so a Next.js app needs one dependency. Everything\n// server-side (auth, currentUser, route handlers, middleware) lives in\n// @lumoauth/nextjs/server, which is never bundled for the browser.\n\n// Named re-exports, not `export *`: Next 14 rejects `export *` in a module\n// carrying the \"use client\" directive. Keep this list in sync with\n// @lumoauth/react's index.\nexport { LumoAuth, type LumoAuthConfig } from '@lumoauth/react';\n\n// Provider\nexport { LumoAuthProvider } from '@lumoauth/react';\n\n// Authentication Components\nexport { SignIn, SignUp, AuthCallback } from '@lumoauth/react';\n\n// User Components\nexport { UserButton, UserAvatar, UserProfile } from '@lumoauth/react';\n\n// Authorization Components\nexport { Protect } from '@lumoauth/react';\n\n// Control Components\nexport { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';\n\n// Unstyled Components\nexport { SignInButton, SignUpButton, SignOutButton } from '@lumoauth/react';\n\n// Hooks\nexport {\n useAuth,\n useUser,\n useSignIn,\n useSession,\n useLumoAuth,\n usePermission,\n useZanzibar,\n useAbac,\n useMagicLink,\n useEmailFirst,\n} from '@lumoauth/react';\n\n// Types\nexport type {\n LumoAuthProviderProps,\n LumoAuthUser,\n AuthState,\n AuthStatus,\n LumoAuthContextValue,\n SignInProps,\n SignUpProps,\n UserButtonProps,\n UserAvatarProps,\n UserProfileProps,\n ProtectProps,\n AppearanceProps,\n AuthCallbackProps,\n SignedInProps,\n SignedOutProps,\n SignInButtonProps,\n SignUpButtonProps,\n SignOutButtonProps,\n RedirectToSignInProps,\n UseMagicLinkReturn,\n UseEmailFirstReturn,\n} from '@lumoauth/react';\n\nexport { LumoAuthNextProvider } from './provider';\n","'use client';\n\nimport { useMemo } from 'react';\nimport { LumoAuthProvider, type LumoAuthProviderProps } from '@lumoauth/react';\nimport { cookieStorageAdapter } from '@lumoauth/client';\n\nexport type LumoAuthNextProviderProps = Omit<LumoAuthProviderProps, 'storage'> & {\n /** Base path where createRouteHandler is mounted. @default '/api/auth' */\n basePath?: string;\n};\n\n/**\n * Provider wired to the server-side session.\n *\n * The plain `<LumoAuthProvider>` keeps tokens in web storage, which the server\n * cannot see — so a page always renders signed-out first and corrects itself\n * after hydration. This one reads the session from the httpOnly cookie via the\n * route handler, matching what `auth()` already rendered on the server.\n */\nexport function LumoAuthNextProvider({\n basePath = '/api/auth',\n children,\n ...rest\n}: LumoAuthNextProviderProps) {\n // Memoised: `storage` is a dependency of the provider's session useMemo, so\n // a new adapter each render would rebuild the session every render.\n const storage = useMemo(\n () =>\n cookieStorageAdapter({\n sessionEndpoint: `${basePath}/session`,\n logoutEndpoint: `${basePath}/logout`,\n }),\n [basePath],\n );\n\n return (\n <LumoAuthProvider {...rest} storage={storage}>\n {children}\n </LumoAuthProvider>\n );\n}\n"],"mappings":";;;;AAWA,SAAS,gBAAqC;AAG9C,SAAS,oBAAAA,yBAAwB;AAGjC,SAAS,QAAQ,QAAQ,oBAAoB;AAG7C,SAAS,YAAY,YAAY,mBAAmB;AAGpD,SAAS,eAAe;AAGxB,SAAS,UAAU,WAAW,wBAAwB;AAGtD,SAAS,cAAc,cAAc,qBAAqB;AAG1D;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACG;;;ACzCP,SAAS,eAAe;AACxB,SAAS,wBAAoD;AAC7D,SAAS,4BAA4B;AAgC7B;AAjBD,SAAS,qBAAqB;AAAA,EACjC,WAAW;AAAA,EACX;AAAA,EACA,GAAG;AACP,GAA8B;AAG1B,QAAM,UAAU;AAAA,IACZ,MACI,qBAAqB;AAAA,MACjB,iBAAiB,GAAG,QAAQ;AAAA,MAC5B,gBAAgB,GAAG,QAAQ;AAAA,IAC/B,CAAC;AAAA,IACL,CAAC,QAAQ;AAAA,EACb;AAEA,SACI,oBAAC,oBAAkB,GAAG,MAAM,SACvB,UACL;AAER;","names":["LumoAuthProvider"]}
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { UserInfo } from '@lumoauth/shared';
|
|
2
|
+
import { NextRequest, NextResponse } from 'next/server';
|
|
3
|
+
|
|
4
|
+
interface LumoAuthNextConfig {
|
|
5
|
+
/** Base URL of your LumoAuth instance. */
|
|
6
|
+
domain: string;
|
|
7
|
+
/** Organization slug. */
|
|
8
|
+
orgId: string;
|
|
9
|
+
/** OAuth client id. */
|
|
10
|
+
clientId: string;
|
|
11
|
+
/** Client secret, for confidential clients. Public + PKCE clients omit it. */
|
|
12
|
+
clientSecret?: string;
|
|
13
|
+
/** Secret used to seal the session cookie. At least 32 characters. */
|
|
14
|
+
secret: string;
|
|
15
|
+
/** Absolute redirect URI registered with the OAuth client. */
|
|
16
|
+
redirectUri: string;
|
|
17
|
+
/** Where to send a signed-out user. @default '/' */
|
|
18
|
+
afterSignOutUrl?: string;
|
|
19
|
+
/** Where to send a freshly signed-in user. @default '/' */
|
|
20
|
+
afterSignInUrl?: string;
|
|
21
|
+
/** OAuth scopes. @default 'openid profile email' */
|
|
22
|
+
scope?: string;
|
|
23
|
+
/** Session cookie lifetime in seconds. @default 30 days */
|
|
24
|
+
sessionMaxAge?: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Resolve config from the environment.
|
|
28
|
+
*
|
|
29
|
+
* The public values are read from `NEXT_PUBLIC_*` so the same names work in
|
|
30
|
+
* both the client provider and the server. `LUMOAUTH_SECRET` and
|
|
31
|
+
* `LUMOAUTH_CLIENT_SECRET` are deliberately NOT public — a `NEXT_PUBLIC_`
|
|
32
|
+
* prefix would inline them into the browser bundle.
|
|
33
|
+
*/
|
|
34
|
+
declare function resolveConfig(overrides?: Partial<LumoAuthNextConfig>): LumoAuthNextConfig;
|
|
35
|
+
|
|
36
|
+
interface AuthObject {
|
|
37
|
+
/** OIDC subject of the signed-in user, or null. */
|
|
38
|
+
userId: string | null;
|
|
39
|
+
/**
|
|
40
|
+
* Whether the user has a live SESSION — not whether the access token is
|
|
41
|
+
* currently fresh. A stale access token with a valid refresh token is still
|
|
42
|
+
* a signed-in user.
|
|
43
|
+
*/
|
|
44
|
+
isSignedIn: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* The access token, or null if it is stale and nothing refreshed it.
|
|
47
|
+
*
|
|
48
|
+
* Returns null rather than refreshing, because a server component cannot
|
|
49
|
+
* persist the result: LumoAuth rotates and revokes refresh tokens on use,
|
|
50
|
+
* so an unpersisted refresh would burn the token and break the session on
|
|
51
|
+
* the very next request. Add `lumoAuthMiddleware()` and the token is always
|
|
52
|
+
* fresh by the time this runs.
|
|
53
|
+
*/
|
|
54
|
+
getToken: () => string | null;
|
|
55
|
+
/** Access-token expiry, epoch milliseconds. */
|
|
56
|
+
expiresAt: number | null;
|
|
57
|
+
/**
|
|
58
|
+
* True when the session is live but the access token needs replacing.
|
|
59
|
+
* Only possible when middleware is not installed on this route.
|
|
60
|
+
*/
|
|
61
|
+
isStale: boolean;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Read the session in a server component, route handler, or server action.
|
|
65
|
+
*
|
|
66
|
+
* Because the session lives in an httpOnly cookie the server can read directly,
|
|
67
|
+
* a page can decide what to render *before* it responds — no client round-trip,
|
|
68
|
+
* and therefore none of the signed-out-then-signed-in flash that a purely
|
|
69
|
+
* client-side provider produces on every load.
|
|
70
|
+
*
|
|
71
|
+
* ```tsx
|
|
72
|
+
* export default async function Page() {
|
|
73
|
+
* const { isSignedIn, userId } = await auth();
|
|
74
|
+
* if (!isSignedIn) redirect('/api/auth/login');
|
|
75
|
+
* return <p>Hello {userId}</p>;
|
|
76
|
+
* }
|
|
77
|
+
* ```
|
|
78
|
+
*
|
|
79
|
+
* The session is trusted because it is sealed with AES-256-GCM using
|
|
80
|
+
* `LUMOAUTH_SECRET`: the browser can neither read nor forge it. This does not
|
|
81
|
+
* re-verify the access token's signature against the issuer's JWKS — the token
|
|
82
|
+
* is only ever accepted here because *we* put it in the cookie after a
|
|
83
|
+
* successful exchange.
|
|
84
|
+
*/
|
|
85
|
+
declare function auth(overrides?: Partial<LumoAuthNextConfig>): Promise<AuthObject>;
|
|
86
|
+
/**
|
|
87
|
+
* The signed-in user's profile, or null.
|
|
88
|
+
*
|
|
89
|
+
* This makes a network call to the OIDC `/userinfo` endpoint on every
|
|
90
|
+
* invocation, so prefer `auth()` when the subject is all you need.
|
|
91
|
+
*/
|
|
92
|
+
declare function currentUser(overrides?: Partial<LumoAuthNextConfig>): Promise<UserInfo | null>;
|
|
93
|
+
/**
|
|
94
|
+
* Redirect signed-out visitors to sign in. Call at the top of a protected
|
|
95
|
+
* server component.
|
|
96
|
+
*
|
|
97
|
+
* ```tsx
|
|
98
|
+
* export default async function Page() {
|
|
99
|
+
* await protectPage();
|
|
100
|
+
* ...
|
|
101
|
+
* }
|
|
102
|
+
* ```
|
|
103
|
+
*/
|
|
104
|
+
declare function protectPage(opts?: {
|
|
105
|
+
returnTo?: string;
|
|
106
|
+
}): Promise<AuthObject>;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Backend-for-frontend route handlers.
|
|
110
|
+
*
|
|
111
|
+
* Mount once, at `app/api/auth/[...lumoauth]/route.ts`:
|
|
112
|
+
*
|
|
113
|
+
* ```ts
|
|
114
|
+
* import { createRouteHandler } from '@lumoauth/nextjs/server';
|
|
115
|
+
* export const { GET, POST } = createRouteHandler();
|
|
116
|
+
* ```
|
|
117
|
+
*
|
|
118
|
+
* The server owns the whole OAuth exchange, so tokens live in an httpOnly
|
|
119
|
+
* cookie and never reach JavaScript. That is what makes `auth()` work in a
|
|
120
|
+
* server component — and therefore what makes a signed-in page render
|
|
121
|
+
* server-side with no loading flash.
|
|
122
|
+
*/
|
|
123
|
+
type Ctx = {
|
|
124
|
+
params: Promise<{
|
|
125
|
+
lumoauth?: string[];
|
|
126
|
+
}>;
|
|
127
|
+
};
|
|
128
|
+
declare function createRouteHandler(overrides?: Partial<LumoAuthNextConfig>): {
|
|
129
|
+
GET: (request: Request, context: Ctx) => Promise<Response>;
|
|
130
|
+
POST: (request: Request, context: Ctx) => Promise<Response>;
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
interface MiddlewareOptions extends Partial<LumoAuthNextConfig> {
|
|
134
|
+
/**
|
|
135
|
+
* Paths requiring a session. Accepts globs (`/dashboard/:path*`), regexes,
|
|
136
|
+
* or a predicate. Everything else is public.
|
|
137
|
+
*/
|
|
138
|
+
protect?: Array<string | RegExp> | ((req: NextRequest) => boolean);
|
|
139
|
+
/**
|
|
140
|
+
* Keep the access token fresh automatically. @default true
|
|
141
|
+
*
|
|
142
|
+
* Turning this off means `auth().getToken()` returns null once the token
|
|
143
|
+
* goes stale, because nothing else in the request pipeline is able to
|
|
144
|
+
* persist a refreshed one.
|
|
145
|
+
*/
|
|
146
|
+
refresh?: boolean;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Session refresh and route protection.
|
|
150
|
+
*
|
|
151
|
+
* ```ts
|
|
152
|
+
* // middleware.ts
|
|
153
|
+
* import { lumoAuthMiddleware } from '@lumoauth/nextjs/server';
|
|
154
|
+
*
|
|
155
|
+
* export default lumoAuthMiddleware({ protect: ['/dashboard/:path*'] });
|
|
156
|
+
* export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
|
|
157
|
+
* ```
|
|
158
|
+
*
|
|
159
|
+
* ## Why refresh belongs here
|
|
160
|
+
*
|
|
161
|
+
* An access token lasts about an hour; a session lasts weeks. Something has to
|
|
162
|
+
* trade the refresh token for a new access token, and in Next.js that can only
|
|
163
|
+
* happen where cookies are writable: middleware, route handlers, and server
|
|
164
|
+
* actions. Server components cannot set cookies, so they can never persist a
|
|
165
|
+
* refresh.
|
|
166
|
+
*
|
|
167
|
+
* That distinction is not cosmetic. LumoAuth rotates refresh tokens and revokes
|
|
168
|
+
* the old one on use, so refreshing somewhere that cannot persist the result
|
|
169
|
+
* would spend the token and break the session on the next request. Middleware
|
|
170
|
+
* runs before the page renders and can write the response cookie, so it is the
|
|
171
|
+
* correct place.
|
|
172
|
+
*
|
|
173
|
+
* Because middleware writes the cookie on the *response* while the page reads
|
|
174
|
+
* the *request*, the fresh session is also forwarded on a request header that
|
|
175
|
+
* `auth()` prefers — otherwise the refresh would not take effect until the
|
|
176
|
+
* following request.
|
|
177
|
+
*/
|
|
178
|
+
declare function lumoAuthMiddleware(options?: MiddlewareOptions): (req: NextRequest) => Promise<NextResponse<unknown>>;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The server-side session, sealed into an httpOnly cookie.
|
|
182
|
+
*
|
|
183
|
+
* This is the trust boundary for everything else in the package: `auth()`
|
|
184
|
+
* believes what is in here, so it must be unforgeable. The cookie is encrypted
|
|
185
|
+
* AND authenticated with AES-256-GCM, so a client can neither read the tokens
|
|
186
|
+
* nor alter the payload without the auth tag failing.
|
|
187
|
+
*
|
|
188
|
+
* Encrypting rather than merely signing matters because the payload holds the
|
|
189
|
+
* refresh token, which must never be readable by the browser.
|
|
190
|
+
*
|
|
191
|
+
* Implemented with Web Crypto rather than `node:crypto` because these helpers
|
|
192
|
+
* run in three different places: route handlers (Node runtime), `auth()` in a
|
|
193
|
+
* server component (Node), and `lumoAuthMiddleware` (edge runtime, where
|
|
194
|
+
* `node:crypto` does not exist). Web Crypto is the one API present in all of
|
|
195
|
+
* them. The cost is that seal/unseal are async.
|
|
196
|
+
*/
|
|
197
|
+
declare const SESSION_COOKIE = "lumo_session";
|
|
198
|
+
/**
|
|
199
|
+
* Two different lifetimes live in here, and conflating them is the classic
|
|
200
|
+
* bug: an access token lasts ~1 hour, a session lasts weeks.
|
|
201
|
+
*
|
|
202
|
+
* `expiresAt` is when the ACCESS TOKEN goes stale — routine, expected, and
|
|
203
|
+
* fixed by a refresh.
|
|
204
|
+
* `sessionExpiresAt` is when the SESSION itself ends and the user must sign in
|
|
205
|
+
* again.
|
|
206
|
+
*
|
|
207
|
+
* A user whose access token expired five minutes ago is still signed in.
|
|
208
|
+
*/
|
|
209
|
+
interface ServerSession {
|
|
210
|
+
accessToken: string;
|
|
211
|
+
refreshToken: string | null;
|
|
212
|
+
idToken: string | null;
|
|
213
|
+
/** Access-token expiry, epoch milliseconds. */
|
|
214
|
+
expiresAt: number;
|
|
215
|
+
/** Session expiry, epoch milliseconds. Absent on cookies written before this field existed. */
|
|
216
|
+
sessionExpiresAt?: number;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Header used to hand a freshly refreshed session from middleware to the
|
|
220
|
+
* server component rendering the same request.
|
|
221
|
+
*
|
|
222
|
+
* Middleware writes the new cookie on the RESPONSE, but the component reads
|
|
223
|
+
* REQUEST cookies — which still hold the stale value. Without this header the
|
|
224
|
+
* refresh would only take effect on the following request.
|
|
225
|
+
*/
|
|
226
|
+
declare const REFRESHED_SESSION_HEADER = "x-lumo-session";
|
|
227
|
+
/** True when the session itself is still valid, regardless of token staleness. */
|
|
228
|
+
declare function isSessionLive(session: ServerSession | null): session is ServerSession;
|
|
229
|
+
/** True when the access token needs replacing before it can be used. */
|
|
230
|
+
declare function isTokenStale(session: ServerSession): boolean;
|
|
231
|
+
|
|
232
|
+
export { type AuthObject, type LumoAuthNextConfig, type MiddlewareOptions, REFRESHED_SESSION_HEADER, SESSION_COOKIE, type ServerSession, auth, createRouteHandler, currentUser, isSessionLive, isTokenStale, lumoAuthMiddleware, protectPage, resolveConfig };
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { UserInfo } from '@lumoauth/shared';
|
|
2
|
+
import { NextRequest, NextResponse } from 'next/server';
|
|
3
|
+
|
|
4
|
+
interface LumoAuthNextConfig {
|
|
5
|
+
/** Base URL of your LumoAuth instance. */
|
|
6
|
+
domain: string;
|
|
7
|
+
/** Organization slug. */
|
|
8
|
+
orgId: string;
|
|
9
|
+
/** OAuth client id. */
|
|
10
|
+
clientId: string;
|
|
11
|
+
/** Client secret, for confidential clients. Public + PKCE clients omit it. */
|
|
12
|
+
clientSecret?: string;
|
|
13
|
+
/** Secret used to seal the session cookie. At least 32 characters. */
|
|
14
|
+
secret: string;
|
|
15
|
+
/** Absolute redirect URI registered with the OAuth client. */
|
|
16
|
+
redirectUri: string;
|
|
17
|
+
/** Where to send a signed-out user. @default '/' */
|
|
18
|
+
afterSignOutUrl?: string;
|
|
19
|
+
/** Where to send a freshly signed-in user. @default '/' */
|
|
20
|
+
afterSignInUrl?: string;
|
|
21
|
+
/** OAuth scopes. @default 'openid profile email' */
|
|
22
|
+
scope?: string;
|
|
23
|
+
/** Session cookie lifetime in seconds. @default 30 days */
|
|
24
|
+
sessionMaxAge?: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Resolve config from the environment.
|
|
28
|
+
*
|
|
29
|
+
* The public values are read from `NEXT_PUBLIC_*` so the same names work in
|
|
30
|
+
* both the client provider and the server. `LUMOAUTH_SECRET` and
|
|
31
|
+
* `LUMOAUTH_CLIENT_SECRET` are deliberately NOT public — a `NEXT_PUBLIC_`
|
|
32
|
+
* prefix would inline them into the browser bundle.
|
|
33
|
+
*/
|
|
34
|
+
declare function resolveConfig(overrides?: Partial<LumoAuthNextConfig>): LumoAuthNextConfig;
|
|
35
|
+
|
|
36
|
+
interface AuthObject {
|
|
37
|
+
/** OIDC subject of the signed-in user, or null. */
|
|
38
|
+
userId: string | null;
|
|
39
|
+
/**
|
|
40
|
+
* Whether the user has a live SESSION — not whether the access token is
|
|
41
|
+
* currently fresh. A stale access token with a valid refresh token is still
|
|
42
|
+
* a signed-in user.
|
|
43
|
+
*/
|
|
44
|
+
isSignedIn: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* The access token, or null if it is stale and nothing refreshed it.
|
|
47
|
+
*
|
|
48
|
+
* Returns null rather than refreshing, because a server component cannot
|
|
49
|
+
* persist the result: LumoAuth rotates and revokes refresh tokens on use,
|
|
50
|
+
* so an unpersisted refresh would burn the token and break the session on
|
|
51
|
+
* the very next request. Add `lumoAuthMiddleware()` and the token is always
|
|
52
|
+
* fresh by the time this runs.
|
|
53
|
+
*/
|
|
54
|
+
getToken: () => string | null;
|
|
55
|
+
/** Access-token expiry, epoch milliseconds. */
|
|
56
|
+
expiresAt: number | null;
|
|
57
|
+
/**
|
|
58
|
+
* True when the session is live but the access token needs replacing.
|
|
59
|
+
* Only possible when middleware is not installed on this route.
|
|
60
|
+
*/
|
|
61
|
+
isStale: boolean;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Read the session in a server component, route handler, or server action.
|
|
65
|
+
*
|
|
66
|
+
* Because the session lives in an httpOnly cookie the server can read directly,
|
|
67
|
+
* a page can decide what to render *before* it responds — no client round-trip,
|
|
68
|
+
* and therefore none of the signed-out-then-signed-in flash that a purely
|
|
69
|
+
* client-side provider produces on every load.
|
|
70
|
+
*
|
|
71
|
+
* ```tsx
|
|
72
|
+
* export default async function Page() {
|
|
73
|
+
* const { isSignedIn, userId } = await auth();
|
|
74
|
+
* if (!isSignedIn) redirect('/api/auth/login');
|
|
75
|
+
* return <p>Hello {userId}</p>;
|
|
76
|
+
* }
|
|
77
|
+
* ```
|
|
78
|
+
*
|
|
79
|
+
* The session is trusted because it is sealed with AES-256-GCM using
|
|
80
|
+
* `LUMOAUTH_SECRET`: the browser can neither read nor forge it. This does not
|
|
81
|
+
* re-verify the access token's signature against the issuer's JWKS — the token
|
|
82
|
+
* is only ever accepted here because *we* put it in the cookie after a
|
|
83
|
+
* successful exchange.
|
|
84
|
+
*/
|
|
85
|
+
declare function auth(overrides?: Partial<LumoAuthNextConfig>): Promise<AuthObject>;
|
|
86
|
+
/**
|
|
87
|
+
* The signed-in user's profile, or null.
|
|
88
|
+
*
|
|
89
|
+
* This makes a network call to the OIDC `/userinfo` endpoint on every
|
|
90
|
+
* invocation, so prefer `auth()` when the subject is all you need.
|
|
91
|
+
*/
|
|
92
|
+
declare function currentUser(overrides?: Partial<LumoAuthNextConfig>): Promise<UserInfo | null>;
|
|
93
|
+
/**
|
|
94
|
+
* Redirect signed-out visitors to sign in. Call at the top of a protected
|
|
95
|
+
* server component.
|
|
96
|
+
*
|
|
97
|
+
* ```tsx
|
|
98
|
+
* export default async function Page() {
|
|
99
|
+
* await protectPage();
|
|
100
|
+
* ...
|
|
101
|
+
* }
|
|
102
|
+
* ```
|
|
103
|
+
*/
|
|
104
|
+
declare function protectPage(opts?: {
|
|
105
|
+
returnTo?: string;
|
|
106
|
+
}): Promise<AuthObject>;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Backend-for-frontend route handlers.
|
|
110
|
+
*
|
|
111
|
+
* Mount once, at `app/api/auth/[...lumoauth]/route.ts`:
|
|
112
|
+
*
|
|
113
|
+
* ```ts
|
|
114
|
+
* import { createRouteHandler } from '@lumoauth/nextjs/server';
|
|
115
|
+
* export const { GET, POST } = createRouteHandler();
|
|
116
|
+
* ```
|
|
117
|
+
*
|
|
118
|
+
* The server owns the whole OAuth exchange, so tokens live in an httpOnly
|
|
119
|
+
* cookie and never reach JavaScript. That is what makes `auth()` work in a
|
|
120
|
+
* server component — and therefore what makes a signed-in page render
|
|
121
|
+
* server-side with no loading flash.
|
|
122
|
+
*/
|
|
123
|
+
type Ctx = {
|
|
124
|
+
params: Promise<{
|
|
125
|
+
lumoauth?: string[];
|
|
126
|
+
}>;
|
|
127
|
+
};
|
|
128
|
+
declare function createRouteHandler(overrides?: Partial<LumoAuthNextConfig>): {
|
|
129
|
+
GET: (request: Request, context: Ctx) => Promise<Response>;
|
|
130
|
+
POST: (request: Request, context: Ctx) => Promise<Response>;
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
interface MiddlewareOptions extends Partial<LumoAuthNextConfig> {
|
|
134
|
+
/**
|
|
135
|
+
* Paths requiring a session. Accepts globs (`/dashboard/:path*`), regexes,
|
|
136
|
+
* or a predicate. Everything else is public.
|
|
137
|
+
*/
|
|
138
|
+
protect?: Array<string | RegExp> | ((req: NextRequest) => boolean);
|
|
139
|
+
/**
|
|
140
|
+
* Keep the access token fresh automatically. @default true
|
|
141
|
+
*
|
|
142
|
+
* Turning this off means `auth().getToken()` returns null once the token
|
|
143
|
+
* goes stale, because nothing else in the request pipeline is able to
|
|
144
|
+
* persist a refreshed one.
|
|
145
|
+
*/
|
|
146
|
+
refresh?: boolean;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Session refresh and route protection.
|
|
150
|
+
*
|
|
151
|
+
* ```ts
|
|
152
|
+
* // middleware.ts
|
|
153
|
+
* import { lumoAuthMiddleware } from '@lumoauth/nextjs/server';
|
|
154
|
+
*
|
|
155
|
+
* export default lumoAuthMiddleware({ protect: ['/dashboard/:path*'] });
|
|
156
|
+
* export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
|
|
157
|
+
* ```
|
|
158
|
+
*
|
|
159
|
+
* ## Why refresh belongs here
|
|
160
|
+
*
|
|
161
|
+
* An access token lasts about an hour; a session lasts weeks. Something has to
|
|
162
|
+
* trade the refresh token for a new access token, and in Next.js that can only
|
|
163
|
+
* happen where cookies are writable: middleware, route handlers, and server
|
|
164
|
+
* actions. Server components cannot set cookies, so they can never persist a
|
|
165
|
+
* refresh.
|
|
166
|
+
*
|
|
167
|
+
* That distinction is not cosmetic. LumoAuth rotates refresh tokens and revokes
|
|
168
|
+
* the old one on use, so refreshing somewhere that cannot persist the result
|
|
169
|
+
* would spend the token and break the session on the next request. Middleware
|
|
170
|
+
* runs before the page renders and can write the response cookie, so it is the
|
|
171
|
+
* correct place.
|
|
172
|
+
*
|
|
173
|
+
* Because middleware writes the cookie on the *response* while the page reads
|
|
174
|
+
* the *request*, the fresh session is also forwarded on a request header that
|
|
175
|
+
* `auth()` prefers — otherwise the refresh would not take effect until the
|
|
176
|
+
* following request.
|
|
177
|
+
*/
|
|
178
|
+
declare function lumoAuthMiddleware(options?: MiddlewareOptions): (req: NextRequest) => Promise<NextResponse<unknown>>;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The server-side session, sealed into an httpOnly cookie.
|
|
182
|
+
*
|
|
183
|
+
* This is the trust boundary for everything else in the package: `auth()`
|
|
184
|
+
* believes what is in here, so it must be unforgeable. The cookie is encrypted
|
|
185
|
+
* AND authenticated with AES-256-GCM, so a client can neither read the tokens
|
|
186
|
+
* nor alter the payload without the auth tag failing.
|
|
187
|
+
*
|
|
188
|
+
* Encrypting rather than merely signing matters because the payload holds the
|
|
189
|
+
* refresh token, which must never be readable by the browser.
|
|
190
|
+
*
|
|
191
|
+
* Implemented with Web Crypto rather than `node:crypto` because these helpers
|
|
192
|
+
* run in three different places: route handlers (Node runtime), `auth()` in a
|
|
193
|
+
* server component (Node), and `lumoAuthMiddleware` (edge runtime, where
|
|
194
|
+
* `node:crypto` does not exist). Web Crypto is the one API present in all of
|
|
195
|
+
* them. The cost is that seal/unseal are async.
|
|
196
|
+
*/
|
|
197
|
+
declare const SESSION_COOKIE = "lumo_session";
|
|
198
|
+
/**
|
|
199
|
+
* Two different lifetimes live in here, and conflating them is the classic
|
|
200
|
+
* bug: an access token lasts ~1 hour, a session lasts weeks.
|
|
201
|
+
*
|
|
202
|
+
* `expiresAt` is when the ACCESS TOKEN goes stale — routine, expected, and
|
|
203
|
+
* fixed by a refresh.
|
|
204
|
+
* `sessionExpiresAt` is when the SESSION itself ends and the user must sign in
|
|
205
|
+
* again.
|
|
206
|
+
*
|
|
207
|
+
* A user whose access token expired five minutes ago is still signed in.
|
|
208
|
+
*/
|
|
209
|
+
interface ServerSession {
|
|
210
|
+
accessToken: string;
|
|
211
|
+
refreshToken: string | null;
|
|
212
|
+
idToken: string | null;
|
|
213
|
+
/** Access-token expiry, epoch milliseconds. */
|
|
214
|
+
expiresAt: number;
|
|
215
|
+
/** Session expiry, epoch milliseconds. Absent on cookies written before this field existed. */
|
|
216
|
+
sessionExpiresAt?: number;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Header used to hand a freshly refreshed session from middleware to the
|
|
220
|
+
* server component rendering the same request.
|
|
221
|
+
*
|
|
222
|
+
* Middleware writes the new cookie on the RESPONSE, but the component reads
|
|
223
|
+
* REQUEST cookies — which still hold the stale value. Without this header the
|
|
224
|
+
* refresh would only take effect on the following request.
|
|
225
|
+
*/
|
|
226
|
+
declare const REFRESHED_SESSION_HEADER = "x-lumo-session";
|
|
227
|
+
/** True when the session itself is still valid, regardless of token staleness. */
|
|
228
|
+
declare function isSessionLive(session: ServerSession | null): session is ServerSession;
|
|
229
|
+
/** True when the access token needs replacing before it can be used. */
|
|
230
|
+
declare function isTokenStale(session: ServerSession): boolean;
|
|
231
|
+
|
|
232
|
+
export { type AuthObject, type LumoAuthNextConfig, type MiddlewareOptions, REFRESHED_SESSION_HEADER, SESSION_COOKIE, type ServerSession, auth, createRouteHandler, currentUser, isSessionLive, isTokenStale, lumoAuthMiddleware, protectPage, resolveConfig };
|