@dotpress/auth 2.0.0-alpha.4 → 2.0.0-alpha.5

package/dist/index.js

@@ -4,6 +4,10 @@ declareContextKey("user", "authPlugin");
 declareContextKey("auth", "authPlugin");
 
 // src/auth.ts
+import {
+  createMemoryRateLimitStore,
+  parseDuration
+} from "@dotpress/core";
 import bcrypt from "bcryptjs";
 import {
   CompactSign,
@@ -47,43 +51,6 @@ var isCookieAuthenticationAllowed = async (req, isTrustedOrigin) => {
   return originHost !== void 0 && originHost === (req.header("host") ?? hostOf(req.url));
 };
 
-// src/rate-limit.ts
-var memoryRateLimitStore = (options = {}) => {
-  const maxKeys = options.maxKeys ?? 1e4;
-  if (!Number.isInteger(maxKeys) || maxKeys < 1) {
-    throw new RangeError("Invalid maxKeys: expected a positive integer.");
-  }
-  const counters = /* @__PURE__ */ new Map();
-  const makeRoom = (now) => {
-    if (counters.size < maxKeys) return;
-    for (const [key, state] of counters) {
-      if (state.resetAt.getTime() <= now) counters.delete(key);
-    }
-    for (const key of counters.keys()) {
-      if (counters.size < maxKeys) break;
-      counters.delete(key);
-    }
-  };
-  return {
-    async increment(key, windowSeconds) {
-      const now = Date.now();
-      const current = counters.get(key);
-      if (current && current.resetAt.getTime() > now) {
-        current.count += 1;
-        return { ...current };
-      }
-      counters.delete(key);
-      makeRoom(now);
-      const state = { count: 1, resetAt: new Date(now + windowSeconds * 1e3) };
-      counters.set(key, state);
-      return { ...state };
-    },
-    async reset(key) {
-      counters.delete(key);
-    }
-  };
-};
-
 // src/auth.ts
 var ALGORITHM = "RS256";
 var ACCESS_TOKEN_TYPE = "at+jwt";
@@ -96,6 +63,67 @@ var AuthError = class extends Error {
   }
   code;
 };
+var internals = /* @__PURE__ */ new WeakMap();
+var internalsOf = (auth) => typeof auth === "object" && auth !== null ? internals.get(auth) : void 0;
+var wholeSeconds = (label, value, min) => {
+  const result = Math.round(
+    parseDuration(value, `createAuth(): ${label}`) / 1e3
+  );
+  if (result < min) {
+    throw new RangeError(
+      `createAuth(): ${label} must be at least ${min} second${min === 1 ? "" : "s"}.`
+    );
+  }
+  return result;
+};
+var assertKnown = (options, known, prefix = "") => {
+  if (options === void 0) return;
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(
+      `createAuth(): ${prefix ? prefix.slice(0, -1) : "options"} must be an object.`
+    );
+  }
+  for (const key of Object.keys(options)) {
+    if (!known.includes(key)) {
+      throw new TypeError(`createAuth(): unknown option "${prefix}${key}".`);
+    }
+  }
+};
+var OPTIONS = [
+  "keys",
+  "dataProvider",
+  "accessTokenTTL",
+  "session",
+  "issuer",
+  "audience",
+  "cookies",
+  "clients",
+  "onLoginFailed",
+  "onLoginSuccess",
+  "loginThrottle",
+  "beforeLogin",
+  "passwordHashRounds",
+  "usernameClaim",
+  "refreshTokenReuseInterval",
+  "onRefreshTokenReuse",
+  "getUserRoles"
+];
+var KEY_OPTIONS = [
+  "privateKey",
+  "publicKey",
+  "kid",
+  "additionalPublicKeys"
+];
+var SESSION_OPTIONS = [
+  "idleTimeout",
+  "absoluteTimeout"
+];
+var CLIENT_OPTIONS = [
+  "allowed",
+  "required",
+  "isUserRoleAllowed",
+  "sessions"
+];
 var DEFAULT_COOKIE_SETTINGS = {
   enabled: false,
   httpOnly: true,
@@ -117,15 +145,15 @@ var defaultUserRoles = (user) => {
   }
   return typeof role === "string" ? [role] : [];
 };
-var checkSession = (session, name) => {
-  for (const key of ["idleTimeout", "absoluteTimeout"]) {
-    const value = session?.[key];
-    if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) {
-      throw new RangeError(
-        `Invalid ${name}.${key}: expected a positive number of seconds.`
-      );
-    }
+var resolveSession = (session, name) => {
+  assertKnown(session, SESSION_OPTIONS, `${name}.`);
+  const resolved = {};
+  for (const key of SESSION_OPTIONS) {
+    if (session === void 0 || !(key in session)) continue;
+    const value = session[key];
+    resolved[key] = value === void 0 ? void 0 : wholeSeconds(`${name}.${key}`, value, 1);
   }
+  return resolved;
 };
 var DEFAULT_LOGIN_LIMITS = {
   usernameAndIp: { max: 5, window: 60 },
@@ -133,21 +161,39 @@ var DEFAULT_LOGIN_LIMITS = {
 };
 var resolveLoginThrottle = (input) => {
   if (input === false) return void 0;
+  assertKnown(input, ["store", "limits"], "loginThrottle.");
+  assertKnown(
+    input?.limits,
+    ["usernameAndIp", "username"],
+    "loginThrottle.limits."
+  );
   const limit = (name) => {
     const value = input?.limits?.[name];
     if (value === false) return void 0;
     const resolved = value ?? DEFAULT_LOGIN_LIMITS[name];
-    if (!Number.isInteger(resolved.max) || resolved.max < 1 || !Number.isFinite(resolved.window) || resolved.window <= 0) {
+    assertKnown(
+      resolved,
+      ["max", "window"],
+      `loginThrottle.limits.${name}.`
+    );
+    if (!Number.isInteger(resolved.max) || resolved.max < 1) {
       throw new RangeError(
-        `Invalid loginThrottle.limits.${name}: expected a positive integer max and a positive window, in seconds.`
+        `createAuth(): loginThrottle.limits.${name}.max must be a positive integer.`
       );
     }
-    return { max: resolved.max, window: resolved.window };
+    return {
+      max: resolved.max,
+      window: wholeSeconds(
+        `loginThrottle.limits.${name}.window`,
+        resolved.window,
+        1
+      )
+    };
   };
-  const store = input?.store ?? memoryRateLimitStore();
+  const store = input?.store ?? createMemoryRateLimitStore();
   if (typeof store.increment !== "function" || typeof store.reset !== "function") {
     throw new TypeError(
-      "Invalid loginThrottle.store: expected increment() and reset() methods."
+      "createAuth(): loginThrottle.store must have increment() and reset() methods."
     );
   }
   return {
@@ -159,37 +205,62 @@ var resolveLoginThrottle = (input) => {
   };
 };
 var resolveSettings = (settings) => {
-  if (!settings?.keys?.secretKey || !settings.keys.publicKey) {
+  if (typeof settings !== "object" || settings === null) {
+    throw new TypeError("createAuth(): expected an object of options.");
+  }
+  if ("refreshTokenTTLInDays" in settings) {
     throw new TypeError(
-      "createAuth() requires keys.secretKey and keys.publicKey."
+      "createAuth(): refreshTokenTTLInDays is replaced by session.idleTimeout."
+    );
+  }
+  if (typeof settings.keys === "object" && settings.keys !== null && "secretKey" in settings.keys) {
+    throw new TypeError(
+      "createAuth(): keys.secretKey is renamed keys.privateKey."
+    );
+  }
+  assertKnown(settings, OPTIONS);
+  assertKnown(settings.keys, KEY_OPTIONS, "keys.");
+  for (const [index, entry] of (settings.keys?.additionalPublicKeys ?? []).entries()) {
+    if (typeof entry !== "string") {
+      assertKnown(
+        entry,
+        ["publicKey", "kid"],
+        `keys.additionalPublicKeys[${index}].`
+      );
+    }
+  }
+  assertKnown(settings.clients, CLIENT_OPTIONS, "clients.");
+  assertKnown(
+    settings.cookies,
+    Object.keys(DEFAULT_COOKIE_SETTINGS),
+    "cookies."
+  );
+  if (!settings?.keys?.privateKey || !settings.keys.publicKey) {
+    throw new TypeError(
+      "createAuth(): keys.privateKey and keys.publicKey are required."
     );
   }
   if (!settings.dataProvider) {
-    throw new TypeError("createAuth() requires a dataProvider.");
+    throw new TypeError("createAuth(): dataProvider is required.");
   }
   if (typeof settings.issuer !== "string" || settings.issuer === "") {
     throw new TypeError(
-      "createAuth() requires an issuer (iss claim), such as the URL of the API."
+      "createAuth(): issuer is required (the iss claim), such as the URL of the API."
     );
   }
   if (settings.audience !== void 0 && settings.audience === "") {
-    throw new TypeError("Invalid audience: expected a non-empty string.");
+    throw new TypeError("createAuth(): audience must be a non-empty string.");
   }
   const clients = settings.clients;
   if (clients && (!Array.isArray(clients.allowed) || clients.allowed.length === 0 || clients.allowed.some((id) => typeof id !== "string" || id === ""))) {
     throw new TypeError(
-      "Invalid clients.allowed: expected a non-empty list of client identifiers."
+      "createAuth(): clients.allowed must be a non-empty list of client identifiers."
     );
   }
   const rounds = settings.passwordHashRounds;
   if (rounds !== void 0 && (!Number.isInteger(rounds) || rounds < 4 || rounds > 31)) {
     throw new RangeError(
-      "Invalid passwordHashRounds: expected an integer between 4 and 31."
-    );
-  }
-  if ("refreshTokenTTLInDays" in settings) {
-    throw new TypeError(
-      "refreshTokenTTLInDays is replaced by session.idleTimeout, in seconds."
+      "createAuth(): passwordHashRounds must be an integer between 4 and 31."
     );
   }
   for (const origin of settings.cookies?.trustedOrigins ?? []) {
@@ -200,33 +271,33 @@ var resolveSettings = (settings) => {
     }
     if (!valid) {
       throw new TypeError(
-        `Invalid cookies.trustedOrigins: "${origin}" is not an origin (expected a scheme and a host, such as https://app.example.com, without path or trailing slash).`
+        `createAuth(): cookies.trustedOrigins: "${origin}" is not an origin (expected a scheme and a host, such as https://app.example.com, without path or trailing slash).`
       );
     }
   }
-  checkSession(settings.session, "session");
-  for (const [clientId, session] of Object.entries(clients?.sessions ?? {})) {
+  const session = resolveSession(settings.session, "session");
+  const clientSessions = {};
+  for (const [clientId, override] of Object.entries(clients?.sessions ?? {})) {
     if (!clients?.allowed.includes(clientId)) {
       throw new TypeError(
-        `Invalid clients.sessions: "${clientId}" is not in clients.allowed.`
+        `createAuth(): clients.sessions: "${clientId}" is not in clients.allowed.`
       );
     }
-    checkSession(session, `clients.sessions.${clientId}`);
-  }
-  const reuseInterval = settings.refreshTokenReuseInterval;
-  if (reuseInterval !== void 0 && (!Number.isFinite(reuseInterval) || reuseInterval < 0)) {
-    throw new RangeError(
-      "Invalid refreshTokenReuseInterval: expected a non-negative number of seconds."
+    clientSessions[clientId] = resolveSession(
+      override,
+      `clients.sessions.${clientId}`
     );
   }
+  const optional = (label, fallback, min) => settings[label] === void 0 ? fallback : wholeSeconds(label, settings[label], min);
   return {
     keys: settings.keys,
     dataProvider: settings.dataProvider,
-    accessTokenTTL: settings.accessTokenTTL ?? 900,
+    accessTokenTTL: optional("accessTokenTTL", 900, 1),
     session: {
-      idleTimeout: settings.session?.idleTimeout ?? DEFAULT_IDLE_TIMEOUT,
-      absoluteTimeout: settings.session?.absoluteTimeout
+      idleTimeout: session.idleTimeout ?? DEFAULT_IDLE_TIMEOUT,
+      absoluteTimeout: session.absoluteTimeout
     },
+    clientSessions,
     issuer: settings.issuer,
     audience: settings.audience ?? settings.issuer,
     cookies: resolveCookies(settings.cookies),
@@ -237,7 +308,7 @@ var resolveSettings = (settings) => {
     beforeLogin: settings.beforeLogin,
     passwordHashRounds: settings.passwordHashRounds ?? 12,
     usernameClaim: settings.usernameClaim ?? false,
-    refreshTokenReuseInterval: settings.refreshTokenReuseInterval ?? 10,
+    refreshTokenReuseInterval: optional("refreshTokenReuseInterval", 10, 0),
     onRefreshTokenReuse: settings.onRefreshTokenReuse,
     getUserRoles: settings.getUserRoles ?? defaultUserRoles
   };
@@ -252,12 +323,12 @@ var cookieName = (setting, name, base, attributes) => {
   const lowerName = name.toLowerCase();
   if (lowerName.startsWith("__host-") && !hostAllowed) {
     throw new TypeError(
-      `Invalid cookies.${setting}: a __Host- cookie must be secure, without domain, and with path "/".`
+      `createAuth(): cookies.${setting}: a __Host- cookie must be secure, without domain, and with path "/".`
     );
   }
   if (lowerName.startsWith("__secure-") && !secure) {
     throw new TypeError(
-      `Invalid cookies.${setting}: a __Secure- cookie must be secure.`
+      `createAuth(): cookies.${setting}: a __Secure- cookie must be secure.`
     );
   }
   return name;
@@ -269,9 +340,7 @@ var resolveCookies = (settings = {}) => {
   }
   for (const key of ["path", "refreshTokenPath"]) {
     if (!merged[key].startsWith("/")) {
-      throw new TypeError(
-        `Invalid cookies.${key}: expected a path starting with "/".`
-      );
+      throw new TypeError(`createAuth(): cookies.${key} must start with "/".`);
     }
   }
   const { secure, domain } = merged;
@@ -298,14 +367,14 @@ var loadKey = async (kind, load) => {
     return await load();
   } catch (error) {
     throw new TypeError(
-      `Invalid auth ${kind}: expected an RSA PEM key (${error.message}).`,
+      `createAuth(): keys.${kind} must be an RSA PEM key (${error.message}).`,
       { cause: error }
     );
   }
 };
 var loadPublicKey = async (kind, pem, kid) => {
   if (pem.includes("BEGIN RSA PUBLIC KEY")) {
-    throw new TypeError(`Invalid auth ${kind}: ${PKCS1_PUBLIC_KEY_ERROR}`);
+    throw new TypeError(`createAuth(): keys.${kind}: ${PKCS1_PUBLIC_KEY_ERROR}`);
   }
   const key = await loadKey(
     kind,
@@ -316,27 +385,27 @@ var loadPublicKey = async (kind, pem, kid) => {
   return { kid: kid ?? await calculateJwkThumbprint(jwk), key, jwk };
 };
 var importKeys = async ({
-  secretKey,
+  privateKey,
   publicKey,
   kid,
   additionalPublicKeys = []
 }) => {
-  if (secretKey.includes("BEGIN RSA PRIVATE KEY")) {
+  if (privateKey.includes("BEGIN RSA PRIVATE KEY")) {
     throw new TypeError(
-      'Invalid auth secretKey: PKCS#1 keys ("BEGIN RSA PRIVATE KEY") are not supported, use PKCS#8 ("BEGIN PRIVATE KEY"). Convert it with: openssl pkcs8 -topk8 -nocrypt -in private.pem -out private.pkcs8.pem'
+      'createAuth(): keys.privateKey: PKCS#1 keys ("BEGIN RSA PRIVATE KEY") are not supported, use PKCS#8 ("BEGIN PRIVATE KEY"). Convert it with: openssl pkcs8 -topk8 -nocrypt -in private.pem -out private.pkcs8.pem'
     );
   }
-  const privateKey = await loadKey(
-    "secretKey",
-    () => importPKCS8(secretKey, ALGORITHM)
+  const signingKey = await loadKey(
+    "privateKey",
+    () => importPKCS8(privateKey, ALGORITHM)
   );
   const active = await loadPublicKey("publicKey", publicKey, kid);
   try {
-    const probe = await new CompactSign(new Uint8Array([1])).setProtectedHeader({ alg: ALGORITHM }).sign(privateKey);
+    const probe = await new CompactSign(new Uint8Array([1])).setProtectedHeader({ alg: ALGORITHM }).sign(signingKey);
     await compactVerify(probe, active.key);
   } catch (error) {
     throw new TypeError(
-      "Invalid auth keys: publicKey does not match secretKey.",
+      "createAuth(): keys.publicKey does not match keys.privateKey.",
       { cause: error }
     );
   }
@@ -353,11 +422,11 @@ var importKeys = async ({
       verificationKeys.push(loaded);
     } else if (existing.jwk.n !== loaded.jwk.n || existing.jwk.e !== loaded.jwk.e) {
       throw new TypeError(
-        `Invalid auth keys: kid "${loaded.kid}" is used by several keys.`
+        `createAuth(): keys: kid "${loaded.kid}" is used by several keys.`
       );
     }
   }
-  return { privateKey, kid: active.kid, verificationKeys };
+  return { signingKey, kid: active.kid, verificationKeys };
 };
 var verifyWithKeys = async (token, verificationKeys, verify) => {
   const { kid } = decodeProtectedHeader(token);
@@ -379,14 +448,14 @@ var verifyWithKeys = async (token, verificationKeys, verify) => {
 var BCRYPT_HASH = /^\$2[aby]\$\d{2}\$[./A-Za-z0-9]{53}$/;
 var nowInSeconds = () => Math.floor(Date.now() / 1e3);
 var toSession = (claims, roles) => {
-  if (typeof claims.sub !== "string" || claims.sub === "") {
+  if (typeof claims.sub !== "string" || claims.sub === "" || typeof claims.sid !== "string" || claims.sid === "") {
     throw new AuthError("INVALID_ACCESS_TOKEN");
   }
   return {
     userId: claims.sub,
     username: typeof claims.username === "string" ? claims.username : void 0,
-    tokenId: typeof claims.jti === "string" ? claims.jti : "",
-    sessionId: typeof claims.sid === "string" ? claims.sid : void 0,
+    accessTokenId: typeof claims.jti === "string" ? claims.jti : "",
+    sessionId: claims.sid,
     clientId: typeof claims.client_id === "string" ? claims.client_id : void 0,
     roles,
     claims
@@ -411,7 +480,7 @@ var createAuth = (input) => {
     return dummyHash;
   };
   const sessionPolicy = (clientId) => {
-    const override = clientId === void 0 ? void 0 : settings.clients?.sessions?.[clientId];
+    const override = clientId === void 0 ? void 0 : settings.clientSessions[clientId];
     if (!override) return settings.session;
     return {
       idleTimeout: override.idleTimeout ?? settings.session.idleTimeout,
@@ -423,8 +492,8 @@ var createAuth = (input) => {
     return absoluteTimeout === void 0 ? void 0 : authTime + absoluteTimeout;
   };
   const signAccessToken = async (claims) => {
-    const { privateKey, kid } = await getKeys();
-    const jwtId = crypto.randomUUID();
+    const { signingKey, kid } = await getKeys();
+    const accessTokenId = crypto.randomUUID();
     const issuedAt = nowInSeconds();
     const expiresAt = Math.min(
       issuedAt + settings.accessTokenTTL,
@@ -434,17 +503,21 @@ var createAuth = (input) => {
       // Personal data: written on demand only.
       ...settings.usernameClaim && claims.username && { username: claims.username },
       auth_time: claims.auth_time,
-      ...claims.sid !== void 0 && { sid: claims.sid },
+      sid: claims.sid,
       ...claims.client_id !== void 0 && { client_id: claims.client_id }
-    }).setProtectedHeader({ alg: ALGORITHM, typ: ACCESS_TOKEN_TYPE, kid }).setSubject(claims.sub).setIssuer(settings.issuer).setAudience(settings.audience).setJti(jwtId).setIssuedAt(issuedAt).setExpirationTime(expiresAt).sign(privateKey);
-    return { jwtId, accessToken: token, expiresAt: new Date(expiresAt * 1e3) };
+    }).setProtectedHeader({ alg: ALGORITHM, typ: ACCESS_TOKEN_TYPE, kid }).setSubject(claims.sub).setIssuer(settings.issuer).setAudience(settings.audience).setJti(accessTokenId).setIssuedAt(issuedAt).setExpirationTime(expiresAt).sign(signingKey);
+    return {
+      accessTokenId,
+      accessToken: token,
+      expiresAt: new Date(expiresAt * 1e3)
+    };
   };
   const generateRefreshToken = async () => {
     const token = toHex(crypto.getRandomValues(new Uint8Array(128)));
     return { token, tokenHash: await sha256(token) };
   };
-  const issueTokens = async (claims, familyId) => {
-    const access = await signAccessToken({ ...claims, sid: familyId });
+  const issueTokens = async (claims, sessionId) => {
+    const access = await signAccessToken({ ...claims, sid: sessionId });
     const refreshToken = await generateRefreshToken();
     const end = sessionEnd(claims.auth_time, claims.client_id);
     const refreshTokenExpiresAt = new Date(
@@ -454,10 +527,10 @@ var createAuth = (input) => {
       )
     );
     await settings.dataProvider.storeRefreshToken({
-      ...refreshToken,
+      tokenHash: refreshToken.tokenHash,
       userId: claims.sub,
-      jwtId: access.jwtId,
-      familyId,
+      accessTokenId: access.accessTokenId,
+      sessionId,
       expiresAt: refreshTokenExpiresAt
     });
     return {
@@ -473,17 +546,17 @@ var createAuth = (input) => {
     if (usedAt !== void 0 && Date.now() - usedAt < settings.refreshTokenReuseInterval * 1e3) {
       return;
     }
-    const familyId = stored.familyId ?? void 0;
-    if (familyId) {
-      await settings.dataProvider.revokeTokenFamily(familyId);
+    const sessionId = stored.sessionId ?? void 0;
+    if (sessionId) {
+      await settings.dataProvider.revokeSessionTokens(sessionId);
     } else {
-      await settings.dataProvider.revokeTokens(stored.userId);
+      await settings.dataProvider.revokeUserTokens(stored.userId);
     }
     try {
       await settings.onRefreshTokenReuse?.({
         userId: stored.userId,
-        familyId,
-        jwtId: stored.jwtId
+        sessionId,
+        accessTokenId: stored.accessTokenId
       });
     } catch {
     }
@@ -507,7 +580,6 @@ var createAuth = (input) => {
       client_id: clientId
     };
   };
-  const generateAccessToken = async (subject) => signAccessToken(sessionClaims(subject));
   let routesPath;
   let cors;
   const isTrustedOrigin = (req) => (origin) => {
@@ -519,12 +591,12 @@ var createAuth = (input) => {
   const bindRoutesPath = (path) => {
     if (typeof path !== "string" || !path.startsWith("/")) {
       throw new TypeError(
-        `Invalid routesPath: expected a path starting with "/", received ${JSON.stringify(path)}.`
+        `authPlugin(): the routes path must start with "/", received ${JSON.stringify(path)}.`
       );
     }
     if (routesPath !== void 0 && routesPath !== path) {
       throw new Error(
-        `This auth service already serves routes under "${routesPath}": create one auth service per app to serve them under "${path}".`
+        `authPlugin(): this auth service already serves routes under "${routesPath}": create one auth service per app to serve them under "${path}".`
       );
     }
     routesPath = path;
@@ -539,16 +611,8 @@ var createAuth = (input) => {
     const { httpOnly, secure, sameSite, path, domain } = settings.cookies;
     return { httpOnly, secure, sameSite, path, domain };
   };
-  return {
-    settings,
+  const auth = {
     isCookieAuthenticationAllowed: (req) => isCookieAuthenticationAllowed(req, isTrustedOrigin(req)),
-    init: async (options = {}) => {
-      if (options.routesPath !== void 0) bindRoutesPath(options.routesPath);
-      if (options.cors !== void 0) cors = options.cors;
-      await Promise.all([getKeys(), getDummyHash()]);
-    },
-    generateAccessToken,
-    generateRefreshToken,
     async generateTokensForUser(subject) {
       return issueTokens(sessionClaims(subject), crypto.randomUUID());
     },
@@ -574,7 +638,7 @@ var createAuth = (input) => {
       );
       const refreshTokenHash = await sha256(refreshToken);
       const stored = await settings.dataProvider.findRefreshToken(refreshTokenHash);
-      if (!userId || !stored || stored.userId !== userId || stored.jwtId !== claims.jti || stored.revokedAt || // Client removed from the configuration: the session ends.
+      if (!userId || !stored || stored.userId !== userId || stored.accessTokenId !== claims.jti || stored.revokedAt || // Client removed from the configuration: the session ends.
       !isClientAccepted(clientId)) {
         throw new AuthError("INVALID_REFRESH_TOKEN");
       }
@@ -590,10 +654,10 @@ var createAuth = (input) => {
       }
       const user = await settings.dataProvider.findUserById(userId);
       if (!user) {
-        if (stored.familyId) {
-          await settings.dataProvider.revokeTokenFamily(stored.familyId);
+        if (stored.sessionId) {
+          await settings.dataProvider.revokeSessionTokens(stored.sessionId);
         } else {
-          await settings.dataProvider.revokeTokens(userId);
+          await settings.dataProvider.revokeUserTokens(userId);
         }
         throw new AuthError("INVALID_REFRESH_TOKEN");
       }
@@ -604,9 +668,9 @@ var createAuth = (input) => {
           auth_time: authTime,
           client_id: clientId
         },
-        // Tokens stored without family start one, derived from the token
-        // so that concurrent rotations land in the same family.
-        stored.familyId || stored.jwtId
+        // Tokens stored before sessions (V1) start one, derived from the
+        // token so that concurrent rotations land in the same session.
+        stored.sessionId || stored.accessTokenId
       );
       if (!stored.isUsed) {
         await settings.dataProvider.markRefreshTokenAsUsed(
@@ -652,19 +716,27 @@ var createAuth = (input) => {
         await sha256(refreshToken)
       );
       if (!stored) return void 0;
-      const sessionId = stored.familyId || void 0;
+      const sessionId = stored.sessionId || void 0;
       if (scope === "all") {
         if (stored.revokedAt || stored.isUsed || stored.expiresAt.getTime() <= Date.now()) {
           return void 0;
         }
-        await dataProvider.revokeTokens(stored.userId);
+        await dataProvider.revokeUserTokens(stored.userId);
       } else if (sessionId) {
-        await dataProvider.revokeTokenFamily(sessionId);
+        await dataProvider.revokeSessionTokens(sessionId);
       } else {
-        await dataProvider.revokeTokens(stored.userId);
+        await dataProvider.revokeUserTokens(stored.userId);
       }
       return { userId: stored.userId, sessionId };
     },
+    async revokeUserSessions(userId) {
+      if (typeof userId !== "string" || userId === "") {
+        throw new TypeError(
+          "revokeUserSessions(): userId must be a non-empty string."
+        );
+      }
+      await settings.dataProvider.revokeUserTokens(userId);
+    },
     async getJwks() {
       const { verificationKeys } = await getKeys();
       return {
@@ -683,13 +755,13 @@ var createAuth = (input) => {
       return end === void 0 ? void 0 : new Date(end * 1e3);
     },
     getUserRoles: (user) => settings.getUserRoles(user),
-    setAuthCookies(res, tokens, expiresInSeconds) {
+    setAuthCookies(res, tokens) {
       const cookies = settings.cookies;
       if (!cookies.enabled) return;
       const expiresAt = tokens.refreshTokenExpiresAt?.getTime();
       const options = {
         ...cookieOptions(),
-        maxAge: expiresInSeconds ?? (expiresAt === void 0 ? settings.session.idleTimeout : Math.max(0, Math.ceil((expiresAt - Date.now()) / 1e3)))
+        maxAge: expiresAt === void 0 ? settings.session.idleTimeout : Math.max(0, Math.ceil((expiresAt - Date.now()) / 1e3))
       };
       res.setCookie(cookies.refreshTokenName, tokens.refreshToken, {
         ...options,
@@ -711,7 +783,7 @@ var createAuth = (input) => {
         res.clearCookie(cookies.accessTokenName, cookieOptions());
       }
     },
-    hashPassword: (password, saltRounds = settings.passwordHashRounds) => generatePasswordHash(password, saltRounds),
+    hashPassword: (password) => generatePasswordHash(password, { rounds: settings.passwordHashRounds }),
     passwordNeedsRehash: (passwordHash) => BCRYPT_HASH.test(passwordHash) && bcrypt.getRounds(passwordHash) !== settings.passwordHashRounds,
     // No length check: the password was verified, and a longer V1 password
     // is truncated the same way.
@@ -724,16 +796,39 @@ var createAuth = (input) => {
       return false;
     }
   };
+  internals.set(auth, {
+    settings,
+    init: async (options = {}) => {
+      if (options.routesPath !== void 0) bindRoutesPath(options.routesPath);
+      if (options.cors !== void 0) cors = options.cors;
+      await Promise.all([getKeys(), getDummyHash()]);
+    }
+  });
+  return auth;
 };
 var MAX_PASSWORD_BYTES = 72;
 var isPasswordTooLong = (password) => bcrypt.truncates(password);
-var generatePasswordHash = async (password, saltRounds = 12) => {
+var generatePasswordHash = async (password, options = {}) => {
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("generatePasswordHash(): options must be an object.");
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== "rounds") {
+      throw new TypeError(`generatePasswordHash(): unknown option "${key}".`);
+    }
+  }
+  const { rounds = 12 } = options;
+  if (!Number.isInteger(rounds) || rounds < 4 || rounds > 31) {
+    throw new RangeError(
+      "generatePasswordHash(): rounds must be an integer between 4 and 31."
+    );
+  }
   if (isPasswordTooLong(password)) {
     throw new RangeError(
       `Password too long: bcrypt reads ${MAX_PASSWORD_BYTES} bytes at most (UTF-8). Check it with isPasswordTooLong().`
     );
   }
-  return bcrypt.hash(password, saltRounds);
+  return bcrypt.hash(password, rounds);
 };
 
 // src/middlewares.ts
@@ -749,7 +844,7 @@ var requireAuth = defineMiddleware(
 );
 var requireRole = (...roles) => {
   if (roles.length === 0) {
-    throw new TypeError("requireRole() expects at least one role.");
+    throw new TypeError("requireRole(): expected at least one role.");
   }
   return defineMiddleware((ctx) => {
     if (!ctx.user || !ctx.auth) return unauthorizedError();
@@ -759,7 +854,7 @@ var requireRole = (...roles) => {
 };
 var requireClient = (...clientIds) => {
   if (clientIds.length === 0) {
-    throw new TypeError("requireClient() expects at least one client.");
+    throw new TypeError("requireClient(): expected at least one client.");
   }
   return defineMiddleware((ctx) => {
     if (!ctx.user || !ctx.auth) return unauthorizedError();
@@ -776,6 +871,11 @@ import {
   tooManyRequestsError,
   unauthorizedError as unauthorizedError2
 } from "@dotpress/core";
+var PLUGIN_OPTIONS = [
+  "prefix",
+  "routes",
+  "jwks"
+];
 var AUTH_SECURITY_SCHEMES = {
   bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" }
 };
@@ -802,7 +902,6 @@ var findAccessToken = (req, cookies) => {
   }
   return void 0;
 };
-var extractAccessToken = (req, cookies) => findAccessToken(req, cookies)?.token;
 var loginThrottleKeys = async (throttle, username, ipAddress) => {
   const normalized = username.trim().toLowerCase();
   const { usernameAndIp, username: perUsername } = throttle.limits;
@@ -838,8 +937,7 @@ var refreshErrorResponse = (error, fallback) => {
   }
   return internalError(fallback);
 };
-var registerRoutes = (group, auth) => {
-  const { settings } = auth;
+var registerRoutes = (group, auth, settings) => {
   const { dataProvider, cookies } = settings;
   const expiration = (accessTokenExpiresAt, sessionExpiresAt) => ({
     expiresIn: Math.max(
@@ -944,7 +1042,11 @@ var registerRoutes = (group, auth) => {
       if (!passwordValid) {
         return loginFailed({ ...event, errorType: "invalid_password" });
       }
-      if (clientId !== void 0 && clients?.isUserRoleAllowed && !clients.isUserRoleAllowed(user.role ?? "", clientId)) {
+      if (clientId !== void 0 && clients?.isUserRoleAllowed && !clients.isUserRoleAllowed({
+        userId: user.userId,
+        role: user.role,
+        clientId
+      })) {
         return loginFailed({ ...event, errorType: "invalid_role" });
       }
       const tokens = await auth.generateTokensForUser({
@@ -1123,9 +1225,9 @@ var registerRoutes = (group, auth) => {
       const revoked = refreshToken ? await auth.revokeSession(refreshToken, { scope }) : void 0;
       if (!revoked && session) {
         if (scope === "all") {
-          await dataProvider.revokeTokens(session.userId);
+          await dataProvider.revokeUserTokens(session.userId);
         } else if (session.sessionId) {
-          await dataProvider.revokeTokenFamily(session.sessionId);
+          await dataProvider.revokeSessionTokens(session.sessionId);
         }
       } else if (!revoked && scope === "all") {
         return unauthorizedError2();
@@ -1137,13 +1239,28 @@ var registerRoutes = (group, auth) => {
 };
 var normalizePrefix = (prefix) => `/${prefix.split("/").filter(Boolean).join("/")}`;
 var authPlugin = (auth, options = {}) => {
+  const internal = internalsOf(auth);
+  if (!internal) {
+    throw new TypeError(
+      "authPlugin(): expected an auth service created with createAuth()."
+    );
+  }
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("authPlugin(): options must be an object.");
+  }
+  for (const key of Object.keys(options)) {
+    if (!PLUGIN_OPTIONS.includes(key)) {
+      throw new TypeError(`authPlugin(): unknown option "${key}".`);
+    }
+  }
+  const { settings } = internal;
   const prefix = options.prefix ?? "/auth";
   return definePlugin({
     name: "auth",
     auth,
     securitySchemes: AUTH_SECURITY_SCHEMES,
     async setup(api) {
-      await auth.init({
+      await internal.init({
         ...options.routes === false ? {} : { routesPath: api.publicPath(normalizePrefix(prefix)) },
         ...api.cors ? { cors: api.cors } : {}
       });
@@ -1151,8 +1268,7 @@ var authPlugin = (auth, options = {}) => {
       api.decorateContext("auth", () => void 0);
       const rejectedTokens = /* @__PURE__ */ new WeakSet();
       const authenticate = async (ctx) => {
-        const { cookies } = auth.settings;
-        const found = findAccessToken(ctx.req, cookies);
+        const found = findAccessToken(ctx.req, settings.cookies);
         if (!found) return;
         const { token } = found;
         if (found.source === "cookie" && !await auth.isCookieAuthenticationAllowed(ctx.req)) {
@@ -1164,9 +1280,7 @@ var authPlugin = (auth, options = {}) => {
         }
         try {
           const session = await auth.verifyAccessToken(token);
-          const user = await auth.settings.dataProvider.findUserById(
-            session.userId
-          );
+          const user = await settings.dataProvider.findUserById(session.userId);
           if (!user) {
             if (found.source === "header") rejectedTokens.add(ctx);
             return;
@@ -1197,7 +1311,7 @@ var authPlugin = (auth, options = {}) => {
         };
       });
       if (options.jwks) {
-        api.addRoute({
+        api.defineRoute({
           path: "/.well-known/jwks.json",
           meta: { tags: ["auth"], summary: "Public keys of the access tokens" },
           handler: async ({ res }) => {
@@ -1207,7 +1321,7 @@ var authPlugin = (auth, options = {}) => {
         });
       }
       if (options.routes !== false) {
-        registerRoutes(api.addRouteGroup(prefix), auth);
+        registerRoutes(api.createGroup(prefix), auth, settings);
       }
     }
   });
@@ -1215,13 +1329,10 @@ var authPlugin = (auth, options = {}) => {
 export {
   AUTH_SECURITY_SCHEMES,
   AuthError,
-  MAX_PASSWORD_BYTES,
   authPlugin,
   createAuth,
-  extractAccessToken,
   generatePasswordHash,
   isPasswordTooLong,
-  memoryRateLimitStore,
   requireAuth,
   requireClient,
   requireRole