fix: handle EasyAuth 302 redirect and improve auth error detection in useAgentCard

[ccastrotrejo]

Commit Type

• feature - New functionality
• fix - Bug fix
• refactor - Code restructuring without behavior change
• perf - Performance improvement
• docs - Documentation update
• test - Test-related changes
• chore - Maintenance/tooling

Risk Level

• Low - Minor changes, limited scope
• Medium - Moderate changes, some user impact
• High - Major changes, significant user/system impact

What & Why

When Azure EasyAuth is enabled and the user's session expires, the server returns a 302 redirect to the login page instead of a 401. Because the fetch API follows redirects by default and the login page is on a different origin, this results in a CORS error (opaque redirect / TypeError: Failed to fetch) rather than a meaningful HTTP status code. The useAgentCard hook did not handle this scenario, causing it to surface a generic network error instead of triggering the onUnauthorized callback.

Additionally, authentication detection relied on comparing response.statusText === 'Unauthorized', which is fragile and does not cover 403 Forbidden responses.

Changes

• Handle network/CORS errors as auth failures: Wrapped the fetch() call in a try/catch block so that TypeError: Failed to fetch (caused by EasyAuth 302 redirects or CORS blocks) triggers the onUnauthorized callback and throws an Unauthorized error.
• Use HTTP status codes for auth detection: Replaced response.statusText === 'Unauthorized' check with response.status === 401 || response.status === 403 for robust authentication failure detection.
• Extract handleUnauthorized helper: Consolidated the duplicated unauthorized handling logic (calling onUnauthorized callback + throwing error) into a reusable handleUnauthorized async function.
• Improve error messages: Updated non-auth error messages to include the HTTP status code (e.g., Failed to fetch agent card: 500 Internal Server Error).
• Add comprehensive tests: Added tests for EasyAuth redirect handling, 403 Forbidden responses, and network failure without onUnauthorized callback. Updated existing test mocks to include status property.

Impact of Change

• Users: Users behind EasyAuth will now be properly redirected to re-authenticate when their session expires, instead of seeing a generic network error.
• Developers: No API changes. The onUnauthorized callback now also fires on network/CORS errors and 403 responses.
• System: No performance or architecture impact. Only affects the iframe-app's useAgentCard hook.

Test Plan

• Unit tests added/updated
• E2E tests added/updated
• Manual testing completed
• Tested in: EasyAuth-enabled Azure environment with expired session

Contributors

Screenshots/Videos

[github-actions]

🤖 AI PR Validation Report

PR Review Results

Thank you for your submission! Here's detailed feedback on your PR title and body compliance:

✅ PR Title

• Current: fix: handle EasyAuth 302 redirect and improve auth error detection in useAgentCard
• Issue: None — title is clear, follows conventional commit prefix, and names the affected hook.
• Recommendation: No change required.

---

✅ Commit Type

• Properly selected (fix).
• Note: Only one commit type selected which is correct.

---

✅ Risk Level

• The PR body marks this as Low and the PR has the label risk:low. They match.
• Note: There is also a needs-pr-update label on the PR — if you have addressed maintainers' previous requests, consider removing that label.

---

✅ What & Why

• Current: The body contains a clear explanation of the EasyAuth 302 redirect -> CORS/network error problem, why prior statusText checks were fragile, and enumerates changes made.
• Issue: None significant.
• Recommendation: No change required; great explanation and change list.

---

⚠️ Impact of Change

• The PR documents Users/Developers/System impact and that it only affects iframe-app's useAgentCard hook.
• Recommendation: Good. You may optionally call out the two changed files in the Impact section for quick reviewer context (apps/iframe-app/src/hooks/useAgentCard.ts and its tests).
  • Users: Users behind EasyAuth will now be redirected to re-authenticate rather than getting a generic network error.
  • Developers: onUnauthorized now also fires for network/CORS errors and 403 responses; no API surface changes.
  • System: No perf/arch changes.

---

✅ Test Plan

• Unit tests were added/updated (confirmed in diff). Manual testing is checked in the PR body. E2E tests are not added — which is acceptable here given this is a small hook change.
• Recommendation: Ensure CI passes (unit tests). If you performed the manual EasyAuth test in a real EasyAuth-enabled environment, consider checking the optional line under Test Plan (Tested in: EasyAuth-enabled Azure environment with expired session) or add a short note describing the manual steps taken.

---

⚠️ Contributors

• The Contributors section is blank.
• Recommendation: It's optional, but please remember to credit any PMs/designers/reviewers who helped. If there are no additional contributors, leaving blank is acceptable.

---

✅ Screenshots/Videos

• No visual changes — appropriate to leave blank.

---

Summary Table

Section	Status	Recommendation
Title	✅	No change needed.
Commit Type	✅	No change needed.
Risk Level	✅	Matches label; OK.
What & Why	✅	Clear and sufficient.
Impact of Change	⚠️	Optionally call out changed files.
Test Plan	✅	Unit tests present; ensure CI passes.
Contributors	⚠️	Optional: add credits if applicable.
Screenshots/Videos	✅	Not applicable.

---

Final notes and actionable recommendations

Overall this PR passes the PR title/body checks and the advised risk level based on the code diff is low, which matches the submitter's assigned Low risk.

A few actionable code-related suggestions discovered from the diff that you should address before merging:

• Remove the debug console.log: the diff contains console.log('charlie error:', er); in the catch block. Please remove or replace with an appropriate logger call (or leave a meaningful comment) before merging.

• CI and linter: ensure the added tests and TypeScript changes pass CI and linting. (The handleUnauthorized helper returns Promise<never> and is used where an AgentCard would be expected at the type level — TypeScript accepts never as a subtype, but please verify your build/tsconfig flags don't flag this pattern.)

• Manual test documentation: if you ran manual verification in an EasyAuth-enabled environment, consider checking the optional Test Plan checkbox and adding 1–2 lines describing the steps you followed (so reviewers can reproduce if needed).

• Optional test enhancement: you already added good unit tests for network/CORS errors and 403 handling. If onUnauthorized may be async in some callers, consider adding a test that validates an async onUnauthorized is awaited (the code uses await config.onUnauthorized(), so that behavior is already implemented, but a test would protect regressions).

Please make the minor fixes (remove debug log, verify CI), update any small test or documentation gaps if desired, and then re-run CI. Thank you for the thorough change and the test coverage — this looks well scoped and safe to merge once the small items above are addressed.

---

Last updated: Mon, 09 Feb 2026 21:58:24 GMT

[github-actions]

📊 Coverage check completed. See workflow run for details.

[github-actions]

📊 Coverage check completed. See workflow run for details.

[Copilot]

Pull request overview

This PR updates the iframe-app’s useAgentCard hook to better handle Azure App Service EasyAuth scenarios where unauthenticated requests can result in a 302 redirect (often surfacing as an opaque redirect / status 0 in the browser), and to funnel those cases through the existing onUnauthorized flow.

Changes:

• Adds a shared handleUnauthorized helper to centralize onUnauthorized invocation + error throwing.
• Forces fetch to use redirect: 'manual' and treats opaque redirects / status === 0 as unauthorized.
• Treats fetch rejection (e.g., network/CORS failures) as unauthorized.

[github-actions]

📊 Coverage check completed. See workflow run for details.

[github-actions]

📊 Coverage check completed. See workflow run for details.