@crombolo/auth 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "OAuth2 authorization server, password hashing, cookies and member tickets for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.10.0",
-    "@crombolo/data": "0.10.0"
+    "@crombolo/core": "0.11.0",
+    "@crombolo/data": "0.11.0"
   }
 }

package/src/routes.ts

@@ -17,6 +17,7 @@ import {
 } from './cookies.ts'
 import type { AuthService } from './service.ts'
 import { BACKOFFICE_CLIENT_ID, DEFAULT_SCOPE } from './service.ts'
+import type { UserRow } from './store.ts'
 
 export const SECURITY_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office`
 
@@ -24,6 +25,17 @@ export interface AuthRouteOptions {
   backOfficePath: string
   service: AuthService
   cookies: CookieOptions
+  /** Told about every sign-in, failed sign-in and sign-out, for the audit log. */
+  onAudit?: (event: AuthAuditEvent, request: Request) => Promise<void>
+}
+
+export interface AuthAuditEvent {
+  action: 'SignIn' | 'SignInFailed' | 'LockedOut' | 'SignOut'
+  /** Absent when the login named nobody. */
+  user?: Pick<UserRow, 'key' | 'userName'>
+  /** The login that was tried, for a failure that names nobody. */
+  login?: string
+  detail?: string
 }
 
 export interface AuthRoutes {
@@ -47,6 +59,8 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
   const names = cookieNames(options.cookies)
   const secure = options.cookies.securePrefix
   const { service } = options
+  const audit = (event: AuthAuditEvent, request: Request) =>
+    options.onAudit?.(event, request) ?? Promise.resolve()
 
   const expectedRedirectUri = (origin: string) =>
     `${origin}${options.backOfficePath}/oauth_complete`
@@ -144,7 +158,14 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
     // API users: a machine client presents its own id and secret and gets a bearer token back
     if (grantType === 'client_credentials') {
       const issued = await service.clientCredentials(clientId, form.get('client_secret') ?? '')
-      if (!issued.ok) return oauthError(issued.error, issued.description, 401)
+      if (!issued.ok) {
+        await audit(
+          { action: 'SignInFailed', login: clientId, detail: 'Client credentials refused' },
+          request,
+        )
+        return oauthError(issued.error, issued.description, 401)
+      }
+      await audit({ action: 'SignIn', user: issued.user, detail: 'Client credentials' }, request)
       return Response.json({
         access_token: issued.accessToken,
         token_type: 'Bearer',
@@ -262,6 +283,29 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       request.headers.get('x-forwarded-for') ?? undefined,
     )
 
+    if (result.status === 'success') await audit({ action: 'SignIn', user: result.user }, request)
+    else if (result.status === 'invalid') {
+      await audit(
+        result.user
+          ? { action: 'SignInFailed', user: result.user, detail: 'Wrong password' }
+          : { action: 'SignInFailed', login: username, detail: 'No such user' },
+        request,
+      )
+      if (result.lockedOut && result.user)
+        await audit(
+          { action: 'LockedOut', user: result.user, detail: 'Too many failed attempts' },
+          request,
+        )
+    } else if (result.status === 'notAllowed')
+      await audit(
+        {
+          action: 'SignInFailed',
+          ...(result.user ? { user: result.user } : { login: username }),
+          detail: result.reason === 'notApproved' ? 'Account disabled' : 'Account locked',
+        },
+        request,
+      )
+
     // Status codes the login UI branches on: 401 invalid, 402 needs 2FA,
     // 403 locked or not approved.
     if (result.status === 'invalid') {
@@ -296,7 +340,8 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
   async function handleRevoke(request: Request): Promise<Response> {
     const form = new URLSearchParams(await request.text())
     const token = resolveRedacted(form.get('token'), readCookie(request, names.accessToken))
-    if (token) await service.revokeAccessToken(token)
+    const revoked = token ? await service.revokeAccessToken(token) : undefined
+    if (revoked) await audit({ action: 'SignOut', user: revoked }, request)
     const response = new Response(null, { status: 200 })
     for (const cookie of clearedCookies()) response.headers.append('set-cookie', cookie)
     return response
@@ -304,7 +349,8 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
 
   async function handleSignOut(request: Request, url: URL): Promise<Response> {
     const sessionId = readCookie(request, names.session)
-    if (sessionId) await service.signOut(sessionId)
+    const ended = sessionId ? await service.signOut(sessionId) : undefined
+    if (ended) await audit({ action: 'SignOut', user: ended }, request)
 
     const requested = url.searchParams.get('post_logout_redirect_uri')
     const allowed = `${url.origin}${options.backOfficePath}/logout`

package/src/service.ts

@@ -38,11 +38,15 @@ export const DEFAULT_AUTH_SETTINGS: AuthSettings = {
   maxFailedLoginAttempts: 10,
 }
 
+/**
+ * `user` on a refusal is for the audit log only, and never reaches the response:
+ * the status alone is what the sign-in page may learn.
+ */
 export type LoginResult =
   | { status: 'success'; user: UserRow; sessionId: string }
-  | { status: 'invalid' }
+  | { status: 'invalid'; user?: UserRow; lockedOut?: boolean }
   | { status: 'twoFactorRequired'; providers: string[] }
-  | { status: 'notAllowed'; reason: 'disabled' | 'lockedOut' | 'notApproved' }
+  | { status: 'notAllowed'; reason: 'disabled' | 'lockedOut' | 'notApproved'; user?: UserRow }
 
 export interface AuthorizationRequest {
   clientId: string
@@ -125,22 +129,20 @@ export class AuthService {
       // this path costing what the others cost.
       if (user.isLockedOut) {
         await verifyPassword(password, await DUMMY_HASH_PROMISE)
-        return { status: 'notAllowed', reason: 'lockedOut' } as const
+        return { status: 'notAllowed', reason: 'lockedOut', user } as const
       }
       if (!(await verifyPassword(password, user.passwordHash))) {
         const attempts = await this.#store.recordLoginFailure(user.id)
-        if (
+        const lockedOut =
           this.#settings.maxFailedLoginAttempts > 0 &&
           attempts >= this.#settings.maxFailedLoginAttempts
-        ) {
-          await this.#store.lockOut(user.id)
-        }
-        return { status: 'invalid' } as const
+        if (lockedOut) await this.#store.lockOut(user.id)
+        return { status: 'invalid', user, lockedOut } as const
       }
       // `isApproved` stays behind the password on purpose: it is not a state an
       // attacker can induce, so answering it only to whoever knows the password
       // discloses strictly less than checking it up front.
-      if (!user.isApproved) return { status: 'notAllowed', reason: 'notApproved' } as const
+      if (!user.isApproved) return { status: 'notAllowed', reason: 'notApproved', user } as const
 
       const sessionId = crypto.randomUUID()
       await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
@@ -247,7 +249,7 @@ export class AuthService {
     clientId: string,
     secret: string,
   ): Promise<
-    | { ok: true; accessToken: string; expiresIn: number; issuedAt: number }
+    | { ok: true; accessToken: string; expiresIn: number; issuedAt: number; user: UserRow }
     | { ok: false; error: TokenError; description: string }
   > {
     const credential = await this.#store.findClientCredential(clientId)
@@ -273,6 +275,7 @@ export class AuthService {
       accessToken,
       expiresIn: this.#settings.accessTokenSeconds,
       issuedAt: Math.floor(now / 1000),
+      user,
     }
   }
 
@@ -301,13 +304,18 @@ export class AuthService {
     return this.#store.findSession(sessionId)
   }
 
-  async signOut(sessionId: string): Promise<void> {
+  /** Ends the session, and returns whose it was while it was still open. */
+  async signOut(sessionId: string): Promise<UserRow | undefined> {
+    const session = await this.#store.findSession(sessionId)
+    const user = session ? await this.#store.findUserById(session.userId) : undefined
     await this.#store.endSession(sessionId)
+    return user
   }
 
-  async revokeAccessToken(accessToken: string): Promise<void> {
+  async revokeAccessToken(accessToken: string): Promise<UserRow | undefined> {
     const token = await this.#store.findToken(accessToken, 'access')
-    if (token) await this.#store.endSession(token.sessionId)
+    if (!token) return undefined
+    return this.signOut(token.sessionId)
   }
 
   async #issue(