docs(auth): add email link authentication guide

[rutvik24]

Summary

• Add Auth email-link authentication guide and wire it into the docs nav.
• Cross-link related Auth docs (usage, phone, OIDC) and update the spellcheck dictionary.

Test plan

• yarn lint:markdown
• yarn lint:spellcheck
• Confirm Documentation / Spelling & Grammar check is green on the PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.09%. Comparing base (b7c4749) to head (9987e2b).

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #9170      +/-   ##
============================================
- Coverage     68.10%   68.09%   -0.01%     
+ Complexity     1912     1911       -1     
============================================
  Files           510      510              
  Lines         37877    37877              
  Branches       5193     5193              
============================================
- Hits          25792    25788       -4     
- Misses        10261    10262       +1     
- Partials       1824     1827       +3     

Flag	Coverage Δ
android-native	63.73% <ø> (-<0.01%)	⬇️
e2e-ts-android	53.92% <ø> (-0.06%)	⬇️
e2e-ts-ios	56.53% <ø> (ø)
e2e-ts-macos	49.74% <ø> (+0.01%)	⬆️
ios-native	68.63% <ø> (ø)
ios-ruby	100.00% <ø> (ø)
jest	45.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mikehardy]

We need to follow the upstream as closely as possible to start and emphasize the non-custom / default path first I think

Going with that - please drop the "plus two community helpers…" framing here so the intro matches upstream (official Hosting / App Links / Universal Links only), but tease the custom domain info for advanced integrations. Suggested replacement:

This page focuses on wiring the flow in React Native Firebase. It starts with the same default Hosting-domain path as the official Android and Apple guides; There is information on optionally adding custom domains and branded landing pages later.

[mikehardy]

handleCodeInApp / omit dynamicLinkDomain / omit default linkDomain is correct — please keep that.

Please add a short Migrate from Dynamic Links subsection (after this paragraph or after Console setup) covering the Admin SDK API call integrators need to run from the Android migration guide. This is the #1 failure mode in #8405 (DYNAMIC_LINK_NOT_ACTIVATED, emails still using FDL).

Suggested snippet:

import { getAuth } from 'firebase-admin/auth';

await getAuth().projectConfigManager().updateProjectConfig({
  mobileLinksConfig: {
    // Literal value from the Firebase migration docs — switches the project
    // from Dynamic Links to Firebase Hosting mobile links.
    domain: 'HOSTING_DOMAIN',
  },
});

Also note: if emails still contain *.page.link after this, the project is still on FDL; linkDomain in ActionCodeSettings is only for a custom Hosting domain, not this switch.

[mikehardy]

Please make the default Firebase Hosting domain the first and most prominent path. Every project already has PROJECT_ID.firebaseapp.com; that is how people will first integrate, and it matches upstream. Branded / custom-domain hosting is as-needed, not the getting-started path.

Suggested table (community tools mentioned, not promoted):

# Choose a hosting path

You need a domain that can receive `/__/auth/links` (App Links / Universal Links). Pick the simplest path that matches your app:

| Situation | Use |
| --- | --- |
| **Getting started** (no custom domain) | Use the project's default Hosting domain `PROJECT_ID.firebaseapp.com`. Register Android SHA-1 + SHA-256 in Firebase project settings so Firebase can serve association files. |
| **Custom / branded domain** | Attach a custom domain in Firebase Hosting (or reuse a domain you already operate). Serve `/.well-known/assetlinks.json` and `/.well-known/apple-app-site-association` on that host. Set `linkDomain` in `ActionCodeSettings` to that custom domain. |

Then keep a short "Optional: custom domain" section with the official association-file format (link Digital Asset Links + Apple associated domains). If you mention generators or sample hosts, one sentence is enough — e.g. "Community generators exist for these JSON files; they are optional." Please don't lead with or deep-link a specific third-party repo as Path A/B.

[mikehardy]

Thanks for documenting a full custom-host flow - this will be useful for people that need to step up to doing links with branding.

However, please demote this so it is not Path A. After the default PROJECT_ID.firebaseapp.com path, a short optional subsection is enough focusing on the steps and then showing your projects as possible implementations (what files to publish, Content-Type: application/json, include /__/auth/links*). Please don't clone/deploy a specific third-party host as the recommended getting-started steps; that diverges from upstream style. Mentioning that community hosts/generators exist is fine.

[mikehardy]

Same ask as Path A: treat this as optional custom-domain material, not a primary path, and mention but don't promote a specific helper UI as the way to generate association files.

Suggested replacement for this whole subsection - official files only:

### Association files (custom domain only)

Publish these at the Hosting / custom domain (inline JSON, not a file download):

- `https://YOUR_DOMAIN/.well-known/assetlinks.json`
- `https://YOUR_DOMAIN/.well-known/apple-app-site-association`

`assetlinks.json` needs `package_name` + SHA-256 fingerprints. AASA needs your Apple Team ID + bundle ID and paths covering `/__/auth/links*`.

On the default PROJECT_ID.firebaseapp.com path, Firebase serves these after SHA fingerprints are registered — no separate generator required.

[mikehardy]

Please don't throw when the stored email is missing - that's the normal cross-device case. Prompt for the email, then call signInWithEmailLink (you already describe that in §3; the snippet should match).

Suggested replacement for the missing-email branch:

const email = await AsyncStorage.getItem(EMAIL_KEY);
if (!email) {
  // Same device: shouldn't happen. Other device / cleared storage:
  // prompt the user to type the address the link was sent to, then continue.
  return;
}

Also wrap signInWithEmailLink in try/catch and surface error.code (expired/reused links show up as auth/invalid-action-code).

[mikehardy]

Optional but useful - the upstream guides cover these and they're easy to miss:

• Link / re-auth: EmailAuthProvider.credentialWithLink(email, url) then linkWithCredential / reauthenticateWithCredential (same URL handling as sign-in).
• Email enumeration protection: projects created after 2023-09-15 should not use fetchSignInMethodsForEmail for identifier-first UI; see Firebase's note on the email-link pages.

[mikehardy]

Please don't make a specific third-party sample the “Example app” centerpiece - same style as other RNFB auth pages, which stay in-repo / official.

Suggested replacement: reduce it to one optional sentence at the end of Related, e.g. "Community sample apps exist that wire App Links + Universal Links + the modular Auth APIs." The in-page snippets + checklist should be the worked example.

[mikehardy]

Checklist is great. Please add a Troubleshooting heading after it - this is the part people (and agents these days...) actually search for. Suggested rows:

Symptom	What to check
DYNAMIC_LINK_NOT_ACTIVATED / email still uses *.page.link	Run Admin SDK mobileLinksConfig.domain: 'HOSTING_DOMAIN'. Do not set dynamicLinkDomain.
Link opens the browser, not the app	Physical device; AASA/assetlinks 200 + application/json; intent-filter / applinks: host is the Hosting link domain (PROJECT_ID.firebaseapp.com/__/auth/links), not only the continue URL.
iOS: Firebase email URL doesn't open the app, but pasting the Hosting URL does	Custom SMTP (e.g. SendGrid) wrapping the Auth URL in a redirect. Universal Links do not follow that redirect into the app. Use Firebase's default email sender, or a custom SMTP that does not wrap the destination URL. Reported in #8405.
auth/invalid-action-code	Link expired or already used; send a new one.
auth/internal-error	Check native logs (adb logcat / Console.app on a real device), not just the JS error.

[mikehardy]

Please lead Related with official docs only (same as phone/social pages):

# Related

- [Authentication usage](/auth/usage)
- Firebase: [Android email link](https://firebase.google.com/docs/auth/android/email-link-auth) · [iOS email link](https://firebase.google.com/docs/auth/ios/email-link-auth) · [Migrate off Dynamic Links](https://firebase.google.com/docs/auth/android/email-link-migration)

If you want a community-tools mention, one trailing sentence is enough — no extra doc/demo/helper links in this list.

[mikehardy]

Thank you for this - it's a substantial, carefully researched guide on a genuinely hard flow, and filling this gap in the RNFB docs is really appreciated.

Requesting a structural pass so the page matches the style of the upstream Firebase email-link docs: official default / non-branded path first (the way people will first integrate), then optional custom-domain / branded hosting. Community tools can be mentioned where they help, but please don't promote specific projects - same approach as our other auth pages (phone, social), which link official Firebase docs and leave third-party helpers as optional asides.

Inline comments have suggested copy where that might reduce back-and-forth. None of this is a knock on the work you've already done; it's aligning the page with how we document the rest of Auth and I think this will help a lot of people in one of the more difficult areas of cross-platform mobile dev