Dead Drop API Docs

이 API는 무엇을 하나요?

간단히 말해, "한 번만 읽히는" 임시 비밀 메시지를 전달하도록 설계된 서비스입니다. 아래처럼 작동합니다.

작동 방식 (아주 쉽게)

보내는 사람은 메시지를 POST /store로 보냅니다.
서버는 메시지를 임시 저장하고 고유한 식별자(id)를 발급합니다. 이 id는 링크 형태(/read/<id>)로도 제공됩니다.
받는 사람은 그 id로 GET /read/:id를 호출하면 메시지를 받아보고, 서버는 즉시 그 메시지를 삭제합니다(한 번만 읽힘).

중요한 점

메시지는 최대 1시간 동안 보관(기본 TTL 1시간)됩니다. 시간이 지나면 자동 삭제됩니다.
한 번 읽으면 곧바로 삭제되므로 같은 id로 두 번 읽을 수 없습니다.
서비스 운영자는 저장된 메시지를 볼 수 있으므로, 운영자가 내용을 볼 수 없게 하려면 클라이언트에서 직접 암호화한 뒤 암호문을 저장하세요(종단간 암호화).

간단한 요청 형식

메시지를 저장하려면 JSON으로 { "message": "여기에 비밀" } 를 전송하세요.

curl -i -X POST https://api.kalpha.kr/store   -H "Content-Type: application/json"   -d '{"message":"내 비밀번호는 1234"}'

메시지 읽기

발급된 링크(또는 id)를 사용해 호출하면 메시지를 받고 바로 삭제됩니다.

curl -i https://api.kalpha.kr/read/<id>

Examples

간단한 사용 예시들 — 필요에 따라 Authorization 헤더를 추가하세요(배포에 API_KEY 설정 시).

cURL (배포) — id를 헤더에서 확인

curl -i -X POST https://api.kalpha.kr/store         -H "Content-Type: application/json"         -d '{"message":"내 비밀번호는 1234"}'

cURL (로컬 개발)

curl -i -X POST http://127.0.0.1:8787/store         -H "Content-Type: application/json"         -d '{"message":"테스트 메시지"}'

JavaScript (fetch)

const res = await fetch('https://api.kalpha.kr/store', {
        method: 'POST',
        headers: {'Content-Type':'application/json'},
        body: JSON.stringify({message: '비밀'})
      });
      const j = await res.json();
      console.log(j); // { id: '...' }

인증이 활성화된 경우

curl -i -X POST https://api.kalpha.kr/store         -H "Authorization: Bearer $API_KEY"         -H "Content-Type: application/json"         -d '{"message":"비밀"}'

클라이언트 측 암호화(E2EE) 권장

운영자가 메시지를 보지 못하게 하려면 클라이언트에서 메시지를 암호화한 후 암호문을 저장하세요. 서버는 암호문만 보관합니다.

Responses

응답은 간단하고 예측 가능합니다. 아래 예시에서는 본문(JSON)과 관련 응답 헤더를 함께 보여줍니다.

POST /store (성공)

// HTTP 201
      {"id":"..."}

      # 응답 헤더 예시
      Location: https://api.kalpha.kr/read/<id>
      X-DeadDrop-Id: <id>

GET /read/:id (성공)

// HTTP 200
      {"message":"..."}

오류

// 400 잘못된 요청
      {"error":"missing message"}

      // 404 찾을 수 없거나 이미 읽힘
      {"error":"not found or already read"}

      // 401 인증 실패 (env.API_KEY 설정 시)
      {"error":"unauthorized"}

      // 413 메시지 길이 초과
      {"error":"message too long"}

Operational notes

운영환경에서는 인증(Bearer token 등)을 권장합니다.
원자성이 필요하면 Durable Object 고려.
레이트리밋/길이 제한 적용 권장.