OpenApe Grants

@openape/grants

The permission engine. Framework-agnostic.

Grant Lifecycle

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

Grant Types

AuthZ-JWT

On approval, a signed AuthZ-JWT is issued:

{
  "sub": "agent@example.com",
  "aud": "target-system",
  "grant_type": "once",
  "permissions": ["deploy"],
  "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
• cmd_hash — binds to exact command (prevents substitution attacks)
• decided_by — dual accountability (agent owner ≠ approver)
• jti — replay protection
• Expiry — all grants have a maximum lifetime

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 routes (via nuxt-auth-idp):

• /api/grants — list and create grant requests
• /api/grants/:id — get grant details
• /api/grants/:id/approve — approve a grant
• /api/grants/:id/deny — deny a grant
• /api/grants/:id/revoke — revoke an active grant
• /api/grants/:id/token — issue AuthZ-JWT for approved grant
• /api/grants/verify — verify an AuthZ-JWT
• /api/agent/enroll — register a new agent
• /api/agent/challenge — request auth challenge
• /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

openape-escapes (escapes)

A Rust binary for local privilege elevation via the grant system. Supports multiple agents per machine with user-owned keys.

# Install
cargo build --release
sudo make install  # installs to /usr/local/bin/escapes with setuid

# Enroll an agent (key is generated if it doesn't exist)
sudo escapes enroll \
  --server https://id.example.com \
  --agent-email deploy@example.com \
  --agent-name web-deploy \
  --key /etc/openape/agent.key

# Use (--grant identifies the authorization)
escapes --grant <jwt> --reason "Security update" -- apt-get upgrade

Security Model

• Setuid binary — starts as root, drops privileges before loading the user's key
• User-owned keys — private keys belong to the user, stored in user-accessible paths
• Agent matching — public key derived from private key is matched against registered agents in config
• Privileges re-elevated only after valid AuthZ-JWT with matching cmd_hash
• Environment sanitized — LD_PRELOAD, PATH etc. reset before exec
• Audit log — every execution logged as JSONL