Tracking: converting the route table to pure handlers

[otavio]

The roadmap for the handler conversion, recovered from a local planning file that was never
committed. It is here so the stack has a link.

Decision

Deepen the route declaration seam before converting the remaining ~160 handlers.

#6941 gave routes three shapes and a gateway.Declaration recording what a
route claims. #7030 made mounting and declaring the same act, so a declaration
now knows its own address, permission and API-key policy, and the route-table tests are invariants
over every route the router mounts rather than a hand-maintained ledger.

Stack

master
└─ #6941 / cloud#2509 ......... three shapes                                 (open)
   └─ #7030 .................... registration declares the whole claim       (open)
      └─ A-cloud ............... cloud adopts the same registration  (spec: team#239)
         └─ B .................. list-query contract moves into the List shape
            └─ A′ ............... every route states a permission or why it needs none
               └─ A′-cloud ...... the same for the /admin/api surface
                  └─ C… ......... per-resource conversion (separate planning pass)

The original plan ordered this A → A′ → B, with cloud following one step behind at each rung.
Reordered for two reasons: cloud/ does not compile against #7030 until A-cloud lands, which
taxes every change made in the workspace meanwhile; and A′ is a security review needing a human
answer per route, so it should not block a mechanical cleanup. B depends on A only — Accepts
is a RouteOption on the mount call, which #7030 delivered.

A-cloud — cloud adopts the same registration

Spec: shellhub-io/team#239.

The four shape constructors changed return type in #7030, so internal/billing/routes,
internal/admin/routes and internal/cloud/routes no longer build. Mechanical: the same diff shape
as #7030 over 81 call sites, with Requires/NoAPIKey/Guard already built and tested. Cloud
registers no declarations today, so the audits do not yet see it.

Note the billing webhook registers on the router root, and the two admin groups are groups — all
three are covered by gateway.MountOn(router, target).

B — the list-query contract belongs to the List shape

Goal. Delete the 14 shellhub (and later 7 cloud) copies of normalize → unmarshal → validate →
log → 400, and the 171-line go/ast test that polices them.

Shape. gateway.Accepts(services.DeviceQuery) on the registration; prepare[T] runs the
contract before the handler is entered, where it already normalizes the paginator and sorter. The
per-resource FieldSet/FieldConstraints pairs move behind one named value per resource.

Carries these fixes. The List shape owns X-Total-Count, so the three endpoints answering it
with len(list) — the page size, not the collection size — are corrected as a side effect:
access-policy.go:32, service-account.go:34, ssh-identity.go:48. invitation.go's
FormatInt/Itoa split goes with them. The default sort columns picked in api-key.go:52 and
install-key.go:57 move to the resource's contract, where they are policy rather than handler code.

Deletes. server/api/routes/list_validation_test.go, replaced by a check over Declarations():
a List route names a query contract.

A′ — every route states a permission claim, or why it needs none

A security review, not a mechanical diff. 21 mutating shellhub routes carry no permission today.
Most are legitimately self-service or pre-credential (auth, register, accept invite, leave
namespace, web reauth, setup) and want gateway.NoPermission("...") with a written reason.

One is not what the route table suggests: DeleteSSHIdentity registers with no permission while its
two siblings require SSHIdentityAdd. It is guarded, in the handler body, so the behaviour is
correct — the route table under-reports it, which is exactly the class of thing declaring the
permission at the registration is meant to end.

Ends with the invariant: a route names a permission or states why it needs none. Same argument
as Unbounded/Anonymous — the claim cannot arrive by omission.

A′-cloud covers the 30 /admin/api routes, which need a decision rather than a default:
shellhub-io/team#238.

Deferred, and why

• Per-resource conversion of the remaining ~160 handlers — the bulk of the work, but it wants
  its own planning pass once A and B fix the shape of a converted route. Each resource carries
  scope-into-the-service and actor-instead-of-req.UserID for that resource.
• gateway.Context deletion (15 accessors, duplicate pairs, GetTennat) — falls out of the
  conversion, not before it.
• MCP calling handlers directly — needs A, because the httptest round-trip is currently what
  re-runs the permission check.
• Authorization decided in handlers (req.Manage, the silent req.All downgrade,
  GetNamespace's membership check) — behaviour changes; keep them out of mechanical PRs so they
  are reviewed as such.
• The tenant guard and the legacy authorize middleware — the latter looks close to vestigial,
  and deciding its fate is a behaviour question.
• Collapsing the anonymous allowlist into the route table — the allowlist must survive for
  routes that never touch the gateway, and registering from the mount call needs an authenticator
  the mount helper does not have. The all-routes anonymity invariant added in refactor(server): make route registration and declaration the same act #7030 is what makes
  this safe to do later.

CI

A PR based on a feature branch runs zero checks in these repos: the workflows are gated on
branches: [master]. Every PR in this stack needs lint and tests run locally, in-container, before
it is called green.

[otavio]

A′ is specified in #7036.

Two corrections to this issue's A′ section, from the audit that produced that spec:

• The count is 46 registrations without a permission, 21 of them mutating — not 21 in total. The
  spec classifies all 46.
• The vocabulary needs three options, not one. NoPermission(reason) alone would file
  DeleteSSHIdentity — guarded in the handler by two acceptable permissions — under the same word as
  a route that is genuinely open. RequiresAny moves that guard back onto the mounting line;
  PermissionInHandler(reason) records the four routes whose admission decision needs request data
  the middleware cannot see.

The audit also found one bug in scope for that rung: POST /api/auth/device and POST /api/auth/user
declare no anonymity and are in no allowlist, so the authenticator's fail-closed default answers 401
to the clients they exist for. anonymityMismatches misses it because a route carrying neither claim
nor entry reads as consistent.

[otavio]

A′-cloud is specified in shellhub-io/team#240.

Three corrections to this issue's A′-cloud line, from the audit that produced that spec:

• The count is 54 registrations, not 30: 32 on /admin/api (26 in the admin package, 4 in
  AddAdminRoutes, and 2 mounted with raw group.GET that declare nothing at all), 21 on the
  public /api surface, and GET /api/billing/customer. Cloud's own surface needs the claim too,
  not just admin's.
• team#238 framed the admin decision as cheap-versus-thorough; it is narrower than that.
  Requires resolves to ctx.Role().HasPermission(...), and on /admin/api there is no role to
  ask: the authenticator strips the identity's user and tenant on that prefix, and an instance API
  key yields Admin: true with no role at all. Stating a real permission there would 403 every
  instance-API-key caller. Option 1 is the only behaviour-neutral answer, and team#240 closes
  team#238 by picking it.
• The audit found one gap in scope for that rung and one bug adjacent to it. TunnelsCreate and
  TunnelsDelete are defined, granted to admin and owner, and referenced by no production
  code in either repo — so an observer can expose a device port publicly through any of the four
  web-endpoint/tunnel writes. And GET /admin/api/auth/token/:id mints a JWT for any user named in
  the path, with no check on the caller, while being one of the two routes Declarations() cannot
  see. team#240 recommends declaring the first and filing it separately, since applying the
  permission would also 403 every service-role API key.

[gustavosbarreto]

Two of three now. #7149 deletes `routes/service-account.go`, so the handlers answering `X-Total-Count` with `len(list)` are `access-policy.go:32` and `ssh-identity.go:48`. The rest of the carried-fixes list is unaffected.