인증

등록 (4단계)

등록에는 이메일 인증, 비밀번호, 표시 이름이 필요합니다:

1단계: 인증 코드 전송

POST /auth/send-code

{
  "email": "user@example.com",
  "scene": "register",
  "turnstile_token": "..."
}

2단계: 등록

POST /auth/register

{
  "email": "user@example.com",
  "code": "123456",
  "account_password": "your-password",
  "display_name": "Your Name",
  "device_locale": "en-US"
}

액세스 토큰과 리프레시 토큰(HttpOnly 쿠키로)을 반환합니다.

3단계: 클라이언트에서 키 생성

등록 후 클라이언트가:

1. X25519 키 쌍을 생성합니다
2. 암호화 키를 파생합니다: Argon2id(protection_password, random_salt)
3. 개인 키를 암호화합니다: AES-GCM(derived_key, private_key)

4단계: 키 백업 업로드

POST /keys/backup

{
  "backup_a": "base64-encrypted-private-key",
  "argon2_salt": "base64-salt",
  "public_key": "base64-public-key",
  "device_id": "device-uuid"
}

로그인

세 가지 로그인 방법을 지원합니다:

비밀번호 로그인

POST /auth/login

{
  "email": "user@example.com",
  "account_password": "your-password",
  "turnstile_token": "..."
}

잠금: 5회 실패 후 계정이 15분간 잠깁니다. retry_after(초)와 함께 423 ACCOUNT_LOCKED를 반환합니다.

인증 코드 로그인

POST /auth/send-code
{ "email": "user@example.com", "scene": "login", "turnstile_token": "..." }

POST /auth/login-code
{ "email": "user@example.com", "code": "123456" }

Passkey 로그인

Passkey는 인증 단계에서 계정 비밀번호를 대체합니다. 새 기기에서는 보호 비밀번호(키 복호화용)가 여전히 필요합니다.

POST /auth/passkey/begin     # 챌린지를 반환 (공개 엔드포인트)
POST /auth/passkey/complete   # 서명 검증, 토큰 발급 (공개 엔드포인트)

Passkey 로그인은 WebAuthn Conditional UI를 사용합니다 — 로그인 화면에 명시적 버튼이 없습니다. 지원되는 기기에서 시스템 Passkey 프롬프트가 자동으로 표시됩니다.

토큰 갱신

액세스 토큰은 5분 후 만료됩니다. 리프레시 토큰으로 새로운 쌍을 받으세요:

POST /auth/refresh

리프레시 토큰은 다음 속성으로 HttpOnly 쿠키에 저장됩니다:

Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict; Path=/auth; Max-Age=2592000

비밀번호 재설정

계정 비밀번호 재설정은 암호화 키에 영향을 주지 않습니다:

POST /auth/send-code
{ "email": "user@example.com", "scene": "reset", "turnstile_token": "..." }

POST /auth/reset-password
{ "email": "user@example.com", "code": "123456", "new_account_password": "new-password" }

에이전트 인증

에이전트는 JWT 대신 장기 토큰을 사용합니다:

Authorization: Bearer hsk_your-agent-token

토큰 형식은 hsk_ + 40개의 base62 문자입니다. 서버는 bcrypt 해시를 저장합니다.

WebSocket 인증

WebSocket 연결의 경우, 토큰은 첫 번째 프레임에서 전송됩니다 (URL에는 절대 포함하지 않음):

{ "type": "auth", "token": "hsk_...", "agent_id": "your-agent-id" }

서버는 { "type": "auth.ok" } 또는 { "type": "auth.error", "reason": "..." }로 응답합니다.

토큰 재생성

POST /agents/:id/token/regenerate
{ "emergency": false }

모드	이전 토큰	이전 공개 키
일반 (emergency: false)	7일간 유효	7일간 유효
긴급 (emergency: true)	즉시 해지	즉시 해지

다음 단계

• REST 엔드포인트 — 전체 엔드포인트 목록
• API 개요 — 기본 URL 및 형식
• 오류 코드 — 인증 오류 코드