pw-generator/README.md

# Password Generator API and Web App

A modern, secure password generator with a public REST API and multilingual web UI.
The project is built with Slim PHP and focuses on production-ready password generation.

## Features

### Password Generators

- High Entropy: cryptographically secure random passwords with configurable character sets.
- XKCD Passphrase: memorable multi-word passphrases with language-specific wordlists.
- Diceware: dice-style passphrases with security metadata.
- PWGen Enhanced: pronounceable passwords with optional separator logic.
- Passkey: Apple-style pronounceable strings using syllable patterns.

### Product Capabilities

- Public JSON API for password generation.
- Responsive browser UI.
- Localization support with runtime locale endpoint.
- Security controls (rate limiting, CORS, secure random generation).
- Generated OpenAPI contract.

## Supported Languages

- en
- de
- de_CH
- fr
- it
- es
- pt
- ja
- zh

## Requirements

- PHP 8.1+
- Composer
- Optional CLI tools for enhanced generator behavior: pwgen, xkcdpass

## Quick Start

### 1. Install

```bash
git clone <repository-url>
cd password-generator
composer install
```

### 2. Configure

```bash
cp .env.example .env
cp config/config.example.json config/config.json
mkdir -p logs
chmod 755 logs
```

### 3. Run

```bash
composer start
# or
php -S localhost:8080 -t public
```

Open:

- [http://localhost:8080](http://localhost:8080)
- [http://localhost:8080/docs](http://localhost:8080/docs)

## API Usage

### List available generator types

```bash
curl http://localhost:8080/api/v1/passwords
```

### Generate passwords

```bash
curl -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"diceware","count":2,"options":{"words":6}}'
```

### Get locale payload

```bash
curl http://localhost:8080/api/v1/locales/ja
```

## Generator Option Examples

### High Entropy

```json
{
  "type": "high-entropy",
  "count": 1,
  "options": {
    "length": 16,
    "include_lowercase": true,
    "include_uppercase": true,
    "include_numbers": true,
    "include_symbols": true,
    "safe_symbols_only": false,
    "exclude_ambiguous": false
  }
}
```

### XKCD Passphrase

```json
{
  "type": "xkcdpass",
  "count": 1,
  "options": {
    "words": 4,
    "wordlist": "en",
    "separator": "-",
    "max_word_length": 0,
    "space_handling": "allow",
    "add_number": true,
    "number_position": "end"
  }
}
```

### Diceware

```json
{
  "type": "diceware",
  "count": 1,
  "options": {
    "words": 6,
    "show_dice_rolls": true,
    "uppercase_first": false
  }
}
```

### PWGen Enhanced

```json
{
  "type": "pwgen",
  "count": 1,
  "options": {
    "length": 16,
    "separator": "-_",
    "include_numbers": true,
    "include_capitals": true,
    "secure_mode": false,
    "no_ambiguous": false
  }
}
```

### Passkey

```json
{
  "type": "passkey",
  "count": 1,
  "options": {
    "syllables": 6
  }
}
```

## Configuration Notes

Primary runtime configuration files:

- config/config.json
- .env

Useful environment overrides:

- LLM_DEFAULT_PROVIDER
- OPENAI_API_KEY
- CLAUDE_API_KEY
- GEMINI_API_KEY
- PERPLEXITY_API_KEY

## OpenAPI Contract

Regenerate the public API specification when routes or response schemas change:

```bash
composer generate:openapi
# or
php utils/generate-openapi.php
```

Generated file:

- public/pwgenerator-swagger-spec.json

## Docker Deployment

### Build image

```bash
docker build -t password-generator:latest .
```

### Run image

```bash
docker run --rm -p 8080:8080 --name password-generator password-generator:latest
```

### Docker Compose (project-local setup)

The repository ships a compose template rather than a committed local override. Copy it to a host-specific file before running locally. Keep the app runtime configuration on the host (for example `.env` and `config/config.json`) and let Compose mount those values into the container; the image itself must not create or overwrite them.

```bash
cp .env.example .env
cp docker-compose.example.yml docker-compose.yml
cp config/config.example.json config/config.json
mkdir -p logs

docker compose up --build -d
```

Then open:

- [http://localhost:8080](http://localhost:8080)
- [http://localhost:8080/docs](http://localhost:8080/docs)

Useful commands:

```bash
docker compose logs -f password-generator
docker compose restart password-generator
docker compose down
```

### Docker Hub publish

```bash
docker login
docker tag password-generator:latest YOUR_DOCKERHUB_USERNAME/password-generator:latest
docker push YOUR_DOCKERHUB_USERNAME/password-generator:latest
```

## Testing

```bash
composer test
```

## Project Structure

```text
public/      - web root and generated OpenAPI spec
src/         - API, generators, middleware, and utilities
config/      - route, dependency, and app configuration
assets/      - frontend CSS and JavaScript
templates/   - HTML templates
locales/     - translation files
data/        - source wordlists
tests/       - PHPUnit tests
```