Profile Inspector — Firestore & Auth Diagnostic Tool

Last Updated: 2026-03-18

A unified inspection tool that queries Firebase Auth, users, adminProfiles, and merchantProfiles for a given UID and presents them side by side with automatic consistency checks.

Why this exists: Admin users have data spread across users/{uid} and adminProfiles/{uid} (same UID, different collections). Fields like displayName, phone, and updatedAt can drift out of sync. This tool makes mismatches immediately visible.

---

Quick Start

# Full inspection — Auth + users + adminProfiles + merchantProfiles
./tooling/scripts/inspect-profile.sh <USER_UID>

# Compare shared fields between users and adminProfiles
./tooling/scripts/inspect-profile.sh <USER_UID> --diff

# Raw JSON (pipe to jq, save to file, etc.)
./tooling/scripts/inspect-profile.sh <USER_UID> --json

# Inspect only one source
./tooling/scripts/inspect-profile.sh <USER_UID> --collection users
./tooling/scripts/inspect-profile.sh <USER_UID> --collection adminProfiles
./tooling/scripts/inspect-profile.sh <USER_UID> --collection auth

# Target a different project
./tooling/scripts/inspect-profile.sh <USER_UID> --project lantern-app-prod

---

Prerequisites

• Node.js 22+
• firebase-admin installed (available in the repo's root node_modules)
• Application Default Credentials for the target project, or GOOGLE_CLOUD_PROJECT set in .env.local

---

What It Shows

Summary Header

A quick at-a-glance view:

╔══════════════════════════════════════════════════╗
║  PROFILE INSPECTOR — aR7ivxIk48Wi...            ║
║  Project: lantern-app-dev                        ║
╚══════════════════════════════════════════════════╝

  Summary:
  UID:              aR7ivxIk48Wijw1nXBs8C9KyfhB2
  Role:             admin
  Auth record:      ✓
  users doc:        ✓
  adminProfiles:    ✓
  merchantProfiles: —

Automatic Consistency Warnings

The script checks for common mismatches and flags them:

Check	Example Warning
Admin role but no adminProfiles doc	User has admin role but NO adminProfiles document
adminProfiles exists but role ≠ admin	User has adminProfiles document but role is "user", not admin
Merchant role but no merchantProfiles doc	User has merchant role but NO merchantProfiles document
Email mismatch (Auth vs Firestore)	Email mismatch: Auth=a@b.com, Firestore=x@y.com
displayName mismatch (Auth vs users)	displayName mismatch: Auth="Foo", users="Bar"
displayName mismatch (users vs adminProfiles)	displayName mismatch: users="Foo", adminProfiles="Bar"

Collection Sections

Each source is printed with all fields, ordered alphabetically. Long encrypted/sensitive values are truncated with length indicators:

• [encrypted] — Client-side encrypted fields (e.g., encryptedBirthDate, encryptedSeed)
• [sensitive] — Key material or hashes (e.g., salt, phoneSalt, authProofHash)

Diff Mode (--diff)

Compares the four shared fields between users and adminProfiles:

• displayName
• phone
• githubUsername
• updatedAt

Flags mismatches with ⚠ and shows both values. Also lists fields unique to each collection.

---

Options Reference

Flag	Description
--json	Output raw JSON instead of formatted table. Timestamps are ISO 8601.
--diff	Show field-by-field comparison of users vs adminProfiles.
--collection <name>	Only query one source: users, adminProfiles, merchantProfiles, or auth.
--project <id>	Override Firebase project (default: lantern-app-dev).

---

Collections Compared

users/{uid}

The main user profile document. Contains public fields (lanternName, interests, mood), encrypted personal data, encryption key material, auth method fields, role/ban state, and timestamps.

adminProfiles/{uid}

Supplementary document for admin users. Contains displayName (real name), phone (emergency contact), emergencyContact, notes, githubUsername, and admin password fields. Same UID as users.

merchantProfiles/{uid}

Supplementary document for merchant users. Created by Cloud Functions only. Read by merchants (own doc) and admins (all docs).

Firebase Auth Record

The authentication record: email, phone, providers, custom claims (role), disabled state, and login timestamps.

---

Common Workflows

"Is this admin fully set up?"

./tooling/scripts/inspect-profile.sh <UID>

Check for:

• Auth record: ✓ and customClaims: {"role":"admin"}
• users doc: ✓ with role: admin
• adminProfiles: ✓ with displayName populated
• No consistency warnings

"Why is displayName wrong in the admin portal?"

./tooling/scripts/inspect-profile.sh <UID> --diff

The admin portal reads from adminProfiles.displayName, while the main app may show users.displayName or Auth.displayName. The diff shows which one is stale.

"Quickly check encryption state"

./tooling/scripts/inspect-profile.sh <UID> --collection users

Look for salt or phoneSalt (which auth method), encryptionCanary, encryptedSeed, and recoveryBackupBlob.

"Export profile data for debugging"

./tooling/scripts/inspect-profile.sh <UID> --json > /tmp/profile-debug.json

---

See Also

• PHONE_AUTH_RESET.md — Reset phone auth state for re-testing
• FIREBASE_EMULATOR_TESTING.md — Local emulator testing
• LOCAL_TESTING.md — General local dev testing
• Scripts Guide — All available scripts