@repo/auth - Perform

packages/auth holds the better-auth instance and everything it needs to tie an auth user to a studio. The behaviour is described on Authentication. This page is the map of the package.

Public exports

src/index.ts exports everything from auth.ts plus the config:

Export	Kind	Notes
`auth`	better-auth instance	`auth.handler(request)` for HTTP, `auth.api.*` for in-process calls such as `getSession` and `generateOpenAPISchema`.
`authConfig`	object	The flags from `config.ts`.
`updateSeatsInOrganizationSubscription(organizationId)`	function	Re-exported from `lib/organization.ts`.
`Session`	type	`typeof auth.$Infer.Session`
`ActiveOrganization`	type	Result of `auth.api.getFullOrganization`, non null
`Organization`	type	`typeof auth.$Infer.Organization`
`OrganizationMemberRole`	type	The role of a member of an active organization
`OrganizationInvitationStatus`	type
`OrganizationMetadata`	type	`Record<string, unknown> \| undefined`

core-api imports auth for AppContext and the in-process session verifier. @repo/api imports it for the handler and for getSession in procedures.

Files

packages/auth/src/
├── auth.ts                      the betterAuth({...}) call, hooks, plugins
├── config.ts                    feature flags
├── types.ts                     AuthConfig interface
├── lib/
│   ├── phone.ts                 phone normalization and matching
│   ├── phone-otp.ts             WhatsApp OTP send, phone to user resolution
│   ├── staff-account.ts         create an account from a team directory entry
│   ├── claim-staff-seats.ts     link coach rows and memberships on sign-in
│   ├── provision-coach.ts       signed call to /v1/internal/coaches
│   ├── organization.ts          legacy seat add-on sync
│   ├── studio-lifecycle.ts      archive studio, deactivate coaches, finish onboarding
│   ├── deletion-hooks.ts        before delete hooks for organization and user
│   └── helper.ts                isOrganizationAdmin
└── plugins/
    ├── invitation-only/         block sign-up without an invitation (when sign-up is off)
    └── two-factor-otp-lanes.ts  raise the 2FA challenge on OTP sign-ins too

`config.ts`

export const config = {
  enableSignup: true,
  enableMagicLink: true,
  enableSocialLogin: true,
  enablePasskeys: true,
  enablePasswordLogin: true,
  enableTwoFactor: true,
  sessionCookieMaxAge: 60 * 60 * 24 * 30,
  users: { enableOnboarding: true },
  organizations: {
    enable: true,
    hideOrganization: false,
    enableUsersToCreateOrganizations: true,
    requireOrganization: false,
    forbiddenOrganizationSlugs: [/* route names the web app owns */],
  },
} as const satisfies AuthConfig;

Only some flags are read on the server: sessionCookieMaxAge sets the session lifetime and enableSignup controls the invitation only plugin. The rest are read by the web app, which has the same config in its own repo.

`lib/phone.ts`

Pure functions, with tests beside them.

Function	Behaviour
`digitsOnly(value)`	Strips everything but digits.
`nationalCore(value)`	Digits without a leading country code of `972` or `234` and without leading zeros. Used to compare numbers written in different formats.
`toMsisdn(value)`	Digits with a country code and no plus sign. A number starting with `+` keeps its digits as written. A local number is given a country code by its shape: an 11 digit number starting with `0`, or a 10 digit number starting with 7, 8 or 9, gets `234`. Other local numbers get `972`.
`phoneMatchVariants(value)`	The forms a stored number might take (digits, core, with `0`, with each country code, last 9 and last 10 digits). Variants shorter than 6 digits are dropped.
`isValidLoginPhoneNumber(value)`	Core of at least 6 digits and at most 15 digits in total.

core-api has its own apps/core-api/src/lib/phone.ts with toMsisdn, normalizePhone and phoneKey for domain rows. The two files implement the same toMsisdn rules separately. A change to number handling has to be made in both.

`lib/phone-otp.ts`

Function	Purpose
`sendLoginOtpOverWhatsapp(phoneNumber, code)`	Sends the `registercode` template through SmartSend. Dev mode logs the code and sends nothing.
`findUserIdByPhoneNumber(phoneNumber)`	User with that MSISDN.
`linkPhoneNumberFromCoachRecord(phoneNumber)`	Finds an active coach row by phone, resolves or creates the account, links both ways. Returns null when the account already has a different number.
`resolveUserIdForLoginPhone(phoneNumber)`	The first of the two above that returns an id.

`lib/staff-account.ts`

Export	Purpose
`staffCoachSelect`	The Prisma `select` for the coach fields the provisioning needs.
`provisionStaffAccount(coach, msisdn?)`	Creates an auth user from a team directory entry. No password, email not verified.
`provisionStaffAccountForEmail(email)`	The email OTP lane’s entry: creates the account when the email belongs to a listed staff member. Returns the user id or null.

`lib/claim-staff-seats.ts`

claimStaffSeats(userId, email) runs in the session create hook. It links active coach rows that match the user or the email, makes sure a member row exists with the right role, and returns the organization the new session should open. Every failure is logged and swallowed. A broken claim must not block sign-in.

`lib/provision-coach.ts`

provisionCoach({ studioId, externalUserId, name, email, role }) signs and sends POST /v1/internal/coaches to CORE_API_URL. See the warning about its studioId on Authentication.

`lib/organization.ts`

updateSeatsInOrganizationSubscription(organizationId) looks for a purchase on a seat based price (seatBased: true, the legacy teamSeat add-on). If the organization has one, it sets its seats to the active coach count minus the 2 included seats, never below 1. For every other studio it returns without doing anything.

`lib/studio-lifecycle.ts`

Function	Purpose
`archiveStudioForOrganization(organizationId)`	Archives the studio behind an organization that is being deleted. Sets `deletedAt`, releases the organization id, parks the slug and quiesces everything that could still message trainees.
`deactivateCoachesForUser(userId)`	Closes the user’s coach rows in every studio. The rows stay for history.
`markOnboardingFinished(userId)`	Stamps `settings.onboarding.completedAt` on studios this user owns that the `/start` wizard bootstrapped, that are not stamped yet and that are still inside the wizard window. Returns how many were stamped.

These write domain tables directly through db. They used to be signed HTTP calls from the API to itself. Doing the write in process removed every way that call could silently fail.

`lib/deletion-hooks.ts`

beforeOrganizationDelete(organizationId) and beforeUserDelete(userId). Each cancels the relevant billed subscriptions first, then quiesces the domain side.

`lib/helper.ts`

isOrganizationAdmin(organization, user) is true when the user’s member role in the organization is owner or admin, or the user is a platform admin.

Plugins

Plugin	File	Effect
`invitationOnlyPlugin()`	`plugins/invitation-only/index.ts`	A `before` hook on `/sign-up/email`. When `enableSignup` is false it requires a pending invitation for the email and otherwise throws `BAD_REQUEST` with code `INVALID_INVITATION`.
`twoFactorWithOtpLanes()`	`plugins/two-factor-otp-lanes.ts`	Returns the stock `twoFactor()` plugin with each `after` hook’s matcher widened to `/phone-number/verify` and `/sign-in/email-otp`.

Tests

The package has tests beside the code: auth-deletion-hooks.test.ts, lib/claim-staff-seats.test.ts, lib/deletion-hooks.test.ts, lib/organization.test.ts, lib/phone.test.ts, lib/staff-account.test.ts, lib/studio-lifecycle.test.ts.

Changing the auth configuration

A new plugin or option goes in auth.ts. If it adds tables or columns, add the models to packages/database/prisma/schema.prisma under @@schema("auth") and write a migration in packages/db.
A new field on the user goes in user.additionalFields and in the User model.
Rebuild with pnpm --filter @repo/auth build. core-api loads the package from dist.
The web app has its own better-auth client configuration. A server side plugin usually needs its client counterpart there.

​Public exports

​Files

​config.ts

​lib/phone.ts

​lib/phone-otp.ts

​lib/staff-account.ts

​lib/claim-staff-seats.ts

​lib/provision-coach.ts

​lib/organization.ts

​lib/studio-lifecycle.ts

​lib/deletion-hooks.ts

​lib/helper.ts

​Plugins

​Tests

​Changing the auth configuration