AltsCodex SDK — Backend Guide

Environment Environment Setup 환경변수 설정

All three SDKs read NO environment variables on their own — they accept plain options. Inject them from your server-side environment so the client secret never reaches the browser bundle. 세 SDK 모두 자체적으로 환경 변수를 읽지 않습니다. 옵션으로 직접 전달받습니다. 서버 측 환경변수로 주입해 클라이언트 시크릿이 절대 브라우저 번들에 도달하지 않도록 하세요.

# .env.local — 절대 git 에 커밋 금지, .gitignore 에 추가하세요
ALTSCODEX_AUTH_SERVER_URL=https://api.altscodex.com
ALTSCODEX_CLIENT_ID=your-registered-client-id
ALTSCODEX_CLIENT_SECRET=your-client-secret
ALTSCODEX_REDIRECT_URI=https://yourapp.com/getinfo

const AltsCodexBackend = require('@altscodex/sdk/backend');

const sdk = new AltsCodexBackend({
  authServerUrl: process.env.ALTSCODEX_AUTH_SERVER_URL,
  clientId:      process.env.ALTSCODEX_CLIENT_ID,
  clientSecret:  process.env.ALTSCODEX_CLIENT_SECRET,    // server side ONLY
  redirectUri:   process.env.ALTSCODEX_REDIRECT_URI,
});

# .env — 서버 측 전용, .gitignore 에 반드시 추가
ALTSCODEX_AUTH_SERVER_URL=https://api.altscodex.com
ALTSCODEX_CLIENT_ID=your-registered-client-id
ALTSCODEX_CLIENT_SECRET=your-client-secret
ALTSCODEX_REDIRECT_URI=https://yourapp.com/getinfo

# 단순 os.environ 방식
import os
from altscodex import AltsCodexBackend

sdk = AltsCodexBackend(
    auth_server_url=os.environ.get("ALTSCODEX_AUTH_SERVER_URL"),
    client_id=os.environ["ALTSCODEX_CLIENT_ID"],
    client_secret=os.environ["ALTSCODEX_CLIENT_SECRET"],
    redirect_uri=os.environ["ALTSCODEX_REDIRECT_URI"],
)

# Pydantic Settings 사용 시
from pydantic_settings import BaseSettings
from altscodex import AltsCodexBackend

class AltsCodexSettings(BaseSettings):
    auth_server_url: str = "https://api.altscodex.com"
    client_id: str
    client_secret: str
    redirect_uri: str

    model_config = {"env_prefix": "ALTSCODEX_"}

settings = AltsCodexSettings()
sdk = AltsCodexBackend(**settings.model_dump())

# .env — systemd EnvironmentFile / docker --env-file 로 주입
ALTSCODEX_AUTH_SERVER_URL=https://api.altscodex.com
ALTSCODEX_CLIENT_ID=your-registered-client-id
ALTSCODEX_CLIENT_SECRET=your-client-secret
ALTSCODEX_REDIRECT_URI=https://yourapp.com/getinfo

// os.Getenv 직접 사용
import (
    "log"
    "os"

    sdk "github.com/alts-codex/auth-sdk"
)

client, err := sdk.NewBackend(sdk.BackendConfig{
    AuthServerURL: os.Getenv("ALTSCODEX_AUTH_SERVER_URL"),
    ClientID:      os.Getenv("ALTSCODEX_CLIENT_ID"),
    ClientSecret:  os.Getenv("ALTSCODEX_CLIENT_SECRET"),
    RedirectURI:   os.Getenv("ALTSCODEX_REDIRECT_URI"),
})
if err != nil {
    log.Fatal(err)
}

// .env 로컬 로딩이 필요하면 caarlos0/env 또는 joho/godotenv 같은 작은 패키지 권장
// 프로덕션에서는 systemd EnvironmentFile=, docker --env-file, k8s Secret/ConfigMap 으로 주입
// SDK 자체는 dotenv 종속성을 가지지 않음 (표준 라이브러리만 사용)

Use a separate .env.<mode> per environment (local / staging / production). Next.js auto-loads .env.local; for plain Node use dotenv or PM2 ecosystem files. Python — use python-dotenv + a process manager (systemd / uvicorn --env-file). Go — inject via systemd EnvironmentFile, docker --env-file, or Kubernetes Secret/ConfigMap. 환경별로 .env.<mode> 파일을 분리하세요. Next.js 는 .env.local 을 자동 로드합니다. 순수 Node 는 dotenv 또는 PM2 ecosystem 파일 주입. Python 은 python-dotenv + 프로세스 매니저(systemd / uvicorn --env-file) 조합. Go 는 systemd EnvironmentFile, docker --env-file, Kubernetes Secret/ConfigMap 으로 주입.

Pitfalls ⚠️ Common Pitfalls ⚠️ 자주 부딪히는 함정

1. Use the registered hosts only 1. 등록된 호스트만 사용하세요

Do NOT point authServerUrl at invented subdomains like oauth.altscodex.com, auth.altscodex.com. They resolve to NXDOMAIN and every getSlotInfo() / get_slot_info() / GetSlotInfo call will fail with a network error. authServerUrl 을 oauth.altscodex.com, auth.altscodex.com 같은 미등록 서브도메인으로 박지 마세요. NXDOMAIN 이 떨어지고 모든 getSlotInfo() / get_slot_info() / GetSlotInfo 호출이 네트워크 오류로 실패합니다.

2. redirectUri must match the registered value EXACTLY 2. redirectUri 는 등록된 값과 정확히 일치해야 합니다

The redirectUri / redirect_uri / RedirectURI you pass must exactly match the value registered at the Developer Center — including scheme (https), host, port, path, and even trailing slash. Any difference triggers redirect_uri mismatch 401 at the OAuth callback step. redirectUri / redirect_uri / RedirectURI 는 개발자 센터에 등록된 값과 정확히 일치해야 합니다 — scheme(https), 호스트, 포트, 경로, 트레일링 슬래시까지. 한 글자라도 다르면 OAuth 콜백 단계에서 redirect_uri mismatch 401 이 발생합니다.

3. POST callback route only — never GET 3. 콜백 라우트는 POST 전용 — GET 금지

Express → app.post('/getinfo', ...). FastAPI → @app.post("/getinfo"). Go → http.HandleFunc handles all methods, but routers like chi/gin should pin to POST: r.MethodFunc(http.MethodPost, "/getinfo", client.HandleCallback). If wired as GET, the framework returns 405 and the originating call hangs until timeout. Express → app.post('/getinfo', ...). FastAPI → @app.post("/getinfo"). Go → http.HandleFunc 는 모든 메서드를 받지만, chi/gin 같은 라우터에서는 POST 로 명시: r.MethodFunc(http.MethodPost, "/getinfo", client.HandleCallback). GET 으로 묶으면 프레임워크가 405를 반환하고 호출 측이 타임아웃까지 hang 합니다.

4. The respose_type typo is intentional 4. respose_type 오타는 의도된 것입니다

The DeOAuth server expects the misspelled query parameter respose_type (not response_type). All three SDKs preserve it. Do not "fix" it in any fork — the server contract will break. DeOAuth 서버는 오타 형태의 쿼리 파라미터 respose_type (정상 스펠링 response_type 가 아닙니다) 을 기대합니다. 세 SDK 모두 이를 그대로 보존합니다. fork 시 절대 "수정" 하지 마세요 — 서버 계약이 깨집니다.

5. Migrating from @webxcom/sdk / github.com/webxcom/auth-sdk 5. @webxcom/sdk / github.com/webxcom/auth-sdk 마이그레이션

All three SDKs talk to the same backend. v1.x apps continue working unchanged during gradual migration — the platform server emits postMessage in dual-broadcast mode (from: "altscodex" + from: "webxcom") so the frontend SDK of either version stays compatible. 세 SDK 모두 같은 백엔드와 통신합니다. v1.x 앱은 코드 변경 없이 동작합니다 — 플랫폼 서버가 dual-broadcast(from: "altscodex" + from: "webxcom") 로 postMessage 를 발송해 양 버전 프론트엔드 SDK 가 모두 호환됩니다.

6. Always call shutdown() on process exit 6. 프로세스 종료 시 반드시 shutdown() 호출

If your server exits without calling shutdown, pending callback promises / futures / channels stay unresolved and connected clients see indefinite hang. Node — hook on SIGTERM/SIGINT. Python — wire it into FastAPI lifespan (preferred — also closes the SDK-owned httpx.AsyncClient). Go — hook client.Shutdown(ctx) alongside http.Server.Shutdown(ctx) in a signal.Notify handler. 서버가 shutdown 호출 없이 종료되면 대기 중인 콜백 promise / future / channel 들이 미완료 상태로 남아 연결된 클라이언트가 무한 hang 합니다. Node 는 SIGTERM/SIGINT 훅, Python 은 FastAPI lifespan 에 연결 (권장 — SDK 소유의 httpx.AsyncClient 도 함께 close), Go 는 signal.Notify 핸들러에서 client.Shutdown(ctx) 와 http.Server.Shutdown(ctx) 를 동시에 호출.

7. Python-specific: single-worker pending map 7. Python 전용: 단일 워커 pending map 제약

The Python SDK's pending map is in-process. If you run uvicorn --workers 4 and the DeOAuth callback hits a different worker than the one that called get_slot_info, the callback silently no-ops. For now, run a single worker (--workers 1) or use sticky sessions. Python SDK 의 pending map 은 프로세스 내 메모리에 있습니다. uvicorn --workers 4 환경에서 DeOAuth 콜백이 get_slot_info 를 호출한 워커와 다른 워커로 들어오면 콜백이 조용히 no-op 됩니다. 당분간은 단일 워커(--workers 1) 또는 sticky session 운영을 권장합니다.

8. Python-specific: must be called inside a running event loop 8. Python 전용: 실행 중인 event loop 안에서만 호출

The Python SDK is fully async. Calling sdk.get_slot_info(...) without await returns a coroutine object, not a result. From sync code, wrap with asyncio.run(...) or anyio.from_thread.run(...). Python SDK 는 완전 비동기입니다. sdk.get_slot_info(...) 를 await 없이 호출하면 coroutine 객체만 반환됩니다. 동기 코드에서는 asyncio.run(...) 또는 anyio.from_thread.run(...) 으로 감싸세요.

9. Go-specific: multi-replica deployments 9. Go 전용: 멀티 레플리카 배포 제약

The Go SDK's pending map is per-process (map[string]chan callbackResult). If your service runs multiple replicas behind a load balancer and the DeOAuth callback hits a replica different from the one that called GetSlotInfo, the callback silently no-ops and the originating request times out. Pin to one replica, use sticky sessions on state, or implement a Redis-backed pending store. Go SDK 의 pending map 은 프로세스별로 존재합니다 (map[string]chan callbackResult). 로드밸런서 뒤에서 멀티 레플리카로 실행 시 DeOAuth 콜백이 GetSlotInfo 를 호출한 레플리카와 다른 곳으로 들어오면 콜백이 조용히 no-op 되고 원 요청은 타임아웃됩니다. 단일 레플리카, sticky session(state 기준), 또는 Redis 기반 pending store 구현 중 하나를 선택하세요.

10. Go-specific: context cancellation does not cancel HandleCallback's token exchange 10. Go 전용: context 취소는 HandleCallback 의 token exchange 를 취소하지 않음

HandleCallback intentionally runs get_token in a goroutine with a fresh context.Background() so the DeOAuth server's HTTP connection isn't blocked. Cancelling the caller's request context will NOT abort the exchange. Use client.Shutdown(ctx) for that. HandleCallback 은 의도적으로 get_token 을 새 context.Background() 의 goroutine 에서 실행해 DeOAuth 서버의 HTTP 연결이 블록되지 않도록 합니다. 호출자의 request context 를 취소해도 exchange 는 중단되지 않습니다. 그 용도로는 client.Shutdown(ctx) 를 사용하세요.

Python+ Python SDK — Bonus Patterns Python SDK — 보너스 패턴

Testing with httpx.MockTransport httpx.MockTransport 로 테스트하기

The Python SDK accepts an injected httpx.AsyncClient, so you can run unit tests without a real DeOAuth server. The SDK's own test suite (6 ported Jest scenarios + contract checks) uses this exact pattern. Python SDK는 httpx.AsyncClient 를 주입받으므로 실제 DeOAuth 서버 없이 단위 테스트를 돌릴 수 있습니다. SDK 자체 테스트(Jest 시나리오 6개 포팅 + 계약 테스트)도 이 패턴을 사용합니다.

import json, httpx, pytest, asyncio
from altscodex import AltsCodexBackend

@pytest.mark.asyncio
async def test_login_succeeds():
    def handler(request):
        if "/authorize" in request.url.path:
            return httpx.Response(200, content=json.dumps({"success": True}).encode(),
                                  headers={"content-type": "application/json"})
        if "/get_token" in request.url.path:
            return httpx.Response(200, content=json.dumps({"id": "u-1"}).encode(),
                                  headers={"content-type": "application/json"})
        return httpx.Response(404)

    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
    sdk = AltsCodexBackend(
        client_id="cid", client_secret="cs",
        redirect_uri="http://localhost/cb", http_client=client,
    )
    try:
        task = asyncio.create_task(sdk.get_slot_info("jwt"))
        await asyncio.sleep(0.05)
        state = next(iter(sdk._pending_by_state))
        await sdk.handle_callback({"query": {"success": "1", "code": "c", "state": state}})
        result = await task
        assert result["id"] == "u-1"
    finally:
        await sdk.shutdown()

Multi-tenant SDK registry 멀티테넌트 SDK 레지스트리

class SdkRegistry:
    def __init__(self):
        self._by_client: dict[str, AltsCodexBackend] = {}

    def get(self, client_id: str) -> AltsCodexBackend:
        if client_id not in self._by_client:
            cfg = load_client_config(client_id)  # 너의 DB
            self._by_client[client_id] = AltsCodexBackend(
                client_id=client_id,
                client_secret=cfg.secret,
                redirect_uri=cfg.redirect_uri,
            )
        return self._by_client[client_id]

    async def shutdown(self):
        for sdk in self._by_client.values():
            await sdk.shutdown()

Resources 참고 자료

• PyPI · altscodex-sdk
• GitHub · banstorm/altscodex-sdk-python
• examples/fastapi_app.py

Go+ Go SDK — Bonus Patterns Go SDK — 보너스 패턴

Bundled local test server 번들된 로컬 테스트 서버

The Go module ships with cmd/localtestserver — a self-contained mock that runs the full authorize → callback → get_token flow locally without any external network dependency. Useful for integration tests and local UI development. Go 모듈은 cmd/localtestserver 를 함께 배포합니다 — 외부 네트워크 의존성 없이 전체 authorize → callback → get_token 플로우를 로컬에서 돌리는 mock 입니다. 통합 테스트 / 로컬 UI 개발에 유용합니다.

# 두 개의 로컬 HTTP 서버를 동시 기동
go run ./cmd/localtestserver

# 출력 예:
# local frontend mock listening on http://127.0.0.1:8888
# local backend test server listening on http://127.0.0.1:9999

# 사용 가능한 라우트
curl http://127.0.0.1:9999/frontend/login-url
curl "http://127.0.0.1:9999/login?jwt=test-jwt"

# 환경변수로 포트/URL 오버라이드 가능
# SDK_CLIENT_ID, SDK_CLIENT_SECRET, SDK_FRONTEND_ADDR, SDK_BACKEND_ADDR,
# SDK_FRONTEND_BASE_URL, SDK_BACKEND_BASE_URL

Injecting a custom *http.Client (proxies, mTLS, retries) 커스텀 *http.Client 주입 (프록시 / mTLS / 재시도)

Pass BackendConfig.HTTPClient to override the default http.Client{Timeout: 15s}. Useful for corporate proxies, mTLS certificates, custom retry budgets, or instrumented transports. 기본 http.Client{Timeout: 15s} 를 오버라이드하려면 BackendConfig.HTTPClient 를 전달하세요. 기업 프록시, mTLS 인증서, 커스텀 재시도, 계측된 transport 에 유용합니다.

import (
    "crypto/tls"
    "net/http"
    "time"

    sdk "github.com/alts-codex/auth-sdk"
)

// mTLS + 30초 타임아웃 클라이언트
tlsCert, _ := tls.LoadX509KeyPair("client.crt", "client.key")
customClient := &http.Client{
    Timeout: 30 * time.Second,
    Transport: &http.Transport{
        TLSClientConfig: &tls.Config{Certificates: []tls.Certificate{tlsCert}},
    },
}

client, err := sdk.NewBackend(sdk.BackendConfig{
    ClientID:     os.Getenv("ALTSCODEX_CLIENT_ID"),
    ClientSecret: os.Getenv("ALTSCODEX_CLIENT_SECRET"),
    RedirectURI:  os.Getenv("ALTSCODEX_REDIRECT_URI"),
    HTTPClient:   customClient,
})

Testing with httptest.Server httptest.Server 로 테스트하기

import (
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "testing"
    "time"

    sdk "github.com/alts-codex/auth-sdk"
)

func TestLoginFlow(t *testing.T) {
    authServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        switch r.URL.Path {
        case "/v1/oauth-meta/authorize":
            _ = json.NewEncoder(w).Encode(map[string]bool{"success": true})
        case "/v1/oauth-meta/get_token":
            _ = json.NewEncoder(w).Encode(map[string]any{
                "data": []map[string]any{{"id": "slot-1", "access_token": "t"}},
            })
        }
    }))
    defer authServer.Close()

    client, _ := sdk.NewBackend(sdk.BackendConfig{
        AuthServerURL: authServer.URL,
        ClientID:      "cid", ClientSecret: "cs",
        RedirectURI:   "http://localhost/cb",
    })

    // HandleCallback 을 직접 호출해 콜백 도착을 흉내낸다 (httptest.NewRecorder 사용)
    _ = client
    _ = time.Second
}

Resources 참고 자료

• pkg.go.dev · github.com/alts-codex/auth-sdk — godoc + latest release godoc + 최신 릴리스
• GitHub · alts-codex/auth-sdk — source, issues, full README 소스, 이슈, 전체 README
• cmd/localtestserver/main.go — runnable local mock server 실행 가능한 로컬 mock 서버
• github.com/webxcom/auth-sdk — legacy module (deprecated, use altscodex) 레거시 모듈 (deprecated, altscodex 사용 권장)