Phase 16: hardening and release 0.1.0

- TOTP second factor (RFC 6238, secret encrypted under the master key),
  ten hashed single-use recovery codes, two-step login with a pending token
  bound to the client address, account enrolment/disable, admin reset
- tests/security: prompt-injection corpus never acts or creates evidence-free
  beliefs; roles and CSRF on form and API paths; cross-mind isolation
  (demo scenario 5); stored-XSS escaping and CSP across pages; secrets never
  echoed (API, pages, database, archives); hostile archive import; session
  lifecycle and security headers
- OpenAPI 3.1 document generated from the route table, served at
  /api/v1/openapi.json and kept complete by a test
- gosec clean (justified #nosec annotations, cookie/redirect hardening,
  bounded multipart parsing, UUID packing without narrowing conversions);
  govulncheck clean with toolchain pinned to go1.26.8
- THREAT_MODEL verification pointers, SECURITY.md testing section, README,
  CHANGELOG 0.1.0, docs/RELEASE_NOTES.md, PLAN status

internal/api/openapi_test.go

@@ -0,0 +1,41 @@
+package api
+
+import (
+	"encoding/json"
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// TestOpenAPICoversEveryRoute keeps openapi.json honest: every /api/v1 route
+// registered in this package must be documented with its method.
+func TestOpenAPICoversEveryRoute(t *testing.T) {
+	var doc struct {
+		Paths map[string]map[string]any `json:"paths"`
+	}
+	if err := json.Unmarshal(openAPI, &doc); err != nil {
+		t.Fatal(err)
+	}
+	re := regexp.MustCompile(`Handle(?:Func)?\("(GET|POST|PUT|PATCH|DELETE) (/api/v1[^"]*)"`)
+	entries, _ := os.ReadDir(".")
+	var missing []string
+	for _, e := range entries {
+		if !strings.HasSuffix(e.Name(), ".go") || strings.HasSuffix(e.Name(), "_test.go") {
+			continue
+		}
+		src, _ := os.ReadFile(e.Name())
+		for _, m := range re.FindAllStringSubmatch(string(src), -1) {
+			method, path := strings.ToLower(m[1]), m[2]
+			if path == "/api/v1/openapi.json" {
+				continue
+			}
+			if _, ok := doc.Paths[path][method]; !ok {
+				missing = append(missing, m[1]+" "+path)
+			}
+		}
+	}
+	if len(missing) > 0 {
+		t.Fatalf("routes missing from openapi.json (regenerate it):\n%s", strings.Join(missing, "\n"))
+	}
+}

internal/api/server.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	_ "embed"
 	"net/http"
 
 	"github.com/prometheus/client_golang/prometheus/promhttp"
@@ -11,6 +12,10 @@ import (
 )
 
 // Server composes the API routes, the web UI and the middleware chain.
+//
+//go:embed openapi.json
+var openAPI []byte
+
 type Server struct {
 	deps           app.Deps
 	mux            *http.ServeMux
@@ -42,6 +47,10 @@ func (s *Server) routes() {
 	m.Handle("GET /metrics", require(auth.RoleObserver, promhttp.HandlerFor(s.deps.Metrics.Registry, promhttp.HandlerOpts{}).ServeHTTP))
 
 	m.Handle("GET /api/v1/system/status", require(auth.RoleObserver, s.systemStatus))
+	m.HandleFunc("GET /api/v1/openapi.json", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write(openAPI) //nolint:errcheck
+	})
 	m.Handle("GET /api/v1/audit", require(auth.RoleOperator, s.auditList))
 
 	m.Handle("GET /api/v1/users", require(auth.RoleAdministrator, s.usersList))