# auth Specification

## Purpose
Buyer registration, sign-in and current-user lookup backed by the API's JWT auth.
## Requirements
### Requirement: Customer registration
The API SHALL provide `POST /api/auth/register` accepting email, password, display_name. New users are created with role `customer`. Duplicate emails MUST be rejected with 409.

#### Scenario: successful registration
- **WHEN** a client posts a unique email with password ≥ 8 chars
- **THEN** the API returns 201 with `{ token, user }` and the user can call `/api/auth/me` with the token

#### Scenario: duplicate email
- **WHEN** the email already exists
- **THEN** the API returns 409 with code `CONFLICT`

### Requirement: Login
The API SHALL provide `POST /api/auth/login` issuing a signed JWT (24h TTL) containing user id and role.

#### Scenario: valid credentials
- **WHEN** email + correct password are posted
- **THEN** the API returns `{ token, user }`

#### Scenario: invalid credentials
- **WHEN** the password is wrong or email unknown
- **THEN** the API returns 401 with code `UNAUTHORIZED` and no token

### Requirement: Current user
`GET /api/auth/me` SHALL return the authenticated user profile.

#### Scenario: missing token
- **WHEN** no Bearer token is supplied
- **THEN** the API returns 401