146 lines
2.5 KiB
Markdown
146 lines
2.5 KiB
Markdown
# 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.
|