# Getting Started

> Install kyzen and wire it into your Koze middleware

Package: Kyzen
Canonical: https://kuratchi.dev/docs/kyzen/getting-started
Markdown: https://kuratchi.dev/docs/kyzen/getting-started.md

## What this is

`kyzen` is the Koze quickstart auth library. It gets you to "users can sign in" fast - credentials, magic links, sessions, role-based permissions, rate limiting, CSRF/origin checks, OAuth, Turnstile bot protection - driven by a single config object that you pass to a middleware factory.

It's a **starter, not a standard.** The framework has no built-in auth; `kyzen` plugs in via ordinary middleware, the same shape any other auth library would use. If you outgrow it (federated identity, complex authorization graphs, custom session backends), swap it out - nothing else in your app cares.

## Install

```bash
npm install @kuratchi/kyzen @kuratchi/kunii
```

`kyzen` depends on ORM-backed tables for users, sessions, magic-link tokens, OAuth accounts, activity logs, and related auth state.

## Minimal setup

Auth is wired through middleware. For Koze, the primary adapter is `kyzen/koze`. Keep the config in its own module so it's easy to find and easy to test, then import it into `src/middleware.ts`.

```ts
// src/server/auth-config.ts
import { kyzenAuthConfig } from '@kuratchi/kyzen/adapter';

export const authConfig = kyzenAuthConfig({
  cookieName: 'kuratchi_session',
  sessionEnabled: true,
  credentials: { binding: 'DB' },
  csrf: {
    paths: ['/auth/*'],
  },
  guards: {
    paths: ['/admin/*'],
    redirectTo: '/auth/login',
  },
});
```

```ts
// src/middleware.ts
import { defineMiddleware } from '@kuratchi/koze';
import { initKyzenAuth } from '@kuratchi/kyzen/koze';
import { authConfig } from '$server/auth-config';

const auth = initKyzenAuth(authConfig);

export default defineMiddleware({
  auth: auth.middleware(),
});
```

That is the primary integration point. `kyzen/middleware` remains available as the lower-level compatibility path, but `kyzen/koze` is the first-class adapter for framework apps.

## Adapter defaults

`kyzenAuthConfig({...})` is an optional helper that fills in sensible defaults. You can pass a plain object to `auth.middleware()` or `kyzenAuthMiddleware()` directly; the adapter just adds:

- `cookieName`: `kuratchi_session`
- `secretEnvKey`: `AUTH_SECRET`
- `sessionEnabled`: `true`

## Common imports

Once the middleware is wired, the auth helpers become available in any route, action, or `$server/*` module:

```ts
import {
  signUp,
  signIn,
  signOut,
  getCurrentUser,
  getAuth,
  requestMagicLink,
  consumeMagicLink,
  requestPasswordReset,
  resetPassword,
  verifyEmail,
  resendEmailVerification,
  inviteMember,
  acceptInvite,
  logActivity,
  hasRole,
  hasPermission,
  startOAuth,
  handleOAuthCallback,
  requireAuthGuard,
  verifyTurnstile,
} from '@kuratchi/kyzen';
```

All of these read from request-scoped locals populated by auth middleware. Call them from route handlers, actions, RPC functions - the auth context is available wherever the framework runs request code.

## Single-tenant vs multi-tenant

`kyzen` supports two modes:

| Mode | When | Storage |
| --- | --- | --- |
| Single-tenant | One shared user pool. No organizations. | All auth tables on the admin D1 binding. |
| **Org-mode** | Per-organization isolation. Each org gets its own SQLite-backed Durable Object. | Admin D1 stores `organizations` + `organizationUsers` + verification tokens; users + sessions live inside each org's DO. |

Org-mode is the more interesting case (and the one the framework's reference app, `apps/web`, runs in). Switch it on with the `organizations` config block - see [Organizations and Schema](/docs/kyzen/organizations-and-schema).

## Required env

At minimum, auth flows expect:

- `AUTH_SECRET`

Feature-specific flows can also require:

- `RESEND_API_KEY`
- `EMAIL_FROM`
- `GITHUB_CLIENT_ID`
- `GITHUB_CLIENT_SECRET`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `TURNSTILE_SECRET`
- `TURNSTILE_SITE_KEY`
- `ORIGIN`

Set these via Cloudflare secrets (`wrangler secret put`) or `.dev.vars` for local development.

## What to read next

- [Credentials and Sessions](/docs/kyzen/credentials-and-sessions)
- [Magic Links](/docs/kyzen/magic-links)
- [Auth Context](/docs/kyzen/auth-context)
- [OAuth and RBAC](/docs/kyzen/oauth-and-rbac)
- [Guards, CSRF, Rate Limits, and Turnstile](/docs/kyzen/guards-rate-limit-turnstile)
- [Organizations and Schema](/docs/kyzen/organizations-and-schema)
- `send_email` Worker binding (when using built-in magic-link delivery on Cloudflare Workers)