Add Debian packaging, Makefile, manpages, tests, and design doc

Introduces a static-binary build and Debian package (amd64/arm64) with
version/commit/date stamped via -ldflags. Ships section-1 manpages for
ctool, ctfetch, and ctail. Adds a `version` subcommand reachable as
`ctool version`, `ctool -version`, `ctool --version`, `ctool fetch
version`, `ctool tail version`, and via the ctfetch/ctail symlinks. Adds
tests covering the dispatcher, fetch/tail argument parsing, and the
formatter/helper functions. Adds a retrofit design document modelled on
the vpp-maglev one, with FRs and NFRs for each tool and the dispatcher.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/ctfetch.1

@@ -0,0 +1,130 @@
+.TH CTFETCH 1 "April 2026" "ctool" "User Commands"
+.SH NAME
+ctfetch \- fetch and decode Static CT log entries as JSON
+.SH SYNOPSIS
+.B ctfetch
+[\fIflags\fR] \fIlog\-url\fR \fIleaf\-index\fR [\fB+sct\fR] [\fB+issuer\fR] [\fB+ctlog\fR] [\fB+all\fR]
+.PP
+.B ctfetch
+[\fIflags\fR] \fItile\-url\-or\-file\fR [\fB+sct\fR] [\fB+issuer\fR] [\fB+ctlog\fR] [\fB+all\fR]
+.PP
+.B ctfetch version
+.SH DESCRIPTION
+.B ctfetch
+reads entries from a Static CT API log (c2sp.org/static\-ct\-api) and
+writes them to stdout as pretty\-printed JSON.
+It is also available as the
+.B fetch
+subcommand of
+.BR ctool (1);
+the two invocations are equivalent.
+.PP
+Two modes are distinguished by whether the second positional argument
+parses as an integer.
+.SS Leaf\-index mode
+.PP
+.RS
+.EX
+ctfetch <log\-url> <leaf\-index> [modifiers...]
+.EE
+.RE
+.PP
+Fetches the data tile that contains
+.IR leaf\-index ,
+decompresses it, and decodes the single entry at that position.
+.SS Tile\-dump mode
+.PP
+.RS
+.EX
+ctfetch <tile\-url\-or\-file> [modifiers...]
+.EE
+.RE
+.PP
+Fetches (or reads from disk) one tile and decodes every entry in it.
+Hash tiles (\fB/tile/N/\fR..., N \(>= 0) produce the list of 32\-byte
+SHA\-256 node hashes; output modifiers are an error in this case.
+Data tiles (\fB/tile/data/\fR...) produce the full decoded
+entry list.
+.SH OUTPUT MODIFIERS
+The modifiers are positional tokens beginning with
+.BR + .
+They control which optional fields are computed and included in the
+JSON output.
+.TP
+.B +sct
+Parse the embedded Signed Certificate Timestamp list from final
+(non\-precert) certificates and include it alongside the entry.
+.TP
+.B +issuer
+Fetch the issuer certificate from the log's
+.B /issuer/<fp>
+endpoint and include parsed issuer details.
+.TP
+.B +ctlog
+Look up each SCT's log ID in the CT log list (see
+.BR \-\-logs\-list\-url )
+and enrich it with operator and state information.
+.TP
+.B +all
+Shorthand for
+.BR +sct " " +issuer " " +ctlog .
+.SH FLAGS
+.TP
+.BI \-\-logs\-list\-url " url"
+CT log list JSON used for
+.B +ctlog
+enrichment.
+Default:
+.IR https://www.gstatic.com/ct/log_list/v3/all_logs_list.json .
+.TP
+.BI \-\-monitoring\-url " url"
+Log root URL used for
+.B +issuer
+lookups when the input is a local tile file. Ignored when the input
+is already an HTTP(S) URL; in that case the root is derived by
+stripping
+.I /tile/...
+from the path.
+.SH SUBCOMMANDS
+.TP
+.B version
+Print the binary's version, git commit hash, and build date, then
+exit.
+.SH EXAMPLES
+Fetch one entry with all enrichments:
+.PP
+.RS
+.EX
+$ ctfetch https://halloumi2026h1.mon.ct.ipng.ch 629794635 +all
+.EE
+.RE
+.PP
+Dump a data tile straight off the web:
+.PP
+.RS
+.EX
+$ ctfetch https://halloumi2026h1.mon.ct.ipng.ch/tile/data/x002/x460/135 +sct +ctlog
+.EE
+.RE
+.PP
+Dump a tile from disk, pointing at a monitoring URL so
+.B +issuer
+lookups can find the issuer endpoint:
+.PP
+.RS
+.EX
+$ ctfetch \-\-monitoring\-url https://halloumi2026h1.mon.ct.ipng.ch tile.bin +issuer
+.EE
+.RE
+.SH NOTES
+Partial tiles (the
+.I .p/N
+suffix) are tried first; on 404 the full tile is fetched
+automatically.
+The CT log list and any fetched issuer certificates are cached in
+memory for the lifetime of a single invocation.
+.SH SEE ALSO
+.BR ctool (1),
+.BR ctail (1)
+.SH AUTHOR
+Pim van Pelt <pim@ipng.ch>