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
24 changes: 24 additions & 0 deletions .claude/rules/docs-pages.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
paths:
- "internal/handler/docs*"
- "internal/handler/home*"
- "internal/handler/render.go"
- "internal/handler/openapi.go"
- "internal/handler/changelog.go"
Expand All @@ -20,6 +21,29 @@ from it. **Adding a page is one table row.** Tests that apply to only some pages
(`docsPagesWithLanguageTabs()`) rather than re-list. Do not spell the page set out anywhere
else — not in the router, not in a test, not in a template's nav.

## The home page is not a docs page

`home.html` is the company page at `/`, served by `Handler.Home`. **It is not a row in
`docsPages`.** It is the front door: same design language as the docs, different page.

- **Shared:** `docs_styles.css` for the tokens, typefaces, page background, code blocks,
tags and theme toggle; `docs.js` for the toggle and the copy buttons; `htmlPageCSP`; and
the template data, so its price and payment link come from the same config keys.
- **Its own:** the header, the hero and its fan-out diagram, the plan panels, the contact
panel — all in the page's inline `<style>`, under `home-` class names, built from the
shared tokens. **Do not reuse the docs page shell there** (`.topbar`, `.topbar-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.

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.

The fan-out diagram is a **sample that ends in "and more"**, on purpose, so a new lookup
does not mean redrawing it. Do not make it exhaustive. The Product section's two lists
are the full set and do gain a line with each new lookup. The grid-track and injected-control rules below apply to it; the
docs-nav and table rules do not.

## Layout rules — pinned by `docs_layout_test.go`

- **Every table is wrapped in `<div class="table-scroll">`.** `docs.js` gives the wrapper
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/adding-features/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ surfaces late — usually as a drift test failing in CI or a stale docs surface.
8. Add the column to `usage.LookupColumns` and a migration for `request_log` (the drift test will fail until you do)
9. Add a setter method for tests (`SetThingLookup`)
10. Update all test files that call `New()` or `SetLookups()`
11. Update `docs/api-reference.md` (lookup table, response field section, caching TTL table) and `docs/operations.md` (the `cache.ttl.<name>` config row), docs HTML (request table, valid-lookups table, response field section with its `cache_hit` row, caching TTL table), api.http, smoke test, integration tests, changelog.yaml
11. Update `docs/api-reference.md` (lookup table, response field section, caching TTL table) and `docs/operations.md` (the `cache.ttl.<name>` config row), docs HTML (request table, valid-lookups table, response field section with its `cache_hit` row, caching TTL table), the Product list on the home page (`home.html`; not its diagram, which is a sample), api.http, smoke test, integration tests, changelog.yaml

## Adding a New Endpoint

Expand Down
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ OpenAPI 3.1 at `/docs/openapi.yaml`.
cmd/api/main.go entry point, version via ldflags
cmd/sactl/ operator CLI: interactive menu with no args, flags otherwise
internal/app/ dependency wiring, bootstrap, shutdown
internal/handler/ HTTP handlers, route registration, request validation, docs pages
internal/handler/ HTTP handlers, route registration, request validation, docs pages,
company home page
internal/service/ lookup orchestration, caching, fan-out
internal/domain/ lookup implementations + types (model.go)
internal/middleware/ auth, rate limit, logging, security headers, body limit, request ID
Expand Down Expand Up @@ -46,7 +47,7 @@ behind them live elsewhere, so read the one that matches before editing:
|---|---|
| `internal/service`, `cache`, `notifications` | `.claude/rules/service-layer.md` |
| `internal/domain`, `safenet`, lookup handlers | `.claude/rules/lookups.md` |
| `internal/handler/docs*` | `.claude/rules/docs-pages.md` |
| `internal/handler/docs*`, `internal/handler/home*` | `.claude/rules/docs-pages.md` |
| `internal/auth`, `billing`, `usage`, `adminops`, `cmd/sactl`, `migrations` | `.claude/rules/auth-billing.md` |
| `internal/middleware`, `httpapi`, `app`, `config` | `.claude/rules/http-layer.md` |
| Anything that looks removable | `docs/decisions.md` — it may be load-bearing |
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ client ──> Gin router ──> middleware chain ──> handler ──> servi
| Package | Responsibility |
|---|---|
| `internal/httpapi`, `internal/middleware` | Router assembly, the middleware chain in a fixed order, graceful shutdown |
| `internal/handler` | Request validation, plan gating, the embedded docs pages and OpenAPI document |
| `internal/handler` | Request validation, plan gating, the embedded company home page, docs pages and OpenAPI document |
| `internal/service` | Fan-out orchestration, per-lookup Redis caching with singleflight coalescing, risk scoring |
| `internal/domain` | One file per lookup, plus the response types in `model.go` |
| `internal/safenet` | SSRF prevention at dial time: every outbound HTTP client in the server goes through it |
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): `/` (redirect), `/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), `/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 | Redirects to `/docs` |
| GET | `/` | None | Company home page |
| 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
18 changes: 18 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,24 @@ meant finding all six by hand.
select rather than re-list — `docsPagesWithLanguageTabs()` — so a page that gains a Go
example gets it compiled without anyone remembering.

### The company home page is served by the API and is not in `docsPages`

**Decision.** `/` renders `home.html`, the Security Accelerated company page, from the same
binary as the docs. It stays out of the `docsPages` table. It uses the docs' design
language (the shared stylesheet's tokens, typefaces, code blocks and theme toggle) with a
layout of its own.

**Why.** The root used to be a 301 to `/docs`, which left the company with no page of its
own. Serving it here means no second host, deploy or toolchain, and the price it shows
comes from the same config keys as the Plans table on `/docs`. The split between shared
language and own layout was arrived at by getting it wrong in both directions: the first
version reused the docs page shell and looked like a copy of the docs overview; the second
had its own typeface and palette and no longer looked like the same company.

**Instead of.** A separate static site, which would need its own hosting and would quote
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.

### 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
15 changes: 10 additions & 5 deletions integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -517,18 +517,23 @@ func TestIntegration_DomainLookup_InvalidDomain(t *testing.T) {
}
}

func TestIntegration_Docs_RootRedirects(t *testing.T) {
// The root is public and sits outside /v1, so this is the full middleware chain
// serving it without an API key.
func TestIntegration_Home_ServesCompanyPage(t *testing.T) {
r, _ := setupRouter(t)

w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/", nil)
r.ServeHTTP(w, req)

if w.Code != http.StatusMovedPermanently {
t.Fatalf("status = %d, want %d", w.Code, http.StatusMovedPermanently)
if w.Code != http.StatusOK {
t.Fatalf("status = %d, want %d", w.Code, http.StatusOK)
}
if ct := w.Header().Get("Content-Type"); !strings.Contains(ct, "text/html") {
t.Errorf("Content-Type = %q, want text/html", ct)
}
if loc := w.Header().Get("Location"); loc != "/docs" {
t.Errorf("Location = %q, want /docs", loc)
if !strings.Contains(w.Body.String(), "<title>Security Accelerated</title>") {
t.Error("expected the company home page at the root")
}
}

Expand Down
10 changes: 10 additions & 0 deletions internal/handler/changelog.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@
# 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.0
date: 2026-11-11
changes:
- text: "The site root is now a Security Accelerated home page: what the Intelligence API covers, the plans, and how to reach us. It used to redirect to the docs, which are one link away and unchanged"
audience: public
- text: "In dark mode the Pro button, the method badges and the copy button on the checkout page had near-white text on a pale accent and were hard to read; the text is now dark"
audience: public
- text: "The home page is `internal/handler/home.html`, served by `Handler.Home`. It is not in `docsPages`: it uses the docs stylesheet's tokens, code blocks and theme toggle with its own layout, and shares the CSP and template data; the brand link on every docs page now goes to `/` instead of `/docs`. `GET /` returns 200 where it returned 301, and the smoke test expects that"
audience: internal

- version: v1.0.2
date: 2026-10-20
changes:
Expand Down
4 changes: 2 additions & 2 deletions internal/handler/checkout_success.html
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ <h1>Intelligence API</h1>
<div class="error-icon">!</div>
<h2>Unable to retrieve your API key</h2>
<p>{{.Error}}</p>
<a href="/" class="docs-link">Back to documentation</a>
<a href="/docs" class="docs-link">Back to documentation</a>
{{else}}
<div class="success-icon">&#10003;</div>
<h2>Your API key is ready</h2>
Expand All @@ -168,7 +168,7 @@ <h2>Your API key is ready</h2>

<p>Include this key in your requests via the <code>X-API-Key</code> header.</p>

<a href="/" class="docs-link">View API documentation</a>
<a href="/docs" class="docs-link">View API documentation</a>
{{if .PortalLink}}
<span style="margin: 0 8px; color: var(--border);">|</span>
<a href="{{.PortalLink}}" class="docs-link" target="_blank">Manage subscription</a>
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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" 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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" 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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" 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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" 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_controls_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import (
func TestDocs_InteractiveControlsAreInjected(t *testing.T) {
markers := []string{"code-copy", "code-block", "docs-search"}

for _, page := range allDocsHTML() {
for _, page := range allSitePages() {
t.Run(page.Path, func(t *testing.T) {
for _, marker := range markers {
if strings.Contains(page.HTML, marker) {
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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" 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="/docs" class="topbar-brand"><span>Security</span> Accelerated</a>
<a href="/" class="topbar-brand"><span>Security</span> Accelerated</a>
<div class="topbar-actions">
<nav class="topbar-nav">
<a href="/docs">Overview</a>
Expand Down
4 changes: 3 additions & 1 deletion internal/handler/docs_styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,9 @@ html[data-theme="dark"] {
--lang-tab-hover-border: rgba(141, 156, 255, 0.2);
--lang-tab-hover-bg: rgba(141, 156, 255, 0.16);
--divider: rgba(169, 187, 207, 0.14);
--on-accent: #f4f7ff;
/* Dark, not light: in this theme the accent gradient runs from #8d9cff to
#bcc7ff, and near-white text on it measured between 1.5:1 and 2.4:1. */
--on-accent: #0b1220;
--theme-toggle-bg: rgba(15, 24, 37, 0.82);
--theme-toggle-border: rgba(169, 187, 207, 0.12);
--theme-toggle-shadow: 0 18px 36px rgba(0, 0, 0, 0.28);
Expand Down
15 changes: 0 additions & 15 deletions internal/handler/docs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,21 +26,6 @@ func docsRouter() *gin.Engine {
return r
}

func TestDocs_RootRedirectsToDocs(t *testing.T) {
r := docsRouter()
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/", http.NoBody)
r.ServeHTTP(w, req)

if w.Code != http.StatusMovedPermanently {
t.Fatalf("status = %d, want %d", w.Code, http.StatusMovedPermanently)
}
loc := w.Header().Get("Location")
if loc != "/docs" {
t.Errorf("Location = %q, want /docs", loc)
}
}

func TestDocs_LandingPage(t *testing.T) {
r := docsRouter()
w := httptest.NewRecorder()
Expand Down
5 changes: 2 additions & 3 deletions internal/handler/handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ import (
"database/sql"
_ "embed"
"fmt"
"net/http"

"github.com/gin-gonic/gin"
"github.com/security-accelerated/intelligence-api/internal/billing"
Expand Down Expand Up @@ -149,9 +148,9 @@ func (h *Handler) maxIPs(plan string) int {
return h.cfg.GetInt(fmt.Sprintf("ip.max_ips.%s", plan))
}

// RegisterRoutes registers unauthenticated routes only (health check, docs, billing).
// RegisterRoutes registers unauthenticated routes only (home page, health check, docs, billing).
func (h *Handler) RegisterRoutes(router *gin.Engine) {
router.GET("/", func(c *gin.Context) { c.Redirect(http.StatusMovedPermanently, "/docs") })
router.GET("/", h.Home)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
for _, page := range docsPages {
router.GET(page.Path, h.docsPageHandler(page.Tmpl))
}
Expand Down
29 changes: 29 additions & 0 deletions internal/handler/home.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
package handler

import (
_ "embed"
"html/template"

"github.com/gin-gonic/gin"
)

//go:embed home.html
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.
//
// 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.
func (h *Handler) Home(c *gin.Context) {
h.renderDocs(c, homeTmpl)
}
Loading
Loading