# ZKProofID — 영지식증명 기반 연령 인증 SaaS + 양자내성 드론 보안 플랫폼

> **대한민국 특허 출원 완료** | Aleo 블록체인 ZKP 기반 | 완전 오프라인 동작 | 개인정보 Zero 노출

---

## 🛡️ 프로젝트 개요

**ZKProofID**는 Aleo 블록체인의 영지식증명(Zero-Knowledge Proof, ZKP) 기술을 활용하여
사용자의 생년월일·이름·주민번호 등 개인정보를 **일절 공개하지 않으면서도**
성인/미성년자 여부를 안전하게 인증하는 오프라인 SaaS 플랫폼입니다.

### 핵심 가치
- **Zero Privacy Leak**: 검증 단말기에 개인정보가 전달되지 않음
- **Offline First**: QR 코드 기반 오프라인 전달, 인터넷 불필요
- **위변조 불가**: Groth16/Marlin 영지식증명의 수학적 보증
- **4가지 연령 등급**: 다양한 업종 요구사항 대응

---

## 📱 주요 기능

### ✅ 구현 완료

| 기능 | 설명 |
|------|------|
| 랜딩 페이지 | SaaS 소개, 연령 등급, 작동 원리 |
| 사용자 앱 (user.html) | 커스텀 캘린더 생년월일 선택 + WebAuthn 생체인증 + ZKP 생성 + QRCode 표시 (완전 인라인) |
| 검증 단말기 (verify.html) | 카메라 QR 스캔 + 수동 입력, ZKP 검증, 이력 관리 |
| 관리 대시보드 (dashboard.html) | 실시간 KPI, 5종 차트, 가맹점 관리, 인증 로그 |
| 쇼핑 ZKP 데모 (shop.html) | 쿠팡 스타일 이커머스 + PASS 3단계 인증 + ZKP 5단계 애니메이션 |
| **SSO 통합 데모 (shopping.html)** | **Aleo ZKP SSO — 현대/롯데/CJ/GS/NS/홈앤쇼핑 6개 채널 통합, 구독 요금제, API 비교표** |
| **가맹점 시연 데모 (demo.html)** | **4가지 시나리오 탭 · PASS/FAIL 시연 · 고객+가맹점 패널 · 영업 포인트** |
| QR 접근 경로 (qr-access.html) | 4개 페이지 QR코드 + PWA 설치 가이드 |
| **온라인 쇼핑몰 데모 (shop.html)** | **쿠팡 스타일 이커머스 · PASS 3단계 모달 · ZKP 5단계 애니메이션 · QR 발급** |
| **쇼핑몰 인증 앱 (shop-verify.html)** | **4단계 생체인증+ZKP+인증QR 사용자 흐름** |
| **🆕 ZKP SSO 홈쇼핑 통합 (shopping.html)** | **Aleo ZKP SSO · 6개 홈쇼핑 동시연결 · 기존SSO vs ZKP SSO 비교 · ROI계산기 · 구독 요금제** |
| ZKP 엔진 | Leo/Aleo 회로 시뮬레이터, QR 직렬화/파싱 (js/zkp-engine.js) |
| DB 스키마 | verify_logs, merchants 테이블 |
| 샘플 데이터 | 8개 가맹점, 10개 검증 로그 초기 데이터 |

### ✅ 백엔드 서버 (Node.js + PostgreSQL 16) — 완성

> 상세: `server/README-SERVER.md`

| 파일 | 설명 |
|------|------|
| `server/server.js` | Express 4 메인 서버 |
| `server/db/schema.sql` | PostgreSQL 16 스키마 (6개 테이블) |
| `server/db/connection.js` | pg.Pool 연결 풀 |
| `server/db/init.js` | 스키마 자동 초기화 |
| `server/routes/auth.js` | PASS 본인인증 + JWT |
| `server/routes/zkp.js` | ★ 서버 ZKP 생성 (거짓 입력 차단) |
| `server/routes/verify.js` | QR 검증 + 로그 |
| `server/routes/merchant.js` | 가맹점 관리 |
| `server/routes/admin.js` | KPI 대시보드 |

**지원 DB 호스팅**: Supabase (무료) / Neon (무료) / AWS RDS / Railway

### ⚠️ 연령인증 데모 모드 안내 (중요)

현재 `user.html` / `shop.html` / `shop-verify.html` / `index.html`의 연령인증은
**사용자가 화면에서 직접 선택한 생년월일**을 그대로 신뢰하는 **데모/시뮬레이션**입니다.
따라서 미성년자라도 성인 생년월일을 입력하면 성인으로 인식됩니다.
이는 정적 웹사이트(클라이언트 JS)의 근본적 한계이며, 실제 서비스에서는
**서버가 통신3사로부터 검증한 값**만 사용해야 조작이 불가능해집니다.

- 각 데모 페이지 상단에 **"⚠️ 데모 모드"** 경고 배너를 표시하여 명확히 안내함
- `js/age-verify-service.js` — 데모(demo) ↔ 실전(real) 전환용 서비스 레이어 (설정값 2개만 바꾸면 전환 가능하도록 설계)
- 실전 전환 상세 가이드: **`server/TELECOM-AUTH-INTEGRATION.md`** (통신3사 연동 절차, 대행사 비교, 비용, 개발 범위)

### 🆕 `privacy.html` 실제 Aleo SDK 기반 ZK Proof 생성 (진짜 연동, 시뮬레이션 아님)

`privacy.html`의 `#live-demo` STEP 3(회로 실행 & 증명 생성) 단계는 이제 **Aleo 공식 SDK(`@provablehq/sdk`, jsDelivr `+esm` 경로)를 브라우저에서 실제로 로드**하여 다음을 수행합니다:

- `new sdk.Account()`로 **실제 유효한 Aleo 키페어/주소** 생성 (시뮬레이션 문자열이 아님)
- `sdk.Program.fromString()`으로 실제 Aleo Instructions(bytecode) 회로(`membership_proof_live.aleo`) 파싱
- `ProgramManager.run()`으로 **진짜 Groth16 증명 키 합성 + 회로 실행**을 수행 (증명 계산은 무겁기 때문에 Web Worker에서 실행하여 UI 프리징 방지)
- 계산 중 SDK가 내부적으로 출력하는 실제 로그(`Loading program`, `Creating authorization`, `Executing program` 등)를 실시간으로 화면 로그 패널에 중계

**UI 토글**: STEP 3 화면에 `실제 Aleo SDK로 진짜 Groth16 증명 계산` 체크박스가 있으며, 체크 해제 시 빠른 애니메이션 시연 모드(기존 방식)로 즉시 전환 가능합니다. 실제 모드 실행 실패 시(예: 네트워크 문제) 자동으로 시연 모드로 안전하게 폴백합니다.

**알려진 제약(투자자 데모 시 안내 필요)**:
- Aleo 공식 네트워크 API(`api.explorer.provable.com`)가 이 프리뷰 도메인에 대해 CORS를 막아, edition/amendment 조회는 실패하고 기본값으로 진행됩니다(치명적이지 않음, 경고 로그로 표시).
- WASM 멀티스레딩(`initThreadPool`)이 Worker 스크립트 cross-origin 문제로 동작하지 않아 **증명 키 합성이 싱글스레드로 느리게(수 초~1분 이상)** 진행될 수 있습니다.
- 관련 파일: `js/aleo-proof-worker.js` (Aleo SDK 로드 + 실제 증명 계산 Worker)

### 🔗 SSO 통합인증과 통신3사 인증의 관계

`sport_sso.html`의 ZKP SSO 통합인증은 통신3사 본인인증을 **"1회만" 수행하고 그 결과를 Aleo 토큰으로 재사용**하는 구조입니다.

```
① [최초 1회] 회원가입 시 통신3사 PASS 본인인증 → 서버 DB 저장
② [서버] 검증된 신원정보로 Leo/Aleo 회로 실행 → ZKP 증명 생성
③ Aleo ZKP 회원자격 토큰 발급 (재사용 가능, 유효기간 정책 필요)
④ [SSO 계층] 발급된 토큰으로 N개 기관(6개 스포츠기관 등) 모두 접근
   — 매 접근마다 통신사 재조회 없음 (오프라인 가능)
```

- `sport_sso.html`의 5단계 인터랙티브 데모는 위 **④단계(토큰 재사용)만** 시연하며, ①~③(최초 통신사 인증)은 "이미 완료된 상태"를 전제로 시작합니다.
- 이 구조 덕분에 통신3사 인증 비용은 "전체 로그인 횟수"가 아닌 **"신규 회원가입 건수"**에만 비례하여 대폭 절감됩니다.
- 상세 내용: `server/TELECOM-AUTH-INTEGRATION.md` 6-1절 "SSO 통합인증과의 관계"

#### ⚠️ 중요 오해 방지 — "PASS도 원래 1회만 인증하면 되는 것 아닌가?"

**아닙니다.** 통신3사 PASS(나이스/다날/KG모빌리언스 등)는 **원래 세션·토큰 재사용 기능이 없는 1회성 인증
이벤트**입니다 — 검증이 필요할 때마다 사용자가 그 순간 지문/PIN으로 재인증해야 하는 것이 PASS의
기본 스펙이며, 이것이 정상입니다.

위 "①~④ 1회 인증→토큰 재사용" 구조에서 실제로 일어나는 일은:
- PASS 호출 자체는 정말로 **딱 1번만** 발생시킵니다 (맞습니다)
- 그 결과를 **우리 백엔드가 직접 설계한 Aleo ZKP 토큰**으로 감싸서 재사용 가능하게 만든 것입니다 — **이건 PASS가 제공하는 기능이 아니라 우리 서버가 새로 구현해야 하는 부분**입니다
- 대행사 입장에서는 여전히 "호출 1건 = 과금 1건"이며, 우리가 호출을 자주 안 하도록 설계한 것뿐입니다
- 토큰의 유효기간·폐기(Revocation) 로직 품질에 보안 수준이 좌우되므로, 이 부분을 허술하게 만들면 "한 번 인증한 사람이 영구 재사용 가능한 취약점"이 될 수 있습니다

즉 "통신3사 인증은 매번 해야 하는 것이 맞다"는 이해가 **원칙적으로 정확**합니다. 상세: `server/TELECOM-AUTH-INTEGRATION.md` 6-2절 "오해 방지"

### 🆕 프라이버시 SaaS — PASS 미사용 Aleo ZKP 단독 인증 플랫폼 (privacy.html)

> "통신3사 PASS를 쓰지 않고 Aleo ZKP만으로 구독형(SaaS) 신원/프라이버시 인증 플랫폼을 만들 수 있는가?"에 대한 가능성 검토 + 전체 구현 페이지.

**결론(요약): 조건부로 가능합니다.**
- ✅ **가능**: "멤버십·구독등급·자격"처럼 **서비스 자체가 발급 주체**가 되는 사실을 증명하는 SaaS는 PASS 없이 Aleo ZKP만으로 100% 구현 가능 (Tier 1 지갑 기반 자기증명 / Tier 2 자체 발급 서버).
   - 예: 구독 등급 인증, DAO/커뮤니티 멤버십, Web3 로그인, NFT/토큰 게이팅, 익명 투표 자격 증명, B2B API 접근권한.
- ⚠️ **한계**: "실제 생년월일·실명 같은 현실 신원 사실"을 검증하려면 ZKP와 무관하게 **최소 1곳의 외부 신뢰 발급 주체**(통신3사 PASS, 모바일 신분증, KYC 벤더 등)가 필요 (Tier 3). ZKP는 "계산이 올바른지"만 증명하고 "입력값이 진실인지"는 증명하지 못하기 때문입니다(Garbage-in, Garbage-out 원칙).
- 페이지 구성: 가능성 검토(Tier 1~3 신뢰수준 모델) · Pure-Aleo 아키텍처 다이어그램 · **실제 동작 데모(#live-demo)** · PASS vs Pure-Aleo 비교표 · 적합/부적합 사례 매트릭스 · B2B 구독 요금제(안) · Web MVP→발급서버→네이티브 앱(Android/iOS)→Tier3 확장의 4단계 로드맵 · 기술스택.
- **실제 동작 데모 (5단계, 통신3사 PASS 호출 전혀 없음)**: ① Aleo 지갑 연결(로컬 생성) → ② 구독등급(Free/Pro/Enterprise) 선택 + 파트너사 요구조건 지정 → ③ `membership_proof.aleo` Leo 회로 실행 시뮬레이션 + ZK Proof(Groth16) 생성 로그 → ④ 재사용 가능한 세션 토큰 발급(30분 유효) → ⑤ 가상 파트너사(스트리밍/B2B API/커뮤니티) 선택 및 ZKP 검증 시뮬레이션으로 접근 허용/거부 결정. 전 과정이 이 정적 사이트 내 범위로 실행되며, 서버/통신3사 API가 전혀 호출되지 않음.
- 안드로이드/iOS 네이티브 앱은 **Phase 3**로 로드맵에 포함(React Native/Flutter + BiometricPrompt/LocalAuthentication + Aleo 모바일 SDK 바인딩 검토) — 단, 앱 빌드/스토어 배포는 이 정적 사이트 툴로 직접 만들 수 없는 별도 개발 단계임을 명시.
- 상세: `privacy.html` 페이지 본문 참고 (index.html 상단 네비게이션 "🛡️ 프라이버시SaaS"에서 진입 가능)

#### ⚠️ "지금 바로 실전에 써도 되는가?" — 1~5단계 실제 구현 완료 (`account.html` / `legal.html` 추가)

"무료 시작 → 유료 전환" 질문에 대해 실제로 동작하는 회원/구독 관리 계층을 다음 5단계로 직접 개발하여 `account.html`/`legal.html`에 반영했습니다:

1. **진짜 회원/구독 DB** — `pv_members`, `pv_payments` Table API 스키마로 실제 저장(새로고침해도 유지). `account.html`에서 회원가입(해시된 비밀번호 저장)/로그인/대시보드로 동작. 실제 fetch POST/GET/PATCH로 회원가입→재조회→등급 업그레이드가 DB에 영속 저장되는 것을 검증함.
2. **서버(DB) 기준 등급 접근제어 데모** — `account.html` "서버(DB) 기준 접근 제어 테스트" 섹션은 로컬 JS 변수를 버리고 매번 DB를 재조회해 판정. 단, 판정 로직 자체가 여전히 브라우저 JS에서 실행되므로 완벽한 보안은 아니고, 진짜 보안은 Cloudflare Worker 같은 서버가 판정까지 다 처리해야 함.
3. **결제(PG) 흐름 UI(샌드박스)** — `account.html`에 결제 UI/DB 반영 흐름(pv_payments 레코드 생성→상태전환→등급 PATCH)을 개발함. 실제 토스페이먼츠 등 PG API 연동은 아니며(실제 카드 승인·청구 없음), 해당 페이지에 "샌드박스 모드이며, 진짜 결제 전환에는 PG사 가입 + 웹훅 검증 서버가 필수"라고 명시되어 있음.
4. **`legal.html` 이용약관/개인정보처리방침 초안 + 사업자등록/신고 체크리스트** — 법률 문서 템플릿과, 사업자등록·통신판매업신고·PG가맹점가입 등 행정 절차를 체크리스트로 정리함(이 단계는 코드로 대신할 수 없어 사용자가 직접 행정 처리해야 하며, 문서 초안은 반드시 변호사 검토 후 사용).
5. **실제 Aleo 지갑 확장 연동 코드** — `account.html`의 지갑연결 버튼은 `window.leoWallet`/`window.puzzle` 확장을 감지해 실제 connect() 호출을 시도하고, 발견 실패 시 시뮬레이션 주소로 대체하여 DB에 `wallet_is_real` 플래그로 구분 저장한다.

이 단계로 "무료 시작 → 유료 구독 전환" 사업모델이 타당함을 넘어, **그 모델을 실제로 즉시 운영할 수 있는 회원/구독 DB 토대**가 마련된 것을 실질적으로 검증했습니다. 단, 진짜 돈을 받기 위해서는 여전히 ① PG사 가맹점 가입 + 웹훅 검증 서버, ② 사업자등록·신고, ③ Table API 앞단을 보호하는 진짜 인증 서버(Cloudflare Worker 등)가 추가로 필요합니다.

> 📌 **기획서 다운로드 파일 비공개 처리**: 아이디어 유출 방지를 위해 `PrivacySaaS-App-Development-Spec.doc`(앱 개발 종합 기획서) 및 사이트 내 다운로드 링크는 전부 제거했습니다. 문서 내용은 이 README와 `privacy.html`/`account.html`/`legal.html` 본문에 상세히 반영되어 있습니다.

- **네이티브 앱(Android/iOS)으로 동일하게 만들 경우 추가 고려사항**: Apple/Google은 앱 내 구독을 자체 IAP로 강제(수수료 15~30%), 지갑 키 관리 기능 포함 시 암호화폐 앱으로 분류되어 심사 강화, 모바일 기기에서 Groth16 증명 생성 성능/배터리 실기기 검증 필요, 정책 변경·심사 반려 리스크에 대한 일정 확보 필요
- 상세: `privacy.html` 페이지 내 "⚠️ 실전 배포 전 체크" 섹션(`#readiness`) · `account.html`(실제 데모) · `legal.html`(문서/체크리스트)

### ❌ 미구현 (향후 프로덕션 전환)
- 실제 Aleo SDK (@provablehq/sdk) 연동 → 현재: 시뮬레이션 유지 예정
- Leo 언어 ZKP 회로 컴파일 및 증명 생성
- WebAuthn/FIDO2 실제 생체인증 → navigator.credentials.create() 구현됨, HTTPS 환경 필요
- snarkOS 노드 연동
- HSM 기반 검증키 관리
- **통신3사(PASS) 실제 본인인증 연동** — 현재 전 페이지 데모/simulation 모드. 실전 전환 시 별도 백엔드 서버 배포 + 본인인증 대행사(나이스/다날/KCP 등) 계약 필요. 상세: `server/TELECOM-AUTH-INTEGRATION.md`
- **privacy.html Tier 2 발급 서버** — 최초 1회 자격 발급 API, Aleo 토큰 발급/만료/폐기(Revocation) 정책 — 현재는 컨셉·아키텍처 설명까지만 구현, 실제 백엔드 미구축
- **privacy.html Tier 3 실신원 확장** — 통신3사 PASS/모바일 신분증(NFC) 연동 — `server/TELECOM-AUTH-INTEGRATION.md`와 동일한 백엔드 필요
- **네이티브 Android/iOS 앱** — 정적 웹사이트 툴로는 앱 빌드/스토어 배포 불가. React Native/Flutter 별도 프로젝트 및 배포 파이프라인 구축 필요
- **실제 PG(결제대행)사 연동** — `account.html`은 샌드박스(테스트) 모드만 구현. 진짜 결제를 받으려면 PG사(토스페이먼츠 등) 가맹점 가입 + 서버 측 결제승인 웹훅 검증 로직이 반드시 필요
- **Table API 앞단의 인증 서버** — 현재 Table API는 별도 인증 계층이 없는 공개 REST 엔드포인트. `account.html`의 서버측 등급 재조회는 클라이언트가 직접 DB를 조회하는 방식이라, 완전한 보안을 위해서는 Cloudflare Worker 등 진짜 서버가 앞단에서 인증/판정을 전담해야 함
- **사업자등록·통신판매업신고 등 실제 행정 절차** — `legal.html`에 체크리스트는 정리했으나, 실제 신청/신고는 사용자가 국세청 홈택스·정부24 등에서 직접 진행해야 함
- **`legal.html` 법률 문서의 법무 검토** — 이용약관/개인정보처리방침은 템플릿 초안이며, 실제 게시 전 변호사 검토가 필수

---

## 🗺️ 페이지 구조

| URL | 설명 |
|-----|------|
| `index.html` | 메인 랜딩 페이지 (SaaS 소개) — **섹션 순서: 기능→작동원리→인증등급→활용업종→기술스택→요금제** |
| `user.html` | 사용자 앱 (생체인증 + ZKP + QR) |
| `verify.html` | 검증 단말기 (POS 역할) |
| `dashboard.html` | 관리자 대시보드 |
| `demo.html` | 가맹점 영업 시연용 데모 |
| `shop.html` | **온라인 쇼핑몰 가맹점 측 데모** (성인인증 QR 생성, 쿠팡 스타일) |
| `shop-verify.html` | **사용자 스마트폰 측 성인인증** (4단계 생체인증+ZKP) |
| `shopping.html` | **🆕 ZKP SSO 멀티 홈쇼핑 통합 데모** — 현대/롯데/CJ/GS/NS/홈앤 6개사 단일 ZKP 인증 |
| `sales.html` | **ZKP 영업 제안서** — 꼭 해야 하는 이유, 초등학생 ZKP 설명, 아키텍처, 경쟁사 비교 |
| `quantum.html` | **🆕 양자내성 ZKP 드론 보안** — PQC+ZKP 5레이어 아키텍처, 인터랙티브 시뮬레이터, 위협 타임라인 |
| `qr-access.html` | QR 접근 경로 안내 (PWA 설치 가이드) |
| `manual.html` | 플랫폼 전체 매뉴얼 |
| **🆕 `privacy.html`** | **PASS 미사용 Aleo ZKP 단독 프라이버시 인증 SaaS** — 가능성 검토(Tier 1~3 신뢰수준 모델), Pure-Aleo 아키텍처, PASS 비교표, 적합도 매트릭스, B2B 구독 요금제(안), Web→네이티브앱 로드맵, 실전 준비도 체크리스트(`#readiness`) |
| **🆕 `account.html`** | **실제 DB 연동 회원가입/로그인/대시보드** — Table API(`pv_members`/`pv_payments`)에 실제 저장, 서버(DB) 기준 등급 접근제어 데모, 샌드박스 테스트 결제, 실제 Aleo 지갑 확장(Leo/Puzzle Wallet) 연동 시도 코드 |
| **🆕 `legal.html`** | **이용약관/개인정보처리방침 초안 + 사업자등록·신고 체크리스트** — 실전 서비스 오픈 전 필요한 법률 문서 템플릿과 행정 절차 안내 (법무 검토 필수 고지 포함) |

---

## 🔢 4가지 연령 인증 등급

| 등급 | 조건 | 활용 업종 |
|------|------|-----------|
| 🍺 **성인 인증** | `age >= 19` | 주류·담배·유흥업소 |
| 🎮 **청소년 인증** | `age < 18` | 게임·영화·청소년 할인 |
| 🧒 **어린이 인증** | `age < 12` | 키즈카페·어린이 요금 |
| 🛡️ **미성년자 인증** | `age < 19` | 청소년보호법 전반 |

---

## 🔄 작동 플로우

```
[사용자 스마트폰]
  1. 생체 인증 (지문/Face ID) — 로컬 처리
  2. ZKP 생성 (Leo/Aleo SDK) — 개인정보 비공개
  3. QR 코드 표시 (3분 유효)

[오프라인 전송 - QR 스캔]

[검증 단말기 (POS 등)]
  4. QR 코드 스캔
  5. ZKP 검증 (Provable/snarkJS)
  6. 성인/미성년 결과만 표시
```

---

## 💾 데이터 모델

### `verify_logs` 테이블
| 필드 | 타입 | 설명 |
|------|------|------|
| tier_key | text | adult19/youth18/child12/minor19 |
| passed | bool | 인증 통과 여부 |
| merchant_id | text | 가맹점 ID |
| reason | text | 결과 사유 코드 |
| proof_hash | text | ZKP 증명 해시 (32자) |
| process_ms | number | 처리 시간 (ms) |
| verified_at | text | 검증 일시 |

### `merchants` 테이블
| 필드 | 타입 | 설명 |
|------|------|------|
| merchant_id | text | 고유 코드 (STORE-XXX) |
| name | text | 상호명 |
| type | text | 업종 |
| default_tier | text | 기본 인증 등급 |
| address | text | 주소 |
| status | text | active/inactive |

### 🆕 `pv_members` 테이블 (`account.html` — 실제 회원/구독 DB)
| 필드 | 타입 | 설명 |
|------|------|------|
| email | text | 가입 이메일 (로그인 ID) |
| display_name | text | 닉네임 |
| password_hash | text | SHA-256(salt+password) 해시값 — 평문 비밀번호 미저장 |
| password_salt | text | 비밀번호 해시용 랜덤 salt |
| tier | text | 구독 등급 (free/pro/enterprise) |
| tier_expires_at | datetime | 구독 만료 시각 (free는 null) |
| wallet_address | text | 연결된 Aleo 지갑 주소 |
| wallet_is_real | bool | true=실제 지갑 확장 연결, false=시뮬레이션 |
| status | text | active/disabled |
| created_at / last_login_at | datetime | 가입/최근 로그인 시각 |

### 🆕 `pv_payments` 테이블 (`account.html` — 샌드박스 결제 기록)
| 필드 | 타입 | 설명 |
|------|------|------|
| member_id / member_email | text | 결제한 회원 |
| target_tier | text | 업그레이드 대상 등급 (pro/enterprise) |
| amount / currency | number/text | 결제 금액/화폐 |
| provider | text | toss_sandbox / manual |
| status | text | pending/test_paid/failed/cancelled |
| order_id / payment_key | text | 주문번호/결제키(샌드박스 값) |
| is_sandbox | bool | true=테스트 결제(실제 금액 이동 없음) |
| created_at | datetime | 결제 시도 시각 |

> ⚠️ `pv_members`/`pv_payments`는 이 플랫폼의 공개 REST Table API로 접근됩니다. 인증 계층이 없으므로, 프로덕션 전환 시 반드시 서버(Cloudflare Worker 등)를 앞단에 추가해 접근을 제한해야 합니다.

---

## 🛠️ 기술 스택

### Frontend
- HTML5 / CSS3 (커스텀, Tailwind 미사용)
- Vanilla JavaScript (ES2020+)
- Chart.js 4.4 (대시보드 차트)
- QRCode.js 1.5 (QR 코드 생성)
- jsQR 1.4 (QR 코드 스캔)
- Font Awesome 6.4 (아이콘)
- `js/age-verify-service.js` — 연령/본인인증 데모↔실전 전환 서비스 레이어 (🆕)

### ZKP / 블록체인 (실제 구현 시)
- Aleo Blockchain (프라이버시 블록체인)
- Leo Language (ZKP 회로 작성)
- Aleo SDK / @provablehq/sdk (JS 라이브러리)
- Groth16 / Marlin 영지식증명 알고리즘
- snarkOS (노드 소프트웨어)

### 인증
- WebAuthn / FIDO2 (생체인증)

### 서버 (실제 배포 시)
- Rocky Linux 9
- Node.js 22 LTS
- REST Table API (현재 사용 중)

---

## 📊 REST API 엔드포인트

```
GET    tables/verify_logs          # 검증 로그 목록
POST   tables/verify_logs          # 검증 로그 추가
GET    tables/merchants            # 가맹점 목록
POST   tables/merchants            # 가맹점 추가
PUT    tables/merchants/{id}       # 가맹점 수정
DELETE tables/merchants/{id}       # 가맹점 삭제
```

---

## 🚀 다음 개발 단계

1. **Leo 회로 구현**: `age_proof.aleo` 프로그램 작성 및 Aleo testnet 배포
2. **Aleo SDK 연동**: 브라우저 내 실제 ZKP 생성 (`@provablehq/sdk`)
3. **WebAuthn 실제 연동**: 기기 생체인증 API 연결
4. **PWA 변환**: 오프라인 사용 가능한 Progressive Web App
5. **Rocky Linux 서버**: snarkOS 노드 + Node.js 백엔드 구축
6. **POS 연동 SDK**: REST API 클라이언트 라이브러리 배포
7. **국제화**: 영어/일본어 다국어 지원

---

## 📦 설치 및 배포 파일

| 파일 | 크기 | 용도 |
|------|------|------|
| `INSTALL.md` | ~24KB | 단계별 설치 가이드 (Windows/Mac/Rocky Linux 9) |
| `FULL-SOURCE-BUNDLE.md` | ~68KB | 전체 서버 소스 코드 번들 (모든 파일 인라인) |
| `setup-windows.bat` | ~14KB | Windows 10/11 자동 설치 배치 스크립트 |
| `setup-linux.sh` | ~30KB | Rocky Linux 9 / Ubuntu 완전 자동 설치 스크립트 |
| `server/TELECOM-AUTH-INTEGRATION.md` | ~9KB | **🆕 통신3사(PASS) 본인인증 실전 연동 가이드** — 대행사 비교, 비용, 사업자 요건, 개발 로드맵 |

### 빠른 시작

```bash
# Windows: setup-windows.bat 우클릭 → 관리자 권한으로 실행

# Linux:
chmod +x setup-linux.sh && sudo ./setup-linux.sh

# 수동:
cd server && npm install
cp .env.example ../.env  # .env 수정 후
node db/init.js          # DB 초기화
npm run dev              # 개발 서버 시작
```

---

## 📄 특허 정보

- **발명의 명칭**: 생체 인증 및 오프라인 QR 코드 전송을 이용한 영지식증명 기반 연령 인증 시스템
- **영문**: ZKP-based Age Verification System Using Biometric Authentication and Offline QR Code Transmission
- **출원 국가**: 대한민국 (KIPO 특허로 시스템)
- **기술 분야**: Aleo 블록체인 기반 영지식증명(ZKP), 오프라인 QR 코드 연령 인증

---

© 2026 ZKProofID | Aleo Blockchain & Zero-Knowledge Proof Based Age Verification Platform  
프로젝트 기획자 & DA/DBA: **Ban Chae Hun**