feat(client): choose the callback binding in Config, not on the session store

[osanderson]

Summary

These are the fixes from the security and DevX review of v0.45.0..fa120ab, before v0.46.0. There are three commits, for release-please.

feat(client): the callback binding moves to client.Config (both reviews' main point).

#532 let a session store declare storage.Capabilities.SingleUserAgent, which let a callback complete with no SessionHandle. But "only one user agent writes this store" is a fact about where a store is deployed, not about its type:

• A SQLite store written for a mobile app and reused in a server-side web app (or wrapped by embedding) would carry the declaration with it, and silently bring login CSRF back (RFC 9700 §4.7).
• It was also the only capability that relaxed a check rather than adding a production requirement.

It hasn't been released, so it moves now:

• client.Config.CallbackBinding:

  • CallbackBindingSessionHandle is the zero value, unchanged behaviour: AuthorizationCallback.Session is required and compared.
  • CallbackBindingDeviceLocalStore is for a native app whose session store is its own on-device storage. The session is the callback's own state, read from the verified signed response under Message Signing.

  It's an enum (per the bool→enum rule, feat!: require explicit AuthorizationResponseIssPolicy #358), chosen per deployment by whoever wires the client. New refuses an unknown value. Its doc says never to use it with a store a server shares between users, to keep SessionLifetime short (any pending session in the store can complete), and that saving Handle().String() on the device works too.

• storage.Capabilities.SingleUserAgent is removed.

• The missing-Session error said "required unless … declares SingleUserAgent", which told a web developer who forgot the cookie how to switch off their CSRF protection. It now points at the SessionHandle and client/sessioncookie.

fix(client): bounded error text.

• A malformed error code (not RFC 6749 error text) is cut to 64 bytes before being quoted into Error(), so only bounded server text reaches it.
• The client.Error type doc no longer calls PublicDescription safe to show a user, since it can be the server's own error_description.

docs:

• A "Native apps" section in client's package doc ties together the native story from v0.44–v0.46:

  • registration as native, and RedirectPort;
  • platform-keystore keys via keys.NewKeyManagerFromSigners + DeclareCustody(Durable);
  • the on-device session store and its locking;
  • completing after relaunch;
  • TokenSetSealer;
  • mapping errors to Code()/ServerResponse() before gomobile turns them into an NSError.

  GETTING_STARTED links to it.

• Stale statements fixed:

  • client/doc.go and ARCHITECTURE no longer say the SessionHandle is always required.
  • Dependencies.Sessions states its production requirements.
  • KeyCustody.Durable says a native key is kept until the tokens bound to it are discarded, not until "the flow ends", which could be read as deleting the DPoP key at code exchange.

Tests

• TestCallbackWithoutSessionForADeviceLocalStore: completion with no Session works under CallbackBindingDeviceLocalStore, both plain and JARM.
• TestCallbackWithoutSessionStillRefused:
  • the default binding requires Session;
  • a state this app never began is refused;
  • a mismatching Session is refused.
• TestNewRefusesAnUnknownCallbackBinding.
• TestMissingSessionErrorPointsAtTheHandle: the error names sessioncookie and doesn't mention the device-local binding.
• TestPARErrorBoundsAMalformedCode: a 500-byte malformed code shows only its first 64 bytes.
• Mutation checks: each of these fails a test:
  • ignoring the binding;
  • deriving the session by default;
  • overriding a given handle;
  • accepting an unknown binding;
  • dropping the truncation.
• Other checks:
  • go test -race across client, storage, keys, fapitest and server passes.
  • go test ./cmd/... passes.
  • Every demo's tests pass.
  • golangci-lint is clean.
  • The package doc renders the new heading.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud