Mô hình token và context

Mục tiêu

Giải thích cách CenterOS phân biệt account-level branch selection với branch-scoped business access, và cách downstream services nhận context từ API Gateway.

Trạng thái hiện tại

Đã đóng:

• Single branch login trả branch-scoped accessToken.
• Multi branch login trả accountAccessToken + branches[].
• POST /api/auth/select-branch đổi account token thành branch-scoped accessToken.
• Gateway inject trusted headers sau khi branch token hợp lệ.

Chưa đóng:

• Entitlement Service E2E consume headers qua Gateway cho current-context.

Luồng chính

Single branch customer:

POST /api/auth/login
→ accessToken
→ nextAction = load_current_context
→ business APIs

Multi branch customer:

POST /api/auth/login
→ accountAccessToken + branches[]
→ FE shows branch selection
→ POST /api/auth/select-branch
→ accessToken
→ business APIs

Refresh:

refreshToken
→ POST /api/auth/refresh
→ rotated session token response

Quy tắc quan trọng

Token roles:

• accountAccessToken: account-scoped token dùng cho select/switch branch.
• accessToken: branch-scoped token dùng cho business APIs sau khi branch context được chọn.
• refreshToken: session rotation token, cũng được set làm HttpOnly cookie khi applicable.

Gateway trusted headers sau branch token:

• X-Account-Id
• X-Workspace-Id
• X-Member-Id
• X-Active-Branch-Id
• X-Branch-Ids
• X-Roles
• X-Token-Scope=BRANCH
• X-Request-Id
• X-Correlation-Id

Downstream services consume headers:

• Downstream services như Entitlement Service nên dùng Gateway trusted headers.
• Downstream services không nên verify client JWT trong normal internal runtime.
• Client body workspaceId must not override trusted context.
• Workspace/member isolation phải đến từ trusted Gateway context, không từ client-provided body fields.

Liên quan

• Checkpoint Go Gateway và Identity đã đóng
• Boundary giữa service
• Trusted headers
• Token scopes

TODO

• Chưa đóng: Entitlement Service E2E proof cho trusted context qua Gateway.