[brionmario]

Purpose

Two changes to backend mode (endpoints.backend, sign-in on a backend the app owns, RFC 10017 §6.1), ported alongside the JavaScript SDKs.

1. baseUrl is the backend, and the API is reached only through its proxy. Until now the backend's address was endpoints.backend.baseUrl, and the top-level baseUrl meant the API whose requests go through the proxy. In backend mode the app never talks to the ThunderID server or to the API: it talks to the backend, which holds the tokens and decides where API requests go. So the top-level baseUrl is now the backend, and the app's API base is the backend's proxy. The client no longer needs, or is told, the API's real address.

2. Permissions come from the session. In backend mode the access token stays on the backend, but getGrantedPermissions() read the permissions by decoding the access token, which getAccessToken() asks the backend's token endpoint for. A BFF doesn't offer one, since keeping tokens away from the client is the point of the pattern. The app saw no permissions, and GrantedPermissionsNotifier hid everything. A client learns what it was granted from the token response's scope (RFC 6749 §5.1), so the backend reports it with the session and the app reads it from there.

Approach

• Resolution (resolve_backend_endpoints.dart): the top-level baseUrl must use HTTPS. Each endpoint is a path that resolves against baseUrl, or an absolute HTTPS URL that's used as it is; anything else is refused before any network call. BackendEndpoints.baseUrl is removed.
• API requests (BackendClient.toProxyUrl), all going through the proxy with the session handle, the backend attaching the access token:
  • a path starting with / goes to baseUrl + proxy + the path;
  • a URL already under the proxy, or a path already starting with the proxy's path, is sent as it is, not prefixed again;
  • any other absolute URL is refused unless it's under a bypass URL.
• Management: collection URLs are built on the proxy (baseUrl + proxy + the collection), and requests go through the backend's HTTP client with the session handle and no access token: none is requested from the backend. Collection overrides in endpoints still win. The client's config is now kept in backend mode, so management no longer throws there.
• Session model: BackendSession gains an optional scope, parsed in fromMap, so every session read keeps it.
• Permissions: in backend mode getGrantedPermissions() reads only the session's scope and never calls getAccessToken(). Redirect mode still reads the access token's scope or scopes claim.
• Playground: THUNDERID_BACKEND_URL becomes the SDK's baseUrl; the backend's proxy fronts the ThunderID server.
• README: a "Sign-in through a backend" section with the rules above.

Related Issues

• N/A

Related PRs

• Read granted permissions from the backend session in backend mode javascript-sdks#148: permissions from the session, in the JavaScript SDKs.
• BFF: Treat baseUrl config as the BFF's base URL javascript-sdks#149: baseUrl is the backend, in the JavaScript SDKs.
• BFF: send API calls through the backend's proxy, and drop apiBaseUrl javascript-sdks#150: the JavaScript follow-up that builds API URLs on the proxy instead of an API base.
• BFF: baseUrl is the backend, and permissions come from the session ios-sdks#41, BFF: baseUrl is the backend, and permissions come from the session android-sdks#49: the iOS and Android ports.
• Sign in through the app's backend in the Flutter SDK #52: backend mode.

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified.
• Documentation provided. (Add links if there are any)
  • README, "Sign-in through a backend".
• Tests provided. (Add links if there are any)
  • Unit Tests (test/resolve_backend_endpoints_test.dart: the backend in baseUrl, HTTPS for it, an absolute HTTPS endpoint, refused endpoints. test/backend_mode_test.dart: a relative path through the proxy, a URL already under the proxy not prefixed again, URLs outside the proxy refused, management URLs on the proxy and sent without an access token, and the "granted permissions" group.)
  • Integration Tests
• Breaking changes. (Fill if applicable)
  • Breaking changes section filled.
  • breaking change label added.
• Cross-SDK parity. Exactly one of parity/prs-raised or parity/prs-not-needed added.
  • If parity/prs-raised, the port links are posted as a reply on the parity check's comment.

Not run locally: Flutter isn't installed on the machine this was written on, so flutter analyze and flutter test, including the new tests, haven't run. CI is the first run of both.

Security checks

• Followed secure coding standards.
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

Every backend URL, including an absolute endpoint, must use HTTPS. In backend mode the client never asks for an access token: management requests and API calls go through the backend's proxy with the session handle, and permissions come from the session. The permissions decide only what the app shows; the server still checks every request.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: thunder-id/flutter-sdks
• Branch: main
• File: .coderabbit.yaml
• Commit: 5905760
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: a8d660a4-5222-4d96-a4a5-8c93c1e2018e

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔀 Cross-SDK feature parity, ports raised

This pull request is labelled parity/prs-raised, so the capability it introduces is expected in the other ThunderID SDKs as well.

Ports (DO NOT EDIT)

• thunder-id/javascript-sdks, JavaScript (React, Vue, Nuxt, Next.js, Express, React Router, TanStack Router, Browser, Node) => #148, #149, #150
• thunder-id/ios-sdks, iOS => #41
• thunder-id/android-sdks, Android => #49

3 of 3 sibling SDKs accounted for.

Every sibling SDK is accounted for.

The contract is in the SDK development specification.

[brionmario]

• thunder-id/ios-sdks: BFF: baseUrl is the backend, and permissions come from the session ios-sdks#41
• thunder-id/android-sdks: BFF: baseUrl is the backend, and permissions come from the session android-sdks#49