@crombolo/auth 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.11.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.11.0",
-    "@crombolo/data": "0.11.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/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'
 
@@ -131,7 +131,11 @@ export class AuthService {
         await verifyPassword(password, await DUMMY_HASH_PROMISE)
         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)
         const lockedOut =
           this.#settings.maxFailedLoginAttempts > 0 &&
@@ -143,6 +147,13 @@ export class AuthService {
       // 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', 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)

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'
+}