express-defender/readme.md

Express middleware to enforce domain and country-based access, blocking direct IP requests and unwanted bots.

<div align="center">
  <br />
  <p>
    <img src="./logo.png" width="800" alt="express-defender" />
  </p>
  <br />
  <p>
    <a href="https://www.npmjs.com/package/express-defender"><img src="https://img.shields.io/npm/v/express-defender.svg?maxAge=3600" alt="NPM version" /></a>
    <a href="https://www.npmjs.com/package/express-defender"><img src="https://img.shields.io/npm/dt/express-defender.svg?maxAge=3600" alt="NPM downloads" /></a>
    <a href="https://github.com/Mssjim/express-defender"><img src="https://badge.fury.io/gh/Mssjim%2Fexpress-defender.svg" alt="GitHub Version" /></a>
    <a href="https://github.com/Mssjim/express-defender/blob/master/LICENSE"><img src="https://img.shields.io/github/license/Mssjim/express-defender.svg" alt="GitHub Version" /></a>
  </p>
</div>

## About
Express middleware to enforce domain and country-based access, blocking direct IP requests and unwanted bots.

<div align="center">

### ⭐ Like **Express Defender**? [Star it on GitHub](https://github.com/Mssjim/express-defender) to support the project!  

</div>

## Installation 
```bash
npm i express-defender
```

## Basic Usage
```js
const express = require('express');
const expressDefender = require('express-defender');

const app = express();

app.use(expressDefender({
    allowedDomains: ['example.com'],
    allowedCountries: ['BR', 'US']
}));

app.get('/', (req, res) => {
    res.json(req.expressDefender);
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));
```

| Option              | Type       | Default                                 | Description                                                                                                                                |
| ------------------ | ---------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `allowedDomains`   | `string[]` | `['*']`                                | List of allowed domains. Accepts `*` to allow all. E.g., `['example.com']` also allows `www.example.com` and `api.example.com`. |
| `allowedCountries` | `string[]` | `['*']`                                | List of allowed countries (ISO Alpha-2). Use `*` to allow all.                                                                    |
| `allowedBots`      | `RegExp[]` | Googlebot, Bingbot, Slurp, DuckDuckBot | List of User-Agents of bots authorized to ignore country/domain restrictions.                                                           |
| `log`              | `boolean`  | `true`                                 | Enables or disables logging in the console.                                                                                             |

## Examples
> • Allow all domains and countries
```js
app.use(expressDefender({
    allowedDomains: ['*'],
    allowedCountries: ['*']
}));
```

> • Allow only the US and Canada
```js
app.use(expressDefender({
    allowedCountries: ['US', 'CA']
}));
```

> • Allow only direct requests from mysite.com and Googlebot
```js
app.use(expressDefender({
    allowedDomains: ['mysite.com'],
    allowedBots: [/Googlebot/]
}));
```

## Extra
• Output of `req.expressDefender`
```json
{
  "ip": "192.0.2.25",
  "country": "BR",
  "region": "SP",
  "city": "SP",
  "method": "GET",
  "url": "/home",
  "fromDomain": true,
  "isBot": false
}
```

• Logs when
> Bot Acess  
> Localhost Acess  
> Sucessful Acess  
> Blocked Acess by Country  
> Blocked Acess by direct IP traffic  
> Blocked Acess by Country and direct IP traffic  

respectively.

<img src="./example.png" width="800" alt="express-defender example" />

## Contributing - bug fixes
Contributions are welcome! Please feel free to open an issue or submit a pull request, for bug fixes or new features.

1. Fork the repository
2. Create a new branch `git checkout -b <new-feature-name>`
3. Make the changes
4. Commit the changes `git commit -am "Add new feature"`
5. Push the changes `git push origin <new-feature-name>`
6. Create a pull request on GitHub