@byline/admin 5.0.0 → 5.1.0

package/src/modules/auth/jwt-session-provider.ts

@@ -11,22 +11,26 @@ import { createHash, randomBytes, randomUUID } from 'node:crypto'
 import {
   type AccessTokenPayload,
   type AdminAuth,
+  ERR_ACCESS_EXPIRED,
   ERR_ACCOUNT_DISABLED,
   ERR_INVALID_CREDENTIALS,
   ERR_INVALID_TOKEN,
   ERR_REVOKED_TOKEN,
+  ERR_SESSION_CHANGED,
   type RefreshSessionArgs,
+  type RevokeSessionArgs,
   type SessionProvider,
   type SessionProviderCapabilities,
   type SessionTokens,
   type SignInResult,
   type SignInWithPasswordArgs,
 } from '@byline/auth'
-import { jwtVerify, SignJWT } from 'jose'
+import { passwordSignInSchema } from '@byline/core/validation'
+import { compactVerify, jwtVerify, SignJWT } from 'jose'
 import { v7 as uuidv7 } from 'uuid'
 
 import { verifyPassword } from './password.js'
-import { resolveActor } from './resolve-actor.js'
+import { resolveActor, resolveActorFromUser } from './resolve-actor.js'
 import type { AdminStore } from '../../store.js'
 
 const DEFAULT_ISSUER = 'byline'
@@ -39,7 +43,13 @@ const CAPABILITIES: SessionProviderCapabilities = {
   sso: false,
 }
 
+export interface NativeSessionEvent {
+  type: 'refresh_attempted' | 'refresh_completed' | 'refresh_contested'
+}
+
 export interface JwtSessionProviderConfig {
+  /** Best-effort, token-free renewal telemetry. Errors never change authentication outcomes. */
+  onEvent?: (event: NativeSessionEvent) => void
   /**
    * Adapter-backed admin repositories. Construct via the DB adapter's
    * admin-store factory (e.g. `createAdminStore(db)` from
@@ -68,6 +78,7 @@ export interface JwtSessionProviderConfig {
 export class JwtSessionProvider implements SessionProvider {
   public readonly capabilities = CAPABILITIES
 
+  readonly #onEvent?: (event: NativeSessionEvent) => void
   readonly #store: AdminStore
   readonly #signingKey: Uint8Array
   readonly #issuer: string
@@ -76,6 +87,7 @@ export class JwtSessionProvider implements SessionProvider {
   readonly #now: () => Date
 
   constructor(config: JwtSessionProviderConfig) {
+    this.#onEvent = config.onEvent
     this.#store = config.store
     this.#signingKey =
       typeof config.signingSecret === 'string'
@@ -97,18 +109,19 @@ export class JwtSessionProvider implements SessionProvider {
   // -----------------------------------------------------------------------
 
   async signInWithPassword(args: SignInWithPasswordArgs): Promise<SignInResult> {
+    const credentials = passwordSignInSchema.parse(args)
     const users = this.#store.adminUsers
-    const row = await users.getByEmailForSignIn(args.email)
+    const row = await users.getByEmailForSignIn(credentials.email)
 
     // Uniform error response for unknown email vs. wrong password — don't
     // leak which one. Still do a real verify against a dummy hash so the
     // timing is comparable; the argon2 cost dominates regardless.
     if (!row) {
-      await verifyPassword(args.password, DUMMY_HASH_FOR_TIMING)
+      await verifyPassword(credentials.password, DUMMY_HASH_FOR_TIMING)
       throw ERR_INVALID_CREDENTIALS({ message: 'invalid credentials' })
     }
 
-    const ok = await verifyPassword(args.password, row.password_hash)
+    const ok = await verifyPassword(credentials.password, row.password_hash)
     if (!ok) {
       await users.recordLoginFailure(row.id)
       throw ERR_INVALID_CREDENTIALS({ message: 'invalid credentials' })
@@ -118,110 +131,204 @@ export class JwtSessionProvider implements SessionProvider {
       throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
     }
 
-    await users.recordLoginSuccess(row.id, args.ip ?? null)
-
-    const actor = await resolveActor(this.#store, row.id)
-    // resolveActor also checks is_enabled, but we just recorded success
-    // above, so null here would indicate a race (the account was disabled
-    // between the check and the resolve). Treat as disabled.
-    if (!actor) {
-      throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
-    }
-
-    const tokens = await this.#issueTokens({
-      adminUserId: row.id,
-      ip: args.ip ?? null,
-      userAgent: args.userAgent ?? null,
+    const previous = await this.#observedLogins(args)
+    const withLocks = <T>(work: (store: AdminStore) => Promise<T>) =>
+      previous.length
+        ? this.#store.withSessionLocks(
+            [row.id, ...previous.map((login) => login.admin_user_id)],
+            work
+          )
+        : this.#store.withSessionLock(row.id, (store) => work(store))
+    return withLocks(async (store) => {
+      const current = await store.adminUsers.getByIdForSignIn(row.id)
+      if (!current?.is_enabled) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+      // Password verification is deliberately outside the lock. Revalidate
+      // both the credential and generation before issuing under that lock.
+      if (
+        current.password_hash !== row.password_hash ||
+        current.session_version !== row.session_version
+      ) {
+        throw ERR_INVALID_CREDENTIALS({ message: 'credentials changed during sign-in' })
+      }
+      for (const observed of previous) {
+        const login = await store.loginSessions.findById(observed.id)
+        if (login && login.admin_user_id === observed.admin_user_id) {
+          await store.loginSessions.revoke(login.id, this.#now())
+        }
+      }
+      await store.adminUsers.recordLoginSuccess(row.id, args.ip ?? null)
+      const actor = await resolveActorFromUser(store, current)
+      if (!actor) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+      const tokens = await this.#issueTokens(store, {
+        adminUserId: row.id,
+        sessionVersion: current.session_version,
+        ip: args.ip ?? null,
+        userAgent: args.userAgent ?? null,
+      })
+      return { ...tokens, actor }
     })
-
-    return { ...tokens, actor }
   }
 
-  async verifyAccessToken(token: string): Promise<{ actor: AdminAuth }> {
+  async verifyAccessToken(token: string): Promise<{ actor: AdminAuth; sessionId: string }> {
     let payload: AccessTokenPayload
     try {
       const result = await jwtVerify<AccessTokenPayload>(token, this.#signingKey, {
         issuer: this.#issuer,
+        algorithms: ['HS256'],
+        currentDate: this.#now(),
+        requiredClaims: ['sub', 'iat', 'exp', 'jti', 'sv', 'sid'],
       })
       payload = result.payload
     } catch (err) {
+      if (err instanceof Error && 'code' in err && err.code === 'ERR_JWT_EXPIRED') {
+        throw ERR_ACCESS_EXPIRED({ message: 'access token expired' })
+      }
       throw ERR_INVALID_TOKEN({ message: 'access token verification failed', cause: err })
     }
 
-    if (payload.typ !== 'access') {
+    if (
+      payload.typ !== 'access' ||
+      typeof payload.sub !== 'string' ||
+      !validSid(payload.sid) ||
+      !Number.isSafeInteger(payload.sv) ||
+      payload.sv < 0
+    ) {
       throw ERR_INVALID_TOKEN({ message: 'unexpected token type' })
     }
 
-    const actor = await resolveActor(this.#store, payload.sub)
-    if (!actor) {
-      // The token was valid but the user is now disabled or deleted.
+    const current = await this.#store.adminUsers.getByIdForSignIn(payload.sub)
+    if (!current?.is_enabled) {
       throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
     }
-
-    return { actor }
+    if (current.session_version !== payload.sv) {
+      throw ERR_REVOKED_TOKEN({ message: 'account session generation changed' })
+    }
+    const login = await this.#store.loginSessions.findById(payload.sid)
+    if (
+      !login ||
+      login.admin_user_id !== payload.sub ||
+      login.session_version !== payload.sv ||
+      login.revoked_at != null ||
+      login.expires_at.getTime() <= this.#now().getTime()
+    ) {
+      throw ERR_REVOKED_TOKEN({ message: 'login revoked or expired' })
+    }
+    const actor = await resolveActorFromUser(this.#store, current)
+    if (!actor) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
+    return { actor, sessionId: payload.sid }
   }
 
   async refreshSession(args: RefreshSessionArgs): Promise<SessionTokens> {
-    const refreshTokens = this.#store.refreshTokens
+    this.#emit('refresh_attempted')
     const hash = hashToken(args.refreshToken)
-    const row = await refreshTokens.findByHash(hash)
-
-    if (!row) {
-      throw ERR_INVALID_TOKEN({ message: 'refresh token not recognised' })
-    }
-
-    const now = this.#now()
-
-    // Already revoked?
-    if (row.revoked_at != null) {
-      if (row.rotated_to_id != null) {
-        // Rotated token replayed — the chain is compromised. Revoke every
-        // descendant so the attacker and the legitimate holder are both
-        // signed out.
-        await refreshTokens.revokeChain(row.id, now)
-        throw ERR_REVOKED_TOKEN({
-          message: 'refresh token was already rotated — chain revoked',
+    const observed = await this.#store.refreshTokens.findByHash(hash)
+    if (!observed) throw ERR_INVALID_TOKEN({ message: 'refresh token not recognised' })
+
+    const outcome = await this.#store.withSessionLock(
+      observed.admin_user_id,
+      async (store, user) => {
+        if (!user?.is_enabled)
+          throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
+        const refreshTokens = store.refreshTokens
+        const row = await refreshTokens.findByHash(hash)
+        if (!row) throw ERR_INVALID_TOKEN({ message: 'refresh token not recognised' })
+        const now = this.#now()
+        const login = row.sid ? await store.loginSessions.findById(row.sid) : null
+        if (
+          !login ||
+          login.admin_user_id !== user.id ||
+          login.session_version !== user.session_version ||
+          login.revoked_at != null
+        ) {
+          throw ERR_REVOKED_TOKEN({ message: 'login revoked' })
+        }
+        if (args.expectedSessionId && args.expectedSessionId !== login.id) {
+          throw ERR_SESSION_CHANGED({ message: 'session changed before renewal' })
+        }
+        if (row.revoked_at != null) {
+          if (row.rotated_to_id != null) {
+            await store.loginSessions.revoke(login.id, now)
+            await refreshTokens.revokeChain(row.id, now)
+          }
+          // Return the error so replay revocation commits before it is thrown.
+          // Strict replay revokes this login even if the replayed row is also expired.
+          return {
+            contested: row.rotated_to_id != null,
+            error: ERR_REVOKED_TOKEN({ message: 'refresh token has been revoked' }),
+          }
+        }
+        if (row.session_version !== user.session_version) {
+          throw ERR_REVOKED_TOKEN({ message: 'account session generation changed' })
+        }
+        // Preserve the terminal expiry classification for an ordinary aged-out login.
+        // Explicit revocation/replay and generation changes above retain precedence.
+        if (
+          row.expires_at.getTime() <= now.getTime() ||
+          login.expires_at.getTime() <= now.getTime()
+        ) {
+          throw ERR_INVALID_TOKEN({ message: 'refresh token expired' })
+        }
+        const newId = uuidv7()
+        const newRefreshPlain = generateOpaqueToken()
+        const refreshExpiresAt = new Date(now.getTime() + this.#refreshTtl * 1000)
+        await refreshTokens.issue({
+          id: newId,
+          admin_user_id: row.admin_user_id,
+          token_hash: hashToken(newRefreshPlain),
+          session_version: user.session_version,
+          sid: login.id,
+          expires_at: refreshExpiresAt,
+          user_agent: args.userAgent ?? null,
+          ip: args.ip ?? null,
         })
+        await store.loginSessions.extend(login.id, refreshExpiresAt)
+        await refreshTokens.markRotated(row.id, newId, now)
+        const accessToken = await this.#signAccessToken(
+          row.admin_user_id,
+          user.session_version,
+          login.id,
+          now
+        )
+        return {
+          tokens: {
+            sessionId: login.id,
+            accessToken,
+            refreshToken: newRefreshPlain,
+            accessTokenExpiresAt: new Date(now.getTime() + this.#accessTtl * 1000),
+            refreshTokenExpiresAt: refreshExpiresAt,
+          },
+        }
       }
-      throw ERR_REVOKED_TOKEN({ message: 'refresh token has been revoked' })
-    }
-
-    if (row.expires_at.getTime() <= now.getTime()) {
-      throw ERR_INVALID_TOKEN({ message: 'refresh token expired' })
+    )
+    if ('error' in outcome) {
+      if (outcome.contested) this.#emit('refresh_contested')
+      throw outcome.error
     }
+    this.#emit('refresh_completed')
+    return outcome.tokens
+  }
 
-    // Rotate: mint a new token, mark the old one rotated_to the new id.
-    const newId = uuidv7()
-    const newRefreshPlain = generateOpaqueToken()
-    const newRefreshHash = hashToken(newRefreshPlain)
-    const refreshExpiresAt = new Date(now.getTime() + this.#refreshTtl * 1000)
-
-    await refreshTokens.issue({
-      id: newId,
-      admin_user_id: row.admin_user_id,
-      token_hash: newRefreshHash,
-      expires_at: refreshExpiresAt,
-      user_agent: args.userAgent ?? null,
-      ip: args.ip ?? null,
+  async revokeSession(args: RevokeSessionArgs): Promise<void> {
+    const logins = await this.#observedLogins({
+      previousAccessToken: args.accessToken,
+      previousRefreshToken: args.refreshToken,
     })
-    await refreshTokens.markRotated(row.id, newId, now)
-
-    const accessToken = await this.#signAccessToken(row.admin_user_id, now)
-    const accessExpiresAt = new Date(now.getTime() + this.#accessTtl * 1000)
-
-    return {
-      accessToken,
-      refreshToken: newRefreshPlain,
-      accessTokenExpiresAt: accessExpiresAt,
-      refreshTokenExpiresAt: refreshExpiresAt,
+    if (args.expectedSessionId && logins.some((login) => login.id !== args.expectedSessionId))
+      throw ERR_SESSION_CHANGED({ message: 'session changed before logout' })
+    for (const login of logins) {
+      await this.#store.withSessionLock(login.admin_user_id, async (store) => {
+        await store.loginSessions.revoke(login.id, this.#now())
+      })
+    }
+    // Also retire a known legacy refresh row. Native rows are denied by login validity.
+    if (args.refreshToken) {
+      const row = await this.#store.refreshTokens.findByHash(hashToken(args.refreshToken))
+      if (row) {
+        await this.#store.withSessionLock(row.admin_user_id, async (store) => {
+          await store.refreshTokens.revokeChain(row.id, this.#now())
+        })
+      }
     }
-  }
-
-  async revokeSession(refreshToken: string): Promise<void> {
-    const refreshTokens = this.#store.refreshTokens
-    const row = await refreshTokens.findByHash(hashToken(refreshToken))
-    if (!row) return // Idempotent — unknown tokens are a no-op.
-    await refreshTokens.revoke(row.id, this.#now())
   }
 
   async resolveActor(adminUserId: string): Promise<AdminAuth | null> {
@@ -232,30 +339,96 @@ export class JwtSessionProvider implements SessionProvider {
   // Internals
   // -----------------------------------------------------------------------
 
-  async #issueTokens(input: {
-    adminUserId: string
-    ip: string | null
-    userAgent: string | null
-  }): Promise<SessionTokens> {
-    const now = this.#now()
-    const refreshTokens = this.#store.refreshTokens
+  #emit(type: NativeSessionEvent['type']) {
+    try {
+      this.#onEvent?.({ type })
+    } catch {
+      /* Telemetry is not an authentication dependency. */
+    }
+  }
+
+  async #observedLogins(
+    args: Pick<SignInWithPasswordArgs, 'previousAccessToken' | 'previousRefreshToken'>
+  ) {
+    const ids = new Set<string>()
+    if (args.previousAccessToken) {
+      let claims: Record<string, unknown> | undefined
+      try {
+        const verified = await compactVerify(args.previousAccessToken, this.#signingKey, {
+          algorithms: ['HS256'],
+        })
+        claims = JSON.parse(new TextDecoder().decode(verified.payload))
+      } catch {
+        /* An invalid credential supplies no revocation authority. */
+      }
+      if (
+        claims?.iss === this.#issuer &&
+        claims.typ === 'access' &&
+        validSid(claims.sid) &&
+        typeof claims.sub === 'string'
+      ) {
+        const login = await this.#store.loginSessions.findById(claims.sid)
+        if (login?.admin_user_id === claims.sub) ids.add(login.id)
+      }
+    }
+    if (args.previousRefreshToken) {
+      const token = await this.#store.refreshTokens.findByHash(hashToken(args.previousRefreshToken))
+      if (token?.sid) {
+        const login = await this.#store.loginSessions.findById(token.sid)
+        if (login?.admin_user_id === token.admin_user_id) ids.add(login.id)
+      }
+    }
+    const result = []
+    for (const id of ids) {
+      const login = await this.#store.loginSessions.findById(id)
+      if (login) result.push(login)
+    }
+    return result
+  }
 
-    const accessToken = await this.#signAccessToken(input.adminUserId, now)
+  async #issueTokens(
+    store: AdminStore,
+    input: {
+      sessionVersion: number
+      adminUserId: string
+      ip: string | null
+      userAgent: string | null
+    }
+  ): Promise<SessionTokens> {
+    const now = this.#now()
+    const refreshTokens = store.refreshTokens
+
+    const sessionId = randomUUID()
+    const accessToken = await this.#signAccessToken(
+      input.adminUserId,
+      input.sessionVersion,
+      sessionId,
+      now
+    )
     const accessExpiresAt = new Date(now.getTime() + this.#accessTtl * 1000)
 
     const refreshPlain = generateOpaqueToken()
     const refreshHash = hashToken(refreshPlain)
     const refreshExpiresAt = new Date(now.getTime() + this.#refreshTtl * 1000)
+    await store.loginSessions.create({
+      id: sessionId,
+      admin_user_id: input.adminUserId,
+      session_version: input.sessionVersion,
+      expires_at: refreshExpiresAt,
+    })
     await refreshTokens.issue({
       id: uuidv7(),
       admin_user_id: input.adminUserId,
       token_hash: refreshHash,
+      session_version: input.sessionVersion,
+      sid: sessionId,
       expires_at: refreshExpiresAt,
       user_agent: input.userAgent,
       ip: input.ip,
     })
 
     return {
+      sessionId,
       accessToken,
       refreshToken: refreshPlain,
       accessTokenExpiresAt: accessExpiresAt,
@@ -263,10 +436,15 @@ export class JwtSessionProvider implements SessionProvider {
     }
   }
 
-  async #signAccessToken(adminUserId: string, now: Date): Promise<string> {
+  async #signAccessToken(
+    adminUserId: string,
+    sessionVersion: number,
+    sessionId: string,
+    now: Date
+  ): Promise<string> {
     const iat = Math.floor(now.getTime() / 1000)
     const exp = iat + this.#accessTtl
-    return new SignJWT({ typ: 'access' })
+    return new SignJWT({ typ: 'access', sv: sessionVersion, sid: sessionId })
       .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
       .setSubject(adminUserId)
       .setIssuer(this.#issuer)
@@ -299,3 +477,10 @@ function hashToken(token: string): string {
  */
 const DUMMY_HASH_FOR_TIMING =
   '$argon2id$v=19$m=19456,t=2,p=1$c2lkZS1jaGFubmVsLW1pdGlnYXRpb24$0Hqf2vQKZqSfZZ4nJRr7K5IOjn9ngjzaQjV+yTG6iNY'
+
+function validSid(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+  )
+}

package/src/modules/auth/login-sessions-repository.ts

@@ -0,0 +1,25 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/** Native JWT login membership. This is not a browser binding or a bearer credential store. */
+export interface LoginSessionRow {
+  id: string
+  admin_user_id: string
+  session_version: number
+  expires_at: Date
+  revoked_at: Date | null
+}
+
+export interface LoginSessionsRepository {
+  /** All writes run under the owning account lock, through its scoped store. */
+  create(input: Omit<LoginSessionRow, 'revoked_at'>): Promise<void>
+  findById(id: string): Promise<LoginSessionRow | null>
+  extend(id: string, expiresAt: Date): Promise<void>
+  revoke(id: string, at?: Date): Promise<void>
+  revokeAllForUser(adminUserId: string, at?: Date): Promise<void>
+}

package/src/modules/auth/refresh-tokens-repository.ts

@@ -21,6 +21,9 @@ export interface RefreshTokenRow {
   id: string
   admin_user_id: string
   token_hash: string
+  /** Null only for legacy rows, which cannot authorize native sessions. */
+  sid: string | null
+  session_version: number
   issued_at: Date
   expires_at: Date
   revoked_at: Date | null
@@ -31,9 +34,13 @@ export interface RefreshTokenRow {
 }
 
 export interface IssueRefreshTokenInput {
+  /** Omitted only by legacy fixtures/imports; never accepted for native renewal. */
+  sid?: string | null
   id: string
   admin_user_id: string
   token_hash: string
+  /** Account generation observed under the native issuance lock. */
+  session_version: number
   expires_at: Date
   user_agent?: string | null
   ip?: string | null
@@ -47,19 +54,15 @@ export interface RefreshTokensRepository {
   /** Stamp `last_used_at` for observability. */
   touch(id: string, at?: Date): Promise<void>
   /**
-   * Atomically revoke `oldId` and set its `rotated_to_id` to `newId`.
-   * Caller is responsible for inserting the new row (via `issue`) before
-   * calling this — ordering is a contract.
+   * Revoke `oldId` and set its `rotated_to_id` to `newId`. This is not
+   * independently a compare-and-swap. Native callers must hold the account
+   * lock, reread the predecessor, and insert the successor before this write,
+   * all through the same `withSessionLock` transaction.
    */
   markRotated(oldId: string, newId: string, at?: Date): Promise<void>
   /** Revoke a single token. Idempotent. */
   revoke(id: string, at?: Date): Promise<void>
-  /**
-   * Walk the rotation chain starting at `startId` and revoke every token
-   * in it. Called when a rotated token is replayed — indicates the chain
-   * has been compromised and every descendant is suspect. Returns the
-   * number of rows touched.
-   */
+  /** Revoke all refresh rows sharing the start member's sid, without traversal. */
   revokeChain(startId: string, at?: Date): Promise<number>
   /** Revoke every non-revoked token for a user. Used on password change / sign-out everywhere. */
   revokeAllForUser(adminUserId: string, at?: Date): Promise<number>

package/src/modules/auth/resolve-actor.ts

@@ -9,6 +9,7 @@
 import { AdminAuth } from '@byline/auth'
 
 import type { AdminStore } from '../../store.js'
+import type { AdminUserRow } from '../admin-users/repository.js'
 
 /**
  * Build an `AdminAuth` from a user id by reading the admin-users row and
@@ -29,10 +30,18 @@ export async function resolveActor(
   adminUserId: string
 ): Promise<AdminAuth | null> {
   const user = await store.adminUsers.getById(adminUserId)
+  return resolveActorFromUser(store, user)
+}
+
+/** Internal helper: reuse the account snapshot already checked by native authentication. */
+export async function resolveActorFromUser(
+  store: AdminStore,
+  user: AdminUserRow | null
+): Promise<AdminAuth | null> {
   if (!user) return null
   if (!user.is_enabled) return null
 
-  const abilities = await store.adminPermissions.listAbilitiesForUser(adminUserId)
+  const abilities = await store.adminPermissions.listAbilitiesForUser(user.id)
 
   return new AdminAuth({
     id: user.id,