Skip to content

ADR-0024: Opaque cookie sessions with origin checks

  • Status: Accepted
  • Date: 2026-11-12

The office system and the driver app run in a browser, on an origin different from the API. A user may belong to several companies and works in one at a time. Sessions must be revocable at once, for example when a user is deactivated.

How does the API know who is calling, and how are cookie sessions protected from requests made by another site?

  • Deactivating a user or signing out ends the session on the next request.
  • Scripts in the page cannot read the credential.
  • No secret whose leak would allow sessions to be forged.
  • Protection against cross-site requests without extra state in the front ends.

For the session:

  1. A random token in an HttpOnly cookie, with only its hash stored in a sessions table.
  2. A signed token verified without the database. Common market alternative, listed for comparison.

For cross-site requests:

  1. SameSite=Lax cookies, plus verification of the Origin and Sec-Fetch-Site headers on methods that write.
  2. A CSRF token in every form and request. Considered and not adopted.

Chosen: option 1 in both.

The session token is random and stored only as a hash (ADR-0018). Each request resolves it through a gate function, which also checks that the user is active. A session lasts 30 days by default and ends after 7 days without use. Over HTTPS the cookie has the __Host- prefix. Passwords are hashed with argon2id, and sign-in attempts are limited per email and per IP address in Redis before the password is verified.

CrossSiteRequestGuard rejects a writing request when the browser reports another site and the origin is not one of the allowed front ends. Requests without Origin and without fetch metadata come from non-browser clients, which carry no ambient cookie, and pass.

The active company is part of the session. The office system sends the header X-Ochema-Tenant with the company the tab is showing, and the API answers 409 tenant_changed when it differs from the session. The header never selects the company.

  • Good, because revocation is deleting a row, effective immediately.
  • Good, because there is no signing secret to protect or rotate.
  • Good, because the front ends carry no CSRF token.
  • Bad, because every request costs a session lookup in the database.
  • Bad, because the protection relies on the browser sending Origin or fetch metadata on cross-site requests.
  • Bad, because a session has one active company: two tabs cannot work in two companies at the same time. The other tab is told that the company changed.
  • Bad, because cookie sessions do not suit calls from other systems. The lead intake API uses API keys instead.
  • apps/api/src/core/auth/session.service.ts and guards.ts: the cookie, SessionGuard and CrossSiteRequestGuard.
  • packages/db/migrations/0003_gate_functions.sql: sign-in lookup and session resolution.
  • apps/api/src/core/rate-limit/rate-limiter.ts: the sign-in limit.
  • packages/app-kit/src/tenant-header.ts: the company header of the apps.
  • Concept page: Authentication and permissions.
  • Related: ADR-0023 for the separate session of the platform team.