Subscribe

A ratchet test that stops new gin routes shipping without an authorization policy

Keep route authorization in one table keyed by method and gin route template, then let two tests guard it: one fails on policies for routes that don't exist, and a ratchet file lets the list of routes without a policy shrink but never grow.

A ratchet test that stops new gin routes shipping without an authorization policy

Most authorization bugs in an API are not clever. Someone adds GET /v1/users/:user_id/orders, tests it with their own user id, it works, it ships. Nobody tried someone else's id. Code review didn't catch it because the handler looked fine, the missing check is the thing that isn't there.

In this blog we will look at the setup I like for gin: all route policies in one table keyed by method and route template, plus two tests. One fails when a policy points at a route that doesn't exist. The other is a ratchet: a small file lists routes that are allowed to have no policy, and that list can only get shorter.

Why one table

You can protect routes by wrapping each handler, r.GET(path, requireOwner(handler)). It works, but you can't easily answer "which routes have no check?" without reading every file. When we moved route checks into one central table, the main gain was that the answer became a diff between two sets:

  • every route gin knows about, from router.Routes()
  • every key in the policy table

Two sets can be compared in a test. A few hundred handlers spread over many files can't.

The key is the HTTP method plus gin's route template, the same string c.FullPath() returns. So one policy covers /v1/users/u1/orders and /v1/users/u2/orders.

The registry

Here is the core of the authz package I wrote for this post. It is generic, the full code also has PUT/DELETE helpers and an admin check.

package authz

import (
    "fmt"
    "log/slog"
    "net/http"
    "sync"

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

type Key struct {
    Method string
    Path   string // gin route template, e.g. /v1/users/:user_id/orders
}

func GET(p string) Key { return Key{http.MethodGet, p} }

type Caller struct {
    ID    string
    Admin bool
}

type Policy struct {
    Name  string
    Allow func(c *gin.Context, who *Caller) bool
}

type Registry struct {
    mu       sync.RWMutex
    policies map[Key]Policy
}

func NewRegistry() *Registry { return &Registry{policies: map[Key]Policy{}} }

// Register adds policies. Two policies for one route means one silently
// wins, so a duplicate panics at startup.
func (r *Registry) Register(entries map[Key]Policy) {
    r.mu.Lock()
    defer r.mu.Unlock()
    for k, p := range entries {
        if _, dup := r.policies[k]; dup {
            panic(fmt.Sprintf("authz: duplicate policy for %s %s", k.Method, k.Path))
        }
        r.policies[k] = p
    }
}

The panic on duplicates looks harsh. I prefer it. Two policies for the same route in a Go map means the last one registered wins, and which one is last depends on the order of init or setup calls. A crash at boot is easier to fix than a rule that is right on Monday and wrong after a refactor.

Policies are small functions. The one that matters most is "the caller owns the id in the path, or is an admin":

func SelfOrAdmin(param string) Policy {
    return Policy{Name: "self_or_admin", Allow: func(c *gin.Context, who *Caller) bool {
        if who == nil {
            return false
        }
        return who.Admin || (who.ID != "" && who.ID == c.Param(param))
    }}
}

And the table for the example service:

func registerPolicies(reg *authz.Registry) {
    reg.Register(map[authz.Key]authz.Policy{
        authz.GET("/healthz"):                      authz.Public(),
        authz.GET("/v1/products"):                  authz.Authenticated(),
        authz.GET("/v1/users/:user_id/orders"):     authz.SelfOrAdmin("user_id"),
        authz.DELETE("/v1/admin/orders/:order_id"): authz.AdminOnly(),
    })
}

The middleware

The middleware looks up c.FullPath(). If there is a policy, it runs it. If there isn't, the route has to be on a known list of older routes that still do their check inside the handler; anything else gets a 403. That list is the same file the ratchet test reads, embedded with go:embed.

func (r *Registry) Middleware(legacy map[Key]bool) gin.HandlerFunc {
    return func(c *gin.Context) {
        k := Key{Method: c.Request.Method, Path: c.FullPath()}
        if k.Path == "" { // no route matched, let gin return 404
            c.Next()
            return
        }

        p, ok := r.Lookup(k)
        if !ok {
            if legacy[k] {
                c.Next()
                return
            }
            slog.Warn("authz: route has no policy", "method", k.Method, "path", k.Path)
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "forbidden"})
            return
        }

        if !p.Allow(c, CallerFrom(c)) {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "forbidden"})
            return
        }
        c.Next()
    }
}

Denying at runtime is good, but a 403 in production is still a bug report from a user. I want the build to fail before that. That's what the two tests are for.

Test 1: policies that point at nothing

The table is keyed on strings. Rename :user_id to :id in the router and forget the table, and the policy just never matches. So the first test builds the real router and checks every policy key exists in it:

func TestPoliciesMatchRealRoutes(t *testing.T) {
    routes, reg := realRoutes(t)
    var orphans []string
    for k := range reg.Snapshot() {
        if !routes[k] {
            orphans = append(orphans, k.Method+" "+k.Path)
        }
    }
    slices.Sort(orphans)
    if len(orphans) > 0 {
        t.Errorf("policies for routes that do not exist:\n  %s", strings.Join(orphans, "\n  "))
    }
}

func realRoutes(t *testing.T) (map[authz.Key]bool, *authz.Registry) {
    t.Helper()
    gin.SetMode(gin.TestMode)
    r, reg := NewRouter()
    out := map[authz.Key]bool{}
    for _, ri := range r.Routes() {
        out[authz.Key{Method: ri.Method, Path: ri.Path}] = true
    }
    if len(out) == 0 {
        t.Fatal("router has no routes")
    }
    return out, reg
}

When I checked this, I made the typo on purpose and wrote :userid in the table. Three things failed at once, which was nice to see:

--- FAIL: TestPoliciesMatchRealRoutes (0.00s)
    router_authz_test.go:44: policies for routes that do not exist:
          GET /v1/users/:userid/orders
--- FAIL: TestAuthzRatchet (0.00s)
    router_authz_test.go:86: new route(s) with no authz policy. Register one in registerPolicies:
          GET /v1/users/:user_id/orders
--- FAIL: TestMiddleware (0.00s)
    --- FAIL: TestMiddleware/own_orders (0.00s)
        router_authz_test.go:132: got 403, want 200

Test 2: the ratchet

If you bring a policy table into an API that already has a lot of routes, you won't write every policy on day one. Older routes keeps their in-handler checks for a while. The ratchet is a text file that names them:

# Routes that predate the policy table. May shrink, must not grow.
GET /v1/users/:user_id/addresses

The test works out which real routes have no policy, and fails if any of them is not on that list. Routes that got a policy since are only logged, with a hint to re-record:

var updateLegacy = flag.Bool("update-legacy-routes", false, "re-record legacy_routes.txt")

func TestAuthzRatchet(t *testing.T) {
    routes, reg := realRoutes(t)
    policies := reg.Snapshot()

    var uncovered []string
    for k := range routes {
        if _, ok := policies[k]; !ok {
            uncovered = append(uncovered, k.Method+" "+k.Path)
        }
    }
    slices.Sort(uncovered)

    if *updateLegacy {
        body := "# Routes that predate the policy table. May shrink, must not grow.\n" +
            strings.Join(uncovered, "\n") + "\n"
        if err := os.WriteFile("legacy_routes.txt", []byte(body), 0o644); err != nil {
            t.Fatal(err)
        }
        t.Logf("recorded %d legacy routes", len(uncovered))
        return
    }

    b, err := os.ReadFile("legacy_routes.txt")
    if err != nil {
        t.Fatal(err)
    }
    legacy := ParseRouteList(string(b))

    var added []string
    for _, line := range uncovered {
        method, path, _ := strings.Cut(line, " ")
        if !legacy[authz.Key{Method: method, Path: path}] {
            added = append(added, line)
        }
    }
    if len(added) > 0 {
        t.Errorf("new route(s) with no authz policy. Register one in registerPolicies:\n  %s",
            strings.Join(added, "\n  "))
    }

    var fixed []string
    for k := range legacy {
        if _, ok := policies[k]; ok || !routes[k] {
            fixed = append(fixed, k.Method+" "+k.Path)
        }
    }
    if len(fixed) > 0 {
        slices.Sort(fixed)
        t.Logf("%d legacy route(s) now covered or gone, re-record to tighten:\n  %s",
            len(fixed), strings.Join(fixed, "\n  "))
    }
}

Adding a route without a policy now looks like this in CI:

--- FAIL: TestAuthzRatchet (0.00s)
    router_authz_test.go:86: new route(s) with no authz policy. Register one in registerPolicies:
          PUT /v1/users/:user_id/orders/:order_id

And when someone finally writes a policy for the addresses route, the test passes and nudges:

go test ./api/ -run Ratchet -v
go test ./api/ -run Ratchet -update-legacy-routes
    router_authz_test.go:98: 1 legacy route(s) now covered or gone, re-record to tighten:
          GET /v1/users/:user_id/addresses

Why log and not fail on shrink? Because failing would punish the person who did the right thing. Logging plus a re-record keeps the file honest without making anyone's day worse.

Re-recording is a decision

The flag is there so that growing the list is possible, but it shows up as a diff in legacy_routes.txt in the pull request. That line is easy to spot in review, much easier than a missing check inside a handler. I'd also add a CODEOWNERS rule on that file so one specific person has to approve it.

It's the same idea as the golden hash test from the post on keeping a shared golang package in sync: put the thing you want to protect in a small text file, and let a test compare reality against it.

Testing the policies themselves

The table tests prove a policy exists. They don't prove it's right, so I keep a plain table-driven test over the real router too:

{"own orders", "GET", "/v1/users/u1/orders", "u1", "", 200},
{"someone else's orders", "GET", "/v1/users/u2/orders", "u1", "", 403},
{"admin reads any orders", "GET", "/v1/users/u2/orders", "a1", "1", 200},
{"no caller", "GET", "/v1/products", "", "", 403},
{"legacy route, handler check", "GET", "/v1/users/u2/addresses", "u1", "", 403},
{"unknown route", "GET", "/nope", "u1", "", 404},

The "someone else's id" row is the one people forget. Write it for every route that takes a user id.

I built and ran this with Go 1.27.3 and gin v1.12.0. The example uses two headers as fake auth to keep it short; in a real service the caller comes from your token middleware, which runs before the authz middleware.