Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .claude/rules/docs-pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand Down
24 changes: 24 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
19 changes: 19 additions & 0 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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 <hostname>`) and DNS records
pointing at it; `fly certs show <hostname>` 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 |
Expand All @@ -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) |
Expand Down
6 changes: 6 additions & 0 deletions fly.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions internal/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
6 changes: 6 additions & 0 deletions internal/config/sample-config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions internal/handler/changelog.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 accepts either answer at `/`, a 200 or a 302 to `/docs`, without following the redirect"
audience: internal

- version: v1.1.0
date: 2026-11-11
changes:
Expand Down
17 changes: 16 additions & 1 deletion internal/handler/docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs.html
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs" class="active">Overview</a>
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs_404.html
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs_account.html
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs_changelog.html
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs_domain.html
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
2 changes: 1 addition & 1 deletion internal/handler/docs_ip.html
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<body>

<header class="topbar">
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="{{.HomeURL}}" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
66 changes: 55 additions & 11 deletions internal/handler/home.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ package handler
import (
_ "embed"
"html/template"
"net"
"net/http"
"strings"

"github.com/gin-gonic/gin"
)
Expand All @@ -12,18 +15,59 @@ var homeHTML string

var homeTmpl = template.Must(template.New("home").Parse(homeHTML))

// Home serves the Security Accelerated company page at the site root: what the
// company makes, the plans, and how to reach it, with the docs one link away.
// The root used to redirect to /docs.
// Home answers the site root: the Security Accelerated company page — what the
// company makes, the plans, and how to reach it — or a redirect to the docs.
//
// It is deliberately not a row in docsPages. That table is the documentation
// set, whose pages share one shell (topbar nav, sidebar, reference tables);
// this is the front door. It uses the docs' design language — the shared
// stylesheet's tokens, typefaces, code blocks and theme toggle — with a layout
// of its own, so it reads as the same company without being a copy of the
// docs overview. It also shares the CSP and the template data, so the price
// and payment link shown here come from the same config keys as the Plans
// table on /docs.
// Which one depends on the hostname. One app serves two names: the company's
// own domain, where the root is the company page, and the API's, where the
// root is the way into the docs. site.home_host names the first; with it set,
// the root of any other host redirects to /docs. With it unset the page is
// served on every host, which is what local development and the tests want.
//
// The redirect is a 302, not a 301. Which host gets the page is configuration,
// and a browser keeps a 301 after the configuration has changed: v1.1.0 served
// this page at the API's root, and anyone holding the 301 from before it never
// saw it there.
//
// The page is deliberately not a row in docsPages. That table is the
// documentation set, whose pages share one shell (topbar nav, sidebar,
// reference tables); this is the front door. It uses the docs' design language
// — the shared stylesheet's tokens, typefaces, code blocks and theme toggle —
// with a layout of its own, so it reads as the same company without being a
// copy of the docs overview. It also shares the CSP and the template data, so
// the price and payment link shown here come from the same config keys as the
// Plans table on /docs.
func (h *Handler) Home(c *gin.Context) {
if !h.servesHomeOn(c.Request.Host) {
c.Redirect(http.StatusFound, "/docs")
return
}
h.renderDocs(c, homeTmpl)
}

// servesHomeOn reports whether the company page is the root of the host a
// request named. www. on the home host counts, so both spellings of the
// company's domain show the same page.
//
// The Host header is the caller's to set, which is safe here: it only chooses
// between the page and a redirect to a fixed path on the same host.
func (h *Handler) servesHomeOn(requestHost string) bool {
home := h.siteHost("site.home_host")
if home == "" {
return true
}
if hostname, _, err := net.SplitHostPort(requestHost); err == nil {
requestHost = hostname
}
host := strings.ToLower(strings.TrimSuffix(requestHost, "."))
return host == home || host == "www."+home
}

// siteHost returns one of the site.*_host config values as a bare lowercase
// hostname, or "" when it is not set.
func (h *Handler) siteHost(key string) string {
if h.cfg == nil {
return ""
}
return strings.ToLower(strings.TrimSpace(h.cfg.GetString(key)))
}
Loading
Loading