fix: 맵핑 관련 오류 로그 셋팅

docs/sso_guides/rp-installed.md

@@ -0,0 +1,71 @@
+# 설치형 RP 가이드
+
+## 보안 모델
+
+설치형 Interactive RP는 Public PKCE client다. 앱은 Hydra client secret이나 Hydra token을 보관하지 않는다. 복구 기능을 선택한 앱은 기기 키에 결합된 Baron 복구 자격증명을 OS 보안 저장소에 보관한다. [복구 및 다중 프로세스 연동](rp-integration.md#설치형-앱의-세션-복구와-다중-프로세스)을 따른다.
+
+- Installation ID: RP·환경·local enrollment별 256-bit random value
+- Device Key: 설치별 비대칭 key pair
+- Installation Binding: 서버가 Installation ID를 RP와 subject에 결속한 값
+- Device Session: Baron Token Vault를 가리키는 opaque session
+
+MAC address, IMEI, serial, hostname, IP, User-Agent를 Installation ID로 사용하지 않는다. private key는 OS secure storage에 보관하고 다른 환경이나 RP와 공유하지 않는다.
+
+## 최초 등록
+
+1. 앱이 새 Installation ID와 device key pair를 만든다.
+2. 일반 Public PKCE authorization과 consent를 완료한다.
+3. 앱이 authorization completion, Installation ID, public JWK, device proof를 Backend Broker에 제출한다.
+4. Backend가 subject, RP, proof, quota, key tombstone을 검증한다.
+5. Backend는 Hydra token을 Token Vault에 보관하고 opaque device session을 반환한다. RP별 발급 허용과 앱 opt-in이 켜져 있고 서버 전체 차단이 없으면 복구 자격증명도 반환한다.
+
+Device public JWK를 DevFront Client JWKS에 등록하지 않는다.
+
+### Device Proof 시간 오류 처리
+
+이 절은 저장소 코드의 응답을 설명합니다. 오류 정책은 [Error Handling Policy](https://gitea.hmac.kr/baron/baron-sso/wiki/Error-Handling-Policy)에서 관리합니다.
+구현과 검증 기록은 [#2186](https://gitea.hmac.kr/baron/baron-sso/issues/2186)을 참고하세요. 운영 반영 여부는 별도로 확인하세요.
+
+Authorization completion의 시간 오류는 HTTP 400과 본문의 `status=400`을 반환합니다. 필수 `code`는 `device_proof_expired`처럼 서버가 확인한 실패를 식별합니다.
+응답 구조와 코드 목록은 [OpenAPI의 InstalledDeviceProofTimeFailureResponse](../../backend/docs/openapi.yaml)를 따릅니다. `message`는 선택적인 영문 설명이며 번역하지 않습니다.
+
+RP는 오류 상세에 HTTP 상태와 `code`를 표시합니다. `message`가 있으면 영문 그대로 표시하며, 문구를 해석해서 복구 동작을 선택하지 않습니다.
+`next_action=restart_login`이면 앱의 시각과 proof 생성 시점을 확인한 뒤 새 로그인을 시작합니다. 새 로그인에서는 authorization code와 proof를 새로 만듭니다.
+`next_action=contact_support`이면 `request_id`를 첨부해 관리자에게 문의합니다.
+
+시간 진단의 `retryable`은 `false`입니다. 알 수 없는 코드나 다음 행동을 받아도 같은 proof 또는 authorization code를 자동 재전송하지 않습니다.
+만료와 미래 발급 시각은 서버가 확인한 시간 조건입니다. 이 조건만으로 실제 기기 시계의 방향이나 네트워크 지연을 확정하지 않습니다.
+
+공개 진단과 민감정보의 경계는 [Error Handling Policy](https://gitea.hmac.kr/baron/baron-sso/wiki/Error-Handling-Policy)를 따릅니다.
+
+## Operation 호출
+
+- operation마다 현재 device key로 proof를 서명한다.
+- proof에는 method, path, body digest, nonce/issued time처럼 Backend가 요구하는 context를 결속한다.
+- idempotency key는 동일한 logical operation에 재사용하고 다른 payload에 재사용하지 않는다.
+- timeout 뒤 임의로 새 operation을 만들기 전에 기존 operation 상태를 조회한다.
+- Redis replay 방지는 보조 계층이며 durable 중복 실행 방지는 PostgreSQL execution ledger가 담당한다.
+
+## Device lifecycle
+
+- 등록 상태와 활성 authorization/token family를 구분한다.
+- disable은 새 operation을 막고 local family/session을 fence한다.
+- revoke는 복구 가능한 disable보다 강한 종료다.
+- key rotation은 기존 key proof와 새 key possession을 모두 검증한다.
+- retired/revoked thumbprint는 tombstone으로 보존하고 재사용하지 않는다.
+- rotation 뒤에는 새 key로 fresh PKCE authorization이 필요할 수 있다.
+
+## Quota
+
+- 사용자 device quota는 `(client_id, subject_kind, subject_id)` 경계에서 계산한다.
+- 활성 수는 PostgreSQL token family 상태를 기준으로 한다.
+- Redis TTL이나 마지막 heartbeat만으로 active quota를 계산하지 않는다.
+- quota 퇴출은 local fence와 revoke outbox를 하나의 transaction에 기록한다.
+
+## 운영 확인
+
+- DevFront inventory에서 device ID, subject UUID, Tenant, 등록 상태, 활성 authorization, key generation을 구분해 확인한다.
+- private JWK, Hydra token, raw vault material은 어떤 화면에도 표시하지 않는다.
+- disable/rotate/revoke 뒤 기존 proof와 session이 실패하는지 확인한다.
+
+공통 Client 등록은 [RP Integration Guide](rp-integration.md), 정확한 endpoint와 proof schema는 OpenAPI를 따른다.