spomeni/docs/adminImplem.md

# SuperAdmin & Admin + Code Access System — Implementation Plan

> ## ⚠ Historical implementation plan — see `docs/admin.md` for current state
>
> This was the original plan doc. Several specifics differ from the
> actual implementation (`src/lib/admin-session.ts`,
> `src/app/api/admin/*`, `src/app/admin/**`):
>
> - Cookie **path**: planned as `/admin`; shipped as `/` (so admin
>   API routes under `/api/admin/*` receive the cookie).
> - **Super-admin credentials**: planned as hardcoded `super`/`admin`;
>   shipped from env (`SUPER_ADMIN_USERNAME` + `SUPER_ADMIN_PASSWORD_HASH`,
>   bcrypt) — see `docs/admin.md`.
> - **Super-admin row in `AdminUser`**: planned as optional seed;
>   required by the `Code.createdById` FK and provisioned by
>   `prisma/seed.ts`.
> - **Rate limiting, CSRF/Origin checks, password complexity, atomic
>   code claim** (updateMany guard): all added in Phases 1–6 and not
>   in the original plan.
> - All admin API routes now funnel through `requireAdmin` /
>   `requireAdminPost` / `requireSuperAdminPost` in
>   `src/lib/admin-session.ts`; the rolling-helpers in
>   `admin-session.ts` supersede the inline `getAdminSession()` checks
>   described per-route in this top-of-the-doc walkthrough.

## Overview

Implement SuperAdmin/admin role management and code-gated memorial creation as outlined in `admin.md`.

- SuperAdmin: hardcoded username `super`, password `admin`
- SuperAdmin creates admin accounts
- Admins generate access codes
- Users must enter a valid code during onboarding to create memories

---

## Phase 1 — Database & Dependencies

### New Prisma Models (`prisma/schema.prisma`)

```prisma
enum Role {
  SUPER_ADMIN
  ADMIN
}

model AdminUser {
  id           String   @id @default(cuid())
  username     String   @unique
  passwordHash String
  role         Role     @default(ADMIN)
  createdAt    DateTime @default(now())
  createdCodes Code[]
}

model Code {
  id           String    @id @default(cuid())
  code         String    @unique
  createdById  String
  createdBy    AdminUser @relation(fields: [createdById], references: [id])
  usedByUserId String?                            // User.clerkId
  usedAt       DateTime?
  createdAt    DateTime  @default(now())
  expiresAt    DateTime?

  @@index([code])
  @@index([usedByUserId])
}
```

### New Dependencies

- `bcryptjs` + `@types/bcryptjs` — hash admin passwords

### Seed SuperAdmin

Seed script or migration that creates the SuperAdmin `AdminUser` record with hashed password. However, the login itself checks hardcoded `super`/`admin` first (and also queries DB by role for token auth), so the seed is optional — used mainly for listing in the admin panel.

### Migration

`npx prisma migrate dev --name add_admin_and_code`

---

## Phase 2 — Admin Auth

Admin auth is separate from Clerk. Uses a signed HMAC cookie.

### `src/lib/admin-session.ts` (new)

Helpers:

- `createAdminSession(username: string, role: Role): string` — sign a cookie value with HMAC-SHA256 using `ADMIN_SESSION_SECRET` env var
- `verifyAdminSession(token: string): { username: string; role: Role } | null` — verify and decode
- `getAdminSession(): { username: string; role: Role } | null` — read from `request.cookies` or `cookies()`
- Cookie name: `admin_session`

Payload: `{ username, role, iat }` serialized + HMAC signature.

### `src/app/api/admin/login/route.ts` (new)

- POST: accept `{ username, password }`
- If `username === "super"` and `password === "admin"` → set session with role `SUPER_ADMIN`
- Else query `AdminUser` where `username === username`, compare with `bcrypt.compare`
- Return `{ success: true }` and set `admin_session` cookie (httpOnly, secure, sameSite=lax, path=/admin)
- On failure: `401`

### `src/app/api/admin/logout/route.ts` (new)

- POST: clear `admin_session` cookie

### `src/app/api/admin/change-password/route.ts` (new)

- POST: accept `{ currentPassword, newPassword }`
- Verify admin session, then verify current password against DB
- Hash new password, update `AdminUser` record

### `src/app/admin/login/page.tsx` (new)

- Macedonian UI: username/password form
- On submit → `POST /api/admin/login`
- On success → redirect to `/admin/dashboard`
- Show error on failure

### `src/middleware.ts` (modify)

- Add `/admin(.*)` and `/api/admin(.*)` to the Clerk exclude list
- Before Clerk middleware runs: if path starts with `/admin`, check admin session cookie
  - No/invalid cookie → redirect to `/admin/login`
  - Valid → allow
- If path starts with `/api/admin`, check admin session cookie
  - No/invalid cookie → return `401`

---

## Phase 3 — Admin Panel

All UI in Macedonian. Layout with sidebar navigation.

### `src/app/admin/layout.tsx` (new)

- Checks admin session (server component)
- Redirects to `/admin/login` if not authenticated
- Provides sidebar with links: Dashboard, Users (SuperAdmin only), Codes
- Logout button

### `src/app/admin/dashboard/page.tsx` (new)

- Stats cards:
  - Total AdminUsers count
  - Total Codes generated
  - Codes used vs unused
- Simple overview

### `src/app/admin/users/page.tsx` (new)

- Accessible only to `SUPER_ADMIN`
- Table of admin users (username, role, created at)
- Button to create new admin (modal/page with username + password fields)
- Button to delete admin (with confirmation)
- Inline password reset option

### `src/app/admin/users/create/page.tsx` or modal (new)

- Form: username, password (with confirmation)
- POST to `/api/admin/users/`

### `src/app/admin/codes/page.tsx` (new)

- "Generate Code" button → POST `/api/admin/codes` → returns new code string, displays it
- Table of all codes: code value, who created it, status (used/unused), used by, used at
- Admin can see their own codes. SuperAdmin sees all.
- Delete code button

### `src/app/api/admin/users/route.ts` (new)

- GET: list all `AdminUser` (SuperAdmin only)
- POST: create `AdminUser` with hashed password (SuperAdmin only)

### `src/app/api/admin/users/[id]/route.ts` (new)

- DELETE: remove `AdminUser` (SuperAdmin only)
- PUT: reset password (SuperAdmin only)

### `src/app/api/admin/codes/route.ts` (new)

- GET: list codes (Admins see their own, SuperAdmin sees all)
- POST: generate a new code (`crypto.randomBytes(6).toString('hex').toUpperCase()` → 12 chars), store with `createdById` from session

### `src/app/api/admin/codes/[id]/route.ts` (new)

- DELETE: remove unused code

---

## Phase 4 — Code Gating

### `src/app/api/validate-code/route.ts` (new)

- Requires Clerk auth (`auth()` from `@clerk/nextjs/server`)
- POST: `{ code: string }`
- Look up `Code` where `code === code` and `usedByUserId === null`
- If not found → `{ valid: false, error: "Невалиден или веќе искористен код" }`
- If found → update `usedByUserId = userId`, `usedAt = now()`
- Return `{ valid: true }`

### `src/app/onboarding/page.tsx` (modify)

- Add `"Код"` as step 0 (before "Податоци")
- STEPS becomes: `["Код", "Податоци", "Датуми", "Фотографии", "Поддомен", "Шаблон"]`
- Step 0: single input for code + "Потврди" button
  - Calls `POST /api/validate-code`
  - On success → shows green checkmark, enables "Продолжи"
  - On failure → shows error, blocks progression
- Once validated, user can proceed to step 1
- `canProceed()` for step 0 returns true only if code validated successfully

### `src/app/api/publish/route.ts` (modify)

- After Clerk auth check, query: `prisma.code.findFirst({ where: { usedByUserId: userId } })`
- If no code found → return `403` with `"Потребен е валиден код за креирање спомен страница"`

---

## Phase 5 — Environment & Build

### New Env Variable

```
ADMIN_SESSION_SECRET=<random-64-char-string>
```

Add to `.env.example` and `docker-compose` files.

### Build & Verify

```bash
npm install bcryptjs
npm install -D @types/bcryptjs
npx prisma migrate dev --name add_admin_and_code
npm run build
```

Verify:
- [ ] Admin login at `/admin/login` with `super`/`admin`
- [ ] Create admin user from admin panel
- [ ] Login as created admin
- [ ] Generate code from admin panel
- [ ] Sign up as new user via Clerk
- [ ] Enter code in onboarding step 0
- [ ] Proceed through onboarding and publish
- [ ] Verify publish fails without valid code

---

## File Change Summary

### New Files
| Path | Purpose |
|------|---------|
| `src/lib/admin-session.ts` | HMAC cookie helpers |
| `src/app/admin/login/page.tsx` | Admin login form |
| `src/app/admin/layout.tsx` | Admin layout with sidebar |
| `src/app/admin/dashboard/page.tsx` | Dashboard stats |
| `src/app/admin/users/page.tsx` | Admin user management |
| `src/app/admin/codes/page.tsx` | Code generation & listing |
| `src/app/api/admin/login/route.ts` | Admin login API |
| `src/app/api/admin/logout/route.ts` | Admin logout API |
| `src/app/api/admin/change-password/route.ts` | Self-service password change |
| `src/app/api/admin/users/route.ts` | List/create admin users |
| `src/app/api/admin/users/[id]/route.ts` | Delete/reset-password admin user |
| `src/app/api/admin/codes/route.ts` | List/create codes |
| `src/app/api/admin/codes/[id]/route.ts` | Delete code |
| `src/app/api/validate-code/route.ts` | Public code validation |

### Modified Files
| Path | Change |
|------|--------|
| `prisma/schema.prisma` | Add `AdminUser` and `Code` models |
| `src/middleware.ts` | Exclude `/admin/*` from Clerk, add admin session check |
| `src/app/onboarding/page.tsx` | Add code step (step 0) |
| `src/app/api/publish/route.ts` | Add code usage check before publish |