@oneunit/auth 2.0.0 → 2.0.1

package/src/auth.ts

@@ -19,6 +19,7 @@ import type {
   RBACOptions,
   RefreshRecord,
   RefreshStore,
+  SessionStore,
   RequestLike,
   RoleDefinition,
   Secret,
@@ -58,6 +59,10 @@ const RESERVED_CLAIMS: ReadonlySet<string> = new Set([
   "iat",
   "nbf",
   "jti",
+  // Session version. Written by the library from the SessionStore and compared
+  // on every verification, so it must not be settable by an extractor or by
+  // additionalClaims.
+  "sv",
 ]);
 
 type ClaimExtractor = (user: UserRecord) => unknown;
@@ -74,6 +79,7 @@ export class Auth {
   trustUserPermissions: boolean;
   userStore: UserStore | null;
   refreshStore: RefreshStore;
+  sessionStore?: SessionStore;
   onLogin: AuthOptions["onLogin"];
   onLink: AuthOptions["onLink"];
   rbac: RBAC;
@@ -102,6 +108,7 @@ export class Auth {
 
     this.userStore = options.userStore ?? null;
     this.refreshStore = options.refreshStore ?? createMemoryRefreshStore();
+    this.sessionStore = options.sessionStore;
     this.onLogin = options.onLogin;
     this.onLink = options.onLink;
 
@@ -180,6 +187,13 @@ export class Auth {
       ...additional,
     };
 
+    // Only stamped when a SessionStore is configured, so tokens are unchanged
+    // for the many deployments that do not opt into session revocation.
+    const sessionVersion = await this.currentSessionVersion(user.id);
+    if (sessionVersion !== undefined) {
+      payload.sv = sessionVersion;
+    }
+
     const subject = String(user.id);
 
     const accessToken = encodeAccessToken(payload, this.secret, {
@@ -194,7 +208,7 @@ export class Auth {
     if (options.refresh !== false) {
       const jwtid = randomToken(16);
       refreshToken = encodeRefreshToken(
-        { sub: subject, userId: user.id, roles },
+        { sub: subject, userId: user.id, roles, ...(sessionVersion !== undefined && { sv: sessionVersion }) },
         this.refreshSecret,
         {
           audience: this.audience,
@@ -297,6 +311,10 @@ export class Auth {
       clockTolerance: options.clockTolerance ?? this.clockTolerance,
     });
 
+    // Checked after the signature, so `sv` is a claim this library signed
+    // rather than a number the caller supplied.
+    await this.assertSessionActive(claims);
+
     // A refresh token is signed with the same secret and would otherwise verify
     // as a bearer credential, turning a 7-day token into a 7-day access token.
     if (claims.typ === "refresh" && options.acceptTokenType !== "refresh") {
@@ -334,8 +352,16 @@ export class Auth {
       return cookies[cookieName];
     }
 
-    const query = collectQuery(req);
-    return query.access_token ?? query.token ?? null;
+    // Opt-in only. Reading the query string by default put the token in every
+    // access log, proxy log, browser history entry, and outgoing Referer header
+    // on every request, which is a far wider blast radius than a header or a
+    // cookie.
+    if (options.query) {
+      const query = collectQuery(req);
+      return query.access_token ?? query.token ?? null;
+    }
+
+    return null;
   }
 
   async refresh(refreshToken: string, options: LoginOptions = {}): Promise<LoginResult> {
@@ -354,7 +380,18 @@ export class Auth {
       throw new UnauthorizedError("Not a refresh token");
     }
 
-    if (claims.jti) {
+    if (!claims.jti) {
+      // A refresh token without a jti has no store entry, so there is nothing
+      // to consume and nothing to revoke: it would stay valid until it expired
+      // and would survive logout entirely. encodeRefreshToken is public, so
+      // this is reachable by anyone holding the secret; refuse it rather than
+      // mint a session that no revocation list can ever reach.
+      throw new UnauthorizedError(
+        "Refresh token is missing a jti and cannot be revoked; mint refresh tokens through login()",
+      );
+    }
+
+    {
       // Consume the token in a single store operation when the store supports
       // it, so two concurrent refreshes cannot both pass the validity check.
       if (typeof this.refreshStore.consume === "function") {
@@ -376,6 +413,12 @@ export class Auth {
       id: (claims.userId ?? claims.sub) as string | number,
       roles: claims.roles,
     };
+
+    // Before the store is touched. A revoked session must not be able to
+    // consume its refresh token and mint a fresh access token, which would
+    // make revokeAllSessions pointless for anyone holding a stolen one.
+    await this.assertSessionActive(claims);
+
     if (this.userStore?.findById) {
       user = await this.userStore.findById(user.id) ?? user;
     }
@@ -395,6 +438,57 @@ export class Auth {
     }
   }
 
+  /**
+   * The user's current session version, or undefined when no SessionStore is
+   * configured and the feature is therefore off.
+   */
+  private async currentSessionVersion(userId: string | number): Promise<number | undefined> {
+    if (!this.sessionStore) {
+      return undefined;
+    }
+    const version = await this.sessionStore.getVersion(userId);
+    return version ?? 0;
+  }
+
+  /**
+   * Rejects a token whose session version has been superseded. A token minted
+   * before any SessionStore existed carries no `sv`, and is treated as
+   * version 0 so that enabling the feature does not invalidate sessions that
+   * were already in flight.
+   */
+  private async assertSessionActive(claims: JwtPayload): Promise<void> {
+    if (!this.sessionStore) {
+      return;
+    }
+    const current = await this.currentSessionVersion(claims.userId ?? claims.sub ?? "");
+    const presented = typeof claims.sv === "number" ? claims.sv : 0;
+    if (presented !== current) {
+      throw new UnauthorizedError("Session has been revoked");
+    }
+  }
+
+  /**
+   * Invalidates every session currently issued to a user, across all devices.
+   * Returns false when no SessionStore is configured, since there is then
+   * nothing to bump and the call would silently do nothing.
+   */
+  async revokeAllSessions(userId: string | number): Promise<boolean> {
+    if (!this.sessionStore?.bumpVersion) {
+      return false;
+    }
+    await this.sessionStore.bumpVersion(userId);
+    return true;
+  }
+
+  /** Invalidates a single session by the jti of its refresh token. */
+  async revokeSession(jti: string): Promise<boolean> {
+    if (!this.sessionStore?.revokeSession) {
+      return false;
+    }
+    await this.sessionStore.revokeSession(jti);
+    return true;
+  }
+
   async revoke(refreshToken?: string | null): Promise<boolean> {
     if (!refreshToken) {
       return false;

package/src/password.ts

@@ -26,6 +26,74 @@ const DEFAULT_BLOCK_SIZE = 8;
 const DEFAULT_PARALLELISM = 1;
 const PREFIX = "scrypt";
 
+// Every one of these values can be attacker-influenced when they come out of a
+// stored hash string: N and r decide the memory block, p and keyLength decide
+// the CPU time and output size, and none of them are covered by the 32MB
+// maxmem guard Node applies by default. A stored hash of
+// "scrypt$16384$8$1$1073741824$..." costs ~25s of CPU on a default
+// configuration, on every login attempt, and costs the attacker one string to
+// write. So parameters are bounded on the way in as well as on the way out, and
+// a hash asking for more work than this is treated as malformed rather than
+// computed.
+const MIN_COST = 2;
+const MAX_COST = 1 << 20;
+const MIN_BLOCK_SIZE = 1;
+const MAX_BLOCK_SIZE = 32;
+const MIN_PARALLELISM = 1;
+const MAX_PARALLELISM = 16;
+const MIN_KEY_LENGTH = 16;
+const MAX_KEY_LENGTH = 128;
+const MAX_SALT_BYTES = 64;
+
+// The real constraint is the product, not N on its own: scrypt needs roughly
+// 128 * N * r bytes, and Node rejects anything at or above 32MB. Capping N * r
+// at 24MB of working memory therefore accepts every configuration Node can
+// actually run while rejecting the ones that would throw at the crypto layer.
+// The default is 16MB (16384 * 8), leaving 50% headroom to raise N, r, or both.
+const MAX_WORK = (24 * 1024 * 1024) / 128;
+
+// The floor matters as much as the ceiling. A stored hash asking for a tiny
+// amount of work (N=2, r=1) is a downgrade attack in slow motion: it verifies
+// instantly, so an attacker able to write a hash row can brute-force passwords
+// against it at enormous speed. 2^12 is three orders of magnitude below the
+// default and still weaker than OWASP's recommended N=2^17, r=8.
+const MIN_WORK = 1 << 12;
+
+interface ScryptParams {
+  N: number;
+  r: number;
+  p: number;
+  keyLength: number;
+}
+
+/**
+ * Returns null when any parameter is non-integer or outside its bounds, which
+ * is what makes an over-budget stored hash uncomputable rather than slow.
+ */
+function parseBoundedParams(n: number, r: number, p: number, keyLength: number): ScryptParams | null {
+  const values = [n, r, p, keyLength];
+  if (!values.every((value) => Number.isInteger(value))) {
+    return null;
+  }
+  if (n < MIN_COST || n > MAX_COST || (n & (n - 1)) !== 0) {
+    // scrypt requires N to be a power of two greater than one.
+    return null;
+  }
+  if (r < MIN_BLOCK_SIZE || r > MAX_BLOCK_SIZE) {
+    return null;
+  }
+  if (n * r > MAX_WORK || n * r < MIN_WORK) {
+    return null;
+  }
+  if (p < MIN_PARALLELISM || p > MAX_PARALLELISM) {
+    return null;
+  }
+  if (keyLength < MIN_KEY_LENGTH || keyLength > MAX_KEY_LENGTH) {
+    return null;
+  }
+  return { N: n, r, p, keyLength };
+}
+
 function toBuffer(value: string | Buffer): Buffer {
   return Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8");
 }
@@ -36,12 +104,39 @@ export async function hashPassword(password: string, options: PasswordOptions =
   }
 
   const saltBytes = options.saltBytes ?? DEFAULT_SALT_BYTES;
-  const keyLength = options.keyLength ?? DEFAULT_KEY_LENGTH;
-  const N = options.cost ?? DEFAULT_COST;
-  const r = options.blockSize ?? DEFAULT_BLOCK_SIZE;
-  const p = options.parallelism ?? DEFAULT_PARALLELISM;
+  const params = parseBoundedParams(
+    options.cost ?? DEFAULT_COST,
+    options.blockSize ?? DEFAULT_BLOCK_SIZE,
+    options.parallelism ?? DEFAULT_PARALLELISM,
+    options.keyLength ?? DEFAULT_KEY_LENGTH,
+  );
+  if (!params) {
+    throw new ValidationError(
+      "Password hashing parameters are out of range: N must be a power of two in " +
+        `[${MIN_COST}, ${MAX_COST}], blockSize in [${MIN_BLOCK_SIZE}, ${MAX_BLOCK_SIZE}], ` +
+        `parallelism in [${MIN_PARALLELISM}, ${MAX_PARALLELISM}], keyLength in ` +
+        `[${MIN_KEY_LENGTH}, ${MAX_KEY_LENGTH}], and N * blockSize must be in ` +
+        `[${MIN_WORK}, ${MAX_WORK}] (24MB of working memory)`,
+    );
+  }
+  if (saltBytes < 8 || saltBytes > MAX_SALT_BYTES) {
+    throw new ValidationError(`saltBytes must be in [8, ${MAX_SALT_BYTES}]`);
+  }
+  const { N, r, p, keyLength } = params;
   const salt = options.salt ? toBuffer(options.salt) : randomBytes(saltBytes);
-  const key = await scrypt(password, salt, keyLength, { N, r, p });
+
+  // The bounds above are a cheap pre-filter, not a complete model of what
+  // OpenSSL accepts. Node also throws synchronously for some in-range
+  // combinations, so it is translated here rather than escaping as a raw
+  // RangeError from a function whose contract is to report bad input.
+  let key: Buffer;
+  try {
+    key = await scrypt(password, salt, keyLength, { N, r, p });
+  } catch {
+    throw new ValidationError(
+      `scrypt rejected the combination N=${N}, r=${r}, p=${p}, keyLength=${keyLength} for this platform`,
+    );
+  }
 
   return [
     PREFIX,
@@ -70,14 +165,22 @@ export async function verifyPassword(password: string, storedHash: string): Prom
   const p = Number.parseInt(pRaw, 10);
   const keyLength = Number.parseInt(lengthRaw, 10);
 
-  if (![N, r, p, keyLength].every(Number.isFinite)) {
+  // An over-budget or non-integer parameter is a malformed hash, not a slow
+  // one. This check has to happen before scrypt is called: Node's own maxmem
+  // guard only covers the 128 * N * r memory block, so keyLength and p are
+  // otherwise unbounded and a crafted hash buys unbounded CPU per login.
+  const params = parseBoundedParams(N, r, p, keyLength);
+  if (!params) {
     return false;
   }
 
   try {
     const salt = Buffer.from(saltB64, "base64url");
     const expected = Buffer.from(hashB64, "base64url");
-    const actual = await scrypt(password, salt, keyLength, { N, r, p });
+    if (salt.length < 8 || salt.length > MAX_SALT_BYTES || expected.length !== keyLength) {
+      return false;
+    }
+    const actual = await scrypt(password, salt, keyLength, { N: params.N, r: params.r, p: params.p });
     if (actual.length !== expected.length) {
       return false;
     }
@@ -102,6 +205,13 @@ export function needsRehash(storedHash: string, options: PasswordOptions = {}):
   const p = Number.parseInt(parts[3], 10);
   const keyLength = Number.parseInt(parts[4], 10);
 
+  // A hash carrying out-of-range parameters can never be verified, so it is
+  // reported as needing a rehash rather than silently comparing equal to a
+  // legitimate-looking configuration.
+  if (!parseBoundedParams(N, r, p, keyLength)) {
+    return true;
+  }
+
   return (
     N !== (options.cost ?? DEFAULT_COST) ||
     r !== (options.blockSize ?? DEFAULT_BLOCK_SIZE) ||

package/src/providers.ts

@@ -1,4 +1,4 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, createPublicKey, randomBytes, verify as verifySignature } from "node:crypto";
 import { ProviderError, ValidationError } from "./errors.js";
 import type {
   AuthorizationUrlOptions,
@@ -357,6 +357,133 @@ export const discord = createProvider({
 });
 
 const APPLE_ISSUER = "https://appleid.apple.com";
+const APPLE_JWKS_URL = "https://appleid.apple.com/auth/keys";
+const DEFAULT_JWKS_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Fetched signing keys, shared across providers and kept past a single request
+ * so a burst of logins does not turn into a burst of JWKS traffic. An entry
+ * whose kid is missing triggers a single refetch before failing, which is what
+ * makes a routine Apple key rotation invisible to callers.
+ */
+const jwksCache = new Map<string, { set: Record<string, unknown>; expiresAt: number }>();
+
+function clearJwksCache(url: string): void {
+  jwksCache.delete(url);
+}
+
+async function loadJwks(url: string, ttlMs: number, refresh: boolean): Promise<Record<string, unknown>> {
+  if (!refresh) {
+    const cached = jwksCache.get(url);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.set;
+    }
+  }
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new ProviderError(`Could not fetch signing keys from ${url}: HTTP ${response.status}`);
+  }
+  const set = (await response.json()) as Record<string, unknown>;
+  jwksCache.set(url, { set, expiresAt: Date.now() + ttlMs });
+  return set;
+}
+
+async function resolveJwks(config: OAuthProviderConfig): Promise<Record<string, unknown>> {
+  if (typeof config.jwks === "function") {
+    return (await config.jwks()) as Record<string, unknown>;
+  }
+  if (config.jwks && typeof config.jwks === "object") {
+    return config.jwks;
+  }
+  const url = typeof config.jwksUrl === "string" ? config.jwksUrl : APPLE_JWKS_URL;
+  const ttl = typeof config.jwksCacheTtlMs === "number" ? config.jwksCacheTtlMs : DEFAULT_JWKS_TTL_MS;
+  return loadJwks(url, ttl, false);
+}
+
+function findJwk(set: Record<string, unknown>, kid: string): Record<string, unknown> | undefined {
+  const keys = set.keys;
+  if (!Array.isArray(keys)) {
+    return undefined;
+  }
+  return keys.find((entry): entry is Record<string, unknown> =>
+    typeof entry === "object" && entry !== null && (entry as { kid?: unknown }).kid === kid);
+}
+
+/**
+ * Verifies the RS256 signature over an id_token's header and payload against
+ * the provider's published keys, and returns the decoded payload.
+ *
+ * The claims inside a token are unauthenticated until this runs. Checking `iss`
+ * or `aud` on an unverified payload only proves the payload says what the
+ * attacker wants it to say, so the signature has to be checked first and the
+ * claim checks read the verified bytes.
+ */
+async function verifyIdToken(idToken: string, config: OAuthProviderConfig, providerName: string): Promise<Record<string, unknown>> {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new ProviderError(`${providerName} id_token is not a well-formed JWT`);
+  }
+  const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string];
+
+  let header: { alg?: unknown; kid?: unknown };
+  let payload: Record<string, unknown>;
+  try {
+    header = JSON.parse(Buffer.from(encodedHeader, "base64url").toString("utf8")) as { alg?: unknown; kid?: unknown };
+    payload = JSON.parse(Buffer.from(encodedPayload, "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    throw new ProviderError(`${providerName} id_token has undecodable segments`);
+  }
+
+  if (config.verifyIdTokenSignature === false) {
+    return payload;
+  }
+
+  // Pinning the algorithm is what stops the classic JWT confusion attack: a
+  // token declaring "alg": "none", or an HMAC algorithm keyed with the RSA
+  // public key, would otherwise be accepted.
+  if (header.alg !== "RS256") {
+    throw new ProviderError(`${providerName} id_token must be signed with RS256, got ${String(header.alg)}`);
+  }
+  if (typeof header.kid !== "string" || header.kid.length === 0) {
+    throw new ProviderError(`${providerName} id_token is missing a kid`);
+  }
+
+  const ttl = typeof config.jwksCacheTtlMs === "number" ? config.jwksCacheTtlMs : DEFAULT_JWKS_TTL_MS;
+  const url = typeof config.jwksUrl === "string" ? config.jwksUrl : APPLE_JWKS_URL;
+  const usesCache = typeof config.jwks !== "function" && typeof config.jwks !== "object";
+
+  let jwk = findJwk(await resolveJwks(config), header.kid);
+  if (!jwk && usesCache) {
+    // An unknown kid is either a rotation or an attack. Refetch once, since a
+    // rotation is the common case and the attacker has to survive the retry.
+    clearJwksCache(url);
+    jwk = findJwk(await loadJwks(url, ttl, true), header.kid);
+  }
+  if (!jwk) {
+    throw new ProviderError(`${providerName} id_token was signed by an unknown key (kid: ${header.kid})`);
+  }
+
+  let publicKey;
+  try {
+    publicKey = createPublicKey({ key: jwk, format: "jwk" });
+  } catch {
+    throw new ProviderError(`${providerName} id_token signing key could not be read`);
+  }
+
+  const signed = Buffer.from(`${encodedHeader}.${encodedPayload}`, "utf8");
+  let signature: Buffer;
+  try {
+    signature = Buffer.from(encodedSignature, "base64url");
+  } catch {
+    throw new ProviderError(`${providerName} id_token has an undecodable signature`);
+  }
+  if (signature.length === 0 || !verifySignature("RSA-SHA256", signed, publicKey, signature)) {
+    throw new ProviderError(`${providerName} id_token signature is invalid`);
+  }
+
+  return payload;
+}
 
 export const apple = createProvider({
   id: "apple",
@@ -365,16 +492,17 @@ export const apple = createProvider({
   tokenUrl: "https://appleid.apple.com/auth/token",
   scopes: ["name", "email"],
   extraAuthParams: { response_mode: "form_post" },
-  parseProfile(tokens, config) {
+  async parseProfile(tokens, config) {
     const idToken = tokens?.id_token;
     if (!idToken) {
       return { provider: "apple", raw: tokens };
     }
 
     // Apple is the only built-in provider whose profile comes from a token in
-    // the response rather than a server-side userinfo call, so the claims are
-    // checked here instead. See ARCHITECTURE.md for the signature caveat.
-    const payload = JSON.parse(Buffer.from(idToken.split(".")[1], "base64url").toString("utf8")) as Record<string, unknown>;
+    // the response rather than a server-side userinfo call, so the token is
+    // verified here. See ARCHITECTURE.md for why the signature is checked even
+    // though the token usually arrives over a server-side TLS exchange.
+    const payload = await verifyIdToken(idToken, config, "Apple");
 
     const iss = typeof payload.iss === "string" ? payload.iss : undefined;
     if (iss !== APPLE_ISSUER) {
@@ -390,10 +518,19 @@ export const apple = createProvider({
       }
     }
 
-    if (typeof payload.exp === "number" && payload.exp <= Math.floor(Date.now() / 1000)) {
+    // Required rather than checked when present. A token with no usable exp
+    // would otherwise be treated as never expiring, which turns a leaked token
+    // into permanent access.
+    const exp = payload.exp;
+    if (typeof exp !== "number" || !Number.isFinite(exp)) {
+      throw new ProviderError("Apple id_token is missing a numeric exp claim");
+    }
+    if (exp <= Math.floor(Date.now() / 1000)) {
       throw new ProviderError("Apple id_token has expired");
     }
 
+    // Apple only returns these on the first authorization for an account, so
+    // callers must not depend on them being present.
     return {
       provider: "apple",
       id: payload.sub as string | undefined,

package/src/types.ts

@@ -47,6 +47,8 @@ export type JwtPayload = Record<string, unknown> & {
   name?: string;
   roles?: string[];
   permissions?: string[];
+  /** Session version, written only when a SessionStore is configured. */
+  sv?: number;
 };
 
 export type Secret = string | Buffer;
@@ -128,6 +130,32 @@ export interface OAuthProviderConfig {
   userInfoHeaders?: Record<string, string>;
   tokenAuthMethod?: TokenAuthMethod;
   provider?: OAuthProvider | (Pick<OAuthProvider, "id"> & Partial<OAuthProvider>);
+  /**
+   * Where to fetch id_token signing keys. Defaults to Apple's published JWKS
+   * endpoint. Only used by providers that carry an id_token in the token
+   * response.
+   */
+  jwksUrl?: string;
+  /**
+   * Supply signing keys directly instead of fetching them. Useful for tests, for
+   * offline environments, and for applications that already maintain their own
+   * JWKS cache. Accepts a JWK set or a function returning one.
+   */
+  jwks?: Record<string, unknown> | (() => Promise<Record<string, unknown>> | Record<string, unknown>);
+  /**
+   * How long fetched keys are reused before being refreshed, in milliseconds.
+   * Defaults to one hour. Apple rotates its keys infrequently, and an unknown
+   * `kid` always triggers one immediate refetch regardless of this.
+   */
+  jwksCacheTtlMs?: number;
+  /**
+   * Set to false to skip id_token signature verification. Verification is on by
+   * default and should stay on: an id_token is a bearer assertion of identity,
+   * and accepting one without checking Apple's signature means anyone who can
+   * influence the token response can choose the user. Only turn this off in a
+   * test harness, never in production.
+   */
+  verifyIdTokenSignature?: boolean;
   [key: string]: unknown;
 }
 
@@ -294,6 +322,25 @@ export interface LoginResult {
   };
 }
 
+export interface SessionStore {
+  /**
+   * The user's current session version. Tokens are minted carrying the value
+   * that was current at login, and are rejected once it no longer matches, so
+   * bumping the number logs out every session issued before that moment.
+   * Returning `undefined` or `null` is treated as version 0.
+   */
+  getVersion(userId: string | number): Promise<number | undefined | null> | number | undefined | null;
+  /**
+   * Invalidate every session currently issued to this user and return the new
+   * version. Called by `revokeAllSessions`.
+   */
+  bumpVersion?(userId: string | number): Promise<number> | number;
+  /**
+   * Invalidate one session by its jti. Called by `revokeSession`.
+   */
+  revokeSession?(jti: string): Promise<void> | void;
+}
+
 export interface AuthOptions {
   secret: Secret;
   refreshSecret?: Secret;
@@ -312,6 +359,13 @@ export interface AuthOptions {
   trustUserPermissions?: boolean;
   userStore?: UserStore;
   refreshStore?: RefreshStore;
+  /**
+   * Enables session revocation. Configuring one adds an `sv` claim to minted
+   * tokens and costs one store read per verification, which is why it is
+   * opt-in: without it, revoking a refresh token only invalidates that one
+   * session, and an already-issued access token stays valid until it expires.
+   */
+  sessionStore?: SessionStore;
   rbac?: import("./rbac.js").RBAC | RBACOptions;
   roles?: RBACOptions | Record<string, RoleDefinition> | Array<string | RoleDefinition>;
   oauth?: import("./oauth.js").OAuth | OAuthOptions;
@@ -336,6 +390,14 @@ export interface RequestLike {
 
 export interface ExtractTokenOptions {
   cookie?: string;
+  /**
+   * Allow reading the token from `?access_token=` or `?token=`. Off by default:
+   * a token in a URL is written to access logs, proxy logs, browser history, and
+   * the Referer header sent to third parties, none of which a header or cookie
+   * token leaks into. Only enable it for flows that genuinely cannot set a
+   * header, such as an EventSource or a file download.
+   */
+  query?: boolean;
   optional?: boolean;
   passthrough?: boolean;
   audience?: string | string[];