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

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

2. Configure

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

3. Run

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

Open:

• http://localhost:8080
• http://localhost:8080/docs

API Usage

List available generator types

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

Generate passwords

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

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

Generator Option Examples

High Entropy

{
  "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

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

Diceware

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

PWGen Enhanced

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

Passkey

{
  "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:

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

Generated file:

• public/pwgenerator-swagger-spec.json

Docker Deployment

Build image

docker build -t password-generator:latest .

Run image

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.

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/docs

Useful commands:

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

Docker Hub publish

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

Testing

composer test

Project Structure

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