otpdoor 0.0.22
OTPdoor is a Python library for creating and managing OTP (One-Time Password) authentication with nginx.
License: MIT

# <img src="https://github.com/germanespinosa/otpdoor/blob/main/logo.png?raw=true" width="48" height="48" valign="middle"> OTPdoor

**OTPdoor** is a premium, lightweight Python library for creating and managing TOTP (One-Time Password) authentication, specifically designed to be used as an `auth_request` backend for Nginx.

It provides a modern, glassmorphic UI for user login and a dedicated configuration portal for initial setup and device provisioning.

## Features

-   **Multi-Domain Support**: Protect multiple independent applications with a single OTPdoor instance, each with its own secret and settings.
-   **TOTP Authentication**: Industry-standard Time-based One-Time Passwords (RFC 6238).
-   **Premium UI**: Modern, glassmorphic design with support for **Light** and **Dark** modes.
-   **Runtime Configuration**: Update session durations and TOTP secrets on the fly via the `/_config` endpoint.
-   **Flexible Sessions**: Configure session duration in seconds, minutes, or hours.
-   **Security First**:
    -   Secure, encrypted session cookies using Fernet (AES-128).
    -   Restricted configuration mode with explicit CLI activation and warnings.
    -   Safety confirmation dialogs for critical actions.
-   **Production Ready**: Powered by **Waitress**, a stable production-grade WSGI server.
-   **Easy Provisioning**: Built-in QR code generation for quick configuration with apps like Google Authenticator or Authy.

## Installation

Install OTPdoor using pip:

```shell
pip install otpdoor
```

## Quick Start

### 1. Installation
```shell
pip install otpdoor
```

### 2. Launch
```shell
export OTPDOOR_COOKIE_SECRET="your-secure-key"
python -m otpdoor -c
```

### 3. Setup via Browser
1.  Navigate to `http://localhost:8080/_config`.

> [!CAUTION]
> **SECURITY REQUIREMENT**: Log in with the default secret **`BASE32SECRET3232`** and **Immediately generate a new secret** for the `default` domain. Never leave the default secret active after initial setup.

*   *Scan this QR for quick access:*  
    ![Default QR](https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=otpauth%3A%2F%2Ftotp%2FOTPdoor%3Aadmin%3Fsecret%3DBASE32SECRET3232%26issuer%3DOTPdoor)

4.  Use the **"Create New Domain"** section to add other applications.

> [!IMPORTANT]
> Access to the configuration portal now requires a valid authentication session for the `default` domain.

## Multi-Domain Support

OTPdoor allows you to manage multiple independent authentication domains. Each domain has its own secret, session duration, and theme. Configurations are encrypted and persisted in `otpdoor_config.json`.

### Managing Domains
- **Add a domain**: `python -m otpdoor --add-domain myapp`
- **List domains**: `python -m otpdoor --list-domains`

### Using Domains in URLs
Access routes for a specific domain by adding the `domain` parameter:
- `http://127.0.0.1:8080/_auth?domain=myapp`
- `http://127.0.0.1:8080/_check?domain=myapp`
- `http://127.0.0.1:8080/_config?domain=myapp`

If no domain is provided, it defaults to `default`.



### 5. Nginx Configuration (Multi-Domain)
To protect a specific app (`myapp`), pass the `domain` parameter in the proxy requests:

```nginx
upstream otpdoor_backend {
    server 127.0.0.1:8080;
}

server {
    listen 80;
    server_name myapp.example.com;

    location / {
        # Pass the domain to the check endpoint
        auth_request /_check;
        error_page 401 = @error401;
        proxy_pass http://your_app_backend;
    }

    location = /_check {
        internal;
        # Pass domain=myapp to use the correct secret
        proxy_pass http://otpdoor_backend/_check?domain=myapp;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
    }

    location /_auth {
        # Pass domain=myapp so the login page uses the correct configuration
        proxy_pass http://otpdoor_backend/_auth?domain=myapp;
        proxy_set_header Host $host;
    }

    location @error401 {
        # Redirect to the domain-specific auth page
        return 302 $scheme://$http_host/_auth?domain=myapp&originator=$request_uri;
    }
}
```

## Configuration Reference

- `OTPDOOR_TOTP_SECRET`: Shared secret for the `default` domain.
- `OTPDOOR_COOKIE_SECRET`: Key used to encrypt session cookies.
- `OTPDOOR_CONFIG_FILE`: Path to the JSON configuration file (default: `otpdoor_config.json`).
- `OTPDOOR_SESSION_DURATION`: Default session duration in seconds.
- `OTPDOOR_THEME`: Default theme (`dark` or `light`).
- `OTPDOOR_ALLOWED_DOMAINS`: Allowed domains for redirects.
- `OTPDOOR_COOKIE_SECURE`: Set to `true` to enable HTTPS-only cookies (default: `false`).

## Persistence & Updates ðŸ”„

OTPdoor is designed to keep your data safe during version upgrades. The `otpdoor_config.json` file resides in your working directory, entirely separate from the package code. 

**Steps for a safe update:**
1. Run `python -m otpdoor --show-config` and note the path.
2. Back up that file.
3. Install the new version (`pip install --upgrade otpdoor` or similar).
4. Restart the server. Your configuration will be automatically detected and reloaded.

## License
MIT License - see the LICENSE file for details.

## Contact
[germanespinosa@gmail.com]

---
<small>Package created with Easy-pack</small>