@hm-soft/account-lock

로그인 브루트포스 공격을 막는 계정 잠금 정책. 저장소에 의존하지 않는 순수 상태 계산이라, 잠금 상태를 어디에(DB·Redis 등) 저장하든 끼워 넣을 수 있습니다.

설치

npm install @hm-soft/account-lock

사용

import { initialState, isLocked, recordFailure, recordSuccess } from "@hm-soft/account-lock";

const policy = { maxAttempts: 5, lockDurationMs: 15 * 60 * 1000 };

// 로그인 시도
let state = user.lockState ?? initialState();

if (isLocked(state)) {
  throw new Error("계정이 잠겼습니다. 잠시 후 다시 시도하세요.");
}

if (await checkPassword(input)) {
  await db.save(userId, { lockState: recordSuccess() }); // 성공 → 리셋
} else {
  const r = recordFailure(state, policy);
  await db.save(userId, { lockState: r.state });          // 새 상태 저장
  if (r.locked) {
    throw new Error(`${Math.ceil(r.retryAfterMs / 1000)}초 후 다시 시도하세요.`);
  }
  throw new Error(`비밀번호가 틀렸습니다. ${r.remainingAttempts}회 남음.`);
}

API

| 함수 | 설명 | |------|------| | initialState() | 빈 잠금 상태 | | isLocked(state, now?) | 현재 잠김 여부 | | msUntilUnlock(state, now?) | 잠금 해제까지 남은 ms | | recordFailure(state, policy?, now?) | 실패 1건 기록 → { state, locked, retryAfterMs, remainingAttempts, lockedUntil } | | recordSuccess() | 성공 시 상태 초기화 |

LockPolicy

| 옵션 | 기본값 | 설명 | |------|--------|------| | maxAttempts | 5 | 잠기기까지 허용 실패 횟수 | | lockDurationMs | 15분 | 잠금 지속 시간 | | attemptWindowMs | — | 이 시간 내 새 실패 없으면 횟수 리셋 | | backoff | "fixed" | "exponential"이면 반복 잠금마다 시간 2배 | | maxLockDurationMs | — | 지수 백오프 시간 상한 |

특징

• 저장소 비의존 — LockState는 숫자뿐이라 그대로 직렬화/저장 가능
• 테스트 용이 — now를 주입할 수 있어 시간 의존 로직도 결정적으로 테스트
• 고정/지수 백오프 — 단순 잠금부터 반복 공격 점증 차단까지

License

Apache-2.0