Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/better-auth

better-auth

Verified

references/self-hosted-stack.md

View on GitHub
Implementation Plan: Self‑Hosting BetterAuth,

Convex, Supabase PostgreSQL, Hono & TanStack

Start

Architecture Overview

In this unified authentication architecture, BetterAuth acts as the central Identity Provider (IdP) using

OpenID Connect. All components (frontend and backend) rely on BetterAuth for user authentication.

Supabase PostgreSQL (self-hosted) serves as the primary database backing BetterAuth – storing user

accounts, authentication sessions, and any OIDC data (clients, tokens, etc.)

1

. The  TanStack Start

frontend   (React/Solid   SSR   framework)   integrates   with   BetterAuth   for   user   login,   while   the   backend

services (Hono API and Convex) validate and trust BetterAuth-issued tokens for secure interactions.

Key components and their roles:

•

BetterAuth (OIDC Provider): Handles user authentication (email/password, social logins, etc.)

and issues OIDC tokens (ID/Access tokens) via standard flows (e.g. Authorization Code with

PKCE)

2

. It persists user profiles, credentials, sessions, and OIDC client data in Postgres for

reliability

1

.

•

Supabase PostgreSQL: The Postgres database instance that stores BetterAuth’s data (tables for

users, sessions, accounts, etc.) and can also store application data. BetterAuth is configured to

connect to this DB (via a connection URL and credentials)

3

4

. (In our Docker Compose setup,

this is a single Postgres container for simplicity).

•

Hono (Backend API): A lightweight TypeScript web server (running on Node) that implements

business logic. Hono integrates the BetterAuth library as middleware/route handlers, so it
effectively hosts the BetterAuth authentication endpoints (e.g.  /api/auth/*  routes) and also

provides protected application APIs. This means the Hono server will serve login, token, and

userinfo routes via BetterAuth’s handler, and also serve other API routes for the app

5

. All API

routes will require valid BetterAuth tokens.

•

Convex (Self-Hosted Backend): A real-time backend data platform (Convex’s open-source

reactive database) that our app uses for application data and server-side logic. We self-host

Convex as a separate service connected to its own underlying store (we will use the same

Postgres instance for Convex’s data for convenience). Convex is configured to trust BetterAuth

as an OIDC provider, so it will accept BetterAuth’s JWTs to authenticate incoming client requests

6

. This allows Convex functions to know the caller’s identity securely.

•

TanStack Start (Frontend): The front-end application (React/Solid) that interacts with the

backend. It uses BetterAuth for user authentication (either by redirecting to BetterAuth’s hosted

login page or by using BetterAuth’s client utilities) and obtains OIDC tokens upon login. It then

calls the Hono API and/or the Convex backend, presenting the BetterAuth token for

authorization.

Inter-component   trust:  Both   Hono   and   Convex   validate   JWTs   issued   by   BetterAuth   using   OIDC

standards. BetterAuth publishes a JWKS (JSON Web Key Set) endpoint for its signing keys

2

, which

Hono and Convex use to verify token signatures and claims. This means the backend services do  not

manage passwords or separate session stores – they defer to BetterAuth for auth. Convex’s integration

1

specifically   uses   BetterAuth’s  issuer   domain  and   the   client   ID   (audience)   to   validate   ID   tokens

7

,

ensuring tokens are genuine and meant for our application.

Below is a high-level flow of authentication and data calls in this architecture:

1.

User Login (Frontend → BetterAuth): A user on the TanStack Start app initiates login. The
frontend redirects the user to BetterAuth’s OIDC authorization endpoint (hosted by the

BetterAuth service) or invokes the BetterAuth client SDK, which in turn hits the BetterAuth auth

routes. The user provides credentials (or social login) on BetterAuth’s interface.

2.

Authentication & Token Issuance (BetterAuth → Postgres → Frontend): BetterAuth verifies
credentials (e.g. checks email/password) and creates a user session. All user and session data is

persisted in the Postgres DB (for example, new user records or session tokens are stored)

1

.

Upon success, BetterAuth issues an ID token (JWT) and an access token (and possibly a refresh

token) for the user

2

. These tokens are returned to the frontend (either via redirect callback

with an authorization code that the frontend exchanges for tokens, or directly if using an implicit

flow). The ID/Access tokens are signed by BetterAuth and include claims like the user’s ID, the
issuer ( iss  = BetterAuth URL), audience ( aud  = our app’s client ID), and expiration.

3.

Frontend Stores Token & Requests API: The TanStack frontend receives the tokens (or a

session cookie if using cookies) and stores them (commonly in memory or an HttpOnly cookie).

The user is now logged in on the frontend. For any protected data operations, the frontend
includes the access token (usually as an  Authorization: Bearer <token>  header) when

making requests. For example, to call our application’s backend API (Hono) to fetch user data,

the frontend sends the JWT in the header.

4.

Backend API Authentication (Frontend → Hono): The Hono API receives the request with the
user’s JWT. It verifies the token by checking its signature and claims against BetterAuth’s public

keys. Because we use BetterAuth’s OIDC provider, Hono can retrieve the JWKS from BetterAuth’s
.well-known/jwks.json  URL and cache it for token verification
iss  matches the BetterAuth issuer URL and that it’s not expired. (If we configure audience
checking, Hono can also ensure the token’s  aud  matches the expected client/application ID.) If

. Hono ensures the token

8

the token is valid, Hono knows the user’s identity (e.g. user ID from token claims) and authorizes

the request.

5.

Implementation: In our Hono server code, we will likely use a middleware or the BetterAuth
library to protect routes. For example, BetterAuth provides an  auth.handler()  that we
mount on  /api/auth/*  for authentication endpoints

, and we can use its utilities or a JWT

5

verification middleware for other routes. Once verified, Hono’s route handlers can access the

user info from the token (or BetterAuth session) for authorization logic.

6.

Convex Backend Authentication (Frontend → Convex): The TanStack app may also
communicate with Convex directly (using Convex’s client SDK for real-time updates and queries).

We configure the Convex client to supply the BetterAuth ID token on every request. Convex,

running self-hosted, is set up with a Custom OIDC provider config pointing to BetterAuth. This

means Convex knows the BetterAuth issuer domain and our application’s OIDC client ID
(audience), as configured in Convex’s  auth.config.ts

. When the frontend opens a

7

WebSocket or sends an HTTP request to Convex, Convex receives the JWT and validates it against

BetterAuth’s issuer and JWKS keys, just like Hono does

6

. A valid token lets Convex identify the

user (Convex will make the user’s identity available in its server functions securely). If the token is

missing or invalid, Convex denies access. (Note: Alternatively, Hono could act as a proxy to Convex,

but the typical integration is the client communicates directly with Convex using the token.)

7.

Secure Data Access and Interaction: Once the user is authenticated to backend services,

requests proceed to data interactions:

8.

Hono can now perform its API logic. It may read or write data in the Supabase Postgres (for

example, if Hono needs to query relational data or use Postgres for additional storage beyond

2

Convex). The Hono service would use a Postgres client or ORM to query the database. It can

safely use the user’s identity from the token to, say, query rows belonging to that user.

(BetterAuth’s user ID can serve as a foreign key in application tables if needed).

9.

Hono can also call Convex if needed. In cases where our API layer needs to trigger Convex

actions (server-to-server), Hono could call Convex’s HTTP endpoints or use Convex client libraries

on the server. For instance, Hono could forward a request to a Convex function. In doing so,

Hono would include the user’s JWT (or use an admin key if performing privileged actions). This

ensures Convex receives a valid token even for calls initiated server-side.

10.

Convex, upon validating the user via JWT, executes its functions and database operations.

Convex’s state is stored in the underlying Postgres (in a separate schema or database). In our
setup, we’ll create a dedicated database (e.g.  convex_self_hosted ) within the Postgres

instance for Convex to use

9

. Convex will persist and query app data there, and can also

enforce access control within its functions using the user identity from the token.

11.

Response to Frontend: Both backend services then return responses to the frontend. Hono

sends back JSON responses over HTTP (e.g. user profile data, etc.), while Convex’s responses

(queries, reactive updates) flow back over its real-time connection. The frontend now has the

requested data and can render the UI. All interactions were gated by BetterAuth’s authentication,

ensuring the user was authorized at each step.

Throughout   this   flow,  BetterAuth   is   the   single   source   of   truth   for   identity.   If   a   user   logs   out,

BetterAuth can revoke the session or tokens (e.g. a refresh token can be invalidated in the DB). Backend

services could consult BetterAuth’s UserInfo or introspection endpoint (if available) to get additional

user   details   if   needed,   but   in   most   cases   the   JWTs   themselves   contain   needed   info.   The   Supabase

Postgres   persists   all   critical   auth   data   so   that   the   system   remains   stateful   (e.g.   allowing   session

persistence across restarts).

Docker Compose Setup

We will use Docker Compose to orchestrate all components on a common network. Each service runs in

its own container, and we define environment variables, networking, and volumes for data persistence.
Below is a sample  docker-compose.yml  snippet illustrating the setup:

version: '3.8'

services:

db:

image: postgres:15-alpine

# Using Postgres (Supabase-

compatible) for data

container_name: supabase-db

environment:

POSTGRES_USER: postgres

POSTGRES_PASSWORD: <YOUR_DB_PASSWORD>

POSTGRES_DB: postgres

# Default database (used by

BetterAuth)

volumes:

- supabase-data:/var/lib/postgresql/data

networks:

- internal

# (Optional: expose 5432 if you need external DB access)

api:

3

build: ./hono-api

# Hono API + BetterAuth service

(Dockerfile builds the Node app)

container_name: hono-api

depends_on:

- db

- convex

environment:

DATABASE_URL: postgres://postgres:<YOUR_DB_PASSWORD>@db:5432/postgres

BETTER_AUTH_SECRET: <YOUR_AUTH_SECRET>

BETTER_AUTH_URL: http://localhost:4000

# Base URL of the Hono API

service (for BetterAuth config)

10

# OIDC settings, e.g. client IDs, can be set in auth config or env as

needed

networks:

- internal

ports:

- "4000:4000"

endpoints) on port 4000

convex:

# Expose Hono (and BetterAuth

image: ghcr.io/get-convex/convex-backend:latest

container_name: convex-backend

depends_on:

- db

environment:

DATABASE_URL: postgresql://postgres:<YOUR_DB_PASSWORD>@db

#

Convex will use Postgres; ensure DB exists

9

# (No DB name here because Convex expects a default; we'll create a

'convex_self_hosted' DB in the Postgres service)

CONVEX_CLOUD_ORIGIN: http://convex:3210

# Convex internal URL

for core service

CONVEX_SITE_ORIGIN: http://convex:3211

# Convex internal URL

for HTTP actions

# (Above origins default to localhost; here we set them to container

name for clarity on the network)

networks:

- internal

ports:

- "3210:3210"

(database queries, etc.)

- "3211:3211"

# Convex client connection

# Convex HTTP endpoints (actions, webhooks)

# (Optional: expose dashboard on 6791 if using convex-dashboard

container)

frontend:

build: ./tanstack-start

# TanStack Start SSR app (Node

server or static build)

container_name: tanstack-frontend

depends_on:

- api

4

environment:

PUBLIC_AUTH_URL: "http://localhost:4000/api/auth"

# URL to BetterAuth endpoints (through Hono)

PUBLIC_API_URL: "http://localhost:4000/api"

# Base URL for Hono API

PUBLIC_CONVEX_URL: "http://localhost:3210"

# Convex URL for

client SDK

# OIDC client ID, redirect URIs could be configured here if needed

networks:

- internal

ports:

- "3000:3000"

3000 for users

# Expose frontend (SSR) on port

# (If TanStack Start is purely static, you might serve it differently)

networks:

internal:

driver: bridge

volumes:

supabase-data:

Networking: All services join the  internal  network, which allows them to communicate by container
name. For example, the Hono service can reach Postgres at host   db:5432 , and Convex can reach

Postgres at the same hostname. In the Compose file, we set environment URLs accordingly (e.g. the
DATABASE_URL   for BetterAuth uses host   db ). We expose only the needed ports to the host: - The

frontend (TanStack Start) is exposed on port 3000 (for users to access the web app). - The Hono API

(which   also   hosts   BetterAuth’s   OIDC   endpoints)   is   on   port   4000.   -   The  Convex   backend  exposes
3210/3211 for client connections. The frontend will connect to Convex at  localhost:3210  (mapped

to the convex service). - The  Postgres  service is  not  exposed to the host (for security), but you can

expose 5432 if you need direct database access for admin tasks. It’s confined to the internal network for

use by BetterAuth and Convex.

Environment Variables & Secrets: We use environment variables to configure each service securely: -
Postgres   ( db   service):  Set   a   strong   POSTGRES_PASSWORD .   (In   a   production   setup,   also   consider
using   Docker   secrets   for   the   password).   The   volume   supabase-data   ensures   data   is   persisted
between container restarts. - BetterAuth (within  api  service): -  DATABASE_URL : Connection string
.   This   points   to   the   db   service   and   includes   the
for   the   Postgres   DB   that   BetterAuth   will   use
credentials.   In   our   example,   BetterAuth   will   store   its   tables   in   the   default   postgres   database.
(Optionally, you could set   POSTGRES_DB: auth   on the db service and use that for BetterAuth, to
separate it from other data.) -  BETTER_AUTH_SECRET : A secret key for BetterAuth used for encryption/
. This should be a long random string (you can generate one with  openssl rand -hex

hashing
32   or use BetterAuth’s CLI)
. It’s critical to keep this secret consistent across deployments (so that
session tokens/hashes remain valid) and  never expose it publicly. -   BETTER_AUTH_URL : The base

10

3

4

URL of the application (used by BetterAuth for OIDC issuer identification, callback URLs, etc.)

10

. In

development we set it to localhost (as shown). In production, this would be your API’s external URL (e.g.
https://api.myapp.com ). This ensures tokens have the correct issuer and any absolute URLs in

emails or redirects are correct. - OIDC Client config: If using BetterAuth’s OIDC provider plugin, you will

configure OIDC clients. For example, you might register the frontend as a public client in BetterAuth
(with a client ID like  tanstack_frontend  and redirect URI  http://localhost:3000  for dev). This

5

can be done via BetterAuth’s API/CLI

11

, or by adding a config snippet. In a simple setup, you might

not need to set these as env vars – you could register clients in code or at runtime. Ensure that the

client ID (audience) you use here is the same one Convex expects (we will configure Convex with it as

well). - Trusted Origins (CORS): In the BetterAuth config, specify the allowed origins for requests. We
include the frontend’s origin here. For example, in code:  trustedOrigins: ['http://localhost:
3000']   to   allow   the   dev   server’s   origin

.   This   is   important   for   security   –   BetterAuth   will   block

12

requests (like XHR for token refresh or login) from origins not listed
. In our integration, because we
serve BetterAuth through Hono at the same origin as the API, the frontend will be calling   http://
localhost:4000   from   http://localhost:3000 ,   so   we   need   http://localhost:3000   as   a
trusted origin. -  Convex ( convex   service):  -   DATABASE_URL : Tells Convex to use Postgres for its

13

storage (instead of the default SQLite)

9

. We provide the connection without a database name so that

Convex will use the default and look for (or create) its own DB. Convex by default uses a database
named  convex_self_hosted  in the Postgres instance
. We must ensure this exists – we can do so
by extending our Compose setup: for example, add an initialization script in   docker-entrypoint-
initdb.d  for the Postgres service to create that database. (Alternatively, manually connect once and
create   the   DB.)   For   clarity,   you   could   also   use   POSTGRES_DB:   convex_self_hosted   in   the

14

environment, but that would set the default database for the Postgres container itself; better to create

an   additional   DB   for   Convex   explicitly.   -  Convex   Auth   Config:  In   Convex   application   code   (not   an
environment variable), we set up   auth.config.ts   to recognize BetterAuth. We add an entry with
domain: "<BetterAuth Issuer URL>"   and   applicationID: "<OIDC Client ID>"
. For
example, if BetterAuth’s issuer is  http://localhost:4000  (as set by  BETTER_AUTH_URL ) and the
client   ID   for   our   frontend   is   tanstack_frontend ,   we   put   those   in   Convex’s   config.   This   ensures
Convex   will   accept   tokens   where   iss   matches   the   BetterAuth   URL   and   aud   matches
. (If BetterAuth’s ID tokens do not include an   aud , or you want to accept
tanstack_frontend

15

7

tokens without strict aud matching, Convex also supports a custom JWT mode

16

  – but using proper

OIDC fields is recommended.) - No sensitive secret is needed for Convex here (except the DB password

which is already in the connection string). However, Convex does have an  admin key  for deploying

updates or using the dashboard. We will generate this key after the container is running (using the
provided script  ./generate_admin_key.sh  inside the convex container)

. That key can be set as

17

an   environment   variable   or   provided   when   using   the   Convex   CLI   to   deploy   function   code.   For   this

architecture, the admin key is not directly involved in runtime auth flow, so we simply note that it should
be kept secret if used. - Frontend ( frontend  service): - We pass configuration for the frontend app to
know how to reach the other services. For example,  PUBLIC_AUTH_URL  is the endpoint of BetterAuth’s
routes.   In   development   it   might   be   http://localhost:4000/api/auth   (pointing   to   Hono),   as

shown above. This could be used by a BetterAuth client SDK on the frontend to direct login requests.
  PUBLIC_API_URL   could   be   used   for   constructing   REST   API   calls   to   Hono,   and
Similarly,
PUBLIC_CONVEX_URL   for Convex. - If the TanStack Start app needs to know the OIDC  client ID  or

redirect   URL,   those   can   be   baked   into   the   app   or   provided   via   env.   Typically,   you’ll   configure   the

BetterAuth client library in the frontend with the issuer and client ID. For instance, if using BetterAuth’s

client plugin, you might instantiate it with the known config (client ID, issuer, scopes). - The TanStack

Start  framework  supports  server-side  rendering  and  server  functions,  so  it  might  also  interact  with

BetterAuth on the server side. In a full SSR scenario, instead of using the BetterAuth endpoints directly

from the browser, the SSR server could handle the OAuth redirect callback: e.g., the user is redirected

back to a TanStack Start server route, which then calls BetterAuth (via Hono) to exchange the auth code

for tokens and set an HttpOnly cookie for the session. This approach would involve the frontend talking

“through” the backend for auth. We’ll discuss this in the next section.

All services share the  internal  network, allowing them to refer to each other by service name (e.g.,
db ,   api ,   convex ,   etc.).   We’ve   used   depends_on   to   ensure   that,   for   example,   the   Hono   API

doesn’t start before the database and Convex are up.

6

Volumes: We defined a named volume  supabase-data  for Postgres data persistence. You might also

mount volumes for any service that needs to persist data (Convex stores most data in Postgres, but if it

used any local disk for e.g. search indexes or files, you’d mount those too). The Convex container’s
data  volume (for SQLite or other ephemeral data) is less crucial if using Postgres, but the Compose

file we based on uses an in-container volume for any data directory by default

18

19

. In our case, the

critical persistence is already handled by Postgres.

Authentication Flow Details

To   ensure   clarity,   here’s   a   step-by-step   authentication   flow   from   the   frontend   to   backend   in   this

integrated system:

1.

User Initiates Login: The user navigates to the TanStack Start frontend. If not authenticated, the

frontend (TanStack app) will present a login option. When the user clicks “Login,” the app triggers

BetterAuth’s authentication flow. This could happen via redirect – e.g., the app redirects the
browser to  http://localhost:4000/api/auth/sign-in  (the BetterAuth sign-in page

served by Hono), or opens a pop-up. Alternatively, if using BetterAuth’s JavaScript client, it may

perform a fetch to the auth endpoint. Either way, the user is now interacting with BetterAuth
(through the Hono service) for credentials. The BetterAuth service (on the  /api/auth  routes)

serves the login form (or forwards to an identity provider if using social logins).

2.

BetterAuth Authenticates User: The user enters credentials (for example, email and

password). BetterAuth verifies these – possibly consulting the Postgres DB for the user’s hashed

password and checking it. On success, BetterAuth creates a new session entry in the database

(recording the user ID, session token, expiration, etc.)

20

21

. If using an OIDC code flow,

BetterAuth now generates an authorization code. If using an implicit flow or BetterAuth’s own

session mechanism, it might directly create a JWT and a session cookie. Assuming Authorization
Code Flow: BetterAuth redirects the user back to a specified callback URL (e.g.,  http://
localhost:3000/auth/callback  on the frontend) with the authorization code.

3.

Token Issuance (OIDC Code Exchange): The TanStack frontend (or its SSR server) handles the

callback. If the code is returned to the frontend app (browser), the app now makes a back-
channel request to BetterAuth’s token endpoint ( /api/auth/callback  or
/api/auth/token ) to exchange the code for tokens. Often this request is done by the frontend

server to keep the client secret safe (for confidential clients). In our setup, since the frontend is a

public client (no secret in browser), we can use PKCE. The frontend sends the code + PKCE

verifier to BetterAuth (again hitting the Hono API’s auth route). BetterAuth validates the code

and responds with an ID token (JWT) and access token, and possibly a refresh token
ID token contains the user’s identity claims (e.g.,  sub  claim as user ID, email, etc.), and the

2

. The

access token is typically a shorter-lived JWT meant for resource server authorization.

4.

Frontend Stores Credentials: The frontend now has the tokens. If TanStack Start has an SSR

component, it might set an HttpOnly cookie with the access token or a session identifier at this

point (particularly if the SSR server did the token exchange, it can set a cookie on the app’s

domain). Alternatively, in a pure SPA scenario, the tokens might be stored in memory or

localStorage (though http-only cookies are more secure). The user is now logged in from the

frontend’s perspective.

5.

Frontend Calls Protected APIs: The user interacts with the app (e.g., clicking a “Load my profile”

button). The frontend needs data from the backend, so it makes a request to Hono’s API (for
example,  GET /api/profile ). It includes the access token in the  Authorization  header:
Bearer <JWT> . If we opted to use cookies for auth, the cookie (containing a session or token)

would be automatically sent. The frontend may also initiate a connection to Convex at this point

7

(the Convex client library will take the ID token and call  ConvexClient.setAuth(token)  to

include it in its WebSocket communications).
Hono API Verifies Token: The Hono server receives the API call at  /api/profile  (for

6.

instance). We have secured this route by requiring authentication. In the Hono code, before

reaching the handler, a middleware (or the handler itself) uses BetterAuth to verify the request. If
we integrated BetterAuth fully, we might call  auth.getSession()  or similar to validate any

session cookie, or we manually validate the JWT. JWT validation involves checking the signature
with BetterAuth’s public key. Hono fetches the JWKS from BetterAuth’s  .well-known  endpoint

(if not cached)
verify the JWT signature. It also checks that the token has not expired ( exp  claim) and that the

, and finds the key that matches the token’s  kid . It then uses that key to

8

issuer matches our BetterAuth URL and audience matches our client ID (if we configured Hono

to expect a certain aud). With a valid token, Hono knows the user is authenticated. It may then

decode the JWT to get the user’s ID and any claims (like roles or permissions if included) to

authorize the specific action.

7.

Convex Verifies Token (if accessed): Meanwhile, if the frontend opened a Convex connection or

called a Convex function, the Convex backend performs a similar verification. Convex’s server
(running in the  convex  container) inspects the token sent by the Convex client. According to
our Convex auth config, it expects  iss == http://localhost:4000  (BetterAuth) and  aud
== tanstack_frontend  (for example). It finds the token satisfies these (BetterAuth issued it

with that audience). Convex then uses the cached JWKS for BetterAuth to verify the token’s

signature as well

6

. (Convex caches the JWKS from the domain given in config; BetterAuth’s

OIDC plugin exposes the JWKS URL by default under the base auth URL

22

.) If valid, Convex

establishes an authenticated session for the client connection, associating it with the user
described in the JWT. From now on, any Convex function can call  auth.getUser()  (or similar)

to get the user’s ID and claims, knowing they were validated.

8.

Backend Processes Request: The Hono API handler now executes the requested operation (e.g.,

fetch user profile). It might query the Postgres database (since BetterAuth stores user info

there, Hono could even join additional data from user profiles table, etc.). For example, Hono
could run a SQL query on the  users  table (populated by BetterAuth) or on another table that
references  users . Since Hono trusts the user’s identity from the token, it can safely use the
userId  to query only that user’s data. Hono could also call a Convex function from the server

side – for instance, if some data is in Convex, Hono might use the Convex HTTP API to retrieve it.

In that case, Hono would include either an admin auth (to call Convex as a privileged service) or

forward the user’s token in the request to Convex. For simplicity, our architecture leans toward

the frontend calling Convex directly, but these options exist for server-to-server communication.

9.

Responses Sent Back: After performing the logic, Hono sends the HTTP response (e.g., JSON

with profile data) back to the frontend. Convex, if queried, sends its response data (over the

WebSocket or HTTP response for a function call) back to the frontend as well. The TanStack

frontend now has the data it needs. From the user’s perspective, they seamlessly fetched

protected data after logging in. All subsequent interactions follow a similar pattern: the frontend

presents a token, backends verify it. When the token expires, BetterAuth’s refresh token can be
used by the frontend (likely via a silent refresh call to  POST /api/auth/session/refresh  or

similar) to get a new token, which again involves checking the session in the database. This

keeps the user logged in without re-entering credentials, until logout.

Throughout these steps,  BetterAuth is the core  that ties everything together: it provided the tokens

that   both   Convex   and   Hono   rely   on   for   authenticating   requests.   Supabase   Postgres   ensures   that

BetterAuth’s state (users, sessions, etc.) is consistent and durable. Convex and Hono do not need their

own user databases – they refer to the identity in the BetterAuth token and can, if needed, query the

central user info stored in Postgres (for example, Hono could query additional user profile fields in

Postgres, or Convex could periodically sync certain user data).

8

This flow shows a division of concerns: BetterAuth handles auth, Convex handles real-time data logic,

Hono  handles RESTful API and any server-side rendering or integration logic, and  Postgres  persists

data. All components communicate over the internal Docker network securely, and external exposure is

limited to the necessary endpoints for the end-user.

Frontend Integration: Direct vs. Proxy communication with

BetterAuth

One important consideration is whether the frontend should communicate directly with the BetterAuth

service or go through the Hono backend for authentication flows. We have two possible approaches:

•

Direct   Frontend   ↔   BetterAuth   communication:  In   this   model,   the   frontend   (TanStack   app

running in the browser) talks to BetterAuth’s endpoints directly (which could be on a separate
subdomain or port, e.g.   auth.myapp.com   or   localhost:4000 ). This is analogous to how

one might use an external provider like Auth0 – the SPA redirects to Auth0 and gets tokens from

it.   The   advantage   is   that   the   authentication   flow   is   handled   by   the   dedicated   auth   service

(BetterAuth)   and   the   frontend   obtains   tokens   to   use   on   other   APIs.   This   can   simplify   token

exchange in a public client scenario (BetterAuth’s OIDC plugin supports public clients for SPA/

mobile

23

). However, it does introduce  cross-origin considerations. We must enable CORS in

BetterAuth for the frontend origin, and the redirect URIs must be configured. In our setup, since

BetterAuth is actually served via the Hono container (on port 4000), “direct” means the browser
calls  localhost:4000  from an app served on  localhost:3000  – which is cross-origin. We
handle   this   by   setting   trustedOrigins:   ['http://localhost:3000']   in   BetterAuth,
which ensures the proper   Access-Control-Allow-Origin   headers and prevents CSRF

12

13

. In production, this list would include your actual frontend URL(s). The direct approach keeps

the backend (Hono) mostly out of the login process (aside from hosting the endpoints), and the

frontend deals with tokens.

•

Frontend   ↔   Hono   (Proxy)   ↔   BetterAuth:  In   this   approach,   the   frontend   communicates   with

BetterAuth  through  the   Hono   backend   (which   is   possible   since   BetterAuth   is   integrated   into

Hono). Essentially, the Hono server acts as an intermediary or even handles the auth flow server-

side. For example, instead of the SPA doing a OAuth code exchange, the frontend could simply
hit an endpoint on Hono (e.g.  /api/auth/login ) and Hono could perform a server-side OIDC

flow then set a cookie for the frontend. TanStack Start, being a full-stack framework, supports

server-side logic – we could leverage that to manage auth. The potential benefit here is security

and simplicity for the client: the frontend doesn’t need to handle tokens explicitly; Hono could

issue   an   HttpOnly   session   cookie   (containing   the   BetterAuth   access   token   or   a   session

reference).   This   cookie   would   be   on   the   frontend’s   domain,   making   API   calls   automatically

include  it,  and  Hono  can  validate  the  cookie  via  BetterAuth.  This  approach  is  similar  to  how

Next.js with NextAuth might operate – the backend takes care of exchanges and the client just

gets a cookie. It can also avoid storing tokens in JavaScript memory at all (reducing XSS risk).

Another benefit is that all auth traffic stays on the same origin (the frontend domain or API

domain), so CORS issues are minimized.

Recommendation – Hybrid Approach:  Given our architecture, we have  already integrated BetterAuth

with Hono, meaning the distinction between “direct” and “through Hono” is somewhat blurred – the

frontend’s requests to BetterAuth endpoints are in fact going to the Hono service (which routes them to

BetterAuth handler). In development, this is just a different port, but in production we might deploy
Hono and frontend under a single domain (e.g.,  api.myapp.com  hosting both API and auth, with the
frontend app at  myapp.com  or another domain).

9

For a smooth implementation,  we recommend using the frontend’s server capabilities (TanStack

Start’s SSR) to handle the OAuth callback through Hono, resulting in an HttpOnly cookie for the

session.   In   practice,   this   means   the   frontend   will  redirect   the   user   to   BetterAuth’s   sign-in   page

(direct) for login, but the return callback will be caught by a TanStack Start server route which then talks

to BetterAuth’s token endpoint (server to server). This yields tokens which the server can set as a secure

cookie. Subsequent frontend calls to the API will include this cookie (same-site or same-domain), and

Hono can verify the session via BetterAuth. This approach offloads complexity from the client code (no

manual JS token storage) and centralizes auth logic in the backend. It also mitigates cross-origin issues

– the only cross-origin navigation is the initial redirect for login, which is normal in OIDC. All XHR/fetch

calls after login would be same-origin (frontend <-> Hono).

If we wanted to avoid even the initial cross-origin redirect, an alternative is to have the frontend call a

Hono endpoint to initiate login (Hono could then redirect the user to BetterAuth, acting as a proxy).

However, this is usually unnecessary overhead; it’s standard to let the browser redirect to the IdP for

authentication.

In summary, the frontend should talk to BetterAuth’s OIDC endpoints through the Hono service –

and since Hono hosts those endpoints, the difference between direct and proxy is minimal. We ensure

that: - The frontend is configured with the correct base URL for BetterAuth’s endpoints (in our example,
http://localhost:4000/api/auth ). This allows the front-end to know where to send the user for

login or which URL to use for token refresh calls. - We include the frontend’s origin in BetterAuth’s
trustedOrigins   so that any direct XHR communication is allowed

. - For production, consider

13

using the backend to manage tokens and set cookies. This means the TanStack Start server would need

credentials   to   communicate   with   BetterAuth   (client   ID   &   secret   if   using   confidential   flow).   Given

BetterAuth supports first-party integration, this is feasible.

By following this plan, the TanStack Start frontend will have a robust authentication setup where it

either uses BetterAuth’s client SDK or simple redirects to log users in, and all subsequent interactions

with Convex or Hono will automatically carry the user’s identity. The decision to go “direct vs through

Hono” essentially boils down to where token exchange happens: our recommendation is to perform

token   exchange   and   storage   on   the   server   side   (through   Hono),   which   provides   better   security.

Regardless,   both   methods   rely   on   BetterAuth   as   the   single   auth   provider   and   thus   will   function

correctly.

Conclusion

This implementation combines the strengths of each component:  BetterAuth  for flexible, self-hosted

authentication   (with   OIDC   capabilities),  Supabase   Postgres  for   a   reliable   data   store,  Convex  for   a

reactive   backend   datastore,  Hono  for   a   fast   API   layer,   and  TanStack   Start  for   a   modern   full-stack

frontend. By using Docker Compose, we ensure these services run together and can communicate over

a   secure   internal   network.   Each   service   is   configured   with   the   necessary   environment   variables

(database URLs, secrets, client IDs) and appropriate Docker networking so they can discover each other
(using service names like  db ,  api , etc.).

Security is maintained at each boundary: - All passwords/secrets (DB password, BetterAuth secret, any

OAuth   client   secrets)   are   kept   out   of   source   code   and   injected   via   environment   variables

3

4

(consider using Docker secrets or environment files with proper .gitignore in place). - Communication

between   services   does   not   leave   the   Docker   network   –   e.g.,   Hono   queries   the   database   directly,

avoiding   external   exposure.   -   The   frontend   and   API   can   be   configured   with   TLS   (outside   of   Docker

10

Compose   scope,   typically   via   a   reverse   proxy   like   Nginx   or   Caddy   in   front   of   these   containers   in

production).

With this setup, when a user registers or logs in via BetterAuth, their data is stored in Postgres and an

OIDC session is established. The frontend can retrieve application data through Convex or Hono, and

both   of   those   trust   BetterAuth’s   tokens   to   authenticate   requests.   This   unified   approach   avoids

duplicating user management in multiple services and provides a clear separation of concerns:

•

BetterAuth + Postgres: Identity and session management (authentication).

•

Convex: Application data and real-time updates (with built-in auth via OIDC tokens).

•

Hono + BetterAuth (mounted): API gateway/business logic, also serving auth endpoints for

BetterAuth.

•

TanStack Start: Frontend UI/UX, utilizing the backend services securely.

By   following   this   plan   and   using   the   sample   Compose   configuration   as   a   starting   point,   you   can

implement   a   cohesive,   self-hosted   system   where   users   authenticate   once   via   BetterAuth   and   gain

secure access across your frontend and backend components. The result is a scalable and maintainable

architecture   with   centralized   auth   and   seamless   integration   between   the   modern   tech   stack

components.

References:

•

BetterAuth documentation on using PostgreSQL and configuration

, and OIDC plugin
. BetterAuth’s integration with Hono (example showing  trustedOrigins  and

features

2

4

3

route mounting)

12

5

.

•

Convex documentation for custom OIDC integration and self-hosting details

7

6

9

. These

show how Convex accepts ID tokens from an OIDC provider and how to configure a Postgres DB

for Convex.

•

Docker Compose configuration and environment setup for Convex’s self-hosted backend (open-

source)

9

24

, which guided our Compose file structure.

1

20

21

Installation | Better Auth

https://www.better-auth.com/docs/installation

2

8

11

23

OIDC Provider | Better Auth

https://www.better-auth.com/docs/plugins/oidc-provider

3

4

How to connect to your Supabase Database using Better-Auth | by Joshua K Barua | Medium

https://medium.com/@joshua.k.barua/how-to-connect-to-your-supabase-database-using-better-auth-aa6be3e985e1

5

10

12

13

Better Auth - Hono

https://hono.dev/examples/better-auth

6

7

15

16

22

Custom OIDC Provider | Convex Developer Hub

https://docs.convex.dev/auth/advanced/custom-auth

9

14

17

Self-Hosting with Convex: Everything You Need to Know

https://stack.convex.dev/self-hosted-develop-and-deploy

18

19

24

raw.githubusercontent.com

https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml

11

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall