Partner Operations Guide (Beta-4)

Sổ tay vận hành đối tác qua ops CLI — KHÔNG cần thao tác SQL trực tiếp. Mọi thao tác có audit.
Nguồn sự thật: packages/platform-infrastructure/src/ops/cli.ts. Vòng đời: ../platform/PARTNER-LIFECYCLE.md.
KHÔNG chứa secret. Raw API key chỉ hiển thị một lần lúc cấp/rotate — giao khách qua kênh an toàn.

Chạy CLI

cd packages/platform-infrastructure
# Cần DATABASE_URL trỏ tới Postgres tương ứng (staging/prod đã kiểm soát).
npm run ops -- <command> [flags]
# Thêm --json để lấy output máy-đọc.

Các lệnh nguy hiểm (revoke-key, revoke-partner, churn-customer, outbox-replay) bắt buộc --confirm;
thiếu → exit 2, không thực thi.

Bảng lệnh Partner

partnerId == customerId. issue-key dùng cờ --customer (tương thích lịch sử) nhưng nhận chính partnerId.

Quy trình chuẩn

1. Tạo Partner

npm run ops -- create-partner --name "Đối tác A" --owner ops@bng --json
# → { "partnerId": "…", "status": "pending" }

Partner ở pending — chưa dùng key được.

2. Kích hoạt

npm run ops -- create-tenant --partner <partnerId> --tenant t_partner_a --name "Tenant A"
npm run ops -- activate-partner --partner <partnerId>     # → active

issue-key yêu cầu Partner đã có Tenant (create-tenant).

3. Cấp key

npm run ops -- issue-key --customer <partnerId> --env sandbox --deliver --json
# In BANNER + raw key MỘT LẦN, rồi { keyId, prefix, environment, status:"active" }

• --deliver: kích hoạt key ngay (sandbox/demo). Bỏ --deliver ⇒ key pending_delivery, bàn giao sau bằng deliver-key.
• Giao raw key cho đối tác qua one-time secret link / password manager — không email/chat thô.

4. Suspend

npm run ops -- suspend-partner --partner <partnerId> --reason nonpayment

Hiệu lực tức thì: mọi request của partner → 401. Key KHÔNG bị huỷ (thuận nghịch).

5. Re-activate

npm run ops -- reactivate-partner --partner <partnerId>

Đúng key cũ hoạt động trở lại — không cần cấp lại.

6. Revoke (chấm dứt)

npm run ops -- revoke-partner --partner <partnerId> --reason offboarding --confirm

Terminal: revoke mọi key. Không khôi phục (muốn dùng lại = tạo Partner mới).

7. Rotate API Key

npm run ops -- rotate-key --key <keyId> --json                 # cutover ngay: key cũ revoke
npm run ops -- rotate-key --key <keyId> --grace-days 7 --json  # key cũ còn dùng 7 ngày rồi hết hạn

In raw key mới một lần. Key cũ:

• không grace ⇒ revoked ngay (401 tức thì).
• có grace ⇒ rotating, vẫn auth tới hết grace-days rồi tự hết hạn.

Quy trình xử lý khi NGHI NGỜ LỘ API KEY

Ưu tiên: cắt hiệu lực trước, điều tra sau. Guardrail bất khả xâm phạm = không để key lộ tiếp tục dùng được.

1. Chặn ngay (chọn 1):

• Lộ một key cụ thể → revoke-key --key <keyId> --reason suspected-leak --confirm (401 tức thì), rồi

rotate-key để cấp key mới cho đối tác (hoặc issue-key mới).

• Nghi lộ diện rộng / chưa rõ key nào → suspend-partner --partner <id> --reason suspected-leak

(chặn toàn bộ key của partner tức thì, thuận nghịch — khôi phục nhanh sau khi xử lý).

1. Cấp key thay thế: rotate-key (giữ lineage) hoặc issue-key --deliver, giao qua kênh an toàn.
2. Điều tra: show-provisioning --customer <id> (xem lastUsedAt, prefix, status — không có raw/hash),

show-audit --partner <id> (lịch sử issue/rotate/revoke/suspend).

1. Khôi phục: sau khi đã rotate + xác minh, reactivate-partner (nếu đã suspend).
2. Ghi nhận: lý do đã nằm trong revokedReason/audit. Không dán raw key vào ticket/log.

Raw key không lưu ở đâu (DB chỉ giữ hash sha256). "Xem lại" key cũ là không thể — mất/lộ ⇒ rotate.

An toàn & bảo mật

• Raw key/JWT chỉ in ở issue-key/rotate-key/mint-session-token, kèm banner "MỘT LẦN", không nằm trong dòng JSON summary.
• show-provisioning/show-audit không bao giờ lộ raw key hay keyHash.
• Ở NODE_ENV=production: guard chặn key demo bng_demo_* (fail-fast).
• Đối tác giao tiếp key: dùng one-time secret link / password manager.