GoFin services consolidation & hardening: shared platform layer, dead-code sweep, correctness fixes

frontend/apps/finance/src/features/settings/__tests__/ExportDataSection.test.tsx

@@ -318,7 +318,6 @@ describe("ExportDataSection", () => {
             body: {
               code: "RATE_LIMITED",
               message: `Export limit reached. You can request another export after ${formatDateOnly(retryAfter)}.`,
-              retryAfter,
             },
           },
         ]),
@@ -587,7 +586,6 @@ describe("ExportDataSection", () => {
             body: {
               code: "RATE_LIMITED",
               message: `Export limit reached. Next available: ${retryAfter}`,
-              retryAfter,
             },
           },
         ]),

frontend/apps/finance/src/features/settings/types.ts

@@ -26,13 +26,6 @@ export interface ExportListResponse {
   hasMore: boolean;
 }
 
-/** Error response from 429 rate-limited requests. */
-export interface ExportRateLimitedResponse {
-  code: string;
-  message: string;
-  retryAfter: string;
-}
-
 /** Export lifecycle phases: exactly one is active at any time. */
 export type ExportStatus = 'idle' | 'loading' | 'creating' | 'polling' | 'error';
 

services/access/access.go

@@ -5,19 +5,19 @@
 // from the Registry) can import it without a build dependency on each other.
 //
 // The package owns three things:
-//   - the Access classification applied to every route (access.go),
+//   - the access Level applied to every gateway-facing route (access.go),
 //   - the Registry of concrete routes and their access levels (registry.go),
 //   - a gin-priority path resolver used by the gateway middleware (resolver.go).
 package access
 
-// Access is the classification applied to every gateway-facing route. It
+// Level is the access classification applied to every gateway-facing route. It
 // determines whether a request needs a token and, if so, which role may
 // proceed.
-type Access int
+type Level int
 
 const (
 	// Public routes are reachable with no token.
-	Public Access = iota
+	Public Level = iota
 	// Authenticated routes require any valid token, regardless of role.
 	Authenticated
 	// Personal routes require a valid token acting as a regular user (role == "user").
@@ -32,7 +32,7 @@ const (
 )
 
 // String returns the level name, used for readable logs and test diagnostics.
-func (a Access) String() string {
+func (a Level) String() string {
 	switch a {
 	case Public:
 		return "Public"

services/access/proxy.go

@@ -12,21 +12,33 @@ type ProxyPrefix struct {
 	Service string
 }
 
-// ProxyPrefixes is the ordered inventory of downstream prefixes the gateway
+// proxyPrefixes is the ordered inventory of downstream prefixes the gateway
 // proxies and the service each targets. It makes "what prefixes and services
 // exist" part of the single source of truth: the gateway derives its proxy
 // wiring from this list (see services/gateway/internal/router), and a
 // cross-check test pins it against the Registry so every classified route sits
 // under a proxied prefix and every proxied prefix has at least one classified
 // route.
 //
+// It is set once at init and unexported so no caller can reassign it; the
+// gateway reads a copy via Prefixes().
+//
 // Two prefixes map to the auth service: /api/auth (its own routes) and
 // /api/admin (operator routes such as GET /api/admin/users, still served by
 // auth even though their Access is Admin).
-var ProxyPrefixes = []ProxyPrefix{
+var proxyPrefixes = []ProxyPrefix{
 	{Prefix: "/api/auth", Service: "auth"},
 	{Prefix: "/api/admin", Service: "auth"},
 	{Prefix: "/api/expenses", Service: "expense"},
 	{Prefix: "/api/finance", Service: "finance"},
 	{Prefix: "/api/datarights", Service: "datarights"},
 }
+
+// Prefixes returns a copy of the proxy-prefix inventory. The copy is why the
+// gateway can derive its routing wiring (router.New) from this list without
+// being able to mutate the shared, init-time-fixed backing array.
+func Prefixes() []ProxyPrefix {
+	out := make([]ProxyPrefix, len(proxyPrefixes))
+	copy(out, proxyPrefixes)
+	return out
+}

services/access/proxy_test.go

@@ -16,7 +16,7 @@ func underPrefix(path, prefix string) bool {
 // coveringPrefix returns the single ProxyPrefix a path sits under (prefixes are
 // disjoint on segment boundaries, so at most one matches).
 func coveringPrefix(path string) (ProxyPrefix, bool) {
-	for _, p := range ProxyPrefixes {
+	for _, p := range proxyPrefixes {
 		if underPrefix(path, p.Prefix) {
 			return p, true
 		}
@@ -30,7 +30,7 @@ func coveringPrefix(path string) (ProxyPrefix, bool) {
 // same service that serves the route (else the gateway would forward it to the
 // wrong downstream).
 func TestProxyPrefixes_EveryRegistryRouteIsReachable(t *testing.T) {
-	for _, r := range Registry {
+	for _, r := range registry {
 		prefix, ok := coveringPrefix(r.Path)
 		if !ok {
 			t.Errorf("route %s (%s %s) is classified but sits under no ProxyPrefix; the gateway would never proxy it (add a ProxyPrefix for its prefix)", r.ID, r.Method, r.Path)
@@ -47,9 +47,9 @@ func TestProxyPrefixes_EveryRegistryRouteIsReachable(t *testing.T) {
 // prefix with no Registry route is proxied-but-unclassified, so under
 // deny-by-default every request to it would 403 (a silently dead prefix).
 func TestProxyPrefixes_EveryPrefixHasARoute(t *testing.T) {
-	for _, p := range ProxyPrefixes {
+	for _, p := range proxyPrefixes {
 		found := false
-		for _, r := range Registry {
+		for _, r := range registry {
 			if underPrefix(r.Path, p.Prefix) {
 				found = true
 				break

services/access/registry.go

@@ -20,20 +20,20 @@ type Route struct {
 	// "/api/finance/tags/:id" or "/api/expenses/:id/history".
 	Path string
 	// Access is the classification enforced by the gateway middleware.
-	Access Access
+	Access Level
 }
 
-// Registry is the single, exhaustive list of every gateway-facing downstream
-// route. It is the sole source of truth: downstream services register their
-// routes by iterating RoutesFor, and the gateway classifies each request by
-// resolving against these patterns (see resolver.go).
+// registry is the single, exhaustive list of every gateway-facing downstream
+// route. It is the sole source of truth, set once at init and unexported so no
+// caller can reassign it: downstream services read it via RoutesFor and the
+// gateway classifies each request via Resolve (see resolver.go).
 //
 // Gateway-native endpoints (/health, /metrics) are intentionally absent: no
 // downstream service serves them, so the gateway classifies them itself.
 //
 // Path strings must match gin's registered patterns byte-for-byte (verified by
 // each service's registration coverage test against engine.Routes()).
-var Registry = []Route{
+var registry = []Route{
 	// --- auth service ---
 	{ID: "auth.register", Service: "auth", Method: http.MethodPost, Path: "/api/auth/register", Access: Public},
 	{ID: "auth.login", Service: "auth", Method: http.MethodPost, Path: "/api/auth/login", Access: Public},
@@ -89,23 +89,10 @@ var Registry = []Route{
 // a route missing from the Registry can never be served.
 func RoutesFor(service string) []Route {
 	var routes []Route
-	for _, r := range Registry {
+	for _, r := range registry {
 		if r.Service == service {
 			routes = append(routes, r)
 		}
 	}
 	return routes
 }
-
-// Classifies reports whether method+path is matched by an explicit Registry
-// entry, as opposed to falling through to the fail-safe Deny default in
-// Resolve. Services use it as a defense-in-depth check that every route they
-// register is classified by the Registry.
-func Classifies(method, path string) bool {
-	for _, r := range Registry {
-		if r.Method == method && matchPattern(r.Path, path) {
-			return true
-		}
-	}
-	return false
-}

services/access/registry_test.go

@@ -5,8 +5,8 @@ import "testing"
 // TestRegistry_IDsAreUnique guards the bind-by-ID contract: services look up
 // handlers by Route.ID, so a duplicate ID would silently shadow a handler.
 func TestRegistry_IDsAreUnique(t *testing.T) {
-	seen := make(map[string]Route, len(Registry))
-	for _, r := range Registry {
+	seen := make(map[string]Route, len(registry))
+	for _, r := range registry {
 		if prev, dup := seen[r.ID]; dup {
 			t.Errorf("duplicate route ID %q: %s %s and %s %s", r.ID, prev.Method, prev.Path, r.Method, r.Path)
 		}
@@ -18,24 +18,13 @@ func TestRegistry_IDsAreUnique(t *testing.T) {
 // directly from the Registry (no second hand-list): every entry's own
 // method+path must resolve to the Access it declares.
 func TestRegistry_EveryEntryResolvesToItsAccess(t *testing.T) {
-	for _, r := range Registry {
+	for _, r := range registry {
 		if got := Resolve(r.Method, r.Path); got != r.Access {
 			t.Errorf("Resolve(%q, %q) = %s, want %s (route %s)", r.Method, r.Path, got, r.Access, r.ID)
 		}
 	}
 }
 
-// TestRegistry_EveryEntryIsClassified confirms Classifies agrees with the
-// Registry for every real route: each entry's path is matched by an explicit
-// entry rather than the fail-safe default.
-func TestRegistry_EveryEntryIsClassified(t *testing.T) {
-	for _, r := range Registry {
-		if !Classifies(r.Method, r.Path) {
-			t.Errorf("Classifies(%q, %q) = false, want true (route %s)", r.Method, r.Path, r.ID)
-		}
-	}
-}
-
 // TestRoutesFor_PartitionsRegistry proves RoutesFor slices the Registry cleanly:
 // the four known services together account for every entry with no gaps or
 // duplicates, and each returned route actually belongs to the requested service.
@@ -53,8 +42,8 @@ func TestRoutesFor_PartitionsRegistry(t *testing.T) {
 		total += len(routes)
 	}
 
-	if total != len(Registry) {
-		t.Errorf("RoutesFor over %v covered %d routes, but Registry has %d; a service is misnamed or missing", services, total, len(Registry))
+	if total != len(registry) {
+		t.Errorf("RoutesFor over %v covered %d routes, but Registry has %d; a service is misnamed or missing", services, total, len(registry))
 	}
 }
 
@@ -65,31 +54,3 @@ func TestRoutesFor_UnknownServiceIsEmpty(t *testing.T) {
 		t.Errorf("RoutesFor(%q) = %d routes, want 0", "nope", len(routes))
 	}
 }
-
-// TestClassifies_UnknownRoutesAreUnclassified is the failure-mode guardrail: a
-// route with no Registry entry, or a real path under the wrong method, is not
-// classified, so Resolve returns the fail-safe Deny default (403 at the
-// gateway).
-func TestClassifies_UnknownRoutesAreUnclassified(t *testing.T) {
-	cases := []struct {
-		name   string
-		method string
-		path   string
-	}{
-		{"unknown service", "GET", "/api/newservice/records"},
-		{"wrong method on a real route", "GET", "/api/auth/login"},
-		{"sibling substring of a real route", "POST", "/api/datarights/exports-admin"},
-		{"bare group with no exact route", "GET", "/api/finance"},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if Classifies(tc.method, tc.path) {
-				t.Errorf("Classifies(%q, %q) = true, want false", tc.method, tc.path)
-			}
-			if got := Resolve(tc.method, tc.path); got != Deny {
-				t.Errorf("Resolve(%q, %q) = %s, want Deny (fail-safe default)", tc.method, tc.path, got)
-			}
-		})
-	}
-}

services/access/resolver.go

@@ -19,10 +19,10 @@ import "strings"
 // borrow "/api/datarights/exports"'s level: static segments must match
 // byte-for-byte. This makes the leading-substring bug that segment-boundary
 // prefix matching guarded against (commit ca37e4c) impossible by construction.
-func Resolve(method, path string) Access {
+func Resolve(method, path string) Level {
 	var best *Route
-	for i := range Registry {
-		entry := &Registry[i]
+	for i := range registry {
+		entry := &registry[i]
 		if entry.Method != method || !matchPattern(entry.Path, path) {
 			continue
 		}

services/access/resolver_test.go

@@ -10,7 +10,7 @@ func TestResolve_WorkedExamples(t *testing.T) {
 		name   string
 		method string
 		path   string
-		want   Access
+		want   Level
 	}{
 		{"login is public", "POST", "/api/auth/login", Public},
 		{"register is public", "POST", "/api/auth/register", Public},
@@ -65,6 +65,7 @@ func TestResolve_FallsBackToDeny(t *testing.T) {
 		{"bare admin group", "GET", "/api/admin"},
 		{"bare datarights group", "GET", "/api/datarights"},
 		{"unknown api path", "GET", "/api/unknown"},
+		{"unknown service deep path", "GET", "/api/newservice/records"},
 		{"extra trailing segment", "GET", "/api/finance/tags/abc/extra"},
 	}
 

services/apierr/codes.go

@@ -0,0 +1,16 @@
+// Package apierr single-sources the GoFin API error contract: the typed
+// service error, the shared error-code constants, and the HTTP wire-response
+// mapping. It is the one place the {code, message, fields?} contract lives so
+// all four API services emit a byte-identical error shape.
+package apierr
+
+// Shared, cross-service error codes (domain truth). Service-specific codes
+// (e.g. PERIOD_LOCKED, DUPLICATE_TAG) stay as local constants in each service;
+// they are still valid Code strings and do not belong here.
+const (
+	CodeUnauthorized = "UNAUTHORIZED"
+	CodeNotFound     = "NOT_FOUND"
+	CodeValidation   = "VALIDATION_ERROR"
+	CodeInternal     = "INTERNAL_SERVER_ERROR"
+	CodeForbidden    = "FORBIDDEN"
+)

services/apierr/error.go

@@ -0,0 +1,40 @@
+package apierr
+
+import "net/http"
+
+// Error is the single typed service error. It carries everything the wire
+// contract can express, including Fields (the field-level validation detail
+// that most services drop today).
+type Error struct {
+	Code    string            // maps to the "code" wire field
+	Message string            // maps to "message"
+	Status  int               // HTTP status to write
+	Fields  map[string]string // optional field-level validation detail
+}
+
+func (e *Error) Error() string { return e.Message }
+
+// Unauthorized builds a 401 UNAUTHORIZED error.
+func Unauthorized(msg string) *Error {
+	return &Error{Code: CodeUnauthorized, Message: msg, Status: http.StatusUnauthorized}
+}
+
+// NotFound builds a 404 NOT_FOUND error.
+func NotFound(msg string) *Error {
+	return &Error{Code: CodeNotFound, Message: msg, Status: http.StatusNotFound}
+}
+
+// Validation builds a 400 VALIDATION_ERROR error carrying optional field detail.
+func Validation(msg string, fields map[string]string) *Error {
+	return &Error{Code: CodeValidation, Message: msg, Status: http.StatusBadRequest, Fields: fields}
+}
+
+// Conflict builds a 409 error with a caller-supplied code (for DUPLICATE_* style codes).
+func Conflict(code, msg string) *Error {
+	return &Error{Code: code, Message: msg, Status: http.StatusConflict}
+}
+
+// Internal builds a 500 INTERNAL_SERVER_ERROR error.
+func Internal(msg string) *Error {
+	return &Error{Code: CodeInternal, Message: msg, Status: http.StatusInternalServerError}
+}