267 lines
19 KiB
Markdown
267 lines
19 KiB
Markdown
# Persistence, Secure Image Handling, and Scenario Editors Design
|
||
|
||
## Purpose
|
||
|
||
Plan 3 of the four-plan BattleForge build. Closes the gap between the pure-PHP `Domain` layer (Plans 1 and 2) and the in-browser experience by adding:
|
||
|
||
- Anonymous-browser persistence of scenarios and in-progress matches (no user accounts, no cross-device, no server-side storage of game state).
|
||
- Server-rendered editor pages for teams and battlefields, with the domain's `Scenario` and `ScenarioValidator` enforcing every rule.
|
||
- A secure image-upload pipeline (content-sniffed, size-limited, dimension-limited, session-scoped).
|
||
- A minimal plain-PHP web stack with the cross-cutting security concerns the spec demands (CSRF, output escaping, content-validated uploads).
|
||
|
||
## Success Criteria
|
||
|
||
Plan 3 succeeds when a new user, without developer assistance and with no global state, can:
|
||
|
||
1. Visit `http://localhost:8000/`, see a home page that lists their recent scenarios, and start a new one.
|
||
2. Use the team editor to build two teams of 3-6 units each, choosing archetypes, stats, abilities, names, and optional custom images.
|
||
3. Use the battlefield editor to choose dimensions, paint terrain, place deployment zones, and place an objective (when the victory condition requires it).
|
||
4. Validate the assembled scenario server-side; see clear errors when something is invalid.
|
||
5. Upload a custom image and have it appear in the team editor.
|
||
6. "Start a match" from a saved scenario and have the initial `MatchState` round-trip through the browser.
|
||
7. Refresh the page, lose the connection, or come back tomorrow and find their saved scenarios still in their browser (no data loss from the user's perspective).
|
||
8. Reject forged cross-site requests, accept only image types the spec allows, and never let a user access another user's uploads.
|
||
|
||
## Out of Scope (deferred to Plan 4 or later)
|
||
|
||
- Hot-seat battle interface: Plan 3 ships a placeholder page that reads the assembled `MatchState` from `localStorage` and renders a "Battle interface coming in Plan 4" stub.
|
||
- Bundled scenarios (the three ready-made scenarios in the spec): Plan 4.
|
||
- Real-time interaction, drag-and-drop, or any other JS surface beyond the single fetch-based grid editor and the small `localStorage` helper.
|
||
- Server-side storage of scenarios, matches, or any game state.
|
||
- User accounts, sessions beyond the CSRF cookie, or any per-user server-side state.
|
||
- Mobile-native, PWA, offline service workers, or any non-server-rendered path.
|
||
- Antivirus scanning or upload rate limiting.
|
||
|
||
## In Scope
|
||
|
||
### Persistence
|
||
|
||
- Scenarios are JSON-serialized in the browser's `localStorage`, keyed as `scenario:{id}`.
|
||
- In-progress matches are JSON-serialized in `localStorage`, keyed as `match:current`.
|
||
- The server never sees a `Scenario` or `MatchState` after the editor POST completes. Each form submission is validated and acknowledged; the browser then writes to `localStorage` on its own.
|
||
- The home page lists scenarios by enumerating `localStorage` keys; no server call.
|
||
- "Resume in-progress match" reads `match:current` and shows a banner on the home page.
|
||
|
||
### Team Editor
|
||
|
||
- One form per scenario, with sections for: meta (id, name), team A, team B, victory condition.
|
||
- Each team section has 3-6 unit rows; rows are added and removed client-side (DOM manipulation, no fetch).
|
||
- Each unit row has: archetype dropdown, display name, image upload button + hidden URL field, four stat inputs (with `min`/`max` from the chosen archetype's template), and an abilities multi-select (limited to the chosen archetype's allowlist).
|
||
- The archetype JSON is served from `/assets/archetypes.json` and includes the four `ArchetypeTemplate` definitions.
|
||
- A new "Upload" form submits a single image to `POST /assets/upload` and writes the returned URL into the unit row's hidden `image` field. The unit-editor form is not submitted as part of the upload.
|
||
- Victory condition: a radio pair (`EliminateAll` / `HoldObjective`). When `HoldObjective` is selected, an input for `holdRoundsRequired` (1-10) appears.
|
||
- Submitting the form POSTs the full draft to `POST /scenarios/{id}/edit/team`. The server parses, builds a `ScenarioDraft`, runs `ScenarioValidator::validate()`, and on failure re-renders the form with errors inline.
|
||
|
||
### Battlefield Editor
|
||
|
||
- One page per scenario. Width/height inputs (8-16 each) at the top.
|
||
- Terrain palette: one button per `Terrain` enum value. The selected button is the "current paint."
|
||
- Grid: an HTML `<table>` of `<button>` cells with `data-x` and `data-y`. Clicking applies the current paint. Shift-click erases.
|
||
- Two deployment-zone controls (one per team). Each is a "click on grid to add this tile to my zone" mode.
|
||
- Objective control: a single "click on grid to place the objective" mode that is only shown when the victory condition is `HoldObjective`.
|
||
- The page ships with a small ESM helper (~50 lines, no build step) that maintains an in-memory `tileMap` object, posts it as JSON to `POST /scenarios/{id}/edit/battlefield` on save, and writes the server's response to `localStorage`.
|
||
|
||
### Image Upload Pipeline
|
||
|
||
- Multipart POST to `POST /assets/upload` with a hidden CSRF field.
|
||
- Server reads `$_FILES['image']`, validates with `ImageValidator` (see below), stores the file at `var/uploads/{userToken}/{hash}.{ext}`, and returns `{"url": "/assets/{userToken}/{hash}.{ext}"}`.
|
||
- `GET /assets/{userToken}/{filename}` streams the file with the right `Content-Type`. The `{userToken}` is derived from the session cookie and the request's `{userToken}` is verified to match; mismatch returns 404. Misses return 404.
|
||
- No listing endpoint. No directory traversal.
|
||
- Bundled placeholder images at `/assets/placeholders/{archetype}.png` are committed under `public/assets/placeholders/` and served without the `{userToken}` prefix.
|
||
|
||
### Security and Quality
|
||
|
||
- A per-session CSRF token stored in an `HttpOnly`, `SameSite=Lax` cookie, signed with the app's secret using `hash_hmac('sha256', …)`.
|
||
- Every form includes a hidden `_csrf` field; the fetch helper reads the value from a `<meta name="csrf-token">` tag and sends it in an `X-CSRF-Token` header.
|
||
- All output escaping goes through `Escape::html`, `Escape::attr`, and `Escape::url` helpers. Code review enforces the pattern; PHPStan has no rule for it.
|
||
- All uploaded images are content-validated by reading the first 12 bytes and checking the magic number against an allowlist (PNG, JPEG, WebP, GIF), then `getimagesizefromstring()` to confirm dimensions are ≤ 512×512, then size-checked at ≤ 2 MB.
|
||
- `Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self'` is set on every page. No `unsafe-inline`.
|
||
- `X-Content-Type-Options: nosniff` and `Referrer-Policy: same-origin` on every page.
|
||
- Bundled placeholders are committed; user uploads live in `var/uploads/` (git-ignored).
|
||
- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
|
||
- The single small JS file (`public/js/grid-editor.js` and `public/js/storage.js`) passes ESLint `airbnb/base` and Prettier.
|
||
|
||
## System Boundaries
|
||
|
||
The Plan 1+2 system boundaries are preserved and extended:
|
||
|
||
1. **Content library** (Domain, unchanged): owns curated unit archetypes, abilities, terrain, and bundled asset metadata. Served read-only to the web layer.
|
||
2. **Scenario editor** (web, NEW): hosts the team and battlefield editor pages. The `Application` layer translates form input into a `Scenario` and runs `ScenarioValidator`. The web layer never inspects a `Scenario` directly.
|
||
3. **Rules engine** (Domain, unchanged from Plans 1 and 2): authoritatively validates actions and resolves combat.
|
||
4. **Battle interface** (Plan 4, stubbed in Plan 3 as a "match is loaded" page that reads `match:current` from `localStorage`).
|
||
|
||
The new Application and Http layers sit between the web pages and the Domain. They do not depend on browser presentation code, and the Domain does not depend on them.
|
||
|
||
## Architecture
|
||
|
||
The four `// @phpstan-ignore` annotations in `src/Domain/` (in `UnitState`, `MatchState`, `Scenario`, `DeploymentZone`) reference "Plan 4" in their parenthetical comments. The comments will be updated to "Plan 3" in a follow-up amend after this design is approved.
|
||
|
||
```
|
||
src/
|
||
├── Domain/ (Plan 1 + 2, unchanged)
|
||
│ └── … 19 files …
|
||
│
|
||
├── Application/ (NEW)
|
||
│ ├── ScenarioSerializer.php JSON ↔ Scenario
|
||
│ ├── ScenarioDraft.php mutable draft state for the editor
|
||
│ ├── ImageUploadService.php validates + stores a user-uploaded image
|
||
│ └── ImageValidator.php content-sniff + size + dimension checks
|
||
│
|
||
├── Http/ (NEW)
|
||
│ ├── Router.php tiny path → handler dispatcher
|
||
│ ├── Request.php value object wrapping $_GET, $_POST, $_FILES, $_SERVER
|
||
│ ├── Response.php value object with status, headers, body
|
||
│ ├── CsrfToken.php per-session token store + verify helper
|
||
│ ├── Escape.php html(), attr(), url() helpers
|
||
│ └── Handlers/
|
||
│ ├── GetHomePage.php
|
||
│ ├── GetTeamEditor.php
|
||
│ ├── PostTeamEditor.php
|
||
│ ├── GetBattlefieldEditor.php
|
||
│ ├── PostBattlefieldEditor.php
|
||
│ ├── GetAssets.php
|
||
│ └── PostImageUpload.php
|
||
│
|
||
├── Views/ (NEW — plain PHP templates)
|
||
│ ├── layout.php
|
||
│ ├── home.php
|
||
│ ├── team-editor.php
|
||
│ ├── battlefield-editor.php
|
||
│ ├── match-stub.php
|
||
│ └── upload-result.php
|
||
│
|
||
└── public/ (NEW — document root for `php -S`)
|
||
├── index.php front controller
|
||
├── assets/
|
||
│ ├── archetypes.json
|
||
│ ├── placeholders/{defender,striker,support,scout}.png
|
||
│ └── (user uploads live under var/uploads/, not here)
|
||
└── js/
|
||
├── storage.js
|
||
└── grid-editor.js
|
||
```
|
||
|
||
`var/` is the only runtime-writable directory. It is git-ignored. It contains:
|
||
|
||
```
|
||
var/
|
||
├── cache/ PHP opcode cache (created by `php -S` if enabled)
|
||
├── phpunit/ PHPUnit cache
|
||
├── phpstan/ PHPStan cache
|
||
└── uploads/
|
||
├── .htaccess Deny from all (Apache)
|
||
├── index.php Sentinel that returns 403 (built-in dev server)
|
||
└── {userToken}/ Per-browser namespace; created on first upload
|
||
```
|
||
|
||
## Data and Action Flow
|
||
|
||
### Cold-start flow
|
||
|
||
1. Browser hits `GET /`. Server renders the home page.
|
||
2. A small inline script in the home page enumerates `localStorage` keys matching `scenario:*` and `match:current` and renders the list.
|
||
3. User picks an existing scenario → the team editor opens with the form pre-filled.
|
||
4. User picks "New scenario" → the team editor opens with an empty form for a new id.
|
||
|
||
### Team editor save flow
|
||
|
||
1. User edits the form, presses Save.
|
||
2. Browser POSTs the form to `POST /scenarios/{id}/edit/team` with `Content-Type: application/x-www-form-urlencoded` and a hidden `_csrf` field.
|
||
3. Server's `PostTeamEditor` handler:
|
||
a. Verifies the CSRF token.
|
||
b. Parses the form into a `ScenarioDraft`.
|
||
c. Builds a `Scenario` from the draft.
|
||
d. Runs `ScenarioValidator::validate($scenario)`.
|
||
e. On failure: re-renders the editor with the validator's errors next to each field, preserving the form's values.
|
||
f. On success: renders the editor with an inline `<script>` block that calls `localStorage.setItem('scenario:' + id, JSON.stringify(scenarioJson))` and shows a "Saved" toast. The server does not store the scenario.
|
||
|
||
### Battlefield editor save flow
|
||
|
||
1. User clicks tiles in the grid; the small JS helper maintains an in-memory `tileMap` object.
|
||
2. User presses Save; the JS helper POSTs the assembled JSON to `POST /scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and an `X-CSRF-Token` header.
|
||
3. Server's `PostBattlefieldEditor` handler:
|
||
a. Verifies the CSRF token.
|
||
b. Decodes the JSON body, validates the shape, builds a `ScenarioDraft`, runs the validator.
|
||
c. On failure: returns `{"ok": false, "errors": [...]}` with HTTP 400.
|
||
d. On success: returns `{"ok": true, "scenario": ...}` with HTTP 200. The JS helper writes `localStorage` and shows a toast.
|
||
|
||
### Image upload flow
|
||
|
||
1. User picks an image in the team editor and presses Upload.
|
||
2. Browser submits the file to `POST /assets/upload` as `multipart/form-data` with a hidden `_csrf` field.
|
||
3. Server's `PostImageUpload` handler:
|
||
a. Verifies the CSRF token.
|
||
b. Validates the upload with `ImageValidator`.
|
||
c. Writes the file to `var/uploads/{userToken}/{hash}.{ext}`.
|
||
d. Returns `{"url": "/assets/{userToken}/{hash}.{ext}"}` with HTTP 200.
|
||
4. JS writes the returned URL into the unit row's hidden `image` field. The unit-editor form is not submitted as part of the upload.
|
||
|
||
### Start-match flow
|
||
|
||
1. User on the team editor presses "Continue to battlefield" or on the battlefield editor presses "Start match."
|
||
2. JS reads the assembled `Scenario` JSON from `localStorage`, POSTs to `POST /scenarios/{id}/start` with `Content-Type: application/json`.
|
||
3. Server runs `ScenarioValidator` (defense in depth), calls `Scenario::startMatch('alpha')`, returns the initial `MatchState` JSON. (No browser-side `startMatch` call; the JS does not run the domain's PHP code.)
|
||
4. JS writes `match:current` to `localStorage` and navigates to `GET /match/current`.
|
||
|
||
## Validation and Failure Handling
|
||
|
||
- `ScenarioValidator` is the single source of truth for "is this scenario valid." Both the server (on every form POST) and the browser (before navigating forward) call it.
|
||
- A rejected action or form never partially mutates the persisted state. The browser's `localStorage` write happens only on a successful server response.
|
||
- Failure to save a scenario leaves the user's in-progress form intact; the editor re-renders the same values with errors inline.
|
||
- The CSRF token's invalid-or-missing case returns a generic 403 page that links back to `GET /`. The user's in-progress form state is preserved in `localStorage` via the on-change JS hook.
|
||
- A failed image upload shows an inline error next to the upload button; the unit row keeps whatever `image` field it had.
|
||
- Corrupt or incompatible JSON in `localStorage` (e.g. a hand-edited scenario) is rejected on read: the home page's "Recent scenarios" list skips it and shows a "scenario corrupt" placeholder for that key.
|
||
|
||
## Security and Quality Requirements
|
||
|
||
- Every state-changing form or request uses and verifies a CSRF token before mutation. The token is per-session, signed with the app's secret, and the form's hidden field is required for HTML forms or the `X-CSRF-Token` header is required for fetch POSTs.
|
||
- All input is sanitized and validated at the application boundary in the `Request` value object and the `ImageValidator`.
|
||
- All rendered output is escaped for its output context via the `Escape::html`, `Escape::attr`, and `Escape::url` helpers. Templates do not interpolate user input without one of these helpers.
|
||
- Uploaded images are validated by content (magic number) and by dimensions; the stored file's name is a server-generated random hex; the original filename and declared MIME are discarded after validation.
|
||
- `var/uploads/` is denied by `.htaccess` (Apache) and `index.php` (built-in server).
|
||
- The dev server is the built-in `php -S` running on a single port. No CGI, no Apache-only assumptions; the `var/uploads/.htaccess` and `var/uploads/index.php` sentinels cover both Apache deployments and the built-in server respectively.
|
||
- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
|
||
- The small JS surface passes ESLint `airbnb/base` and Prettier.
|
||
- Composer configuration passes `composer validate --strict`.
|
||
- All output includes `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin`, and a `Content-Security-Policy` header that forbids inline scripts and styles.
|
||
|
||
## Verification Strategy
|
||
|
||
### Unit tests
|
||
|
||
- `ScenarioSerializerTest`: round-trip every Plan 2 fixture through `toJson` → `fromJson`; add fixtures for all four archetypes, both victory conditions, every terrain, and at least one uploaded-image reference.
|
||
- `ScenarioDraftTest`: form fields → `ScenarioDraft` → `Scenario` for every field combination; error cases (out-of-bounds stat, unknown archetype, ability not in allowlist, oversized team, etc.).
|
||
- `ImageValidatorTest`: valid PNG/JPEG/WebP/GIF headers; invalid headers (text, executable, fake extension); size > 2 MB; dimension > 512; MIME/extension mismatch.
|
||
- `ImageUploadServiceTest`: round-trips a temp file through the service; asserts the file lands at the expected path; asserts the response URL is well-formed.
|
||
- `CsrfTokenTest`: round-trip; cross-session rejection; expired-cookie rejection.
|
||
- `EscapeTest`: regression set for `<`, `>`, `'`, `"`, `&`, control characters, NULL bytes.
|
||
- `RequestTest`: synthetic `$_GET`/`$_POST`/`$_FILES`/`$_SERVER` extraction.
|
||
|
||
### Integration tests
|
||
|
||
- One happy-path and one validation-error test per handler. Asserts cover status code, `Content-Type` header, presence/absence of the CSRF token in the response body, and inline error placement.
|
||
- A round-trip "save scenario" integration test: POST a full team-editor form, assert the response says "saved," then GET the same page and assert the form is pre-filled.
|
||
- A round-trip "upload + read back" integration test: POST a small PNG to `/assets/upload`, then GET the returned URL and assert the body matches the uploaded bytes exactly.
|
||
- A round-trip "forged CSRF" test: a POST without the token returns 403.
|
||
- A round-trip "wrong user" test: an upload stored under one session's `{userToken}` is unreadable from a different session.
|
||
|
||
### End-to-end smoke test (seeded in Plan 3, completed in Plan 4)
|
||
|
||
- Plan 3 ships the *plumbing* of an E2E test that boots a tiny PHP server in a background process, sends a sequence of HTTP requests, and asserts on response bodies. Plan 4 fills in the battle-interaction assertions.
|
||
|
||
### Static analysis / lint
|
||
|
||
- PHPCS rules stay `PSR-12`; the new `src/Http/`, `src/Application/`, `src/Views/`, and `public/` directories are added to the `phpcs.xml` `<file>` list.
|
||
- PHPStan level 6 stays. New exclusions: `src/Views/*` and `public/index.php`.
|
||
- ESLint `airbnb/base` + Prettier on the single small JS file. `package.json` + `package-lock.json` are committed; CI gains an `npm run lint` step.
|
||
|
||
### Manual usability check
|
||
|
||
- A new tester with no BattleForge context can: open the dev URL, see the home page, create a new scenario, build two teams with mixed archetypes, paint a simple battlefield, save both, and start a match — without leaving the browser or seeing any error from the validator that wasn't explained inline.
|
||
|
||
## Release Boundary
|
||
|
||
Plan 3 is releasable when every in-scope capability and success criterion is met, the verification suite is green (PHPUnit, PHPStan, PHPCS, ESLint, Prettier), and no out-of-scope capability (battle interface, bundled scenarios, AI, online play) is required to exercise the local creation flow. The local dev server runs the full app on a single port with `php -S`.
|
||
|
||
The next plan (Plan 4) will replace the battle-page stub with a real battle interface, add the three bundled scenarios, and ship the end-to-end smoke test that the Plan 3 plumbing seeds.
|