SJH

문제 해결 포트폴리오 / SaaS 과금 / 멀티테넌트 보안

시나리오 검증AI Usage Billing Gateway

과금 중복 처리와 Ledger 검증

멀티테넌트 과금 흐름에서 API Key hash 저장, 사용량 중복 처리, Webhook duplicate/conflict, append-only ledger invariant를 검증했습니다.

해결 키워드API Key HashIdempotencyWebhookLedger
프로젝트
AI Usage Billing Gateway
참여
개인 / BE 1
기술
Java · Spring Boot · PostgreSQL · Redis · Spring Security

문제 구간 아키텍처

멀티테넌트 과금에서 API key hash 인증, usage idempotency, invoice, webhook duplicate/conflict, append-only ledger를 연결한 아키텍처
API Key 인증, usage idempotency, webhook duplicate/conflict, append-only ledger를 tenant 경계 안에서 검증한 구조입니다.

핵심 설계 판단

  • API Key raw value는 1회만 반환하고, DB에는 prefix/hash만 저장합니다.
  • Usage와 webhook 중복 요청은 예외가 아니라 정상 입력으로 처리합니다.
  • Usage Event, Invoice, Append-only Ledger, Audit Log를 과금 판단의 최종 기준 데이터로 둡니다.

문제

  1. API Key 원문 저장은 유출 시 tenant 보안 사고로 이어질 수 있었습니다.
  2. 사용량 수집과 결제 webhook은 retry와 duplicate delivery가 정상 입력처럼 들어올 수 있었습니다.
  3. invoice, payment, ledger 흐름은 중복 처리와 감사 가능성을 함께 만족해야 했습니다.

해결

  1. API Key는 raw value를 1회만 반환하고 DB에는 prefix와 hash만 저장하는 방식으로 정리했습니다.
  2. usage event와 webhook은 idempotency key, providerEventId, payload hash로 duplicate/conflict를 분리했습니다.
  3. append-only ledger invariant를 두어 debit/credit balance와 audit log를 검증 대상으로 만들었습니다.

결과

  1. API Key 저장 방식, 사용량 중복 처리, quota reservation, invoice scheduler, Webhook 중복 처리, refund reversal ledger를 시나리오로 검증했습니다.
  2. Audit metadata sanitizer로 민감 metadata redaction 경계를 unit test로 검증했습니다.
  3. 혼합 사용량 부하 테스트는 2026-05-23 local full mixed repeat3에서 checks 150/150/run, HTTP failure 0/150/run을 기록했습니다.

검증 근거

API Key 저장 방식

시나리오 검증

raw key 1회 반환, DB에는 prefix/hash 저장

사용량 중복 처리

시나리오 검증

중복 usage event 처리와 request hash mismatch 구분

Webhook 중복 처리

시나리오 검증

providerEventId와 payload hash로 duplicate/conflict 구분

Refund reversal ledger

시나리오 검증

refund webhook의 balanced reversal, duplicate idempotency, original ledger group 추적 검증

혼합 사용량 부하 테스트

측정 완료

2026-05-23 local full mixed repeat3: 5 VU, 30s, checks 150/150/run, HTTP failure 0/150/run, p95 18.5976-44.1454ms, invoice/webhook branch 각 6회/run

구현 포인트

  1. tenant isolation은 organization 단위 경계와 API Key 인증 흐름으로 설명합니다.
  2. 중복 요청은 예외가 아니라 정상 입력으로 보고 request hash mismatch 같은 conflict를 별도로 다룹니다.
  3. quota, scheduler, audit/counter guard 세부는 GitHub README/docs 근거로 분리했습니다.

세부 테스트, guard, raw artifact는 GitHub README와 docs에 정리했습니다.

GitHub 근거 보기