@nestjs/authentication 0.0.1 → 0.1.1

package/dist/jwt/token.service.js

@@ -28,7 +28,7 @@ import { JwtSigner } from './jwt-signer.service.js';
  * short-lived JWT access token, and an opaque refresh token that renews it.
  *
  * - `issue()` is to token clients what `SignInService.signIn()` is to
- *   browsers: a user with a confirmed authenticator gets no tokens without
+ *   browsers: with `mfa` configured, a user with a confirmed authenticator gets no tokens without
  *   a second factor.
  * - Access tokens are signed with the module's `accessToken` options, the
  *   same ones `JwtBearerProvider` verifies with by default.
@@ -38,13 +38,20 @@ import { JwtSigner } from './jwt-signer.service.js';
  *   concurrent presentations (`markRefreshTokenUsed()` is a compare-and-set), means two
  *   parties hold it: the whole family is revoked, and both have to sign in
  *   again (OAuth 2.0 Security BCP §4.14.2).
+ * - With `refreshToken: false`, there are none: `issue()` returns an access
+ *   token alone and stores nothing, `refresh()` and `revoke()` throw, and
+ *   `revokeAll()` does nothing. For a service that signs short-lived access
+ *   tokens and asks the client to sign in again; a service that only
+ *   verifies tokens can also leave `accessToken` out and give its
+ *   `JwtBearerProvider` the key (`super({ key })`).
  */
 let TokenService = TokenService_1 = class TokenService {
     constructor(storage, options, events = new AuthenticationEvents(), mfa = new MfaService(storage)) {
         this.storage = storage;
         this.events = events;
         this.mfa = mfa;
-        const refresh = options?.refreshToken ?? {};
+        this.refreshTokensOff = options?.refreshToken === false;
+        const refresh = options?.refreshToken || {};
         this.ttl = durationOr(refresh.ttl, '30d');
         this.absoluteTtl = durationOr(refresh.absoluteTtl, '90d');
         this.clock = refresh.now;
@@ -62,8 +69,10 @@ let TokenService = TokenService_1 = class TokenService {
     }
     /**
      * At sign-in: signs an access token and starts a refresh-token family.
+     * With `refreshToken: false`, returns the access token alone (typed by
+     * {@link IssuedTokens}), and stores nothing.
      *
-     * A user with a confirmed authenticator must send a second factor
+     * With `mfa` configured, a user with a confirmed authenticator must send a second factor
      * (`secondFactor`). Without one, `issue()` throws an
      * `AuthenticationError` whose body says `mfa_required`, and counts
      * nothing against the user's lockout; with a wrong one, `Invalid code`.
@@ -76,6 +85,16 @@ let TokenService = TokenService_1 = class TokenService {
         const verified = await this.checkSecondFactor(userId, secondFactor);
         const own = this.ownClaims(claims);
         const familyClaims = verified ? { ...own, amr: [...(own?.amr ?? []), 'mfa'] } : own;
+        if (this.refreshTokensOff) {
+            this.events.emit({
+                type: 'sign-in',
+                userId,
+                ...(method && { method }),
+                ...(verified && { mfa: 'verified' }),
+            });
+            const issued = { accessToken: signer.sign({ ...familyClaims, sub: userId }), expiresIn: this.expiresIn };
+            return issued;
+        }
         const familyExpiresAt = new Date(this.now() + this.absoluteTtl);
         const { token, record } = await this.create(userId, randomToken(16), familyExpiresAt, familyClaims);
         this.events.emit({
@@ -90,10 +109,12 @@ let TokenService = TokenService_1 = class TokenService {
     /**
      * Spends a refresh token: returns its successor, and an access token with
      * the family's claims. Throws {@link RefreshTokenError} (`invalid`,
-     * `expired`, `reused`), which a route answers with 401.
+     * `expired`, `reused`), which a route answers with 401. Throws without
+     * `accessToken`, and with `refreshToken: false`.
      */
     async refresh(refreshToken) {
         const signer = this.requireSigner();
+        this.requireRefreshTokens('refresh');
         if (typeof refreshToken !== 'string' || !TOKEN_PATTERN.test(refreshToken)) {
             throw new RefreshTokenError('invalid');
         }
@@ -131,9 +152,12 @@ let TokenService = TokenService_1 = class TokenService {
      * Signs out the client holding `refreshToken` (one device): revokes its
      * family. Spent tokens of the family work too. Resolves `false` for
      * unknown or malformed tokens, which a route should not reveal (RFC 7009
-     * §2.2).
+     * §2.2). Throws without `accessToken`, and with `refreshToken: false`, as
+     * `refresh()` does.
      */
     async revoke(refreshToken) {
+        this.requireSigner();
+        this.requireRefreshTokens('revoke');
         if (typeof refreshToken !== 'string' || !TOKEN_PATTERN.test(refreshToken)) {
             return false;
         }
@@ -146,9 +170,20 @@ let TokenService = TokenService_1 = class TokenService {
         this.events.emit({ type: 'sign-out', userId: record.userId, tokenFamilyId: record.familyId });
         return true;
     }
-    /** Signs the user out of every token client. Issued access tokens live until they expire. */
-    revokeAll(userId) {
-        return this.storage.refreshTokens.revokeUserRefreshTokens(userId);
+    /**
+     * Signs the user out of every token client. Issued access tokens live
+     * until they expire. Without `accessToken`, or with `refreshToken: false`,
+     * this app issues no refresh tokens, and there is nothing to revoke: the
+     * store is not read. Apps that
+     * share a user database configure `accessToken` in all of them if any of
+     * them issues tokens: otherwise this one's sign-outs everywhere leave the
+     * token clients of the others signed in.
+     */
+    async revokeAll(userId) {
+        if (!this.signer || this.refreshTokensOff) {
+            return;
+        }
+        await this.storage.refreshTokens.revokeUserRefreshTokens(userId);
     }
     /** `true` when a second factor was required and verified; throws when one is required and missing or wrong. */
     async checkSecondFactor(userId, secondFactor) {
@@ -171,6 +206,11 @@ let TokenService = TokenService_1 = class TokenService {
         const accessToken = signer.sign({ ...record.claims, sub: record.userId });
         return { accessToken, refreshToken, expiresIn: this.expiresIn };
     }
+    requireRefreshTokens(method) {
+        if (this.refreshTokensOff) {
+            throw new Error(`TokenService.${method}(): refresh tokens are disabled (\`refreshToken: false\` in the AuthenticationModule options)`);
+        }
+    }
     requireSigner() {
         if (!this.signer) {
             throw new Error('TokenService: configure `accessToken` (the signing key) in the AuthenticationModule options');

package/dist/magic-link/magic-link.service.d.ts

@@ -18,7 +18,9 @@ import type { MagicLinkOptions, MagicLinkRequest, CreatedMagicLink } from '../in
  * site's page must not start a link here), and sets an `HttpOnly`,
  * `SameSite=Lax` cookie, `__Host-magic_link_tx`, holding a secret that no
  * link carries; the store keys the link by the token and that secret
- * together, so `consume()` finds it only with the cookie. The `__Host-`
+ * together, so `consume()` finds it only with the cookie. The cookie holds
+ * the secrets of the last five links the browser requested, so a "resend"
+ * leaves the link before it usable there. The `__Host-`
  * prefix keeps sibling subdomains from planting one. So the link's page
  * must be on the same site as the API, as the session cookie requires
  * anyway, and a link forwarded to another browser or device, or read from
@@ -73,6 +75,7 @@ export declare class MagicLinkService {
     private feature;
     /** The generic answer: which refusal it was is told only by the event. */
     private refuse;
+    private pendingCookie;
     private txCookie;
     private setCookie;
     private now;

package/dist/magic-link/magic-link.service.js

@@ -37,6 +37,24 @@ function linkId(token, binding) {
 function hintOf(token) {
     return sha256(`nestjs-authentication magic-link hint ${token}`).slice(0, 12);
 }
+/**
+ * How many links a browser holds the secrets of: a "resend" leaves the
+ * links it requested before usable there, up to this many.
+ */
+const PENDING_LINKS = 5;
+const HINT_PATTERN = /^[\w-]{12}$/;
+/** The links in the cookie, newest first: `<hint>.<secret>`, joined by `~`. Anything else is dropped. */
+function readPending(value) {
+    return (value ?? '')
+        .split('~')
+        .map((pair) => pair.split('.'))
+        .filter(([hint, secret, ...rest]) => HINT_PATTERN.test(hint) && TOKEN_PATTERN.test(secret ?? '') && !rest.length)
+        .slice(0, PENDING_LINKS)
+        .map(([hint, secret]) => ({ hint, secret }));
+}
+function writePending(links) {
+    return links.map(({ hint, secret }) => `${hint}.${secret}`).join('~');
+}
 /**
  * Passwordless sign-in links: 256-bit single-use tokens, stored hashed,
  * short-lived, and bound to the browser that requested them.
@@ -49,7 +67,9 @@ function hintOf(token) {
  * site's page must not start a link here), and sets an `HttpOnly`,
  * `SameSite=Lax` cookie, `__Host-magic_link_tx`, holding a secret that no
  * link carries; the store keys the link by the token and that secret
- * together, so `consume()` finds it only with the cookie. The `__Host-`
+ * together, so `consume()` finds it only with the cookie. The cookie holds
+ * the secrets of the last five links the browser requested, so a "resend"
+ * leaves the link before it usable there. The `__Host-`
  * prefix keeps sibling subdomains from planting one. So the link's page
  * must be on the same site as the API, as the session cookie requires
  * anyway, and a link forwarded to another browser or device, or read from
@@ -106,7 +126,10 @@ let MagicLinkService = class MagicLinkService {
         });
         let cookie;
         if (binding) {
-            cookie = this.txCookie(`${hintOf(token)}.${binding}`, this.ttl / 1000);
+            // The links this browser requested before stay usable here, the oldest dropped past the cap.
+            const hint = hintOf(token);
+            const before = readPending(this.pendingCookie(this.scope.exchange()?.request)).filter((link) => link.hint !== hint);
+            cookie = this.txCookie(writePending([{ hint, secret: binding }, ...before].slice(0, PENDING_LINKS)), this.ttl / 1000);
             this.setCookie(cookie);
         }
         const url = new URL(options.url);
@@ -131,23 +154,27 @@ let MagicLinkService = class MagicLinkService {
             return this.refuse('unknown');
         }
         let binding;
+        let pending = [];
+        let link;
         if (this.bindToBrowser) {
-            const req = request ?? this.scope.exchange()?.request;
-            const [hint, secret] = (readCookie(firstHeader(req?.headers, 'cookie'), this.txCookieName) ?? '').split('.');
-            // The hint names the link this browser requested; anyone holding the link can compute it, so it
+            pending = readPending(this.pendingCookie(request ?? this.scope.exchange()?.request));
+            // The hint names a link this browser requested; anyone holding the link can compute it, so it
             // only tells a link opened elsewhere from a bad one. The secret, which no link carries, is what
             // the link is stored under: a leaked or forwarded link finds nothing without it. On a refusal
-            // here the cookie stays (it may be for a link this browser did request), and nothing is looked
+            // here the cookie stays (it holds the links this browser did request), and nothing is looked
             // up: a link was presented, not proved.
-            if (!hint || !secret || !TOKEN_PATTERN.test(secret) || !safeEqual(hint, hintOf(token))) {
+            const hint = hintOf(token);
+            link = pending.find((candidate) => safeEqual(candidate.hint, hint));
+            if (!link) {
                 this.events.emit({ type: 'magic-link-refused', reason: 'not-this-browser' });
                 throw new MagicLinkError();
             }
-            binding = secret;
+            binding = link.secret;
         }
         const record = await this.storage.magicLinks.consumeMagicLink(linkId(token, binding));
-        // This browser's link is settled either way: the cookie goes.
-        this.setCookie(this.txCookie('', 0));
+        // This link is settled either way: its secret goes, and the cookie with it when it held no other.
+        const rest = writePending(pending.filter((candidate) => candidate !== link));
+        this.setCookie(this.txCookie(rest, rest ? this.ttl / 1000 : 0));
         if (!record) {
             return this.refuse('unknown');
         }
@@ -185,6 +212,9 @@ let MagicLinkService = class MagicLinkService {
         this.events.emit({ type: 'magic-link-refused', reason, ...(email && { email }) });
         return null;
     }
+    pendingCookie(request) {
+        return readCookie(firstHeader(request?.headers, 'cookie'), this.txCookieName);
+    }
     txCookie(value, maxAge) {
         return serializeCookie(this.txCookieName, value, { ...this.options?.cookie, sameSite: 'lax', maxAge });
     }

package/dist/mfa/mfa.service.d.ts

@@ -37,6 +37,12 @@ export declare class MfaService {
     constructor(storage: AuthenticationStorage, options?: {
         mfa?: MfaOptions;
     }, events?: AuthenticationEvents);
+    /**
+     * Whether the user has a confirmed authenticator. Without the `mfa`
+     * option, MFA is off: `false`, without reading the store, even for a user
+     * who enrolled through another app sharing the user database. Every app
+     * that signs those users in must configure `mfa` if any of them does.
+     */
     isEnrolled(userId: string): Promise<boolean>;
     /**
      * Starts an enrollment. Throws {@link MfaAlreadyEnrolledError} when the user
@@ -97,7 +103,11 @@ export declare class MfaService {
     private seal;
     private open;
     private matchingStep;
-    /** Read at each call, never in the constructor: the registry locks once the module starts. */
+    /**
+     * Read at each call, never in the constructor: the registry locks once the
+     * module starts. Without the `mfa` option it throws before reading: MFA is
+     * off, and the production guard asks for no `MfaStore`.
+     */
     private get store();
     private get maxAttempts();
     private now;

package/dist/mfa/mfa.service.js

@@ -71,7 +71,7 @@ let MfaService = MfaService_1 = class MfaService {
         this.options = options?.mfa;
         this.lockoutWindow = durationOr(this.options?.lockoutWindow, '15m');
         if (!this.options) {
-            return; // MFA unused: isEnrolled() works, enrollment throws
+            return; // MFA off: isEnrolled() answers false, everything else throws, and the store is never read
         }
         if (this.options.encryption === undefined) {
             throw new Error('MFA: `mfa.encryption` is required. TOTP secrets cannot be hashed, so a store dump would let anyone ' +
@@ -86,7 +86,16 @@ let MfaService = MfaService_1 = class MfaService {
         requireIntegerOption(this.options.window, 'mfa.window', { min: 0, max: 10 });
         requireIntegerOption(this.options.recoveryCodes, 'mfa.recoveryCodes', { min: 1 });
     }
+    /**
+     * Whether the user has a confirmed authenticator. Without the `mfa`
+     * option, MFA is off: `false`, without reading the store, even for a user
+     * who enrolled through another app sharing the user database. Every app
+     * that signs those users in must configure `mfa` if any of them does.
+     */
     async isEnrolled(userId) {
+        if (!this.options) {
+            return false;
+        }
         // Truthy, not `=== true`: a store that reads the flag back as `1` must not skip the second factor.
         return !!(await this.store.getTotp(userId))?.confirmed;
     }
@@ -211,7 +220,7 @@ let MfaService = MfaService_1 = class MfaService {
         this.failed(userId, 'recovery-code', attempt);
         return false;
     }
-    remainingRecoveryCodes(userId) {
+    async remainingRecoveryCodes(userId) {
         return this.store.countRecoveryCodes(userId);
     }
     /**
@@ -271,15 +280,9 @@ let MfaService = MfaService_1 = class MfaService {
         this.events.emit({ type: 'mfa-failed', userId, method, failures: attempt, locked: attempt >= this.maxAttempts });
     }
     seal(userId, secret) {
-        if (!this.options) {
-            throw new Error('MFA is not configured: add `mfa: { encryption: … }` to the AuthenticationModule options');
-        }
         return this.cipher ? this.cipher.encrypt(secret, `totp.${userId}`) : secret;
     }
     open(userId, stored) {
-        if (!this.options) {
-            throw new Error('MFA is not configured: add `mfa: { encryption: … }` to the AuthenticationModule options');
-        }
         if (!this.cipher) {
             return { plaintext: stored, needsReencrypt: false };
         }
@@ -322,8 +325,15 @@ let MfaService = MfaService_1 = class MfaService {
         }
         return found;
     }
-    /** Read at each call, never in the constructor: the registry locks once the module starts. */
+    /**
+     * Read at each call, never in the constructor: the registry locks once the
+     * module starts. Without the `mfa` option it throws before reading: MFA is
+     * off, and the production guard asks for no `MfaStore`.
+     */
     get store() {
+        if (!this.options) {
+            throw new Error('MFA is not configured: add `mfa: { encryption: … }` to the AuthenticationModule options');
+        }
         return this.storage.mfa;
     }
     get maxAttempts() {

package/dist/oidc/oidc.client.d.ts

@@ -5,7 +5,7 @@ import type { OidcTransaction, OidcClientOptions } from '../interfaces/oidc.inte
  * PKCE (S256), `state` and `nonce`.
  *
  * Checks, in order: IdP error, `iss` response parameter (RFC 9207, mix-up
- * defence), token response shape, ID token signature (JWKS, RS256/ES256,
+ * defence), token response shape, ID token signature (JWKS, RS256/ES256 by default,
  * alg/key binding), `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, and that
  * userinfo's `sub` matches the ID token's (OIDC Core §5.3.2).
  */

package/dist/oidc/oidc.client.js

@@ -29,7 +29,7 @@ function assertSecureUrl(value, what) {
  * PKCE (S256), `state` and `nonce`.
  *
  * Checks, in order: IdP error, `iss` response parameter (RFC 9207, mix-up
- * defence), token response shape, ID token signature (JWKS, RS256/ES256,
+ * defence), token response shape, ID token signature (JWKS, RS256/ES256 by default,
  * alg/key binding), `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, and that
  * userinfo's `sub` matches the ID token's (OIDC Core §5.3.2).
  */

package/dist/oidc/oidc.service.d.ts

@@ -82,6 +82,7 @@ export declare class OidcService {
     private feature;
     /** A fully signed-in session (second factor done, if any) on this request. */
     private currentSession;
+    /** `oidc.callbackUrl` for this request, with the provider's name in it. */
     private callbackUrl;
     private txCookie;
     private now;

package/dist/oidc/oidc.service.js

@@ -79,7 +79,9 @@ let OidcService = class OidcService {
         this.clients = new Map();
         this.options = options?.oidc;
         if (this.options) {
-            assertCallbackUrl(this.options.callbackUrl);
+            if (typeof this.options.callbackUrl !== 'function') {
+                assertCallbackUrl(this.options.callbackUrl);
+            }
             assertProviderCredentials(this.options.providers);
         }
         this.transactionTtl = durationOr(this.options?.transactionTtl, '10m');
@@ -120,7 +122,7 @@ let OidcService = class OidcService {
             linking = { userId: session.userId, sessionId: session.id };
         }
         const { url, transaction, binding } = await this.client(provider)
-            .authorizationRequest(this.callbackUrl(provider), safeRedirectPath(redirectTo), this.transactionTtl)
+            .authorizationRequest(await this.callbackUrl(provider, req), safeRedirectPath(redirectTo), this.transactionTtl)
             .catch(toHttp);
         await this.storage.oidcStates.saveOidcState({ ...transaction, ...(linking && { link: linking }) });
         return this.redirect(exchange?.response, url, [this.txCookie(binding, this.transactionTtl / 1000)]);
@@ -146,7 +148,10 @@ let OidcService = class OidcService {
         if (!transaction || transaction.provider !== provider || hasExpired(transaction.expiresAt, this.now())) {
             throw new BadRequestException('unknown or expired login');
         }
-        const result = await this.client(provider).callback(query, transaction, this.callbackUrl(provider)).catch(toHttp);
+        // Asked again rather than stored with the login: the cookie keeps the callback on the login's host,
+        // and a function that answers otherwise gets the code refused by the provider, not accepted.
+        const callbackUrl = await this.callbackUrl(provider, req);
+        const result = await this.client(provider).callback(query, transaction, callbackUrl).catch(toHttp);
         const location = transaction.redirectTo ?? options.redirectAfterLogin ?? '/';
         if (transaction.link) {
             // The session that asked to link must still be the one on this browser.
@@ -194,8 +199,14 @@ let OidcService = class OidcService {
         const session = await this.sessions.validate(this.sessions.tokenFrom(request));
         return session && session.mfa !== 'pending' ? session : null;
     }
-    callbackUrl(provider) {
-        return this.feature().options.callbackUrl.replaceAll(':provider', encodeURIComponent(provider));
+    /** `oidc.callbackUrl` for this request, with the provider's name in it. */
+    async callbackUrl(provider, request) {
+        const { callbackUrl } = this.feature().options;
+        const url = typeof callbackUrl === 'function' ? await callbackUrl(request) : callbackUrl;
+        if (typeof callbackUrl === 'function') {
+            assertCallbackUrl(url, 'the `oidc.callbackUrl` function must return');
+        }
+        return url.replaceAll(':provider', encodeURIComponent(provider));
     }
     txCookie(value, maxAge) {
         return serializeCookie(this.txCookieName, value, { ...this.options?.cookie, sameSite: 'lax', maxAge });
@@ -216,8 +227,11 @@ OidcService = __decorate([
         HttpAdapterHost])
 ], OidcService);
 export { OidcService };
-/** `oidc.callbackUrl`, checked at startup: an absolute http(s) URL. */
-function assertCallbackUrl(value) {
+/**
+ * `oidc.callbackUrl`, checked at startup (or each URL its function returns,
+ * when it returns it): an absolute http(s) URL.
+ */
+function assertCallbackUrl(value, must = '`oidc.callbackUrl` must be') {
     let url;
     try {
         url = typeof value === 'string' ? new URL(value.replaceAll(':provider', 'provider')) : undefined;
@@ -226,7 +240,7 @@ function assertCallbackUrl(value) {
         url = undefined;
     }
     if (!url || (url.protocol !== 'https:' && url.protocol !== 'http:')) {
-        throw new Error('OidcService: `oidc.callbackUrl` must be the absolute URL of your callback route, with `:provider` where the ' +
+        throw new Error(`OidcService: ${must} the absolute URL of your callback route, with \`:provider\` where the ` +
             `provider's name goes, e.g. 'https://app.example.com/auth/oidc/:provider/callback'. Got ${JSON.stringify(value)}.`);
     }
 }

package/dist/session/in-memory-session.store.d.ts

@@ -15,6 +15,7 @@ export declare class InMemorySessionStore implements SessionStore {
         lastActiveAt: Date;
         mfa?: import("../index.js").MfaState;
         metadata?: Record<string, unknown>;
+        extra?: import("../index.js").SessionExtra;
     } | undefined>;
     createSession(record: SessionRecord): Promise<void>;
     touchSession(id: string, lastActiveAt: Date): Promise<void>;
@@ -27,6 +28,7 @@ export declare class InMemorySessionStore implements SessionStore {
         lastActiveAt: Date;
         mfa?: import("../index.js").MfaState;
         metadata?: Record<string, unknown>;
+        extra?: import("../index.js").SessionExtra;
     }[]>;
     deleteUserSessions(userId: string): Promise<void>;
     private sweep;

package/dist/session/in-memory-session.store.js

@@ -20,7 +20,9 @@ let InMemorySessionStore = class InMemorySessionStore {
         return record && { ...record };
     }
     async createSession(record) {
-        this.sessions.set(record.id, { ...record });
+        // `extra` is read with a session, never stored.
+        const { extra: _, ...stored } = record;
+        this.sessions.set(record.id, stored);
         // The new session's own clock, so tests with a fake one agree.
         if (this.sessions.size >= this.sweepAt) {
             this.sweep(record.lastActiveAt.getTime());

package/dist/session/session-cookie.provider.d.ts

@@ -18,6 +18,19 @@ import { SessionService } from './session.service.js';
  * }
  * ```
  *
+ * A store whose `getSession()` reads the user in the same query (a `JOIN`)
+ * can hand it over in `session.extra`, typed by `sessionExtra` on
+ * `AuthenticationTypes`, which saves the second read on every request:
+ *
+ * ```ts
+ * validate(session: SessionRecord) {
+ *   return session.extra?.user ?? null;
+ * }
+ * ```
+ *
+ * `extra` stays out of the result: `@CurrentSession()`, `request.session`
+ * and `AuthenticationContext.session` get the session without it.
+ *
  * A missing, stale or unknown cookie counts as "no credentials" rather than
  * a 401: browsers keep sending them, and optional routes should keep
  * working. So does the cookie on a cross-origin POST, PUT, PATCH or DELETE
@@ -28,7 +41,10 @@ import { SessionService } from './session.service.js';
  */
 export declare abstract class SessionCookieProvider<TUser> extends AuthenticationProvider<TUser, SessionRecord> {
     protected readonly sessions: SessionService;
-    /** Loads the user for a live session; `null` for deleted or banned users, which ends the session. */
+    /**
+     * Loads the user for a live session; `null` for deleted or banned users, which ends the session.
+     * `session.extra` is what the store read with the session, if anything.
+     */
     protected abstract validate(session: SessionRecord): TUser | null | undefined | Promise<TUser | null | undefined>;
     authenticate(context: ExecutionContext): Promise<AuthenticationResult<TUser, SessionRecord> | null>;
     /** @internal An instance created with `new` was not property-injected. */

package/dist/session/session-cookie.provider.js

@@ -26,6 +26,19 @@ import { SessionService } from './session.service.js';
  * }
  * ```
  *
+ * A store whose `getSession()` reads the user in the same query (a `JOIN`)
+ * can hand it over in `session.extra`, typed by `sessionExtra` on
+ * `AuthenticationTypes`, which saves the second read on every request:
+ *
+ * ```ts
+ * validate(session: SessionRecord) {
+ *   return session.extra?.user ?? null;
+ * }
+ * ```
+ *
+ * `extra` stays out of the result: `@CurrentSession()`, `request.session`
+ * and `AuthenticationContext.session` get the session without it.
+ *
  * A missing, stale or unknown cookie counts as "no credentials" rather than
  * a 401: browsers keep sending them, and optional routes should keep
  * working. So does the cookie on a cross-origin POST, PUT, PATCH or DELETE
@@ -45,7 +58,9 @@ export class SessionCookieProvider extends AuthenticationProvider {
             await this.sessions.discard(session.id);
             return null;
         }
-        return { user, session, mfa: session.mfa };
+        // What the store joined (often the user's row, password hash and all) is for `validate()` only.
+        const { extra: _, ...stored } = session;
+        return { user, session: stored, mfa: session.mfa };
     }
     /** @internal An instance created with `new` was not property-injected. */
     [PROVIDER_INIT](resolve) {

package/dist/session/session.service.d.ts

@@ -18,6 +18,7 @@ type RequestHeaders = Record<string, string | string[] | undefined>;
 export declare class SessionService {
     private readonly storage;
     private readonly events;
+    private static readonly logger;
     private readonly options;
     private readonly absoluteTtl;
     private readonly pendingTtl;
@@ -25,6 +26,8 @@ export declare class SessionService {
     private readonly touchInterval;
     private readonly cookieName;
     private readonly trustedOrigins;
+    /** Touches failed since the last successful one: a spell of failures logs one warning, not one per request. */
+    private failedTouches;
     constructor(storage: AuthenticationStorage, options?: {
         session?: SessionOptions;
         mfa?: {
@@ -43,7 +46,11 @@ export declare class SessionService {
         metadata?: Record<string, unknown>;
         replacing?: string;
     }): Promise<IssuedSession>;
-    /** The live session for a token, sliding its idle timeout. */
+    /**
+     * The live session for a token, sliding its idle timeout. Sliding is
+     * best-effort: when the store fails to record the activity, the session
+     * is still returned, as read (see `SessionStore.touchSession()`).
+     */
     validate(token: string | undefined): Promise<SessionRecord | null>;
     /**
      * Replaces the session id, keeping its user and absolute expiry. For
@@ -53,7 +60,8 @@ export declare class SessionService {
      * `absoluteTtl` from its creation, in place of its `mfa.pendingTtl`.
      * Resolves `null` when the session was gone by the time it was replaced:
      * revoked (a sign-out everywhere, a password reset) or rotated by another
-     * request, which leaves no new session behind.
+     * request, which leaves no new session behind. The session's `extra` is
+     * not carried over.
      */
     rotate(session: SessionRecord, changes?: Pick<Partial<SessionRecord>, 'mfa' | 'metadata'>): Promise<IssuedSession | null>;
     /**
@@ -90,6 +98,14 @@ export declare class SessionService {
     clearCookie(): string;
     /** @internal Deletes a session by id, for sessions whose user is gone. */
     discard(sessionId: string): Promise<void>;
+    /**
+     * Records activity, best-effort: the session was read live, so a failed write (a lock timeout,
+     * a read-only replica) does not fail the request, and the session keeps the idle deadline the
+     * store still has. Every failure is published as `session-touch-failed`; the log gets one warning
+     * per spell of failures (the first), then one line once a touch succeeds again, with how many
+     * failed in between.
+     */
+    private touch;
     private isLive;
     private issue;
     private now;