chimera-gfx-Public/docs/runtime/phase-0.9d-existing-stack-endpoint-matrix.md

# Phase 0.9D existing-stack endpoint matrix

Date: 2026-07-18
Status: `DESIGN_ONLY`

## Scope and common behavior

The full-profile matrix is bound to controlled Payload Manager commit
`e23d94ff91233aa770e2342800c1467875bdef44`,
`include/pldmgr.h:8-40` and `src/http_server.c:188-1181`. Its public-base
equivalent is commit `cfbc70f30f419b09bf2b52283f7409e2d3117ee1`;
the public base lacks the two `chimera` routes. The separately compiled minimal
controlled profile is in `src/controlled_manager.c:181-334`.

Unless a row says otherwise:

- authentication is absent and full-profile responses add permissive CORS;
- every non-`OPTIONS` full-profile request writes the process-local
  `server_active_flag` (`http_server.c:207-208`);
- non-noisy requests also append stdout/ring log state
  (`http_server.c:638-641`);
- handler responses are bounded in-memory text/JSON/static assets, not an
  arbitrary-file response;
- there is no automatic server-side retry, but client/UI retry is not a safe
  property of the route;
- exact timeouts and maximum request/response sizes are `UNPROVEN` unless
  explicitly bounded in the handler;
- no row is a readback candidate.

`ANY` means the handler branch itself does not enforce a verb. This is not a
recommendation to call it.

## Full-profile routes

| Method | Exact endpoint | Handler lines | Parameters / response | File and functional effects | Classification |
|---|---|---:|---|---|---|
| `OPTIONS` | any | 193-205 | empty CORS preflight | no active flag; sockets/counters only | observation false; not file readback |
| `ANY` | `/`, `/index.html`, `/cache.appcache`, `/favicon.svg`, `/icon.png` | 709-733 | compiled static bytes | no file open; active flag | `LOW_VOLATILE`, observation partial |
| `POST` | `/chimera:upload-controlled` | 212-252, 481-537 | query filename plus identity headers; text | exclusive write flags, then verified `O_RDONLY|O_NOFOLLOW|O_CLOEXEC` reopen/hash, fsync, rename, metadata write | forbidden: create/write/rename |
| `ANY` | `/manage:upload` | 254-286, 540-585 | query filename, request body; text | `fopen("wb")`, write, rename/import, metadata | forbidden: create/truncate/write/rename |
| `POST` | `/set_config` | 288-295, 363-398 | form body; text | reads current config, then config/autoload files can use `fopen("w")` | forbidden: configuration write |
| `POST` | `/repository_push` | 297-304, 401-443 | JSON body; text | temp/cache write, remove on error, rename, config timestamp | forbidden: write/remove/rename |
| `POST` | `/sources_set` | 306-313, 446-478 | JSON body; text | sources file replacement | forbidden: configuration write |
| `POST` | `/repository_install_push` | 315-356, 588-636 | filename/repo URL plus body; text | `fopen("wb")`, write, install rename/metadata | forbidden: create/truncate/write/rename |
| `ANY` | `/usb_move_check` | 648-674 | query `path`; JSON includes USB size | directory/stat reads only; path resolve | not binary response; observation partial |
| `ANY` | `/usb_move_perform` | 676-706 | path, overwrite, keep; JSON | reads USB, writes internal copy, optionally removes source | forbidden: write/remove |
| `ANY` | `/manage:check` | 735-759 | filename; existence JSON | `stat` directory and file | no bytes/size/hash; observation partial |
| `ANY` | `/list_payloads` | 760-767 | JSON list | directory traversal, `stat`, metadata-sidecar reads | no file bytes/size/hash attestation; observation partial |
| `ANY` | `/processes_list` | 768-775 | process JSON | process enumeration | functional observation only; not readback |
| `ANY` | `/process_kill` | 776-796 | pid query; text | sends process signal | forbidden: process action |
| `ANY` | `/repository_payloads` | 797-810 | JSON cache/list | cache/config reads; multi-source path can refresh/write | forbidden: possible network/cache write |
| `ANY` | `/repository_refresh` | 811-824 | JSON | network download, cache/temp/config writes and renames | forbidden: network/write/rename |
| `ANY` | `/repository_install` | 825-865 | filename/source/detail; JSON | network or cache reads, temp/final write and rename | forbidden: install/write/rename |
| `ANY` | `/sources_list` | 866-873 | JSON | reads sources configuration | configuration disclosure; no binary file framing |
| `ANY` | `/sources_add` | 874-900 | URL query; JSON | sources configuration write | forbidden: configuration write |
| `ANY` | `/sources_remove` | 901-921 | index query; JSON | sources configuration write | forbidden: configuration write |
| `ANY` | `/chimera:load-controlled` | 922-951 | filename plus identity headers; text | `O_RDONLY|O_NOFOLLOW|O_CLOEXEC`, stat/hash/read, sends to elfldr and launches | forbidden: payload launch |
| `ANY` | `/loadpayload:<path>` | 952-983 | path suffix; text | `open(O_RDONLY)`, stat/read, sends to elfldr and launches | forbidden: payload launch |
| `ANY` | `/manage:delete` | 984-1008 | filename query; text | unlinks payload/metadata, may update autoload | forbidden: delete/configuration |
| `ANY` | `/shutdown` | 1009-1015 | text | changes server run state | forbidden: service action |
| `ANY` | `/log` | 1016-1024 | log JSON | reads ring; active flag and connection state | observation partial |
| `ANY` | `/version` | 1025-1028 | text version | no file open; active flag | observation partial |
| `ANY` | `/getip` | 1029-1036 | text address | interface/socket query; active flag | observation partial; device/network metadata |
| `ANY` | `/autoload_status` | 1037-1091 | JSON | reads config/autoload; **sets `autoload_triggered=1`** | forbidden in Windows 1 and 2 |
| `ANY` | `/autoload_clear` | 1092-1097 | text | resets process-local autoload counters/trigger state; no file write in this call | forbidden: functional autoload mutation |
| `ANY` | `/abort` | 1098-1103 | text | changes autoload abort state | forbidden: functional mutation |
| unreachable | `/autoload_status` | 1104-1111 | short JSON | duplicate branch shadowed by 1037 | never independently callable |
| `ANY` | `/get_config` | 1112-1155 | JSON | `fopen("r")` config/autoload | no arbitrary file bytes; observation partial |
| `ANY` | `/events` | 1156-1165 | server-sent log stream | connection allocation and log reads | indefinite stream; not file readback |

## Minimal controlled-profile routes

This source defines a different listener/profile, not extra routes proven to be
installed beside the full profile.

| Method | Exact endpoint | Handler lines | Parameters / response | Effects | Classification |
|---|---|---:|---|---|---|
| `POST` | `/chimera/upload` | 181-303, 322-324 | required identity headers and filename; text status | exclusive temp create/write, then verified read/hash, fsync/rename | forbidden: device write |
| `POST` | `/chimera/launch` | 305-309, 324-326 | filename and identity headers; text status | verified local read/hash, sends and launches | forbidden: payload launch |
| `DELETE` | `/chimera/artifact` | 311-327 | filename; text status | unlink | forbidden: delete |

## Requested capability inventory

| Capability | Existing route | Result |
|---|---|---|
| Directory listing | `/list_payloads` | yes, filtered payload listing |
| File stat | `/manage:check`, `/usb_move_check`, listing internals | partial/fixed-purpose; no general stat identity |
| File read | internal only | no arbitrary bytes returned |
| File download | none | absent |
| File hash | internal controlled-launch verification only | no hash response route |
| File size | `/usb_move_check` for allowed USB source | no general live component size route |
| Upload | both upload routes and minimal `/chimera/upload` | present and forbidden |
| Rename | internal upload/install commits | present and forbidden; no standalone route |
| Delete | `/manage:delete`, minimal `/chimera/artifact` | present and forbidden |
| Process listing | `/processes_list` | present |
| Service listing | none | absent |
| Listener listing | none | absent |
| Firmware | none | absent |
| Configuration | `/get_config` | present, but request has functional active-flag effect |
| Autoload | status/clear/config routes | present and excluded |
| Payload launch | both load routes and minimal `/chimera/launch` | present and forbidden |

## File-open evidence

Filesystem reads occur in listing, configuration, repository/source handling,
USB checking, self-update discovery, and launch verification. The only
launch-side exact flags are controlled
`O_RDONLY|O_NOFOLLOW|O_CLOEXEC` (`verified_launcher.c:83-99`) and legacy
`O_RDONLY` (`ps5_launcher.c:77-84`). Upload paths use the write/create flags
shown above. None of these internal reads is wired to an HTTP binary-body
response.

Consequently:

- `readback_candidate=false` for every existing route;
- binary framing, remote EOF, returned byte count, partial-transfer detection,
  and end-to-end integrity are absent;
- a local file read for launch is not evidence of host readback;
- a general HTTP response is not evidence of file streaming.

The machine-readable matrix in
`manifests/runtime/phase-0.9d-existing-stack-readback.json` records the
per-route booleans and hard-stop reasons used by the validator.