# Research: Authentication (SP-01)

**Feature**: Admin authentication with Bearer tokens
**Completed**: 2026-06-01

---

## Research 1: Laravel Sanctum Token Storage

**Question**: How does Sanctum store and hash tokens?

**Finding**:
- Sanctum uses `personal_access_tokens` table
- Tokens are hashed using SHA-256 hash before storage (not plaintext)
- When authenticating, the provided token is hashed and compared against stored hash
- This satisfies Constitution requirement: "Token storage MUST be hashed — plain text tokens are prohibited"

**Source**: Laravel Sanctum documentation — "Token Storage"

---

## Research 2: Laravel Sanctum Rate Limiting

**Question**: How to implement rate limiting on login endpoint only?

**Finding**:
- Use Laravel's built-in `throttle:5,1` middleware (5 attempts per minute)
- Apply directly to the login route in routes/api.php
- Other auth routes (logout, me) use `auth:sanctum` but no throttle
- This satisfies Constitution: "Rate Limiting on /login (5 attempts/minute)"

**Source**: Laravel documentation — "Rate Limiting"

---

## Research 3: Single Admin with Pre-Seeded Account

**Question**: How to seed admin without hardcoding credentials?

**Finding**:
- Use `.env` variables: ADMIN_NAME, ADMIN_EMAIL, ADMIN_PASSWORD
- In seeder, read via `env('ADMIN_EMAIL')` etc.
- Check if admin exists by email before creating (idempotent)
- Password hashed using bcrypt via `Hash::make()`

**Source**: Laravel documentation — "Database Seeding"

---

## Research 4: Sanctum API Token Abilities

**Question**: Should we use abilities/permissions with Sanctum tokens?

**Finding**:
- For this project, single-admin means all abilities are implicitly granted
- No need for ability checks on tokens — they simply prove identity
- Each token has `abilities` column but we don't need to enforce specific abilities
- The auth layer just needs to verify the token is valid (identity confirmation)

**Source**: Laravel Sanctum documentation — "Token Abilities"

---

## Research 5: Laravel FormRequest Validation

**Question**: How to properly validate login request?

**Finding**:
- Create `LoginRequest` extending `Illuminate\Foundation\Http\FormRequest`
- Rules: `['email' => 'required|email', 'password' => 'required|string']`
- Override `failedValidation()` to return Unified Response format (422)
- Controller receives validated data via `$loginRequest->validated()`

**Source**: Laravel documentation — "Form Request Validation"

---

## Summary

All technical decisions align with Constitution requirements:
- ✅ Laravel Sanctum (Constitution Section 5)
- ✅ Token storage hashed (Sanctum default behavior)
- ✅ Rate limiting on /login (5/min) via throttle middleware
- ✅ FormRequest validation
- ✅ No business logic in Controller
- ✅ Unified API response format

No further research needed. Ready for Phase 1 design.