Skip to main content
A forge API turns away every request without a valid credential, but a valid credential only proves the caller is signed in. Any signed-in user can call a handler that never asks who they are, which is how one customer ends up reading another’s orders (IDOR, or BOLA in the OWASP API list). This guide finds those handlers and closes each one. Forge can find them because it knows which RPCs require sign-in, from the proto, and can read the Go handler that serves each one. The security model explains the design.

Before you begin

  • The shop project from Add a database table with a CRUD API and pages, with its Product and Review entities. Any forge API works the same way.
  • Forge v1.6.1 or later, run as reliant forge inside the project.
  • jq, to read the JSON report.
1

List the RPCs that never read the caller

The check is the unscoped_auth category of project audit. There is no lint flag for it.
terminal
The list itself is under categories:
terminal
A handler counts as reading the caller when it calls 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. Review and 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:
internal/handlers/catalog/authz.go
Call it first in 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 // forge:auth-unscoped-ok is ignored, and the RPC stays on the list.
internal/handlers/catalog/handlers_crud.go
Do the same for GetProduct.
5

Run the audit again

terminal
jq output
The three product writes now count as scoped, the two reads appear with their reasons for a reviewer, and the five 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. 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
A mismatch fails with 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 audit exits 0, until you declare an owner. A forge:owner column 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

The category is nested: use .categories.unscoped_auth.details.unscoped_rpcs, not .unscoped_auth.
The marker needs a reason after a colon, and it must sit on the handler method’s doc comment: // forge:auth-unscoped-ok: <reason>.
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 caller

Security 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