Skip to content

Commit

Permalink
feat(docs): add docs about helmet
Browse files Browse the repository at this point in the history
  • Loading branch information
jlenon7 committed Aug 30, 2023
1 parent 522777f commit 9f3f7ae
Show file tree
Hide file tree
Showing 6 changed files with 115 additions and 15 deletions.
2 changes: 1 addition & 1 deletion docs/rest-api-application/error-handling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,6 @@ bootstrapping your application:

```typescript title="Path.bootstrap('main.ts')"
await ignite.httpServer({
exceptionHandlerPath: '#app/http/exceptions/Handler', 👈
exceptionHandlerPath: '#app/http/exceptions/Handler' 👈
})
```
5 changes: 3 additions & 2 deletions docs/rest-api-application/middlewares.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,8 @@ Route.get('/welcome', () => {
:::info

The requests log created by Athenna when the `logger`
property is true in your `Path.config('http.ts')` file are handled
by a terminator middleware! You can see the code [here](https://github.com/AthennaIO/Http/blob/develop/src/kernels/HttpKernel.ts#L93).
property is true in your `Path.config('http.ts')` file are
handled by a terminator middleware! You can see the code
[here](https://github.com/AthennaIO/Http/blob/develop/src/kernels/HttpKernel.ts#L93).

:::
2 changes: 1 addition & 1 deletion docs/rest-api-application/rate-limiting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ export default {
cache: 5000,
allowList: [],
continueExceeding: false,
enableDraftSpec: false,
enableDraftSpec: false
}
}
```
Expand Down
101 changes: 100 additions & 1 deletion docs/rest-api-application/security-with-helmet.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,103 @@ See how to improve the security of your REST API with Helmet in Athenna.

## Introduction

Coming soon
[`Helmet`](https://www.npmjs.com/package/helmet) helps secure
applications by setting HTTP response headers. By default,
Helmet sets the following headers:

- `Content-Security-Policy`: A powerful allow-list of what can
happen on your page which mitigates many attacks.
- `Cross-Origin-Opener-Policy`: Helps process-isolate your
page.
- `Cross-Origin-Resource-Policy`: Blocks others from loading
your resources cross-origin.
- `Origin-Agent-Cluster`: Changes process isolation to be
origin-based.
- `Referrer-Policy`: Controls the Referer header.
- `Strict-Transport-Security`: Tells browsers to prefer
HTTPS.
- `X-Content-Type-Options`: Avoids MIME sniffing.
- `X-DNS-Prefetch-Control`: Controls DNS prefetching.
- `X-Download-Options`: Forces downloads to be saved
(Internet Explorer only).
- `X-Frame-Options`: Legacy header that mitigates clickjacking
attacks.
- `X-Permitted-Cross-Domain-Policies`: Controls cross-domain
behavior for Adobe products, like Acrobat.
- `X-Powered-By`: Info about the web server. Removed because
it could be used in simple attacks.
- `X-XSS-Protection`: Legacy header that tries to mitigate XSS
attacks, but makes things worse, so Helmet disables it.

## Basic usage

Athenna uses the [`@fastify/helmet`](https://github.com/fastify/helmet)
plugin inside `HttpKernel`. All the configurations that
`@fastify/helmet` supports can be set inside `Path.config('http.ts')`
file in the `helmet` object:

```typescript
export default {
helmet: {
global: true
}
}
```

## Configuring for specific routes

In Athenna you can set specific options of helmet
for specific routes. You can also disable the `global`
option of your `helmet` configuration in `Path.config('http.ts')`
and set different rules in your routes:

```typescript title="Path.route('http.ts')"
Route
.get('/hello', 'WelcomeController.show')
.helmet({ frameguard: { action: 'foo' } }) 👈
```

### Usage in route groups

You can also use the `helmet()` method in route groups.
This will set the same configuration for all routes inside
the group:

```typescript title="Path.route('http.ts')"
Route.group(() => {
Route.get('/hello', 'WelcomeController.show')
}).helmet({ frameguard: { action: 'foo' } }) 👈
```

:::warning

The `helmet()` method of route groups will never
subscribe the already set methods of routes. Use it
to create "defaults" configurations for all routes.

:::

### Usage in route resources

Same behavior as route groups, but for resources:

```typescript title="Path.route('http.ts')"
// Set the same configurations for all routes of resource
Route.resource('/tests', 'WelcomeController').helmet({...})

// Set configuration only for that specific action of resource
Route.resource('/tests', 'WelcomeController').helmet('index', {...})
Route.resource('/tests', 'WelcomeController').helmet('store', {...})
```

## Disabling helmet

The `HttpKernel` class will automatically disable the
plugin registration if the package does not exist, so
to disable helmet in Athenna you need to
remove the `@fastify/helmet` package from your
application:

```shell
npm remove @fastify/helmet
```
12 changes: 6 additions & 6 deletions docs/rest-api-application/swagger-documentation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ export default {
swagger: {
ui: {
staticCSP: true,
routePrefix: '/documentation',
routePrefix: '/documentation'
},
configurations: {
mode: 'dynamic',
Expand All @@ -43,15 +43,15 @@ export default {
info: {
title: Config.get('app.name'),
version: Config.get('app.version'),
description: Config.get('app.description'),
description: Config.get('app.description')
},
externalDocs: {
url: 'https://athenna.io',
description: 'Find more info about Athenna here',
description: 'Find more info about Athenna here'
},
},
},
},
}
}
```

Expand All @@ -71,9 +71,9 @@ Route.get('/hello', 'WelcomeController.show')
schema: {
type: 'object',
properties: {
name: { type: 'string' },
name: { type: 'string' }
},
},
}
})
```

Expand Down
8 changes: 4 additions & 4 deletions docs/rest-api-application/tracing-requests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ export default {
echoHeader: false,
useHeader: false,
headerName: 'X-Request-Id',
useFastifyRequestId: false,
},
useFastifyRequestId: false
}
}
```

Expand Down Expand Up @@ -77,7 +77,7 @@ You can also disable the tracer by setting `http.trace` to `false`:

```typescript title="Path.config('http.ts')"
export default {
trace: false,
trace: false
}
```

Expand All @@ -90,7 +90,7 @@ import { Ignite } from '@athenna/core'
const ignite = await new Ignite().load(import.meta.url)

await ignite.httpServer({
trace: false, 👈
trace: false 👈
})
```

0 comments on commit 9f3f7ae

Please sign in to comment.