jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

Record API security boundary and teardown decisions

Browse Source
This commit is contained in:
jester 2026-04-30 19:18:34 +00:00
parent 1e5a02dfe5
commit d5c224ca9d
1 changed files with 11 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Codex/API/DECISIONS.md
View File

@ -16,7 +16,7 @@
- JWT verification hardening is allowed to be contract-sensitive; access, refresh, and IDE proxy tokens may use distinct audience expectations. - JWT verification hardening is allowed to be contract-sensitive; access, refresh, and IDE proxy tokens may use distinct audience expectations.
- hosted IDE proxy cookies should default to hardened behavior appropriate for public HTTPS deployments. - hosted IDE proxy cookies should default to hardened behavior appropriate for public HTTPS deployments.
- proxy logging should avoid exposing cookies or detailed forwarded-header values in routine logs. - proxy logging should avoid exposing cookies or detailed forwarded-header values in routine logs.
- legacy worker-based provisioning is no longer a live API path and should stay archived unless intentionally revived. - legacy worker-based provisioning is no longer a live API path and should stay out of the active tree unless intentionally revived.
- legacy port allocation / slot reservation is no longer part of the active provisioning model and should stay retired unless intentionally revived end to end. - legacy port allocation / slot reservation is no longer part of the active provisioning model and should stay retired unless intentionally revived end to end.
- Minecraft edge routing uses Velocity; API should call the bridge's real HTTP routes: `POST /zpack/register`, `POST /zpack/unregister`, and `GET /zpack/status`. - Minecraft edge routing uses Velocity; API should call the bridge's real HTTP routes: `POST /zpack/register`, `POST /zpack/unregister`, and `GET /zpack/status`.
- API must not depend on a nonexistent Velocity `/zpack/list` route for registration verification. - API must not depend on a nonexistent Velocity `/zpack/list` route for registration verification.
@ -31,6 +31,16 @@
- API must check ownership before any host/LXC lifecycle action. - API must check ownership before any host/LXC lifecycle action.
- API should resolve the actual Proxmox node for a VMID when possible instead of assuming the configured default node is always correct. - API should resolve the actual Proxmox node for a VMID when possible instead of assuming the configured default node is always correct.
- Listener-limit fixes should target the socket creation/attachment point. For outbound Axios/follow-redirects traffic, use configured HTTP/HTTPS agents rather than relying on inbound HTTP socket handling. - Listener-limit fixes should target the socket creation/attachment point. For outbound Axios/follow-redirects traffic, use configured HTTP/HTTPS agents rather than relying on inbound HTTP socket handling.
- API control-plane routes must have explicit route-level authorization even when network access is already gated behind OPNsense/internal routing.
- `requireAdmin` is the shared policy for admin-only API routes such as audit logs and global instance inventory.
- `requireInternalToken` is the shared policy for internal-only control-plane routes such as raw edge publishing, Proxmox access, raw container teardown, and service discovery.
- Internal-token-protected routes should fail closed when token configuration is missing, except for explicit `NODE_ENV=development` or `NODE_ENV=test` local flows.
- User-owned delete should use `DELETE /api/servers/:id` with a normal user bearer token and ownership check.
- Raw `DELETE /api/containers/:vmid` is primarily an internal/admin/orphan-remediation surface. It temporarily accepts owned-user bearer deletes for Portal compatibility, but Portal should migrate to `/api/servers/:id`.
- Orphan cleanup belongs to internal/admin workflows, not normal Portal user paths. Portal deletes only active servers the DB says the user owns.
- Container teardown should live in a reusable service so Portal-owned delete and internal raw teardown share archival/Proxmox/DNS/Velocity/dev-IDE cleanup behavior.
- Completed teardown should archive `DeletedInstance` before removing the active `ContainerInstance` row so cleanup metadata remains available.
- Non-runtime clutter such as checked-in keys/tokens, local artifacts, `.old` scripts, `src/tmp`, and retired legacy trees should stay out of the active repo.
## Tracking rule ## Tracking rule
- when API work completes, remove it from `OPEN_ITEMS.md` - when API work completes, remove it from `OPEN_ITEMS.md`