gori AGENTS.md

AGENTS.md: working on gori

gori is an intercepting proxy and workbench for authorized security testing, written in Crystal and shipped as one binary. It sits in the loop between a client and its target, capturing every request and response as a flow you can intercept, replay, fuzz, and scan across HTTP/1.1, HTTP/2, WebSocket, gRPC, and SSE.

Three entry points, one engine layer underneath: gori (TUI), gori mcp (stdio JSON-RPC for agents), gori run <sub> (headless, for scripts).

This file is the short version, and it is the whole contract for a change that stays inside one subsystem. DESIGN.md is the long one, and its numbering is load-bearing: source comments cite principles as (P4), (P6/P7) and sections as DESIGN.md §4.

• Changing behavior? Read Invariants below first — those three are what changes get wrong.
• Committing? House rules has the commit, CHANGELOG and pre-commit checklist.
• Adding a subsystem? DESIGN.md, then back here.

Invariants: three things not to get wrong

1. Malformed input is the payload (P7)

A security proxy that sanitizes its operator's bytes is broken. The captured wire bytes are canonical; parsed columns and pretty views are derived projections.

• There is no stdlib HTTP::Request parsing anywhere on the proxy path. src/gori/proxy/codec/http1.cr is a byte-exact sans-IO codec: it flags malformed? and keeps the octets rather than rejecting. serialize_head is the identity function.
• The axis is provenance, not byte values. The same octet gets three different answers:
  • operator bytes (imported HAR, an MCP raw request, a replay) go out verbatim, never sanitized. See the comment at src/gori/import/builder.cr:31-38 and src/gori/mcp/request_builder.cr (normalize_raw).
  • page-authored bytes (a crawled <a href>) get percent-encoded where they merely break, and refused where they frame. See src/gori/discover/url.cr (encode_unsafe).
  • remote-chosen bytes (a redirect Location) are refused outright, not repaired. See src/gori/fuzz/engine.cr (redirect following).
• The predicate has one home: Codec::Http1.request_token_safe?. Do not re-derive it next to a new caller; that exact shape has already recurred three times (#390, #394, #397).
• Request framing rejects any obfuscation (obfuscated_header?); response framing is deliberately narrower (framing_ambiguous?, and read the comment above it). Do not "symmetrize" them: a request's peer is the operator's own browser, a response's peer is the whole internet.