Skip to content

docs(native-dart): getting-started guide and Auth sample updates - #1650

Merged
cadivus merged 65 commits into
mainfrom
docs/dart-guide-1.0.0
Nov 19, 2026
Merged

cadivus merged 65 commits into
mainfrom
docs/dart-guide-1.0.0

Conversation

@ekjotmultani

Copy link
Copy Markdown
Contributor

Problem

Following the Dart README as a new Flutter user did not work:

  • Step 2 set spec: lib/blocks.spec.json in build.yaml. The builder never reads that option: it reads only fail_on_collision and native_package_opt_out, applies itself to every package that depends on blocks_codegen, and turns every *.spec.json into a *.blocks.dart.
  • The README never said how to get blocks.spec.json from a backend.
  • Requirements said Dart 3.3+. The pubspecs need Dart 3.11, and blocks_runtime_flutter needs Flutter 3.41.
  • The "Using Auth" sample did not compile: it mixed top-level declarations with top-level await and try. Once wrapped, it crashed: a password user's signOut action reached the UnsupportedError case, and signUp required an email field that an email sign-in block does not ask for. It also always passed FlutterBrowserLauncher, which is wrong on macOS, Linux and Windows.
  • The sample opens the logout URL with url_launcher, which the README never said to add.
  • A Flutter macOS app runs in the App Sandbox and cannot reach the backend without the com.apple.security.network.client entitlement. No doc mentioned it, so every call failed with a connection error.

Issue #, if available:

Changes

README-only changes in native/dart/README.md and the three package READMEs.

  • Getting started (native/dart/README.md): create a backend with npm create @aws-blocks/blocks-app@latest my-backend -- --template api-only, run npm run dev, generate the spec with npm run spec, add the packages (now including blocks_runtime_flutter), copy the spec into lib/ and run build_runner. No build.yaml. Blocks() with no baseUrl calls the server the spec names. Notes for the macOS network.client entitlement and the Android emulator host. To use AWS: npm run sandbox:deploy, then BLOCKS_SPEC_STAGE=sandbox npm run spec; npm run sandbox:destroy to tear down. Requirements now say Dart 3.11+ and Flutter 3.41+.
  • blocks_codegen README: a table of the options the CLI and the builder actually read, and the build.yaml shape for them.
  • Using Auth (native/dart/README.md and blocks_runtime/README.md): the sample is now a ChangeNotifier that compiles against a generated client. It submits SignOutInput for a password sign-out, passes only the fields the action lists, passes FlutterBrowserLauncher on iOS and Android only so desktop signs in through the loopback listener, and returns quietly on OidcCancelledException. It says to add url_launcher, and that local federated sign-in needs a store: 'builtin' block with stubIdp().
  • blocks_runtime_flutter README: the macOS entitlements (network.client in both files, network.server in Release.entitlements), what to do when keychain-access-groups needs a development team, and an OIDC sample that takes the generated provider enum and catches OidcCancelledException.
  • Em dashes removed from the lines touched.

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, using path: overrides:

  • Local dev server: backend from the api-only template plus a store: 'builtin' block with stubIdp(). flutter test against it passes 6/6: a signed-out call to a gated KVStore method is a 401 ApiException that isBlocksError matches; 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, then oidc.signOut(); a relaunch after sign-out is signed out.
  • Deployed sandbox (npm run sandbox:deploy, then BLOCKS_SPEC_STAGE=sandbox npm run spec): the same 6/6, against the API Gateway URL with its stage segment. The sandbox was then destroyed.
  • macOS: 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.
  • Every Dart snippet changed here analyzes clean in that app (flutter analyze). Statement-only fragments were checked inside a small wrapper.

Not tested: iOS, Android, and a real identity provider.

Checklist

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

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
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
@ekjotmultani
ekjotmultani marked this pull request as ready for review November 19, 2026 14:49
@ekjotmultani
ekjotmultani requested a review from a team as a code owner November 19, 2026 14:49
@cadivus
cadivus merged commit fad006b into main Nov 19, 2026
20 of 22 checks passed
@cadivus
cadivus deleted the docs/dart-guide-1.0.0 branch November 19, 2026 17:45

This branch had an error being deployed

1 failed deployment
e2e — 7d31f48b Deployed Nov 19, 2026 by ekjotmultani via E2E Sandbox #7458
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants