@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/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 };
@@ -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 };