Auth

@halostack/auth is the authentication layer for the monorepo, built on top of better-auth. It provides email/password sessions, multi-tenant organizations, and an admin role layer. Authentication is owned by the API: the auth handler is mounted by @halostack/elysia, and the web app talks to it through the browser client this package exposes.

Importing

The package has two entry points — one for the server, one for the browser:

Because the client exposes React hooks, react is declared as a peer dependency here rather than a direct one — don't bundle React into this package.

Structure

The package keeps its configuration in one place and exposes thin server and client entrypoints around it.

• src/options.ts — the better-auth configuration, including the organization and admin plugins and the email hooks wired to @halostack/notifications/email.
• src/server.ts and src/client.ts — the server and client entrypoints, respectively.
• src/auth.cli.ts — configuration consumed only by the schema-generation CLI.

Schema codegen

better-auth needs its own database tables, but rather than living in this package they're generated directly into @halostack/db. Run the generator whenever you change the plugins or fields in options.ts:

Copybun run --filter @halostack/auth auth:generate   # → packages/db/src/schema/auth.ts

After regenerating, create and apply a database migration to bring the schema up to date. The generated file at packages/db/src/schema/auth.ts should never be hand-edited.

Conventions

All configuration and secrets flow through @halostack/env. And in keeping with the repo-wide strict-TypeScript rules, never reach for as any to work around better-auth's inferred session, user, or role types — narrow them properly instead.