ai-developer-skill-os 9.1.1 → 9.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/.agents/AGENTS.md +139 -42
  2. package/.agents/DEV_PROFILE.md +95 -0
  3. package/.agents/registry/capability-graph.yml +171 -334
  4. package/.agents/registry/graph.json +52 -18
  5. package/.agents/registry/index.yaml +66 -12
  6. package/.agents/registry/skills-index.yml +204 -447
  7. package/.agents/rules/coding.md +23 -0
  8. package/.agents/rules/global.md +44 -30
  9. package/.agents/skills/_template/SKILL.md +2 -300
  10. package/.agents/skills/qk-access-policy/SKILL.md +98 -393
  11. package/.agents/skills/qk-agent-observability/SKILL.md +3 -359
  12. package/.agents/skills/qk-ai-builder/SKILL.md +132 -485
  13. package/.agents/skills/qk-api-consumer/SKILL.md +256 -0
  14. package/.agents/skills/qk-api-consumer/capability.yaml +21 -0
  15. package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +29 -0
  16. package/.agents/skills/qk-api-lifecycle/SKILL.md +133 -376
  17. package/.agents/skills/qk-bug-resolution/SKILL.md +128 -481
  18. package/.agents/skills/qk-code-review/SKILL.md +142 -340
  19. package/.agents/skills/qk-context-loader/SKILL.md +99 -391
  20. package/.agents/skills/qk-data-engineer/SKILL.md +253 -0
  21. package/.agents/skills/qk-data-lifecycle/SKILL.md +89 -408
  22. package/.agents/skills/qk-db-optimizer/SKILL.md +102 -408
  23. package/.agents/skills/qk-design-system-engineering/SKILL.md +76 -381
  24. package/.agents/skills/qk-devops-platform/SKILL.md +77 -383
  25. package/.agents/skills/qk-docs/SKILL.md +88 -414
  26. package/.agents/skills/qk-engineering-standard/SKILL.md +4 -508
  27. package/.agents/skills/qk-fe-api-integration/SKILL.md +343 -263
  28. package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +29 -29
  29. package/.agents/skills/qk-feature-delivery/SKILL.md +137 -365
  30. package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
  31. package/.agents/skills/qk-frontend-architecture/SKILL.md +5 -399
  32. package/.agents/skills/qk-help/evals/scorecard.yaml +13 -13
  33. package/.agents/skills/qk-orchestrator/SKILL.md +63 -422
  34. package/.agents/skills/qk-orchestrator/references/routing-table.md +10 -14
  35. package/.agents/skills/qk-product-specification/SKILL.md +70 -399
  36. package/.agents/skills/qk-production-release/SKILL.md +80 -457
  37. package/.agents/skills/qk-project-audit/SKILL.md +174 -0
  38. package/.agents/skills/qk-project-bootstrap/SKILL.md +244 -392
  39. package/.agents/skills/qk-project-health/SKILL.md +97 -416
  40. package/.agents/skills/qk-project-memory/SKILL.md +76 -21
  41. package/.agents/skills/qk-refactor/SKILL.md +167 -304
  42. package/.agents/skills/qk-security-audit/SKILL.md +141 -383
  43. package/.agents/skills/qk-security-audit/capability.yaml +1 -2
  44. package/.agents/skills/qk-system-evolution/SKILL.md +343 -263
  45. package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +26 -26
  46. package/.agents/skills/qk-test-engineering/SKILL.md +119 -429
  47. package/.agents/skills/qk-ui-audit/SKILL.md +73 -457
  48. package/.agents/skills/qk-ui-builder/SKILL.md +521 -482
  49. package/.agents/skills/qk-ui-system-builder/SKILL.md +68 -434
  50. package/.agents/skills/qk-upgrade/SKILL.md +301 -0
  51. package/.agents/skills/qk-upgrade/capability.yaml +24 -0
  52. package/.agents/skills/qk-upgrade/evals/scorecard.yaml +26 -0
  53. package/.agents/skills/qk-validation-gate/SKILL.md +4 -523
  54. package/.agents/skills/qk-web-quality-gate/SKILL.md +85 -383
  55. package/.agents/workflows/bug-resolution.yml +6 -6
  56. package/.agents/workflows/context-discovery.yml +94 -0
  57. package/.agents/workflows/feature-delivery.yml +8 -4
  58. package/.agents/workflows/refactor.yml +6 -3
  59. package/.agents/workflows/shared/quality-gate.yml +94 -0
  60. package/.agents/workflows/skin-governance.yml +115 -0
  61. package/README.md +152 -67
  62. package/package.json +2 -2
  63. package/tooling/build-registry.js +30 -8
@@ -1,9 +1,9 @@
1
- ---
1
+ ---
2
2
  # ── Identity ───────────────────────────────────────────────
3
3
  name: qk-access-policy
4
- version: 9.1.0
4
+ version: 9.2.0
5
5
  status: stable
6
- description: "Quản lý RBAC, ABAC — định nghĩa role matrix trước, implement middleware sau."
6
+ description: "Quản lý và thiết lập chính sách phân quyền RBAC/ABAC, định nghĩa permission matrix, sinh auth middleware bảo vệ endpoint. Dùng skill này khi user nhắc đến: phân quyền, rbac, abac, auth middleware, access control, bảo mật api, quyền truy cập, role permission — kể cả khi chỉ nói 'chỉ admin mới được xóa bài viết'."
7
7
  platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
8
8
 
9
9
  # ── V9: Classification ─────────────────────────────────────
@@ -21,11 +21,16 @@ complexity:
21
21
  has_external_dependency: true
22
22
  has_breaking_change: false
23
23
 
24
- triggers:
25
- - "cấu hình rbac"
26
- - "phân quyền"
27
- - "bảo mật api"
28
- - "auth middleware"
24
+ triggers:
25
+ - "phân quyền"
26
+ - "rbac"
27
+ - "abac"
28
+ - "auth middleware"
29
+ - "access control"
30
+ - "bảo mật api"
31
+ - "quyền truy cập"
32
+ - "role permission"
33
+
29
34
 
30
35
  # ── V8: References ─────────────────────────────────────────
31
36
  workflow: feature-delivery
@@ -33,6 +38,7 @@ workflow: feature-delivery
33
38
  rules:
34
39
  - global
35
40
  - coding
41
+ - security
36
42
 
37
43
  tools:
38
44
  - filesystem
@@ -40,11 +46,13 @@ tools:
40
46
 
41
47
  related_skills:
42
48
  - qk-api-lifecycle
49
+ - qk-security-audit
43
50
 
44
51
  knowledge_scope:
45
52
  owns:
46
53
  - security-policy
47
54
  - role-matrix
55
+ - permission-middleware
48
56
  references:
49
57
  - architecture
50
58
  - security
@@ -72,430 +80,127 @@ produces: [code, report]
72
80
  consumes: [user-description]
73
81
 
74
82
  token_budget:
75
- max_files_read: 3
76
- max_lines_per_read: 100
77
- max_shell_commands: 0
83
+ max_files_read: 5
84
+ max_lines_per_read: 150
85
+ max_shell_commands: 1
78
86
  stop_early: true
79
87
 
80
- exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
88
+ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
81
89
  ---
82
90
 
83
- # qk-access-policy — Access Control Designer
91
+ # qk-access-policy — Access Control & Authorization Designer
84
92
 
85
93
  > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
86
94
 
95
+ Chịu trách nhiệm thiết kế và triển khai cơ chế kiểm soát truy cập (RBAC / ABAC), bảo đảm nguyên tắc Least Privilege và Zero-Trust: **định nghĩa role matrix trước, implement middleware/guard sau**.
96
+
87
97
  ---
88
98
 
89
- ## Memory Workflow
90
-
91
- ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
92
- - Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
93
- - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
94
- - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
95
-
96
- ---
97
-
98
- ### Pre-flight Retrieve (Trước khi thực thi)
99
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
100
- bắt buộc tra cứu:
101
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
102
-
103
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
104
- - Architecture
105
- - Hard Bug
106
- - Convention
107
- - Pattern
108
- - Tech Debt Pattern
109
- - 👉 *Domain Focus:* Architecture/Pattern (vd: ma trận quyền authz, middleware rbac).
110
-
111
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
112
- Không được xem Memory là Source of Truth.
113
- Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
114
-
115
- ---
116
-
117
- ### Learning Flow (AI tự học có kiểm soát)
118
- - Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
119
- - Hard Bug có khả năng tái diễn.
120
- - Pattern làm việc lặp lại trong dự án.
121
- - Convention hoặc quy tắc kiến trúc mới.
122
- - Quyết định Architecture quan trọng.
123
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
124
- - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern bảo mật (vd: guard mới, chính sách Zero-Trust).
125
-
126
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
127
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
128
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
129
-
130
- ---
131
-
132
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
133
- Sau khi hoàn thành task:
134
- - AI đánh giá các Candidate Memory đã tạo.
135
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
136
- - Đề xuất người dùng xem xét.
137
- - Gửi yêu cầu phê duyệt thông qua:
138
- - `/learn`
139
- - `qk-project-memory`
140
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
141
-
142
- ```
143
- .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
144
- ```
145
-
146
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
147
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
148
-
149
- ---
150
-
151
- ### Ignore (Không đưa vào Memory)
152
- Không lưu:
153
- - Trace log của một session đơn lẻ.
154
- - Temporary debugging data.
155
- - Output của một lần chạy test/scan.
156
- - Report health tạm thời của một đợt kiểm tra.
157
- - Lỗi nhỏ chỉ xảy ra một lần.
158
- - Thông tin không có khả năng tái sử dụng.
159
- - 👉 *Domain Ignore:* Thao tác thêm 1 route/role thông thường vào bảng quyền đã có.
160
-
161
- ---
162
-
163
- ### Golden Rule
164
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
165
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
166
-
167
- ---
168
-
169
-
170
-
171
- ### Pre-flight Retrieve (Trước khi thực thi)
172
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
173
- bắt buộc tra cứu:
174
- - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
175
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
176
-
177
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
178
- - Architecture
179
- - Hard Bug
180
- - Convention
181
- - Pattern
182
- - Tech Debt Pattern
183
- - 👉 *Domain Focus:* Architecture/Pattern (vd: ma trận quyền authz, middleware rbac).
184
-
185
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
186
- Không được xem Memory là Source of Truth.
187
- Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
188
-
189
- ---
190
-
191
- ### Learning Flow (AI tự học có kiểm soát)
192
- - Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
193
- - Hard Bug có khả năng tái diễn.
194
- - Pattern làm việc lặp lại trong dự án.
195
- - Convention hoặc quy tắc kiến trúc mới.
196
- - Quyết định Architecture quan trọng.
197
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
198
- - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern bảo mật (vd: guard mới, chính sách Zero-Trust).
199
-
200
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
201
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
202
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
203
-
204
- ---
205
-
206
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
207
- Sau khi hoàn thành task:
208
- - AI đánh giá các Candidate Memory đã tạo.
209
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
210
- - Đề xuất người dùng xem xét.
211
- - Gửi yêu cầu phê duyệt thông qua:
212
- - `/learn`
213
- - `qk-project-memory`
214
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
215
-
216
- ```
217
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
218
- ```
219
-
220
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
221
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
222
-
223
- ---
224
-
225
- ### Ignore (Không đưa vào Memory)
226
- Không lưu:
227
- - Trace log của một session đơn lẻ.
228
- - Temporary debugging data.
229
- - Output của một lần chạy test/scan.
230
- - Report health tạm thời của một đợt kiểm tra.
231
- - Lỗi nhỏ chỉ xảy ra một lần.
232
- - Thông tin không có khả năng tái sử dụng.
233
- - 👉 *Domain Ignore:* Thao tác thêm 1 route/role thông thường vào bảng quyền đã có.
234
-
235
- ---
236
-
237
- ### Golden Rule
238
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
239
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
240
-
241
- ---
242
- ---
243
-
244
- ### Learning Flow (AI tự học có kiểm soát)
245
- - Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
246
- - Hard Bug có khả năng tái diễn.
247
- - Pattern làm việc lặp lại trong dự án.
248
- - Convention hoặc quy tắc kiến trúc mới.
249
- - Quyết định Architecture quan trọng.
250
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
251
- - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern bảo mật (vd: guard mới, chính sách Zero-Trust).
252
-
253
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
254
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
255
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
256
-
257
- ---
258
-
259
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
260
- Sau khi hoàn thành task:
261
- - AI đánh giá các Candidate Memory đã tạo.
262
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
263
- - Đề xuất người dùng xem xét.
264
- - Gửi yêu cầu phê duyệt thông qua:
265
- - `/learn`
266
- - `qk-project-memory`
267
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
268
-
269
- ```
270
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
271
- ```
272
-
273
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
274
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
275
-
276
- ---
277
-
278
- ### Ignore (Không đưa vào Memory)
279
- Không lưu:
280
- - Trace log của một session đơn lẻ.
281
- - Temporary debugging data.
282
- - Output của một lần chạy test/scan.
283
- - Report health tạm thời của một đợt kiểm tra.
284
- - Lỗi nhỏ chỉ xảy ra một lần.
285
- - Thông tin không có khả năng tái sử dụng.
286
- - 👉 *Domain Ignore:* Thao tác thêm 1 route/role thông thường vào bảng quyền đã có.
287
-
288
- ---
289
-
290
- ### Golden Rule
291
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
292
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
293
-
294
- ---
295
- ---
296
-
297
- ### Learning Flow (AI tự học có kiểm soát)
298
- - Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
299
- - Hard Bug có khả năng tái diễn.
300
- - Pattern làm việc lặp lại trong dự án.
301
- - Convention hoặc quy tắc kiến trúc mới.
302
- - Quyết định Architecture quan trọng.
303
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
304
- - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern bảo mật (vd: guard mới, chính sách Zero-Trust).
305
-
306
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
307
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
308
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
309
-
310
- ---
311
-
312
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
313
- Sau khi hoàn thành task:
314
- - AI đánh giá các Candidate Memory đã tạo.
315
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
316
- - Đề xuất người dùng xem xét.
317
- - Gửi yêu cầu phê duyệt thông qua:
318
- - `/learn`
319
- - `qk-project-memory`
320
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
321
-
322
- ```
323
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
324
- ```
325
-
326
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
327
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
328
-
329
- ---
330
-
331
- ### Ignore (Không đưa vào Memory)
332
- Không lưu:
333
- - Trace log của một session đơn lẻ.
334
- - Temporary debugging data.
335
- - Output của một lần chạy test/scan.
336
- - Report health tạm thời của một đợt kiểm tra.
337
- - Lỗi nhỏ chỉ xảy ra một lần.
338
- - Thông tin không có khả năng tái sử dụng.
339
- - 👉 *Domain Ignore:* Thao tác thêm 1 route/role thông thường vào bảng quyền đã có.
340
-
341
- ---
342
-
343
- ### Golden Rule
344
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
345
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
346
-
347
- ---
348
- ---
349
- ---
350
- ---
351
-
352
99
  ## Preconditions
353
- - [ ] User roles and protected resources are defined
354
- - [ ] Auth system (JWT, session, OAuth) is identified
355
100
 
356
- ```
357
- On missing precondition:
358
- EXIT: BLOCKED
359
- Message: "Cần định nghĩa: danh sách roles + resources cần bảo vệ."
360
- ```
101
+ Trước khi bắt đầu code, AI BẮT BUỘC xác nhận các thông tin sau:
102
+
103
+ - [ ] Danh sách Roles & Entities trong hệ thống (e.g. `guest`, `user`, `editor`, `admin`).
104
+ - [ ] Danh mục tài nguyên (Resources) thao tác (Actions: create, read, update, delete).
105
+ - [ ] Cơ chế truyền tải identity hiện tại (JWT payload claims, Session cookie, hay Header API Key).
106
+ - [ ] Nếu yêu cầu ABAC: Xác định rõ thuộc tính ngữ cảnh (e.g. `owner_id === user.id`, `tenant_id === org.id`).
107
+
108
+ *Nếu thiếu thông tin về Role hoặc Auth mechanism:*
109
+ → **EXIT: BLOCKED**
110
+ → Thông báo user: "Vui lòng xác nhận danh sách Roles và cơ chế Identity hiện tại trước khi thiết lập phân quyền."
361
111
 
362
112
  ---
363
113
 
364
114
  ## Scope
365
- - ✅ Define explicit Role-Permission Matrix before coding
366
- - ✅ Implement middleware/guards based strictly on the matrix
367
- - ✅ Separate auth (who are you?) from authz (what can you do?)
368
- - ✅ **Bắt buộc tuân thủ R-SEC-04: Mọi kiểm tra phân quyền phải thực hiện ở Backend (Server-side) qua Middleware. Tuyệt đối không tin tưởng JWT Claims thô chưa xác thực từ Client.**
369
-
370
- ## Non-Goals
371
- - ❌ Grant wildcard (*) permissions
372
- - ❌ Mix authentication logic with authorization logic
373
- - ❌ Hardcode role checks in business logic (use middleware/guards)
374
115
 
375
- ---
116
+ ✅ Skill này làm:
117
+ - Thiết lập **Role-Permission Matrix** rõ ràng (dạng bảng Markdown đối chiếu).
118
+ - Tạo Type definitions / Enums cho `Role`, `Permission`, `Resource`, `Action`.
119
+ - Xây dựng Auth Middleware / Guard / Decorator kiểm tra quyền truy cập.
120
+ - Xử lý phân quyền theo ngữ cảnh / sở hữu tài nguyên (Resource Ownership check).
121
+ - Phân tách rõ ràng mã trạng thái HTTP: `401 Unauthorized` (chưa authenticate) vs `403 Forbidden` (đã login nhưng không đủ quyền).
376
122
 
377
- ## Priority Order
378
- | P | Task | Skip Threshold |
379
- |---|------|----------------|
380
- | P1 | Define Role-Permission Matrix | Never |
381
- | P2 | Implement deny-by-default middleware | Never |
382
- | P3 | Add role guards to routes/controllers | Budget < 30% |
383
- | P4 | Add audit logging for auth failures | Budget < 60% |
123
+ Skill này KHÔNG làm:
124
+ - Viết flow đăng ký, đăng nhập, hash password (thuộc auth lifecycle cơ bản).
125
+ - Lưu trữ secret/token vào client-side không an toàn.
126
+ - Chỉ đặt guard controller/route bỏ qua validation ở service layer đối với logic nhạy cảm.
384
127
 
385
128
  ---
386
129
 
387
- ## Role-Permission Matrix Format (Required)
130
+ ## Execution Steps
388
131
 
132
+ ### Step 1 — Xây dựng Role-Permission Matrix
389
133
  ```
390
- Resource | admin | manager | user | guest
391
- ─────────────────────────────────────────────────
392
- GET /resource | ✅ | ✅ | ✅ | ✅
393
- POST /resource | |||
394
- DELETE /resource | ✅ | ❌ | ❌ | ❌
134
+ Inputs: user_description, DEV_PROFILE.md
135
+ Actions:
136
+ - Liệt kê bảng ma trận phân quyền Role x Resource x Action:
137
+ | Role | Resource | Actions | Conditions (ABAC) |
138
+ |--------|----------|----------------------|-----------------------|
139
+ | user | post | read, create | isOwner to update/del |
140
+ | admin | post | read, create, delete | any |
141
+ Outputs: Markdown table Role Matrix được phê duyệt
142
+ Exit: BLOCKED nếu quyền hạn bị mâu thuẫn hoặc chưa rõ scope
395
143
  ```
396
144
 
397
- ---
398
-
399
- ## Workflow
400
-
401
- ### Phase 1 — Matrix Definition
402
- 1. List all roles and resources from requirements
403
- 2. Create Role-Permission Matrix (table format above)
404
- 3. Identify conflicts or contradictions
405
-
406
- **Decision:** `IF matrix has contradiction → EXIT: BLOCKED — resolve ambiguity`
407
-
408
- ### Phase 2 — Implementation
409
- 1. Create deny-by-default guard/middleware
410
- 2. Apply guards to routes using matrix
411
- 3. Add auth failure logging
412
-
413
- ### Phase 3 — Verification
414
- 1. Read matrix vs implementation — spot check 3 routes
415
-
416
- ---
417
-
418
- ## Evidence Format
145
+ ### Step 2 — Khởi tạo Types & Constants
419
146
  ```
420
- [SEVERITY] src/middleware/auth.ts:LINE
421
- Rule: [WILDCARD | MISSING_GUARD | SOC_VIOLATION | HARDCODED_ROLE]
422
- Reason: [specific issue]
423
- Confidence: HIGH
424
- Fix: [specific change]
147
+ Actions:
148
+ - Khai báo enum/type an toàn (TypeScript/Python/Go) cho Role và Permission.
149
+ - Định nghĩa Policy / Rule registry có type-check chặt chẽ.
150
+ - Không dùng hardcoded string rải rác trong controller.
425
151
  ```
426
152
 
427
- ---
428
-
429
- ## Exit Codes
430
- | Code | Meaning | When |
431
- |------|---------|------|
432
- | SUCCESS | Matrix defined, middleware implemented, deny-by-default applied | Implementation complete |
433
- | PARTIAL | Implemented but missing audit logging or some routes unguarded | Post-verification minor gaps |
434
- | BLOCKED | Roles or resources undefined — cannot create matrix | Missing inputs |
435
- | FAILED | Contradiction in matrix or auth/authz mixed | Architectural violation |
436
-
437
- ---
153
+ ### Step 3 — Triển khai Guard / Middleware
154
+ ```
155
+ Actions:
156
+ - Express/Fastify: Tạo middleware `requirePermission(perm)` hoặc `requireRole(role)`.
157
+ - NestJS: Tạo `@Roles()`, `@Permissions()` decorator + `AuthGuard`, `RolesGuard`.
158
+ - FastAPI: Tạo security dependency `Security(get_current_active_user, scopes=[...])`.
159
+ - Next.js: Xử middleware.ts (route matching) + Server Action permission assertion.
160
+ Rules:
161
+ - Kiểm tra 401 trước (chưa đăng nhập hoặc token hết hạn).
162
+ - Kiểm tra 403 sau (đã đăng nhập nhưng thiếu quyền).
163
+ - Không bao giờ trả về 500 khi vi phạm authorization.
164
+ ```
438
165
 
439
- ## Confidence Model
440
- | Level | Condition | Action |
441
- |-------|-----------|--------|
442
- | HIGH | Roles and resources explicitly defined | Build matrix and implement |
443
- | MEDIUM | Roles inferred from codebase | Build matrix, ask user to verify |
444
- | LOW | Authentication strategy unknown | EXIT: BLOCKED |
166
+ ### Step 4 — Verification & Guard Test
167
+ ```
168
+ Actions:
169
+ - Kiểm tra endpoint được bảo vệ: gọi không token -> 401.
170
+ - Gọi với role thường vào endpoint admin -> 403 Forbidden.
171
+ - Gọi đúng quyền -> 200 OK.
172
+ - Đảm bảo không có lỗ hổng IDOR (Insecure Direct Object Reference).
173
+ ```
445
174
 
446
175
  ---
447
176
 
448
- ## Severity
449
- | Level | Definition | Example |
450
- |-------|-----------|---------|
451
- | CRITICAL | Route unguarded due to missing middleware | Anyone can access DELETE /users |
452
- | HIGH | Hardcoded roles in business logic | `if (user.role === 'admin')` in service layer |
453
- | MEDIUM | Wildcard permissions granted | `user` can access `*` |
454
- | LOW | Audit log missing for auth failure | Unlogged 403 error |
177
+ ## Prompt Template
455
178
 
456
- ---
457
-
458
- ## Retry Policy
459
179
  ```
460
- Route verification fails
461
- └─ Route unguarded
462
- ├─ Add missing guard to route
463
- └─ Do NOT retry more than 1 time per route
180
+ Hệ thống: [Tên app / module cần phân quyền]
181
+ Roles: [Danh sách roles: vd: viewer, editor, admin]
182
+ Resource: [Tài nguyên cần bảo vệ: vd: documents, orders, users]
183
+ Yêu cầu: [RBAC đơn giản hay điều kiện sở hữu ABAC]
184
+ Stack: [NestJS / Express / FastAPI / Next.js]
464
185
  ```
465
186
 
466
- ---
187
+ ### Ví dụ theo Stack:
467
188
 
468
- ## Escalation Rules
189
+ **role: be (NestJS + TypeScript)**
469
190
  ```
470
- BLOCKED: Roles or resources undefined
471
- Missing:
472
- - List of user roles
473
- - List of protected resources
474
- Questions:
475
- 1. Hệ thống có những role nào? (ví dụ: admin, user, manager)
476
- 2. Những API/Route nào cần bảo vệ?
477
- Recommended Assumptions:
478
- - Deny-by-default for all non-public routes
191
+ Roles: User, Moderator, Admin
192
+ Resource: Comment
193
+ Yêu cầu: User chỉ sửa comment của chính mình; Moderator xóa được mọi comment; Admin toàn quyền.
194
+ Stack: NestJS (Guards + Decorators)
479
195
  ```
196
+ → AI tạo: `Role` enum, `@Roles()` decorator, `RolesGuard` implements `CanActivate`, `OwnershipGuard` kiểm tra `comment.authorId === request.user.id`.
480
197
 
481
- ---
482
-
483
- ## Handoff Contract
484
- ### Consumes
485
- ```json
486
- {
487
- "from": "user",
488
- "required_fields": ["roles", "resources"],
489
- "optional_fields": ["auth_strategy"]
490
- }
198
+ **role: fullstack (Next.js 14 App Router)**
491
199
  ```
492
- ### Produces
493
- ```json
494
- {
495
- "to": "user",
496
- "output_fields": ["role_matrix", "middleware_files", "guarded_routes", "exit_code"]
497
- }
200
+ Roles: Member, Owner
201
+ Resource: Workspace Settings
202
+ Yêu cầu: Chỉ Owner mới được đổi tên workspace hoặc xóa workspace. Member chỉ xem.
203
+ Stack: Next.js Server Actions + DAL (Data Access Layer)
498
204
  ```
499
-
500
- ---
205
+ → AI tạo: Hàm assertion `assertWorkspaceOwner(workspaceId, userId)` dùng chung trong Server Actions, redirect/throw `ForbiddenError` chuẩn SEO & UX.
501
206