Before you begin
- The
shopproject from Add a database table with a CRUD API and pages, with itsProductandReviewentities. Any forge API works the same way. - Forge v1.6.1 or later, run as
reliant forgeinside the project. jq, to read the JSON report.
1
List the RPCs that never read the caller
The check is the The list itself is under A handler counts as reading the caller when it calls
unscoped_auth category of project audit. There is no lint flag for it.terminal
categories:terminal
middleware.GetUser, directly or through a helper in its own package.2
Decide what each RPC needs
Every RPC on the list gets one of three answers:
- Rows belong to someone. Filter by the caller.
Reviewand any order or account table are this case: follow Scope rows to their owner. - Only some callers may do it. Check a role. Changing the product catalog is this case.
- It is the same for every signed-in caller. Say so in code. Reading the catalog is this case.
3
Check a role
Write the check once, as a helper in the handler package:Call it first in
internal/handlers/catalog/authz.go
CreateProduct, UpdateProduct and DeleteProduct:internal/handlers/catalog/handlers_crud.go
Claims.Roles comes from the token’s roles claim. Roles kept in your own tables can be added in the enrichClaims hook in pkg/middleware, which runs before any handler.4
Mark the global reads
Put the marker on the handler’s doc comment. The reason after the colon is required: a bare Do the same for
// forge:auth-unscoped-ok is ignored, and the RPC stays on the list.internal/handlers/catalog/handlers_crud.go
GetProduct.5
Run the audit again
terminal
jq output
Review RPCs are left for owner scoping.6
Prove the check with a test
The audit proves a handler reads the caller, not that it decides correctly. A test does. Give the scaffolded test context the role (
crudTestCtx in handlers_crud_test.go now needs Roles: []string{"admin"}, or the lifecycle test fails with admin role required), and add a caller without it:terminal
7
Check that each listener serves one kind of caller
A user’s token must not reach a service meant for daemons or operators. A mismatch fails with
lint --graph checks that every listener serves only services of its authenticator’s audience (//forge:audience user on NewUserAuth in internal/app/providers.go):terminal
forge-graph-audience.What this does not do
- It is a static check. It finds handlers that never read the caller. It can’t tell whether a handler that does read the caller uses the answer correctly; that is what your tests are for.
- It warns, and
project auditexits 0, until you declare an owner. Aforge:ownercolumn turns the RPCs over that table into errors that fail the audit. See Scope rows to their owner. - A custom RPC can’t arm the gate. The audit matches RPCs to tables by their CRUD names, so a custom RPC is listed as a warning only.
- Forge writes no access rules. It has no roles or permission model of its own. Every check on this page is code in your repository.
Troubleshooting
jq prints null
jq prints null
The category is nested: use
.categories.unscoped_auth.details.unscoped_rpcs, not .unscoped_auth.The RPC stays on the list after you add the marker
The RPC stays on the list after you add the marker
The marker needs a reason after a colon, and it must sit on the handler method’s doc comment:
// forge:auth-unscoped-ok: <reason>.create #1: admin role required
create #1: admin role required
The scaffolded lifecycle test calls with
crudTestCtx(), which has no roles. Add the role your check requires to the claims there.Next steps
Scope rows to their owner
Declare a
forge:owner column and filter every query by the callerSecurity model
Fail-closed auth, the audit, audiences and error redaction
Add sign-in
Passkeys, magic links or social login, and the RPCs that stay public
Middleware and the request path
Where the auth interceptor and your enrich hook run