@lumoauth/client 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 +754 -2
- package/dist/index.d.mts +325 -0
- package/dist/index.d.ts +325 -0
- package/dist/index.js +462 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +435 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +52 -5
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
import * as _lumoauth_shared from '@lumoauth/shared';
|
|
2
|
+
import { ApprovalsModule, PermissionsModule, ZanzibarModule, AbacModule, AuthModule, AgentsModule, PermissionsModuleOptions, TokenResponse } from '@lumoauth/shared';
|
|
3
|
+
export * from '@lumoauth/shared';
|
|
4
|
+
|
|
5
|
+
interface LumoAuthConfig {
|
|
6
|
+
/**
|
|
7
|
+
* Base URL of your LumoAuth instance.
|
|
8
|
+
* @example "https://auth.example.com"
|
|
9
|
+
*/
|
|
10
|
+
baseUrl: string;
|
|
11
|
+
/**
|
|
12
|
+
* Access token for the authenticated user.
|
|
13
|
+
* Can be a static string or an async function that returns a fresh token.
|
|
14
|
+
*
|
|
15
|
+
* Optional — not needed before first sign-in when using PKCE flow.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* // Static token
|
|
19
|
+
* token: 'eyJhbGciOi...'
|
|
20
|
+
*
|
|
21
|
+
* // Dynamic token (recommended for SPAs & server-side)
|
|
22
|
+
* token: () => getAccessTokenFromSession()
|
|
23
|
+
*/
|
|
24
|
+
token?: string | (() => string | Promise<string>);
|
|
25
|
+
/**
|
|
26
|
+
* Authentication strategy.
|
|
27
|
+
* - `'pkce'` — OAuth 2.0 Authorization Code + PKCE (default, recommended for SPAs)
|
|
28
|
+
* - `'password'` — Resource Owner Password Credentials grant (legacy)
|
|
29
|
+
*
|
|
30
|
+
* @default 'pkce'
|
|
31
|
+
*/
|
|
32
|
+
authStrategy?: 'pkce' | 'password';
|
|
33
|
+
/**
|
|
34
|
+
* Your organization ID (e.g. "acme-corp").
|
|
35
|
+
* Required for building authorization URLs.
|
|
36
|
+
*/
|
|
37
|
+
orgId?: string;
|
|
38
|
+
/**
|
|
39
|
+
* OAuth client ID.
|
|
40
|
+
* Required when using the auth module.
|
|
41
|
+
*/
|
|
42
|
+
clientId?: string;
|
|
43
|
+
/** Request timeout in milliseconds. Default: 30 000 ms. */
|
|
44
|
+
timeout?: number;
|
|
45
|
+
/**
|
|
46
|
+
* Custom `fetch` implementation.
|
|
47
|
+
* Defaults to the global `fetch`. Useful for testing or
|
|
48
|
+
* environments without a global `fetch` (e.g. older Node.js).
|
|
49
|
+
*/
|
|
50
|
+
fetch?: typeof globalThis.fetch;
|
|
51
|
+
/** Additional headers sent with every request. */
|
|
52
|
+
headers?: Record<string, string>;
|
|
53
|
+
/** Options for the permissions module cache. */
|
|
54
|
+
cache?: boolean | PermissionsModuleOptions['cache'];
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Browser-safe subset of the approvals surface: status polling only.
|
|
58
|
+
* Creating approvals lives on the server/agent SDKs.
|
|
59
|
+
*/
|
|
60
|
+
type ClientApprovals = Pick<ApprovalsModule, 'getStatus' | 'wait'>;
|
|
61
|
+
/**
|
|
62
|
+
* The main LumoAuth client. Provides access to all authorization and
|
|
63
|
+
* authentication modules.
|
|
64
|
+
*
|
|
65
|
+
* @example
|
|
66
|
+
* ```ts
|
|
67
|
+
* import { LumoAuth } from '@lumoauth/client';
|
|
68
|
+
*
|
|
69
|
+
* // PKCE mode (recommended)
|
|
70
|
+
* const client = new LumoAuth({
|
|
71
|
+
* baseUrl: 'https://auth.example.com',
|
|
72
|
+
* orgId: 'acme-corp',
|
|
73
|
+
* clientId: 'my-client-id',
|
|
74
|
+
* });
|
|
75
|
+
*
|
|
76
|
+
* // Build authorization URL and redirect
|
|
77
|
+
* const { url, codeVerifier, state } = await client.auth.buildAuthorizationUrl({
|
|
78
|
+
* redirectUri: 'http://localhost:3000/callback',
|
|
79
|
+
* });
|
|
80
|
+
*
|
|
81
|
+
* // Legacy mode with token
|
|
82
|
+
* const authedClient = new LumoAuth({
|
|
83
|
+
* baseUrl: 'https://auth.example.com',
|
|
84
|
+
* token: () => getAccessToken(),
|
|
85
|
+
* });
|
|
86
|
+
*
|
|
87
|
+
* // Permission checks (RBAC)
|
|
88
|
+
* const canEdit = await authedClient.permissions.check('document.edit');
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
91
|
+
declare class LumoAuth {
|
|
92
|
+
/** RBAC permission checks. */
|
|
93
|
+
readonly permissions: PermissionsModule;
|
|
94
|
+
/** Zanzibar-style (ReBAC) relationship checks. */
|
|
95
|
+
readonly zanzibar: ZanzibarModule;
|
|
96
|
+
/** ABAC policy evaluation and attribute management. */
|
|
97
|
+
readonly abac: AbacModule;
|
|
98
|
+
/** OAuth 2.0 authentication — PKCE flow, token exchange, refresh. */
|
|
99
|
+
readonly auth: AuthModule;
|
|
100
|
+
/** Agent identity — ask/isAllowed and self-inspection. */
|
|
101
|
+
readonly agents: AgentsModule;
|
|
102
|
+
/**
|
|
103
|
+
* Approval status polling — the browser-safe subset of the approvals
|
|
104
|
+
* surface. Creating approvals (`require()`) is an agent/server action;
|
|
105
|
+
* use `@lumoauth/backend` or `@lumoauth/agent` for that.
|
|
106
|
+
*/
|
|
107
|
+
readonly approvals: ClientApprovals;
|
|
108
|
+
private readonly http;
|
|
109
|
+
constructor(config: LumoAuthConfig);
|
|
110
|
+
/**
|
|
111
|
+
* @deprecated Renamed to {@link agents}. This alias will be removed
|
|
112
|
+
* before 2.0.
|
|
113
|
+
*/
|
|
114
|
+
get agent(): AgentsModule;
|
|
115
|
+
/**
|
|
116
|
+
* Clear all client-side caches.
|
|
117
|
+
* Call after the user's roles, groups, or attributes change.
|
|
118
|
+
*/
|
|
119
|
+
clearCache(): void;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Token storage adapters.
|
|
124
|
+
*
|
|
125
|
+
* Where tokens live is the single most consequential security decision in a
|
|
126
|
+
* browser SDK, and the right answer depends on the app. This module makes it a
|
|
127
|
+
* choice rather than a hardcoded default.
|
|
128
|
+
*
|
|
129
|
+
* The trade-off:
|
|
130
|
+
*
|
|
131
|
+
* | Adapter | XSS-readable | Survives reload | Cross-tab | SSR |
|
|
132
|
+
* |------------------|--------------|-----------------|-----------|-----|
|
|
133
|
+
* | `sessionStorage` | yes | per tab | no | no |
|
|
134
|
+
* | `localStorage` | yes | yes | yes | no |
|
|
135
|
+
* | `memory` | no* | no | no | yes |
|
|
136
|
+
* | `cookie` (BFF) | no | yes | yes | yes |
|
|
137
|
+
*
|
|
138
|
+
* \* memory is not readable from another origin's script, but it is still in
|
|
139
|
+
* the JS heap; it is "safe" only in the sense that nothing persists.
|
|
140
|
+
*
|
|
141
|
+
* `cookie` is the strongest option: tokens live in an httpOnly cookie your
|
|
142
|
+
* server sets, and never enter JavaScript at all. It requires a same-origin
|
|
143
|
+
* backend to exchange and refresh on the browser's behalf, which is what
|
|
144
|
+
* @lumoauth/express and (Phase 3) @lumoauth/nextjs provide.
|
|
145
|
+
*/
|
|
146
|
+
interface StoredTokens {
|
|
147
|
+
accessToken: string | null;
|
|
148
|
+
refreshToken: string | null;
|
|
149
|
+
idToken: string | null;
|
|
150
|
+
/** Absolute expiry, epoch milliseconds. */
|
|
151
|
+
expiresAt: number | null;
|
|
152
|
+
}
|
|
153
|
+
declare const EMPTY_TOKENS: StoredTokens;
|
|
154
|
+
interface TokenStorage {
|
|
155
|
+
/** Identifies the adapter in errors and diagnostics. */
|
|
156
|
+
readonly name: string;
|
|
157
|
+
get(): StoredTokens | Promise<StoredTokens>;
|
|
158
|
+
set(tokens: StoredTokens): void | Promise<void>;
|
|
159
|
+
clear(): void | Promise<void>;
|
|
160
|
+
/**
|
|
161
|
+
* Optional. Called when the store changes outside this tab; return an
|
|
162
|
+
* unsubscribe function. Adapters backed by a shared medium (localStorage,
|
|
163
|
+
* cookies) can implement this so other tabs stay in sync.
|
|
164
|
+
*/
|
|
165
|
+
subscribe?(onExternalChange: () => void): () => void;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Default. Per-tab, cleared when the tab closes.
|
|
169
|
+
*
|
|
170
|
+
* Note this means a new tab starts signed out and must complete a redirect
|
|
171
|
+
* round-trip. Use {@link localStorageAdapter} to share the session across tabs,
|
|
172
|
+
* or {@link cookieStorageAdapter} to keep tokens out of JavaScript entirely.
|
|
173
|
+
*/
|
|
174
|
+
declare function sessionStorageAdapter(): TokenStorage;
|
|
175
|
+
/** Shared across tabs and survives a browser restart. Still XSS-readable. */
|
|
176
|
+
declare function localStorageAdapter(): TokenStorage;
|
|
177
|
+
/**
|
|
178
|
+
* In-memory only. Nothing persists, so a reload signs the user out.
|
|
179
|
+
*
|
|
180
|
+
* This is the correct default on the server: it is inert during SSR instead of
|
|
181
|
+
* touching a `window` that does not exist.
|
|
182
|
+
*/
|
|
183
|
+
declare function memoryStorageAdapter(): TokenStorage;
|
|
184
|
+
interface CookieStorageOptions {
|
|
185
|
+
/**
|
|
186
|
+
* Same-origin endpoint that returns the current session as JSON
|
|
187
|
+
* (`{accessToken, expiresAt, ...}`) reading it from an httpOnly cookie.
|
|
188
|
+
* @default '/auth/session'
|
|
189
|
+
*/
|
|
190
|
+
sessionEndpoint?: string;
|
|
191
|
+
/**
|
|
192
|
+
* Same-origin endpoint that clears the session cookie.
|
|
193
|
+
* @default '/auth/logout'
|
|
194
|
+
*/
|
|
195
|
+
logoutEndpoint?: string;
|
|
196
|
+
fetch?: typeof globalThis.fetch;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Backend-for-frontend adapter: tokens live in an httpOnly cookie and are never
|
|
200
|
+
* exposed to JavaScript.
|
|
201
|
+
*
|
|
202
|
+
* This is the only option here that survives XSS. The cost is that a
|
|
203
|
+
* same-origin server must own the OAuth exchange and refresh —
|
|
204
|
+
* @lumoauth/express already provides those routes.
|
|
205
|
+
*
|
|
206
|
+
* `set()` is intentionally a no-op: the browser cannot write an httpOnly
|
|
207
|
+
* cookie, so only the server may establish the session. Reads go over the
|
|
208
|
+
* network, so the session store caches them rather than calling per request.
|
|
209
|
+
*/
|
|
210
|
+
declare function cookieStorageAdapter(options?: CookieStorageOptions): TokenStorage;
|
|
211
|
+
/**
|
|
212
|
+
* The default: `sessionStorage` in a browser, memory on the server.
|
|
213
|
+
*
|
|
214
|
+
* Chosen so that importing the SDK into an SSR framework does not blow up on a
|
|
215
|
+
* missing `window`, while browser behaviour is unchanged.
|
|
216
|
+
*/
|
|
217
|
+
declare function defaultStorage(): TokenStorage;
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Framework-agnostic session runtime.
|
|
221
|
+
*
|
|
222
|
+
* This owns everything that is not React: token persistence, the refresh
|
|
223
|
+
* schedule, the PKCE handshake, and cross-tab coordination. `@lumoauth/react`
|
|
224
|
+
* is a thin binding over it, and a Vue or Svelte binding would be the same
|
|
225
|
+
* shape — which is the reason this exists as a standalone class rather than
|
|
226
|
+
* living inside a provider component.
|
|
227
|
+
*
|
|
228
|
+
* Subscribe/getSnapshot are deliberately shaped for React's
|
|
229
|
+
* `useSyncExternalStore`, but they are plain functions with no React
|
|
230
|
+
* dependency.
|
|
231
|
+
*/
|
|
232
|
+
type SessionStatus = 'loading' | 'authenticated' | 'unauthenticated';
|
|
233
|
+
interface SessionState {
|
|
234
|
+
status: SessionStatus;
|
|
235
|
+
isLoaded: boolean;
|
|
236
|
+
isSignedIn: boolean;
|
|
237
|
+
/**
|
|
238
|
+
* Why the last operation failed, if it did. The previous implementation
|
|
239
|
+
* discarded this — an ERROR action collapsed to `unauthenticated` and the
|
|
240
|
+
* message was dropped, so callers could not tell "signed out" from
|
|
241
|
+
* "refresh failed".
|
|
242
|
+
*/
|
|
243
|
+
error: string | null;
|
|
244
|
+
}
|
|
245
|
+
interface SessionOptions {
|
|
246
|
+
auth: AuthModule;
|
|
247
|
+
redirectUri: string;
|
|
248
|
+
scope?: string;
|
|
249
|
+
storage?: TokenStorage;
|
|
250
|
+
/**
|
|
251
|
+
* Share the session across tabs. When enabled, a token refresh in one tab
|
|
252
|
+
* is broadcast to the others, and only one tab performs the refresh.
|
|
253
|
+
*
|
|
254
|
+
* Independent of the storage adapter: `sessionStorage` is per-tab, so
|
|
255
|
+
* broadcasting keeps siblings live for the current session even though
|
|
256
|
+
* nothing is shared on disk.
|
|
257
|
+
* @default true
|
|
258
|
+
*/
|
|
259
|
+
crossTab?: boolean;
|
|
260
|
+
/** Called after tokens change, so the host can refetch the user. */
|
|
261
|
+
onTokens?: (tokens: StoredTokens) => void;
|
|
262
|
+
}
|
|
263
|
+
declare class LumoAuthSession {
|
|
264
|
+
private state;
|
|
265
|
+
private tokens;
|
|
266
|
+
private listeners;
|
|
267
|
+
private timer;
|
|
268
|
+
private channel;
|
|
269
|
+
private unsubscribeStorage;
|
|
270
|
+
private inflightRefresh;
|
|
271
|
+
private readonly auth;
|
|
272
|
+
private readonly storage;
|
|
273
|
+
private readonly redirectUri;
|
|
274
|
+
private readonly scope;
|
|
275
|
+
private readonly onTokens?;
|
|
276
|
+
constructor(opts: SessionOptions);
|
|
277
|
+
subscribe: (fn: () => void) => (() => void);
|
|
278
|
+
getSnapshot: () => SessionState;
|
|
279
|
+
/** Server snapshot for `useSyncExternalStore` — always the loading state. */
|
|
280
|
+
getServerSnapshot: () => SessionState;
|
|
281
|
+
private emit;
|
|
282
|
+
/** Load persisted tokens and settle into signed-in or signed-out. */
|
|
283
|
+
hydrate(): Promise<void>;
|
|
284
|
+
dispose(): void;
|
|
285
|
+
getTokens(): Readonly<StoredTokens>;
|
|
286
|
+
private persist;
|
|
287
|
+
static tokensFrom(res: TokenResponse, previous?: StoredTokens): StoredTokens;
|
|
288
|
+
/**
|
|
289
|
+
* A valid access token, refreshing first if it is about to expire.
|
|
290
|
+
* Returns null when there is no session.
|
|
291
|
+
*/
|
|
292
|
+
getToken(): Promise<string | null>;
|
|
293
|
+
/**
|
|
294
|
+
* Refresh the access token.
|
|
295
|
+
*
|
|
296
|
+
* Concurrent callers share one in-flight request. Across tabs, a Web Lock
|
|
297
|
+
* elects a single refresher — without it, every tab refreshes on its own
|
|
298
|
+
* timer and they race on a rotated refresh token, so all but the winner
|
|
299
|
+
* are signed out.
|
|
300
|
+
*/
|
|
301
|
+
refresh(): Promise<string | null>;
|
|
302
|
+
private doRefresh;
|
|
303
|
+
private scheduleRefresh;
|
|
304
|
+
/** Adopt tokens obtained elsewhere (e.g. a completed code exchange). */
|
|
305
|
+
adopt(res: TokenResponse): Promise<void>;
|
|
306
|
+
/** Build the PKCE authorization URL; the caller persists verifier + state. */
|
|
307
|
+
buildAuthorizationUrl(extraParams?: Record<string, string>): Promise<_lumoauth_shared.AuthorizationUrlResult>;
|
|
308
|
+
/**
|
|
309
|
+
* Drop the session.
|
|
310
|
+
*
|
|
311
|
+
* `emit: false` clears tokens and storage without notifying subscribers.
|
|
312
|
+
* That is required during sign-out: emitting re-renders the tree, which
|
|
313
|
+
* mounts any `<SignedOut><RedirectToSignIn/></SignedOut>` guard, whose
|
|
314
|
+
* effect then races the pending logout navigation and sends the user back
|
|
315
|
+
* to /authorize — where the IdP session is still alive and silently
|
|
316
|
+
* re-issues a code, defeating logout entirely.
|
|
317
|
+
*/
|
|
318
|
+
clearSession(error?: string | null, opts?: {
|
|
319
|
+
broadcast?: boolean;
|
|
320
|
+
emit?: boolean;
|
|
321
|
+
}): Promise<void>;
|
|
322
|
+
private onBroadcast;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
export { type ClientApprovals, type CookieStorageOptions, EMPTY_TOKENS, LumoAuth, type LumoAuthConfig, LumoAuthSession, type SessionOptions, type SessionState, type SessionStatus, type StoredTokens, type TokenStorage, cookieStorageAdapter, defaultStorage, localStorageAdapter, memoryStorageAdapter, sessionStorageAdapter };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
import * as _lumoauth_shared from '@lumoauth/shared';
|
|
2
|
+
import { ApprovalsModule, PermissionsModule, ZanzibarModule, AbacModule, AuthModule, AgentsModule, PermissionsModuleOptions, TokenResponse } from '@lumoauth/shared';
|
|
3
|
+
export * from '@lumoauth/shared';
|
|
4
|
+
|
|
5
|
+
interface LumoAuthConfig {
|
|
6
|
+
/**
|
|
7
|
+
* Base URL of your LumoAuth instance.
|
|
8
|
+
* @example "https://auth.example.com"
|
|
9
|
+
*/
|
|
10
|
+
baseUrl: string;
|
|
11
|
+
/**
|
|
12
|
+
* Access token for the authenticated user.
|
|
13
|
+
* Can be a static string or an async function that returns a fresh token.
|
|
14
|
+
*
|
|
15
|
+
* Optional — not needed before first sign-in when using PKCE flow.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* // Static token
|
|
19
|
+
* token: 'eyJhbGciOi...'
|
|
20
|
+
*
|
|
21
|
+
* // Dynamic token (recommended for SPAs & server-side)
|
|
22
|
+
* token: () => getAccessTokenFromSession()
|
|
23
|
+
*/
|
|
24
|
+
token?: string | (() => string | Promise<string>);
|
|
25
|
+
/**
|
|
26
|
+
* Authentication strategy.
|
|
27
|
+
* - `'pkce'` — OAuth 2.0 Authorization Code + PKCE (default, recommended for SPAs)
|
|
28
|
+
* - `'password'` — Resource Owner Password Credentials grant (legacy)
|
|
29
|
+
*
|
|
30
|
+
* @default 'pkce'
|
|
31
|
+
*/
|
|
32
|
+
authStrategy?: 'pkce' | 'password';
|
|
33
|
+
/**
|
|
34
|
+
* Your organization ID (e.g. "acme-corp").
|
|
35
|
+
* Required for building authorization URLs.
|
|
36
|
+
*/
|
|
37
|
+
orgId?: string;
|
|
38
|
+
/**
|
|
39
|
+
* OAuth client ID.
|
|
40
|
+
* Required when using the auth module.
|
|
41
|
+
*/
|
|
42
|
+
clientId?: string;
|
|
43
|
+
/** Request timeout in milliseconds. Default: 30 000 ms. */
|
|
44
|
+
timeout?: number;
|
|
45
|
+
/**
|
|
46
|
+
* Custom `fetch` implementation.
|
|
47
|
+
* Defaults to the global `fetch`. Useful for testing or
|
|
48
|
+
* environments without a global `fetch` (e.g. older Node.js).
|
|
49
|
+
*/
|
|
50
|
+
fetch?: typeof globalThis.fetch;
|
|
51
|
+
/** Additional headers sent with every request. */
|
|
52
|
+
headers?: Record<string, string>;
|
|
53
|
+
/** Options for the permissions module cache. */
|
|
54
|
+
cache?: boolean | PermissionsModuleOptions['cache'];
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Browser-safe subset of the approvals surface: status polling only.
|
|
58
|
+
* Creating approvals lives on the server/agent SDKs.
|
|
59
|
+
*/
|
|
60
|
+
type ClientApprovals = Pick<ApprovalsModule, 'getStatus' | 'wait'>;
|
|
61
|
+
/**
|
|
62
|
+
* The main LumoAuth client. Provides access to all authorization and
|
|
63
|
+
* authentication modules.
|
|
64
|
+
*
|
|
65
|
+
* @example
|
|
66
|
+
* ```ts
|
|
67
|
+
* import { LumoAuth } from '@lumoauth/client';
|
|
68
|
+
*
|
|
69
|
+
* // PKCE mode (recommended)
|
|
70
|
+
* const client = new LumoAuth({
|
|
71
|
+
* baseUrl: 'https://auth.example.com',
|
|
72
|
+
* orgId: 'acme-corp',
|
|
73
|
+
* clientId: 'my-client-id',
|
|
74
|
+
* });
|
|
75
|
+
*
|
|
76
|
+
* // Build authorization URL and redirect
|
|
77
|
+
* const { url, codeVerifier, state } = await client.auth.buildAuthorizationUrl({
|
|
78
|
+
* redirectUri: 'http://localhost:3000/callback',
|
|
79
|
+
* });
|
|
80
|
+
*
|
|
81
|
+
* // Legacy mode with token
|
|
82
|
+
* const authedClient = new LumoAuth({
|
|
83
|
+
* baseUrl: 'https://auth.example.com',
|
|
84
|
+
* token: () => getAccessToken(),
|
|
85
|
+
* });
|
|
86
|
+
*
|
|
87
|
+
* // Permission checks (RBAC)
|
|
88
|
+
* const canEdit = await authedClient.permissions.check('document.edit');
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
91
|
+
declare class LumoAuth {
|
|
92
|
+
/** RBAC permission checks. */
|
|
93
|
+
readonly permissions: PermissionsModule;
|
|
94
|
+
/** Zanzibar-style (ReBAC) relationship checks. */
|
|
95
|
+
readonly zanzibar: ZanzibarModule;
|
|
96
|
+
/** ABAC policy evaluation and attribute management. */
|
|
97
|
+
readonly abac: AbacModule;
|
|
98
|
+
/** OAuth 2.0 authentication — PKCE flow, token exchange, refresh. */
|
|
99
|
+
readonly auth: AuthModule;
|
|
100
|
+
/** Agent identity — ask/isAllowed and self-inspection. */
|
|
101
|
+
readonly agents: AgentsModule;
|
|
102
|
+
/**
|
|
103
|
+
* Approval status polling — the browser-safe subset of the approvals
|
|
104
|
+
* surface. Creating approvals (`require()`) is an agent/server action;
|
|
105
|
+
* use `@lumoauth/backend` or `@lumoauth/agent` for that.
|
|
106
|
+
*/
|
|
107
|
+
readonly approvals: ClientApprovals;
|
|
108
|
+
private readonly http;
|
|
109
|
+
constructor(config: LumoAuthConfig);
|
|
110
|
+
/**
|
|
111
|
+
* @deprecated Renamed to {@link agents}. This alias will be removed
|
|
112
|
+
* before 2.0.
|
|
113
|
+
*/
|
|
114
|
+
get agent(): AgentsModule;
|
|
115
|
+
/**
|
|
116
|
+
* Clear all client-side caches.
|
|
117
|
+
* Call after the user's roles, groups, or attributes change.
|
|
118
|
+
*/
|
|
119
|
+
clearCache(): void;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Token storage adapters.
|
|
124
|
+
*
|
|
125
|
+
* Where tokens live is the single most consequential security decision in a
|
|
126
|
+
* browser SDK, and the right answer depends on the app. This module makes it a
|
|
127
|
+
* choice rather than a hardcoded default.
|
|
128
|
+
*
|
|
129
|
+
* The trade-off:
|
|
130
|
+
*
|
|
131
|
+
* | Adapter | XSS-readable | Survives reload | Cross-tab | SSR |
|
|
132
|
+
* |------------------|--------------|-----------------|-----------|-----|
|
|
133
|
+
* | `sessionStorage` | yes | per tab | no | no |
|
|
134
|
+
* | `localStorage` | yes | yes | yes | no |
|
|
135
|
+
* | `memory` | no* | no | no | yes |
|
|
136
|
+
* | `cookie` (BFF) | no | yes | yes | yes |
|
|
137
|
+
*
|
|
138
|
+
* \* memory is not readable from another origin's script, but it is still in
|
|
139
|
+
* the JS heap; it is "safe" only in the sense that nothing persists.
|
|
140
|
+
*
|
|
141
|
+
* `cookie` is the strongest option: tokens live in an httpOnly cookie your
|
|
142
|
+
* server sets, and never enter JavaScript at all. It requires a same-origin
|
|
143
|
+
* backend to exchange and refresh on the browser's behalf, which is what
|
|
144
|
+
* @lumoauth/express and (Phase 3) @lumoauth/nextjs provide.
|
|
145
|
+
*/
|
|
146
|
+
interface StoredTokens {
|
|
147
|
+
accessToken: string | null;
|
|
148
|
+
refreshToken: string | null;
|
|
149
|
+
idToken: string | null;
|
|
150
|
+
/** Absolute expiry, epoch milliseconds. */
|
|
151
|
+
expiresAt: number | null;
|
|
152
|
+
}
|
|
153
|
+
declare const EMPTY_TOKENS: StoredTokens;
|
|
154
|
+
interface TokenStorage {
|
|
155
|
+
/** Identifies the adapter in errors and diagnostics. */
|
|
156
|
+
readonly name: string;
|
|
157
|
+
get(): StoredTokens | Promise<StoredTokens>;
|
|
158
|
+
set(tokens: StoredTokens): void | Promise<void>;
|
|
159
|
+
clear(): void | Promise<void>;
|
|
160
|
+
/**
|
|
161
|
+
* Optional. Called when the store changes outside this tab; return an
|
|
162
|
+
* unsubscribe function. Adapters backed by a shared medium (localStorage,
|
|
163
|
+
* cookies) can implement this so other tabs stay in sync.
|
|
164
|
+
*/
|
|
165
|
+
subscribe?(onExternalChange: () => void): () => void;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Default. Per-tab, cleared when the tab closes.
|
|
169
|
+
*
|
|
170
|
+
* Note this means a new tab starts signed out and must complete a redirect
|
|
171
|
+
* round-trip. Use {@link localStorageAdapter} to share the session across tabs,
|
|
172
|
+
* or {@link cookieStorageAdapter} to keep tokens out of JavaScript entirely.
|
|
173
|
+
*/
|
|
174
|
+
declare function sessionStorageAdapter(): TokenStorage;
|
|
175
|
+
/** Shared across tabs and survives a browser restart. Still XSS-readable. */
|
|
176
|
+
declare function localStorageAdapter(): TokenStorage;
|
|
177
|
+
/**
|
|
178
|
+
* In-memory only. Nothing persists, so a reload signs the user out.
|
|
179
|
+
*
|
|
180
|
+
* This is the correct default on the server: it is inert during SSR instead of
|
|
181
|
+
* touching a `window` that does not exist.
|
|
182
|
+
*/
|
|
183
|
+
declare function memoryStorageAdapter(): TokenStorage;
|
|
184
|
+
interface CookieStorageOptions {
|
|
185
|
+
/**
|
|
186
|
+
* Same-origin endpoint that returns the current session as JSON
|
|
187
|
+
* (`{accessToken, expiresAt, ...}`) reading it from an httpOnly cookie.
|
|
188
|
+
* @default '/auth/session'
|
|
189
|
+
*/
|
|
190
|
+
sessionEndpoint?: string;
|
|
191
|
+
/**
|
|
192
|
+
* Same-origin endpoint that clears the session cookie.
|
|
193
|
+
* @default '/auth/logout'
|
|
194
|
+
*/
|
|
195
|
+
logoutEndpoint?: string;
|
|
196
|
+
fetch?: typeof globalThis.fetch;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Backend-for-frontend adapter: tokens live in an httpOnly cookie and are never
|
|
200
|
+
* exposed to JavaScript.
|
|
201
|
+
*
|
|
202
|
+
* This is the only option here that survives XSS. The cost is that a
|
|
203
|
+
* same-origin server must own the OAuth exchange and refresh —
|
|
204
|
+
* @lumoauth/express already provides those routes.
|
|
205
|
+
*
|
|
206
|
+
* `set()` is intentionally a no-op: the browser cannot write an httpOnly
|
|
207
|
+
* cookie, so only the server may establish the session. Reads go over the
|
|
208
|
+
* network, so the session store caches them rather than calling per request.
|
|
209
|
+
*/
|
|
210
|
+
declare function cookieStorageAdapter(options?: CookieStorageOptions): TokenStorage;
|
|
211
|
+
/**
|
|
212
|
+
* The default: `sessionStorage` in a browser, memory on the server.
|
|
213
|
+
*
|
|
214
|
+
* Chosen so that importing the SDK into an SSR framework does not blow up on a
|
|
215
|
+
* missing `window`, while browser behaviour is unchanged.
|
|
216
|
+
*/
|
|
217
|
+
declare function defaultStorage(): TokenStorage;
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Framework-agnostic session runtime.
|
|
221
|
+
*
|
|
222
|
+
* This owns everything that is not React: token persistence, the refresh
|
|
223
|
+
* schedule, the PKCE handshake, and cross-tab coordination. `@lumoauth/react`
|
|
224
|
+
* is a thin binding over it, and a Vue or Svelte binding would be the same
|
|
225
|
+
* shape — which is the reason this exists as a standalone class rather than
|
|
226
|
+
* living inside a provider component.
|
|
227
|
+
*
|
|
228
|
+
* Subscribe/getSnapshot are deliberately shaped for React's
|
|
229
|
+
* `useSyncExternalStore`, but they are plain functions with no React
|
|
230
|
+
* dependency.
|
|
231
|
+
*/
|
|
232
|
+
type SessionStatus = 'loading' | 'authenticated' | 'unauthenticated';
|
|
233
|
+
interface SessionState {
|
|
234
|
+
status: SessionStatus;
|
|
235
|
+
isLoaded: boolean;
|
|
236
|
+
isSignedIn: boolean;
|
|
237
|
+
/**
|
|
238
|
+
* Why the last operation failed, if it did. The previous implementation
|
|
239
|
+
* discarded this — an ERROR action collapsed to `unauthenticated` and the
|
|
240
|
+
* message was dropped, so callers could not tell "signed out" from
|
|
241
|
+
* "refresh failed".
|
|
242
|
+
*/
|
|
243
|
+
error: string | null;
|
|
244
|
+
}
|
|
245
|
+
interface SessionOptions {
|
|
246
|
+
auth: AuthModule;
|
|
247
|
+
redirectUri: string;
|
|
248
|
+
scope?: string;
|
|
249
|
+
storage?: TokenStorage;
|
|
250
|
+
/**
|
|
251
|
+
* Share the session across tabs. When enabled, a token refresh in one tab
|
|
252
|
+
* is broadcast to the others, and only one tab performs the refresh.
|
|
253
|
+
*
|
|
254
|
+
* Independent of the storage adapter: `sessionStorage` is per-tab, so
|
|
255
|
+
* broadcasting keeps siblings live for the current session even though
|
|
256
|
+
* nothing is shared on disk.
|
|
257
|
+
* @default true
|
|
258
|
+
*/
|
|
259
|
+
crossTab?: boolean;
|
|
260
|
+
/** Called after tokens change, so the host can refetch the user. */
|
|
261
|
+
onTokens?: (tokens: StoredTokens) => void;
|
|
262
|
+
}
|
|
263
|
+
declare class LumoAuthSession {
|
|
264
|
+
private state;
|
|
265
|
+
private tokens;
|
|
266
|
+
private listeners;
|
|
267
|
+
private timer;
|
|
268
|
+
private channel;
|
|
269
|
+
private unsubscribeStorage;
|
|
270
|
+
private inflightRefresh;
|
|
271
|
+
private readonly auth;
|
|
272
|
+
private readonly storage;
|
|
273
|
+
private readonly redirectUri;
|
|
274
|
+
private readonly scope;
|
|
275
|
+
private readonly onTokens?;
|
|
276
|
+
constructor(opts: SessionOptions);
|
|
277
|
+
subscribe: (fn: () => void) => (() => void);
|
|
278
|
+
getSnapshot: () => SessionState;
|
|
279
|
+
/** Server snapshot for `useSyncExternalStore` — always the loading state. */
|
|
280
|
+
getServerSnapshot: () => SessionState;
|
|
281
|
+
private emit;
|
|
282
|
+
/** Load persisted tokens and settle into signed-in or signed-out. */
|
|
283
|
+
hydrate(): Promise<void>;
|
|
284
|
+
dispose(): void;
|
|
285
|
+
getTokens(): Readonly<StoredTokens>;
|
|
286
|
+
private persist;
|
|
287
|
+
static tokensFrom(res: TokenResponse, previous?: StoredTokens): StoredTokens;
|
|
288
|
+
/**
|
|
289
|
+
* A valid access token, refreshing first if it is about to expire.
|
|
290
|
+
* Returns null when there is no session.
|
|
291
|
+
*/
|
|
292
|
+
getToken(): Promise<string | null>;
|
|
293
|
+
/**
|
|
294
|
+
* Refresh the access token.
|
|
295
|
+
*
|
|
296
|
+
* Concurrent callers share one in-flight request. Across tabs, a Web Lock
|
|
297
|
+
* elects a single refresher — without it, every tab refreshes on its own
|
|
298
|
+
* timer and they race on a rotated refresh token, so all but the winner
|
|
299
|
+
* are signed out.
|
|
300
|
+
*/
|
|
301
|
+
refresh(): Promise<string | null>;
|
|
302
|
+
private doRefresh;
|
|
303
|
+
private scheduleRefresh;
|
|
304
|
+
/** Adopt tokens obtained elsewhere (e.g. a completed code exchange). */
|
|
305
|
+
adopt(res: TokenResponse): Promise<void>;
|
|
306
|
+
/** Build the PKCE authorization URL; the caller persists verifier + state. */
|
|
307
|
+
buildAuthorizationUrl(extraParams?: Record<string, string>): Promise<_lumoauth_shared.AuthorizationUrlResult>;
|
|
308
|
+
/**
|
|
309
|
+
* Drop the session.
|
|
310
|
+
*
|
|
311
|
+
* `emit: false` clears tokens and storage without notifying subscribers.
|
|
312
|
+
* That is required during sign-out: emitting re-renders the tree, which
|
|
313
|
+
* mounts any `<SignedOut><RedirectToSignIn/></SignedOut>` guard, whose
|
|
314
|
+
* effect then races the pending logout navigation and sends the user back
|
|
315
|
+
* to /authorize — where the IdP session is still alive and silently
|
|
316
|
+
* re-issues a code, defeating logout entirely.
|
|
317
|
+
*/
|
|
318
|
+
clearSession(error?: string | null, opts?: {
|
|
319
|
+
broadcast?: boolean;
|
|
320
|
+
emit?: boolean;
|
|
321
|
+
}): Promise<void>;
|
|
322
|
+
private onBroadcast;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
export { type ClientApprovals, type CookieStorageOptions, EMPTY_TOKENS, LumoAuth, type LumoAuthConfig, LumoAuthSession, type SessionOptions, type SessionState, type SessionStatus, type StoredTokens, type TokenStorage, cookieStorageAdapter, defaultStorage, localStorageAdapter, memoryStorageAdapter, sessionStorageAdapter };
|