[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F44APK7X15EFYDDA5N8EKB":3,"skill-same:01M7F44APK7X15EFYDDA5N8EKB":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7F44APK7X15EFYDDA5N8EKB","handling-auth-and-workspace",null,"Dual authentication CRM\u002FClient (JWT chỉ chứa uid, 2FA TOTP, device limit qua rts:{uid} zset) và các module config liên quan (IndexedDB master-data sync). Dùng skill này KHI đụng login\u002Flogout\u002Frefresh-token\u002F2FA, session\u002Fdevice management, trước khi tái tạo helper đọc company\u002Fusername từ JWT (đã xoá 2026-07-04 — PHẢI dùng GetBranchActiveID; company đã xoá hoàn toàn D15\u002Fstory-41), hoặc khi thêm bảng IndexedDB mới ở FE.","cluvix\u002Fcluvix-crm","cluvix","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F324537109?v=4","01M7F40XX639HYM8HRW4JW1TA5","Cluvix Solutions","01M7F40XYG6YMX0CD0QZNV61K4",21,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fhandling-auth-and-workspace\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: handling-auth-and-workspace\ndescription: >-\n  Dual authentication CRM\u002FClient (JWT chỉ chứa uid, 2FA TOTP, device limit qua rts:{uid}\n  zset) và các module config liên quan (IndexedDB master-data sync). Dùng skill này KHI đụng login\u002Flogout\u002Frefresh-token\u002F2FA,\n  session\u002Fdevice management, trước khi tái tạo helper đọc company\u002Fusername từ JWT (đã\n  xoá 2026-07-04 — PHẢI dùng GetBranchActiveID; company đã xoá hoàn toàn D15\u002Fstory-41),\n  hoặc khi thêm bảng IndexedDB mới ở FE.\n---\n\n# Auth & Workspace\n\n> reference\u002Findexeddb.md: IndexedDB master-data sync phía BE.\n\n\n## Tổng quan\n2 hệ thống auth hoàn toàn tách biệt: CRM (nhân viên) và Client (đối tác bên ngoài).\n\n## CRM Auth (Nhân viên)\n\n### Flow\n```\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogin   { username, password, device_fingerprint }\n  → BE: validates credentials\n  → BE: upsert user_device (device binding — xem §Device binding); đóng fingerprint vào refresh token\n  → BE: Set-Cookie: refresh_token=\u003Copaque>; HttpOnly; Secure; SameSite=None; Path=\u002Fapi\u002Fauth; Max-Age=...\n       (HTTP dev: SameSite=Lax + Secure=false — None yêu cầu Secure=true)\n  → Response body: { accessToken, expiresAt, refreshExpiresAt }   ← NO refreshToken in body\n  → FE: TokenService.setTokens(accessToken, expiresAt, refreshExpiresAt)\n       stores encrypted access_token (AES-GCM) + refresh_token_expires_at in localStorage\n       refresh_token cookie managed entirely by browser\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Frefresh-token   { device_fingerprint }\n  → Browser auto-sends refresh_token cookie (withCredentials: true, default in ApiService)\n  → BE: reads c.Cookie(\"refresh_token\"), verify device fingerprint theo DEVICE_BINDING_MODE, rotates, sets new cookie\n  → Response body: { accessToken, expiresAt, refreshExpiresAt }   ← NO refreshToken in body\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogout   ← PUBLIC route (không qua JWTAuth)\n  → Hoạt động cả khi access token đã hết hạn — bắt buộc để consume refresh cookie\n  → Prod: reject Sec-Fetch-Site: cross-site (403) — chống CSRF forced-logout; dev skip (FE\u002FBE khác site)\n  → BE: revoke access jti (best-effort nếu có Bearer, truyền c.ClientIP() cho IP binding) + consume refresh + clear cookie (Max-Age=-1)\n  → FE: TokenService.clearToken() wipes localStorage timestamps\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogout-all (authed)\n  → RevokeAllSessions + RevokeAllRefreshTokens — PHẢI revoke cả 2 (xem §Security)\n\nRequest → middleware.JWTAuth(tokenSvc) → decode JWT + check revoked:{jti} (Redis) → set userID\n       → middleware.AuthResponseHeaders() → loadUserScope() → set branchActiveId, branchIds, locale\n```\n\n### JWT Claims\n```go\ntype Claims struct {\n    UID uint `json:\"uid\"`\n}\n\u002F\u002F KHÔNG có branch_id\u002Fusername trong JWT — branch scope lấy từ UserScope\n\u002F\u002F (GetBranchActiveID). GetCompanyID đã xóa 2026-07-04, KHÔNG tái tạo. D15\u002Fstory-41:\n\u002F\u002F company đã xoá hoàn toàn khỏi hệ thống (1 thương hiệu\u002FDB) — không còn company_id\u002F\n\u002F\u002F companyActiveId\u002FcompanyIds ở bất kỳ tầng nào.\n```\n\n### Context getters\n- `GetUserID(c)` → uint\n- `GetBranchActiveID(c)` → uint\n- `GetBranchIDs(c)` → []uint\n\n### UserScope (cached Redis 5 phút)\n- Load từ `user` (driving) LEFT JOIN `user_profile` → branchActive_id, branchIds (JSON), locale, **status**\n- `InvalidateUserScope(userID)` — gọi khi user đổi branch\u002Fstatus\n- `branchActive_id` chỉ được tin khi còn ∈ `branchIds` (`effectiveActiveBranch`, 2026-10-20) — lệch ⇒ về chi nhánh đầu tiên được phép; `branchIds` rỗng = không giới hạn ⇒ giữ nguyên\n- `AuthResponseHeaders` abort 401 nếu `scope.Status != define.UserStatusActive` — enforce per-request, không chỉ lúc login\n- Cache cleared khi admin update user → request ngay sau re-read DB → enforce ngay không cần logout\n\n### Security\n- **Device limit thật = giới hạn refresh token** (2026-07-04): zset `rts:{uid}` (rid → expiry) index refresh token\u002Fuser; login vượt `TOKEN_MAX_SESSIONS` (default 3) → evict refresh của thiết bị ít-refresh-nhất (LRU) → thiết bị đó chết trong ≤ AccessTTL. Giới hạn access-session một mình VÔ NGHĨA (bị revoke thì silent-refresh sống lại)\n- **Logout dùng `ConsumeRefresh` KHÔNG `VerifyAndRotateRefresh`** — rotate lúc logout tạo orphan token chiếm 1 slot device đến hết RefreshTTL\n- **Rotation nguyên tử + phát hiện dùng lại (2026-10-20)**: `claimRefresh` (Lua: DEL `rt` + ghi `rtused:{rid}` = uid:hash:unix) — 2 request cùng token chỉ 1 cái thắng; thua ⇒ `ErrRefreshRaced` ⇒ handler trả **409, KHÔNG xoá cookie** (FE coi là lỗi thoáng qua). Token đã xoay vòng bị trình lại sau `refreshReuseGrace` (30s) ⇒ `ErrRefreshReused`: thu hồi MỌI refresh + access của user, seclog `refresh_reuse_detected`\n- Token revocation (jti blacklist), IP binding (optional)\n- **Revocation enforce tại `JWTAuth(tokenSvc)`** (2026-07-04): check `revoked:{jti}` mỗi request — fail-open khi Redis lỗi\n- **TTL blacklist = phần đời còn lại của token** (lấy từ `sess:{uid}` zset score) — TTL cố định ngắn hơn AccessTTL sẽ mở resurrection window (token revoke xong sống lại)\n- **Revoke access PHẢI kèm revoke refresh (CRITICAL)**: chỉ `RevokeAllSessions` → thiết bị khác 401 thoáng qua rồi silent-refresh lấy token mới → revoke vô dụng. LUÔN gọi cặp `RevokeAllSessions(uid)` + `RevokeAllRefreshTokens(uid)` (logout-all, đổi mật khẩu, đổi role\u002Fstatus)\n- refresh_token: HttpOnly Secure SameSite=None cookie (Lax trên HTTP dev), Path=\u002Fapi\u002Fauth (Cấp 2, implemented 2026-04-26)\n- access_token: AES-GCM encrypted at rest in localStorage (Cấp 1)\n- Login rate limit: 10 req\u002FIP\u002F5min via Redis INCR\n- **Trusted proxies (CRITICAL)**: `r.SetTrustedProxies(cfg.TrustedProxies)` — gin default tin MỌI proxy → `ClientIP()` spoof được qua X-Forwarded-For. Set `TRUSTED_PROXIES` đúng khi sau reverse proxy, nếu không rate-limit\u002FIP-binding\u002Fseclog đều dựa IP giả. Chiều ngược lại cũng chết: sau nginx mà `.env` TRỐNG ⇒ `ClientIP()` = 127.0.0.1 cho MỌI request ⇒ rate limit key theo IP thành 1 bucket toàn cục (livechat 2026-09-03). Rate limit mới theo IP phải key thêm tenant\u002Fsite và ghi tiền điều kiện này\n- **IP binding** (`TOKEN_IP_BINDING=true`): `buildAccessJWT` nhét `ipHash=sha256(ip)` vào access token; `JWTAuth` so với `sha256(ClientIP)` mỗi request → 401 khi lệch. User di động đổi IP → 401 → interceptor silent-refresh → token rebind IP mới (không logout). Opt-in, default off\n- **Token khác access (challenge 2FA, one-time...) PHẢI ký key riêng** (vd `sha256(Secret+\":purpose\")`) — `JWTAuth` verify chữ ký + expiry + `revoked:{jti}` + issuer\u002Faudience (`token.ClaimsMatchTenant`, issuer\u002Faud chứa DB_NAME từ 2026-10-18 — chặn token chéo khách) nhưng KHÔNG phân biệt mục đích token; ký chung `TOKEN_SECRET` → token đó dùng được làm Bearer access token (challenge không có jti → bỏ qua cả revocation check) = bypass. Test guard: `pkg\u002Ftoken\u002Fchallenge_isolation_test.go`\n\n### IP allowlist nhân viên (Hướng 2A — khác IP binding)\n- **`IP_ALLOWLIST_MODE=off|log|enforce`** (`SetIPAllowlistMode` ở boot). Chặn nhân viên theo `allowed_ips` (IP\u002FCIDR) — KHÁC IP binding (bind token vào 1 IP): allowlist là danh sách IP\u002Fdải được phép\n- **Cột `allowed_ips` JSON** trên `business_profile` (D15\u002Fstory-62, qua `pkg\u002Fbrand`; trước đây trên `company`) + `user`. **Effective = user override > hồ sơ thương hiệu** (user non-empty thắng; rỗng cả hai = không giới hạn). Load vào `UserScope.AllowedIPs` (cache 5 phút → đổi allowed_ips propagate ≤5 phút hoặc `InvalidateUserScope`)\n- **Enforce trong `AuthResponseHeaders`** (sau khi set branchActiveId): `helpers.IPInAllowlist(ClientIP, list)` (exact IP + CIDR). enforce → 403 `ip_not_allowed`; log → chỉ seclog (throttle 1 lần\u002F(user,ip)\u002F5phút chống flood)\n- **Super-user LUÔN bypass** (`UserScope.IsSuper` = EXISTS role trong `define.SuperRoles`) — cấu hình sai không tự khóa admin\n- **PHỤ THUỘC trusted proxies** — ClientIP phải thật\n- FE: field `allowed_ips` (textarea IP\u002FCIDR mỗi dòng) trong form hồ sơ doanh nghiệp (`authBusinessProfile`) + user; cảnh báo lockout. `helpers.IPInAllowlist` cũng nâng `checkPartnerIP` (partner_auth) từ exact match lên CIDR\n- Test: `pkg\u002Fhelpers\u002Fipmatch_test.go` (exact\u002FCIDR\u002FIPv6\u002Fedge)\n\n### Device binding (fingerprint)\n- **Bảng `user_device`** (auth-level, KHÔNG company_id): `(user_id, fingerprint)` UNIQUE, status trusted\u002Fpending\u002Frevoked. Nền cho 2FA\u002FWebAuthn per-device sau này\n- FE gửi `device_fingerprint` (SHA-256 base64url, `fingerprint.ts`, KHÔNG gồm screen — đổi khi cắm màn ngoài) ở login + refresh\n- Fingerprint đóng vào refresh token value: `rt:{uid}:{rid}` = `\u003Chash>` (legacy) hoặc `\u003Chash>:fp:\u003Cfingerprint>`\n- **`DEVICE_BINDING_MODE=off|log|enforce`**: enforce → refresh với fp lệch storedFP = 401; log → chỉ seclog `refresh_fp_mismatch` (đo tỷ lệ trước khi bật enforce); token legacy (không fp) luôn bỏ qua, tự nâng cấp ở rotation kế\n- API self-service: `GET \u002Fauth\u002Fdevices`, `POST \u002Fauth\u002Fdevices\u002F:id\u002Frevoke` — CHỈ thiết bị của chính user (`GetOwned` scope theo user_id); FE ở menu profile\n- **Upsert throttle**: `Dao.Upsert(..., minTouchInterval)` — login truyền 0 (luôn ghi), refresh truyền 1h (bỏ qua write nếu last_seen còn mới) → giảm tải hot-path refresh\n- **Dọn nền**: `user_device_cleanup` (`helpers.RunBackground` ở bootstrap, 24h) xoá device `last_seen` quá `define.UserDeviceStaleDays` (90) — chống phình bảng\n- **`pkg\u002Fseclog`**: structured security events (`sec_event` field) — login_success\u002Ffailed, new_device, refresh_fp_mismatch, access_ip_mismatch, device_evicted\u002Frevoked, revoked_token_reused, ip_not_allowed. **`Event` no-op khi `logger.L` nil** (test\u002Fboot sớm)\n- **Test**: `pkg\u002Ftoken\u002Ftoken_device_test.go` (miniredis) — fingerprint binding enforce\u002Flog, legacy upgrade, device limit cap, ConsumeRefresh, RevokeRefreshByFingerprint, ActiveFingerprints, revocation blacklist\n\n### Audit log (Hướng 2B — persist seclog vào DB)\n- **`seclog.InitSink(buf, flush)`** (wire ở bootstrap): `Event` đẩy `Entry` vào buffered channel → goroutine batch-INSERT (`CreateInBatches`). **Non-blocking**: channel đầy → drop + `seclog.Dropped()` đếm, KHÔNG chặn request. Flush do module audit cấp (seclog không import DB\u002FDAO)\n- `Event` promote key `user_id`\u002F`username` sang cột, còn lại vào `detail` JSON.\n- **Bảng `security_audit_log`** (auth-level, TOÀN DB — D15\u002Fstory-58 đã bỏ hẳn cột `company_id`, 1 thương hiệu\u002FDB nên không cần scope company nữa): index `(user_id,created_at)`, `(event,created_at)`\n- **API `GET \u002Fauth\u002Faudit-log`**: super-user only (`RbacSvc.IsSuperUser` — config module không có perm middleware), KHÔNG scope gì thêm — xem hết log của DB. paginate + filter `user_id \u002F event (1) \u002F events (nhóm, phẩy) \u002F from \u002F to`.\n- **Dọn nền** `security_audit_cleanup` (`helpers.RunBackground`, 24h) xoá quá `define.AuditRetentionDays` (180)\n- **FE**: trang `config\u002Fsecurity-audit` (audit tổng) + `log\u002Flogin` (lịch sử đăng nhập, module history) — cả 2 super-user, p-table lazy. `authService.getAuditLog()`\n- **Test**: `pkg\u002Fseclog\u002Fseclog_test.go` — sink batch flush + field promotion + nil-logger no-panic\n\n### Login history (chi tiết kiểm soát đăng nhập)\n- `login_failed` mang `reason` trong detail: `user_not_found | bad_password | inactive | rate_limited`. **Distinction chỉ ở audit (super-user), response luôn generic `login_failed`** — chống user enumeration\n- Login query bỏ `WHERE status=Active` → query theo username rồi check status (phân biệt not_found vs inactive). Rate-limit (429) giờ cũng ghi `login_failed reason=rate_limited`\n- `login_failed` (user thật) + `logout` resolve `companyActive_id` sớm → hiện trong view theo company (trước đây NULL → vô hình)\n- `logout` event ghi khi decode được bearer (user_id + company). Login là public route → resolve company qua query user_profile\n- FE `log\u002Flogin` (`modules\u002Fhistory\u002Flogin`): gộp login_success\u002Ffailed\u002Flogout\u002Fnew_device\u002Flogin_no_fingerprint qua `?events=`; cột reason + device. Menu gate `isSuperUser()` (không gắn permission để non-super khỏi thấy rồi 403)\n\n### FE TokenService API (post Cấp-2 refactor)\n```typescript\n\u002F\u002F ✅ Current API\ntokenService.setTokens(accessToken: string, expiresAt?: number, refreshExpiresAt?: number)\ntokenService.getAccessToken(): string | null   \u002F\u002F decrypts AES-GCM from localStorage\ntokenService.hasValidToken: boolean\ntokenService.hasValidRefreshSession(): boolean  \u002F\u002F checks refresh_token_expires_at timestamp only\ntokenService.isRefreshTokenExpired(): boolean\ntokenService.clearToken()                       \u002F\u002F clears localStorage, cookie cleared by BE on logout\n\n\u002F\u002F ❌ REMOVED — do NOT use\n\u002F\u002F tokenService.getRefreshToken()     → no longer exists (cookie is HttpOnly, JS cannot read)\n\u002F\u002F tokenService.setTokens(a, b, c, d) → 4-arg form removed\n```\n\n### doRefresh — clearToken chỉ khi 401\u002F403 (CRITICAL)\n\n`doRefresh()` catch block **không được gọi `clearToken()` cho mọi lỗi**. Chỉ clear khi BE xác nhận token thực sự invalid:\n\n```typescript\n\u002F\u002F ✅ CORRECT (hiện tại)\n} catch (err: any) {\n    const status = (err as any)?.status;\n    if (status === 401 || status === 403) {\n        this.clearToken();  \u002F\u002F token thực sự hết hạn ở Redis\n    }\n    return false;  \u002F\u002F network\u002F5xx: không xóa refresh_token_expires_at\n}\n\n\u002F\u002F ❌ NEVER — clearToken với mọi lỗi\n} catch (err: any) {\n    this.clearToken();  \u002F\u002F lỗi mạng thoáng qua xóa refresh_token_expires_at\n    return false;       \u002F\u002F → isRefreshTokenExpired() = true → \"session expired\" giả\n}\n```\n\n**Lý do:** `clearToken()` xóa `refresh_token_expires_at` khỏi localStorage. `isRefreshTokenExpired()` trả `true` khi key bị thiếu. Nếu auto-refresh timer gặp lỗi mạng và clear session, điều hướng kế tiếp sẽ báo \"Refresh session expired\" dù refresh token trong Redis vẫn còn hiệu lực.\n\n**Phân biệt 3 path:**\n- **auto-refresh timer** → network error: `doRefresh()` retry backoff (status 0\u002F5xx) rồi mới trả false, không clearToken → state giữ nguyên\n- **API request → 401 → refresh fail (interceptor)**: chỉ clearToken khi `hasValidRefreshSession()` = false; transient → propagate error, không logout\n- **authGuard → trySilentRefresh fail**: transient (session còn) → cho điều hướng tiếp, interceptor refresh lại ở 401 kế tiếp; chỉ redirect login khi session hết\n\nChi tiết retry\u002Fdiscriminator: `frontend\u002Fskill\u002Fskills\u002Fhandling-fe-auth-and-i18n\u002Freference\u002Ffe-patterns-gotchas-auth.md` §\"refresh fail ≠ logout\"\n\n### authGuard (post Cấp-2)\nFE cannot read the refresh_token cookie. Guard checks expiry via timestamp only:\n```typescript\n\u002F\u002F ✅ Correct check\nif (tokenService.isRefreshTokenExpired()) { redirect to \u002Flogin }\n\n\u002F\u002F ❌ Old pattern — removed\n\u002F\u002F const rt = tokenService.getRefreshToken(); if (!rt) { redirect }\n```\n\n### authInitialized — race với withEnabledBlockingInitialNavigation (CRITICAL)\n\n`withEnabledBlockingInitialNavigation()` đăng ký APP_INITIALIZER riêng chạy **song song** với `initializeAuth` — không phải sau. Khi access token còn hạn: `initialize()` (crypto ~1ms) xong trước → `hasValidToken=true` → `authGuard` pass ngay → `requirePerm` chạy synchronous — nhưng IDB read trong `restoreAuthUser()` (~10–50ms) chưa xong → `userPermissions = Set()` rỗng → redirect `\u002Fauth\u002Faccessdenied` trên mọi deep route khi F5.\n\nXảy ra khi: auth storage dùng IndexedDB (async) + SW cache chunk (fast import) — cả hai cộng lại làm race đủ lớn để xảy ra deterministic.\n\n**Fix pattern (đã implement):**\n```typescript\n\u002F\u002F auth.state.ts\nexport const authInitialized = signal(false);\n\n\u002F\u002F auth.service.ts — restoreAuthUser()\ntry { \u002F* ... restore logic ... *\u002F } finally { authInitialized.set(true); }\n\n\u002F\u002F authGuard.ts — waitInitialized$ tạo trong injection context (toObservable không gọi được trong switchMap)\nconst waitInitialized$ = authInitialized()\n  ? of(true as const)\n  : toObservable(authInitialized).pipe(filter(Boolean), take(1), map(() => true as const));\n\u002F\u002F Dùng ở CẢ 2 path: hasValidToken = true VÀ silent-refresh thành công\n\u002F\u002F (refresh xong nhưng restoreAuthUser Case 1a còn đang fetch \u002Fme → phải đợi)\n```\n\nOverhead: chỉ xảy ra lần đầu tiên (F5 với token còn hạn). Mọi navigation sau đó `authInitialized()` đã `true` → zero overhead.\n\n### withCredentials\n`ApiService.createHttpOptions()` sets `withCredentials: true` by default — all requests\nautomatically include cookies. No need to pass it explicitly at call sites.\n\n### Cấp 3 (NOT implemented — deferred)\nMoving access_token to HttpOnly cookie would trade XSS risk for CSRF risk (no CSRF protection in place).\nTriggers to re-evaluate: SOC2 Type II audit, PCI-DSS scope expansion, or pen-test finding.\n\n## (đã bỏ, D15\u002FCRM standalone) Client Auth (Đối tác — Zalo Mini App, website)\n\nModule `internal\u002Fmodules\u002Fclient\u002F` (PartnerAuth, `partners.company_id`\u002F`companyActiveId`,\n`GetPartnerCompanyID`) **KHÔNG còn tồn tại trong repo CRM standalone này** — verify 2026-09-28:\n`internal\u002Fmodules\u002F` chỉ còn `webapp\u002F` (không có `client\u002F`\u002F`mobile\u002F`\u002F`public\u002F`), không có\n`internal\u002Fmiddleware\u002Fpartner_auth.go`. Nội dung dưới đây (flow OAuth partner, JWT `PartnerClaims`,\n`GetPartnerID`\u002F`GetPartnerCompanyID`) mô tả kiến trúc ERP cũ trước khi tách CRM standalone — giữ\nlàm lịch sử, KHÔNG áp dụng. Skill `building-client-and-sync-apis` đã xoá khỏi CRM standalone.\n\n## Response format khác nhau\n\n### CRM — `pkg\u002Fresponse\u002Fresponse.go`\n- `Data(c, data)`, `DataWithMessage(c, data, msg)`, `Validate(c, msg)`, `NotFound(c)`, `ServerError(c, err)`\n\n### Client — `pkg\u002Fresponse\u002Fclient.go`\n- `ClientSuccess(c, data, msg)` → `{success: true, code: 200, message, data, timestamp}`\n- `ClientError(c, msg, code)` → `{success: false, code, message, data: null, timestamp}`\n- `ClientValidate(c, msg)` → `{success: false, code: 422, message, data: null, timestamp}`\n\n## Router\n```go\napi := r.Group(\"\u002Fapi\")\napi.POST(\"\u002Fclient\u002Foauth\u002Ftoken\", h.OAuthToken)                          \u002F\u002F public\n\u002F\u002F CRM public: \u002Fauth\u002Flogin, \u002Fauth\u002Frefresh-token, \u002Fauth\u002Flogout (xem Flow)\nauthed := api.Group(\"\", middleware.JWTAuth(d.TokenSvc), middleware.AuthResponseHeaders(db, d.Cache)) \u002F\u002F CRM\nclientGroup := api.Group(\"\u002Fclient\", middleware.PartnerAuth())           \u002F\u002F Client\n```\n\n### 2FA — TOTP (Hướng 3)\n- **Login 2 bước**: `POST \u002Fauth\u002Flogin` → nếu user bật 2FA + thiết bị chưa trusted → trả `{requires_2fa, challenge_token}` (CHƯA cấp token). `POST \u002Fauth\u002Flogin\u002F2fa {challenge_token, code, remember_device}` → verify TOTP\u002Fbackup → cấp token. `challenge_token` = JWT 5 phút aud=`2fa-challenge` (proof đã qua password).\n- **Device-aware skip**: bỏ qua 2FA CHỈ khi `user_device.totp_trusted_until > now` **VÀ** client trình đúng token remember-device (cookie HttpOnly `device_trust_\u003CuserID>` path `\u002Fapi\u002Fauth`; mobile transport: body `device_trust_token`) khớp `user_device.totp_trust_hash` (SHA-256, so constant-time), thiết bị chưa revoked. `remember_device` ⇒ server sinh token ngẫu nhiên 32 byte, hạn = now + `business_profile.totp_trust_days` (0 = luôn hỏi, cho máy dùng chung). ⚠ KHÔNG bao giờ tin riêng `device_fingerprint` — client tự tính từ UA\u002Fngôn ngữ\u002Fmúi giờ\u002FCPU, đoán được (lỗ hổng vá 2026-10-20). Revoke thiết bị xoá trust.\n- **Secret mã hóa** AES-GCM bằng `TOTP_ENC_KEY` (env riêng); backup codes hash sha256, 1 lần. Rate-limit verify 5 lần\u002F5 phút.\n- **Endpoints** (authed): `\u002Fauth\u002F2fa\u002Fstatus|setup|verify-setup|disable`, `\u002Fauth\u002F2fa\u002Freset\u002F:userId` (super-user).\n- **Policy per-company + per-role**: `company.require_2fa=1` HOẶC role ∈ `company.require_2fa_roles`. Bắt buộc mà chưa enroll → `UserScope.MustSetup2FA=true` → **AuthResponseHeaders chặn mọi API (trừ `\u002Fauth\u002F2fa\u002F*`, `\u002Fauth\u002Fme`, `\u002Fauth\u002Fpermission`) với 403 code=`2fa_setup_required`** → FE interceptor redirect `\u002F2fa-setup`.\n- **`AuthResponseHeaders` chạy các gate nối tiếp sau khi set `branchActiveId`\u002F`branchIds`**: 2FA (`code=2fa_setup_required`, chặn mọi API trừ endpoint setup 2FA + `\u002Fme`) rồi IP allowlist (`ip_not_allowed`, mode `enforce`). ⚠ **(đã bỏ, D15)** Trước đây còn gate thứ 3 chặn khi `GetCompanyActiveID(c)==0` (`code=company_active_required`, FE redirect `\u002Fchoose-company`) — đã xoá cùng company (1 thương hiệu\u002FDB không cần chọn thương hiệu active).\n- **Hai gate loại trừ nhau về cấu trúc**: `require_2fa`\u002F`require_2fa_roles` lấy qua `LEFT JOIN company c ON c.id = p.companyActive_id` ⇒ `companyActive_id` NULL thì join rỗng ⇒ `MustSetup2FA` **luôn false**. Nghĩa là chính sách 2FA theo thương hiệu KHÔNG đọc được khi chưa chọn thương hiệu, và thứ tự thật là **chọn thương hiệu trước → 2FA sau** (không phải ngược lại). Không có lỗ hổng: giữa hai bước, mọi API nghiệp vụ đều bị một trong hai gate chặn.\n- **Prefix `\u002Fapi\u002Fconfig\u002Fonboarding\u002F` được MIỄN gate** (DB trắng chưa có thương hiệu nào thì `switch-profile` vô dụng). Cửa này KHÔNG tự bảo vệ — handler tự kiểm super-user + bảng `company` rỗng **toàn bảng** (không `ScopedDB*`), tự đóng vĩnh viễn khi đã có company. `bootstrap` tạo company\u002Fbranch + gán active trong 1 transaction, tuần tự hoá bằng named lock kèm tên DB.\n- **Module**: `internal\u002Fmodules\u002Fwebapp\u002Fauth\u002Ftwofa` (service `pquerna\u002Fotp` + handler). FE: `login.ts` (challenge), `twofa-setup\u002F` (enroll\u002Fdisable + QR `ng-qrcode`), menu profile \"Bảo mật 2 lớp\".\n- seclog: `2fa_challenge`, `2fa_failed`, `2fa_enrolled`, `2fa_disabled`, `2fa_reset`.\n\n## Env\n```\nTOKEN_SECRET=\u003Csecret>           # CRM JWT key\nPARTNER_JWT_KEY=\u003Cdifferent>     # Client JWT key — PHẢI khác nhau\nTOTP_ENC_KEY=\u003Chex 64 chars>    # mã hóa TOTP secret 2FA (openssl rand -hex 32) — prod BẮT BUỘC\n```\n","# Auth & Workspace\n\n> reference\u002Findexeddb.md: IndexedDB master-data sync phía BE.\n\n\n## Tổng quan\n2 hệ thống auth hoàn toàn tách biệt: CRM (nhân viên) và Client (đối tác bên ngoài).\n\n## CRM Auth (Nhân viên)\n\n### Flow\n```\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogin   { username, password, device_fingerprint }\n  → BE: validates credentials\n  → BE: upsert user_device (device binding — xem §Device binding); đóng fingerprint vào refresh token\n  → BE: Set-Cookie: refresh_token=\u003Copaque>; HttpOnly; Secure; SameSite=None; Path=\u002Fapi\u002Fauth; Max-Age=...\n       (HTTP dev: SameSite=Lax + Secure=false — None yêu cầu Secure=true)\n  → Response body: { accessToken, expiresAt, refreshExpiresAt }   ← NO refreshToken in body\n  → FE: TokenService.setTokens(accessToken, expiresAt, refreshExpiresAt)\n       stores encrypted access_token (AES-GCM) + refresh_token_expires_at in localStorage\n       refresh_token cookie managed entirely by browser\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Frefresh-token   { device_fingerprint }\n  → Browser auto-sends refresh_token cookie (withCredentials: true, default in ApiService)\n  → BE: reads c.Cookie(\"refresh_token\"), verify device fingerprint theo DEVICE_BINDING_MODE, rotates, sets new cookie\n  → Response body: { accessToken, expiresAt, refreshExpiresAt }   ← NO refreshToken in body\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogout   ← PUBLIC route (không qua JWTAuth)\n  → Hoạt động cả khi access token đã hết hạn — bắt buộc để consume refresh cookie\n  → Prod: reject Sec-Fetch-Site: cross-site (403) — chống CSRF forced-logout; dev skip (FE\u002FBE khác site)\n  → BE: revoke access jti (best-effort nếu có Bearer, truyền c.ClientIP() cho IP binding) + consume refresh + clear cookie (Max-Age=-1)\n  → FE: TokenService.clearToken() wipes localStorage timestamps\n\nPOST \u002Fapi\u002Fcrm\u002Fauth\u002Flogout-all (authed)\n  → RevokeAllSessions + RevokeAllRefreshTokens — PHẢI revoke cả 2 (xem §Security)\n\nRequest → middleware.JWTAuth(tokenSvc) → decode JWT + check revoked:{jti} (Redis) → set userID\n       → middleware.AuthResponseHeaders() → loadUserScope() → set branchActiveId, branchIds, locale\n```\n\n### JWT Claims\n```go\ntype Claims struct {\n    UID uint `json:\"uid\"`\n}\n\u002F\u002F KHÔNG có branch_id\u002Fusername trong JWT — branch scope lấy từ UserScope\n\u002F\u002F (GetBranchActiveID). GetCompanyID đã xóa 2026-07-04, KHÔNG tái tạo. D15\u002Fstory-41:\n\u002F\u002F company đã xoá hoàn toàn khỏi hệ thống (1 thương hiệu\u002FDB) — không còn company_id\u002F\n\u002F\u002F companyActiveId\u002FcompanyIds ở bất kỳ tầng nào.\n```\n\n### Context getters\n- `GetUserID(c)` → uint\n- `GetBranchActiveID(c)` → uint\n- `GetBranchIDs(c)` → []uint\n\n### UserScope (cached Redis 5 phút)\n- Load từ `user` (driving) LEFT JOIN `user_profile` → branchActive_id, branchIds (JSON), locale, **status**\n- `InvalidateUserScope(userID)` — gọi khi user đổi branch\u002Fstatus\n- `branchActive_id` chỉ được tin khi còn ∈ `branchIds` (`effectiveActiveBranch`, 2026-10-20) — lệch ⇒ về chi nhánh đầu tiên được phép; `branchIds` rỗng = không giới hạn ⇒ giữ nguyên\n- `AuthResponseHeaders` abort 401 nếu `scope.Status != define.UserStatusActive` — enforce per-request, không chỉ lúc login\n- Cache cleared khi admin update user → request ngay sau re-read DB → enforce ngay không cần logout\n\n### Security\n- **Device limit thật = giới hạn refresh token** (2026-07-04): zset `rts:{uid}` (rid → expiry) index refresh token\u002Fuser; login vượt `TOKEN_MAX_SESSIONS` (default 3) → evict refresh của thiết bị ít-refresh-nhất (LRU) → thiết bị đó chết trong ≤ AccessTTL. Giới hạn access-session một mình VÔ NGHĨA (bị revoke thì silent-refresh sống lại)\n- **Logout dùng `ConsumeRefresh` KHÔNG `VerifyAndRotateRefresh`** — rotate lúc logout tạo orphan token chiếm 1 slot device đến hết RefreshTTL\n- **Rotation nguyên tử + phát hiện dùng lại (2026-10-20)**: `claimRefresh` (Lua: DEL `rt` + ghi `rtused:{rid}` = uid:hash:unix) — 2 request cùng token chỉ 1 cái thắng; thua ⇒ `ErrRefreshRaced` ⇒ handler trả **409, KHÔNG xoá cookie** (FE coi là lỗi thoáng qua). Token đã xoay vòng bị trình lại sau `refreshReuseGrace` (30s) ⇒ `ErrRefreshReused`: thu hồi MỌI refresh + access của user, seclog `refresh_reuse_detected`\n- Token revocation (jti blacklist), IP binding (optional)\n- **Revocation enforce tại `JWTAuth(tokenSvc)`** (2026-07-04): check `revoked:{jti}` mỗi request — fail-open khi Redis lỗi\n- **TTL blacklist = phần đời còn lại của token** (lấy từ `sess:{uid}` zset score) — TTL cố định ngắn hơn AccessTTL sẽ mở resurrection window (token revoke xong sống lại)\n- **Revoke access PHẢI kèm revoke refresh (CRITICAL)**: chỉ `RevokeAllSessions` → thiết bị khác 401 thoáng qua rồi silent-refresh lấy token mới → revoke vô dụng. LUÔN gọi cặp `RevokeAllSessions(uid)` + `RevokeAllRefreshTokens(uid)` (logout-all, đổi mật khẩu, đổi role\u002Fstatus)\n- refresh_token: HttpOnly Secure SameSite=None cookie (Lax trên HTTP dev), Path=\u002Fapi\u002Fauth (Cấp 2, implemented 2026-04-26)\n- access_token: AES-GCM encrypted at rest in localStorage (Cấp 1)\n- Login rate limit: 10 req\u002FIP\u002F5min via Redis INCR\n- **Trusted proxies (CRITICAL)**: `r.SetTrustedProxies(cfg.TrustedProxies)` — gin default tin MỌI proxy → `ClientIP()` spoof được qua X-Forwarded-For. Set `TRUSTED_PROXIES` đúng khi sau reverse proxy, nếu không rate-limit\u002FIP-binding\u002Fseclog đều dựa IP giả. Chiều ngược lại cũng chết: sau nginx mà `.env` TRỐNG ⇒ `ClientIP()` = 127.0.0.1 cho MỌI request ⇒ rate limit key theo IP thành 1 bucket toàn cục (livechat 2026-09-03). Rate limit mới theo IP phải key thêm tenant\u002Fsite và ghi tiền điều kiện này\n- **IP binding** (`TOKEN_IP_BINDING=true`): `buildAccessJWT` nhét `ipHash=sha256(ip)` vào access token; `JWTAuth` so với `sha256(ClientIP)` mỗi request → 401 khi lệch. User di động đổi IP → 401 → interceptor silent-refresh → token rebind IP mới (không logout). Opt-in, default off\n- **Token khác access (challenge 2FA, one-time...) PHẢI ký key riêng** (vd `sha256(Secret+\":purpose\")`) — `JWTAuth` verify chữ ký + expiry + `revoked:{jti}` + issuer\u002Faudience (`token.ClaimsMatchTenant`, issuer\u002Faud chứa DB_NAME từ 2026-10-18 — chặn token chéo khách) nhưng KHÔNG phân biệt mục đích token; ký chung `TOKEN_SECRET` → token đó dùng được làm Bearer access token (challenge không có jti → bỏ qua cả revocation check) = bypass. Test guard: `pkg\u002Ftoken\u002Fchallenge_isolation_test.go`\n\n### IP allowlist nhân viên (Hướng 2A — khác IP binding)\n- **`IP_ALLOWLIST_MODE=off|log|enforce`** (`SetIPAllowlistMode` ở boot). Chặn nhân viên theo `allowed_ips` (IP\u002FCIDR) — KHÁC IP binding (bind token vào 1 IP): allowlist là danh sách IP\u002Fdải được phép\n- **Cột `allowed_ips` JSON** trên `business_profile` (D15\u002Fstory-62, qua `pkg\u002Fbrand`; trước đây trên `company`) + `user`. **Effective = user override > hồ sơ thương hiệu** (user non-empty thắng; rỗng cả hai = không giới hạn). Load vào `UserScope.AllowedIPs` (cache 5 phút → đổi allowed_ips propagate ≤5 phút hoặc `InvalidateUserScope`)\n- **Enforce trong `AuthResponseHeaders`** (sau khi set branchActiveId): `helpers.IPInAllowlist(ClientIP, list)` (exact IP + CIDR). enforce → 403 `ip_not_allowed`; log → chỉ seclog (throttle 1 lần\u002F(user,ip)\u002F5phút chống flood)\n- **Super-user LUÔN bypass** (`UserScope.IsSuper` = EXISTS role trong `define.SuperRoles`) — cấu hình sai không tự khóa admin\n- **PHỤ THUỘC trusted proxies** — ClientIP phải thật\n- FE: field `allowed_ips` (textarea IP\u002FCIDR mỗi dòng) trong form hồ sơ doanh nghiệp (`authBusinessProfile`) + user; cảnh báo lockout. `helpers.IPInAllowlist` cũng nâng `checkPartnerIP` (partner_auth) từ exact match lên CIDR\n- Test: `pkg\u002Fhelpers\u002Fipmatch_test.go` (exact\u002FCIDR\u002FIPv6\u002Fedge)\n\n### Device binding (fingerprint)\n- **Bảng `user_device`** (auth-level, KHÔNG company_id): `(user_id, fingerprint)` UNIQUE, status trusted\u002Fpending\u002Frevoked. Nền cho 2FA\u002FWebAuthn per-device sau này\n- FE gửi `device_fingerprint` (SHA-256 base64url, `fingerprint.ts`, KHÔNG gồm screen — đổi khi cắm màn ngoài) ở login + refresh\n- Fingerprint đóng vào refresh token value: `rt:{uid}:{rid}` = `\u003Chash>` (legacy) hoặc `\u003Chash>:fp:\u003Cfingerprint>`\n- **`DEVICE_BINDING_MODE=off|log|enforce`**: enforce → refresh với fp lệch storedFP = 401; log → chỉ seclog `refresh_fp_mismatch` (đo tỷ lệ trước khi bật enforce); token legacy (không fp) luôn bỏ qua, tự nâng cấp ở rotation kế\n- API self-service: `GET \u002Fauth\u002Fdevices`, `POST \u002Fauth\u002Fdevices\u002F:id\u002Frevoke` — CHỈ thiết bị của chính user (`GetOwned` scope theo user_id); FE ở menu profile\n- **Upsert throttle**: `Dao.Upsert(..., minTouchInterval)` — login truyền 0 (luôn ghi), refresh truyền 1h (bỏ qua write nếu last_seen còn mới) → giảm tải hot-path refresh\n- **Dọn nền**: `user_device_cleanup` (`helpers.RunBackground` ở bootstrap, 24h) xoá device `last_seen` quá `define.UserDeviceStaleDays` (90) — chống phình bảng\n- **`pkg\u002Fseclog`**: structured security events (`sec_event` field) — login_success\u002Ffailed, new_device, refresh_fp_mismatch, access_ip_mismatch, device_evicted\u002Frevoked, revoked_token_reused, ip_not_allowed. **`Event` no-op khi `logger.L` nil** (test\u002Fboot sớm)\n- **Test**: `pkg\u002Ftoken\u002Ftoken_device_test.go` (miniredis) — fingerprint binding enforce\u002Flog, legacy upgrade, device limit cap, ConsumeRefresh, RevokeRefreshByFingerprint, ActiveFingerprints, revocation blacklist\n\n### Audit log (Hướng 2B — persist seclog vào DB)\n- **`seclog.InitSink(buf, flush)`** (wire ở bootstrap): `Event` đẩy `Entry` vào buffered channel → goroutine batch-INSERT (`CreateInBatches`). **Non-blocking**: channel đầy → drop + `seclog.Dropped()` đếm, KHÔNG chặn request. Flush do module audit cấp (seclog không import DB\u002FDAO)\n- `Event` promote key `user_id`\u002F`username` sang cột, còn lại vào `detail` JSON.\n- **Bảng `security_audit_log`** (auth-level, TOÀN DB — D15\u002Fstory-58 đã bỏ hẳn cột `company_id`, 1 thương hiệu\u002FDB nên không cần scope company nữa): index `(user_id,created_at)`, `(event,created_at)`\n- **API `GET \u002Fauth\u002Faudit-log`**: super-user only (`RbacSvc.IsSuperUser` — config module không có perm middleware), KHÔNG scope gì thêm — xem hết log của DB. paginate + filter `user_id \u002F event (1) \u002F events (nhóm, phẩy) \u002F from \u002F to`.\n- **Dọn nền** `security_audit_cleanup` (`helpers.RunBackground`, 24h) xoá quá `define.AuditRetentionDays` (180)\n- **FE**: trang `config\u002Fsecurity-audit` (audit tổng) + `log\u002Flogin` (lịch sử đăng nhập, module history) — cả 2 super-user, p-table lazy. `authService.getAuditLog()`\n- **Test**: `pkg\u002Fseclog\u002Fseclog_test.go` — sink batch flush + field promotion + nil-logger no-panic\n\n### Login history (chi tiết kiểm soát đăng nhập)\n- `login_failed` mang `reason` trong detail: `user_not_found | bad_password | inactive | rate_limited`. **Distinction chỉ ở audit (super-user), response luôn generic `login_failed`** — chống user enumeration\n- Login query bỏ `WHERE status=Active` → query theo username rồi check status (phân biệt not_found vs inactive). Rate-limit (429) giờ cũng ghi `login_failed reason=rate_limited`\n- `login_failed` (user thật) + `logout` resolve `companyActive_id` sớm → hiện trong view theo company (trước đây NULL → vô hình)\n- `logout` event ghi khi decode được bearer (user_id + company). Login là public route → resolve company qua query user_profile\n- FE `log\u002Flogin` (`modules\u002Fhistory\u002Flogin`): gộp login_success\u002Ffailed\u002Flogout\u002Fnew_device\u002Flogin_no_fingerprint qua `?events=`; cột reason + device. Menu gate `isSuperUser()` (không gắn permission để non-super khỏi thấy rồi 403)\n\n### FE TokenService API (post Cấp-2 refactor)\n```typescript\n\u002F\u002F ✅ Current API\ntokenService.setTokens(accessToken: string, expiresAt?: number, refreshExpiresAt?: number)\ntokenService.getAccessToken(): string | null   \u002F\u002F decrypts AES-GCM from localStorage\ntokenService.hasValidToken: boolean\ntokenService.hasValidRefreshSession(): boolean  \u002F\u002F checks refresh_token_expires_at timestamp only\ntokenService.isRefreshTokenExpired(): boolean\ntokenService.clearToken()                       \u002F\u002F clears localStorage, cookie cleared by BE on logout\n\n\u002F\u002F ❌ REMOVED — do NOT use\n\u002F\u002F tokenService.getRefreshToken()     → no longer exists (cookie is HttpOnly, JS cannot read)\n\u002F\u002F tokenService.setTokens(a, b, c, d) → 4-arg form removed\n```\n\n### doRefresh — clearToken chỉ khi 401\u002F403 (CRITICAL)\n\n`doRefresh()` catch block **không được gọi `clearToken()` cho mọi lỗi**. Chỉ clear khi BE xác nhận token thực sự invalid:\n\n```typescript\n\u002F\u002F ✅ CORRECT (hiện tại)\n} catch (err: any) {\n    const status = (err as any)?.status;\n    if (status === 401 || status === 403) {\n        this.clearToken();  \u002F\u002F token thực sự hết hạn ở Redis\n    }\n    return false;  \u002F\u002F network\u002F5xx: không xóa refresh_token_expires_at\n}\n\n\u002F\u002F ❌ NEVER — clearToken với mọi lỗi\n} catch (err: any) {\n    this.clearToken();  \u002F\u002F lỗi mạng thoáng qua xóa refresh_token_expires_at\n    return false;       \u002F\u002F → isRefreshTokenExpired() = true → \"session expired\" giả\n}\n```\n\n**Lý do:** `clearToken()` xóa `refresh_token_expires_at` khỏi localStorage. `isRefreshTokenExpired()` trả `true` khi key bị thiếu. Nếu auto-refresh timer gặp lỗi mạng và clear session, điều hướng kế tiếp sẽ báo \"Refresh session expired\" dù refresh token trong Redis vẫn còn hiệu lực.\n\n**Phân biệt 3 path:**\n- **auto-refresh timer** → network error: `doRefresh()` retry backoff (status 0\u002F5xx) rồi mới trả false, không clearToken → state giữ nguyên\n- **API request → 401 → refresh fail (interceptor)**: chỉ clearToken khi `hasValidRefreshSession()` = false; transient → propagate error, không logout\n- **authGuard → trySilentRefresh fail**: transient (session còn) → cho điều hướng tiếp, interceptor refresh lại ở 401 kế tiếp; chỉ redirect login khi session hết\n\nChi tiết retry\u002Fdiscriminator: `frontend\u002Fskill\u002Fskills\u002Fhandling-fe-auth-and-i18n\u002Freference\u002Ffe-patterns-gotchas-auth.md` §\"refresh fail ≠ logout\"\n\n### authGuard (post Cấp-2)\nFE cannot read the refresh_token cookie. Guard checks expiry via timestamp only:\n```typescript\n\u002F\u002F ✅ Correct check\nif (tokenService.isRefreshTokenExpired()) { redirect to \u002Flogin }\n\n\u002F\u002F ❌ Old pattern — removed\n\u002F\u002F const rt = tokenService.getRefreshToken(); if (!rt) { redirect }\n```\n\n### authInitialized — race với withEnabledBlockingInitialNavigation (CRITICAL)\n\n`withEnabledBlockingInitialNavigation()` đăng ký APP_INITIALIZER riêng chạy **song song** với `initializeAuth` — không phải sau. Khi access token còn hạn: `initialize()` (crypto ~1ms) xong trước → `hasValidToken=true` → `authGuard` pass ngay → `requirePerm` chạy synchronous — nhưng IDB read trong `restoreAuthUser()` (~10–50ms) chưa xong → `userPermissions = Set()` rỗng → redirect `\u002Fauth\u002Faccessdenied` trên mọi deep route khi F5.\n\nXảy ra khi: auth storage dùng IndexedDB (async) + SW cache chunk (fast import) — cả hai cộng lại làm race đủ lớn để xảy ra deterministic.\n\n**Fix pattern (đã implement):**\n```typescript\n\u002F\u002F auth.state.ts\nexport const authInitialized = signal(false);\n\n\u002F\u002F auth.service.ts — restoreAuthUser()\ntry { \u002F* ... restore logic ... *\u002F } finally { authInitialized.set(true); }\n\n\u002F\u002F authGuard.ts — waitInitialized$ tạo trong injection context (toObservable không gọi được trong switchMap)\nconst waitInitialized$ = authInitialized()\n  ? of(true as const)\n  : toObservable(authInitialized).pipe(filter(Boolean), take(1), map(() => true as const));\n\u002F\u002F Dùng ở CẢ 2 path: hasValidToken = true VÀ silent-refresh thành công\n\u002F\u002F (refresh xong nhưng restoreAuthUser Case 1a còn đang fetch \u002Fme → phải đợi)\n```\n\nOverhead: chỉ xảy ra lần đầu tiên (F5 với token còn hạn). Mọi navigation sau đó `authInitialized()` đã `true` → zero overhead.\n\n### withCredentials\n`ApiService.createHttpOptions()` sets `withCredentials: true` by default — all requests\nautomatically include cookies. No need to pass it explicitly at call sites.\n\n### Cấp 3 (NOT implemented — deferred)\nMoving access_token to HttpOnly cookie would trade XSS risk for CSRF risk (no CSRF protection in place).\nTriggers to re-evaluate: SOC2 Type II audit, PCI-DSS scope expansion, or pen-test finding.\n\n## (đã bỏ, D15\u002FCRM standalone) Client Auth (Đối tác — Zalo Mini App, website)\n\nModule `internal\u002Fmodules\u002Fclient\u002F` (PartnerAuth, `partners.company_id`\u002F`companyActiveId`,\n`GetPartnerCompanyID`) **KHÔNG còn tồn tại trong repo CRM standalone này** — verify 2026-09-28:\n`internal\u002Fmodules\u002F` chỉ còn `webapp\u002F` (không có `client\u002F`\u002F`mobile\u002F`\u002F`public\u002F`), không có\n`internal\u002Fmiddleware\u002Fpartner_auth.go`. Nội dung dưới đây (flow OAuth partner, JWT `PartnerClaims`,\n`GetPartnerID`\u002F`GetPartnerCompanyID`) mô tả kiến trúc ERP cũ trước khi tách CRM standalone — giữ\nlàm lịch sử, KHÔNG áp dụng. Skill `building-client-and-sync-apis` đã xoá khỏi CRM standalone.\n\n## Response format khác nhau\n\n### CRM — `pkg\u002Fresponse\u002Fresponse.go`\n- `Data(c, data)`, `DataWithMessage(c, data, msg)`, `Validate(c, msg)`, `NotFound(c)`, `ServerError(c, err)`\n\n### Client — `pkg\u002Fresponse\u002Fclient.go`\n- `ClientSuccess(c, data, msg)` → `{success: true, code: 200, message, data, timestamp}`\n- `ClientError(c, msg, code)` → `{success: false, code, message, data: null, timestamp}`\n- `ClientValidate(c, msg)` → `{success: false, code: 422, message, data: null, timestamp}`\n\n## Router\n```go\napi := r.Group(\"\u002Fapi\")\napi.POST(\"\u002Fclient\u002Foauth\u002Ftoken\", h.OAuthToken)                          \u002F\u002F public\n\u002F\u002F CRM public: \u002Fauth\u002Flogin, \u002Fauth\u002Frefresh-token, \u002Fauth\u002Flogout (xem Flow)\nauthed := api.Group(\"\", middleware.JWTAuth(d.TokenSvc), middleware.AuthResponseHeaders(db, d.Cache)) \u002F\u002F CRM\nclientGroup := api.Group(\"\u002Fclient\", middleware.PartnerAuth())           \u002F\u002F Client\n```\n\n### 2FA — TOTP (Hướng 3)\n- **Login 2 bước**: `POST \u002Fauth\u002Flogin` → nếu user bật 2FA + thiết bị chưa trusted → trả `{requires_2fa, challenge_token}` (CHƯA cấp token). `POST \u002Fauth\u002Flogin\u002F2fa {challenge_token, code, remember_device}` → verify TOTP\u002Fbackup → cấp token. `challenge_token` = JWT 5 phút aud=`2fa-challenge` (proof đã qua password).\n- **Device-aware skip**: bỏ qua 2FA CHỈ khi `user_device.totp_trusted_until > now` **VÀ** client trình đúng token remember-device (cookie HttpOnly `device_trust_\u003CuserID>` path `\u002Fapi\u002Fauth`; mobile transport: body `device_trust_token`) khớp `user_device.totp_trust_hash` (SHA-256, so constant-time), thiết bị chưa revoked. `remember_device` ⇒ server sinh token ngẫu nhiên 32 byte, hạn = now + `business_profile.totp_trust_days` (0 = luôn hỏi, cho máy dùng chung). ⚠ KHÔNG bao giờ tin riêng `device_fingerprint` — client tự tính từ UA\u002Fngôn ngữ\u002Fmúi giờ\u002FCPU, đoán được (lỗ hổng vá 2026-10-20). Revoke thiết bị xoá trust.\n- **Secret mã hóa** AES-GCM bằng `TOTP_ENC_KEY` (env riêng); backup codes hash sha256, 1 lần. Rate-limit verify 5 lần\u002F5 phút.\n- **Endpoints** (authed): `\u002Fauth\u002F2fa\u002Fstatus|setup|verify-setup|disable`, `\u002Fauth\u002F2fa\u002Freset\u002F:userId` (super-user).\n- **Policy per-company + per-role**: `company.require_2fa=1` HOẶC role ∈ `company.require_2fa_roles`. Bắt buộc mà chưa enroll → `UserScope.MustSetup2FA=true` → **AuthResponseHeaders chặn mọi API (trừ `\u002Fauth\u002F2fa\u002F*`, `\u002Fauth\u002Fme`, `\u002Fauth\u002Fpermission`) với 403 code=`2fa_setup_required`** → FE interceptor redirect `\u002F2fa-setup`.\n- **`AuthResponseHeaders` chạy các gate nối tiếp sau khi set `branchActiveId`\u002F`branchIds`**: 2FA (`code=2fa_setup_required`, chặn mọi API trừ endpoint setup 2FA + `\u002Fme`) rồi IP allowlist (`ip_not_allowed`, mode `enforce`). ⚠ **(đã bỏ, D15)** Trước đây còn gate thứ 3 chặn khi `GetCompanyActiveID(c)==0` (`code=company_active_required`, FE redirect `\u002Fchoose-company`) — đã xoá cùng company (1 thương hiệu\u002FDB không cần chọn thương hiệu active).\n- **Hai gate loại trừ nhau về cấu trúc**: `require_2fa`\u002F`require_2fa_roles` lấy qua `LEFT JOIN company c ON c.id = p.companyActive_id` ⇒ `companyActive_id` NULL thì join rỗng ⇒ `MustSetup2FA` **luôn false**. Nghĩa là chính sách 2FA theo thương hiệu KHÔNG đọc được khi chưa chọn thương hiệu, và thứ tự thật là **chọn thương hiệu trước → 2FA sau** (không phải ngược lại). Không có lỗ hổng: giữa hai bước, mọi API nghiệp vụ đều bị một trong hai gate chặn.\n- **Prefix `\u002Fapi\u002Fconfig\u002Fonboarding\u002F` được MIỄN gate** (DB trắng chưa có thương hiệu nào thì `switch-profile` vô dụng). Cửa này KHÔNG tự bảo vệ — handler tự kiểm super-user + bảng `company` rỗng **toàn bảng** (không `ScopedDB*`), tự đóng vĩnh viễn khi đã có company. `bootstrap` tạo company\u002Fbranch + gán active trong 1 transaction, tuần tự hoá bằng named lock kèm tên DB.\n- **Module**: `internal\u002Fmodules\u002Fwebapp\u002Fauth\u002Ftwofa` (service `pquerna\u002Fotp` + handler). FE: `login.ts` (challenge), `twofa-setup\u002F` (enroll\u002Fdisable + QR `ng-qrcode`), menu profile \"Bảo mật 2 lớp\".\n- seclog: `2fa_challenge`, `2fa_failed`, `2fa_enrolled`, `2fa_disabled`, `2fa_reset`.\n\n## Env\n```\nTOKEN_SECRET=\u003Csecret>           # CRM JWT key\nPARTNER_JWT_KEY=\u003Cdifferent>     # Client JWT key — PHẢI khác nhau\nTOTP_ENC_KEY=\u003Chex 64 chars>    # mã hóa TOTP secret 2FA (openssl rand -hex 32) — prod BẮT BUỘC\n```\n",{"name":5,"description":7},"main","ea9f5ed9bd4eaf32e9489bcbe9603955c1462a63","skill\u002Fskills\u002Fhandling-auth-and-workspace",20,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm","https:\u002F\u002Fgithub.com\u002Fcluvix","cluvixsolutions.com","Cluvix Solutions is a technology outsourcing company specializing in custom software development for growing businesses. We build end-to-end enterprise solution","2026-11-02 19:55:39",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add cluvix\u002Fcluvix-crm --skill handling-auth-and-workspace",{"tool":39,"command":40},"bunx","bunx skills add cluvix\u002Fcluvix-crm --skill handling-auth-and-workspace",{"tool":42,"command":43},"pnpm","pnpm dlx skills add cluvix\u002Fcluvix-crm --skill handling-auth-and-workspace","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fhandling-auth-and-workspace\u002FSKILL.md",true,[47],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"reference\u002Findexeddb.md","REFERENCE","参考文档",6417,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fhandling-auth-and-workspace\u002Freference\u002Findexeddb.md",[54,61,68,75,82,89],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7F47FCP2MP548SWCP0BJ6B1","writing-mysql-migrations","Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD\u002FDROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới\u002Fcũ, và luật CẤM tuyệt đối test\u002Fmigrate chạm DB dev\u002Fprod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột\u002FFK, backfill dữ liệu, hoặc trước khi chạy `cmd\u002Fmigrate`\u002Fintegration test đụng tới database — kể cả migration chỉ 1-2 dòng.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7F475VEPATD0D8KP8V2HHYV","writing-backend-resources","Hướng dẫn quy trình 6 bước TẠO MỚI resource backend Go (entity, dao, repository, service, handler, router, DTO, module layout) cho ERP Cluvix. Dùng skill này TRƯỚC KHI tạo resource CRUD mới hoặc module mới trong internal\u002Fmodules\u002F, khi cần biết Handler DI\u002FRouter\u002FRepository Reader\u002FDTO pattern chuẩn, hoặc trước khi đụng module service (status filter 2 tầng, cascade, optimistic lock). KHÔNG dùng skill này để debug\u002Fsửa query đang sai — xem debugging-backend-queries cho việc đó.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-backend-resources\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7F46Z6MMBQ0AP2ZA5HW5R4X","working-on-ops","Hướng dẫn nghiệp vụ dashboard CRM, export, và import dữ liệu trong module ops của backend Cluvix. Dùng skill này KHI đụng report\u002Fdashboard CRM, thêm cột export (`?columns=`), hoặc import khách hàng (migration onboard SAAS client) — đọc trước khi đổi bất kỳ hành vi nào trong các luồng này.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-ops\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7F46PPNCK976F4SYWVHXAHC","working-on-hr","Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role\u002FRBAC, đổi\u002Fđặt lại mật khẩu, import user. Dùng skill này KHI làm feature\u002Fsửa bug đụng module hr (chỉ còn `hr\u002Fuser`) — trước khi đọc code.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-hr\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7F468VEARVSRRYBJ8VHJSJ3","working-on-crm","Quy tắc và pattern nghiệp vụ CRM Cluvix: khách hàng, lịch hẹn, liệu trình, đơn hàng, thanh toán. Dùng skill này KHI làm feature\u002Fsửa bug đụng module crm (customer, appointment, order, treatment, payment) — trước khi đọc code, để tránh phá vỡ business rule đã có (tái khai thác, customer status IN(...)).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-crm\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7F45Y15Q0CBEP06CFF2AAEY","working-on-config","Quy tắc và pattern nghiệp vụ Config Cluvix còn sống trong CRM standalone: mẫu in (print_template), control field trong bảng (control_field_in_table), IndexedDB sync của config. Dùng skill này KHI làm feature\u002Fsửa bug đụng các module đó — trước khi đọc code. Tổng đài\u002Fchữ ký số\u002FAI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-config\u002FSKILL.md",[],[]]