Release Notes

v1.2.2

종합 위험도 (Suspect Score) 도입 및 봇/VM/시크릿/헤더 불일치 시그널 대량 추가 릴리스입니다.

FingerprintJS Pro 의 suspect_score 에 대응하는 0–100 통합 리스크 지표를 제공합니다.

Highlights

• 신규 프로토콜 8종 추가 (207, 208, 510, 511, 706, 707, 708, 709)
• Suspect Score (510/511) — VPN/Proxy/Bot/Tor/VM/Incognito/UA-CH/Font-Lang 시그널을 0–100 으로 통합
• Bot Score (706/707) — 자동화 도구 전역 객체, webdriver, $cdc_, navigator chrome 이상 등 10+ 시그널 가중합
• Virtual Machine (708) — WebGL UNMASKED_RENDERER 가 SwiftShader/llvmpipe/VirtualBox/VMware 등인지 탐지
• Incognito (709) — 엔진별 시크릿 모드 탐지 (Blink: storage quota, Gecko: serviceWorker, WebKit: localStorage quota)
• UA Client Hints 교차검증 (207) — navigator.userAgentData.getHighEntropyValues() 와 UA 문자열 플랫폼 불일치 탐지
• Font × Language 불일치 (208) — ko/zh/ja/ar/he/th 언어별 대표 폰트 존재 검증
• example.html 상단에 버전·빌드시간 배지 및 릴리즈 노트 모달 뷰어 추가
• internal-build.sh 가 빌드 시점에 버전/시간 플레이스홀더 치환 + RELEASE.md 를 dist/ 로 복사

신규 Protocol

Suspect Score 계산 가중치

• VPN score × 0.35
• Proxy score × 0.30
• Bot score × 0.30
• Tor Exit IP / Tor Browser : +25 each
• VirtualMachine : +10
• Incognito : +10
• UA-CH mismatch : +25
• Font-Lang mismatch : +15
• 최종 0–100 으로 clamp, 4단계 레벨 변환 (0–19 clean / 20–49 suspicious / 50–79 likely_bad / 80–100 high_risk)

신규 모듈

• src/main/utils/browser/botDetectUtils.ts — 봇 스코어/레벨
• src/main/utils/browser/vmDetectUtils.ts — VM 플래그
• src/main/utils/browser/incognitoDetectUtils.ts — 시크릿 모드 플래그
• src/main/utils/browser/uaChUtils.ts — UA-CH 교차검증
• src/main/utils/browser/fontLangUtils.ts — 폰트-언어 매치
• src/main/utils/browser/suspectScoreUtils.ts — 종합 위험도 집계

Dev / Build

• vitest 테스트 프레임워크 도입 (npm run test, test:watch, test:ui, typecheck)
• devDependencies 에 vitest@^1.6.0, @vitest/ui@^1.6.0 추가
• rtcUtils.ts — TypeScript never 경고 해결 (Promise 클로저 내부 할당에 대한 control-flow narrowing 우회)
• internal-build.sh — __FACEJS_VERSION__ / __FACEJS_BUILDTIME__ 플레이스홀더 치환 및 RELEASE.md 를 dist/ 로 배포
• resources/example.html — 상단에 버전/빌드시간 배지 + 릴리즈 노트 뷰어 버튼 추가

Migration Guide (v1.2.1 → v1.2.2)

1. API 변경 없음 — 결과 JSON 에 신규 protocol 번호가 포함됩니다

2. 서버 처리 — 510/511 (suspect) 및 706–709 값을 저장/모니터링 대상에 추가 권장

3. 서버가 isTorExitIp 를 내려주어야 502 가 true 로 표기됩니다 (v1.2.1 에서 도입)

4. UA Client Hints 는 Chromium 90+ 에서만 동작하며, 그 외 브라우저는 207=false

v1.2.1

네트워크/프록시 시그널 대폭 강화 및 프로토콜 카테고리 정리 릴리스입니다.

Highlights

• WebRTC STUN 기반 공인 IP 수집 (504)
• 다중 STUN 교차검증 (505) — 여러 STUN 서버 결과 비교로 TURN/멀티 WAN 이상징후 탐지
• Proxy Score (506/507) — 서버 관측 IP 와 WebRTC srflx IP 불일치 + cross-check mismatch 기반 점수
• VPN Score (508/509) — 언어/타임존/지역/IP 간 inconsistency 를 점수화
• Tor Exit IP 플래그 (502) — 서버가 natIp 를 공개 Tor exit 목록과 대조한 결과
• Tor Browser 플래그 (503) — 클라이언트 사이드에서 Tor Browser 동작 특성 탐지
• 네트워크 카테고리 500 번대로 통합 정렬 (구 783/785–789 → 504–509)

신규 Protocol

Proxy Score 기준

• serverIp (501) 와 rtcIp (504) 불일치 : +40
• multi-STUN mismatch (서로 다른 STUN 이 다른 공인 IP 보고) : +30
• rtcIp 수집 실패 (WebRTC 차단) : +20
• crossCheck.count === 1 에서 IPv6-only : +10

VPN Score 기준

• clientTimezone ↔ serverGeoRegion 불일치 : +35
• language prefix ↔ serverGeoRegion 불일치 : +20
• tzOffset 과 timezone name 불일치 : +15
• rtcIp 와 serverIp 다름 : +25 (Proxy 와 중복 반영)

신규 모듈

• src/main/utils/browser/rtcUtils.ts — ipFromRTC(), publicIpCrossCheck()
• src/main/utils/browser/proxyScoreUtils.ts — calculateProxyScore()
• src/main/utils/browser/vpnScoreUtils.ts — calculateVpnScore()
• src/main/utils/browser/torDetectUtils.ts — isTorBrowser()

Bug Fixes

• rtcUtils.ts — 기존 | 1000 비트 OR 버그 수정 (|| 1000 로 변경)
• mainUtils.ts — 서버 통신 실패 + 로컬 키 로드 실패 시 키 덮어쓰지 않도록 보완

Migration Guide (v1.2.0 → v1.2.1)

1. API 변경 없음 — 결과 JSON 에 새 protocol 번호만 추가됩니다

2. 서버가 isTorExitIp/geoRegion 를 응답해야 502/508 이 정확해집니다

3. WebRTC 차단 환경 — 기업 정책 등으로 WebRTC 가 차단된 경우 504 는 빈 문자열, 506 에 +20 반영

Breaking Changes

• 구 protocol 번호 783/785–789 는 504–509 로 이동되었습니다. 서버 측 저장 스키마가 옛 번호를 기준으로 매핑되어 있다면 마이그레이션 필요

v1.2.0

v4 프로토콜 도입 및 보안 핸드셰이크 전면 개편 릴리스입니다.

Highlights

• RSA-OAEP (SHA-256) 기반 /see 핸드셰이크 도입 (v4 프로토콜)
• 기존 Basic auth 방식 (v3) 과 완전 하위호환 — config.packetVersion 으로 분기
• browserEnvKey 생성 시 AES 암호화 → SHA-256 해시로 전환 (v4)
• DENY 응답 감지 및 자동 재시도 (strict 모드 대응)
• example.html UI 대폭 개선
• 외부 의존성 제거 (node-forge → pure JS RSA-OAEP 구현)

Security / Protocol

• RSA-OAEP SHA-256 핸드셰이크 (v4+)
• /see 요청 시 세션 AES key/iv 를 RSA 공개키로 암호화하여 body JSON {sessionKey, kid} 으로 전송
• 기존 Authorization: Basic base64(key:iv) 정적 credential 헤더 완전 폐기
• Java 서버 RSA/ECB/OAEPWithSHA-256AndMGF1Padding 과 호환
• 키 로테이션 지원: RSA_PUBLIC_KEYS[] 배열 + kid 식별자 구조
• Pure JS RSA fallback (외부 의존성 0)
• HTTPS/localhost → WebCrypto 네이티브 (crypto.subtle)
• HTTP 환경 → CryptoES SHA-256 + BigInt 기반 pure JS 구현 (node-forge 제거)
• config.packetVersion 기반 /see 분기
• v3 이하: postWithAuth() — Basic auth 헤더에 세션 key/iv 전달
• v4 이상: postJson() — RSA-OAEP 암호화 body JSON 전송
• browserEnvKey v4 해시 전환
• v3: AES-CBC/PKCS7 암호화 후 base64
• v4: SHA-256 hex 64자 해시 (서버 canonical JSON 비교)
• packetVersion 에 따라 keyManager.makeBrowserEnvKey() 에서 자동 분기
• DENY 응답 대응
• /face 응답에서 DENY 감지 시 로컬 키 초기화 후 /see 부터 1회 자동 재시도
• isDenyResponse() 방어적 다중 필드 체크 (denied, resultCode, status, denyReason)

Network / HTTP

• http.ts 전면 개편
• 기본 reqConfig 에서 하드코딩 Basic auth (478e…:2cd1…) 제거
• postJson() 메서드 추가 — v4 /see JSON body 전용
• postWithAuth() 메서드 복원 — v3 Basic auth 호환
• /face 요청의 Content-Type: application/json 기본 헤더 제거 (AES 암호문 문자열에 쌍따옴표 감싸지는 버그 수정)
• networkUtils.ts 통신 흐름 전면 재작성
• requestServer() → requestServerOnce(url, denyRetried) 2단 구조
• parseSeeResponse() 에 세션 key/iv 기반 복호화
• makeFaceRequest() 에 packetVersion 파라미터 추가
• v4 에서 envSecret 빈 문자열 전송 (서버 미사용)

Spec 변경

• SeeResponseSpec 에 packetVersion?: number 추가
• FaceResponseSpec 에 denied?: boolean, denyReason?: string 추가
• ResultSpec 에 serverEnvConfig: number[] 추가

Crypto

• cryptoUtils.ts 에 sha256Hex() 함수 추가 — WebCrypto 우선, CryptoES fallback
• rsaUtils.ts 신규 모듈
• RsaKeyEntry 인터페이스, RSA_PUBLIC_KEYS[] 배열, CURRENT_KID
• rsaOaepSha256Encrypt() — WebCrypto / pure JS 자동 분기
• ASN.1 DER 파서, OAEP 패딩, MGF1-SHA256, BigInt modPow 내장

Bug Fixes

• entry.ts — timeout fallback 에 serverEnvConfig: [] 누락 수정 (envConfig N/A 이슈)
• mainUtils.ts — faceResult() 에서 /face 성공 시 entryStore() 미호출 수정 (602/609 프로토콜 데이터 누락 이슈)
• http.ts — /face body 에 쌍따옴표 감싸지는 문제 수정 (Content-Type 기본 헤더 제거)

example.html

• BrowserEnvKey 구성 분석 섹션 기본 접힘 상태로 변경
• Raw JSON 위치를 BrowserEnvKey 위로 이동, rawData 만 표시하도록 변경
• 최종 결과 Packet 보기 버튼 추가 (uuidKey, data, resultCode, duration)
• 결과 POST 전송 버튼 추가 (외부 웹서버로 JSON POST)
• Raw Data / Packet 영역에 복사 버튼 추가
• 스크립트 캐시 방지: 타임스탬프 쿼리스트링 자동 부여
• HTML 캐시 방지 메타태그 추가 (iOS Safari 대응)

Migration Guide (v1.1.0 → v1.2.0)

1. face.config.js 에서 packetVersion 확인

• v3 서버 유지 시: packetVersion: 3 (기본값, 변경 불필요)
• v4 서버 전환 시: packetVersion: 4 로 설정

2. 서버가 v4 프로토콜을 지원해야 v4 로 전환 가능

• /see 요청 body {sessionKey, kid} 수신 및 RSA 개인키 복호화
• /see 응답에 packetVersion: 4 포함
• /face 요청의 currentEnvKey 가 SHA-256 hex 64자로 변경됨

3. API 변경 없음

• FaceJS.load(timeout) 호출 방식 동일

4. npm install 재실행 필요

• node-forge 의존성 제거됨, 추가 패키지 없음

Breaking Changes

• /see 요청의 Authorization: Basic 헤더가 v4 에서 완전 제거됨 (v3 유지 시 영향 없음)
• 하드코딩된 Basic auth credential (478e… / 2cd1…) 이 코드에서 삭제됨

v1.1.0

facejs 의 빌드 체인 현대화, 타입 안전성 강화, 신규 핑거프린팅 시그널 추가를 포함한 메이저 정비 릴리스입니다.

Highlights

• Rollup 4 기반 빌드 체인으로 전면 마이그레이션
• @babel/polyfill 제거 및 core-js@3 자동 폴리필 주입 전환
• TypeScript 5.x + 공식 @rollup/plugin-typescript 적용
• 신규 핑거프린팅 8종 추가 (Protocol 790–797)
• 일부 유틸 모듈의 안정성/타입 안전성 개선

Build & Toolchain

• Rollup: 2.x → ^4.12.0
• TypeScript: 4.x → ^5.4.0
• TypeScript Plugin: rollup-plugin-typescript2 → @rollup/plugin-typescript@^11.1.6
• Rollup 4 호환 이슈 해결 (entry .ts 파일이 transform 되기 전에 다른 플러그인에 파싱되는 문제)
• tsconfig.json 의 declaration: false 로 변경 (불필요한 .d.ts 산출 방지)
• Terser Plugin: rollup-plugin-terser → @rollup/plugin-terser@^0.4.4
• 기존 패키지의 peer rollup@^2.0.0 충돌 해결
• Plugin Order 정비: 모든 config 에서 typescript() → resolve() → commonjs() → babel() → terser() 순서로 통일
• 기타 플러그인 메이저 업데이트
• @rollup/plugin-node-resolve ^15.2.3
• @rollup/plugin-commonjs ^25.0.7
• @rollup/plugin-babel ^6.0.4

Polyfill 전략 변경

• @babel/polyfill (Babel 7.4 부터 deprecated) 제거
• @babel/preset-env 의 useBuiltIns: "usage" + corejs: { version: 3, proposals: true } 도입
• 코드에서 실제 사용한 ES API 만 자동으로 core-js 폴리필 import
• 번들 크기 최적화와 IE 지원 동시 달성
• @babel/plugin-transform-runtime 에 corejs: 3 추가 — 헬퍼/폴리필 sandboxed import
• 외부 polyfill.min.js 산출 중단
• internal-build.sh 의 관련 copyfiles 라인 제거
• resources/example.html 의 <script nomodule src="/dist/polyfill.min.js"> 라인 제거
• 폴리필이 face-compatible.min.js 번들 내부에 자동 포함되어 별도 파일 로드 불필요

Library Updates (dependencies)

• axios → ^1.7.0
• uuid → ^9.0.1
• idb → ^8.0.0
• crypto-es → ^2.1.0
• core-js → ^3.36.0 (devDependency 에서 dependency 로 이동)
• @babel/runtime-corejs3 → ^7.24.0 (런타임 헬퍼 import 대상)
• @egjs/agent → ^2.4.4

TypeScript 설정 강화

• lib: ["dom", "dom.iterable", "es2015", "es2017", "es2020.promise"]
• noImplicitThis: true 추가
• declaration: false (배포 산출물엔 .d.ts 불필요)
• target: es5 유지 (구형 브라우저 호환)

코드 품질 개선

• entry.ts
• 레거시 @babel/polyfill import 제거
• externalConfiguration 파라미터 타입을 any → Record<string, unknown> 으로 강타입화
• browserInfo.ts
• getWebglRenderer() 의 rendererInfo 타입 안전성 개선 (number 명시 + nullish 병합)
• audioUtils.ts
• window 객체 안전 참조 패턴 단순화
• OfflineAudioContext.startRendering() 호출 누락 (finishRendering()) 수정
• headlessDetect.ts
• getHeadlessScore() 로직 강화: 동기 테스트, Chrome headless, 자동화 도구, webdriver 다중 체크
• mainUtils.ts
• awaitNumber 에 신규 비동기 프로토콜(790, 794, 795, 796, 797) 등록

신규 핑거프린팅 (Protocol 790–797)

• 790 WebGL Extended Parameters — webglExtUtils.ts
• 791 CSS Media Queries Profile — cssMediaUtils.ts
• 792 Network Information API — networkInfoUtils.ts
• 793 Performance API Timing — performanceUtils.ts
• 794 Media Device Enumeration — mediaDeviceUtils.ts
• 795 Speech Synthesis Voices — speechSynthesisUtils.ts
• 796 Storage Estimate — storageEstimateUtils.ts
• 797 Permission API States — permissionUtils.ts

자세한 필드/예시는 PROTOCOL.md 의 700 번대 표를 참고하세요.

Migration Guide

기존 통합처를 v1.1.0 으로 업데이트할 때 다음 사항만 확인하면 됩니다.

1. polyfill.min.js 로드 라인 제거

• HTML 에서 <script nomodule src=".../polyfill.min.js"> 라인을 삭제합니다.
• 폴리필은 face-compatible.min.js 안에 포함되므로 별도 로드가 불필요합니다.

2. 빌드 환경

• Node.js 18+ 권장 (Rollup 4 / TypeScript 5 호환).
• npm install 시 깨끗한 재설치를 위해 node_modules / package-lock.json 삭제 후 진행할 것을 권장합니다.

3. API 변경 없음

• FaceJS.load(timeout) 인터페이스 및 결과 스펙은 v1.0.x 와 동일합니다.
• 서버 응답 protocol 도 700 번대 추가 외에는 변경 없음.

Breaking Changes

• polyfill.min.js 산출물 제거 — 외부 폴리필 파일을 직접 의존하던 통합처는 위 마이그레이션 가이드 1번에 따라 HTML 의 로드 라인을 제거해야 합니다. (번들 내부에 자동 포함되므로 추가 작업 불필요)
• 빌드 산출물의 선언 파일(.d.ts) 미생성 — 라이브러리 타입 정의가 필요한 환경이면 별도 rollup-plugin-dts 빌드를 추가해 주세요.