Add ctail, refactor README

docs/ctail.md

@@ -0,0 +1,57 @@
+# ctail
+
+Tail a Static CT log, printing a one-liner per new certificate or precertificate as it arrives.
+
+## Install
+
+```bash
+GOPRIVATE=git.ipng.ch go install git.ipng.ch/certificate-transparency/ctfetch/cmd/ctail@latest
+```
+
+## Usage
+
+```bash
+ctail [flags] <log-url>
+```
+
+Example:
+
+```bash
+ctail https://halloumi2026h1.mon.ct.ipng.ch
+```
+
+By default `ctail` starts at the current tree tip and prints new entries as they appear. Use `--from-leaf 0` to replay from the beginning.
+
+## Output format
+
+One line per entry:
+
+```
+ leaf-index  type  validity-range            issuer (up to 40 chars)          subject name
+```
+
+Example:
+
+```
+1440154358 cert  2026-03-31..2026-06-29  Let's Encrypt R13                bereavementcounselling.uk
+1440154359 pre   2026-03-31..2026-06-29  ZeroSSL ECC Domain Secured Ce... alpenglowforeverfilms.com
+```
+
+- **type**: `cert` for a final certificate, `pre` for a precertificate
+- **issuer**: CommonName, prefixed with the organisation name when the CN alone is terse (e.g. `R13` → `Let's Encrypt R13`)
+- **subject name**: first DNS SAN, falling back to the certificate's CommonName
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--interval` | `15s` | How often to poll the checkpoint (minimum 1s) |
+| `--from-leaf` | `-1` | Start from this leaf index; `-1` means current tree tip |
+| `--rate-limit` | `2s` | Minimum time between HTTP requests (minimum 100ms) |
+| `--user-agent` | `ctail/VERSION (https://git.ipng.ch/certificate-transparency/)` | User-Agent header sent with every request |
+
+## Notes
+
+- The interval timer starts when the checkpoint is fetched, so tile-fetch time counts against the interval and the next poll stays on schedule.
+- A tile is only fetched once the checkpoint confirms it is complete (256 entries). This avoids unnecessary 404s at the tree tip.
+- Status and error messages go to stderr; the entry one-liners go to stdout.

docs/ctfetch.md

@@ -0,0 +1,75 @@
+# ctfetch
+
+Fetch and decode entries from a Static CT log, outputting structured JSON.
+
+## Install
+
+```bash
+GOPRIVATE=git.ipng.ch go install git.ipng.ch/certificate-transparency/ctfetch/cmd/ctfetch@latest
+```
+
+The `GOPRIVATE` variable skips the Go checksum database and module proxy, which do not index modules on `git.ipng.ch`.
+
+## Modes
+
+`ctfetch` operates in two modes depending on the arguments given.
+
+### Leaf-index mode
+
+Fetch the entry at a specific leaf index:
+
+```bash
+ctfetch [flags] <log-url> <leaf-index> [+sct] [+issuer] [+ctlog] [+all]
+```
+
+Examples:
+
+```bash
+ctfetch https://halloumi2026h1.mon.ct.ipng.ch 629794635
+ctfetch https://halloumi2026h1.mon.ct.ipng.ch 629794635 +all
+```
+
+### Tile-dump mode
+
+Fetch all entries from a tile URL or local file. Automatically detects data tiles (log entries) and hash tiles (Merkle tree hashes).
+
+```bash
+ctfetch [flags] <tile-url-or-file> [+sct] [+issuer] [+ctlog] [+all]
+```
+
+Examples:
+
+```bash
+ctfetch https://halloumi2026h1.mon.ct.ipng.ch/tile/data/x002/x460/135
+ctfetch https://halloumi2026h1.mon.ct.ipng.ch/tile/data/x002/x460/135 +sct +ctlog
+ctfetch https://halloumi2026h1.mon.ct.ipng.ch/tile/0/x100/999
+ctfetch --monitoring-url https://halloumi2026h1.mon.ct.ipng.ch tile.bin +issuer
+```
+
+## Output modifiers
+
+| Modifier | Description |
+|---|---|
+| `+sct` | Parse embedded Signed Certificate Timestamps from final (non-precert) certificates |
+| `+issuer` | Fetch issuer certificate details from the log's `/issuer/<fp>` endpoint |
+| `+ctlog` | Look up each SCT's log ID in the CT log list and include operator/state details |
+| `+all` | Enable all of `+sct`, `+issuer`, and `+ctlog` |
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--logs-list-url` | `https://www.gstatic.com/ct/log_list/v3/all_logs_list.json` | CT log list URL for `+ctlog` lookups |
+| `--monitoring-url` | _(none)_ | Log root URL for issuer lookups when input is a local file |
+
+## Hash tiles vs data tiles
+
+**Data tiles** (`/tile/data/...`) contain DER-encoded certificates and precertificates with metadata (leaf index, timestamp, chain fingerprints). Output modifiers `+sct`, `+issuer`, `+ctlog`, and `+all` only apply here.
+
+**Hash tiles** (`/tile/N/...`, N ≥ 0) contain raw 32-byte SHA-256 hashes — the internal nodes of the Merkle tree used for inclusion and consistency proofs. `ctfetch` outputs only the list of hashes; using output modifiers with a hash tile is an error.
+
+## Notes
+
+- With a tile URL, `+issuer` derives the log root by stripping the `/tile/...` path. With a local file, `--monitoring-url` must be provided.
+- Partial tiles (`.p/N` suffix) are tried first; on 404 the full tile is fetched automatically.
+- The CT log list and issuer certificates are cached in memory per invocation.