From 8a6fab666e980a2049312c328e4c696d1074e24d Mon Sep 17 00:00:00 2001 From: Jason Norch Date: Thu, 12 Nov 2026 13:58:34 -0500 Subject: [PATCH 1/2] Serve the home page on the company's domain, the docs at the API's root v1.1.0 put the company home page at "/" on every hostname, and the only hostname the app has is api.securityaccelerated.com. So the company page lives at the API's address, and securityaccelerated.com is still a registrar placeholder. One app can answer for both names if the root tells them apart. site.home_host names the company's domain: "/" is the home page there and on its www., and a redirect to /docs on any other host. site.api_host is where the home page's docs links point. Both default to empty, which keeps the home page at "/" on every host with relative links, so local development and the existing tests are unchanged. The cross-links are absolute because a relative one keeps the reader on the wrong name: the docs' brand link was "/", which on the API host would now redirect straight back to the docs. They are built from config, never from the Host header, so a caller cannot choose where they point. The stylesheet and scripts stay same-origin paths; the page CSP allows nothing else. The redirect is a 302 where the pre-v1.1.0 one was a 301. Which host gets the page is now configuration, and a browser keeps a 301 after the configuration changes. fly.toml sets both hosts, so this takes effect at the next release. The company's domain needs its Fly certificate and DNS records before that release, or the home page has no address at all; docs/operations.md has the steps. Assisted-by: Claude Fable 5.2 --- .claude/rules/docs-pages.md | 9 +++ AGENTS.md | 4 +- docs/api-reference.md | 4 +- docs/decisions.md | 24 ++++++ docs/operations.md | 19 +++++ fly.toml | 6 ++ internal/config/config.go | 2 + internal/config/sample-config.yml | 6 ++ internal/handler/changelog.yaml | 8 ++ internal/handler/docs.go | 17 ++++- internal/handler/docs.html | 2 +- internal/handler/docs_404.html | 2 +- internal/handler/docs_account.html | 2 +- internal/handler/docs_changelog.html | 2 +- internal/handler/docs_domain.html | 2 +- internal/handler/docs_ip.html | 2 +- internal/handler/home.go | 66 +++++++++++++--- internal/handler/home.html | 20 ++--- internal/handler/home_test.go | 110 +++++++++++++++++++++++++++ scripts/smoke-test.sh | 4 +- 20 files changed, 279 insertions(+), 32 deletions(-) diff --git a/.claude/rules/docs-pages.md b/.claude/rules/docs-pages.md index 9b4af3f..4b6449b 100644 --- a/.claude/rules/docs-pages.md +++ b/.claude/rules/docs-pages.md @@ -35,6 +35,15 @@ else — not in the router, not in a test, not in a template's nav. `.hero-card`, `.section-card`, the Plans table). The first version did and came out as a copy of the docs overview. It has no `.topbar-actions`, so `docs.js` injects no search. +**The hostname decides what `/` is.** One app serves the company's domain and the API's. +With `site.home_host` set, `/` is the home page on that host (and its `www.`) and a 302 to +`/docs` on any other; unset, it is the home page everywhere, which is what local +development and most tests run with. So the two sites link to each other through template +data, never a bare path: the docs' brand link is `{{.HomeURL}}` and the home page's links +into the docs are `{{.DocsBase}}/docs…`. A bare `/` on a docs page would loop back to the +docs in production. The stylesheet and scripts stay same-origin paths; the CSP allows +nothing else. + Use the tokens, never a new colour or typeface: a version with its own palette and face was rejected as too far the other way. Its plan limits repeat the Plans table on `/docs`; change both together. diff --git a/AGENTS.md b/AGENTS.md index baf2458..28bb874 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,9 @@ open the file. ## Infrastructure Docker Compose locally (API + Redis + Postgres). Production on Fly.io (iad, auto-stop) with -Neon Postgres and Upstash Redis. A Fly volume `maxmind_data` (name predates DB-IP) at +Neon Postgres and Upstash Redis. One app answers for two hostnames: +`securityaccelerated.com` (`/` is the company home page) and `api.securityaccelerated.com` +(`/` redirects to `/docs`), told apart by `site.home_host`. A Fly volume `maxmind_data` (name predates DB-IP) at `/data/geoip` persists the GeoIP database; `docker-entrypoint.sh` chowns it as root then drops to `appuser`. Version is baked in via `-ldflags "-X main.version=..."`. GitHub Actions: `test.yml`, diff --git a/docs/api-reference.md b/docs/api-reference.md index bbd663b..76b2d37 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -8,7 +8,7 @@ billing internals) is in [operations.md](operations.md). ## Authentication -Most API endpoints require an API key passed via the `X-API-Key` header. Keys are stored in PostgreSQL as `hex(sha256(key))` and belong to a customer, who has a plan. A customer normally holds one live key, but holds several during a rotation grace window: `POST /v1/keys/rotate` issues a new key and leaves the previous ones authenticating until `auth.rotation_grace` (default 24h) elapses, so deployed clients can be switched over without downtime. The following routes are public (no API key required): `/` (the company home page), `/docs`, `/docs/domain`, `/docs/ip`, `/docs/account`, `/docs/changelog`, `/docs/openapi.yaml`, `/v1/hello`, `/v1/health`, `/billing/webhook` (Stripe signature), and `/billing/success` (session token). +Most API endpoints require an API key passed via the `X-API-Key` header. Keys are stored in PostgreSQL as `hex(sha256(key))` and belong to a customer, who has a plan. A customer normally holds one live key, but holds several during a rotation grace window: `POST /v1/keys/rotate` issues a new key and leaves the previous ones authenticating until `auth.rotation_grace` (default 24h) elapses, so deployed clients can be switched over without downtime. The following routes are public (no API key required): `/` (the company home page on the company's hostname, a redirect to `/docs` on the API's), `/docs`, `/docs/domain`, `/docs/ip`, `/docs/account`, `/docs/changelog`, `/docs/openapi.yaml`, `/v1/hello`, `/v1/health`, `/billing/webhook` (Stripe signature), and `/billing/success` (session token). ### Customer Plans @@ -44,7 +44,7 @@ When the limit is exceeded, the API returns `429 Too Many Requests` with a `Retr | Method | Path | Plan | Description | |--------|------|------|-------------| -| GET | `/` | None | Company home page | +| GET | `/` | None | Company home page on the company's hostname; 302 to `/docs` on any other when `site.home_host` is set | | GET | `/docs` | None | API documentation landing page | | GET | `/docs/domain` | None | Domain Intelligence API docs | | GET | `/docs/ip` | None | IP Intelligence API docs | diff --git a/docs/decisions.md b/docs/decisions.md index 82e48ae..d4ea790 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -270,6 +270,30 @@ had its own typeface and palette and no longer looked like the same company. plan limits and a price that nothing ties to this service's config. And instead of a sixth docs page, which is what reusing the docs shell produced. +### The hostname decides what `/` is, and the redirect is a 302 + +**Decision.** One app answers for two names. `site.home_host` names the company's domain: +`/` is the home page there (and on `www.`), and a 302 to `/docs` on every other host. The +home page links to the docs on `site.api_host`, and the docs' brand link goes to the home +host. Both keys empty, the default, serves the home page at `/` on every host with relative +links. + +**Why.** v1.1.0 served the home page at the root of the API's hostname, which put the +company page at `api.` and left the company's own domain on a registrar placeholder. The +links are absolute because a relative one keeps the reader on the wrong name: the docs +would be read at the company's domain, and the docs' brand link would go to a root that +redirects straight back to the docs. They are built from config, never from the request's +`Host` header, so a caller cannot choose where they point. The redirect is a 302 because +which host gets the page is configuration, and a browser keeps a 301 after the +configuration has changed: anyone holding the pre-v1.1.0 301 never saw the home page at +the API's root. + +**Instead of.** A second app or a static site for the company's domain, for the reasons in +the entry above. And instead of redirecting everything except `/` on the home host over to +the API host: the docs and the API still answer there, which is untidy but harmless, and +the redirect would need its own exceptions for the stylesheet and scripts the home page +loads. + ### Every table is wrapped in `.table-scroll`, and grid tracks use `minmax(0, 1fr)` **Decision.** Both are pinned by tests in `docs_layout_test.go`. diff --git a/docs/operations.md b/docs/operations.md index 070f099..5dcc523 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -97,6 +97,8 @@ Config values: | `stripe.payment_link.pro` | `""` | Stripe Payment Link URL for pro plan | | `stripe.price_display.pro` | `""` | Price text shown on the docs Plans table (e.g. `$29/month`); empty hides it. Change it together with the Stripe price | | `stripe.portal_link` | `""` | Stripe Customer Portal URL for subscription management | +| `site.home_host` | `""` | Hostname whose `/` is the company home page (`www.` on it counts too); `/` on any other host redirects to `/docs`. Empty serves the home page at `/` on every host | +| `site.api_host` | `""` | Hostname the home page's docs links point at. Empty keeps them relative | | `billing.stale_key_days` | `365` | Days of inactivity before key deactivation | | `billing.cleanup_interval` | `10m` | Sweep cadence for expired provisioned keys | | `usage.buffer_size` | `256` | Channel buffer size for async usage logging | @@ -244,6 +246,21 @@ A release is a `v*` tag on `main`, created with `make release`. The full procedu make release V=v0.X.Y # tag main and push the tag; the tag is the deploy, gated on the production reviewer ``` +### Hostnames + +One Fly app answers for two names, and `site.home_host` / `site.api_host` (set in +`fly.toml` `[env]`) tell it which is which: + +| Hostname | `/` | Everything else | +|----------|-----|-----------------| +| `securityaccelerated.com`, `www.securityaccelerated.com` | Company home page | Served as on the API host | +| `api.securityaccelerated.com` | 302 to `/docs` | The API and the docs | + +Each name needs a certificate on the app (`fly certs add `) and DNS records +pointing at it; `fly certs show ` prints the records it expects and whether the +certificate has been issued. The company's domain has no page until both exist, so a +hostname is added to Fly and DNS before `site.home_host` is released, not after. + ### Environment variables (Fly secrets) | Variable | Description | @@ -270,6 +287,8 @@ make release V=v0.X.Y # tag main and push the tag; the tag is the de | `STRIPE_PAYMENT_LINK_PRO` | Stripe Payment Link URL for pro plan | | `STRIPE_PRICE_DISPLAY_PRO` | Price text shown on the docs Plans table; set in `fly.toml` `[env]`, not a secret | | `STRIPE_PORTAL_LINK` | Stripe Customer Portal URL for subscription management | +| `SITE_HOME_HOST` | Hostname whose `/` is the company home page; set in `fly.toml` `[env]`, not a secret | +| `SITE_API_HOST` | Hostname the home page's docs links point at; set in `fly.toml` `[env]`, not a secret | | `USAGE_BUFFER_SIZE` | Channel buffer size for async usage logging (default: 256) | | `USAGE_FLUSH_INTERVAL` | Flush interval for usage batch inserts (default: 5s) | | `THREAT_INTEL_VIRUSTOTAL_API_KEY` | VirusTotal API key (enables VirusTotal threat intel provider) | diff --git a/fly.toml b/fly.toml index 2f52301..a7bdc22 100644 --- a/fly.toml +++ b/fly.toml @@ -12,6 +12,12 @@ primary_region = 'iad' # text the docs Plans table shows and must change together with that price. [env] STRIPE_PRICE_DISPLAY_PRO = '$29/month' + # One app, two names. "/" is the company home page on the first (and on + # www.) and a redirect to /docs on any other host; the home page links to + # the docs on the second. The first needs its certificate and DNS in place + # before this ships, or the home page has no address at all. + SITE_HOME_HOST = 'securityaccelerated.com' + SITE_API_HOST = 'api.securityaccelerated.com' [http_service] internal_port = 8080 diff --git a/internal/config/config.go b/internal/config/config.go index ce3321e..f24b69f 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -125,6 +125,8 @@ func setDefaults(v *viper.Viper) { v.SetDefault("stripe.payment_link.pro", "") v.SetDefault("stripe.price_display.pro", "") v.SetDefault("stripe.portal_link", "") + v.SetDefault("site.home_host", "") + v.SetDefault("site.api_host", "") v.SetDefault("billing.stale_key_days", 365) v.SetDefault("usage.buffer_size", 256) v.SetDefault("usage.flush_interval", "5s") diff --git a/internal/config/sample-config.yml b/internal/config/sample-config.yml index 86a1031..b098e93 100644 --- a/internal/config/sample-config.yml +++ b/internal/config/sample-config.yml @@ -96,6 +96,12 @@ stripe: pro: "" # shown on the docs Plans table, e.g. "$29/month"; keep in step with prices.pro_monthly portal_link: "" +# Which hostname shows what at "/". Both empty (the default) serves the company +# home page at the root of every host, which is what local development wants. +site: + home_host: "" # e.g. securityaccelerated.com: "/" is the home page here (and on www.), a redirect to /docs on any other host + api_host: "" # e.g. api.securityaccelerated.com: the home page links to the docs on this host + billing: stale_key_days: 365 cleanup_interval: 10m # sweep cadence for expired provisioned keys diff --git a/internal/handler/changelog.yaml b/internal/handler/changelog.yaml index 50cadb8..86bf5d1 100644 --- a/internal/handler/changelog.yaml +++ b/internal/handler/changelog.yaml @@ -10,6 +10,14 @@ # terms (#91). An entry a later release reversed keeps its text and gains a # "superseded in vX" note, rather than being hidden or rewritten. +- version: v1.1.1 + date: 2026-11-12 + changes: + - text: "The Security Accelerated home page moves to securityaccelerated.com. The root of api.securityaccelerated.com goes back to redirecting to the docs, as it did before v1.1.0, and the two sites link to each other" + audience: public + - text: "`site.home_host` and `site.api_host` (`SITE_HOME_HOST`, `SITE_API_HOST`, set in `fly.toml` `[env]`) tell the one app which hostname is which: `/` renders the home page on the home host and its `www.`, and is a 302 to `/docs` on any other. Both empty keeps v1.1.0's behaviour, the home page at `/` on every host. The home host needs its Fly certificate and DNS before this is released. The smoke test follows the redirect" + audience: internal + - version: v1.1.0 date: 2026-11-11 changes: diff --git a/internal/handler/docs.go b/internal/handler/docs.go index 23ddfb1..dddc872 100644 --- a/internal/handler/docs.go +++ b/internal/handler/docs.go @@ -94,6 +94,13 @@ type docsData struct { PortalLink string Version string Changelog []docsChangelogVersion + + // HomeURL is where the brand link on the docs pages goes. DocsBase is put + // in front of the home page's links into the docs. With no site hosts + // configured they are "/" and "", so every link stays on the host it was + // served from; with them set, the two sites link to each other by name. + HomeURL string + DocsBase string } type docsChangelogVersion struct { @@ -143,12 +150,20 @@ func (h *Handler) buildDocsData() docsData { if h.status != nil { version = h.status.System.Version } - data := docsData{Version: version} + data := docsData{Version: version, HomeURL: "/"} if h.cfg != nil { data.ProPaymentLink = h.cfg.GetString("stripe.payment_link.pro") data.ProPrice = h.cfg.GetString("stripe.price_display.pro") data.PortalLink = h.cfg.GetString("stripe.portal_link") } + // Built from config, never from the request's Host header, so a caller + // cannot choose where these links point. + if host := h.siteHost("site.home_host"); host != "" { + data.HomeURL = "https://" + host + "/" + } + if host := h.siteHost("site.api_host"); host != "" { + data.DocsBase = "https://" + host + } for _, v := range h.changelog { var publicChanges []template.HTML diff --git a/internal/handler/docs.html b/internal/handler/docs.html index 588722a..fcde48d 100644 --- a/internal/handler/docs.html +++ b/internal/handler/docs.html @@ -257,7 +257,7 @@
- Security Accelerated + Security Accelerated