Home Mac app guides Auth GUI

Auth GUI

Last updated on Jul 12, 2026

Purpose

The Auth module manages Firebase Authentication users. It supports user listing, search, sorting, filtering, editing, bulk actions, import/export, transfers, JS scripting, provider visibility, custom claims, and Auth-to-Firestore linking.

User List and Search

The table/grid supports:

  • paginated or streaming user list loading
  • sorting by email, phone, UID, created time, and last login
  • direct search by UID, email, and phone number
  • local filtering by display name, claim value, provider, email verified, disabled/enabled status, creation range, and last sign-in range
  • combined filters
  • saved search presets
  • real-time result updates

Output Modes

  • TABLE: user grid and primary admin workflow
  • TREE: structured user/provider/claim view
  • JSON: raw user payload view
  • LOGS: Auth API, app, script, warning, and error logs

User Editing

Editable or visible fields:

  • UID
  • created timestamp, read-only
  • last login timestamp, read-only
  • email
  • password update flow
  • hashed password import/update path where supported
  • phone number
  • display name
  • photo URL
  • disabled state
  • email verified state
  • custom claims/tokens
  • provider linkage visibility
  • linked provider list

User actions:

  • create user, including custom UID
  • edit attributes
  • delete user
  • disable or enable user
  • mark or unmark email verified
  • bulk disable
  • bulk delete

Import, Export, Transfer

The module supports CSV/JSON import and export plus project-to-project transfer of users. Long-running imports, exports, deletes, disables, and transfers should run through Tasks.

JS Scripting

Auth JS scripts run locally with a local admin.auth()-style shim. Scripts can list users, update the local runtime snapshot, return structured objects for table/tree/json rendering, and emit logs. Use the Auth editor/import/transfer actions for Firebase mutations.

Auth to Firestore Linking

Auth/Firestore linking settings belong to the project selected in the sidebar. The Auth source dropdown selects project-wide Auth, a discovered/configured tenant, or a custom tenant ID when discovery is unavailable. The Firestore destination dropdown selects a linked Firestore instance and database as one endpoint; collection path is configured separately. This lets multiple tenants share one Firestore instance with separate collections or route to different Firestore instances without presenting a generic Firebase-project selector. UID mapping can use the Firestore document ID or a field value; shared collections can additionally filter by a tenant discriminator field/value pair. Auth user views can open linked Firestore user documents and show clear linked/unlinked states.

Current emulator evidence covers persisted mapping settings, selected-project sync, linked and missing Auth-side states, disabled navigation for a missing Firestore document, Auth-to-Firestore navigation, and focused Firestore-to-Auth reverse navigation. App-state tests cover selected-project route ownership, endpoint selector state, tenant-scoped route selection, shared-collection discriminator filtering, cross-project/database forward routing, and reverse restoration of the source Auth project and tenant. The endpoint-selector XCUITest passed on 2026-07-12 against external Firebase emulators and created one tenant route to a separate Firestore destination plus another route to a nested collection in the selected project's Firestore instance. Its retained result bundle is build/emulator-ui-artifacts/20260712-150333-auth-firestore-endpoint-selectors.xcresult.

Storage Photo Workflow

When Storage is configured, the Auth editor can write a selected Storage download URL back to photoURL. Current emulator proof covers the Storage URL handoff path: choosing an existing Storage object URL, writing it through the Auth editor, verifying the Auth emulator value, and confirming the Storage object remains browsable. Direct file-picker upload proof and approved live Storage proof remain open. Signed URL generation is handled separately by the Storage URL action.

Safety

  • Read-only projects block Auth writes.
  • Pro access gates Auth mutations, import/export, transfer, and scripts.
  • Production writes and destructive actions require confirmation.

Source Anchors

  • Sources/FirestructApp/Features/Auth/UI/AuthModuleView.swift
  • Sources/FirestructApp/Features/Auth/UI/AuthModuleView+Controls.swift
  • Sources/FirestructApp/Features/Auth/UI/AuthModuleView+Editor.swift
  • Sources/FirestructApp/Features/Auth/UI/AuthModuleView+Outputs.swift
  • Sources/FirestructApp/Features/Auth/Services/
  • Sources/FirestructCore/AuthListService.swift
  • Sources/FirestructCore/AuthListService+Operations.swift