API Reference

Aegis Guard ships three entry points.

`aegis-guard/core`

Framework free: types, config, the pure engine, and the guard factory.

Export	Description
`initAegis(config)`	Initialize the library with your adapter and auth context
`createGuard(config)`	Build a portable `AegisGuard`. The base for any framework binding
`evaluatePermission(r, c, d)`	Pure decision engine. Explicit context and deps, no globals
`createValidatedAdapter`	Wrap an adapter so its returned data is validated
`AegisAdapter`	Interface your database adapter must implement
`AegisConfig`	Configuration object type
`AegisContext`	User context type (`{ userId, ...custom }`)
`AegisResource`	Resource type (`{ key, description? }`)
`AegisGuard` / `BoundGuard`	The universal guard surface and its per request binder
`AegisDecision`	Explainable result (`allowed`, `reason`, matched/missing roles)
`GuardInput`	Context input union (omit, `{ request }`, or `AegisContext`)
`Validator<T>`	`(data: unknown) => T`. Runtime validator type
`AegisError` / `AegisDeniedError`	Typed config error and denial error (`.decision`)
`AegisValidationError`	Thrown when a validator rejects (`.source`, `.cause`)

`aegis-guard/server`

Next.js specific. Re-exports the core guard functions plus Shield and handlers.

Export	Description
`<Shield>`	Async Server Component that gates content by permission
`checkPermission(resource)`	Returns `boolean`. Use in API routes, middleware, tRPC
`decidePermission(resource)`	Returns the full `AegisDecision` (allowed, reason, roles)
`requirePermission(resource)`	Returns the decision, or throws `AegisDeniedError` on deny
`createAegisHandler()`	Returns `{ GET, POST }` handlers for the admin API
`createAegisMiddleware(options)`	Returns a Next.js middleware that gates routes by permission

`aegis-guard/client`

React specific. Hooks and dashboard components.

Export	Description
`useAegisResources(options?)`	Hook to fetch resources with their roles
`useUpdatePermissions(options?)`	Hook to update resource permissions
`<AegisDashboard>`	Unstyled dashboard with semantic HTML. Bring your own CSS
`<AegisDashboardStyled>`	Tailwind styled dashboard, ready to use

Adapter interface


interface AegisAdapter {
  getUserRoles(ctx: AegisContext): Promise<string[]>;
  getAllowedRoles(resourceKey: string): Promise<string[]>;
  getAllResources(): Promise<AegisResource[]>;
  setResourcePermissions(resourceKey: string, roles: string[]): Promise<void>;
  upsertResource(resourceKey: string, description?: string): Promise<void>;
}

Dashboard props

Prop	Type	Default	Description
`roles`	`string[]`	required	All possible roles in your app
`apiBase`	`string`	`"/api/aegis"`	Base path for the admin API
`className`	`string`		CSS class for the root element
`title`	`string`	`"Aegis Permissions"`	Dashboard heading

Tailwind setup

If using <AegisDashboardStyled>, scan the library’s compiled classes.

Tailwind v4, add to your CSS:


@source "../../node_modules/aegis-guard/dist";

Tailwind v3, add to tailwind.config.js content:


"./node_modules/aegis-guard/dist/**/*.{js,mjs}",