@pyric/ui/auth

Classes

AuthFlowController

Constructors

Constructor

new AuthFlowController(auth: Auth): AuthFlowController;

Parameters

Returns

AuthFlowController

Methods

add()

add(spec: NewIdentitySpec): void;

Add + sign in as a new identity. The backend creates the identity (so claims resolve in rules and it shows up in the picker next time) and mints the credential in one step.

Credential creation happens BEFORE take’s emit: subscribers recompute the snapshot synchronously on emit, so creating after would publish a stale identity list (a useSyncExternalStore consumer would miss the new account until the next unrelated emit).

Parameters

Returns

void

cancel()

cancel(): void;

Dismiss — rejects with the faithful auth/popup-closed-by-user.

Returns

void

install()

install(): void;

Wire this controller’s resolver into the auth handle. Paired with uninstall for use in a React effect (install in the body, uninstall in the cleanup) — StrictMode-safe.

Returns

void

pick()

pick(uid: string): void;

Pick an existing identity (by uid). The backend mints the credential (and records the provider on the identity).

Parameters

Returns

void

resolver()

resolver(): AuthFlowResolver;

The resolver to hand to sandbox.setAuthFlowResolver. Popup and redirect share one implementation (the sandbox has no navigation).

Returns

AuthFlowResolver

snapshot()

snapshot(): HelperState;

Returns

HelperState

subscribe()

subscribe(fn: () => void): () => void;

Parameters

Returns

(): void;

Returns

void

uninstall()

uninstall(): void;

Returns

void

Interfaces

AuthProviderConfigEntry

One provider’s current enablement, as the hook exposes it.

Properties

AuthProviderTogglesProps

Properties

AuthSignInHelperProps

Properties

AuthUserEditorErrors

Properties

AuthUserEditorFields

Editable field set. claimsText is the raw textarea JSON. providerIds are the linked FEDERATED providers (google.com, apple.com, …) — password is credential-derived (the password field) and never appears here.

Properties

AuthUserEditorState

Properties

AuthUserFormField

What the AuthUserFormProps.renderField slot receives per field.

Properties

AuthUserFormProps

Properties

AuthUserListProps

Properties

ClaimsFieldProps

Properties

ClearUsersWithConfirmProps

Properties

DeleteUserWithConfirmProps

Properties

HelperState

Snapshot the helper UI renders from.

Properties

NewIdentitySpec

A field set for “add new account” — mirrors the emulator’s add-user form.

Properties

UseAuthFlowHelperResult

Properties

UseAuthProviderConfigResult

Properties

UseAuthUserEditorOptions

Properties

UseAuthUserEditorResult

Properties

UseAuthUsersResult

Properties

Type Aliases

AuthApi

type AuthApi = Pick<typeof sandbox,
  | "listUsers"
  | "subscribeUsers"
  | "createUser"
  | "updateUser"
  | "deleteUser"
  | "clearUsers"
  | "getAuthProviderConfig"
  | "setAuthProviderConfig"
| "subscribeAuthProviderConfig">;

The sandbox auth admin ops useAuthUsers drives, as an INJECTABLE bundle.

WHY (same rationale as @pyric/ui/firestore’s FirestoreApi): the hook defaults to the in-process pyric/auth sandbox ops, but Pyric Studio’s served mode drives the SAME ops over a SharedWorker (a parallel client over a MessagePort). Reading them from this context lets a consumer inject the worker client’s fns so the hook operates on the live worker user DB without knowing the backend.

The bundle is typed to the in-process signatures; a worker bundle is adapted (cast) at the Studio boundary. NOTE the worker listUsers is ASYNC (an RPC) whereas the in-process one is sync, so useAuthUsers tolerates a promise (it wraps the result in Promise.resolve).

Default = the real pyric/auth sandbox ops, so every existing consumer is unchanged: no provider needed unless swapping the backend.

AuthUserEditorAction

type AuthUserEditorAction =
  | {
  field: keyof AuthUserEditorFields;
  type: "setField";
  value: AuthUserEditorFields[keyof AuthUserEditorFields];
}
  | {
  type: "reset";
};

AuthUserFormFieldName

type AuthUserFormFieldName =
  | "email"
  | "password"
  | "display-name"
  | "phone-number"
  | "photo-url"
  | "providers"
  | "email-verified"
  | "disabled";

Field names the AuthUserFormProps.renderField slot receives, in render order. Claims is NOT a slot field — it stays the standalone <ClaimsField> (override it by composing useAuthUserEditor).

AuthUserFormSubmit

type AuthUserFormSubmit =
  | {
  mode: "create";
  request: CreateUserRequest;
}
  | {
  mode: "edit";
  request: UpdateUserRequest;
  uid: string;
};

What onSubmit receives — discriminated on the form’s mode.

ClaimsValidationResult

type ClaimsValidationResult =
  | {
  claims: Record<string, unknown> | undefined;
  ok: true;
}
  | {
  message: string;
  ok: false;
};

Type Declaration

{
  claims: Record<string, unknown> | undefined;
  ok: true;
}

claims

claims: Record<string, unknown> | undefined;

ok

ok: true;

claims is undefined when the input was empty/whitespace.

{
  message: string;
  ok: false;
}

message

message: string;

ok

ok: false;

SandboxIdentity

type SandboxIdentity = ReturnType<typeof listIdentities>[number];

One pickable identity, as reported by sandbox.listIdentities.

Variables

CUSTOM_CLAIMS_MAX_LENGTH

const CUSTOM_CLAIMS_MAX_LENGTH: 1000 = 1000;

Serialized-length cap, matching the emulator’s CUSTOM_ATTRIBUTES_MAX_LENGTH.

DEFAULT_KNOWN_PROVIDER_IDS

const DEFAULT_KNOWN_PROVIDER_IDS: readonly ["password", "anonymous", "google.com", "github.com", "apple.com", "microsoft.com"];

Providers always shown as a toggle row, regardless of whether the backend has an explicit entry for them yet (an unconfigured provider simply reads as disabled — same default the sandbox backend applies).

FORBIDDEN_CUSTOM_CLAIMS

const FORBIDDEN_CUSTOM_CLAIMS: readonly string[];

Reserved JWT/OIDC keys the Auth emulator rejects as custom claims. https://firebase.google.com/docs/auth/admin/create-custom-tokens

PROVIDER_LABELS

const PROVIDER_LABELS: Record<string, string>;

Provider-id → human label mapping, mirroring the provider set the Firebase emulator UI recognizes (it maps the same ids to icons; a headless library maps them to text and leaves icons to the consumer via data-pyric-provider-id).

Functions

AuthApiProvider()

function AuthApiProvider(__namedParameters: {
  children: ReactNode;
  value: AuthApi;
}): FunctionComponentElement<ProviderProps<AuthApi>>;

Provide an auth API bundle to the subtree. Pyric Studio supplies the in-process bundle for dev-seed review and the SharedWorker client bundle under pyric dev --ui.

Parameters

Returns

FunctionComponentElement<ProviderProps<AuthApi>>

AuthProviderToggles()

function AuthProviderToggles(__namedParameters: AuthProviderTogglesProps): Element;

Headless “Sign-in providers” toggle grid — the Authentication → Sign-in method surface. Known providers (password / anonymous / the built-in OAuth set) always render as a row; any OTHER provider already present in config (a custom OAuth id a host previously added) also gets a row. A free-text field lets a consumer enable an arbitrary OAuth provider id not in the known set — this is a SECTION, not a dialog: the add row lives inline, no modal.

Fully headless: styling hangs off data-pyric-*, matching the rest of @pyric/ui/auth (AuthUserList, AuthUserForm, …). Data + mutation come from useAuthProviderConfig; this component only renders + fires events.

Parameters

Returns

Element

AuthSignInHelper()

function AuthSignInHelper(__namedParameters: AuthSignInHelperProps): Element;

Headless emulator-style sign-in helper: an account picker over the sandbox’s known identities plus an add-account form (email, display name, custom-claims JSON with emulator-grade validation messages).

Ships zero styling. Structure is addressable via the data-pyric-* contract:

• root: [data-pyric-ui="auth-signin-helper"], [data-pyric-provider-id], [data-pyric-auth-type]
• picker: [data-pyric-account-list] > [data-pyric-account-entry]

  button[data-pyric-account-pick]

• form: form[data-pyric-add-account-form], fields [data-pyric-field="email" | "display-name" | "claims"], [data-pyric-claims-error] (role=alert), button[data-pyric-cancel], button[data-pyric-submit]

Positioning is the consumer’s job — render it inside your own modal or panel (the flow is host-UI-agnostic; only onCancel carries the popup-closed semantics).

Parameters

Returns

Element

authUserEditorReducer()

function authUserEditorReducer(state: AuthUserEditorState, action: AuthUserEditorAction): AuthUserEditorState;

Parameters

Returns

AuthUserEditorState

AuthUserForm()

function AuthUserForm(__namedParameters: AuthUserFormProps): Element;

Headless add/edit-user form over useAuthUserEditor — the emulator UI’s user dialog fields (email, password, display name, phone, photo URL, verified/disabled toggles, custom claims) with its validation messages. Zero CSS; structure addressable via data-pyric-*:

• root form[data-pyric-ui="auth-user-form"] with data-pyric-mode, data-pyric-is-dirty, data-pyric-is-valid state attrs
• every field (text inputs AND checkboxes) is wrapped in a label[data-pyric-field-label="<name>"] carrying a visible span[data-pyric-label-text] — labeled grid layouts are pure CSS (display: grid on the wrappers); label-less designs hide [data-pyric-label-text] and lean on the placeholders
• inputs [data-pyric-field="email" | "password" | "display-name" | "phone-number" | "photo-url" | "email-verified" | "disabled"]
• CREATE mode only: a “Sign-in providers” group (fieldset[data-pyric-field-label="providers"] wrapping [data-pyric-provider-checklist]) — one checkbox per federated provider the sandbox supports (FEDERATED_PROVIDER_IDS from pyric/auth; multiple selectable, entries land on CreateUserRequest.providerUserInfo)
• claims via the standalone <ClaimsField>
• per-field messages [data-pyric-field-error="email" | "password"] render INSIDE the field’s label wrapper, after the input
• button[data-pyric-cancel] / button[data-pyric-submit] (submit is disabled while invalid, or pristine in edit mode)

Submit emits payloads only — no sandbox calls — so the same form works for create and edit and the consumer owns error handling.

Parameters

Returns

Element

AuthUserList()

function AuthUserList(__namedParameters: AuthUserListProps): Element;

Headless users table — the emulator UI’s columns (Identifier, Provider, Created, Signed In, User UID, actions) over the data-pyric-* styling contract, with role-based table semantics so rows can virtualize (a real <table> can’t wrap a scroll container).

The hook (useAuthUsers) owns data + filter state; this component just renders. Disabled accounts carry data-pyric-user-disabled for dimmed styling.

Parameters

Returns

Element

ClaimsField()

function ClaimsField(__namedParameters: ClaimsFieldProps): Element;

Headless custom-claims textarea — the emulator UI’s customAttributes control. Standalone so custom forms can reuse the exact field (the playground’s sign-in helper and the user form both render one); validation itself lives in validateSerializedClaims.

Parameters

Returns

Element

ClearUsersWithConfirm()

function ClearUsersWithConfirm(__namedParameters: ClearUsersWithConfirmProps): Element;

Confirm-gated clear-all (the emulator UI’s “Clear all data”). Requires a <ConfirmProvider> ancestor.

Parameters

Returns

Element

DeleteUserWithConfirm()

function DeleteUserWithConfirm(__namedParameters: DeleteUserWithConfirmProps): Element;

Confirm-gated single-user delete (the emulator UI’s row-menu “Delete user”). Requires a <ConfirmProvider> ancestor.

Parameters

Returns

Element

fieldsFromRecord()

function fieldsFromRecord(record?: AuthUserRecord): AuthUserEditorFields;

Parameters

Returns

AuthUserEditorFields

initAuthUserEditorState()

function initAuthUserEditorState(initial?: AuthUserRecord): AuthUserEditorState;

Parameters

Returns

AuthUserEditorState

providerLabel()

function providerLabel(providerId: string): string;

Label for a provider id; falls back to the raw id for custom OAuthProvider ids the map doesn’t know.

Parameters

Returns

string

toCreateRequest()

function toCreateRequest(state: AuthUserEditorState): CreateUserRequest;

Full payload for sandbox.createUser — every non-empty field.

Parameters

Returns

CreateUserRequest

toUpdateRequest()

function toUpdateRequest(state: AuthUserEditorState): UpdateUserRequest;

Delta payload for sandbox.updateUser — only fields that changed from the initial record. A cleared displayName maps to null (the update API’s clear semantics).

Parameters

Returns

UpdateUserRequest

useAuthApi()

function useAuthApi(): AuthApi;

Read the active auth API bundle (defaults to in-process pyric/auth).

Returns

AuthApi

useAuthFlowHelper()

function useAuthFlowHelper(auth: Auth): UseAuthFlowHelperResult;

Emulator-style sign-in helper for a sandbox Auth handle.

Installs an AuthFlowController as the handle’s AuthFlowResolver for the lifetime of the calling component — the analog of browser getAuth wiring browserPopupRedirectResolver. While mounted, any signInWithPopup / signInWithRedirect call made against auth parks on state.request; render an account-picker UI (e.g. <AuthSignInHelper>) from state and settle with pick / add / cancel.

Install/uninstall is a paired effect, so the StrictMode double-mount installs and cleanly uninstalls. Sandbox-only: the controller throws failed-precondition if auth is prod-backed.

Parameters

Returns

UseAuthFlowHelperResult

useAuthProviderConfig()

function useAuthProviderConfig(auth: Auth): UseAuthProviderConfigResult;

Live sign-in provider config view over a sandbox Auth handle: sandbox.getAuthProviderConfig + sandbox.subscribeAuthProviderConfig + sandbox.setAuthProviderConfig. Mirrors useAuthUsers’s shape exactly (coarse “something changed, re-list” subscription; sync in-process, tolerates a promise over the SharedWorker client).

Sandbox-only: throws failed-precondition on a prod-backed handle (the hook surfaces that via error, same as useAuthUsers).

Parameters

Returns

UseAuthProviderConfigResult

useAuthUserEditor()

function useAuthUserEditor(options?: UseAuthUserEditorOptions): UseAuthUserEditorResult;

Headless add/edit-user state machine (reducer-based, like useDocumentEditor): field edits, claims-JSON validation with emulator-grade messages, dirtiness vs the initial record, and payload builders for useAuthUsers’ createUser / updateUser.

Parameters

Returns

UseAuthUserEditorResult

useAuthUsers()

function useAuthUsers(auth: Auth): UseAuthUsersResult;

Live user-admin view over a sandbox Auth handle: sandbox.listUsers + sandbox.subscribeUsers + CRUD actions.

The subscription is coarse (“something changed”): any user-DB mutation (from these actions, the running app’s sign-ups, the agent’s seeding) triggers a re-list, so the view stays live without per-row bookkeeping. Filtering is client-side (the sandbox is in-process; there is no server to push the query to).

Mutation errors (e.g. auth/uid-already-exists) throw to the caller: handle them at the call site like the firestore hooks’ createDocument. Sandbox-only: throws failed-precondition on a prod-backed handle (the hook surfaces that via error).

Parameters

Returns

UseAuthUsersResult

validateAuthUserFields()

function validateAuthUserFields(fields: AuthUserEditorFields): AuthUserEditorErrors;

Parameters

Returns

AuthUserEditorErrors

validateSerializedClaims()

function validateSerializedClaims(text: string): ClaimsValidationResult;

Validate the claims textarea’s raw text. Empty input is valid (no claims). Messages match the emulator UI verbatim so users see the same wording in both tools.

Parameters

Returns

ClaimsValidationResult