@crombolo/auth 0.10.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "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.12.1",
+    "@crombolo/data": "0.12.1"
   }
 }

package/src/index.ts

@@ -6,3 +6,4 @@ export * from './pkce.ts'
 export * from './routes.ts'
 export * from './service.ts'
 export * from './store.ts'
+export * from './umbraco-passwords.ts'

package/src/password.ts

@@ -1,11 +1,11 @@
 /**
- * Password hashing.
- *
- * Umbraco stores ASP.NET Core Identity v3 hashes (PBKDF2-HMAC-SHA512). We are not
- * reading existing Umbraco databases, so we use argon2id instead, and keep the
- * `password_config` marker column so the algorithm is recorded per row and can be
- * rotated later exactly as Umbraco rotates its legacy formats.
+ * Password hashing: argon2id, with the algorithm recorded per row in
+ * `password_config`. A hash imported from Umbraco (story 071) is verified in
+ * its own format (`umbraco-passwords.ts`) and replaced with argon2id on the
+ * first successful sign-in, as Umbraco rotates its legacy formats.
  */
+import { verifyUmbracoPassword } from './umbraco-passwords.ts'
+
 export const PASSWORD_ALGORITHM = 'ARGON2ID'
 
 export interface PasswordConfig {
@@ -19,12 +19,23 @@ export async function hashPassword(password: string): Promise<string> {
   return Bun.password.hash(password, { algorithm: 'argon2id' })
 }
 
+/** Whether a stored hash is crombolo's own; anything else is replaced on a successful sign-in. Pure. */
+export const isNativeHash = (hash: string | null | undefined): boolean =>
+  typeof hash === 'string' && hash.startsWith('$argon2')
+
 /**
  * Verifies a password. Returns false rather than throwing for a malformed or
- * absent hash, so a user row with no password simply cannot sign in.
+ * absent hash, so a user row with no password simply cannot sign in. A hash
+ * that is not argon2id is tried as Umbraco's, by its `passwordConfig`.
  */
-export async function verifyPassword(password: string, hash: string | null): Promise<boolean> {
+export async function verifyPassword(
+  password: string,
+  hash: string | null,
+  imported: { passwordConfig?: string | null; forMember?: boolean } = {},
+): Promise<boolean> {
   if (!hash) return false
+  if (!isNativeHash(hash))
+    return verifyUmbracoPassword(password, hash, imported.passwordConfig, imported.forMember)
   try {
     return await Bun.password.verify(password, hash)
   } catch {

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

@@ -3,7 +3,7 @@
  * actually sends. See docs/backoffice-hosting.md for the wire contract.
  */
 import { type ExtensionSectionAlias, type SectionAlias, toSectionAliases } from '@crombolo/core'
-import { hashPassword, passwordConfigJson, verifyPassword } from './password.ts'
+import { hashPassword, isNativeHash, passwordConfigJson, verifyPassword } from './password.ts'
 import { type CodeChallengeMethod, generateToken, verifyChallenge } from './pkce.ts'
 import type { AuthStore, UserRow } from './store.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,31 @@ 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))) {
+      if (
+        !(await verifyPassword(password, user.passwordHash, {
+          passwordConfig: user.passwordConfig,
+        }))
+      ) {
         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
+      // An imported Umbraco hash is replaced now the password is known to match it.
+      if (!isNativeHash(user.passwordHash))
+        await this.#store.rehashPassword(
+          user.id,
+          await hashPassword(password),
+          passwordConfigJson(),
+        )
 
       const sessionId = crypto.randomUUID()
       await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
@@ -247,7 +260,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 +286,7 @@ export class AuthService {
       accessToken,
       expiresIn: this.#settings.accessTokenSeconds,
       issuedAt: Math.floor(now / 1000),
+      user,
     }
   }
 
@@ -301,13 +315,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(

package/src/store.ts

@@ -14,6 +14,8 @@ export interface UserRow {
   login: string
   email: string
   passwordHash: string | null
+  /** The algorithm marker beside the hash; an imported one names Umbraco's. */
+  passwordConfig: string | null
   language: string | null
   avatar: string | null
   isLockedOut: boolean
@@ -71,6 +73,7 @@ function mapUser(row: Record<string, unknown>): UserRow {
     login: String(row.login),
     email: String(row.email),
     passwordHash: (row.password_hash as string | null) ?? null,
+    passwordConfig: (row.password_config as string | null) ?? null,
     language: (row.language as string | null) ?? null,
     avatar: (row.avatar as string | null) ?? null,
     isLockedOut: fromDbBool(row.is_locked_out),
@@ -81,7 +84,7 @@ function mapUser(row: Record<string, unknown>): UserRow {
 }
 
 const USER_COLUMNS =
-  'id, key, user_name, login, email, password_hash, language, avatar, is_locked_out, is_approved, failed_login_attempts, kind'
+  'id, key, user_name, login, email, password_hash, password_config, language, avatar, is_locked_out, is_approved, failed_login_attempts, kind'
 
 export class AuthStore {
   #db: Db
@@ -154,6 +157,21 @@ export class AuthStore {
    * Replaces a user's password. The caller supplies an already-hashed value, so
    * this module never needs to know which algorithm is in use.
    */
+  /**
+   * Replaces an imported hash with argon2id after a successful sign-in. The
+   * password is the same, so the security stamp and change date stand.
+   */
+  async rehashPassword(
+    userId: number,
+    passwordHash: string,
+    passwordConfig: string,
+  ): Promise<void> {
+    await this.#db.exec(
+      'UPDATE user_account SET password_hash = ?, password_config = ? WHERE id = ?',
+      [passwordHash, passwordConfig, userId],
+    )
+  }
+
   async setPassword(userId: number, passwordHash: string, passwordConfig: string): Promise<void> {
     const now = DbDate.toDb(new Date())
     await this.#db.exec(

package/src/umbraco-passwords.ts

@@ -0,0 +1,128 @@
+/**
+ * Verifying the password hashes an Umbraco site stores, so an imported user or
+ * member signs in with the password they had; a success is then re-hashed to
+ * argon2id. In the order Umbraco's `UmbracoPasswordHasher` and
+ * `MemberPasswordHasher` try them:
+ *
+ * - ASP.NET Core Identity v3 (`0x01`, PBKDF2 with the PRF and iterations it
+ *   records) and v2 (`0x00`, PBKDF2-HMAC-SHA1, 1,000 iterations);
+ * - Umbraco 4's HMAC-SHA1 keyed with the password itself;
+ * - Umbraco 6–8's HMAC-SHA256 (or plain SHA1) over a base64 salt that prefixes
+ *   the hash, named by `passwordConfig` — or assumed for a member with none,
+ *   as a site upgraded from 8 has.
+ *
+ * Every comparison is constant-time. Pure.
+ */
+import { createHash, createHmac, pbkdf2Sync, timingSafeEqual } from 'node:crypto'
+
+export const UMBRACO_PASSWORD_ALGORITHMS = [
+  'PBKDF2.ASPNETCORE.V3',
+  'PBKDF2.ASPNETCORE.V2',
+  'HMACSHA256',
+  'HMACSHA1',
+] as const
+
+const same = (a: Buffer, b: Buffer) => a.length === b.length && timingSafeEqual(a, b)
+
+const utf16 = (value: string) => Buffer.from(value, 'utf16le')
+
+function base64(value: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 !== 0) return undefined
+  return Buffer.from(value, 'base64')
+}
+
+const PRFS = ['sha1', 'sha256', 'sha512'] as const
+
+/** ASP.NET Core Identity v3 or v2, by its first byte; the password as UTF-8. */
+export function verifyAspNetIdentity(password: string, hash: string): boolean {
+  const bytes = base64(hash)
+  if (!bytes || bytes.length === 0) return false
+  if (bytes[0] === 0x00) {
+    if (bytes.length !== 49) return false
+    const salt = bytes.subarray(1, 17)
+    const expected = bytes.subarray(17)
+    return same(pbkdf2Sync(password, salt, 1000, 32, 'sha1'), expected)
+  }
+  if (bytes[0] === 0x01) {
+    if (bytes.length < 13) return false
+    const prf = PRFS[bytes.readUInt32BE(1)]
+    const iterations = bytes.readUInt32BE(5)
+    const saltLength = bytes.readUInt32BE(9)
+    if (!prf || iterations < 1 || saltLength < 16 || bytes.length < 13 + saltLength + 16)
+      return false
+    const salt = bytes.subarray(13, 13 + saltLength)
+    const expected = bytes.subarray(13 + saltLength)
+    return same(pbkdf2Sync(password, salt, iterations, expected.length, prf), expected)
+  }
+  return false
+}
+
+/** Umbraco 4's "legacy encoding": HMAC-SHA1 whose key is the password, over the password. */
+export function verifyUmbraco4(password: string, hash: string): boolean {
+  const expected = base64(hash)
+  if (!expected) return false
+  return same(createHmac('sha1', utf16(password)).update(utf16(password)).digest(), expected)
+}
+
+/**
+ * Umbraco 6–8: a 24-character base64 salt, then the base64 hash of the
+ * password (UTF-16) under HMAC-SHA256 keyed with the salt repeated to 64
+ * bytes — .NET's key length for it — or SHA1 over salt and password.
+ */
+export function verifyUmbraco8(password: string, hash: string, algorithm = 'HMACSHA256'): boolean {
+  if (hash.length <= 24) return false
+  const salt = base64(hash.slice(0, 24))
+  const expected = base64(hash.slice(24))
+  if (!salt || !expected || salt.length === 0) return false
+  const name = algorithm.toUpperCase()
+  if (name === 'HMACSHA256') {
+    const key = Buffer.alloc(64)
+    for (let at = 0; at < key.length; at += salt.length)
+      salt.copy(key, at, 0, Math.min(salt.length, key.length - at))
+    return same(createHmac('sha256', key).update(utf16(password)).digest(), expected)
+  }
+  if (name === 'SHA1')
+    return same(
+      createHash('sha1')
+        .update(Buffer.concat([salt, utf16(password)]))
+        .digest(),
+      expected,
+    )
+  return false
+}
+
+/** The `hashAlgorithm` an Umbraco `passwordConfig` names, when it names one. Pure. */
+export function umbracoAlgorithmOf(passwordConfig: string | null | undefined): string | undefined {
+  if (!passwordConfig) return undefined
+  try {
+    const parsed = JSON.parse(passwordConfig) as { hashAlgorithm?: unknown }
+    return typeof parsed.hashAlgorithm === 'string' ? parsed.hashAlgorithm : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether a password matches a hash an Umbraco site stored. `forMember`: a
+ * member with no `passwordConfig` is assumed to be on Umbraco 8's hashing,
+ * which is how Umbraco treats one upgraded from 8.
+ */
+export function verifyUmbracoPassword(
+  password: string,
+  hash: string | null | undefined,
+  passwordConfig: string | null | undefined,
+  forMember = false,
+): boolean {
+  if (!hash || !password) return false
+  if (verifyAspNetIdentity(password, hash)) return true
+  if (verifyUmbraco4(password, hash)) return true
+  const algorithm = umbracoAlgorithmOf(passwordConfig) ?? (forMember ? 'HMACSHA256' : undefined)
+  if (!algorithm) return false
+  return verifyUmbraco8(password, hash, algorithm)
+}
+
+/** Whether a `passwordConfig` is one of Umbraco's, rather than crombolo's argon2id. Pure. */
+export const isUmbracoPasswordConfig = (passwordConfig: string | null | undefined): boolean => {
+  const algorithm = umbracoAlgorithmOf(passwordConfig)
+  return algorithm !== undefined && algorithm.toUpperCase() !== 'ARGON2ID'
+}