# Kavach — Auth (kavach)

> Core authentication client for SvelteKit. Wraps platform adapters with a unified
> interface for sign-in, sign-out, and session management.

## IMPORTANT — Use the CLI

Never import from 'kavach' directly in hooks.server.js or hand-write kavach.config.js.

    npx kavach init          # scaffolds everything correctly
    npx kavach doctor --fix  # repairs existing broken setups

## Install

    npm install kavach @kavach/vite
    npm install @kavach/adapter-supabase  # choose your adapter — required

## Setup

Run `npx kavach init` — it handles all steps automatically.

If you must set up manually (run `kavach doctor` to verify afterwards):

### 1. kavach.config.js

    export default {
      adapter: 'supabase',
      providers: [
        { name: 'google', label: 'Continue with Google' },
        { name: 'magic', mode: 'otp', label: 'Magic Link' },
        { name: 'email', mode: 'password', label: 'Email' }
      ],
      rules: [
        { path: '/auth', public: true },
        { path: '/', public: true },
        { path: '/dashboard', protected: true },
        { path: '/admin', roles: ['admin'] }
      ],
      env: {
        url: 'PUBLIC_SUPABASE_URL',
        anonKey: 'PUBLIC_SUPABASE_ANON_KEY'
      }
    }

### 2. vite.config.js — kavach() must come before sveltekit()

    import { kavach } from '@kavach/vite'
    import { sveltekit } from '@sveltejs/kit/vite'
    import { defineConfig } from 'vite'

    export default defineConfig({
      plugins: [kavach(), sveltekit()]
    })

### 3. hooks.server.js

    import { kavach } from '$kavach/auth'
    export const handle = kavach.handle

### 4. +layout.server.js

    export function load({ locals }) {
      return { session: locals.session }
    }

## Anti-Patterns

    // No default export — will fail
    import kavach from 'kavach'

    // Do not call createKavach in hooks.server — $kavach/auth already has a configured instance
    import { createKavach } from 'kavach'
    export const handle = createKavach(adapter).handle

    // Do not alias the kavach package
    resolve: { alias: { kavach: '/path/to/src/index.ts' } }

    // Not needed when using $kavach/auth virtual module
    ssr: { noExternal: ['kavach'] }

    // Correct
    import { kavach } from '$kavach/auth'
    export const handle = kavach.handle

## Client-Side Setup

In root layout onMount (browser only):

    // src/routes/+layout.svelte
    import { setContext, onMount } from 'svelte'
    import { page } from '$app/stores'

    const kavach = $state({})
    setContext('kavach', kavach)

    onMount(async () => {
      const { createKavach } = await import('kavach')
      const { adapter, logger } = await import('$kavach/auth')
      const { invalidateAll } = await import('$app/navigation')
      const instance = createKavach(adapter, { logger, invalidateAll })
      Object.assign(kavach, instance)
      instance.onAuthChange($page.url)
    })

## API

### createKavach(adapter, options)

Creates a browser-side kavach instance.

    const instance = createKavach(adapter, {
      logger?,       // from $kavach/auth
      invalidateAll? // from $app/navigation
    })

Returns: { signIn, signOut, onAuthChange, handle, getCachedLogins, ... }

### kavach.signIn(credentials)

    await kavach.signIn({ provider: 'google' })
    await kavach.signIn({ provider: 'email', email, password })
    await kavach.signIn({ provider: 'magic', email })

### kavach.signOut()

    await kavach.signOut()

## Virtual Module: $kavach/auth

Generated by @kavach/vite from kavach.config.js. Exports:

- `kavach` — pre-configured server-side instance with .handle hook
- `adapter` — instantiated adapter
- `logger` — configured logger instance

## Session

Kavach sets `event.locals.session` on every request via kavach.handle.

    // src/routes/+layout.server.js
    export function load({ locals }) {
      return { session: locals.session }
    }

    // guard individual routes
    export function load({ locals }) {
      if (!locals.session) redirect(303, '/auth')
      return { user: locals.session.user }
    }

Session shape:

    {
      user: { id: string, email: string, role: string },
      access_token: string,
      refresh_token: string,
      expires_in: number
    }

## Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| ERR_RESOLVE_PACKAGE_ENTRY_FAIL | Direct kavach import or resolve.alias in hooks | Use $kavach/auth virtual module |
| kavach is undefined | Default import from kavach | No default export; use $kavach/auth |
| kavach.handle is not a function | Old manual setup | Run kavach doctor --fix |
| Hook not running | kavach() plugin missing from vite.config | Run kavach doctor --fix |

Run `npx kavach doctor` to diagnose any setup issue.

## Related

- [CLI](./cli.txt) — kavach init, doctor, add
- [Sentry](./sentry.txt) — standalone route protection engine
- [UI](./ui.txt) — pre-built sign-in components
- [Vite Plugin](./vite.txt) — virtual module generation