feat(client): carry declared auth end to end, from security schemes to client capabilities

[juicycleff]

This started as one wrong line in spec_parser.go and grew into the whole path an auth requirement travels: what your service declares, what the router writes into the OpenAPI document, and what a generated client can do with it once it gets there. Authentication is the first half. Authorization is the second, and it is new here.

The bug it started as

The generated Go client could not do cookie or session auth. It turns out it could not do much else either: it sent X-API-Key for every apiKey scheme whatever the document declared, ignored query and cookie locations entirely, declared basic-auth fields that nothing read, and had no cookie jar, so a login-then-use flow was impossible.

One line caused most of it. spec_parser.go built the client IR like this:

secScheme := SecurityScheme{
    Type: scheme.Type,
    Name: name,        // the securitySchemes MAP KEY
    In:   scheme.In,
}

Name on the source type is the wire parameter name, the session_id in {type: apiKey, in: cookie, name: session_id}. The parser overwrote it with the map key and dropped it, and the IR had one Name field for two different concepts, so there was nowhere to put it even if the parser had wanted to keep it. With nothing to emit, the generator hardcoded.

The server side was fine the whole time. APIKeyProvider takes WithAPIKeyCookie(name) and emits {apiKey, cookie, <name>} correctly, and the OpenAPI generator puts it in components.securitySchemes. Your service was describing itself accurately and the client generator threw the answer away one step later.

Authentication: one field per declared scheme

SecurityScheme now carries Key and ParamName separately. That rename is the point: it made the compiler enumerate every read site so each could be checked rather than mechanically renamed.

The generated AuthConfig has one typed field per declared scheme, named from the scheme key:

type AuthConfig struct {
    BearerAuth  string           // http bearer   -> Authorization: Bearer <v>
    BasicAuth   BasicCredentials // http basic    -> Authorization: Basic <...>
    SessionAuth string           // apiKey cookie -> session_id
    TenantKey   string           // apiKey header -> X-Tenant-Key
    ListKey     string           // apiKey query  -> api_key
}

A single apply(header, url) puts each credential where the document says it goes, and REST, SSE, WebSocket and WebTransport all route through it. Before this, addAuth was REST-only and the WebSocket path carried its own bearer-only copy, which is how the two drifted apart.

Sessions are opt-in:

c := api.NewClient(base, api.WithSessionJar())
_ = c.Login(ctx, creds)   // the server sets the cookie
me, _ := c.Me(ctx)        // the jar replays it

A jar makes the client stateful, so the doc comment says plainly that it must not be shared between users. WithCookieJar(jar) takes your own if you want a per-user or persistent one.

On the TypeScript side the manifest emits a securitySchemes table plus per-operation scheme keys, so an AuthProvider can dispatch on meta.security the way transport.ts always said it would. RestTransportOptions gained credentials, threaded through to the generated fetch client, for cross-origin cookie sessions. Unset by default, so nothing changes unless you ask for it.

Authorization: declared once, carried the whole way

AuthContext now holds Roles and Permissions next to the scopes it already had, and a route's requirement is a value rather than a closure:

type Requirement struct {
    Providers   []string // authentication
    Scopes      []string // all of
    Roles       []string // any of
    Permissions []string // all of
    Mode        string   // "or" or "and", providers only
}

That constraint is deliberate. A value can be written into an OpenAPI document and read back by a generated client, and a closure cannot, which is what keeps resource-scoped questions (can this user edit document 42) inside handlers where they have the document in hand.

Registry.SetAuthorizer is the seam. Forge ships plain set membership and stops there: no role hierarchies, no permission inheritance, no wildcard matching. That is policy, and warden replaces the authorizer wholesale to provide it.

Routes and groups declare what they want:

router.DELETE("/users/:id", handler,
    forge.WithRequiredAuth("jwt"),
    forge.WithAnyRole("admin", "owner"),
    forge.WithAllPermissions("users:write", "users:delete"),
)

The names carry the combining rule because a name that hides and-versus-or sends you to the source to find out. Declaring records a requirement on the route's metadata and nothing more; enforcement happens when that requirement reaches MiddlewareWithRequirement. The docs used to read as though the option itself did the checking, and no longer do.

From there the OpenAPI generator carries roles and permissions as x-forge-authz, which is how the client generator learns about them without importing the auth extension.

What the clients do with it

Both generated clients get a capability surface. In Go:

c.SetPrincipal(api.Principal{
    Roles:       []api.Role{api.RoleAdmin},
    Permissions: []api.Permission{api.PermissionUsersWrite},
})

if c.CanCall(api.OperationNameDeleteUser) {
    // render the button
}

missing := c.MissingCapabilities(api.OperationNameDeleteUser)

TypeScript gets the same vocabulary in its own idiom: setPrincipal, can, hasRole, hasPermission, canCall, missingCapabilities, and a requiredCapabilities table you can read directly. It also has capabilitiesKnown(), so a UI can tell "this principal may not" apart from "nobody has told us yet" instead of rendering a disabled button at a user who is merely still loading.

None of this is a gate. Every predicate answers from a principal you handed the client, so it exists to hide a button the server would refuse anyway. The generated file says so in its own header, and the review that added it kept finding places where the wording implied more than that.

Two names that meant two opposite things

auth.roles was route metadata for the roles a route requires, and also the context key for the roles the subject holds. Same for auth.scopes. Different maps, so nothing ever collided at runtime, but one literal covering both requirement and possession is a trap for whoever reads it next.

The context keys are now auth.subject.roles and auth.subject.scopes. The route metadata keys are untouched, since the OpenAPI and client generators read them. Both interceptors still honour the old key as a deprecated fallback, so an application that sets it from its own middleware keeps working.

Breaking change

AuthConfig.BearerToken and AuthConfig.APIKey are gone.

// before
client.WithAuth(api.AuthConfig{BearerToken: tok, APIKey: key})

// after: one field per declared scheme
client.WithAuth(api.AuthConfig{BearerAuth: tok, TenantKey: key, SessionAuth: sid})

Regenerate and rename at the call site. There is no compatibility flag, because the old shape could not express what the specs already declared.

The generated client compiles now, which it did not before

This was not planned. While verifying the auth work, we wrote generated output into a scratch module and ran a real build. It failed, and had been failing for a while: client.go, rest.go and types.go emitted imports that go unused for some specs, client.go and websocket.go referenced c.auth when no AuthConfig was declared at all, and webtransport.go destructured the dial as (*Session, *http.Response, error) when every version of webtransport-go returns those two the other way round.

All of that is fixed here, and six more of the same shape once we went looking: dead imports as soon as a streaming endpoint declares no payload schema, a time in websocket.go nobody had noticed, a doc comment that a multi-line inline struct broke out of, a go.mod that never required webtransport-go at all, and a Dialer the package had renamed to Transport several versions earlier. ConnectionState and the reconnect helpers moved into streaming.go on the way, because sse.go used all four and only websocket.go declared them, so an SSE-only spec generated a client naming identifiers nothing had defined.

Two gates stand behind that now. Every emitted file gets parsed and each import checked for a real user, which needs no module cache and runs everywhere. Then TestGoGeneratorGeneratedModuleBuilds writes a generated client into a temporary module and runs the actual compiler over six configurations, because an undefined symbol and an unresolvable module are both perfectly valid syntax with no unused imports, and only a compiler finds them. It skips rather than fails when the environment cannot support a build, under -short, with no go on PATH, or when the module cache cannot resolve offline. Compile errors are never skipped, so a green run offline still means everything checkable was checked.

Six client-core gaps, closed along the way

Not auth, but on the branch: entity garbage collection, container identity across a refetch, a WebTransport adapter, hydration for Vue and Angular, and a streamed SSR payload. Each was written down in the README as deliberately left rather than overlooked, so that list is six shorter.

The refetch one is the behaviour change to know about. A refetch used to hand back a new root even when no record moved, because a second skeleton gets built and the container memos are keyed by node identity. read() now takes the previous value and reuses a container whose children are all identical to it. That changes what useQuery gives you, and the React test asserting the old contract asserts its converse now.

Verification

• go build ./... and go vet clean; go test ./internal/client/... ./internal/router/... ./extensions/auth/... passes
• packages/client-core: suite green, typecheck clean, all size budgets within limit
• web-client/generated-package.mdx documents the generated auth surface and the breaking change

Two tests are worth reading rather than skimming. The end-to-end one feeds a document identical to what WithAPIKeyCookie produces and asserts the generated client sends that cookie, with a negative assertion that X-API-Key is absent; both fail against the pre-branch code. The parity one drives a deliberately unnormalized endpoint through the Go and TypeScript generators and compares the two emitted tables against each other rather than against a literal, because a table pinned to Go's output would have passed before that fix as happily as after it.

Worth knowing during review

The generator has two IR builders, spec_parser.go for documents on disk and introspector.go for a live router. Every defect fixed here existed in both, and the second one was easy to miss. Both now keep cookie parameters, warn on an unknown parameter location, sort schemes deterministically, and populate declared authorization, so a client generated from an introspected router behaves the same as one generated from a file.

Warnings rather than silence is the theme. A scheme type the generator cannot emit, two scheme keys that derive to the same Go field, two capability strings that derive to the same constant, a parameter location it does not recognise, a cookie parameter it will not put on the wire: each of those used to vanish, and each now reports through the generated client's Warnings.

Known gaps

Both of the ones this section used to list are closed.

An apiKey scheme whose in value the generator does not recognise used to get an AuthConfig field regardless, while apply encodes only header, cookie and query. You could set that credential and it went nowhere. OpenAPI 3.1 allows exactly those three locations, but neither IR builder validates what the document said, so a typo, an OpenAPI 2.0 body, or a scheme with no in all arrive at the generator. They warn and claim no field now, like every other unhandled scheme in that file. A credential that vanishes is the defect this work exists to remove; one that looks configured and goes nowhere is worse, because nothing at the call site suggests you should check.

The six unrelated compile bugs are fixed too, in the section above.

Downstream

xraph/authsome#51 is the first consumer, and it is blocked on this shipping. It stamps a session's roles onto the auth context, declares on its admin routes the permission its middleware already enforces, and declares the session cookie its provider has always accepted and never described. None of it compiles until AuthContext.Roles is in a release, so that branch sits red until this one merges.

Worth reading alongside this PR if you want to see whether the declaration path actually holds up: it is the same journey from a real service's own auth model out to a generated client, and it turned up two things this side got wrong on the first pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
forge	Ready	Preview	Aug 17, 2026 6:38pm

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 15 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 17 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 18 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 45 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 45 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 45 follow conventional format

[github-actions]

Conventional Commits Validation

PR Title: valid
Commits: all 45 follow conventional format