radioactive 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db78ab47dc98a9125d0dde9cb3ec17e95b83cafc3fae5922fa3f48cbcb85f0f2
+  data.tar.gz: 8da7cf85d58c94bab1a13466ef7a236b24a2da1d6e021835bd5bf959b690d38c
+SHA512:
+  metadata.gz: 594fcc7d8f2f3d670154b11d9d0194df8f9fe2da2e8d4eadf222516cb76b6b1d82ac70214e873ccdaaf9947f95f0ca6012aba1079ee8942e25ad50845b2035be
+  data.tar.gz: 35ee0b007e1e41807b9376d80c1e98d6b933af4388b8e4dae0aef6d5dc451d6ec0f012284619d9390cb4f055db82a5efce4199f73220df2ba8c26680a5006331

data/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-05-04
+
+Tooling and documentation only. No runtime behavior changes.
+
+### Changed
+
+- Gem build / install / release rake tasks moved from the top-level namespace
+  to `gem:`, matching the project's `lint:` / `types:` / `security:` pattern.
+  Use `rake gem:build`, `rake gem:install`, `rake gem:release[remote]`.
+
+### Fixed
+
+- RBS signatures for three Fetcher constants/methods added in 0.1.0 were
+  missing from `sig/radioactive.rbs` (`NUMERIC_ONLY_HOST`, `HEADER_INVALID_CHAR`,
+  `Fetcher#canonicalize_host`). Caught by Steep on first run of `rake types:check`
+  after the security hardening landed.
+
+### Documentation
+
+- New Releasing section in the README covering pre-flight checks, the
+  `rake gem:release` flow, and a pointer to RubyGems Trusted Publishing
+  for stronger publishing setups.
+
+## [0.1.0] - 2026-05-04
+
+Initial release.
+
+### Added
+
+- `Radioactive.fetch(url, **opts)` returning a frozen
+  `Result(url, final_url, status, headers, body, hops)`.
+- `Radioactive.open(url, **opts)` returning a `StringIO`; with a block, streams
+  the body chunk-by-chunk to a `Tempfile` so peak memory stays at ~16 KB
+  regardless of `max_size`.
+- `Radioactive::Fetcher` class for reusable per-instance configuration.
+- 14 configuration options: `schemes`, `max_size`, `open_timeout`,
+  `read_timeout`, `total_timeout`, `max_redirects`, `accept_encoding`,
+  `user_agent`, `private_ranges`, `allow_private`, `allow_credentials`,
+  `headers`, `resolver`, `clock`.
+- Distinct `Radioactive::Error` subclasses for every failure mode:
+  `SchemeError`, `AddressError`, `TimeoutError`, `SizeError`, `RedirectError`,
+  `EncodingError`, `ResponseError` (the last carrying `#status`, `#headers`,
+  `#body` for partial response data).
+- RBS signatures in `sig/radioactive.rbs`, validated by `rake types:validate`
+  and type-checked against the implementation by `rake types:check` (Steep).
+
+### Security
+
+Defenses on by default with zero configuration:
+
+- **SSRF address blocklist.** 25 CIDR ranges blocked: RFC1918, loopback,
+  link-local (incl. cloud metadata at `169.254.169.254`), CGNAT, IPv6 ULA,
+  IPv6 link-local, multicast, TEST-NET, Teredo, and reserved ranges.
+- **DNS rebinding defense.** Hostname is resolved once; the resolved IP is
+  pinned via `Net::HTTP#ipaddr=`; SNI and certificate verification still use
+  the original hostname.
+- **Strict dual-A rejection.** If *any* resolved address falls in a forbidden
+  range, the request is refused (defeats split-horizon SSRF tricks).
+- **Redirect re-validation.** Every redirect target is re-run through the full
+  pipeline (scheme, credentials, DNS, address check) before the next request.
+- **Scheme allowlist.** Default `%w[http https]`; `file://`, `gopher://`,
+  `javascript:`, etc. are rejected.
+- **Embedded-credential rejection.** URLs with `userinfo` are refused unless
+  `allow_credentials: true` is set explicitly.
+- **Non-canonical IP rejection.** `http://2130706433/` (decimal) and
+  `http://0x7f000001/` (hex) hosts are rejected outright rather than relying
+  on resolver behavior.
+- **Header CRLF/NUL injection rejection.** Caller-supplied header names and
+  values containing `\r`, `\n`, or `\0` are refused before the socket opens.
+- **Slowloris and stall defenses.** `read_timeout` per chunk; `total_timeout`
+  applied as a wall-clock deadline across all redirects, with per-operation
+  timeouts clamped to remaining budget.
+- **Response and decompression bombs.** `max_size` enforced per chunk on the
+  raw socket; `Content-Length` exceeding `max_size` rejected before any body
+  is read; default `Accept-Encoding: identity` rejects compressed responses;
+  opt-in `gzip` decompression bounded by **decoded** byte count.
+- **TLS verification.** `OpenSSL::SSL::VERIFY_PEER`, no opt-out.

data/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem is
+
+Radioactive is a hardened HTTP fetcher for URLs supplied by untrusted users — a near drop-in alternative to `URI.open` for link previews, image proxying, webhook delivery, and metadata extraction. It defends against the SSRF and DoS classes that `URI.open` leaves open (cloud-metadata exfiltration, RFC1918 access, DNS rebinding, slowloris, response/decompression bombs, redirect chains into private addresses, disallowed schemes).
+
+**The spec is `docs/REQUIREMENTS.md` and it is authoritative.** Read it before designing or changing behavior; threat model, public API, defaults, error hierarchy, and explicit non-goals all live there. This file only summarizes things that constrain *how* you write code.
+
+## Status
+
+The scaffold from `bundle gem radioactive` is still mostly untouched: `lib/radioactive.rb` defines only the module and a base `Error` class, `test/test_radioactive.rb` contains the generator's failing `assert false`, and the gemspec metadata (`summary`, `description`, `homepage`, `allowed_push_host`, `source_code_uri`, `changelog_uri`) is still TODO placeholders. Implementation work is greenfield — match the API surface in `docs/REQUIREMENTS.md` rather than inventing one.
+
+Note: the parent directory `/Users/pablo/code/posiczko/CLAUDE.md` documents a different project (Ougai). It does not apply here — Radioactive uses Minitest (not RSpec), Standard (not RuboCop directly), and has no Oj/JrJackson dependency.
+
+## Architectural constraints (from the spec)
+
+These are non-negotiable design choices in `docs/REQUIREMENTS.md`. Don't propose changes that violate them without flagging the spec change first:
+
+- **No global state, no `Radioactive.configure`.** Configuration is per-call or per-`Fetcher` instance. This is explicit in the spec to keep tests sane and avoid cross-tenant leaks.
+- **`Net::HTTP` only.** No Faraday, HTTParty, `http.rb`, HTTP/2, HTTP/3, or gRPC. Use `Net::HTTP.start` directly — not `URI.open` — so timeouts and chunked reads are first-class.
+- **GET only in v1.** No POST/PUT/DELETE. No WebSocket/SSE.
+- **No outbound proxy support in v1**, no connection pooling, no HTTP caching, no retries, no circuit breakers, no MIME sniffing.
+- **TLS:** system trust store is authoritative. `verify_mode = VERIFY_PEER` and there is no option to disable it. No TLS pinning, CT, or mTLS.
+- **DNS pinning preserves SNI.** Resolve once via the injected `resolver`, validate every resolved address against `private_ranges`, then connect via `http.ipaddr = ip` while leaving `http.address` as the hostname so SNI and cert verification still work. Re-resolve and re-validate on every redirect (defeats DNS rebinding TOCTOU).
+- **Strict address check:** if *any* resolved address is in a forbidden range, reject — defeats dual-A-record SSRF.
+- **Size enforcement is on the raw socket reader**, not after decompression. Default `Accept-Encoding: identity`; compression is opt-in. Per-chunk size check (16 KB chunks); also reject when `Content-Length` exceeds `max_size` *before* reading the body.
+- **All failures raise distinct subclasses of `Radioactive::Error`** so callers can rescue the base class and degrade gracefully. The hierarchy (`SchemeError`, `AddressError`, `TimeoutError`, `SizeError`, `RedirectError`, `EncodingError`, `ResponseError`) is fixed by the spec — don't invent new top-level error classes.
+- **`Result` is a frozen `Data.define(:url, :final_url, :status, :headers, :body, :hops)`.** Don't change the shape; downstream code pattern-matches on it.
+- **Inject `resolver` and `clock`** rather than calling `Resolv` / `Process.clock_gettime` directly inside fetch logic — the spec calls these out as test seams.
+- **Sockets close on every exit path**, success or raise. No leaking connections.
+
+## Commands
+
+- `bin/setup` — install dependencies (wraps `bundle install`).
+- `bin/console` — IRB session with the gem preloaded.
+- `bundle exec rake` — default task: runs `test` then `standard` (lint). Both must pass.
+- `bundle exec rake test` — Minitest suite (driven by `Minitest::TestTask`, picks up `test/**/test_*.rb`).
+- `bundle exec rake test TESTOPTS="--name=/pattern/"` — run a single test or matching subset.
+- `ruby -Ilib -Itest test/test_radioactive.rb` — run one test file directly without rake.
+- `bundle exec rake standard` / `bundle exec rake standard:fix` — lint / autofix.
+- `bundle exec rake build` / `install` / `release` — gem packaging tasks (release is maintainer-only and currently blocked by the `allowed_push_host` TODO in the gemspec).
+
+## Layout and conventions
+
+- Code lives under `lib/radioactive/`; the entry point `lib/radioactive.rb` requires `radioactive/version` and defines the `Radioactive` module. New files should be required from there.
+- Long-form design docs live in `docs/`. `docs/REQUIREMENTS.md` is the spec; treat it as a contract and update it deliberately (in the same commit as behavior changes) rather than letting code and spec drift.
+- RBS signatures live in `sig/radioactive.rbs` — keep them in sync when adding public API.
+- Versioning: bump `Radioactive::VERSION` in `lib/radioactive/version.rb` for releases.
+- Ruby version: gemspec requires `>= 3.2.0`; `.standard.yml` pins the Standard target to `3.2`. Match that when writing code (no 3.3-only syntax unless you also bump these).
+- CI (`.github/workflows/main.yml`) only runs on pull requests — its `push` trigger is wired to a placeholder branch (`.invalid`), so pushes to `main` will not run CI until that's fixed. The matrix currently lists Ruby `'4.0.3'`, which does not exist; expect CI to fail until the version is corrected.