agent-governance

Configure fail-closed identity, authorization, and ownership gates for AdonisJS agent routes.

1|Updated Jul 7, 2026
One-click install
npx skills add https://github.com/DavideCarvalho/adonis-agora-agent --skill agent-governance-davidecarvalho
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-governance
Source: https://github.com/DavideCarvalho/adonis-agora-agent/tree/main/packages/adonis/skills/agent-governance
Command: npx skills add https://github.com/DavideCarvalho/adonis-agora-agent --skill agent-governance-davidecarvalho

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Securing an AI agent's HTTP surface is easy to get wrong: tools leak to unauthorized roles, governance routes expose every actor's data, and header-based identity lets anyone impersonate an admin. This Skill guides you through @adonis-agora/agent's three fail-closed layers — actor identity resolution, role/ability tool authorization, and object-level ownership — so misconfigurations fail safe instead of failing open. ## Core Features & Use Cases - Identity resolution: Wire AuthActorResolver over ctx.auth.user with a toActor mapper, understand why HeaderActorResolver is only safe behind a gateway, and avoid per-agent resolver identity mismatches. - Tool authorization: Apply DefaultToolAuthorizer role intersection at both the offered-tools filter and invoke-time re-check, or swap to ability-based checks via authzToolAuthorizer. - Governance gating: Mount /agent/governance/* routes only behind governanceAuthorize, keep unknown ids answering 404 via evaluateOwnership, and configure the dashboard's shell gate versus data gate correctly. - Use Case: Your /agent/governance/* routes all return 404 after configuring the store — this Skill explains that mounting is conditional on governanceAuthorize and shows the exact config to fix it. ## Quick Start Ask the agent to configure AuthActorResolver and an ADMIN-only governanceAuthorize gate in config/agent.ts so governance routes mount securely.

Frequently Asked Questions about agent-governance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I secure agent tool access by user role in AdonisJS?▼

Configure an ActorResolver to establish identity, then rely on DefaultToolAuthorizer, which intersects the actor's roles with each tool's required roles. The check runs twice: once filtering tools offered to the model and again at invoke time.

Why do my /agent/governance/* routes return 404?▼

The governance read-model routes are only mounted when governanceAuthorize is configured. Setting up the store alone is not enough; add a gate such as an ADMIN role check, or explicitly opt into open reads with a predicate returning true.

Is HeaderActorResolver safe to use in production?▼

No. HeaderActorResolver trusts client-sent x-actor-id and x-actor-role headers, so any caller can impersonate any actor. Use it only behind a gateway that strips and re-sets those headers; otherwise use AuthActorResolver over ctx.auth.user.

How do I swap role checks for ability-based authorization?▼

Replace the authorizer binding with authzToolAuthorizer from @adonis-agora/agent/authz, which consults each tool's ability annotation via the authz Bouncer adapter. Both the offered-tools filter and invoke-time re-check follow the same seam, so they stay consistent.

Why does the governance dashboard refuse to mount?▼

The dashboard is a pure consumer of /agent/governance/* and refuses to mount without governanceAuthorize configured. Its dashboard.authorize option only gates the SPA shell; the data gate must be set separately for panels to work.

Why does ownership return 404 instead of 403 for some ids?▼

evaluateOwnership deliberately returns 404 for unknown ids so a response never confirms that a record the caller does not own exists. Known ids owned by someone else return 403, while owners and privileged actors get 200.