go-http-routing-stub-auth-ordering

Answer

Root cause (C19 + C20): the auth gate was a global middleware wrapping the mux with no knowledge of stub routes, and /instance/* had no registration at all.

• C19 — /instance/* existed in neither main.go's mux nor the shim mux → every request 404'd.
• C20 — PATCH /project/:id hit authMiddleware before the 501 stub → unauthenticated callers got 401 instead of 501.

Fix (SPEC-017 §3.9): register + mount /instance/* as 501 stubs in both route tables, and replace the blunt "auth everything" gate with an ordering valve: auth is required only for GET on /project and /vcs. Everything else — /instance/* (fully public), non-GET stub calls, and unmounted paths — bypasses auth and lets the mux answer (501 or 404). This is the single point that reconciles the two suites: shim smoke (no-auth GET → 401) and full-contract (stubs → 501, unmounted → 404).

// isStubPath — auth-skip predicate (SPEC-017 §3.9):
//   - /instance/* fully public, every method
//   - /project/* & /vcs/*: GET auth-gated; non-GET reaches the 501 stub
func isStubPath(path, method string) bool {
    if pathIn(path, "/instance") { return true }
    if method == http.MethodGet { return false }
    return pathIn(path, "/project") || pathIn(path, "/vcs")
}

// authRequired — the only auth gate in the stub stage.
func authRequired(path, method string) bool {
    return method == http.MethodGet &&
        (pathIn(path, "/project") || pathIn(path, "/vcs"))
}

func pathIn(path, prefix string) bool {
    return path == prefix || strings.HasPrefix(path, prefix+"/")
}

// authMiddleware runs OUTSIDE the route table; the gate applies only to GET
// on /project|/vcs. PATCH /project/:id no longer hits 401 before the stub.
func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !authRequired(r.URL.Path, r.Method) {
            next.ServeHTTP(w, r) // public / stub / unmounted: no auth check
            return
        }
        if r.Header.Get("Authorization") != bearerToken {
            writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
            return
        }
        next.ServeHTTP(w, r)
    })
}

func stubHandler(w http.ResponseWriter, r *http.Request) {
    writeJSON(w, http.StatusNotImplemented, map[string]string{
        "error": "not implemented", "method": r.Method, "path": r.URL.Path,
    })
}

// C19: register + mount /instance/* in the PRODUCTION mux …
func newMux() *http.ServeMux {
    mux := http.NewServeMux()
    mux.HandleFunc("/project/", routeHandler)
    mux.HandleFunc("/vcs/", routeHandler)
    mux.HandleFunc("/instance/", stubHandler) // ← was missing → 404
    return mux
}

// … and in the SHIM mux used by smoke tests.
func newShimMux() *http.ServeMux {
    mux := http.NewServeMux()
    mux.HandleFunc("/project/", routeHandler)
    mux.HandleFunc("/vcs/", routeHandler)
    mux.HandleFunc("/instance/", stubHandler) // ← was missing → 404
    return mux
}

func newHandler() http.Handler      { return authMiddleware(newMux()) }
func newShimHandler() http.Handler  { return authMiddleware(newShimMux()) }

The fix is two lines of routing registration plus one ordering predicate — no stub-handler changes, no contract hacks.