zlh-grind/CONSTRAINTS.md

System Constraints

These are non-negotiable guardrails.

---

1. Agent Is Authority

The agent:

• Owns filesystem enforcement
• Owns path normalization
• Owns write restrictions
• Owns upload allowlist
• Owns metadata

The API must NOT duplicate filesystem logic.

---

2. Runtime Root Sandbox

No operation may escape runtime root.

All paths:

• Cleaned
• Symlink-resolved
• Verified inside root

---

3. No Symlink Deployment Model

Uploads write directly to runtime.

No:

• Staging folders
• Symlink injection
• Delayed deployment

---

4. Metadata Is Hidden

.zlh_metadata.json and .zlh-shadow must never be exposed via file APIs.

Filtered centrally inside the agent internal/files package, not in route handlers.

---

5. Upload Allowlist Only

Only:

• mods/*.jar
• world/datapacks/*.zip

Anything else → 403.

---

6. Delete Is Strictly Constrained

No recursive delete. No directory delete. One-level file only.

Allowed paths:

• mods-removed/<file>
• mods-uploaded/<file>
• logs/<file>.log
• logs/<file>.log.gz

---

7. No Curated Inference

If metadata does not exist → source: null

Do not assume curated status from filename or path.

---

8. Upload Transport

API upload must:

• Stream via raw http.request piping
• Not buffer entire file in memory
• Not use fetch() streaming
• Not re-implement upload policy (agent enforces)

---

9. Timeouts

Upload route must use extended timeout. Other file routes remain short.

---

10. Portal Does Not Enforce Security

Portal may validate for UX (extension pre-check, size warning). Agent enforces real policy.

---

11. Frontend Cannot Reach Agents Directly

All agent access flows through API. Container IPs are internal-only (10.x network). No CORS headers on agents.

Frontend → API → Agent     ✅
Frontend → Agent            ❌

---

12. Authentication

• JWT tokens issued by API only
• No cookies for auth
• No CSRF tokens
• No APIv1 or Pterodactyl auth patterns
• Portal stores tokens client-side (sessionStorage)

---

13. Console Must Remain PTY-Backed

• PTY-backed
• Agent-owned
• WebSocket-based
• Full duplex (input + output)

Disallowed:

• Log tailing as "console"
• Exec-per-command models
• Frontend-owned processes
• Proxmox console passthrough

---

Enforcement

If a change violates these constraints:

• The change must be reverted
• The documentation takes precedence
• AI tools must be corrected

These constraints override convenience.