Getting Started

This guide wires Aegis Guard into a Next.js App Router project.

1. Implement an adapter

The adapter is the only code that touches your database. It answers which roles a user holds and which roles a resource allows.


// lib/aegis-adapter.ts
import type { AegisAdapter } from "aegis-guard/core";
 
export const adapter: AegisAdapter = {
  getUserRoles: async (ctx) => db.getUserRoles(ctx.userId),
  getAllowedRoles: async (resourceKey) => db.getResourceRoles(resourceKey),
  getAllResources: async () => db.getAllResources(),
  setResourcePermissions: async (resourceKey, roles) =>
    db.updateResourceRoles(resourceKey, roles),
  upsertResource: async (resourceKey, description) =>
    db.upsertResource(resourceKey, description),
};

2. Initialize Aegis

Use Next.js instrumentation to initialize once at server startup. The getSecurityContext function resolves the current user for each request.


// instrumentation.ts
export async function register() {
  const { initAegis } = await import("aegis-guard/core");
  const { adapter } = await import("./lib/aegis-adapter");
 
  initAegis({
    adapter,
    getSecurityContext: async () => {
      const { auth } = await import("./lib/auth"); // your auth library
      const session = await auth();
      return { userId: session?.userId ?? null };
    },
  });
}

3. Protect pages with Shield


// app/admin/page.tsx
import { Shield } from "aegis-guard/server";
 
export default function AdminPage() {
  return (
    <Shield resource="admin.page" fallback={<p>Access denied.</p>}>
      <h1>Welcome, admin</h1>
    </Shield>
  );
}

In development, Shield calls adapter.upsertResource() to register the resource automatically. See Shield component.

4. Guard API routes


// app/api/secret/route.ts
import { checkPermission } from "aegis-guard/server";
 
export async function GET() {
  if (!(await checkPermission("api.secret"))) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }
  return Response.json({ data: "secret" });
}

For the explainable decision or a throwing variant, see Universal guard.

5. Add the admin API and dashboard


// app/api/aegis/route.ts
import { createAegisHandler } from "aegis-guard/server";
 
export const { GET, POST } = createAegisHandler();


// app/admin/permissions/page.tsx
import { AegisDashboardStyled } from "aegis-guard/client";
 
export default function PermissionsPage() {
  return <AegisDashboardStyled roles={["admin", "editor", "viewer"]} />;
}

6. Gate routes with middleware (optional)


// middleware.ts
import { createAegisMiddleware } from "aegis-guard/server";
 
export const middleware = createAegisMiddleware({
  rules: [
    { matcher: "/admin/*", resource: "admin.area" },
    { matcher: "/billing", resource: "billing.view" },
  ],
  redirectTo: "/login", // omit to return 403, or pass onDenied for full control
});
 
export const config = {
  matcher: ["/admin/:path*", "/billing"],
};

Next.js middleware runs on the Edge runtime by default, where the config set by initAegis() in instrumentation.ts (Node runtime) is not visible. Either opt the middleware into the Node.js runtime, or call initAegis() with an Edge compatible adapter inside the middleware module.