ADR-0018: Public tokens stored only as hashes
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”Many things in Ochema are proven by possession of a secret value: the session cookie, an invitation, a password reset, the link to resume an application, a scheduling link, an unsubscribe link, the reply address of a conversation, a calendar feed, the full application link, the candidate area, a signing link, a request to a previous employer and the lead intake API keys.
How are these values kept on the server?
Decision drivers
Section titled “Decision drivers”- Reading the database must not give anyone a working link, session or key.
- Revoking must take effect on the next request.
- One way of doing it for every kind of token.
Considered options
Section titled “Considered options”- A random token given to the holder, with only its SHA-256 stored.
- The token stored as text. Obvious alternative, listed for comparison.
- A signed token that carries its own data and is verified without the database. Common market alternative, listed for comparison.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
The API draws a random token of 128 or 256 bits, depending on the kind, and stores only its SHA-256 in a 32-byte token_hash column. The raw value exists only where it is delivered: the cookie, the link in a message or the screen that shows a new API key once. A request presents the token, the API hashes it, and the lookup is by hash. On public paths that lookup is a gate function, see ADR-0003.
Two rules follow from the same decision. An invitation or reset token travels in the body of a request to the API, never in an API address. The stored text of a message keeps [link] in place of an address that carries a token: the real link is made when the message leaves.
Identifiers that are public by nature, such as the careers slug of a company and the code of a short link, are not secrets and are stored as text.
Consequences
Section titled “Consequences”- Good, because a copy of the database contains no usable token.
- Good, because revoking or expiring is a change of one row and is immediate.
- Bad, because a link cannot be shown again after it is created. Getting it again means generating a new one, which for the candidate area and for a signing request invalidates the previous link.
- Bad, because every request with a token costs a database lookup.
- Bad, because the message history shows
[link], not the address the person received.
More information
Section titled “More information”packages/db/src/tokens.ts:createTokenandhashToken.packages/db/src/context.ts: the public context keys that take a token hash.apps/api/src/modules/platform-messaging/message-links.ts: the[link]placeholder in stored messages.- Concept pages: Authentication and permissions, Tenant isolation.
- User guide: Limits lists how long each link is valid.
- Related: ADR-0024.