Skip to content

ADR-0018: Public tokens stored only as hashes

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

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?

  • 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.
  1. A random token given to the holder, with only its SHA-256 stored.
  2. The token stored as text. Obvious alternative, listed for comparison.
  3. A signed token that carries its own data and is verified without the database. Common market alternative, listed for comparison.

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.

  • 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.
  • packages/db/src/tokens.ts: createToken and hashToken.
  • 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.