feat(api): serve the web app on / and for its own links, with a strict policy

A GET or HEAD outside /api is a file of the app, or its page for a link inside it (/admin/users). A file that is missing (under assets/ or with an extension) answers 404, never the page, so a missing script is not run as HTML; hidden files and folders are never served; everything else, and any unknown /api address, keeps the JSON 404. The page gets a Content-Security-Policy that allows only its own server (no address, no wildcard, no inline script), nosniff, DENY and no referrer. Hashed assets are cached for good and the page is asked again. With no app in the binary, / says how to build it. The app is an optional dependency, so existing wiring is unchanged.
This commit is contained in:
tgiachi 2026-11-12 15:56:33 +01:00
commit 7acac73dd0
3 changed files with 379 additions and 2 deletions

View file

@ -5,6 +5,7 @@ package httpapi
import ( import (
"context" "context"
"io/fs"
"net/http" "net/http"
"reflect" "reflect"
"strings" "strings"
@ -158,6 +159,9 @@ type Deps struct {
ArtistImages artistImageService ArtistImages artistImageService
Settings userSettingsService Settings userSettingsService
Streams streamService Streams streamService
// Web is the built web app, served on / and for its own links. It is optional: with none (a build
// without the app) / shows a page that says how to build it, and the API works the same.
Web fs.FS
} }
// missingDeps names the services of d that were not set. Every field but the logger is an // missingDeps names the services of d that were not set. Every field but the logger is an
@ -167,7 +171,7 @@ func missingDeps(d Deps) []string {
v := reflect.ValueOf(d) v := reflect.ValueOf(d)
for i := 0; i < v.NumField(); i++ { for i := 0; i < v.NumField(); i++ {
f := v.Type().Field(i) f := v.Type().Field(i)
if f.Name == "Logger" { if f.Name == "Logger" || f.Name == "Web" {
continue continue
} }
if v.Field(i).Kind() == reflect.Interface && v.Field(i).IsNil() { if v.Field(i).Kind() == reflect.Interface && v.Field(i).IsNil() {
@ -186,7 +190,7 @@ func NewRouter(d Deps) *gin.Engine {
r := gin.New() r := gin.New()
_ = r.SetTrustedProxies(nil) // use the socket address; no forwarded-header trust yet _ = r.SetTrustedProxies(nil) // use the socket address; no forwarded-header trust yet
r.Use(gin.Recovery(), limitBody(maxBodyBytes), requestLog(d.Logger)) r.Use(gin.Recovery(), limitBody(maxBodyBytes), requestLog(d.Logger))
r.NoRoute(func(c *gin.Context) { writeError(c, http.StatusNotFound, "not_found", "no such route") }) r.NoRoute(noRoute(d.Web))
v1 := r.Group("/api/v1") v1 := r.Group("/api/v1")
v1.GET("/health", health) v1.GET("/health", health)

137
internal/api/http/web.go Normal file
View file

@ -0,0 +1,137 @@
package httpapi
import (
"io/fs"
"mime"
"net/http"
"path"
"strconv"
"strings"
"github.com/gin-gonic/gin"
)
// appPolicy is what the page of the web app may load: only things from its own server. No
// address, no wildcard and no inline or eval script, so a page of the app cannot reach another
// host. `style-src-attr` lets the app set `style="..."` on an element (bars and rings); stylesheets
// and scripts still have to come from the server.
const appPolicy = "default-src 'self'; script-src 'self'; style-src 'self'; style-src-attr 'unsafe-inline'; " +
"img-src 'self' data: blob:; media-src 'self' blob:; font-src 'self'; connect-src 'self'; " +
"object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'"
// Files under assets/ have a hash in their name, so a name never means two different files.
const (
assetsDir = "assets"
foreverCache = "public, max-age=31536000, immutable"
askAgainCache = "no-cache"
pageNotBuilt = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Sonda</title><body style="font-family:system-ui,sans-serif;max-width:40rem;margin:3rem auto;padding:0 1rem;line-height:1.5"><h1>Sonda</h1><p>The server is running, but the web app is not part of this build.</p><p>Build it with <code>make build</code> (or build the app in <code>web/</code> and then <code>go build -tags webui</code>), or use the Docker image, which has it.</p><p>The API is at <code>/api/v1</code> and its documentation at <a href="/api/docs/">/api/docs/</a>.</p></body></html>`
)
// appHeaders protects the page of the app: it cannot be framed, the browser does not guess content
// types, no address leaves in a Referer, and the policy keeps it to its own server.
func appHeaders(c *gin.Context) {
h := c.Writer.Header()
h.Set("Content-Security-Policy", appPolicy)
h.Set("X-Content-Type-Options", "nosniff")
h.Set("X-Frame-Options", "DENY")
h.Set("Referrer-Policy", "no-referrer")
}
// noRoute answers every address that no API route owns. A GET or HEAD outside /api is the web
// app: a file of it, or, for a link inside the app (/admin/users), its page. Everything else
// keeps the JSON 404 the API has always given, and so does a file that is not there: a script
// that is missing must never come back as the page, which the browser would try to run.
func noRoute(web fs.FS) gin.HandlerFunc {
hasApp := false
if web != nil {
if info, err := fs.Stat(web, "index.html"); err == nil && !info.IsDir() {
hasApp = true
}
}
return func(c *gin.Context) {
urlPath := c.Request.URL.Path
readOnly := c.Request.Method == http.MethodGet || c.Request.Method == http.MethodHead
if !readOnly || urlPath == "/api" || strings.HasPrefix(urlPath, "/api/") {
writeError(c, http.StatusNotFound, "not_found", "no such route")
return
}
appHeaders(c)
if !hasApp {
respond(c, "text/html; charset=utf-8", askAgainCache, []byte(pageNotBuilt))
return
}
name := strings.Trim(urlPath, "/")
if name == "" {
serveIndex(c, web)
return
}
// Hidden files and anything that is not a clean path inside the app are never served.
if hidden(name) || !fs.ValidPath(name) {
writeError(c, http.StatusNotFound, "not_found", "no such file")
return
}
if info, err := fs.Stat(web, name); err == nil && !info.IsDir() {
serveFile(c, web, name)
return
}
// Not a file: under assets/ or with an extension it is a file that is missing; anything else
// is a link inside the app, which the app itself resolves.
if name == assetsDir || strings.HasPrefix(name, assetsDir+"/") || path.Ext(name) != "" {
writeError(c, http.StatusNotFound, "not_found", "no such file")
return
}
serveIndex(c, web)
}
}
// hidden is true when any part of the path starts with a dot (.gitkeep, .env, ..).
func hidden(name string) bool {
for _, part := range strings.Split(name, "/") {
if strings.HasPrefix(part, ".") {
return true
}
}
return false
}
func serveIndex(c *gin.Context, web fs.FS) {
body, err := fs.ReadFile(web, "index.html")
if err != nil {
writeError(c, http.StatusInternalServerError, "internal", "internal error")
return
}
respond(c, "text/html; charset=utf-8", askAgainCache, body)
}
func serveFile(c *gin.Context, web fs.FS, name string) {
body, err := fs.ReadFile(web, name)
if err != nil {
writeError(c, http.StatusNotFound, "not_found", "no such file")
return
}
contentType := mime.TypeByExtension(path.Ext(name))
if contentType == "" {
contentType = http.DetectContentType(body)
}
cache := askAgainCache
if strings.HasPrefix(name, assetsDir+"/") {
cache = foreverCache
}
respond(c, contentType, cache, body)
}
// respond sends a body with its type and cache rule. A HEAD gets the same headers and no body.
func respond(c *gin.Context, contentType, cache string, body []byte) {
h := c.Writer.Header()
h.Set("X-Content-Type-Options", "nosniff")
h.Set("Cache-Control", cache)
h.Set("Content-Type", contentType)
if c.Request.Method == http.MethodHead {
h.Set("Content-Length", strconv.Itoa(len(body)))
c.Status(http.StatusOK)
c.Writer.WriteHeaderNow()
return
}
c.Data(http.StatusOK, contentType, body)
}

View file

@ -0,0 +1,236 @@
package httpapi
import (
"net/http"
"net/http/httptest"
"strings"
"testing"
"testing/fstest"
)
const indexHTML = `<!doctype html><title>Sonda app</title><script type="module" src="/assets/app-abc123.js"></script>`
// theApp is a small built web app: a page, hashed assets, a top-level file, and files that must never be served.
func theApp() fstest.MapFS {
return fstest.MapFS{
"index.html": {Data: []byte(indexHTML)},
"favicon.svg": {Data: []byte("<svg xmlns='http://www.w3.org/2000/svg'/>")},
"assets/app-abc123.js": {Data: []byte("console.log('app')")},
"assets/app-abc123.css": {Data: []byte("body{margin:0}")},
"assets/font-1.woff2": {Data: []byte("font")},
"assets/.hidden": {Data: []byte("secret")},
".gitkeep": {Data: []byte("")},
}
}
func serve(t *testing.T, app fstest.MapFS, method, path string) *httptest.ResponseRecorder {
t.Helper()
h, _ := newTestEnv(t, func(d *Deps) {
if app != nil {
d.Web = app
}
})
rec := httptest.NewRecorder()
h.ServeHTTP(rec, httptest.NewRequest(method, path, nil))
return rec
}
func TestRootServesTheAppWithItsHeaders(t *testing.T) {
rec := serve(t, theApp(), http.MethodGet, "/")
if rec.Code != http.StatusOK {
t.Fatalf("status %d, want 200", rec.Code)
}
if rec.Body.String() != indexHTML {
t.Errorf("body %q is not the page of the app", rec.Body.String())
}
if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/html") {
t.Errorf("Content-Type %q, want text/html", ct)
}
if got := rec.Header().Get("Cache-Control"); got != "no-cache" {
t.Errorf("Cache-Control %q: the page must be asked again, so that an update shows at once", got)
}
for header, want := range map[string]string{
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"Referrer-Policy": "no-referrer",
} {
if got := rec.Header().Get(header); got != want {
t.Errorf("%s = %q, want %q", header, got, want)
}
}
csp := rec.Header().Get("Content-Security-Policy")
for _, directive := range []string{
"default-src 'self'", "script-src 'self'", "connect-src 'self'", "img-src 'self' data: blob:",
"media-src 'self' blob:", "font-src 'self'", "object-src 'none'", "frame-ancestors 'none'",
"base-uri 'self'", "form-action 'self'", "style-src 'self'", "style-src-attr 'unsafe-inline'",
} {
if !strings.Contains(csp, directive) {
t.Errorf("the policy %q lacks %q", csp, directive)
}
}
// Nothing in the policy may let the page reach another server.
if strings.Contains(csp, "http:") || strings.Contains(csp, "https:") || strings.Contains(csp, "*") {
t.Errorf("the policy %q allows resources from outside", csp)
}
if strings.Contains(csp, "script-src 'self' 'unsafe") || strings.Contains(csp, "'unsafe-eval'") {
t.Errorf("the policy %q allows inline or eval scripts", csp)
}
}
func TestDirectLinksOfTheAppServeThePage(t *testing.T) {
for _, path := range []string{"/admin/users", "/artists/5", "/search?q=bjork", "/settings"} {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code != http.StatusOK || rec.Body.String() != indexHTML {
t.Errorf("GET %s: status %d, body %q; want the page of the app", path, rec.Code, rec.Body.String())
}
if rec.Header().Get("Content-Security-Policy") == "" {
t.Errorf("GET %s: no policy", path)
}
}
}
func TestAssetsAreServedWithTheirTypeAndForever(t *testing.T) {
cases := map[string]string{
"/assets/app-abc123.js": "javascript",
"/assets/app-abc123.css": "text/css",
"/assets/font-1.woff2": "font/woff2",
}
for path, wantType := range cases {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code != http.StatusOK {
t.Errorf("GET %s: status %d, want 200", path, rec.Code)
continue
}
if ct := rec.Header().Get("Content-Type"); !strings.Contains(ct, wantType) {
t.Errorf("GET %s: Content-Type %q, want %q", path, ct, wantType)
}
if got := rec.Header().Get("Cache-Control"); got != "public, max-age=31536000, immutable" {
t.Errorf("GET %s: Cache-Control %q: a file with a hash in its name never changes", path, got)
}
if rec.Header().Get("X-Content-Type-Options") != "nosniff" {
t.Errorf("GET %s: no nosniff", path)
}
}
}
func TestATopLevelFileIsServedButAskedAgain(t *testing.T) {
rec := serve(t, theApp(), http.MethodGet, "/favicon.svg")
if rec.Code != http.StatusOK || !strings.Contains(rec.Header().Get("Content-Type"), "svg") {
t.Fatalf("status %d, type %q; want the icon", rec.Code, rec.Header().Get("Content-Type"))
}
if got := rec.Header().Get("Cache-Control"); got != "no-cache" {
t.Errorf("Cache-Control %q: a file with no hash in its name may change", got)
}
}
// A script that is missing must never come back as the HTML page: the browser would try to run it.
func TestAMissingFileIsA404NotThePage(t *testing.T) {
for _, path := range []string{"/assets/nope.js", "/assets/", "/assets", "/missing.js", "/some/deep/missing.css", "/robots.txt"} {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code != http.StatusNotFound {
t.Errorf("GET %s: status %d, want 404", path, rec.Code)
}
if strings.Contains(rec.Body.String(), "Sonda app") {
t.Errorf("GET %s: answered with the page of the app", path)
}
}
}
func TestHiddenFilesAreNeverServed(t *testing.T) {
for _, path := range []string{"/.gitkeep", "/assets/.hidden", "/.env", "/assets/../.gitkeep"} {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code == http.StatusOK && rec.Body.String() != indexHTML {
t.Errorf("GET %s: served %q", path, rec.Body.String())
}
if strings.Contains(rec.Body.String(), "secret") {
t.Errorf("GET %s: leaked a hidden file", path)
}
}
if rec := serve(t, theApp(), http.MethodGet, "/assets/.hidden"); rec.Code != http.StatusNotFound {
t.Errorf("a hidden file under assets: status %d, want 404", rec.Code)
}
}
func TestHeadWorksAndSendsNoBody(t *testing.T) {
rec := serve(t, theApp(), http.MethodHead, "/")
if rec.Code != http.StatusOK || rec.Body.Len() != 0 {
t.Errorf("HEAD /: status %d with %d bytes", rec.Code, rec.Body.Len())
}
if rec := serve(t, theApp(), http.MethodHead, "/assets/app-abc123.js"); rec.Code != http.StatusOK {
t.Errorf("HEAD of an asset: status %d", rec.Code)
}
}
func TestOtherMethodsOutsideTheAPIAreAJSON404(t *testing.T) {
for _, method := range []string{http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch} {
rec := serve(t, theApp(), method, "/admin/users")
if rec.Code != http.StatusNotFound {
t.Errorf("%s /admin/users: status %d, want 404", method, rec.Code)
}
if !strings.Contains(rec.Body.String(), `"code":"not_found"`) {
t.Errorf("%s /admin/users: body %q, want the JSON error", method, rec.Body.String())
}
}
}
// The API keeps answering as it did: an unknown address under /api is a JSON 404, never the page.
func TestUnknownAPIAddressesStayJSON404(t *testing.T) {
for _, path := range []string{"/api/v1/not-there", "/api/nothing", "/api"} {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code != http.StatusNotFound {
t.Errorf("GET %s: status %d, want 404", path, rec.Code)
}
if !strings.Contains(rec.Body.String(), `"code":"not_found"`) || strings.Contains(rec.Body.String(), "Sonda app") {
t.Errorf("GET %s: body %q, want the JSON error", path, rec.Body.String())
}
}
}
func TestTheAPIAndItsDocsAreNotAffected(t *testing.T) {
if rec := serve(t, theApp(), http.MethodGet, "/api/v1/health"); rec.Code != http.StatusOK {
t.Errorf("health: status %d", rec.Code)
}
rec := serve(t, theApp(), http.MethodGet, "/api/docs/")
if rec.Code != http.StatusOK {
t.Fatalf("docs: status %d", rec.Code)
}
if strings.Contains(rec.Header().Get("Content-Security-Policy"), "default-src") {
t.Errorf("the docs page got the policy of the app: %q", rec.Header().Get("Content-Security-Policy"))
}
}
func TestPathsThatTryToLeaveTheAppDoNotBreakAnything(t *testing.T) {
for _, path := range []string{"/..%2f..%2fetc%2fpasswd", "/%2e%2e/%2e%2e/etc/passwd", "/assets/..%2f..%2fgo.mod", "/%00"} {
rec := serve(t, theApp(), http.MethodGet, path)
if rec.Code >= 500 {
t.Errorf("GET %s: status %d", path, rec.Code)
}
if strings.Contains(rec.Body.String(), "root:") || strings.Contains(rec.Body.String(), "module codeberg.org") {
t.Errorf("GET %s: left the app", path)
}
}
}
// With no app in the binary (a build without the webui tag) / says how to build it, and the API works.
func TestWithNoAppTheRootSaysHowToBuildIt(t *testing.T) {
for name, app := range map[string]fstest.MapFS{"nil": nil, "empty": {}} {
for _, path := range []string{"/", "/admin/users"} {
rec := serve(t, app, http.MethodGet, path)
if rec.Code != http.StatusOK {
t.Errorf("%s FS, GET %s: status %d, want 200", name, path, rec.Code)
}
body := rec.Body.String()
for _, want := range []string{"make build", "/api/docs/", "/api/v1"} {
if !strings.Contains(body, want) {
t.Errorf("%s FS, GET %s: the page does not mention %q", name, path, want)
}
}
if !strings.HasPrefix(rec.Header().Get("Content-Type"), "text/html") {
t.Errorf("%s FS: Content-Type %q", name, rec.Header().Get("Content-Type"))
}
}
if rec := serve(t, app, http.MethodGet, "/api/v1/health"); rec.Code != http.StatusOK {
t.Errorf("%s FS: the API does not work, status %d", name, rec.Code)
}
}
}