Access Code 명세

개요

이 문서는 사용자 등록 과정에서 사용되는 Access Code의 기술적 명세를 정의합니다. Access Code는 서비스 접근 권한이 있는 사용자만이 회원가입할 수 있도록 하는 제어 메커니즘입니다.

Access Code 구조

Access Code는 다음과 같은 형식을 가집니다:

총 16자리 영문자 및 숫자 조합
형식: XXXX-XXXX-XXXX-XXXX (실제 저장 및 전송 시에는 하이픈 제외)
영문자는 대문자만 사용 (A-Z)
숫자는 0-9만 사용
유사한 문자(O와 0, I와 1 등)은 혼동을 방지하기 위해 제외 가능

속성

Access Code 엔티티는 다음과 같은 속성을 가집니다:

속성	타입	설명
id	string	Access Code의 고유 식별자 (UUID)
code	string	16자리 Access Code 문자열
isUsed	boolean	사용 여부 (기본값: false)
usedAt	Date \| null	사용된 시간 (사용되지 않은 경우 null)
usedBy	UUID \| null	코드를 사용한 사용자 ID (사용되지 않은 경우 null)
expiresAt	Date	만료 시간 (기본값: 생성 후 30일)
createdAt	Date	생성 시간
updatedAt	Date	최종 업데이트 시간
batchId	string \| null	일괄 생성된 코드의 경우 배치 ID

생성 규칙

Access Code는 다음과 같은 규칙에 따라 생성됩니다:

충분한 엔트로피를 가지도록 암호학적으로 안전한 난수 생성기 사용
생성 시 중복 검사 수행
생성 시 유사한 문자 제외 (선택적)
일괄 생성 시 배치 ID 할당

검증 규칙

Access Code 검증 시 다음 조건을 모두 만족해야 합니다:

등록된 유효한 코드여야 함
이미 사용된 코드가 아니어야 함
만료되지 않은 코드여야 함

데이터베이스 스키마

CREATE TABLE access_codes (
  id UUID PRIMARY KEY,
  code VARCHAR(16) UNIQUE NOT NULL,
  is_used BOOLEAN NOT NULL DEFAULT FALSE,
  used_at TIMESTAMP WITH TIME ZONE,
  used_by UUID REFERENCES users(id),
  expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  batch_id VARCHAR(36)
);

CREATE INDEX idx_access_codes_code ON access_codes(code);
CREATE INDEX idx_access_codes_batch_id ON access_codes(batch_id);

보안 고려사항

Access Code는 데이터베이스에 해시화하여 저장하지 않습니다 (검색 및 조회 목적으로 원본 값 필요)
브루트 포스 공격을 방지하기 위해 API 요청 제한(rate limiting) 적용
Access Code 생성 및 관리 권한은 관리자 계정으로 제한
Access Code 검증 로그를 기록하여 오용 시도 모니터링

API 인터페이스

Access Code 관련 API는 다음과 같습니다:

검증 API: /v1/auth/access-code/validate
관리자용 생성 API: /v1/admin/access-codes
관리자용 조회 API: /v1/admin/access-codes/{id}
관리자용 일괄 생성 API: /v1/admin/access-codes/batch

개요​

Access Code 구조​

속성​

생성 규칙​

검증 규칙​

데이터베이스 스키마​

보안 고려사항​

API 인터페이스​

개요