@tulipes/cli 0.1.0 → 0.2.0-rc.1

package/templates/app/modules/auth/helpers/documents.ts

@@ -0,0 +1,57 @@
+import type { HydratedDocument, Types } from "mongoose";
+
+/**
+ * The shapes auth reads through the model store.
+ *
+ * `models.get()` is generic precisely so a consumer can say what it
+ * expects — the store cannot know, since models are registered by name
+ * from other modules. Declaring them here keeps the casts in one file
+ * instead of scattered through the handlers.
+ */
+export interface UserAttrs {
+  _id: Types.ObjectId;
+  email: string;
+  role: string;
+  tokens_valid_from?: Date;
+  created_at: Date;
+}
+
+export interface SessionAttrs {
+  _id: Types.ObjectId;
+  sid: string;
+  user: Types.ObjectId;
+  credential_version: string;
+  refresh_jti: string;
+  ip?: string;
+  user_agent?: string;
+  last_seen_at?: Date;
+  expires_at: Date;
+  /** From baseSchemaOptions, like every model's. */
+  created_at: Date;
+}
+
+/**
+ * `req.auth.user` and `req.auth.session` are hydrated documents, not lean
+ * objects: the plugins and instance methods are available on them, and a
+ * handler holding one can save it.
+ *
+ * The cost of that convenience is that the request object is now a write
+ * handle — mutating `req.auth.user` and saving it persists, wherever in a
+ * handler that happens.
+ */
+export type UserDoc = HydratedDocument<UserAttrs>;
+export type SessionDoc = HydratedDocument<SessionAttrs>;
+
+export interface CredentialDoc {
+  _id: Types.ObjectId;
+  user: Types.ObjectId;
+  password_hash: string;
+  /** Missing only on credentials created before versioned sessions. */
+  version?: string;
+}
+
+/** A local-password verification result, kept separate from the public user. */
+export interface PasswordIdentity {
+  user: UserDoc;
+  credentialVersion: string;
+}

package/templates/app/modules/auth/helpers/passport.ts

@@ -0,0 +1,180 @@
+import passport from "passport";
+import { randomUUID } from "node:crypto";
+import { Strategy as JwtStrategy, ExtractJwt } from "passport-jwt";
+import { Strategy as LocalStrategy } from "passport-local";
+import type { Ctx } from "@tulipes/core/boot";
+import type { Auth } from "@tulipes/core/http";
+
+import { verifyPassword } from "./passwords.ts";
+import {
+  isRevoked,
+  loadSession,
+  touchSession,
+  type TokenClaims,
+} from "./tokens.ts";
+import { GUEST } from "./auth.ts";
+import { readIdentity, writeIdentity } from "./session-cache.ts";
+import type {
+  CredentialDoc,
+  PasswordIdentity,
+  SessionAttrs,
+  SessionDoc,
+  UserAttrs,
+  UserDoc,
+} from "./documents.ts";
+
+/**
+ * Two strategies, both stateless as far as passport is concerned
+ * (`session: false` — this module keeps its own session rows):
+ *
+ *   local  runs once, at login, to check an email and password
+ *   jwt    runs on every request, to turn a Bearer token into a req.auth
+ *
+ * The jwt strategy never trusts the token's claims for authority: it
+ * resolves the session and the user, from the app cache when a request
+ * resolved them recently and nothing revoked them since (one Redis read),
+ * from the database otherwise (three reads). Every revocation deletes the
+ * cached entry, which is what makes a demotion, a ban or a logout take
+ * effect on the next request instead of whenever the token expires.
+ */
+export function configurePassport(ctx: Ctx): void {
+  passport.use(
+    new LocalStrategy(
+      { usernameField: "email", passwordField: "password", session: false },
+      async (email, password, done) => {
+        try {
+          const user = await ctx.models!
+            .get<UserDoc>("User")
+            .findOne({ email: String(email).toLowerCase() });
+          if (!user) return done(null, false);
+
+          // The hash is select:false, so it has to be asked for by name.
+          const Credential = ctx.models!.get<CredentialDoc>("Credential");
+          const credential = await Credential
+            .findOne({ user: user._id })
+            .select("+password_hash")
+            .lean();
+          if (!credential) return done(null, false);
+
+          const ok = await verifyPassword(password, credential.password_hash);
+          if (!ok) return done(null, false);
+
+          if (!credential.version) {
+            // Upgrade a legacy credential only if the verified hash is unchanged.
+            // A racing password change or another upgrade makes this login retry.
+            const version = randomUUID();
+            const upgraded = await Credential.updateOne(
+              {
+                user: user._id,
+                password_hash: credential.password_hash,
+                version: { $exists: false },
+              },
+              { $set: { version } },
+            );
+            if (!upgraded.matchedCount) return done(null, false);
+            credential.version = version;
+          }
+
+          return done(null, {
+            user,
+            credentialVersion: credential.version,
+          } satisfies PasswordIdentity);
+        } catch (error) {
+          return done(error as Error);
+        }
+      },
+    ),
+  );
+
+  passport.use(
+    new JwtStrategy(
+      {
+        // Cookies and URL parameters never authenticate this starter. A cookie
+        // extractor would also need the policy described in docs/browser-auth.md.
+        jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+        secretOrKey: String(ctx.Environment.get("JWT_ACCESS_SECRET")),
+        passReqToCallback: false,
+      },
+      async (claims: TokenClaims, done) => {
+        try {
+          if (claims.typ !== "access") return done(null, false);
+
+          // A hit is the identity a cold path resolved moments ago, for
+          // this sid and subject, and no revocation has run since — every
+          // revocation path deletes the entry before it answers. Documents
+          // are hydrated from the cached attributes, so handlers hold the
+          // same kind of value either way.
+          const cached = await readIdentity(ctx, claims.sid);
+          if (cached && String(cached.user._id) === claims.sub && cached.session.sid === claims.sid
+            && new Date(cached.session.expires_at).getTime() > Date.now()) {
+            const user = ctx.models!.get<UserDoc>("User").hydrate(cached.user) as UserDoc;
+            const session = ctx.models!.get<SessionDoc>("Session").hydrate(cached.session) as SessionDoc;
+            if (await touchSession(ctx, session, touchInterval(ctx))) {
+              await writeIdentity(ctx, claims.sid, { user: cached.user, session: session.toObject() as SessionAttrs });
+            }
+            return done(null, resolve(user, session, claims) as unknown as Express.User);
+          }
+
+          // Logout blacklists the jti; without this check a "logged out"
+          // token keeps working until it expires.
+          if (await isRevoked(ctx, claims.jti)) return done(null, false);
+
+          // The session row is the server-side half: deleting it signs the
+          // device out even though the access token is still signed and
+          // unexpired. A token whose session is gone is not a caller.
+          const session = await loadSession(ctx, claims.sid, claims.sub);
+          if (!session) return done(null, false);
+
+          const user = await ctx.models!.get<UserDoc>("User").findById(claims.sub);
+          if (!user) return done(null, false);
+
+          await touchSession(ctx, session, touchInterval(ctx));
+          await writeIdentity(ctx, claims.sid, { user: user.toObject() as UserAttrs, session: session.toObject() as SessionAttrs });
+
+          return done(null, resolve(user, session, claims) as unknown as Express.User);
+        } catch (error) {
+          return done(error as Error);
+        }
+      },
+    ),
+  );
+}
+
+/**
+ * The session row plus the token in hand. The three access-token fields
+ * are attached to the document rather than stored on it — they belong to
+ * one request, while the row outlives every token it ever issued.
+ */
+function resolve(user: UserDoc, session: SessionDoc, claims: TokenClaims): Auth {
+  return {
+    isAuthenticated: true,
+    user,
+    session: Object.assign(session, {
+      access_jti: claims.jti,
+      access_issued_at: new Date(claims.iat * 1000),
+      access_expires_at: new Date(claims.exp * 1000),
+    }),
+  };
+}
+
+/** How stale `last_seen_at` may get before a request pays for a write. */
+function touchInterval(ctx: Ctx): number {
+  return Number(ctx.config.auth?.sessionTouchSeconds ?? 60);
+}
+
+/**
+ * Runs on every request. Populates `req.auth`, and never rejects: an
+ * unauthenticated caller becomes the guest, and the ACL decides from there.
+ */
+export function authenticate(): import("express").RequestHandler {
+  return (req, res, next) => {
+    passport.authenticate(
+      "jwt",
+      { session: false },
+      (_err: unknown, resolved: Auth | false) => {
+        req.auth = resolved || { ...GUEST };
+        next();
+      },
+    )(req, res, next);
+  };
+}

package/templates/app/modules/auth/helpers/passwords.ts

@@ -0,0 +1,58 @@
+import bcrypt from "bcryptjs";
+import { randomUUID } from "node:crypto";
+import type { CredentialDoc } from "./documents.ts";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+import { forgetUser } from "./session-cache.ts";
+
+/**
+ * bcryptjs — pure JavaScript, so installs never need a native toolchain.
+ * The cost factor comes from config rather than a literal: raising it is
+ * how you keep pace with hardware, and it should not require a code change.
+ */
+const rounds = (ctx: Ctx): number => Number(ctx.config.security?.passwordRounds ?? 12);
+
+export async function hashPassword(ctx: Ctx, plain: string): Promise<string> {
+  return bcrypt.hash(plain, rounds(ctx));
+}
+
+export async function verifyPassword(plain: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(plain, hash);
+}
+
+/**
+ * Set or replace a user's password and invalidate every session they have.
+ *
+ * Revoking here is the whole point of changing a password after a suspected
+ * compromise: leaving other devices signed in would defeat it.
+ */
+export async function setPassword(ctx: Ctx, userId: string, plain: string, expectedVersion?: string): Promise<string> {
+  const password_hash = await hashPassword(ctx, plain);
+  const version = randomUUID();
+
+  // The password and its session version change in one atomic document write.
+  // Returning the previous version lets delayed cleanup target only that version.
+  const previous = await ctx.models!.get<CredentialDoc>("Credential").findOneAndUpdate(
+    { user: userId, ...(expectedVersion === undefined ? {} : { version: expectedVersion }) },
+    { $set: { password_hash, version } },
+    { upsert: expectedVersion === undefined, returnDocument: "before" },
+  );
+  if (expectedVersion !== undefined && !previous) throw new HttpError(401, "invalidCredentials");
+
+  // Authorization already rejects the previous version even if cleanup fails.
+  // Never delete sessions issued under a newer, concurrent password change.
+  // Cached identities of this user go first: they carry the old version.
+  await forgetUser(ctx, userId);
+  await ctx.models!.get("Session").deleteMany({
+    user: userId,
+    credential_version: previous?.version ?? { $exists: false },
+  });
+  return version;
+}
+
+/** Read only the version, never the hash, during session authorization. */
+export async function currentCredentialVersion(ctx: Ctx, userId: string): Promise<string | undefined> {
+  const credential = await ctx.models!.get<CredentialDoc>("Credential")
+    .findOne({ user: userId }).select("version").lean();
+  return credential?.version;
+}

package/templates/app/modules/auth/helpers/session-cache.ts

@@ -0,0 +1,67 @@
+import { appCache } from "@app/core";
+import type { Ctx } from "@tulipes/core/boot";
+
+import type { SessionAttrs, UserAttrs } from "./documents.ts";
+
+/**
+ * What a bearer token resolves to, kept in the app cache (Redis in
+ * production, shared by every replica) under the session id. A hit is one
+ * Redis read in place of the three Mongo reads the cold path performs
+ * (RevokedToken, Session, User); the entry lives no longer than
+ * `auth.cacheTtlSeconds`, and every path that revokes — logout, refresh
+ * reuse, rotation, session end, password change, user deletion — deletes
+ * it before answering, so a revoked session is refused on the very next
+ * request on any replica, as strictly as the cold path refuses it.
+ *
+ * The cache is best effort: a Redis outage is a miss, never an error, and
+ * the cold path is what every request takes then.
+ */
+export interface CachedIdentity {
+  user: UserAttrs;
+  session: SessionAttrs;
+}
+
+const KEY = "auth:session:";
+
+/** How long an entry may live: the setting, bounded by the access token's own lifetime. */
+export function cacheTtlSeconds(ctx: Ctx): number {
+  const configured = Number(ctx.config.auth?.cacheTtlSeconds ?? 60);
+  const access = durationSeconds(String(ctx.config.auth?.accessTtl ?? "15m"));
+  return Math.max(0, Math.min(configured, access));
+}
+
+export async function readIdentity(ctx: Ctx, sid: string): Promise<CachedIdentity | null> {
+  if (cacheTtlSeconds(ctx) === 0) return null;
+  return appCache(ctx.Environment).get<CachedIdentity>(KEY + sid);
+}
+
+export async function writeIdentity(ctx: Ctx, sid: string, identity: CachedIdentity): Promise<void> {
+  const ttl = cacheTtlSeconds(ctx);
+  if (ttl === 0) return;
+  await appCache(ctx.Environment).set(KEY + sid, identity, ttl);
+}
+
+/** Forget one session: the next request with its token takes the cold path. */
+export async function forgetSession(ctx: Ctx, sid: string): Promise<void> {
+  await appCache(ctx.Environment).del(KEY + sid);
+}
+
+/**
+ * Forget every session of a user — after a password change, a role
+ * change or a deletion. The sids come from the rows that exist now, so
+ * this runs BEFORE the rows are deleted when both happen.
+ */
+export async function forgetUser(ctx: Ctx, userId: string): Promise<void> {
+  const rows = await ctx.models!.get<{ sid: string }>("Session").find({ user: userId }).select("sid -_id").lean();
+  await Promise.all(rows.map((row) => forgetSession(ctx, row.sid)));
+}
+
+/** `15m`, `1h`, `30d`, `900` (seconds) — the subset of ms/jsonwebtoken durations a TTL is written in. */
+function durationSeconds(value: string): number {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w|y)?\s*$/i.exec(value);
+  if (!match) return 15 * 60;
+  const amount = Number(match[1]);
+  const unit = (match[2] ?? "s").toLowerCase();
+  const factor = { ms: 0.001, s: 1, m: 60, h: 3600, d: 86_400, w: 604_800, y: 31_557_600 }[unit] ?? 1;
+  return Math.floor(amount * factor);
+}

package/templates/app/modules/auth/helpers/tokens.ts

@@ -0,0 +1,329 @@
+import { randomUUID } from "node:crypto";
+import jwt from "jsonwebtoken";
+import type { Request } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+import { currentCredentialVersion } from "./passwords.ts";
+import { forgetSession, forgetUser } from "./session-cache.ts";
+
+import type { SessionDoc } from "./documents.ts";
+
+/**
+ * What a verified token tells us. Roles are never trusted from here.
+ *
+ * `sid` names the session both tokens of a pair belong to; `jti` names the
+ * individual token. The split is what lets an access token find its own
+ * session row, whose refresh jti has meanwhile rotated out from under it.
+ */
+export interface TokenClaims {
+  sub: string;
+  sid: string;
+  jti: string;
+  typ: "access" | "refresh";
+  iat: number;
+  exp: number;
+}
+
+export interface TokenPair {
+  access_token: string;
+  refresh_token: string;
+  expires_in: string;
+}
+
+/** Where a session was started, for the row and for the user to review. */
+export interface SessionOrigin {
+  ip?: string;
+  user_agent?: string;
+}
+
+const secret = (ctx: Ctx, typ: "access" | "refresh"): string =>
+  String(
+    ctx.Environment.get(
+      typ === "access" ? "JWT_ACCESS_SECRET" : "JWT_REFRESH_SECRET",
+    ),
+  );
+
+// Read at signing time, never cached: token policy is a setting an operator
+// changes without a restart.
+const ttl = (ctx: Ctx, typ: "access" | "refresh"): string =>
+  String(typ === "access" ? ctx.config.auth?.accessTtl ?? "15m" : ctx.config.auth?.refreshTtl ?? "30d");
+
+/**
+ * Mint a pair for an existing session.
+ *
+ * The access token deliberately carries no role. Roles change, tokens do
+ * not, and a stale role in a signed token is a privilege bug waiting to
+ * happen — the request pipeline reloads the user instead.
+ */
+function mint(
+  ctx: Ctx,
+  userId: string,
+  sid: string,
+): TokenPair & { refreshJti: string; refreshExp: number } {
+  const refreshJti = randomUUID();
+
+  const access_token = jwt.sign({ typ: "access", sid }, secret(ctx, "access"), {
+    subject: userId,
+    jwtid: randomUUID(),
+    expiresIn: ttl(ctx, "access") as jwt.SignOptions["expiresIn"],
+  });
+
+  const refresh_token = jwt.sign(
+    { typ: "refresh", sid },
+    secret(ctx, "refresh"),
+    {
+      subject: userId,
+      jwtid: refreshJti,
+      expiresIn: ttl(ctx, "refresh") as jwt.SignOptions["expiresIn"],
+    },
+  );
+
+  const { exp } = jwt.decode(refresh_token) as { exp: number };
+  return {
+    access_token,
+    refresh_token,
+    expires_in: ttl(ctx, "access"),
+    refreshJti,
+    refreshExp: exp,
+  };
+}
+
+/** Open a session — a sign-in, from a device worth remembering. */
+export async function startSession(
+  ctx: Ctx,
+  userId: string,
+  credentialVersion: string,
+  origin: SessionOrigin = {},
+): Promise<TokenPair> {
+  const sid = randomUUID();
+  const { refreshJti, refreshExp, ...pair } = mint(ctx, userId, sid);
+
+  await ctx.models!.get("Session").create({
+    sid,
+    user: userId,
+    credential_version: credentialVersion,
+    refresh_jti: refreshJti,
+    ip: origin.ip,
+    user_agent: origin.user_agent,
+    expires_at: new Date(refreshExp * 1000),
+  });
+
+  // A password change may have committed while this insert was in flight.
+  if (!(await loadSession(ctx, sid, userId))) {
+    await endSession(ctx, sid);
+    throw new HttpError(401, "invalidCredentials");
+  }
+
+  return pair;
+}
+
+/**
+ * Each sid is one device's token family. A valid current token rotates it;
+ * a valid superseded token expires it, including all previously issued access.
+ * Both decisions happen in one document write, so reuse cannot race a second
+ * revocation write or leave a newly rotated descendant alive afterward.
+ */
+export async function rotateSession(
+  ctx: Ctx,
+  claims: TokenClaims,
+): Promise<TokenPair | undefined> {
+  // Only verified refresh claims belong here; retain shape/type checks for
+  // custom callers before constructing a query or an aggregation expression.
+  if (!validClaims(claims, "refresh")) return undefined;
+
+  try {
+    const version = await currentCredentialVersion(ctx, claims.sub);
+    if (!version) return undefined;
+
+    const now = new Date();
+    const { refreshJti, refreshExp, ...pair } = mint(
+      ctx,
+      claims.sub,
+      claims.sid,
+    );
+    const current = { $eq: ["$refresh_jti", { $literal: claims.jti }] };
+
+    const previous = await ctx
+      .models!.get<SessionDoc>("Session")
+      .findOneAndUpdate(
+        {
+          sid: claims.sid,
+          user: claims.sub,
+          credential_version: version,
+          expires_at: { $gt: now },
+        },
+        [
+          {
+            $set: {
+              refresh_jti: { $cond: [current, refreshJti, "$refresh_jti"] },
+              // Existing access/session checks already reject this expired family.
+              // Its TTL removes the row later; cleanup timing is not authorization.
+              expires_at: {
+                $cond: [current, new Date(refreshExp * 1000), new Date(0)],
+              },
+              last_seen_at: { $cond: [current, now, "$last_seen_at"] },
+            },
+          },
+        ],
+        {
+          returnDocument: "before",
+          writeConcern: { w: "majority", j: true, wtimeout: 5000 },
+        },
+      );
+
+    // Either branch changed the row — rotated, or expired by reuse — so a
+    // cached copy of it is stale either way; the next request re-reads.
+    if (previous) await forgetSession(ctx, claims.sid);
+
+    // Returning the pre-update row tells us which atomic branch actually ran.
+    // Another replay may revoke this pair before its HTTP response is delivered.
+    return previous?.refresh_jti === claims.jti ? pair : undefined;
+  } catch {
+    // A missing acknowledgment is not proof that MongoDB applied no change.
+    // Never return a pair or claim successful revocation on that uncertain path.
+    throw new HttpError(503, "refreshUnavailable", {
+      code: "REFRESH_UNAVAILABLE",
+      defaultMessage:
+        "The refresh operation could not be acknowledged; sign in again",
+    });
+  }
+}
+
+/** Verify signature, expiry, type and the shape required for scoped session writes. */
+export function verify(
+  ctx: Ctx,
+  token: string,
+  typ: "access" | "refresh",
+): TokenClaims | undefined {
+  try {
+    const claims = jwt.verify(token, secret(ctx, typ));
+    return validClaims(claims, typ) ? claims : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function validClaims(
+  value: unknown,
+  typ: "access" | "refresh",
+): value is TokenClaims {
+  if (!value || typeof value !== "object") return false;
+
+  const claims = value as Record<string, unknown>;
+  const identifier = (value: unknown): value is string =>
+    typeof value === "string" && value.length > 0 && value.length <= 128;
+
+  return (
+    claims.typ === typ &&
+    identifier(claims.sub) &&
+    /^[a-f0-9]{24}$/i.test(claims.sub) &&
+    identifier(claims.sid) &&
+    identifier(claims.jti) &&
+    typeof claims.iat === "number" &&
+    Number.isSafeInteger(claims.iat) &&
+    typeof claims.exp === "number" &&
+    Number.isSafeInteger(claims.exp) &&
+    claims.iat >= 0 &&
+    claims.exp > claims.iat
+  );
+}
+
+/** A live session owned by the token subject. TTL cleanup is not authorization. */
+export async function loadSession(
+  ctx: Ctx,
+  sid: string,
+  userId: string,
+): Promise<SessionDoc | null> {
+  const version = await currentCredentialVersion(ctx, userId);
+  if (!version) return null;
+
+  return ctx.models!.get<SessionDoc>("Session").findOne({
+    sid,
+    user: userId,
+    credential_version: version,
+    expires_at: { $gt: new Date() },
+  });
+}
+
+/**
+ * Record that a session is still in use — at most once per `afterSeconds`,
+ * because a write on every request would cost more than the field is
+ * worth. Returns whether it wrote, so a cached copy can follow.
+ */
+export async function touchSession(
+  ctx: Ctx,
+  session: SessionDoc,
+  afterSeconds: number,
+): Promise<boolean> {
+  const age = Date.now() - (session.last_seen_at?.getTime() ?? 0);
+  if (age < afterSeconds * 1000) return false;
+
+  const now = new Date();
+  session.last_seen_at = now;
+  await ctx
+    .models!.get("Session")
+    .updateOne({ sid: session.sid }, { last_seen_at: now });
+  return true;
+}
+
+/** End one session: the refresh half dies with its row, and its cached identity with it. */
+export async function endSession(ctx: Ctx, sid: string): Promise<boolean> {
+  await forgetSession(ctx, sid);
+  const result = await ctx.models!.get("Session").deleteOne({ sid });
+  return result.deletedCount === 1;
+}
+
+/** Blacklist an access token for whatever is left of its lifetime. */
+export async function revokeAccess(
+  ctx: Ctx,
+  claims: TokenClaims,
+): Promise<void> {
+  await forgetSession(ctx, claims.sid);
+  await ctx
+    .models!.get("RevokedToken")
+    .updateOne(
+      { jti: claims.jti },
+      {
+        $setOnInsert: {
+          jti: claims.jti,
+          expires_at: new Date(claims.exp * 1000),
+        },
+      },
+      { upsert: true },
+    );
+}
+
+export async function isRevoked(ctx: Ctx, jti: string): Promise<boolean> {
+  return (
+    (await ctx.models!.get("RevokedToken").countDocuments({ jti }).limit(1)) > 0
+  );
+}
+
+/** Drop stored sessions for a user; this alone does not block concurrent sign-ins. */
+export async function endAllSessions(ctx: Ctx, userId: string): Promise<void> {
+  await forgetUser(ctx, userId);
+  await ctx.models!.get("Session").deleteMany({ user: userId });
+}
+
+/** Active devices, newest first, including when expired rows await TTL cleanup. */
+export async function listSessions(
+  ctx: Ctx,
+  userId: string,
+): Promise<SessionDoc[]> {
+  const version = await currentCredentialVersion(ctx, userId);
+  if (!version) return [];
+
+  return ctx
+    .models!.get<SessionDoc>("Session")
+    .find({
+      user: userId,
+      credential_version: version,
+      expires_at: { $gt: new Date() },
+    })
+    .sort({ created_at: -1 });
+}
+
+/** Where a request came from, for the session row. */
+export function originOf(req: Request): SessionOrigin {
+  return { ip: req.ip, user_agent: req.header("user-agent") };
+}