Hành vi session

Session owner

Identity Service owns session trong:

identity.auth_session

Session gắn với:

• account_id
• optional workspace_id
• optional member_id
• optional active_branch_id
• jti
• status
• expires_at

Login tạo session

POST /api/auth/login:

• Validate account và credential.
• Create identity.auth_session.
• Issue refreshToken.
• Set refreshToken bằng HttpOnly cookie.
• Với single branch: session có branch scope ngay.
• Với multi branch: session chờ POST /api/auth/select-branch.

Refresh behavior

POST /api/auth/refresh:

• Nhận refreshToken từ request body JSON field refreshToken hoặc refresh cookie.
• Nếu body token và cookie token cùng tồn tại nhưng khác nhau, request invalid.
• Verify refreshToken.
• Load active session theo session_id.
• Check jti trong token khớp session jti.
• Rotate session bằng cách update jti và expires_at.
• Issue rotated refreshToken.
• Set lại refresh HttpOnly cookie.

Nếu session đã có branch scope, refresh trả branch-scoped accessToken và nextAction.type = load_current_context.

Nếu session chưa có branch scope, refresh trả accountAccessToken, branches[] và nextAction.type = select_branch.

Frontend note

First stale/missing /api/auth/refresh trả 401 là acceptable nếu sau đó login/refresh hợp lệ thành công.

Không xem 401 đầu tiên đó là blocker riêng nếu full auth flow vẫn pass.

Select branch cập nhật session

POST /api/auth/select-branch:

• Yêu cầu accountAccessToken.
• Validate branchId.
• Check branch cùng workspace, active, và account có branch membership.
• Update identity.auth_session với branch scope.
• Issue branch-scoped accessToken.

Logout behavior

POST /api/auth/logout confirm từ code:

• Có thể nhận access token qua Authorization.
• Có thể nhận refreshToken từ body hoặc cookie.
• Nếu tìm được session hợp lệ, set status = REVOKED và revoked_at.
• Clear refresh cookie.
• Trả success message.

README ghi compatibility note: no-token logout trả 200 AUTH_LOGOUT_SUCCESS.

Cookie behavior

Refresh cookie config dùng env vars:

• CENTEROS_AUTH_REFRESH_COOKIE_NAME
• CENTEROS_AUTH_COOKIE_PATH
• CENTEROS_AUTH_COOKIE_SECURE
• CENTEROS_AUTH_COOKIE_SAME_SITE

Cookie flags từ code:

• HttpOnly=true
• Secure theo config
• SameSite theo config
• MaxAge theo refresh token expiry

TODO

• Chưa đóng: logout chưa nằm trong checkpoint chính.
• Chưa đóng: exact browser cookie behavior theo từng environment.