IS-11327 LWA: WebAuthn ceremony errors as HAAPI step AppErrors by aleixsuau · Pull Request #194 · curityio/ui-kit

aleixsuau · 2026-05-20T12:47:12Z

Jira: https://curity.atlassian.net/browse/IS-11327

Summary

Follow-up to IS-11252. Catches WebAuthn ceremony exceptions (cancel / timeout / parse error / unsupported API / null credential), classifies them via a two-bucket discriminator (cancelOrTimeout / failed), and surfaces them as client-synthesised AppError-class problems through useHaapiStepper().error.app. Copy comes from step.metadata.messages.error.clientOperation.webauthn.{cancelOrTimeout | registration | authentication}. Since the BE is not providing the error copies yet, it currently shows the default error message ('An error occurred').

Test plan

Setup:

Wrap HaapiStepperStepUI with HaapiStepperErrorNotifier in `App.tsx
Visit https://localhost:8443/dev/authn/authenticate?serviceProviderId=oauth-dev&resumePath=%2Fdev%2Foauth%2Fauthorize&state=R_BSe01wRAxWsdItkHVc5BkdkVwIaDGRmF&client_id=client-one
Select the webauthn authenticator
johndoe/johnsPassword1

Test cases:

Trigger a WebAuthn registration and click the cancel button → assert error message renders via the consumer's error.app subscription.
Trigger a WebAuthn registration generic failure (by applying webauthnerrors.patch) → assert the registration-failed copy
Same for authentication (cancel + generic failure)
Confirm the WebAuthn step renderer stays mounted after each failure and the button is clickable for retry

Catch every WebAuthn ceremony failure in the runners and surface it as a synthesised HaapiUnexpectedProblemStep via the existing error.app pipeline (rather than escalating to the React error boundary as a programming bug). Two-bucket discriminator (cancelOrTimeout / failed) matching Velocity parity. Copy comes from step.metadata.messages.error.clientOperation.webauthn with empty-string fallback while the BE keys land. * Runner-level synthesis: runWebAuthn{Registration,Authentication} catch the full error catalog (parse DOMException, create/get DOMException, TypeError, null credential, unsupported API) and throw a synthesised HaapiStepperError built via formatErrorStepData(HaapiUnexpectedProblemStep). * Dispatcher wrapping: performClientOperation wraps each WebAuthn runner in a .then/.catch chain returning ClientOperationResult discriminated union. The catch discriminates HaapiStepperError vs raw rejections via a type guard; raw errors propagate to the React boundary as programming bugs. * Type hierarchy: HaapiWebAuthnRegistrationClientOperationAction is now a proper discriminated union (passkeys | any-device) so consumers narrow via positive + negative type guards without casts. HaapiWebAuthnAnyDeviceArgs is also a discriminated union (platform-required | crossPlatform-required) expressing the "at least one of two" HAAPI spec invariant. * Metadata surface: HaapiMetadata.messages.error.clientOperation.webauthn carries the per-ceremony copy (cancelOrTimeout shared, registration, authentication). * Auto-start parity: manageWebAuthnAutoStart stays fire-and-forget via nextStep(); ceremony failures surface the same way as manual click (matching Velocity's .catch(handleError) pattern). * Tests: 23 runner-level tests in webauthn.spec.ts cover the full catalog per ceremony; HaapiStepper.spec.tsx wiring tests consolidated under one WebAuthn suite (Auto-Start gating + Registration/Authentication success+error routing), dropping the duplicate auto-start error-surfacing cases since manual click + auto-start share the dispatcher plumbing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…apiStepperError * Rename `HaapiMetadata.messages` → `HaapiMetadata.viewData` (and the dependent type aliases) so the metadata branch reads as view-customisation data emitted by the server rather than HAAPI step messages. Path becomes `step.metadata.viewData.error.clientOperation.webauthn.<key>`. * Extract `getHaapiStepperError` from `webauthn.ts` to `client-operations.ts` as a shared helper that takes a resolved message string and synthesises a `HaapiStepperError` from a `HaapiUnexpectedProblemStep`. WebAuthn-specific message resolution stays in `webauthn.ts` (`getWebAuthnErrorMessage`); other client operations (BankID, EBF) can reuse the helper when their per-runtime error handling lands. * Test fixtures + path-access assertions in `webauthn.spec.ts` updated to use the new `viewData` key. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ClientOperationResult is no longer WebAuthn-specific — the EBF and BankID runners will need it next. Extract it into a new sibling typings.ts file alongside the operation runners; keep the WebAuthn-specific enums where they are. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…nputs.

Flip the runtime semantics from `!!field.required` to `field.required ?? true` on the four visible field UIs (text, password, select, checkbox). Matches the JSDoc on HaapiBaseFormField.required ("Defaults to true.") and reflects the production reality that most LWA form fields are required. Update HaapiStepperFormUI.spec.tsx to keep `createLoginFormAction()` mirroring production (no `required: false` overrides) and instead fill the fields each test actually needs to clear via per-field helpers (fillUsername, fillPassword, selectCountry, checkRememberMe).

- Render theme.logo.path as <img className="haapi-stepper-logo">, positioned before or inside <Well> based on theme.logo.isInsideWell. - Add .haapi-stepper-logo CSS reusing --login-logo-* theme tokens (200px max-width, 40px max-height, object-fit: contain) and mirror legacy spacing (1.5rem mobile, 5rem >=576px outside the well, 0 inside). - Decorative alt="" + role="presentation".

luisgoncalves

I did a few tests and seems OK. I also skimmed on the code changes and they are bigger than I imagined. I see there are other reviews ongoing, so I'm adding my comments but leaving the final review for others that started before I did.

…8-required-attr-form-fields

…-page-symbols-data IS-11318 LWA: rework page symbols data in bootstrap configuration

…form-fields IS-11368 LWA: forward HaapiBaseFormField.required to rendered field inputs

…etup

…eb-app/IS-11345-display-logos IS-11345 Display configured logo in the Login Web App

@vahag-curity

Narrows the WebAuthn-runner classifier to honour the typings.ts contract: only DOMException routes to error.app (NotAllowed/Abort -> CANCEL_OR_TIMEOUT, any other DOMException -> FAILED). Anything else (TypeError, helper throw, malformed-payload access errors, etc.) propagates so the React error boundary catches it instead of being buried under 'Registration/Authentication failed' copy. Keeps Velocity-parity for users and covers future WebAuthn-spec DOMException names without an allowlist. Spec updated: the registration/authentication asserts that TypeError / 'arbitrary non-DOMException' map to the FAILED copy are flipped to .rejects.toBe(error), and the authentication side gains symmetric coverage. Addresses PR #194 review feedback from @vahag-curity and @luisgoncalves. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@vahag-curity

Switches mockRunWebAuthnRegistration / mockRunWebAuthnAuthentication from bare vi.fn() (Mock<any, any>) to vi.fn<typeof runWebAuthnX>(). With the runner contract Promise<ClientOperationResult> in scope, TypeScript now rejects mock fixtures that resolve outside the shape — including mockResolvedValue(undefined) which previously compiled silently and TypeError'd at runtime. The Auto-Start beforeEach baseline is updated to resolve to a sentinel clientOperationError: failedWebAuthnCeremonyError() so an unintended runner invocation surfaces loudly via error.app instead of progressing the stepper silently. Addresses PR #194 review feedback from @vahag-curity: the dispatcher's destructure has no production hazard — strict mode already prevents runners from falling off the end of Promise<ClientOperationResult>. The hazard was test-fixture authoring; this commit closes it at that layer rather than adding a runtime guard. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Follow-up to IS-11252: WebAuthn ceremony failures (cancel/timeout, parse errors, unsupported API, null credential) are now caught inside the WebAuthn runners and surfaced as client-synthesised AppError-class HaapiStepperErrors via useHaapiStepper().error.app, rather than throwing to the React error boundary. Runners now share a ClientOperationResult discriminated union; performClientOperation is restructured to propagate errors through the stepper instead of try/catch with null returns. Step metadata gains a viewData.error.clientOperation.webauthn.{cancelOrTimeout|registration|authentication} channel that supplies the user-facing copy.

Changes:

Introduce a ClientOperationResult shape and refactor performClientOperation + WebAuthn runners to return {clientOperationData} / {clientOperationError} rather than throw.
Classify caught WebAuthn errors via a two-bucket discriminator (cancelOrTimeout / failed) and resolve copy from currentStep.metadata.viewData.error.clientOperation.webauthn.
Restructure WebAuthn tests around the new result type, add error-bucket coverage, and extend HaapiMetadata/WebAuthn action types accordingly.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`feature/actions/client-operation/operations/webauthn/webauthn.ts`	Wraps ceremonies in try/catch, classifies errors, returns `ClientOperationResult`; threads `currentStep` for message lookup.
`feature/actions/client-operation/operations/webauthn/webauthn.spec.ts`	Replaces "throws" tests with "resolves with `clientOperationError`" tests covering DOM exceptions, null credentials, missing API, and metadata fallback.
`feature/actions/client-operation/operations/webauthn/typings.ts`	New `WEBAUTHN_ERROR_TYPE` / `WEBAUTHN_OPERATION` enums for bucket selection.
`feature/actions/client-operation/operations/typings.ts`	New `ClientOperationResult` discriminated-union shared across runners.
`feature/actions/client-operation/operations/client-operations.ts`	`performClientOperation` returns `ClientOperationResult`; adds `getHaapiStepperError` synthesiser; drops AbortError swallowing.
`feature/stepper/HaapiStepper.tsx`	Adapts to the new client-operation return shape and forwards `currentStep` + `clientOperationError` into `nextStepError`.
`feature/stepper/HaapiStepper.spec.tsx`	Reorganises WebAuthn tests under Auto-Start vs Registration/Authentication describes and adds error / retry coverage via `error.app`.
`data-access/types/haapi-step.types.ts`	Adds `HaapiMetadataViewData` chain typing the per-step WebAuthn error copy.
`data-access/types/haapi-action.types.ts`	Reworks WebAuthn registration action union and tightens any-device args to enforce at least one creation-options field.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…fier.

…-ui-with-error-notifier IS-5161 Wrap HaapiStepperStepUI with HaapiStepperErrorNotifier

…ader-fix-config IS-11318 LWA: fix propagation of bootstrap configuration in the dev setup

Catch every WebAuthn ceremony failure in the runners and surface it as a synthesised HaapiUnexpectedProblemStep via the existing error.app pipeline (rather than escalating to the React error boundary as a programming bug). Two-bucket discriminator (cancelOrTimeout / failed) matching Velocity parity. Copy comes from step.metadata.messages.error.clientOperation.webauthn with empty-string fallback while the BE keys land. * Runner-level synthesis: runWebAuthn{Registration,Authentication} catch the full error catalog (parse DOMException, create/get DOMException, TypeError, null credential, unsupported API) and throw a synthesised HaapiStepperError built via formatErrorStepData(HaapiUnexpectedProblemStep). * Dispatcher wrapping: performClientOperation wraps each WebAuthn runner in a .then/.catch chain returning ClientOperationResult discriminated union. The catch discriminates HaapiStepperError vs raw rejections via a type guard; raw errors propagate to the React boundary as programming bugs. * Type hierarchy: HaapiWebAuthnRegistrationClientOperationAction is now a proper discriminated union (passkeys | any-device) so consumers narrow via positive + negative type guards without casts. HaapiWebAuthnAnyDeviceArgs is also a discriminated union (platform-required | crossPlatform-required) expressing the "at least one of two" HAAPI spec invariant. * Metadata surface: HaapiMetadata.messages.error.clientOperation.webauthn carries the per-ceremony copy (cancelOrTimeout shared, registration, authentication). * Auto-start parity: manageWebAuthnAutoStart stays fire-and-forget via nextStep(); ceremony failures surface the same way as manual click (matching Velocity's .catch(handleError) pattern). * Tests: 23 runner-level tests in webauthn.spec.ts cover the full catalog per ceremony; HaapiStepper.spec.tsx wiring tests consolidated under one WebAuthn suite (Auto-Start gating + Registration/Authentication success+error routing), dropping the duplicate auto-start error-surfacing cases since manual click + auto-start share the dispatcher plumbing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…apiStepperError * Rename `HaapiMetadata.messages` → `HaapiMetadata.viewData` (and the dependent type aliases) so the metadata branch reads as view-customisation data emitted by the server rather than HAAPI step messages. Path becomes `step.metadata.viewData.error.clientOperation.webauthn.<key>`. * Extract `getHaapiStepperError` from `webauthn.ts` to `client-operations.ts` as a shared helper that takes a resolved message string and synthesises a `HaapiStepperError` from a `HaapiUnexpectedProblemStep`. WebAuthn-specific message resolution stays in `webauthn.ts` (`getWebAuthnErrorMessage`); other client operations (BankID, EBF) can reuse the helper when their per-runtime error handling lands. * Test fixtures + path-access assertions in `webauthn.spec.ts` updated to use the new `viewData` key. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ClientOperationResult is no longer WebAuthn-specific — the EBF and BankID runners will need it next. Extract it into a new sibling typings.ts file alongside the operation runners; keep the WebAuthn-specific enums where they are. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@vahag-curity

Narrows the WebAuthn-runner classifier to honour the typings.ts contract: only DOMException routes to error.app (NotAllowed/Abort -> CANCEL_OR_TIMEOUT, any other DOMException -> FAILED). Anything else (TypeError, helper throw, malformed-payload access errors, etc.) propagates so the React error boundary catches it instead of being buried under 'Registration/Authentication failed' copy. Keeps Velocity-parity for users and covers future WebAuthn-spec DOMException names without an allowlist. Spec updated: the registration/authentication asserts that TypeError / 'arbitrary non-DOMException' map to the FAILED copy are flipped to .rejects.toBe(error), and the authentication side gains symmetric coverage. Addresses PR #194 review feedback from @vahag-curity and @luisgoncalves. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@vahag-curity

Switches mockRunWebAuthnRegistration / mockRunWebAuthnAuthentication from bare vi.fn() (Mock<any, any>) to vi.fn<typeof runWebAuthnX>(). With the runner contract Promise<ClientOperationResult> in scope, TypeScript now rejects mock fixtures that resolve outside the shape — including mockResolvedValue(undefined) which previously compiled silently and TypeError'd at runtime. The Auto-Start beforeEach baseline is updated to resolve to a sentinel clientOperationError: failedWebAuthnCeremonyError() so an unintended runner invocation surfaces loudly via error.app instead of progressing the stepper silently. Addresses PR #194 review feedback from @vahag-curity: the dispatcher's destructure has no production hazard — strict mode already prevents runners from falling off the end of Promise<ClientOperationResult>. The hazard was test-fixture authoring; this commit closes it at that layer rather than adding a runtime guard. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…:curityio/ui-kit into feature/IS-11327/webauthn-error-handling

Decouples the WebAuthn runner from the client-operation dispatcher. Previously the runner imported `getHaapiStepperError` from `client-operations.ts`, which itself imports the runners — an awkward upward dependency. Co-locating the helper with `ClientOperationResult` (typings.ts) by way of a sibling `helpers.ts` follows the same shape used for the shared result type. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

aleixsuau and others added 5 commits May 20, 2026 14:46

IS-11327: reduce doc useless verbosity

65476cc

IS-11327: refactor webauthn error handling

16cc0cb

aleixsuau mentioned this pull request May 21, 2026

IS-11327 Unify EBF and BankID error handling #195

Merged

aleixsuau marked this pull request as ready for review May 25, 2026 07:50

aleixsuau requested review from luisgoncalves, urre and vahag-curity May 25, 2026 07:50

urre approved these changes May 25, 2026

View reviewed changes

aleixsuau added 2 commits May 25, 2026 14:40

IS-11368 LWA: forward HaapiBaseFormField.required to rendered field i…

2818521

…nputs.

IS-11368 Default createMockFormAction fields to required: true.

57743ad

vahag-curity reviewed May 26, 2026

View reviewed changes

Comment thread src/login-web-app/src/haapi-stepper/feature/stepper/HaapiStepper.tsx

vahag-curity reviewed May 26, 2026

View reviewed changes

aleixsuau and others added 4 commits May 26, 2026 14:34

IS-11368: remove default field required

20d5905

IS-11318 LWA: rework page symbols data in bootstrap configuration

01600a7

Base automatically changed from feature/IS-11302/webauthn-single-option-auto-start to integration/IS-5161/login-web-app May 26, 2026 16:21

luisgoncalves reviewed May 26, 2026

View reviewed changes

aleixsuau and others added 9 commits May 27, 2026 08:53

IS-5161: remove duplicated wells

a944e6a

Merge branch 'integration/IS-5161/login-web-app' into feature/IS-1136…

1d13d9b

…8-required-attr-form-fields

Merge pull request #205 from curityio/feature/IS-5161/IS-11318-update…

90f61bd

…-page-symbols-data IS-11318 LWA: rework page symbols data in bootstrap configuration

IS-11345: remove non-used deps

f4f9c2b

Merge pull request #200 from curityio/feature/IS-11368-required-attr-…

a4c4f2a

…form-fields IS-11368 LWA: forward HaapiBaseFormField.required to rendered field inputs

IS-11318 LWA: fix propagation of bootstrap configuration in the dev s…

3a4d2d5

…etup

IS-5161 Remove header, move app-layout side outside well

7224b9f

IS-5161 Logo spacing tweaks

4eec80c

IS-11345: refactor to use config provider

9fc10cb

aleixsuau and others added 4 commits May 27, 2026 15:53

IS-11345: logo tests

cd3eb5a

Merge pull request #204 from curityio/fix/integration/IS-5161/login-w…

78ff304

…eb-app/IS-11345-display-logos IS-11345 Display configured logo in the Login Web App

aleixsuau requested a review from Copilot May 28, 2026 08:42

Copilot started reviewing on behalf of aleixsuau May 28, 2026 08:43 View session

Copilot AI reviewed May 28, 2026

View reviewed changes

Comment thread ...n-web-app/src/haapi-stepper/feature/actions/client-operation/operations/webauthn/webauthn.ts

aleixsuau and others added 5 commits May 28, 2026 11:10

IS-11327: remove useless comment

f21525f

IS-11327: return failed error for null credentials

66bea62

IS-11327: remove viewData error messages

a1cdd99

IS-5161 Wrap HaapiStepperStepUI in App.tsx with HaapiStepperErrorNoti…

c582a9d

…fier.

Merge pull request #203 from curityio/feature/IS-5161/wrap-haapi-step…

69660e4

…-ui-with-error-notifier IS-5161 Wrap HaapiStepperStepUI with HaapiStepperErrorNotifier

vahag-curity reviewed May 28, 2026

View reviewed changes

Comment thread ...n-web-app/src/haapi-stepper/feature/actions/client-operation/operations/webauthn/webauthn.ts Outdated

vahag-curity approved these changes May 28, 2026

View reviewed changes

luisgoncalves and others added 13 commits May 28, 2026 15:46

Merge pull request #206 from curityio/feature/IS-5161/IS-11318-dev-lo…

da52027

…ader-fix-config IS-11318 LWA: fix propagation of bootstrap configuration in the dev setup

IS-11327: reduce doc useless verbosity

e1211c7

IS-11327: refactor webauthn error handling

bd01831

IS-11327: remove useless comment

c65a98f

IS-11327: return failed error for null credentials

e7eacaf

IS-11327: remove viewData error messages

1784e8c

Merge branch 'feature/IS-11327/webauthn-error-handling' of github.com…

e6b4e00

…:curityio/ui-kit into feature/IS-11327/webauthn-error-handling

aleixsuau merged commit f11acb1 into integration/IS-5161/login-web-app May 29, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

IS-11327 LWA: WebAuthn ceremony errors as HAAPI step AppErrors#194

IS-11327 LWA: WebAuthn ceremony errors as HAAPI step AppErrors#194
aleixsuau merged 42 commits into
integration/IS-5161/login-web-appfrom
feature/IS-11327/webauthn-error-handling

aleixsuau commented May 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luisgoncalves left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

aleixsuau commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luisgoncalves left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aleixsuau commented May 20, 2026 •

edited

Loading