컴플라이언스

이 페이지는 HACS FI API에 구현되어 있는 기술적 통제(controls)를 사실 그대로 기술합니다. 각 항목이 특정 법령·규정의 요건을 충족하는지에 대한 판단은 각 기관의 검토 사항입니다.

1. 동의 통제

• 기본 차단(deny-by-default): 활성 동의가 검증된 요청에만 데이터가 반환됩니다. 동의 검사는 매 조회마다 수행됩니다.
• 동의는 기관(clientId) × 목적(purpose) 단위로 저장되며, 공유 범위는 데이터 카테고리(CSV)로 제한됩니다. 기본 카테고리는 score,tier,reason-codes이며 contributions/history/monitoring은 명시 선택입니다.
• 철회는 즉시 효력이 발생하며, 철회 이후에는 consent.revoked 웹훅 외에 어떤 데이터·이벤트도 제공되지 않습니다.
• 동의마다 영수증(receipt) 식별자가 발급되어 부여·철회 시각과 함께 조회·내보내기가 가능합니다.

2. 접근로그와 해시체인

• 모든 FI 조회(성공·거부 모두)는 접근로그에 기록됩니다: 시각, 클라이언트, pairwise 주체, 목적, 결과(outcome), 반환 등급, 모델 버전, 환경(LIVE/SANDBOX), 배치 ID.
• 각 로그 항목은 이전 항목의 해시를 포함하는 해시체인(entryHash)으로 연결되어, 사후 삭제·수정 시 체인 불일치로 탐지됩니다.
• 사용자는 앱에서 자신에 대한 조회 내역(기관·시각·목적)을 열람할 수 있습니다.
• 관리자는 접근로그와 동의 내역을 CSV로 내보내 증적으로 보관할 수 있습니다(entryHash 열 포함).
• 배치 조회는 건별로 로그가 남고 공통 batchId로 묶입니다. 샌드박스 호출은 environment='SANDBOX'로 분리 기록됩니다.

3. 사유코드 (설명가능성)

• 점수 응답에는 표준 카탈로그(31종)에서 선별된 사유코드가 최대 4건, 영향 순으로 포함됩니다.
• 각 코드는 영어 라벨과 현지어 라벨, 카테고리, (프로비넌스가 있는 경우) 감점 폭을 함께 제공합니다.
• 사유코드는 결정 시점에 기록된 값을 그대로 반환하며 재계산하지 않습니다 — FI가 검토하는 것은 "그때의 결정"입니다.

4. 모델 거버넌스

• 모든 점수에는 산출에 사용된 modelVersion이 명시됩니다.
• 모델은 버전 관리되며, 신규 모델은 검증(OOT 성능 지표) 및 승격 절차를 거쳐야 서비스에 반영됩니다. 승격 이력은 감사 가능하게 기록됩니다.
• 운영 중 모델은 분포 변화(PSI) 등 모니터링 지표로 추적됩니다.

5. 결정 프로비넌스 (decision provenance)

• 점수 결정은 canonical JSON(HACS_DECISION_V1)으로 직렬화되어 해시(decisionHash)가 계산·보존됩니다. 이 canonical 형식은 불변이며, 이후 추가된 응답 메타데이터는 해시 대상에 포함되지 않습니다.
• 결정 시점의 피처 기여·사유코드가 프로비넌스로 기록되어, 동일 입력에 대한 결정 재현(replay) 검증이 가능합니다.
• 신용등급 증명서(어테스테이션)는 블록체인에 앵커링될 수 있으며(앵커 트랜잭션 해시 제공), 유효기간은 발급 후 90일입니다. 폐기(revocation) 상태도 발급기관 기록으로 검증됩니다.

6. 식별자 최소화

• FI 표면의 유일한 주체 식별자는 파트너별 pairwise 식별자입니다. 내부 식별자(civilId/userId)·실명·연락처는 노출되지 않습니다.
• 동일 사용자라도 기관마다 다른 식별자가 발급되어 기관 간 결합이 차단됩니다.
• 거부 응답은 사유를 구분하지 않는 동일 라벨로 반환되어, 주체의 서비스 가입 여부를 추론할 수 없습니다.

7. 전송·키 보안

• API 키는 서버에 BCrypt 해시로만 저장되며 발급 시 1회만 평문 표시됩니다.
• 웹훅은 https 엔드포인트만 허용되고, 요청마다 HMAC-SHA256 서명이 첨부됩니다. 웹훅 페이로드에는 점수 원값이 포함되지 않습니다.
• 속도 제한(60 req/min)이 인증 이전 단계에서 적용됩니다.