🔌 star365 Integration Guide

9 플랫폼 (plus365, safenet, sjclinic, emr, vn, upfinance, mlm, gws, politics)을 star365 통합 회원으로 연결하는 방법.

빠른 시작 — 가입 훅은 서버에서 호출합니다

⚠️ 2026-07-28 변경: 브라우저에서의 star365.signup() 은 더 이상 동작하지 않습니다(401). 브라우저는 키를 가질 수 없어, 이 경로를 열어두면 누구나 임의 email/platform 으로 중앙 회원을 만들 수 있는 오픈 프록시가 됩니다. (ssoLogin 이 2026-07-26 에 같은 이유로 서버 전용이 된 것과 동일)

가입 성공 직후, 플랫폼 서버에서:

const r = await fetch('https://api.star365.site/members/register', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-api-key': process.env.KAHAN_MEMBERS_KEY },
  body: JSON.stringify({ email, platform: 'plus365', local_user_id: String(userId) }),
  signal: AbortSignal.timeout(5000),
});
if (r.ok) {
  const { star365_uid } = await r.json();
  // ⚠️ 반드시 저장할 것 — 이 값이 없으면 구독·엔타이틀먼트를 조회할 키가 없어
  //    해당 회원은 영원히 무료 등급에 머뭅니다(2026-07 에 4개 플랫폼에서 실제로 발생).
  await db.users.update({ where: { id: userId }, data: { star365Uid: star365_uid } });
}

호출은 best-effort 로 두되(가입 흐름을 막지 않음), 응답의 star365_uid 는 반드시 저장하세요.

API 엔드포인트

Base: https://api.star365.site

회원 등록

POST /members/register
Content-Type: application/json

{ "email": "user@example.com", "platform": "plus365", "local_user_id": "u-123", "extra": {} }

응답: { "star365_uid": "...", "created": true|false, "tier": "BRONZE" }

멱등(idempotent): 같은 email+platform 재호출 시 기존 UID 반환.

이벤트 로그

POST /members/events
{ "star365_uid": "...", "platform": "plus365", "event": "visit|login|purchase|referral", "meta": {} }

SSO 발급

POST /auth/sso/issue
{ "email": "...", "platform": "...", "local_user_id": "..." }

응답 시 브라우저에 star365_sso (httpOnly, 7일) + star365_uid 쿠키가 .star365.site 도메인으로 세팅됨.

현재 세션 확인

GET /auth/me
Cookie: star365_sso=...

응답: { "authenticated": true, "star365_uid": "...", "member": {...} }

SDK 레퍼런스

star365.signup(...)    // ❌ 서버 전용 (브라우저 호출 시 reject)
star365.ssoLogin(...)  // ❌ 서버 전용 (브라우저 호출 시 reject)
star365.logEvent({ platform, event, meta })   // uid 자동
star365.me()
star365.logout()
star365.uid()                    // 쿠키에서 읽기
star365.isAuthenticated()
star365.byEmail(email)
star365.byUid(uid)
star365.statsCrossPlatform()
star365.statsNorthStar()

쿠키 정책

쿠키	HttpOnly	Secure	SameSite	Domain	Max-Age
star365_sso	✅	✅	Lax	.star365.site	604800 (7일)
star365_uid	❌	✅	Lax	.star365.site	604800 (7일)

모든 서브도메인(*.star365.site)에서 자동 인식. 가입된 플랫폼 도메인이 .star365.site 밖이면 SSO 쿠키 공유 불가 → 해당 플랫폼은 signup 훅만 사용.

배포킷 (각 플랫폼 서버에 적용)

킷	대상	다운로드
Node.js signup patch	plus365, safenet, sjclinic, emr, vn, upfinance, mlm, gws, politics	hospital-nodejs.patch
PHP / WP signup snippet	레거시 플랫폼	php-wp.php
README	적용 가이드	README.md

장애 격리 원칙

• 서버측 /members/register 호출은 best-effort — 실패해도 플랫폼 가입 자체는 성공해야 함
• 단, 응답의 star365_uid 저장은 필수 — 버리면 유료화가 구조적으로 불가능해짐
• SDK는 .catch(()=>{}) 로 소음 무시 권장
• API 서버가 kahan:3720 에 2초 내 응답 못 하면 502 반환