Giao diện
Xác thực & phiên
Trang sinh tự động
Đo trên source và trên schema sau khi chạy 820 migration, tại commit ad83b0aea.
Danh tính là của PIDEAL. Không dùng Supabase Auth: không code path nào gọi /auth/v1/*, đọc auth.users hay nạp SDK của Supabase.
Mật khẩu
Băm PBKDF2-HMAC-SHA256, 600.000 vòng, salt 16 byte, lưu dạng pbkdf2-sha256$<vòng>$<salt>$<hash>. Số vòng lưu theo từng dòng và được nâng khi người dùng đăng nhập, nên tăng tham số không cần migration dữ liệu.
Một số điện thoại không tồn tại tốn đúng chừng ấy CPU (derive giả), nên không đo được thời gian phản hồi để dò xem tài khoản có tồn tại hay không.
Khách hàng và nhân viên dùng hai bảng credential khác nhau, nên chính sách của hai nhóm độc lập với nhau.
Token
| Access token | JWT ES256, mang kid, iss, aud, sub, sid, app, hạn 15 phút |
| Refresh token | Chuỗi đục <sid>.<secret>; database chỉ lưu sha256(secret) |
| Xoay vòng | Refresh token đổi mới ở mỗi lần refresh |
| Dùng lại | Token vừa bị xoay, dùng lại ngay → lỗi nhưng giữ phiên; dùng lại muộn hơn → thu hồi phiên |
Token không chứa vai trò hay quyền — chúng được đọc lại ở mỗi request.
Khoá bất đối xứng nên chỉ auth giữ khoá riêng; function khác chỉ cần khoá công khai. Xoay khoá theo kid không đăng xuất ai.
Thời hạn phiên
| Ứng dụng | Không hoạt động | Tối đa |
|---|---|---|
| User App, Sale App | 30 ngày | — |
| Web Admin | 30 phút | 12 giờ |
Web Admin ngắn hơn hẳn vì đó là nơi có quyền thay đổi dữ liệu của người khác.
Thu hồi phiên
Phiên bị thu hồi khi: đăng xuất (phiên này hoặc mọi phiên), đổi mật khẩu, đặt lại mật khẩu, MFA reset được duyệt, vai trò Web Admin bị hạ, cấp lại mật khẩu tạm, và khi một lần refresh bị từ chối vì mất quyền truy cập.
Mỗi lý do được ghi lại trên phiên, nên tra được vì sao một người bị đăng xuất.
Đăng nhập Web Admin luôn là một challenge
/sign-in với WEB_ADMIN không bao giờ trả phiên ngay. Nó trả về một challenge, và các bước phải xong theo thứ tự:
- Đổi mật khẩu — khi đang dùng mật khẩu tạm
- Đăng ký TOTP — khi chưa có factor
- Xác thực TOTP — khi đã có
Bước cuối mới trả phiên. Mật khẩu tạm hết hạn đọc giống hệt mật khẩu sai, chỉ khác một mã lý do — để không lộ trạng thái tài khoản.
/sign-up/* và /password-reset/* từ chối WEB_ADMIN: Web Admin không có tự đăng ký và không có đặt lại mật khẩu bằng OTP. Mất quyền truy cập thì đi qua quy trình của người vận hành.
19 route của function auth
Tất cả đều là POST và đều cần header x-pi-app.
/sign-up—/sign-up/start,/sign-up/verify/sign-in—/sign-in,/sign-in/password-change,/sign-in/mfa/enroll,/sign-in/mfa/enroll/verify,/sign-in/mfa/password—/password/change/staff—/staff/temporary-password/session—/session/refresh/sign-out—/sign-out/password-reset—/password-reset/start,/password-reset/verify,/password-reset/complete/mfa—/mfa/status,/mfa/enroll,/mfa/enroll/verify,/mfa/step-up/pipoint—/pipoint/exchange
Danh sách đầy đủ kèm ghi chú trong code: Route của function auth.
Bảng của luồng xác thực
Thông tin đăng nhập
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
credential_challenges | 16 | 0 | P1-01. SECRET_BEARING. Hashed one-time code bound to phone+app+purpose; one open challenge per key. |
password_credentials | 7 | 0 | AF-P2-01. SECRET_BEARING password credential of the local provider, one per phone. subject = account_id once the account exists (no FK: the sign-up saga creates it first). sign_up_challenge_id is the saga idempotency key. Hash only, self-describing format (credential-policy). |
staff_credentials | 9 | 0 | PPI-P2-01 (E-05). SECRET_BEARING password credential of a STAFF account (Web Admin), one per account and phone. Hash only (credential-policy format). must_change + temporary_expires_at = a temporary password issued by another admin (D-15, 72 h); issued_by = that admin (null for the operator script). Reached only through identity_flow. |
Phiên
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
account_sessions | 13 | 0 | AF-P2-01. SYSTEM_ONLY PIDEAL session per sign-in and app: refresh token hash (sha256 of the secret), previous hash for the rotation grace, idle and absolute expiry (session-policy), revocation reason. No raw token, IP or user agent is stored. |
Challenge đăng nhập và đăng ký
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
credential_challenges | 16 | 0 | P1-01. SECRET_BEARING. Hashed one-time code bound to phone+app+purpose; one open challenge per key. |
sign_in_challenges | 10 | 0 | PPI-P2-01 (03 s3.3). SECRET_BEARING multi-step WEB_ADMIN sign-in: token <id>.<secret>, only sha256(secret) stored, 10 minutes, steps PASSWORD_CHANGE? then MFA_ENROLL | MFA_VERIFY in order; no session exists until finish. Reached only through identity_flow.sign_in_challenge_*; purged by identity_flow.purge_expired_credentials. |
MFA
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
mfa_factors | 17 | 0 | P1-07. SECRET_BEARING Admin MFA factor (TOTP), one live (non-REMOVED) row per account. The secret is AES-256-GCM sealed outside the DB; attempt/lock columns are the MFA lockout (AD-AUTH-05-locked). |
mfa_reset_requests | 14 | 0 | P1-07. PERM_GATED maker/checker MFA reset (AD-03 mfa_reset.request, AD-04 mfa_reset.approve); one open request per target; executes on approval; COMPLETED when the target re-enrolls. |
mfa_step_up_grants | 12 | 0 | P1-07. SYSTEM_ONLY step-up grant: one MFA verification -> one privileged command, bound to account, app, Supabase session, action (matrix res.act) and expiry; consumed once inside the command transaction. |
Khôi phục
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
recovery_grants | 9 | 0 | P1-01. SECRET_BEARING. One-use grant from a consumed challenge; never a session. |
Giới hạn tần suất
Khoá theo (loại tài khoản, số điện thoại) chứ không theo id tài khoản, nên đổi id không né được.
| Bảng | Cột | Policy | Mô tả |
|---|---|---|---|
api_guest_throttles | 5 | 0 | #469 (DEC-469-03). SYSTEM_ONLY call counter of token-less GraphQL requests per client (sha256 of the client key: cf-connecting-ip or the shared bucket of requests without one; never an address). Written only by public.api_guest_throttle_begin (pi_api, definer); rows 10 minutes past their window are purged by it. No payload. |
campaign_write_throttles | 4 | 0 | CV3-P4-01 (DEC-CV3-18). SYSTEM_ONLY call counter of the campaign writes saveCampaignDraft / createCampaign / updateCampaign / saveRecurringCampaignDraft per Web Admin account (fixed window). Written only by campaign.write_throttle_begin (pi_api, definer); rows a day past their window are purged by it. No payload, no PII. |
pipoint_exchange_throttles | 5 | 0 | PPI-P3-10 (GAP-PPI-01). SYSTEM_ONLY attempt counter of POST auth/pipoint/exchange per (scope, sha256 of the key): UID = verified PiPoint uid, IP = caller address. Never stores a raw uid, address or token. Written only by identity_flow.pipoint_exchange_begin (pi_auth); rows a day past their window are purged by it. |
sign_in_throttles | 6 | 0 | P1-03 + PPI-P1-02 (B-07). SYSTEM_ONLY temporary sign-in lockout per (kind, phone): kind = the app's account kind (identity_flow.account_kind_for_app), so a STAFF lockout never locks the CUSTOMER sign-in of the same phone. Counts attempts, never stores a password, code or token. Not the staff lock: accounts/app_memberships.status LOCKED is separate. |