@nalvietnam/avatar-cli 3.19.1 → 3.19.3

package/README.md

@@ -1,14 +1,16 @@
 # @nalvietnam/avatar-cli
 
-AI harness CLI for NAL Vietnam engineering. Implements the Avatar architecture defined in [`avatar-cli-implementation_4.html`](../init-doc/avatar-cli-implementation_4.html).
+AI harness CLI for NAL Vietnam engineering. Kiến trúc v3 (multi-repo workspace + pack tarball qua Supabase) mô tả trong [`docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html`](docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html).
 
 ## v3 — Trạng thái hiện tại
 
 avatar-cli v3 mang 3 thay đổi lớn:
 
-- **Pack distribution qua Supabase tarball** — pack tải dưới dạng tarball ký số từ
-  edge function `get-pack` (signed URL, xác thực `id_token` Google NAL), giải nén
-  vào `.claude/pack/`. Không còn git submodule.
+- **Pack distribution qua Supabase tarball** — pack tải dưới dạng tarball từ edge
+  function `get-pack` (signed URL, xác thực `id_token` Google NAL), giải nén vào
+  `.claude/pack/`. Toàn vẹn kiểm bằng **SHA-256 soft-verify**: CLI so digest tarball
+  tải về với digest backend trả — backend chưa trả digest thì CLI **cảnh báo rồi bỏ
+  qua verify, pack vẫn cài** (không phải chữ ký số, không chặn cài). Không còn git submodule.
 - **Multi-repo workspace** — 1 workspace chứa nhiều repo code trong `src/<name>`
   (thêm bằng `avatar add repo`).
 - **Google SSO login** — `avatar login` (workspace `@nal.vn` / `nal-software.com`).
@@ -34,7 +36,7 @@ npm install -g @nalvietnam/avatar-cli
 
 ```bash
 avatar --help                    # liệt kê toàn bộ 20 commands
-avatar --version                 # 3.17.0
+avatar --version                 # ví dụ output — nguồn sự thật là package.json
 
 # Lần đầu — đăng nhập Google SSO (workspace @nal.vn / nal-software.com)
 avatar login
@@ -105,14 +107,28 @@ avatar-cli/
 
 ## Google OAuth setup
 
-Client ID và Client Secret được hardcode trong `src/lib/google-oauth-device-flow.ts`.
+**Client Secret KHÔNG nằm trong CLI.** Từ **v3.16.0**, mọi call OAuth (device code / poll /
+refresh / revoke) đi qua Edge Function `auth-device` trên `avatar-supabase`; secret lưu ở
+Supabase secrets `NAL_GOOGLE_CLIENT_SECRET`, CLI không bao giờ thấy nó.
+
+Thứ **có** trong `src/lib/google-oauth-device-flow.ts` là **Client ID** — đây là public
+identifier, không phải secret. CLI giữ nó để verify claim `aud` của `id_token`.
 
 OAuth Client tạo trong Google Cloud Console:
 - Project: `avatar-cli`
 - Application type: **TV and Limited Input devices**
 - Hosted domain: `nal.vn` và `nal-software.com` (2 Google Workspace riêng biệt, đều được chấp nhận — xem `ALLOWED_HOSTED_DOMAINS`)
 
-Rotate secret: Console → APIs & Services → Credentials → OAuth client → Reset Secret → cập nhật `GOOGLE_CLIENT_SECRET` trong source.
+**Rotate secret** = việc server-side, KHÔNG cần release CLI:
+
+```bash
+# Console → APIs & Services → Credentials → OAuth client → Reset Secret
+supabase secrets set NAL_GOOGLE_CLIENT_SECRET=<secret-mới>
+```
+
+Nếu đổi hẳn OAuth client trên Console: cập nhật Client ID trong
+`src/lib/google-oauth-device-flow.ts` **và** cả 2 secrets `NAL_GOOGLE_CLIENT_ID` /
+`NAL_GOOGLE_CLIENT_SECRET` phía Supabase.
 
 ## Dev workflow
 
@@ -125,6 +141,6 @@ npm run build                    # production bundle vào dist/
 
 ## Liên quan
 
-- Blueprint kiến trúc: [`../init-doc/avatar-blueprint-v1_10.html`](../init-doc/avatar-blueprint-v1_10.html)
-- Implementation spec: [`../init-doc/avatar-cli-implementation_4.html`](../init-doc/avatar-cli-implementation_4.html)
-- Knowledge pack: [`../team-ai-pack/`](../team-ai-pack/) — tải dưới dạng tarball ký số từ Supabase edge function `get-pack` (signed URL, xác thực `id_token` Google NAL) khi `avatar init` / `avatar sync`, giải nén vào `.claude/pack/`
+- Kiến trúc v3 (multi-repo + pack distribution): [`docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html`](docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html)
+- Tham chiếu lệnh: [`docs/avatar-cli-commands-reference.html`](docs/avatar-cli-commands-reference.html)
+- Knowledge pack: [`../team-ai-pack/`](../team-ai-pack/) — tải dưới dạng tarball từ Supabase edge function `get-pack` (signed URL, xác thực `id_token` Google NAL, SHA-256 soft-verify) khi `avatar init` / `avatar sync`, giải nén vào `.claude/pack/`