API 인터페이스 명세서
클래스 시그니처, 파라미터 타입, 반환값 규격 및 메모리 수명주기 (AMEVA-Sentinel)
Release: 
v2.3.0
핵심 가치 제안 (Why It Matters)
보안 감도와 차단 기준을 손쉽게 설정하여 내 서비스의 안전을 완벽하게 통제하는 가이드입니다.
1. 코어 엔진 인터페이스 및 주요 메서드
| 메서드 / 인터페이스 | 시그니처 | 반환 타입 | 기능 및 엔지니어링 설명 |
|---|---|---|---|
Sentinel.init() |
(config: SentinelConfig) |
SentinelInstance |
싱글톤 보안 관측성 인스턴스 초기화. 윈도우 폭, 토큰 시크릿, 허니팟 배열을 주입합니다. |
Sentinel.middleware() |
(options?: MiddlewareOptions) |
RequestHandler |
Express, Fastify, Next.js, FastAPI 등에 바인딩할 자동 트래픽 검증 및 차단 미들웨어 생성. |
Sentinel.verifyToken() |
(token: string, clientIp: string) |
AttestationResult |
클라이언트 브라우저가 발행한 HMAC-SHA256 토큰의 무결성 및 재생 공격 여부를 결정론적 검증. |
Sentinel.recordAnomaly() |
(event: SecurityAnomalyEvent) |
AnomalyRecord |
허니팟 엔드포인트 접촉 또는 비정상 헤더 주입 시 위험 점수를 가산하고 메트릭에 기록. |
Sentinel.getRiskScore() |
(identifier: string) |
Promise<RiskScore> |
클라이언트 IP 또는 토큰 세션 식별자 기준 현재 누적 위험도 점수(0~100) 산출. |
Sentinel.tarpit() |
(res: Response, delayMs?: number) |
Promise<void> |
악성 봇/스크래퍼에 대해 청크 단위 지연 스트리밍을 수행하여 공격자 소켓 리소스를 고갈. |
2. 보안 예외 클래스 및 HTTP 상태 코드
| 예외 클래스 | HTTP 상태 코드 | 발생 조건 및 세부 원인 |
|---|---|---|
RateLimitExceededError |
HTTP 429 Too Many Requests | 슬라이딩 윈도우 내 최대 허용 요청 횟수를 초과한 과도한 버스트 트래픽 인입 시 발생. |
TokenAttestationFailedError |
HTTP 403 Forbidden | 클라이언트 토큰 HMAC 서명이 불일치하거나 위조된 토큰 헤더가 탐지되었을 때 분출. |
HoneypotTriggeredError |
HTTP 403 Forbidden / Tarpit | 보안 유인용 가짜 경로(/.env, /admin/debug)에 무단 접근 시 즉각 분출. |
ReplayAttackDetectedError |
HTTP 401 Unauthorized | 타임스탬프 유효 범위를 초과했거나 이미 소비된 1회용 토큰을 재사용한 경우 차단. |
3. 요청 인터셉션 라이프사이클 명세
| 라이프사이클 단계 | 검증 및 필터 메커니즘 | 차단 조치 및 로깅 정책 |
|---|---|---|
onRequest |
클라이언트 IP 및 인바운드 헤더 기반 슬라이딩 윈도우 카운터 인메모리 증분 | 임계치 초과 시 즉시 HTTP 429 반환 또는 Tarpit 지연 큐로 핸들러 위임 |
onTokenVerify |
HMAC-SHA256 결정론적 해시 일치 검증 및 윈도우 타임스탬프 유효성 평가 | 위조 시 IP 위험 점수를 100으로 갱신하고 인메모리 블랙리스트에 등록 |
onPayloadCheck |
사용자 마우스/스크롤 지터의 Shannon 엔트로피 신호 평가 (최소 2.1 bit) | 엔트로피 부족(매크로 봇 판별) 시 CAPTCHA 챌린지 또는 방어 모드로 격리 |
onAuditTrail |
보안 이벤트(IP, 위험점수, 차단유형) 비동기 감사 로그 버퍼 기록 | 개인식별정보(PII) 제로 수집 정책을 준수하며 내부 보안 텔레메트리만 보존 |