@lumoauth/nextjs 0.0.0-stage → 1.0.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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LumoAuth LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,147 @@
1
- # Temporary Holding Version
1
+ # @lumoauth/nextjs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ LumoAuth for Next.js: server-side `auth()` in the App Router, route-protection
4
+ middleware, and a backend-for-frontend that keeps tokens out of the browser.
5
+
6
+ ## Why this exists
7
+
8
+ A purely client-side auth provider cannot render a signed-in page on the
9
+ server. It has to boot, read storage, and fetch the profile — so the first
10
+ paint is always signed-out and corrects itself after hydration. That is the
11
+ flash.
12
+
13
+ This package puts the session in an httpOnly cookie the server can read, so a
14
+ page knows who the user is *before* it responds.
15
+
16
+ ## Setup
17
+
18
+ ```bash
19
+ npm install @lumoauth/nextjs
20
+ ```
21
+
22
+ ```
23
+ # .env.local
24
+ NEXT_PUBLIC_LUMOAUTH_DOMAIN=https://app.lumoauth.dev
25
+ NEXT_PUBLIC_LUMOAUTH_ORG_ID=acme-corp
26
+ NEXT_PUBLIC_LUMOAUTH_CLIENT_ID=your-client-id
27
+ NEXT_PUBLIC_REDIRECT_URI=http://localhost:3000/api/auth/callback
28
+
29
+ # Seals the session cookie. Never expose this: openssl rand -hex 32
30
+ LUMOAUTH_SECRET=...
31
+ ```
32
+
33
+ Mount the backend-for-frontend once:
34
+
35
+ ```ts
36
+ // app/api/auth/[...lumoauth]/route.ts
37
+ import { createRouteHandler } from '@lumoauth/nextjs/server';
38
+ export const { GET, POST } = createRouteHandler();
39
+ ```
40
+
41
+ That gives you `/api/auth/login`, `/callback`, `/session` and `/logout`.
42
+ Register the callback URL as a redirect URI on your OAuth client, and the
43
+ origin as a post-logout redirect URI so sign-out returns to your app.
44
+
45
+ ## Server components
46
+
47
+ ```tsx
48
+ import { auth, currentUser } from '@lumoauth/nextjs/server';
49
+
50
+ export default async function Page() {
51
+ const { isSignedIn, userId } = await auth();
52
+ if (!isSignedIn) return <a href="/api/auth/login">Sign in</a>;
53
+
54
+ const user = await currentUser();
55
+ return <p>Hello {user?.email}</p>;
56
+ }
57
+ ```
58
+
59
+ `auth()` is cheap — it reads and decrypts a cookie. `currentUser()` makes a
60
+ network call to `/userinfo`, so prefer `auth()` when the subject is enough.
61
+
62
+ To require a session, `await protectPage()` redirects signed-out visitors.
63
+
64
+ ## Middleware
65
+
66
+ ```ts
67
+ // middleware.ts
68
+ import { lumoAuthMiddleware } from '@lumoauth/nextjs/server';
69
+
70
+ export default lumoAuthMiddleware({ protect: ['/dashboard/:path*'] });
71
+ export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
72
+ ```
73
+
74
+ Convenience, not the security boundary — that is your API rejecting a bad
75
+ token. It only checks that a valid, unexpired session cookie is present.
76
+
77
+ ## Client components
78
+
79
+ ```tsx
80
+ 'use client';
81
+ import { LumoAuthNextProvider, useUser } from '@lumoauth/nextjs';
82
+ ```
83
+
84
+ `<LumoAuthNextProvider>` is `<LumoAuthProvider>` wired to the cookie session,
85
+ so client and server agree. Every hook and component from `@lumoauth/react` is
86
+ re-exported.
87
+
88
+ ## How the session is protected
89
+
90
+ The cookie is encrypted **and** authenticated with AES-256-GCM using
91
+ `LUMOAUTH_SECRET`, via Web Crypto so the same code runs in the Node and edge
92
+ runtimes. Encrypted rather than merely signed because the payload holds the
93
+ refresh token, which must never be readable by the browser. A tampered cookie
94
+ fails the auth tag and is treated as no session at all.
95
+
96
+ `auth()` does not re-verify the access token against the issuer's JWKS. It does
97
+ not need to: the token is only ever in that cookie because this package put it
98
+ there after a successful exchange, and the cookie is unforgeable.
99
+
100
+ ## Sessions vs access tokens
101
+
102
+ These are two different lifetimes, and treating them as one is the classic way
103
+ to log everybody out every hour.
104
+
105
+ | | Lifetime | Meaning |
106
+ |---|---|---|
107
+ | **Session** | weeks (`sessionMaxAge`) | The user is signed in |
108
+ | **Access token** | ~1 hour (issuer's choice) | A credential for calling the API |
109
+
110
+ `auth().isSignedIn` reports on the **session**. A user whose access token
111
+ expired a minute ago is still signed in; the token just needs replacing.
112
+
113
+ `lumoAuthMiddleware()` does that replacing, in the background, before the page
114
+ renders. Install it and `getToken()` always returns a fresh token:
115
+
116
+ ```ts
117
+ export default lumoAuthMiddleware(); // refresh only, protect nothing
118
+ ```
119
+
120
+ ### Why refresh lives in middleware
121
+
122
+ Only middleware, route handlers, and server actions can write cookies in
123
+ Next.js. Server components cannot — so a server component can never persist a
124
+ refreshed token.
125
+
126
+ That is not a technicality to route around. LumoAuth **rotates refresh tokens
127
+ and revokes the old one on use**, so refreshing somewhere that cannot save the
128
+ result would spend the token and break the session on the very next request.
129
+ `auth()` therefore returns `getToken() === null` and `isStale === true` rather
130
+ than performing a refresh it cannot persist.
131
+
132
+ Middleware writes the new cookie on the *response*, but the page reads the
133
+ *request* — so the fresh session is also forwarded on a request header that
134
+ `auth()` prefers. Without that, a refresh would not take effect until the
135
+ following request.
136
+
137
+ This is the same problem Clerk solves with its handshake, but simpler here:
138
+ Clerk must bounce the browser through its API because only that origin holds
139
+ the session, whereas this package holds the refresh token in its own cookie and
140
+ can refresh server-to-server with no redirect.
141
+
142
+ ## Limitations
143
+
144
+ - Without `lumoAuthMiddleware()`, `getToken()` returns null once the access
145
+ token goes stale (`isStale` tells you why). The session stays valid; nothing
146
+ is silently broken, but you get no token until something refreshes it.
147
+ - Pages Router is not supported yet. App Router only.
@@ -0,0 +1,19 @@
1
+ import { LumoAuthProviderProps } from '@lumoauth/react';
2
+ export { AppearanceProps, AuthCallback, AuthCallbackProps, AuthState, AuthStatus, LumoAuth, LumoAuthConfig, LumoAuthContextValue, LumoAuthProvider, LumoAuthProviderProps, LumoAuthUser, Protect, ProtectProps, RedirectToSignIn, RedirectToSignInProps, SignIn, SignInButton, SignInButtonProps, SignInProps, SignOutButton, SignOutButtonProps, SignUp, SignUpButton, SignUpButtonProps, SignUpProps, SignedIn, SignedInProps, SignedOut, SignedOutProps, UseEmailFirstReturn, UseMagicLinkReturn, UserAvatar, UserAvatarProps, UserButton, UserButtonProps, UserProfile, UserProfileProps, useAbac, useAuth, useEmailFirst, useLumoAuth, useMagicLink, usePermission, useSession, useSignIn, useUser, useZanzibar } from '@lumoauth/react';
3
+ import * as react from 'react';
4
+
5
+ type LumoAuthNextProviderProps = Omit<LumoAuthProviderProps, 'storage'> & {
6
+ /** Base path where createRouteHandler is mounted. @default '/api/auth' */
7
+ basePath?: string;
8
+ };
9
+ /**
10
+ * Provider wired to the server-side session.
11
+ *
12
+ * The plain `<LumoAuthProvider>` keeps tokens in web storage, which the server
13
+ * cannot see — so a page always renders signed-out first and corrects itself
14
+ * after hydration. This one reads the session from the httpOnly cookie via the
15
+ * route handler, matching what `auth()` already rendered on the server.
16
+ */
17
+ declare function LumoAuthNextProvider({ basePath, children, ...rest }: LumoAuthNextProviderProps): react.JSX.Element;
18
+
19
+ export { LumoAuthNextProvider };
@@ -0,0 +1,19 @@
1
+ import { LumoAuthProviderProps } from '@lumoauth/react';
2
+ export { AppearanceProps, AuthCallback, AuthCallbackProps, AuthState, AuthStatus, LumoAuth, LumoAuthConfig, LumoAuthContextValue, LumoAuthProvider, LumoAuthProviderProps, LumoAuthUser, Protect, ProtectProps, RedirectToSignIn, RedirectToSignInProps, SignIn, SignInButton, SignInButtonProps, SignInProps, SignOutButton, SignOutButtonProps, SignUp, SignUpButton, SignUpButtonProps, SignUpProps, SignedIn, SignedInProps, SignedOut, SignedOutProps, UseEmailFirstReturn, UseMagicLinkReturn, UserAvatar, UserAvatarProps, UserButton, UserButtonProps, UserProfile, UserProfileProps, useAbac, useAuth, useEmailFirst, useLumoAuth, useMagicLink, usePermission, useSession, useSignIn, useUser, useZanzibar } from '@lumoauth/react';
3
+ import * as react from 'react';
4
+
5
+ type LumoAuthNextProviderProps = Omit<LumoAuthProviderProps, 'storage'> & {
6
+ /** Base path where createRouteHandler is mounted. @default '/api/auth' */
7
+ basePath?: string;
8
+ };
9
+ /**
10
+ * Provider wired to the server-side session.
11
+ *
12
+ * The plain `<LumoAuthProvider>` keeps tokens in web storage, which the server
13
+ * cannot see — so a page always renders signed-out first and corrects itself
14
+ * after hydration. This one reads the session from the httpOnly cookie via the
15
+ * route handler, matching what `auth()` already rendered on the server.
16
+ */
17
+ declare function LumoAuthNextProvider({ basePath, children, ...rest }: LumoAuthNextProviderProps): react.JSX.Element;
18
+
19
+ export { LumoAuthNextProvider };
package/dist/index.js ADDED
@@ -0,0 +1,110 @@
1
+ "use client";
2
+ "use strict";
3
+ "use client";
4
+ var __defProp = Object.defineProperty;
5
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
6
+ var __getOwnPropNames = Object.getOwnPropertyNames;
7
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
8
+ var __export = (target, all) => {
9
+ for (var name in all)
10
+ __defProp(target, name, { get: all[name], enumerable: true });
11
+ };
12
+ var __copyProps = (to, from, except, desc) => {
13
+ if (from && typeof from === "object" || typeof from === "function") {
14
+ for (let key of __getOwnPropNames(from))
15
+ if (!__hasOwnProp.call(to, key) && key !== except)
16
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
17
+ }
18
+ return to;
19
+ };
20
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
21
+
22
+ // src/index.ts
23
+ var src_exports = {};
24
+ __export(src_exports, {
25
+ AuthCallback: () => import_react5.AuthCallback,
26
+ LumoAuth: () => import_react3.LumoAuth,
27
+ LumoAuthNextProvider: () => LumoAuthNextProvider,
28
+ LumoAuthProvider: () => import_react4.LumoAuthProvider,
29
+ Protect: () => import_react7.Protect,
30
+ RedirectToSignIn: () => import_react8.RedirectToSignIn,
31
+ SignIn: () => import_react5.SignIn,
32
+ SignInButton: () => import_react9.SignInButton,
33
+ SignOutButton: () => import_react9.SignOutButton,
34
+ SignUp: () => import_react5.SignUp,
35
+ SignUpButton: () => import_react9.SignUpButton,
36
+ SignedIn: () => import_react8.SignedIn,
37
+ SignedOut: () => import_react8.SignedOut,
38
+ UserAvatar: () => import_react6.UserAvatar,
39
+ UserButton: () => import_react6.UserButton,
40
+ UserProfile: () => import_react6.UserProfile,
41
+ useAbac: () => import_react10.useAbac,
42
+ useAuth: () => import_react10.useAuth,
43
+ useEmailFirst: () => import_react10.useEmailFirst,
44
+ useLumoAuth: () => import_react10.useLumoAuth,
45
+ useMagicLink: () => import_react10.useMagicLink,
46
+ usePermission: () => import_react10.usePermission,
47
+ useSession: () => import_react10.useSession,
48
+ useSignIn: () => import_react10.useSignIn,
49
+ useUser: () => import_react10.useUser,
50
+ useZanzibar: () => import_react10.useZanzibar
51
+ });
52
+ module.exports = __toCommonJS(src_exports);
53
+ var import_react3 = require("@lumoauth/react");
54
+ var import_react4 = require("@lumoauth/react");
55
+ var import_react5 = require("@lumoauth/react");
56
+ var import_react6 = require("@lumoauth/react");
57
+ var import_react7 = require("@lumoauth/react");
58
+ var import_react8 = require("@lumoauth/react");
59
+ var import_react9 = require("@lumoauth/react");
60
+ var import_react10 = require("@lumoauth/react");
61
+
62
+ // src/provider.tsx
63
+ var import_react = require("react");
64
+ var import_react2 = require("@lumoauth/react");
65
+ var import_client = require("@lumoauth/client");
66
+ var import_jsx_runtime = require("react/jsx-runtime");
67
+ function LumoAuthNextProvider({
68
+ basePath = "/api/auth",
69
+ children,
70
+ ...rest
71
+ }) {
72
+ const storage = (0, import_react.useMemo)(
73
+ () => (0, import_client.cookieStorageAdapter)({
74
+ sessionEndpoint: `${basePath}/session`,
75
+ logoutEndpoint: `${basePath}/logout`
76
+ }),
77
+ [basePath]
78
+ );
79
+ return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.LumoAuthProvider, { ...rest, storage, children });
80
+ }
81
+ // Annotate the CommonJS export names for ESM import in node:
82
+ 0 && (module.exports = {
83
+ AuthCallback,
84
+ LumoAuth,
85
+ LumoAuthNextProvider,
86
+ LumoAuthProvider,
87
+ Protect,
88
+ RedirectToSignIn,
89
+ SignIn,
90
+ SignInButton,
91
+ SignOutButton,
92
+ SignUp,
93
+ SignUpButton,
94
+ SignedIn,
95
+ SignedOut,
96
+ UserAvatar,
97
+ UserButton,
98
+ UserProfile,
99
+ useAbac,
100
+ useAuth,
101
+ useEmailFirst,
102
+ useLumoAuth,
103
+ useMagicLink,
104
+ usePermission,
105
+ useSession,
106
+ useSignIn,
107
+ useUser,
108
+ useZanzibar
109
+ });
110
+ //# sourceMappingURL=index.js.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":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,IAAAA,gBAA8C;AAG9C,IAAAA,gBAAiC;AAGjC,IAAAA,gBAA6C;AAG7C,IAAAA,gBAAoD;AAGpD,IAAAA,gBAAwB;AAGxB,IAAAA,gBAAsD;AAGtD,IAAAA,gBAA0D;AAG1D,IAAAA,iBAWO;;;ACzCP,mBAAwB;AACxB,IAAAC,gBAA6D;AAC7D,oBAAqC;AAgC7B;AAjBD,SAAS,qBAAqB;AAAA,EACjC,WAAW;AAAA,EACX;AAAA,EACA,GAAG;AACP,GAA8B;AAG1B,QAAM,cAAU;AAAA,IACZ,UACI,oCAAqB;AAAA,MACjB,iBAAiB,GAAG,QAAQ;AAAA,MAC5B,gBAAgB,GAAG,QAAQ;AAAA,IAC/B,CAAC;AAAA,IACL,CAAC,QAAQ;AAAA,EACb;AAEA,SACI,4CAAC,kCAAkB,GAAG,MAAM,SACvB,UACL;AAER;","names":["import_react","import_react"]}
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 };