@bulwark/nextjs

Next.js integration for Bulwark — middleware, route handlers, and Server Component support.

Installation

npm install @bulwark/nextjs

Setup

1. Environment variables

BULWARK_TENANT_ID=your-tenant-id
BULWARK_API_KEY=bwk_live_...
NEXT_PUBLIC_BULWARK_TENANT_ID=your-tenant-id
BULWARK_BASE_URL=https://api.bulwarkauth.io

2. Middleware

// middleware.ts
import { bulwarkMiddleware } from "@bulwark/nextjs/middleware";

export default bulwarkMiddleware({
  publicRoutes: ["/", "/login", "/api/auth/(.*)"],
});

export const config = {
  matcher: ["/((?!_next|static|favicon.ico).*)"],
};

3. Route handler

// app/api/auth/[...bulwark]/route.ts
import { bulwarkHandler } from "@bulwark/nextjs";

export const { GET, POST } = bulwarkHandler();

Server Components

import { getSession } from "@bulwark/nextjs/server";

export default async function Dashboard() {
  const session = await getSession();

  if (!session) {
    redirect("/login");
  }

  return <div>Hello, {session.user.name}</div>;
}

Client Components

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

export default function Header() {
  const { user, logout } = useAuth();
  return <button onClick={logout}>{user?.email}</button>;
}

Route Protection

Protect a page

// app/dashboard/page.tsx
import { requireAuth } from "@bulwark/nextjs/server";

export default async function Dashboard() {
  const { user } = await requireAuth(); // throws if not authenticated
  return <div>Welcome {user.name}</div>;
}

API route protection

// app/api/protected/route.ts
import { withAuth } from "@bulwark/nextjs/api";

export const GET = withAuth(async (req, { user }) => {
  return Response.json({ userId: user.id });
});

Agent Sessions in Server Actions

"use server";
import { createAgentSession } from "@bulwark/nextjs/server";

export async function runAgentTask(agentId: string) {
  const session = await createAgentSession({
    agentId,
    requestedScopes: ["read:data"],
  });

  // Use session.credentialToken in your agent
  return session;
}