Skip to content

docs(bb-auth, auth-common): quick start, options and error tables for Auth; three corrected statements - #1638

Open
xyos wants to merge 4 commits into
aws:mainfrom
xyos:docs/readme-auth
Open

xyos wants to merge 4 commits into
aws:mainfrom
xyos:docs/readme-auth

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • The bb-auth README had two wrong statements about sessions: "existing AuthCognito sessions are accepted" (they are not; every user signs in once), and MIGRATION.md gave the default session lifetime of Auth as 400 days (it is 30).
  • The bb-auth README had no table of the constructor options. Defaults were spread over 987 lines, and session.freshAgeSeconds was documented only inside the MFA recipe.
  • It did not say which HTTP status each error name carries or which names are retriable, and the auth-common README did not list the AuthErrors names.
  • It opened with ## 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.
  • 60 prose lines of the bb-auth README and 9 of the auth-common README were longer than 400 characters, several holding five or more rules each (the users command flags, the verified-email rules, the provider-secret steps).

Issue #, if available:

Changes

packages/bb-auth/README.md

  • Corrected: "existing AuthCognito sessions are accepted" is removed. Auth reads a new session store (packages/bb-auth/src/session-store-id.ts:11-17; MIGRATION.md:73 already said so).
  • Corrected: the ttlSeconds default reads "30 days", not "30 days (was 400 days)" (packages/bb-auth/src/sessions.ts:59). rememberDevice on AWS now names its error, InvalidParameterException (packages/bb-auth/src/engines/native-cognito.ts:239-246).
  • Added ## Quick start: the backend file and the frontend mount. The mount example moved here from ## Sign-in UI.
  • Added ### Options (40 rows) from AuthOptions in packages/bb-auth/src/types.ts; two rows in the session table (freshAgeSeconds, crossDomain).
  • Added ## Errors: statuses from statusForAuthError (packages/bb-auth/src/errors.ts:28-59), retriable names from isRetriableAuthError (errors.ts:70-81), 403 from auth-base.ts:561, 501 from engines/federation-unavailable.ts:77, and the import path of each matcher on the server and in the browser.
  • Added a local-versus-AWS table (8 rows) at the top of ## Local development. Seven rows restate text the README had; the local rememberDevice cell is from engines/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 the store section.
  • ## Usage and ## Which option and why moved above ## Recipes. ## What it does is replaced by ## Sign-out and password reset, ## Bearer tokens (allowBearerAuth) and ## Changes the block refuses. ## One sign-up and sign-in policy: validateUser is now ## validateUser.
  • Long paragraphs are lists with one fact per item; the feature-plan rates are a table.
  • Removed: mentions of the former blocks in reference text (## Migrating from … still points to MIGRATION.md) and the ## Design section (the introduction links to DESIGN.md).

Five test files of packages/bb-auth read this README (readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics). The README keeps what they read: ## Recipes and its recipe titles, ### The first admin and its position, exactly two snippets with two new Auth(, and the npx @aws-blocks/bb-auth users lines.

packages/auth-common/README.md

  • Corrected: Theming named three components that inject the stylesheet; all five do (packages/auth-common/src/ui.ts:939,1133,1847,2053,2225).
  • Added the AuthErrors table (44 rows: constant, error.name, meaning) from packages/auth-common/src/errors.ts:38-181.
  • ## Exports says that application code imports the UI from @aws-blocks/blocks/ui.
  • submitAuthAction: says both calls are fully typed and need no as any.
  • ## Types Reference moved above ## Custom auth UI: submitAuthAction; the /cookies section moved to the end as a function table plus a list.
  • Removed: how the Authenticator renders, 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.md

  • MIGRATION.md:427: "400 days in Auth" 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.
File Lines Words Prose lines over 400 characters
packages/bb-auth/README.md 987 → 1166 12899 → 12826 60 → 22
packages/auth-common/README.md 428 → 437 3334 → 3584 9 → 0
packages/bb-auth/CUSTOMIZING-AUTH-UI.md 424 → 428 2786 → 2813 0 → 0
packages/bb-auth/MIGRATION.md 560 → 560 7662 → 7662 one line changed

The 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:

  • The ### Options table, row by row against AuthOptions and against where each default is applied in packages/bb-auth/src.
  • The 44-row AuthErrors table in the auth-common README.
  • The corrected statement that existing AuthCognito sessions are not accepted, and the 30-day default in MIGRATION.md.
  • The two new Quick start snippets: they are complete files under one heading.

Not changed on purpose:

  • Headings that other files link to or quote keep their names: ## Which option and why, ### Where do your users live?, ## Usage, ## Planning to use Amplify client libraries?.
  • Examples keep their import specifiers (@aws-blocks/bb-auth, @aws-blocks/auth-common/ui in some, @aws-blocks/blocks in others).

Open questions:

  • Should every example import from the @aws-blocks/blocks paths?
  • ## Native apps, ## Frontend on a different origin and ## Planning to use Amplify client libraries? (about 145 lines) serve narrower readers. Should they move to their own files to shorten the README?
  • The four headings above do not name what they document. Renaming them needs the links in docs/DECISIONS.md, MIGRATION.md and packages/blocks/README.md, a quoted title in the create-blocks-app template and two source messages to change together.
  • ## Types Reference in the auth-common README omits AuthUser.displayName, AuthAction.capability and AuthAction.unavailable.
  • JSDoc still gives the former 400-day value: 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: setAuthState and submitAuthAction are fully typed, so a custom form needs no as any (one paragraph in the auth-common README, one in CUSTOMIZING-AUTH-UI.md). Open pull requests that touch the same files:

Whichever 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, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in 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 main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and 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

  • 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.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5a00223

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@aws-blocks/bb-auth Patch
@aws-blocks/auth-common Patch
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch

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

xyos added 4 commits November 19, 2026 05:47
…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`.

This branch has not been deployed

No deployments
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.

1 participant