@fladeed/auth

Sign-in shared by Fladeed's internal apps (HandOff, the apps portal, the review queue, the CRM): one Supabase user pool, one session cookie on .fladeed.com, and per-app access from the apps and app_access tables. Sign in on any app and you are signed in on all of them; sign out and it is sign-out everywhere.

Use in an app

// lib/supabase/client.ts
import { createFladeedClient } from "@fladeed/auth";
import type { Database } from "@/lib/supabase/database.types";

export const supabase = createFladeedClient<Database>(process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!);

// app/layout.tsx
<SessionProvider client={supabase} onError={(code) => toast.error(t(`auth.${code}`))}>{children}</SessionProvider>

// a page
<RequireAccess app="reviews">…</RequireAccess>
<RequireAccess app="handoff" roles={["admin"]} loginUrl="/login">…</RequireAccess>   // the portal has its own login page

// the login page (the portal; other apps redirect there)
const login = useLogin(supabase, { next: searchParams.get("next") });
<form onSubmit={login.submit}>…</form>   // login.error is "invalid_credentials" | "unknown" | null, translate it

useSession() gives session, profile (id, name, email, active, GitHub login), access (the person's rows), isPlatformAdmin, roleIn(app), canOpen(app, roles?), mfa (currentLevel, nextLevel, enrolled), mfaPolicy(app), signOut(), reload() and refreshMfa().

How the session is shared

createFladeedClient builds the Supabase browser client from @supabase/ssr with the session cookie on .fladeed.com whenever the page runs on a *.fladeed.com host. On localhost, a LAN address or a preview host the cookie stays on that host, so local development behaves as before (and a local Supabase is reached on the page's host from another device). The cookie name derives from the project URL, so every app on the same project reads the same cookie.

RequireAccess sends a visitor without a session to https://apps.fladeed.com/login?next=<current page>; useLogin sends them back once signed in. next is only honoured for a path on the current origin or an https page of a *.fladeed.com host (safeNextUrl).

Two-factor authentication

Supabase marks a session aal1 after the password and aal2 once a code from an authenticator app (TOTP) was entered in that session. Each app carries a policy in apps.mfa: off (never asked), if_enrolled (people who have an authenticator are asked once per session, people without are not) or required (someone without an authenticator is sent to enrol). RequireAccess reads the app's policy with the access rows and decides (decideMfa, pure):

<RequireAccess app="reviews">…</RequireAccess>                       // the policy of apps.mfa
<RequireAccess app="platform" roles={["admin"]} mfa="required">…</RequireAccess>   // a prop overrides it
<RequireAccess app="handoff" portalUrl="http://localhost:3002">…</RequireAccess>  // development: the portal runs elsewhere

The enrol and verify pages live on the portal (/account/security?enroll=1&next=… and /login/verify?next=…, enrollUrlFor / verifyUrlFor); the other apps redirect there and come back through next. useLogin does the same after the password when the person has an authenticator. The session cookie is per host in development, so the cross-app redirect only works in production; test the flows on the portal itself locally, with [auth.mfa.totp] on in supabase/config.toml.

// /account/security
const enroll = useMfaEnroll(supabase);
await enroll.start("Phone");        // enroll.qrCode (svg), enroll.secret
await enroll.confirm(code);         // true → confirmed, session is aal2; refreshMfa() after an unenroll

// /login/verify
const verify = useMfaVerify(supabase);
if (verify.ready && !verify.factorId) …  // nobody to challenge: ask a platform admin to reset
if (await verify.verify(code)) window.location.assign(safeNextUrl(next, window.location.origin));

Errors are short codes (MfaErrorCode: invalid_code, code_expired, too_many_factors, name_taken, no_factor, rate_limited, mfa_unavailable, unknown) for the app to translate. A lost authenticator is removed by a platform admin on an aal2 session through the admin function's reset_mfa, which also signs the person out everywhere.

Publishing

Public package on npm, published by hand from a Platform checkout after a merge to main:

npm login                                   # once per machine
cd packages/auth && npm version patch       # or minor / major; commits the bump in its own PR
npm run build && npm publish                # access public from publishConfig

Each app then bumps its dependency in its own PR.