# CASAN Agentic Client — Mô hình bảo mật & giới hạn bypass (Plan-20)

Tài liệu này nêu rõ **CASAN đảm bảo gì và không đảm bảo gì** khi developer gõ
prompt trực tiếp trong một agentic client (Claude Code, Codex, VS Code). Mục tiêu
là không dùng từ “bắt buộc tuyệt đối” sai mức: một số tuyến chỉ là guardrail theo
project, có thể bị người có quyền sửa cấu hình bypass.

Liên quan:
[Plan-20 §3](../plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) ·
[Spike-20 §9](../spikes/CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md).

## 1. Certification strength — bốn mức, không gộp

| Strength | Ý nghĩa | Cam kết | Bypass |
|---|---|---|---|
| `casan_owned` | Launcher/SDK/Chat Participant do CASAN điều khiển toàn vòng đời | Mạnh nhất trong local client | Rất khó với người dùng thường |
| `managed_hook` | Hook/policy được tổ chức pin, user không tắt được | Guardrail tổ chức | Cần quyền quản trị môi trường |
| `project_hook` | Hook commit trong repo, user trust project | Guardrail theo project | **Có thể bypass** bởi người sửa/tắt config |
| `observed_only` | Chỉ telemetry, không đủ admission/tool gate | Không certified | N/A |

UI và export H6 **không** được gộp bốn mức trên thành một nhãn `pass`. Turn ở
`observed_only` không bao giờ hiển thị `certified`.

## 2. Điều kiện tối thiểu để một turn được certified

1. Có `admission_id` hợp lệ, còn hạn (TTL), gắn đúng project root canonical và
   session/turn.
2. Mọi side-effect tool trong coverage đã công bố đều qua `pre-tool`.
3. Enforcement mode = `enforce` và certification strength ∈
   {`project_hook`, `managed_hook`, `casan_owned`}.
4. Không có tín hiệu bypass coverage (ví dụ tool cross-project, tool ngoài
   coverage).
5. `finalize` chạy đúng một lần và các control kết thúc không đánh flag.

Nếu bất kỳ điều kiện nào thiếu → turn là **non-certified**. Bridge fail-closed:
khi không quyết định được trong internal timeout → block/deny.

**Phân biệt timeout vs gate-unavailable (graceful degradation):**

- **Timeout** (gate tồn tại nhưng không trả lời kịp) → **fail-closed**: block prompt
  / deny tool. Coi như có thể có rủi ro.
- **Gate không chạy được** (ví dụ Windows không có `bash`/Git Bash) → **degrade**:
  turn bị hạ cấp `observed_only`, **không certify**, nhưng **không chặn** developer.
  Đây là thực tế triển khai, không phải tấn công. CASAN không bao giờ certify âm
  thầm khi H4/H2 không chạy, và cũng không biến việc thiếu bash thành lý do chặn
  mọi prompt. Cài Git Bash để bật lại certification.

## 3. Những gì CASAN KHÔNG hứa

- **Không** chặn được mọi prompt trong mọi AI extension bên thứ ba.
- **Không** coi `project_hook` là security boundary tuyệt đối khi user có quyền
  sửa/tắt `.claude/settings.json` hoặc `.codex/hooks.json`.
- **Không** gọi model lần hai từ hook để “chạy lại qua CASAN”.
- **Không** suy diễn token/cost khi client không cấp nguồn tin cậy — số thiếu là
  `null` kèm warning, không phải `0`.
- Codex tool hooks là guardrail, **không** phủ 100% hosted/specialized tools; turn
  dùng tool ngoài coverage bị hạ cấp, không certified.

## 4. Threat model đã kiểm thử

Suite `tests/phase-agentic-bridge-tests.sh` (Spike-20 C1–C12 + threat) kiểm:

| Mối đe dọa | Phòng thủ | Test |
|---|---|---|
| Side-effect không admission | Deny fail-closed | C4 |
| Replay admission hết hạn | TTL check → deny | C5 |
| Dùng lại admission khác project | Project binding → deny + bypass_signal | C5, THREAT bypass |
| Prompt injection | H4 admission scan → block trước model | C2 |
| Tamper `admission_id` (path traversal) | Chỉ chấp nhận uuid hex, chặn `..` | THREAT tamper |
| Bridge/hook timeout | Internal timeout ngắn hơn outer → block/deny; ghi H6 failure | C6 |
| Outer hook timeout (fail-open của client) | Side-effect vẫn bị `pre-tool` deny nếu thiếu admission | C7/C4 |
| Stop loop | finalize idempotent, `stop_hook_active` guard | C8/C9 |
| Secret/tool output lọt log | Redact + chỉ lưu hash, không lưu raw prompt/output | C11 |
| Cost hiding (bịa số 0) | Missing → null + `telemetry_quality` | C10 |
| Certified giả ở observe mode | Observe luôn `observed_only`, không certified | THREAT observe |

## 5. Contract dữ liệu & privacy

- State ở `.specify/state/agentic-sessions/`, ghi atomic + lock per-turn.
- **Không** dùng raw prompt làm key; dùng salted hash + `turn_id` opaque.
- Admission có TTL, project root canonical, và session binding.
- **Không** ghi secret/credential hoặc toàn bộ tool output vào audit; evidence chỉ
  giữ bản redact + hash.
- Mỗi record mang `schema_version`, `trace_id`, `project_id`, `client`,
  `client_version`, `integration_mode`, `certification_strength`, `occurred_at`.

## 6. Khi cần enforcement mạnh

Absolute enforcement cần `casan_owned` hoặc `managed_hook`:

- **managed_hook:** pin hook/policy qua managed environment/MDM/requirements; user
  không tắt được. Đặt `CASAN_AGENTIC_INTEGRATION_MODE=managed_hook` qua môi trường
  quản trị, **không** commit trong repo.
- **casan_owned:** dùng launcher/SDK/Chat Participant do CASAN sở hữu toàn bộ vòng
  đời (ví dụ `@casan` VS Code Chat Participant — tuyến CASAN-owned, không phải
  global interceptor cho mọi prompt Copilot).

Plan-20 **không** quảng bá `project_hook` như một sandbox tuyệt đối.

## 7. Rollout & rollback

- Feature flags: `CASAN_AGENTIC_BRIDGE_ENABLED`,
  `CASAN_AGENTIC_ENFORCEMENT_MODE`, `CASAN_AGENTIC_CLIENT_ALLOWLIST`.
- Bắt đầu `observe`, sau đó `enforce` trong pilot; production default chỉ đổi sau
  exit gate.
- Trace sinh trong observe mode luôn `observed_only`, **không** retroactively
  certified.
- Rollback chỉ tắt adapter; `bin/casan-chat` và core H1→H7 hiện tại vẫn hoạt động.