Starchild로 로그인

starchild-auth-sdk로 웹 앱에 로그인을 추가하고 세션과 서버 토큰 검증을 구현하는 안내서입니다.

시작하기 전

iamstarchild.com → More → OAuth Apps → Create App에서 OAuth 앱을 만드세요. 이름, 서드파티 페이지의 정확한 Allowed Origin, 필요한 Scope, 선택 사항인 System Prompt를 입력합니다. Origin은 scheme과 포트를 포함하고 경로, query, hash, 끝 슬래시는 포함하지 않습니다. http://localhost:5173처럼 사용하는 모든 로컬 포트를 각각 등록하세요. http://localhost:6066은 Starchild 웹 앱의 로컬 포트이므로 서드파티 앱 Origin으로 등록하지 마세요.

Scope 권한 승인
profile 이름, 아바타, 사용자 ID, Guest 상태 자동
chat 대화, 스레드, 컨테이너, 스킬, 미디어, 작업, 지갑 조회, WebSocket 관리자 검토
credit:read 크레딧 잔액과 기록 관리자 검토
credit:write 충전, 기프트 카드, Points 교환 및 credit:read 포함 관리자 검토

profile만 선택하면 Client ID를 즉시 받을 수 있습니다. 다른 Scope는 검토가 필요합니다. 승인되고 active인 앱의 Origin은 약 5분마다 CORS 허용 목록에 반영됩니다.

설치와 로그인 
npm install starchild-auth-sdk
# 또는 yarn add starchild-auth-sdk
# 또는 pnpm add starchild-auth-sdk

import { StarchildAuth } from 'starchild-auth-sdk'

const auth = new StarchildAuth({
  clientId: 'YOUR-CLIENT-ID',
  scope: 'profile', // 승인된 경우에만 chat 또는 credit Scope 추가
  onLogin: ({ accessToken, refreshToken, expiresIn, userInfo }) => {
    console.log(userInfo.agentName, userInfo.isGuest)
  },
})

button.addEventListener('click', async () => {
  try { await auth.login() }
  catch (error) {
    if (error?.message?.includes('cancelled')) console.log('사용자가 로그인을 취소했습니다')
    else if (error?.message?.includes('blocked')) console.log('브라우저가 팝업을 차단했습니다')
    else console.error(error)
  }
})

login()은 click 같은 사용자 제스처에서 직접 호출해야 합니다. onLogin payload는 { accessToken, refreshToken, expiresIn, userInfo }입니다.

Guest 계정과 연결

loginAsGuest()는 없습니다. Guest와 영구 계정은 같은 auth.login() 흐름을 사용합니다. userInfo.isGuest === true이면 Starchild에서 Google, X, Email, Phone 또는 Wallet을 연결하세요. 앱에 연결 페이지를 직접 만들지 마세요.

const user = await auth.fetchUserInfo()
if (auth.isGuest() || user?.isGuest) {
  const tab = auth.bindAccount()
  if (!tab) window.location.href = auth.getBindAccountUrl()
}

연결 후 다음 fetchUserInfo() 또는 token refresh에서 isGuest: false가 표시됩니다. Guest의 결제와 되돌릴 수 없는 작업 허용 여부를 명시적으로 결정하세요.

서버 검증

현재 token을 읽어 서버에서 매 요청 검증합니다.

GET https://ai-api.iamstarchild.com/v1/oauth/userinfo
Authorization: Bearer <access-token>

소유권과 쿼터의 안정적인 키로 userInfoId를 사용하세요. 검증 실패는 401로 거부합니다. detail이 Insufficient scope인 403은 token에 승인된 권한이 없다는 뜻이며 만료 token과 다릅니다.

userinfo에는 userInfoId, agentName, agentAvatar, isGuest가 포함됩니다. token refresh/logout은 https://go-api.iamstarchild.com/v1/oauth/{refresh,logout}를 사용합니다.

세션 보안

Access token은 15분 동안 유효하며 기본적으로 12분마다, 페이지가 다시 표시될 때 갱신됩니다. Refresh token은 7일 동안 유효하고 localStorage의 starchild_rt_{clientId}에 저장됩니다. SDK 자동 갱신을 우선 사용하세요. getRefreshToken() 결과는 비밀번호처럼 다루고 기록하거나 외부로 보내거나 URL에 넣지 마세요. 결제와 민감한 작업은 검증 실패 시 fail closed 하세요.

문제 해결과 체크리스트
  • 팝업 차단: click handler에서 login()을 호출합니다.
  • Origin 오류: 서드파티 페이지의 scheme과 포트를 확인하고 6066을 사용하지 않습니다.
  • CORS 오류: allowed origins, 승인 상태를 확인하고 약 5분 기다립니다.
  • Guest: auth.bindAccount()를 사용하고 직접 연결 흐름을 만들지 않습니다.
  • 401: 다시 로그인합니다.

  • 403 Scope 오류: 필요한 승인 Scope로 다시 인증합니다.

  • [ ] 필요한 Scope만 요청

  • [ ] 운영과 모든 로컬 Origin 등록
  • [ ] 모든 보호 요청을 서버에서 검증
  • [ ] isGuest 처리
  • [ ] Refresh token을 기록하거나 전송하지 않기

다음으로 Starchild Auth SDK API 레퍼런스를 읽으세요. 예시는 starchild-auth-sdk 0.4.1 기준입니다.