name	toss-iap-proxy-ops
description	Toss IAP 검증 스킬 — Edge Function 404 우회, Service Role 감지, mTLS mock 설정, 토큰 헬퍼 분리, subscriptions 활성화 E2E.

Toss IAP Proxy Ops

Toss 미니앱의 IAP(인앱 결제) 검증이 Edge Function 경로 차단(404)으로 실패할 때 FastAPI proxy로 우회하는 패턴, Service Role Key 감지 방식, mTLS mock 강제 설정을 표준화한 스킬.

언제 사용하나

"IAP 검증이 404로 실패하는데 어떻게 우회할까?"
"Edge Function에서 Supabase Service Role을 감지하려고 하는데?"
"mTLS 검증을 개발 단계에서 스킵하고 싶은데?"
"iap.ts 토큰 헬퍼가 너무 많으니 분리해줄래?"
"결제는 됐는데 subscriptions 테이블에 is_active가 안 세팅돼요"
"toss_orders에만 granted되고 구독 활성화가 안 돼요"

공식 문서 (항상 최신 기준 재확인)

IAP 공식 문서: https://developers-apps-in-toss.toss.im/in-app-purchase/intro.html
IAP Webhook: https://developers-apps-in-toss.toss.im/in-app-purchase/webhook.html
Supabase Edge Function: https://supabase.com/docs/guides/functions
Supabase Secrets: https://supabase.com/docs/guides/functions/secrets

패턴 1: IAP Edge Function 404 → FastAPI Proxy 우회

문제 현상

Toss 미니앱(intoss-private:// URL scheme)이 /functions/v1/ 경로 차단
Edge Function 호출 시 404 응답 반환
검증 서버 연동 불가능

해결 방식

1.1 FastAPI 엔드포인트 준비

# FastAPI 서버 실행 (포트 8765)
cd /Users/family/jason/TaillogToss
python -m uvicorn Backend.main:app --reload --host 127.0.0.1 --port 8765

FastAPI 라우터:

File: Backend/app/features/subscription/router.py
Endpoint: POST /api/v1/subscription/iap/verify
Method: Service Role Key 없이 JWT 검증 스킵, body.userId 사용

1.2 adb reverse 설정

# Device 포트 8000이 점유되어 있으면 8765 사용
adb reverse tcp:8765 tcp:8765

이유: 로컬 개발 시 device에서 http://127.0.0.1:8765/api/v1/...로 접근 가능

1.3 클라이언트 코드 수정

File: src/lib/api/iap.ts
Function: verifyAndGrant(receipt, userId)
Line: 269-284

// 기존 코드 (Edge Function 직접 호출)
try {
  const response = await fetch(`${SUPABASE_URL}/functions/v1/verify-iap-order`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ receipt, userId }),
  });
  
  // 404 감지 → FastAPI proxy로 우회
  if (response.status === 404) {
    console.warn('[IAP] Edge Function 404, FastAPI proxy로 우회');
    return await fallbackFastAPIVerify(receipt, userId);
  }
  
  return await response.json();
} catch (error) {
  console.error('[IAP] 검증 실패:', error);
  return await fallbackFastAPIVerify(receipt, userId);
}

// FastAPI proxy 호출
async function fallbackFastAPIVerify(receipt: string, userId: string) {
  const response = await fetch('http://127.0.0.1:8765/api/v1/subscription/iap/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ receipt, userId }),
  });
  
  if (!response.ok) {
    throw new Error(`FastAPI verify failed: ${response.status}`);
  }
  
  return await response.json();
}

검증 체크리스트

FastAPI 서버 실행 중 (:8765)
adb reverse tcp:8765 tcp:8765 설정 완료
src/lib/api/iap.ts:269-284 fallback 함수 추가
앱 재빌드 후 IAP 검증 재시도
로그에 404 → proxy 전환 메시지 확인

패턴 2: Service Role Key 감지 (JWT Claims 파싱)

문제 현상

Supabase 환경변수명 SUPABASE_SERVICE_ROLE_KEY는 prefix SUPABASE_ 때문에 거부됨
Edge Function에서 Service Role을 명시적으로 감지할 방법이 없음
FastAPI가 service role로 호출할 때와 클라이언트가 호출할 때 다른 검증 로직 필요

해결 방식

2.1 JWT Token Claims 파싱 함수

File: supabase/functions/verify-iap-order/main.ts

// JWT 토큰에서 role 클레임 추출
function parseTokenRole(token: string): string | null {
  try {
    // JWT 형식: header.payload.signature
    const parts = token.split('.');
    if (parts.length !== 3) {
      console.log('[JWT] Invalid token format');
      return null;
    }

    // payload 부분 base64 디코딩
    const payload = parts[1];
    // base64url -> base64 변환 (padding 처리)
    const decoded = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
    const claims = JSON.parse(decoded);

    return claims.role || null;
  } catch (error) {
    console.error('[JWT] Parse failed:', error);
    return null;
  }
}

// 함수 사용 예시
async function handleVerifyRequest(req: Request) {
  const authHeader = req.headers.get('authorization');
  const token = authHeader?.replace('Bearer ', '') || '';
  const role = parseTokenRole(token);

  if (role === 'service_role') {
    // FastAPI 등 서버에서 호출했다고 간주
    // JWT 검증 스킵, body.userId 신뢰
    const { userId, receipt } = await req.json();
    return await processIAPWithoutJWTVerification(userId, receipt);
  } else {
    // 클라이언트 호출이므로 JWT + 본인 확인
    return await processIAPWithFullValidation(token, req);
  }
}

2.2 FastAPI에서 호출 시

File: Backend/app/features/subscription/router.py

@router.post("/api/v1/subscription/iap/verify")
async def verify_iap_order(request: IAPVerifyRequest):
    """
    FastAPI에서 Supabase Edge Function으로 요청.
    Service Role로 호출되므로 JWT 검증 스킵.
    """
    user_id = request.user_id  # 클라이언트가 보낸 user_id 직접 사용
    receipt = request.receipt

    # 앱 서명 + 영수증 검증 (Toss 공식 API)
    verification_result = await verify_with_toss_server(receipt)
    
    if verification_result["status"] == "verified":
        # 구독 권리 부여
        await grant_subscription(user_id)
        return {"success": True}
    
    return {"success": False, "reason": "Invalid receipt"}

핵심 원칙:

JWT claims의 role === 'service_role'이면 JWT 검증 스킵
body.userId를 신뢰하고 직접 사용
클라이언트 JWT는 항상 검증

검증 체크리스트

parseTokenRole(token) 함수 구현
Edge Function에서 role 감지 후 분기 처리
FastAPI에서 Service Role 호출 시 JWT 검증 스킵 로직 추가
Edge Function + FastAPI 통합 테스트 완료

패턴 3: mTLS Mock 강제 설정

문제 현상

개발 단계에서 실제 mTLS 인증서가 없어 Toss 서버 연동 불가
프로덕션 환경변수명을 개발에 쓸 수 없음
mTLS mock 모드의 우선 순위가 명확하지 않음

해결 방식

3.1 Supabase Secrets 설정

# Supabase 프로젝트 대시보드에서 또는 CLI로 설정
supabase secrets set TOSS_MTLS_MODE=mock

핵심:

환경변수명: TOSS_MTLS_MODE (Supabase 제약으로 SUPABASE_ prefix 불가)
값: mock (개발 모드) 또는 production (실제 환경)
mock 설정이 있으면 실제 cert/key 무시하고 우선 적용

3.2 Edge Function에서 적용

File: supabase/functions/_shared/mtlsMode.ts

// mTLS 모드 감지
function getMTLSMode(): 'mock' | 'production' {
  const mode = Deno.env.get('TOSS_MTLS_MODE');
  return mode === 'mock' ? 'mock' : 'production';
}

// Mock mTLS Client 사용
class MockMTLSClient {
  async verifyReceipt(receipt: string): Promise<VerificationResult> {
    console.log('[mTLS] Mock mode enabled, skipping real certificate validation');
    return {
      status: 'success',
      orderId: `mock_order_${Date.now()}`,
      amount: 9900,
    };
  }
}

// 실제 호출 코드
async function verifyIAPReceipt(receipt: string) {
  const mode = getMTLSMode();
  
  if (mode === 'mock') {
    const mockClient = new MockMTLSClient();
    return await mockClient.verifyReceipt(receipt);
  } else {
    // 실제 cert/key로 mTLS 연결
    return await realMTLSClient.verifyReceipt(receipt);
  }
}

3.3 배포 확인

# 현재 Supabase 설정 확인
supabase secrets list

# 출력 예시:
# TOSS_MTLS_MODE=mock
# TOSS_CERT_PEM=<...>  (프로덕션에만 설정)
# TOSS_KEY_PEM=<...>   (프로덕션에만 설정)

배포 순서:

Supabase 대시보드 → Settings → Secrets
TOSS_MTLS_MODE=mock 입력
"Save" 클릭
Edge Function 재배포 또는 재시작

검증 체크리스트

TOSS_MTLS_MODE=mock 설정 완료
supabase secrets list로 확인
Edge Function 재배포
Toss API 호출 시 mock 응답 확인 (로그)
프로덕션 배포 전 TOSS_MTLS_MODE 제거 또는 production 변경

패턴 4: iap-invoke.ts 분리

문제 현상

src/lib/api/iap.ts에 토큰 헬퍼 함수 7개가 섞여 있음
외부 의존성이 있어서 복잡도 증가
테스트/재사용성 어려움

해결 방식

4.1 헬퍼 함수 목록 (분리 대상)

// 현재 iap.ts에 포함된 함수들
1. getAuthToken()           // Supabase JWT 토큰 획득
2. buildIAPHeaders()        // IAP 요청 헤더 생성
3. encodeReceiptPayload()   // 영수증 payload 인코딩
4. decodeTokenClaims()      // JWT 클레임 파싱
5. validateTokenExpiry()    // 토큰 만료 검증
6. sanitizeReceipt()        // 영수증 형식 검증
7. parseIAPResponse()       // 검증 응답 파싱

4.2 새 파일 생성

File: src/lib/api/iap-invoke.ts

/**
 * IAP 토큰/헬퍼 함수 전용 모듈.
 * iap.ts에서만 import 가능 (외부 import 금지).
 */

import { JwtPayload, jwtDecode } from 'jwt-decode'; // 필요시만 추가

// ============ 토큰 함수 ============

export function getAuthToken(): string {
  // Supabase 클라이언트에서 JWT 획득
  // const supabase = useSupabaseClient();
  // return supabase.auth.session?.access_token || '';
}

export function decodeTokenClaims(token: string): JwtPayload | null {
  try {
    return jwtDecode(token);
  } catch (error) {
    console.error('[IAP] Token decode failed:', error);
    return null;
  }
}

export function validateTokenExpiry(token: string): boolean {
  const claims = decodeTokenClaims(token);
  if (!claims?.exp) return false;
  
  const now = Math.floor(Date.now() / 1000);
  return claims.exp > now;
}

// ============ 요청 함수 ============

export function buildIAPHeaders(token: string): Record<string, string> {
  return {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'X-IAP-Request-Id': `iap_${Date.now()}_${Math.random()}`,
  };
}

export function encodeReceiptPayload(receipt: string): string {
  return Buffer.from(receipt).toString('base64');
}

export function sanitizeReceipt(receipt: string): string {
  return receipt.trim().replace(/\s+/g, '');
}

// ============ 응답 함수 ============

export function parseIAPResponse(response: any): {
  success: boolean;
  subscriptionId?: string;
  expiryDate?: number;
  error?: string;
} {
  if (!response || typeof response !== 'object') {
    return { success: false, error: 'Invalid response' };
  }

  if (response.status !== 'verified') {
    return { success: false, error: response.statusMessage || 'Verification failed' };
  }

  return {
    success: true,
    subscriptionId: response.latestReceiptInfo?.[0]?.subscription_id,
    expiryDate: response.latestReceiptInfo?.[0]?.expires_date_ms,
  };
}

4.3 iap.ts 수정

File: src/lib/api/iap.ts (수정)

// 기존: 함수들이 섞여 있음
// 변경: iap-invoke에서 import

import {
  getAuthToken,
  buildIAPHeaders,
  encodeReceiptPayload,
  decodeTokenClaims,
  validateTokenExpiry,
  sanitizeReceipt,
  parseIAPResponse,
} from './iap-invoke';

export async function verifyAndGrant(receipt: string, userId: string) {
  const token = getAuthToken();
  
  if (!validateTokenExpiry(token)) {
    throw new Error('Token expired');
  }

  const sanitized = sanitizeReceipt(receipt);
  const headers = buildIAPHeaders(token);

  try {
    const response = await fetch(`${SUPABASE_URL}/functions/v1/verify-iap-order`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ receipt: sanitized, userId }),
    });

    if (response.status === 404) {
      return await fallbackFastAPIVerify(sanitized, userId);
    }

    const data = await response.json();
    return parseIAPResponse(data);
  } catch (error) {
    console.error('[IAP] Verify failed:', error);
    return { success: false, error: String(error) };
  }
}

// 나머지 함수들은 변경 없음

검증 체크리스트

src/lib/api/iap-invoke.ts 생성
토큰 헬퍼 7개 함수 이동
src/lib/api/iap.ts에서 import 추가
타입스크립트 컴파일 성공 확인
기존 IAP 기능 동작 확인

패턴 5: subscriptions 활성화 E2E (검증 완료 2026-05-04)

문제 현상

verify-iap-order Edge Function이 toss_orders.grant_status='granted'만 기록
subscriptions 테이블 업데이트 없음 → is_active=false 그대로
useIsPro() → false → PRO 기능 잠금 해제 안 됨

근본 원인

verify-iap-order/main.ts에 toss_orders upsert 이후 subscriptions 업데이트 로직 누락.
subscriptions.user_id에 UNIQUE 제약도 없어서 upsert 자체가 불가능했음.

해결 순서

5-1. UNIQUE 제약 마이그레이션

-- supabase/migrations/20260504000001_subscriptions_user_id_unique.sql
ALTER TABLE public.subscriptions
  ADD CONSTRAINT subscriptions_user_id_key UNIQUE (user_id);

# DB에 직접 적용 (migration drift 시)
supabase db query "DO \$\$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname='subscriptions_user_id_key') THEN ALTER TABLE public.subscriptions ADD CONSTRAINT subscriptions_user_id_key UNIQUE (user_id); END IF; END\$\$;" --linked

5-2. Edge Function PRODUCT_GRANTS 매핑 추가

File: supabase/functions/verify-iap-order/main.ts

const SUPABASE_SERVICE_ROLE_KEY = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY');

// productId → 지급 유형 매핑 (src/types/subscription.ts IAP_PRODUCTS와 동기화)
const PRODUCT_GRANTS: Record<string, { planType?: string; aiTokens?: number; durationDays?: number }> = {
  'ait.0000020829.09e69bf9.90a91624b0.7443236299': { planType: 'PRO_MONTHLY', durationDays: 30 },
  'ait.0000020829.b0b00d71.17c5290dc1.7444362301': { aiTokens: 10 },
  'ait.0000020829.32dc32cf.49e67a4cfa.7443541064': { aiTokens: 30 },
};

5-3. activateSubscription 함수 추가

async function activateSubscription(userId: string, productId: string): Promise<void> {
  if (!SUPABASE_URL || !SUPABASE_SERVICE_ROLE_KEY) return;

  const grant = PRODUCT_GRANTS[productId];
  if (!grant) return;

  const now = new Date();
  const svcHeaders = {
    apikey: SUPABASE_SERVICE_ROLE_KEY,
    Authorization: `Bearer ${SUPABASE_SERVICE_ROLE_KEY}`,
    'Content-Type': 'application/json',
  };

  if (grant.planType) {
    // PRO_MONTHLY: subscriptions upsert (on_conflict=user_id)
    const nextBilling = new Date(now);
    nextBilling.setDate(nextBilling.getDate() + (grant.durationDays ?? 30));

    await fetch(`${SUPABASE_URL}/rest/v1/subscriptions?on_conflict=user_id`, {
      method: 'POST',
      headers: { ...svcHeaders, Prefer: 'resolution=merge-duplicates,return=minimal' },
      body: JSON.stringify([{
        user_id: userId,
        plan_type: grant.planType,
        is_active: true,
        next_billing_date: nextBilling.toISOString().split('T')[0],
        updated_at: now.toISOString(),
      }]),
    });
  } else if (grant.aiTokens) {
    // 토큰 상품: 기존 row PATCH or 신규 INSERT
    const getResp = await fetch(
      `${SUPABASE_URL}/rest/v1/subscriptions?user_id=eq.${userId}&select=id,ai_tokens_remaining,ai_tokens_total`,
      { headers: svcHeaders },
    );
    const rows = await getResp.json().catch(() => []) as Array<{
      id: string; ai_tokens_remaining: number | null; ai_tokens_total: number | null;
    }>;

    if (rows.length > 0) {
      await fetch(`${SUPABASE_URL}/rest/v1/subscriptions?user_id=eq.${userId}`, {
        method: 'PATCH',
        headers: { ...svcHeaders, Prefer: 'return=minimal' },
        body: JSON.stringify({
          ai_tokens_remaining: (rows[0].ai_tokens_remaining ?? 0) + grant.aiTokens,
          ai_tokens_total: (rows[0].ai_tokens_total ?? 0) + grant.aiTokens,
          updated_at: now.toISOString(),
        }),
      });
    } else {
      await fetch(`${SUPABASE_URL}/rest/v1/subscriptions?on_conflict=user_id`, {
        method: 'POST',
        headers: { ...svcHeaders, Prefer: 'resolution=merge-duplicates,return=minimal' },
        body: JSON.stringify([{
          user_id: userId, plan_type: 'FREE', is_active: false,
          ai_tokens_remaining: grant.aiTokens, ai_tokens_total: grant.aiTokens,
        }]),
      });
    }
  }
}

5-4. handleRequest에서 호출

// upsertTossOrder 성공 직후, response 반환 전에 삽입
if (grantStatus === 'granted') {
  try {
    await activateSubscription(resolvedUserId!, body.productId);
  } catch (err) {
    console.error('[verify-iap-order] subscription activation failed (non-fatal):', err);
    // non-fatal: toss_orders grant는 이미 기록됨
  }
}

5-5. 배포

supabase functions deploy verify-iap-order --no-verify-jwt

E2E 검증 방법

# 1. 앱에서 [DEV] IAP 바이패스 버튼 누름
# 2. DB 확인
supabase db query "SELECT user_id, plan_type, is_active, next_billing_date, updated_at FROM subscriptions WHERE user_id = '<userId>';" --linked

# 기대값:
# is_active: true
# plan_type: PRO_MONTHLY
# next_billing_date: <오늘+30일>

Failure Modes

증상	원인	해결
`toss_orders` granted, `subscriptions` 없음	activateSubscription 미호출 또는 SUPABASE_SERVICE_ROLE_KEY 없음	Edge Function 재배포 + secrets 확인
upsert 400 에러	`subscriptions.user_id` UNIQUE 제약 없음	5-1 마이그레이션 재실행
`plan_type` enum 에러	DB enum: `FREE`, `PRO_MONTHLY`, `PRO_YEARLY` 외 값 사용	PRODUCT_GRANTS planType 값 확인
토큰 상품 증분 안 됨	PATCH 경로에서 user row 없을 때 INSERT 미처리	else 분기 확인

전체 운영 순서 (권장)

FastAPI 준비
- FastAPI :8765 실행 확인
- Backend/app/features/subscription/router.py 검토
클라이언트 수정
- src/lib/api/iap.ts:269-284 fallback 함수 추가
- 앱 재빌드
Edge Function 업그레이드
- supabase/functions/verify-iap-order/main.ts JWT 파싱 함수 추가
- role 기반 분기 처리 구현
mTLS 설정
- supabase secrets set TOSS_MTLS_MODE=mock 적용
- Edge Function 재배포
코드 리팩토링
- src/lib/api/iap-invoke.ts 생성
- src/lib/api/iap.ts import 수정
- 통합 테스트
검증 및 문서 동기화
- IAP 엔드-투-엔드 검증 완료
- docs/PROJECT-STATUS.md 업데이트
- docs/ref/AIT-IAP-MESSAGE-POINTS-REFERENCE.md 패턴 추가

Failure Modes

404 우회 작동 안 함: adb reverse 설정 누락 또는 FastAPI 서버 미실행 → adb logcat -d | grep IAP 확인
JWT claims 파싱 실패: 토큰 format 오류 (header.payload.signature 아님) → jwtDecode() 라이브러리 대체
mTLS mock이 안 먹음: Supabase secrets 배포 후 Edge Function 재시작 필요 → supabase functions list --verbose 확인
iap-invoke 분리 후 빌드 실패: 순환 import 확인 → iap-invoke.ts에서 iap.ts import 금지