@plinthjs/auth 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +13 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +53 -53
- package/dist/index.d.ts +53 -53
- package/dist/index.js +13 -13
- package/dist/index.js.map +1 -1
- package/package.json +7 -7
package/dist/index.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { Session } from '@plinthjs/session';
|
|
|
3
3
|
import { Hasher } from '@plinthjs/encryption';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* Authentication contracts
|
|
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
|
*/
|
|
@@ -16,7 +16,7 @@ interface Authenticatable {
|
|
|
16
16
|
/** The hashed password used to validate credentials. */
|
|
17
17
|
getAuthPassword(): string;
|
|
18
18
|
}
|
|
19
|
-
/** Login credentials
|
|
19
|
+
/** Login credentials - typically `{ email, password }`. */
|
|
20
20
|
type Credentials = Record<string, unknown>;
|
|
21
21
|
/** A user that supports "remember me" persistence. */
|
|
22
22
|
interface Rememberable {
|
|
@@ -26,7 +26,7 @@ interface Rememberable {
|
|
|
26
26
|
setRememberToken(token: string): void;
|
|
27
27
|
}
|
|
28
28
|
/**
|
|
29
|
-
* A user whose password hash can be replaced
|
|
29
|
+
* A user whose password hash can be replaced - the persist seam used by
|
|
30
30
|
* {@link UserProvider.rehashPasswordIfRequired} (mirrors how remember tokens are persisted).
|
|
31
31
|
*/
|
|
32
32
|
interface PasswordUpdatable {
|
|
@@ -34,7 +34,7 @@ interface PasswordUpdatable {
|
|
|
34
34
|
setAuthPassword(hashed: string): void;
|
|
35
35
|
}
|
|
36
36
|
/**
|
|
37
|
-
* A structural event-dispatcher seam
|
|
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.
|
|
@@ -57,7 +57,7 @@ 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)
|
|
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>;
|
|
@@ -103,9 +103,9 @@ interface MustVerifyEmail {
|
|
|
103
103
|
/** Mark the email as verified (persist `email_verified_at`). */
|
|
104
104
|
markEmailAsVerified(): void | Promise<void>;
|
|
105
105
|
}
|
|
106
|
-
/** A verifiable user
|
|
106
|
+
/** A verifiable user - an {@link Authenticatable} that also implements {@link MustVerifyEmail}. */
|
|
107
107
|
type VerifiableUser = Authenticatable & MustVerifyEmail;
|
|
108
|
-
/** A signed, expiring verification payload
|
|
108
|
+
/** A signed, expiring verification payload - what a verification link carries. */
|
|
109
109
|
interface VerificationSignature {
|
|
110
110
|
/** Expiry as epoch milliseconds. */
|
|
111
111
|
expires: number;
|
|
@@ -130,7 +130,7 @@ declare class EmailVerifier {
|
|
|
130
130
|
private readonly now;
|
|
131
131
|
private readonly events;
|
|
132
132
|
constructor(options: EmailVerifierOptions);
|
|
133
|
-
/** A stable hash of the user's email
|
|
133
|
+
/** A stable hash of the user's email - proves the link was issued for this exact address. */
|
|
134
134
|
hashFor(user: VerifiableUser): string;
|
|
135
135
|
/** Build a signed, expiring verification payload for `user` (embed it in the verification URL). */
|
|
136
136
|
sign(user: VerifiableUser): VerificationSignature;
|
|
@@ -138,7 +138,7 @@ declare class EmailVerifier {
|
|
|
138
138
|
isValid(user: VerifiableUser, payload: VerificationSignature): boolean;
|
|
139
139
|
/**
|
|
140
140
|
* Verify a payload and mark the user verified. Returns `false` on a bad or expired signature;
|
|
141
|
-
* idempotent
|
|
141
|
+
* idempotent - an already-verified user returns `true` without re-marking.
|
|
142
142
|
*/
|
|
143
143
|
verify(user: VerifiableUser, payload: VerificationSignature): Promise<boolean>;
|
|
144
144
|
/** The HMAC binding the user id, email hash, and expiry. */
|
|
@@ -146,33 +146,33 @@ declare class EmailVerifier {
|
|
|
146
146
|
}
|
|
147
147
|
|
|
148
148
|
/**
|
|
149
|
-
* Authentication events
|
|
149
|
+
* Authentication events - the conventional API classes. Guards and brokers dispatch
|
|
150
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
|
|
154
154
|
* logout variants, and {@link Registered} / {@link Verified} / {@link PasswordReset} /
|
|
155
|
-
* {@link Lockout} around the account lifecycle. Plain classes with readonly data
|
|
155
|
+
* {@link Lockout} around the account lifecycle. Plain classes with readonly data - dispatchable
|
|
156
156
|
* through any dispatcher that takes an object.
|
|
157
157
|
*/
|
|
158
158
|
|
|
159
|
-
/** Fired before every credential attempt
|
|
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;
|
|
163
|
-
/** The credentials being attempted (includes the plaintext password
|
|
163
|
+
/** The credentials being attempted (includes the plaintext password - handle with care). */
|
|
164
164
|
readonly credentials: Credentials;
|
|
165
165
|
/** Whether the attempt asked for "remember me" persistence. */
|
|
166
166
|
readonly remember: boolean;
|
|
167
167
|
constructor(
|
|
168
168
|
/** The guard name the attempt runs on. */
|
|
169
169
|
guard: string,
|
|
170
|
-
/** The credentials being attempted (includes the plaintext password
|
|
170
|
+
/** The credentials being attempted (includes the plaintext password - handle with care). */
|
|
171
171
|
credentials: Credentials,
|
|
172
172
|
/** Whether the attempt asked for "remember me" persistence. */
|
|
173
173
|
remember?: boolean);
|
|
174
174
|
}
|
|
175
|
-
/** Fired when credentials validate against a user
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
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,7 +289,7 @@ declare class PasswordReset {
|
|
|
289
289
|
user: Authenticatable);
|
|
290
290
|
}
|
|
291
291
|
/**
|
|
292
|
-
* Fired when login attempts are rate-limited
|
|
292
|
+
* Fired when login attempts are rate-limited - the `Lockout` event. Conventional implementations carry the
|
|
293
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
|
*/
|
|
@@ -302,19 +302,19 @@ declare class Lockout {
|
|
|
302
302
|
}
|
|
303
303
|
|
|
304
304
|
/**
|
|
305
|
-
* Session key holding the hash of the authenticated user's password
|
|
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.
|
|
309
309
|
*/
|
|
310
310
|
declare const PASSWORD_HASH_SESSION_KEY = "auth.password_hash";
|
|
311
|
-
/** An `attemptWhen` callback
|
|
311
|
+
/** An `attemptWhen` callback - runs after credential validation; all must return `true` to log in. */
|
|
312
312
|
type AttemptCallback = (user: Authenticatable, guard: SessionGuard) => boolean | Promise<boolean>;
|
|
313
313
|
/** Options for {@link SessionGuard}. */
|
|
314
314
|
interface SessionGuardOptions {
|
|
315
315
|
/** Guard name carried on dispatched events. Default `'web'`. */
|
|
316
316
|
name?: string;
|
|
317
|
-
/** The current request
|
|
317
|
+
/** The current request - required only for the HTTP Basic helpers. */
|
|
318
318
|
request?: Request;
|
|
319
319
|
/** Optional event dispatcher; when unset no events are dispatched. */
|
|
320
320
|
events?: AuthEvents;
|
|
@@ -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
|
|
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,24 +349,24 @@ 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
|
|
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
|
|
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
|
|
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
|
-
* checked by `authenticateSession` whose stored hash is now stale is logged out
|
|
369
|
+
* checked by `authenticateSession` whose stored hash is now stale is logged out - the same
|
|
370
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
|
*
|
|
@@ -381,7 +381,7 @@ declare class SessionGuard implements StatefulGuard {
|
|
|
381
381
|
/** Whether the current user was authenticated via a remember-me recaller. The `viaRemember` equivalent. */
|
|
382
382
|
viaRemember(): boolean;
|
|
383
383
|
/**
|
|
384
|
-
* Set how long (in minutes) issued recaller cookies should live
|
|
384
|
+
* Set how long (in minutes) issued recaller cookies should live - the `setRememberDuration`
|
|
385
385
|
* equivalent. The guard does not write cookies itself; read it back via
|
|
386
386
|
* {@link SessionGuard.getRememberDuration} when turning a recaller value into a cookie.
|
|
387
387
|
*/
|
|
@@ -389,14 +389,14 @@ declare class SessionGuard implements StatefulGuard {
|
|
|
389
389
|
/** The "remember me" cookie lifetime in minutes. The `getRememberDuration` equivalent. */
|
|
390
390
|
getRememberDuration(): number;
|
|
391
391
|
/**
|
|
392
|
-
* Attempt HTTP Basic authentication, logging the user in for the session
|
|
392
|
+
* Attempt HTTP Basic authentication, logging the user in for the session - the `basic`.
|
|
393
393
|
* Resolves to `undefined` when already authenticated or when the `Authorization: Basic` header
|
|
394
394
|
* validates; otherwise resolves to a `401` challenge response (`WWW-Authenticate: Basic`).
|
|
395
395
|
* Requires the request (constructor option or {@link SessionGuard.setRequest}).
|
|
396
396
|
*/
|
|
397
397
|
basic(field?: string): Promise<Response | undefined>;
|
|
398
398
|
/**
|
|
399
|
-
* Perform a stateless HTTP Basic attempt (no session persistence)
|
|
399
|
+
* Perform a stateless HTTP Basic attempt (no session persistence) - the `onceBasic`.
|
|
400
400
|
* Resolves to `undefined` on success, or the `401` challenge response on failure.
|
|
401
401
|
*/
|
|
402
402
|
onceBasic(field?: string): Promise<Response | undefined>;
|
|
@@ -450,13 +450,13 @@ declare class TokenGuard implements Guard {
|
|
|
450
450
|
private tokenForRequest;
|
|
451
451
|
}
|
|
452
452
|
/**
|
|
453
|
-
* The user-resolver callback behind a {@link RequestGuard}
|
|
453
|
+
* The user-resolver callback behind a {@link RequestGuard} - the closure passed to
|
|
454
454
|
* `Auth::viaRequest`. Receives the request (and the provider, when one was registered) and returns
|
|
455
455
|
* the authenticated user, or `null`/`undefined` for a guest.
|
|
456
456
|
*/
|
|
457
457
|
type RequestUserResolver = (request: Request, provider?: UserProvider) => Authenticatable | null | undefined | Promise<Authenticatable | null | undefined>;
|
|
458
458
|
/**
|
|
459
|
-
* Closure-driven guard over the current request
|
|
459
|
+
* Closure-driven guard over the current request - the `RequestGuard` (the engine behind
|
|
460
460
|
* `Auth::viaRequest`). Resolves the user once per instance through the callback.
|
|
461
461
|
*/
|
|
462
462
|
declare class RequestGuard implements Guard {
|
|
@@ -471,7 +471,7 @@ declare class RequestGuard implements Guard {
|
|
|
471
471
|
guest(): Promise<boolean>;
|
|
472
472
|
id(): Promise<string | number | null>;
|
|
473
473
|
/**
|
|
474
|
-
* Whether the callback resolves a user for `credentials['request']`
|
|
474
|
+
* Whether the callback resolves a user for `credentials['request']` - the conventional
|
|
475
475
|
* `RequestGuard::validate`, which runs the resolver against the given request.
|
|
476
476
|
*/
|
|
477
477
|
validate(credentials: Credentials): Promise<boolean>;
|
|
@@ -493,7 +493,7 @@ declare class AuthManager {
|
|
|
493
493
|
/** Register a guard factory under `name`. The `Auth::extend()` equivalent. */
|
|
494
494
|
extend(name: string, factory: GuardFactory): this;
|
|
495
495
|
/**
|
|
496
|
-
* Register a closure-driven guard under `name`
|
|
496
|
+
* Register a closure-driven guard under `name` - the `Auth::viaRequest()` equivalent. The
|
|
497
497
|
* callback receives the request (and `provider`, when given) and returns the authenticated user
|
|
498
498
|
* or `null`; the manager builds a {@link RequestGuard} around it on every resolve.
|
|
499
499
|
*/
|
|
@@ -511,13 +511,13 @@ declare class AuthManager {
|
|
|
511
511
|
}
|
|
512
512
|
|
|
513
513
|
/**
|
|
514
|
-
* Authentication middleware bridging `@plinthjs/auth` to `@plinthjs/http`
|
|
514
|
+
* Authentication middleware bridging `@plinthjs/auth` to `@plinthjs/http` - the `Authenticate`
|
|
515
515
|
* (`auth`) middleware family. {@link authenticateSession} resolves the user from the session
|
|
516
516
|
* (requires the session middleware) and {@link authenticateToken} from a request token; both attach
|
|
517
517
|
* the user to the request (readable via {@link getUser}) or render a `401` via
|
|
518
518
|
* {@link AuthenticationError}. {@link authenticateSession} also keeps a hash of the user's password
|
|
519
519
|
* in the session so sessions die when the password
|
|
520
|
-
* changes
|
|
520
|
+
* changes - e.g. after `SessionGuard.logoutOtherDevices`. {@link redirectIfAuthenticated} is the
|
|
521
521
|
* `guest` middleware, and {@link requirePassword} / {@link confirmPassword} implement the conventional
|
|
522
522
|
* `password.confirm` flow over an `auth.password_confirmed_at` session timestamp.
|
|
523
523
|
*/
|
|
@@ -531,7 +531,7 @@ declare class AuthenticationError extends HttpException {
|
|
|
531
531
|
/** The authenticated user attached by an authenticate middleware, or `undefined`. */
|
|
532
532
|
declare function getUser(req: Request): Authenticatable | undefined;
|
|
533
533
|
/**
|
|
534
|
-
* Authenticate via the session
|
|
534
|
+
* Authenticate via the session - the web `auth` middleware. Requires the session middleware to have
|
|
535
535
|
* run; resolves the user from the session id and attaches it, or throws {@link AuthenticationError}.
|
|
536
536
|
* Also enforces the `AuthenticateSession` password-hash check: the user's password hash is
|
|
537
537
|
* stored in the session on first sight and compared on every request, so a password change (e.g.
|
|
@@ -539,31 +539,31 @@ declare function getUser(req: Request): Authenticatable | undefined;
|
|
|
539
539
|
*/
|
|
540
540
|
declare function authenticateSession(provider: UserProvider): Middleware;
|
|
541
541
|
/**
|
|
542
|
-
* Authenticate via a request token
|
|
542
|
+
* Authenticate via a request token - the stateless `auth:api` middleware. Resolves the user from a
|
|
543
543
|
* bearer/query/input token and attaches it, or throws {@link AuthenticationError}.
|
|
544
544
|
*/
|
|
545
545
|
declare function authenticateToken(provider: UserProvider, inputKey?: string): Middleware;
|
|
546
546
|
/**
|
|
547
|
-
* Redirect authenticated users away (e.g. from login/register pages)
|
|
547
|
+
* Redirect authenticated users away (e.g. from login/register pages) - the conventional
|
|
548
548
|
* `RedirectIfAuthenticated` (`guest`) middleware. Guests (and requests without a session) pass
|
|
549
549
|
* through; an authenticated session is redirected to `redirectTo`.
|
|
550
550
|
*/
|
|
551
551
|
declare function redirectIfAuthenticated(provider: UserProvider, redirectTo?: string): Middleware;
|
|
552
552
|
/**
|
|
553
|
-
* Require a recent password confirmation
|
|
553
|
+
* Require a recent password confirmation - the `RequirePassword` (`password.confirm`)
|
|
554
554
|
* middleware. Passes when the session's `auth.password_confirmed_at` timestamp is within
|
|
555
555
|
* `passwordTimeoutSeconds`; otherwise redirects to `redirectTo` (or renders `423 Locked` for JSON
|
|
556
556
|
* clients). Stamp the timestamp via {@link confirmPassword} after re-validating the password.
|
|
557
557
|
*/
|
|
558
558
|
declare function requirePassword(redirectTo?: string, passwordTimeoutSeconds?: number, now?: () => Date): Middleware;
|
|
559
559
|
/**
|
|
560
|
-
* Re-validate the user's password and stamp the session's confirmation timestamp
|
|
560
|
+
* Re-validate the user's password and stamp the session's confirmation timestamp - what the conventional
|
|
561
561
|
* `ConfirmablePasswordController` does for the `password.confirm` flow. Returns `false` (leaving
|
|
562
562
|
* the session untouched) when the password does not match.
|
|
563
563
|
*/
|
|
564
564
|
declare function confirmPassword(provider: UserProvider, session: Session, user: Authenticatable, password: string, now?: () => Date): Promise<boolean>;
|
|
565
565
|
|
|
566
|
-
/** The outcome of a broker operation
|
|
566
|
+
/** The outcome of a broker operation - the `Password::*` status constants. */
|
|
567
567
|
declare const PasswordStatus: {
|
|
568
568
|
readonly ResetLinkSent: "passwords.sent";
|
|
569
569
|
readonly PasswordReset: "passwords.reset";
|
|
@@ -600,7 +600,7 @@ interface ArrayTokenRepositoryOptions {
|
|
|
600
600
|
/** Plaintext token generator. Default 40 random hex chars; tests may inject a fixed value. */
|
|
601
601
|
createToken?: () => string;
|
|
602
602
|
}
|
|
603
|
-
/** In-memory {@link TokenRepository}, keyed by the user's auth identifier
|
|
603
|
+
/** In-memory {@link TokenRepository}, keyed by the user's auth identifier - ideal for tests/small apps. */
|
|
604
604
|
declare class ArrayTokenRepository implements TokenRepository {
|
|
605
605
|
private readonly store;
|
|
606
606
|
private readonly hasher;
|
|
@@ -660,7 +660,7 @@ declare class GenericUser implements Authenticatable, Rememberable, PasswordUpda
|
|
|
660
660
|
/** Read an arbitrary attribute, used by providers to match credentials. */
|
|
661
661
|
getAttribute(key: string): unknown;
|
|
662
662
|
}
|
|
663
|
-
/** An in-memory {@link UserProvider} over a fixed list of users
|
|
663
|
+
/** An in-memory {@link UserProvider} over a fixed list of users - ideal for tests and small apps. */
|
|
664
664
|
declare class ArrayUserProvider implements UserProvider {
|
|
665
665
|
private readonly users;
|
|
666
666
|
private readonly hasher;
|
|
@@ -672,19 +672,19 @@ declare class ArrayUserProvider implements UserProvider {
|
|
|
672
672
|
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
673
673
|
/**
|
|
674
674
|
* Re-hash and persist the user's password when its cost parameters no longer match the hasher's
|
|
675
|
-
* (or always, when `force` is set)
|
|
675
|
+
* (or always, when `force` is set) - the `rehashPasswordIfRequired`. Persists through the
|
|
676
676
|
* {@link PasswordUpdatable} seam, mirroring how remember tokens are persisted.
|
|
677
677
|
*/
|
|
678
678
|
rehashPasswordIfRequired(user: Authenticatable, credentials: Credentials, force?: boolean): Promise<void>;
|
|
679
679
|
}
|
|
680
680
|
|
|
681
681
|
/**
|
|
682
|
-
* @plinthjs/auth
|
|
682
|
+
* @plinthjs/auth - authentication.
|
|
683
683
|
*
|
|
684
684
|
* The {@link Authenticatable} / {@link UserProvider} / {@link Guard} contracts, an in-memory
|
|
685
685
|
* {@link ArrayUserProvider} over {@link GenericUser}s (passwords verified through `@plinthjs/encryption`,
|
|
686
686
|
* re-hashed on login via {@link UserProvider.rehashPasswordIfRequired}), the {@link SessionGuard}
|
|
687
|
-
* (stateful, web
|
|
687
|
+
* (stateful, web - with `attemptWhen`, HTTP Basic, remember-me, and the logout variants), the
|
|
688
688
|
* {@link TokenGuard} (stateless, API), the {@link RequestGuard} behind
|
|
689
689
|
* {@link AuthManager.viaRequest}, an {@link AuthManager} that resolves named guards, the conventional
|
|
690
690
|
* auth event classes dispatched through the structural {@link AuthEvents} seam, and the
|
package/dist/index.js
CHANGED
|
@@ -112,7 +112,7 @@ var EmailVerifier = class {
|
|
|
112
112
|
this.now = options.now ?? (() => /* @__PURE__ */ new Date());
|
|
113
113
|
this.events = options.events;
|
|
114
114
|
}
|
|
115
|
-
/** A stable hash of the user's email
|
|
115
|
+
/** A stable hash of the user's email - proves the link was issued for this exact address. */
|
|
116
116
|
hashFor(user) {
|
|
117
117
|
return createHash("sha256").update(user.getEmailForVerification()).digest("hex");
|
|
118
118
|
}
|
|
@@ -128,7 +128,7 @@ var EmailVerifier = class {
|
|
|
128
128
|
}
|
|
129
129
|
/**
|
|
130
130
|
* Verify a payload and mark the user verified. Returns `false` on a bad or expired signature;
|
|
131
|
-
* idempotent
|
|
131
|
+
* idempotent - an already-verified user returns `true` without re-marking.
|
|
132
132
|
*/
|
|
133
133
|
async verify(user, payload) {
|
|
134
134
|
if (!this.isValid(user, payload)) return false;
|
|
@@ -201,7 +201,7 @@ var SessionGuard = class {
|
|
|
201
201
|
return this.attemptWhen(credentials);
|
|
202
202
|
}
|
|
203
203
|
/**
|
|
204
|
-
* Attempt to authenticate with additional callbacks
|
|
204
|
+
* Attempt to authenticate with additional callbacks - the `attemptWhen`. The callbacks
|
|
205
205
|
* run after the credentials validate, receiving the user and this guard; every one must return
|
|
206
206
|
* `true` (a falsy result fails the attempt without logging the user in).
|
|
207
207
|
*/
|
|
@@ -238,7 +238,7 @@ var SessionGuard = class {
|
|
|
238
238
|
return user;
|
|
239
239
|
}
|
|
240
240
|
/**
|
|
241
|
-
* Log the current user out, cycling the remember token so every recaller dies
|
|
241
|
+
* Log the current user out, cycling the remember token so every recaller dies - the conventional
|
|
242
242
|
* `logout`. The session keys are cleared synchronously; the returned promise resolves once the
|
|
243
243
|
* token has been cycled through the provider and the `Logout` event dispatched.
|
|
244
244
|
*/
|
|
@@ -246,7 +246,7 @@ var SessionGuard = class {
|
|
|
246
246
|
return this.performLogout(true);
|
|
247
247
|
}
|
|
248
248
|
/**
|
|
249
|
-
* Log the current user out on this device only
|
|
249
|
+
* Log the current user out on this device only - the `logoutCurrentDevice`. Unlike
|
|
250
250
|
* {@link SessionGuard.logout} the remember token is *not* cycled, so other remembered devices
|
|
251
251
|
* stay logged in. Dispatches `CurrentDeviceLogout`.
|
|
252
252
|
*/
|
|
@@ -254,12 +254,12 @@ var SessionGuard = class {
|
|
|
254
254
|
return this.performLogout(false);
|
|
255
255
|
}
|
|
256
256
|
/**
|
|
257
|
-
* Invalidate the user's sessions on every other device
|
|
257
|
+
* Invalidate the user's sessions on every other device - the `logoutOtherDevices`.
|
|
258
258
|
* Validates `password` against the current user (throwing when it does not match), then:
|
|
259
259
|
*
|
|
260
260
|
* - force re-hashes the password through {@link UserProvider.rehashPasswordIfRequired} (when the
|
|
261
261
|
* provider supports it) and refreshes this session's stored password hash, so any session
|
|
262
|
-
* checked by `authenticateSession` whose stored hash is now stale is logged out
|
|
262
|
+
* checked by `authenticateSession` whose stored hash is now stale is logged out - the same
|
|
263
263
|
* session-password-hash mechanism the conventional `AuthenticateSession` middleware uses; and
|
|
264
264
|
* - cycles the remember token, killing every previously issued recaller cookie.
|
|
265
265
|
*
|
|
@@ -296,7 +296,7 @@ var SessionGuard = class {
|
|
|
296
296
|
return this.viaRememberFlag;
|
|
297
297
|
}
|
|
298
298
|
/**
|
|
299
|
-
* Set how long (in minutes) issued recaller cookies should live
|
|
299
|
+
* Set how long (in minutes) issued recaller cookies should live - the `setRememberDuration`
|
|
300
300
|
* equivalent. The guard does not write cookies itself; read it back via
|
|
301
301
|
* {@link SessionGuard.getRememberDuration} when turning a recaller value into a cookie.
|
|
302
302
|
*/
|
|
@@ -309,7 +309,7 @@ var SessionGuard = class {
|
|
|
309
309
|
return this.rememberDuration;
|
|
310
310
|
}
|
|
311
311
|
/**
|
|
312
|
-
* Attempt HTTP Basic authentication, logging the user in for the session
|
|
312
|
+
* Attempt HTTP Basic authentication, logging the user in for the session - the `basic`.
|
|
313
313
|
* Resolves to `undefined` when already authenticated or when the `Authorization: Basic` header
|
|
314
314
|
* validates; otherwise resolves to a `401` challenge response (`WWW-Authenticate: Basic`).
|
|
315
315
|
* Requires the request (constructor option or {@link SessionGuard.setRequest}).
|
|
@@ -321,7 +321,7 @@ var SessionGuard = class {
|
|
|
321
321
|
return failedBasicResponse();
|
|
322
322
|
}
|
|
323
323
|
/**
|
|
324
|
-
* Perform a stateless HTTP Basic attempt (no session persistence)
|
|
324
|
+
* Perform a stateless HTTP Basic attempt (no session persistence) - the `onceBasic`.
|
|
325
325
|
* Resolves to `undefined` on success, or the `401` challenge response on failure.
|
|
326
326
|
*/
|
|
327
327
|
async onceBasic(field = "email") {
|
|
@@ -509,7 +509,7 @@ var RequestGuard = class {
|
|
|
509
509
|
return user === null ? null : user.getAuthIdentifier();
|
|
510
510
|
}
|
|
511
511
|
/**
|
|
512
|
-
* Whether the callback resolves a user for `credentials['request']`
|
|
512
|
+
* Whether the callback resolves a user for `credentials['request']` - the conventional
|
|
513
513
|
* `RequestGuard::validate`, which runs the resolver against the given request.
|
|
514
514
|
*/
|
|
515
515
|
async validate(credentials) {
|
|
@@ -543,7 +543,7 @@ var AuthManager = class {
|
|
|
543
543
|
return this;
|
|
544
544
|
}
|
|
545
545
|
/**
|
|
546
|
-
* Register a closure-driven guard under `name`
|
|
546
|
+
* Register a closure-driven guard under `name` - the `Auth::viaRequest()` equivalent. The
|
|
547
547
|
* callback receives the request (and `provider`, when given) and returns the authenticated user
|
|
548
548
|
* or `null`; the manager builds a {@link RequestGuard} around it on every resolve.
|
|
549
549
|
*/
|
|
@@ -819,7 +819,7 @@ var ArrayUserProvider = class {
|
|
|
819
819
|
}
|
|
820
820
|
/**
|
|
821
821
|
* Re-hash and persist the user's password when its cost parameters no longer match the hasher's
|
|
822
|
-
* (or always, when `force` is set)
|
|
822
|
+
* (or always, when `force` is set) - the `rehashPasswordIfRequired`. Persists through the
|
|
823
823
|
* {@link PasswordUpdatable} seam, mirroring how remember tokens are persisted.
|
|
824
824
|
*/
|
|
825
825
|
rehashPasswordIfRequired(user, credentials, force = false) {
|