Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
6d28e06
feat(api): create internal/api package structure
mattmattox Dec 31, 2025
7daedbe
feat(api): implement route registration with groups
mattmattox Dec 31, 2025
8d7ecae
feat(api): implement middleware (auth, CORS, logging)
mattmattox Dec 31, 2025
3b24cce
feat(api): define comprehensive JSON request/response types
mattmattox Dec 31, 2025
215587b
feat(api): implement /health endpoint with component health checks
mattmattox Dec 31, 2025
098f467
feat(api): implement /api/v1/status endpoint with version and capacit…
mattmattox Dec 31, 2025
a247e98
feat(api): integrate API server into mount command
mattmattox Dec 31, 2025
dd68b18
feat(api): add CLI flags for API server configuration
mattmattox Dec 31, 2025
68450f4
feat(fs): add SnapshotRegistry() accessor for API endpoints
mattmattox Dec 31, 2025
760ffe5
feat(stats): create internal/stats package structure
mattmattox Dec 31, 2025
3e619d7
feat(stats): add TrimStats, SFBStats, and ClusterInfo types
mattmattox Dec 31, 2025
707e96f
feat(api): implement stats endpoints for cache, journal, trim, lock, …
mattmattox Dec 31, 2025
f5beb8c
style(api): gofmt the API and stats code
mattmattox Nov 10, 2026
a8146bf
fix(api): bind to loopback by default and refuse remote access withou…
mattmattox Nov 10, 2026
33b0bdc
fix(mount): warn at startup when broadcast runs without a secret
mattmattox Nov 10, 2026
4c94506
fix(api): read the build version from internal/version
mattmattox Nov 10, 2026
f1bbcf1
docs: document the HTTP API flags, loopback default and new warnings
mattmattox Nov 10, 2026
79c2ee5
test(stats): cover the filesystem provider
mattmattox Nov 10, 2026
78c425c
test(api): create the image file before sizing it
mattmattox Nov 10, 2026
76d66a8
fix(mount): skip API shutdown when the API never started
mattmattox Nov 10, 2026
e373cf4
fix(api): close CORS, DNS-rebinding and auth-path gaps
mattmattox Nov 10, 2026
68e93dd
fix(mount): check the API flags before opening the device
mattmattox Nov 10, 2026
2174722
docs: document the Host check and the CORS rule without a token
mattmattox Nov 10, 2026
cbbcc4f
Merge remote-tracking branch 'origin/main' into claude/land-api-work-…
mattmattox Nov 10, 2026
6732903
Merge remote-tracking branch 'origin/claude/land-api-work-c8b883' int…
mattmattox Nov 10, 2026
ec51891
Merge origin/main (#48 squash) into claude/api-hardening
mattmattox Nov 10, 2026
0c30ba9
ci: trigger checks after retargeting to main
mattmattox Nov 10, 2026
6fc9959
test(api): format and mount in one process in the loopback health test
mattmattox Nov 10, 2026
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
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- CI gates: unit tests with the race detector and coverage, golangci-lint (`make lint`), govulncheck (`make vuln`), and a `go mod tidy` check.
- Release workflow: pushing a `v*` tag publishes a GitHub Release with `linux/amd64` and `linux/arm64` archives, checksums, and the matching `CHANGELOG.md` section. `scripts/dist.sh` builds the same archives locally.
- `goclusterfs-fsck -version` prints the release version, commit, and commit date.
- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` without `-api-token`.
- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` or `-api-cors '*'` without `-api-token`, and checks the API flags before it opens the device.
- `goclusterfs-mount -version`, which prints the same version string as `goclusterfs-fsck -version`. `/api/v1/status` reports it too.
- Mount logs a `WARNING` line at startup when `-broadcast` is on without `-broadcast-secret`.
- Design, deployment, operations, and troubleshooting docs in `docs/`.
Expand Down
12 changes: 10 additions & 2 deletions cmd/mount/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package main

import (
"context"
"errors"
"flag"
"fmt"
"log"
Expand Down Expand Up @@ -55,7 +56,7 @@ func (p *fsStatusProvider) Capacity() *api.CapacityInfo {
freeBlocks := p.bitmapMgr.FreeCount()
usedBlocks := totalBlocks - freeBlocks

const blockSize uint64 = 1024 * 1024 // 1MB blocks
const blockSize uint64 = goclusterfs.BlockSize
totalBytes := totalBlocks * blockSize
usedBytes := usedBlocks * blockSize
freeBytes := freeBlocks * blockSize
Expand Down Expand Up @@ -148,8 +149,15 @@ func main() {

apiCfg := apiConfig(*apiAddr, *apiToken, *apiCORS)
if *apiEnabled {
if err := apiCfg.Validate(); err != nil {
log.Fatalf("Invalid API settings: %v", err)
}
if err := apiCfg.CheckExposure(); err != nil {
log.Fatalf("Refusing to start the API: %v. Set -api-token, set -api-addr to a loopback address such as 127.0.0.1:8080, or pass -api=false", err)
hint := "set -api-addr to a loopback address such as 127.0.0.1:8080"
if errors.Is(err, api.ErrWildcardCORSWithoutToken) {
hint = "list the allowed origins in -api-cors"
}
log.Fatalf("Refusing to start the API: %v. Set -api-token, %s, or pass -api=false", err, hint)
}
}
if *broadcastEnabled && *broadcastSecret == "" {
Expand Down
2 changes: 2 additions & 0 deletions docs/API-CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,8 @@ The kernel caches file attributes and directory entries for `-attr-timeout`. For

The API serves `GET /health`, `GET /metrics`, `GET /api/v1/status` and `GET /api/v1/stats/...`. Mount does not feed statistics to the API yet, so `/api/v1/stats/...` answers 503, `/health` only checks the API itself, and `/metrics` only reports `goclusterfs_up`. With `-api-token` set, `/api/v1/...` requests need `Authorization: Bearer <token>`. `/health` and `/metrics` never need the token.

Without `-api-token`, the API answers only requests whose `Host` header is `localhost`, a `127.x` address or `[::1]`, so a web page cannot reach it through DNS rebinding, and mount refuses `-api-cors '*'`. List the dashboard's origin instead, for example `-api-cors http://localhost:5173`.

By default the API only accepts connections from this host. To serve other hosts, set `-api-addr` (for example `:8080` or `10.0.0.5:8080`) and `-api-token`. Mount exits before it opens the device when the address is not loopback (`127.0.0.0/8`, `::1` or `localhost`) and the token is empty. The token is a command-line flag, so local users can read it with `ps`.

Each mount on a host needs its own `-api-addr`. When the port is taken, mount logs a warning and runs without the API.
Expand Down
1 change: 1 addition & 0 deletions docs/OPERATIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,7 @@ GoClusterFS assumes every node, and everything that can reach the shared device

- To expose it, set `-api-addr` and `-api-token`. Mount refuses a non-loopback address without a token.
- `/health` and `/metrics` never need the token, so anyone who can reach the port can read them.
- Without a token, the API rejects requests whose `Host` header is not a loopback name, and mount refuses `-api-cors '*'`. Both stop web pages that a local user opens from reading the API.
- The API uses plain HTTP. Put a TLS proxy in front of it if the token crosses an untrusted network.
- The token is a command-line flag, so local users can read it with `ps`.

Expand Down
11 changes: 9 additions & 2 deletions internal/api/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"fmt"
"net"
"net/url"
"slices"
"strings"
"time"
)
Expand Down Expand Up @@ -133,11 +134,17 @@ func (c *Config) LoopbackOnly() bool {
return ip != nil && ip.IsLoopback()
}

// CheckExposure refuses a config that serves other hosts without an auth token.
// CheckExposure refuses a config that lets other hosts, or any web page, read the API without an auth token.
func (c *Config) CheckExposure() error {
if c.AuthToken == "" && !c.LoopbackOnly() {
if c.AuthToken != "" {
return nil
}
if !c.LoopbackOnly() {
return fmt.Errorf("%w: %s", ErrUnauthenticatedRemote, c.ListenAddr)
}
if slices.Contains(c.CORSOrigins, "*") {
return ErrWildcardCORSWithoutToken
}
return nil
}

Expand Down
13 changes: 7 additions & 6 deletions internal/api/doc.go
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
// Package api provides the HTTP JSON API server for GoClusterFS.
//
// The API server runs embedded within the mount process and exposes
// endpoints for health checks, status queries, statistics, and
// administrative operations. It is consumed by the gfsctl CLI tool
// and the web dashboard.
// read-only endpoints for health checks, status queries and statistics.
//
// # Endpoints
//
// The following endpoints are available:
//
// - GET /health - Health check (always returns 200)
// - GET /health - Health check (503 when a checker reports unhealthy)
// - GET /api/v1/status - Filesystem status overview
// - GET /api/v1/stats/* - Detailed component statistics
// - GET /metrics - Prometheus metrics export
Expand All @@ -18,16 +16,19 @@
//
// Authentication is via Bearer token when configured. Set the AuthToken
// in Config to enable authentication. When enabled, all endpoints except
// /health require a valid Authorization header:
// /health and /metrics require a valid Authorization header:
//
// Authorization: Bearer <token>
//
// Without a token, Config.CheckExposure refuses non-loopback addresses and
// CORS "*", and the server rejects requests whose Host is not a loopback name.
//
// # Configuration
//
// Use DefaultConfig() to get sensible defaults, then customize as needed:
//
// cfg := api.DefaultConfig()
// cfg.ListenAddr = ":9090"
// cfg.ListenAddr = "127.0.0.1:9090"
// cfg.AuthToken = "secret-token"
// server, err := api.NewServer(cfg)
//
Expand Down
3 changes: 3 additions & 0 deletions internal/api/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ var (
// ErrUnauthenticatedRemote is returned when other hosts could reach the API without a token.
ErrUnauthenticatedRemote = errors.New("api: no auth token set for an address other hosts can reach")

// ErrWildcardCORSWithoutToken is returned when CORS allows every origin and no token is set.
ErrWildcardCORSWithoutToken = errors.New("api: CORS origin \"*\" without an auth token lets any web page open on this host read the API")

// ErrShutdownTimeout is returned when graceful shutdown times out.
ErrShutdownTimeout = errors.New("api: shutdown timed out")
)
100 changes: 100 additions & 0 deletions internal/api/exposure_test.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package api

import (
"context"
"errors"
"net/http"
"testing"
)

Expand Down Expand Up @@ -38,3 +40,101 @@ func TestDefaultConfigPassesExposureCheck(t *testing.T) {
t.Fatalf("default config refused: %v", err)
}
}

func TestCheckExposureRefusesWildcardCORSWithoutToken(t *testing.T) {
cfg := DefaultConfig().WithCORSOrigins("*")
if err := cfg.CheckExposure(); !errors.Is(err, ErrWildcardCORSWithoutToken) {
t.Fatalf("CORS * without token: got %v, want ErrWildcardCORSWithoutToken", err)
}
cfg = cfg.WithAuthToken("secret")
if err := cfg.CheckExposure(); err != nil {
t.Fatalf("CORS * with token refused: %v", err)
}
cfg = DefaultConfig().WithCORSOrigins("http://localhost:5173")
if err := cfg.CheckExposure(); err != nil {
t.Fatalf("listed CORS origin refused: %v", err)
}
}

func get(t *testing.T, srv *Server, path, host string, header map[string]string) *http.Response {
t.Helper()
req, err := http.NewRequest(http.MethodGet, "http://"+srv.Addr()+path, nil)
if err != nil {
t.Fatal(err)
}
if host != "" {
req.Host = host
}
for k, v := range header {
req.Header.Set(k, v)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatal(err)
}
resp.Body.Close()
return resp
}

func startServer(t *testing.T, cfg Config) *Server {
t.Helper()
srv, err := NewServer(cfg)
if err != nil {
t.Fatal(err)
}
if err := srv.Start(context.Background()); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { srv.Stop() })
return srv
}

func TestTokenlessLoopbackServerRejectsForeignHost(t *testing.T) {
srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0"))
for host, want := range map[string]int{
"": http.StatusOK,
"localhost:8080": http.StatusOK,
"LOCALHOST": http.StatusOK,
"[::1]:8080": http.StatusOK,
"127.0.0.2": http.StatusOK,
"evil.example": http.StatusForbidden,
"evil.example:80": http.StatusForbidden,
"10.0.0.5:8080": http.StatusForbidden,
} {
if got := get(t, srv, "/api/v1/status", host, nil).StatusCode; got != want {
t.Errorf("Host %q: status %d, want %d", host, got, want)
}
}
}

func TestTokenServerSkipsHostCheck(t *testing.T) {
srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret"))
resp := get(t, srv, "/api/v1/status", "evil.example", map[string]string{"Authorization": "Bearer secret"})
if resp.StatusCode != http.StatusOK {
t.Fatalf("status %d, want 200", resp.StatusCode)
}
}

func TestAuthSkipsOnlyExactPaths(t *testing.T) {
srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret"))
for _, path := range []string{"/health/x", "/metrics/x"} {
if got := get(t, srv, path, "", nil).StatusCode; got != http.StatusUnauthorized {
t.Errorf("%s without token: status %d, want 401", path, got)
}
}
if got := get(t, srv, "/health", "", nil).StatusCode; got != http.StatusOK {
t.Errorf("/health without token: status %d, want 200", got)
}
}

func TestCORSHeaders(t *testing.T) {
srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithCORSOrigins("http://localhost:5173"))
resp := get(t, srv, "/health", "", map[string]string{"Origin": "http://other.example"})
if resp.Header.Get("Vary") != "Origin" {
t.Errorf("Vary = %q, want Origin", resp.Header.Get("Vary"))
}
resp = get(t, srv, "/health", "", map[string]string{"Origin": "http://localhost:5173"})
if got := resp.Header.Get("Access-Control-Allow-Methods"); got != "GET, HEAD, OPTIONS" {
t.Errorf("Allow-Methods = %q, want GET, HEAD, OPTIONS", got)
}
}
39 changes: 33 additions & 6 deletions internal/api/middleware.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package api
import (
"crypto/subtle"
"log"
"net"
"net/http"
"strings"
"time"
Expand Down Expand Up @@ -61,7 +62,7 @@ func AuthMiddleware(token string, skipPaths ...string) Middleware {

// Check if path should skip auth
for _, path := range skipPaths {
if r.URL.Path == path || strings.HasPrefix(r.URL.Path, path+"/") {
if r.URL.Path == path {
next.ServeHTTP(w, r)
return
}
Expand Down Expand Up @@ -103,6 +104,7 @@ func CORSMiddleware(origins []string) Middleware {
next.ServeHTTP(w, r)
return
}
w.Header().Add("Vary", "Origin")

origin := r.Header.Get("Origin")
if origin == "" {
Expand All @@ -111,22 +113,22 @@ func CORSMiddleware(origins []string) Middleware {
}

// Check if origin is allowed
allowed := false
allowOrigin := ""
for _, o := range origins {
if o == "*" || o == origin {
allowed = true
allowOrigin = o
break
}
}

if !allowed {
if allowOrigin == "" {
next.ServeHTTP(w, r)
return
}

// Set CORS headers
w.Header().Set("Access-Control-Allow-Origin", origin)
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Origin", allowOrigin)
w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
w.Header().Set("Access-Control-Max-Age", "86400")

Expand All @@ -140,3 +142,28 @@ func CORSMiddleware(origins []string) Middleware {
})
}
}

// LoopbackHostMiddleware rejects requests whose Host header is not a loopback
// name, so a DNS-rebinding web page cannot read an API that has no token.
func LoopbackHostMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !isLoopbackHost(r.Host) {
writeError(w, http.StatusForbidden, "host not allowed", "without an auth token, use localhost, 127.0.0.1 or [::1]")
return
}
next.ServeHTTP(w, r)
})
}

func isLoopbackHost(hostport string) bool {
host := hostport
if h, _, err := net.SplitHostPort(hostport); err == nil {
host = h
}
host = strings.TrimSuffix(strings.Trim(host, "[]"), ".")
if strings.EqualFold(host, "localhost") {
return true
}
ip := net.ParseIP(host)
return ip != nil && ip.IsLoopback()
}
4 changes: 2 additions & 2 deletions internal/api/middleware_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -281,8 +281,8 @@ func TestCORSMiddleware_Wildcard(t *testing.T) {
defer resp.Body.Close()

cors := resp.Header.Get("Access-Control-Allow-Origin")
if cors != "http://any-origin.com" {
t.Errorf("expected CORS header 'http://any-origin.com', got %q", cors)
if cors != "*" {
t.Errorf("expected CORS header '*', got %q", cors)
}
}

Expand Down
11 changes: 7 additions & 4 deletions internal/api/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,16 @@ func NewServer(cfg Config) (*Server, error) {
// Register routes
s.registerRoutes()

// Build middleware chain (order: logging -> CORS -> auth)
handler := Chain(
s.router,
LoggingMiddleware,
// Build middleware chain (order: logging -> loopback Host check -> CORS -> auth)
middlewares := []Middleware{LoggingMiddleware}
if cfg.AuthToken == "" && cfg.LoopbackOnly() {
middlewares = append(middlewares, LoopbackHostMiddleware)
}
middlewares = append(middlewares,
CORSMiddleware(cfg.CORSOrigins),
AuthMiddleware(cfg.AuthToken, "/health", "/metrics"),
)
handler := Chain(s.router, middlewares...)

// Create HTTP server
s.server = &http.Server{
Expand Down
Loading
Loading