Repository navigation
docs(native-dart): getting-started guide and Auth sample updates - #1650
Merged
Merged
Conversation
A namespace whose export name already ends in Api keeps it as the class name instead of gaining a second one, as the Kotlin and Swift clients name it: oidcAuthApi generates OidcAuthApi and OidcAuthApiGetClientProvider, and api generates Api. Two exports that would now share a class, such as oidcAuth and oidcAuthApi, are a generation error naming both. Regenerates the Dart fixture goldens and updates the tests and the e2e OIDC test that name generated classes.
A transferable is read-only and has no toJson(), so a generated method taking one compiled and then always threw on the call. The codegen now fails with an error naming the method and parameter for a direct, optional, nullable, list, map or tuple parameter, and for a model parameter holding a transferable at any depth, as the Kotlin codegen does. Fixture 35's Dart golden becomes codegen-error.txt, which the golden test and the fixture analyze script expect.
…gment OidcClient resolved its auth routes against the base URL with one trailing /aws-blocks/api stripped. A base URL that repeated the RPC prefix kept the second copy, so every auth request went under the RPC path. It now keeps the scheme, host, port and the path segments before the first segment that is exactly aws-blocks, which keeps an API Gateway stage. A URL with no such segment is used with its trailing slash stripped, as before.
restore() read only stored tokens. A cookie session stores none, so it reported signed out while the cookie was still valid, and with tokens it built the user id from the JWT sub instead of the server's userId. restore() now GETs the block's session route with the cookie, and the stored access token as a bearer token when there is one, and returns the user. 200 signs in with the server's user, 401 clears the tokens and signs out, and any other status throws the new OidcRequestException without changing the state. A 404 says the block has no sign-in providers.
signOut() ignored the sign-out response. It dropped the identity provider's logout URL, so the provider's session survived, and it reported signed out whatever the backend answered. signOut() now POSTs with ?format=json and returns the logoutUrl, or null. A 2xx signs out locally. A 503 SignOutIncompleteException signs out locally and then throws OidcRequestException with that name. Any other status, or a transport error, throws after clearing the stored tokens and keeps the session cookie and the state.
The exchange and session routes send userSub, groups, attributes and signInProvider with the user. OidcUser kept only userId, username and groups. It now reads userSub, signInProvider and attributes too, each null when the server leaves it out.
signOut() cleared the whole session store after a 2xx or a 503 SignOutIncompleteException. The store is shared with the app's BlocksClient, so signing out of one Auth block also dropped the session cookie of every other block on the app. signOut() no longer clears the store. The Set-Cookie the server sends on the sign-out response removes this block's cookie.
Every OidcClient stored its tokens and sign-in state under the same keys (access_token, refresh_token, expires_at, provider and the oidc_* PKCE keys). Two clients sharing a token store, one per Auth block, overwrote each other's tokens. A client built with fromJson, which is how a block's getClient() hydrates it, now prefixes every key with the directory of the descriptor's exchangePath. Clients built with the constructor keep the unprefixed keys.
…thProvider BlocksClient dropped the session cookie whenever an authProvider was set. An app that set an OidcClient signed in with the cookie as its authProvider sent neither a cookie nor a bearer token on RPC calls. It now always sends the cookie when there is one, and adds the bearer token only when the provider has one. The server prefers the cookie when both are sent.
…rrorName The field that carries the error name an auth route sends was called name. The Kotlin and Swift runtimes call it errorName. The class is unreleased, so it is renamed to match.
…block sessions restore() threw a raw FormatException or TypeError on a 200 whose body was not JSON or had an unreadable user. It now throws an OidcRequestException and leaves the state as is. A client built with the constructor or fromJson took its session route from callbackPath, so a custom block's client read the Auth block's /aws-blocks/auth/session. The default is now the directory of exchangePath, which is the same route for an Auth block. The constructor no longer throws when that path has no '/', and the 404 message names a custom block that serves no session route as a cause. restore() also leaves out an expired access token.
signInRelay reported a relayed error= before it checked the state and the CSRF value inside its envelope. Any page that could open the app's scheme could make a sign-in fail with an IdP error of its choosing. The state checks now run first and fail closed.
The signOut and restore entries had lines left over from earlier edits. The two-block sign-out test uses cookie names shaped like the ones an Auth block sets.
signOut() sent the stored refresh token in its body. The Auth block's
sign-out route ignores the body, so the client now sends {} and leaves
the token out.
…ssage The error appended the decode exception, which quotes part of the state. It now says only that the envelope can't be decoded.
…s stored signIn compared the callback's state with the stored one, which passes when both are missing, and then threw a TypeError on a null assertion. It now throws the state error.
The README asked for blocks_runtime and blocks_codegen ^1.0.0, which doesn't exist; the next release is 0.2.0. It also said the compiler makes an app handle every auth state, which isn't true of the state machine's state and actions.
OidcClient exposed its sign-in state only as the authStateChanges stream, so an app had to subscribe to read it once. authState returns the state most recently added to the stream, or OidcLoading before the first one, matching Kotlin's authState.value. Every emission now goes through one helper that records the state before adding it to the stream. authStateChanges now gives each new listener that current state first, then each change, as Kotlin's authState flow does, so a listener added after restore() or a sign-in sees the state at once.
OidcClient.fromJson cast every descriptor field it read, so a getClient() result without providers, providerConfigs, signOutPath or a provider's kind threw a TypeError. It ignored a sessionPath the descriptor sent, and took a missing callbackPath or authorizeParamsBasePath from the default block's routes. It now reads sessionPath and refreshPath when they are sent, derives them, signOutPath, callbackPath and authorizeParamsBasePath from the directory of exchangePath otherwise, and treats the missing lists and kind as empty. A missing or non-string exchangePath, which every route is found from, throws a FormatException naming the field, raised by one descriptor-field helper next to validateTransferableDescriptor.
Version 0.2.0 stored an OidcClient's tokens under unprefixed keys, which a client from fromJson no longer reads, so an upgrade would sign a bearer session out. The first time such a client reads or writes its tokens, it moves the unprefixed access token, refresh token, expiry and provider to its own keys. Version 0.2.0 only signed in against the default Auth block, so only the client whose exchangePath is /aws-blocks/auth/exchange takes them, and only when it has no tokens of its own, whatever other blocks share the store and in whatever order they are used. It never takes another block's tokens or overwrites its own.
… ones first The blocks_runtime, blocks_codegen and blocks_runtime_flutter changelogs group the Unreleased entries under Breaking and Other changes, so the breaking changes come first.
…sign-out A restore() still in flight when a sign-in or sign-out finished applied its response anyway: a 401 signed out, and cleared the tokens of, the sign-in that had just finished, and a 200 signed back in after a sign-out. exchange and signOut now count each change to the session, and restore applies its response only when the count is unchanged; otherwise it returns the current user. The OidcClient docs say to hold one client per block.
A sign-out that failed with a transport error, a cancelled request, or a status other than 2xx and the 503 SignOutIncompleteException cleared the stored tokens but kept the session cookie and the signed-in state. It now does what the 503 path does: it clears this block's tokens, removes this block's session cookie, emits OidcSignedOut, then throws. The block's session cookie is the descriptor's sessionCookieName, which fromJson now reads into OidcClient.sessionCookieName. With an older backend that doesn't send it, the exchange records the names of the cookies it set, and signOut removes those. Other Auth blocks' cookies are left alone either way. The counter that keeps a late restore or refresh from undoing a sign-out now moves on every sign-out outcome.
OidcClient.signIn is now the relay sign-in that was signInRelay, the flow the client a block's getClient() returns is for, as in Kotlin and Swift. The direct custom-scheme flow that was signIn is now signInDirect. TypedOidcClient renames both the same way. Callers, tests, the OIDC e2e, the READMEs and the docs use the new names.
refresh() took its generation snapshot only after reading the refresh token, so a sign-out that finished during that read went unnoticed: the refresh posted the old token and stored a live access token on a signed-out client. It now takes the snapshot before its first await and checks it again after the read. The completer that dedupes concurrent refreshes always completed normally, so callers that joined a refresh that failed went on with the expired token. It now completes with the refresh's error.
The Dart SDK signs in with the session cookie and sends no bearer tokens on its calls. A backend with bearer tokens enabled still minted them on every exchange. The exchange body now carries tokens: false, which the backend honours by returning only the user. Decision: D2
…fresh Refresh read expiresAt, which the auth block never sends; it sends expiresIn seconds. Every refreshed token looked expired, so each getAccessToken() refreshed again. Refresh also sent no provider, which a backend with several providers rejects. The exchange now stores the provider with the tokens, refresh sends it, and both store the expiry from expiresIn with expiresAt as a fallback. The rotated refresh token is stored when the response has one. The unit tests mocked expiresAt and now use the auth block's response shape. Refresh and onAuthFailure signed out on any failure. They now sign out only on a 400 or 401 from the refresh route, and throw otherwise, keeping the tokens. A refresh that a sign-in or sign-out overtakes ignores its response, so it never stores tokens after a sign-out. Decision: D2b
…client The Dart and blocks_runtime READMEs gain a "Using Auth" section. The app renders one federated sign-in button per provider in the providers of the client createOidcApi().getClient() returns, calling signIn, and takes everything else from the state machine createApi() exposes: whether the user is signed in, password sign-in, sign-up, confirmation and MFA steps, and unavailable actions. It doesn't render the state machine's signIn:<id> actions as buttons. The blocks_runtime_flutter README snippet now uses parameters that exist. Decision: D1
The OIDC e2e uses the client oidcAuthApi.getClient() returns as is, without rebuilding it at the API origin, and signs out with oidc.signOut() instead of an RPC. It runs the flow an app does: getAuthState says signed out, the client's providers give a google sign-in button, signIn with google, then getAuthState says signed in. The backend may serve other providers too. It also checks that a fresh client on a reloaded cookie store restores the session, that signOut returns a logout URL, and that restore is null and the state signedOut afterwards. Decision: D1
# Conflicts: # native/dart/packages/blocks_codegen/CHANGELOG.md # native/dart/packages/blocks_codegen/lib/src/builder.dart # native/dart/packages/blocks_runtime/CHANGELOG.md # native/dart/packages/blocks_runtime/lib/blocks_runtime.dart # native/dart/packages/blocks_runtime/lib/src/blocks_client.dart # native/dart/packages/blocks_runtime/lib/src/oidc_client.dart # native/dart/packages/blocks_runtime_flutter/CHANGELOG.md
…nnot be printed A failed session write logs a warning to standard error. When standard error is a closed pipe, that write threw out of the write chain, so every later write was skipped and flush() threw. The warning is now best effort, and the write chain drops any error so it keeps running.
… default store The class docs told Flutter apps to build a store over FlutterSecureStore and call load(). The plugin now registers that store as the default before main, load() is no longer needed, and a second store over the same storage is the duplicate the docs warn about.
…re entry FileTokenStore strips leading dots from an application id or key before it compares the reduced name with the original, so .acme.cli and acme.cli shared one directory and .foo and foo one file. The comparison now uses the name before the dots are stripped, so stripping them appends the digest. A name without leading dots or unsafe characters maps to the same name as before.
…d write set() removed its temporary file only on a FileSystemException. A ProcessException from chmod, or any other error, left a randomly named .tmp file behind, so they could pile up. It now removes the file on any error and rethrows it.
# Conflicts: # native/dart/packages/blocks_runtime_flutter/README.md
…de-1.0.0 # Conflicts: # native/dart/README.md # native/dart/packages/blocks_runtime/README.md # native/dart/packages/blocks_runtime_flutter/README.md
ekjotmultani
changed the base branch from
main
to
feat/dart-persistent-session-default
November 19, 2026 13:00
Base automatically changed from
feat/dart-persistent-session-default
to
main
November 19, 2026 13:48
VarshithaPamisetty
approved these changes
Nov 19, 2026
This branch had an error being deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Following the Dart README as a new Flutter user did not work:
spec: lib/blocks.spec.jsoninbuild.yaml. The builder never reads that option: it reads onlyfail_on_collisionandnative_package_opt_out, applies itself to every package that depends onblocks_codegen, and turns every*.spec.jsoninto a*.blocks.dart.blocks.spec.jsonfrom a backend.blocks_runtime_flutterneeds Flutter 3.41.awaitandtry. Once wrapped, it crashed: a password user'ssignOutaction reached theUnsupportedErrorcase, andsignUprequired anemailfield that an email sign-in block does not ask for. It also always passedFlutterBrowserLauncher, which is wrong on macOS, Linux and Windows.url_launcher, which the README never said to add.com.apple.security.network.cliententitlement. No doc mentioned it, so every call failed with a connection error.Issue #, if available:
Changes
README-only changes in
native/dart/README.mdand the three package READMEs.native/dart/README.md): create a backend withnpm create @aws-blocks/blocks-app@latest my-backend -- --template api-only, runnpm run dev, generate the spec withnpm run spec, add the packages (now includingblocks_runtime_flutter), copy the spec intolib/and runbuild_runner. Nobuild.yaml.Blocks()with nobaseUrlcalls the server the spec names. Notes for the macOSnetwork.cliententitlement and the Android emulator host. To use AWS:npm run sandbox:deploy, thenBLOCKS_SPEC_STAGE=sandbox npm run spec;npm run sandbox:destroyto tear down. Requirements now say Dart 3.11+ and Flutter 3.41+.build.yamlshape for them.native/dart/README.mdandblocks_runtime/README.md): the sample is now aChangeNotifierthat compiles against a generated client. It submitsSignOutInputfor a password sign-out, passes only the fields the action lists, passesFlutterBrowserLauncheron iOS and Android only so desktop signs in through the loopback listener, and returns quietly onOidcCancelledException. It says to addurl_launcher, and that local federated sign-in needs astore: 'builtin'block withstubIdp().network.clientin both files,network.serverinRelease.entitlements), what to do whenkeychain-access-groupsneeds a development team, and an OIDC sample that takes the generated provider enum and catchesOidcCancelledException.This PR depends on #1571, #1574, #1575, #1578 and #1599, and stays a draft until they merge. It describes the 1.0.0 API those PRs add (the error taxonomy, the default session store, sign-in cancellation, the shared
AuthActionInput). Where a section here comes from one of those PRs, this PR keeps the 1.0.0 wording, so it will be rebased once they are in.Pins stay
^0.2.0. The release PR bumps them. No changeset or CHANGELOG entry: docs only.Validation
Followed word for word, end to end, as a new Flutter app (
flutter create, Flutter 3.47.1), with the packages from main plus the PRs above, usingpath:overrides:api-onlytemplate plus astore: 'builtin'block withstubIdp().flutter testagainst it passes 6/6: a signed-out call to a gatedKVStoremethod is a 401ApiExceptionthatisBlocksErrormatches; sign-up, confirm, and the gated call; a relaunch restores the session; sign-out, a wrong password, sign-in; OIDC sign-in through the stub IdP over the loopback listener, thenoidc.signOut(); a relaunch after sign-out is signed out.npm run sandbox:deploy, thenBLOCKS_SPEC_STAGE=sandbox npm run spec): the same 6/6, against the API Gateway URL with its stage segment. The sandbox was then destroyed.flutter build macos, then three real launches of the app: sign in; still signed in after a restart, a gated write and read, sign out; still signed out after a restart. Done against both the local server and the sandbox.flutter analyze). Statement-only fragments were checked inside a small wrapper.Not tested: iOS, Android, and a real identity provider.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.