# IKEv2 Shop → VPN 백엔드 액션 요청 규격서

## 목적
- `IKEv2SellerOffice4U/vpn_users.php`의 서버 액션 라우터에 대해,
  쇼핑몰 백엔드가 **신뢰 가능한 방식으로만** 사용자 제어 액션을 호출하도록 규격을 정의한다.
- 특히 `쇼핑몰 자동등록(shop-managed)` 계정의 경우,
  로컬 관리자 수동 조작은 차단되고 본 규격을 따르는 백엔드 요청만 허용된다.

---

## 1) 인증/신뢰 조건 (필수)
백엔드 요청으로 인정되려면 아래를 모두 만족해야 함.

1. HTTP Method: `POST`
2. origin 식별값:
   - POST 필드 `sync_origin` 또는
   - 헤더 `X-VPN-Sync-Origin`
   - 값은 아래 중 하나: `shop_backend`, `shop_sync`, `shop_update`
3. 헤더 `X-VPN-Sync-Signature` 존재
4. 서버측 `shop_sync_shared_secret`로 HMAC-SHA256 검증 통과
   - 검증 대상: **raw request body 전체**

> 참고: `shop_sync_shared_secret`가 비어 있으면 백엔드 신뢰 요청은 허용되지 않음.

---

## 2) 허용 액션 화이트리스트
신뢰 요청이라도 아래 액션만 허용.

- `add_user`
- `update_user`
- `delete_user`
- `extend_expire`
- `charge_points`
- `withdraw_points`
- `enable_user`
- `disable_user`

그 외 액션은 거부된다.

---

## 3) 공통 요청 필드
| 필드 | 위치 | 필수 | 설명 |
|---|---|---:|---|
| `action` | POST body | Y | 실행할 액션 |
| `sync_origin` | POST body (권장) | Y* | `shop_backend`/`shop_sync`/`shop_update` |
| `X-VPN-Sync-Origin` | Header (대체) | Y* | body 대체 가능 |
| `X-VPN-Sync-Signature` | Header | Y | HMAC-SHA256 서명 |

`Y*`: body 또는 header 중 하나는 반드시 필요.

---

## 4) 액션별 최소 필수 필드
| action | 필수 POST 필드 | 비고 |
|---|---|---|
| `add_user` | `user_id`, `password` | `expire`, `memo`, `billing_config` 선택 |
| `update_user` | `user_id` | `password`, `expire`, `memo`, `admin`, `billing_config` 선택 |
| `delete_user` | `user_id` | - |
| `extend_expire` | `user_id` + (모드별 필드) | absolute: `extend_mode=absolute`, `target_datetime` / duration: `extend_mode=duration`, `add_months/add_days/add_hours/add_minutes` |
| `charge_points` | `user_id`, `amount` | `reason`, `activation_choice` 선택 |
| `withdraw_points` | `user_id`, `amount` | `reason` 선택 |
| `enable_user` | `user_id` | - |
| `disable_user` | `user_id` | - |

---

## 5) 수동/백엔드 처리 정책
| 대상 사용자 | 로컬 관리자 수동 요청 | 쇼핑몰 백엔드 요청(검증 통과) |
|---|---|---|
| 일반(수동 등록 등) | 허용(권한 범위 내) | 허용 |
| 쇼핑몰 자동등록(shop-managed) | **차단** | **허용** |

차단 대상 수동 액션: 삭제, 수정(비번/만료 포함), 만료변경, 충전, 출금.

---

## 6) 오류 응답 가이드
| 상황 | 기대 응답 |
|---|---|
| 백엔드 신뢰 조건 불충족 | 일반 권한 흐름 진입(로그인/권한 필요), 또는 해당 흐름에서 오류 |
| 백엔드 화이트리스트 외 액션 | `success:false`, `error:"허용되지 않은 쇼핑몰 백엔드 액션입니다."` |
| shop-managed 수동 제어 시도 | `success:false`, `error:"쇼핑몰 자동등록 사용자에 대한 ...은(는) 쇼핑몰에서만 처리할 수 있습니다."` |

---

## 7) 운영 체크리스트
1. 양쪽 서버 `shop_sync_shared_secret` 동일값 확인
2. 쇼핑몰 전송부가 raw body 기준으로 서명 생성하는지 확인
3. `sync_origin` 값이 허용 목록 중 하나인지 확인
4. `action`이 화이트리스트 내인지 확인
5. shop-managed 계정 수동 조작 시 거부되는지 확인
6. 동일 요청을 백엔드 서명 포함으로 재시도 시 정상 반영되는지 확인

---

## 참고 파일
- `IKEv2SellerOffice4U/vpn_users.php`
- `mylib/ikev2_shop_sync_event_receiver.php`
- `ikev2_shop_payload_mapping.md`
- `ikev2_shop_sync_healthcheck_runbook.md`
