legant

Legant

Open-source delegated authorization for AI agents. Legant lets an AI agent act on behalf of a user with authority you can scope, time-box, revoke, and audit. It's written in Go and ships as a single self-hostable binary.

_{make demo-driftstop — the same stolen-token replay that hit ~700 orgs, against a Legant token: no bulk export, no secret-bearing records, no audience pivot, minutes of life, and a one-entry offline kill. The theft still happens; the blast radius is what changes.}

Website and live demos: https://legant-dev.github.io/legant/ · Releases: https://github.com/legant-dev/legant/releases

New here? Bound your first agent in a few minutes (no database), or jump to: what it is · try a demo · quick start · documentation.

What makes Legant different

A plain OIDC/OAuth server (Keycloak, Ory, Zitadel) can authenticate an agent and hand it a token. It cannot express "this agent may act for Alice, but only to submit travel/meal expenses under $500 for the next hour, and any sub-agent it spawns can only ever do less." Legant's core is exactly that:

• RFC 8693 token exchange → composite sub/act tokens. The agent acts on behalf of the user (sub = user, act = the agent chain), never as the user. The full delegation provenance (user → agent → sub-agent) is recorded in the token.
• Constraint policy enforced offline. Fine-grained limits (max amount, categories, tools, resource audiences, and time-of-day/weekday windows) ride inside the signed token, so a resource server enforces them from the token alone — no callback to Legant. A rolling-hour rate cap is enforced by Legant at mint time (it needs shared state a resource server lacks).
• Monotonic attenuation. Authority can only ever narrow as it is re-delegated down a chain: a child that asks for a broader scope is rejected, and a looser constraint (a bigger amount, an extra category) is clamped down to the parent's.

The canonical engine for this lives in internal/delegation (pure, unit-tested) and there's a runnable, no-database demo in examples/agent-obo (make demo) that shows the whole flow end to end. On top of this, Legant is a full OAuth 2.1 / OpenID Connect provider (authorization code + PKCE, client credentials, refresh, discovery, JWKS, introspection, revocation) with multi-tenancy, SSO, and SCIM as the substrate.

Try it — the demo gallery

The fastest way to understand Legant is to run a demo. Each is a narrated, self-contained walkthrough; the ones below need only Go (no database, no Docker) unless noted. Clone the repo and:

make demo            # agent-on-behalf-of: the whole delegation flow, end to end
make demo-twoasks    # confused deputy closed — one shared agent, two humans, audit names the human
make demo-splice     # multi-hop attenuation: a sub-agent can only ever do LESS than its parent
make demo-driftstop  # replays the Salesloft–Drift / UNC6395 OAuth theft on a survivable token
make demo-foureyes   # segregation of duties: "execute" needs a second distinct human
make demo-blastdoor  # k8s MCP gateway: filtered tools/list, change-freeze, mid-loop kill
make demo-conductor  # one agent across an MCP fleet + a tamper-evident flight recorder
make demo-leash · demo-charter · demo-honeytool · demo-helpdesk · demo-cloudops · demo-gateway

Enterprise, production-integrated demos (real infrastructure — under examples/enterprise/):

make demo-aisre      # AI-SRE on a REAL kind cluster + REAL mcp-server-kubernetes, guarded by Legant
make demo-breach     # the Salesloft–Drift OAuth theft replayed on the shipped RS middleware
make demo-copilot    # entitlement-preserving analytics copilot over a REAL Postgres warehouse

Landing page & visual demos: site/ is a build-free static site (open site/index.html or deploy to any static host) with a landing page, a revocation deep-dive, and live in-browser replays of conductor, leash, charter, and honeytool.

Status

Built and tested against Postgres (go test -race ./...).

Endpoints: /oauth2/{authorize,token,revoke,introspect,userinfo,register}, /consent/delegate, /delegations/redelegate, /account/delegations, /admin/audit, /admin/live{,/snapshot,/events,/ingest}, /.well-known/{openid-configuration,oauth-authorization-server,jwks.json,revoked}, /metrics, /healthz, /readyz, and (gateway mode) /mcp/{slug}.

CLI: legant serve | gateway | init grants|resource-server | lint | apply | mint | show | revoke | who-can | snippet <framework> | guard install|uninstall|check|demo|mint|revoke|show|deny|allow|rules|ui | migrate up|down|version | keys list|rotate|prune|reencrypt | maintenance prune | audit verify|anchor | admin grant-superadmin | dcr issue-token.

Deployment & roles — who runs what

Legant is an authorization server (like Keycloak, Ory, or Auth0), so it's deployed the same way: one component is stateful infrastructure, and the rest just talk to it. There isn't a single "integration" — there are roles, and only one of them runs a server:

To integrate with Legant you need only the Go SDK (verify a token against the issuer's published JWKS — no Postgres, no server). Postgres is only for the issuer — the one component that holds signing keys, sessions, the revocation state, and the audit chain — and even then the bundled docker compose brings its own, so there's no manual install.

  user ──delegates──▶  ISSUER (legant serve + Postgres)  ──JWKS──▶  RESOURCE SERVER (your API)
                              ▲   mints short-lived                    verifies OFFLINE with the SDK
        AI agent ──exchange──┘   "acting-for-Alice" token             (no callback to the issuer)

Self-hosted. You run the issuer in your own infrastructure (Docker, Kubernetes — see deployments/); nothing leaves your environment.

Quick Start

Three ways in, by what you want to do. The first two need only Go: no database, no Docker. The full, end-to-end walkthrough is docs/GETTING_STARTED.md.

Install the CLI

# macOS / Linux — download the latest release binary
curl -fsSL https://raw.githubusercontent.com/legant-dev/legant/main/install.sh | sh

# or with Go
go install github.com/legant-dev/legant/cmd/legant@latest

A. Define and inspect authority (no database)

Declare what an agent may do in a reviewable legant.grants.yaml, mint the signed tokens locally, and ask who can do what. All offline.

legant init grants                          # writes a commented starter
legant lint  -f legant.grants.yaml          # validate (CI-gateable)
legant apply -f legant.grants.yaml          # mints signed tokens into .legant/ (no Postgres)
legant who-can -f legant.grants.yaml --scope warehouse:query --resource finance

Every field is documented in docs/GRANTS.md.

B. Protect your own API (no database)

Verify and authorize those tokens at your own resource server, offline, with the SDK. The whole loop (define, mint, enforce, revoke) runs in one command:

make demo-protect      # see examples/protect-your-endpoint

Walk it step by step in docs/GETTING_STARTED.md, or generate a starter for your framework: legant init resource-server --framework go-chi (also express, fastify, fastapi, flask, go-nethttp, mcp-go).

C. Govern a coding agent

legant guard install wires a PreToolUse hook into Claude Code, Codex, or opencode that authorizes every tool call against a delegation token, offline. This is one adapter on top of the same engine, not the whole product.

legant guard install     # see docs/CLAUDE_CODE.md
legant guard demo        # see it work, no setup

Run the issuer (only for live token exchange)

Lanes A and B need no server. To have agents fetch tokens from a running issuer via RFC 8693 (see docs/AGENT_AUTHOR.md), run legant serve. It needs Go 1.26+ and PostgreSQL 16+; the bundled compose brings its own:

docker compose -f deployments/docker-compose.yml up -d    # issuer at http://localhost:8080

Or run it manually:

export LEGANT_DATABASE_URL="postgres://legant:legant@localhost:5432/legant?sslmode=disable"
export LEGANT_SECRETS_SYSTEM="your-32-byte-or-longer-random-secret"
export LEGANT_SECRETS_COOKIE="another-32-byte-or-longer-random-secret"
export LEGANT_ISSUER_URL="http://localhost:8080"
make build && ./bin/legant serve

Container image: ghcr.io/legant-dev/legant:latest. Releases are cut by pushing a v* tag (see .goreleaser.yaml).

Documentation

• Getting started — bound your first agent end to end, no database.
• Core concepts — sub/act tokens, attenuation, offline verification, revocation tiers.
• Grants reference — every field of legant.grants.yaml.
• Agent author guide — fetch a token from the issuer via RFC 8693.
• Gateway guide — front an MCP server you do not control.
• Coding-agent guard — govern Claude Code / Codex / opencode.
• Revocation and threat model — the honest design.

API Overview

OIDC Endpoints

Admin API

Configuration

Legant is configured via environment variables (prefix LEGANT_), config file (legant.yaml), or CLI flags.

Signing keys

Signing keys are persisted in the database (private keys envelope-encrypted), so tokens survive restarts and replicas sign consistently. Manage them with the CLI:

legant keys list                      # show keys and which is active
legant keys rotate                    # mint a new active key (old one stays published during the overlap window)
legant keys prune                     # deactivate keys whose overlap window has passed
legant keys reencrypt --new-secret …  # re-wrap all keys under a new key-encryption secret

A rotated-out key stays in the JWKS for the overlap window so tokens it already signed keep verifying. A running server (and the gateway) picks up a new active key live, without a restart: each process reloads the keystore on SIGHUP and on a 5-minute ticker, so a legant keys rotate in another process propagates on its own. Concurrent cold-start replicas converge on a single first key.

Resource-server SDKs (Go · TypeScript · Python)

Any service that accepts Legant delegation tokens can verify and authorize them offline — RS256 + kid + iss + aud + exp (requiring an act chain), the full constraint PDP, and the Tier-B revocation feed — with no callback to Legant. Three SDKs implement the identical behavior:

• Go — sdk: go get github.com/legant-dev/legant/sdk (only depends on golang-jwt). Docs on pkg.go.dev.
• TypeScript / Node — clients/typescript: npm i @legant/sdk (zero runtime deps; built-in crypto).
• Python — clients/python: pip install legant-sdk (only depends on cryptography).

They cannot silently drift: golden conformance vectors minted by the real Go signer (clients/conformance) are run against all three. The Go usage:

keys, _ := sdk.FetchJWKS(ctx, "https://auth.example.com/.well-known/jwks.json")
v := sdk.NewVerifier("https://auth.example.com", "https://my-api.example/", keys)

claims, err := v.Verify(bearerToken) // RS256 + kid + iss + aud + exp, requires an act chain
if err != nil { /* 401 */ }
if err := claims.Authorize(sdk.Action{Scope: "expenses:submit", Amount: 120, Category: "travel"}); err != nil {
    /* 403 — scope or constraint denied */
}
log.Printf("acting for %s", claims.Provenance()) // "user:alice -> agent:assistant"

The TypeScript and Python SDKs offer the same API shape (fetchJWKS → Verifier.verify → claims.authorize/provenance, plus fetchRevocationFeed); see clients/ for per-language usage.

You don't have to wire it by hand. Each SDK ships middleware, and the CLI prints a ready-to-paste integration for your framework:

legant snippet go-chi          # also: go-nethttp · express · fastify · fastapi · flask · mcp-go
legant init resource-server --framework fastapi --issuer https://auth.example.com

// Go (net/http + chi): verify + authorize in a couple of lines
r.Use(sdk.Authenticate(v))                         // verify the bearer, attach Claims
r.With(sdk.RequireAction(func(req *http.Request) sdk.Action {
    return sdk.Action{Scope: "warehouse:query", Resource: req.URL.Query().Get("schema")}
})).Get("/query", handler)

The middleware is the delegation-aware analog of a generic OIDC JWT middleware — it understands the act chain, the constraint dimensions, RFC 8707 audience canonicalization, and the signed revocation feed, which a plain access-token middleware doesn't. Equivalents ship for Express/Fastify and FastAPI/Flask.

Authority as reviewable config

Authority doesn't have to be minted from shell history. Declare it in a legant.grants.yaml, code-review it in a PR, and apply it:

legant init grants                          # writes a commented starter
legant lint  -f legant.grants.yaml          # validate: over-broad scopes, bad windows, typos (CI-gateable)
legant apply -f legant.grants.yaml          # idempotent: mints the signed tokens, prints a diff
legant who-can -f legant.grants.yaml --scope warehouse:query --resource finance

It's a fixed serialization of Legant's own constraint dimensions — not a policy DSL — so a grant travels inside the token and verifies offline anywhere.

Revocation, honestly

A signed JWT is valid until it expires — so how fast can you kill one? Legant doesn't pretend a single answer fits every deployment. Each resource server picks a tier, and the worst case is never worse than the token's short TTL (5m by default, configurable — there's no hard ≤5m ceiling):

• Tier A — per-call. The MCP gateway and /oauth2/introspect consult the revocation store on every request, so a revoke takes effect immediately.
• Tier B — signed feed. An offline resource server polls GET /.well-known/revoked — a JWS-signed, TTL-bounded snapshot of revoked, unexpired jtis (signed with the same key as the JWKS, so no new trust root) — and rejects revoked tokens within its refresh interval, with no per-request callback to Legant. The set is bounded by revoke-rate × TTL, so it stays kilobytes; a monotonic version defeats rollback/replay.
• Tier C — TTL only. A fully air-gapped verifier that polls nothing is still bounded by the short token expiry.

Tier B is two lines in the SDK:

feed, _ := sdk.FetchRevocationFeed(ctx, "https://auth.example.com/.well-known/revoked", issuer, keys)
feed.StartPolling(ctx, 10*time.Second, func(err error) { log.Print(err) }) // background refresh
v := sdk.NewVerifier(issuer, "https://my-api.example/", keys, sdk.WithRevocationFeed(feed))
// v.Verify now returns sdk.ErrRevoked for a revoked token, within ~10s of the revoke.

The feed can only ever miss a revocation (then fall back to the TTL), never forge one — so a stale or unreachable feed degrades to Tier C rather than failing a valid token. High-assurance servers can flip that with sdk.WithFeedFailClosed(maxStaleness) to reject when the feed goes stale.

The full design — tier table, endpoint, safety properties, and an explicit list of what is not claimed — is in docs/REVOCATION.md.

Observability

legant serve and legant gateway expose Prometheus metrics at /metrics (text exposition; no client-library dependency):

• legant_http_requests_total{method,route,code} and legant_http_request_duration_seconds — labeled by the route pattern, never the raw path, so cardinality stays bounded.
• legant_delegations_total{kind}, legant_token_exchanges_total{result}, legant_tokens_minted_total{source}, legant_revocations_total{kind}, legant_gateway_calls_total{upstream,decision} — the delegation-activity signals raw HTTP counts can't show, from consent through mint to revocation.
• legant_http_requests_in_flight, Go-runtime gauges, and legant_build_info.

/metrics is unauthenticated by design (scrapers carry no session) — keep it cluster-internal. /healthz is a liveness ping; /readyz also checks the database, an active signing key, and that migrations are applied.

Deployment

The recommended path is the Helm chart at deployments/charts/legant:

helm install legant ./deployments/charts/legant \
  --set issuer=https://auth.example.com --set secrets.existingSecret=legant-secrets

It templates everything below, runs migrations as a pre-install/pre-upgrade hook (so they always complete before rollout), and bundles an optional Grafana dashboard. The raw manifests in deployments/k8s remain a readable reference: server + gateway Deployments (non-root, read-only rootfs, dropped capabilities), a pre-deploy migration Job, an HPA, Prometheus ServiceMonitors, and a nightly data-retention CronJob. See deployments/k8s/README.md for the apply order.

Data retention is a scheduled command:

legant maintenance prune --dry-run                 # report what would be deleted
legant maintenance prune --token-grace 720h        # purge dead tokens > 30d past expiry
legant maintenance prune --audit-retention 8760h   # also purge audit events > 1y (opt-in)

It removes expired sessions, used/expired email and registration tokens, the Fosite OAuth token rows (access/refresh/auth-code/PKCE/OIDC-session — the highest-volume tables), expired agent tokens, and delegation tokens dead beyond the grace window; audit purging is off by default.

Architecture

• Go with chi router — stdlib-compatible, zero-dependency HTTP
• Fosite — Ory's OAuth2/OIDC engine
• PostgreSQL via pgx/v5 — direct driver, no ORM
• Argon2id — OWASP-recommended password hashing
• Single binary — all migrations, templates, and static assets embedded

License

Apache 2.0