OAuth + PIN Security

Traditional Password Login:
  Password → Argon2id → User Key → Decrypt Account Keys ✅

OAuth Login (Google/GitHub):
  OAuth token → ??? → User Key → Decrypt Account Keys ❌
                 ^
                 No secret available!

OAuth (Google/GitHub) → JWT session (authentication)
PIN (6-8 digits)      → User Key derivation (encryption)

OAuth Flow (New User):
  |
  1. Click "Continue with Google/GitHub"
  |
  2. OAuth provider redirects to callback with user profile
  |
  3. Backend creates user, generates session tokens (JWT)
  |
  4. Frontend redirects to /setup-pin
  |
  5. User enters 6-8 digit PIN
  |
  6. Frontend:
     - Generates key_salt (random 256-bit hex)
     - Derives UserKey = Argon2id(PIN, key_salt)
     - Generates verification_blob (encrypted known plaintext)
     - Creates AccountKey, encrypts with UserKey
  |
  7. Backend stores: key_salt, verification_blob, encrypted AccountKey
  |
  `-> Dashboard unlocked

OAuth Flow (Returning User):
  |
  1. Click "Continue with Google/GitHub"
  |
  2. OAuth provider redirects to callback
  |
  3. Backend finds existing user by oauth_id, generates session tokens
  |
  4. Frontend checks if user has encrypted keys
  |
  5. If keys exist:
     |-> Redirect to /unlock
     |-> User enters PIN
     |-> Frontend:
     |   - GET /auth/keys -> fetch key_salt, verification_blob, encrypted_keys
     |   - UserKey = Argon2id(PIN, key_salt)
     |   - Verify PIN: decrypt(verification_blob, UserKey) == KNOWN_PLAINTEXT
     |   - Decrypt all AccountKeys
     `-> Dashboard unlocked
  |
  6. If no keys exist:
     `-> Redirect to /setup-pin (setup incomplete)

// frontend/lib/crypto.ts

const ARGON2_OPTIONS = {
  t: 3,        // iterations
  m: 65536,    // 64 MB memory
  p: 4,        // parallelism
}

export async function deriveUserKey(password: string, saltHex: string): Promise<CryptoKey> {
  const salt = hexToBytes(saltHex)
  const passwordBytes = utf8ToBytes(password)  // PIN or password

  const derivedBytes = argon2id(passwordBytes, salt, {
    ...ARGON2_OPTIONS,
    dkLen: 32,
  })

  return crypto.subtle.importKey(
    'raw',
    toArrayBuffer(derivedBytes),
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt']
  )
}

// frontend/lib/crypto.ts

const VERIFICATION_PLAINTEXT = 'HOME_ACCOUNT_VERIFIED_2026'

/**
 * Generate verification blob by encrypting a known plaintext with UserKey.
 * Stored in DB. At unlock, we decrypt:
 * - If result == VERIFICATION_PLAINTEXT → PIN correct
 * - If AES-GCM fails → PIN incorrect
 */
export async function generateVerificationBlob(userKey: CryptoKey): Promise<string> {
  return encrypt(VERIFICATION_PLAINTEXT, userKey)
}

/**
 * Verify if a PIN/password is correct by decrypting the blob.
 */
export async function verifyUserKey(
  verificationBlob: string,
  userKey: CryptoKey
): Promise<boolean> {
  try {
    const result = await decrypt(verificationBlob, userKey)
    return result === VERIFICATION_PLAINTEXT
  } catch {
    return false  // AES-GCM decryption failed
  }
}

// backend/repositories/auth/user-repository.ts

export async function recordFailedPinAttempt(userId: string): Promise<{
  attempts: number
  locked: boolean
  lockedUntil: string | null
}> {
  const [rows] = await db.query<UserRow[]>(
    `SELECT pin_attempts, pin_locked_until FROM users WHERE id = ?`,
    [userId]
  )

  const user = rows[0]
  if (!user) throw new AppError('User not found', 404)

  const attempts = (user.pin_attempts || 0) + 1
  const MAX_ATTEMPTS = 5

  if (attempts >= MAX_ATTEMPTS) {
    const lockedUntil = new Date(Date.now() + 30 * 60 * 1000) // 30 minutes
    await db.query(
      `UPDATE users SET pin_attempts = ?, pin_locked_until = ? WHERE id = ?`,
      [attempts, lockedUntil, userId]
    )

    return {
      attempts,
      locked: true,
      lockedUntil: lockedUntil.toISOString(),
    }
  }

  await db.query(
    `UPDATE users SET pin_attempts = ? WHERE id = ?`,
    [attempts, userId]
  )

  return {
    attempts,
    locked: false,
    lockedUntil: null,
  }
}

// Example unlock flow with rate limiting

const handleUnlock = async (pin: string) => {
  try {
    // 1. Derive UserKey from PIN
    const userKey = await deriveUserKey(pin, keySalt)
    
    // 2. Verify PIN using verification blob
    const isValid = await verifyUserKey(verificationBlob, userKey)
    
    if (!isValid) {
      // Record failed attempt
      const res = await fetch('/api/auth/record-failed-pin', {
        method: 'POST',
        credentials: 'include',
        headers: { 'x-csrf-token': csrfToken },
      })
      
      const data = await res.json()
      
      if (data.locked) {
        throw new Error(`Too many attempts. Locked until ${data.lockedUntil}`)
      }
      
      throw new Error(`Incorrect PIN. ${5 - data.attempts} attempts remaining.`)
    }
    
    // 3. Reset attempts on success
    await fetch('/api/auth/reset-pin-attempts', {
      method: 'POST',
      credentials: 'include',
      headers: { 'x-csrf-token': csrfToken },
    })
    
    // 4. Decrypt AccountKeys
    await cryptoStore.unlockAccounts(encryptedKeys)
    
    router.push('/dashboard')
  } catch (error) {
    console.error('Unlock failed:', error)
  }
}

// backend/controllers/auth/auth-controller.ts

export const changePin = asyncHandler(async (req: Request, res: Response) => {
  const { currentPassword, newPin, newKeySalt, verificationBlob, reEncryptedKeys } = req.body

  // Validate current password (OAuth users with linked password)
  // OR validate current PIN (OAuth users without password)
  
  await UserRepository.changePin(
    req.user!.id,
    currentPassword,
    newPin,
    newKeySalt,
    verificationBlob,
    reEncryptedKeys
  )

  // Force re-login with new PIN
  res.clearCookie('accessToken', { path: '/' })
  res.clearCookie('refreshToken', { path: '/' })
  res.clearCookie('csrfToken', { path: '/' })

  res.status(200).json({
    success: true,
    message: 'PIN changed successfully. Please log in again.',
  })
})

# Initiate OAuth (redirects to provider)
GET /api/auth/google
GET /api/auth/github

# OAuth callback (handled by backend)
GET /api/auth/google/callback?code=...
GET /api/auth/github/callback?code=...

# Save verification blob (after setup-pin)
POST /api/auth/verification-blob
Content-Type: application/json

{
  "verificationBlob": "base64_encrypted_blob..."
}

# Change PIN (authenticated)
POST /api/auth/change-pin
Content-Type: application/json

{
  "currentPassword": "old_pin_or_password",
  "newPin": "12345678",
  "newKeySalt": "new_salt_hex...",
  "verificationBlob": "new_verification_blob...",
  "reEncryptedKeys": [
    { "accountId": "acc-001", "encryptedKey": "..." }
  ]
}

# Record failed PIN attempt (authenticated)
POST /api/auth/record-failed-pin

# Response:
{
  "success": true,
  "attempts": 3,
  "locked": false,
  "lockedUntil": null
}

# Reset PIN attempts (after successful unlock)
POST /api/auth/reset-pin-attempts