คีย์ Sandbox และการหมุนคีย์

หน้านี้ใช้ได้เฉพาะ Merchant ที่กำลังอยู่ใน home scope ของตัวเองบน sandbox เท่านั้น White Label, Agent, การสลับไปดูลูกข่าย และทุก live session จะไม่เห็นเมนูและเรียก route ไม่ได้

สิ่งที่หน้าจออ่านได้

GET /v1/bo/sandbox?scope_id=<merchant UUID> คืน metadata แบบไม่มี secret:

• current credential UUID, prefix sk_test, fixed scopes deposits:read และ deposits:write;
• วันสร้างและวันหมดอายุที่ระบบกำหนดไว้ 90 วันพอดี;
• singleton-slot revision ซึ่งต้องตรงกับ response ETag;
• predecessor ที่ยังใช้ได้และเวลา valid_until ถ้ามี overlap อยู่.

Plaintext, suffix, digest, R2 reference, ciphertext และ keyring metadata ไม่อยู่ใน response โดยโครงสร้าง หาก client พบ field นอก closed schema จะทิ้ง response ทั้งก้อน.

เลือกนโยบายก่อนหมุน

ตัวเลือก	ผลที่เกิด
ทันที (overlap_seconds=0)	คีย์ปัจจุบันและ predecessor ที่เหลือถูกยกเลิกใน commit เดียว เหมาะกับเหตุด้านความปลอดภัย
ผ่อนผัน 5 นาที (overlap_seconds=300)	คีย์ใหม่ใช้ได้ทันที และคีย์เดิมใช้ต่อถึง DB clock +5 นาที เหมาะกับการสลับระบบตามแผน

มี predecessor ที่ยัง active ได้สูงสุดหนึ่งคีย์ การขอ overlap ซ้อนตอบ 409 sandbox_overlap_active; กดหมุนทันทีได้เพื่อ collapse chain โดยไม่ต่ออายุเวลาเดิม.

Flow ที่ UI ต้องใช้

1. อ่าน metadata ล่าสุดและเก็บ credential.id, revision กับ ETag.
2. ผู้ใช้เลือกทันทีหรือ 5 นาทีและยืนยันเหตุผล.
3. UI เปิด fresh OIDC popup จาก click gesture แล้วเรียก POST /v1/bo/auth/step-up/sandbox. Proof ผูก exact body bytes, revision, credential, scope, overlap และ idempotency key.
4. Callback ส่ง exact-origin message ชนิด paygate:sandbox-step-up; token ต้องขึ้นต้น pgsba1. และเก็บใน memory เท่านั้น.
5. ส่ง body bytes เดิมไป POST /v1/bo/sandbox/rotate พร้อม Content-Type: application/json; charset=utf-8, If-Match, Idempotency-Key, X-PG-Step-Up-Token และ X-PG-BO-Client: 1.

ครั้งแรกที่สำเร็จจะได้ secret รูป sk_test_<43 base64url chars> ครั้งเดียว. ให้คัดลอก ไปเก็บใน secret manager แล้วปิด dialog; UI ล้าง plaintext เมื่อปิด dialog เปลี่ยนหน้า หรือ logout. ระบบไม่มี endpoint สำหรับเปิดดูย้อนหลัง.

Response หายหลัง commit

Retry ด้วย idempotency key เดิมจะได้ metadata เดิมพร้อม Idempotency-Replayed: true, secret_available=false และ secret=null เพื่อไม่เปิด secret ซ้ำ หากไม่ได้เก็บ secret จาก response แรก ให้หมุนคีย์ใหม่อีกครั้ง.

Error ที่ต้องจัดการ

• 404 sandbox_credential_not_found — scope/session ไม่ใช่ exact Merchant sandbox หรือ slot เปลี่ยนไป;
• 409 sandbox_version_conflict — refetch metadata และให้ผู้ใช้ตรวจใหม่;
• 409 sandbox_overlap_active — รอ valid_until หรือเลือกหมุนทันทีด้วย idempotency key ใหม่;
• 401 step_up_required — เริ่ม fresh popup ใหม่ ห้าม reuse token;
• 428 mutation_precondition_required — If-Match หายหรือผิดรูป;
• 503 sandbox_rotation_unavailable — หยุดและ retry แบบมี backoff; ห้ามสร้าง secret ฝั่ง browser.

Preview เป็น read-only และไม่จำลอง rotation สำเร็จหรือสร้าง secret.