@fayz-ai/auth

Pluggable auth for Fayz apps — one hook, swappable adapters.

Status: beta — published to npm and used across Fayz dogfood apps. Pre-1.0: minor APIs may change before 1.0.

Auth shouldn't be the thing that couples your app to a backend. @fayz-ai/auth wraps authentication behind the core AuthAdapter contract so a Fayz app reads the same whether it's running on Supabase in production or a mock adapter in tests and previews. One provider, one useAuth hook, a Zustand-backed session store — the rest is an implementation detail you can swap.

This is the auth layer for composed Fayz SaaS apps: drop in AuthProvider, pick an adapter, and every plugin gets a consistent user and session without knowing where it came from.

What's inside

• createSupabaseAuthAdapter — production Supabase auth, typed via SupabaseAuthConfig
• createMockAuthAdapter — deterministic auth for tests, demos, and previews (MockUser)
• AuthProvider + useAuth — React context and hook for the current user and session
• useAuthStore — the underlying Zustand store (AuthState, AuthStore) for advanced access
• Screens and rules, imported by path: @fayz-ai/auth/views/AuthGate, views/LoginPage, views/SetPasswordPage, views/usePasswordSetupGate, lib/runtime (createAuthRuntime), domain/auth-config (AuthPluginOptions, LoginAmbassador), domain/password. Terms in GLOSSARY.md.

Install

npm install @fayz-ai/auth

Peer dep: react (^18 or ^19). Built on @fayz-ai/core.

Usage

import { AuthProvider, useAuth, createSupabaseAuthAdapter } from '@fayz-ai/auth'

const adapter = createSupabaseAuthAdapter({ url, anonKey })

function App() {
  return (
    <AuthProvider adapter={adapter}>
      <Dashboard />
    </AuthProvider>
  )
}

function Dashboard() {
  const { user } = useAuth()
  return <p>Hello, {user?.email}</p>
}

Part of the Fayz SDK

The auth seam between @fayz-ai/core and the multi-tenant @fayz-ai/admin layer.

Roadmap & contributing

Built and evolving in the open. See the Fayz SDK roadmap for current gaps, missing features, and good first issues.