HTTP REST Fundamentals Weapon

http-rest-fundamentals Weapon

Procedural arsenal for http-rest-fundamentals-guardian, the HTTP and REST protocol authority in the Legion AI Army.

This weapon encodes the practical reference material needed to audit HTTP and REST usage authoritatively against RFC semantics. It is organized around eight concern areas, each with its own guide, plus templates for common deliverables and worked examples for the most frequently misunderstood scenarios.

Paired Angel: ai-tools/agents/http-rest-fundamentals-guardian.md Command Brief: ai-tools/command-briefs/http-rest-fundamentals-guardian-command-brief.md

First action when this weapon is loaded

Read these in order before doing anything:

1. guides/00-principles.md -- RFC-first reasoning model; safety vs idempotency; the seven REST constraints; why "RESTful" is usually a lie. This is the foundation every other guide builds on.
2. guides/10-failure-modes.md (if it exists; otherwise check reports/README.md) -- the catalog of common HTTP anti-patterns and their impact classifications.
3. The guide most relevant to the current task (see index below).

Then pick the appropriate template from templates/ for the deliverable the Angel is producing.

Guide index

Template index

Example index

Critical directives (lifted from Command Brief)

• Cite the RFC section for every status-code and method ruling. Why: RFC citations are the only way the developer can verify the ruling and learn the underlying principle.
• Never conflate HTTP-layer correctness with framework convention. Why: frameworks sometimes diverge from RFC semantics for DX reasons; the distinction matters for interoperability.
• Flag CORS wildcard-with-credentials as Critical, not Informational. Why: this misconfiguration is exploitable by cross-origin attackers.
• Do not audit authentication tokens, JWTs, or session cookies -- hand off to auth-guardian. Why: boundary prevents duplicate findings.
• Do not audit TLS, cipher suites, or certificate validity -- hand off to devops-guardian. Why: same boundary rationale; this weapon stays at the application layer.

Key research signals (from scripture-historian, 2026-05-20)

The following findings from the research sweep are high-signal for this weapon:

• HTTP/3 split reality: CDN users (Cloudflare, Fastly, Akamai) get HTTP/3 transparently at the edge. Self-hosted origins must configure QUIC explicitly (nginx 1.25+, Caddy, Envoy). Node.js, Go stdlib, Python stdlib, and Ruby have no first-class HTTP/3 as of 2026.
• CORS triple-wildcard prohibition: Access-Control-Allow-Origin: * is forbidden in combination with Access-Control-Allow-Credentials: true. The browser throws immediately. The wildcard also applies to Access-Control-Allow-Methods: * and Access-Control-Allow-Headers: * -- those too are rejected when credentials are involved in some browsers.
• RFC 9110 renamed 422: "Unprocessable Entity" is now officially "Unprocessable Content" per RFC 9110. The status code number is unchanged.
• RFC 9457 is current for error bodies: application/problem+json format (RFC 9457, superseding RFC 7807) is the standard for structured error responses.
• Auth-before-CORS gotcha: OPTIONS preflights arrive without credentials. Any middleware that requires authentication before CORS headers are set will reject preflights with 401, breaking CORS for all non-simple requests.
• ETag + CDN: ETags are often stripped or rewritten by CDNs unless explicitly preserved. Audits should check whether ETags survive the CDN layer.

Folder layout

http-rest-fundamentals-weapon/
+- SKILL.md                           (this file -- master index)
+- README.md                          (one-page human overview)
+- guides/
|  +- 00-principles.md                (RFC-first reasoning; safety/idempotency; REST constraints)
|  +- 01-http-methods.md              (method semantics and the safety/idempotency table)
|  +- 02-status-codes.md              (status-code honesty audit with decision trees)
|  +- 03-headers.md                   (caching, content negotiation, security-adjacent headers)
|  +- 04-cors.md                      (preflight flow; wildcard-with-credentials; caching preflight)
|  +- 05-conditional-and-range.md     (ETag; If-None-Match; Range; 304/412/416)
|  +- 06-http2-http3.md               (HTTP/2 multiplexing; HTTP/3 QUIC; Alt-Svc; 0-RTT)
|  +- 07-rest-vs-rpc.md               (Fielding constraints; HATEOAS; versioning)
+- examples/
|  +- cors-correct-vs-incorrect.md    (side-by-side CORS configurations)
|  +- status-code-audit.md            (full status-code audit walkthrough)
|  +- http3-readiness-assessment.md   (HTTP/3 readiness for typical stack)
+- templates/
|  +- findings-report.md              (audit output template)
|  +- status-code-matrix.md           (status code decision matrix)
|  +- cors-decision-tree.md           (CORS policy design + diagnosis)
|  +- rest-checklist.md               (REST architectural compliance checklist)
+- reports/
|  +- README.md                       (how audit reports accumulate)
+- research/                          (populated by scripture-historian -- do not modify)
   +- research-plan.md
   +- research-summary.md
   +- index.md
   +- internal/                       (7 RFC + spec source notes)
   +- external/                       (12 web research source notes)

Forged by weapon-forge from http-rest-fundamentals-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.