# Session and Fingerprint

This page covers the two cookies go-ip-sentry issues, the HMAC-signed session, how the device fingerprint is built, and multi-session fingerprint detection.

## Two Cookies

| Cookie | Content | Lifetime | Attributes |
|---|---|---|---|
| `conn.sess.id` | `s:{id}.{signature}`, where `id` is 32 random characters | 30 days | `HttpOnly`, `Secure`, `SameSiteStrictMode`, `Path=/` |
| `conn.device.id` | 128 random characters, unsigned | 365 days | Same as above |

Both are rewritten on every `Check`, `LoginFailure`, and `NotFound404` call to refresh their lifetime.

## Session Signing

| Step | Behavior |
|---|---|
| Sign | `HMAC-SHA256(secret, id)`, base64url without trailing `=` |
| Verify | Cookie must start with `s:` and split on `.` into two parts; the signature is compared in constant time |
| Invalid or missing | Issues a new session silently |
| Key source | `.sessionSecret` in the working directory (mode `0600`); when missing or empty, a 128-character random value is generated and written |
| Load timing | Read once per process (`sync.Once`) |

### Multi-Instance Deployment

`.sessionSecret` uses a relative path. If each instance generates its own key, a session signed by instance A fails verification on instance B and gets replaced, which distorts `session:ip` and the other correlations. When running several instances:

- Give every instance the same `.sessionSecret` (mount one file or write it before startup)
- Start them in the same working directory, or make sure the file sits in each one's working directory
- Rotating the key invalidates every existing session

## Device Fingerprint

```
fingerprint = hex(SHA-256("{Platform}/{Browser}/{Type}/{OS}/{conn.device.id}"))
```

| Field | Parsing |
|---|---|
| Platform | User-Agent contains `android` / `iphone`, `ipad` / `windows` / `macintosh`, `mac os` / `linux` |
| Browser | Chrome (excluding Edge), Firefox, Safari (excluding Chrome), Edge, Opera |
| Type | Mobile keywords first, then tablet, otherwise Desktop |
| OS | iOS, Android, Windows 10/11, 8.1, 7, macOS versions, else falls back to Platform |

The fingerprint is tied to the device cookie, so clearing cookies yields a new fingerprint; keeping the device cookie but switching browsers or upgrading to a new major OS version also changes it.

## Fingerprint Multi-Session

`calcFingerprint` adds the session ID to `fp:session:{minute}:{fp}` (TTL 1 minute):

| Condition | Flag | Score |
|---|---|---|
| More than 2 sessions on one fingerprint within the same minute | `fp_multi_session` | `ScoreFpMultiSession` (50) |

Typical causes are a client that keeps the device cookie but keeps dropping the session cookie, or one device cookie copied into several parallel crawlers. This flag alone reaches the suspicious tier.

## Boundaries

| Case | Behavior |
|---|---|
| Plain HTTP (not localhost) | Browsers do not store `Secure` cookies, so every request is a new session and fingerprint and one IP quickly triggers `ip_multi_device` |
| Cross-site embedding (iframes, third-party requests) | `SameSiteStrictMode` withholds the cookies; same as above |
| Client forges `conn.device.id` | The device cookie is unsigned and can be anything; a forged value only changes the fingerprint, while the session still needs a valid signature |