# coggers-session

> Session middleware for Coggers

Latest version **1.3.0** (published 2021-12-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install coggers-session
pnpm add coggers-session
yarn add coggers-session
bun add coggers-session
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2021-12-03 |
| First published | 2021-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | tbhmens |
| Maintainers | tbhmens |
| Keywords | session, coggers |

## Links

- npm: https://www.npmjs.com/package/coggers-session
- Repository: https://github.com/tbhmens/coggers-session
- Homepage: https://github.com/tbhmens/coggers-session#readme
- Issues: https://github.com/tbhmens/coggers-session/issues
- npm.io page: https://npm.io/package/coggers-session

## Dependencies (1)

- [coggers](https://npm.io/package/coggers.md) ^1.5.0

## Recent versions

- 1.3.0 (latest) — 2021-12-03
- 1.2.1 — 2021-11-06
- 1.2.0 — 2021-11-06
- 1.1.0 — 2021-11-03
- 1.0.0 — 2021-11-01

## README

# coggers-session

Coggers-session is a secure session middleware for Coggers

## Example

```ts
import { Coggers } from "coggers";
import session from "coggers-session";
const coggers = new Coggers({
	$: [
		session({
			password: "secure_password_above_32_characters_do_not_hardcode_this",
		}),
	],
	$get(req, res) {
		const count = req.session.count;
		if (count) req.session.count++;
		else req.session.count = 1;
		res.saveSession();
		res.send(`You've refreshed ${count} times!`);
	},
});

coggers
	.listen(8080)
	.then(() => console.log("Listening at http://localhost:8080/"));
```

### session(options)

Used to get an initialized middleware for coggers. The `options` object contains:

- password: string | Buffer | Array<string | Buffer> <br>
  This is used for encrypting the session so that only the server knows what the session contains. (Needs to be over 32 characters, please do not hardcode this)

- name: string <br>
  The name of the cookie sent to the client. (defaults to "session")

- passwordIndex: number <br>
  When using [rotating passwords](#password-rotation), the index of the password to seal with. Defaults to the last password in the array.

- cookie <br>
  Options for the cookie. Defaults are { httpOnly: true, sameSite: "Lax" }

### req.session

Used to modify the session.

```ts
req.session.count = 1;
// or
req.session = {
	count: 1,
};
```

### res.saveSession()

Used to save the session. Chainable.

```ts
res.saveSession().send(`You've refreshed ${count} times!`);
```

### res.deleteSession()

Used to delete the session. Chainable. **This does not invalidate the session, it only tells the client to remove the cookie.**

```ts
res.deleteSession().send(`There goes your session!`);
```

### Password rotation

coggers-session supports password rotation, meaning that you can switch around the passwords used for sealing and unsealing the session cookies.

You can use password rotation simply by putting an array into the `password` field.
If you ever want to use a new password, you can just add it to the end of the array. If you want to reuse an old password, you'll need to define the `passwordIndex` option to be the index of that old password.

For example, if you want to add a password to `session({ password: "pass1" })`, it would look like `session({ password: ["pass1", "pass2"] })`. Then, if you wanted to go back to `pass1`, you can use `session({ password: ["pass1", "pass2"], passwordIndex: 0 })`.

**Do not move a password around, or remove it from the array. This can invalidate old sessions.**

#### Internal workings

If you want to be reassured, or want to know how it works, see [sealing.md](./sealing.md)

---
_Source: https://npm.io/package/coggers-session · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._