Brute-Force Protection

User submits login
     |
     v
Hera loginAction: normalize identifier to lowercase
     |
     v
SDK checkLockout(identifier)
     |-- LOCKED --> return lockout message (do NOT contact Kratos)
     |
     +-- NOT LOCKED --> continue
          |
          v
     Kratos: submit credentials
          |
          |-- SUCCESS --> SDK clearAttempts(identifier) [fire-and-forget] --> redirect
          |
          +-- FAILURE --> SDK recordFailedAttempt(identifier, ip)
                              |
                              +-- { shouldLockout: true }
                              |       --> lockout row inserted inside recordFailedAttempt
                              |       --> appendAuditLog called inside recordFailedAttempt
                              |
                              +-- { shouldLockout: false }
                                      --> return generic "Invalid email or password."

// Check whether an account is currently locked out.
// FAIL-OPEN: returns { locked: false } if the database is unavailable.
checkLockout(identifier: string): Promise<LockoutState>

// Record a failed login attempt. If the count within the sliding window
// reaches maxAttempts, inserts a lockout row and appends an audit log entry.
// FAIL-OPEN: returns { shouldLockout: false, attemptCount: 0 } if the database is unavailable.
recordFailedAttempt(
  identifier: string,
  ipAddress?: string | null
): Promise<{ shouldLockout: boolean; attemptCount: number }>

// Delete all failed attempt rows for the identifier.
// Call on successful login. Errors are logged at WARN and not re-thrown.
clearAttempts(identifier: string): Promise<void>

// List all accounts that are currently locked (locked_until > NOW(), unlocked_at IS NULL).
// Used by the Athena admin UI.
listLockedAccounts(): Promise<LockedAccount[]>

// Manually unlock an account by setting unlocked_at on the active lockout row.
// Returns true if an active lockout was found and unlocked.
// Returns false for all not-found cases (no distinction between "no lockout" and
// "wrong identifier" -- prevents enumeration attacks).
// Appends an audit log entry on success.
unlockAccount(identifier: string, adminIdentityId: string): Promise<boolean>

// Append a row to the security audit log table.
// Metadata keys are validated against an allowlist; values are truncated to 500 chars.
appendAuditLog(event: AuditLogEvent): Promise<void>

// Read brute-force configuration from the settings table.
// Results are cached for 60 seconds.
getBruteForceConfig(): Promise<BruteForceConfig>

interface BruteForceConfig {
  /** Number of failed attempts before triggering a lockout. Default: 5. */
  maxAttempts: number;
  /** Sliding window in seconds for counting attempts. Default: 600 (10 min). */
  windowSeconds: number;
  /** Lockout duration in seconds. Minimum enforced: 60. Default: 900 (15 min). */
  lockoutDurationSeconds: number;
}

interface LockoutState {
  locked: boolean;
  /** When the lockout expires. Undefined if not locked. */
  lockedUntil?: Date;
}

interface LockedAccount {
  id: number;
  identifier: string;
  identity_id: string | null;
  locked_at: Date | null;
  locked_until: Date | null;
  lock_reason: string | null;
  /** Attempt count at the time the lockout was triggered. */
  auto_threshold_at: number | null;
  trigger_ip: string | null;
}

interface LoginAttempt {
  id: number;
  identifier: string;
  ip_address: string | null;
  attempt_time: Date;
}

interface AuditLogEvent {
  event_type: string;
  identifier?: string;
  identity_id?: string;
  admin_identity_id?: string;
  /**
   * Keys are validated against AUDIT_METADATA_ALLOWLIST before insert.
   * Allowed keys: 'ip', 'reason', 'locked_until', 'lock_reason'.
   * Any other key is silently dropped. Values truncated to 500 chars.
   */
  metadata?: Record<string, string>;
}

[security][brute_force] lockout_duration_seconds value <N> is below minimum 60. Using default: 900

import {
  checkLockout,
  recordFailedAttempt,
  clearAttempts,
} from "@olympusoss/sdk";

export async function loginAction(
  identifier: string,
  password: string,
  clientIp: string | null
) {
  const normalizedIdentifier = identifier.toLowerCase().trim();

  // Step 1: Check lockout before contacting Kratos.
  const lockoutState = await checkLockout(normalizedIdentifier);
  if (lockoutState.locked) {
    const lockedUntil = lockoutState.lockedUntil;
    const remainingMs = lockedUntil ? lockedUntil.getTime() - Date.now() : 0;
    const minutes = Math.max(1, Math.ceil(remainingMs / 60_000));
    return {
      error: "account_locked",
      message: `Account temporarily locked. Try again in ${minutes} minute${minutes !== 1 ? "s" : ""}.`,
    };
  }

  // Step 2: Forward credentials to Kratos.
  const kratosResult = await submitLoginToKratos(normalizedIdentifier, password);

  if (kratosResult.success) {
    // Step 3a: Clear attempt counter on success (fire-and-forget).
    // Do not await -- a cleanup failure must not block a successful login redirect.
    clearAttempts(normalizedIdentifier).catch(() => {});
    return { success: true, sessionToken: kratosResult.sessionToken };
  }

  // Step 3b: Record the failed attempt.
  // recordFailedAttempt handles lockout creation internally when the threshold is reached.
  // clientIp should come from the X-Real-IP header set by the Caddy reverse proxy --
  // not from X-Forwarded-For, which clients can spoof.
  const { shouldLockout } = await recordFailedAttempt(normalizedIdentifier, clientIp);

  if (shouldLockout) {
    // The account is now locked. The lockout row and audit log entry were written
    // inside recordFailedAttempt. Return the same generic message -- do not reveal
    // that a lockout was just triggered.
  }

  // Never reveal whether the failure is a wrong password or a lockout threshold.
  return { error: "invalid_credentials", message: "Invalid email or password." };
}

import { listLockedAccounts, unlockAccount } from "@olympusoss/sdk";

// GET /api/security/locked-accounts
export async function getLockedAccounts() {
  return listLockedAccounts();
}

// POST /api/security/locked-accounts/:identifier/unlock
// :identifier is the URL-encoded email or username (e.g., user%40example.com).
export async function adminUnlockAccount(
  rawIdentifier: string,
  adminIdentityId: string
) {
  // URL-decode before normalizing. The identifier in the path is URL-encoded
  // because email addresses contain '@' which must be encoded in URL path segments.
  const normalizedIdentifier = decodeURIComponent(rawIdentifier).toLowerCase().trim();

  const unlocked = await unlockAccount(normalizedIdentifier, adminIdentityId);

  if (!unlocked) {
    // Return 404 for all not-found cases. Do not distinguish between
    // "account not locked" and "identifier does not exist" -- prevents enumeration.
    return { status: 404, body: { error: "not_found" } };
  }

  return { status: 200, body: { message: "Account unlocked successfully." } };
}