feat: add INVALID_CALLBACK_URL web auth error code

[subhankarmaiti]

Adds a typed INVALID_CALLBACK_URL web auth error code so callers can catch callback-URL mismatches without string-matching on the error message.

On iOS, this surfaces when ASWebAuthenticationSession captures an in-page link that uses thenapp's custom scheme (e.g. a privacy-policy link inside Universal Login) instead of the real callback. Because Apple's custom-scheme callback matches on scheme only (no host/path), any same-scheme URL ends the session and fails authorize(). Previously this came through as an uncategorized UNKNOWN_ERROR with a "Invalid callback URL" message.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds INVALID_CALLBACK_URL handling across iOS native error translation, JavaScript error classification, tests, and WebAuth error documentation.

Changes

Callback URL error handling

Layer / File(s)	Summary
Callback URL error classification src/core/models/WebAuthError.ts, ios/NativeBridge.swift	Adds the INVALID_CALLBACK_URL error constant and raw-code mapping, and translates matching iOS native messages to that code.
Callback URL error validation and documentation src/core/models/__tests__/ErrorCodes.spec.ts, src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts, README.md	Validates the new error constant and iOS provider mapping, and documents the updated platform-specific error behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant NativeBridge
  participant NativeWebAuthProvider
  participant WebAuthError
  NativeBridge->>NativeWebAuthProvider: reject authorize with INVALID_CALLBACK_URL
  NativeWebAuthProvider->>WebAuthError: classify raw error code
  WebAuthError-->>NativeWebAuthProvider: type INVALID_CALLBACK_URL

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the INVALID_CALLBACK_URL web auth error code.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/invalid-callback-url-error-code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts (1)

192-198: 🎯 Functional Correctness | 🔵 Trivial | 🏗️ Heavy lift

Cover the native-to-JavaScript translation path.

This test injects INVALID_CALLBACK_URL after translation, so it does not verify the changed NativeBridge.swift branch. Add a native or integration test starting from the underlying "Invalid callback URL" error and asserting that the bridge emits INVALID_CALLBACK_URL.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts`
around lines 192 - 198, Extend the native error translation coverage for the
authorize flow represented by the existing INVALID_CALLBACK_URL case. Start the
test with the underlying “Invalid callback URL” error before translation, then
assert that the native bridge emits the INVALID_CALLBACK_URL code and
corresponding translated error to JavaScript; do not inject the
already-translated code as the mock input.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ios/NativeBridge.swift`:
- Around line 705-710: Replace the errorDescription-based classification in
NativeBridge.swift lines 705-710 with a stable native error-code check, or
explicitly preserve and test the message contract if no code is available. In
src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts
lines 192-198, add coverage that supplies the underlying invalid-callback error
and verifies the bridge emits INVALID_CALLBACK_URL rather than injecting that
code after translation.

In `@README.md`:
- Line 894: Update the INVALID_CALLBACK_URL guidance in the README to preserve
the required iOS callback format
{BUNDLE_ID}://{DOMAIN}/ios/{BUNDLE_ID}/callback. Clarify that only unrelated
in-page links, such as privacy-policy links, should use HTTPS instead of the
app’s custom scheme; do not recommend replacing the configured callback with an
HTTPS or Universal Link redirect.

In `@src/core/models/WebAuthError.ts`:
- Around line 60-61: Update the JSDoc comment for the INVALID_CALLBACK_URL enum
member to include the required “iOS only” notation, while preserving its
existing callback URL description.

---

Nitpick comments:
In
`@src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts`:
- Around line 192-198: Extend the native error translation coverage for the
authorize flow represented by the existing INVALID_CALLBACK_URL case. Start the
test with the underlying “Invalid callback URL” error before translation, then
assert that the native bridge emits the INVALID_CALLBACK_URL code and
corresponding translated error to JavaScript; do not inject the
already-translated code as the mock input.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: abe7974f-04e9-448b-978c-a084758b4676

📥 Commits

Reviewing files that changed from the base of the PR and between 22065da and 8ab890d.

📒 Files selected for processing (5)

• README.md
• ios/NativeBridge.swift
• src/core/models/WebAuthError.ts
• src/core/models/__tests__/ErrorCodes.spec.ts
• src/platforms/native/adapters/__tests__/NativeWebAuthProvider.errors.spec.ts