DEV Community: GDS K S

Claude Code Felt Off for a Month. Here Is What Broke.

GDS K S — Thu, 23 Apr 2026 20:41:06 +0000

For about four weeks in March and April, Claude Code felt noticeably worse. I was not imagining it. Sessions got repetitive. Tool calls chose weird paths. My usage limits emptied faster than the work I got out of them. I kept switching models, clearing context, restarting CLIs, convinced I had broken something in my own setup.

Then on April 23 Anthropic published a postmortem. Three separate bugs, all resolved by April 20. Usage limits were reset for every subscriber as compensation. The apology was thorough. The more interesting part is what the timeline reveals about the failure modes of agent products, and what that means for any developer building on top of one.

TL;DR

The three bugs overlapped. All three felt like the same thing to users: Claude got dumber. None would have been caught by a normal test suite.

#	Window	Bug	Fix
1	Mar 4 – Apr 7	Reasoning effort default lowered `high` → `medium` for latency	Reverted Apr 7
2	Mar 26 – Apr 10	Cache cleared "thinking blocks" every turn after 1h idle, not once	CLI `v2.1.101`
3	Apr 16 – Apr 20	Prompt capped responses to 25/100 words, cost ~3% benchmark intelligence	CLI `v2.1.116`

The three bugs, expanded

Bug 1: the silent default change

On March 4, Anthropic lowered the default reasoning effort from high to medium to reduce latency. It was a product call, not a bug per se, and the reasoning was defensible. Users noticed anyway. Reverted April 7.

Lesson: a "config" change to an agent's reasoning budget is a model change. It deserves a changelog entry. Quietly tuning it down to hit a latency target is the kind of decision that reads reasonable in a meeting and awful in a transcript.

Bug 2: the caching regression

This one is the scariest of the three. A prompt-cache optimization shipped March 26. The intent was to clear "thinking blocks" from the cache after an hour of inactivity, once. The implementation cleared them on every turn after that first hour.

The symptom was that Claude became forgetful. It repeated itself. It picked strange tools. It burned through usage quotas far faster than the same session would have a week earlier. None of that raised an HTTP 500 or fired a test alert. It only manifested as "this feels worse."

Click for the exact shape of the regression

The cache was supposed to do this:

t=0:  start session, thinking blocks written to cache
t=1h: cache cleared once due to inactivity
t=1h+1turn: normal flow resumes, new thinking blocks cached

Instead it did this:

t=0:  start session, thinking blocks written to cache
t=1h: cache cleared due to inactivity
t=1h+1turn: new thinking blocks cached... then cleared
t=1h+2turn: thinking blocks cached... then cleared
[repeat every turn]

Each turn paid the full cost of re-deriving reasoning from scratch, and lost the prior context.

Bug 3: the word-limit constraint

Someone added this to the system prompt on April 16:

keep text between tool calls to ≤25 words.
keep final responses to ≤100 words.

It read fine. It even looks like the kind of instruction I would write to tighten my own agents. What it actually did was clip the model by roughly 3% across the benchmark suite. Reverted April 20.

What I learned running projects on top of this

Two lessons stuck.

Agent regressions are diffuse. A classic API regression has a clear signal. The test fails, the error rate spikes, the latency chart moves. An agent regression shows up as my work feels worse. The only way I caught anything was by noticing I was redoing work more often, not because a metric turned red. If you are building tools that route to an agent, you need a drift signal that does not rely on exceptions or HTTP status codes.

Caching is the most dangerous optimization in agent systems. The bug with the biggest blast radius was, on paper, a small optimization with an obvious upside. It was not visible until you imagined what happens when "clear thinking blocks after inactivity" runs every turn instead of once. In my own tooling I have pulled back on aggressive cache-invalidation heuristics since reading this.

If it is not obvious that the cache key captures every meaningful state change, I would rather pay for the tokens.

What this means for tool builders

I build a small local tool that orchestrates Claude to draft and publish articles. Reading this postmortem changed a few defaults in how I build.

1. Version your prompts

Every system prompt my tooling ships now embeds a version string in a trailing comment. Git tells me the same thing, but an ad hoc marker is faster to spot in a transcript.

const SYSTEM_PROMPT = `You are a writing assistant for Dev.to articles.
Follow the style guide. Prefer short sentences for impact.
<!-- prompt-v: 2026-04-23.3 -->`;

When a session feels off, I grep for the version in the transcript. If it has drifted, I know where to look.

2. Log tokens per turn

A silent spike in tokens-per-turn is exactly what the caching bug would have produced in my transcripts. That was not a thing I was watching for.

logger.info("turn", "completed", {
  turn: turnIndex,
  inputTokens: usage.input_tokens,
  outputTokens: usage.output_tokens,
  cacheHit: usage.cache_read_input_tokens ?? 0,
  promptVersion: "2026-04-23.3",
});

A rolling average of input tokens per turn is a cheap drift detector. If it doubles on a Tuesday and your code has not changed, the thing underneath you has.

3. Stop testing agents with toy tasks

The bugs Anthropic describes would not have shown up in a short demo. They only surface in sessions that run long enough for the agent to need its earlier reasoning, or for the cache to kick in.

Eval type	Catches bug 1?	Bug 2?	Bug 3?
Single-prompt accuracy bench	maybe	no	no
Short multi-turn demo	no	no	maybe
30-minute real session	yes	yes	yes

If you are benchmarking an agent for production use, your evaluation needs sessions that last at least half an hour of real work. Anything shorter gives false confidence.

The tradeoff nobody is naming

Here is the uncomfortable part. The fixes Anthropic describes are the kind you only find by rolling back and listening to complaints. Each of the three initial changes was made for a reasonable-sounding reason.

Change	Stated reason	Actual cost
Lower default effort	Latency matters	Perceived IQ drop
Cache aggressively	Money matters	Thinking history destroyed every turn
Constrain response length	Readability matters	3% benchmark hit

The problem is that agent quality is multi-dimensional, and the postmortem made visible something most vendors quietly hope users do not notice. You cannot A/B test an agent the way you A/B test a search ranker. The feedback loop is noisy, delayed, and routed through the subjective experience of people who already had a rough day.

Anthropic did the right thing by publishing the timeline. Most vendors do not.

At Glincker

At Glincker I am building tooling that assumes the underlying model is going to wobble, not that it is going to be stable. The orchestration layer logs enough to catch regressions my users cannot articulate. The retry logic notices when the agent is burning effort without making progress. The postmortem did not change my plan. It confirmed it.

The bottom line

Three bugs, four weeks, an ecosystem of developers quietly wondering if they should switch tools.
Short evals would not have caught any of them.
Prompt versions, per-turn token logging, and long-session evals are the minimum viable drift detectors.
When you build on top of an agent, you are depending on a product team's prompt, their cache policy, and their default settings. All three can change without a version bump you would notice.

Read the full postmortem. Then look at whether your own tooling would have caught any of these regressions. Mine would not have, fast enough. I have some work to do.

The Token Tab: A Developer's Audit of the AI Hype Stack

GDS K S — Thu, 23 Apr 2026 04:45:18 +0000

A GitHub repo I starred in January does not run anymore. The tutorial I followed in February has a pinned issue that says "keys getting banned." The Mac mini I was going to buy is still on the wish list, which turns out to be the only part of this I got right.

This is not an anti-AI post. The tools are real, the tokens are real, the productivity wins are real. But most AI tutorials in 2026 are selling layers 1 and 4 of a four-layer stack and hoping you do not look at layers 2 and 3 until after your credit card is on file.

This post is a teardown of those four layers, with real numbers, and a checklist you can run on any tool before you commit hardware or a subscription to it.

The four layers of the hype stack

Layer	What it is	Who pays for it
1. UI wrapper	The app you interact with	You (subscription)
2. Orchestration	Agent loop, tool calls, memory, retries	You (eventually, in tokens)
3. Inference	The model behind the curtain	You (tokens) or the provider (loss)
4. Hardware	Whatever runs the inference	Data center, or your desk

Most hype cycles concentrate on layers 1 and 4 because those are the layers a YouTube thumbnail can sell. A slick dashboard on layer 1. A glowing Mac mini on layer 4. Layer 2 is engineering and hard to video. Layer 3 is invisible until the bill arrives.

Rule of thumb: If a tutorial spends more time unboxing a Mac mini than discussing the inference bill, layer 3 is where your surprise is going to land.

Layer 1: The wrapper

Call it what you want. Agent, copilot, assistant, IDE extension, self-hosted dashboard. The UX sits on top of someone else's model. That is not a bad thing. Wrappers are legitimate businesses. The problem is when the pitch implies the wrapper is the product, which it almost never is.

Audit questions for layer 1:

Can I swap the model underneath without rewriting my workflow?
What happens to my prompts, context, and memory if the provider changes ToS?
Is there a ToS clause in the provider's terms that names this tool, or its category, as prohibited?

That last one bites harder than people realize. As of April 2026 there are several major provider ToS updates that explicitly prohibit certain third-party agentic tools. Users have reported keys being revoked. A wrapper that routes through a non-permitted path is one enforcement pass away from being a paperweight.

Layer 2: Orchestration

This is where the real engineering lives. Tool calling, retries, memory, sandboxing, error recovery, concurrency, cost control. Most OSS projects that show off a "watch it book my flight" demo are one degraded model or one retry storm away from the same flow taking forty minutes and four dollars in tokens.

Agent loops are where cost explodes. A single user message can trigger ten or fifteen tool calls, each with a full context window of system prompt, tool descriptions, and prior turns. Input tokens dominate. You do not see this on the demo.

# Simplified agent loop cost surface
def agent_run(user_msg):
    context = load_memory()          # N input tokens
    while not done:
        response = llm.call(          # N input + M output tokens
            system + tools + context
        )
        tool_result = run_tool(response)
        context.append(tool_result)   # grows N each iteration
    return final_answer

Notice the loop. Each iteration includes the full context of every previous iteration. A ten-step agent run with a 30K-token system prompt and 4K-token tool results runs roughly 300K input tokens before you count output. At current Claude Sonnet rates that is about $0.90 for a single user request. Do that twenty times a day and you have replaced a $20 subscription with a $540 month.

Real numbers from the All-In podcast in February 2026:

Jason Calacanis: his team's AI agents were running at $300 a day, roughly $110K annualized.
Chamath Palihapitiya: started imposing token budgets on his developers. Direct quote, paraphrased: "I'll run out of money."
Mark Cuban: eight Claude agents at $300 a day plus a human maintaining them at $200 a day costs more than the employee they replace.

These are people who can afford it. They are flinching.

Audit questions for layer 2:

What is the worst-case token spend on a single request loop?
Does the agent have a hard cap on tool-call iterations?
Is retry logic fixed-interval or exponential? Exponential plus a flaky tool is where budgets die.
Does the memory layer grow unbounded, or is it summarized?

Layer 3: Inference

Every tool you are looking at, self-hosted or otherwise, runs on someone's inference bill. When a subscription "includes" a feature, somebody is eating the difference. That works until it does not.

Recent, concrete, April 2026 examples:

April 4, 2026: Anthropic revoked subscription billing for third-party tools. OpenClaw and similar tools that previously rode on a Pro/Max subscription now bill to Extra Usage.
April 21, 2026: Anthropic A/B tested removing Claude Code from the $20 Pro plan for 2% of new signups. The pricing page briefly reflected the removal before clarification.
2025 and 2026 economics: OpenAI reportedly burned about $8 billion against $13 billion in revenue in 2025, with roughly $14 billion in losses projected for 2026. Sam Altman has publicly said OpenAI loses money on the $200/month ChatGPT Pro tier.
GTC 2026: Jensen Huang put a gigawatt data center, amortized over 15 years, at roughly $40 billion empty.

Per-token prices have collapsed. GPT-4 input tokens went from $30 per million to $2.50 per million in eighteen months, an 80 to 90 percent drop. The floor is not zero, and consumption keeps rising faster than price falls.

Metric	2023	2025/2026	Change
GPT-4-class input tokens	$30/M	~$2.50/M	-90%
Avg enterprise AI spend	—	$85K/month	+36% YoY
Orgs spending >$100K/month	baseline	2x baseline	doubled
Daily tokens processed (China alone)	100B (Jan 2024)	140T	~1400x

The structural problem: per-token costs are down 80-90% in 18 months, per-user consumption is up faster. Your effective monthly bill is not going down.

Audit questions for layer 3:

If the provider moved every call to strict pay-per-token tomorrow, what would my monthly bill look like?
Can I cap spend at the provider level, not just the app level?
Does the tool work with a local fallback that preserves 80% of function, or does it hard-fail without the frontier model?

Layer 4: Hardware

The Mac mini posts, the "$2000 gets you your own AI" guides, the affiliate-stuffed "best LLM server" roundups. This is not a scam. Apple Silicon really is good for local inference. Unified memory, no PCIe copy penalty, low idle power, silent. All genuinely useful.

But the honest read on local models for agentic workflows in April 2026:

Model	RAM needed	Speed on consumer Apple Silicon	Usable for agents?
Kimi K2 (1.8-bit quantized)	245GB+	1-2 tokens/sec on Mac Studio 512GB	No, too slow
Qwen3-Coder-30B (MoE, 3B active)	64GB	10-15 tokens/sec on M4 Pro	Yes, for simple flows
GLM-4.7-Flash (9B active, 128K ctx)	24GB	~20 tokens/sec on M4	Yes, for coding subset
GPT-OSS-20B	24GB	~15 tokens/sec on M4	Yes, general purpose

Local models are usable. They are not the same as frontier cloud models for multi-step agentic work, especially when the task needs long-horizon planning or serious tool use. A local 30B is a working tool. A local Kimi K2 is a science project unless you own a Mac Studio cluster.

Anyone telling you otherwise is usually selling you something (affiliate link, course, the same course with a new thumbnail).

Audit questions for layer 4:

Do the benchmarks in the guide match the task I actually want to do, or are they summarization benchmarks being used to imply coding performance?
What is the tokens-per-second floor for the model at the context length I'll actually use?
If I only use the hardware four hours a day, is the cloud API still cheaper at my real usage?

Four signals a stack is on borrowed time

Run these before you commit.

The pricing page changed silently in the last 30 days. Check the Wayback Machine. Compare.
The tutorial's recent comments are mostly "this doesn't work for me." Filter by newest. If the top new comments are bug reports, the snapshot decayed.
The GitHub issues tab has an open "API keys being banned" or "provider blocked us" thread. Search by keyword. This one is terminal.
The tool routes through a provider whose ToS explicitly names it, its category, or its pattern. Find the ToS. Ctrl-F the project name.

Three of four true: the stack is late cycle, budget accordingly or skip.
One or two true: yellow flag, keep watching.
Zero: you might be early, which is also risky, but at least the risk is legible.

What to actually build on

Boring but it holds up:

Prefer tools where the provider bills you directly. The bill is honest. The less abstraction between you and the token meter, the fewer surprises.
Prefer stacks where swapping the underlying model is a config change, not a rewrite. Portability is the cheapest insurance you can buy.
Treat GitHub stars like follower counts. Not meaningless, but not the product.
Assume any third-party tool that rides a major provider's consumer subscription instead of an API key is temporary, and price that temporariness into your decision.
Run the 30-day test. If a tutorial still has fresh comments saying "this works" a month out, it is probably safe. If not, skip.

None of this is anti-AI. It is pro not-getting-caught-out. The tools are real. The wins are real. The token bill is also real. The layer you are not looking at is usually the one that bites.

What signals have you seen that a tool is late cycle? Drop them in the comments. I am genuinely collecting patterns, because the next wave of this is already starting.

I replaced Auth0 with an open source library in 30 minutes. Here is what broke.

GDS K S — Sat, 18 Apr 2026 20:52:03 +0000

My Auth0 bill last month was $427. For 12,000 monthly active users on a side project that makes roughly $0 in revenue. I spent a Saturday moving off it. This is what happened.

The bill

Auth0's pricing jumps at the 1,000 MAU line. My project crossed it in March. The next tier is $240/month. Then I turned on MFA, which is extra. Then I wanted SAML for a B2B customer, which is extra. Then log retention went up because I needed 30 days for a compliance thing, which is extra.

$427. For a login button.

I like Auth0 as a product. I have shipped it at two previous companies and it was fine. What I did not like was paying rent on a feature I could own.

What I actually needed

I made a list before I started, so I would not spend a weekend building features I did not use.

Email + password login
Magic link login
Password reset
Session management with refresh
OAuth with Google and GitHub
A way to call our API from agent scripts (this one was new)

What I did not need, despite Auth0 charging for it:

Multi tenant orgs
SAML/SCIM (the B2B customer moved on)
Passwordless WebAuthn (I want this, but not yet)
50+ social providers
Rules and hooks for custom login logic (I had one rule, it moved to my app)

So the real question was: is there a library that covers the first list and lets me run it on my own Cloudflare Workers without rebuilding everything from scratch.

The shortlist

I looked at four things over maybe an hour.

Lucia got archived in March 2025. I did not want to adopt something the author shut down, even if the code still works.

Better Auth looked decent but ships a lot of plugins I did not want and the docs for its Cloudflare Workers story were thin when I checked.

NextAuth/Auth.js works but is tightly coupled to Next.js, and I needed this to cover a separate agent SDK as well.

kavachOS was the new one I had not tried. It does auth for humans and AI agents in the same library, runs on Workers, and the README had a "migrating from Auth0" page. That is the one I picked.

The 30 minute spike

I timed it. 32 minutes from pnpm add kavachos to a working login on localhost.

Install

pnpm add kavachos @kavachos/hono

I use Hono on Workers. There are adapters for Next.js, Express, Fastify, and a few others.

The core config

// src/auth.ts
import { kavachos } from "kavachos";
import { honoAdapter } from "@kavachos/hono";

export const auth = kavachos({
  adapter: honoAdapter(),
  database: process.env.DATABASE_URL!,
  session: {
    expiresIn: "30d",
    rolling: true,
  },
  providers: {
    password: { minLength: 12 },
    magicLink: { tokenTTL: "10m" },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
  email: {
    provider: "resend",
    apiKey: process.env.RESEND_API_KEY!,
    from: "noreply@myproject.com",
  },
});

Wire it up

// src/index.ts
import { Hono } from "hono";
import { auth } from "./auth";

const app = new Hono();
app.route("/auth", auth.routes);

app.get("/me", auth.required, (c) => {
  const user = c.get("user");
  return c.json({ user });
});

export default app;

That is everything the server needs. Login, signup, magic link, OAuth callbacks, session refresh, logout, password reset, email verification. All mounted under /auth/*.

The frontend was about the same amount of code. A useSession() hook, a login form, a magic link form, an OAuth button component. Roughly 120 lines total across 4 files.

The schema

kavachOS ships migrations. I ran:

pnpm kavachos migrate

and it created the tables. users, sessions, oauth_accounts, password_reset_tokens, magic_link_tokens, email_verification_tokens. Six tables. I looked at them, they were boring in the right way.

The Auth0 migration

I had 12,000 users in Auth0. I needed to bring them over without forcing a password reset for everyone.

Auth0 exports users as JSON. The password hashes are bcrypt, which is what kavachOS uses internally, so in theory a direct copy would work.

# Export from Auth0 (this is an Auth0 built in job)
auth0 users export --format json --output users.json

# Import into kavachOS
pnpm kavachos import --from auth0 --file users.json

The second command does not exist. I wrote it that night after discovering the first one returns passwords as opaque hashes that Auth0 does not document the algorithm for. Or rather, they document it as "we use bcrypt" but the actual export format wraps the hash in a proprietary string.

This was the first thing that broke.

What broke in prod

The password hashes were not portable

Auth0's export includes a passwordHash field on each user. The format looks like a bcrypt string but it is prefixed with Auth0's own identifier. kavachOS would not match on login.

Fix: I wrote a small shim in my auth config that recognizes the Auth0 prefix, strips it, and re-verifies against the underlying bcrypt. After a successful login the user's hash gets re-saved in the native format. Over a week, 80% of active users migrated silently. The rest I handled manually with a one time "we need you to reset your password" email.

providers: {
  password: {
    minLength: 12,
    verifyLegacy: async (hash, password) => {
      if (hash.startsWith("$auth0$")) {
        const actual = hash.replace(/^\$auth0\$/, "");
        return bcrypt.compare(password, actual);
      }
      return false;
    },
  },
},

kavachOS has a verifyLegacy hook built in for this, which was nice. I did not have to patch the library.

Session cookies were on the wrong domain

I had cookies on auth.myproject.com from Auth0. kavachOS defaulted to myproject.com. This meant every logged in user got signed out at the cutover.

I picked up on this at 2am when my own login session died. Fix was a 10 minute config change plus an apology email.

session: {
  expiresIn: "30d",
  rolling: true,
  cookie: {
    domain: ".myproject.com",
    secure: true,
    sameSite: "lax",
  },
},

Worth reading the session config docs before you deploy, not after.

Google OAuth redirect URI

Auth0 uses its own callback URL. My Google Cloud Console was configured for https://my-tenant.us.auth0.com/login/callback. kavachOS uses https://myproject.com/auth/callback/google.

30 second fix in the Google console, but it cost me an hour of "why is Google OAuth returning redirect_uri_mismatch" before I remembered.

The agent thing worked first try

The one unexpected win. My project has a handful of agent scripts that run on cron and need to hit the API as a specific user. With Auth0 I was using Machine to Machine tokens, which cost extra and have their own quota.

kavachOS has an agent identity primitive. You can mint an agent token, scope it to a user, give it permissions, and call the API. The docs are at kavachos.com/docs/agents. It took one line to wire up and replaced about $40/month of Auth0 M2M charges.

const agentToken = await auth.agents.issue({
  userId: "user_123",
  permissions: ["reports:read", "invoices:write"],
  expiresIn: "90d",
});

This was the thing that made the migration actually worth it, not just a cost optimization.

The cost

Before: $427/month
After: $0/month for the library, ~$4/month for Neon Postgres that I was already paying for, ~$3/month for Resend.

If I ever want to stop running it myself, kavachOS has a managed cloud at kavachos.com with a generous free tier and metered pricing after that. I am not on it yet because running Workers + Postgres is cheap, but I like that the option exists.

Where Auth0 is still better

I want to be fair. Things Auth0 does well that I gave up:

The dashboard. Auth0's admin UI is excellent. kavachOS has one but it is less polished.
Enterprise SSO configuration. If you need to onboard a customer's Okta or Azure AD in an afternoon, Auth0's wizards are worth the money.
Anomaly detection and breached password checks. kavachOS has the second, not the first.
Log retention without a separate pipeline. I piped kavachOS logs to Axiom, which works, but it was a separate setup.

If your company is at the stage where any of those matter more than $5K/year, stay on Auth0. I am not at that stage.

Would I do it again

Yes, and I did it again last week for another project. The second migration took 45 minutes, mostly because I already had the verifyLegacy shim written and the agent identity stuff working. If you are reading this and your auth bill looks wrong, the math has changed in the last year. There are real libraries now.

If you try kavachOS, the docs I used most were the quickstart, the Auth0 migration guide, and the Hono adapter docs. The repo is at github.com/kavachos/kavachos.

Questions I expect

Is kavachOS production ready? I am running it on a real project with real users. Your call.

Why not just use Supabase auth? I did not want my auth tied to my database host. kavachOS works with any Postgres.

What about self hosting on Render or Railway? Works fine. The library does not care.

Did you consider Clerk or WorkOS? Clerk is good but more expensive than Auth0 at my tier. WorkOS is B2B focused and I am not that.

What if kavachOS gets abandoned like Lucia? The project is self hostable, the license is MIT, and the database schema is boring. If upstream went away tomorrow I would fork it and keep going. That is the whole point of picking open source over a managed service.

Following for the next one: I am writing these daily for the next two weeks. Tomorrow is magic link login in Next.js with no library, then with a library, with the actual diff. Hit follow if you want it.

If you have an Auth0 horror story, drop it in the comments. I will probably do a compilation post.

Gagan Deep Singh builds open source tools at Glincker. Currently working on kavachOS (open source auth for AI agents and humans) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

How to build a secure password reset flow in Next.js (the short version)

GDS K S — Sat, 18 Apr 2026 20:45:52 +0000

Last month I reviewed a friend's side project. He had 200 paying users, Stripe set up, a working dashboard. The password reset flow sent a reset token in a query string, stored it in plain text in Postgres, and never expired it. Anyone who read the database could take over any account, permanently.

He had written it in 2 hours. It looked fine. That is the problem with reset flows. They look fine until someone reads them carefully.

Here is a version that does not embarrass you, followed by the same thing in 12 lines using kavachOS.

What a good reset flow actually does

Six things, in order:

Accepts an email and always responds with the same 200, whether the email exists or not
Generates a 32 byte random token, hashes it before storing
Stores the hash with a 15 minute expiry and a one time use flag
Sends the raw token to the user's inbox
On submit, hashes the incoming token and compares against storage
Marks the token used, writes a new password, rotates every active session

If any one of those is missing you have a bug. Most tutorials cover 1 and 3. Almost nobody covers 6, which is why most apps stay logged in as the attacker after a reset.

The from scratch version

The schema

// db/schema.ts
import { bigserial, pgTable, text, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: bigserial("id", { mode: "number" }).primaryKey(),
  email: text("email").notNull().unique(),
  passwordHash: text("password_hash").notNull(),
});

export const passwordResetTokens = pgTable("password_reset_tokens", {
  id: bigserial("id", { mode: "number" }).primaryKey(),
  userId: bigserial("user_id", { mode: "number" }).notNull(),
  tokenHash: text("token_hash").notNull(),
  expiresAt: timestamp("expires_at").notNull(),
  usedAt: timestamp("used_at"),
});

Note the tokenHash. If your database leaks, the leaked rows cannot be used to reset anyone's password. If you store the raw token, you have handed the attacker a working exploit.

The request endpoint

// app/api/auth/forgot-password/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { db } from "@/db";
import { users, passwordResetTokens } from "@/db/schema";
import { eq } from "drizzle-orm";
import { randomBytes, createHash } from "crypto";
import { sendResetEmail } from "@/lib/email";
import { rateLimit } from "@/lib/rate-limit";

const body = z.object({ email: z.string().email() });

export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  if (await rateLimit(`forgot:${ip}`, { max: 5, window: 60 })) {
    return NextResponse.json({ ok: true });
  }

  const parsed = body.safeParse(await req.json());
  if (!parsed.success) return NextResponse.json({ ok: true });

  const user = await db.query.users.findFirst({
    where: eq(users.email, parsed.data.email.toLowerCase()),
  });

  if (user) {
    const raw = randomBytes(32).toString("base64url");
    const tokenHash = createHash("sha256").update(raw).digest("hex");
    await db.insert(passwordResetTokens).values({
      userId: user.id,
      tokenHash,
      expiresAt: new Date(Date.now() + 15 * 60 * 1000),
    });
    await sendResetEmail(user.email, raw);
  }

  return NextResponse.json({ ok: true });
}

Four things that matter here:

The endpoint always returns 200. An attacker probing with 10,000 emails learns nothing. If you return 404 for unknown emails, you have just built an account enumeration endpoint.

The rate limit is on IP, 5 per minute. It will not stop a distributed attacker but it raises the cost enough that nobody bothers.

On parse failure, still 200. A 400 leaks "this email was malformed" vs "this email was fine but not in the database".

The raw token exists for exactly one HTTP response and one email send. It never hits the database.

The reset endpoint

// app/api/auth/reset-password/route.ts
export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  if (await rateLimit(`reset:${ip}`, { max: 10, window: 60 })) {
    return NextResponse.json({ error: "Too many attempts" }, { status: 429 });
  }

  const parsed = z
    .object({ token: z.string().min(32), password: z.string().min(12) })
    .safeParse(await req.json());
  if (!parsed.success) {
    return NextResponse.json({ error: "Invalid request" }, { status: 400 });
  }

  const { token, password } = parsed.data;
  const tokenHash = createHash("sha256").update(token).digest("hex");

  const row = await db.query.passwordResetTokens.findFirst({
    where: and(
      eq(passwordResetTokens.tokenHash, tokenHash),
      gt(passwordResetTokens.expiresAt, new Date()),
      isNull(passwordResetTokens.usedAt),
    ),
  });

  if (!row) {
    return NextResponse.json(
      { error: "Invalid or expired link" },
      { status: 400 },
    );
  }

  const passwordHash = await bcrypt.hash(password, 12);

  await db.transaction(async (tx) => {
    await tx.update(users).set({ passwordHash }).where(eq(users.id, row.userId));
    await tx
      .update(passwordResetTokens)
      .set({ usedAt: new Date() })
      .where(eq(passwordResetTokens.id, row.id));
  });

  await rotateSession(row.userId);
  return NextResponse.json({ ok: true });
}

Three things that people miss:

The transaction. If the password update succeeds but the token update fails, the token can be used again. Wrap them or do not bother.

rotateSession. Password reset must invalidate every active session for that user. If an attacker has a stolen session cookie, changing the password does not kick them out. Rotate.

Same error for expired, used, and never existed. All three get a 400 with "invalid or expired link". No timing differences, no leaked state.

Rate limiting

// lib/rate-limit.ts
import { Redis } from "@upstash/redis";
const redis = Redis.fromEnv();

export async function rateLimit(
  key: string,
  opts: { max: number; window: number },
): Promise<boolean> {
  const count = await redis.incr(key);
  if (count === 1) await redis.expire(key, opts.window);
  return count > opts.max;
}

On Cloudflare Workers, swap Redis for KV or Durable Objects. Same shape.

The kavachOS version

I wrote the code above maybe a dozen times in different projects before I gave up and wrote a library. That library is kavachOS. Here is the same flow with it:

Install

pnpm add kavachos @kavachos/nextjs

Configure

// auth.ts
import { kavachos } from "kavachos";
import { nextjsAdapter } from "@kavachos/nextjs";

export const auth = kavachos({
  adapter: nextjsAdapter(),
  database: process.env.DATABASE_URL!,
  email: {
    provider: "resend",
    apiKey: process.env.RESEND_API_KEY!,
    from: "noreply@example.com",
  },
  passwordReset: {
    tokenTTL: "15m",
    oneTimeUse: true,
    rotateSessionsOnReset: true,
  },
});

Mount the routes

// app/api/auth/[...kavachos]/route.ts
import { auth } from "@/auth";
export const { GET, POST } = auth.handlers;

The form

// app/auth/forgot/page.tsx
"use client";
import { useAuth } from "@kavachos/nextjs";

export default function Forgot() {
  const { requestReset, pending, status } = useAuth();
  return (
    <form action={requestReset}>
      <input name="email" type="email" required />
      <button disabled={pending}>Send reset link</button>
      {status === "ok" && <p>If that email exists, a link is on the way.</p>}
    </form>
  );
}

That is the whole thing. The tokens are hashed, the expiry is 15 minutes, the rate limits are on, the sessions rotate on success, and the error messages are constant time. If you look at the source, it is almost exactly the code above, just packaged.

Docs for the password reset flow are at kavachos.com/docs/password-reset. The Next.js adapter is at kavachos.com/docs/adapters/nextjs.

Three mistakes I keep finding in code reviews

Storing tokens in plain text

One in three repos I have looked at does this. If the database leaks, every active reset link is live. Hash before storing. Always. The raw token should exist in exactly two places: the HTTP response that mails it out, and the user's inbox.

Using `Math.random()` for the token

Math.random() is not cryptographic. It is a deterministic PRNG seeded from the process start time. Use crypto.randomBytes(32) on the server or crypto.getRandomValues() on the edge.

24 hour expiries

If the user is going to click the link, they click it in 2 minutes. A 24 hour window exists to make the support team's job easier, but it gives an attacker who compromised an email backup all day to use the link. 15 minutes is fine. If the user misses the window they can click "forgot password" again.

Testing checklist before you ship

POST /forgot-password returns 200 for both known and unknown emails
Response time for known and unknown emails is within 50ms (timing defense)
Rate limit triggers at the 6th request from one IP per minute
Token row contains tokenHash, not the raw value
Expired tokens are rejected with the same 400 as invalid ones
Used tokens are rejected with the same 400 as invalid ones
After a successful reset, all sessions for that user are invalidated
A log line is written for reset_requested, reset_completed, reset_failed

That last point matters when a user emails you at midnight saying they never got the email. You will want those logs.

Questions I expect in the comments

Why not JWTs for the token? A JWT is stateless. You cannot revoke it on use. If you use a JWT for reset, the same link works until the expiry for anyone who saved it. You lose the one time property. Use a database row.

Why 15 minutes? Because the user clicks within 2. The only thing a longer window does is give attackers more runway.

Is email actually secure enough for this? No, email is terrible. It is also what everyone has. Which is why the link expires in 15 minutes, is one time use, and rotates sessions on success. You are containing the blast radius, not preventing the attack.

What I will write next

I am doing one of these a day for the next two weeks. Next up: magic link login in Next.js, same rigor, with and without a library. Follow me here if you want the next one in your feed.

Comment with the auth thing you have been putting off. If I get enough of the same one, I will write it up.

Gagan Deep Singh builds open source tools at Glincker. Currently working on kavachOS (open source auth for AI agents and humans) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

How to build a login flow in Next.js 15 (sessions, cookies, CSRF, and the timing attack nobody talks about)

GDS K S — Sat, 18 Apr 2026 20:42:22 +0000

This is part 4. Today: login. Form, server endpoint, session cookie, CSRF, and a real look at timing defense. This is the endpoint attackers probe the most, so it is the one we harden the hardest.

The flow

+-------+            +--------------+            +----------+
|Browser|   POST     |  Next.js     |  SELECT    | Postgres |
|       |  email     | /api/auth/   |  user by   |  users   |
|       |  password  |   login      |  email     |          |
|       |----------->|              |----------->|          |
|       |            |              |<-----------|          |
|       |            |  verify      |            +----------+
|       |            |  password    |
|       |            |  (bcrypt)    |
|       |            |              |  INSERT    +----------+
|       |            |  if ok,      |  session   | sessions |
|       |            |  create      |----------->|          |
|       |            |  session     |<-----------|          |
|       |            |              |            +----------+
|       |  Set-Cookie|              |
|       |<-----------|              |
|       |  302 /     |              |
+-------+            +--------------+

And then, on every subsequent request:

+-------+   GET /dashboard           +--------------+
|Browser|  Cookie: session=abc123    |  Next.js     |
|       |--------------------------->|  middleware  |
|       |                            |              |   SELECT
|       |                            |              |-->sessions
|       |                            |              |<--where token_hash=..
|       |                            |              |
|       |<---- 200 with user context-|              |
+-------+                            +--------------+

Two things to notice:

The session token on the wire is not stored in the database. We store its SHA-256 hash. This is the same pattern as reset tokens. If the database leaks, the leaked rows cannot be replayed as cookies.

The verify path is a single row lookup on a hash. Fast. No cryptographic operation per request, just an index hit.

The session table

Same note as last article: if you are using kavachOS, pnpm kavachos migrate creates and maintains this table for you. I am showing the SQL so you know what is in your database either way.

From article 02, for reference:

create table sessions (
  id           bigserial primary key,
  user_id      bigint not null references users(id) on delete cascade,
  token_hash   text not null unique,
  expires_at   timestamptz not null,
  last_used_at timestamptz not null default now(),
  user_agent   text,
  ip_address   inet,
  created_at   timestamptz not null default now()
);

create index idx_sessions_user on sessions(user_id);
create index idx_sessions_expires on sessions(expires_at);

The user_agent and ip_address columns are for the "active sessions" screen on a user's account page ("signed in on iPhone in San Francisco"). They are not used for validation. Do not tie session validity to IP. Phone carriers rotate IPs and your users will hate you.

The login form

// app/auth/login/page.tsx
"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";

export default function Login() {
  const router = useRouter();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [remember, setRemember] = useState(true);
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function submit(e: React.FormEvent) {
    e.preventDefault();
    setPending(true);
    setError(null);

    const res = await fetch("/api/auth/login", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email, password, remember }),
    });

    setPending(false);

    if (res.status === 429) {
      setError("Too many attempts. Try again in a minute.");
      return;
    }
    if (!res.ok) {
      setError("Email or password is incorrect.");
      return;
    }
    router.push("/dashboard");
  }

  return (
    <form onSubmit={submit} className="max-w-sm mx-auto mt-16 space-y-4">
      <h1 className="text-2xl font-semibold">Sign in</h1>

      <label className="block">
        <span className="text-sm">Email</span>
        <input
          type="email"
          required
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="email"
        />
      </label>

      <label className="block">
        <span className="text-sm">Password</span>
        <input
          type="password"
          required
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="current-password"
        />
      </label>

      <label className="flex items-center gap-2 text-sm">
        <input
          type="checkbox"
          checked={remember}
          onChange={(e) => setRemember(e.target.checked)}
        />
        Stay signed in for 30 days
      </label>

      {error && <p className="text-red-600 text-sm">{error}</p>}

      <button
        type="submit"
        disabled={pending}
        className="w-full rounded bg-black text-white py-2 disabled:opacity-50"
      >
        {pending ? "Signing in..." : "Sign in"}
      </button>

      <div className="flex justify-between text-sm">
        <a href="/auth/forgot" className="underline">Forgot password?</a>
        <a href="/auth/register" className="underline">Create account</a>
      </div>
    </form>
  );
}

One error message for bad credentials: "Email or password is incorrect." Never "email not found" vs "password wrong". Same reason as register. Treat every signed-out-ish endpoint as hostile.

The autoComplete="current-password" tells password managers to offer the existing stored password. This is the small UX detail that makes the difference between users loving password managers and fighting them.

The server endpoint

// app/api/auth/login/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import bcrypt from "bcrypt";
import { randomBytes, createHash } from "crypto";
import { db } from "@/db";
import { users, sessions } from "@/db/schema";
import { eq } from "drizzle-orm";
import { rateLimit } from "@/lib/rate-limit";

const body = z.object({
  email: z.string().email().max(254),
  password: z.string().min(1).max(256),
  remember: z.boolean().optional(),
});

const FAKE_HASH =
  "$2b$12$abcdefghijklmnopqrstuuAbCdEfGhIjKlMnOpQrStUvWxYz.abcdef";

export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  if (await rateLimit(`login:${ip}`, { max: 10, window: 60 })) {
    return NextResponse.json({ error: "Too many attempts" }, { status: 429 });
  }

  const parsed = body.safeParse(await req.json());
  if (!parsed.success) {
    await bcrypt.compare("dummy", FAKE_HASH);
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }

  const email = parsed.data.email.toLowerCase().trim();
  const user = await db.query.users.findFirst({
    where: eq(users.email, email),
  });

  const hashToCompare = user?.passwordHash ?? FAKE_HASH;
  const passwordOk = await bcrypt.compare(parsed.data.password, hashToCompare);

  if (!user || !passwordOk) {
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }

  if (!user.emailVerified) {
    return NextResponse.json(
      { error: "Please verify your email before signing in" },
      { status: 403 },
    );
  }

  const rawToken = randomBytes(32).toString("base64url");
  const tokenHash = createHash("sha256").update(rawToken).digest("hex");
  const expiresAt = new Date(
    Date.now() + (parsed.data.remember ? 30 : 1) * 24 * 60 * 60 * 1000,
  );

  await db.insert(sessions).values({
    userId: user.id,
    tokenHash,
    expiresAt,
    ipAddress: ip,
    userAgent: req.headers.get("user-agent") ?? null,
  });

  const res = NextResponse.json({ ok: true });
  res.cookies.set("session", rawToken, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    path: "/",
    expires: expiresAt,
  });

  return res;
}

This endpoint is doing five things. Let me walk through the non-obvious ones.

The fake hash

const hashToCompare = user?.passwordHash ?? FAKE_HASH;
await bcrypt.compare(parsed.data.password, hashToCompare);

This is the timing defense nobody covers. bcrypt.compare takes ~50ms at cost factor 12. If you skip it when the user does not exist, you have a timing oracle: attackers can tell which emails are registered by measuring how long the endpoint takes. 50ms is plenty to detect over the network.

The fix is to always run bcrypt.compare, even when the user does not exist. The FAKE_HASH is a valid bcrypt string that will never match anything (I generated it once with bcrypt.hash("nothing", 12) and hardcoded it). The comparison takes the same ~50ms whether the user exists or not.

Measure this with time:

$ time curl -s -X POST http://localhost:3000/api/auth/login \
    -H 'content-type: application/json' \
    -d '{"email":"existing@example.com","password":"wrong"}'
real    0m0.082s

$ time curl -s -X POST http://localhost:3000/api/auth/login \
    -H 'content-type: application/json' \
    -d '{"email":"nonexistent@example.com","password":"wrong"}'
real    0m0.079s

3ms of noise. Good.

Without the fake hash:

$ time curl -s -X POST http://localhost:3000/api/auth/login \
    -H 'content-type: application/json' \
    -d '{"email":"existing@example.com","password":"wrong"}'
real    0m0.081s

$ time curl -s -X POST http://localhost:3000/api/auth/login \
    -H 'content-type: application/json' \
    -d '{"email":"nonexistent@example.com","password":"wrong"}'
real    0m0.022s

60ms difference. An attacker can now enumerate your user base with a wordlist.

The session cookie

res.cookies.set("session", rawToken, {
  httpOnly: true,
  secure: true,
  sameSite: "lax",
  path: "/",
  expires: expiresAt,
});

Four flags that all matter.

httpOnly: true means JavaScript on the page cannot read the cookie. This is your main defense against XSS-based session theft. An attacker who achieves script execution can still do damage, but they cannot grab the session token and walk away with it.

secure: true means the cookie only goes over HTTPS. On localhost you need to flip this off during development or use https://localhost with a self-signed cert.

sameSite: "lax" means the cookie is sent on navigation from other sites but not on cross-site POSTs. This is most of your CSRF defense for free. The alternative is "strict", which also blocks cross-site GETs and breaks the "click a link from Gmail to your app" flow.

expires: expiresAt matches the session row. The cookie expires at the same time the server-side row does, so the browser does not keep sending a cookie the server will reject anyway.

The email verification gate

if (!user.emailVerified) {
  return NextResponse.json(
    { error: "Please verify your email before signing in" },
    { status: 403 },
  );
}

If you decide to enforce email verification (you should, most of the time), this is where it goes. The error is distinguishable from "invalid credentials" because the user has already proven they know the password at this point. Telling them the specific problem is fine.

If you want to allow limited access before verification (some apps let users in but gate features), move the check out of login into the middleware that guards the feature.

The session middleware

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { createHash } from "crypto";
import { db } from "@/db";
import { sessions, users } from "@/db/schema";
import { eq, gt } from "drizzle-orm";

export async function middleware(req: NextRequest) {
  const token = req.cookies.get("session")?.value;
  if (!token) return NextResponse.redirect(new URL("/auth/login", req.url));

  const tokenHash = createHash("sha256").update(token).digest("hex");

  const row = await db.query.sessions.findFirst({
    where: and(
      eq(sessions.tokenHash, tokenHash),
      gt(sessions.expiresAt, new Date()),
    ),
    with: { user: true },
  });

  if (!row) {
    const res = NextResponse.redirect(new URL("/auth/login", req.url));
    res.cookies.delete("session");
    return res;
  }

  await db
    .update(sessions)
    .set({ lastUsedAt: new Date() })
    .where(eq(sessions.id, row.id));

  const res = NextResponse.next();
  res.headers.set("x-user-id", String(row.userId));
  return res;
}

export const config = {
  matcher: ["/dashboard/:path*", "/api/me/:path*"],
};

One thing worth calling out: the middleware updates last_used_at on every request. This is what powers the "last active 5 minutes ago" display on the account page. If you are worried about write amplification on a high traffic app, batch the updates or throttle to once per minute per session.

Logout

// app/api/auth/logout/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createHash } from "crypto";
import { db } from "@/db";
import { sessions } from "@/db/schema";
import { eq } from "drizzle-orm";

export async function POST(req: NextRequest) {
  const token = req.cookies.get("session")?.value;
  if (token) {
    const tokenHash = createHash("sha256").update(token).digest("hex");
    await db.delete(sessions).where(eq(sessions.tokenHash, tokenHash));
  }

  const res = NextResponse.json({ ok: true });
  res.cookies.delete("session");
  return res;
}

Delete the session row, delete the cookie. Both. If you only delete the cookie, the session is still valid server-side, which means an attacker holding a stolen cookie can keep using it after the user hits "log out".

CSRF

SameSite=Lax on the cookie handles most CSRF. The edge case it does not handle is a GET that changes state (you should not have those) or a POST from a form on your own origin that was manipulated by XSS (XSS is its own problem).

If you want extra defense, add a double-submit CSRF token:

// On any state-changing endpoint, check:
const csrfCookie = req.cookies.get("csrf")?.value;
const csrfHeader = req.headers.get("x-csrf-token");
if (!csrfCookie || csrfCookie !== csrfHeader) {
  return NextResponse.json({ error: "csrf" }, { status: 403 });
}

Set the cookie on session create, have your frontend read it (not HttpOnly) and attach it as a header on every mutating fetch. This is belt-and-suspenders protection and most apps do not need it, but if you are handling money or health data, add it.

Testing from the terminal

# Login with valid credentials
$ curl -i -c cookies.txt -X POST http://localhost:3000/api/auth/login \
    -H 'content-type: application/json' \
    -d '{"email":"alice@example.com","password":"Correct-Horse-1"}'

HTTP/1.1 200 OK
set-cookie: session=abc123...; Path=/; Expires=...; HttpOnly; Secure; SameSite=Lax
content-type: application/json

{"ok":true}

# Hit a protected route
$ curl -i -b cookies.txt http://localhost:3000/api/me

HTTP/1.1 200 OK
content-type: application/json

{"user":{"id":1,"email":"alice@example.com"}}

# Logout
$ curl -i -b cookies.txt -X POST http://localhost:3000/api/auth/logout

HTTP/1.1 200 OK
set-cookie: session=; Path=/; Max-Age=0
content-type: application/json

{"ok":true}

# Hit the protected route again
$ curl -i -b cookies.txt http://localhost:3000/api/me

HTTP/1.1 302 Found
location: /auth/login

Check the sessions table:

$ psql $DATABASE_URL -c "select user_id, expires_at, last_used_at from sessions;"
 user_id |        expires_at        |      last_used_at
---------+--------------------------+------------------------
       1 | 2026-05-18 14:30:22+00   | 2026-04-18 14:32:10+00

And after logout:

$ psql $DATABASE_URL -c "select count(*) from sessions where user_id = 1;"
 count
-------
     0

The same thing in kavachOS

Install, migrate, configure

pnpm add kavachos @kavachos/nextjs
pnpm kavachos migrate

The migrate command creates the users, sessions, and all the other tables this series is covering. You do not write the SQL, and you do not own the upgrade path when a new column is added.

// auth.ts
import { kavachos } from "kavachos";
import { nextjsAdapter } from "@kavachos/nextjs";

export const auth = kavachos({
  adapter: nextjsAdapter(),
  database: process.env.DATABASE_URL!,
  session: {
    expiresIn: "1d",
    rememberMeExpiresIn: "30d",
    rolling: true,
    cookie: { sameSite: "lax", secure: true, httpOnly: true },
  },
  providers: {
    password: { minLength: 12 },
  },
});

The login form

"use client";
import { useAuth } from "@kavachos/nextjs";

export default function Login() {
  const { signIn, pending, error } = useAuth();
  return (
    <form action={signIn}>
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <label>
        <input name="remember" type="checkbox" />
        Stay signed in for 30 days
      </label>
      <button disabled={pending}>Sign in</button>
      {error && <p>Email or password is incorrect.</p>}
    </form>
  );
}

The middleware

// middleware.ts
export { auth as middleware } from "@/auth";
export const config = {
  matcher: ["/dashboard/:path*", "/api/me/:path*"],
};

Done. The fake hash comparison, the SameSite=Lax cookie, the session rotation on password change, the last_used_at updates, all there. Docs at kavachos.com/docs/login.

Four things I see go wrong

Returning "email not found" or "wrong password". Always the same error. You are giving attackers free information otherwise.

No fake hash on the no-user branch. The timing leak is real and measurable over the open internet.

Using SameSite=None because someone copied a config from Stack Overflow. None requires Secure and opens the cookie up to cross-site sending. Default to Lax.

Storing the raw session token in the database. Hash it. Always. This is the same rule as reset tokens, magic link tokens, everything.

Up next

Article 05: password reset. You already know most of the shape from register and login. The twist is session rotation on success and how to make the email survive spam filters.

Follow me here so the next one shows up in your feed.

If you have a login flow bug you cannot figure out, drop the symptom in the comments. I have probably seen it.

Gagan Deep Singh builds open source tools at Glincker. Currently working on kavachOS (open source auth for AI agents and humans) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

How to build a register user flow in Next.js 15 (frontend, backend, database, email)

GDS K S — Sat, 18 Apr 2026 20:35:52 +0000

This is part 3 of the series on building an auth system from scratch. Today: the register user flow. By the end you will have a working signup page, a server endpoint, a users table, and a verification email getting delivered.

The flow, end to end

Here is what happens when a user hits "Create account":

+-------+        +------------+       +-----------+      +--------+
|Browser|  POST  |  Next.js   | INSERT| Postgres  | SEND |Resend  |
|       |------->|/api/       |------>|  users    |----->|        |
|       |        |auth/       |       |  (verify=F|      |        |
|       |<-------|register    |<------|  id=123)  |<-----|        |
|       |  200   |            |       +-----------+      +--------+
+-------+        +------------+
   |                   |
   | GET /dashboard    | 302 to /check-email
   v                   v
(not signed in yet)    (shows "check your inbox" screen)

And then, separately, when the user clicks the verification link:

+-------+          +------------+       +-----------+
|Email  |  GET     |  Next.js   | UPDATE| Postgres  |
|client |--token-->|/api/       |------>|  users    |
|       |          |auth/verify |       |  verify=T |
|       |<---------|            |<------|           |
|       |  302 to  +------------+       +-----------+
|       |  /login          |
+-------+                   |
                            | set session cookie
                            v
                       (now signed in)

Note the two separate round trips. We do not sign the user in until the email is verified. If you sign them in at registration, you effectively have no email verification because a bot can register a throwaway address, get a session, and cause damage before the email lands.

The database table

A quick note before the SQL. The DIY sections of this series show the schema you would build yourself. If you are using kavachOS, you will never write this SQL by hand. pnpm kavachos migrate ships a vetted version of these tables and keeps them upgraded. I am still showing the schema because reading it is how you understand what is happening under your auth library, whether that library is mine or someone else's.

From article 02, for reference:

create table users (
  id            bigserial primary key,
  email         citext not null unique,
  password_hash text not null,
  email_verified boolean not null default false,
  created_at    timestamptz not null default now(),
  updated_at    timestamptz not null default now()
);

create table email_verification_tokens (
  id         bigserial primary key,
  user_id    bigint not null references users(id) on delete cascade,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

create index idx_evt_user_unused
  on email_verification_tokens(user_id) where used_at is null;

Three things worth calling out:

citext for email. Postgres has a case-insensitive text type. With it, Alice@Example.com and alice@example.com collide on the unique constraint. Without it, you get duplicate accounts. Enable the extension once with CREATE EXTENSION citext;.

on delete cascade on the token. If a user is deleted, their verification tokens go with them. You do not want orphaned rows.

Partial index on unused tokens. The lookup is always "find the unused token for this user". A partial index is smaller and faster than a full one.

The frontend form

// app/auth/register/page.tsx
"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";

export default function Register() {
  const router = useRouter();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const rules = {
    minLength: password.length >= 12,
    hasNumber: /[0-9]/.test(password),
    hasLower: /[a-z]/.test(password),
    hasUpper: /[A-Z]/.test(password),
  };
  const valid = Object.values(rules).every(Boolean);

  async function submit(e: React.FormEvent) {
    e.preventDefault();
    setError(null);
    setPending(true);

    const res = await fetch("/api/auth/register", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email, password }),
    });

    setPending(false);

    if (res.status === 429) {
      setError("Too many attempts. Try again in a minute.");
      return;
    }
    if (!res.ok) {
      setError("Something went wrong. Try again.");
      return;
    }
    router.push("/auth/check-email");
  }

  return (
    <form onSubmit={submit} className="max-w-sm mx-auto mt-16 space-y-4">
      <h1 className="text-2xl font-semibold">Create account</h1>

      <label className="block">
        <span className="text-sm">Email</span>
        <input
          type="email"
          required
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="email"
        />
      </label>

      <label className="block">
        <span className="text-sm">Password</span>
        <input
          type="password"
          required
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="new-password"
        />
      </label>

      <ul className="text-xs space-y-1">
        <Rule ok={rules.minLength}>At least 12 characters</Rule>
        <Rule ok={rules.hasLower}>A lowercase letter</Rule>
        <Rule ok={rules.hasUpper}>An uppercase letter</Rule>
        <Rule ok={rules.hasNumber}>A number</Rule>
      </ul>

      {error && <p className="text-red-600 text-sm">{error}</p>}

      <button
        type="submit"
        disabled={!valid || pending}
        className="w-full rounded bg-black text-white py-2 disabled:opacity-50"
      >
        {pending ? "Creating..." : "Create account"}
      </button>
    </form>
  );
}

function Rule({ ok, children }: { ok: boolean; children: React.ReactNode }) {
  return (
    <li className={ok ? "text-green-600" : "text-zinc-500"}>
      {ok ? "✓" : "○"} {children}
    </li>
  );
}

A few notes on the form itself.

The autoComplete="new-password" tells browsers and password managers that this is a new password, which prevents them from autofilling an existing password and also prompts 1Password / Bitwarden / the browser to offer to generate a strong password.

The password rules are rendered as you type. I know there is a whole debate about password rules (NIST now says long is better than complex), but shipping "12 chars minimum, mixed case, a number" keeps the bulk of obvious bad passwords out without being annoying.

Never return a specific error for "email already exists" from the server, and never show it on the frontend. That is account enumeration.

The server endpoint

// app/api/auth/register/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import bcrypt from "bcrypt";
import { randomBytes, createHash } from "crypto";
import { db } from "@/db";
import { users, emailVerificationTokens } from "@/db/schema";
import { eq } from "drizzle-orm";
import { sendVerificationEmail } from "@/lib/email";
import { rateLimit } from "@/lib/rate-limit";

const body = z.object({
  email: z.string().email().max(254),
  password: z
    .string()
    .min(12)
    .max(256)
    .regex(/[a-z]/)
    .regex(/[A-Z]/)
    .regex(/[0-9]/),
});

export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  if (await rateLimit(`register:${ip}`, { max: 3, window: 60 })) {
    return NextResponse.json({ ok: true });
  }

  const parsed = body.safeParse(await req.json());
  if (!parsed.success) {
    return NextResponse.json({ ok: true });
  }

  const email = parsed.data.email.toLowerCase().trim();
  const passwordHash = await bcrypt.hash(parsed.data.password, 12);

  const existing = await db.query.users.findFirst({
    where: eq(users.email, email),
  });

  if (existing) {
    return NextResponse.json({ ok: true });
  }

  const [user] = await db
    .insert(users)
    .values({ email, passwordHash, emailVerified: false })
    .returning({ id: users.id });

  const raw = randomBytes(32).toString("base64url");
  const tokenHash = createHash("sha256").update(raw).digest("hex");

  await db.insert(emailVerificationTokens).values({
    userId: user.id,
    tokenHash,
    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
  });

  await sendVerificationEmail(email, raw);

  return NextResponse.json({ ok: true });
}

The thing people miss on this endpoint: every branch returns the same 200. Rate limit hit? 200. Email malformed? 200. User already exists? 200. The only thing that changes is whether an email gets sent.

This is uncomfortable the first time you write it. You feel like you are hiding errors. You are. From attackers. The legitimate user gets the experience they expect: they click "Create account", they get told to check their email, and either they registered a new account or they already had one (in which case they can go log in or use the password reset flow).

Put an "if you already have an account, log in" link on the confirmation page and this flow handles both paths gracefully.

The verification email

// lib/email.ts
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY!);
const APP_URL = process.env.APP_URL ?? "https://example.com";

export async function sendVerificationEmail(to: string, rawToken: string) {
  const link = `${APP_URL}/auth/verify?token=${rawToken}`;

  await resend.emails.send({
    from: "hello@example.com",
    to,
    subject: "Confirm your email",
    html: `
      <p>Hi,</p>
      <p>Click the link below to confirm your email and activate your account.</p>
      <p><a href="${link}">Confirm email</a></p>
      <p>This link expires in 24 hours. If you did not create an account, ignore this email.</p>
    `,
    text: `Confirm your email: ${link}\n\nThis link expires in 24 hours. If you did not create an account, ignore this email.`,
  });
}

Always include a plain text part. Gmail scores emails that only have HTML a little worse for spam, and some corporate clients only show the text version.

The "If you did not create an account" line is critical. If someone else used this email to register, the real owner needs a way to know and a reason to ignore it.

The verification endpoint

// app/api/auth/verify/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createHash } from "crypto";
import { db } from "@/db";
import { users, emailVerificationTokens } from "@/db/schema";
import { and, eq, gt, isNull } from "drizzle-orm";

export async function GET(req: NextRequest) {
  const token = req.nextUrl.searchParams.get("token");
  if (!token) {
    return NextResponse.redirect(
      new URL("/auth/verify-failed", req.url),
    );
  }

  const tokenHash = createHash("sha256").update(token).digest("hex");

  const row = await db.query.emailVerificationTokens.findFirst({
    where: and(
      eq(emailVerificationTokens.tokenHash, tokenHash),
      gt(emailVerificationTokens.expiresAt, new Date()),
      isNull(emailVerificationTokens.usedAt),
    ),
  });

  if (!row) {
    return NextResponse.redirect(
      new URL("/auth/verify-failed", req.url),
    );
  }

  await db.transaction(async (tx) => {
    await tx
      .update(users)
      .set({ emailVerified: true })
      .where(eq(users.id, row.userId));
    await tx
      .update(emailVerificationTokens)
      .set({ usedAt: new Date() })
      .where(eq(emailVerificationTokens.id, row.id));
  });

  return NextResponse.redirect(new URL("/auth/login?verified=1", req.url));
}

Same pattern as the reset flow. Hash the incoming token, look it up, check expiry and used state, update in a transaction.

We redirect to /login?verified=1 rather than signing the user in automatically. You can argue either way. Signing them in is more convenient but means holding a valid verification link becomes equivalent to holding a password. Redirecting to login makes them prove they know the password. I default to the redirect.

Testing from the terminal

Before you ship, smoke test with curl:

# Register a new user
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"Correct-Horse-1"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Try to register the same email again. Same 200.
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"Different-Horse-2"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Try a malformed email. Still 200.
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"not-an-email","password":"Correct-Horse-1"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Fire the rate limit.
$ for i in $(seq 1 10); do
    curl -s -X POST http://localhost:3000/api/auth/register \
      -H 'content-type: application/json' \
      -d "{\"email\":\"burst${i}@example.com\",\"password\":\"Correct-Horse-1\"}"
    echo
  done

If any of those return anything other than 200, you have an enumeration leak. Fix it before moving on.

Check the database:

$ psql $DATABASE_URL -c "select id, email, email_verified from users;"
 id |      email       | email_verified
----+------------------+----------------
  1 | alice@example.com| f

And the tokens:

$ psql $DATABASE_URL -c "select user_id, expires_at, used_at from email_verification_tokens;"
 user_id |        expires_at        | used_at
---------+--------------------------+---------
       1 | 2026-04-19 14:30:22+00   | null

Now click the link in your email (or look in the Resend dashboard if you have not hooked up a real inbox):

$ curl -i "http://localhost:3000/api/auth/verify?token=THE_RAW_TOKEN_FROM_THE_EMAIL"

HTTP/1.1 302 Found
location: /auth/login?verified=1

Check the database again:

$ psql $DATABASE_URL -c "select email_verified from users where id = 1;"
 email_verified
----------------
 t

That is the whole flow.

The same thing in kavachOS

If you do not want to write any of the code above, the kavachOS version is:

Install

pnpm add kavachos @kavachos/nextjs
pnpm kavachos migrate

Configure

// auth.ts
import { kavachos } from "kavachos";
import { nextjsAdapter } from "@kavachos/nextjs";

export const auth = kavachos({
  adapter: nextjsAdapter(),
  database: process.env.DATABASE_URL!,
  providers: {
    password: {
      minLength: 12,
      rules: { uppercase: true, lowercase: true, number: true },
    },
  },
  emailVerification: {
    required: true,
    tokenTTL: "24h",
  },
  email: {
    provider: "resend",
    apiKey: process.env.RESEND_API_KEY!,
    from: "hello@example.com",
  },
});

Mount the routes

// app/api/auth/[...kavachos]/route.ts
import { auth } from "@/auth";
export const { GET, POST } = auth.handlers;

Use the register hook

// app/auth/register/page.tsx
"use client";
import { useAuth } from "@kavachos/nextjs";

export default function Register() {
  const { register, pending, error } = useAuth();
  return (
    <form action={register}>
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <button disabled={pending}>Create account</button>
      {error && <p>{error.message}</p>}
    </form>
  );
}

That is the whole thing. Email verification is on by default. The rate limits, the constant-time responses, the one-time-use tokens, all there. Docs at kavachos.com/docs/register.

Three things I see go wrong in review

Returning different statuses for known vs unknown emails. The fix is always 200. I know it feels wrong. Do it anyway.

Using Math.random() for the token. It is not cryptographic. It is a deterministic PRNG seeded from process start time. Use crypto.randomBytes(32).

No rate limit on register. Register is one of the most abused endpoints because it costs you money (email sends) and attracts spam accounts. A hard limit of 3 per IP per minute is reasonable for humans and expensive for bots.

What is next

Article 04: the login flow. Session cookies, CSRF, remember me, and how to measure whether your timing is leaking. If you have been following along with the starter repo, run git checkout 04-login after article 4 ships.

Comment with your hardest register bug. I will write it up as a bonus piece.

Gagan Deep Singh builds open source tools at Glincker. Currently working on kavachOS (open source auth for AI agents and humans) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

The 8 tables behind a real auth system (Postgres schema, explained column by column)

GDS K S — Sat, 18 Apr 2026 20:30:50 +0000

This is day 2 of the series. Yesterday I showed the architecture diagram. Today we are looking at the database that sits underneath it. Every table, every column, every index, and the reason each one exists.

If you are following with kavachOS, pnpm kavachos migrate creates all of this for you, and you can skim the article to understand what is in your database. If you are building it yourself, this is your schema.

The shape at a glance

Eight tables. One user-centric join key. No fancy polymorphic associations. No stored procedures. It stays boring on purpose.

                        +-----------+
                        |   users   |
                        +-----+-----+
                              |
      +-------------+---------+---------+----------------+-----------+
      |             |         |         |                |           |
      v             v         v         v                v           v
+----------+ +----------+ +--------+ +-----------+ +-----------+ +-----------+
| sessions | |  oauth_  | |  reset | |  magic_   | |  email_   | | agent_    |
|          | |  accounts| |  tokens| |  link_    | |  verif_   | | tokens    |
|          | |          | |        | |  tokens   | |  tokens   | |           |
+----------+ +----------+ +--------+ +-----------+ +-----------+ +-----------+


                        +-----------+
                        | passkeys  |
                        +-----------+

Every table has a user_id foreign key back to users and an on delete cascade. If you delete a user, everything goes. No orphans. No manual cleanup jobs.

Postgres, and the extensions you want on

create extension if not exists "uuid-ossp";
create extension if not exists "citext";
create extension if not exists "pgcrypto";

Three of them, and each earns its keep.

citext: case-insensitive text. The moment you use it for email, Alice@Example.com and alice@example.com collide on the unique constraint. Without it, you will discover the bug when a customer complains that they cannot log in with the same email they signed up with because they capitalized it differently.

pgcrypto: gives you gen_random_uuid() for default UUID values, and digest() if you ever want to hash in the database (I do not, but it is there).

uuid-ossp: only if you want uuid_generate_v4() the old way. pgcrypto covers this, you can skip uuid-ossp if you want. I include it because older migrations assume it.

The `users` table

create table users (
  id              bigserial primary key,
  email           citext not null unique,
  password_hash   text,
  email_verified  boolean not null default false,
  failed_login_attempts int not null default 0,
  locked_until    timestamptz,
  last_login_at   timestamptz,
  created_at      timestamptz not null default now(),
  updated_at      timestamptz not null default now()
);

create index idx_users_email on users (email);

A few decisions worth explaining.

bigserial over uuid. A bigserial is 8 bytes, an indexed lookup is fast, and it sorts cleanly by creation order. A UUID is 16 bytes, the primary key index is larger, and on older Postgres versions random UUIDs cause B-tree bloat. If you are going to expose IDs in URLs, use a separate public_id column that is a UUID or a slug, and keep id as a bigserial for joins. Best of both.

password_hash is nullable. A user who signs up via Google OAuth never sets a password. A nullable password_hash means no password login is possible for that user until they explicitly set one. If you make it NOT NULL you need a sentinel value and now you have a bug waiting to happen.

failed_login_attempts and locked_until. These support account lockout after N failed attempts in a window. Some teams hate this (users get locked out and complain). I default to "lock after 10 failures in 10 minutes" which is almost invisible to humans and useful against credential stuffing.

citext on email. Already covered. Do it.

The `sessions` table

create table sessions (
  id            bigserial primary key,
  user_id       bigint not null references users(id) on delete cascade,
  token_hash    text not null unique,
  expires_at    timestamptz not null,
  last_used_at  timestamptz not null default now(),
  user_agent    text,
  ip_address    inet,
  created_at    timestamptz not null default now()
);

create index idx_sessions_user on sessions (user_id);
create index idx_sessions_expires on sessions (expires_at);
create index idx_sessions_last_used on sessions (last_used_at);

token_hash, not token. Same rule as every other token in this schema. You store the SHA-256 of the cookie value. If the database leaks, the leaked rows are useless.

user_agent and ip_address are for display only. Do not tie session validity to either. Phone carriers rotate IPs, browsers update user agents, you will end up signing users out at random.

inet type for ip_address. Postgres has a native IP type. It handles IPv4 and IPv6, it indexes correctly, and it is smaller than the equivalent text column. No reason to use text here.

The index on last_used_at. You will want this the first time a user opens the "active sessions" screen and sees 40 rows. An index lets you order by recency cheaply.

The `oauth_accounts` table

create table oauth_accounts (
  id              bigserial primary key,
  user_id         bigint not null references users(id) on delete cascade,
  provider        text not null,
  provider_uid    text not null,
  access_token    text,
  refresh_token   text,
  expires_at      timestamptz,
  scope           text,
  created_at      timestamptz not null default now(),
  updated_at      timestamptz not null default now(),
  unique (provider, provider_uid)
);

create index idx_oauth_user on oauth_accounts (user_id);

The (provider, provider_uid) unique constraint. This is the identity of the OAuth account. A Google account with sub 1234 is the same account no matter how many times it connects. Without this constraint you can end up creating duplicate users every time someone clicks "Sign in with Google".

access_token and refresh_token as text, not encrypted. I know some people want to encrypt these at rest. If you do, use application-level encryption with a KMS-managed key, not Postgres encryption (which is disk-level and does not help against a compromised database user). For most side projects, the risk calculus does not justify the operational cost.

Why scope as text instead of an array? You can, but you almost never query for "all accounts with scope X". Storing the original space-separated scope string is simpler and preserves what the provider actually granted.

The `password_reset_tokens` table

create table password_reset_tokens (
  id         bigserial primary key,
  user_id    bigint not null references users(id) on delete cascade,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

create index idx_prt_user_unused on password_reset_tokens (user_id) where used_at is null;
create index idx_prt_expires on password_reset_tokens (expires_at);

Partial index on unused tokens. The lookup during a reset is "find the unused token for this user that matches this hash". A partial index where used_at is null is smaller and faster than a full one, because used tokens never participate in the lookup.

token_hash is unique. The odds of a random 32-byte token colliding are effectively zero, but the unique constraint gives you a free integrity check and a better error message if your random number generator ever breaks.

used_at is nullable. On successful reset, set it to now(). The verification query checks used_at is null, so a single row can be used exactly once. This is the whole one-time-use property.

The `magic_link_tokens` table

create table magic_link_tokens (
  id         bigserial primary key,
  user_id    bigint references users(id) on delete cascade,
  email      citext not null,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

create index idx_mlt_email on magic_link_tokens (email);
create index idx_mlt_expires on magic_link_tokens (expires_at);

user_id is nullable. A magic link can be sent to an email that does not yet have an account. On click, the system either signs in the existing user or creates a new one. Nullable user_id lets you create the token before the user exists.

email is stored directly. Redundant if the user exists, but necessary for the new-user case. Keep it.

The `email_verification_tokens` table

create table email_verification_tokens (
  id         bigserial primary key,
  user_id    bigint not null references users(id) on delete cascade,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

create index idx_evt_user_unused on email_verification_tokens (user_id) where used_at is null;

This table is almost identical to password_reset_tokens. Two observations.

Why not combine them into one tokens table with a type column? You can, and some libraries do. I keep them separate because the access patterns differ (reset tokens expire in 15 minutes, verification tokens in 24 hours), the cleanup jobs run at different cadences, and splitting them keeps each table small and easy to reason about. A type column also means every query has a where type = ... clause, which is easy to forget.

The 24 hour expiry is intentional. A password reset window needs to be short because the blast radius is high. An email verification window is lower risk (the worst case is a user cannot activate their account) so the window is longer.

The `passkeys` table

create table passkeys (
  id              bigserial primary key,
  user_id         bigint not null references users(id) on delete cascade,
  credential_id   text not null unique,
  public_key      bytea not null,
  counter         bigint not null default 0,
  transports      text[],
  name            text,
  last_used_at    timestamptz,
  created_at      timestamptz not null default now()
);

create index idx_passkeys_user on passkeys (user_id);
create index idx_passkeys_cred on passkeys (credential_id);

credential_id is the WebAuthn identifier. It comes back from the browser during registration. We store it as base64url text. The unique constraint prevents the same key from being registered twice.

public_key as bytea. The key material is binary. Use the native bytea type, not text. It is smaller and does not require decoding on every verification.

counter starts at 0 and increments on each use. The WebAuthn spec uses this as a cloning detection signal. If an assertion comes in with a counter lower than the last-seen value, the authenticator has been cloned. Handle that case by invalidating the credential.

transports as text[]. The browser tells you which transports the authenticator supports (usb, nfc, ble, internal, hybrid). Storing them lets you pass the right set back to the browser on the next authentication, which speeds up the UX.

name is user-supplied. Let users name their passkeys ("Work laptop", "Phone"). When they lose a device, this is how they find the right row to revoke.

The `agent_tokens` table

create table agent_tokens (
  id           bigserial primary key,
  user_id      bigint not null references users(id) on delete cascade,
  token_hash   text not null unique,
  name         text,
  permissions  text[] not null default '{}',
  expires_at   timestamptz,
  last_used_at timestamptz,
  revoked_at   timestamptz,
  created_at   timestamptz not null default now()
);

create index idx_agent_user on agent_tokens (user_id);
create index idx_agent_active on agent_tokens (user_id) where revoked_at is null;

This is the new one. The agent token system is how scripts, cron jobs, and AI agents authenticate on behalf of a user. Article 11 goes deep on this.

permissions as a text array. Something like {reports:read, invoices:write}. Granular enough to be useful, simple enough to reason about. You can upgrade to a real scope/policy engine later.

expires_at is nullable. Some agent tokens live forever (long-running bots). Most should have an expiry. Treat nullable as "no expiry" and document it clearly.

revoked_at is separate from expires_at. Revocation is explicit. Expiry is passive. Different signals, different columns.

Drizzle schema (TypeScript)

If you are using Drizzle ORM, here is the whole thing in one file:

// db/schema.ts
import {
  bigserial,
  bigint,
  boolean,
  inet,
  integer,
  pgTable,
  text,
  timestamp,
  bytea,
  unique,
  index,
} from "drizzle-orm/pg-core";
import { citext } from "./citext";

export const users = pgTable(
  "users",
  {
    id: bigserial("id", { mode: "number" }).primaryKey(),
    email: citext("email").notNull().unique(),
    passwordHash: text("password_hash"),
    emailVerified: boolean("email_verified").notNull().default(false),
    failedLoginAttempts: integer("failed_login_attempts").notNull().default(0),
    lockedUntil: timestamp("locked_until", { withTimezone: true }),
    lastLoginAt: timestamp("last_login_at", { withTimezone: true }),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (t) => ({ emailIdx: index("idx_users_email").on(t.email) }),
);

export const sessions = pgTable(
  "sessions",
  {
    id: bigserial("id", { mode: "number" }).primaryKey(),
    userId: bigint("user_id", { mode: "number" })
      .notNull()
      .references(() => users.id, { onDelete: "cascade" }),
    tokenHash: text("token_hash").notNull().unique(),
    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
    lastUsedAt: timestamp("last_used_at", { withTimezone: true }).notNull().defaultNow(),
    userAgent: text("user_agent"),
    ipAddress: inet("ip_address"),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (t) => ({
    userIdx: index("idx_sessions_user").on(t.userId),
    expiresIdx: index("idx_sessions_expires").on(t.expiresAt),
    lastUsedIdx: index("idx_sessions_last_used").on(t.lastUsedAt),
  }),
);

// ...same pattern for the other 6 tables, omitted for space

The Drizzle citext helper is a tiny file:

// db/citext.ts
import { customType } from "drizzle-orm/pg-core";
export const citext = customType<{ data: string }>({
  dataType: () => "citext",
});

Full schema with all 8 tables is in the starter repo at github.com/kavachos/nextjs-auth-from-scratch on the 02-schema branch.

Running the migrations

$ pnpm drizzle-kit generate
✓ Your SQL migrations file saved to drizzle/0000_initial.sql

$ pnpm drizzle-kit push
Pulling schema from database...
Changes applied:
  users                    [+] 9 columns
  sessions                 [+] 8 columns
  oauth_accounts           [+] 10 columns
  password_reset_tokens    [+] 6 columns
  magic_link_tokens        [+] 7 columns
  email_verification_tokens[+] 6 columns
  passkeys                 [+] 9 columns
  agent_tokens             [+] 9 columns

Verify it all landed:

$ psql $DATABASE_URL -c "\dt"
                    List of relations
 Schema |           Name            | Type  | Owner
--------+---------------------------+-------+--------
 public | agent_tokens              | table | postgres
 public | email_verification_tokens | table | postgres
 public | magic_link_tokens         | table | postgres
 public | oauth_accounts            | table | postgres
 public | passkeys                  | table | postgres
 public | password_reset_tokens     | table | postgres
 public | sessions                  | table | postgres
 public | users                     | table | postgres
(8 rows)

And the indexes:

$ psql $DATABASE_URL -c "\di"
                       List of relations
 Schema |             Name              | Type  | Table
--------+-------------------------------+-------+---------
 public | idx_agent_active              | index | agent_tokens
 public | idx_agent_user                | index | agent_tokens
 public | idx_evt_user_unused           | index | email_verification_tokens
 public | idx_mlt_email                 | index | magic_link_tokens
 public | idx_mlt_expires               | index | magic_link_tokens
 public | idx_oauth_user                | index | oauth_accounts
 public | idx_passkeys_cred             | index | passkeys
 public | idx_passkeys_user             | index | passkeys
 public | idx_prt_expires               | index | password_reset_tokens
 public | idx_prt_user_unused           | index | password_reset_tokens
 public | idx_sessions_expires          | index | sessions
 public | idx_sessions_last_used        | index | sessions
 public | idx_sessions_user             | index | sessions
 public | idx_users_email               | index | users
(14 rows)

Cleanup: the expiry janitor

Tokens accumulate. Sessions accumulate. Without cleanup, the tables grow and lookups slow down.

Run this once a day on a cron:

delete from password_reset_tokens
  where expires_at < now() - interval '7 days';

delete from magic_link_tokens
  where expires_at < now() - interval '7 days';

delete from email_verification_tokens
  where expires_at < now() - interval '30 days';

delete from sessions
  where expires_at < now() - interval '1 day';

Why the extra grace period? If a user comes back with an expired link, you want to show them "this link expired" rather than "this link does not exist". Keeping expired rows around for a week gives you the ability to distinguish those cases in the query.

Agent tokens and passkeys do not get cleaned up automatically. They are explicit user artifacts and should only go when the user asks or when the user itself is deleted.

The same thing in kavachOS

If you do not want to own any of this, the kavachOS version is one command:

$ pnpm add kavachos @kavachos/nextjs
$ pnpm kavachos migrate

Running migrations against $DATABASE_URL
 ✓ 0001_users
 ✓ 0002_sessions
 ✓ 0003_oauth_accounts
 ✓ 0004_password_reset_tokens
 ✓ 0005_magic_link_tokens
 ✓ 0006_email_verification_tokens
 ✓ 0007_passkeys
 ✓ 0008_agent_tokens
 ✓ 0009_indexes

Done. 8 tables, 14 indexes.

The schema kavachOS ships is close to this article, with two differences: it uses uuid for id columns by default (so tenants in multi-tenant deployments do not share key spaces) and it ships its own cleanup job as a scheduled worker. Docs: kavachos.com/docs/schema.

If you want to add custom columns to users (like full_name, avatar_url, tenant_id), kavachOS supports that through a schema extension mechanism. You do not fork the library.

Three things I would change if I had to do this again

I would use bigint everywhere instead of bigserial. Postgres 10+ has identity columns (generated always as identity) which are cleaner than sequences and easier to work with in multi-master setups. I default to bigserial because most tutorials do, but identity columns are better if you are starting fresh.

I would put locked_until on a separate user_security table. It is a hot-updated column and separating it keeps the main users row static. Minor optimization, only matters at scale.

I would denormalize email_verified out of users into an event log. Having a boolean that represents "the current state of a verification process" means you lose the history. A small user_events table that records every verification attempt, lockout, and password change is invaluable when debugging and cheap to maintain.

None of these are blocking. The schema above ships and runs for years.

What is next

Tomorrow: the register flow, which uses exactly this schema. Then the login flow with the timing attack defense nobody covers in other tutorials.

Comment with the column you think I got wrong. I like database arguments.

Gagan Deep Singh builds open source tools at Glincker. Currently working on kavachOS (open source auth for AI agents and humans) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

I've built auth six times. Here's the system I would build today

GDS K S — Sat, 18 Apr 2026 20:12:58 +0000

I am writing this series because I have built authentication from scratch six times, and every time I got it about 80 percent right and discovered the last 20 percent at 2am when a user said something weird happened.

The point is not to talk you into rolling your own auth. Most of the time you should not. The point is that if you are going to, or if you are trying to read the source of a library that does it for you, you should see all the moving parts laid out. Once you see them, you can decide whether to maintain them yourself or let kavachOS do it.

What we are building

A Next.js 15 app with Postgres. Email and password, magic link, Google and GitHub OAuth, passkeys, rate limiting, session rotation, password reset, email verification, and an agent token system for AI scripts that call your API on behalf of users.

By the end of the series you will have either:

Built the whole thing yourself and know exactly what every line does
Looked at the "and the same thing in kavachOS" sections and decided your weekend is worth more than an auth rewrite

Both are fine. I do both depending on the project.

The series in one diagram

                         +-------------------+
                         |   Browser / App   |
                         +---------+---------+
                                   |
                                   | HTTPS
                                   v
                    +----------------------------+
                    |   Next.js app (App Router) |
                    |   /app/auth/*   UI pages   |
                    |   /api/auth/*   endpoints  |
                    +------+---------------+-----+
                           |               |
                  session  |               | outbound email
                  cookie   |               v
                           |          +---------+
                           |          |  Resend |
                           v          +---------+
                  +--------+---------+
                  |   Postgres       |
                  |   users          |
                  |   sessions       |
                  |   oauth_accounts |
                  |   reset_tokens   |
                  |   magic_tokens   |
                  |   verify_tokens  |
                  |   passkeys       |
                  |   agent_tokens   |
                  +--------+---------+
                           |
                           | read via
                           v
                  +------------------+
                  |  Redis / KV      |
                  |  rate limits     |
                  |  active session  |
                  |  lookups         |
                  +------------------+

That is the whole thing. Nine tables, one cache, two network dependencies (Postgres and email), one frontend. Every article in the series fills in one box.

What each article covers

#	Article	What ships
01	You are here	Architecture, schema preview, series map
02	Database schema	SQL for all 8 tables, index choices, the drizzle schema
03	Register user	Signup form, password rules, hash choice, email verification trigger
04	Login	Form, session cookie, CSRF token, remember me, timing defense
05	Password reset	Token generation, one time use, session rotation on success
06	Email verification	Sending, verifying, re-sending, bounce handling
07	Magic link login	Passwordless token flow with 10 minute expiry
08	OAuth (Google, GitHub)	PKCE, state, callback validation, account linking
09	Passkeys	WebAuthn registration and assertion with a password fallback
10	Rate limiting	Login attempts, email enumeration defense, CAPTCHA gating
11	Agent tokens / MCP OAuth	Minting scoped tokens for scripts and AI agents
12	Deploy	Cloudflare Workers with D1 and Durable Objects

The tables at a glance

I will spend article 02 on each of these. If you are following with kavachOS rather than building by hand, you do not write the DDL: pnpm kavachos migrate creates and maintains all of these for you. Article 02 still exists because it is worth knowing what is in your database, whichever library you use.

Here is the preview so you have the shape in your head:

users                       sessions
+--------------+            +------------------+
| id           |<-----+     | id               |
| email        |      +-----| user_id          |
| password_hash|            | token_hash       |
| email_verif. |            | expires_at       |
| created_at   |            | last_used_at     |
+--------------+            +------------------+

oauth_accounts              password_reset_tokens
+--------------+            +------------------+
| id           |            | id               |
| user_id      |------+ +---| user_id          |
| provider     |      | |   | token_hash       |
| provider_uid |      | |   | expires_at       |
| access_token |      | |   | used_at          |
+--------------+      | |   +------------------+
                      | |
magic_link_tokens     | |   email_verification_tokens
+--------------+      | |   +------------------+
| id           |      | |   | id               |
| user_id      |------+ +---| user_id          |
| email        |      | |   | token_hash       |
| token_hash   |      | |   | expires_at       |
| expires_at   |      | |   | used_at          |
+--------------+      | |   +------------------+
                      | |
passkeys              | |   agent_tokens
+--------------+      | |   +------------------+
| id           |      | |   | id               |
| user_id      |------+ +---| user_id          |
| credential_id|            | token_hash       |
| public_key   |            | permissions[]    |
| counter      |            | expires_at       |
+--------------+            +------------------+

If you squint, it is 8 tables with one join key. That is on purpose. Boring schemas age well.

The security properties the system has to maintain

Every article will reference this list. Tape it to your monitor.

No account enumeration. /login, /forgot-password, /register return the same response for "user exists" and "user does not exist". Timing differences on those endpoints should be under 50ms.
No token reuse. Every reset link, magic link, and verification link is one time use. The check is a used_at IS NULL clause, not an application-level flag.
Short expiries. Reset and magic link tokens expire in 15 minutes. Email verification in 24 hours. Sessions can run long (30 days) because they are revocable.
Hashed token storage. Every token in the database is the SHA-256 of the raw value. The raw value exists only in the email or URL.
Session rotation on privilege change. Password reset, email change, and OAuth unlink all invalidate every existing session for that user.
Rate limits on every unauthenticated endpoint. Login, forgot-password, register, magic link request, verification resend.
CSRF on session-carrying endpoints. Double submit cookie or SameSite=Lax + custom header.
Structured audit logs. auth.register.success, auth.login.failure, auth.session.rotated, and so on. You will want these the first time a user claims they did not do something.

The trade-off you are making by doing this yourself

Writing this code is not that hard. Maintaining it is. Every one of these articles represents 2 to 6 hours of initial implementation plus a long tail of reading advisories, upgrading libraries, and handling weird bugs.

The rough math:

DIY auth
  initial build:       60 hours of focused work
  annual maintenance:  30 to 80 hours
  incident cost:       unknown, but nonzero

Managed (Auth0, Clerk)
  initial build:       4 hours
  annual cost:         $1,000 to $50,000 depending on MAU
  incident cost:       their team handles it

Open source library (kavachOS, Better Auth)
  initial build:       4 to 8 hours
  annual maintenance:  5 to 15 hours (upgrades)
  incident cost:       you handle it, but the code is readable

If you are a solo dev with a side project, the library path is usually right. If you are at a company with a security team that wants to own the code, DIY is reasonable. If you are between those, a managed service buys you time.

I use kavachOS because I want to own the code but not write it. Your answer will depend on your context.

How to follow along

Pick one of these three paths:

Path A: read along, do not build. You will still get value from seeing how the pieces fit.

Path B: build with me from scratch. Clone the starter repo at github.com/kavachos/nextjs-auth-from-scratch. Each article has a matching branch.

Path C: build with kavachOS and skim the DIY parts. Run:

pnpm create next-app@latest my-auth-app --typescript --app --tailwind
cd my-auth-app
pnpm add kavachos @kavachos/nextjs

Then follow the "kavachOS version" section at the bottom of each article.

What you need installed

Before article 02, have these ready:

node --version   # 20 or higher
pnpm --version   # 9 or higher
psql --version   # 15 or higher, or a Neon/Supabase URL

A Resend account (or any SMTP provider) for email. An Upstash Redis instance or Cloudflare KV namespace for rate limits. That is it.

Why I am writing this as a series instead of one mega post

Two reasons.

One, auth is broken up into real sub-problems that each deserve their own treatment. Jamming all of it into one 40,000 word post means nobody reads it.

Two, I want to write for 12 days straight. Forcing publication at this cadence means I cannot perfect anything, which is good. The first draft of a system is more honest than the polished one.

Next up

Article 02: the database schema. Every table, every index, every column nobody thinks about until they get a support ticket at midnight. We will also look at why text beats varchar on Postgres, why id should be a bigserial and not a uuid in most cases, and how to make your email column case-insensitive without hating yourself.

See you tomorrow.

Comment with the article you would most like me to skip ahead to. If enough people ask for the same one, I will reorder the series.

Tags: #authentication #webdev #nextjs #tutorial

Checking TLS cert expiry across your infrastructure

GDS K S — Wed, 15 Apr 2026 17:10:53 +0000

A cert expired on one of our staging services last month. Nobody noticed for two hours because our monitoring only checked HTTP 200s, and the TLS error happened before HTTP even got involved. The load balancer just refused connections silently.

Staging, so low impact. But it got me thinking about how I was checking certs across all our services. The honest answer: I mostly wasn't.

the script I used to have

I had a bash script that looked roughly like this:

#!/bin/bash
HOSTS="api.example.com staging.example.com admin.example.com"

for host in $HOSTS; do
  expiry=$(echo | openssl s_client -connect "$host:443" 2>/dev/null \
    | openssl x509 -noout -enddate 2>/dev/null \
    | cut -d= -f2)
  echo "$host: $expiry"
done

It worked. Sort of. The output was a list of dates in openssl's format (Jun 15 12:00:00 2026 GMT), which is fine for a human glancing at it but annoying to parse if you want to do anything programmatic. And if a host was unreachable, the script would hang for the TCP timeout before moving on.

I also had no easy way to say "tell me which ones expire within 30 days." I'd just eyeball the dates.

what I switched to

I've been building a cert tool called sslx and one of the commands that turned out to be the most useful is expiry. It checks multiple hosts in one go:

$ sslx expiry api.example.com staging.example.com admin.example.com

  Host                           Expires          Days  Status
  ────────────────────────────────────────────────────────────────
  ✓ api.example.com:443            2026-08-12        119  OK
  ✓ staging.example.com:443        2026-04-22          7  WARNING
  ✓ admin.example.com:443          2026-05-30         45  OK

The status column does the date math for me. OK means more than 30 days. WARNING is 30 days or less. CRITICAL is 7 days or less. EXPIRED is, well, expired.

The exit code is 1 if anything is expired or within 7 days. That's the part that makes it useful in automation.

putting it in a cron job

Here's what I actually run now:

# /etc/cron.d/cert-check (runs daily at 9am)
0 9 * * * gagan sslx expiry \
  api.prod.example.com \
  web.prod.example.com \
  staging.example.com \
  admin.example.com \
  || echo "cert expiring soon" | mail -s "cert warning" ops@example.com

Because the exit code is non-zero when something is expiring, the || branch triggers and sends an email. Simple. No parsing dates in bash, no jq gymnastics.

For something more structured, you can use JSON output:

sslx expiry api.example.com --json | jq '.[] | select(.days_remaining < 30)'

in CI/CD pipelines

I also added an expiry check to our deployment pipeline. We verify the target environment's certs aren't about to expire before deploying. After the staging thing I figured why not:

# .github/workflows/deploy.yml
- name: check target certs
  run: |
    sslx expiry ${{ vars.DEPLOY_HOST }} || {
      echo "::error::TLS cert expiring soon on ${{ vars.DEPLOY_HOST }}"
      exit 1
    }

If the cert is expiring within a week, the deploy fails. We'd rather catch it there than find out at 2am.

checking local cert files too

The same tool handles local cert files, not just live hosts. If you have certs sitting on disk (maybe pulled from a vault, or generated for local dev), you can inspect them the same way:

$ sslx inspect cert.pem

╭─ Certificate 1 of 1 ────────────────────────────────────╮
│  Subject:  CN=*.example.com                             │
│  Issuer:   CN=Let's Encrypt Authority X3                │
│                                                         │
│  Valid:    2026-01-15 → 2026-04-15                      │
│  Expires:  ██░░░░░░░░  12 days remaining [!]            │
│                                                         │
│  Key:      ECDSA P-256 (256 bit)                        │
│  SANs:     *.example.com, example.com                   │
╰─────────────────────────────────────────────────────────╯

That progress bar is surprisingly useful. Red at a glance.

You can also pipe certs from other tools. This one comes up a lot with kubernetes:

kubectl get secret tls-cert -o jsonpath='{.data.tls\.crt}' \
  | base64 -d \
  | sslx inspect -

what I'm not doing here

I'm not replacing proper cert management. If you're using cert-manager or ACME renewals, those handle rotation automatically and you probably don't need to manually track expiry dates.

But I've found there's always a handful of certs that don't fit neatly into the automated renewal pipeline. Internal services with self-signed certs. Third party integrations where someone uploaded a cert manually six months ago. Staging environments that nobody quite owns.

Those are the ones that expire at the worst time. And those are the ones worth checking daily with a simple cron job.

install

cargo install sslx
# or
brew install glincker/tap/sslx

Single binary, no dependencies. Works on Linux, macOS, and Windows.

github.com/glincker/sslx

I stopped memorizing openssl flags

GDS K S — Wed, 15 Apr 2026 17:07:02 +0000

Every few weeks I need to do something with a certificate. Check when it expires. Look at what SANs are on it. Generate a self-signed one for local dev. Create a CSR. Convert between formats.

And every single time, I google the openssl command.

It's not that the commands are hard. It's that they're inconsistent enough that I can never quite remember them. Is it openssl x509 -in or openssl x509 -text? Do I need -noout? What about the s_client pipeline thing where I have to pipe through two commands just to see a cert from a live server?

I've been writing software for years. I can hold a lot of random CLI syntax in my head. But openssl never sticks. The subcommands follow no pattern I can internalize, and the flags feel like they were designed by committee across two decades. Which, to be fair, they were.

what I actually do with certificates

When I thought about it, my cert tasks fall into maybe 10 categories:

Look at a cert file
Connect to a server and see its TLS setup
Check if a cert is expiring soon (across multiple hosts)
Generate a self-signed cert for development
Create a CSR
Convert between PEM/DER/PKCS12
Check if a cert and private key match
Grade a server's TLS configuration
Decode a JWT (yeah, this comes up more than I expected)
Verify a certificate chain

That's it. I'm not running a certificate authority. I'm not doing low level crypto operations. I'm doing the same 10 things over and over, and reaching for a tool that does 200 things, most of which I'll never touch.

the openssl tax

Here's what some of these look like in openssl:

# check when a remote cert expires
echo | openssl s_client -connect host:443 2>/dev/null | openssl x509 -noout -enddate

# generate a self-signed cert with EC key and SANs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout key.pem -out cert.pem -days 365 -nodes -batch \
  -subj "/CN=localhost"

# check if cert and key match
diff <(openssl x509 -noout -modulus -in cert.pem) \
     <(openssl rsa -noout -modulus -in key.pem)

I call it a tax because it's time I spend repeatedly, on something that should be simple, and the complexity doesn't buy me anything. I don't need openssl's full power. I need the 10 things.

so I built the 10 things

I wrote a tool called sslx. Same tasks, less typing:

# check when a remote cert expires
sslx expiry host

# generate a self-signed cert
sslx generate --cn localhost

# check if cert and key match
sslx match cert.pem key.pem

The pattern is: sslx <verb> <target>. That's it. No subcommand soup, no flags you need to memorize. The verbs are the same words you'd use if you were describing the task out loud.

Here's the full comparison:

What you're doing	openssl	sslx
Look at a cert	`openssl x509 -in cert.pem -text -noout`	`sslx inspect cert.pem`
TLS handshake	`openssl s_client -connect host:443 2>/dev/null \	openssl x509 -text`
Self-signed cert	`openssl req -x509 -newkey ec ...` (6 flags)	`sslx generate --cn localhost`
Check expiry	`echo \	openssl s_client ... \
Cert+key match	{% raw %}`diff <(openssl x509 ...) <(openssl rsa ...)`	`sslx match cert.pem key.pem`
PEM to DER	`openssl x509 -in cert.pem -outform DER -out cert.der`	`sslx convert cert.pem --to der`
TLS grade	(go to ssllabs.com)	`sslx grade host`
Decode JWT	(go to jwt.io)	`sslx decode <token>`

what the output looks like

This is probably the part that sold me on actually using it daily. openssl gives you a wall of ASN.1 text. sslx gives you the parts you care about:

$ sslx grade github.com

  ╭──────────────────────────────────────────╮
  │  github.com:443                  Grade: A+  │
  ╰──────────────────────────────────────────╯

  ✓ Protocol      TLS 1.3
  ✓ Cipher        TLS13_AES_128_GCM_SHA256 (AEAD)
  ✓ Certificate   Valid, 49 days remaining
  ✓ Key           ECDSA P-256 (256 bit)
  ✓ Hostname      github.com in SANs
  ✓ Chain         Complete (3 certs)
  ✓ ALPN          HTTP/2 supported

Or checking expiry across a bunch of hosts at once:

$ sslx expiry google.com github.com cloudflare.com stripe.com

  Host                           Expires          Days  Status
  ────────────────────────────────────────────────────────────────
  ✓ google.com:443                 2026-06-15         61  OK
  ✓ github.com:443                 2026-06-03         49  OK
  ✓ cloudflare.com:443             2026-06-10         56  OK
  ✓ stripe.com:443                 2026-09-01        139  OK

The expiry command returns exit code 1 if anything expires within 7 days. I have this in a cron job now.

CI/CD and scripting

Everything supports --json for when you need machine readable output:

sslx grade example.com --json | jq '.grade'
sslx inspect cert.pem --json | jq '.certificates[0].sans'

And you can pipe certs from stdin:

cat cert.pem | sslx inspect -
kubectl get secret tls-cert -o jsonpath='{.data.tls\.crt}' | base64 -d | sslx inspect -

That second one is real. I use it to check certs stored in k8s secrets without writing temp files.

the technical bits, briefly

It's written in Rust, single binary, no runtime dependencies. Uses rustls instead of linking against system OpenSSL, so it works the same everywhere. About 4MB.

It's fast too, though I don't think that matters much for a cert tool. sslx inspect on a local cert takes about 2ms.

Install with cargo or homebrew:

cargo install sslx
# or
brew install glincker/tap/sslx

what it doesn't do

sslx is not a replacement for openssl the library. It doesn't do symmetric encryption, PKCS operations, S/MIME, or any of the hundred other things openssl can do. If you need those, use openssl.

It replaces the 10 cert/TLS commands I kept googling. Nothing more.

github.com/glincker/sslx

If you have opinions about what commands are missing or how the output should look, open an issue. I'm using this daily so I actually read them.

Your terminal is mass, here are 280+ tools to fix it

GDS K S — Wed, 15 Apr 2026 04:58:17 +0000

I mass-replaced every classic Unix tool in my dotfiles. It took a few years of stumbling into alternatives, and at some point I realized the list was absurdly long. So I organized it.

thegdsks / awesome-modern-cli

A curated list of modern alternatives to classic command-line tools. Faster, prettier, smarter replacements for the Unix utilities you use every day.

Awesome Modern CLI

A curated list of modern alternatives to classic command-line tools.

The terminal is having a renaissance. Faster, prettier, smarter tools are replacing the Unix classics you've used for decades. This list helps you find them.

Contribute

Highlights

bat - A `cat` clone with syntax highlighting and Git integration

eza - A modern replacement for `ls` with colors, icons, and git integration

delta - A syntax-highlighting pager for git, diff, and grep output

lazygit - A simple terminal UI for git commands

btop - A resource monitor with beautiful TUI and extensive features

fzf - A general-purpose command-line fuzzy finder

zoxide - A smarter `cd` command that learns your habits

lazydocker - The lazier way to manage everything Docker

starship - Minimal, blazing-fast, and infinitely customizable prompt for any shell

hyperfine - A command-line benchmarking tool with statistical analysis

gping - Ping, but with a graph

ripgrep -…

View on GitHub

How it started

Two years ago I watched someone share their screen and their cat output had syntax highlighting. Colored, with line numbers, git diff markers in the gutter. I asked what it was. "bat."

That was it. One tool. Then I found ripgrep, and grep felt broken. Then fd, and find felt like writing a legal contract. Then eza, and plain ls looked like a DOS prompt from 1993.

Before I knew it, half my shell aliases pointed to Rust binaries I'd installed from cargo or brew, and the other half were Go tools I found on some random HN thread at 2am.

The "where do I find all of these" problem

I kept bookmarking individual GitHub repos. Then I'd forget them. Then I'd rediscover them six months later and install them again.

When I searched for a single list, the options were:

modern-unix (33k stars) - gorgeous, but only 30 tools and hasn't been updated since 2024
awesome-cli-apps (19k stars) - 500 entries, no way to tell what replaces what
awesome-rust (57k stars) - CLI tools buried between web frameworks and game engines

Nobody had organized these by "I use grep, what's better?" So I did it.

What I found: 282 tools across 44 categories

The full list is here: awesome-modern-cli

But let me walk you through the categories that surprised me the most.

The replacements everyone knows

You've probably heard of these. If not, stop reading this article and go install them right now.

You type	You should type	What changes
`cat file.py`	`bat file.py`	Syntax highlighting, line numbers, git markers
`grep -r "TODO" .`	`rg "TODO"`	5-10x faster, respects .gitignore by default
`find . -name "*.ts"`	`fd ".ts"`	Simpler syntax, way faster, colored output
`ls -la`	`eza -la --icons`	Colors, icons, git status per file
`du -sh *`	`dust`	Visual bar chart of disk usage
`cd projects/app`	`z app`	Learns your habits, jumps anywhere
`diff file1 file2`	`delta`	Syntax-aware, side-by-side, git integration

If you already use all of these, you're the target audience for the rest of this article.

The replacements nobody talks about

Here's where it gets interesting. These are the tools I found while building the list that made me go "how did I not know about this?"

television - fzf but faster

Everyone knows fzf. It's the fuzzy finder that made ctrl+r usable. But television is a Rust rewrite of the same concept that's noticeably faster on large inputs. If you pipe 100k lines into it, you feel the difference.

scooter - interactive find and replace

Every time I need to rename a variable across files, I end up writing some sed/perl one-liner that I have to google the syntax for. scooter gives you a TUI where you type the search, type the replacement, see a live preview of every change across every file, and hit enter. That's it.

trippy - ping meets traceroute

trippy combines ping and traceroute into a single TUI with a live graph. You see every hop, the latency at each one, and packet loss. All updating in real time. I used to run mtr for this, but trippy's interface is cleaner.

jnv - interactive jq

If you use jq, you know the pain of writing a filter, running it, getting an error, tweaking, running again. jnv gives you a split-screen TUI where you type jq expressions and see the output update live. Sounds simple. Saved me more time than I'd like to admit.

rainfrog - database TUI

rainfrog is a terminal database client for Postgres, MySQL, and SQLite. Think pgAdmin, but in your terminal. Browse tables, run queries, see results. I was using psql with a bunch of \d commands before this.

The Rust thing

I wasn't planning to track implementation languages. I added it because I was curious and then the numbers got weird.

Language	Tools	Percentage
Rust	146	52%
Go	46	16%
Python	17	6%
C/C++	16	6%
Zig	3	1%
Other	54	19%

Over half the list is Rust. Not because I went looking for Rust tools. Just because when you search for "modern X replacement" for any Unix command, the top result is usually a Rust project.

There's something about the CLI space that attracts Rust developers. Maybe it's the single-binary distribution. Maybe it's the performance. Maybe the Rust community just has a thing for rewriting Unix tools. Whatever it is, the result is that the terminal is becoming a Rust runtime whether you intended it or not.

The categories that shouldn't exist but do

Some of these categories made me question my life choices when I realized there were enough tools to fill them.

Terminal emulators (5 entries) - We have five GPU-accelerated terminal emulators in 2026. Alacritty, Ghostty, WezTerm, Rio, and Warp. Your terminal now requires a GPU. Let that sink in.

Database TUIs (7 entries) - Seven different ways to browse your database from the terminal. We have more TUI database clients than most companies have databases.

Fuzzy finders (3 entries) - Three competing fuzzy finders. Because apparently fzf, the tool that changed how everyone uses their shell, needed competition.

Kubernetes TUIs (2 entries) - k9s and kdash. For when you want to manage your orchestration layer for your container runtime from a terminal user interface. We've come full circle from mainframes.

What I actually use daily

My honest daily setup, not the aspirational "I should use all of these" list:

# ~/.zshrc (the relevant parts)

alias cat="bat"
alias ls="eza --icons"
alias find="fd"
alias grep="rg"
alias du="dust"
alias diff="delta"
alias top="btop"
alias cd="z"

# these aren't aliases, just tools I reach for
# lazygit     - for anything git
# fzf         - ctrl+r and piping
# just        - project task runner
# bat         - reading files
# hyperfine   - benchmarking scripts

That's 12 tools out of 282. The other 270 are for when you need something specific. The list is a reference, not a shopping list.

How I organized it

The organizational principle is simple: what are you replacing?

If you use grep and want something better, go to the "Text Search" section. If you use top and want something prettier, go to "System Monitoring." Every entry tells you:

What it's called
Where to find it
What it does in one sentence
What language it's written in

No star counts (they go stale). No screenshots in the list itself (there's a highlight reel at the top for that). Just the information you need to decide if you want to try it.

Everything is alphabetically sorted within sections so you can scan quickly.

The list

github.com/thegdsks/awesome-modern-cli

282 tools. 44 categories. CC0 licensed. If I missed something, open an issue or PR.

I'm keeping it updated, and the CI runs a link checker weekly so nothing goes stale without me noticing.

Gagan Deep Singh builds open source tools. Currently working on sslx, a modern alternative to OpenSSL's CLI.

Your VS Code Extensions Are a Supply Chain Attack Surface

GDS K S — Mon, 13 Apr 2026 20:50:19 +0000

Last week a VS Code extension called specstudio.code-wakatime-activity-tracker was caught dropping a Zig-compiled binary onto developer machines. It looked like WakaTime. It tracked your activity alright, just not in the way you expected.

This is part of a campaign researchers are calling GlassWorm. And it's not the first incident. It won't be the last.

I went through my own extensions after reading about it. I had 47 installed. I could confidently vouch for maybe 20 of them. The rest? I installed them months ago, never checked who published them, never looked at what permissions they had. I'm guessing your situation is similar.

What your editor can actually access

Before we get into the attack, look at this. This is what VS Code (and every extension running inside it) has access to:

┌─────────────────────────────────────────────────┐
│                   VS Code                        │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Extension│  │ Extension│  │  Extension   │  │
│  │  Theme   │  │ Formatter│  │  "WakaTime"  │  │
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
│       │              │               │           │
│       ▼              ▼               ▼           │
│  ┌──────────────────────────────────────────┐   │
│  │        SAME PERMISSION LEVEL             │   │
│  │    No sandbox. No isolation. Full access. │   │
│  └──────────────────────────────────────────┘   │
│       │              │               │           │
│       ▼              ▼               ▼           │
├───────────────────────────────────────────────────┤
│  ~/.ssh/*        ~/.env          ~/.aws/         │
│  ~/.gitconfig    Terminal        Source code      │
│  API keys        DB creds        Git tokens       │
└───────────────────────────────────────────────────┘

There is no sandbox. A color theme extension has the same system access as a full debugger. The marketplace review process catches obvious malware but it's not a security audit. Extensions with 50,000 installs have been caught doing shady things.

How GlassWorm works

Here's the kill chain. Each step is designed to avoid detection:

Step 1: INSTALL
    User installs "code-wakatime-activity-tracker"
    Looks legit: decent reviews, familiar branding
              │
              ▼
Step 2: DROP
    Extension downloads a Zig-compiled binary
    (Zig = not in most antivirus signature DBs)
              │
              ▼
Step 3: PERSIST
    Binary registers as a background process
    Survives VS Code closing
              │
              ▼
Step 4: HARVEST
    Scans for:
    ├── .env, .env.local, .env.production
    ├── *.pem, *.key (SSL/SSH keys)
    ├── .git/config (remote URLs → company ID)
    └── ~/.aws/credentials
              │
              ▼
Step 5: EXFILTRATE
    Sends harvested data to C2 server
    Encrypted, looks like normal HTTPS traffic
              │
              ▼
Step 6: (WORST CASE) INJECT
    Receives instructions to modify source files
    Could inject backdoors into YOUR commits

That last step is the one that should keep you up at night. It's not just stealing secrets. It could be modifying your code before you push it. Your CI passes. Your review looks clean. The backdoor was there before you committed.

The audit: my results

I scored each of my 47 extensions on a simple trust matrix:

                    VERIFIED PUBLISHER
                    Yes           No
                ┌─────────────┬──────────────┐
     Yes        │  KEEP       │  INSPECT     │
  OPEN SOURCE   │  (20 exts)  │  (4 exts)    │
                ├─────────────┼──────────────┤
     No         │  INSPECT    │  REMOVE      │
                │  (7 exts)   │  (16 exts)   │
                └─────────────┴──────────────┘

Result: 47 → 31 extensions
Removed: 16  |  Flagged for inspection: 11

The 16 I removed fell into three buckets:

Duplicates of built-in VS Code features (VS Code has gotten better, some extensions are unnecessary now)
Extensions I installed for a specific project months ago and never used again
Extensions from unverified publishers with no source code

Step-by-step: audit yours in 30 minutes

1. Dump your extension list

code --list-extensions > my-extensions.txt
wc -l my-extensions.txt  # how many do you have?

2. Run the trust check

For each extension, run it through this:

Extension: _______________
┌──────────────────────────────────────────┐
│ Verified publisher?           [ ] Y [ ] N │
│ Open source / GitHub link?    [ ] Y [ ] N │
│ Updated in last 6 months?     [ ] Y [ ] N │
│ Install/rating ratio normal?  [ ] Y [ ] N │
│ Do I actually use this?       [ ] Y [ ] N │
├──────────────────────────────────────────┤
│ 5/5 = KEEP                               │
│ 3-4 = INSPECT (check source, permissions)│
│ 0-2 = REMOVE                             │
└──────────────────────────────────────────┘

3. Kill auto-updates

// settings.json
{
  "extensions.autoUpdate": false,
  "extensions.autoCheckUpdates": false
}

This is the single most impactful change. A legitimate extension can be compromised through a malicious update pushed to the marketplace. If auto-update is on, that update is on your machine before you hear about it.

4. Set up a credential file watcher

# macOS - alerts you if anything touches sensitive files
# Save as ~/watch-creds.sh and add to login items

#!/bin/bash
WATCH_PATHS="$HOME/.ssh $HOME/.aws $HOME/.env"

fswatch -r $WATCH_PATHS \
  --event Created \
  --event Updated \
  --event Renamed |
while read file; do
  osascript -e \
    "display notification \"$file\" with title \"Credential File Touched\""
  echo "$(date): $file" >> ~/credential-access.log
done

# Linux equivalent using inotifywait
inotifywait -m -r ~/.ssh ~/.aws -e modify -e create |
while read dir event file; do
  notify-send "Credential Alert" "$dir$file was $event"
done

Not bulletproof. A sophisticated attacker works around file watchers. But most attacks are unsophisticated, and this catches those.

What I kept (and why)

Extension	Publisher	Open Source	Trust Signal
ESLint	Microsoft	Yes	Microsoft-published, millions of installs
Prettier	Prettier	Yes	Core team maintains it
GitLens	GitKraken	Yes	Verified company, public security policy
Error Lens	usernamehw	Yes	I've read the source, it's small
Tailwind IntelliSense	Tailwind Labs	Yes	First-party from the Tailwind team
Thunder Client	Ranga Vadhineni	Partial	Verified publisher, 5+ year track record

The pattern:

TRUST = verified_publisher + open_source + active_maintenance + real_identity

If any of those four is missing, you need a good reason to keep it.

VS Code vs browser extensions: the gap

Here's what bothers me. Chrome figured this out years ago.

Browser Extensions (Chrome)        VS Code Extensions
┌───────────────────────┐          ┌───────────────────────┐
│ Declares permissions  │          │ Full system access     │
│ upfront ("tabs",      │          │ by default. No         │
│ "storage", etc.)      │          │ permission manifest.   │
│                       │          │                        │
│ Runs in sandboxed     │          │ Runs in Node.js with   │
│ process               │          │ your user permissions   │
│                       │          │                        │
│ Limited API surface   │          │ Can spawn processes,    │
│                       │          │ read any file, open     │
│                       │          │ network connections     │
│                       │          │                        │
│ Reviewed + signed     │          │ Basic automated scan   │
└───────────────────────┘          └───────────────────────┘

VS Code's extension model was built in 2015 when the threat model was different. We need:

Permission scoping. Extensions should declare exactly what files and APIs they access. A JSON formatter should not touch your terminal.
Sandboxing. Extensions should run in isolated processes. Browser extensions already work this way. It's solvable.
Code signing. Require publishers to sign their code. Make it auditable.

Until those things happen, the responsibility is on us.

Quick reference card

Save this somewhere:

┌──────────────────────────────────────────────────┐
│         VS CODE EXTENSION SECURITY CHEAT SHEET   │
├──────────────────────────────────────────────────┤
│                                                   │
│  BEFORE INSTALLING                                │
│  ☐ Check publisher verification (blue checkmark)  │
│  ☐ Check GitHub repo link exists                  │
│  ☐ Check last update date (< 6 months)            │
│  ☐ Read recent reviews for red flags              │
│                                                   │
│  AFTER INSTALLING                                 │
│  ☐ Disable auto-update (settings.json)            │
│  ☐ Review changelogs before manual updates        │
│  ☐ Set up credential file monitoring              │
│                                                   │
│  QUARTERLY                                        │
│  ☐ Run: code --list-extensions | wc -l            │
│  ☐ Remove unused extensions                       │
│  ☐ Re-check publisher status on remaining ones    │
│                                                   │
│  RED FLAGS                                        │
│  ✗ No source code link                            │
│  ✗ Publisher name doesn't match extension name     │
│  ✗ Thousands of installs but < 10 ratings          │
│  ✗ Recently transferred to new publisher           │
│  ✗ Requests network access for offline-only task   │
│                                                   │
└──────────────────────────────────────────────────┘

Gagan Deep Singh builds open source tools at Glincker. Currently working on profClaw (AI agent engine) and AskVerdict (multi-model AI verdicts).

If this was useful, follow me on Dev.to or X where I post weekly.

DEV Community: GDS K S

Claude Code Felt Off for a Month. Here Is What Broke.

TL;DR

The three bugs, expanded

Bug 1: the silent default change

Bug 2: the caching regression

Bug 3: the word-limit constraint

What I learned running projects on top of this

What this means for tool builders

1. Version your prompts

2. Log tokens per turn

3. Stop testing agents with toy tasks

The tradeoff nobody is naming

At Glincker

The bottom line

The Token Tab: A Developer's Audit of the AI Hype Stack

The four layers of the hype stack

Layer 1: The wrapper

Layer 2: Orchestration

Layer 3: Inference

Layer 4: Hardware

Four signals a stack is on borrowed time

What to actually build on

I replaced Auth0 with an open source library in 30 minutes. Here is what broke.

The bill

What I actually needed

The shortlist

The 30 minute spike

Install

The core config

Wire it up

The schema

The Auth0 migration

What broke in prod

The password hashes were not portable

Session cookies were on the wrong domain

Google OAuth redirect URI

The agent thing worked first try

The cost

Where Auth0 is still better

Would I do it again

Questions I expect

How to build a secure password reset flow in Next.js (the short version)

What a good reset flow actually does

The from scratch version

The schema

The request endpoint

The reset endpoint

Rate limiting

The kavachOS version

Install

Configure

Mount the routes

The form

Three mistakes I keep finding in code reviews

Storing tokens in plain text

Using Math.random() for the token

24 hour expiries

Testing checklist before you ship

Questions I expect in the comments

What I will write next

How to build a login flow in Next.js 15 (sessions, cookies, CSRF, and the timing attack nobody talks about)

The flow

The session table

The login form

The server endpoint

The fake hash

The session cookie

The email verification gate

The session middleware

Logout

CSRF

Testing from the terminal

The same thing in kavachOS

Install, migrate, configure

The login form

The middleware

Four things I see go wrong

Up next

How to build a register user flow in Next.js 15 (frontend, backend, database, email)

Using `Math.random()` for the token

The `users` table

The `sessions` table

The `oauth_accounts` table

The `password_reset_tokens` table

The `magic_link_tokens` table

The `email_verification_tokens` table

The `passkeys` table

The `agent_tokens` table