ADR-0024: Opaque cookie sessions with origin checks
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”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?
Decision drivers
Section titled “Decision drivers”- 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.
Considered options
Section titled “Considered options”For the session:
- A random token in an HttpOnly cookie, with only its hash stored in a
sessionstable. - A signed token verified without the database. Common market alternative, listed for comparison.
For cross-site requests:
SameSite=Laxcookies, plus verification of theOriginandSec-Fetch-Siteheaders on methods that write.- A CSRF token in every form and request. Considered and not adopted.
Decision outcome
Section titled “Decision outcome”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.
Consequences
Section titled “Consequences”- 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
Originor 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.
More information
Section titled “More information”apps/api/src/core/auth/session.service.tsandguards.ts: the cookie,SessionGuardandCrossSiteRequestGuard.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.