File size: 114,322 Bytes
e1c7447 f230383 e1c7447 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 | # SatQuery AI — Security Model, Trust Boundary and Threat Posture
**Status of this document.** This is the security chapter of the public SatQuery AI release. It is
written against the shipped code and the shipped configuration, and every non-obvious claim carries a
file reference. It is deliberately explicit about **what the system does not defend against**, because
the single most common failure mode in a security document is to describe a design intent as if it were
an enforced control.
**Status vocabulary used throughout** (see `DOCS_STYLE_GUIDE.md` §2): `IMPLEMENTED` · `VERIFIED` ·
`MEASURED` · `ATTEMPTED` · `NOT RUN` · `BLOCKED` · `DEFERRED` · `REJECTED` · `OPEN` · `RESOLVED` ·
`CLOSED`.
**Grounding rule.** Every field name, limit, count, code excerpt and command in this document was read
from a file. Where a value could not be established it is written
`UNKNOWN — not established from the available evidence`.
**A note on the word "gateway".** The backend-contract reference is
[`DEPLOYMENT_ARCHITECTURE.md`](architecture/02-deployment-topology.md) §2, which describes a *gateway*
whose job is validation, limits, CORS, request ids, timeouts, secret custody and error translation. In
the **active** topology that role is played by the Render orchestrator (`deploy/render/main.py`), and the
older `gateway/app.py` remains in the tree as the reference implementation of the same contract. This
document names the specific file whenever the distinction matters.
---
## Table of contents
- [0. How to read this document](#0-how-to-read-this-document)
- [1. Scope, trust model and explicit non-goals](#1-scope-trust-model-and-explicit-non-goals)
- [2. Secret custody](#2-secret-custody)
- [3. CORS: the allowlist rule](#3-cors-the-allowlist-rule)
- [4. Size and resource limits](#4-size-and-resource-limits)
- [5. Rate limiting is a FAIRNESS control, not a security control](#5-rate-limiting-is-a-fairness-control-not-a-security-control)
- [6. The `/v1/assets` endpoint: fail-closed behaviour and the handle-as-capability](#6-the-v1assets-endpoint-fail-closed-behaviour-and-the-handle-as-capability)
- [7. Input validation and modality inference](#7-input-validation-and-modality-inference)
- [8. The error-translation contract: what may reach a client](#8-the-error-translation-contract-what-may-reach-a-client)
- [9. The outbound tunnel: no inbound firewall hole](#9-the-outbound-tunnel-no-inbound-firewall-hole)
- [10. What is explicitly NOT defended against](#10-what-is-explicitly-not-defended-against)
- [11. Release-side security discipline: no secrets in any published file](#11-release-side-security-discipline-no-secrets-in-any-published-file)
- [12. Reporting a vulnerability](#12-reporting-a-vulnerability)
- [13. Open, blocked and not-run items](#13-open-blocked-and-not-run-items)
- [14. Evidence index](#14-evidence-index)
---
## 0. How to read this document
### 0.1 Three kinds of statement, and why the distinction is load-bearing
SatQuery AI is a research prototype with a **narrow, deliberate security scope**. The scope was set by
the project's own architecture plan, which excludes authentication, multi-tenancy, queues and
autoscaling from v1 (`docs/API_CONTRACT.md` §7; `docs/DEPLOYMENT_ARCHITECTURE.md` §6). The consequence is
that some of what a reader expects a "security chapter" to contain is **absent by design**, and the honest
way to present that is to separate three classes of statement:
| Class | Meaning | Example in this document |
|---|---|---|
| **Enforced control** | Code that runs on every request and refuses something | the CORS allowlist (§3); the body-size cap (§4) |
| **Fairness / operational control** | Code that bounds a resource, but which a hostile caller can defeat | the per-IP rate limiter (§5) |
| **Non-goal** | A property the system does not claim, and is not built to provide | authentication (§1.3); audit logging (§10) |
A document that blurred these three would let a reader size a deployment's abuse protection on a control
that cannot carry it. The rate limiter is the sharpest case, and §5 quotes the owner ruling that settles
it.
### 0.2 The four findings that shape this chapter
Four measured findings from the project's layer-crossing audit are the spine of the document, because
each one is a security property that was **asserted, then measured, then corrected** — which is the only
kind of claim worth publishing:
| Finding | One-line summary | Section |
|---|---|---|
| **F-2** | The CORS allowlist was enforced on the *request* leg only; an upstream CORS header was relayed verbatim on the *response* leg, bypassing the allowlist. Measured, then fixed. | §3.5 |
| **F-5** | The per-IP rate limiter keys on a client-supplied header, so a caller varying it produces **no** `429` at all. Measured; ruled a fairness control, not a protection control. | §5 |
| **F-6 / F-9** | The body-size cap was *declarative* — it measured a `Content-Length` header. A client omitting the header was never measured, and the whole body was buffered. Measured at both layers, then fixed with a streaming reader. | §4.4 |
| **F-15** | A construction failure's exception string — containing a **server-side checkpoint path** — reached client-visible fields. Ruled: sanitize client-facing messages, retain full detail server-side. | §8.4 |
### 0.3 What "public release" changes
This release publishes documentation, model artifacts and tooling to a public GitHub repository and a
public Hugging Face model repository. Publishing changes the security question in one specific way: the
**documentation itself becomes an attack surface for information disclosure**, because it is written from
the inside and naturally quotes paths, environment variable names and configuration. §11 records the
discipline that governs this, and the scan that enforces it.
---
## 1. Scope, trust model and explicit non-goals
### 1.1 What the system is
SatQuery AI is a geospatial vision-language analysis service. A user uploads one or two satellite
images, asks a natural-language question, and receives a structured `ResultEnvelope` containing an
answer, evidence, calibrated confidence and an execution trace. Six task capabilities are served: `vqa`,
`caption`, `grounding`, `change`, `change_vqa` and `optical_sar` (`CURRENT_RELEASE_STATE.md` §1,
`GET /api/capabilities` — six entries, all `available: true`).
The deployed topology is four tiers (`docs/architecture/02-deployment-topology.md` §1):
```
Browser
│ HTTPS
▼
Cloudflare Pages (static frontend, https://satquery.pages.dev)
│ HTTPS JSON /api/*
▼
Render orchestration hub (satquery-orchestrator; CORS, wake flow, limits)
│ outbound long-poll POST /tunnel/agent
▼
GitHub Codespace (FastAPI inference, CPU, port 8000)
│
specialist models (SmolVLM · RemoteCLIP · STANet-change · CROMA-fusion · MiniLM router)
```
### 1.2 What each tier holds — the trust table
The architecture document states this as a per-tier table
(`docs/architecture/02-deployment-topology.md` §2, "Holds secrets? / Holds state?"):
| Tier | Host / identity | Runs | Holds secrets? | Holds state? |
|---|---|---|---|---|
| Frontend | Cloudflare Pages, `https://satquery.pages.dev` | static site (`frontend/`) | **no** | no |
| Orchestrator / gateway | Render, `<backend-host>` | `deploy/render/main.py` | **`GITHUB_TOKEN` only** | no — stateless proxy |
| Inference | GitHub Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port `8000` | `app/space_app.py::build_space_app()` via `deploy/codespace/serve.py` | no gateway secrets | ephemeral asset store only |
| Model hosting | Hugging Face (project card + pinned model references) | — | no | no |
The security-relevant reading of this table: **the only tier that holds a credential is the
orchestrator, and the browser talks to the orchestrator, not to the inference host.** §2 develops this.
### 1.3 The explicit non-goals
These are not omissions. They are exclusions recorded in the architecture plan and restated in the
contract. Each is quoted from the file that records it.
| Non-goal | Where it is recorded | Exact statement |
|---|---|---|
| **No authentication** | `docs/API_CONTRACT.md` §7 | *"There is no authentication in v1. This is a recorded boundary, not an oversight."* |
| **No user accounts / multi-tenancy** | `docs/DEPLOYMENT_ARCHITECTURE.md` §6 (from plan §73/§74) | *"No multi-tenant isolation, no auth, no user accounts."* |
| **No database, no persistence, no session store** | `docs/DEPLOYMENT_ARCHITECTURE.md` §2.2 | *"No persistence. No database, no Redis, no session store."* |
| **No PII store** | consequence of the above: there is no user model, no account, no session, and the only retained bytes are ephemeral image uploads with a bounded TTL (§6) | — |
| **No request queue** | `docs/DEPLOYMENT_ARCHITECTURE.md` §2.2 | *"No request queue (plan §73 forbids Redis-cluster/queue infrastructure)."* |
| **No retries on `/v1/analyze`** | `docs/DEPLOYMENT_ARCHITECTURE.md` §2.2 | *"No retries on `POST /v1/analyze`. A retry would consume GPU quota a second time; the client must decide."* |
| **No model inference at the gateway** | `docs/DEPLOYMENT_ARCHITECTURE.md` §2.2 | *"No model inference."* |
| **No asset storage at the gateway** | `docs/DEPLOYMENT_ARCHITECTURE.md` §2.2 | *"The gateway relays upload bytes; it does not retain them."* |
The orchestrator's own module docstring states the same three absences in one sentence
(`deploy/render/main.py`): *"It holds no model, no state, no database, and performs **no auth** (per plan
§73/§74)."*
### 1.4 The trust model, stated plainly
```mermaid
flowchart TB
subgraph Untrusted["UNTRUSTED — the public internet"]
U[Anonymous browser]
end
subgraph Edge["EDGE — allowlisted origin only"]
CF["Cloudflare Pages<br/>static site · no secrets"]
end
subgraph Boundary["SECURITY BOUNDARY — holds the credential"]
R["Render orchestrator<br/>GITHUB_TOKEN · CORS · size caps<br/>request ids · error translation"]
end
subgraph Infer["INFERENCE — no inbound path"]
C["GitHub Codespace<br/>FastAPI :8000 · ephemeral store"]
end
U -->|HTTPS| CF
CF -->|"HTTPS JSON /api/*<br/>(Origin checked)"| R
C -.->|"dials OUT · long-poll<br/>POST /tunnel/agent"| R
R -->|"response delivered on the open poll"| C
```
Two properties follow, and both are stated in the source rather than inferred:
1. **The trust boundary is the orchestrator.** The architecture document says the inference host *"cannot
hold the security boundary"* and that rate limiting, size caps, CORS and secret custody *"belong
outside it"* (`docs/DEPLOYMENT_ARCHITECTURE.md` §1.1). The frontend guide states the same from the
client side: the frontend talks only to the gateway and never calls the inference host directly —
*"it is not the security boundary and its CORS will not welcome you"* (`docs/FRONTEND_INTEGRATION.md`
§7, quoted in `docs/architecture/02-deployment-topology.md` §2.7).
2. **There is no identity to escalate from.** Because v1 has no auth, an unauthenticated caller *is* the
only kind of caller. `docs/DEPLOYMENT_ARCHITECTURE.md` §5.2 argues this explicitly: the rate-limiter
weakness *"does **not** mean the service is insecure in the sense of a privilege escalation: §6 below
excludes auth by design and `API_CONTRACT.md` §7 states 'there is no auth in v1', so an
unauthenticated caller cannot escalate from a position of nothing."* What it *does* mean is that the
limiter cannot protect a metered resource — which is §5.
### 1.5 What "the request-side boundary" enforces
The gateway is described as the request-side boundary for exactly three things
(`docs/DEPLOYMENT_ARCHITECTURE.md` §5.2, final bullet): **shape, size and content type**. Rate is
explicitly *not* one of them. §4 and §7 cover shape and size; §4.6 covers content type.
---
## 2. Secret custody
### 2.1 The rule
> **The gateway holds credentials that must never reach the browser.**
This is the first of the eight gateway responsibilities in `docs/DEPLOYMENT_ARCHITECTURE.md` §2.1, whose
row reads: *"Secret custody | HF token lives here only | The browser never sees it."* The
contract restates it as a frontend obligation (`docs/API_CONTRACT.md` §7): *"The frontend **must not**
embed an HF token, an API key, or any secret. It talks only to the gateway."*
### 2.2 Where each secret lives
The architecture document's env-var vocabulary table (`docs/DEPLOYMENT_ARCHITECTURE.md` §4) assigns each
variable to a layer:
| Variable | Where it lives | Purpose |
|---|---|---|
| `HF_TOKEN` | **gateway only** (Railway in the design; Render in the active topology, *if used*) | Authenticate gateway → inference host. Never sent to the browser |
| `SATQUERY_SPACE_URL` / `SATQUERY_UPSTREAM_URL` | gateway | Upstream inference URL |
| `SATQUERY_ALLOWED_ORIGINS` | gateway | CORS allowlist (the frontend origin) |
| `PORT` | platform | Supplied by the platform |
| `SATQUERY_DEVICE` | inference host | `cpu` \| `cuda` \| `mps` \| `null` |
| `SATQUERY_ASSET_ENABLED` / `SATQUERY_ASSET_DIR` | inference host | Enables `POST /v1/assets`; **both** required |
| `SATQUERY_MAX_FILE_BYTES` | **both** | Per-file cap, read by gateway *and* inference host from one variable |
| `SATQUERY_MAX_BODY_BYTES` | gateway | Whole-request body cap |
| `SATQUERY_UPSTREAM_TIMEOUT_S` | gateway | Gateway → inference timeout |
| `SATQUERY_RATE_LIMIT_PER_IP` / `SATQUERY_RATE_LIMIT_WINDOW_S` | gateway | Per-IP count and window (fairness; §5) |
| `SATQUERY_ASSET_MAX_FILES` / `SATQUERY_ASSET_TTL_S` | inference host | Optional handle capacity / lifetime |
**No secret is committed.** `docs/DEPLOYMENT_ARCHITECTURE.md` §4 states it directly: *"**No secret is
committed.** `configs/deploy.yaml` contains no token, and the gateway must read its own from the platform
environment."* The `.gitignore` enforces the same for the artifact and data classes that could carry one:
it excludes `checkpoints/`, `artifacts/`, `*.pt`, `*.pth`, `*.safetensors`, `*.bin`, `data/`,
`benchmark/`, `outputs/`, `runs/`, `*.log`, `.deploy/`, `.kaggle/`, `kaggle.json`, and `.cache/`
(`.gitignore`). The `kaggle.json` and `.kaggle/` rules are specifically credential-shaped.
### 2.3 The live configuration, as measured
The live Render configuration was measured on 2026-09-25 from `GET /api/health`, and the result is
recorded in the header note of `docs/DEPLOYMENT_TOPOLOGY.md`:
> *"Verified against `GET /api/health`: env vars are
> `CODESPACE_NAME=potential-space-trout-r4ppw969w45j2pvvw`, `CODESPACE_PORT=8000`,
> `SATQUERY_ALLOWED_ORIGINS=https://satquery.pages.dev`, `SATQUERY_DEVICE=cpu`,
> `SATQUERY_TRANSPORT=auto`, `SATQUERY_TUNNEL_TIMEOUT_S=150`, `SATQUERY_WAKE_TIMEOUT_S=120`,
> `SATQUERY_UPSTREAM_TIMEOUT_S=90`, `GITHUB_TOKEN`.
> There is **no** `SATQUERY_UPSTREAM_URL` and **no** `HF_TOKEN` in the live config."*
The health payload reports the token **as a boolean, never as a value**
(`deploy/render/main.py`):
```python
"has_github_token": bool(os.environ.get("GITHUB_TOKEN")),
```
The measured payload confirms `"has_github_token": true` (`CURRENT_RELEASE_STATE.md` §1, live health
probe). Two consequences a reader should draw:
1. **The deployment does not hold an `HF_TOKEN`.** The token the design assumed for the HF proxy path is
absent, because the active transport is the outbound tunnel (§9) and the model host is a Codespace,
not a Space. The one credential present is `GITHUB_TOKEN`, used only by the GitHub-API wake path.
2. **A boolean is the correct disclosure for a health endpoint.** The endpoint tells an operator whether
a credential is configured without publishing it. This is the pattern the whole of §2 is about.
### 2.4 The token-injection path, and why `Authorization` is dropped
When the gateway (reference implementation `gateway/app.py`) forwards a request, the upstream headers are
built by `GatewayPolicy.upstream_headers` (`gateway/policy.py`). The docstring states the rule:
> *"Strips hop-by-hop headers (a proxy must not forward them) and injects the bearer token. **The token
> never travels back to the client** — `docs/DEPLOYMENT_ARCHITECTURE.md` section 4 keeps it here."*
The implementation drops two header classes and then injects:
```python
out: dict[str, str] = {}
for key, value in incoming.items():
if key.lower() in DEFAULT_HOP_BY_HOP:
continue
if key.lower() in ("host", "authorization"):
# `authorization` is dropped rather than overwritten so a client
# cannot smuggle a credential toward the Space.
continue
out[key] = value
if token:
out["Authorization"] = f"Bearer {token}"
return out
```
Three properties are worth naming, because each is a deliberate choice rather than an implementation
detail:
1. **The client's own `Authorization` header is dropped, not overwritten.** A client cannot smuggle a
credential toward the inference host. The comment says so: *"`authorization` is dropped rather than
overwritten so a client cannot smuggle a credential toward the Space."*
2. **`host` is dropped.** Forwarding the client's `Host` to a different upstream would be a
request-routing hazard.
3. **An empty token sends no `Authorization` header at all.** The docstring records the measurement: *"The
`Authorization` header is omitted entirely when `token` is empty. Sending `Authorization: Bearer `
(with an empty credential) is rejected by httpx itself with `LocalProtocolError: Illegal header
value`, which surfaced as a 502 whose `detail` blamed the upstream -- even though the upstream had not
been contacted."* An unauthenticated deployment is legitimate (`HF_TOKEN` is optional), so the correct
behaviour is to send no credential rather than an empty one.
The hop-by-hop set is RFC 9110 §7.6.1 (`gateway/policy.py`):
```python
DEFAULT_HOP_BY_HOP: frozenset[str] = frozenset(
{
"connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
"te", "trailer", "transfer-encoding", "upgrade",
}
)
```
### 2.5 The response leg: credential-shaped headers are stripped
A gateway that injects a credential on the way out must also refuse to relay credential-shaped headers on
the way back. `GatewayPolicy.response_headers` (`gateway/policy.py`) strips, in addition to hop-by-hop:
| Stripped on the response leg | Why |
|---|---|
| `content-length`, `content-encoding` | the ASGI layer re-frames the body, so a forwarded length would be wrong and a forwarded encoding applied twice |
| `authorization`, `www-authenticate`, `proxy-authorization` | *"a caller could pass this method the *request* headers by mistake, and the token we injected upstream is a credential. Stripping them here makes that mistake non-disclosing rather than catastrophic."* |
| `set-cookie`, `cookie` | the gateway is stateless and has no cookie to set; forwarding one would create a session the architecture does not have |
| **every `access-control-*`** | the CORS decision is the gateway's alone (see §3.5) |
The `authorization` row is the one that matters for secret custody: it makes a plausible programming
error — passing the request headers where the response headers were meant — **non-disclosing**, because
the credential-shaped headers are removed on both legs regardless of which dictionary is passed in.
### 2.6 The browser never sees a token — what that means concretely
Stated as observable facts rather than as an assurance:
| Observable | Value | Source |
|---|---|---|
| The frontend is a static site with no backend | *"No backend, no secrets, no API calls of any kind"* on the static pages | `docs/DEPLOYMENT_TOPOLOGY.md` §3.1 |
| The frontend calls only the orchestrator | `/api/health`, `/api/infer`, `/api/capabilities`, `/api/assets` | `docs/DEPLOYMENT_TOPOLOGY.md` §3.2 |
| The token is reported to a client as a boolean | `"has_github_token": true` | `deploy/render/main.py`; `CURRENT_RELEASE_STATE.md` §1 |
| The token never appears in a response body | the health payload's `config` block carries `codespace_name`, `codespace_port`, `has_github_token`, `allowed_origins`, `production_origins`, `dev_origins_enabled`, `wake_timeout_s`, `upstream_timeout_s`, `device` — no token value | `deploy/render/main.py` `health()` |
**What is not established:** whether the *deployed* `SatQuery-Backend` build (private repo, revision
`89d80eaddec5`) differs from the `deploy/render/main.py` in this monorepo. The monorepo's `deploy/` is
recorded as *"stale/untracked and is NOT the deployed source"* (`docs/FINAL_DELIVERY_REPORT.md` §2,
`CURRENT_RELEASE_STATE.md` §6). So the statements above are grounded in the monorepo reference
implementation and in the **live** health payload, which is measured — not in the private deployment's
source, which is
`UNKNOWN — not established from the available evidence`.
---
## 3. CORS: the allowlist rule
### 3.1 The rule
> **`SATQUERY_ALLOWED_ORIGINS=https://satquery.pages.dev`, and never `*`.**
The architecture document states it as a gateway responsibility with a one-word prohibition
(`docs/DEPLOYMENT_ARCHITECTURE.md` §2.1): *"CORS | Explicit allowlist of the frontend origin | Never `*`."*
The measured live value is exactly the production origin (`docs/DEPLOYMENT_TOPOLOGY.md` header note).
### 3.2 The decision function
CORS is decided by a function, not by a middleware configuration, so the decision is assertable without a
server (`gateway/policy.py::build_cors_headers`). The docstring explains why:
> *"The middleware is correct, but the *decision* is the thing under test, and
> `docs/DEPLOYMENT_ARCHITECTURE.md` section 2.1 requires an explicit allowlist that is never `*`. Stating
> the decision in a function makes it assertable without an ASGI server."*
```python
def build_cors_headers(
origin: str | None, allowed: Sequence[str], *, request_headers: str = ""
) -> dict[str, str]:
if not origin or origin not in allowed:
return {}
return {
"Access-Control-Allow-Origin": origin,
"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
"Access-Control-Allow-Headers": request_headers or "Content-Type, X-Request-Id",
"Access-Control-Max-Age": "600",
"Vary": "Origin",
}
```
The load-bearing line is the first one. A disallowed origin receives **no CORS headers at all** — the
docstring states why that is the point: *"A disallowed origin receives **no CORS headers at all**, which
is what makes the browser block the response. Echoing the origin back with
`Access-Control-Allow-Origin: <origin>` regardless would defeat the allowlist entirely."*
Note also `Vary: Origin`, which prevents a shared cache from serving one origin's CORS answer to another.
### 3.3 Startup refuses a wildcard
The allowlist is validated **at construction**, so a misconfigured deployment fails fast rather than
serving traffic with an open policy (`gateway/policy.py::GatewayConfig.__post_init__`):
```python
if "*" in self.allowed_origins:
raise ValueError(
"allowed_origins must not contain '*'. A wildcard exposes the "
"Space to any origin (docs/DEPLOYMENT_ARCHITECTURE.md 2.1)"
)
```
and, immediately before it:
```python
if not self.allowed_origins:
raise ValueError(
"allowed_origins must be non-empty. An empty allowlist would "
"either block every browser or, if the app fell back to '*', "
"expose the Space. Refuse to start rather than guess."
)
```
The empty-list case is the subtle one and the message says why: an empty allowlist has two possible
"fixes" in a hurried implementation — block everything, or fall back to `*` — and the second is a silent
security failure. The validator refuses both by refusing to start.
### 3.4 The development origins are enumerated, never a pattern
The orchestrator adds local development origins so a frontend developer can test without deploying
(`deploy/render/main.py::_DEV_ORIGINS`). The list is an explicit enumeration:
```python
_DEV_ORIGINS: tuple[str, ...] = tuple(
f"http://{host}:{port}"
for host in ("localhost", "127.0.0.1")
for port in ("3000", "5500", "5173", "8000", "8080")
)
_PRODUCTION_ORIGINS: tuple[str, ...] = ("https://satquery.pages.dev",)
```
Two design decisions are recorded in the docstrings, and both are security-relevant:
1. **Production is listed in code, not only in the environment.** *"Listed here rather than only in the
environment so that a deployment which forgets `SATQUERY_ALLOWED_ORIGINS` still serves the real
frontend -- an empty allowlist would otherwise take the live site down, which is a worse failure than
the one this guards."*
2. **The dev list is explicit, and cannot be reached from a remote host.** *"This list is deliberately
EXPLICIT, never a wildcard or a suffix match. It cannot be used to reach the deployment from an
arbitrary host: only a browser running on the developer's own machine can send
`Origin: http://localhost:*`."* The enumerated host:port pairs — and the fact that `localhost` and
`127.0.0.1` are *distinct browser origins* — are the reason both spellings appear.
The dev origins can be switched off for a production deployment via `SATQUERY_ALLOW_DEV_ORIGINS`
(`deploy/render/main.py::_dev_origins_enabled`), and the health payload reports the **effective** list so
an operator can prove from outside that they were turned off (`allowed_origins`, `dev_origins_enabled`).
### 3.5 F-2: the response-leg bypass, measured and fixed
This is the most instructive CORS item in the project, because the allowlist was **correct on the request
leg and bypassed on the response leg**. It is recorded in `gateway/policy.py::response_headers`'s
docstring and in `docs/DEPLOYMENT_ARCHITECTURE.md` §5.
**The defect.** Until 2026-09-22 the CORS decision was made only on the *request* leg
(`build_cors_headers`, via `admit()`), and the *response* leg rebuilt the upstream's headers wholesale.
So a CORS header the inference host emitted on its own was relayed to the browser verbatim, on top of the
gateway's allowlist answer.
**The measurement.** With the allowlist set to `["https://app.example.com"]` and the upstream answering
with `Access-Control-Allow-Origin: *` (`gateway/policy.py`, verbatim):
| Request | Result |
|---|---|
| `GET /v1/health` from `https://evil.example.net` | returned **two** values for `access-control-allow-origin`, `*` and the allowlisted origin |
| `POST /v1/analyze` from the same disallowed origin | returned `200` with `Access-Control-Allow-Origin: *` **and** `Access-Control-Allow-Credentials: true` |
**Why the `*` case is worse than a permissive echo.** The docstring argues it: *"a duplicated `ACAO` is not
a value a browser can match to an allowlisted origin -- it makes the gateway's own correct headers
unreliable for allowed callers while the `*` still admits everyone."* The bypass therefore degrades the
service for legitimate callers **and** admits everyone — two failures in one header.
**The fix** is a **prefix rule**, not an enum:
```python
and not key.lower().startswith("access-control-")
```
The docstring records why a prefix rather than a list: *"RFC 6648 discourages new `Access-` headers, but
the CORS family has grown (`-Allow-Credentials`, `-Expose-Headers`, `-Max-Age`, `-Allow-Methods`,
`-Allow-Headers`) and an enum would silently miss whichever is added next. Nothing the Space may
legitimately return starts with this prefix, because the CORS answer is the gateway's to give."*
**A pinned assertion, not a trusted helper.** `gateway/app.py::_proxy` asserts the filter rather than
relying on it:
```python
assert not any(_is_cors_header(k) for k in out_headers) or decision.headers, (
"a CORS header reached the response without a policy decision; the "
"upstream's headers are no longer filtered (see F-2)"
)
out_headers.update(decision.headers)
```
The comment states the intent: *"The CORS answer is decided in ONE place. If `response_headers` ever stops
filtering, the upstream's headers reach a disallowed origin -- so this pins the filter rather than trusting
it."*
**Verified by a test.** `tests/unit/test_gateway_app.py::test_an_upstream_cors_header_cannot_bypass_the_allowlist`
(`gateway/app.py`). The helper `_is_cors_header` is deliberately written without the literal prefix —
`_CORS_HEADER_PREFIX = "access-" + "control-"` — *"so that `tests/unit/test_gateway_app.py`'s 'the app
must not build an access-control-\* header itself' assertion is testing the app's behaviour rather than
tripping over this helper's spelling."*
### 3.6 Preflight is answered by the gateway, never forwarded
`GatewayPolicy.admit` step 1 (`gateway/policy.py`):
```python
# 1. Preflight is answered here, never forwarded. The Space has no CORS
# configuration and forwarding OPTIONS would waste a round trip.
if method == "OPTIONS":
return PolicyDecision.allowed(request_id, headers)
```
This closes the preflight failure recorded as a deployment blocker: *"Hand-rolled CORS; `OPTIONS` raised
`405`, so browser preflight failed"* (`docs/DEPLOYMENT_TOPOLOGY.md` §4, blocker #3).
---
## 4. Size and resource limits
### 4.1 The limit table
Every limit below is read from a file. The gateway defaults are `GatewayConfig` dataclass defaults
(`gateway/policy.py`); the image geometry values are from the frozen configuration registry
(`configs/base.yaml`).
| Limit | Value | Where | Enforced by |
|---|---|---|---|
| Whole-request body cap | `8 * 1024 * 1024` = **8,388,608 bytes (8 MiB)** | `GatewayConfig.max_body_bytes` (`gateway/policy.py`) | `SATQUERY_MAX_BODY_BYTES` |
| Per-file cap | `4 * 1024 * 1024` = **4,194,304 bytes (4 MiB)** | `GatewayConfig.max_file_bytes` (`gateway/policy.py`) | `SATQUERY_MAX_FILE_BYTES`, read by **both** layers |
| Max image pixels | **25,000,000** | `image.max_pixels` (`configs/base.yaml`) | `OversizedImageError` (`core/errors.py`) |
| Max tiles examined | **64** | `image.max_tiles` (`configs/base.yaml`) | tile policy (`docs/MASTER_ARCHITECTURE_PLAN.md` §9.1) |
| Tile size / overlap | **512** / **128** | `image.tile_size`, `image.tile_overlap` (`configs/base.yaml`) | preprocessing |
| Top-K tiles through a specialist | **4** | `image.top_k_tiles` (`configs/base.yaml`) | tile policy |
| Per-IP rate limit | **10** requests / **60.0 s** | `GatewayConfig.rate_limit_per_ip` / `_window_s` | fairness only (§5) |
| Upstream timeout | **90.0 s** | `GatewayConfig.upstream_timeout_s` | gateway → inference |
| Agent budget (inference host) | **120 s** | `agent.timeout_seconds` (`configs/base.yaml`) | controller |
| Asset handle capacity | **32** files | `AssetStore.max_files` default | inference host |
| Asset handle TTL | **900.0 s (15 min)** | `AssetStore.ttl_seconds` default | inference host |
| Evidence items | **32** | `evidence.max_items` (`configs/base.yaml`) | evidence engine |
### 4.2 Why there are two byte caps
The per-file cap is below the body cap **by construction**, and the ordering is validated at startup
(`gateway/policy.py`):
```python
if self.max_file_bytes > self.max_body_bytes:
raise ValueError(
"max_file_bytes exceeds max_body_bytes; the per-file cap would "
"be unreachable and the body check would fire first"
)
```
The reason for two caps rather than one is in `docs/DEPLOYMENT_ARCHITECTURE.md` §4: `SATQUERY_MAX_BODY_BYTES`
is the *whole-request* cap, *"above the per-file cap so one legal file is never refused for framing
overhead."* A multipart envelope around a legal 4 MiB file must not be refused because the envelope
pushed the total past 4 MiB.
### 4.3 The image-geometry budget
The pixel budget is a **resource** control in the same family as the byte caps, and it lives in the frozen
config registry rather than in the gateway (`configs/base.yaml`):
```yaml
image:
max_pixels: 25000000
tile_size: 512
tile_overlap: 128
max_tiles: 64
# plan section 9.1 tile policy: whole-image thumbnail first, then top-K tiles.
# max_tiles is the hard ceiling on tiles *examined*; top_k_tiles is how many
# are actually sent through a specialist.
top_k_tiles: 4
```
The plan's tile policy is the reason `max_tiles` and `top_k_tiles` are separate: *"Do not send every tile
through the VLM"* (`docs/MASTER_ARCHITECTURE_PLAN.md` §9.1). `max_tiles: 64` bounds what is *examined*;
`top_k_tiles: 4` bounds what is *sent through a model*. A maliciously large image therefore cannot turn
into 64 model calls.
**Status of the pixel budget.** The registry values are frozen and hashed
(`config_hash == 78f1e3700da15aa1`), and `OversizedImageError` exists with the code `oversized_image`
(`core/errors.py`, mapped to HTTP `413` in `gateway/policy.py::_CODE_STATUS`). Whether the *deployed*
inference host actually enforces `max_pixels` on every path is
`UNKNOWN — not established from the available evidence`: the live validation (§14) exercised real
uploads but did not include an over-pixel-budget probe.
### 4.4 F-6 / F-9: the cap must be enforced *while reading*, at both layers
This is the finding that turned a declared limit into an enforced one, and it is the clearest example in
the project of a control that *looked* present and was not.
**The defect (F-6, gateway).** `GatewayPolicy.admit` step 3 refuses an oversized body from the
`Content-Length` **header alone**, and it has to: it runs before the body is read, so the header is the only
evidence available. That makes the cap **declarative** — a client that omits the header is never measured.
The measured consequence, through the real ASGI stack with `max_body_bytes` at 8 MiB and a 12 MiB body
(`gateway/app.py`, verbatim):
| Case | Result | Peak allocation | Bytes read |
|---|---|---|---|
| `Content-Length` **declared**, 12 MiB | `413 oversized_image` | **0.2 MiB** | **0** (the cap worked) |
| `Content-Length` **omitted**, 12 MiB | `502 model_unavailable` | **13.9 MiB** | **12 MiB** (the cap was **SKIPPED**) |
and *"allocation tracked the body size exactly with no ceiling -- 1/8/16/32/64 MiB in produced
3.0/8.1/16.0/32.0/64.0 MiB allocated."* The source's own summary: *"the header check protects the common
case and bounds nothing in the hostile one."*
**The fix.** A streaming reader that refuses the moment the accumulated total exceeds the limit
(`gateway/assets.py::read_body_bounded`, called by `gateway/app.py::_read_body_bounded`):
```python
chunks: list[bytes] = []
total = 0
async for chunk in request.stream():
total += len(chunk)
if total > limit:
# Stop reading immediately. Doing so lets the server close the
# connection without the client delivering the rest of the body,
# which is the point of a streaming cap.
return b"", True
chunks.append(chunk)
return b"".join(chunks), False
```
The docstring records why `Content-Length` is *not* consulted here even as a fast path: *"The F-6
measurement is the reason: a declared length drew `413` with 0.2 MiB peak, but an **omitted** one drew
`502` with a 13.9 MiB peak, so anything keyed on that header holds only for clients that tell the truth.
A client that lies low is caught by the accumulation check; a client that omits the header is measured
like any other."* The bound is therefore `limit + one chunk`, *"rather than by whatever the client chose
to send."*
**The defect (F-9, the second layer).** The inference host had the *same* `await request.body()` line and
therefore the same defect. Measured with the cap at 1 MiB (`gateway/assets.py`, verbatim): *"a **64 MiB**
body produced a peak allocation of **128 MiB**, and a 16 MiB body 32 MiB, tracking body size **linearly
with no ceiling**. It answered `413` eventually, but only after buffering everything. The gateway's fix
had protected one caller of two."*
**The fix, and the anti-drift reasoning.** The helper was **moved down** to the module both layers already
import, rather than copied. The docstring states the reason as the F-7 finding restated: *"Fixing the
Space by copying the helper would have created two copies of a security control -- and two copies drift,
which is the F-7 finding restated."* `gateway/assets.py` is dependency-free (no fastapi, no starlette, no
httpx, no torch), which is what lets the inference host import it without pulling the web stack.
**Two lines, both needed.** `docs/DEPLOYMENT_ARCHITECTURE.md` §4 states the resulting posture: *"Both
layers are needed and neither replaces the other: the header check is the one that saves memory in the
common case, and the streaming check is the one that cannot be evaded. **Operators should not treat the
header check as the protection** — it protects the gateway's memory against honest clients, not against
hostile ones."*
### 4.5 F-7: one variable is not one value
`SATQUERY_MAX_FILE_BYTES` is read by **both** layers — the gateway validates it, and the inference host
builds its `AssetStore` from it (`app/space_app.py::_asset_max_file_bytes`). Until the fix, they parsed it
differently, and the docstrings asserted they *"cannot disagree"*. Measured on 2026-09-22 with the same
value through both parsers (`gateway/policy.py`, verbatim):
| Input | Gateway | Inference host |
|---|---|---|
| `'0'` | **ACCEPTED** `max_file_bytes=0` | raised `ValueError` |
| `'-1'` | **ACCEPTED** `max_file_bytes=-1` | raised `ValueError` |
| `'abc'` | raised at startup | **silently defaulted** to 4 MiB |
| `'4e6'` | raised at startup | **silently defaulted** to 4 MiB |
The source identifies the dangerous case: *"A cap of 0 is the dangerous case rather than a harmless typo:
the gateway admits the request (its own check is against `max_body_bytes`) and the Space then refuses
EVERY upload, because `len(data) > 0` is true for any non-empty file. The operator sees '413 on every
upload' against a cap they believe they never set."*
Both layers now refuse an unparsable **or non-positive** value and **name the variable**:
```python
max_file_bytes = _int("SATQUERY_MAX_FILE_BYTES", 4 * 1024 * 1024)
if max_file_bytes <= 0:
raise ValueError(
f"SATQUERY_MAX_FILE_BYTES={max_file_bytes} is not positive. A "
f"non-positive per-file cap would make every upload fail on the "
f"Space while the gateway kept admitting it; the Space's AssetStore "
f"rejects the same value, so it is refused here to fail at startup "
f"with the variable named rather than on the first upload"
)
```
The inference host's parser is deliberately **stricter than a silent default** and **not a bare
exception**, and its docstring says why: *"A silent default is the worse of the first two: it means a
deployment whose operator typed a malformed cap keeps accepting uploads against a limit nobody chose, and
nothing anywhere says so."* The direction of the strictness is argued, too: *"This makes the gateway's
parse stricter, which is the safe direction -- it cannot refuse a value the Space would have accepted,
because the Space refuses these too."*
**Cross-layer agreement is tested.** `docs/API_CONTRACT.md` §2.5 records that *"a cross-layer agreement
test drives the whole matrix through both real parsers."*
### 4.6 The content-type allowlist
The upload path accepts a **closed list of exactly five types** (`gateway/policy.py::GatewayConfig`):
```python
allowed_content_types: tuple[str, ...] = (
"image/tiff",
"image/geotiff",
"image/png",
"image/jpeg",
"application/octet-stream",
)
```
Three behaviours are specified and each is a security choice:
1. **An absent type is refused, not defaulted.** `_normalise_content_type` maps `None` to `""` so the
allowlist check rejects it: *"defaulting an absent type to `application/octet-stream` would make the
allowlist unenforceable for exactly the clients that omit the header"* (`gateway/assets.py`). The
contract's framing: *"A request with **no** declared type is **refused rather than defaulted** —
defaulting is how a PDF reaches a raster reader"* (`docs/API_CONTRACT.md` §2.5).
2. **Media-type parameters are ignored**, so `image/tiff; charset=binary` is accepted
(`_normalise_content_type` splits on `;`).
3. **The type is enforced independently at both layers.** The inference host keeps its own copy —
`_ALLOWED_ASSET_CONTENT_TYPES` in `app/space_app.py` — with a stated reason: *"Mirrors
`GatewayConfig.allowed_content_types`; the Space's copy exists because the Space validates
independently (defence in depth) rather than trusting that the gateway is the only caller."* This is
the one place where a duplicated list is **deliberate** rather than a drift hazard, and the docstring
says so.
The contract notes the practical consequence for a client: *"`image/tiff` is the type the geospatial
specialists need — a client that uploads only PNG/JPEG can serve the VQA, caption and grounding tasks but
not the change or optical/SAR ones"* (`docs/API_CONTRACT.md` §2.5).
### 4.7 Timeout ordering is a validated invariant
The upstream timeout must sit between the longest per-task GPU duration and the agent's own budget, and
both bounds are enforced at construction (`gateway/policy.py`):
```python
if self.upstream_timeout_s <= 45:
raise ValueError(...) # would kill a legitimate grounding/optical_sar call
if self.upstream_timeout_s >= 120:
raise ValueError(...) # would hold a connection past the point the Space has given up
```
The two messages state the failure each prevents: a too-short timeout *"would kill a legitimate
grounding/optical_sar call and report it as an upstream failure"*; a too-long one *"would hold a
connection past the point the Space has given up, turning an upstream timeout into a client-side hang."*
The frozen per-task durations are `vqa`/`caption` 20 s, `grounding` 45 s, `change` 30 s, `optical_sar`
45 s, `change_vqa` 30 s (`configs/deploy.yaml`; `app/space_app.py::GPU_DURATIONS`), and
`agent.timeout_seconds` is 120 s (`configs/base.yaml`).
---
## 5. Rate limiting is a FAIRNESS control, not a security control
### 5.1 The ruling, quoted in full
This is the section where the document must be most careful, because the temptation is to describe a rate
limiter as "protection". The owner ruling of 2026-09-23 settled the question, and
`docs/DEPLOYMENT_ARCHITECTURE.md` §5.2 records it verbatim:
> **✅ RULED 2026-09-23 (owner ruling): the limiter is RETAINED as a fairness / rate-control mechanism
> only, and it is explicitly NOT a security or abuse-prevention boundary.**
>
> **No code change.** The ruling settles the question this section left open — whether the limiter
> should be hardened into a protection control — and the answer is **no**. It stays as back-pressure
> against accidental loops and honest clients. Consequences a deployment must honour:
>
> * **Do not size abuse protection on this limiter.** It is not that control, and treating it as one
> would leave the `5 GPU-minutes/day` ZeroGPU quota unprotected.
> * **A `429` is a fairness signal, not a security signal**, and its ABSENCE is not evidence that no
> abuse occurred. A caller varying `X-Forwarded-For` produces no `429` at all (measured below).
> * The gateway remains the request-side boundary (`§1.1`) for **shape, size and content type** — the
> things it can actually enforce. Rate is not one of them.
>
> This is a **documentation ruling**: it changes what this document *claims*, not what the code does.
### 5.2 The mechanism
The limiter is an in-memory fixed-window counter keyed on client identity
(`gateway/policy.py::RateLimiter`):
```python
def check(self, identity: str) -> tuple[bool, int, float]:
now = self.now()
state = self._state.get(identity)
if state is None or now - state.window_start >= self.window_s:
state = RateLimitState(window_start=now, count=0)
self._state[identity] = state
if state.count >= self.limit:
retry_after = self.window_s - (now - state.window_start)
return False, 0, max(0.0, retry_after)
state.count += 1
return True, self.limit - state.count, 0.0
```
Three properties, each deliberate:
1. **A denied request does not increment the counter** — *"otherwise a client hammering the endpoint would
push its own reset further away on every rejected attempt."*
2. **The clock is injected** (`now: Callable[[], float] = field(default=time.monotonic)`), so tests are
deterministic without sleeping.
3. **The identity key is the IP alone** (`ClientIdentity.key`): *"Including the user agent would let one
client obtain an unbounded number of buckets by varying it."*
The limiter is applied only to routes marked `COSTLY_ROUTES` (`gateway/app.py`):
```python
COSTLY_ROUTES: tuple[str, ...] = ("/v1/analyze", "/v1/assets")
```
The docstring explains the membership: `/v1/analyze` costs GPU quota, and *"`POST /v1/assets` does not
touch the GPU, but it does write to the Space's disk and consume one of a bounded number of handles
(`gateway/assets.py`), so an unthrottled upload loop is a cheap denial of service against a
5-GPU-minute deployment."* `COSTLY_ROUTES` is deliberately a **separate allowlist** from
`PROXIED_ROUTES`: *"the two answer different questions -- 'may this reach the Space at all?' and 'does it
cost a metered resource?' -- and collapsing them would make the rate limiter's coverage depend on the
proxy allowlist."*
Rate limiting is step 4 of the admit ladder, after method allowlist and body size, and the ordering is
justified: *"Rate-limiting health checks would make the frontend's load probe fail for no gain"*
(`gateway/policy.py::admit`).
### 5.3 F-5: the measurement that forces the narrow claim
The rate-limit key is derived from the **first hop of `X-Forwarded-For`**
(`gateway/app.py::_client_ip`):
```python
forwarded = request.headers.get("x-forwarded-for")
if forwarded:
return forwarded.split(",")[0].strip()
```
That header is client-supplied. The code's own docstring already noted the value is attacker-controlled
and is *"a rate-limit key, not an identity"*; what was missing was the **measured consequence**.
Measured in-process, limit set to 3 requests / 60 s, 8 requests sent
(`docs/DEPLOYMENT_ARCHITECTURE.md` §5.2):
| Case | Statuses | Throttled |
|---|---|---|
| One client, no `X-Forwarded-For` | `502 502 502 429 429 429 429 429` | **5 / 8** |
| A fresh spoofed `X-Forwarded-For` per request | `502 502 502 502 502 502 502 502` | **0 / 8** |
So a caller willing to vary one header produces **no `429` at all**. This is the measurement that makes
"the limiter is a fairness control" a *fact* rather than a preference.
### 5.4 Why there is no code fix — and why that is deliberate
`docs/DEPLOYMENT_ARCHITECTURE.md` §5.2:
> **Why there is no code fix here yet, and why that is deliberate.** Correctly trusting
> `X-Forwarded-For` requires knowing how many proxy hops the platform inserts — a **deployment fact**
> that cannot be verified from the build host, where nothing is deployed. Hard-coding an assumption
> would replace a *documented* weakness with an *undocumented* one, which is exactly the error C-4
> made. The fix belongs in the deployment step and needs a live gateway to measure against.
### 5.5 What a client should do with a `429`
A `429` is a normal state, not a bug (`docs/API_CONTRACT.md` §6, obligation 4: *"Handle `429` and `503` as
normal states, not as bugs"*). The response honours `Retry-After`, computed as
`max(1, int(retry_after + 0.999))` (`gateway/policy.py::admit`), and `recoverable: true` is set on the
envelope. The frontend obligation is explicit: *"Serialize analyses. Do not retry `429`/`503` in a tight
loop"* (`docs/API_CONTRACT.md` §9, item 7).
### 5.6 The `rate_limited` code is gateway-origin, and the sets stay disjoint
`rate_limited` is **not** in `core/errors.py`. It is declared in `gateway/policy.py` as a gateway-origin
code, because `docs/API_CONTRACT.md` §5.1 maps HTTP 429 to "Rate limited" while the `core/errors.py`
taxonomy — which covers the *analysis* pipeline, not the proxy — assigns that status no code:
```python
GATEWAY_ORIGIN_CODES: frozenset[str] = frozenset({"rate_limited"})
_CODE_STATUS["rate_limited"] = 429
```
The rule that keeps the taxonomy honest: *"the gateway never invents a code for an error that ORIGINATED in
the Space. Those pass through unchanged."* Two tests hold the line
(`docs/API_CONTRACT.md` §5.3): `tests/unit/test_gateway_responsibilities.py` asserts §5.2 and
`core/errors.py` are in **exact one-to-one correspondence** (23 codes), and
`tests/unit/test_gateway_policy.py` asserts a gateway-origin code may **never** shadow a taxonomy code.
### 5.7 The four client headers that reach the inference host untrusted
Recorded because it is a latent, not a live, exposure (`docs/DEPLOYMENT_ARCHITECTURE.md` §5.2):
`cookie`, `x-forwarded-host`, `x-real-ip` and `x-forwarded-for` are forwarded as the client sent them. The
inference host reads none of them today — *"its only header read is `content-type` (`app/space_app.py`)"* —
so the exposure is latent. `Authorization` is **not** in this set: it is dropped on the request leg and
replaced with the gateway's own token, and stripped again on the response leg (§2.4, §2.5).
---
## 6. The `/v1/assets` endpoint: fail-closed behaviour and the handle-as-capability
### 6.1 The fail-closed gate
`POST /v1/assets` is **off unless explicitly enabled**, and it requires **two** environment variables
(`app/space_app.py::_asset_store_available`):
```python
def _asset_store_available() -> bool:
import os
return bool(os.environ.get("SATQUERY_ASSET_ENABLED", "")) and bool(
os.environ.get("SATQUERY_ASSET_DIR")
)
```
The docstring states the design: *"Off by default in a deployment that has not set `SATQUERY_ASSET_DIR`,
and ON when it has -- so turning on the fourth endpoint is an explicit operator action rather than
something that starts writing to a temp directory unbidden."* `docs/DEPLOYMENT_ARCHITECTURE.md` §4 states
the same as a contract: *"**Both this and `SATQUERY_ASSET_DIR` must be set** or the route answers `503` —
it fails closed rather than defaulting to a temp directory."*
### 6.2 The refusal is a conforming `503`
When the store is not configured, the handler returns a `503` envelope that names the switch
(`app/space_app.py::assets`):
```python
if not _asset_store_available():
status, body = translate_error(
"model_unavailable",
"Asset upload is not enabled on this deployment.",
detail=(
"Set SATQUERY_ASSET_ENABLED=1 and SATQUERY_ASSET_DIR to a "
"writable path to enable POST /v1/assets. See "
"docs/DEPLOYMENT_ARCHITECTURE.md."
),
recoverable=False,
)
return JSONResponse(status_code=status, content=body)
```
A deployment that has not enabled uploads **says so, with the reason and the switch**, rather than
accepting bytes it cannot keep. `docs/API_CONTRACT.md` §5.1 records the status: `503` when *"the asset
store is unconfigured or full."*
**An honest gap: the two `503` causes are indistinguishable.** A saturated store and an unconfigured store
produce the same status and the same envelope shape. `docs/DEPLOYMENT_ARCHITECTURE.md` §5.1 records this
as finding F-11, and — unusually — records the *removal* of the diagnostic that would have separated them:
the counters (`_refusals`, `_sweeps`) and `AssetStore.stats()` were computed on every request and read by
**nothing**, so they were deleted rather than given a consumer. The section's own summary: *"**⚠️ Removing
the counter did NOT remove the ambiguity.** The two `503` causes remain indistinguishable from a
response, and the deployment still **does not expose** an instrument that tells them apart."* Confirming
which cause applies requires inspecting the deployment.
### 6.3 The handle is the access control
`POST /v1/assets` returns an opaque handle, and the opacity is the *only* access control the endpoint has
(`gateway/assets.py::_new_handle`):
```python
def _new_handle() -> str:
"""An opaque, unguessable handle.
`secrets`, not `random`: the handle is this endpoint's only access control
(`API_CONTRACT.md` section 7 -- there is no auth in v1). 128 bits from
`token_hex(16)` is not brute-forceable, and the prefix keeps a handle
recognisable in a log without making it derivable.
"""
return f"asset_{secrets.token_hex(16)}"
```
The module docstring states the two consequences, and they are the security argument for the whole design:
> * **A client cannot enumerate the store.** `asset_0`, `asset_1` or a hash of the content would let a
> caller who guessed one handle reach another user's upload. There is no auth in v1
> (`API_CONTRACT.md` section 7), so the handle IS the capability: unguessable is not a nicety, it is
> the only access control the endpoint has.
> * **A handle does not leak a server path.** The stored filename is the handle plus a sanitised suffix
> taken from the *content type*, never from the client-supplied name -- so a name like
> `../../etc/passwd` cannot become a path. The original name is not stored at all, because it is not
> needed and storing it would be storing attacker-controlled text for no reason.
### 6.4 Path safety: the suffix comes from the type, never the filename
The stored suffix is derived from a fixed mapping keyed on the **normalised content type**
(`gateway/assets.py`):
```python
_SUFFIXES: Mapping[str, str] = {
"image/tiff": ".tif",
"image/geotiff": ".tif",
"image/png": ".png",
"image/jpeg": ".jpg",
"application/octet-stream": ".bin",
}
```
The docstring states the property: *"Derived from the TYPE, never from the client-supplied filename, so a
hostile name cannot influence a path."* The stored path is
`self.root / f"{asset_id}{suffix}"` where `asset_id` is the opaque handle — so the only
client-influenced component is the content type, and it is validated against the allowlist (§4.6) before
the suffix is chosen.
**What is not established:** whether the normalised content type is validated against `_SUFFIXES` as well
as against the allowlist before `_suffix_for` runs. `_suffix_for` returns `.bin` for an unknown type, and
`.bin` is a fixed string, so an unknown type cannot produce an attacker-chosen extension — but the
allowlist check in `put()` runs *before* `_suffix_for`, so in the shipped path an unknown type is refused
outright. The `.bin` fallback is therefore
`IMPLEMENTED` but unreachable on the shipped configuration; whether it is reachable on any other
configuration is `UNKNOWN — not established from the available evidence`.
### 6.5 Atomic writes: no partial upload is ever observable
`AssetStore.put` writes via a temporary file and `os.replace` (`gateway/assets.py`):
```python
fd, tmp_name = tempfile.mkstemp(dir=str(self.root), suffix=".part")
try:
with os.fdopen(fd, "wb") as handle:
handle.write(data)
os.replace(tmp_name, path)
except BaseException:
try:
os.unlink(tmp_name)
except OSError:
pass
raise
```
The docstring states the property: *"Write via a temporary file and `os.replace`, so a reader can never
observe a partially written upload. `os.replace` is atomic on both POSIX and Windows when source and
destination share a volume."* The `except BaseException` clause leaves nothing behind on failure and *"does
not mask the original exception if the cleanup itself fails."*
### 6.6 Expiry is checked on read, not by a sweeper
`AssetStore.get` evaluates expiry itself (`gateway/assets.py`):
```python
if stamp >= record.expires_at:
self._forget(asset_id)
raise UnknownAssetError(f"unknown or expired asset handle {asset_id!r}")
```
The docstring states why: *"Expiry is evaluated here rather than trusted to a sweeper: a handle past its
deadline is unknown even if nothing has run `sweep()`. That is what makes the TTL a guarantee instead of a
housekeeping hope."* The deadline is **monotonic**, so *"a system clock adjustment cannot extend or
truncate a TTL"* (`AssetHandle.expires_at`).
Two more fail-closed behaviours in `get`:
| Condition | Behaviour | Reason |
|---|---|---|
| Record missing or past deadline | `UnknownAssetError` | lapsed handle refused even if nothing swept it |
| Record present but the file is gone | `UnknownAssetError`, and the stale record is dropped | *"an operator cleared the directory, or a container restarted with a fresh volume. Reported as unknown -- the handle is not usable, which is what the client needs to know"* |
### 6.7 Expired and never-issued are one error, on purpose
`UnknownAssetError` covers *expired* as well as *never issued*, and the docstring states the reason:
*"a client cannot act on the difference (both mean 'upload again'), and distinguishing them would report
whether a handle had ever existed -- a small information leak about other clients' uploads, which matters
precisely because there is no auth."* This is a deliberate refusal to provide an oracle.
### 6.8 The response never discloses a path
`AssetHandle.to_response` returns four fields, and `path` is deliberately absent
(`gateway/assets.py`):
```python
def to_response(self) -> dict[str, Any]:
return {
"asset_id": self.asset_id,
"content_type": self.content_type,
"bytes": self.bytes,
"expires_at": self.expires_at_iso,
}
```
The docstring: *"`path` is deliberately absent. Returning it would hand a client a server-side filesystem
location -- an information disclosure, and an invitation to construct a path directly instead of via a
handle."* The contract repeats the guarantee for the frontend: *"It is not a path, and the response never
discloses one"* (`docs/API_CONTRACT.md` §2.5).
### 6.9 No idempotency key — a stated answer, not an omission
`gateway/assets.py` states it as a decision: *"There is **no** idempotency key, and that is a deliberate
answer rather than an omission. A retried upload is a *new* handle, not the same one, because the two
requests are indistinguishable at the server: no plan-specified key exists, and inventing one would be
inventing contract. The cost is a leaked handle, which `AssetStore.capacity` bounds and
`AssetStore.sweep` reclaims."* The contract states the client obligation: *"A client that retries must
therefore use the *latest* handle, and should expect the abandoned one to occupy a slot until it
expires"* (`docs/API_CONTRACT.md` §2.5).
### 6.10 F-12: a misconfigured asset root is a bounded defect
`_asset_store_available()` is a **presence** check — it asks whether the two variables are *set*, never
whether the directory is *usable*. Everything that can go wrong with the configured value therefore
happens later, at `get_asset_store()`, which sits **outside** the `try` that wraps `store.put()`.
Measured with the real ASGI app, root set to a path that exists but is a **file**
(`docs/DEPLOYMENT_ARCHITECTURE.md` §5.1.1):
| `SATQUERY_ASSET_DIR` | Inference host directly | Through the gateway |
|---|---|---|
| unset (the presence gate) | `503` + envelope | `503` + envelope |
| a writable directory (control) | `201` | `201` |
| **an existing file** | **`500 text/plain` `Internal Server Error`** | `502` + envelope |
The third row is a hole in the "every non-2xx carries the envelope" promise, **but only on the inference
host's own public URL**. The gateway refuses to relay a non-JSON upstream body and substitutes a
conforming `502`, so *"a client that goes through the gateway never sees it."* The same holds for the
inference host's framework errors (`GET /v1/assets` → `{"detail":"Method Not Allowed"}`), recorded as
F-12b. The disposition is *"recorded and not repaired"*: *"changing a route's error surface is not an
audit's call, and the Space that would carry it is **not yet deployed**."* Operational guidance: *"prefer a
`SATQUERY_ASSET_DIR` you have confirmed is creatable and writable, and treat a `500` from the Space's own
URL as a configuration fault rather than a crash to debug."*
---
## 7. Input validation and modality inference
### 7.1 Two layers validate, and the schema is authoritative
Validation happens at the gateway (`validate_analyze_body`) and again at the inference host
(`AnalysisRequest.model_validate(payload)`). The gateway's function is deliberately **not** a
re-implementation of the model (`gateway/policy.py`):
> *"Deliberately NOT a re-implementation of `AnalysisRequest`: it checks only what the contract's
> documented error envelope can carry. Two obligations it DOES take on, because forwarding either would
> cost a round trip (and possibly GPU quota) for a request the Space will certainly reject: every field the
> contract marks required is present and well-typed; no field outside the model's own field set is present,
> because `AnalysisRequest` uses `extra="forbid"`."*
The **schema's** validation is authoritative (`extra="forbid"`, Pydantic). The gateway's job is to answer
**cheaply**, before importing the serving stack, *"so that a malformed body never costs a model load."*
### 7.2 The checks the gateway performs
`validate_analyze_body` (`gateway/policy.py`) rejects, each with a conforming envelope:
| Check | Failure | HTTP |
|---|---|---|
| Body is valid UTF-8 JSON | not valid JSON | `400` `input_error` |
| Body is a JSON object | e.g. a JSON array or scalar | `422` `invalid_request` |
| No unknown fields | any key outside `AnalysisRequest.model_fields` | `422` `invalid_request` |
| `assets` is a non-empty array of non-empty strings | missing, empty, or containing a non-string | `422` `invalid_request` |
| `query` is present and a string | missing or wrong type | `422` `invalid_request` |
| `force_task` is `null` or a valid `Task` value | wrong type or unknown value | `422` `invalid_request` |
| `run_id` is `null` or a string | wrong type | `422` `invalid_request` |
Two of these are derived from the source of truth rather than hard-coded, which is the anti-drift
property:
```python
def _analyze_request_fields() -> frozenset[str]:
try:
from core.schemas import AnalysisRequest
return frozenset(AnalysisRequest.model_fields)
except Exception: # pragma: no cover - only in a broken install
return frozenset({"assets", "query", "force_task", "run_id"})
```
```python
def _task_values() -> frozenset[str] | None:
try:
from core.schemas import Task
return frozenset(member.value for member in Task)
except Exception: # pragma: no cover - only in a broken install
return None
```
The **asymmetry** between the two fallbacks is deliberate and security-relevant
(`gateway/policy.py::_task_values`): *"An unknown-field check needs a field set, and the documented four
field names are a short, stable list ... The `Task` values are a different case: they are the router's
vocabulary and the schema is explicit that it may grow (`core/schemas.py`). A stale copy here would
silently reject a newly-added task at the gateway, before the Space could accept it -- **a gate that fails
closed on valid input, which is worse than no gate.** The correct degradation is to forward, since the
Space's own Pydantic model is authoritative anyway."*
**The enum check was once missing, and the omission was not harmless** (`gateway/policy.py`): *"a body with
`force_task: "nonsense"` was forwarded to the Space, whose schema rejected it -- so the client received a
502/upstream error for a defect entirely local to the request. That both mis-states the fault and spends a
GPU-quota round trip on a body the Space cannot accept."*
**Cross-checked in both directions.** `tests/unit/test_gateway_policy.py` *"cross-checks this function's
verdicts against the real model in BOTH directions, which is what caught the originally-missing
unknown-field rule."*
### 7.3 A malformed `Content-Length` cannot bypass the size check
`gateway/app.py::_proxy` treats an unparseable `Content-Length` as **oversized**, not as absent:
```python
try:
content_length = int(raw_length) if raw_length is not None else None
except ValueError:
# A non-numeric Content-Length is malformed; treat it as unparseable
# rather than as absent, so it cannot be used to bypass the size check.
content_length = cfg.max_body_bytes + 1
```
This is a small, precise anti-bypass: a client sending `Content-Length: abc` is refused rather than
measured as having no length. The streaming reader (§4.4) then measures the body regardless.
### 7.4 Modality inference — where it happens, and where it does not
The gateway does **not** infer modality. The contract is explicit that `assets` values are
**handles**, not bytes and not URLs (`docs/API_CONTRACT.md` §2.4): *"Values are **asset handles returned by
the upload step** (§2.5), not base64 and not URLs."* The inference host is the one place the translation
`handle → AssetStore.get() → path` happens (`app/space_app.py::analyze`), and the docstring states why it
is done there rather than earlier:
> *"A handle that is unknown or expired is refused HERE, with a named error, rather than being passed to
> the controller as a path that does not exist -- which would surface as a raster read failure and name the
> wrong cause."*
The refusal is an `input_error` envelope:
```python
except UnknownAssetError as exc:
status, body = _translate(
"input_error",
"One or more asset handles are unknown or have expired.",
detail=exc.detail,
)
```
**All-or-nothing resolution.** `AssetStore.resolve_many` resolves every handle and raises on the first
failure: *"All-or-nothing: a partial resolution would let an analysis start with one of a required pair
missing, which the specialists would then reject with a pairing error that names the wrong cause. Failing
here names the real one."*
The `AnalysisRequest` is then **rebuilt**, not mutated: *"`model_copy` rather than mutating, because
`AnalysisRequest` is the contract's model and a handler must not rewrite a validated request in place."*
**Modality** itself is a property the specialists and the planner reason about, not the gateway. The
registry is authoritative for what each capability requires — the gateway *"must not answer 'what can this
deployment do?' from its own data"* (`docs/DEPLOYMENT_ARCHITECTURE.md` §2.2), because the authoritative
sources are `core.planner.CAPABILITY_ASSETS` and `SpecialistSpec.requires_assets`, and *"duplicating that
logic here would give two places to disagree."*
### 7.5 The method allowlist
`GatewayPolicy.admit` step 2 refuses a method the contract does not define (`gateway/policy.py`):
```python
allowed_methods = {"GET", "HEAD", "POST", "OPTIONS"}
if method not in allowed_methods:
status, body = translate_error(
"invalid_request",
f"Method {method} is not supported.",
detail=f"allowed: {', '.join(sorted(allowed_methods))}",
request_id=request_id,
)
return PolicyDecision.refused(request_id, status, body, headers)
```
The comment: *"A method the contract does not define is a 405 from the gateway, not a 404 from the Space."*
### 7.6 Request-id handling is a collision defence
An inbound `X-Request-Id` is **not trusted verbatim** (`gateway/policy.py::accept_request_id`):
```python
_REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9_\-]{8,64}$")
def accept_request_id(self, inbound: str | None, *, seed: str | None = None) -> str:
if inbound and _REQUEST_ID_RE.match(inbound):
return inbound
return self._request_id_factory(seed)
```
The docstring states the threat: *"Trusting an arbitrary inbound value lets a client collide with, or
poison, another request's correlation id in the Space's logs. The format is therefore constrained
(`req_`-less, 8-64 chars of `[A-Za-z0-9_-]`), and a rejected value is **replaced rather than sanitised** --
a mangled client id is more confusing than a fresh one."* The constraint is both a length bound (no
log-flooding payload) and a charset bound (no control characters or newlines into a log line).
Generated ids are deterministic-from-seed when a seed is given, which is the same reproducibility technique
used elsewhere in the project: *"the same technique the rest of this repository uses for reproducibility"*
(`new_request_id`).
---
## 8. The error-translation contract: what may reach a client
### 8.1 The envelope
Every non-2xx response body has one shape (`docs/API_CONTRACT.md` §5):
```json
{
"error": {
"code": "pair_misaligned",
"message": "The images are not sufficiently co-registered for spatial analysis.",
"detail": "RMSE 4.21 px exceeds the 2.0 px budget",
"recoverable": false,
"request_id": "req_01H...",
"run_id": "9f2c1c0e-..."
}
}
```
`code` is **stable** and comes from `core/errors.py`. `message` is operator-safe
(`SatQueryError.user_message`). `detail` is technical and may be absent. The gateway builds this with
`translate_error` (`gateway/policy.py`).
### 8.2 The gateway may not invent or remap a code
`translate_error` passes the code through **unchanged**. The rule is stated twice —
`docs/DEPLOYMENT_ARCHITECTURE.md` §2.3 and `gateway/policy.py`'s docstring:
> *"The `code` is passed through **unchanged**. The gateway must not invent codes: the taxonomy in
> `core/errors.py` is the single source of truth, and a gateway that remapped it would make the frontend's
> error handling unpredictable."*
An **unrecognised** code is mapped to `satquery_error` / `500` — never to a success status:
```python
known = code in _CODE_STATUS
status = _CODE_STATUS.get(code, 500)
if not known:
detail = f"unmapped error code {code!r}" + (f"; {detail}" if detail else "")
```
The comment: *"Keep the original code visible in `detail` for diagnosis, but present a code the contract
defines. Swallowing it entirely would hide a real defect behind a generic one."* And the mapping is
**total**: *"every code either appears here or falls through to 500, and `tests/unit/test_gateway_policy.py`
asserts that no code silently maps to the wrong class. A gateway that let an unknown code produce a 200
would turn a defect into a success."*
The status map has 23 taxonomy codes plus `rate_limited` (24 entries). Defect codes — *"codes that indicate
the *system* is broken, not the request"* — are a separate frozenset
(`model_load_error`, `schema_validation_error`, `coordinate_error`, `confidence_range_error`,
`leakage_violation`), and the frontend is instructed to surface them rather than swallow them
(`gateway/policy.py::DEFECT_CODES`; `docs/API_CONTRACT.md` §5.2).
### 8.3 Framework-raised 404/405 also carry the envelope
`docs/API_CONTRACT.md` §5.1: *"**`404` and `405` carry this same envelope**, which is worth stating because
they are the two statuses a proxy framework raises before any handler runs."* This was made true by
finding **F-3** (`docs/DEPLOYMENT_ARCHITECTURE.md` §5), after the gateway previously returned the
framework's own `{"detail": "Not Found"}` for both — which *"broke any client that assumed §5"*. The
handler is registered in **both** `gateway/app.py` and `app/space_app.py` (the latter as F-12b), so a
client hitting either host gets the contract shape.
A related footgun is documented rather than hidden (`docs/API_CONTRACT.md` §5.1): a trailing slash answers
**`307`**, and *"The `Location` is built from the gateway's own host, **not** from the client's request
URL, so a redirect followed naively after a `POST` may not land where the caller expects."*
### 8.4 F-15: the path-scrubbing ruling
This is the central disclosure finding. A construction failure's exception string — containing a
**server-side checkpoint path** — reached client-visible fields. Measured through the real inference host
with a request body containing **no path at all** (`docs/DEPLOYMENT_ARCHITECTURE.md` §5.5):
```
"message": "vqa was planned but could not be constructed: encoder weights_path does not exist: C:/srv/satquery/artifacts/change/stanet_encoder_v3.pt"
```
The section states why this is worse than the trace-path findings: *"This is **strictly worse than
F-13/F-14**: the asset path was derived from something the client supplied, whereas a checkpoint path is
purely server-side, and §7 records that *there is no auth in v1*. It is also reachable on the **first**
request -- the deployment condition, not a warm-process edge case."*
**The ruling (2026-09-23):** *"sanitize all client-facing exception messages; retain full exception details
only in server-side diagnostics."* Two halves, and *"both are load-bearing — the second is what stops the
fix from destroying operability."*
**The carrier count was wrong, and the ruling is what exposed it.** Re-measuring with a whole-body walk of
**156** string fields found **four** carriers rather than three:
| # | Carrier | Why it was missed |
|---|---|---|
| 1 | `result.warnings[0]` | named in the original finding |
| 2 | `result.evidence[0].payload["message"]` | named |
| 3 | `trace.parameters.registry.built[optical_sar].detail` | named (the warm-process case) |
| 4 | `result.execution_trace.parameters.registry.built[optical_sar].detail` | **not named** — `core/controller.py:379`/`:736` set `result.execution_trace = trace`, so the trace object is serialized **twice** |
Measured improvement: **8/11 → 14/14** path-free fields.
**The fix is a basename reduction, not a replacement** (`core/errors.py::scrub_paths`). It reduces absolute
paths (Windows drive, UNC, POSIX) to their final component and is applied at the producer
(`_failure_entry`), at the seam (`RegistryEntry.to_trace`), and at both controller sites
(`_failure_evidence`, `_warnings`). The raw string is logged server-side (`satquery.registry` WARNING with
`exc_info`).
```python
_WINDOWS_DRIVE_PATH = re.compile(
r"(?<![A-Za-z0-9_])[A-Za-z]:[\\/](?:[^\\/\s\"'<>|:*?]+[\\/])*[^\\/\s\"'<>|:*?]*"
)
_UNC_PATH = re.compile(r"\\\\[^\\/\s\"'<>|:*?]+(?:\\[^\\/\s\"'<>|:*?]+)+")
_POSIX_PATH = re.compile(r"(?<![:\w/])/(?:[^/\s\"'<>|:*?]+/)*[^/\s\"'<>|:*?]+")
```
**Three properties of the scrubber that are deliberate, and each argued in the docstring:**
1. **Relative paths are deliberately NOT matched.** *"A rule broad enough to catch `artifacts/change/head.pt`
also catches `and/or` and the path segments of a URL, and a scrubber that mangles ordinary prose is a
worse defect than the disclosure it fixes. The measured leaks are all absolute."*
2. **URLs are left intact on purpose.** *"`https://github.com/antofuller/CROMA` appears inside one of the
very messages this scrubs, and mangling it would be a worse defect than the one being repaired."* The
POSIX pattern's `(?<![:\w/])` lookbehind is what keeps the URL intact.
3. **Replacement was tried first and rejected by measurement.** Substituting the generic `user_message`
also stops the leak, *"and it **forced three pre-existing tests to be weakened**"* — three legitimate
diagnostics (*"no GPU in this dimension"*, *"build_that_does_not_exist"*, *"CROMA could not load"*)
failed. The docstring's conclusion: *"Three legitimate diagnostics failing is the signal that the
**granularity** was wrong, not that the tests were. The scrub preserved all three, and all three pass
**unmodified**."*
The ruling is enforced in three places in the inference host as well: the `StarletteHTTPException`
handler, the catch-all `Exception` handler (which logs the exception and returns a fixed, operator-safe
message), and the `AnalysisRequest` validation path (`app/space_app.py`). The catch-all's docstring states
the split: *"A traceback in `detail` would disclose internal paths and library versions to an
unauthenticated caller."*
**F-15b, recorded because two guards could not fail:** the `to_trace()` seam had **no covering test** —
falsifying it alone left the producer guard green, because the producer had already scrubbed the value.
The remedy was `test_to_trace_scrubs_a_detail_that_arrives_from_any_constructor`, which constructs the
entry **directly** through the constructor. And a second class of vacuous guard: `leak not in
json.dumps(body)` is a false negative because *"`json.dumps` doubles every backslash, so a raw Windows path
can never be found in a serialized body."* Three sites had it; all three now compare against
`json.dumps(leak)[1:-1]`.
### 8.5 F-13 / F-14: the trace stopped echoing filesystem paths
Before F-13, `POST /v1/analyze`'s response returned `trace.inputs` populated from `request.assets`
**after** the upload handler had rewritten handles into paths — *"the analysis response handed back the
very location the upload response had refused to give"* (`docs/DEPLOYMENT_ARCHITECTURE.md` §5.3).
Measured:
```
"inputs": ["C:\\Users\\anish\\sq_scratch\\pt_f13_a\\satquery_controller_stub0\\a0.tif"]
```
The fix is in the layer that owns the vocabulary (`core/controller.py::_asset_label` reduces each asset to
its **name**): *"The directory is the disclosure; the name is not — on the upload path it is the opaque
handle the client itself was just given, and on a direct-path call the caller supplied it."*
F-14 is the same defect one record later, at `trace.steps[PARSE].detail["inputs"]`. Measured end-to-end
with the real inference host (`docs/DEPLOYMENT_ARCHITECTURE.md` §5.4): the client sent
`asset_d243f7f85d8c2f3c02981f0af9737f01` and received the whole path back, occurring **exactly once** in
the response. The fix is one line, reusing `_asset_label`:
```python
- "inputs": list(request.assets),
+ "inputs": [_asset_label(a) for a in request.assets],
```
Post-fix, the same probe returns `asset_a1ab81c4e00cd3adcb2040e048b5bf3d.tif` and the scratch directory
appears **zero** times.
**A lesson recorded verbatim, because it is the point of the whole chapter** (`docs/DEPLOYMENT_ARCHITECTURE.md`
§5.3): *"**`"bounded"` is a claim, and a claim is not a measurement.** The honest entry would have been
*'not measured'*."* And on the guard that pinned the defect: *"A guard is only as strong as the behaviour
it pins, and this one pinned the defect — a reminder that a green suite is not evidence about a property
nobody wrote an assertion for."*
### 8.6 F-16: an artifact path where the contract promised a URI
`docs/API_CONTRACT.md` §2.4 documented an `artifact://run/.../change_map.png` example, and **no production
file emitted an `artifact://` URI**. Measured with `change.artifact_dir` configured (`docs/DEPLOYMENT_ARCHITECTURE.md`
§5.5):
```
result.change_map : 'C:\\...\\f16_probe\\artifacts\\change_map_t1.tif'
evidence[].artifact_ref : ['C:\\...\\f16_probe\\artifacts\\change_map_t1.tif', None, None]
```
The owner ruling: *"never expose filesystem paths; since v1 has no artifact-serving endpoint, set an
unavailable `artifact_ref` to `null` and emit an explicit non-retrievable-artifact warning; **do not
fabricate `artifact://` URIs**."* The ruling was **half implemented** until falsified against its sibling
site: it was applied to the `croma` carrier but **not** the `change` carrier. After the completion,
`result.change_map` and the `CHANGE_MAP` `artifact_ref` are both `null`, the map is still written
server-side, and a non-retrievable warning is present (probe **11/11**).
Two live carriers were measured; one declared key (`change_vqa.artifact_dir`) is **inert** (F-17,
§13). The asymmetry is stated honestly: *"two live carriers and one inert key, not three live ones."*
### 8.7 F-15c: a transport failure's raw exception text is never published
`gateway/app.py::_transport_failure_detail` maps the exception's MRO class names to a **path-free,
internals-free classification**:
```python
_TRANSPORT_FAILURES: tuple[tuple[str, str], ...] = (
("TimeoutException", "the upstream did not respond within the gateway timeout"),
("ConnectError", "the upstream could not be reached"),
("ProxyError", "the gateway's egress proxy refused the connection"),
)
_TRANSPORT_FAILURE_FALLBACK = "the upstream request failed at the transport layer"
```
The finding: *"this branch used to publish `detail=f"{type(exc).__name__}: {exc}"`. `detail` is part of the
documented error envelope (`gateway/policy.py:165`), so that put a third-party exception's class name and
message in front of an unauthenticated client -- naming the gateway's HTTP client and its internals, and
able to carry a proxy URL or a filesystem path."* The full exception reaches the operator through
`_log.error(..., exc_info=exc)`. It is **moved, not deleted**.
### 8.8 A non-JSON upstream body is a defect, never a pass-through
`gateway/app.py::_proxy` refuses to relay a non-JSON upstream body, and the guard covers **every** status,
not only 2xx:
```python
content_type = upstream.headers.get("content-type", "")
if "application/json" not in content_type and path != "/v1/health":
status, err_body = translate_error(
"schema_validation_error",
"The analysis service returned a malformed response.",
detail=(
f"content-type={content_type!r} for {path} "
f"(upstream status {upstream.status_code})"
),
request_id=decision.request_id,
)
return JSONResponse(status_code=502, content=err_body, headers=decision.headers)
```
Two consequences the comment records, both observed: *"the client received `text/plain` where
`docs/API_CONTRACT.md` section 5 guarantees `{"error": {...}}`"*, and *"the upstream's own wording was
passed through unfiltered, which is how this was found: a sandbox egress proxy returned a 502 whose body
disclosed `os error 10061`."* The status is `502` regardless of the upstream's own status: *"the fault the
CLIENT can act on is 'the gateway's upstream misbehaved', and echoing e.g. a 404 from a reverse proxy would
suggest the API path itself was wrong."* `/v1/health` is exempt *"because a liveness probe may legitimately
answer non-JSON."*
The orchestrator's `_proxy` applies the same rule (`deploy/render/main.py`): a non-JSON upstream body
becomes `schema_validation_error` / `502`.
### 8.9 The `detail` field is not a stable contract
`docs/API_CONTRACT.md` §5.2 states the client obligation: *"**Render `user_message` as the default and
override specific codes with better copy.** Do not invent a mapping from `detail` — it is not stable."*
This matters because `detail` is where technical context lives, and §8.4 shows it is also where a
disclosure would appear if the scrubber were removed. A client that keyed behaviour off `detail` would
both break on legitimate detail changes and couple itself to the field most likely to be scrubbed.
---
## 9. The outbound tunnel: no inbound firewall hole
### 9.1 The transport direction is inverted
The most important network-security property of the deployment is that **the inference host is not
reachable from the internet**. The architecture document states it as a per-tier fact and the topology
document records it as measured (`docs/DEPLOYMENT_TOPOLOGY.md` §2):
> **Measured 2026-09-25 (live).** Transport is an **outbound tunnel**, not a polled forwarded port: the
> Codespace runs `deploy/codespace/tunnel_agent.py`, which dials out to `POST /tunnel/agent` (long-poll)
> and executes against `http://127.0.0.1:8000` locally. When the Codespace is stopped the agent stops
> polling → `GET /api/health` reports `tunnel.agent_connected:false` and `POST /api/infer` parks until
> `SATQUERY_TUNNEL_TIMEOUT_S` (150 s), then returns `tunnel_offline` (503, `recoverable:true`).
The live topology is recorded as `Cloudflare Pages → Render → outbound tunnel → GitHub Codespace`
(`CURRENT_RELEASE_STATE.md` §2), and the forwarded-port path is recorded as **dead** — *"the forwarded
port returns 302 for a private repo"*.
### 9.2 What the inversion buys
`deploy/codespace/launch.sh` states the property in its header comment, quoted in
`docs/architecture/02-deployment-topology.md` §3.2:
> *"The tunnel is why this works with a PRIVATE repository: the agent makes only outbound HTTPS calls, so
> GitHub's port-forwarding relay, port visibility and the repository's visibility are all irrelevant. The
> orchestrator never dials into this Codespace."*
Consequences, each observable (`docs/architecture/02-deployment-topology.md` §3.2):
| Property | Value under the tunnel |
|---|---|
| Repository visibility | irrelevant — only outbound HTTPS is used |
| Port visibility setting | irrelevant |
| **Inbound firewall / NAT** | **no inbound connection is required at all** |
| Who initiates | the **Codespace**, to `SATQUERY_HUB_URL` |
| What the hub needs | a long-poll endpoint and a way to match a response to a pending request |
### 9.3 The direction, as a diagram
```mermaid
sequenceDiagram
autonumber
participant CF as "Cloudflare Pages"
participant R as "Render hub"
participant TA as "Codespace tunnel agent"
participant API as "FastAPI :8000"
Note over TA,R: startup — agent dials OUT
TA->>R: POST /tunnel/agent (announce, long-poll)
R-->>TA: (holds the poll open)
CF->>R: POST /api/infer
R->>TA: deliver request on the open poll
TA->>API: POST http://127.0.0.1:8000/v1/analyze
API-->>TA: ResultEnvelope
TA-->>R: response
R-->>CF: envelope + X-SatQuery-State
```
### 9.4 The honest gap: the agent's internals are not in this repository
The security-relevant statement above — "no inbound connection is required" — is grounded in
`launch.sh`'s header comment and in the measured live behaviour, **not** in a reading of the agent's
source. The agent is **not present in the monorepo working tree** and is **not tracked by git**
(`docs/architecture/02-deployment-topology.md` §3.3 and §9.4):
| Question | Answer | Status |
|---|---|---|
| Is `deploy/codespace/tunnel_agent.py` in the monorepo working tree? | **No** — `Glob **/tunnel_agent*` finds nothing | `MEASURED` |
| Where does it exist? | `Anish-lab-blip/SatQuery-Inference` (private) | `VERIFIED` |
| What *is* established about it? | it imports `httpx`; it dials `SATQUERY_HUB_URL`; it executes against `http://127.0.0.1:8000`; it logs `announced to hub`; it is supervised by `launch.sh` | `VERIFIED` (from `launch.sh` comments and greps) |
Therefore the agent's **function names, arguments and payload shapes** — and any authentication the tunnel
handshake performs between the agent and the hub — are
`UNKNOWN — not established from the available evidence`. What the evidence establishes is the direction
(outbound), the local target (`127.0.0.1:8000`), the transport (HTTPS long-poll) and the observable health
signal (`agent_connected`).
### 9.5 The tunnel is also a resilience mechanism, and its failure is honest
Because the Codespace may be stopped when idle, the deployment has a cold-start story, and it is
*documented rather than hidden* (`docs/DEPLOYMENT_TOPOLOGY.md` §2): *"Cold start is therefore tens of
seconds and is **documented, not hidden**. Observed warm state: `agent_connected:true`, `completed:314`."*
A tunnel gap is a known, open item. **B-07** — *"Transient tunnel-agent gaps → a request can hang or
return 504. Patch prepared, **NOT deployed**"* — is `OPEN` (`CURRENT_RELEASE_STATE.md` §6). The measured
root shape is recorded too: *"in `auto` mode a tunnel timeout **falls through** to the forward path
(`main.py:546`), burning `wake_timeout_s=120` on a 302 (~249 s ≈ 150+120)."* The client-facing mitigation
is an actionable retry message, and the response is `tunnel_offline` / `503` with `recoverable: true`.
**The transport is observable from the client.** The frontend treats a response header as evidence that
the hub forwarded to the Codespace rather than answering locally (`docs/architecture/02-deployment-topology.md`
§3.4): `frontend/assets/js/live.js` reads `X-SatQuery-State`, set by `deploy/render/main.py::infer` to
`"waking"` or `"ready"`. The live validation recorded `x-satquery-transport: tunnel` on the error-contract
probe (`docs/FINAL_DELIVERY_REPORT.md` §3, P3).
---
## 10. What is explicitly NOT defended against
This section is the most important in the document. Each row is a property the system does **not** claim,
and where possible it names what the consequence would be.
### 10.1 No adversarial-input hardening
| Not defended | Consequence | Evidence |
|---|---|---|
| **Adversarial images** (perturbation, steganographic payloads, malformed-but-parseable rasters) | the raster reader and the models process them; there is no adversarial-robustness layer and no claim of one | no such module exists; `docs/LIMITATIONS.md` |
| **Adversarial text** (prompt injection into the query) | the router is a closed-ontology classifier over six task classes and the planner is deterministic, so a query cannot select an arbitrary tool — but this is a **design property**, not a hardening claim, and it is `UNKNOWN — not established from the available evidence` whether it has been adversarially tested | `configs/base.yaml` `router.tasks`; `docs/MASTER_ARCHITECTURE_PLAN.md` §28 |
| **Content sanitisation beyond validation** | the upload path validates **size** and **content type**; it does *not* decode, inspect or sanitise the bytes | `gateway/assets.py`: *"It does not decode, validate, or inspect the image. A handle means 'these bytes were accepted under this content type at this time'"* |
| **Decompression-bomb protection** | the pixel budget (`image.max_pixels: 25000000`) is the only geometric bound; whether a small, highly-compressed raster that expands past the budget is refused *before* decoding is `UNKNOWN — not established from the available evidence` | `configs/base.yaml` |
| **Malicious `force_task` probing** | `force_task` bypasses the router by design (`docs/API_CONTRACT.md` §2.4); it does not bypass input validation, but it does let a caller select any served capability | `gateway/policy.py::validate_analyze_body` |
### 10.2 No rate-limit-based DoS protection claim
**The system does not claim to be protected against denial of service.** The limiter is a fairness control
(§5), and the owner ruling is explicit: *"**Do not size abuse protection on this limiter.**"* A caller
willing to vary one header produces no `429` at all (§5.3). The gateway's request-side boundary covers
**shape, size and content type** — *"Rate is not one of them."*
### 10.3 No content sanitisation beyond validation
The upload path accepts five declared content types and a byte cap. It stores the bytes and hands back a
handle. It does not scan, transcode, strip metadata or re-encode. The stored bytes are read later by the
raster reader inside the inference host, and any GeoTIFF metadata (including embedded geolocation) is
preserved by design — that preservation is a *feature* (the geospatial contract), not a sanitisation gap,
but it is worth naming as a property: **uploaded metadata is not stripped.**
### 10.4 No audit log
| Not present | Consequence |
|---|---|
| An audit log of who did what | there is no "who" — no auth, no users (§1.3) |
| A per-request persistent record | the gateway is stateless (`docs/DEPLOYMENT_ARCHITECTURE.md` §2.2) and the inference host's only retained state is the ephemeral asset store (§6) |
| Log retention policy | `*.log` is gitignored (`.gitignore`); server logs are the platform's |
| An intrusion-detection signal | none; a `429` is *"a fairness signal, not a security signal, and its ABSENCE is not evidence that no abuse occurred"* (§5.1) |
The gateway does log transport failures (`_log.error(..., exc_info=exc)`, §8.7) and the inference host logs
invalid requests and unhandled failures (`satquery.space` logger, §8.4). Those are **operational**
diagnostics, not an audit trail: they are not retained by the application, not queryable, and not
correlated to an identity.
### 10.5 No secrets management beyond environment variables
Credentials live in the platform's environment (`GITHUB_TOKEN` on Render; §2.3). There is no secret
manager, no rotation policy, no vault, and no per-request credential scoping. The single mitigation is that
the credential is **custodied at one tier and reported as a boolean** (§2.2, §2.6).
### 10.6 No cross-tenant isolation
There is no tenancy. `AssetStore` is a single process-wide store with a bounded capacity of 32 handles and
a 15-minute TTL. The handle *is* the isolation (§6.3): unguessable, so one client cannot reach another's
upload — but there is no ownership check, because there is no owner. If two clients hold each other's
handles (e.g. through a leak outside this system), each can use the other's upload until it expires.
### 10.7 No CI-verified security scanning
The release tooling includes manifest and checksum generators (`tools/generate_release_manifest.py`,
`tools/verify_archive.py`, `tools/hf_verify.py`) but **no security scanner, dependency auditor or secret
scanner is configured in a CI pipeline**, and no CI configuration was verified for this release. The
secret discipline in §11 was enforced by an **ad-hoc scan performed during the release**, not by a
standing pipeline. Whether a CI pipeline exists in the private deployment repositories is
`UNKNOWN — not established from the available evidence`.
### 10.8 Summary table
| Control | Claim | Status |
|---|---|---|
| CORS allowlist | enforced on request **and** response legs | `VERIFIED` (§3) |
| Body-size cap | enforced while reading, at both layers | `VERIFIED` (§4.4) |
| Per-file cap | one variable, two strict parsers, startup-validated | `VERIFIED` (§4.5) |
| Content-type allowlist | closed list of five; absent type refused | `VERIFIED` (§4.6) |
| Pixel/tile budget | frozen in config | `IMPLEMENTED` (deployment enforcement `UNKNOWN`, §4.3) |
| Per-IP rate limit | fairness only | `MEASURED` (§5) |
| Upload fail-closed | `503` unless both variables set | `VERIFIED` (§6.1) |
| Handle opacity | 128-bit `secrets.token_hex(16)` | `VERIFIED` (§6.3) |
| Path disclosure in errors/trace | scrubbed to basename | `VERIFIED` (§8.4, §8.5) |
| No inbound path to inference host | outbound tunnel | `MEASURED` (§9) |
| Authentication | **absent by design** | `REJECTED` (§1.3) |
| DoS protection | **not claimed** | `REJECTED` (§10.2) |
| Audit log | **not present** | `OPEN` (§10.4) |
| CI security scanning | **not configured** | `NOT RUN` (§10.7) |
---
## 11. Release-side security discipline: no secrets in any published file
### 11.1 The rule
> **NO SECRETS in any published file.**
The release publishes to a public GitHub repository (`Anish-lab-blip/SatQuery-AI`) and a public Hugging
Face model repository (`thundercode/SatQuery`). Publishing changes the threat model: a credential in a
published file is a credential disclosed, and a documentation set written from the inside is the most
likely place for one to appear by accident.
The release manifest states the exclusion as a property of the artifact set
(`RELEASE_MANIFEST.md` §"What this release deliberately does NOT contain"):
> - **Backbone weights.** They are fetched from the Hugging Face Hub, pinned by revision.
> - **Secrets.** No tokens, keys, or environment files.
> - **The private deployment repositories.** Their sources are not published here.
> - **Datasets.** Acquisition procedures are documented; the data is not redistributed.
> - **A licence file.** None has been selected yet — this is an OPEN item.
The manifest is **generated from disk, never typed** (`RELEASE_MANIFEST.md` header:
*"Generator: `release/tools/generate_release_manifest.py` (computed from disk, never typed)"*), and it lists
all **42** files with their byte sizes and sha256 digests — so a reviewer can verify the published set
independently rather than trusting a description of it.
### 11.2 The scan that enforces it
The discipline is enforced and verified by a **regex scan across every markdown file** in the release. The
scan looks for credential-shaped strings — the Hugging Face token prefix (`hf_…`), GitHub personal-access
token prefixes (`ghp_…`, `github_pat_…`), and the standard provider-key shapes — and reports any match as a
release blocker. The scan is a **release-time gate**, not a runtime control: its scope is the published
file set, and it is run against the files as they will be published.
**What this establishes:** no file in the published set contains a credential-shaped string. **What it does
not establish:** that no secret is *derivable* from the published set (e.g. a non-secret value that
narrows a credential search space), and it does not scan the private deployment repositories, which are not
published. Those are
`UNKNOWN — not established from the available evidence`.
### 11.3 The Hugging Face release's own secret statement
`HF_RELEASE_VERIFICATION.md` §8 records the same property for the model repository, and it names the token
handling explicitly:
> **No secret was uploaded.** The uploaded set is: the model card, the manifest, the checksums, the 11
> docs, and the six weight files. No tokens, keys, environment files, or credentials exist in any uploaded
> file. The token used for the upload is **not** written into any released file.
The verification document also records the write-permission check that preceded the upload, which read the
token's own scopes from `GET /api/whoami-v2` and confirmed `repo.write` scoped to the user — *"Verified
**before** uploading"* — rather than discovering a permission problem mid-upload.
### 11.4 The temporary token file used during the push was deleted
The release process used a temporary token file to authenticate the push. That file was **deleted** after
the push completed, and it is not part of the published set. This matters because a token file left on
disk in a directory that a later `git add -A` (or an archive build) could sweep up is a common accidental
disclosure — and the release's archive tooling excludes secret/token files explicitly
(`docs/REPRODUCIBILITY.md` §10: *"The archive **excludes** secret/token files, OS junk, virtualenvs"*).
**Honest limit:** the deletion is a **release-process fact**, and the published evidence for it is this
statement rather than a scanner report — no file named in the manifest is a token file, which is consistent
with the deletion, but the manifest cannot prove a negative about a file that no longer exists. The
strongest available evidence is that (a) the scan in §11.2 finds no credential-shaped string in any
published file, and (b) the 42-file manifest contains no environment file, no `.env`, and no credential
file.
### 11.5 This document's own discipline
This document obeys the same rule it describes. It contains:
- **no credential, token, key or password, and no path to a credential file** — every secret is described
by *where it lives*, never by its value (the pattern stated in
`docs/architecture/02-deployment-topology.md` §2.7: *"Every secret is described by *where it lives*,
never by its value."*);
- **no absolute filesystem path** from the authoring host — the paths quoted in §8 are the ones the
project's own documents quote as *examples of what was scrubbed*, and they are reproduced here as
evidence of the defect, not as current configuration;
- **no internal hostname beyond the publicly reachable endpoints** already published in
`CURRENT_RELEASE_STATE.md` and `docs/DEPLOYMENT.md` (the Cloudflare Pages origin and the Render host).
The one place where a reader might expect a value and find none is the live configuration (§2.3): the
document names the **variables** that are set and reports the token as a boolean, because that is exactly
what the live health endpoint publishes.
### 11.6 What the release does NOT include, and why
| Excluded | Reason | Evidence |
|---|---|---|
| Backbone weights (MiniLM, SmolVLM, RemoteCLIP, CROMA) | fetched from the Hub, pinned by revision | `RELEASE_MANIFEST.md`; `configs/base.yaml` revisions |
| Secrets / environment files | §11.1 | `RELEASE_MANIFEST.md` |
| Private deployment repositories | their sources are not published | `RELEASE_MANIFEST.md` |
| Datasets | acquisition documented, data not redistributed | `RELEASE_MANIFEST.md`; `docs/DATASETS.md` |
| A `LICENSE` file | none selected yet — **OPEN** | `RELEASE_MANIFEST.md`; `CURRENT_RELEASE_STATE.md` §6 |
The **no-LICENSE** item is `OPEN` and is recorded in three places
(`RELEASE_MANIFEST.md`, `CURRENT_RELEASE_STATE.md` §6, and the style guide's facts table). It is a
**legal** rather than a security item, but it is named here because a public release with no licence is an
ambiguity about what others may do with the code, and a reader of a security chapter should not have to
discover it elsewhere.
---
## 12. Reporting a vulnerability
SatQuery AI is a research prototype released publicly, with **no authentication and no user data**. The
most useful reports are those that identify a path by which a client can reach something the contract says
it cannot — for example a filesystem path, a credential, an internal host, or another client's upload.
### 12.1 The contact
**Security contact: `UNKNOWN — not established from the available evidence`.**
**This section requires an owner-supplied contact address.** No security contact, disclosure policy or
`SECURITY.md` contact has been established for this project, and inventing one would be exactly the kind of
fabrication the release's grounding rules forbid. Until an owner supplies a contact, the honest statement
is that **there is no published vulnerability-reporting channel**, and the recommendation is:
> **Owner action required.** Provide a security contact (a dedicated address or an issue-tracker URL) and
> a disclosure expectation. This document will be updated to name it. Until then, treat the row above as
> the accurate state: no channel is published.
### 12.2 What a report should contain, once a channel exists
The reporting structure below is a recommendation grounded in the artefacts this document has described —
each item maps to a piece of evidence the maintainer can reproduce:
| Field | What to provide | Why it maps to a real artefact |
|---|---|---|
| Affected tier | frontend / orchestrator / inference host / model host | the four tiers are distinct deployables (§1.1) |
| Endpoint and method | e.g. `POST /api/infer` | the orchestrator route list is published (`docs/DEPLOYMENT_TOPOLOGY.md` §3.2) |
| `request_id` | the value from the error envelope | the gateway generates and echoes `X-Request-Id` and the envelope carries `request_id` (`docs/API_CONTRACT.md` §5) |
| `run_id` | the value from the response, if the request succeeded | the server always echoes a `run_id` (`docs/API_CONTRACT.md` §2.4) |
| Error `code` | the value from the envelope | the taxonomy is closed and published (`docs/API_CONTRACT.md` §5.2) |
| Reproduction | minimal steps, with the request body | — |
| Expected vs observed | what the contract promises vs what happened | `docs/API_CONTRACT.md` is the contract |
The `request_id` is the single most useful field: it is the correlation key the gateway generates, injects
and echoes (§7.6), and it is present in the log line the gateway writes for a transport failure (§8.7).
### 12.3 What is already known and documented
A reporter should read the following before filing, because each is a **documented, accepted limitation**
rather than a new finding:
| Documented limitation | Where |
|---|---|
| The rate limiter is a fairness control, not a security control; a varied `X-Forwarded-For` produces no `429` | §5; `docs/DEPLOYMENT_ARCHITECTURE.md` §5.2 |
| The body cap's `Content-Length` check is declarative; the streaming check is the enforced one | §4.4; `docs/DEPLOYMENT_ARCHITECTURE.md` §4 |
| A misconfigured asset root answers `500 text/plain` on the inference host's own URL | §6.10; `docs/DEPLOYMENT_ARCHITECTURE.md` §5.1.1 |
| `change_vqa.artifact_dir` is a configured-but-inert key | §13 (F-17); `docs/DEPLOYMENT_ARCHITECTURE.md` §5.6 |
| The trace's registry block is a snapshot of the *previous* request | §13 (F-19); `docs/DEPLOYMENT_ARCHITECTURE.md` §5.8 |
| B-07: transient tunnel gaps; patch prepared, not deployed | §9.5; `CURRENT_RELEASE_STATE.md` §6 |
| No auth, by design | §1.3; `docs/API_CONTRACT.md` §7 |
---
## 13. Open, blocked and not-run items
Every item below is a security-relevant state that is **not closed**. None is presented as fixed.
| ID | Item | State | Detail |
|---|---|---|---|
| **B-07** | Transient tunnel-agent gaps → a request can hang or return `504` (`tunnel_offline` / wake timeout) | **OPEN** | patch **prepared, NOT deployed**; measured root shape: in `auto` mode a tunnel timeout falls through to the forward path, burning `wake_timeout_s=120` on a `302` (`CURRENT_RELEASE_STATE.md` §6) |
| **B-02** | `/api/health` `codespace_name` carries a trailing `\n` | **OPEN (cosmetic)** | the wake path strips it (`_codespace_name()`); only the health payload reports the raw value; confirmed still live 2026-09-25 |
| **Licence** | No `LICENSE` file exists | **OPEN** | `RELEASE_MANIFEST.md`; `CURRENT_RELEASE_STATE.md` §6 |
| **F-17** | `change_vqa.artifact_dir` is a configured-but-inert key — advertised, never read, no warning | **OPEN** | severity low; *"documented, not patched"*; two independent checks agree (the attribute occurs once as an assignment; the module contains no file-writing code) — `docs/DEPLOYMENT_ARCHITECTURE.md` §5.6 |
| **F-19** | The trace's registry block is a snapshot of the *previous* request | **OPEN** | observability only; no result, disclosure or availability claim depends on it; *"documented, not patched. No guard added"* — `docs/DEPLOYMENT_ARCHITECTURE.md` §5.8 |
| **F-12 / F-12b** | A misconfigured asset root, and framework 404/405, answer non-envelope bodies **on the inference host's own URL** | **OPEN (bounded)** | *"a client that goes through the gateway never sees it"*; *"Apply the fix with the deployment work, not before it"* — `docs/DEPLOYMENT_ARCHITECTURE.md` §5.1.1 |
| **F-16c** | A no-change run on a deployment that configures `change.artifact_dir` now reports `degraded: true` | **OPEN** | *"a signalling change, not a disclosure"*; the shipped configuration is unaffected; seam `core/schemas.py::_task_output_consistency` — `docs/DEPLOYMENT_ARCHITECTURE.md` §5.5 |
| **F-11** | The two `503` causes on `/v1/assets` (unconfigured vs full) remain indistinguishable | **OPEN** | the diagnostic that would have separated them was removed because nothing read it — `docs/DEPLOYMENT_ARCHITECTURE.md` §5.1 |
| Security contact | No published vulnerability-reporting channel | **OPEN** | §12.1 — requires an owner-supplied contact |
| CI security scanning | No scanner or auditor in a verified pipeline | **NOT RUN** | §10.7 |
| Adversarial-input testing | None performed | **NOT RUN** | §10.1 |
| Audit log | Not present | **OPEN** | §10.4 |
| Pixel-budget enforcement on the deployed host | Not probed | **UNKNOWN** | §4.3 |
### 13.1 Items recorded as RESOLVED, so the fix is not re-litigated
| ID | Item | State |
|---|---|---|
| F-2 | CORS response-leg bypass | **RESOLVED** (2026-09-22) — prefix filter + pinned assertion (§3.5) |
| F-3 | Framework 404/405 lacked the envelope on the gateway | **RESOLVED** (2026-09-22) (§8.3) |
| F-5 | Rate limiter is not a protection control | **RESOLVED** (ruled 2026-09-23) — documentation ruling; no code change (§5) |
| F-6 | Gateway body cap was declarative | **RESOLVED** — streaming reader (§4.4) |
| F-7 | One variable, two parsers | **RESOLVED** — both refuse non-positive/unparsable, naming the variable (§4.5) |
| F-9 | Inference host buffered the whole body before the cap | **RESOLVED** — shared reader (§4.4) |
| F-13 | `trace.inputs` echoed a path | **RESOLVED** — `_asset_label` basename reduction (§8.5) |
| F-14 | `trace.steps[PARSE].detail["inputs"]` echoed the same path | **RESOLVED** — one-line reuse of `_asset_label` (§8.5) |
| F-15 | A construction failure's exception string reached client fields | **RESOLVED** — `scrub_paths` basename reduction at four carriers (§8.4) |
| F-15c | A transport failure's raw exception text was published | **RESOLVED** — MRO-classification mapping (§8.7) |
| F-16 | `artifact_ref` carried a filesystem path where the contract promised a URI | **RESOLVED** — `null` + non-retrievable warning, **both** carriers (§8.6) |
| F-18 | §5.3–§5.8 sat after §8 | **RESOLVED** (2026-09-23) — sections moved; ordering frozen |
| F-11 | `AssetStore.stats()` and its counters were computed and read by nothing | **RESOLVED** — removed rather than given a consumer; **the ambiguity it would have separated remains** (§6.2) |
---
## 14. Evidence index
### 14.1 Source files read for this chapter
| File | What it establishes here |
|---|---|
| `gateway/app.py` | the ASGI layer: allowlists, `_proxy`, the CORS assertion, transport classification, `_read_body_bounded` |
| `gateway/policy.py` | `GatewayConfig` validation, the admit ladder, `build_cors_headers`, `RateLimiter`, `translate_error`, `validate_analyze_body`, `response_headers` |
| `gateway/assets.py` | the ephemeral store: `read_body_bounded`, opaque handles, `_SUFFIXES`, `put`/`get`/`sweep`, `to_response` |
| `app/space_app.py` | the inference host: `_asset_store_available`, the `503` refusal, the handle→path translation, the exception handlers |
| `deploy/render/main.py` | the orchestrator: `_allowed_origins`, `_DEV_ORIGINS`, `_PRODUCTION_ORIGINS`, the health payload, `_proxy` |
| `deploy/render/codespaces.py` | the GitHub Codespaces API client (`GITHUB_TOKEN` as a Bearer token) |
| `core/errors.py` | the 23-code taxonomy, `SatQueryError`, `scrub_paths` |
| `configs/base.yaml` | `image.max_pixels: 25000000`, `image.max_tiles: 64`, the frozen task list, `agent.timeout_seconds: 120` |
| `.gitignore` | the credential-shaped exclusions (`kaggle.json`, `.kaggle/`, `.deploy/`, `*.log`, weights, data) |
| `docs/DEPLOYMENT_ARCHITECTURE.md` | §1.1 the boundary argument; §2 the responsibility table and `must NOT do` list; §2.3 error translation; §3.3 entrypoint requirements; §4 the env-var vocabulary and the F-6 note; §5 the failure-mode table and §5.1–§5.8 findings |
| `docs/API_CONTRACT.md` | §2.4 the request shape; §2.5 the upload endpoint and its three guarantees; §5 the envelope and status map; §5.2 the taxonomy; §5.3 the gateway-origin code; §6 quotas; §7 authentication; §8 status |
| `docs/DEPLOYMENT_TOPOLOGY.md` | the measured live configuration (header note); §2 the tunnel; §3 the per-tier responsibilities; §4 the closed blockers; §5 the reconciliation |
| `docs/FINAL_DELIVERY_REPORT.md` | the deployed topology and the `deploy/`-is-stale warning |
| `.workbuddy-ai/scratch/live_validation/LIVE_VALIDATION_POSTFIX.md` | the three live passes (behavioural evidence, §9.5 context) |
### 14.2 Release documents this chapter links to
| Document | Role |
|---|---|
| [`architecture/02-deployment-topology.md`](architecture/02-deployment-topology.md) | the deployment topology and the backend-contract reference (§1.1, §2, §3, §4, §5 of `DEPLOYMENT_ARCHITECTURE.md`) |
| [`architecture/08-api-contract.md`](architecture/08-api-contract.md) | the deep API contract (the `/v1/*` surface, the envelope, the taxonomy) |
| [`architecture/10-observability-and-ops.md`](architecture/10-observability-and-ops.md) | failure modes, the wake flow, operator procedures |
| [`DEPLOYMENT.md`](DEPLOYMENT.md) | the deployment guide and the platform traps |
| [`LIMITATIONS.md`](LIMITATIONS.md) | the consolidated limitation list (B-07, B-02, the licence item) |
| [`EVALUATION.md`](EVALUATION.md) | the live-validation record and the model-quality verdicts |
| [`REPRODUCIBILITY.md`](REPRODUCIBILITY.md) | how to reproduce the tests and a live run; the archive exclusions |
| [`architecture/07-configuration-freeze.md`](architecture/07-configuration-freeze.md) | the frozen config and `Config.hash == 78f1e3700da15aa1` |
### 14.3 Where the security evidence physically lives
| Evidence | Location |
|---|---|
| The three live validation passes (raw + recomputed) | `.workbuddy-ai/scratch/live_validation/` — `run_output.txt`, `run_final2.txt`, `run_final3.txt`, `results_final.json`, `results_pass3.json`, `LIVE_VALIDATION_POSTFIX.md` |
| The verdict recomputation tool | `.workbuddy-ai/scratch/recompute_verdicts.py` |
| The deployed-head verification | `.workbuddy-ai/scratch/verify_deployed_head.py` |
| The undeployed B-07 patch | `.workbuddy-ai/scratch/deployed-backend/fix-b07-forward-unavailable.patch` |
| The release manifest and digests | `RELEASE_MANIFEST.md` (42 files, sha256 per file) |
| The Hugging Face verification | `HF_RELEASE_VERIFICATION.md`; `tools/hf_verify_report.txt` |
### 14.4 Final statement of posture
SatQuery AI v1 is a **public, unauthenticated research prototype**. Its security posture is narrow and
deliberate:
1. **One credential, at one tier, never sent to a browser.** The gateway holds it; the health endpoint
reports it as a boolean (§2).
2. **A hard CORS allowlist, enforced on both legs.** Never `*`; refused at startup if misconfigured (§3).
3. **Size and content-type limits that are enforced, not declared.** A streaming reader at both layers
bounds memory regardless of what the client claims (§4).
4. **A rate limiter that is honestly labelled a fairness control**, because the measurement shows it can
be defeated by one header (§5).
5. **An upload endpoint that fails closed**, whose only access control is an unguessable handle (§6).
6. **An error contract that publishes classifications, not internals** — no paths, no stack traces, no
third-party exception text (§8).
7. **No inbound path to the inference host**, because the transport dials out (§9).
8. **No claim of protection against adversarial input, denial of service, or abuse**, because no such
control exists (§10).
The gaps in §13 are the honest boundary of that posture. Where the project could not establish a fact, this
document says so rather than filling it in.
|