Forem: ShyGyver

Add Refresh Tokens to Your Hono OIDC Server (with Token Rotation)

ShyGyver — Wed, 06 May 2026 14:57:26 +0000

The previous articles in this series built a working OIDC Authorization Code Flow server, fixed the hardcoded issuer, discussed persistent signing keys, and added a consent screen. Now it's time to tackle the refresh token grant.

Access tokens are short-lived by design (~30 minutes - 90 minutes). Once they expire, the client needs a new one. Without refresh tokens, that means sending the user back through the login and consent flow every hour. That makes a TERRIBLE experience for long-lived sessions like a mobile app or a background service. Can you imagine having to log in (user + password) every hour just to open your email app?

The refresh token grant solves this.

After the user authenticates and grants consent, the server issues a long-lived refresh token alongside the short-lived access token. The client stores the refresh token securely and exchanges it for a new access token whenever the old one expires. No user interaction required.

The offline_access scope controls whether a refresh token is issued. Clients that need to operate when the user is not actively present request it explicitly, which also ensures the user sees it on the consent screen before agreeing.

FYI: I didn't come up with the name offline_access. It is in the OpenID Connect specification.

TL;DR

The full runnable example is available at Github (apps/oidc-refresh-app).

What changes

Three areas of the server need updating:

Area	Change
Client config	Add `"refresh_token"` to authorized `grants` and `"offline_access"` to authorized `scopes`
Storage	Save the refresh tokens and their metadata (client, user, scope, expiration)
Flow builder	Register the new scope, extend `getClient`, update `generateAccessToken`, add `generateAccessTokenFromRefreshToken`

The authorization and consent endpoints are untouched. Refresh tokens are entirely a token-endpoint concern.

Step 1: Update the client configuration

The client needs two additions: the refresh_token grant type and the offline_access scope.

// Before
const CLIENT = {
  id: "example-client",
  secret: "example-secret",
  grants: ["authorization_code"],
  redirectUris: [],
  scopes: ["openid", "profile", "email", "content:read", "content:write"],
};

// After
const CLIENT: {
  id: string;
  secret: string;
  grants: string[];
  redirectUris: string[];
  scopes: string[];
} = {
  id: "example-client",
  secret: "example-secret",
  grants: ["authorization_code", "refresh_token"],
  redirectUris: [],
  scopes: ["openid", "offline_access", "profile", "email", "content:read", "content:write"],
};

The grants array is checked inside getClient to ensure the client is actually allowed to use the refresh token grant. The scopes array is what the consent screen will offer to the user. Without "offline_access" in scopes, the client cannot request it.

Step 2: Add refresh token storage

Add an in-memory map to hold issued refresh tokens:

// in-memory refresh token storage, mapping refresh tokens to client, user, scope, and expiration
const refreshTokenStorage: Record<
  string,
  {
    clientId: string;
    userId: string;
    scope: string[];
    expiresAt: number;
  }
> = {};

Each entry key is the refresh token value. scope records what scopes the token was issued for, so a narrowed scope can be enforced on renewal. expiresAt is checked on every use to reject stale tokens.

In production, replace this with a persistent store (Redis, PostgreSQL, etc.) so refresh tokens survive restarts and can be revoked centrally.

Step 3: Register `offline_access` in the flow builder

Add the new scope to .setScopes() so it appears in the discovery document:

// Before
.setScopes({
  openid: "OpenID Connect scope",
  profile: "Access to your profile information",
  email: "Access to your email address",
  "content:read": "Access to read content",
  "content:write": "Access to write content",
})

// After
.setScopes({
  openid: "OpenID Connect scope",
  offline_access: "Request refresh token for offline access",
  profile: "Access to your profile information",
  email: "Access to your email address",
  "content:read": "Access to read content",
  "content:write": "Access to write content",
})

Step 4: Update `getClient` to handle the refresh token grant

getClient is called for every POST to /token. Previously it only handled authorization_code. Now it needs a second branch for refresh_token.

.getClient(async (tokenRequest) => {
  // existing authorization_code branch unchanged
  if (
    tokenRequest.grantType === "authorization_code" &&
    tokenRequest.clientId === CLIENT.id &&
    tokenRequest.code
  ) {
    // ... same as before
  }

  // handle the refresh token grant type
  if (
    tokenRequest.grantType === "refresh_token" &&
    tokenRequest.clientId === CLIENT.id &&
    CLIENT.grants.includes("refresh_token")
  ) {
    const refreshTokenData = refreshTokenStorage[tokenRequest.refreshToken];

    // validate the refresh token and its association with the client
    if (!refreshTokenData)
      throw new HTTPException(400, {
        res: new Response(
          JSON.stringify({ error: "invalid_grant", error_description: "Invalid refresh token" }),
          { headers: { "Content-Type": "application/json" } }
        ),
      });

    if (refreshTokenData.clientId !== tokenRequest.clientId)
      throw new HTTPException(400, {
        res: new Response(
          JSON.stringify({
            error: "invalid_grant",
            error_description: "Invalid client for refresh token",
          }),
          { headers: { "Content-Type": "application/json" } }
        ),
      });

    // for security, remove the used refresh token to prevent reuse (rotate on each use)
    delete refreshTokenStorage[tokenRequest.refreshToken];

    // check if the refresh token has expired
    if (refreshTokenData.expiresAt < Date.now()) {
      throw new HTTPException(400, {
        res: new Response(
          JSON.stringify({
            error: "invalid_grant",
            error_description: "Refresh token has expired",
          }),
          { headers: { "Content-Type": "application/json" } }
        ),
      });
    }

    // narrow the scope if the client requests a subset
    const requestedScope = Array.isArray(tokenRequest.scope) ? tokenRequest.scope : [];
    const accessScope = requestedScope.length
      ? refreshTokenData.scope.filter((s) => requestedScope.includes(s))
      : refreshTokenData.scope;

    return {
      id: CLIENT.id,
      grants: CLIENT.grants,
      redirectUris: CLIENT.redirectUris,
      scopes: CLIENT.scopes,
      metadata: {
        accessScope,
        userId: refreshTokenData.userId,
        username: USER.username,
        userEmail: USER.email,
        userFullName: USER.fullName,
      },
    };
  }
})

A few things worth noting:

Rotation on every use: delete refreshTokenStorage[tokenRequest.refreshToken] runs before the expiry check. This is intentional. A used token is always removed, whether it is valid or not.
Scope narrowing: a client may request a subset of the original scopes on renewal (e.g., drop content:write for a read-only operation). If the client sends no scope parameter, the full original scope is preserved.
Error format: throwing an HTTPException with a JSON body lets us return the exact invalid_grant error code the OAuth 2 spec requires, without relying on the flow's default error handling. This feels very manual, but it works.

Step 5: Issue a refresh token in `generateAccessToken`

generateAccessToken is called the first time tokens are issued (right after the authorization code exchange). Update it to conditionally generate and store a refresh token when offline_access is in the granted scope:

.generateAccessToken(async (grantContext) => {
  // ... sign accessToken and idToken as before ...

  // generate the refresh token if the "offline_access" scope was requested,
  // and store it in the refresh token storage with an expiration time
  const refreshToken = (() => {
    if (accessScope.includes("offline_access")) {
      return crypto.randomUUID();
    }
    return undefined;
  })();

  if (refreshToken) {
    refreshTokenStorage[refreshToken] = {
      clientId: grantContext.client.id,
      userId: `${grantContext.client.metadata?.userId}`,
      scope: accessScope,
      expiresAt: Date.now() + 30 * 24 * 3600 * 1000, // 30 days
    };
  }

  // return the refresh token in the token response
  return {
    accessToken,
    scope: accessScope,
    idToken,
    refreshToken, // undefined if offline_access was not requested
  };
})

refreshToken is undefined when offline_access was not in the requested scope. The flow omits undefined fields from the token response, so clients that didn't ask for a refresh token simply won't receive one.

Step 6: Add `generateAccessTokenFromRefreshToken`

This new callback mirrors generateAccessToken but is called when the grant type is refresh_token. The grantContext is populated from the metadata returned by getClient in Step 4 (the same pattern used for the authorization code grant).

// generate access token from refresh token, reusing the same claims structure
// and signing method as the initial access token
.generateAccessTokenFromRefreshToken(async (grantContext) => {
  const accessScope = Array.isArray(grantContext.client.metadata?.accessScope)
    ? grantContext.client.metadata.accessScope
    : [];

  const registeredClaims = {
    exp: Math.floor(Date.now() / 1000) + grantContext.accessTokenLifetime,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000),
    iss: grantContext.origin,
    aud: grantContext.client.id,
    jti: crypto.randomUUID(),
    sub: `${grantContext.client.metadata?.userId}`,
  };

  const { token: accessToken } = await jwksAuthority.sign({
    scope: accessScope.join(" "),
    ...registeredClaims,
  });

  const { token: idToken } = await jwksAuthority.sign({
    username: `${grantContext.client.metadata?.username}`,
    name: accessScope.includes("profile")
      ? `${grantContext.client.metadata?.userFullName}`
      : undefined,
    email: accessScope.includes("email")
      ? `${grantContext.client.metadata?.userEmail}`
      : undefined,
    ...registeredClaims,
  });

  // rotate: issue a new refresh token to replace the one consumed in getClient
  const refreshToken = (() => {
    if (accessScope.includes("offline_access")) {
      return crypto.randomUUID();
    }
    return undefined;
  })();

  if (refreshToken) {
    refreshTokenStorage[refreshToken] = {
      clientId: grantContext.client.id,
      userId: `${grantContext.client.metadata?.userId}`,
      scope: accessScope,
      expiresAt: Date.now() + 30 * 24 * 3600 * 1000, // 30 days
    };
  }

  return {
    accessToken,
    scope: accessScope,
    idToken,
    refreshToken,
  };
})

The token-signing logic is identical to generateAccessToken. The only difference is that grantContext.client.metadata was populated from the refresh token data (no nonce because OIDC nonces are one-time values tied to the original authorization request).

How the full flow works

Here is the complete sequence for a client that requests offline_access:

The client redirects the browser to GET /authorize?scope=openid+offline_access+....
The user logs in, sees offline_access on the consent page, and clicks Allow.
The server issues an authorization code and redirects back to the client.
The client POSTs the code to /token → receives access_token, id_token, and refresh_token.
The client stores the refresh token securely.
When the access token expires, the client POSTs to /token with grant_type=refresh_token and the stored refresh_token.
getClient validates the token, rotates it (deletes the old one), and returns the client metadata.
generateAccessTokenFromRefreshToken signs a new access token and a new refresh token.
The client replaces both stored tokens and continues.

Security considerations

Token rotation is already implemented: every refresh removes the old token before issuing a new one. If an attacker intercepts and uses a token first, the legitimate client's next attempt will fail with invalid_grant, alerting it that the token may have been stolen.
Expiry: refresh tokens are stored with a 30-day TTL. After that, the user must authenticate again.
Scope restriction: clients cannot request more scopes on renewal than were originally granted.
In production, store refresh tokens in a database with an index on both the token value and (clientId, userId) so you can revoke all tokens for a user (or a specific client) in one query.

What's next

Well, I think I said enough for authorization code flow. Of course, there are many improvements and additional features you could add on top of this basic implementation:

Persist clients, users, codes, refresh tokens, and session cookies in a database instead of in-memory objects
Add a registration endpoint (POST /register) per RFC 7591
etc...

@saurbit/oauth2 also supports other grant types like client_credentials and device_authorization. If you're building a machine-to-machine API, the client credentials grant allows a service to authenticate without a user context. The device authorization grant is perfect for headless clients like smart TVs or CLI apps that can't display a browser for login.

We could go on and on, but I think the core concepts are clear now. You can build on top of this foundation to create a fully featured authorization server that meets your specific needs.

The series won't stop here though. With time, I might add more articles, less focused on the basics (which is why I had to talk about the basics in the first place).

@saurbit/oauth2 can be used with many frameworks and is not tightly coupled to Hono. @saurbit/hono-oauth2 provides a convenient adapter for Hono, but the core logic lives in @saurbit/oauth2 and can be reused across different environments. If you're using Express, Fastify, Oak, or any other JavaScript framework, you can still use the same flow builder and callbacks to implement your authorization server logic. The main difference will be how you integrate the flow into your HTTP routes and middleware. @saurbit/oauth2 expects Web standard API objects so as long as your framework can provide those (or you can adapt them), you can use the same core logic.

Rambling note

I always wanted to touch on the topic of OpenID Connect and OAuth 2.0 servers in JavaScript, and gave up many times because it felt overwhelming. The specs are long and complex, and there are many edge cases and security considerations to cover. I only hope I was able to present the material in a clear and (kind of) approachable way, without oversimplifying the important details. If you have any questions or suggestions for future articles, feel free to reach out! And thank you for reading this far. I hope it was helpful and not too boring.

Add a Consent Screen to Your OIDC Authorization Server with Hono

ShyGyver — Fri, 01 May 2026 16:29:30 +0000

The previous articles in this series built a working OIDC Authorization Code Flow server, fixed the hardcoded issuer, and discussed how to persist signing keys. Now we will cover another important step: the consent screen.

When a third-party application requests access to a user's account, that user should explicitly choose which permissions to grant and which to deny. Those permissions could be as broad as "full access to your account" or as specific as "read-only access to your calendar".

The OAuth 2 spec defines this step, and every public-facing authorization server needs it. Without it, any registered client silently gets every scope it asks for the moment the user authenticates.

This article adds a consent screen to the server built in the previous articles. After logging in, the user will see a page listing the requested scopes, with Allow and Deny buttons. A short-lived server-side session cookie bridges the login and consent steps so the server knows who is making the decision.

TL;DR

The full runnable example is available at Github (apps/oidc-consent-app).

What changes

The authorization flow now has two interactive steps instead of one:

Login: user submits username and password.
Consent: user sees the requested scopes and clicks Allow or Deny.

A session cookie ties these two steps together. After the user authenticates, the server stores a short-lived session and returns the consent page. On the next POST (the consent form submission), the server reads the session to identify the user and acts on their choice.

The generateAuthorizationCode callback becomes the control point. It now returns one of three outcomes:

Return type	Meaning
`{ type: "continue" }`	Show the consent screen; don't issue a code yet
`{ type: "code", code }`	User approved; issue the authorization code
`{ type: "deny", message }`	User denied; return an `access_denied` error

Step 1: Add imports and augment types

Add the cookie helpers from Hono and the AuthorizationCodeReqData type from the OAuth2 library:

import {
  AccessDeniedError,
  AuthorizationCodeReqData, // add this
  StrategyInsufficientScopeError,
  StrategyInternalError,
  UnauthorizedClientError,
  UnsupportedGrantTypeError,
  getOriginFromRequest,
} from "@saurbit/oauth2";

import { 
  Env, // add this
  Hono 
} from "hono";

import { deleteCookie, getCookie, setCookie } from "hono/cookie"; // add this

The AuthorizationCodeReqData type is the base shape that the flow builder uses for data parsed at the authorization endpoint. We'll extend it in the next step.

The @saurbit/oauth2 module augmentation previously only extended UserCredentials. Add a second interface, AuthorizationCodeUser, to carry the consent decision alongside the user object through generateAuthorizationCode:

declare module "@saurbit/oauth2" {
  interface UserCredentials {
    id: string;
    email: string;
    fullName: string;
    username: string;
  }

  // add this
  interface AuthorizationCodeUser {
    id: string;
    email: string;
    fullName: string;
    username: string;
    consentStatus?: "allow" | "deny" | undefined;
  }
}

AuthorizationCodeUser is what the user argument in generateAuthorizationCode is typed as. Adding consentStatus here lets us read it inside that callback without a type cast.

Step 2: Define `ParsedData`

The flow builder's parseAuthorizationEndpointData callback returns data that is then forwarded to getUserForAuthentication and generateAuthorizationCode. Define a dedicated interface that extends the base type with the extra fields the consent flow needs:

interface ParsedData extends AuthorizationCodeReqData {
  username?: string;
  password?: string;
  consent?: "allow" | "deny";
  sessionCookie?: string;
}

consent captures which button the user clicked. sessionCookie carries the session ID so the server can look up the authenticated user on the consent POST without the user having to re-enter their password.

Step 3: Add session storage

In production, you would use a proper session store (e.g., Redis) with secure cookie flags and expiration handling. For this example, we'll keep it simple with an in-memory object. Note that this is not suitable for production use.

Add an in-memory map to hold active sessions between the login and consent steps:

// Simple in-memory session storage for demonstration (not for production use)
const sessionStorage: Record<
  string,
  {
    userId: string;
    expiresAt: number;
  }
> = {};

Each entry is keyed by a random UUID that becomes the session cookie value. The expiresAt field is checked on every read to discard stale sessions.

Step 4: Update the flow builder

4.1 Pass the generic type parameter

HonoOIDCAuthorizationCodeFlowBuilder.create accepts optional generic type parameters. Pass ParsedData as the second argument so TypeScript infers the correct type inside the callbacks:

// Before
const flow = HonoOIDCAuthorizationCodeFlowBuilder.create({

// After
const flow = HonoOIDCAuthorizationCodeFlowBuilder.create<Env, ParsedData>({

Env is Hono's generic environment type and keeps the context type correct, imported in Step 1. ParsedData is the interface defined in Step 2.

4.2 Parse consent and session cookie

Update parseAuthorizationEndpointData to extract the consent choice and the session cookie in addition to the credentials:

parseAuthorizationEndpointData: async (c) => {
  let formData: FormData | undefined = undefined;
  if (c.req.method === "POST") {
    try {
      formData = await c.req.formData();
    } catch (error) {
      console.error("Error parsing form data:", {
        error: error instanceof Error ? { name: error.name, message: error.message } : error,
      });
    }
  }
  const username = formData?.get("username");
  const password = formData?.get("password");
  const consent = formData?.get("consent");

  const sessionCookie = getCookie(c, "session"); // add this

  return {
    username: typeof username === "string" ? username : undefined,
    password: typeof password === "string" ? password : undefined,
    consent: consent === "allow" || consent === "deny" ? consent : undefined, // add this
    sessionCookie, // add this
  };
},

This callback runs on both GET and POST requests to the authorization endpoint, so formData is only parsed when the method is POST. On a GET, formData is undefined and username, password, and consent will all be undefined. The sessionCookie read is unconditional because it is present in both requests when the session was already created.

4.3 Update `getUserForAuthentication`

The callback now has two paths: session-based identification and credential-based identification.

.getUserForAuthentication((_ctxt, parsedData) => {
  // Path 1: user already authenticated, identify them from the session
  if (parsedData.sessionCookie) {
    const session = sessionStorage[parsedData.sessionCookie];
    if (session) {
      if (session.expiresAt <= Date.now()) {
        // Session expired, clean up
        delete sessionStorage[parsedData.sessionCookie];
      } else if (session.expiresAt > Date.now() && session.userId === USER.id) {
        return {
          type: "authenticated",
          user: {
            id: USER.id,
            fullName: USER.fullName,
            email: USER.email,
            username: USER.username,
            consentStatus: parsedData.consent, // carry the consent decision  forward
          },
        };
      }
    }
  }

  // Path 2: no valid session, validate credentials
  if (parsedData.username === USER.username && parsedData.password === USER.password) {
    return {
      type: "authenticated",
      user: {
        id: USER.id,
        fullName: USER.fullName,
        email: USER.email,
        username: USER.username,
        // no consentStatus yet, the user hasn't seen the consent screen
      },
    };
  }
})

When a session cookie is present and valid, the callback returns authenticated with consentStatus set to whatever the user clicked or undefined if neither button was clicked yet (e.g., a GET request with a cookie). When credentials are submitted for the first time, consentStatus is absent because the consent screen hasn't been shown.

4.4 Update `generateAuthorizationCode`

This callback now drives the entire consent flow:

.generateAuthorizationCode((grantContext, user) => {
  if (!user.id) {
    return undefined;
  }

  if (user.consentStatus === "deny") {
    return {
      type: "deny",
      message: "The user has denied consent for this application.",
    };
  }

  if (user.consentStatus === "allow") {
    const code = crypto.randomUUID();
    codeStorage[code] = {
      clientId: grantContext.client.id,
      scope: grantContext.scope,
      userId: `${user.id}`,
      expiresAt: Date.now() + 60000,
      codeChallenge: grantContext.codeChallenge,
      nonce: grantContext.nonce,
    };
    return { type: "code", code };
  }

  // consentStatus is undefined, the user hasn't decided yet
  return { type: "continue" };
})

The three branches map directly to the three states consentStatus can be in:

"deny": the user clicked Deny; return an access_denied error to the client.
"allow": the user clicked Allow; store the code and return it.
undefined: the user just logged in or the GET request came in with a valid session; signal the flow to continue (show the consent page).

Step 5: Update the GET handler for the authorization endpoint

Previously, this handler only called initiateAuthorization. Now it checks whether the user already has a session and, if so, shows the consent page directly instead of the login form:

app.get(flow.getAuthorizationEndpoint(), async (c) => {
  if (getCookie(c, "session")) {
    const processedAuthorization = await flow.hono().processAuthorization(c);

    if (processedAuthorization.type === "continue") {
      // Valid session, no consent decision yet -> show the consent page
      return c.html(
        HtmlConsentContent({
          app: processedAuthorization.continueResponse.context.client.id,
          userFullName: processedAuthorization.continueResponse.user.fullName,
          scope: processedAuthorization.continueResponse.scope,
        })
      );
    }

    if (processedAuthorization.type === "unauthenticated") {
      // Session expired or invalid -> clear the cookie and show the login form
      deleteCookie(c, "session", { path: "/" });
      return c.html(HtmlFormContent({ usernameField: "username", passwordField: "password" }));
    }

    if (processedAuthorization.type === "error") {
      return c.json({ error: "invalid_request" }, 400);
    }
  }

  // No session -> validate the client and show the login form
  const result = await flow.hono().initiateAuthorization(c);
  if (result.success) {
    return c.html(HtmlFormContent({ usernameField: "username", passwordField: "password" }));
  }
  return c.json({ error: "invalid_request" }, 400);
});

processAuthorization runs the full flow: it calls parseAuthorizationEndpointData, getUserForAuthentication, and generateAuthorizationCode. When a session cookie is present, getUserForAuthentication will identify the user from the session and generateAuthorizationCode will return continue (no consent decision yet), which is exactly the condition that triggers the consent page.

If the session has expired, getUserForAuthentication returns undefined (no valid session, no credentials submitted), which the flow translates to unauthenticated. The handler clears the stale cookie and falls back to the login form.

Step 6: Update the POST handler for the authorization endpoint

The POST handler needs to handle the full spectrum of outcomes: login success (show consent), consent allow (redirect with code), consent deny (redirect with error), login failure (re-render login form), and unexpected errors.

app.post(flow.getAuthorizationEndpoint(), async (c) => {
  try {
    const result = await flow.hono().processAuthorization(c);

    if (result.type === "error") {
      const error = result.error;
      if (result.redirectable) {
        const qs = [
          `error=${encodeURIComponent(
            error instanceof AccessDeniedError ? error.errorCode : "invalid_request"
          )}`,
          `error_description=${encodeURIComponent(
            error instanceof AccessDeniedError ? error.message : "Invalid request"
          )}`,
          result.state ? `state=${encodeURIComponent(result.state)}` : null,
        ]
          .filter(Boolean)
          .join("&");
        return c.redirect(`${result.redirectUri}?${qs}`);
      }
      return c.html(
        HtmlFormContent({ usernameField: "username", passwordField: "password", errorMessage: error.message }),
        400
      );
    }

    if (result.type === "code") {
      const { code, context: { state, redirectUri } } = result.authorizationCodeResponse;
      const searchParams = new URLSearchParams();
      searchParams.set("code", code);
      if (state) searchParams.set("state", state);
      return c.redirect(`${redirectUri}?${searchParams.toString()}`);
    }

    if (result.type === "continue") {
      // First POST (login form) -> create a session, set the cookie, show consent
      const sessionId = crypto.randomUUID();
      sessionStorage[sessionId] = {
        userId: result.continueResponse.user.id,
        expiresAt: Date.now() + 300000, // 5 minutes
      };

      setCookie(c, "session", sessionId, {
        path: "/",
        httpOnly: true,
        secure: true,
        sameSite: "Lax",
        maxAge: 300,
      });

      return c.html(
        HtmlConsentContent({
          app: result.continueResponse.context.client.id,
          userFullName: result.continueResponse.user.fullName,
          scope: result.continueResponse.scope,
        })
      );
    }

    if (result.type === "unauthenticated") {
      return c.html(
        HtmlFormContent({
          usernameField: "username",
          passwordField: "password",
          errorMessage: result.message || "Authentication failed. Please try again.",
        }),
        400
      );
    }
  } catch (error) {
    console.error("Unexpected error at authorization endpoint:", {
      error: error instanceof Error ? { name: error.name, message: error.message } : error,
    });
    return c.html(
      HtmlFormContent({
        usernameField: "username",
        passwordField: "password",
        errorMessage: "An unexpected error occurred. Please try again later.",
      }),
      500
    );
  }
});

The "continue" branch is where the session is created. It only runs once, on the first POST (credential submission), because on subsequent POSTs getUserForAuthentication will already find the session and generateAuthorizationCode will return either "code" or "deny" depending on which button was clicked.

The "error" branch now also handles the "deny" case. When generateAuthorizationCode returns { type: "deny" }, the flow converts it to an AccessDeniedError and sets redirectable: true (assuming the client and redirect URI were already validated). The handler therefore redirects the browser to the client with error=access_denied in the query string.

Step 7: Add the consent page component

Add HtmlConsentContent alongside the existing HtmlFormContent function:

function HtmlConsentContent(props: { scope: string[]; app: string; userFullName: string }) {
  return html` <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <title>Consent</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      </head>
      <body>
        <h1>Consent</h1>
        <p>User: <b>${props.userFullName}</b></p>
        <p><b>${props.app}</b> is requesting the following permissions:</p>
        <form method="POST">
          ${props.scope
            ? html`<ul>
                ${props.scope.map((s) => html`<li>${s}</li>`)}
              </ul>`
            : ""}
          <button type="submit" name="consent" value="allow">Allow</button>
          <button type="submit" name="consent" value="deny">Deny</button>
        </form>
      </body>
    </html>`;
}

Both buttons submit to the same POST endpoint. The difference is the value attribute on the name="consent" field, which parseAuthorizationEndpointData reads and stores as parsedData.consent.

How the full flow works

Here is the complete sequence from a browser's perspective:

The client redirects the browser to GET /authorize?client_id=...&scope=...&....
No session cookie → initiateAuthorization validates the client and returns the login form.
The user submits credentials via POST /authorize.
getUserForAuthentication validates them and returns authenticated (no consentStatus).
generateAuthorizationCode sees no consentStatus and returns { type: "continue" }.
The POST handler creates a session, sets the cookie, and returns the consent page.
The user clicks Allow or Deny → another POST /authorize, this time with consent=allow (or deny) in the body and the session cookie in the header.
getUserForAuthentication finds the session and returns authenticated with consentStatus set.
generateAuthorizationCode acts on the decision: issues a code or returns a deny error.
The POST handler redirects the browser back to the client with either ?code=... or ?error=access_denied.

Improvements

In the scope of this article, we focused on the core consent flow. Here are some improvements that could be made:

Secure forms against CSRF by including a hidden token in the form and validating it on submission.
Remember consent decisions per user per client to skip the consent screen on repeat authorizations.

What's next

Support the refresh_token grant to issue long-lived sessions

Persistent JWT Signing Keys with PostgreSQL

ShyGyver — Sun, 26 Apr 2026 20:15:52 +0000

The previous article ended with this caveat:

In production, replace createInMemoryKeyStore() with a persistent store backed by a database or secrets manager so keys survive restarts.

This article does exactly that. We'll swap the in-memory key store for two PostgreSQL-backed implementations:

A JwksKeyStore that stores private keys with envelope encryption (AES-256-GCM, DEK + KEK) and public keys as plain JSON.
A JwksRotationTimestampStore that derives the last rotation time directly from the key record's creation time.

Everything else in index.ts (the flow builder, endpoints, login form) stays identical.

TL;DR

The full runnable example is available at Github (oidc-persistent-app).

The problem with in-memory keys

createInMemoryKeyStore() keeps key material in process memory. This has two consequences in production:

Scenario	What happens
Server restart	A new key pair is generated. All tokens issued before the restart are now unverifiable
Multiple instances / pods	Each instance generates its own key pair. Tokens verified by a different instance than the one that signed them will fail

The fix is straightforward: persist the key material to a shared store. Because private keys are sensitive, they must be stored encrypted.

Key concepts

@saurbit/oauth2-jwt defines two interfaces that JoseJwksAuthority and JwksRotator depend on:

JwksKeyStore manages key material:

interface JwksKeyStore {
  storeKeyPair(kid: string, privateKey: object, publicKey: object, ttl: number): Promise<void>;
  getPublicKeys(): Promise<object[]>;
  getPrivateKey(): Promise<object | undefined>;
}

JwksRotationTimestampStore tracks when the last rotation occurred:

interface JwksRotationTimestampStore {
  getLastRotationTimestamp(): Promise<number>;
  setLastRotationTimestamp(timestamp: number): Promise<void>;
}

In the in-memory version, createInMemoryKeyStore() returns a single object that satisfies both interfaces, so it can be passed for both jwksStore and rotationTimestampStore. For the persistent version we are going to make two separate objects, each backed by database queries.

Envelope encryption

Understanding DEK and KEK in Encryption: A Practical Guide.

Private keys MUST NEVER be stored in plaintext. This implementation uses an envelope encryption pattern:

A fresh random DEK (Data Encryption Key, 256-bit) is generated for each key pair.
The private key is serialized to JSON and encrypted with the DEK using AES-256-GCM.
The DEK itself is wrapped (encrypted) with a master KEK loaded from the MASTER_KEY environment variable.
The encrypted private key and the wrapped DEK are stored together in the database.

This means:

Even if the database is breached, the private keys are unreadable without the KEK.
The KEK lives only in the environment (or a secrets manager) and NEVER in the database.

Prerequisites

Start from the server built in the previous article. You need a PostgreSQL database (local, Neon, Supabase, etc.) and two environment variables:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`MASTER_KEY`	Base64-encoded 32-byte key (256 bits) used as the KEK

MASTER_KEY must be a base64-encoded 32-byte value. In a real deployment, store it in a secrets manager (AWS Secrets Manager, Vault, etc.) and inject it at runtime. Never commit it to source control.
You can generate a random Base64 of 32 bytes at Random Base64 String Generator.

Database schema

Create the two tables below. The private_keys table stores exactly one active row at a time enforced by UNIQUE (id) and CHECK (id = 1). Older private keys are overwritten on rotation, while public_keys accumulates all keys still within their TTL so that tokens signed with a previous key continue to verify until they expire.

CREATE TABLE IF NOT EXISTS private_keys
(
    key_id      character varying(255) NOT NULL,
    id          integer NOT NULL DEFAULT 1,
    private_key text NOT NULL,
    wrapped_dek text NOT NULL,
    expires_at  timestamp with time zone NOT NULL,
    created_at  timestamp with time zone NOT NULL DEFAULT now(),
    CONSTRAINT private_keys_pkey PRIMARY KEY (key_id),
    CONSTRAINT private_keys_id_unique UNIQUE (id),
    CONSTRAINT id CHECK (id = 1)
);

CREATE TABLE IF NOT EXISTS public_keys
(
    key_id     character varying(255) NOT NULL,
    public_key text NOT NULL,
    expires_at timestamp with time zone NOT NULL,
    created_at timestamp with time zone NOT NULL DEFAULT now(),
    CONSTRAINT public_keys_pkey PRIMARY KEY (key_id)
);

Step 1: Install the PostgreSQL driver

bun add pg
bun add -d @types/pg

Step 2: Write `src/db.ts`

This module owns all database access. It exposes typed interfaces and four query functions used by the stores.

import { Pool } from "pg";

const ENV_DATABASE_URL = process.env.DATABASE_URL;

const pool = new Pool({
  connectionString: ENV_DATABASE_URL,
  max: 10,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
  ssl: {
    rejectUnauthorized: false,
  },
});

export interface PrivateKeyRecord {
  keyId: string;
  privateKey: string;
  wrappedDek: string;
}

export interface PublicKeyRecord {
  keyId: string;
  publicKey: string;
}

`saveKeyPairRecord`

Persists both keys inside a transaction. The ON CONFLICT (id) DO UPDATE clause on private_keys ensures the table always contains at most one row and new rotations overwrite the old private key in-place.

export async function saveKeyPairRecord(
  privateKey: PrivateKeyRecord,
  publicKey: PublicKeyRecord,
  expirationTime: number
) {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    const createdAt = Date.now();
    const queryPrivateKey = `
      INSERT INTO private_keys (id, key_id, private_key, wrapped_dek, expires_at, created_at)
      VALUES ($1, $2, $3, $4, to_timestamp($5::bigint / 1000), to_timestamp($6::bigint / 1000))
      ON CONFLICT (id)
      DO UPDATE SET
        key_id     = EXCLUDED.key_id,
        private_key = EXCLUDED.private_key,
        wrapped_dek = EXCLUDED.wrapped_dek,
        expires_at  = EXCLUDED.expires_at,
        created_at  = EXCLUDED.created_at
      RETURNING *;
    `;
    const queryPublicKey = `
      INSERT INTO public_keys (key_id, public_key, expires_at, created_at)
      VALUES ($1, $2, to_timestamp($3::bigint / 1000), to_timestamp($4::bigint / 1000))
    `;
    await client.query(queryPrivateKey, [
      1,
      privateKey.keyId,
      privateKey.privateKey,
      privateKey.wrappedDek,
      expirationTime,
      createdAt,
    ]);
    await client.query(queryPublicKey, [
      publicKey.keyId,
      publicKey.publicKey,
      expirationTime,
      createdAt,
    ]);
    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

Read functions

export async function getPrivateKeyRecord(): Promise<PrivateKeyRecord | null> {
  const query = "SELECT * FROM private_keys WHERE expires_at > NOW() LIMIT 1";
  try {
    const res = await pool.query<{ key_id: string; private_key: string; wrapped_dek: string }>(
      query
    );
    if (res.rows.length > 0) {
      const row = res.rows[0];
      return {
        keyId: row.key_id,
        privateKey: row.private_key,
        wrappedDek: row.wrapped_dek,
      };
    }
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

export async function getPublicKeyRecords(): Promise<PublicKeyRecord[] | null> {
  const query = "SELECT * FROM public_keys WHERE expires_at > NOW()";
  try {
    const { rows } = await pool.query<{ key_id: string; public_key: string }>(query);
    return rows.map((row) => ({ keyId: row.key_id, publicKey: row.public_key }));
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

export async function getPrivateKeyCreatedAt(): Promise<Date | null> {
  const query = "SELECT created_at FROM private_keys WHERE expires_at > NOW() LIMIT 1";
  try {
    const { rows } = await pool.query<{ created_at: Date }>(query);
    if (rows.length > 0) {
      return rows[0].created_at;
    }
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

getPublicKeyRecords returns all rows where expires_at is in the future and not just the current key. This is intentional: resource servers need to verify tokens signed with the previous key during the overlap period after a rotation.

Step 3: Write `src/stores.ts`

This module implements the two interfaces (JwksKeyStore, JwksRotationTimestampStore). It imports the DB functions from db.ts and handles all the encryption logic.

Imports and master key

import {
  getPrivateKeyCreatedAt,
  getPrivateKeyRecord,
  getPublicKeyRecords,
  PrivateKeyRecord,
  PublicKeyRecord,
  saveKeyPairRecord,
} from "./db";
import { JwksKeyStore, JwksRotationTimestampStore } from "@saurbit/oauth2-jwt";

/**
 * In a production environment, the master key (KEK) should be stored securely,
 * such as in an environment variable or a secrets manager.
 * It should never be hardcoded in the source code.
 * This should be a base64-encoded 32-byte key (256 bits) for AES-256 encryption.
 */
const ENV_MASTER_KEY = process.env.MASTER_KEY!;

const MASTER_KEY_RAW = base64ToUint8Array(ENV_MASTER_KEY);

Crypto helpers

Two small utilities (base64ToUint8Array, uint8ArrayToBase64) convert between Uint8Array and Base64 for storage, and two functions (decrypt, encrypt) wrap the Web Crypto API for AES-GCM encryption. The IV (12 random bytes) is prepended to the ciphertext so decrypt can split them back apart.

function uint8ArrayToBase64(uint8: Uint8Array): string {
  if (uint8.toBase64) {
    return uint8.toBase64();
  }
  return btoa(String.fromCharCode(...uint8));
}

function base64ToUint8Array(base64: string): Uint8Array<ArrayBuffer> {
  if (Uint8Array.fromBase64) {
    return Uint8Array.fromBase64(base64);
  }
  const binaryString = atob(base64);
  const len = binaryString.length;
  const bytes = new Uint8Array(len);
  for (let i = 0; i < len; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }
  return bytes;
}

async function encrypt(plaintext: string, rawKey: BufferSource): Promise<Uint8Array> {
  const encoder = new TextEncoder();
  const data = encoder.encode(plaintext);
  const key = await crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["encrypt"]);
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, data);
  const combined = new Uint8Array(iv.length + ciphertext.byteLength);
  combined.set(iv);
  combined.set(new Uint8Array(ciphertext), iv.length);
  return combined;
}

async function decrypt(combinedData: Uint8Array, rawKey: BufferSource): Promise<string> {
  const iv = combinedData.slice(0, 12);
  const ciphertext = combinedData.slice(12);
  const key = await crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["decrypt"]);
  const decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);
  return new TextDecoder().decode(decrypted);
}

`jwksStore` (JwksKeyStore)

storeKeyPair is called by JoseJwksAuthority whenever a new key pair is generated. The four-step envelope encryption process runs here:

export const jwksStore: JwksKeyStore = {
  async storeKeyPair(kid: string, privateKey: object, publicKey: object, ttl: number) {
    // 1. Generate a fresh, unique DEK (Data Encryption Key)
    const dekRaw = crypto.getRandomValues(new Uint8Array(32));

    // 2. Encrypt the private key with the DEK
    const encryptedPrivateKey = await encrypt(JSON.stringify(privateKey), dekRaw);

    // 3. Wrap (encrypt) the DEK using the Master Key (KEK)
    const wrappedDek = await encrypt(uint8ArrayToBase64(dekRaw), MASTER_KEY_RAW);

    // 4. Store the encrypted private key and the wrapped DEK together
    const expirationTime = Date.now() + ttl * 1000;
    const privateKeyRecord: PrivateKeyRecord = {
      keyId: kid,
      privateKey: uint8ArrayToBase64(encryptedPrivateKey),
      wrappedDek: uint8ArrayToBase64(wrappedDek),
    };
    const publicKeyRecord: PublicKeyRecord = {
      keyId: kid,
      publicKey: JSON.stringify(publicKey),
    };

    await saveKeyPairRecord(privateKeyRecord, publicKeyRecord, expirationTime);
  },

  async getPublicKeys(): Promise<object[]> {
    const publicKeyRecords = await getPublicKeyRecords();
    if (!publicKeyRecords) {
      return [];
    }
    return publicKeyRecords.map((record) => JSON.parse(record.publicKey));
  },

  async getPrivateKey(): Promise<object | undefined> {
    const privateKeyRecord = await getPrivateKeyRecord();
    if (!privateKeyRecord) {
      return undefined;
    }

    // 1. Unwrap (decrypt) the DEK using the Master Key (KEK)
    const wrappedDekBytes = base64ToUint8Array(privateKeyRecord.wrappedDek);
    const dekRawString = await decrypt(wrappedDekBytes, MASTER_KEY_RAW);
    const dekRaw = base64ToUint8Array(dekRawString);

    // 2. Decrypt the private key using the DEK
    const decryptedPrivateKeyString = await decrypt(
      base64ToUint8Array(privateKeyRecord.privateKey),
      dekRaw
    );

    return JSON.parse(decryptedPrivateKeyString);
  },
};

getPrivateKey reverses the process exactly: decode from Base64, unwrap the DEK with the KEK, then decrypt the private key with the DEK.

`rotationTimestampStore` (JwksRotationTimestampStore)

JwksRotator uses this interface to decide whether it's time to rotate. The persistent implementation reads created_at from the private key row directly, so no additional table is needed here.

setLastRotationTimestamp is intentionally left empty. The rotation timestamp is implicitly captured when storeKeyPair inserts a new row, created_at defaults to now(). Keeping a separate timestamp in sync would be redundant and risk drift.

export const rotationTimestampStore: JwksRotationTimestampStore = {
  async getLastRotationTimestamp(): Promise<number> {
    const createdAt = await getPrivateKeyCreatedAt();
    if (!createdAt) {
      return 0; // No keys yet, treat as never rotated
    }
    return createdAt.getTime();
  },

  async setLastRotationTimestamp(_timestamp: number): Promise<void> {
    // No-op: the rotation timestamp is derived from private_keys.created_at
  },
};

Step 4: Update `src/index.ts`

The change is minimal: swap the import and remove the local createInMemoryKeyStore() call.

Before:

import {
  createInMemoryKeyStore,
  JoseJwksAuthority,
  JwksRotator,
} from "@saurbit/oauth2-jwt";

// ...

const jwksStore = createInMemoryKeyStore();
const jwksAuthority = new JoseJwksAuthority(jwksStore, 8.64e6);

const jwksRotator = new JwksRotator({
  keyGenerator: jwksAuthority,
  rotationTimestampStore: jwksStore, // same object fulfilled both interfaces
  rotationIntervalMs: 7.884e9,
});

After:

import { jwksStore, rotationTimestampStore } from "./stores";
import { JoseJwksAuthority, JwksRotator } from "@saurbit/oauth2-jwt";

// ...

const jwksAuthority = new JoseJwksAuthority(jwksStore, 8.64e6);

const jwksRotator = new JwksRotator({
  keyGenerator: jwksAuthority,
  rotationTimestampStore: rotationTimestampStore, // now a separate object
  rotationIntervalMs: 7.884e9,
});

The rest of index.ts does not change.

Step 5: Run the server

Set the required environment variables and start the server:

bunx cross-env DATABASE_URL="postgres://..." MASTER_KEY="<base64-32-bytes>" bun dev

On startup, jwksRotator.checkAndRotateKeys() runs. If the private_keys table is empty (or the current key has passed the rotation interval), a new RSA key pair is generated, encrypted, and stored. The public key is written to public_keys and will be returned from /.well-known/jwks.json immediately.

Key rotation behavior

The server checks the rotation schedule on startup and then once per hour via setInterval. Here is what happens at each check:

getLastRotationTimestamp() reads created_at from the active private key row. If no row exists, it returns 0.
If now - lastRotation >= rotationIntervalMs (91 days in the example), JoseJwksAuthority.generateKeyPair() is called.
storeKeyPair runs: the new private key overwrites the single private_keys row; a new row is appended to public_keys.
The old public key row stays in public_keys until its expires_at is reached. During this window, both the old and new public keys are served from the JWKS endpoint, so tokens signed with the old key continue to verify correctly.

The key lifetime passed to JoseJwksAuthority (8.64e6 ms = 100 days) controls the expires_at stored in the database. It should be longer than the rotation interval (91 days) to ensure the overlap window exists.

Conclusion

This article showed how to implement a persistent key store for the OIDC server using PostgreSQL and envelope encryption. With this setup, signing keys survive server restarts and work correctly across multiple instances.

The management of cryptographic keys is a critical aspect of any authentication system, and this implementation provides a secure and scalable solution for handling keys in a real-world environment.

What's next

Add a consent screen for multi-tenant or third-party client scenarios
Support the refresh_token grant to issue long-lived sessions

Make Your Hono Authorization Server Work on Any Host

ShyGyver — Wed, 22 Apr 2026 21:38:43 +0000

In the previous article we built a working OIDC Authorization Code Flow server. There was one shortcut worth updating before we could continue filling it smoothly: a hardcoded ISSUER constant.

const ISSUER = "http://localhost:3000";

Every place that constant is used is now locked to localhost:3000: the iss JWT claim, the discovery URL, the JWKS endpoint URL returned to clients, etc... Deploy to https://auth.example.com and you will have to change the code to match the new origin. Start the server on a random port and the discovery document won't work at all.

You could use an environment variable to set the issuer at startup, but that adds complexity and is still error-prone. If you forget to set the variable or set it incorrectly, your server will be broken until you fix the configuration and restart it.

The fix is to derive the issuer from the incoming HTTP request at runtime instead of hard-coding it at startup. It's easy to do, trust me.

Step 1: Import `getOriginFromRequest`

@saurbit/oauth2 ships a small helper that extracts the scheme + host from a Request object. Add it to the existing import block:

import {
  AccessDeniedError,
  StrategyInsufficientScopeError,
  StrategyInternalError,
  UnauthorizedClientError,
  UnsupportedGrantTypeError,
  getOriginFromRequest, // add this
} from "@saurbit/oauth2";

Step 2: Remove the `ISSUER` constant and loosen `CLIENT.redirectUris`

Delete the ISSUER constant entirely. While you're there, give CLIENT an explicit type and change redirectUris to an empty array. You'll handle the Scalar redirect URI dynamically in the next step:

// Before
const ISSUER = "http://localhost:3000";

const CLIENT = {
  id: "example-client",
  secret: "example-secret",
  grants: ["authorization_code"],
  redirectUris: ["http://localhost:3000/scalar"],
  scopes: ["openid", "profile", "email", "content:read", "content:write"],
};

// After: no ISSUER constant
const CLIENT: {
  id: string;
  secret: string;
  grants: string[];
  redirectUris: string[];
  scopes: string[];
} = {
  id: "example-client",
  secret: "example-secret",
  grants: ["authorization_code"],
  redirectUris: [], // validated dynamically below
  scopes: ["openid", "profile", "email", "content:read", "content:write"],
};

You can still add static redirect URIs to CLIENT.redirectUris if you have other clients with known URIs. For this app, Scalar's redirect URI is always {origin}/scalar which is why it doesn't make sense to hard-code it here. Unless you don't want every client to be able to redirect to your server's tool, but that's a different topic.

Step 3: Use a relative discovery URL

setDiscoveryUrl previously received the full URL including the origin. Pass only the path instead. The builder will resolve it against the request origin at runtime:

// Before
.setDiscoveryUrl(`${ISSUER}${DISCOVERY_ENDPOINT_PATH}`)

// After
.setDiscoveryUrl(`${DISCOVERY_ENDPOINT_PATH}`)

Step 4: Validate the redirect URI against the request origin

In getClientForAuthentication the redirect URI was validated purely against the static redirectUris array. Now also accept the internal URI {origin}/scalar where origin is the origin of the current authorization request:

// Before
.getClientForAuthentication((data) => {
  if (data.clientId === CLIENT.id && CLIENT.redirectUris.includes(data.redirectUri)) {
    return { … };
  }
})

// After
.getClientForAuthentication((data) => {
  if (
    data.clientId === CLIENT.id &&
    (data.redirectUri === `${data.origin}/scalar` ||
      CLIENT.redirectUris.includes(data.redirectUri))
  ) {
    return { … };
  }
})

data.origin is provided by the builder from the incoming authorization request, so it automatically matches whatever host the server is running on.

Step 5: Set the `iss` claim from the grant context

Inside generateAccessToken, replace the static ISSUER string with grantContext.origin:

// Before
const registeredClaims = {
  …
  iss: ISSUER,
  …
};

// After
const registeredClaims = {
  …
  iss: grantContext.origin,
  …
};

grantContext.origin is derived from the token request that triggered this callback, so the iss claim in every access token and ID token will match the actual host that issued it.

Step 6: Prepend the runtime origin to the OpenAPI security scheme

The Scalar UI reads openIdConnectUrl from the OpenAPI spec to discover the authorization server. Now that URL is a relative path (see Step 3). So prepend the runtime origin in the /openapi.json handler:

// Before
app.get(
  "/openapi.json",
  openAPIRouteHandler(app, {
    documentation: {
      info: { title: "Auth Server API", version: "0.1.0" },
      components: {
        securitySchemes: { ...flow.toOpenAPISecurityScheme() },
      },
    },
  })
);

// After
app.get("/openapi.json", async (c, n) => {
  const issuer = getOriginFromRequest(c.req.raw);

  const schemes = flow.toOpenAPISecurityScheme();

  for (const schemeName in schemes) {
    if (schemeName === "openidConnect") {
      schemes[schemeName].openIdConnectUrl = `${issuer}${schemes[schemeName].openIdConnectUrl}`;
      break;
    }
  }

  return await openAPIRouteHandler(app, {
    documentation: {
      info: { title: "Auth Server API", version: "0.1.0" },
      components: {
        securitySchemes: { ...schemes },
      },
    },
  })(c, n);
});

getOriginFromRequest reads the Host (or X-Forwarded-Host) header from the raw Request object, so it returns the correct base URL whether the server is sitting behind a reverse proxy or running directly.

Result

After these changes the server has no opinion about where it is deployed. The same code works on http://localhost:3000, https://staging.example.com, and https://auth.example.com without environment-specific builds or configuration files.

Oh, and if you wonder why the endpoint URLs in the openid configuration response still have the correct origin, it's because of the way the flow's getDiscoveryConfiguration method is used in the discovery endpoint handler:

app.get(DISCOVERY_ENDPOINT_PATH, (c) => {
  const config = flow.getDiscoveryConfiguration(c.req.raw); // here we pass the Request
  return c.json(config);
});

It accepts the raw Request object as an argument (optional) and uses it to resolve the issuer and all endpoint URLs at runtime.

Now with that out of the way, continuing to the next articles in the series will be much easier. You won't have to worry about you deployment environment... at least for that... and not until you need to support multiple issuers from the same server, but that's a topic for another day 😉

The full runnable example is available at Github (apps/oidc-app).

Build an Authorization Server with Bun, Hono, and OpenID Connect

ShyGyver — Sat, 18 Apr 2026 14:31:06 +0000

Modern applications increasingly rely on OpenID Connect (OIDC) for secure, standards-based authentication. But most tutorials point you at hosted identity providers.
What if you need to run your own authorization server maybe for a microservices platform, an internal tool, or simply to understand how the flow works end to end?

In this article we'll build a fully working OIDC Authorization Code Flow server from scratch using:

Bun : a fast all-in-one JavaScript runtime
Hono : a lightweight, edge-ready web framework
@saurbit/hono-oauth2 : a Hono integration for OAuth 2 / OIDC flows
@saurbit/oauth2-jwt : JWT signing with automatic key rotation

By the end you'll have a server that issues signed JWTs, exposes a discovery endpoint, supports PKCE, and comes with an interactive Scalar UI for testing.

TL;DR

The full runnable example is available at Github, while the conceptual guide is found at OIDC Authorization Code Flow with Hono.

What we're building

The server will expose the following endpoints:

Endpoint	Purpose
`GET /.well-known/openid-configuration`	OIDC Discovery
`GET /.well-known/jwks.json`	JSON Web Key Set
`GET /authorize`	Login page
`POST /authorize`	Login form submission
`POST /token`	Token exchange
`GET /userinfo`	Authenticated user claims
`GET /protected-resource`	Example protected endpoint
`GET /openapi.json`	OpenAPI spec
`GET /scalar`	Interactive API explorer

Prerequisites

Make sure you have Bun installed.

Step 1: Create the project

Scaffold a new Hono project with Bun:

bun create hono@latest auth-server

When prompted, choose bun as the template. Then move into the project:

cd auth-server

Step 2: Install dependencies

bun add @saurbit/hono-oauth2 @saurbit/oauth2 @saurbit/oauth2-jwt hono-openapi @hono/standard-validator @scalar/hono-api-reference

Step 3: Write the server

Open src/index.ts and replace its contents step by step as shown below.

3.1 Imports

Start with all the imports needed for the server:

import { Hono } from "hono";
import { cors } from "hono/cors";
import { html } from "hono/html";
import { HTTPException } from "hono/http-exception";

import { describeRoute, openAPIRouteHandler } from "hono-openapi";
import { Scalar } from "@scalar/hono-api-reference";

import { HonoOIDCAuthorizationCodeFlowBuilder } from "@saurbit/hono-oauth2";

import {
  createInMemoryKeyStore,
  JoseJwksAuthority,
  JwksRotator,
} from "@saurbit/oauth2-jwt";

import {
  AccessDeniedError,
  StrategyInsufficientScopeError,
  StrategyInternalError,
  UnauthorizedClientError,
  UnsupportedGrantTypeError,
} from "@saurbit/oauth2";

3.2 Extend `UserCredentials`

@saurbit/oauth2 provides a UserCredentials interface you can augment via module augmentation. This lets the rest of the flow know what shape your user object has:

declare module "@saurbit/oauth2" {
  interface UserCredentials {
    id: string;
    email: string;
    fullName: string;
    username: string;
  }
}

3.3 Configure JWT key management

Set up an in-memory JWKS key store, a signing authority, and a rotator. The authority signs and verifies JWTs; the rotator generates new keys on a schedule and removes expired ones.

const ISSUER = "http://localhost:3000";
const DISCOVERY_ENDPOINT_PATH = "/.well-known/openid-configuration";

// In-memory key store (swap for a persistent store in production)
const jwksStore = createInMemoryKeyStore();

// Signs JWTs and exposes the public JWKS endpoint
const jwksAuthority = new JoseJwksAuthority(jwksStore, 8.64e6); // 100-day key lifetime

// Rotates keys every 91 days and cleans up expired ones
const jwksRotator = new JwksRotator({
  keyGenerator: jwksAuthority,
  rotationTimestampStore: jwksStore,
  rotationIntervalMs: 7.884e9, // 91 days
});

In production, replace createInMemoryKeyStore() with a persistent store backed by a database or secrets manager so keys survive restarts. We’ll explore persistent storage options in an upcoming article.

3.4 Define clients and users (in-memory)

For this example, a single client and a single user are hardcoded. In a real application, these would be read from a database.

const CLIENT = {
  id: "example-client",
  secret: "example-secret",
  grants: ["authorization_code"],
  redirectUris: [
    "http://localhost:3000/scalar",
  ],
  scopes: ["openid", "profile", "email", "content:read", "content:write"],
};

const USER = {
  id: "user123",
  fullName: "John Doe",
  email: "user@example.com",
  username: "user",
  password: "crossterm",
};

// Short-lived authorization code storage
const codeStorage: Record<
  string,
  {
    clientId: string;
    scope: string[];
    userId: string;
    expiresAt: number;
    codeChallenge?: string;
    nonce?: string;
  }
> = {};

3.5 Build the OIDC flow

HonoOIDCAuthorizationCodeFlowBuilder uses a fluent API. Each method registers a callback or configures an option; call .build() at the end to get the configured flow object.

Parse the authorization endpoint data

This callback extracts user credentials from the login form submission:

const flow = HonoOIDCAuthorizationCodeFlowBuilder.create({
  parseAuthorizationEndpointData: async (c) => {
    const formData = await c.req.formData();
    const username = formData.get("username");
    const password = formData.get("password");

    return {
      username: typeof username === "string" ? username : undefined,
      password: typeof password === "string" ? password : undefined,
    };
  },
})

Configure endpoints and scopes

  .setSecuritySchemeName("openidConnect")
  .setScopes({
    openid: "OpenID Connect scope",
    profile: "Access to your profile information",
    email: "Access to your email address",
    "content:read": "Access to read content",
    "content:write": "Access to write content",
  })
  .setDescription("Example OpenID Connect Authorization Code Flow")
  .setDiscoveryUrl(`${ISSUER}${DISCOVERY_ENDPOINT_PATH}`)
  .setJwksEndpoint("/.well-known/jwks.json")
  .setAuthorizationEndpoint("/authorize")
  .setTokenEndpoint("/token")
  .setUserInfoEndpoint("/userinfo")

Set client authentication methods

Support both private clients (client secret) and public clients (PKCE, no secret):

  .clientSecretPostAuthenticationMethod()
  .noneAuthenticationMethod()

Token lifetime and OIDC metadata

  .setAccessTokenLifetime(3600)
  .setOpenIdConfiguration({
    claims_supported: [
      "sub", "aud", "iss", "exp", "iat", "nbf",
      "name", "email", "username",
    ],
  })

Authenticate the client at the authorization endpoint

This runs before the login page is shown and validates that the client ID and redirect URI are known:

  .getClientForAuthentication((data) => {
    if (
      data.clientId === CLIENT.id &&
      CLIENT.redirectUris.includes(data.redirectUri)
    ) {
      return {
        id: CLIENT.id,
        grants: CLIENT.grants,
        redirectUris: CLIENT.redirectUris,
        scopes: CLIENT.scopes,
      };
    }
  })

Authenticate the user

Validate the submitted username and password. Return an { type: "authenticated", user } object on success, or undefined to reject:

  .getUserForAuthentication((_ctxt, parsedData) => {
    if (parsedData.username === USER.username && parsedData.password === USER.password) {
      return {
        type: "authenticated",
        user: {
          id: USER.id,
          fullName: USER.fullName,
          email: USER.email,
          username: USER.username,
        },
      };
    }
  })

Generate an authorization code

Create a random code, store it with a 60-second TTL, and return it:

  .generateAuthorizationCode((grantContext, user) => {
    if (!user.id) {
      return undefined;
    }
    const code = crypto.randomUUID();
    codeStorage[code] = {
      clientId: grantContext.client.id,
      scope: grantContext.scope,
      userId: `${user.id}`,
      expiresAt: Date.now() + 60000,
      codeChallenge: grantContext.codeChallenge,
      nonce: grantContext.nonce,
    };
    return { type: "code", code };
  })

Exchange the authorization code at the token endpoint

getClient is called when a client POSTs to /token. Validate the code, check expiry, and verify either the client secret or the PKCE code_verifier. Return an enriched client object whose metadata is forwarded to the token generator:

  .getClient(async (tokenRequest) => {
    if (
      tokenRequest.grantType === "authorization_code" &&
      tokenRequest.clientId === CLIENT.id &&
      tokenRequest.code
    ) {
      const codeData = codeStorage[tokenRequest.code];
      if (!codeData) return undefined;
      if (codeData.clientId !== tokenRequest.clientId) return undefined;
      if (codeData.expiresAt < Date.now()) {
        delete codeStorage[tokenRequest.code];
        return undefined;
      }

      if (tokenRequest.clientSecret) {
        // Private client - verify the secret
        if (tokenRequest.clientSecret !== CLIENT.secret) return undefined;
      } else if (tokenRequest.codeVerifier && codeData.codeChallenge) {
        // Public client - verify PKCE code_verifier against the stored code_challenge
        const data = new TextEncoder().encode(tokenRequest.codeVerifier);
        const hashBuffer = await crypto.subtle.digest("SHA-256", data);
        const hashArray = new Uint8Array(hashBuffer);
        const base64url = btoa(String.fromCharCode(...hashArray))
          .replace(/\+/g, "-")
          .replace(/\//g, "_")
          .replace(/=+$/, "");
        if (base64url !== codeData.codeChallenge) return undefined;
      } else {
        return undefined;
      }

      return {
        id: CLIENT.id,
        grants: CLIENT.grants,
        redirectUris: CLIENT.redirectUris,
        scopes: CLIENT.scopes,
        metadata: {
          accessScope: codeData.scope,
          userId: codeData.userId,
          username: USER.username,
          userEmail: USER.email,
          userFullName: USER.fullName,
          nonce: codeData.nonce,
        },
      };
    }
  })

The metadata field is a free-form record. Use it to pass context (user info, granted scopes) from this callback to generateAccessToken.

Generate access and ID tokens

Sign both tokens with the JWKS authority and return them:

  .generateAccessToken(async (grantContext) => {
    const accessScope = Array.isArray(grantContext.client.metadata?.accessScope)
      ? grantContext.client.metadata.accessScope
      : [];

    const registeredClaims = {
      exp: Math.floor(Date.now() / 1000) + grantContext.accessTokenLifetime,
      iat: Math.floor(Date.now() / 1000),
      nbf: Math.floor(Date.now() / 1000),
      iss: ISSUER,
      aud: grantContext.client.id,
      jti: crypto.randomUUID(),
      sub: `${grantContext.client.metadata?.userId}`,
    };

    const { token: accessToken } = await jwksAuthority.sign({
      scope: accessScope.join(" "),
      ...registeredClaims,
    });

    const { token: idToken } = await jwksAuthority.sign({
      username: `${grantContext.client.metadata?.username}`,
      name: accessScope.includes("profile")
        ? `${grantContext.client.metadata?.userFullName}`
        : undefined,
      email: accessScope.includes("email")
        ? `${grantContext.client.metadata?.userEmail}`
        : undefined,
      nonce: grantContext.client.metadata?.nonce
        ? `${grantContext.client.metadata?.nonce}`
        : undefined,
      ...registeredClaims,
    });

    return {
      accessToken,
      scope: accessScope,
      idToken,
    };
  })

Verify access tokens

Called by authorizeMiddleware on every protected route. Verify the JWT signature and return the resolved credentials:

  .tokenVerifier(async (_c, { token }) => {
    try {
      const payload = await jwksAuthority.verify(token);
      if (payload && payload.sub === USER.id && typeof payload.scope === "string") {
        return {
          isValid: true,
          credentials: {
            user: {
              id: USER.id,
              fullName: USER.fullName,
              email: USER.email,
              username: USER.username,
            },
            scope: payload.scope.split(" "),
          },
        };
      }
    } catch (error) {
      console.error("Token verification error:", {
        error: error instanceof Error
          ? { name: error.name, message: error.message }
          : error,
      });
    }
    return { isValid: false };
  })

Handle authorization failures

Customize the HTTP response when authorizeMiddleware rejects a request:

  .failedAuthorizationAction((_, error) => {
    console.error("Authorization failed:", { error: error.name, message: error.message });

    if (error instanceof StrategyInternalError) {
      throw new HTTPException(500, { message: "Internal server error" });
    }
    if (error instanceof StrategyInsufficientScopeError) {
      throw new HTTPException(403, { message: "Forbidden" });
    }
    throw new HTTPException(401, { message: "Unauthorized" });
  })
  .build();

3.6 Create the Hono app and register routes

Now wire everything up:

const app = new Hono();

app.use("/*", cors());

OIDC discovery endpoint returns the server's configuration so clients can discover endpoints automatically:

app.get(DISCOVERY_ENDPOINT_PATH, (c) => {
  const config = flow.getDiscoveryConfiguration(c.req.raw);
  return c.json(config);
});

JWKS endpoint returns the server's public keys so resource servers can verify tokens:

app.get(flow.getJwksEndpoint(), async (c) => {
  return c.json(await jwksAuthority.getJwksEndpointResponse());
});

Authorization endpoint (GET) validates the client, then renders the login form:

app.get(flow.getAuthorizationEndpoint(), async (c) => {
  const result = await flow.hono().initiateAuthorization(c);
  if (result.success) {
    return c.html(
      HtmlFormContent({ usernameField: "username", passwordField: "password" }),
    );
  }
  return c.json({ error: "invalid_request" }, 400);
});

Authorization endpoint (POST) processes the login submission:

app.post(flow.getAuthorizationEndpoint(), async (c) => {
  try {
    const result = await flow.hono().processAuthorization(c);

    if (result.type === "error") {
      const error = result.error;
      if (result.redirectable) {
        const qs = [
          `error=${encodeURIComponent(
            error instanceof AccessDeniedError ? error.errorCode : "invalid_request"
          )}`,
          `error_description=${encodeURIComponent(
            error instanceof AccessDeniedError ? error.message : "Invalid request"
          )}`,
          result.state ? `state=${encodeURIComponent(result.state)}` : null,
        ].filter(Boolean).join("&");
        return c.redirect(`${result.redirectUri}?${qs}`);
      }
      return c.html(
        HtmlFormContent({
          usernameField: "username",
          passwordField: "password",
          errorMessage: error.message,
        }),
        400,
      );
    }

    if (result.type === "code") {
      const { code, context: { state, redirectUri } } =
        result.authorizationCodeResponse;
      const searchParams = new URLSearchParams();
      searchParams.set("code", code);
      if (state) searchParams.set("state", state);
      return c.redirect(`${redirectUri}?${searchParams.toString()}`);
    }

    if (result.type === "unauthenticated") {
      return c.html(
        HtmlFormContent({
          usernameField: "username",
          passwordField: "password",
          errorMessage: result.message || "Authentication failed. Please try again.",
        }),
        400,
      );
    }
  } catch (error) {
    console.error("Unexpected error at authorization endpoint:", {
      error: error instanceof Error
        ? { name: error.name, message: error.message }
        : error,
    });
    return c.html(
      HtmlFormContent({
        usernameField: "username",
        passwordField: "password",
        errorMessage: "An unexpected error occurred. Please try again later.",
      }),
      500,
    );
  }
});

The processAuthorization result has four possible types:

code : authentication succeeded; redirect to the client with the authorization code.
error : something went wrong; check result.redirectable to decide whether to redirect or re-render the form.
continue : used for a consent/approval step (not implemented here).
unauthenticated : wrong credentials; re-render the login form with an error.

Token endpoint exchanges the authorization code for access and ID tokens:

app.post(flow.getTokenEndpoint(), async (c) => {
  const result = await flow.hono().token(c);
  if (result.success) {
    return c.json(result.tokenResponse);
  }
  const error = result.error;
  if (
    error instanceof UnsupportedGrantTypeError ||
    error instanceof UnauthorizedClientError
  ) {
    return c.json(
      { error: error.errorCode, errorDescription: error.message },
      400,
    );
  }
  return c.json({ error: "invalid_request" }, 400);
});

User info endpoint protected with the openid scope; returns standard claims:

app.get(
  flow.getUserInfoEndpoint() || "/userinfo",
  flow.hono().authorizeMiddleware(["openid"]),
  describeRoute({
    summary: "User Info",
    description: "Returns claims about the authenticated end-user.",
    security: [flow.toOpenAPIPathItem(["openid"])],
    responses: {
      200: {
        description: "User claims.",
        content: {
          "application/json": {
            example: {
              sub: "user123",
              username: "user",
              name: "John Doe",
              email: "user@example.com",
            },
          },
        },
      },
    },
  }),
  (c) => {
    const credentials = c.get("credentials");
    const user = credentials?.user;
    const scope = credentials?.scope || [];
    return c.json({
      sub: user?.id,
      username: user?.username,
      name: scope.includes("profile") ? user?.fullName : undefined,
      email: scope.includes("email") ? user?.email : undefined,
    });
  },
);

Protected resource requires the content:read scope:

app.get(
  "/protected-resource",
  flow.hono().authorizeMiddleware(["content:read"]),
  describeRoute({
    summary: "Protected Resource",
    description: "Requires a valid access token with the 'content:read' scope.",
    security: [flow.toOpenAPIPathItem(["content:read"])],
    responses: {
      200: {
        description: "Protected resource data.",
        content: {
          "application/json": {
            example: {
              message: "Hello, John Doe! You have accessed a protected resource.",
            },
          },
        },
      },
      401: { description: "Unauthorized." },
      403: { description: "Forbidden - insufficient scope." },
    },
  }),
  (c) => {
    const user = c.get("credentials")?.user;
    return c.json({
      message: `Hello, ${user?.fullName}! You have accessed a protected resource.`,
    });
  },
);

OpenAPI spec and Scalar UI:

app.get(
  "/openapi.json",
  openAPIRouteHandler(app, {
    documentation: {
      info: { title: "Auth Server API", version: "0.1.0" },
      components: {
        securitySchemes: { ...flow.toOpenAPISecurityScheme() },
      },
    },
  }),
);

app.get("/scalar", Scalar({ url: "/openapi.json" }));

3.7 Key rotation and login form

Rotate keys on startup, then schedule hourly checks:

await jwksRotator.checkAndRotateKeys();

setInterval(async () => {
  await jwksRotator.checkAndRotateKeys();
}, 3.6e6);

Finally, add the HtmlFormContent helper and the default export:

function HtmlFormContent(props: {
  errorMessage?: string;
  usernameField: string;
  passwordField: string;
}) {
  return html`
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Sign in</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
  <h1>Sign in</h1>
  ${props.errorMessage ? html`<p style="color:red">${props.errorMessage}</p>` : ""}
  <form method="POST">
    <label for="${props.usernameField}">${props.usernameField}</label>
    <input id="${props.usernameField}" name="${props.usernameField}" type="text" autocomplete="username" required />
    <label for="${props.passwordField}">${props.passwordField}</label>
    <input id="${props.passwordField}" name="${props.passwordField}" type="password" autocomplete="current-password" required />
    <button type="submit">Sign in</button>
  </form>
</body>
</html>`;
}

export default app;

Step 4: Run the server

bun dev

Open http://localhost:3000/scalar in your browser. You'll see the Scalar interactive API explorer pre-configured with the OpenID Connect security scheme.

Test credentials:

Field	Value
Client ID	`example-client`
Client Secret	`example-secret` (or use PKCE with no secret)
Credentials Location	`body`
Username	`user`
Password	`crossterm`

Click Authorize, complete the login form, and then try GET /protected-resource or GET /userinfo.

Protecting a separate resource server

In a microservices architecture, your resource servers are separate processes. They don't need the full OAuth2 library. They just need to verify the JWT each request carries.

Option A: Hono's built-in JWK middleware

Hono ships a hono/jwk middleware that fetches the public keys from the JWKS endpoint and verifies incoming bearer tokens automatically:

import { jwk } from "hono/jwk";

app.use(
  "/api/*",
  jwk({ 
    jwks_uri: "http://localhost:3000/.well-known/jwks.json",
    alg: ['RS256'],
  }),
);

Option B: jwks-rsa for Node.js or other runtimes

If you're running a Node.js service (Express, Fastify, etc.), use jwks-rsa to pull public keys from the JWKS endpoint and verify tokens with a JWT library like jsonwebtoken or jose.

import jwksClient from "jwks-rsa";

const client = jwksClient({
  jwksUri: "http://localhost:3000/.well-known/jwks.json",
});

Both approaches mean your resource servers remain stateless and never share a database with the authorization server.

What's next

Replace in-memory stores with a database (PostgreSQL, Redis, etc.)
Add a consent screen for multi-tenant applications
Support the refresh_token grant to issue long-lived tokens

Building Modern Backends with Kaapi: Messaging with Kafka

ShyGyver — Sat, 24 Jan 2026 14:31:20 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi's design philosophy.

Messaging?

What does “messaging” actually mean in this context?

Messaging is an asynchronous communication pattern where applications exchange data by sending messages through a broker, rather than calling each other directly. This decouples systems, improves scalability and reliability, and allows components to process messages independently and at their own pace.

— ChatGPT

That definition is correct… but also not very helpful if you’ve never felt the problem it solves.

So let me give you a real-world example from my own experience at work about six years ago (yes, I’m feeling old).

It started with a simple requirement: “When a user signs up, send them a welcome email.”

Easy enough. I put it directly in the signup handler: call the email service, wait for the response, return success.

Then someone asked:

“Can we also send a Slack notification to the sales team?”

Then another request followed:

“Can we log this to our analytics pipeline?”

Before long, the signup handler was doing five different things and if any one of them failed, the entire signup failed.

That’s when it became clear: some things don’t need to happen right now. They just need to happen.

Kafka: the elephant in the room

There are many ways to do async messaging. Redis Pub/Sub. RabbitMQ. AWS SQS.

But if you're building something that needs to scale, handle millions of events, and never lose a message... you're probably looking at Kafka.

The problem? KafkaJS is powerful, but it's verbose. Producers, consumers, admin clients, group IDs, partitions, offsets... it's a lot of ceremony just to send a JSON object from A to B.

Kaapi's @kaapi/kafka-messaging package wraps all of that into something you can actually reason about.

Setting up Kafka locally

Before we write any code, let's get Kafka running.

One command:

docker run -d --name kafka -p 9092:9092 apache/kafka:latest

That's it. You now have a Kafka broker at localhost:9092.

The scenario

We're building two services:

User API: handles signup, publishes a user.created event
Notification Service: listens for user.created, sends a welcome email

Two apps. One Kafka topic. Fully decoupled.

The User API

Let's start with the API that handles signups.

npm install @kaapi/kaapi @kaapi/kafka-messaging

import { Kaapi } from '@kaapi/kaapi';
import { KafkaMessaging } from '@kaapi/kafka-messaging';

const messaging = new KafkaMessaging({
  clientId: 'user-api',
  brokers: ['localhost:9092'],
  name: 'user-api',
});

const app = new Kaapi({
  port: 3000,
  host: 'localhost',
});

app.route<{ Payload: { email: string; name: string } }>({
  method: 'POST',
  path: '/signup',
  handler: async ({ payload }) => {
    const user = {
      id: crypto.randomUUID(),
      email: payload.email,
      name: payload.name,
      createdAt: Date.now(),
    };

    // Save to database (pretend this happened)

    // Publish the event
    await messaging.publish('user.created', user);

    return { success: true, userId: user.id };
  },
});

const start = async () => {
  await app.listen();
  app.log('🚀 User API running at', app.base().info.uri);
};

start();

That's your entire producer.

When a user signs up, we publish to user.created. The API doesn't know or care who's listening. It just announces what happened.

Plugging into Kaapi's lifecycle

You can use KafkaMessaging standalone (like we just did). But if you register it with your Kaapi app, you get lifecycle management for free:

const messaging = new KafkaMessaging({
  clientId: 'user-api',
  brokers: ['localhost:9092'],
  name: 'user-api',
});

const app = new Kaapi({
  port: 3000,
  host: 'localhost',
  messaging, // 👈 register it here
});

Now when you call await app.stop(), Kaapi automatically calls await messaging.shutdown().

No manual cleanup. No forgotten connections. The messaging service follows the app's lifecycle.

You also get shortcuts:

// These are equivalent:
await messaging.publish('user.created', user);
await app.publish('user.created', user);

await messaging.subscribe('user.created', handler);
await app.subscribe('user.created', handler);

// signup route
app.route({
    method: 'POST',
    path: '/signup',
    handler: async (req) => {
        const user = {
            //... 
        };
        // shortcut to publish messages
        await req.publish('user.created', user);
        return { success: true };
    },
});

Use whichever feels right. The behavior is identical.

The Notification Service

Now let's build the service that reacts to those events.

import { KafkaMessaging } from '@kaapi/kafka-messaging';

const messaging = new KafkaMessaging({
  clientId: 'notification-service',
  brokers: ['localhost:9092'],
  name: 'notification-service',
});

interface UserCreatedEvent {
  id: string;
  email: string;
  name: string;
  createdAt: number;
}

const start = async () => {
  await messaging.subscribe<UserCreatedEvent>('user.created', async (user, ctx) => {
    console.log(`📧 Sending welcome email to ${user.email}...`);

    // await emailService.sendWelcome(user.email, user.name);

    console.log(`✅ Email sent (offset: ${ctx.offset})`);
  });

  console.log('👂 Notification service listening...');
};

start();

Run both services. Hit /signup. Watch the notification service pick up the event.

No polling. No webhooks. No coupling.

What's happening under the hood

When you call subscribe(), Kaapi:

Creates a consumer with an auto-generated group ID (notification-service.user.created)
Connects to Kafka
Starts consuming messages
Parses JSON automatically
Passes typed messages to your handler

When you call publish(), Kaapi:

Gets (or creates) a shared producer
Serializes your message to JSON
Adds metadata headers (service name, address)
Sends it to the topic

You don't manage connections. You don't serialize anything. You just publish and subscribe.

When things go wrong

What happens if your email service is down?

By default, Kaapi logs the error and moves on. But sometimes you want more control.

await messaging.subscribe<UserCreatedEvent>('user.created', 
  async (user, ctx) => {
    await emailService.sendWelcome(user.email, user.name);
  },
  {
    onError: async (error, message, ctx) => {
      console.error(`❌ Failed to process message at offset ${ctx.offset}:`, error);

      // Send to dead-letter queue, alert ops, etc.
      await alerting.notify('notification-service', error);
    },
  }
);

The onError callback gives you the error, the original message, and the context.
Do whatever you need, retry, log, alert, forward to a dead-letter topic.

Consumer groups: who gets what

By default, Kaapi generates a group ID based on your service name and the topic:

notification-service.user.created

This means if you spin up 3 instances of the notification service, Kafka will distribute messages across them. Each message is processed by one instance, not all of them.

Need a custom group ID? Easy:

await messaging.subscribe('user.created', handler, {
  groupId: 'custom-notification-group',
});

Or just customize the prefix:

await messaging.subscribe('user.created', handler, {
  groupIdPrefix: 'emails',  // → emails.user.created
});

Shutting down gracefully

When your service stops, you want to disconnect cleanly.

If you registered messaging with your Kaapi app, this happens automatically when you call app.stop().

For standalone usage, handle it yourself:

process.on('SIGTERM', async () => {
  const result = await messaging.shutdown();
  console.log(`Disconnected ${result.successConsumers} consumers, ${result.successProducers} producers`);
  process.exit(0);
});

Kaapi tracks all producers, consumers, and admin clients you've created. shutdown() disconnects them all and tells you what happened.

What we didn't cover (on purpose)

This article focused on the essentials:

publish(): send a message
subscribe(): receive messages
onError: handle failures
shutdown(): clean disconnect

But @kaapi/kafka-messaging can do more:

Feature	What it does
`publishBatch()`	Send multiple messages in one call
`createTopic()`	Programmatically create topics
`fetchTopicOffsets()`	Check partition offsets
`createProducer()` / `createConsumer()`	Manual control when you need it

See the README: https://www.npmjs.com/package/@kaapi/kafka-messaging

Wrapping up

You started with a monolith. You ended with two decoupled services talking over Kafka.

No boilerplate. No manual serialization. No connection juggling.

Just publish() and subscribe().

That's what messaging should feel like.

Source Code

Want to run the full example?

👉 github.com/shygyver/kaapi-monorepo-playground
The example lives under user-api and notification-app.
You can run the applications and the kafka broker in docker:

docker compose up --build -d user-api notification-app kafka

More Kaapi articles are coming! It has plenty more tricks up its sleeve.

📦 Get started now

npm install @kaapi/kafka-messaging kafkajs

🔗 Learn more: https://github.com/demingongo/kaapi/wiki/KafkaMessaging

Building Modern Backends with Kaapi: Request validation Part 2

ShyGyver — Sun, 11 Jan 2026 19:33:29 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

Validation… again?

Maybe you followed along with the previous article on request validation using Joi, ArkType, Valibot, or Zod.

You’ve got a shiny Kaapi app, routes are clean, validation is solid. Everything felt neat and reassuring.

You probably started with something like this:

import { z } from 'zod';

app
  .base()
  .zod({
    params: z.object({
      name: z.string().min(3).max(10)
    })
  })
  .route({
    method: 'GET',
    path: '/hello/{name}',
    handler: function (request, h) {
      return `Hello ${request.params.name}!`;
    }
  });

And honestly?
That works perfectly fine.

Until the day your app stops being small.

At some point, routes start multiplying. You stop defining them inline. They live in their own files, grouped by feature. And suddenly, that nice little chain you had doesn’t quite fit anymore.

So the question becomes:

How do you keep validation close to your routes… when routes are no longer close to your app?

That’s what we’re solving here.

The new setup (you’ve probably done this already)

You want two things:

routes defined independently
a single place where they’re registered with app.route(...)

And you still want:

validation
type safety
freedom to choose your favorite validator

Let’s walk through it, one validator at a time.

Joi: the familiar path

If you’re using Joi, nothing changes. That’s intentional.

Install it:

joi

Then define a route the same way you would with Hapi:

import { Kaapi, KaapiServerRoute } from '@kaapi/kaapi';
import Joi from 'joi';

const app = new Kaapi({ /* ... */ });

const route: KaapiServerRoute<{ Params: { name: string } }> = {
  method: 'GET',
  path: '/hello/{name}',
  options: {
    validate: {
      params: Joi.object({
        name: Joi.string().min(3).max(10).required()
      }),
    },
  },
  handler: function (request, h) {
    return `Hello ${request.params.name}!`;
  }
};

No magic. No surprises.
If you’ve used Hapi before, this should feel like coming home.

Zod: validation that talks to TypeScript

Now let’s say you want strong type inference, without juggling generics.

Install:

zod
@kaapi/validator-zod

First, extend Kaapi:

import { Kaapi } from '@kaapi/kaapi';
import { validatorZod } from '@kaapi/validator-zod';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorZod);
};

start();

Now define your route:

import { withSchema } from '@kaapi/validator-zod';
import { z } from 'zod';

const route = withSchema({
  params: z.object({
    name: z.string().min(3).max(10)
  })
}).route({
  method: 'GET',
  path: '/hello/{name}',
  handler: function (request, h) {
    return `Hello ${request.params.name}!`;
  }
});

No generics.
Your types come straight from the schema.

You write validation once and TypeScript follows along.

Valibot: same idea, different flavor

Valibot plays in the same league as Zod, with a slightly different syntax.

Install:

valibot
@kaapi/validator-valibot

Extend Kaapi:

import { Kaapi } from '@kaapi/kaapi';
import { validatorValibot } from '@kaapi/validator-valibot';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorValibot);
};

start();

Then define the route:

import { withSchema } from '@kaapi/validator-valibot';
import * as v from 'valibot';

const route = withSchema({
  params: v.object({
    name: v.pipe(v.string(), v.minLength(3), v.maxLength(10))
  })
}).route({
  method: 'GET',
  path: '/hello/{name}',
  handler: function (request, h) {
    return `Hello ${request.params.name}!`;
  }
});

ArkType: schemas you can read

Install:

arktype
@kaapi/validator-arktype

Extend Kaapi:

import { Kaapi } from '@kaapi/kaapi';
import { validatorArk } from '@kaapi/validator-arktype';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorArk);
};

start();

Now the route:

import { withSchema } from '@kaapi/validator-arktype';
import { type } from 'arktype';

const route = withSchema({
  params: type({
    name: '3 <= string <= 10'
  })
}).route({
  method: 'GET',
  path: '/hello/{name}',
  handler: function (request, h) {
    return `Hello ${request.params.name}!`;
  }
});

What actually matters here

Regardless of the validator:

Routes are defined independently
Each route picks the validator it wants
Registration stays dead simple:

app.route(route);

Joi works out of the box.
Zod, Valibot, and ArkType plug in via withSchema.

Same app. Same API. Different tools.

So… which validator should you use?

Quick recap:

Minimal code? → Joi or ArkType
Strong type inference without generics? → Zod or Valibot
Human-readable schemas? → ArkType
Great auto-docs? → Zod, Valibot, or Joi

Kaapi doesn’t force a choice.

It gives you the whole toolbox. Pick the screwdriver you like using.

Source code

Want the full example?

👉 github.com/shygyver/kaapi-monorepo-playground
The example lives under validation-app.
Check the README for run instructions.

More Kaapi articles are coming.
This one was just about keeping validation where it belongs.

📦 Get started now

npm install @kaapi/kaapi

🔗 Learn more: https://github.com/demingongo/kaapi/wiki

Building Modern Backends with Kaapi: Authorization

ShyGyver — Thu, 01 Jan 2026 15:40:52 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

Authorization?

I hesitated for a long time before writing this article.

Not because authentication and authorization are boring, quite the opposite. The problem is that they’re big. There are too many angles, too many trade-offs, and too many "it depends" moments to squeeze everything into a single post without turning it into a textbook.

At some point I stopped overthinking it and decided to do what backend engineers do best: split the problem into smaller pieces.

This series will grow over time. Eventually, we’ll get into Kaapi’s AuthDesign plugins, build a real authentication provider, and walk through OAuth2 and OIDC flows. But today, we’ll start simple and focus on the basics and wire up authentication and authorization using good old cookies.

No magic. No black boxes. Just Kaapi, Hapi, and a clear flow you can reason about.

Auth Designs: Kaapi’s way of thinking about auth

In Kaapi, authorization is organized around a concept called an Auth Design.

Think of an Auth Design as a reusable, self-contained authorization module that sits on top of Hapi’s auth system. It doesn’t just validate credentials, it defines how authentication works across your app.

An Auth Design can:

Register its own Hapi auth scheme and strategy
Plug seamlessly into Kaapi routes
Automatically describe itself in OpenAPI documentation

Kaapi ships with several built-in designs (Bearer, Basic, API Key), but the real power comes from being able to extend or replace them.

Enough theory though, let’s start by wiring things up using the built-ins and see how it feels in practice.

Bearer tokens: the “hello world” of APIs

Bearer authentication is usually the first stop. It works well for JWTs, API tokens, and anything that fits neatly into an Authorization header.

Here’s what it looks like in Kaapi.

import { Kaapi, BearerAuthDesign } from '@kaapi/kaapi';

const bearerAuth = new BearerAuthDesign({
  auth: {
    async validate(request, token) {
      if (token !== 'secret') {
        return { isValid: false };
      }

      return {
        isValid: true,
        credentials: { user: { name: 'admin' } },
      };
    },
  },
});

const app = new Kaapi({
  port: 3000,
  host: 'localhost',
  extend: [bearerAuth],
  routes: {
    auth: {
      strategy: bearerAuth.getStrategyName(),
      mode: 'try',
    },
  },
});

app.route(
  {
    method: 'GET',
    path: '/profile',
    auth: true, // shorthand for "mode: required"
  },
  ({ auth: { credentials: { user } } }) => `Hello ${user?.name || 'Guest'}!`
);

await app.listen();

Once this is running, you can hit /profile with:

Authorization: Bearer secret

If the token matches, you’re authenticated. If not, Kaapi quietly falls back to “guest mode”. Simple, explicit, predictable.

Basic auth: boring, but sometimes perfect

Basic authentication isn’t glamorous, but it’s still incredibly useful especially for internal tools, admin panels, or quick prototypes.

Kaapi includes a BasicAuthDesign out of the box, and setting it up feels almost suspiciously straightforward.

import { Kaapi, BasicAuthDesign } from '@kaapi/kaapi';

const basicAuth = new BasicAuthDesign({
  auth: {
    async validate(request, username, password) {
      if (username === 'admin' && password === 'password') {
        return { isValid: true, credentials: { user: { name: username } } };
      }

      return { isValid: false };
    },
  },
});

const app = new Kaapi({
  port: 3000,
  host: 'localhost',
  extend: [basicAuth],
  routes: {
    auth: {
      strategy: basicAuth.getStrategyName(),
      mode: 'try',
    },
  },
});

app.route(
  {
    method: 'GET',
    path: '/profile',
    auth: true,
  },
  ({ auth: { credentials: { user } } }) => `Hello ${user?.name || 'Guest'}!`
);

await app.listen();

Send a standard HTTP Basic header at /profile:

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

No ceremony. No extra wiring. It does exactly what you’d expect.

API keys: headers, queries, cookies

Sometimes you don’t want usernames and passwords. Sometimes you just want a token passed via a header, a query parameter, or a cookie.

That’s where APIKeyAuthDesign comes in.

import { Kaapi, APIKeyAuthDesign } from '@kaapi/kaapi';

const apiKeyAuth = new APIKeyAuthDesign({
  key: 'authorization',
  auth: {
    async validate(request, token) {
      if (token === 'secret') {
        return {
          isValid: true,
          credentials: { user: { name: 'admin' } },
        };
      }
      return { isValid: false };
    },
    headerTokenType: 'Session',
  },
})
  .inHeader() // default
  .setDescription('Session token type');

const app = new Kaapi({
  port: 3000,
  host: 'localhost',
  extend: [apiKeyAuth],
  routes: {
    auth: {
      strategy: apiKeyAuth.getStrategyName(),
      mode: 'try',
    },
  },
});

app.route(
  {
    method: 'GET',
    path: '/profile',
    auth: true,
  },
  ({ auth: { credentials: { user } } }) => `Hello ${user?.name || 'Guest'}!`
);

await app.listen();

By default, it reads from headers, but you can just as easily switch to:

apiKeyAuth.inQuery();
apiKeyAuth.inCookie();

The important detail here is that Kaapi normalizes everything for you. Your validate function receives the token without the prefix, regardless of where it came from.

At this point, we’ve covered the built-ins. Useful, flexible but still generic.

Now let’s do something more interesting.

Rolling our own: a cookie-based session Auth Design

What we want now is a complete flow:

A login page
Session-based authentication
Authorization via cookies
A logout endpoint

And we want all of that encapsulated inside a single Auth Design.

To keep things simple, we’ll use:

@hapi/yar for session cookies
A tiny in-memory user “database”
Plain HTML strings instead of a template engine

This isn’t about production hardening, it’s about understanding the architecture.

A tiny fake database

We’ll start with a mocked list of users.

Yes, the password is stored in clear text. No, that’s not the point here. Please forgive me.

export interface User {
  id: string;
  username: string;
  password: string;
  email: string;
}

export const REGISTERED_USERS: User[] = [
  { id: 'user-1', username: 'user', password: 'crossterm', email: 'user@email.com' },
];

Wiring up session cookies with `yar`

Because we’re relying on cookies, we need to register yar as a Kaapi plugin. This gives us encrypted, HTTP-only session storage with almost no effort.

import yar, { YarOptions } from '@hapi/yar';
import { KaapiPlugin } from '@kaapi/kaapi';

const COOKIE_NAME = 'sid-auth-app';

const yarOptions: YarOptions = {
  name: COOKIE_NAME,
  maxCookieSize: 1024,
  storeBlank: false,
  cookieOptions: {
    password: 'the-password-must-be-at-least-32-characters-long',
    path: '/',
    isSameSite: 'Strict',
    isSecure: process.env.NODE_ENV === 'production',
    isHttpOnly: true,
    clearInvalid: true,
    ignoreErrors: true,
    ttl: 4.32e7, // 12 hours
  },
};

export const yarPlugin: KaapiPlugin = {
  async integrate(t) {
    t.server.register({
      plugin: yar,
      options: yarOptions,
    });
  },
};

Once this plugin is registered, req.yar becomes available everywhere including inside our Auth Design.

HTML without a template engine (on purpose)

To keep the example focused, we’ll generate HTML directly from strings:

One page for the login form
One page for a successful login

This keeps the moving parts to a minimum and makes the flow easy to follow.

function generateFormHtml(errorMessage?: string): string {
  return `
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>Sign in</title>
  <style>
    :root {
      --bg: #0f172a;
      --card: #111827;
      --accent: #6366f1;
      --text: #e5e7eb;
      --muted: #9ca3af;
      --ring: rgba(99,102,241,.35);
    }
    * { box-sizing: border-box; }
    body {
      margin: 0; min-height: 100vh; display: grid; place-items: center;
      background: radial-gradient(1200px 600px at 20% 0%, #1f2937, var(--bg));
      font-family: system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", Arial, sans-serif;
      color: var(--text);
    }
    .card {
      width: 92%; max-width: 380px; padding: 26px 24px; border-radius: 16px;
      background: linear-gradient(180deg, rgba(255,255,255,.04), rgba(255,255,255,.02));
      border: 1px solid rgba(255,255,255,.08);
      box-shadow: 0 20px 50px rgba(0,0,0,.35);
      backdrop-filter: blur(8px);
    }
    .error {
      background: rgba(239,68,68,.15);
      color: #f87171;
      border: 1px solid rgba(239,68,68,.4);
      padding: 10px 14px;
      border-radius: 10px;
      font-size: .9rem;
      margin-bottom: 14px;
    }
    .title { font-size: 1.25rem; font-weight: 600; letter-spacing: .2px; margin: 0 0 8px; }
    .subtitle { color: var(--muted); font-size: .95rem; margin: 0 0 18px; }
    label { display: block; font-size: .85rem; color: var(--muted); margin: 12px 0 8px; }
    .field {
      display: flex; align-items: center; gap: 8px;
      background: #0b1220; border: 1px solid rgba(255,255,255,.08);
      padding: 12px 14px; border-radius: 12px;
      transition: border-color .2s, box-shadow .2s, transform .05s;
    }
    .field:focus-within {
      border-color: var(--accent); box-shadow: 0 0 0 4px var(--ring);
    }
    .field input {
      all: unset; flex: 1; color: var(--text); caret-color: var(--accent);
    }
    .icon {
      width: 18px; height: 18px; opacity: .7;
      filter: drop-shadow(0 1px 0 rgba(0,0,0,.35));
    }
    .actions { margin-top: 18px; display: flex; align-items: center; justify-content: space-between; }
    .btn {
      appearance: none; border: none; cursor: pointer;
      background: linear-gradient(135deg, #7c3aed, var(--accent));
      color: white; padding: 12px 16px; border-radius: 12px; font-weight: 600;
      box-shadow: 0 10px 20px rgba(99,102,241,.35); transition: transform .05s, filter .2s;
    }
    .btn:hover { filter: brightness(1.05); }
    .btn:active { transform: translateY(1px); }
    .meta { font-size: .85rem; color: var(--muted); }
    .link { color: var(--text); text-decoration: none; border-bottom: 1px dashed rgba(255,255,255,.2); }
    .link:hover { color: var(--accent); border-bottom-color: var(--accent); }
  </style>
</head>
<body>
  <form class="card" action="/login" method="post">
    <h1 class="title">Welcome back</h1>
    <p class="subtitle">Sign in to continue</p>

    <!-- Error message placeholder --> 

    ${errorMessage
      ? `<p class="error" id="error-message">
        ${errorMessage}
    </p>`
      : ''
    }

    <label for="username">Username</label>
    <div class="field">
      <svg class="icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
        <path d="M12 12a5 5 0 1 0-5-5 5 5 0 0 0 5 5Zm0 2c-4.42 0-8 2.18-8 4.87V21h16v-2.13C20 16.18 16.42 14 12 14Z"/>
      </svg>
      <input id="username" name="username" type="text" placeholder="yourname" required autocomplete="username"/>
    </div>

    <label for="password">Password</label>
    <div class="field">
      <svg class="icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
        <path d="M17 8V7a5 5 0 0 0-10 0v1H5v12h14V8Zm-8 0V7a3 3 0 0 1 6 0v1Z"/>
      </svg>
      <input id="password" name="password" type="password" placeholder="••••••••" required autocomplete="current-password"/>
    </div>

    <div class="actions">
      <button class="btn" type="submit">Sign in</button>
      <span class="meta"><a class="link" href="#">Forgot password?</a></span>
    </div>
  </form>
</body>
</html>
            `;
}

function generateSuccessHtml(): string {
  return `
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>Login Successful</title>
  <style>
    :root {
      --bg: #0f172a;
      --card: #111827;
      --accent: #22c55e;
      --danger: #ef4444;
      --text: #e5e7eb;
      --muted: #9ca3af;
    }
    * { box-sizing: border-box; }
    body {
      margin: 0; min-height: 100vh; display: grid; place-items: center;
      background: radial-gradient(1200px 600px at 20% 0%, #1f2937, var(--bg));
      font-family: system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", Arial, sans-serif;
      color: var(--text);
    }
    .card {
      width: 92%; max-width: 420px; padding: 32px 28px; border-radius: 18px;
      background: linear-gradient(180deg, rgba(255,255,255,.04), rgba(255,255,255,.02));
      border: 1px solid rgba(255,255,255,.08);
      box-shadow: 0 20px 50px rgba(0,0,0,.35);
      backdrop-filter: blur(8px);
      text-align: center;
    }
    .icon {
      width: 64px; height: 64px; margin-bottom: 20px;
      color: var(--accent);
      filter: drop-shadow(0 4px 6px rgba(34,197,94,.35));
    }
    h1 { font-size: 1.6rem; margin: 0 0 12px; }
    p { font-size: 1rem; color: var(--muted); margin: 0 0 24px; }
    .btn {
      appearance: none; border: none; cursor: pointer;
      padding: 14px 20px; border-radius: 12px; font-weight: 600;
      box-shadow: 0 10px 20px rgba(0,0,0,.25); transition: transform .05s, filter .2s;
      margin: 6px;
    }
    .btn:hover { filter: brightness(1.05); }
    .btn:active { transform: translateY(1px); }
    .btn-success {
      background: linear-gradient(135deg, #16a34a, var(--accent));
      color: white;
      box-shadow: 0 10px 20px rgba(34,197,94,.35);
    }
    .btn-danger {
      background: linear-gradient(135deg, #dc2626, var(--danger));
      color: white;
      box-shadow: 0 10px 20px rgba(239,68,68,.35);
    }
  </style>
</head>
<body>
  <div class="card">
    <!-- Success checkmark icon -->
    <svg class="icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
      <path d="M12 2a10 10 0 1 0 10 10A10 10 0 0 0 12 2Zm-1 15-5-5 1.41-1.41L11 14.17l6.59-6.59L19 9l-8 8Z"/>
    </svg>
    <h1>Login Successful 🎉</h1>
    <p>Welcome back! You’ve successfully signed in.</p>
    <div>
      <button class="btn btn-success" onclick="window.location.href='/docs/api'">Go to Dashboard</button>
      <button class="btn btn-danger" onclick="window.location.href='/logout'">Log Out</button>
    </div>
  </div>
</body>
</html>
`;
}

Building the Auth Design itself

Now for the interesting part.

Instead of starting from scratch, we extend Kaapi’s APIKeyAuthDesign. Why? Because it already knows how to read credentials from cookies and we don’t need to reinvent that wheel.

Our custom design will:

Force authentication to happen only via cookies
Disable OpenAPI documentation (this is an internal mechanism)
Register /login and /logout routes as part of the design itself

import yar from '@hapi/yar';
import { APIKeyAuthArg, APIKeyAuthDesign, KaapiTools } from '@kaapi/kaapi';

export class CookieSessionAuthDesign extends APIKeyAuthDesign {
  constructor(settings: APIKeyAuthArg) {
    super(settings);
    this.inCookie();
  }

  /**
   * @override
   * This override disables OpenAPI generation for this security scheme.
   */
  docs() {
    return undefined;
  }

  /**
   * @override
   * This method has no effect for this subclass.
   */
  inHeader(): this {
    return this;
  }

  /**
   * @override
   * This method has no effect for this subclass.
   */
  inQuery(): this {
    return this;
  }

  async integrateHook(t: KaapiTools): Promise<void> {
    await super.integrateHook(t);

    t.route({
      path: '/logout',
      method: 'GET',
      options: {
        cors: false,
        plugins: {
          kaapi: {
            docs: false,
          },
        },
      },
      handler: (req, h) => {
        req.yar.reset();

        return h.redirect('/login');
      },
    });

    t.route<{ Payload: { username?: string; password?: string }; AuthUser: { id: string } }>({
      path: '/login',
      method: ['GET', 'POST'],
      options: {
        auth: {
          mode: 'try',
          strategy: this.strategyName,
        },
        cors: false,
        plugins: {
          kaapi: {
            docs: false,
          },
        },
      },
      handler: (req, h) => {
        let errorMessage = '';
        let statusCode = 200;

        if (req.auth.credentials?.user?.id) {
          return generateSuccessHtml();
        }

        if (req.method.toUpperCase() === 'POST') {
          const user = REGISTERED_USERS.find((u) => u.username === req.payload.username);

          if (user && user.password === req.payload.password) {
            req.yar.set('userId', user.id);
            return generateSuccessHtml();
          } else {
            statusCode = 401;
            errorMessage = 'Invalid username or password';
          }
        }

        return h.response(generateFormHtml(errorMessage)).code(statusCode);
      },
    });
  }
}

A couple of things are worth calling out here:

We override docs() to prevent this auth scheme from leaking into public API documentation
We explicitly disable headers and query tokens ➜ cookies only
Login and logout live inside the Auth Design, not scattered across the app

This is the key idea: the entire authentication lifecycle is owned by the design.

Validating the session

Finally, we instantiate the design and define how session validation works.

On every request:

We read the session cookie via yar
We look up the user
If it exists, we authenticate and attach credentials

export const cookieSessionAuth = new CookieSessionAuthDesign({
  strategyName: 'cookie-session',
  key: COOKIE_NAME,
  auth: {
    /**
     *
     * @param req
     * @param _token cookie value
     * @returns
     */
    async validate(req, _token) {
      const value = req.yar.get('userId');

      const user = REGISTERED_USERS.find((u) => u.id === value);

      if (user) {
        return {
          isValid: true,
          credentials: {
            user: { id: user.id },
            scope: ['internal:session'],
          },
        };
      }

      return { isValid: false };
    },
  },
}).setDescription(
  `Authentication is managed via a <u>secure</u>, HTTP-only session cookie.  
 The cookie is issued after login and must be included in subsequent requests.  
 It is automatically invalidated when the session expires or the user logs out.`
);

At this point, login, authentication, authorization, and logout are all handled in one place.

Plugging everything into the app

The last steps are almost anticlimactic.

We extend the app:

await app.extend([yarPlugin, cookieSessionAuth]);

Set a default auth strategy:

app.base().auth.default({
  strategies: [cookieSessionAuth.getStrategyName()],
  mode: 'try',
});

And finally, protect the API documentation behind authentication:

app.base().ext('onPostAuth', (request, h) => {
  // restrict access to api docs
  if (request.path.startsWith('/docs/')) {
    if (!(request.auth.isAuthenticated && request.auth.credentials.scope?.includes('internal:session'))) {
      return h.redirect('/login').takeover();
    }
  }

  return h.continue;
});

If a user isn’t authenticated, they get redirected to /login. No middleware soup. No scattered guards.

Wrapping up

This is what Auth Designs are really about.

They’re not just validators. They’re ownership boundaries. When done right, authentication stops being something you sprinkle across routes and starts being something you plug in.

In the next part of this series, we’ll push this further: multiple providers, OAuth flows, and tighter integration with external identity systems.

But for now, you’ve got:

Cookie-based sessions
Login and logout
Route-level authorization
And a clean mental model

That’s a solid foundation.

Source Code

Curious to see the full app, judge the architecture, or spot a typo?

👉 github.com/shygyver/kaapi-monorepo-playground
The example lives under authorization-app.
See the README for instructions on running it.

More Kaapi articles are coming! It has plenty more tricks up its sleeve.

📦 Get started now

npm install @kaapi/kaapi

🔗 Learn more: https://github.com/demingongo/kaapi/wiki

Building Modern Backends with Kaapi: Request validation

ShyGyver — Sun, 07 Dec 2025 16:11:42 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

Validation?

Before we let any data wander freely into our backend (with muddy boots and questionable intentions), it’s usually a good idea to validate it.

Kaapi is built on top of Hapi, which already comes with great tools for this, thanks to Joi. If you want the full lecture, Hapi’s tutorial explains everything in glorious detail.

Here’s a tiny example from their documentation, just to remind ourselves how things look with Joi:

app.route<{ Params: { name: string } }>({
  method: 'GET',
  path: '/hello/{name}',
  handler: function (request, h) {
    return `Hello ${request.params.name}!`;
  },
  options: {
    validate: {
      params: Joi.object({
        name: Joi.string().min(3).max(10)
      })
    }
  }
});

Nothing surprising here… except Kaapi can automatically generate documentation from your validation.

See: documentation generation article.

But Kaapi targets TypeScript, so naturally we want life to be as type-safe and boilerplate-free as possible.

So why are we still writing generic type arguments?

Writing <{ Params: { name: string } }> works, but feels unnecessary when the validator already knows the type.
Zod, Valibot and ArkType provide type inference. Kaapi happily consumes that and eliminate boilerplate for you.

Let’s take a tour through all three.

Integrating Validators

To use anything other than Joi, you install the appropriate plugin and extend your Kaapi instance.

Validate with Zod

Install:

zod
@kaapi/validator-zod

Extend your app:

import { Kaapi } from '@kaapi/kaapi';
import { validatorZod } from '@kaapi/validator-zod';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorZod);
};

start();

And now you can do:

import { z } from 'zod';

app
  .base()
  .zod({
    params: z.object({
      name: z.string().min(3).max(10)
    })
  })
  .route({
    method: 'GET',
    path: '/hello/{name}',
    handler: function (request, h) {
      return `Hello ${request.params.name}!`;
    }
  });

Hover over request.params.name in VSCode to see the magic of type inference.
No generics, no sadness (even without Joi).

Validate with Valibot

Install:

valibot
@kaapi/validator-valibot

Extend:

import { Kaapi } from '@kaapi/kaapi';
import { validatorValibot } from '@kaapi/validator-valibot';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorValibot);
};

start();

Use it:

import * as v from 'valibot';

app
  .base()
  .valibot({
    params: v.object({
      name: v.pipe(v.string(), v.minLength(3), v.maxLength(10))
    })
  })
  .route({
    method: 'GET',
    path: '/hello/{name}',
    handler: function (request, h) {
      return `Hello ${request.params.name}!`;
    }
  });

Valibot is extremely fast and super modular.
It’s like Lego bricks, if Lego bricks did runtime type checking.

Validate with ArkType

Install:

arktype
@kaapi/validator-arktype

Extend:

import { Kaapi } from '@kaapi/kaapi';
import { validatorArk } from '@kaapi/validator-arktype';

const app = new Kaapi({ /* ... */ });

const start = async () => {
  await app.extend(validatorArk);
};

start();

Use:

import { type } from 'arktype';

app
  .base()
  .ark({
    params: type({
      name: '3 <= string <= 10'
    })
  })
  .route({
    method: 'GET',
    path: '/hello/{name}',
    handler: function (request, h) {
      return `Hello ${request.params.name}!`;
    }
  });

ArkType is almost… poetic.
Where else can you write '3 <= string <= 10' and have TypeScript say "Yep, that checks out"?

A Real Example: Binomial Coefficients!

We’ve all written “Hello World” too many times, so let’s compute something actually useful:
the binomial coefficient, a.k.a. n choose r.

Here’s the function:

function binomialCoefficient(n: number, r: number) {
  if (r < 0 || r > n) return 0;
  let result = 1;
  for (let i = 1; i <= r; i++) {
    result = result * (n - i + 1) / i;
  }
  return result;
}

Definitions:

n: total objects
r: objects chosen at once

Rules:

r must be an integer > 0
r ≤ n

Bonus rules (because constraints are fun):

n ∈ [1, 50]
r ∈ {1, 2, 3}
r defaults to 3
Input may be a string or number
Validators should convert strings → numbers

Below we implement this in Zod, Valibot, ArkType, and finally Joi.

(Yes, we’re doing all four. Because we can.)

Zod Version

import { z } from 'zod';

// payload schema
const combinationPayloadSchema = z
  .object({
    n: z
      .preprocess((x) => Number(x), z.int().positive().min(1).max(50))
      .meta({
        description: 'The total number of objects in the set',
        examples: [5],
      }),
    r: z
      .preprocess(
        (x) => Number(x),
        z.enum({
          one: 1,
          two: 2,
          three: 3,
        })
      )
      .optional()
      .default(3)
      .meta({
        description: 'The number of objects chosen at once',
        examples: [3],
      }),
  })
  .refine(
    (schema) => schema.n >= schema.r,
    { error: 'make sure that n ≥ r' }
  )
  .meta({
    description: 'combination nCr inputs',
    ref: '#/components/schemas/CombinationInputsWithZod',
  });

// route
app.base()
  .zod({ payload: combinationPayloadSchema })
  .route(
    {
      method: 'POST',
      path: '/zod/combination',
      options: {
        description: 'Calculate the combination of n and r.',
        tags: ['zod'],
        payload: {
          allow: ['application/json', 'application/x-www-form-urlencoded'],
        },
      },
    },
    ({ payload: { n, r } }) => ({
      inputs: { n, r },
      coefficient: binomialCoefficient(n, r)
    })
  );

Valibot Version

import * as v from 'valibot';

// payload schema
const combinationPayloadSchema = v.pipe(
  v.object({
    n: v.pipe(
      v.union([
        v.number(),
        v.pipe(v.string(), v.transform((input) => Number(input))),
      ]),
      v.integer(),
      v.minValue(1),
      v.maxValue(50),
      v.description('The total number of objects in the set'),
      v.metadata({ examples: [5] })
    ),
    r: v.optional(
      v.pipe(
        v.union([
          v.number(),
          v.pipe(v.string(), v.transform((input) => Number(input))),
        ]),
        v.integer(),
        v.union([v.literal(1), v.literal(2), v.literal(3)]),
        v.description('The number of objects chosen at once'),
        v.metadata({ examples: [3] })
      ),
      3
    ),
  }),
  v.check((input) => input.n >= input.r, 'make sure that n ≥ r'),
  v.description('combination nCr inputs'),
  v.metadata({
    ref: '#/components/schemas/CombinationInputsWithValibot',
  })
);

// route
app.base()
  .valibot({ payload: combinationPayloadSchema })
  .route(
    {
      method: 'POST',
      path: '/valibot/combination',
      options: {
        description: 'Calculate the combination of n and r.',
        tags: ['valibot'],
        payload: {
          allow: ['application/json', 'application/x-www-form-urlencoded'],
        },
      },
    },
    ({ payload: { n, r } }) => ({
      inputs: { n, r },
      coefficient: binomialCoefficient(n, r)
    })
  );

ArkType Version

import { RequestBodyDocsModifier } from '@kaapi/kaapi';
import { type } from 'arktype';

// payload schema
const combinationPayloadSchema = type([
  {
    n: type([
      'number.integer | string',
      '@',
      { description: 'The total number of objects in the set', expected: 'an integer', examples: [5], format: 'integer' },
    ])
      .pipe((v) => Number(v))
      .to('1 <= number.integer <= 50'),
    r: type([
      '1 | 2 | 3 | string',
      '@',
      {
        description: 'The number of objects chosen at once',
        expected: '1, 2 or 3',
        examples: [3],
        format: 'integer',
      },
    ])
      .pipe((v) => (typeof v === 'string' ? (v ? Number(v) : NaN) : v))
      .to('1 | 2 | 3')
      .default(3),
  },
  '@',
  'combination nCr inputs',
]).pipe((payload) => {
  return type({
    n: type(`number >= ${payload.r}`, '@', '≥ r'),
    r: 'number',
  })(payload);
});

// route
app.base()
  .ark({
    payload: combinationPayloadSchema,
  })
  .route(
    {
      method: 'POST',
      path: '/ark/combination',
      options: {
        description: 'Calculate the combination of n and r.',
        tags: ['ark'],
        payload: {
          allow: ['application/json', 'application/x-www-form-urlencoded'],
        },
        plugins: {
          kaapi: {
            docs: {
              modifiers: () => ({
                requestBody: new RequestBodyDocsModifier()
                  .addMediaType('application/json', {
                    schema: {
                      properties: {
                        n: {
                          minimum: 1,
                          maximum: 50,
                        },
                      },
                    },
                  })
                  .addMediaType('application/x-www-form-urlencoded', {
                    schema: {
                      properties: {
                        n: {
                          minimum: 1,
                          maximum: 50,
                        },
                      },
                    },
                  }),
              }),
            },
          },
        },
      },
    },
    ({ payload: { n, r } }) => ({ inputs: { n, r }, coefficient: binomialCoefficient(n, r) })
  );

ArkType gets us most of the way there, but its auto-documentation leaves a few holes. That’s why we stepped in with RequestBodyDocsModifier to round things out.

Joi Version (for comparison)

import Joi from 'joi';

// payload schema
const combinationPayloadSchema = Joi.object({
  n: Joi.number()
    .description('The total number of objects in the set')
    .integer()
    .min(1)
    .max(50)
    .example(5)
    .when('r', {
      is: Joi.number(),
      then: Joi.number().min(Joi.ref('r')),
    })
    .required(),

  r: Joi.number()
    .description('The number of objects chosen at once')
    .integer()
    .valid(1, 2, 3)
    .default(3)
    .example(3)
    .optional(),
})
  .meta({ ref: '#/components/schemas/CombinationInputsWithJoi' })
  .description('combination nCr inputs')
  .required();

// route
app.route<{ Payload: { n: number; r: 1 | 2 | 3 } }>(
  {
    method: 'POST',
    path: '/joi/combination',
    options: {
      description: 'Calculate the combination of n and r.',
      tags: ['joi'],
      payload: {
        allow: ['application/json', 'application/x-www-form-urlencoded'],
      },
      validate: {
        payload: combinationPayloadSchema,
      },
    },
  },
  ({ payload: { n, r } }) => ({
    inputs: { n, r },
    coefficient: binomialCoefficient(n, r)
  })
);

Joi still requires the explicit generic type <{ Payload: … }>, but the schema itself is wonderfully compact.

So… Which Validator Should You Use?

Honestly?
Any of them.
Kaapi doesn’t play favourites. You can mix and match all four in the same project.

Here’s the vibe check:

Validator	Pros	Cons
Zod	Great DX, powerful transforms, strong TS inference	Verbose
Valibot	Very fast, very modular	Piping can get long
ArkType	Most human-readable (`"3 <= string <= 10"`), minimal syntax	Weaker doc generation, sometimes needs manual modifiers for complex schemas
Joi	Built-in with Hapi/Kaapi, concise	Needs explicit TS generics

Choose based on:

Minimal code? → Joi or ArkType
Strong type inference without generics? → Zod or Valibot
Human-readable schemas? → ArkType
Excellent auto-docs? → Zod / Valibot / Joi

Basically:
Kaapi gives you the whole toolbox. Pick the screwdriver that makes you happy.

Source Code

Curious to see the full app, judge the architecture, or spot a typo?

👉 github.com/shygyver/kaapi-monorepo-playground
The example lives under validation-app.
See the README for instructions on running it.

More Kaapi articles are coming! It has plenty more tricks up its sleeve.

📦 Get started now

npm install @kaapi/kaapi

🔗 Learn more: https://github.com/demingongo/kaapi/wiki

Building Modern Backends with Kaapi: API Documentation Generation

ShyGyver — Sat, 29 Nov 2025 18:58:17 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

Documentation?

(Yes, we actually read it… sometimes.)

A good API lives or dies by its documentation.
Whether you have a public API, a private API, or an "API that only Chad from DevOps knows how to use", someone eventually needs to understand it.

Kaapi does this for you by auto-generating docs in two formats, because why settle for one?

OpenAPI v3.1.1: for a complete, machine-readable definition
Postman Collection v2.1: for folks on Postman’s free tier (👋 hi, we see you)

Before we jump straight into documentation generation, we need... configuration. So let’s start there.

Configuration

A Kaapi app starts like a regular Hapi server:

import { Kaapi } from '@kaapi/kaapi';

const app = new Kaapi({
  // ServerOptions
  port: 3000,
  host: 'localhost',
});

const start = async () => {
  app.route({
    method: 'GET',
    path: '/hello',
    options: {
        description: 'Another Hello World.',
    },
    handler: () => `Hello World!`,
  });

  await app.listen();
  app.log('🚀 Server running at:', app.base().info.uri);
};

start();

Once this is running, visit:

Swagger UI → http://localhost:3000/docs/api
OpenAPI schema → /docs/api/schema
Postman collection → /docs/api/schema?format=postman

Boom. Instant documentation. Zero guilt.

Now let’s customize the documentation settings using the docs option:

import { Kaapi } from '@kaapi/kaapi';

const app = new Kaapi({
  // ServerOptions
  port: 3000,
  host: 'localhost',

  // DocsConfig
  docs: {
    disabled: false, // disable documentation generation, default: false
    path: '/docs/api', // path to documentation, default: /docs/api
    title: 'My First App',
    version: '1.0.1',
    ui: {
      swagger: {
        customCss: '.swagger-ui .topbar { display: none; }',
        customSiteTitle: 'My First App',
      },
    },
  },
});

Visit /docs/api again, and voilà! Your Swagger UI now has a personalized title, a missing top bar and shows a new API version and title.

Petstore Example

Because no API documentation article is complete without animals,

Time to recreate the legendary Swagger Petstore with request data validation.

Petstore Configuration

We’re turning the configuration dial up to Fancy Mode:

const app = new Kaapi({
  // LoggerOptions
  loggerOptions: {
    level: 'debug',
  },

  port: 3000,
  host: 'localhost',

  docs: {
    disabled: false,
    path: '/docs/api',
    title: 'Petstore',
    license: {
      name: 'MIT',
      url: 'https://raw.githubusercontent.com/shygyver/kaapi-monorepo-playground/refs/heads/main/LICENSE',
    },
    version: '1.0.12',
    ui: {
      swagger: {
        customCss: '.swagger-ui .topbar { display: none; }',
        customSiteTitle: 'Swagger UI - Petstore',
      },
    },

    host: {
      url: '{baseUrl}',
      variables: {
        baseUrl: {
          default: 'http://localhost:3000',
          enum: ['http://localhost:3000'],
        },
      },
    },

    tags: [
      {
        name: 'pet',
        description: 'Everything about your Pets',
        externalDocs: {
          url: 'https://swagger.io/',
          description: 'Find out more',
        },
      },
    ],
  },
});

Why define docs.host?
Useful when deploying to production so Postman and external clients resolve URLs correctly. For local development, we simply set the internal uri http://localhost:3000. Using a variable like {baseUrl} also keeps things clean when switching between environments.

Why define docs.tags?
This is optional, but helpful if you want to enrich tag metadata with descriptions or external links.

Now let’s also sprinkle some extra documentation seasoning using .setDescription(), .setContact(), .setExternalDoc(), and other goodies.

// info for OpenAPI specification
app.openapi
  .setDescription(
    `This is an OpenAPI 3.1.1 specification of a sample Pet Store Server build with Kaapi. You can find out more about Kaapi at [https://www.npmjs.com/package/@kaapi/kaapi](https://www.npmjs.com/package/@kaapi/kaapi).  
Some useful links:
- [The original Pet Store repository](https://github.com/swagger-api/swagger-petstore)
- [OpenAPI Specification v3.1.1](https://spec.openapis.org/oas/v3.1.1.html)
`
    )
  .setTermsOfService('https://raw.githubusercontent.com/shygyver/kaapi-monorepo-playground/refs/heads/main/LICENSE')
  .setContact({
    url: 'https://github.com/shygyver',
  })
  .setExternalDoc({
    url: 'https://github.com/demingongo/kaapi/wiki',
    description: 'Find out more about Kaapi',
  });

// info for Postman collection
app.postman
  .setDescription(`This is a Postman 2.1.0 collection format of a sample Pet Store Server build with Kaapi. You can find out more about Kaapi at [https://www.npmjs.com/package/@kaapi/kaapi](https://www.npmjs.com/package/@kaapi/kaapi).  
Some useful links:
- [The original Pet Store repository](https://github.com/swagger-api/swagger-petstore)
- [Postman Collection Format v2.1.0](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html)
`);

Petstore - Update an existing pet (Payload)

We’ll use Joi for validation.

We also extend Joi to be nicer with application/x-www-form-urlencoded:

import Joi from 'joi';

// validator ajustments for application/x-www-form-urlencoded
const customJoi: Joi.Root = Joi.extend(
  (joi) => ({
    type: 'array',
    base: joi.array(),
    coerce: {
      from: 'string',
      method(value) {
        try {
          if (typeof value === 'string') {
            if (value.startsWith('[') && value.endsWith(']')) {
              return { value: JSON.parse(value) };
            } else {
              return { value: value.split(',') };
            }
          }
        } catch (err) {
          app.log.error(err);
        }
        return { value };
      },
    },
  }),
  (joi) => ({
    type: 'object',
    base: joi.object(),
    coerce: {
      from: 'string',
      method(value) {
        try {
          if (typeof value === 'string' && value.startsWith('{')) {
            return { value: JSON.parse(value) };
          }
        } catch (err) {
          app.log.error(err);
        }
        return { value };
      },
    },
  })
);

// 'Update an existing pet' endpoint
app.route<{
  Payload: {
    id: number;
    name: string;
    category?: {
      id?: 1;
      name?: string;
    };
    photoUrls: string[];
    tags?: [
      {
        id?: 0;
        name?: 'string';
      },
    ];
    status?: 'available';
  };
}>({
  path: '/pet',
  method: 'PUT',
  options: {
    tags: ['pet'],
    description: 'Update an existing pet.',
    notes: ['Update an existing pet by Id.'],
    payload: {
      allow: ['application/json', 'application/x-www-form-urlencoded'],
    },
    validate: {
      payload: Joi.object({
        id: Joi.number().integer().example(10).meta({ format: 'int64' }).required(),
        name: Joi.string().example('doggie').required(),
        category: customJoi
          .object({
            id: Joi.number().integer().example(1).meta({ format: 'int64' }),
            name: Joi.string().example('Dogs'),
          }),
        photoUrls: customJoi
          .array()
          .items(Joi.string().meta({ xml: { name: 'photoUrl' } }))
          .meta({ xml: { wrapped: true } })
          .required(),
        tags: customJoi
          .array()
          .items(
            Joi.object({
              id: Joi.number().integer().meta({ format: 'int64' }),
              name: Joi.string(),
            }).meta({
              xml: { name: 'tag' },
            })
          )
          .meta({ xml: { wrapped: true } }),
        status: Joi.string().description('pet status in the store').valid('available', 'pending', 'sold'),
      })
        .meta({
          xml: { name: 'pet' },
        })
        .required(),
    },
  },
  handler: ({ payload }) => payload,
});

Boom:
You now have automatic validation and automatic documentation.
Swagger UI will even show examples, which means fewer Slack messages from coworkers asking,

“What does this endpoint expect again?”

Petstore - Update an existing pet (Responses)

Because your API should tell people what it actually does.
Here, if the request is valid, the endpoint simply returns the payload.

Instead of rewriting your response schemas everywhere (aka the “Copy/Paste Olympics”), Kaapi lets you reference components via Joi metadata:

app.route({
  // ...

  options: {

    // ...

    validate: {
      payload: Joi.object({
        id: Joi.number().integer().example(10).meta({ format: 'int64' }).required(),
        name: Joi.string().example('doggie').required(),
        category: customJoi
          .object({
            id: Joi.number().integer().example(1).meta({ format: 'int64' }),
            name: Joi.string().example('Dogs'),
          })
          .meta({
            ref: '#/components/schemas/Category', // 👈 here
          }),
        photoUrls: customJoi
          .array()
          .items(Joi.string().meta({ xml: { name: 'photoUrl' } }))
          .meta({ xml: { wrapped: true } })
          .required(),
        tags: customJoi
          .array()
          .items(
            Joi.object({
              id: Joi.number().integer().meta({ format: 'int64' }),
              name: Joi.string(),
            }).meta({
              xml: { name: 'tag' },
              ref: '#/components/schemas/Tag', // 👈 here
            })
          )
          .meta({ xml: { wrapped: true } }),
        status: Joi.string().description('pet status in the store').valid('available', 'pending', 'sold'),
      })
        .meta({
          xml: { name: 'pet' },
          ref: '#/components/schemas/Pet', // 👈 here
        })
        .required(),
    },
  },
  handler: ({ payload }) => payload,
});

Adding meta({ ref: '#/components/schemas/Pet' }) registers the schema Pet into #/components/schemas, if it was not already registered. We do the same for Tag and Category.

Once registered, documenting responses with modifiers, part of Kaapi’s built-in plugins, becomes easy:

import { ResponseDocsModifier } from '@kaapi/kaapi';

app.route({
  // ...

  options: {

    // ...

    validate: {
      payload: Joi.object({

        // ...

      })
        .meta({
          xml: { name: 'pet' },
          ref: '#/components/schemas/Pet', // 👈 creates schema reference
        })
        .required(),
    },
    plugins: {
      kaapi: {
        docs: {
          modifiers: () => ({
            responses: new ResponseDocsModifier()
              .setCode(200)
              .setDescription('Successful operation')
              .addMediaType('application/json', {
                schema: { $ref: '#/components/schemas/Pet' }, // 👈 use reference
              }),
          }),
        },
      },
    },
  },
  // ...
});

You can also group responses:

import { groupResponses, ResponseDocsModifier } from '@kaapi/kaapi';

app.route({
  // ...

  options: {

    // ...

    plugins: {
      kaapi: {
        docs: {
          modifiers: () => ({
            responses: groupResponses(
              new ResponseDocsModifier()
                .setCode(200)
                .setDescription('Bad Request')
                .addMediaType('application/json', {
                  schema: { $ref: '#/components/schemas/Pet' },
                }),
              new ResponseDocsModifier()
                .setCode(400)
                .setDescription('Bad Request')
                .addMediaType('application/json', {
                  schema: {
                    type: 'object',
                    properties: {
                      statusCode: {
                        type: 'number',
                        enum: [400],
                      },
                      error: { type: 'string', enum: ['Bad Request'] },
                      message: { type: 'string' },
                    },
                    required: ['statusCode', 'error'],
                  },
                }),
              new ResponseDocsModifier().setCode(404).setDescription('Pet not found'),
              new ResponseDocsModifier().setCode(415).setDescription('Unsupported Media Type'),
              new ResponseDocsModifier()
                .setDefault(true)
                .setDescription('Unexpected error')
                .addMediaType('application/json', {
                  schema: {
                    type: 'object',
                    properties: {
                      statusCode: {
                        type: 'number',
                      },
                      error: { type: 'string' },
                      message: { type: 'string' },
                    },
                    required: ['statusCode', 'error'],
                  }
                }
              )
            ),
          }),
        },
      },
    },
  },
  // ...
});

Reusing Shared Responses

Since we’ll probably reuse some responses (like 400 Bad Request) across multiple routes, it’s better to define them once:

import {
  ResponseDocsModifier, 
  SchemaModifier 
} from '@kaapi/kaapi';

// Error schema
const errorSchema = new SchemaModifier('Error', {
  type: 'object',
  properties: {
    statusCode: {
      type: 'number',
    },
    error: { type: 'string' },
    message: { type: 'string' },
  },
  required: ['statusCode', 'error'],
});

// BadRequestResponse response
const badRequestResponse = new ResponseDocsModifier('BadRequestResponse')
  .setDescription('Bad Request')
  .addMediaType('application/json', {
    schema: {
      type: 'object',
      properties: {
        statusCode: {
          type: 'number',
          enum: [400],
        },
        error: { type: 'string', enum: ['Bad Request'] },
        message: { type: 'string' },
      },
      required: ['statusCode', 'error'],
    },
  });

import {
  groupResponses,
  Kaapi
} from '@kaapi/kaapi';

const app = new Kaapi({
  // ...

  docs: {
    // ...

    schemas: [errorSchema], // 👈 register schemas
    responses: groupResponses(badRequestResponse), // 👈 register responses
  },
});

Then reuse them:

import { 
  groupResponses,
  MediaTypeModifier, 
  ResponseDocsModifier,
} from '@kaapi/kaapi';

// endpoint
app.route({
  // ...

  options: {

    // ...

    plugins: {
      kaapi: {
        docs: {
          modifiers: () => ({
            responses: groupResponses(
              new ResponseDocsModifier()
                .setCode(200)
                .setDescription('Successful operation')
                .addMediaType('application/json', {
                  schema: { $ref: '#/components/schemas/Pet' },
                }),
              badRequestResponse.withContext().setCode(400), // 👈 use response in this route context
              new ResponseDocsModifier().setCode(404).setDescription('Pet not found'),
              new ResponseDocsModifier().setCode(415).setDescription('Unsupported Media Type'),
              new ResponseDocsModifier()
                .setDefault(true)
                .setDescription('Unexpected error')
                .addMediaType('application/json', new MediaTypeModifier({ schema: errorSchema })) // 👈 use schema
            ),
          }),
        },
      },
    },
  },
  // ...
});

Less schema duplication. More happiness.

A Note on XML Support

So... we are done for this route but here’s the unfortunate truth:

allow: ['application/json', 'application/x-www-form-urlencoded'],

Unlike the original Swagger Petstore API, our example does not support application/xml, even though our schemas include XML metadata.
So why not do it? Because by default, payloads are parsed into JSON for validation.
Disabling parsing means disabling Joi validation and auto-generated docs.
In short:

disabling JSON parsing = disabling Joi
disabling Joi = sadness or disabling auto-generated docs

But don’t worry, it is possible to disable parsing and manually document payloads, but to keep the example simple, we skipped it.

Instead, let's check it out in the next example.

Petstore - Uploads an image

File uploads should not be parsed into JSON (and they can't be anyway). For this route we will:

disable automatic parsing
manually validate the uploaded file type (PNG/JPEG)
describe the request body manually using RequestBodyDocsModifier

Here is the result:

import Boom from '@hapi/boom';
import { 
  groupResponses, 
  Kaapi, 
  MediaTypeModifier, 
  RequestBodyDocsModifier,
  ResponseDocsModifier, 
  SchemaModifier 
} from '@kaapi/kaapi';
import Joi from 'joi';
import Stream, { PassThrough } from 'node:stream';

// ...

app.route<{ Params: { petId: number }; Payload: Stream.Readable; Query: { additionalMetadata?: string } }>({
  path: '/pet/{petId}/uploadImage',
  method: 'POST',
  options: {
    tags: ['pet'],
    description: 'Uploads an image.',
    notes: ['Upload image of the pet.'],
    payload: {
      allow: ['application/octet-stream'],
      output: 'stream',
      maxBytes: 1024 * 2000,
      multipart: false,
      parse: false, // 👈 disable auto parsing
    },
    validate: {
      params: Joi.object({
        petId: Joi.number().integer().description('ID of pet to update').meta({ format: 'int64' }).required(),
      }),
      query: Joi.object({
        additionalMetadata: Joi.string().description('Additional Metadata'),
      }),
    },
    plugins: {
      kaapi: {
        docs: {
          modifiers: () => ({
            // 👇 payload schema definition
            requestBody: new RequestBodyDocsModifier().addMediaType('application/octet-stream', {
              schema: {
                type: 'string',
                contentMediaType: 'application/octet-stream',
              },
            }),
            responses: groupResponses(
              new ResponseDocsModifier().setCode(200).setDescription('successful operation'),
              badRequestResponse.withContext().setCode(400),
              new ResponseDocsModifier().setCode(404).setDescription('Pet not found'),
              new ResponseDocsModifier()
                .setDefault(true)
                .setDescription('Unexpected error')
                .addMediaType('application/json', new MediaTypeModifier({ schema: errorSchema }))
            ),
          }),
        },
      },
    },
  },
  handler: async ({ params: { petId }, payload, query: { additionalMetadata } }, h) => {
    app.log.debug(`[uploadFile] petId: ${petId}`);
    app.log.debug(`[uploadFile] additionalMetadata: ${additionalMetadata}`);

    // validate file signature (PNG/JPG) and stream it back
    return new Promise((resolve, reject) => {
      // Collect first few bytes for validation
      let buffer = Buffer.alloc(0);
      let validated = false;
      const pass = new PassThrough();

      payload.on('data', (chunk) => {
        if (!validated) {
          buffer = Buffer.concat([buffer, chunk]);

          if (buffer.length >= 8) {
            const header = buffer.subarray(0, 8);

            // PNG/JPG check
            const pngSig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
            const jpegSig = Buffer.from([0xff, 0xd8]);

            if (header.equals(pngSig) || header.subarray(0, 2).equals(jpegSig)) {
              validated = true;
              resolve(h.response(pass).type(header.equals(pngSig) ? 'image/png' : 'image/jpeg'));
            } else {
              payload.unpipe(pass);
              // Drain the rest of the stream so client doesn't hang
              payload.resume();
              return reject(Boom.badRequest('Invalid file type'));
            }
          }
        }
        pass.write(chunk);
      });

      payload.on('end', () => {
        app.log.debug('[uploadFile] Done parsing payload!');
        pass.end();
        if (buffer.length < 8) {
          return reject(Boom.badRequest('No file uploaded'));
        }
      });
    });
  },
});

With that, we’ve covered the core of API documentation in Kaapi.

Source Code

Where all the magic came from (and where you can go judge my code):

👉 github.com/shygyver/kaapi-monorepo-playground
The app demonstrated here is named documentation-app.
See the README for instructions on running it.

Stay tuned for more! Kaapi still has more features to show off!

📦 Get started now

npm install @kaapi/kaapi

🔗 Learn more: github.com/demingongo/kaapi/wiki

Building Modern Backends with Kaapi: Introduction & Getting Started

ShyGyver — Wed, 26 Nov 2025 18:43:32 +0000

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

What Is Kaapi?

Kaapi (@kaapi/kaapi) is a TypeScript-first backend framework built on top of Hapi.js.

It gives you a clean foundation for building modular, documented, and message-driven APIs without the boilerplate.

Think of it as Hapi, but with:

Type safety throughout
Messaging support (Kafka-ready)
Auto-generated OpenAPI & Postman docs
Built-in logging via Winston

So not "Yet again a new Nodejs framework this year!" in case your were thinking that (I know you did) but rather a practical evolution: the same trusted Hapi core, now supercharged.

It’s about cutting boilerplate, not reinventing the wheel.

⚙️ Installation

Install it from npm:

npm install @kaapi/kaapi

🚀 Your First Kaapi Application

Kaapi is built on Hapi, so everything you know from Hapi still works; but Kaapi adds higher-level ergonomics.

Here’s the simplest working server:

import { Kaapi } from '@kaapi/kaapi';

const init = async () => {
  const app = new Kaapi({
    port: 3000,
    host: 'localhost',
  });

  await app.listen();
  app.log('🚀 Server running at:', app.base().info.uri);
};

init();

app.listen() starts the server
app.base() gives access to the underlying Hapi server

Routing

Routing feels familiar, declarative and type-safe:

app.route({
  method: 'GET',
  path: '/',
}, () => 'Hello World!');

Want a custom 404? Just register an empty route config:

app.route({}, (req, h) => h.response('404 Not Found').code(404));

The {} route acts as a global catch-all; simple and intuitive.

Logging Made Easy

Kaapi comes with Winston out of the box.

app.log.silly('This is mindless');
app.log.debug('Debugging');
app.log.info('Server started');
app.log.warn('This is a warning');
app.log.error('Something went wrong');

Or define your own logger:

import winston from 'winston';
import { createLogger, Kaapi } from '@kaapi/kaapi';

const logger = createLogger({
  level: 'info',
  transports: [new winston.transports.Console()],
});

const app = new Kaapi({ logger });

Built-in API Documentation

Kaapi automatically generates OpenAPI + Postman docs.
Once your server runs, open:

/docs/api → Swagger UI
/docs/api/schema → OpenAPI JSON
/docs/api/schema?format=postman → Postman collection

Everything comes from your routes and Joi validations; no manual Swagger config.

Example route:

import Joi from 'joi';

app.route<{ Query: { name: string } }>({
  method: 'GET',
  path: '/',
  options: {
    description: 'Greet someone',
    tags: ['Index'],
    validate: {
      query: Joi.object({
        name: Joi.string()
          .trim()
          .default('World')
          .description('Optional name to personalize the greeting response'),
      }),
    },
  },
}, ({ query: { name } }) => `Hello ${name}!`);

What’s Coming Next

This article is just the start of the Kaapi series.
In upcoming parts, we’ll dive into the interesting subjects:

the configuration and documentation generation (OpenAPI, Postman, SwaggerUI)
Request data validation (with Arktype, Joi, Valibot, Zod)
Authentication with Auth Designs (Basic, API Key, OAuth2)
Messaging with Kafka and Event-Driven Architectures
Testing and Deployment Tips

📦 Get started now

npm install @kaapi/kaapi

🔗 Learn more: github.com/demingongo/kaapi/wiki

To an Old Friend: A Goodbye to Windows

ShyGyver — Mon, 13 Oct 2025 18:28:07 +0000

To an Old Friend: A Goodbye to Windows

We were there.

You were my first real OS. The one I crashed with bad C code, froze with my broken C++ while learning OpenGL, and probably abused a bit more than I should have with pirated tools I didn’t fully understand. But you were patient with me. You let me mess up. You let me learn.

I didn’t know it at the time, but those freezes and crashes were my first lessons in programming, system design, and responsibility. I wasn’t just learning code, I was learning how computers behave when humans get it wrong.

You were there during my curiosity phase, my mistakes, my breakthroughs. You saw the worst code I ever wrote and the first things I was truly proud of. You gave me the space to become who I am now.

But we’ve grown apart.

I still remember Windows 7 like it was yesterday: stable, respectful, customizable. Windows 10, for all its noise, still gave me room to breathe. But now, Windows 11… it’s not you anymore. It’s not me either. It’s a platform built for a different kind of user, with different priorities.

I’ve found other places that support who I am now. Systems that don’t reset my settings, track my actions, or try to push things I didn’t ask for. They don’t feel nostalgic. But they feel right.

Still, I won’t forget you. Not the crashes, not the late nights, not the joy of making something work for the first time.

So this isn’t bitterness.

It’s a handshake, a nod, a “thanks for everything.”

We may still cross paths now and then, maybe once a year, for that one app that still won’t run anywhere else. But the truth is, I’ve moved on.

We were there.

And I’m glad we were.

Forem: ShyGyver

Add Refresh Tokens to Your Hono OIDC Server (with Token Rotation)

TL;DR

What changes

Step 1: Update the client configuration

Step 2: Add refresh token storage

Step 3: Register offline_access in the flow builder

Step 4: Update getClient to handle the refresh token grant

Step 5: Issue a refresh token in generateAccessToken

Step 6: Add generateAccessTokenFromRefreshToken

How the full flow works

Security considerations

What's next

Rambling note

Add a Consent Screen to Your OIDC Authorization Server with Hono

TL;DR

What changes

Step 1: Add imports and augment types

Step 2: Define ParsedData

Step 3: Add session storage

Step 4: Update the flow builder

4.1 Pass the generic type parameter

4.2 Parse consent and session cookie

4.3 Update getUserForAuthentication

4.4 Update generateAuthorizationCode

Step 5: Update the GET handler for the authorization endpoint

Step 6: Update the POST handler for the authorization endpoint

Step 7: Add the consent page component

How the full flow works

Improvements

What's next

Persistent JWT Signing Keys with PostgreSQL

TL;DR

The problem with in-memory keys

Key concepts

Envelope encryption

Prerequisites

Database schema

Step 1: Install the PostgreSQL driver

Step 2: Write src/db.ts

saveKeyPairRecord

Read functions

Step 3: Write src/stores.ts

Imports and master key

Crypto helpers

jwksStore (JwksKeyStore)

rotationTimestampStore (JwksRotationTimestampStore)

Step 4: Update src/index.ts

Step 5: Run the server

Key rotation behavior

Conclusion

What's next

Make Your Hono Authorization Server Work on Any Host

Step 1: Import getOriginFromRequest

Step 2: Remove the ISSUER constant and loosen CLIENT.redirectUris

Step 3: Use a relative discovery URL

Step 4: Validate the redirect URI against the request origin

Step 5: Set the iss claim from the grant context

Step 6: Prepend the runtime origin to the OpenAPI security scheme

Result

Build an Authorization Server with Bun, Hono, and OpenID Connect

TL;DR

What we're building

Prerequisites

Step 1: Create the project

Step 2: Install dependencies

Step 3: Write the server

3.1 Imports

3.2 Extend UserCredentials

3.3 Configure JWT key management

3.4 Define clients and users (in-memory)

3.5 Build the OIDC flow

Parse the authorization endpoint data

Configure endpoints and scopes

Set client authentication methods

Token lifetime and OIDC metadata

Authenticate the client at the authorization endpoint

Authenticate the user

Generate an authorization code

Exchange the authorization code at the token endpoint

Step 3: Register `offline_access` in the flow builder

Step 4: Update `getClient` to handle the refresh token grant

Step 5: Issue a refresh token in `generateAccessToken`

Step 6: Add `generateAccessTokenFromRefreshToken`

Step 2: Define `ParsedData`

4.3 Update `getUserForAuthentication`

4.4 Update `generateAuthorizationCode`

Step 2: Write `src/db.ts`

`saveKeyPairRecord`

Step 3: Write `src/stores.ts`

`jwksStore` (JwksKeyStore)

`rotationTimestampStore` (JwksRotationTimestampStore)

Step 4: Update `src/index.ts`

Step 1: Import `getOriginFromRequest`

Step 2: Remove the `ISSUER` constant and loosen `CLIENT.redirectUris`

Step 5: Set the `iss` claim from the grant context

3.2 Extend `UserCredentials`

Wiring up session cookies with `yar`