Repository navigation
Conversation
🦋 Changeset detectedLatest commit: 5a00223 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-auth
branch
from
November 18, 2026 21:38
5a00223 to
e8c1a60
Compare
xyos
marked this pull request as ready for review
November 18, 2026 22:00
xyos
enabled auto-merge (squash)
November 18, 2026 22:00
…sions are not accepted The README said existing `AuthCognito` sessions are accepted. They are not: `Auth` reads a new session store and every user signs in once (`packages/bb-auth/src/session-store-id.ts`), so the statement is removed. The `session` table gave the `ttlSeconds` default as "30 days (was 400 days)"; it now reads "30 days" and gains rows for `freshAgeSeconds` and `crossDomain`. The README now opens with `## Quick start` (the backend file and the frontend mount), followed by `## Usage` with an `### Options` table of every top-level option and the nested options that had no table, taken from `AuthOptions` in `packages/bb-auth/src/types.ts`. A new `## Errors` section gives the default HTTP status of each error name, the three statuses that differ, the retriable names and where each matcher is imported from; `## Local development` starts with a table of local versus AWS behaviour; `## Mode gates` has a table of the server-side errors of a gated call. `## What it does` is replaced by `## Sign-out and password reset`, `## Bearer tokens (allowBearerAuth)` and `## Changes the block refuses`, and long paragraphs are lists with one fact per item. `## Recipes`, `### The first admin`, the two-block snippets and the `users` command lines that tests in `packages/bb-auth` read are kept.
…h an app uses The Theming section named three components that inject the stylesheet; all five do (`packages/auth-common/src/ui.ts`), so it now says "each component". `## Auth error names (AuthErrors)` lists all 44 names with their constant and meaning, from `packages/auth-common/src/errors.ts`. `## Exports` says that application code imports the UI from `@aws-blocks/blocks/ui`, before the examples. `## Custom auth UI: submitAuthAction` says that `setAuthState` and `submitAuthAction` are fully typed, so a custom form needs no `as any`; `## Types Reference` moves above it. `## Session-cookie security policy (/cookies)` moves to the end as a function table plus a list, and descriptions of how the components and the auth-state store work underneath are removed.
…ll needs no cast
`MIGRATION.md` said the default session lifetime is 400 days in `Auth`. It is 30 days (`DEFAULT_SESSION_TTL_SECONDS` in `packages/bb-auth/src/sessions.ts`), and the line now says so.
`CUSTOMIZING-AUTH-UI.md` gains one paragraph under the `AuthActionInput` contract: `submitAuthAction(authApi, { action: 'signOut' })` type-checks as written, so a hand-written call needs no `as any`.
xyos
force-pushed
the
docs/readme-auth
branch
from
November 19, 2026 06:11
e8c1a60 to
06d2136
Compare
This branch has not been 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
AuthCognitosessions are accepted" (they are not; every user signs in once), andMIGRATION.mdgave the default session lifetime ofAuthas 400 days (it is 30).session.freshAgeSecondswas documented only inside the MFA recipe.AuthErrorsnames.## Recipes; the constructor forms (## Usage) started at line 517, and the example that mounts the login UI was near the end of## Sign-in UI.userscommand flags, the verified-email rules, the provider-secret steps).Issue #, if available:
Changes
packages/bb-auth/README.mdAuthCognitosessions are accepted" is removed.Authreads a new session store (packages/bb-auth/src/session-store-id.ts:11-17;MIGRATION.md:73already said so).ttlSecondsdefault reads "30 days", not "30 days (was 400 days)" (packages/bb-auth/src/sessions.ts:59).rememberDeviceon AWS now names its error,InvalidParameterException(packages/bb-auth/src/engines/native-cognito.ts:239-246).## Quick start: the backend file and the frontend mount. The mount example moved here from## Sign-in UI.### Options(40 rows) fromAuthOptionsinpackages/bb-auth/src/types.ts; two rows in thesessiontable (freshAgeSeconds,crossDomain).## Errors: statuses fromstatusForAuthError(packages/bb-auth/src/errors.ts:28-59), retriable names fromisRetriableAuthError(errors.ts:70-81), 403 fromauth-base.ts:561, 501 fromengines/federation-unavailable.ts:77, and the import path of each matcher on the server and in the browser.## Local development. Seven rows restate text the README had; the localrememberDevicecell is fromengines/native-mock.ts:1110-1121.## Mode gates: the server-side errors of a gated call are a table, with two new rows (auth-base.ts:1809-1815,1822-1829); "What is checked when" moved here from thestoresection.## Usageand## Which option and whymoved above## Recipes.## What it doesis replaced by## Sign-out and password reset,## Bearer tokens (allowBearerAuth)and## Changes the block refuses.## One sign-up and sign-in policy: validateUseris now## validateUser.## Migrating from …still points toMIGRATION.md) and the## Designsection (the introduction links toDESIGN.md).Five test files of
packages/bb-authread this README (readme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnostics). The README keeps what they read:## Recipesand its recipe titles,### The first adminand its position, exactly two snippets with twonew Auth(, and thenpx @aws-blocks/bb-auth userslines.packages/auth-common/README.mdpackages/auth-common/src/ui.ts:939,1133,1847,2053,2225).AuthErrorstable (44 rows: constant,error.name, meaning) frompackages/auth-common/src/errors.ts:38-181.## Exportssays that application code imports the UI from@aws-blocks/blocks/ui.submitAuthAction: says both calls are fully typed and need noas any.## Types Referencemoved above## Custom auth UI: submitAuthAction; the/cookiessection moved to the end as a function table plus a list.Authenticatorrenders, the refetch and ordering mechanics of the store,BroadcastChannel, the plain-HTTP configuration entry, and examples that repeated another one.packages/bb-auth/MIGRATION.md,packages/bb-auth/CUSTOMIZING-AUTH-UI.mdMIGRATION.md:427: "400 days inAuth" is now "30 days" (packages/bb-auth/src/sessions.ts:59).CUSTOMIZING-AUTH-UI.md: one paragraph: a call with a literal action name needs no cast.packages/bb-auth/README.mdpackages/auth-common/README.mdpackages/bb-auth/CUSTOMIZING-AUTH-UI.mdpackages/bb-auth/MIGRATION.mdThe bb-auth README is 179 lines longer and about the same in words. It gains the options table, the error tables and the local-versus-AWS table, and its long paragraphs became lists. For that, a reader finds every option's default and every error's status in one place instead of reading the prose for them.
Look hardest at:
### Optionstable, row by row againstAuthOptionsand against where each default is applied inpackages/bb-auth/src.AuthErrorstable in the auth-common README.AuthCognitosessions are not accepted, and the 30-day default inMIGRATION.md.Not changed on purpose:
## Which option and why,### Where do your users live?,## Usage,## Planning to use Amplify client libraries?.@aws-blocks/bb-auth,@aws-blocks/auth-common/uiin some,@aws-blocks/blocksin others).Open questions:
@aws-blocks/blockspaths?## Native apps,## Frontend on a different originand## Planning to use Amplify client libraries?(about 145 lines) serve narrower readers. Should they move to their own files to shorten the README?docs/DECISIONS.md,MIGRATION.mdandpackages/blocks/README.md, a quoted title in thecreate-blocks-apptemplate and two source messages to change together.## Types Referencein the auth-common README omitsAuthUser.displayName,AuthAction.capabilityandAuthAction.unavailable.packages/bb-auth/src/types.ts:1450,packages/bb-auth/src/sessions.ts:58.Related pull requests: This carries what still applies from the closed #794 for auth:
setAuthStateandsubmitAuthActionare fully typed, so a custom form needs noas any(one paragraph in the auth-common README, one inCUSTOMIZING-AUTH-UI.md). Open pull requests that touch the same files:packages/bb-auth/README.mdpackages/bb-auth/README.mdpackages/auth-common/README.mdWhichever merges second rebases.
Part of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.
Validation
Run on this branch alone at
06d213601, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.