# Twitch Authentication Setup

This document explains how to set up Twitch authentication for the application.

## Prerequisites

1. You need a Twitch account
2. You need to register a Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console/apps)
3. Required Python packages:
   - `cryptography` - For generating SSL certificates
   - `requests` - For making HTTP requests to the Twitch API
   - `python-dotenv` - For managing environment variables

You can install these dependencies using the provided script:

```bash
python scripts/install_auth_deps.py
```

## Registering a Twitch Application

1. Go to [Twitch Developer Console](https://dev.twitch.tv/console/apps)
2. Click "Register Your Application"
3. Fill in the details:
   - **Name**: Choose a name for your application (e.g., "MyStreamInteract")
   - **OAuth Redirect URLs**: Set to `https://localhost:3000` (note: HTTPS is required)
   - **Category**: Choose "Chat Bot"
4. Click "Create"
5. Once created, click "Manage" for your application
6. Make note of your **Client ID**
7. Generate a **Client Secret** and store it securely

## Setting Up Authentication

There are two ways to authenticate:

### Method 1: Using the Setup Script (Recommended)

We provide a setup script that walks you through the authentication process:

```bash
python scripts/setup_twitch_auth.py
```

The script will:
1. Ask for your Client ID and Client Secret
2. Generate a self-signed SSL certificate for HTTPS (required by Twitch)
3. Open a browser window for authentication
4. Store the tokens securely
5. Update your .env file with the credentials

> **Note:** When the browser opens, you will see a security warning about the self-signed certificate.
> This is normal for local development. You need to proceed past this warning to continue the authentication process.
> In Chrome, click "Advanced" and then "Proceed to localhost (unsafe)".

If you want to force the generation of a new token (ignoring any cached ones):

```bash
python scripts/setup_twitch_auth.py --force-new-token
```

### Method 2: Manual Setup

1. Create or edit a `.env` file in the root directory of the project
2. Add the following information:

```
TWITCH_CLIENT_ID=your_client_id_here
TWITCH_CLIENT_SECRET=your_client_secret_here
TWITCH_USERNAME=your_twitch_username
TWITCH_CHANNEL=channel_to_connect_to
```

3. Run the authentication script:

```bash
python scripts/setup_twitch_auth.py --manual
```

4. Follow the instructions to complete authentication

## Windows-Specific Information

On Windows, the application uses the Python `cryptography` library to generate self-signed certificates instead of relying on the OpenSSL command-line tool. This ensures better compatibility with Windows systems.

If you encounter any issues with certificate generation on Windows:

1. Make sure you have the latest version of pip: `python -m pip install --upgrade pip`
2. Try reinstalling the cryptography package: `pip install --force-reinstall cryptography`
3. Visual C++ Build tools might be required. If you get build errors, you may need to install the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)

## Important Notes

- The application uses user access tokens with `chat:read` and `chat:edit` scopes
- IRC chat access requires a user access token (client credentials are not sufficient)
- Twitch requires HTTPS for OAuth redirects, so we use a self-signed certificate for local development
- The tokens are cached in `data/cache/token_cache.json` and refreshed automatically when needed
- Never share your Client Secret or access tokens

## Self-Signed Certificates

The application automatically generates a self-signed certificate for HTTPS, which is stored in `data/ssl/`. This certificate is used for handling OAuth redirects from Twitch.

If you encounter certificate issues, you can delete the files in `data/ssl/` to generate a new certificate:
- `data/ssl/localhost.crt`
- `data/ssl/localhost.key`

## Troubleshooting

If you encounter authentication issues:

1. Make sure your Client ID and Client Secret are correct
2. Check that your OAuth redirect URL in the Twitch Developer Console is exactly `https://localhost:3000` (with HTTPS)
3. When prompted with certificate warnings in your browser, make sure to proceed past these warnings
4. Verify that your Twitch account has the necessary permissions
5. Delete the token cache file (`data/cache/token_cache.json`) and try again
6. Check the application logs for detailed error messages
7. If the browser doesn't open automatically, you can copy and paste the provided URL