feat: prefer canonical awaiting-input contract

[masnwilliams]

Summary

• Add the public canonical awaiting-input shapes (fields and choices) while retaining legacy response support during the deprecation window.
• Treat canonical arrays as authoritative when present so stale legacy fields or choices cannot leak across flow steps.
• Submit canonical field and choice IDs through field_values and selected_choice_id; keep legacy field, SSO, MFA, and sign-in submissions for legacy responses.
• Preserve exact MFA choice IDs for submission and carry masked destinations from the parallel legacy projection when available.
• Export the new public types and mark the package change as minor.

The worker's browser-grounding target stays server-side. The hosted client renders the public API's IDs, labels, descriptions, and optional selectors, then submits stable IDs instead of browser locators.

Test plan

• bun run test
• bun run typecheck
• bun run build
• bun run format:check
• cd packages/managed-auth-react && npm pack --dry-run

---

Note

Medium Risk
Changes managed-auth login submission and state normalization on the critical auth path, though legacy API fallbacks limit breakage during the deprecation window.

Overview
@onkernel/managed-auth-react now understands the canonical awaiting-input API (fields, choices) while keeping legacy discovered_fields, mfa_options, and related shapes during deprecation.

When canonical arrays are present, normalizeManagedAuthState treats them as authoritative (so stale legacy options do not leak across steps), maps them into the existing UI model, and mergeStateEvent clears awaiting-input data when the next SSE snapshot omits it. Submissions go through a single submitManagedAuth path with builders that send field_values / selected_choice_id for canonical responses and the previous fields, sso_button_selector, mfa_option_id, and sign_in_option_id payloads otherwise; MFA clicks pass stable choiceId through the form components.

Public types ManagedAuthField and ManagedAuthChoice are exported, Bun unit tests cover normalization and submission, and CI runs bun run test (minor changeset).

^{Reviewed by Cursor Bugbot for commit 9c6302c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
managed-auth-react-demo	Ready	Preview, Comment	Jul 28, 2026 8:30pm

[dcruzeneil2]

The final shape is close and the hard parts are right: canonical-first with legacy fallback is the correct migration posture, the client only sends canonical submit payloads after the server has sent canonical data first (so rollout ordering is safe), and the snapshot-replace fix in mergeStateEvent landed on the correct semantics. CI is green.

I checked the types and submit payloads here against the upcoming API behavior and most of it lines up: the field and choice type enums match, field_values keyed by canonical field id round-trips correctly, and SSO submit via selected_choice_id works. Two things don't line up, and one behavioral gap will show up as soon as the API starts emitting canonical data. Requesting changes on the first two, the rest are non-blocking.

Blocking

1. The submit strategy is split down the middle, and the MFA half loses information. Fields and SSO now submit canonically, but MFA and sign-in selections rendered from canonical choices still go through the legacy helpers. For MFA this is lossy: mfaOptionsFromCanonical squashes choice.id through normalizeMFAChoiceId, and since MFAOption has no id, the original choice id is gone by submit time. Anything unrecognized collapses to "other", so two unfamiliar MFA methods become indistinguishable to the server. This happens to work right now because of how the server currently builds these ids, but that's a coincidence, not a contract. The fix I'd like to see: add an optional id to MFAOption (and SignInOption) and submit selected_choice_id whenever the option came from canonical data, same as submitSSO already does. If we'd rather not do that yet, then revert fields/SSO to legacy submits too so the switch happens as one coherent change. Half-and-half is the one state we shouldn't ship. Also worth noting the PR description still says everything submits through legacy helpers, which stopped being true a few commits ago.

2. ManagedAuthChoice.display_text and context don't exist in the API contract. The fallback chain in signInOptionsFromCanonical (description ?? context ?? display_text) can never fire, and the type definitions will convince the next reader that the wire carries fields it doesn't. Please drop both, or hold this until they actually exist on the API side if that's the plan.

Should fix

3. MFA options rendered from canonical lose the masked destination. Legacy MFAOption.target carries hints like ***-***-5678, the canonical choice has no slot for it, and this PR prefers canonical when present. So the moment the API ships canonical data, MFA steps stop showing the masked phone/email even though the legacy arrays in the same payload still have it. This is deterministic, not an edge case. A reasonable client-side fix while the dual contract exists: carry target over from the matching legacy mfa_options entry during normalization.

4. The legacy fallback should key off whether canonical data is present, not whether the conversion produced anything. Right now a payload with canonical choices containing only SSO buttons plus a stale legacy mfa_options array would render both, mixing content from two different steps. Not reachable with the current server since both views come from the same source, but the fix is one line per category: if choices is non-null, derive every choice-based category from canonical only, and same for fields.

Nits

5. The snapshot-vs-merge question took three review rounds to settle and the answer now lives only in a comment. mergeStateEvent and the *FromCanonical helpers are pure functions, so a small test file would lock in "absent key means cleared" before someone re-adds the ?? base.fields fallback because it looks like the safe thing to do.

6. ManagedAuthResponse is exported and now references ManagedAuthField and ManagedAuthChoice, which aren't exported from index.ts, so consumers can see the shape but can't name it. And given the new public type surface and new submit behavior, this feels like a minor rather than a patch.

Happy to take another look as soon as 1 and 2 are in. Everything else here is small.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3bb911b. Configure here.}