docs/SECURITY.md

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 §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
• 1. Scope, trust model and explicit non-goals
• 2. Secret custody
• 3. CORS: the allowlist rule
• 4. Size and resource limits
• 5. Rate limiting is a FAIRNESS control, not a security control
• 6. The /v1/assets endpoint: fail-closed behaviour and the handle-as-capability
• 7. Input validation and modality inference
• 8. The error-translation contract: what may reach a client
• 9. The outbound tunnel: no inbound firewall hole
• 10. What is explicitly NOT defended against
• 11. Release-side security discipline: no secrets in any published file
• 12. Reporting a vulnerability
• 13. Open, blocked and not-run items
• 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

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):

"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:

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):

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."

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__):

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:

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:

_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:

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:

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):

# 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):

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):

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):

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:

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):

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):

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):

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):

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):

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:

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):

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):

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):

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):

_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):

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):

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):

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:

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"})

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:

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:

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):

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):

_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):

{
  "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:

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).

_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:

-                "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:

_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:

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

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	the deployment topology and the backend-contract reference (§1.1, §2, §3, §4, §5 of DEPLOYMENT_ARCHITECTURE.md)
architecture/08-api-contract.md	the deep API contract (the /v1/* surface, the envelope, the taxonomy)
architecture/10-observability-and-ops.md	failure modes, the wake flow, operator procedures
DEPLOYMENT.md	the deployment guide and the platform traps
LIMITATIONS.md	the consolidated limitation list (B-07, B-02, the licence item)
EVALUATION.md	the live-validation record and the model-quality verdicts
REPRODUCIBILITY.md	how to reproduce the tests and a live run; the archive exclusions
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.