@plinthjs/auth 0.1.0 → 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.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 Laravel `Illuminate\Contracts\Auth` interfaces. {@link Authenticatable}
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. The Laravel `Authenticatable` contract. */
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;
@@ -16,9 +16,9 @@ interface Authenticatable {
16
16
  /** The hashed password used to validate credentials. */
17
17
  getAuthPassword(): string;
18
18
  }
19
- /** Login credentials — typically `{ email, password }`. */
19
+ /** Login credentials - typically `{ email, password }`. */
20
20
  type Credentials = Record<string, unknown>;
21
- /** A user that supports "remember me" persistence (the Laravel remember-token methods). */
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;
@@ -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 — the persist seam used by
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 — the `Illuminate\Contracts\Events\Dispatcher` shape the auth
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. The Laravel `UserProvider` contract. */
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 Laravel 11+ `rehashPasswordIfRequired` provider method. Optional so
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. The Laravel `Guard` contract. */
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. The Laravel `StatefulGuard`. */
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. The Laravel `MustVerifyEmail` contract. */
97
+ /** A user whose email address can be verified. */
98
98
  interface MustVerifyEmail {
99
99
  /** The email address being verified. */
100
100
  getEmailForVerification(): string;
@@ -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 — an {@link Authenticatable} that also implements {@link MustVerifyEmail}. */
106
+ /** A verifiable user - an {@link Authenticatable} that also implements {@link MustVerifyEmail}. */
107
107
  type VerifiableUser = Authenticatable & MustVerifyEmail;
108
- /** A signed, expiring verification payload — what a verification link carries. */
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 — proves the link was issued for this exact address. */
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 — an already-verified user returns `true` without re-marking.
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 — the Laravel `Illuminate\Auth\Events` classes. Guards and brokers dispatch
150
- * these through the optional {@link AuthEvents} seam at the same moments Laravel fires them:
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
154
154
  * logout variants, and {@link Registered} / {@link Verified} / {@link PasswordReset} /
155
- * {@link Lockout} around the account lifecycle. Plain classes with readonly data — dispatchable
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 — the Laravel `Attempting` event. */
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 — handle with care). */
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 — handle with care). */
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 — the Laravel `Validated` event. */
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 Laravel `Login` event. */
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 Laravel `Authenticated` event. */
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 Laravel `Failed` event. */
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 Laravel `Logout` event. */
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 Laravel `CurrentDeviceLogout` event. */
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 Laravel `OtherDeviceLogout` event. */
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 Laravel `Registered` event. */
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 Laravel `Verified` event. */
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 Laravel `PasswordReset` event. */
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 Laravel `Lockout` event. Laravel carries the
293
- * HTTP request; Mason carries the credentials that triggered the lockout (dispatched by whatever
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,24 +302,24 @@ declare class Lockout {
302
302
  }
303
303
 
304
304
  /**
305
- * Session key holding the hash of the authenticated user's password — the Laravel
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 — runs after credential validation; all must return `true` to log in. */
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 — required only for the HTTP Basic helpers. */
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;
321
321
  }
322
- /** Session-backed, stateful guard. The Laravel `SessionGuard` equivalent. */
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 Laravel `attemptWhen`. The 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,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 Laravel
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 Laravel `logoutCurrentDevice`. Unlike
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 Laravel `logoutOtherDevices`.
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 — the same
370
- * session-password-hash mechanism Laravel's `AuthenticateSession` middleware uses; and
369
+ * checked by `authenticateSession` whose stored hash is now stale is logged out - the same
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 (the Laravel `queueRecallerCookie`
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;
@@ -382,7 +381,7 @@ declare class SessionGuard implements StatefulGuard {
382
381
  /** Whether the current user was authenticated via a remember-me recaller. The `viaRemember` equivalent. */
383
382
  viaRemember(): boolean;
384
383
  /**
385
- * Set how long (in minutes) issued recaller cookies should live — the `setRememberDuration`
384
+ * Set how long (in minutes) issued recaller cookies should live - the `setRememberDuration`
386
385
  * equivalent. The guard does not write cookies itself; read it back via
387
386
  * {@link SessionGuard.getRememberDuration} when turning a recaller value into a cookie.
388
387
  */
@@ -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 Laravel `basic`.
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 Laravel `onceBasic`.
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. The Laravel "remember me" persist.
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 (the Laravel `viaRemember` path). Returns the user, or `null`.
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. The Laravel `TokenGuard` equivalent. */
433
+ /** Stateless token guard. */
435
434
  declare class TokenGuard implements Guard {
436
435
  private readonly provider;
437
436
  private readonly request;
@@ -451,13 +450,13 @@ declare class TokenGuard implements Guard {
451
450
  private tokenForRequest;
452
451
  }
453
452
  /**
454
- * The user-resolver callback behind a {@link RequestGuard} — the closure passed to
453
+ * The user-resolver callback behind a {@link RequestGuard} - the closure passed to
455
454
  * `Auth::viaRequest`. Receives the request (and the provider, when one was registered) and returns
456
455
  * the authenticated user, or `null`/`undefined` for a guest.
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 Laravel `RequestGuard` (the engine behind
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 Laravel
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>;
@@ -494,7 +493,7 @@ declare class AuthManager {
494
493
  /** Register a guard factory under `name`. The `Auth::extend()` equivalent. */
495
494
  extend(name: string, factory: GuardFactory): this;
496
495
  /**
497
- * Register a closure-driven guard under `name` — the `Auth::viaRequest()` equivalent. The
496
+ * Register a closure-driven guard under `name` - the `Auth::viaRequest()` equivalent. The
498
497
  * callback receives the request (and `provider`, when given) and returns the authenticated user
499
498
  * or `null`; the manager builds a {@link RequestGuard} around it on every resolve.
500
499
  */
@@ -512,14 +511,14 @@ declare class AuthManager {
512
511
  }
513
512
 
514
513
  /**
515
- * Authentication middleware bridging `@plinthjs/auth` to `@plinthjs/http` — the Laravel `Authenticate`
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 (the Laravel `AuthenticateSession` middleware) so sessions die when the password
521
- * changes — e.g. after `SessionGuard.logoutOtherDevices`. {@link redirectIfAuthenticated} is the
522
- * `guest` middleware, and {@link requirePassword} / {@link confirmPassword} implement the Laravel
519
+ * in the session so sessions die when the password
520
+ * changes - e.g. after `SessionGuard.logoutOtherDevices`. {@link redirectIfAuthenticated} is 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
 
@@ -532,39 +531,39 @@ declare class AuthenticationError extends HttpException {
532
531
  /** The authenticated user attached by an authenticate middleware, or `undefined`. */
533
532
  declare function getUser(req: Request): Authenticatable | undefined;
534
533
  /**
535
- * Authenticate via the session — the web `auth` middleware. Requires the session middleware to have
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 Laravel `AuthenticateSession` password-hash check: the user's password hash is
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
  */
541
540
  declare function authenticateSession(provider: UserProvider): Middleware;
542
541
  /**
543
- * Authenticate via a request token — the stateless `auth:api` middleware. Resolves the user from a
542
+ * Authenticate via a request token - the stateless `auth:api` middleware. Resolves the user from a
544
543
  * bearer/query/input token and attaches it, or throws {@link AuthenticationError}.
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 Laravel
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 Laravel `RequirePassword` (`password.confirm`)
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 Laravel's
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 Laravel `Password::*` status constants. */
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. The Laravel `TokenRepositoryInterface`. */
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,16 +591,16 @@ 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 (the Laravel `expire`). Default `60`. */
594
+ /** Token lifetime in minutes. Default `60`. */
596
595
  expireMinutes?: number;
597
- /** Re-send throttle window in seconds (the Laravel `throttle`). Default `60`. */
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;
601
600
  /** Plaintext token generator. Default 40 random hex chars; tests may inject a fixed value. */
602
601
  createToken?: () => string;
603
602
  }
604
- /** In-memory {@link TokenRepository}, keyed by the user's auth identifier — ideal for tests/small apps. */
603
+ /** In-memory {@link TokenRepository}, keyed by the user's auth identifier - ideal for tests/small apps. */
605
604
  declare class ArrayTokenRepository implements TokenRepository {
606
605
  private readonly store;
607
606
  private readonly hasher;
@@ -646,7 +645,7 @@ declare class PasswordBroker {
646
645
  private lookupOnly;
647
646
  }
648
647
 
649
- /** A simple record-backed {@link Authenticatable}. The Laravel `GenericUser` equivalent. */
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;
@@ -661,7 +660,7 @@ declare class GenericUser implements Authenticatable, Rememberable, PasswordUpda
661
660
  /** Read an arbitrary attribute, used by providers to match credentials. */
662
661
  getAttribute(key: string): unknown;
663
662
  }
664
- /** An in-memory {@link UserProvider} over a fixed list of users — ideal for tests and small apps. */
663
+ /** An in-memory {@link UserProvider} over a fixed list of users - ideal for tests and small apps. */
665
664
  declare class ArrayUserProvider implements UserProvider {
666
665
  private readonly users;
667
666
  private readonly hasher;
@@ -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 Laravel `rehashPasswordIfRequired`. Persists through 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, the Laravel `Illuminate\Auth` equivalent.
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
- * (stateful, web — with `attemptWhen`, HTTP Basic, remember-me, and the logout variants), the
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 Laravel
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 Mason version this build of `auth` ships with. */
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 };