Skip to content

Commit

Permalink
docs: added session middleware example
Browse files Browse the repository at this point in the history
  • Loading branch information
Reinaldy Rafli committed Jun 25, 2021
1 parent 667646d commit fdd9f25
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 34 deletions.
9 changes: 4 additions & 5 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ about: Create a report to help us improve
title: ''
labels: bug
assignees: ''

---

**Describe the bug**
Expand All @@ -25,10 +24,10 @@ A clear and concise description of what you expected to happen.

**Versions**

* `node`: 14
* `@tinyhttp/app`: 0.X
* `@tinyhttp/csrf`: 0.X
- `node`: 14
- `@tinyhttp/app`: 0.X
- `@tinyhttp/csrf`: 0.X

**Additional context**

Add any other context about the problem here.
Add any other context about the problem here.
3 changes: 1 addition & 2 deletions .github/ISSUE_TEMPLATE/feature_request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ about: Suggest an idea for this project
title: ''
labels: enhancement
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
Expand All @@ -17,4 +16,4 @@ A clear and concise description of what you want to happen.
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.
Add any other context or screenshots about the feature request here.
1 change: 0 additions & 1 deletion .husky/pre-commit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,3 @@

pnpm format:fix
pnpm test
git add .
75 changes: 49 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
<br /><br />

<!-- badges goes here -->

[![npm](https://img.shields.io/npm/v/malibu?style=for-the-badge&logo=npm&label=&color=#31FFF3)](https://npmjs.com/package/malibu) [![npm](https://img.shields.io/npm/dt/malibu?style=for-the-badge&color=#31FFF3)](https://npmjs.com/package/malibu) [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/tinyhttp/malibu/CI?label=&logo=github&style=for-the-badge&color=#31FFF3)](https://github.com/tinyhttp/malibu/actions) [![Codecov](https://img.shields.io/codecov/c/gh/tinyhttp/malibu?style=for-the-badge&color=#31FFF3)](https://app.codecov.io/gh/tinyhttp/malibu)

</div>
</div>

This middleware helps web developers fight [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) attacks. Bear in mind, by solely using this middleware, we can't guarantee your app will be free from CSRF attacks. Refer to [CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) and [pillarjs/understanding-csrf](https://github.com/pillarjs/understanding-csrf) for more details.


## Install

```
Expand All @@ -25,7 +25,6 @@ Like all CSRF plugins, it depends on either Cookie Parser or Session middleware.
import { App } from '@tinyhttp/app'
import { cookieParser } from '@tinyhttp/cookie-parser'
import { csrf } from 'malibu'
import { json, urlencoded } from 'milliparsec'

const app = new App()

Expand All @@ -34,48 +33,72 @@ app.use(cookieParser())

// this lets you acquire CSRF token on response body
// you also have CSRF token on your cookies as _csrf
app.get("/", csrfProtection, (req, res) => {
res.status(200).json({ token: req.csrfToken() });
});
app.get('/', csrfProtection, (req, res) => {
res.status(200).json({ token: req.csrfToken() })
})

// you may only access this if you give a previously acquired CSRF token
app.post("/", csrfProtection, (req, res) => {
res.status(200).json({ message: "hello" });
});
app.post('/', csrfProtection, (req, res) => {
res.status(200).json({ message: 'hello' })
})
```

For signed cookies:

```js
const app = new App()

const csrfProtection = csrf({ cookie: { signed: true }})
app.use(cookieParser(process.env.COOKIE_SECRET))
const csrfProtection = csrf({ cookie: { signed: true } })
app.use(cookieParser('secret key'))

// this lets you acquire CSRF token on the response body
// you also have a CSRF token on your cookies as _csrf
app.get("/", csrfProtection, (req, res) => {
res.status(200).json({ token: req.csrfToken() });
});
app.get('/', csrfProtection, (req, res) => {
res.status(200).json({ token: req.csrfToken() })
})

// you may only access this if you give a previously acquired CSRF token
app.post('/', csrfProtection, (req, res) => {
res.status(200).json({ message: 'hello' })
})
```

For working with [express-session](https://github.com/expressjs/session):

```js
import { App } from '@tinyhttp/app'
import session from 'express-session'
import { csrf } from 'malibu'

const app = new App()

const csrfProtection = csrf({ middleware: 'session' })
app.use(session({ secret: 'secret key', resave: false, saveUninitialized: false }))

// this lets you acquire CSRF token on response body
app.get('/', csrfProtection, (req, res) => {
res.status(200).json({ token: req.csrfToken() })
})

// you may only access this if you give a previously acquired CSRF token
app.post("/", csrfProtection, (req, res) => {
res.status(200).json({ message: "hello" });
});
app.post('/', csrfProtection, (req, res) => {
res.status(200).json({ message: 'hello' })
})
```

For other framework appliances, please refer to [examples](https://github.com/tinyhttp/malibu/tree/master/examples)

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| cookie | `CookieOptions` | `{ signed: false, key: '_csrf', path: '/' }` | `signed` specifies whether the cookie is signed or unsigned, `key` specifies to the cookie key, `path` specifies the domain of the cookie. For other options please refer to [@tinyhttp/cookie serializer options](https://github.com/tinyhttp/tinyhttp/tree/master/packages/cookie#options-1) |
| sessionKey | `string` | `session` | Specifies session key name |
| value | `(req: Request) => any` | `req.body._csrf, req.query._csrf, req.headers["csrf-token"], req.headers["xsrf-token"], req.headers["x-csrf-token"], req.headers["x-xsrf-token"]` | Specifies where to look for the CSRF token |
| ignoreMethod | `Array<HTTPMethod>` | `["GET", "HEAD", "OPTIONS"]` | Specifies the HTTP Method in which CSRF protection will be disabled |
| saltLength | `number` | `8` | Specifies the salt length for CSRF token |
| secretLength | `number` | `18` | Specifies the secret length for CSRF Token |

| Name | Type | Default | Description |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| middleware | `string` | `cookie` | Specifies which middleware to look for. Available options are `cookie` and `session` |
| cookie | `CookieOptions` | `{ signed: false, key: '_csrf', path: '/' }` | `signed` specifies whether the cookie is signed or unsigned, `key` specifies to the cookie key, `path` specifies the domain of the cookie. For other options please refer to [@tinyhttp/cookie serializer options](https://github.com/tinyhttp/tinyhttp/tree/master/packages/cookie#options-1) |
| sessionKey | `string` | `session` | Specifies session key name |
| value | `(req: Request) => any` | `req.body._csrf, req.query._csrf, req.headers["csrf-token"], req.headers["xsrf-token"], req.headers["x-csrf-token"], req.headers["x-xsrf-token"]` | Specifies where to look for the CSRF token |
| ignoreMethod | `Array<HTTPMethod>` | `["GET", "HEAD", "OPTIONS"]` | Specifies the HTTP Method in which CSRF protection will be disabled |
| saltLength | `number` | `8` | Specifies the salt length for CSRF token |
| secretLength | `number` | `18` | Specifies the secret length for CSRF Token |

## Why "malibu"?

Expand Down

0 comments on commit fdd9f25

Please sign in to comment.