pw-generator/integration-guide.md

# Password Generator API Integration Guide

This guide provides comprehensive examples for integrating the Password Generator API with popular password managers, launchers, and automation tools.

## Table of Contents
- [Quick Start](#quick-start)
- [Password Managers](#password-managers)
- [Launchers & Tools](#launchers--tools)
- [Automation Scripts](#automation-scripts)
- [Security Considerations](#security-considerations)

## Quick Start

The API provides several endpoints for password generation:

**Base URL:** `http://localhost:8080/api/v1`

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

## Password Managers

### Bitwarden

#### Bitwarden CLI Integration

**Installation:**
```bash
npm install -g @bitwarden/cli
```

**Basic Password Generation and Storage:**
```bash
#!/bin/bash
# generate-and-store-bitwarden.sh

# Login to Bitwarden (do this once)
bw login

# Unlock vault (enter master password when prompted)
export BW_SESSION="$(bw unlock --raw)"

# Generate high-entropy password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"high-entropy","count":1,"options":{"length":20,"includeSymbols":true}}' | \
  jq -r '.data.passwords[0]')

# Create new login item
ITEM_DATA=$(cat <<EOF
{
  "type": 1,
  "name": "Generated Password $(date +%Y-%m-%d)",
  "login": {
    "username": "user@example.com",
    "password": "$PASSWORD"
  }
}
EOF
)

echo "$ITEM_DATA" | bw encode | bw create item

echo "Password created and stored in Bitwarden: $PASSWORD"
```

**Advanced: Generate Different Password Types:**
```bash
#!/bin/bash
# bitwarden-multi-generator.sh

generate_and_store() {
    local type=$1
    local name=$2
    local options=$3
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$type\",\"count\":1,\"options\":$options}" | \
      jq -r '.data.passwords[0]')
    
    ITEM_DATA="{\"type\": 1, \"name\": \"$name\", \"login\": {\"password\": \"$PASSWORD\"}}"
    echo "$ITEM_DATA" | bw encode | bw create item
    
    echo "Created $name: $PASSWORD"
}

# Generate different types
generate_and_store "diceware" "Diceware Passphrase" '{"words":6,"capitalize":true}'
generate_and_store "passkey" "Apple-style Password" '{"syllables":4,"addNumbers":true}'
generate_and_store "xkcdpass" "XKCD Passphrase" '{"words":4,"language":"english","addNumber":true}'
```

### 1Password

#### 1Password CLI Integration

**Installation:**
Follow 1Password CLI installation guide for your platform.

**Basic Integration:**
```bash
#!/bin/bash
# generate-and-store-1password.sh

# Generate secure password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"high-entropy","count":1,"options":{"length":24}}' | \
  jq -r '.data.passwords[0]')

# Create login item
op item create \
    --category=login \
    --title="Generated Password $(date +%Y-%m-%d)" \
    --field="username=user@example.com" \
    --field="password=$PASSWORD"

echo "Password stored in 1Password: $PASSWORD"
```

**Batch Password Generation:**
```bash
#!/bin/bash
# 1password-batch-generator.sh

TYPES=("diceware" "high-entropy" "passkey" "xkcdpass")
NAMES=("Diceware Phrase" "High Entropy" "Passkey Style" "XKCD Phrase")

for i in "${!TYPES[@]}"; do
    TYPE=${TYPES[$i]}
    NAME=${NAMES[$i]}
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$TYPE\",\"count\":1}" | \
      jq -r '.data.passwords[0]')
    
    op item create \
        --category=login \
        --title="$NAME $(date +%Y-%m-%d)" \
        --field="password=$PASSWORD"
    
    echo "Created $NAME: $PASSWORD"
done
```

### KeePass

#### KeePassXC CLI Integration

```bash
#!/bin/bash
# keepassxc-generator.sh

DB_PATH="$HOME/passwords.kdbx"
KEY_FILE="$HOME/keyfile.key"

# Generate password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"diceware","count":1,"options":{"words":6}}' | \
  jq -r '.data.passwords[0]')

# Add to KeePass database
keepassxc-cli add "$DB_PATH" \
    --key-file "$KEY_FILE" \
    "Generated/$(date +%Y-%m-%d)" \
    --username "user@example.com" \
    --password-prompt

echo "Password: $PASSWORD"
```

## Launchers & Tools

### Raycast

#### Simple Password Generator Extension

Create a Raycast script command:

**generate-password.sh:**

```bash
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Generate Secure Password  
# @raycast.mode compact
# @raycast.icon 🔐
# @raycast.packageName Password Generator
# @raycast.argument1 {"type": "dropdown", "placeholder": "Password Type", "data": [{"title": "High Entropy", "value": "high-entropy"}, {"title": "Diceware", "value": "diceware"}, {"title": "Passkey", "value": "passkey"}, {"title": "XKCD", "value": "xkcdpass"}]}

TYPE=${1:-"passkey"}

case $TYPE in
  "high-entropy")
    OPTIONS='{"length":16,"includeSymbols":true}'
    ;;
  "diceware")
    OPTIONS='{"words":5,"capitalize":true}'
    ;;
  "passkey")
    OPTIONS='{"syllables":3,"addNumbers":true}'
    ;;
  "xkcdpass")
    OPTIONS='{"words":4,"capitalize":true,"addNumber":true}'
    ;;
esac

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"$TYPE\",\"count\":1,\"options\":$OPTIONS}" | \
  jq -r '.data.passwords[0]')

if [ -n "$PASSWORD" ]; then
    echo "$PASSWORD" | pbcopy
    echo "✅ Password copied: $PASSWORD"
else
    echo "❌ Failed to generate password"
fi
```

#### Advanced Raycast Extension with Options

**raycast-advanced.sh:**

```bash
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Advanced Password Generator
# @raycast.mode fullOutput
# @raycast.icon 🔐
# @raycast.packageName Password Generator
# @raycast.argument1 {"type": "text", "placeholder": "Number of passwords", "optional": true}

COUNT=${1:-1}

# Generate multiple password types
echo "🔐 Password Generator Results"
echo "================================"

# High Entropy
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"high-entropy\",\"count\":$COUNT,\"options\":{\"length\":16}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🔒 High Entropy: $PASSWORD"

# Diceware
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"diceware\",\"count\":$COUNT,\"options\":{\"words\":5}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🎲 Diceware: $PASSWORD"

# Passkey
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"passkey\",\"count\":$COUNT,\"options\":{\"syllables\":3}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🗝️  Passkey: $PASSWORD"

echo ""
echo "Select a password above to copy it."
```

### Alfred

#### Alfred Workflow Script Filter

**alfred-password-generator.php:**

```php
<?php
header('Content-Type: application/json');

$types = [
    'high-entropy' => ['name' => 'High Entropy', 'icon' => '🔒', 'options' => '{"length":16}'],
    'diceware' => ['name' => 'Diceware', 'icon' => '🎲', 'options' => '{"words":5}'],
    'passkey' => ['name' => 'Passkey', 'icon' => '🗝️', 'options' => '{"syllables":3}'],
    'xkcdpass' => ['name' => 'XKCD', 'icon' => '💭', 'options' => '{"words":4}']
];

$items = [];

foreach ($types as $type => $config) {
    $items[] = [
        'uid' => $type,
        'title' => $config['name'] . ' Password',
        'subtitle' => 'Generate ' . strtolower($config['name']) . ' password',
        'arg' => $type,
        'icon' => ['emoji' => $config['icon']]
    ];
}

echo json_encode(['items' => $items]);
?>
```

**alfred-generate.sh:**

```bash
#!/bin/bash
TYPE=$1

case $TYPE in
  "high-entropy")
    OPTIONS='{"length":16,"includeSymbols":true}'
    ;;
  "diceware")
    OPTIONS='{"words":5,"capitalize":true}'
    ;;
  "passkey")
    OPTIONS='{"syllables":3,"addNumbers":true}'
    ;;
  "xkcdpass")
    OPTIONS='{"words":4,"capitalize":true,"addNumber":true}'
    ;;
esac

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"$TYPE\",\"count\":1,\"options\":$OPTIONS}" | \
  jq -r '.data.passwords[0]')

echo "$PASSWORD" | pbcopy
echo "$PASSWORD"
```

### LaunchBar

#### LaunchBar Action

**PasswordGenerator.lbaction/Contents/Scripts/default.sh:**

```bash
#!/bin/bash

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"passkey","count":1,"options":{"syllables":4,"addNumbers":true}}' | \
  jq -r '.data.passwords[0]')

if [ -n "$PASSWORD" ]; then
    echo "$PASSWORD" | pbcopy
    echo "$PASSWORD"
else
    echo "Error generating password"
    exit 1
fi
```

### Ubar / Menu Bar Apps

#### BitBar Plugin

**password-generator.1m.sh:**

```bash
#!/bin/bash

echo "🔐 Password Generator"
echo "---"

# Generate different types
TYPES=("high-entropy:High Entropy" "diceware:Diceware" "passkey:Passkey" "xkcdpass:XKCD")

for TYPE_PAIR in "${TYPES[@]}"; do
    TYPE="${TYPE_PAIR%%:*}"
    NAME="${TYPE_PAIR##*:}"
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$TYPE\",\"count\":1}" | \
      jq -r '.data.passwords[0]' 2>/dev/null)
    
    if [ -n "$PASSWORD" ]; then
        echo "$NAME: $PASSWORD | bash='echo \"$PASSWORD\" | pbcopy' terminal=false"
    fi
done

echo "---"
echo "API Status | bash='curl -s http://localhost:8080/api/v1/health' terminal=true"
```

## Automation Scripts

### Automated Password Rotation

```bash
#!/bin/bash
# rotate-passwords.sh

SERVICES=("email:user@example.com" "bank:john.doe" "social:johndoe123")

for SERVICE_PAIR in "${SERVICES[@]}"; do
    SERVICE="${SERVICE_PAIR%%:*}"
    USERNAME="${SERVICE_PAIR##*:}"
    
    # Generate new password
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d '{"type":"high-entropy","count":1,"options":{"length":20}}' | \
      jq -r '.data.passwords[0]')
    
    # Update in password manager (example with Bitwarden)
    ITEM_ID=$(bw list items --search "$SERVICE" | jq -r '.[0].id')
    if [ "$ITEM_ID" != "null" ]; then
        ITEM=$(bw get item "$ITEM_ID")
        UPDATED_ITEM=$(echo "$ITEM" | jq ".login.password = \"$PASSWORD\"")
        echo "$UPDATED_ITEM" | bw encode | bw edit item "$ITEM_ID"
        
        echo "Rotated password for $SERVICE: $PASSWORD"
    fi
done
```

### Bulk Password Generation for Teams

```bash
#!/bin/bash
# team-password-generator.sh

TEAM_MEMBERS=("alice" "bob" "charlie" "diana")
SERVICES=("staging" "development" "testing")

for MEMBER in "${TEAM_MEMBERS[@]}"; do
    echo "Generating passwords for $MEMBER:"
    
    for SERVICE in "${SERVICES[@]}"; do
        PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
          -H "Content-Type: application/json" \
          -d '{"type":"diceware","count":1,"options":{"words":4,"addNumber":true}}' | \
          jq -r '.data.passwords[0]')
        
        # Store in team password manager
        op item create \
            --category=login \
            --title="$SERVICE-$MEMBER" \
            --field="username=$MEMBER" \
            --field="password=$PASSWORD" \
            --vault="Team Vault"
        
        echo "  $SERVICE: $PASSWORD"
    done
    echo ""
done
```

## Security Considerations

### API Security

1. **Local Deployment**: Run the API locally or on a secure internal network
2. **Rate Limiting**: The API includes built-in rate limiting (60 requests/minute by default)
3. **No Logging of Passwords**: Passwords are not logged in server logs
4. **HTTPS**: Use HTTPS in production deployments

### Integration Security

1. **Environment Variables**: Store API endpoints in environment variables:

```bash
export PASSWORD_API_URL="https://passwords.internal.company.com/api/v1"
```

2. **Script Permissions**: Set appropriate permissions on scripts:

```bash
chmod 700 password-scripts/
chmod 600 password-scripts/*.sh
```

3. **Secure Storage**: Ensure integration scripts don't leave passwords in temporary files:

```bash
# Good: Use pipes and variables
PASSWORD=$(curl -s ... | jq -r '.data.passwords[0]')

# Bad: Don't write to temporary files
# curl -s ... > /tmp/password.json
```

### Production Deployment

For production use, consider:

1. **Authentication**: Add API key authentication
2. **Network Security**: Deploy behind a firewall or VPN
3. **Monitoring**: Monitor API usage and failed requests
4. **Backup**: Regular backups of configuration and logs

### Password Manager Sync

When integrating with password managers:

1. **Verify Storage**: Always verify passwords are correctly stored
2. **Error Handling**: Implement proper error handling for API failures
3. **Rollback**: Have procedures to rollback failed password updates
4. **Audit Trail**: Maintain logs of password generation and updates

## Troubleshooting

### Common Issues

**API Connection Issues:**
```bash
# Test API connectivity
curl -s http://localhost:8080/api/v1/health

# Check if service is running
netstat -tlnp | grep 8080
```

**JSON Parsing Issues:**
```bash
# Validate JSON response
curl -s http://localhost:8080/api/v1/passwords | jq '.'

# Check for errors
curl -s http://localhost:8080/api/v1/passwords | jq '.error'
```

**Password Manager Integration:**
```bash
# Test CLI tools separately
bw --version
op --version
keepassxc-cli --version

# Verify authentication
bw status
op whoami
```

This integration guide provides comprehensive examples for connecting the Password Generator API with popular tools and services. Adapt these examples based on your specific requirements and security policies.