OpenApe Grants

@openape/grants

The permission engine. Framework-agnostic. This package provides the core grant lifecycle, AuthZ-JWT issuance, and verification — independent of any framework.

Grant Lifecycle

Request → Pending → Approved/Denied → (if approved) Active → Used/Expired/Revoked

Grant Types

For timed grants, specify a duration in seconds when requesting. For always grants, the AuthZ-JWT expires after 1 hour but can be re-fetched as long as the grant is not revoked.

AuthZ-JWT

On approval, a signed AuthZ-JWT is issued:

{
  "iss": "https://id.example.com",
  "sub": "agent@example.com",
  "aud": "target-system",
  "target_host": "prod-server.example.com",
  "grant_id": "uuid",
  "grant_type": "once",
  "permissions": ["deploy"],
  "command": ["systemctl", "restart", "nginx"],
  "cmd_hash": "sha256:a1b2c3...",
  "decided_by": "alice@example.com",
  "exp": 1234567890,
  "jti": "unique-grant-id"
}

Key security features:

• aud binding — token only valid for the intended target service
• target_host — restricts to a specific host
• cmd_hash — binds to exact command (prevents substitution attacks)
• decided_by — dual accountability (agent identity ≠ approver identity)
• jti — replay protection
• Expiry — all grants have a maximum lifetime

Grant Request Fields

Grant Routes in @openape/nuxt-auth-idp

Grant management is integrated into @openape/nuxt-auth-idp. Enable grant pages with grants.enablePages: true in your module config.

Auto-registered API routes:

• POST /api/grants — create grant request
• GET /api/grants — list grants
• GET /api/grants/:id — get grant details (supports ETag polling)
• POST /api/grants/:id/approve — approve a grant (returns AuthZ-JWT)
• POST /api/grants/:id/deny — deny a grant
• POST /api/grants/:id/revoke — revoke an active grant
• POST /api/grants/:id/token — get AuthZ-JWT for approved grant
• POST /api/grants/:id/consume — consume a once grant
• POST /api/grants/verify — verify an AuthZ-JWT

Agent API routes:

• POST /api/agent/enroll — register a new agent (requires Management Token)
• POST /api/agent/challenge — request auth challenge
• POST /api/agent/authenticate — authenticate with signed challenge

Pages (overridable, enabled via grants.enablePages: true):

• /grants — grant dashboard
• /grant-approval — approve/deny UI
• /enroll — agent enrollment form

For detailed request/response schemas, see the Agent Integration Guide.

Agent Tools

The following tools use the grant system for access control: