Planet Security Communication System

개요

Planet Security REST API를 사용하면 외부 웹사이트에서 Planet 로그인을 연동할 수 있습니다. 비밀번호 없이, 행성의 실시간 회전 상태 기반 상호 인증으로 로그인합니다.

Planet Security는 암호화가 아닌 일방향 상태 바인딩입니다. 비밀 자체를 생성하지 않으므로 탈취될 수 없습니다. 공격의 유일한 결과는 세션 실패입니다.

빠른 시작 (3단계)

1단계: 앱 등록

아래 양식으로 앱을 등록하면 API Key가 발급됩니다.

2단계: SDK 삽입 (가장 간단한 방법)

HTML에 스크립트 한 줄과 로그인 버튼을 추가하세요.

<!-- Planet Security SDK -->
<script src="https://planet.winnerbrothers.org/api/v1/sdk"></script>

<!-- 로그인 버튼 (자동 렌더링) -->
<div
  data-planet-login
  data-planet-key="YOUR_API_KEY"
  data-planet-theme="dark"
  data-planet-size="medium"
></div>

<!-- 또는 JavaScript로 직접 제어 -->
<script>
PlanetSecurity.init({
  apiKey: 'YOUR_API_KEY',
  onAuth: function(result) {
    if (result.success) {
      console.log('인증 성공:', result.username);
      console.log('행성 검증 정보:', result.planetVerification);
      // 서버에 result.requestId를 보내서 검증
    }
  }
});

// 버튼 렌더링
PlanetSecurity.renderButton('#login-container', {
  theme: 'dark',
  size: 'medium'
});
</script>

3단계: 서버에서 검증

콜백으로 받은 planet_token을 서버에서 검증합니다.

// 콜백 URL로 리다이렉트됨:
// https://myblog.com/auth/callback?planet_token=req_xxx&username=user1

// 서버에서 상태 확인
const response = await fetch(
  'https://planet.winnerbrothers.org/api/v1/auth/status?request_id=' + planet_token,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
// {
//   requestId: "req_xxx",
//   status: "authenticated",
//   username: "user1",
//   planetVerification: {
//     serverPlanetId: "...",
//     rotationAxis: { x, y, z },
//     angularSpeed: 42.5
//   }
// }

API 레퍼런스

인증 (Authentication)

POST/api/v1/apps/register

외부 앱 등록 (API Key 발급)

Request Body:

{ "name": "My App", "domain": "example.com", "callbackUrl": "https://..." }

Response:

{ "appId": "app_xxx", "apiKey": "pk_xxx" }

POST/api/v1/auth/init

인증 요청 생성 → loginUrl 반환

Header: Authorization: Bearer API_KEY

Request Body:

{ "redirectUrl": "https://..." }

Response:

{ "requestId": "req_xxx", "loginUrl": "...", "expiresAt": ... }

GET/api/v1/auth/status?request_id=req_xxx

인증 상태 확인

Header: Authorization: Bearer API_KEY

Response:

{ "status": "authenticated", "username": "user1", "planetVerification": {...} }

보안 토큰 (OTP 대체)

POST/api/v1/tokens/issue

일회용 보안 토큰 발행 (행성 상태 바인딩)

Header: Authorization: Bearer API_KEY

Request Body:

{ "planetId": "xxx", "purpose": "login-2fa", "ttlSeconds": 300 }

Response:

{ "tokenId": "tok_xxx", "planetStateHash": "...", "expiresAt": ... }

POST/api/v1/tokens/verify

토큰 검증 및 소비 (1회 사용)

Header: Authorization: Bearer API_KEY

Request Body:

{ "tokenId": "tok_xxx" }

Response:

{ "valid": true, "purpose": "login-2fa", "consumedAt": ... }

GET/api/v1/tokens/status?token_id=tok_xxx

토큰 상태 조회 (소비하지 않음)

Header: Authorization: Bearer API_KEY

Response:

{ "status": "active", "purpose": "login-2fa", "expiresAt": ... }

상태 서명 (전자서명 대체)

POST/api/v1/state/capture

행성의 현재 상태 캡처 (쿼터니언 + 좌표)

Header: Authorization: Bearer API_KEY

Request Body:

{ "planetId": "xxx" }

Response:

{ "stateHash": "...", "quaternion": {w,x,y,z}, "coordinates": {...} }

POST/api/v1/state/sign

데이터에 행성 상태 서명 (문서 인증)

Header: Authorization: Bearer API_KEY

Request Body:

{ "planetId": "xxx", "data": "계약서 내용..." }

Response:

{ "signatureId": "sig_xxx", "stateHash": "...", "quaternion": {...} }

POST/api/v1/state/verify

상태 서명 검증

Header: Authorization: Bearer API_KEY

Request Body:

{ "signatureId": "sig_xxx", "data": "계약서 내용..." }

Response:

{ "valid": true, "dataHashMatch": true, "signedAt": ... }

데이터 바인딩 (무결성 보장)

POST/api/v1/data/bind

데이터를 행성 상태에 바인딩

Header: Authorization: Bearer API_KEY

Request Body:

{ "planetId": "xxx", "data": "중요 데이터", "ttlSeconds": 3600 }

Response:

{ "bindingId": "bind_xxx", "stateHash": "...", "expiresAt": ... }

POST/api/v1/data/verify

바인딩된 데이터 무결성 검증

Header: Authorization: Bearer API_KEY

Request Body:

{ "bindingId": "bind_xxx", "data": "중요 데이터" }

Response:

{ "valid": true, "dataIntegrity": "intact" }

보안 메시징

POST/api/v1/messaging/send

상태 바인딩 메시지 전송

Header: Authorization: Bearer API_KEY

Request Body:

{ "senderPlanetId": "xxx", "receiverPlanetId": "yyy", "content": "..." }

Response:

{ "messageId": "msg_xxx", "stateHash": "..." }

POST/api/v1/messaging/verify

수신 메시지 검증

Header: Authorization: Bearer API_KEY

Request Body:

{ "messageId": "msg_xxx", "receiverPlanetId": "yyy" }

Response:

{ "valid": true, "content": "...", "verifiedAt": ... }

GET/api/v1/messaging/history?planet_id=xxx

메시지 이력 조회

Header: Authorization: Bearer API_KEY

Response:

{ "count": 10, "messages": [...] }

Planet Coin (디지털 화폐)

POST/api/v1/coin/wallet

코인 지갑 생성 (행성에 연결)

Header: Authorization: Bearer API_KEY

Request Body:

{ "planetId": "xxx", "owner": "민수" }

Response:

{ "walletId": "wal_xxx", "balance": 0 }

GET/api/v1/coin/wallet?wallet_id=xxx

지갑 조회 (잔액, 행성 정보)

Header: Authorization: Bearer API_KEY

Response:

{ "walletId": "...", "balance": 50000, "balancePCN": 5.0, "planetVolume": ... }

GET/api/v1/coin/wallet?list=true

앱의 전체 지갑 목록

Header: Authorization: Bearer API_KEY

Response:

{ "count": 5, "wallets": [...] }

POST/api/v1/coin/mint

코인 발행 (행성 상태 기반)

Header: Authorization: Bearer API_KEY

Request Body:

{ "walletId": "wal_xxx", "amount": 100.0, "description": "초기 발행" }

Response:

{ "txId": "tx_xxx", "txHash": "...", "newBalancePCN": 100.0 }

POST/api/v1/coin/transfer

코인 전송 (상호 행성 상태 검증)

Header: Authorization: Bearer API_KEY

Request Body:

{ "fromWalletId": "wal_a", "toWalletId": "wal_b", "amount": 5.0, "type": "purchase" }

Response:

{ "txId": "tx_xxx", "txHash": "...", "senderStateHash": "...", "receiverStateHash": "..." }

GET/api/v1/coin/ledger?wallet_id=xxx

거래 상태 원장 조회

Header: Authorization: Bearer API_KEY

Response:

{ "total": 20, "summary": { "totalMintedPCN": 100, ... }, "entries": [...] }

POST/api/v1/coin/verify

거래 검증

Header: Authorization: Bearer API_KEY

Request Body:

{ "txId": "tx_xxx" }

Response:

{ "valid": true, "txHash": "...", "verification": "..." }

Post-Quantum (양자 내성)

POST/api/v1/pq/keygen

ML-KEM-768 + ML-DSA-65 키쌍 생성

Header: Authorization: Bearer SECRET_KEY

Response:

{ "kem": { "algorithm": "ML-KEM-768", "publicKey": "...", "secretKey": "..." }, "dsa": { "algorithm": "ML-DSA-65", ... } }

POST/api/v1/pq/encapsulate

ML-KEM 키 캡슐화 (공유 비밀 생성)

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "recipientPublicKey": "base64..." }

Response:

{ "cipherText": "...", "sharedSecret": "256-bit base64" }

POST/api/v1/pq/decapsulate

ML-KEM 키 역캡슐화 (공유 비밀 복원)

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "cipherText": "base64...", "secretKey": "base64..." }

Response:

{ "sharedSecret": "256-bit base64" }

POST/api/v1/pq/sign

ML-DSA-65 양자 내성 전자서명

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "data": "서명할 데이터", "secretKey": "base64..." }

Response:

{ "signature": "base64...", "algorithm": "ML-DSA-65" }

POST/api/v1/pq/verify

ML-DSA-65 서명 검증

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "data": "...", "signature": "base64...", "publicKey": "base64..." }

Response:

{ "valid": true, "algorithm": "ML-DSA-65" }

HSM (Hardware Security Module)

GET/api/v1/hsm/status

HSM 상태 조회 (provider, mode, FIPS 준수)

Header: Authorization: Bearer SECRET_KEY

Response:

{ "provider": "Planet SoftHSM v1.0", "mode": "software", "fipsCompliant": true, "usedSlots": 5 }

POST/api/v1/hsm/store

HSM에 키 저장 (행성 파라미터/서명키)

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "label": "Planet-A", "keyType": "planet-params", "owner": "user1", "keyData": "..." }

Response:

{ "slotId": "hsm_xxx", "fingerprint": "abc123...", "status": "active" }

GET/api/v1/hsm/list?owner=user1

HSM 키 슬롯 목록 조회

Header: Authorization: Bearer SECRET_KEY

Response:

{ "count": 3, "slots": [{ "slotId": "...", "label": "...", "accessCount": 42 }] }

Galaxy Protocol (분산 행성 네트워크)

POST/api/v1/galaxy/nodes

Galaxy 노드 등록

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "name": "Seoul-1", "endpoint": "https://seoul.planet.io", "region": "ap-northeast-2" }

Response:

{ "nodeId": "node_xxx", "status": "active" }

GET/api/v1/galaxy/nodes

Galaxy 노드 목록

Header: Authorization: Bearer SECRET_KEY

Response:

{ "count": 3, "nodes": [{ "nodeId": "...", "name": "Seoul-1", "status": "active" }] }

POST/api/v1/galaxy/sync

행성 상태 노드 간 동기화

Header: Authorization: Bearer SECRET_KEY

Request Body:

{ "fromNodeId": "node_a", "toNodeId": "node_b", "planetId": "xxx" }

Response:

{ "syncId": "sync_xxx", "stateHash": "...", "verified": true }

GET/api/v1/galaxy/health

Galaxy 네트워크 헬스체크

Header: Authorization: Bearer SECRET_KEY

Response:

{ "totalNodes": 3, "activeNodes": 3, "networkStatus": "healthy" }

작동 원리

외부 사이트 → Planet API

인증 요청(init) → loginUrl 발급

사용자 → Planet 로그인 페이지

팝업/리다이렉트로 Planet 로그인. 3-Way 상호 인증 (행성 상태 예측 검증)

인증 완료 → 외부 사이트로 복귀

callbackUrl로 리다이렉트 + planet_token 전달

외부 서버 → Planet API 검증

planet_token으로 상태 확인 → 인증된 사용자 정보 + 행성 검증 데이터 수신

보안 참고

Planet API는 Orbital State Function (OSF) 기반 시간-동기식 상호 인증을 제공합니다 (특허 PCT WO 2025/127469).
보안 수준: 159-bit 고전 / 79-bit 양자 — 위조 확률 상한 Adv ≤ q_H · 2⁻¹⁵⁹ (수반 논문 Thm 1, ROM).
OSF primitive는 정수분해/이산로그 미사용 — Shor 알고리즘 무관 (Thm 5).
Transcript(해시 커밋)는 ROM 하 uniform 랜덤과 구별 불가능 (Thm 2) — 네트워크 관측으로 키 정보 누출 0.
Secret Key(sk_)는 반드시 서버 측에서만 사용하세요. 클라이언트 코드에 절대 노출 금지.