Metadata-Version: 2.4
Name: gateway-defender
Version: 0.2.5
Summary: Reusable Django app gateway-defender
Author-email: Muhammad Rabi Uddin <rabiuddin1@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        ... (standard MIT text) ...
Keywords: django,gateway_-defender,gateway_defender,authentication,users
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: Django<7,>=5.2
Requires-Dist: django-widget-tweaks>=1.4

# Gateway Defender

gateway-defender is a small, reusable Django app that provides authentication helpers (login/logout views), a protected portal view, session timeout handling, and packaged templates/static assets. The PyPI distribution name is `gateway-defender`; the importable Python package is `gateway_defender`.

---

## Install

Install from PyPI with pip:

```bash
pip install gateway-defender
```

---

## Quick start

1. Add to `INSTALLED_APPS` in your Django settings:

```py
INSTALLED_APPS = [
    # ...
    "django.contrib.sites",
    "gateway_defender",
]
```

2. Add the middleware (required for multi-site support):

```py
MIDDLEWARE = [
    # ...
    "django.contrib.sites.middleware.CurrentSiteMiddleware",
]
```

3. Include the URLs in your project `urls.py`:

```py
from django.urls import include, path

urlpatterns = [
    path("", include("gateway_defender.urls")),
]
```

4. Configure the portal template to render after successful login:<br/>
Add this inside your settings.py

```py
# Defaults to "gateway_defender/portal.html"
GATEWAY_PORTAL_TEMPLATE = "your_app/portal.html"
```

Ensure the template exists within one of the template directories defined in `TEMPLATES` in your settings.

5. Run migrations:

```bash
python manage.py migrate
```

6. Routes provided by the app:
- `GET /` — login page (uses `gateway_defender/gateway.html`)
- `GET /portal/` — protected portal page
- `GET /logout/` — logout and redirect to `index`

---

## Multi-Site Configuration (v0.1.4+)
****Problem Statement****: We share the same PostgreSQL DB instance across different Django projects: `tarot_juicer`, `hypno_mixer`, and a `CV_Portfolio`, all three of which are hosted and deployed to Heroku. When we install this `gateway-defender` package for all three, in the Admin Dashboard for any one project, originally when we toggled the `is_protected` feature boolean switch to “Off”, that would remove the protective gateway for all three at the same time. That’s a major problem. If `is_protected` is set to Off on one project, it needs to respect the fact that the other two projects could be set to "On". 

****Solution****: Introduced in gateway-defender v0.1.4 the app now uses Django's highly advanced built-in [sites framework](https://docs.djangoproject.com/en/6.0/ref/contrib/sites/) so as to enable us to configure different authentication settings per domain while sharing the same database.

### Configuration and Usage
**Important:** You must have at least one Site configured. Create the Site record(s) in the admin panel. Without a valid Site, Django's Sites framework will likely raise a `Site.DoesNotExist` error when resolving the current site. When installing `gateway-defender` for the first time in a new Django project, to avoid this error you may need to **temporarily** add a line inside `settings.py` such as `SITE_ID = 1` (or any such integer) locally for both database instances to enable access into Django Admin Dashboard. This is just a work around/fallback. Once you establish access you can then proceed with the instructions below. After completing the steps, remember to delete the `SITE_ID = 1` from `settings.py`.
### Steps
1. Create a Site from the Admin Dashboard (usually at the bottom of the menu panel) for each domain you want to support. Then click "Add Site" in the top right corner.
2. Two fields are available: For `Domain name`, for local testing in the development environment, add: `localhost:8000` or `127.0.0.1:8000`. The `Display name` field is used for annotating for your personal reference.
3. Similar to your local configuration, continue adding sites with your production database configured for your one (or multiple) production domain(s). 
    - Keep in mind that including a `https://` prefix or even a trailing `/` at the end could cause Django to throw a 404 so avoid those characters. Plus for production domains, you will likely need to create two sites: One with `www` prefix and one without any prefix, depending on how you you've configured your domain with your registrar.
4. In the Admin Dashboard, add an `AuthToggle` (top left menu panel). In the `Site` dropdown box, select the domain and then choose your dynamic options such as "Is protected", "Faravahar", and/or "Nuclear", and enter the `Email` address. All of these options will be assigned to the specified Site. 
5. It's worth reiterating how **important** it is to remove the intial usage of `SITE_ID = 1` fallback in `settings.py` once all custom data is entered, especially in production.


---


## API / Files included

Key modules included in the package:

- `gateway_defender.models` — `AuthToggle`, `PassPhrase`
- `gateway_defender.views` — `Gateway` (login view) and `EndSession` (logout view)
- `gateway_defender.urls` — URL patterns included above
- `gateway_defender.custom_decorator` — `protected_redirect` decorator
- `gateway_defender/templates/` — packaged templates (gateway_defender/gateway.html, gateway_defender/logged_out.html)
- `gateway_defender/static/` — CSS and images

Refer to module docstrings and the source for details.

---

## Compatibility

- Python: 3.10 — 3.13
- Django: >= 4.2 (tested with Django 5.2)

---

## Development

Run tests and linters in your development environment. For local development:

```bash
pip install -r requirements-dev.txt  # if you create one
pytest
```

When preparing a release:

1. Update `pyproject.toml` version and metadata.
2. Build with `python -m build`.
3. Upload with `twine upload dist/*`.

---

## Contributing

Contributions are welcome. Please open issues or PRs and include tests for new behavior. Keep public APIs stable where possible.

---

## License

MIT — see the `LICENSE` file included in the repository.

---

## Project & PyPI

PyPI package name: `gateway-defender`  
Python package (import): `gateway_defender`  

Update the repository or PyPI URLs here if you host the project on GitHub or another platform.

