# @izri/auth

> Authentication package powered by Better Auth

## Overview

Authentication is implemented with Better Auth using the Drizzle adapter and the shared environment loader. It provides session management, email+password, and GitHub OAuth. IDs for auth tables are generated as ULIDs.

## Package Structure

```
packages/auth/
├── src/
│   ├── index.ts          # Auth exports
│   ├── better-auth.ts    # Better Auth configuration
│   └── utils.ts          # (optional) helpers
└── package.json
```

## Configuration (better-auth.ts)

Key configuration highlights:

- Uses env from @izri/shared (not process.env)
- ULID for ID generation: advanced.generateId = ulid()
- Drizzle adapter with PostgreSQL and schema tables from @izri/database
- Session tuning and cookie cache
- Trusted origins for CSRF protection
- GitHub OAuth provider

```ts
import { accounts, db, sessions, users, verifications } from '@izri/database'
import { env } from '@izri/shared'
import { betterAuth } from 'better-auth'
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { ulid } from 'ulid'

export const auth = betterAuth({
  advanced: {
    generateId: () => ulid(),
    disableErrorMessages: env.IS_PRODUCTION,
  },
  database: drizzleAdapter(db, {
    provider: 'pg',
    schema: { account: accounts, session: sessions, user: users, verification: verifications },
  }),
  emailAndPassword: { enabled: true },
  secret: env.BETTER_AUTH_SECRET,
  baseURL: env.API_URL,
  session: {
    cookieCache: { enabled: true, maxAge: 60 * 5 },
    expiresIn: 60 * 60 * 24 * 7,
    updateAge: 60 * 60 * 24,
  },
  socialProviders: {
    github: { clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET },
  },
  trustedOrigins: [env.API_URL, env.APP_URL],
})
```

## Post-signup initialization

After signup, the tRPC auth router exposes initializeNewUser to create a default organization for the user. Call it client-side after successful signup:

```ts
await trpc.auth.initializeNewUser.mutate({ userId, userEmail })
```

This will:
- Create a personal organization with a generated slug
- Add the user as OWNER

## Environment

Use @izri/shared env in all examples:

```ts
import { env } from '@izri/shared'
console.log(env.API_URL, env.APP_URL)
```

## Notes

- API token functionality is temporarily removed during Better Auth migration. See docs/features/api-keys.md for current status and future plan.
- **All tables** (both auth and application) use ULID for IDs. See `@izri/database` package documentation for complete ID strategy details.

## Related

- ../backend/authentication.md
- ../backend/authentication-security.md