@plinthjs/auth 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +3 -3
- package/dist/index.cjs +13 -14
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +55 -56
- package/dist/index.d.ts +55 -56
- package/dist/index.js +13 -14
- package/dist/index.js.map +1 -1
- package/package.json +6 -7
package/dist/index.d.cts
CHANGED
|
@@ -3,11 +3,11 @@ import { Session } from '@plinthjs/session';
|
|
|
3
3
|
import { Hasher } from '@plinthjs/encryption';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* Authentication contracts — the
|
|
6
|
+
* Authentication contracts — the conventional API interfaces. {@link Authenticatable}
|
|
7
7
|
* is a user that can be authenticated; {@link UserProvider} retrieves and validates users from
|
|
8
8
|
* storage; {@link Guard} reads who the current user is; {@link StatefulGuard} also logs them in/out.
|
|
9
9
|
*/
|
|
10
|
-
/** A user that can be authenticated.
|
|
10
|
+
/** A user that can be authenticated. */
|
|
11
11
|
interface Authenticatable {
|
|
12
12
|
/** The unique identifier (primary key) for the user. */
|
|
13
13
|
getAuthIdentifier(): string | number;
|
|
@@ -18,7 +18,7 @@ interface Authenticatable {
|
|
|
18
18
|
}
|
|
19
19
|
/** Login credentials — typically `{ email, password }`. */
|
|
20
20
|
type Credentials = Record<string, unknown>;
|
|
21
|
-
/** A user that supports "remember me" persistence
|
|
21
|
+
/** A user that supports "remember me" persistence. */
|
|
22
22
|
interface Rememberable {
|
|
23
23
|
/** The persisted remember-me token, or `null` if none. */
|
|
24
24
|
getRememberToken(): string | null;
|
|
@@ -34,7 +34,7 @@ interface PasswordUpdatable {
|
|
|
34
34
|
setAuthPassword(hashed: string): void;
|
|
35
35
|
}
|
|
36
36
|
/**
|
|
37
|
-
* A structural event-dispatcher seam — the
|
|
37
|
+
* A structural event-dispatcher seam — the conventional API shape the auth
|
|
38
38
|
* layer needs. Any object with a `dispatch(event)` method satisfies it (e.g. `@plinthjs/events`),
|
|
39
39
|
* without this package importing an event implementation. When no dispatcher is provided the guards
|
|
40
40
|
* and brokers dispatch nothing, at zero overhead.
|
|
@@ -43,7 +43,7 @@ interface AuthEvents {
|
|
|
43
43
|
/** Dispatch an auth event object to its listeners. */
|
|
44
44
|
dispatch(event: object): void;
|
|
45
45
|
}
|
|
46
|
-
/** Retrieves and validates users from storage.
|
|
46
|
+
/** Retrieves and validates users from storage. */
|
|
47
47
|
interface UserProvider {
|
|
48
48
|
/** Find a user by primary key, or `null`. */
|
|
49
49
|
retrieveById(identifier: string | number): Promise<Authenticatable | null>;
|
|
@@ -57,12 +57,12 @@ interface UserProvider {
|
|
|
57
57
|
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
58
58
|
/**
|
|
59
59
|
* Re-hash and persist the user's password when the hash's cost parameters are stale (or always,
|
|
60
|
-
* when `force` is set) — the
|
|
60
|
+
* when `force` is set) — the conventional `rehashPasswordIfRequired` provider method. Optional so
|
|
61
61
|
* existing providers keep compiling; guards call it through optional chaining.
|
|
62
62
|
*/
|
|
63
63
|
rehashPasswordIfRequired?(user: Authenticatable, credentials: Credentials, force?: boolean): Promise<void>;
|
|
64
64
|
}
|
|
65
|
-
/** A read-only authentication guard.
|
|
65
|
+
/** A read-only authentication guard. */
|
|
66
66
|
interface Guard {
|
|
67
67
|
/** Whether a user is authenticated. */
|
|
68
68
|
check(): Promise<boolean>;
|
|
@@ -77,7 +77,7 @@ interface Guard {
|
|
|
77
77
|
/** Set the current user explicitly (e.g. after registration). */
|
|
78
78
|
setUser(user: Authenticatable): void;
|
|
79
79
|
}
|
|
80
|
-
/** A guard that can also log users in and out across requests.
|
|
80
|
+
/** A guard that can also log users in and out across requests. */
|
|
81
81
|
interface StatefulGuard extends Guard {
|
|
82
82
|
/** Validate credentials and, on success, log the user in. */
|
|
83
83
|
attempt(credentials: Credentials): Promise<boolean>;
|
|
@@ -94,7 +94,7 @@ interface StatefulGuard extends Guard {
|
|
|
94
94
|
logout(): void | Promise<void>;
|
|
95
95
|
}
|
|
96
96
|
|
|
97
|
-
/** A user whose email address can be verified.
|
|
97
|
+
/** A user whose email address can be verified. */
|
|
98
98
|
interface MustVerifyEmail {
|
|
99
99
|
/** The email address being verified. */
|
|
100
100
|
getEmailForVerification(): string;
|
|
@@ -146,8 +146,8 @@ declare class EmailVerifier {
|
|
|
146
146
|
}
|
|
147
147
|
|
|
148
148
|
/**
|
|
149
|
-
* Authentication events — the
|
|
150
|
-
* these through the optional {@link AuthEvents} seam at the same moments
|
|
149
|
+
* Authentication events — the conventional API classes. Guards and brokers dispatch
|
|
150
|
+
* these through the optional {@link AuthEvents} seam at the same moments conventional implementations fire them:
|
|
151
151
|
* {@link Attempting} before a credential attempt, {@link Validated} once credentials check out,
|
|
152
152
|
* {@link Login} + {@link Authenticated} when a user is logged in / set on the guard, {@link Failed}
|
|
153
153
|
* on a bad attempt, {@link Logout} / {@link CurrentDeviceLogout} / {@link OtherDeviceLogout} on the
|
|
@@ -156,7 +156,7 @@ declare class EmailVerifier {
|
|
|
156
156
|
* through any dispatcher that takes an object.
|
|
157
157
|
*/
|
|
158
158
|
|
|
159
|
-
/** Fired before every credential attempt — the
|
|
159
|
+
/** Fired before every credential attempt — the `Attempting` event. */
|
|
160
160
|
declare class Attempting {
|
|
161
161
|
/** The guard name the attempt runs on. */
|
|
162
162
|
readonly guard: string;
|
|
@@ -172,7 +172,7 @@ declare class Attempting {
|
|
|
172
172
|
/** Whether the attempt asked for "remember me" persistence. */
|
|
173
173
|
remember?: boolean);
|
|
174
174
|
}
|
|
175
|
-
/** Fired when credentials validate against a user — the
|
|
175
|
+
/** Fired when credentials validate against a user — the `Validated` event. */
|
|
176
176
|
declare class Validated {
|
|
177
177
|
/** The guard name the validation ran on. */
|
|
178
178
|
readonly guard: string;
|
|
@@ -184,7 +184,7 @@ declare class Validated {
|
|
|
184
184
|
/** The user the credentials validated against. */
|
|
185
185
|
user: Authenticatable);
|
|
186
186
|
}
|
|
187
|
-
/** Fired when a user is logged in for the session — the
|
|
187
|
+
/** Fired when a user is logged in for the session — the `Login` event. */
|
|
188
188
|
declare class Login {
|
|
189
189
|
/** The guard name the login happened on. */
|
|
190
190
|
readonly guard: string;
|
|
@@ -200,7 +200,7 @@ declare class Login {
|
|
|
200
200
|
/** Whether the login came from a remember-me recaller. */
|
|
201
201
|
remember: boolean);
|
|
202
202
|
}
|
|
203
|
-
/** Fired whenever a user is set on a guard — the
|
|
203
|
+
/** Fired whenever a user is set on a guard — the `Authenticated` event. */
|
|
204
204
|
declare class Authenticated {
|
|
205
205
|
/** The guard name the user was set on. */
|
|
206
206
|
readonly guard: string;
|
|
@@ -212,7 +212,7 @@ declare class Authenticated {
|
|
|
212
212
|
/** The user that is now authenticated. */
|
|
213
213
|
user: Authenticatable);
|
|
214
214
|
}
|
|
215
|
-
/** Fired when a credential attempt fails — the
|
|
215
|
+
/** Fired when a credential attempt fails — the `Failed` event. */
|
|
216
216
|
declare class Failed {
|
|
217
217
|
/** The guard name the attempt ran on. */
|
|
218
218
|
readonly guard: string;
|
|
@@ -228,7 +228,7 @@ declare class Failed {
|
|
|
228
228
|
/** The credentials that failed. */
|
|
229
229
|
credentials: Credentials);
|
|
230
230
|
}
|
|
231
|
-
/** Fired when the user logs out (remember token cycled) — the
|
|
231
|
+
/** Fired when the user logs out (remember token cycled) — the `Logout` event. */
|
|
232
232
|
declare class Logout {
|
|
233
233
|
/** The guard name the logout happened on. */
|
|
234
234
|
readonly guard: string;
|
|
@@ -240,7 +240,7 @@ declare class Logout {
|
|
|
240
240
|
/** The user that logged out. */
|
|
241
241
|
user: Authenticatable);
|
|
242
242
|
}
|
|
243
|
-
/** Fired on a current-device-only logout — the
|
|
243
|
+
/** Fired on a current-device-only logout — the `CurrentDeviceLogout` event. */
|
|
244
244
|
declare class CurrentDeviceLogout {
|
|
245
245
|
/** The guard name the logout happened on. */
|
|
246
246
|
readonly guard: string;
|
|
@@ -252,7 +252,7 @@ declare class CurrentDeviceLogout {
|
|
|
252
252
|
/** The user that logged out on this device. */
|
|
253
253
|
user: Authenticatable);
|
|
254
254
|
}
|
|
255
|
-
/** Fired when the user's other devices are logged out — the
|
|
255
|
+
/** Fired when the user's other devices are logged out — the `OtherDeviceLogout` event. */
|
|
256
256
|
declare class OtherDeviceLogout {
|
|
257
257
|
/** The guard name the logout happened on. */
|
|
258
258
|
readonly guard: string;
|
|
@@ -264,7 +264,7 @@ declare class OtherDeviceLogout {
|
|
|
264
264
|
/** The user whose other sessions were invalidated. */
|
|
265
265
|
user: Authenticatable);
|
|
266
266
|
}
|
|
267
|
-
/** Fired when a new account is registered (dispatched by application code) — the
|
|
267
|
+
/** Fired when a new account is registered (dispatched by application code) — the `Registered` event. */
|
|
268
268
|
declare class Registered {
|
|
269
269
|
/** The freshly registered user. */
|
|
270
270
|
readonly user: Authenticatable;
|
|
@@ -272,7 +272,7 @@ declare class Registered {
|
|
|
272
272
|
/** The freshly registered user. */
|
|
273
273
|
user: Authenticatable);
|
|
274
274
|
}
|
|
275
|
-
/** Fired when a user's email address is verified — the
|
|
275
|
+
/** Fired when a user's email address is verified — the `Verified` event. */
|
|
276
276
|
declare class Verified {
|
|
277
277
|
/** The user whose email was just verified. */
|
|
278
278
|
readonly user: Authenticatable;
|
|
@@ -280,7 +280,7 @@ declare class Verified {
|
|
|
280
280
|
/** The user whose email was just verified. */
|
|
281
281
|
user: Authenticatable);
|
|
282
282
|
}
|
|
283
|
-
/** Fired when a password is reset through the broker — the
|
|
283
|
+
/** Fired when a password is reset through the broker — the `PasswordReset` event. */
|
|
284
284
|
declare class PasswordReset {
|
|
285
285
|
/** The user whose password was reset. */
|
|
286
286
|
readonly user: Authenticatable;
|
|
@@ -289,8 +289,8 @@ declare class PasswordReset {
|
|
|
289
289
|
user: Authenticatable);
|
|
290
290
|
}
|
|
291
291
|
/**
|
|
292
|
-
* Fired when login attempts are rate-limited — the
|
|
293
|
-
* HTTP request;
|
|
292
|
+
* Fired when login attempts are rate-limited — the `Lockout` event. Conventional implementations carry the
|
|
293
|
+
* HTTP request; Plinth carries the credentials that triggered the lockout (dispatched by whatever
|
|
294
294
|
* rate-limiting layer the application wires up).
|
|
295
295
|
*/
|
|
296
296
|
declare class Lockout {
|
|
@@ -302,7 +302,7 @@ declare class Lockout {
|
|
|
302
302
|
}
|
|
303
303
|
|
|
304
304
|
/**
|
|
305
|
-
* Session key holding the hash of the authenticated user's password — the
|
|
305
|
+
* Session key holding the hash of the authenticated user's password — the conventional
|
|
306
306
|
* `AuthenticateSession` mechanism. The session middleware compares it against the user's current
|
|
307
307
|
* hash each request, so {@link SessionGuard.logoutOtherDevices} (which re-hashes the password)
|
|
308
308
|
* invalidates every other session while this one is kept in step.
|
|
@@ -319,7 +319,7 @@ interface SessionGuardOptions {
|
|
|
319
319
|
/** Optional event dispatcher; when unset no events are dispatched. */
|
|
320
320
|
events?: AuthEvents;
|
|
321
321
|
}
|
|
322
|
-
/** Session-backed, stateful guard.
|
|
322
|
+
/** Session-backed, stateful guard. */
|
|
323
323
|
declare class SessionGuard implements StatefulGuard {
|
|
324
324
|
private readonly provider;
|
|
325
325
|
private readonly session;
|
|
@@ -340,7 +340,7 @@ declare class SessionGuard implements StatefulGuard {
|
|
|
340
340
|
validate(credentials: Credentials): Promise<boolean>;
|
|
341
341
|
attempt(credentials: Credentials): Promise<boolean>;
|
|
342
342
|
/**
|
|
343
|
-
* Attempt to authenticate with additional callbacks — the
|
|
343
|
+
* Attempt to authenticate with additional callbacks — the `attemptWhen`. The callbacks
|
|
344
344
|
* run after the credentials validate, receiving the user and this guard; every one must return
|
|
345
345
|
* `true` (a falsy result fails the attempt without logging the user in).
|
|
346
346
|
*/
|
|
@@ -349,29 +349,28 @@ declare class SessionGuard implements StatefulGuard {
|
|
|
349
349
|
login(user: Authenticatable): void;
|
|
350
350
|
loginUsingId(id: string | number): Promise<Authenticatable | null>;
|
|
351
351
|
/**
|
|
352
|
-
* Log the current user out, cycling the remember token so every recaller dies — the
|
|
352
|
+
* Log the current user out, cycling the remember token so every recaller dies — the conventional
|
|
353
353
|
* `logout`. The session keys are cleared synchronously; the returned promise resolves once the
|
|
354
354
|
* token has been cycled through the provider and the `Logout` event dispatched.
|
|
355
355
|
*/
|
|
356
356
|
logout(): Promise<void>;
|
|
357
357
|
/**
|
|
358
|
-
* Log the current user out on this device only — the
|
|
358
|
+
* Log the current user out on this device only — the `logoutCurrentDevice`. Unlike
|
|
359
359
|
* {@link SessionGuard.logout} the remember token is *not* cycled, so other remembered devices
|
|
360
360
|
* stay logged in. Dispatches `CurrentDeviceLogout`.
|
|
361
361
|
*/
|
|
362
362
|
logoutCurrentDevice(): Promise<void>;
|
|
363
363
|
/**
|
|
364
|
-
* Invalidate the user's sessions on every other device — the
|
|
364
|
+
* Invalidate the user's sessions on every other device — the `logoutOtherDevices`.
|
|
365
365
|
* Validates `password` against the current user (throwing when it does not match), then:
|
|
366
366
|
*
|
|
367
367
|
* - force re-hashes the password through {@link UserProvider.rehashPasswordIfRequired} (when the
|
|
368
368
|
* provider supports it) and refreshes this session's stored password hash, so any session
|
|
369
369
|
* checked by `authenticateSession` whose stored hash is now stale is logged out — the same
|
|
370
|
-
* session-password-hash mechanism
|
|
370
|
+
* session-password-hash mechanism the conventional `AuthenticateSession` middleware uses; and
|
|
371
371
|
* - cycles the remember token, killing every previously issued recaller cookie.
|
|
372
372
|
*
|
|
373
|
-
* Returns the fresh recaller value for *this* device
|
|
374
|
-
* re-issue), or `null` when nobody is authenticated.
|
|
373
|
+
* Returns the fresh recaller value for *this* device, or `null` when nobody is authenticated.
|
|
375
374
|
*/
|
|
376
375
|
logoutOtherDevices(password: string): Promise<string | null>;
|
|
377
376
|
setUser(user: Authenticatable): void;
|
|
@@ -390,25 +389,25 @@ declare class SessionGuard implements StatefulGuard {
|
|
|
390
389
|
/** The "remember me" cookie lifetime in minutes. The `getRememberDuration` equivalent. */
|
|
391
390
|
getRememberDuration(): number;
|
|
392
391
|
/**
|
|
393
|
-
* Attempt HTTP Basic authentication, logging the user in for the session — the
|
|
392
|
+
* Attempt HTTP Basic authentication, logging the user in for the session — the `basic`.
|
|
394
393
|
* Resolves to `undefined` when already authenticated or when the `Authorization: Basic` header
|
|
395
394
|
* validates; otherwise resolves to a `401` challenge response (`WWW-Authenticate: Basic`).
|
|
396
395
|
* Requires the request (constructor option or {@link SessionGuard.setRequest}).
|
|
397
396
|
*/
|
|
398
397
|
basic(field?: string): Promise<Response | undefined>;
|
|
399
398
|
/**
|
|
400
|
-
* Perform a stateless HTTP Basic attempt (no session persistence) — the
|
|
399
|
+
* Perform a stateless HTTP Basic attempt (no session persistence) — the `onceBasic`.
|
|
401
400
|
* Resolves to `undefined` on success, or the `401` challenge response on failure.
|
|
402
401
|
*/
|
|
403
402
|
onceBasic(field?: string): Promise<Response | undefined>;
|
|
404
403
|
/**
|
|
405
404
|
* Issue a fresh remember-me token for `user`, persist it through the provider, and return the
|
|
406
|
-
* recaller value (`id|token`) to store in a long-lived cookie.
|
|
405
|
+
* recaller value (`id|token`) to store in a long-lived cookie.
|
|
407
406
|
*/
|
|
408
407
|
remember(user: Authenticatable): Promise<string>;
|
|
409
408
|
/**
|
|
410
409
|
* Authenticate from a recaller cookie value (`id|token`), logging the user in for the session on a
|
|
411
|
-
* constant-time token match
|
|
410
|
+
* constant-time token match. Returns the user, or `null`.
|
|
412
411
|
*/
|
|
413
412
|
loginUsingRecaller(value: string): Promise<Authenticatable | null>;
|
|
414
413
|
/** Persist the user's id and current password hash into the session. */
|
|
@@ -431,7 +430,7 @@ interface TokenGuardOptions {
|
|
|
431
430
|
/** Optional event dispatcher; when unset no events are dispatched. */
|
|
432
431
|
events?: AuthEvents;
|
|
433
432
|
}
|
|
434
|
-
/** Stateless token guard.
|
|
433
|
+
/** Stateless token guard. */
|
|
435
434
|
declare class TokenGuard implements Guard {
|
|
436
435
|
private readonly provider;
|
|
437
436
|
private readonly request;
|
|
@@ -457,7 +456,7 @@ declare class TokenGuard implements Guard {
|
|
|
457
456
|
*/
|
|
458
457
|
type RequestUserResolver = (request: Request, provider?: UserProvider) => Authenticatable | null | undefined | Promise<Authenticatable | null | undefined>;
|
|
459
458
|
/**
|
|
460
|
-
* Closure-driven guard over the current request — the
|
|
459
|
+
* Closure-driven guard over the current request — the `RequestGuard` (the engine behind
|
|
461
460
|
* `Auth::viaRequest`). Resolves the user once per instance through the callback.
|
|
462
461
|
*/
|
|
463
462
|
declare class RequestGuard implements Guard {
|
|
@@ -472,7 +471,7 @@ declare class RequestGuard implements Guard {
|
|
|
472
471
|
guest(): Promise<boolean>;
|
|
473
472
|
id(): Promise<string | number | null>;
|
|
474
473
|
/**
|
|
475
|
-
* Whether the callback resolves a user for `credentials['request']` — the
|
|
474
|
+
* Whether the callback resolves a user for `credentials['request']` — the conventional
|
|
476
475
|
* `RequestGuard::validate`, which runs the resolver against the given request.
|
|
477
476
|
*/
|
|
478
477
|
validate(credentials: Credentials): Promise<boolean>;
|
|
@@ -512,14 +511,14 @@ declare class AuthManager {
|
|
|
512
511
|
}
|
|
513
512
|
|
|
514
513
|
/**
|
|
515
|
-
* Authentication middleware bridging `@plinthjs/auth` to `@plinthjs/http` — the
|
|
514
|
+
* Authentication middleware bridging `@plinthjs/auth` to `@plinthjs/http` — the `Authenticate`
|
|
516
515
|
* (`auth`) middleware family. {@link authenticateSession} resolves the user from the session
|
|
517
516
|
* (requires the session middleware) and {@link authenticateToken} from a request token; both attach
|
|
518
517
|
* the user to the request (readable via {@link getUser}) or render a `401` via
|
|
519
518
|
* {@link AuthenticationError}. {@link authenticateSession} also keeps a hash of the user's password
|
|
520
|
-
* in the session
|
|
519
|
+
* in the session so sessions die when the password
|
|
521
520
|
* changes — e.g. after `SessionGuard.logoutOtherDevices`. {@link redirectIfAuthenticated} is the
|
|
522
|
-
* `guest` middleware, and {@link requirePassword} / {@link confirmPassword} implement the
|
|
521
|
+
* `guest` middleware, and {@link requirePassword} / {@link confirmPassword} implement the conventional
|
|
523
522
|
* `password.confirm` flow over an `auth.password_confirmed_at` session timestamp.
|
|
524
523
|
*/
|
|
525
524
|
|
|
@@ -534,7 +533,7 @@ declare function getUser(req: Request): Authenticatable | undefined;
|
|
|
534
533
|
/**
|
|
535
534
|
* Authenticate via the session — the web `auth` middleware. Requires the session middleware to have
|
|
536
535
|
* run; resolves the user from the session id and attaches it, or throws {@link AuthenticationError}.
|
|
537
|
-
* Also enforces the
|
|
536
|
+
* Also enforces the `AuthenticateSession` password-hash check: the user's password hash is
|
|
538
537
|
* stored in the session on first sight and compared on every request, so a password change (e.g.
|
|
539
538
|
* `SessionGuard.logoutOtherDevices`) logs every stale session out.
|
|
540
539
|
*/
|
|
@@ -545,26 +544,26 @@ declare function authenticateSession(provider: UserProvider): Middleware;
|
|
|
545
544
|
*/
|
|
546
545
|
declare function authenticateToken(provider: UserProvider, inputKey?: string): Middleware;
|
|
547
546
|
/**
|
|
548
|
-
* Redirect authenticated users away (e.g. from login/register pages) — the
|
|
547
|
+
* Redirect authenticated users away (e.g. from login/register pages) — the conventional
|
|
549
548
|
* `RedirectIfAuthenticated` (`guest`) middleware. Guests (and requests without a session) pass
|
|
550
549
|
* through; an authenticated session is redirected to `redirectTo`.
|
|
551
550
|
*/
|
|
552
551
|
declare function redirectIfAuthenticated(provider: UserProvider, redirectTo?: string): Middleware;
|
|
553
552
|
/**
|
|
554
|
-
* Require a recent password confirmation — the
|
|
553
|
+
* Require a recent password confirmation — the `RequirePassword` (`password.confirm`)
|
|
555
554
|
* middleware. Passes when the session's `auth.password_confirmed_at` timestamp is within
|
|
556
555
|
* `passwordTimeoutSeconds`; otherwise redirects to `redirectTo` (or renders `423 Locked` for JSON
|
|
557
556
|
* clients). Stamp the timestamp via {@link confirmPassword} after re-validating the password.
|
|
558
557
|
*/
|
|
559
558
|
declare function requirePassword(redirectTo?: string, passwordTimeoutSeconds?: number, now?: () => Date): Middleware;
|
|
560
559
|
/**
|
|
561
|
-
* Re-validate the user's password and stamp the session's confirmation timestamp — what
|
|
560
|
+
* Re-validate the user's password and stamp the session's confirmation timestamp — what the conventional
|
|
562
561
|
* `ConfirmablePasswordController` does for the `password.confirm` flow. Returns `false` (leaving
|
|
563
562
|
* the session untouched) when the password does not match.
|
|
564
563
|
*/
|
|
565
564
|
declare function confirmPassword(provider: UserProvider, session: Session, user: Authenticatable, password: string, now?: () => Date): Promise<boolean>;
|
|
566
565
|
|
|
567
|
-
/** The outcome of a broker operation — the
|
|
566
|
+
/** The outcome of a broker operation — the `Password::*` status constants. */
|
|
568
567
|
declare const PasswordStatus: {
|
|
569
568
|
readonly ResetLinkSent: "passwords.sent";
|
|
570
569
|
readonly PasswordReset: "passwords.reset";
|
|
@@ -575,7 +574,7 @@ declare const PasswordStatus: {
|
|
|
575
574
|
};
|
|
576
575
|
/** A password-broker status value. */
|
|
577
576
|
type PasswordStatus = (typeof PasswordStatus)[keyof typeof PasswordStatus];
|
|
578
|
-
/** Stores, verifies, and expires password-reset tokens.
|
|
577
|
+
/** Stores, verifies, and expires password-reset tokens. */
|
|
579
578
|
interface TokenRepository {
|
|
580
579
|
/** Mint, store, and return a fresh plaintext token for `user` (only its hash is kept). */
|
|
581
580
|
create(user: Authenticatable): Promise<string>;
|
|
@@ -592,9 +591,9 @@ interface TokenRepository {
|
|
|
592
591
|
interface ArrayTokenRepositoryOptions {
|
|
593
592
|
/** Hasher used to store token hashes (never the plaintext). */
|
|
594
593
|
hasher: Hasher;
|
|
595
|
-
/** Token lifetime in minutes
|
|
594
|
+
/** Token lifetime in minutes. Default `60`. */
|
|
596
595
|
expireMinutes?: number;
|
|
597
|
-
/** Re-send throttle window in seconds
|
|
596
|
+
/** Re-send throttle window in seconds. Default `60`. */
|
|
598
597
|
throttleSeconds?: number;
|
|
599
598
|
/** Injected clock for deterministic expiry/throttle. Default `() => new Date()`. */
|
|
600
599
|
now?: () => Date;
|
|
@@ -646,7 +645,7 @@ declare class PasswordBroker {
|
|
|
646
645
|
private lookupOnly;
|
|
647
646
|
}
|
|
648
647
|
|
|
649
|
-
/** A simple record-backed {@link Authenticatable}.
|
|
648
|
+
/** A simple record-backed {@link Authenticatable}. */
|
|
650
649
|
declare class GenericUser implements Authenticatable, Rememberable, PasswordUpdatable {
|
|
651
650
|
readonly attributes: Record<string, unknown>;
|
|
652
651
|
private readonly identifierName;
|
|
@@ -673,26 +672,26 @@ declare class ArrayUserProvider implements UserProvider {
|
|
|
673
672
|
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
674
673
|
/**
|
|
675
674
|
* Re-hash and persist the user's password when its cost parameters no longer match the hasher's
|
|
676
|
-
* (or always, when `force` is set) — the
|
|
675
|
+
* (or always, when `force` is set) — the `rehashPasswordIfRequired`. Persists through the
|
|
677
676
|
* {@link PasswordUpdatable} seam, mirroring how remember tokens are persisted.
|
|
678
677
|
*/
|
|
679
678
|
rehashPasswordIfRequired(user: Authenticatable, credentials: Credentials, force?: boolean): Promise<void>;
|
|
680
679
|
}
|
|
681
680
|
|
|
682
681
|
/**
|
|
683
|
-
* @plinthjs/auth — authentication
|
|
682
|
+
* @plinthjs/auth — authentication.
|
|
684
683
|
*
|
|
685
684
|
* The {@link Authenticatable} / {@link UserProvider} / {@link Guard} contracts, an in-memory
|
|
686
685
|
* {@link ArrayUserProvider} over {@link GenericUser}s (passwords verified through `@plinthjs/encryption`,
|
|
687
686
|
* re-hashed on login via {@link UserProvider.rehashPasswordIfRequired}), the {@link SessionGuard}
|
|
688
687
|
* (stateful, web — with `attemptWhen`, HTTP Basic, remember-me, and the logout variants), the
|
|
689
688
|
* {@link TokenGuard} (stateless, API), the {@link RequestGuard} behind
|
|
690
|
-
* {@link AuthManager.viaRequest}, an {@link AuthManager} that resolves named guards, the
|
|
689
|
+
* {@link AuthManager.viaRequest}, an {@link AuthManager} that resolves named guards, the conventional
|
|
691
690
|
* auth event classes dispatched through the structural {@link AuthEvents} seam, and the
|
|
692
691
|
* {@link authenticateSession} / {@link authenticateToken} / {@link redirectIfAuthenticated} /
|
|
693
692
|
* {@link requirePassword} HTTP middleware (with {@link getUser} to read the user off the request).
|
|
694
693
|
*/
|
|
695
|
-
/** The
|
|
694
|
+
/** The Plinth version this build of `auth` ships with. */
|
|
696
695
|
declare const VERSION = "0.1.0";
|
|
697
696
|
|
|
698
697
|
export { ArrayTokenRepository, type ArrayTokenRepositoryOptions, ArrayUserProvider, type AttemptCallback, Attempting, type AuthEvents, AuthManager, type Authenticatable, Authenticated, AuthenticationError, type Credentials, CurrentDeviceLogout, EmailVerifier, type EmailVerifierOptions, Failed, GenericUser, type Guard, type GuardFactory, Lockout, Login, Logout, type MustVerifyEmail, OtherDeviceLogout, PASSWORD_CONFIRMED_AT_SESSION_KEY, PASSWORD_HASH_SESSION_KEY, PasswordBroker, PasswordReset, type PasswordResetCallback, PasswordStatus, type PasswordUpdatable, Registered, type Rememberable, RequestGuard, type RequestUserResolver, type ResetCredentials, type ResetLinkSender, SessionGuard, type SessionGuardOptions, type StatefulGuard, TokenGuard, type TokenGuardOptions, type TokenRepository, type UserProvider, VERSION, Validated, type VerifiableUser, type VerificationSignature, Verified, authenticateSession, authenticateToken, confirmPassword, getUser, redirectIfAuthenticated, requirePassword };
|