Forem: ShyGyver

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.

Generate documentation with @novice1/api-doc-generator: Part 1

ShyGyver — Wed, 03 Jan 2024 00:26:50 +0000

In the previous articles, we went through:

how to create a Rest API with @novice1/app
how to validate request data with @novice1/validator-joi

Now we wish to use the API for ourself or give an access for other people to use. For that we are missing something of fundamental importance: documentation.

Let us be real, during my years as a developer, I never met anyone who liked writing documentation. That does not mean that it's not necessary to do so.
For a REST API, a schema of the API can be very useful and self explanatory. There are multiple schema specifications like OpenAPI and Postman. @novice1/api-doc-generator covers them both.

With @novice1/api-doc-generator, you can easily generate an OpenAPI and/or Postman schema from your application. That package is quite complete, covers all cases and has a reference sheet for its usage.

In this article we will see how to generate an OpenAPI schema with @novice1/api-doc-generator for a simple REST API.

Create the service

Let's install the dependencies

npm i @novice1/api-doc-generator yamljs
npm i --save-dev @types/yamljs

and create the service that will generate the documentation

src/services/openapi/generator.ts

import { OpenAPI } from '@novice1/api-doc-generator';
import { EXTERNAL_PORT, EXTERNAL_PROTOCOL, HOSTNAME } from '../../config/server';

export const openAPIGenerator = new OpenAPI()
    .setTitle('API DOC')
    .setHost(`${EXTERNAL_PROTOCOL}://${HOSTNAME}${EXTERNAL_PORT ? ':'+EXTERNAL_PORT : ''}`)
    .setConsumes(['application/json'])
    .setTags([
        {
            name: 'default',
            externalDocs: { description: 'Find more info here', url: 'https://swagger.io/specification/' }
        }
    ])

Access documentation

Using @novice1/app, the app provides metadata. Those are used to generate the REST API schema.

src/index.ts

import logger from '@novice1/logger';
import { app } from './app';
import { httpError, httpNotFound } from './middlewares/http';
import { PORT } from './config/server';
import { openAPIGenerator } from './services/openapi/generator';

// 404
app.use(httpNotFound);

// error
app.useError(httpError);

// start server
app.listen(PORT, () => {
    logger.info('Application running on port', PORT)

    /**
     * Add app metadata to API documentation generator
     */
    openAPIGenerator.add(app.meta)
})

Create a route that renders the schema:

src/routes/documentation.ts

import routing from '@novice1/routing';
import Joi from 'joi';
import YAML from 'yamljs';
import { openAPIGenerator } from '../services/openapi/generator';

export default routing().get({
    path: '/documentation',
    parameters: {
        // query
        query: Joi.object().keys({
            json: Joi.boolean().default(false)
        }),
        // do not put this route in the documentation 
        undoc: true
    }
}, (req, res) => {
    // Get the JSON schema
    const result = openAPIGenerator.result()

    if (!req.query.json) {
        // respond with a yaml schema
        res.set('Content-Type', 'text/plain')
        res.send(YAML.stringify(result, 10, 2))
    } else {
        // respond with the JSON schema
        res.json(result)
    }
})

And register it with the other routers:

src/routes/index.ts

import corsOptions from './cors-options';
import documentation from './documentation';
import helloWorld from './hello-world';
import items from './items';

// all routers
export default [
    corsOptions,
    documentation,
    helloWorld,
    items
]

Now, we run the application to see if we have access to the schema at http://localhost:8080/documentation.

For development:

npm run dev

For production:

npm run lint
npm run build
npm start

It should render the schema in yaml format. To get the json format, we can set the following query string in the url ?json=true.

The schema can be copied and pasted to the Swagger Editor to get a UI to test your API.

Render swagger UI

If you want your API to not just serve the schema but also the UI, you can install the following dependencies:

npm i swagger-ui-express
npm i --save-dev @types/swagger-ui-express

and change the route that serves the documentation like so:

src/routes/documentation.ts

import routing, { RequestHandler } from '@novice1/routing';
import Joi from 'joi';
import YAML from 'yamljs';
import swaggerUi from 'swagger-ui-express';
import { openAPIGenerator } from '../services/openapi/generator';

const swaggerUIController: RequestHandler = (req, res, next) => {
  const swaggerDocument = openAPIGenerator.result()
  return swaggerUi.setup(swaggerDocument)(req, res, next)
}

const swaggerRouter = routing()
  .get({
    path: '/',
    parameters: {
      undoc: true
    },
  },
  swaggerUIController)
  .get({
    path: '/schema',
    parameters: {
      query: Joi.object().keys({
        json: Joi.boolean().default(false),
      }).options({ allowUnknown: true, stripUnknown: false }),

      undoc: true
    }
  }, (req, res) => {
    const result = openAPIGenerator.result();

    if (!req.query.json) {
      res.set('Content-Type', 'text/plain');
      res.send(YAML.stringify(result, 10, 2));
    } else {
      res.json(result);
    }
  });

export default routing().use('/documentation', 
  swaggerUi.serve, 
  swaggerRouter
);

That way, your API will serve the UI (html) at /documentation and the schema (yaml/json) at /documentation/schema.

As I said earlier, @novice1/api-doc-generator is quite complete. We can define everything there is in OpenAPI Specification 3.0.3 and Postman Collection Format v2.1.0 so it would be impossible to cover it all in one article. As of today, the best way to learn @novice1/api-doc-generator is by reading the package's documentation that you can find here. It lists and defines the classes, interfaces, enumerations and gives a few examples on how to define authorizations, responses, etc ...
I would gladly talk about more aspects of the package in future articles if it is requested in the comment section.
What is sure is that we will continue using and updating our REST API documentation in the next article that will be about Authorizations with @novice1/app.

References

You can see the result of what we have done till now right here on Github.

Validate request data with @novice1/validator-joi

ShyGyver — Sun, 29 Oct 2023 17:03:33 +0000

In the previous post, we learnt how to setup a Rest API with @novice1/app and create routes and services. Now we will see how to respond different status code and validate request data.

Middlewares

First we want to handle http errors with middlewares.
We are going to start by updating our debug service to export a logger for middlewares.

src/services/debug.ts

import logger from '@novice1/logger';

logger.Debug.enable([
    'route*',
    'middleware*'
].join('|'));

export const debugRoute = logger.debugger('route');
export const debugMiddleware = logger.debugger('middleware');

Now let's handle http errors 404 and 500.
First, we create the functions.

src/middlewares/http.ts

import { ErrorRequestHandler, RequestHandler } from 'express'
import { debugMiddleware } from '../services/debug'

export const httpError: ErrorRequestHandler = (err, _req, res, _) => {
    const logger = debugMiddleware.extend('httpError');
    logger.error(err);
    res.status(500).json({message: 'Something went wrong'})
}

export const httpNotFound: RequestHandler = (_req, res) => {
    res.status(404).json({message: 'Not found'});
}

Then we register them to the app server with the methods use and useError (special method to register ErrorRequestHandler).

src/index.ts

import logger from '@novice1/logger';
import { app } from './app';
import { httpError, httpNotFound } from './middlewares/http';

const PORT = process.env.PORT ? parseInt(process.env.PORT) : 8000;

// 404
app.use(httpNotFound);

// error
app.useError(httpError);

// start server
app.listen(PORT, () => {
    logger.info('Application running on port', PORT)
})

We can check that it works by testing the Not Found handler (e.g.: http://localhost:8080/path-that-does-not-exist).

Validate requests

We can validate requests many ways, @novice1/app being as flexible as Express. We will use @novice1/validator-joi, a validator made expressly for @novice1/routing.

We install the dependencies

npm install joi @novice1/validator-joi

and register the validator globaly in the app (it could also be registered by router, see more examples here)

src/app.ts

import { FrameworkApp } from '@novice1/app';
import cookieParser from 'cookie-parser';
import express from 'express';
import cors from 'cors';
import routes from './routes';
import validatorJoi from '@novice1/validator-joi'
import { debugMiddleware } from './services/debug';

// init app
export const app = new FrameworkApp({
    framework: {
        // middlewares for all requests
        middlewares: [
            cookieParser(),
            express.json(),
            express.urlencoded({ extended: true }),
            cors()
        ],
        validators: [validatorJoi(undefined, (err, _req, res) => {
            debugMiddleware.extend('validator-joi').error(err)
            res.status(400).json({message: "bad request"})
        })]
    },
    routers: routes
})

There we:

registered our validator in the property framework.validators
used a custom error request handler to respond with a status code 400 if data aren't valid (see @novice1/validator-joi)

Now all we need are routes to validate.
Below is an example of http CRUD operations:

src/routes/items.ts

import routing from '@novice1/routing'
import { debugRoute, debugMiddleware } from '../services/debug'
import Joi from 'joi';
import { ErrorRequestHandler } from 'express';

const logger = debugRoute.extend('items')

const customErrorHandler: ErrorRequestHandler = (err, _req, res, _) => {
    const log = debugMiddleware.extend('customErrorHandler');
    log.error(err);
    res.status(400).json({message: 'Bad request: could not update an item'})
}

const itemsRouter = routing()
    .get({
        path: '/'
    }, (_, res) => {
        res.json([])
    })
    .post({
        path: '/',
        parameters: {
            body: Joi.object().keys({
                title: Joi.string().required().min(1).max(128),
                description: Joi.string().max(2560).allow(''),
                text: Joi.string().max(5120).allow(''),
                published: Joi.boolean().default(false)
            })
        }
    }, (req, res) => {
        const item = req.body;
        res.json(item);
    });

const itemsIdRouter = routing()
    .get({
        path: '/:id',
        parameters: {
            params: {
                id: Joi.string().required()
            },
        }
    }, (req, res) => {
        res.json({ message: `Got "${req.params.id}"` });
    })
    .put({ 
        path: '/:id',
        parameters: {
            params: {
                id: Joi.string().required()
            },
            body: Joi.object().keys({
                title: Joi.string().min(1).max(128),
                description: Joi.string().max(2560).allow(''),
                text: Joi.string().max(5120).allow(''),
                published: Joi.boolean()
            }).min(1),
            onerror: customErrorHandler
        }
    }, (req, res) => {
        const item = req.body;
        item.id = req.params.id;
        res.json(item);
    })
    .delete({
        path: '/:id',
        parameters: {
            params: {
                id: Joi.string().required()
            },
        }
    }, (req, res) => {
        res.json({ id: req.params.id });
    })

export default routing().use('/items', (req, _res, next) => {
    logger.debug(`${req.method} ${req.originalUrl}`)
    next()
}, itemsRouter, itemsIdRouter);

There we:

defined routers for the path /items
configured path and parameters for each route

We use the joi package to write the properties' schema that will be validated by our validator (so some knowledge of joi is required).

@novice1/validator-joi can validate the properties params, body, query, headers, cookies, and files (useful when using multer) from the request.

For one route, we defined an Error Request Handler (customErrorHandler) in the parameter onerror. It is useful if we want to do something specific when a validation error happens on that route.

Note: As you can see, we didn't make any operation to a database as it is not the purpose of the example but you can complete the controllers as you wish.

Finally, let's register the new router

src/routes/index.ts

import corsOptions from './cors-options';
import helloWorld from './hello-world';
import items from './items';

// all routers
export default [
    corsOptions,
    helloWorld,
    items
]

Now we can run the application and try our different routes (with a tool like Postman for example) and send invalid data to see if our validator is working and responds with a status code 400.

For development:

npm run dev

For production:

npm run lint
npm run build
npm start

References

You can see the result of what we have done till now right here on Github.

NodeJS Rest API with @novice1/app

ShyGyver — Mon, 11 Sep 2023 20:01:23 +0000

Yet another Node.js library based on Express. What could make you want to use @novice1/app?
I'm glad you asked.

@novice1/app is as fast and minimalist as Express with new functionalities and its own plugins that give a purpose to its existence.

Through this article and those to come, I'm going to show how it can be used to build small/mid-size Rest APIs, validate data, integrate websockets into your server, generate documentation for Swagger UI and/or Postman, etc ...

Setup

First we initialize a project by running the command in the terminal

npm init

and install the dependencies

npm install --save-dev @types/cookie-parser @types/cors @types/node @typescript-eslint/eslint-plugin @typescript-eslint/parser dotenv eslint ts-node typescript
npm install @novice1/app @novice1/logger @novice1/routing cookie-parser cors express nodemon tslib

Once done, we can add the following scripts in the file package.json that was created with npm init:

{
    "scripts": {
        "build": "tsc",
        "dev": "nodemon",
        "lint": "eslint src/**/*.ts",
        "start": "node lib/index.js"
    }
}

To use those scripts we have to configure eslint, nodemon and typescript. Here is what I recommend as configuration files at the root of the project (feel free to add more options):

.eslintrc.json

{
    "env": {
        "browser": true,
        "es6": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "ecmaVersion": 6,
        "sourceType": "module"
    },
    "plugins": [
        "@typescript-eslint"
    ],
    "rules": {
        "quotes": [1, "single"],
        "quote-props": [1, "as-needed"]
    }
}

nodemon.json

{
    "watch": [
        "src"
    ],
    "ext": "ts,json",
    "ignore": [
        "src/**/*.spec.ts"
    ],
    "exec": "ts-node -r dotenv/config ./src/index.ts"
}

tsconfig.json

{
    // see https://www.typescriptlang.org/tsconfig
    "include": ["src"],
    "exclude": ["node_modules"],
    "compilerOptions": {
      "typeRoots": ["node_modules/@types"],
      "module": "CommonJS",
      "lib": ["DOM", "ES6"],
      "target": "ES6",
      "importHelpers": true,
      "declaration": true,
      "sourceMap": true,
      "outDir": "./lib",
      "rootDir": "./src",
      "strict": true,
      "noImplicitReturns": true,
      "noFallthroughCasesInSwitch": true,
      "noUnusedLocals": true,
      "noUnusedParameters": true,
      "moduleResolution": "node",
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true
    }
  }

Now that we are done with the "basic" setup, we can start programming the application.

First application

Let's program our services, routes and http server.

Services

To help the development process, we need a debugging utility.

src/services/debug.ts

import logger from '@novice1/logger';

logger.Debug.enable([
    'route*'
].join('|'));

export const debugRoute = logger.debugger('route');

There, we enable all namespaces starting with 'route' (route*) and create the debugger debugRoute in namespace 'route'. That way, we know that everything that debugRoute will log will be displayed.

Routes

Our first route, for testing purposes, will simply render "Hello World!" or "Hello <name>!", <name> being the value of the url variable name.

src/routes/hello-world.ts

import routing from '@novice1/routing';
import { debugRoute } from '../services/debug';

// hello-world
export default routing().get({
    path: '/hello-world'
}, (req, res) => {
    debugRoute.extend('hello-world').debug(req.path);
    res.json(`Hello ${req.query.name || 'World'}!`);
})

Our second route is optional. It will enable pre-flight request for all requests.

src/routes/cors-options.ts

import cors from 'cors';
import routing from '@novice1/routing';

// enable CORS (Cross-origin resource sharing) pre-flight request
export default routing().options({
    path: '*'
}, cors())

From that we simply allow cross-origin resource sharing pre-flight without restrictions.

Then we export all routers from one module.

src/routes/index.ts

import corsOptions from './cors-options';
import helloWorld from './hello-world';

// all routers
export default [
    corsOptions,
    helloWorld
]

Server

We can now use @novice1/app to register middlewares and routes.

src/app.ts

import { FrameworkApp } from '@novice1/app';
import cookieParser from 'cookie-parser';
import express from 'express';
import cors from 'cors';
import routes from './routes';

// init app
export const app = new FrameworkApp({
    framework: {
        // middlewares for all requests
        middlewares: [
            cookieParser(),
            express.json(),
            express.urlencoded({ extended: true }),
            cors()
        ]
    },
    routers: routes
})

And run the server on a specific port:

src/index.ts

import logger from '@novice1/logger';
import { app } from './app';

const PORT = process.env.PORT ? parseInt(process.env.PORT) : 8000;

// start server
app.listen(PORT, () => {
    logger.info('Application running on port', PORT)
})

Run the application

Development

To start the server in development mode, we add environment variables in the file .env.

.env

PORT=8080

This will set the environment variable PORT to 8080 when using the dependency dotenv (see nodemon.json file).

Then we can start the server with the following command in the terminal:

npm run dev

You should see something like that in your console:

[nodemon] starting `ts-node -r dotenv/config ./src/index.ts`
info : Application running on port 8080

Open your favorite browser and go to http://localhost:8080/hello-world or http://localhost:8080/hello-world?name=stranger to see the result.

Production

In a production environment, you should check, build and start the server as:

npm run lint
npm run build
npm start

What now?

So we have a REST API but really nothing out of what Express can already do. In the next article, we will see how to use @novice1/validator-joi to validate request data and give a better structure to our project.

References

You can see the result of what we have done till now right here on Github.

Forem: ShyGyver

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

Generate access and ID tokens

Verify access tokens

Handle authorization failures

3.6 Create the Hono app and register routes

3.7 Key rotation and login form

Step 4: Run the server

Protecting a separate resource server

What's next

Building Modern Backends with Kaapi: Messaging with Kafka

Messaging?

Kafka: the elephant in the room

Setting up Kafka locally

The scenario

The User API

Plugging into Kaapi's lifecycle

The Notification Service

What's happening under the hood

When things go wrong

Consumer groups: who gets what

Shutting down gracefully

What we didn't cover (on purpose)

Wrapping up

Source Code

Building Modern Backends with Kaapi: Request validation Part 2

Validation… again?

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

Joi: the familiar path

Zod: validation that talks to TypeScript

Valibot: same idea, different flavor

ArkType: schemas you can read

What actually matters here

So… which validator should you use?

Source code

Building Modern Backends with Kaapi: Authorization

Authorization?

Auth Designs: Kaapi’s way of thinking about auth

Bearer tokens: the “hello world” of APIs

Basic auth: boring, but sometimes perfect

API keys: headers, queries, cookies

Rolling our own: a cookie-based session Auth Design

A tiny fake database

Wiring up session cookies with yar

HTML without a template engine (on purpose)

Building the Auth Design itself

Validating the session

Plugging everything into the app

Wrapping up

Source Code

Building Modern Backends with Kaapi: Request validation

Validation?

So why are we still writing generic type arguments?

Integrating Validators

Validate with Zod

Validate with Valibot

Validate with ArkType

A Real Example: Binomial Coefficients!

Zod Version

Valibot Version

ArkType Version

3.2 Extend `UserCredentials`

Wiring up session cookies with `yar`