go build ./cmd/healthcheck (run for verification, not via the bin/ recipe)
drops the binary in the working dir. Untracked previously; landed in the
last commit by accident. Gitignore now lists each cmd binary explicitly so
the same mistake can't recur for canary, healthcheck, or the two pdf/docx
template builders.
Three things that all blocked tunnel-start:
1. justfile: dropped set dotenv-load / set export — they pulled
.env.development into every recipe shell, where empty values
beat docker compose --env-file .env per shell-env precedence
(POSTGRES_PASSWORD was the visible casualty). Dev recipes now
pass --env-file .env.development explicitly so they're not
affected by the change.
2. canary image is distroless/static, so the wget-based healthcheck
had no binary to run and every check failed → nginx/tunnel never
started. Added cmd/healthcheck (tiny Go HTTP probe of /healthz),
built alongside canary, swapped compose healthcheck to /healthcheck.
3. Added tunnel-build and tunnel-rebuild recipes so the next person
doesn't have to remember which compose files the tunnel overlay
needs.
Operator request: give the webbug some personality. Trigger response is now
a small JPEG embedded into the binary via //go:embed, served from
backend/internal/token/generators/webbug/asset/pixel.jpg. Default is a
545-byte 32x32 yellow placeholder I generated with imagemagick — replace
the file with any image (same path, same filename, doesn't matter what
size or content) and the next backend rebuild picks it up. No other code
needs to change.
Scope: ONLY webbug. The docx, pdf, and envfile generators keep their own
Trigger functions that still call pixel.Clone() for the canonical
invisible 1x1 GIF — those types embed the trigger URL inside their
respective artifact bytes (a Word footer, a PDF /AA action, a fake .env
INTERNAL_METRICS_ENDPOINT line) and need the response to stay invisible
so the attacker doesn't notice they pinged us. Stealth preserved where
it matters.
The pixel package itself is untouched (still has the 43-byte GIF
constant); only webbug stops importing it.
Tradeoff baked in: a webbug whose response is a visible image is
*technically* less stealthy than the canonical 1x1 — the attacker can
see "huh there's a small image here." But the visible mechanism is real
too (think Mailchimp / SendGrid email-open tracking, which use sized
"social proof" images, not just 1x1s), so this is a legitimate variant.
For an operator who wants strict 1x1-invisible behavior in prod, the
revert is a 3-line change in webbug/generator.go (swap embed for
pixel.Clone() again).
Tests updated: webbug/generator_test.go no longer asserts gifByteLength
or pixel.Clone() equality; it now asserts the body starts with the JPEG
SOI marker (0xff 0xd8) + ContentType is image/jpeg. The
"independent-copy-per-call" invariant test still passes (bytes.Clone in
the Trigger ensures each Body slice is a fresh allocation).
Cache headers unchanged (no-store / no-cache / must-revalidate) so every
fetch hits the trigger handler.
Upstream 8d2599c0 added a mysqlEnabled parameter to token.NewHandler and
took a long line over the limit in handler_test. Pass the parameter from
the e2e stack (true: integration test exercises mysql token creation) and
reflow the long handler_test return so golines is happy.
Operator request: when MYSQL_FAKE_ENABLED=false (the dev default + the only
viable setting behind Cloudflare Tunnel since CF Tunnel doesn't carry raw
TCP), surface that in the UI so users can see the species but understand
they can't deploy it on this instance. Avoids the silent-broken case where
someone creates a mysql token, gets a connection_string artifact, points
their MySQL client at it, and just times out with no clue why.
Backend (3-line change):
- TypeDescriptor gains `Enabled bool` + optional `DisabledReason string`
- TypeDescriptors() now takes `mysqlEnabled bool`; mysql is the one whose
Enabled tracks the flag, all others are always true (they don't need
any deployment-level infra beyond HTTP)
- Handler stores mysqlEnabled, passes to descriptors call; main.go wires
cfg.MySQL.Enabled in. Handler tests updated to pass false explicitly.
Frontend (matching schema + visual treatment):
- typeDescriptorSchema picks up `enabled` (default true for backward compat)
and `disabled_reason` (optional string)
- TypeCard reads descriptor.enabled, sets `data-disabled` on the label,
disables the radio input, replaces the blurb with the disabled_reason
when present (so the user sees WHY rather than guessing), and renders
a small "disabled" pill in the top-right corner of the card
- SCSS: dashed border, muted palette, opacity 0.55, glyph faded, cursor
not-allowed, hover effect suppressed — reads as "shelf is here but the
specimen is checked out" rather than a broken button
In the operator UI: mysql card renders ghosted with the explanatory text
"Requires direct TCP exposure (port 3306). Not reachable via Cloudflare
Tunnel — only enable on a VPS with raw TCP access." Selecting it is
mechanically impossible (input is disabled), no form-level guard needed.
Flip MYSQL_FAKE_ENABLED=true in env when you stand up a VPS later and the
card re-enables with no other code changes.
Backend builds clean + token-package tests pass.
Frontend gates green: typecheck + biome + lint:scss + build (431ms).
Audit F23: integration tests covered repositories and individual handlers
but no test exercised the full chain. The PDF padding bug (F2) had passing
unit tests for years because the substring-only assertion masked the
embedded underscore padding.
New //go:build integration test in internal/server spins up Postgres via
testcontainers + miniredis, walks each of webbug, slowredirect, docx, pdf,
kubeconfig, envfile, mysql: POSTs /api/tokens, extracts the trigger URL
from the artifact bytes the way a victim would (regex for non-binary, ZIP
walk for docx, base64 decode for pdf), GETs the URL, then asserts the
manage view sees the event and the notifier fired. PDF subtest asserts the
byte after the embedded /c/<id> is not '_' — the structural check that
catches F2-style regressions.
Audit F3: validateURL checked scheme/host/userinfo but never resolved the
host, so an operator-supplied webhook_url could point at the canary's own
Redis (redis:6379), Postgres, link-local IMDS (169.254.169.254), or any
RFC1918 host on the docker network or VPS subnet — a classic confused-deputy
SSRF triggered by self-triggering a token after creation.
validateURL now resolves the hostname (or parses a literal IP) and rejects
loopback, RFC1918, CGNAT, link-local, multicast, unspecified, IMDS, and
IPv6 unique-local. The default HTTP client also installs a DialContext that
re-checks the dialed IP for defense-in-depth against DNS rebinding. The
Config gains an AllowPrivateHosts flag (default false) that test code opts
into when targeting httptest.NewServer.
Audit F2: the PDF placeholder was padded with underscores embedded directly
in the /URI path, so Acrobat fetched /c/<id>____________ and the chi route
extracted the padded id. Lookup returned ErrNotFound, the webbug fallback
served a 1x1 GIF, and event recording skipped because tok was nil. PDF
tokens silently never recorded events.
Part B (durable): pad inside a ?p= query string so the trigger path stays
canonical and chi extracts the real id. Part A (defense in depth): handler
TrimRight on _ so PDFs already in the field also resolve correctly. Added
two regression tests: byte-after-id assertion in the PDF artifact, and the
handler's trim path.
Audit F10: script-src 'self' blocked the Turnstile bootstrap script
(https://challenges.cloudflare.com/turnstile/v0/api.js) and its widget
iframe. Added challenges.cloudflare.com to script-src, connect-src, and a
new frame-src directive so the widget can render under prod CSP.
Audit F4: compose.yml already passed VITE_TURNSTILE_SITE_KEY as a build arg,
but vite.prod never declared an ARG/ENV for it, so Vite's import.meta.env
resolved to undefined. The Turnstile widget never rendered in prod, causing
the backend to reject every create-token request with TURNSTILE_FAILED.
Audit F1: prod.nginx had only the SPA fallback so all API requests, trigger
requests, and kubeconfig requests returned index.html, breaking the prod
deployment end-to-end. Added an upstream canary block to nginx.prod.conf and
three proxy_pass location blocks mirroring dev.nginx (plus CF-Connecting-IP
header since prod sits behind Cloudflare Tunnel).
Two tightly-coupled bugs visible after the PUBLIC_BASE_URL fix landed:
1. Trigger URLs now correctly show :22784 (the host-exposed nginx port),
but opening one in the browser rendered the SPA's NotFound page instead
of hitting the backend trigger handler.
Root cause: dev.nginx only had `location /` → frontend_dev. No location
block for `/c/`, `/k/`, or even `/api/`. Every request went to the SPA;
only `/api/*` happened to work because vite's internal proxy caught it
on its way through frontend_dev → canary. /c/* and /k/* (the trigger
paths) just fell through to the SPA fallback.
Fix: add `upstream canary { server canary:8080 }` to nginx.conf and
three new location blocks in dev.nginx for /api/, /c/, /k/. Each one
proxy_passes directly to the canary upstream with X-Real-IP +
X-Forwarded-For + X-Forwarded-Proto set so middleware.RealIP() resolves
the actual visitor IP rather than the docker bridge. Mirrors what
spec §12.3 prescribes for prod nginx.
2. Manage URL in responses still showed :8080 even after PUBLIC_BASE_URL
was set to :22784. Two separate config keys: canary.base_url
(PUBLIC_BASE_URL → trigger_url) and canary.manage_url (CANARY_MANAGE_URL
→ manage_url). The latter has no env-name overlap with the spec's
PUBLIC_BASE_URL, so it kept its default literal "http://localhost:8080".
Fix: in config.Load(), after unmarshal, fall manage_url back to base_url
when it's empty or still equals the bare default. Operators setting one
env var (PUBLIC_BASE_URL) now get both URLs computed off it. Explicit
CANARY_MANAGE_URL still wins if set — preserves the prod ability to
serve manage at a different domain than triggers. Extracted the literal
to a `defaultCanaryBaseURL` const so the default and the fallback
sentinel reference the same string.
After this + the prior PUBLIC_BASE_URL alias, a fresh token from the form
should produce trigger_url + manage_url both pointing at
http://localhost:${NGINX_HOST_PORT}/... — clickable, reachable, and triggers
hitting /c/ now route to canary and record events.
Operator action: just dev-down && just dev-up to rebuild nginx + canary
containers with the new config.
Spec §12.4, .env.example, .env.development, and dev.compose.yml all use the
name PUBLIC_BASE_URL for the externally-reachable URL stamped into trigger/
manage links. But the koanf env-key map in config.go only routed
CANARY_BASE_URL → canary.base_url. So setting PUBLIC_BASE_URL had no effect,
the default fallback "http://localhost:8080" silently won, and every issued
token came back with trigger_url/manage_url like
"http://localhost:8080/c/<id>" regardless of where canary was actually reachable.
Visible to the operator as: trigger/manage URLs in the SPECIMEN ISSUED dossier
pointing at :8080 (where canary doesn't even listen externally — host port is
nginx ${NGINX_HOST_PORT}, defaulting to randomised 22784).
Fix is one line: add PUBLIC_BASE_URL alongside CANARY_BASE_URL in the env-key
map. Both env names now route to canary.base_url. Backwards-compatible —
existing CANARY_BASE_URL deployments keep working.
Operator action: set `PUBLIC_BASE_URL=http://localhost:${NGINX_HOST_PORT}` in
.env.development (e.g. http://localhost:22784) and restart canary. URLs will
then reflect the actual reachable address.
Backend serializes `Events []Event` as JSON `null` when the slice is nil
(Go's zero value for slices). Spec §8.4 shows it as an array — stale spec,
verified actual behavior with `curl http://localhost:22784/api/m/<uuid>`
returning `"events": null` on a freshly-created token with no triggers.
Zod schema was `events: z.array(eventResponseSchema)` — failed to parse the
null, threw PARSE_ERROR, manage page rendered "CANNOT REACH ARCHIVE" instead
of the empty dossier.
Fixed: `.nullish().transform(v => v ?? [])` — accepts null/undefined and
normalizes to []. Manage page's `events.length === 0` empty-state check
("No events recorded yet") now reachable; consumers always see an array.
Caught by memory rule feedback_verify_data_shapes.md: trust reality > spec.
I trusted §8.4's example object during Phase 14 schema design instead of
hitting the live endpoint. Same kind of drift as the four Phase-14 spec-vs-code
divergences cleared at the time — this one slipped through because
TokenManagePage was never end-to-end exercised pre-UI.
Two latent template-leftover bugs in vite.config.ts proxy that 404'd every
useTokenTypes/useCreateToken/useManageToken/useDeleteToken call:
- Default target was http://localhost:8000. Backend listens on :8080
(backend/config.yaml `server.port: 8080`, default registered in
internal/config/config.go). Off-by-one-port silent for the whole
Phase 14 cycle because Phase 14 didn't end-to-end-test.
- `rewrite: (p) => p.replace(/^\/api/, '')` stripped /api before forwarding.
But backend mounts routes UNDER /api via `r.Route("/api", ...)`
(cmd/canary/main.go:322). So a request for /api/tokens/types got rewritten
to /tokens/types, which backend doesn't serve — 404 page not found.
Frontend axios uses baseURL `/api` and path `/tokens/types` → full URL
`/api/tokens/types`. With these fixes the proxy now passes that through
verbatim to http://localhost:8080/api/tokens/types, which is where chi
actually mounts the route.
dev.compose.yml: added VITE_API_TARGET=http://canary:8080 to the frontend
container's env so the dev-compose path also works (inside the container
"localhost" is the vite container, not the canary container — has to use
docker DNS).
Surfaced today when the operator manually eyeballed the landing page and
SpeciesSection rendered "Could not load species catalog. Try again in a
moment." (the descriptorsError branch in landing/index.tsx SpeciesSection).
System stack was the floor; this is the intended pairing. Three roles, three
voices:
- Archivo Black (display) — the big confident archive voice. CANARIES,
TRAP TRIPPED, DOSSIER NOT FOUND, SPECIMEN ISSUED, NO SPECIMEN HERE. Single
weight 900 black grotesque, wide letterforms, built for huge display. Pairs
visually with the PARADISE-style pixelated typography in the
vector-minimalism reference folder.
- Space Grotesk (sans) — speaking voice. Body, section titles, blurbs,
button labels, error text. Geometric joints + open apertures read as
"designed" where system extra-bold read as "just heavy." Weights 400-700
cover the range; section titles dropped 800→700 since Space Grotesk caps
at 700 (no perceptible difference in the design).
- Departure Mono (mono) — technical scribblings. SerialBar, timestamps,
field labels, strip pills, ID codes, all the spec-sheet micro-text. Its
pixelated character is the deliberate echo of image 1 (PARADISE) that
ui-monospace can't make.
Loaded via Google Fonts <link> in index.html (preconnect + display=swap),
no npm dep. ~50KB cold cache; cached-warm thereafter. System sans / system
mono remain in the fallback chain at the end of each stack so a CDN miss
degrades to the previous design without breaking.
$font-display token added to _fonts.scss for the giant headlines; $font-sans
and $font-mono updated to lead with the new families. Headlines previously at
font-weight: 900 dropped the weight (Archivo Black is single-weight), and
letter-spacing/line-height tightened slightly to match the new metrics.
Gates green: typecheck + biome + lint:scss + build (419ms; no chunk size
delta — fonts load from CDN, not the bundle).
Parallel audit (superpowers:code-reviewer + general-purpose spec adherence)
returned PASS-WITH-NOTES + PASS. All actionable SHOULD-FIX and NIT items
addressed in this commit per the fix-in-phase rule.
SHOULD-FIX (code review):
- Dead ternary at manage/index.tsx:253 (`cursor === undefined ? idx+1 : idx+1`)
collapsed to `idx + 1`. EventLogSection prop renamed `cursor` → `cursorIsSet`
(boolean) since the value itself was never consumed past the dead branch.
- URL.createObjectURL leak in artifact.tsx — both file (base64) and text
variants now run inside useEffect with cleanup that calls
URL.revokeObjectURL on dependency-change AND on unmount. Extracted into
two co-located hooks: useBase64ObjectUrl, useTextObjectUrl.
- Text inputs lacked <label htmlFor=…> association. Refactored the landing
form to use the existing Field primitives (TextField, TextareaField) which
wire htmlFor↔id via useId. This single change also closed the next finding.
- Dead infrastructure: Field primitives existed but no consumer used them.
Landing form's local FieldLabel removed; TextField/TextareaField now have
consumers. Net diff: −181 LOC.
- LeaderLabel: truly unused primitive, no foreseeable consumer in this scope.
Deleted (`frontend/src/components/LeaderLabel/`) and removed from barrel.
SHOULD-FIX (spec adherence):
- §8.6 row 410 → TOKEN_DISABLED: spec is stale. Backend Go ground truth
(verified via `grep StatusGone\|TOKEN_DISABLED backend/internal/`) emits
neither — disabled tokens come back as 200 with `token.enabled=false`,
which the DossierCard already renders with alarm-pill + HEADLINE_DISABLED.
Per feedback_verify_data_shapes.md: backend Go beats spec when they diverge.
No code change; documented here so the next AI doesn't re-open it.
- eventResponseSchema.extra: tightened from `z.unknown()` to
`z.record(z.string(), z.unknown())` to match backend's `json.RawMessage`
default of `{}` (event/repository.go:47). Added EventExtra type alias;
event-row.tsx now uses it instead of casting through unknown.
NIT:
- SerialBar: extracted `BAR_COUNT = 22` const; `FALLBACK_BARS` constant
string replaces the BAR_CHARS array that had length-9 / length-22
inconsistency between the empty-input and computed branches.
- Glyph: removed `default` branch — switch is now exhaustive over the
closed TokenType enum, so a future 8th type would be a compile error
rather than silently rendering WebbugGlyph.
- Dead `export { TOKEN_BLURB }` + `export { ArtifactDisplay }` from
landing/index.tsx — no observed consumer, dropped.
- App.tsx and main.tsx header banners normalized to the project-canonical
19 = signs (matches all other files in repo).
NOT addressed in this commit (intentional):
- CreateTokenRequest `metadata` as `z.unknown()`. Refactor to a discriminated
request schema keyed on `type` would tighten compile-time safety for any
future caller bypassing buildPayload — defer because (a) the form is the
only caller and validates via Zod on submit, (b) the change touches the
Phase 14 contract that was just stabilized two commits before this UI phase.
- NotFound (frontend route fallback) vs ManageNotFound (manage 404) live
separately. Both work; the two paths are intentional — off-path vs
off-dossier are semantically different events.
Gates green: typecheck + biome check + lint:scss + build (414ms; landing
chunk dropped 21KB → 19.93KB after dead style removal).
Landing route (/) is the token-creation page, framed as a "specimen
requisition" intake form per the vector-minimalism ethos. Mind: cataloging
a thing that resists cataloging — a trap baited for an unseen visitor.
Page composition:
- Top archive Strip (FIELD STATION / VOL / ISSUE pill)
- Hero block: large blocky "CANARIES" headline, Latin subtitle, purpose line
- Halftone separator
- Five sections (01 species / 02 annotate / 03 route / 04 species config / 05 verify)
- Bottom Strip with routing/license metadata
Form sub-sections (each a small component to keep complexity under biome's
maxAllowedComplexity=25 cap on FormView):
- SpeciesSection — 7-card grid via TypePicker (radio fieldset, sr-only inputs)
- AnnotateSection — memo textarea + conditional filename (when file-kind)
- RouteSection — Telegram | Webhook radio fieldset + conditional credentials
- ConfigSection — slowredirect destination_url or envfile include_keys
- VerifySection — Turnstile widget if VITE_TURNSTILE_SITE_KEY present
- SubmitFooter — release button + privacy note
Validation: client uses createTokenRequestSchema.safeParse, surfaces field
errors inline (mono caps in alarm color); server-side ApiError.fields are
mapped back into the same FieldErrors shape via buildSubmissionState (Phase 14
single-source envelope contract preserved).
Result view: SpecimenCard with full token dossier (DataRows), kind-discriminated
artifact display (url → CopyField; file/text → download Blob via object-URL;
connection_string → CopyField with note), Manage + Trigger CopyFields, link to
the dossier route /m/:manage_id (route wired in next chunk).
Turnstile: explicit-render widget, lazy script-load, registers token via
setTurnstileTokenProvider on success; cleans up on unmount; no key = no widget
(matches backend dev-bypass at internal/turnstile/verifier.go).
Gates green: typecheck + biome + stylelint + build (406ms, landing chunk
123KB / 38KB gzip).
Strip the inherited template aesthetic so the next AI/designer starts
from a true blank canvas. AI tunnel-vision pattern: when there's an
existing layout/sidebar/color palette, the model tends to redesign
in place rather than truly start fresh. Removing the visual scaffold
forces fresh-canvas thinking when operator-driven UI work begins.
Removed:
- pages/dashboard, pages/settings — template "Welcome / Available
Stores / Suggested Features" stubs that have no canary purpose.
- pages/landing/landing.module.scss, core/app/{shell,toast}.module.scss
— empty header stubs imported only for side effects.
- core/lib/shell.ui.store.ts — zustand store for sidebar open/
collapsed/theme state; entirely template-coupled. core/lib/index.ts
reduced to an empty barrel ready for canary stores.
- core/app/shell.tsx sidebar+nav+header layout; replaced with bare
ErrorBoundary > Suspense > Outlet. Keeps robustness pattern,
drops the navbar template a designer would otherwise inherit.
- App.tsx hardcoded dark Toaster theme + wrapping .app div.
- styles/_tokens.scss color palette ($bg-page, $text-default, etc.)
— biased toward a specific dark aesthetic. Spacing, typography,
weights, line heights, letter spacing, radius, z-index, transitions,
breakpoints, container widths all KEPT — neutral design primitives,
not aesthetic choices.
- styles/_reset.scss body bg-color: #fff / color: #000 defaults.
Designer chooses the palette; reset stays purely structural.
- styles.scss .app class wrapper.
- config.ts USERS endpoints, USERS query keys, STORAGE_KEYS,
HTTP_STATUS, PAGINATION — template constants with no canary
consumer. Reduced to ROUTES.HOME and QUERY_CONFIG (consumed by
query.config.ts). Designer adds back what they actually need.
Kept (logic / infrastructure / Phase 14 work):
- Full api/ and core/api/ — Zod schemas, axios client, hooks,
ApiError, QueryClient, retry strategies.
- main.tsx, index.html (already canary-titled with favicons in
public/asset).
- QueryClientProvider + RouterProvider + bare Toaster + ReactQuery
Devtools provider stack.
- Lazy-route + Suspense + ErrorBoundary pattern in shell.
- styles/_index.scss, _fonts.scss (system font stacks), _mixins.scss
(breakpoint utilities, flex helpers, sr-only, truncate, etc.) —
all neutral.
Gate: pnpm typecheck, pnpm biome check, pnpm lint:scss, pnpm build
all clean. Production bundle: 140-byte landing chunk (the <div />),
~37 KB index chunk (api/core/router/zod machinery), no leftover
template CSS.
Phase 14 deliverables (audited PASS):
- Zod 4 schemas mirror backend handler/DTO byte-shapes (verified
against backend/internal/token/{handler,dto,types}.go,
backend/internal/event/{dto,entity}.go, and
backend/internal/middleware/turnstile.go — not just the spec).
- api/types/token.ts: tokenResponseSchema, manageTokenViewSchema,
artifactSchema (z.discriminatedUnion on kind), typeDescriptorSchema,
createTokenRequestSchema with superRefine for telegram/webhook
required_if semantics, per-type metadata helpers.
- api/types/event.ts: eventResponseSchema (with GeoView, NotifyStatus
enum, nullable user_agent/referer/notified_at) and
manageResponseSchema covering cursor pagination.
- api/types/error.ts: apiErrorEnvelopeSchema + successEnvelope<T>
factory; single source of truth for envelope shape.
- core/api/errors.ts refactored: ApiError carries canary error codes
(VALIDATION_ERROR, TURNSTILE_FAILED, BAD_CURSOR, BAD_PARAM, ...)
and a Record<string,string> fields map. No more FastAPI-style
parsing. Module augmentation flows ApiError as defaultError to all
TanStack hooks. Obsolete template api.config.ts removed.
- api/client.ts: axios instance over VITE_API_URL (fallback /api),
request interceptor adds CF-Turnstile-Response header from
pluggable provider when present, response interceptor routes axios
errors through Zod-backed transformAxiosError -> ApiError.
apiGet/apiPost/apiDelete typed via ZodType<T>; PARSE_ERROR carries
the failing field path + message for debuggability.
- 4 hooks: useTokenTypes (static, no polling), useCreateToken
(invalidates manage on success), useManageToken (URI-encoded id,
splayed cursor/limit query key, frequent polling), useDeleteToken
(removeQueries on success).
Implicit contract documented here for the next AI: the
cf_turnstile_response body field is intentionally optional in
createTokenRequestSchema because backend middleware/turnstile.go
reads the CF-Turnstile-Response HEADER first (set via the request
interceptor). Operators wiring the Turnstile widget should call
setTurnstileTokenProvider(() => widgetToken) on app init; the form
need not carry the token in the body.
Audited: superpowers:code-reviewer + general-purpose spec adherence
— PASS on first dispatch. Audit findings S-1/S-3/S-4/S-7 fixed
pre-rollup in 7c0a504d. I-1 (config_schema gap in
backend TypeDescriptor — spec stale vs code) and I-2 (turnstile
body-field optional) flagged for future phases; not Phase 14 issues.
OPERATOR PAUSE BOUNDARY (spec §16.3, plan line 2314). No UI/
component/page/styling code in this phase. Phase 15 resumes with
infrastructure (nginx + telemetry).
Address audit findings S-1, S-3, S-4, S-7 pre-rollup (fix-in-phase).
S-1: Eliminate hand-rolled envelope error parser duplication.
Moved transformAxiosError out of core/api/errors.ts (where it
required a private parseEnvelopeError mirror of the Zod schema)
into api/client.ts where it now uses apiErrorEnvelopeSchema directly
via safeParse. core/api/errors.ts is now ApiError class + code
constants + module augmentation only, with no canary-envelope
knowledge — keeps layering core <- universal, api <- canary clean.
S-3: useManageToken query key now splays cursor/limit individually
instead of carrying the params object reference. Without this,
callers passing a freshly-allocated { cursor } each render would
miss the cache even with identical values.
S-4: unwrapEnvelope's PARSE_ERROR now includes the first Zod issue
(path + message) in the ApiError.message so operators see WHICH
field shape failed, not just that something did.
S-7: Add request interceptor rejection handler so request-phase
errors propagate via Promise.reject instead of throwing
synchronously.
Four hooks wired through the canary api/client envelope helpers.
Module-augmented defaultError surfaces ApiError everywhere.
- useTokenTypes: GET /tokens/types, parsed via typeDescriptorListSchema.
Uses QUERY_STRATEGIES.static (Infinity stale, no refetch on focus)
since the discoverable types list is build-time stable.
- useCreateToken: POST /tokens (CreateTokenInput -> CreateTokenResponse).
On success invalidates ['canary','manage', manage_id] so a freshly
created token's manage page hydrates with the new row on first hit.
- useManageToken: GET /m/{id} with cursor pagination. URLSearchParams
builds ?cursor=&limit= only for defined values; manageId is
URI-encoded. QUERY_STRATEGIES.frequent enables 30s polling so the
events list feels live. enabled=false when manageId is empty.
- useDeleteToken: DELETE /m/{id}. On success removes the cached
manage data entirely (no point keeping it after a delete).
- api/client.ts: axios instance with baseURL from VITE_API_URL env
(falls back to /api) and 15s timeout.
- Request interceptor adds CF-Turnstile-Response header from a
pluggable provider (setTurnstileTokenProvider). Backend's
middleware/turnstile.go reads header first then body field; using
the header keeps the request body shape clean and matches the plan.
- Response interceptor routes axios errors through transformAxiosError
(canary envelope-aware) so callers see typed ApiError everywhere.
- Envelope-aware helpers apiGet / apiPost / apiDelete:
- apiGet/apiPost unwrap {success:true,data:T} via successEnvelope
factory; on shape mismatch throw ApiError(PARSE_ERROR).
- apiDelete returns void for 204 responses; envelope error path
handled by the interceptor.
- Plumbed into api/index.ts barrel.
Phase 13 deliverables (audited PASS):
- internal/geoip: nil-safe Service over oschwald/geoip2-golang v2
with NopService factory; Open/Close/Lookup contract; cityReader
interface for fixture-free unit testing; extractLookup +
firstSubdivisionName helpers fully covered.
- internal/event: AttachGeoIP(geoip.Lookup) on *Event with empty-
collapses-to-nil overwrite semantics; Service.enrichGeo runs
before repo.Insert so geo_* columns persist in the same row;
ServiceConfig.GeoIP plumbed through; 5 new service tests +
7 entity tests + 2 real-Postgres integration tests.
- config: GeoIPConfig{Path}, GEOLITE_PATH env binding matching
compose.yml, default /data/GeoLite2-City.mmdb.
- cmd/canary/main: openGeoIP wires the mmdb with NopService
fallback on any open failure; close-on-shutdown deferred.
Audited: superpowers:code-reviewer + general-purpose spec
adherence — PASS on first dispatch. One non-blocking nit (direct
unit coverage for firstSubdivisionName) fixed in 32e9c0a3 per
fix-in-phase discipline.
13 of 18 phases closed.
Code-review audit flagged firstSubdivisionName as exercised only
transitively through extractLookup. Adds five direct unit tests
covering the documented branches (nil/empty slice, English-name
prefers, ISOCode fallback, skip-empty-then-find-populated,
all-empty returns ""). Fix-in-phase per project convention; no
backlog rot.
openGeoIP opens cfg.GeoIP.Path and returns a (Lookuper, closer)
pair; on open failure (missing/unreadable mmdb) it returns
geoip.NopService() and a no-op closer so the rest of the wire-up
sees a consistent non-nil interface and the binary stays healthy
in environments without a MaxMind license. buildEventStack now
accepts a geoip.Lookuper and threads it into event.ServiceConfig.
Close is deferred in run() so the mmdb file handle releases on
graceful shutdown; a close-error is logged at warn (not fatal).
- entity: (*Event).AttachGeoIP(geoip.Lookup) sets Geo* nullable
pointer fields with overwrite semantics (empty/zero collapses to
nil so DB column stays NULL). Single-arg signature matches the
call shape in design spec §9 (line 1437) and keeps the helper
symmetric with the geoip.Lookup value type.
- service: ServiceConfig.GeoIP geoip.Lookuper plumbed through to
the Service.geo field. Record now calls enrichGeo(evt) BEFORE
s.repo.Insert so geo_country/region/city/asn/asn_org persist in
the same row. enrichGeo is nil-safe on three axes (geo, evt,
evt.SourceIP) — geo enrichment is best-effort, never an error
path.
- service_test: fakeLookuper + newSvcWithGeo helper; five new
tests (enriches-before-insert, no-geo-leaves-nil, empty-IP-
skips-lookup, NopService-leaves-nil, best-effort-when-insert-
fails). All pre-existing tests pass unchanged because GeoIP
defaults to nil.
- entity_test: seven AttachGeoIP unit tests covering populate-all,
empty Lookup, partial fields, zero/negative ASN guards, overwrite
semantics, and ASN-pointer independence from the input value.
- integration_test: two real-Postgres tests (stub Lookuper writes
populated geo_* columns; NopService leaves them NULL) verify
the wiring round-trips through the Insert SQL.
- internal/geoip: Service over oschwald/geoip2-golang v2 with City db
enrichment (Country/Region/Subdivision/City) and a NopService
factory for environments without the mmdb file. Nil-safe Lookup
returns a zero geoip.Lookup on any failure path (nil receiver,
nil reader, empty/malformed IP, reader error, !rec.HasData).
- internal/geoip: unexported cityReader interface allows whitebox
fake-based unit testing without bundling a real .mmdb fixture;
extractLookup is a pure function for synthetic-record coverage.
- config: GeoIPConfig{Path} koanf section; GEOLITE_PATH env binding
matching compose.yml; default /data/GeoLite2-City.mmdb.
- deps: github.com/oschwald/geoip2-golang/v2 v2.1.0.
ASN/ASNOrg fields are reserved on geoip.Lookup but stay zero with a
City-only mmdb; populating them is a future-extension concern (ASN
db is not fetched by scripts/init.sh per design §12.5).
- Rename admin.Handler.Register → RegisterRoutes for parity with
health.Handler.RegisterRoutes and token.Handler.RegisterAPIRoutes /
RegisterManageRoutes / RegisterTriggerRoutes. Spec §6.3 line 558
also illustrates the canonical wire-up as
`adminH.RegisterRoutes(api)`.
- Drop the local strItoa helper in handler_test.go; use strconv.Itoa.
The helper was a code-reviewer nit — equivalent stdlib already
exists; fewer lines, less surface to drift.
Both findings are non-blocking but covered by the fix-in-phase rule
(no backlog rot). Phase 12 audits otherwise PASS on first dispatch:
- superpowers:code-reviewer: PASS
- general-purpose spec-adherence: PASS
- cmd/canary/main.go: mountAdminRoutes helper keeps run() and
mountRouter under funlen 100. Admin routes mounted INSIDE the /api
subrouter so they inherit read-tier rate limit + CORS; gated by
OperatorBearer(cfg.Operator.Token). If OPERATOR_TOKEN is unset, the
entire mount is skipped (no Bearer middleware, no routes — admin
endpoints simply do not exist), and a structured warn log records
the reason. This is the production safety: misconfiguration leaves
the endpoint nonexistent rather than reachable.
- internal/admin/integration_test.go: testcontainers-backed end-to-end
tests exercising the full /api/admin/* stack:
* 404 on missing Authorization (no WWW-Authenticate leak)
* 404 on wrong token
* 200 on /stats with seeded mixed tokens + events
* 200 on /tokens?limit=2 with HasMore/NextOffset accuracy
* 204 on disable + DB-level verification token.Enabled flipped
* 404 on disable for a missing id
All requests go through the OperatorBearer middleware to verify the
wire-up matches the unit behavior.
- internal/admin/handler.go: replaces unused template stats handler
with the canonical Phase 12 endpoints from spec §8.1:
GET /stats — tokens_count, events_count, by_type,
by_alert_channel
GET /tokens — offset-based pagination, default 50,
cap 100; returns full token.Response
list with trigger/manage URLs via
injected URLBuilder; 400 BAD_PARAM on
negative/non-int offset
POST /tokens/{id}/disable — 204 on success; 404 NOT_FOUND envelope
when token.ErrNotFound; 500 envelope
on other repo errors
Handler takes TokenRepository + EventRepository + URLBuilder
interfaces (test seam); wire-up supplies *token.Repository,
*event.Repository, *token.Service (which already implements
TriggerURL/ManageURL).
- internal/admin/dto.go: Stats, TokenListPage, TokenListResponse.
- token.Repository.CountByType / CountByAlertChannel: GROUP BY type
and GROUP BY alert_channel; returned shapes typed as TypeCount /
ChannelCount with json+db tags for direct JSON emission.
- event.Repository.CountAll: global event count.
- Handler tests cover happy path + 500 propagation for each repo
dependency; pagination (default/limit-cap/offset paging); 400 on
bad offset; 404 on disable miss; 405 on GET to disable endpoint
(sanity check that POST-only routing is intentional).
- internal/middleware/operator_bearer.go: returns 404 on miss (NOT 401)
per spec §11.5; subtle.ConstantTimeCompare for timing safety; rejects
when configured token is empty (defense-in-depth even though wire-up
skips mount in that case).
- Table-driven test covers: missing header, empty header, wrong scheme
(Basic), case-sensitive scheme (lowercase bearer), no payload,
no-space-after-Bearer, equal-length wrong token, different-length
wrong token, correct token, empty-config rejects both empty and
populated headers, extra-whitespace rejection. Also asserts no
WWW-Authenticate header on 404 (endpoint-hiding intent).
- config.OperatorConfig + OPERATOR_TOKEN env mapping; default empty
(mount is skipped when empty).
Phase 11 deliverables (audited PASS):
Service primitives
- event.Service.CountActiveDedup(ctx, tokenID): Redis SCAN over
dedup:trigger:{tokenID}:* (token-scoped pattern), batched 100,
returns sum(value-1) — value=1 (first trigger fired) contributes 0,
value=N (N-1 INCRs) contributes N-1 silenced events. Matches
spec §10.5 "counter = total silenced" semantics.
- token.Service.DeleteByManageID: thin wrapper around
Repository.DeleteByManageID; ServiceRepository interface gains the
method.
DTOs
- ManageTokenView (slimmer than the create-time Response — drops
manage_id / manage_url / metadata since the client is already on
the manage page); ManagePage{NextCursor, HasMore}; ManageResponse
shape exactly matches spec §8.4 example. event.Response (already
in place from Phase 1) reused for the events array.
Handlers
- GET /api/m/{manage_id}: parses ?cursor (int64, must be ≥ 0; 400
BAD_CURSOR otherwise) and ?limit (default 20, capped at 100).
Calls GetByManageID + ListByToken + CountByToken + CountActiveDedup
via the new EventQuery + DedupCounter interfaces, assembles
ManageResponse. Page derived from list.HasMore + list.NextCursor
(audit-fix ca67cf63 — was re-deriving from len before).
- DELETE /api/m/{manage_id}: 204 on success; 404 envelope on miss.
Cascade is via the existing tokens-events FK ON DELETE CASCADE
(verified by integration test).
- 404 on unknown manage_id returns the JSON envelope (not bare
http.NotFound) so the frontend gets a parseable error code.
- NewHandler signature 5 → 6 args (added eventQuery + dedupCounter).
Both test sites and main.go updated.
Wire-up
- cmd/canary/main.go: tokenH.RegisterManageRoutes(api) inside the
/api subrouter. Inherits CORS + read-tier rate limit from /api;
no Turnstile, no create-tier limits (read-style endpoint per
spec §8.1).
- Extracted buildHTTPDeps to keep run() under the funlen ceiling.
Integration tests (testcontainers-Postgres + miniredis):
- ManagePageReturnsTokenAndEventsAndSilencedCount: 3 same-IP triggers
→ events_total=3, events_silenced_active=2, one NotifySent + two
NotifyDeduped, no next page.
- ManagePageReturns404OnUnknownManageID
- ManageDeleteCascadesEvents: DELETE → CountByToken==0 + token gone
Audited: superpowers:code-reviewer + general-purpose spec adherence —
PASS. Both audits flagged one non-blocking nit (buildPage was
re-deriving NextCursor from len rather than using the repo's HasMore
flag); cleaned up in ca67cf63 to avoid future drift if the repo's
pagination logic evolves.
Both audits flagged buildPage as a non-blocking but worth-cleaning nit:
it re-derived next_cursor from len(events) and the last event's ID
rather than using the HasMore + NextCursor flags that
event.Repository.ListByToken already computes via the LIMIT+1 peek
trick. Both calculations agreed today, but the duplication would
mask a divergence if the repo's pagination logic ever evolved
(e.g. switched to opaque token cursors).
Inline buildPage into gatherManageData and use list.HasMore +
list.NextCursor as the authoritative signals. Drops the buildPage
helper. Behavior identical; tests still pass.
- cmd/canary/main.go: tokenH.RegisterManageRoutes(api) mounts GET +
DELETE /m/{manage_id} inside the /api subrouter (read-tier rate
limit applies; no Turnstile, no create-tier limits — read-style
endpoints by spec §8.1).
- Extract buildHTTPDeps to keep run() under the funlen ceiling (was
102, now under 100). Pulls out registry build + tokenSvc + verifier
+ healthH + tokenH construction. Returns the four handles run()
needs to wire the router and shutdown path.
Integration tests (internal/event/integration_test.go,
testcontainers-Postgres + miniredis):
- TestIntegration_ManagePageReturnsTokenAndEventsAndSilencedCount:
POST creates a webbug, three triggers from the same CF-Connecting-IP
fire (one notification, two deduped per the Phase 10 dedup gate);
GET /api/m/{manage_id} returns token with TriggerCount=3,
EventsTotal=3, EventsSilencedActive=2, three event records with
exactly one NotifySent and two NotifyDeduped, no next page.
- TestIntegration_ManagePageReturns404OnUnknownManageID
- TestIntegration_ManageDeleteCascadesEvents: delete via DELETE
/api/m/{manage_id}, verify CountByToken == 0 (FK ON DELETE CASCADE)
and the token is gone (token.ErrNotFound).
Adds the HTTP layer for spec §8.4. The UUID in the URL is the
capability — no other auth required, by design.
- token/dto.go: ManageTokenView (slimmer than Response — no manage_id,
no manage_url, no metadata, since the user is already on the manage
page and those would be redundant), ManagePage{NextCursor, HasMore},
ManageResponse{Token, Events, EventsTotal, EventsSilencedActive, Page}.
Token.ToManageView(triggerURL) builder. Events use the existing
event.Response (already matches spec shape exactly).
- token/handler.go: EventQuery + DedupCounter interfaces declared near
the existing EventRecorder + FingerprintRecorder; same dependency-
injection style. NewHandler signature gains the two new args (5 → 6;
test sites + main.go updated).
- GetManage(w, r): parses ?cursor= (int64, must be >= 0) and ?limit=
(defaults 20, capped at 100). Returns 404 envelope for unknown
manage_id (envelope, not bare http.NotFound, so frontend gets a
parseable error code). 400 BAD_CURSOR for non-numeric or negative.
Calls svc.GetByManageID + eventQuery.ListByToken + CountByToken +
dedupCounter.CountActiveDedup; assembles the manage payload.
- DeleteManage(w, r): 204 on success, 404 on miss. Cascade-delete is
via the existing tokens-events FK ON DELETE CASCADE.
- buildPage helper: NextCursor is the string of the last event's ID
iff len(events) == limit (matches spec example "next_cursor": "41").
Tests cover happy path, 404 on unknown id, 400 on bad/negative cursor,
?limit= respected, ?limit=999 capped at 100, DELETE happy + 404.
Adds the two service primitives Phase 11's manage handler needs.
- event.Service.CountActiveDedup(ctx, tokenID): Redis SCAN over
dedup:trigger:{tokenID}:* in batches of 100, sums (value-1) for each
key (value=1 = first trigger fired notification, value=N>1 = N-1
silenced). Returns 0 when no rdb is configured.
- token.Service.DeleteByManageID: thin wrapper around
Repository.DeleteByManageID; ServiceRepository interface gains the
method so test fakes can implement it (fakeRepo updated). Returns
ErrNotFound on no-rows.
Tests cover: empty pattern returns 0, first-trigger-only returns 0
(notify fired, nothing silenced), aggregation across IPs sums correctly,
other tokens' keys are excluded by the prefix match, nil rdb returns 0.
Phase 10 deliverables (audited PASS):
Domain layer
- event.NotifyInfo / Notifier / TokenIncrementer / Store contracts
in event/contract.go (breaks event→notify→token cycle without
the type-alias relocation pattern from Phase 9)
- token.Token.NotifyInfo() method bridges *Token → event.NotifyInfo
- notify.Sender + StatusWriter interfaces in notify/types.go
Senders
- telegram.Sender: POST /bot{TOKEN}/sendMessage with MarkdownV2
body, cenkalti/backoff/v5 retry (3 tries / 30s window), permanent
on 4xx, 10s overall + 5s connect timeouts. Sanctioned spec deviation:
parse_mode=MarkdownV2 (spec body says Markdown but escape table is
V2); makes the escape rules consistent. Documented in commit body.
- webhook.Sender: POST user URL with versioned JSON envelope
(§10.4 shape verified field-by-field), optional HMAC-SHA256
signing via X-Canary-Signature header, URL validation at the
call site (rejects non-http(s), missing host, userinfo).
Services
- notify.Service: per-channel sender registry, async fire-and-forget
Notify with bounded sendTimeout, sync.WaitGroup for graceful drain
(notifySvc.Wait() called from main.go gracefulShutdown).
- event.Service.Record: Insert → IncrementTriggerCount → Redis SetNX
dedup gate (15m TTL). First trigger calls notifier; duplicates INCR
+ UpdateNotifyStatus(deduped). Fail-open on Redis errors so we don't
silently miss alerts.
- event.Service.RunRetentionLoop: tickered prune to per-token limit.
Wire-up
- cmd/canary/main.go: buildEventStack constructs senders + notify.Service
+ event.Service. eventRecorderAdapter swaps the Phase-9
directEventRecorder for the real event.Service.Record path. Same
adapter wires the mysql listener — one path, one dedup policy.
- fingerprintRecorderAdapter wires event.Repository.AttachFingerprint
with the configured window.
- spawnRetentionLoop runs RunRetentionLoop on the shared wait group.
- Three nested rate limits on POST /api/tokens (read-tier from /api +
createMin 5/min + createHour 20/hr) with distinct Redis namespaces.
- gracefulShutdown drains notifySvc + retention/mysql wg before return.
Closed deferred Phase-9 items
- (1) testcontainers integration test — full create + trigger + dedup
- (2) directEventRecorder → event.Service.Record swap
- (3) nested create-tier rate limit on POST /api/tokens
- (4) gosec G107/G704 path-scoped to telegram/webhook/turnstile;
G101 path-scoped to config (env-var-name false positives)
- (5) FingerprintRecorder wiring (5-min window default)
- (7) drop required tag on TurnstileResp (middleware sole authority)
- (8) consolidate realIP into middleware across 5 generators
(docx, envfile, kubeconfig, pdf, slowredirect)
Audited: superpowers:code-reviewer + general-purpose spec adherence —
PASS. Code-reviewer caught one bug pre-rollup: formatGeo emitted
literal '(' and ')' which are MarkdownV2 reserved chars outside link
delimiters; would crash Telegram with a parse error. Fixed in
41b9d2c9 with regression assertion on the escaped wrapping.
Audit catch (code-reviewer agent). formatGeo emitted literal `(` and `)`
around the geo block (e.g. `(Toronto, CA)`), but `(` and `)` are in the
MarkdownV2 reserved set when used outside `[text](url)` link delimiter
positions. Telegram would reject the entire message with
`Bad Request: can't parse entities: Character '(' is reserved`.
Fix: write the wrapping parens as `\(` and `\)` literals in the three
parens-construction switch arms. The dynamic field values inside still
flow through EscapeMD as before. The `[View full event timeline](url)`
inline link is left alone — its `(` `)` ARE link delimiters and per V2
rules must NOT be escaped (only `)` and `\` inside the URL portion need
escapes, and our manage URL has neither).
Regression test: TestSender_Send_MessageContainsKeyFields now asserts
`require.Contains(text, \\(Toronto, CA\\))` so substring matching can't
hide future regressions on the wrapping parens.
Closes deferred Phase-9 item 1 (testcontainers full-flow test) and
exercises the Phase 10 dedup gate, retention loop, and notify writeback
end to end.
internal/event/integration_test.go (build tag integration):
- TestIntegration_FullCreateAndTriggerFlow: spins up testcontainers
Postgres + miniredis, builds the same chi router shape main.go uses
(RequestID + Recovery + tokenH.RegisterTriggerRoutes + /api subrouter
with /tokens POST). POSTs a webbug create, then GETs /c/{id} twice
from the same CF-Connecting-IP. Asserts: only one notification fires
(capturingSender callCount == 1), both events recorded (CountByToken
== 2), one event marked NotifySent + one NotifyDeduped, dedup INCR
bumped the Redis counter to "2", trigger_count == 2 on the token.
- TestIntegration_DifferentIPsBothNotify: same setup, three different
IPs each fire their own notification (no cross-IP dedup).
- TestIntegration_DedupTTLExpiry: builds an event.Service with 50ms
DedupTTL, records two events (second deduped), miniredis.FastForward
past TTL, third record notifies again — proves the SetNX TTL is the
authoritative window boundary.
- TestIntegration_RetentionLoopPrunes: inserts 7 events, runs
RunRetentionLoop with limit=3, asserts the table converges to 3
rows (newest kept) and the loop exits cleanly on context cancel.
The capturingSender is a notify.Sender impl; this lets us assert
on whether the dispatch goroutine actually called Send() without
mocking the HTTP layer of the real telegram/webhook senders.
Closes deferred Phase-9 item 4. Phase 9's rollup added G107 + G704 to
the global gosec.excludes as a stop-gap so the Turnstile siteverify
call wouldn't flag SSRF taint. With Phase 10 introducing webhook
sender that takes user-supplied URLs (validated at the call site via
webhook.validateURL before the request is built), the global excludes
hide the very kind of issue we want flagged anywhere new outbound HTTP
lands.
- gosec.excludes: drop G107 + G704 globally; keep only G104 + G706
(the codebase-wide errcheck/subprocess policies).
- exclusions.rules path-scope G107|G704 to:
* internal/notify/telegram/sender.go (operator-config bot URL)
* internal/notify/webhook/sender.go (user URL with validateURL gate)
* internal/turnstile/verifier.go (operator-config siteverify URL)
- exclusions.rules path-scope G101 to internal/config/config.go where
the env-var-name map (WEBHOOK_HMAC_SECRET, TURNSTILE_SECRET_KEY,
OPERATOR_TOKEN, etc.) trips the hardcoded-credentials regex on
literal env var names — false positives, not actual secrets.
Any new client.Do(req) outside these three packages will surface
G107 at the call site and force the author to add URL validation.
Closes deferred Phase-9 item 8. Phase 9 promoted realIP / lastNonEmptyXFF /
OptionalHeader to internal/middleware and refactored webbug only; the
other generators kept their byte-identical local copies. Sweeping them
all over now while the touch surface is already open for Phase 10.
- docx, envfile, kubeconfig, pdf, slowredirect: drop the local
realIP / lastNonEmptyXFF / optionalHeader functions plus the
CF-Connecting-IP / X-Forwarded-For / X-Real-IP header constants.
Trigger paths now call middleware.RealIP / middleware.OptionalHeader
directly. Drops the unused "net" import from each.
- slowredirect/fingerprint_handler.go: same treatment for the
AttachFingerprint call site.
No behavior change — middleware.RealIP is byte-identical to what was
previously inlined per generator; verified by re-running the per-package
trigger tests post-refactor.
CarterPerez-dev