Building the foundation Claudius runs on

Néstor Daza details the authentication and provisioning foundation for Claudius, his Claude-based chatbot, in the third part of a tutorial series. The system uses Auth.js v5 with Google OAuth and a MongoDB adapter, resolving user roles server-side with a clear precedence: admin email, member allowlist, then guest. Roles are cached in a JWT, and provisioning uses an aggregation pipeline with $ifNull to set defaults without overwriting admin changes.

This tutorial was written by Néstor Daza. This is the third article in a series about building Claudius, my own Claude-based chatbot Github . The previous article discussed the MongoDB data model to use for the app. The previous article https://dev.to/mongodb/no-messages-table-the-data-model-behind-my-own-claude-based-chatbot-54jp decided the shape of the data. None of it matters until the app around it is working, and getting it there is the unglamorous half of this phase. It comes down to three things: an identity system the client cannot tamper with, proof that Claudius can reach the two services it depends on, and the deployment realities that decide whether any of it runs at all. This is the boring work that quietly decides whether a project survives contact with production. Any Google account on Earth can sign into Claudius safely because a user's role is never something the client sends. It is decided on the server every time. One piece of this lives outside the code. The Google provider needs an OAuth Open Authorization client that you register once in the Google Cloud Console, and the client identifier and secret from that registration are set in corresponding env variables. These setup steps live in the Auth.js and Google documentation, so I am not repeating them here. Sign-in runs on Auth.js v5 with the Google provider and the MongoDB adapter. There are three roles, admin, member, and guest, and they resolve in exactly one place on the server, with a clear precedence: export async function resolveRole email: string | null | undefined : Promise<Role { if email return "guest"; const normalized = email.toLowerCase ; if normalized === env.ADMIN EMAIL.toLowerCase return "admin"; const settings = await settingsCol ; const allowlist = await settings.findOne { id: "allowlist" } ; if allowlist && "emails" in allowlist { const allowed = allowlist.emails.some e = e.toLowerCase === normalized ; if allowed return "member"; } return "guest"; } The bootstrap admin email wins outright, an allowlist of member emails in the settings collection comes next, and everyone else falls through to guest, the least-privileged default. The client supplies a Google identity and nothing more. It never names its own role, so there is no request a user can forge to promote themselves. The session uses a JWT JSON Web Token rather than a database-backed session, so the resolved role is stored in the token and is available without a database read on every request. That choice has one small downside: the token caches the role until it refreshes, so adding someone to the member allowlist takes effect on their next sign-in, not the moment you edit the list. For a personal project, that is a fine trade. The wiring is small: on first sign-in, the jwt callback calls provisionUser and stores the returned role on the token, and the session callback then copies it onto session.user for the app to read. Provisioning is the other half of sign-in. The adapter has already written a bare user document, just the name, email, and image Google returns. It fills in the Claudius-specific fields with a single aggregation-pipeline update built around $ifNull , so each field defaults only when it is absent, and an admin's later change is never overwritten. The role is the exception, recomputed every time, since that is the field on which the whole security model rests: export async function provisionUser userId: string, email: string | null | undefined, : Promise<Role { const role = await resolveRole email ; const users = await usersCol ; const resetsAt = new Date Date.now + 24 60 60 1000 ; await users.updateOne { id: new ObjectId userId }, { $set: { role, allowedModels: { $ifNull: "$allowedModels", null }, monthlyTokenBudget: { $ifNull: "$monthlyTokenBudget", null }, status: { $ifNull: "$status", "active" }, dailyMessageCount: { $ifNull: "$dailyMessageCount", { count: 0, resetsAt } , }, }, }, ; return role; } One TypeScript detail in this layer was a bit of a pain. Augmenting the session type works through the next-auth module as you would expect, but the JWT type does not It is only re-exported from next-auth/jwt and lives in @auth/core/jwt , so a declaration written against next-auth/jwt silently fails to merge, and the token field you were trying to type lands as unknown instead. You have to target the real module: declare module "next-auth" { interface Session { user: { id: string; role: Role; } & DefaultSession "user" ; } } // JWT lives in @auth/core/jwt; next-auth/jwt only re-exports it, so the // augmentation must target the real module to merge rather than shadow. declare module "@auth/core/jwt" { interface JWT { uid?: string; role?: Role; } } That silent failure is the worst kind: when there are no errors, the type just quietly goes wrong. The last piece of the skeleton is a single protected route that proves the app can talk to the things it depends on. Any signed-in role can call /api/health . It always pings Atlas, and given ?probe=bedrock it goes one step further and makes a one-token Converse call against Claude Haiku 4.5, to prove the credentials can invoke a real model. The probe is the interesting part: capped at a single output token, wrapped so no AWS internals leak back to the caller, and returning the counts read from the Converse usage metadata. export async function bedrockHealthProbe : Promise<BedrockHealth { try { const llm = new ChatBedrockConverse { model: HAIKU INFERENCE PROFILE, region: env.AWS REGION, credentials: { accessKeyId: env.AWS ACCESS KEY ID, secretAccessKey: env.AWS SECRET ACCESS KEY, }, maxTokens: 1, temperature: 0, } ; const response = await llm.invoke "human", "ping" ; const usage = response.usage metadata as TokenUsage | undefined; return { ok: true, inputTokens: usage?.input tokens ?? null, outputTokens: usage?.output tokens ?? null, }; } catch { // Do not surface the underlying AWS/SDK error to callers. return { ok: false, error: "Bedrock probe failed" }; } } On a live run, it comes back with the result you want: {"ok":true,"inputTokens":8,"outputTokens":1} Eight tokens in, one token out. That is the signal you want from a health check on an AI app, not only that the network is up, but that the credentials work and the meter is running. The models, the probe, and the rest of the app are seeded into settings as a catalog. Each entry carries a real Bedrock cross-region inference profile ID rather than a bare model ID, which is the correct choice for cross-region routing: {"id":"haiku","inferenceProfileId":"us.anthropic.claude-haiku-4-5-20251001-v1:0"}, {"id":"sonnet","inferenceProfileId":"us.anthropic.claude-sonnet-4-6"}, {"id":"opus","inferenceProfileId":"us.anthropic.claude-opus-4-8"} Each entry also carries per-million-token input and output pricing, which a later phase uses to enforce tier costs. For now, those fields are a deliberate placeholder, to be confirmed against current Bedrock pricing before any billing math depends on them, so I am not quoting numbers here that would only mislead. As we work through this series, each development phase validates only the environment variables it uses, rather than declaring the project's entire surface up front. So far, we need just eight, for the database, Google auth, Bedrock, and the admin bootstrap, so the env schema gates exactly those. A missing or malformed value throws at startup, naming the offending variable and never printing its value: js const EnvSchema = z.object { MONGODB URI: z.string .url , AUTH SECRET: z.string .min 1 , AUTH GOOGLE ID: z.string .min 1 , AUTH GOOGLE SECRET: z.string .min 1 , AWS ACCESS KEY ID: z.string .min 1 , AWS SECRET ACCESS KEY: z.string .min 1 , AWS REGION: z.string .min 1 , ADMIN EMAIL: z.string .email , } ; const parsed = EnvSchema.safeParse process.env ; if parsed.success { // List the offending variable names only, never their values. const offenders = parsed.error.issues .map issue = issue.path.join "." .join ", " ; throw new Error Invalid environment configuration. Check these variables: ${offenders} , ; } export const env = parsed.data; Other variables that will be introduced later, like Tavily for web search, Voyage for embeddings, Blob for file storage, and LangSmith for tracing, are not here yet. The skeleton works, but it did not the first time, and the failures are perhaps the most useful part of this build report. The first was the most painful: the connection string has no database path, so anything that does not explicitly name the database falls back to test , which the Atlas credentials cannot touch. It bit twice, first in the index script: MongoServerError: not authorized on test to execute command { listCollections: 1, ... $db: "test" } Then again, after deployment, in production sign-in, because the Auth.js adapter does not go through the app's database helper and quietly defaults to test until it is told otherwise: auth error AdapterError auth cause : MongoServerError: not authorized on test to execute command { find: "accounts", ... $db: "test" } The fix is to name the database explicitly in both places. The adapter gets its own databaseName : // databaseName is set explicitly because the connection string has no default // database; without it the adapter would target "test" which the Atlas // credentials cannot access . export const { handlers, auth, signIn, signOut } = NextAuth { adapter: MongoDBAdapter clientPromise, { databaseName: DB NAME } , ...authConfig, } ; And the app reaches the database through one helper that names it the same way. That helper is also where the second gotcha lives. A naive new MongoClient per request would leak a connection pool on every serverless invocation and every dev hot reload, so the client is cached on globalThis as a single instance, and DB NAME is a constant rather than an env var because the database name is neither secret nor environment-specific: js const globalForMongo = globalThis as unknown as { claudiusMongoClientPromise?: Promise<MongoClient ; }; const client = new MongoClient env.MONGODB URI ; export const clientPromise: Promise<MongoClient = globalForMongo. claudiusMongoClientPromise ?? globalForMongo. claudiusMongoClientPromise = client.connect ; export const DB NAME = "claudius"; export async function getDb : Promise<Db { const connected = await clientPromise; return connected.db DB NAME ; } The adapter is handed the same clientPromise , so auth, and the app shares one client and one pool rather than opening two. Making them agree on a single driver version took one line at the repo root, since the adapter and the app can otherwise resolve different ones: "overrides": { "mongodb": "7.3.0" } The third is a monorepo trap. The shared package is consumed as raw TypeScript and transpiled by the app's build through transpilePackages: "@claudius/shared" , with no separate build step. That is convenient, but it means every runtime dependency the shared code imports has to resolve from the app workspace, because Vercel scopes its install to the app's root directory. The rule that keeps the build green is to declare a runtime dependency in every workspace that imports it, even when that looks like duplication. The last is the kind of thing that only shows up on deploy. A lockfile generated on macOS omitted the Linux binaries that Tailwind's build needs, and Vercel's Linux install could not find them: Error: Cannot find module '../lightningcss.linux-x64-gnu.node' Declaring those binaries as optionalDependencies puts them in the lockfile for every platform, and the deploy goes green: "optionalDependencies": { "@tailwindcss/oxide-linux-x64-gnu": "4.3.1", "lightningcss-linux-x64-gnu": "1.32.0" } No chat yet, but the foundation is real. Identity resolves on the server and rides safely in the token. The health route confirms Claudius can reach both Atlas and Bedrock, and the configuration fails loud and early when something is missing. The data model from the last article now has something solid underneath it. The role-resolution logic is unit-tested, but the actual sign-in is an OAuth round trip, and that needs a real browser, not just this headless build. Confirming that an admin email lands as admin on the page and on the persisted user document is the one step I finish by hand. Next is the streaming chat backbone, where the conversation finally gets a place to live, and I open the real checkpoint document I have been promising since the start.