warden

Warden — Composable permissions & authorization engine

Warden is a composable authorization engine supporting RBAC, ABAC, and ReBAC in a single unified API. It answers "are you allowed to do this?" and integrates natively with the Forge ecosystem.

Features

• RBAC — Roles, permissions, role inheritance, resource-scoped assignments
• ABAC — Attribute-based policies with conditions (IP ranges, time windows, regex, etc.)
• ReBAC — Zanzibar-style relation tuples with BFS graph walking
• Multi-model — Use RBAC, ABAC, and ReBAC together; explicit deny > allow > default deny
• Multi-tenant — All data is tenant-scoped via forge.Scope or standalone context helpers
• Extensible — Plugin hooks for audit logging, metrics, and custom lifecycle events
• Caching — Built-in in-memory LRU cache with TTL and per-tenant/subject invalidation
• Forge native — Drop-in Forge extension with DI, API routes, and middleware

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/xraph/warden"
    "github.com/xraph/warden/assignment"
    "github.com/xraph/warden/id"
    "github.com/xraph/warden/permission"
    "github.com/xraph/warden/role"
    "github.com/xraph/warden/store/memory"
)

func main() {
    ctx := warden.WithTenant(context.Background(), "myapp", "tenant-1")
    s := memory.New()

    eng, err := warden.NewEngine(warden.WithStore(s))
    if err != nil {
        log.Fatal(err)
    }

    // Create role + permission.
    roleID := id.NewRoleID()
    _ = s.CreateRole(ctx, &role.Role{ID: roleID, TenantID: "tenant-1", Name: "editor", Slug: "editor"})
    _ = s.CreatePermission(ctx, &permission.Permission{ID: id.NewPermissionID(), TenantID: "tenant-1", Name: "doc:read", Resource: "doc", Action: "read"})
    _ = s.AttachPermission(ctx, "tenant-1", roleID, permission.Ref{Name: "doc:read"})

    // Assign role to user.
    _ = s.CreateAssignment(ctx, &assignment.Assignment{
        ID: id.NewAssignmentID(), TenantID: "tenant-1",
        RoleID: roleID, SubjectKind: "user", SubjectID: "alice",
    })

    // Check authorization.
    result, err := eng.Check(ctx, &warden.CheckRequest{
        Subject:  warden.Subject{Kind: warden.SubjectUser, ID: "alice"},
        Action:   warden.Action{Name: "read"},
        Resource: warden.Resource{Type: "doc", ID: "d1"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Allowed: %v\n", result.Allowed) // true
}

Installation

Library

go get github.com/xraph/warden

CLI (warden and warden-lsp)

Using go install — recommended if you have a Go toolchain:

go install github.com/xraph/warden/cmd/warden@latest
go install github.com/xraph/warden/cmd/warden-lsp@latest

Pre-built binaries — multi-platform archives (linux / darwin / windows × amd64 / arm64) are attached to every GitHub Release. Each archive contains both warden and warden-lsp.

# Pick a platform from https://github.com/xraph/warden/releases/latest
curl -L -o warden.tar.gz \
  https://github.com/xraph/warden/releases/latest/download/warden-<version>-<os>-<arch>.tar.gz

# Verify the checksum
curl -L -o checksums.txt \
  https://github.com/xraph/warden/releases/latest/download/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing

tar -xzf warden.tar.gz
sudo mv warden warden-lsp /usr/local/bin/
warden version

VS Code extension

code --install-extension xraph.vscode-warden

Or search for "Warden" in the Extensions panel. See editor/vscode-warden/README.md for a walkthrough.

Architecture

Check Request
     |
     v
+----------+     +---------+     +---------+
|   RBAC   | --> |  ReBAC  | --> |  ABAC   |
| roles &  |     | relation|     | policy  |
| perms    |     | tuples  |     | engine  |
+----------+     +---------+     +---------+
     |                |               |
     +-------+--------+-------+------+
             |                 |
       mergeDecisions    explicit deny
             |            > allow
             v            > default deny
       CheckResult

The engine evaluates all three models and merges results:

1. Explicit deny (from ABAC) always wins
2. Any allow from any model grants access
3. Default deny if no rules match

Authorization Models

RBAC (Role-Based Access Control)

Roles contain permissions. Users are assigned roles (globally or scoped to specific resources). Roles support inheritance via parent chains.

ReBAC (Relationship-Based Access Control)

Zanzibar-style relation tuples (object#relation@subject) with BFS graph walking for transitive permissions. Subject sets enable hierarchical access (e.g., folder membership granting document access).

ABAC (Attribute-Based Access Control)

Policies with conditions evaluate against subject attributes, resource attributes, and request context. Supported operators: eq, neq, in, not_in, contains, starts_with, gt, lt, ip_in_cidr, time_after, time_before, regex, and more.

Store Backends

Warden ships with four pluggable store backends. All implement the composite Store interface from store/store.go.

import "github.com/xraph/warden/store/memory"
import "github.com/xraph/warden/store/postgres"
import "github.com/xraph/warden/store/sqlite"
import "github.com/xraph/warden/store/mongo"

// Memory (no config needed)
s := memory.New()

// PostgreSQL / SQLite — pass a Grove database instance
s := postgres.New(groveDB)

// MongoDB — pass a Grove MongoDB instance
s := mongo.New(mongoDB)

// All stores support Migrate() for schema setup
_ = s.Migrate(ctx)

Plugin System

Warden provides a granular plugin system with 19 lifecycle hooks. Plugins implement the base plugin.Plugin interface (just Name() string) and opt in to specific hooks by implementing additional interfaces. Every hook takes a context.Context first and returns an error; request/result values that would otherwise require importing the root warden package (e.g. *warden.CheckRequest) are typed any to avoid an import cycle.

import "github.com/xraph/warden/plugin"

type AuditPlugin struct{}

func (p *AuditPlugin) Name() string { return "audit" }

// Opt in to the hooks you care about:
func (p *AuditPlugin) OnRoleCreated(ctx context.Context, r *role.Role) error {
    log.Printf("role created: %s", r.Name)
    return nil
}
func (p *AuditPlugin) OnAfterCheck(ctx context.Context, req, result any) error {
    log.Printf("check completed")
    return nil
}

The in-tree plugin/auditlog package implements Audit and logs one structured line per mutation; the Forge extension registers it by default (auth.audit_log: true).

Available Hooks

Hook errors and panics are logged, counted against warden_hook_errors_total{hook,plugin}, and never block the caller. See Plugin System for the full interface definitions.

Caching

Warden includes a built-in in-memory LRU cache for Check() results with TTL-based expiration and scoped invalidation.

import "github.com/xraph/warden/cache"

c := cache.NewMemory(
    cache.WithTTL(5 * time.Minute),   // Default: 5m
    cache.WithMaxSize(10000),          // Default: 10,000 entries
)

eng, _ := warden.NewEngine(
    warden.WithStore(s),
    warden.WithCache(c),
)

Cache keys are scoped by tenantID:subjectKind:subjectID:action:resourceType:resourceID.

Invalidation

// Invalidate all cached results for a tenant.
c.InvalidateTenant(ctx, "tenant-1")

// Invalidate all cached results for a specific subject.
c.InvalidateSubject(ctx, "tenant-1", warden.SubjectUser, "alice")

The cache automatically invalidates when roles, permissions, or assignments are modified through the engine.

Middleware

Warden provides HTTP middleware for Forge route protection.

import wardenmw "github.com/xraph/warden/middleware"

// Require a single permission — returns 403 if denied.
router.GET("/documents/:id", handler,
    forge.WithMiddleware(wardenmw.Require(eng, "read", "document")),
)

// RequireAny — allows if ANY check passes (OR logic).
router.POST("/admin/action", handler,
    forge.WithMiddleware(wardenmw.RequireAny(eng, []warden.CheckRequest{
        {Action: warden.Action{Name: "admin"}, Resource: warden.Resource{Type: "system"}},
        {Action: warden.Action{Name: "write"}, Resource: warden.Resource{Type: "config"}},
    })),
)

// RequireAll — allows only if ALL checks pass (AND logic).
router.DELETE("/documents/:id", handler,
    forge.WithMiddleware(wardenmw.RequireAll(eng, []warden.CheckRequest{
        {Action: warden.Action{Name: "delete"}, Resource: warden.Resource{Type: "document"}},
        {Action: warden.Action{Name: "admin"}, Resource: warden.Resource{Type: "document"}},
    })),
)

Subject resolution:

1. forge.UserIDFromContext() resolves to warden.Subject{Kind: warden.SubjectUser, ID: userID}.
2. No resolved user ID: 401 Unauthorized, unless wardenmw.AllowAnonymous() was passed, in which case the request runs as the fixed subject {Kind: warden.SubjectUser, ID: "anonymous"}.

There's no API-key branch yet: Forge doesn't currently expose one in context, so an API-key-only caller resolves as "no identity" here. See Middleware for WithContext and the 401/403/503 response semantics.

Configuration

eng, err := warden.NewEngine(
    warden.WithStore(store),                  // Required: store backend
    warden.WithCache(cache),                  // Optional: check result cache
    warden.WithConfig(warden.Config{
        MaxGraphDepth: 10,                    // ReBAC graph traversal depth (default: 10)
        CacheTTL:      5 * time.Minute,       // Check result cache TTL (0 = disabled)
        // EnableRBAC, EnableABAC, EnableReBAC are *bool; nil (the zero
        // value) means "default true". Take the address of a local
        // variable to turn one off: see docs/authorization/check-engine.mdx.
    }),
    warden.WithPlugin(auditPlugin),           // Optional: lifecycle plugins
    warden.WithEvaluator(customEvaluator),    // Optional: custom ABAC evaluator
    warden.WithGraphWalker(customWalker),     // Optional: custom ReBAC graph walker
    warden.WithLogger(logger),                // Optional: structured logger
)

ID System

Warden uses TypeID — UUIDv7-based, K-sortable, URL-safe identifiers with type prefixes for all entities.

role_01h2xcejqtf2nbrexx3vqjhp41
perm_01h2xcejqtf2nbrexx3vqjhp41
asgn_01h2xcejqtf2nbrexx3vqjhp41

Prefixes

import "github.com/xraph/warden/id"

// Create
roleID := id.NewRoleID()       // role_01h2xce...
permID := id.NewPermissionID() // perm_01h2xce...

// Parse
parsed, err := id.ParseRoleID("role_01h2xcejqtf2nbrexx3vqjhp41")

// Check
if roleID.IsNil() { /* zero-value */ }

// Database support: SQL (Value/Scan), BSON (MarshalBSONValue/UnmarshalBSONValue)

Forge Integration

import (
    "github.com/xraph/forge"
    wardenext "github.com/xraph/warden/extension"
    wardenmw "github.com/xraph/warden/middleware"
)

// Register as Forge extension.
app := forge.New(
    forge.WithExtensions(
        wardenext.New(
            wardenext.WithStore(store),
        ),
    ),
)

// Use middleware for route protection.
router.GET("/documents/:id", handler,
    forge.WithMiddleware(wardenmw.Require(eng, "read", "document")),
)

Examples

See the _examples/ directory:

• _examples/standalone/ — Warden without Forge
• _examples/forge/ — Warden as Forge extension
• _examples/rbac/ — Pure RBAC with role inheritance
• _examples/rebac/ — Zanzibar-style ReBAC
• _examples/abac/ — Attribute-based policies

License

Part of the Forge ecosystem.