Auth model
Current state
Today,apps/backend/src/index.ts exposes the Hono app with the route handlers that have already shipped — primarily OpenAPI and a small set of placeholder endpoints. There is no auth route, no session middleware, and no user record persistence in code. The Cloudflare Worker runs without an authentication layer.
| Capability | Status today |
|---|---|
| Authentication routes | Not implemented |
| Session middleware | Not implemented |
| User record persistence | Not implemented |
| OAuth provider wiring | Not implemented |
| Consent category gating on routes | Consent contract authored; not yet enforced |
Intended model
When auth lands, Clay adopts a B2C, owner-of-vault model. Each person is the sole owner of their vault, their translated signals, and their consent grants. Sharing requires explicit, reversible permission per category. The candidate library for implementation is Better Auth — a TypeScript-native auth framework with first-class Hono integration, broad OAuth provider coverage, and a database adapter layer that pairs naturally with the intended Hyperdrive boundary. The vendor snapshot atdocs/vendor/better-auth/llms.txt is the reference material; no code depends on it yet. See
Reference materials below for the snapshot location and refresh workflow.
Better Auth is the candidate, not a commitment. The contract on this page describes what
Clay’s auth needs to do, not which library will do it. If a different auth implementation lands
first, the model on this page stays the same; only the implementation changes.
Properties the implementation must satisfy
Owner-of-vault
Each authenticated principal is the sole owner of their personal knowledges, intentions, and
personality signals. No co-tenant, no shared-ownership path.
Consent-gated sharing
External sharing — fit briefs, intro drafts, taste signals — requires an explicit, scoped grant
from the owner. Categories and recipients are surfaced at the moment of share and are
reversible.
Server-side session authority
Sessions live on the server. The client receives an opaque cookie or token; the server is the
source of truth for who is currently authenticated.
OpenAPI-aligned route surface
Auth routes are registered through the same Hono +
@hono/zod-openapi pattern as the rest of
the backend. Schemas are exported with the rest of the OpenAPI document.Consent categories
Auth does not replace the consent contract. The intended auth surface exposes the consent categories as first-class grants, so the server can refuse a request that depends on a category the user has not enabled.| Category | Auth-level concern |
|---|---|
| Check-ins | Permission to push notifications and outbound messages. |
| Opportunity suggestions | Permission to read vault content when producing fit briefs. |
| Introductions | Permission to write draft shares to external recipients on the user’s behalf. |
| Reminders | Permission to schedule and trigger follow-up nudges. |
| Debriefs | Permission to ask for outcome checks after accepted opportunities. |
Data residency rules
User-owned data stays in the user vault
Auth credentials, session records, and personal knowledges live in the same database boundary as
the rest of the user’s data. There is no separate auth silo.
Worker runtime is stateless
The Cloudflare Worker holds no long-lived user state between requests. Sessions resolve through
the database on each call.
No raw database URLs in source
Auth code reaches the database through the intended Hyperdrive binding, never through a raw
connection string committed to the repo.
OAuth provider data is scoped
When an OAuth provider is wired, the scopes Clay requests must be the minimum needed for the
intended features. Broader scopes require a written justification in the matching ADR.
Acceptance criteria
The auth contract is considered implemented only when all of the following are true in code, not just in this page:Auth routes exported through OpenAPI
Sign-in, sign-out, session, and account-management routes appear in
openapi/openapi.yaml and
pass redocly lint.Session middleware on protected routes
Route handlers that read or write vault content reject anonymous requests with a documented
error shape.
Consent category enforcement
A request that depends on a revoked consent category is rejected before any side effect.
Database boundary wired through Hyperdrive
The auth code reads and writes through the intended Hyperdrive binding. No raw connection string
is committed.
Reference materials
The Better Auth vendor snapshot lives in the canonical Clay repository atdocs/vendor/better-auth/llms.txt (and per-page Markdown in docs/vendor/better-auth/docs/). It is
refreshed from the official https://better-auth.com/llms.txt source and tracked by
docs/vendor/manifest.json. Treat the snapshot as offline reference material, not as the
authoritative source — the official Better Auth documentation is canonical when the two disagree.
See the root AGENTS.md for the refresh workflow.
Related
Consent
The translated-signals rule and the consent categories auth must respect.
Backend overview
The Hono + OpenAPI layout auth will plug into.
Architecture
The intended Hyperdrive boundary and Worker runtime auth will share.
CI and local validation
The scripts that gate the auth code change once it lands.