password-generator

# password-generator skill

## What this app does

password-generator is a browser-only React SPA that generates cryptographically secure passwords, passphrases (EFF wordlist), and PINs. No network requests are made after initial load. All state lives in localStorage.

## Running the app

```bash
cd password-generator
pnpm install
pnpm run dev     # opens http://localhost:5173
```

For a production build:
```bash
pnpm run build
pnpm run preview   # preview at http://localhost:4173
```

The built `dist/` folder can be hosted on any static file server or opened directly as `dist/index.html`.

## localStorage schema

The app uses two keys:

**`pg_settings`** - user preferences:
```json
{
  "length": 20,
  "includeUpper": true,
  "includeLower": true,
  "includeDigits": true,
  "includeSymbols": true,
  "excludeAmbiguous": false,
  "customCharset": "",
  "passphraseWords": 5,
  "passphraseSep": "-",
  "pinLength": 6,
  "maxHistory": 100,
  "defaultTab": "password",
  "theme": "system"
}
```

**`pg_history`** - array of saved passwords:
```json
[
  {
    "id": "3f2a1b4c-...",
    "value": "kR7#mZ2$vX9@qP4!nL5&",
    "type": "password",
    "entropy": 131.1,
    "createdAt": "2026-03-20T09:41:00.000Z",
    "label": "GitHub account"
  }
]
```

## Reading history from browser console

```javascript
// View all history
JSON.parse(localStorage.getItem('pg_history') ?? '[]')

// Find by label
JSON.parse(localStorage.getItem('pg_history') ?? '[]')
  .filter(e => e.label.toLowerCase().includes('github'))

// Count by type
const h = JSON.parse(localStorage.getItem('pg_history') ?? '[]')
Object.groupBy(h, e => e.type)
```

## Reset / export from console

```javascript
// Export plain text (one per line)
const h = JSON.parse(localStorage.getItem('pg_history') ?? '[]')
const txt = h.map(e => e.value).join('\n')
const blob = new Blob([txt], { type: 'text/plain' })
const url = URL.createObjectURL(blob)
const a = document.createElement('a'); a.href = url; a.download = 'passwords.txt'; a.click()

// Reset all settings to defaults
localStorage.removeItem('pg_settings')
location.reload()

// Clear history
localStorage.removeItem('pg_history')
location.reload()
```

## Keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| Ctrl+G / Cmd+G | Regenerate password |
| Ctrl+Shift+C | Copy current output |
| Ctrl+1 | Go to Generator |
| Ctrl+2 | Go to History |
| Alt+Left / Alt+Right | Switch generator tab |

## Entropy thresholds

| Bits | Label | Color |
|------|-------|-------|
| < 40 | Weak | red #dc2626 |
| 40-59 | Fair | orange #ea580c |
| 60-79 | Strong | yellow-green #65a30d |
| 80-99 | Very strong | green #16a34a |
| >= 100 | Excellent | blue #2563eb |

## Password formula

`entropy = length * log2(charsetSize)`

Where charsetSize depends on enabled character sets:
- Uppercase (A-Z): +26
- Lowercase (a-z): +26
- Digits (0-9): +10
- Symbols (!@#...): +32 (or custom chars)
- `excludeAmbiguous` removes: 0, O, l, I, 1 (5 chars)

## Behavior notes

- History entries are added automatically every time a password is generated or copied (configurable)
- History is capped at `maxHistory` (default 100); oldest entries are evicted when the limit is exceeded
- The "Exclude ambiguous" option removes 5 characters from the charset, slightly reducing entropy
- Custom charset characters are deduplicated and appended to the active charset
- Dark mode follows system preference by default; can be overridden in Settings
- All generation uses `crypto.getRandomValues` - `Math.random()` is never used