npm package: @kyro-cms/admin
Description: Admin dashboard for Kyro CMS
Latest version: 0.1.6

# @kyro-cms/admin

Admin dashboard for Kyro CMS — a React-based admin interface built with Astro.

## Features

- **Authentication** — JWT-based login/logout with SQLite auth backend
- **Collection Management** — Create, edit, and manage content collections
- **User Management** — Manage users, roles, and permissions
- **Settings** — Configure CMS settings, globals, and plugins
- **Responsive** — Mobile-friendly dashboard with Tailwind CSS

## Quick Start

### Prerequisites

- Node.js 18+
- A Kyro CMS project with `@kyro-cms/core` installed

### Development

```bash
# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type check
npm run check
```

### Integration with Kyro CMS

The admin dashboard is designed to work alongside a Kyro CMS project. In your Astro project:

1. Install the admin package:

   ```bash
   npm install @kyro-cms/admin
   ```

2. Create an admin page at `src/pages/admin/index.astro`:

   ```astro
   ---
   import { Admin } from '@kyro-cms/admin';
   import config from '../../../kyro.config';
   ---
   <!DOCTYPE html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Admin - My Kyro CMS</title>
     </head>
     <body>
       <Admin client:load config={config} />
     </body>
   </html>
   ```

3. Configure your `astro.config.mjs` with the Node adapter:

   ```js
   import { defineConfig } from "astro/config";
   import node from "@astrojs/node";

   export default defineConfig({
     output: "server",
     adapter: node({ mode: "standalone" }),
   });
   ```

## Authentication

The admin uses SQLite for auth by default (stored at `./data/auth.db`). No Redis or external services required.

### Creating Your First Admin User

1. Start the dev server: `npm run dev`
2. Visit `http://localhost:4321/admin`
3. Register with your email and password
4. The first user automatically gets the `super_admin` role

### Environment Variables

| Variable                  | Description                                | Default                   |
| ------------------------- | ------------------------------------------ | ------------------------- |
| `JWT_SECRET`              | Secret for signing JWT tokens              | `change-me-in-production` |
| `JWT_EXPIRES_IN`          | Token expiration time                      | `24h`                     |
| `KYRO_AUTH_DB_PATH`       | Path to auth SQLite database               | `./data/auth.db`          |
| `KYRO_ALLOW_REGISTRATION` | Allow public registration after first user | `true`                    |

### Auth API Endpoints

| Endpoint             | Method | Description                  |
| -------------------- | ------ | ---------------------------- |
| `/api/auth/login`    | POST   | Authenticate user            |
| `/api/auth/register` | POST   | Register new user            |
| `/api/auth/logout`   | POST   | Invalidate session           |
| `/api/auth/me`       | GET    | Get current user info        |
| `/api/auth/users`    | GET    | List all users (admin only)  |
| `/api/auth/users`    | POST   | Create new user (admin only) |

## Project Structure

```
admin/
├── src/
│   ├── components/     # React UI components
│   ├── pages/          # Astro pages + API routes
│   │   └── api/        # REST API endpoints
│   │       └── auth/   # Authentication endpoints
│   ├── collections/    # Auth collection config
│   └── middleware.ts   # Auth middleware
├── public/             # Static assets
└── astro.config.mjs    # Astro configuration
```

## Security

- **Password Hashing** — bcryptjs with 12 salt rounds
- **JWT Tokens** — Signed tokens with configurable expiration
- **Session Management** — Server-side session tracking via SQLite
- **Middleware Protection** — All non-auth routes require valid JWT
- **Password Policy** — Minimum 12 characters with complexity requirements

## Scalability

### Default Setup (Single Instance)

SQLite auth adapter handles everything in a single `./data/auth.db` file. Perfect for:

- Development
- Small to medium projects
- Single-server deployments

### Multi-Instance / Horizontal Scaling

When running multiple Kyro CMS instances behind a load balancer, configure:

```bash
# Shared auth database path (mounted volume, NFS, etc.)
KYRO_AUTH_DB_PATH=/shared/data/auth.db

# Enable write-ahead logging for concurrent access
# (automatically enabled by SQLiteAuthAdapter)
```

### High-Scale Production

For high-traffic deployments with many concurrent users:

1. **Connection Pooling** — SQLite handles concurrent reads well, but writes are serialized. For write-heavy workloads, consider PostgreSQL with the Drizzle auth adapter.

2. **Session Caching** — JWT tokens are self-contained, so session validation doesn't require database reads on every request.

3. **Rate Limiting** — Currently in-memory per instance. For distributed rate limiting, use Redis or a shared SQLite file on fast storage.

4. **Audit Logs** — Stored in SQLite. For high-volume audit logging, consider exporting to a dedicated log store.

## License

MIT