How It Works

Login Flow (DDISA)

User enters email at SP
        ↓
SP extracts domain → DNS lookup: _ddisa.example.com
        ↓
Discovers IdP URL → Redirects to IdP /authorize
        ↓
User authenticates with Passkey (or Agent via Ed25519)
        ↓
IdP issues authorization code → Redirect back to SP
        ↓
SP exchanges code for signed JWT (backchannel)
        ↓
SP validates JWT (issuer, audience, signature, nonce, act)
        ↓
User is logged in ✅

This is a standard Authorization Code + PKCE flow, enhanced with DNS-based IdP discovery and Passkey-only authentication.

Grant Flow (Permissions)

When an agent needs to perform a privileged action:

1. Agent Requests a Grant

POST /api/grants
{
  "requester": "agent@example.com",
  "target": "prod-server",
  "grant_type": "once",
  "permissions": ["deploy"],
  "reason": "Deploy hotfix #123"
}

2. Human Reviews

The agent's owner or designated approver sees the request in the web UI (or via notification) and approves or denies it.

3. Agent Receives AuthZ-JWT

On approval, the agent can request a signed AuthZ-JWT:

{
  "sub": "agent@example.com",
  "act": "agent",
  "aud": "prod-server",
  "grant_type": "once",
  "permissions": ["deploy"],
  "decided_by": "alice@example.com",
  "exp": 1234567890
}

4. Target Verifies

The target system validates the AuthZ-JWT: signature, audience, expiry, permissions, and optionally cmd_hash for exact command binding.

escapes — Privilege Elevation for Agents

escapes is a setuid-root Rust binary that brings the grant flow to local privilege elevation. It receives a pre-approved AuthZ-JWT (typically from grapes) and executes the authorized command.

escapes --grant <jwt> -- systemctl restart nginx

Grant delivery options:

escapes --grant <jwt> -- <command>           # JWT as argument
escapes --grant-stdin -- <command>            # JWT from stdin
escapes --grant-file /path/to/jwt -- <command>  # JWT from file
escapes --run-as <user> --grant <jwt> -- <command>  # Run as specific user

Verification chain:

1. Loads config from /etc/openape/config.toml (root-owned)
2. Verifies the AuthZ-JWT: issuer, signature, approver, audience, target_host, cmd_hash, and IdP consume check
3. Sanitizes environment (LD_PRELOAD, PATH etc.) before execution
4. Executes the command and logs result to /var/log/openape/audit.log (JSONL)

Exit codes: 0 (success), 1 (config/HTTP error), 5 (JWT verification failed), 126 (exec failed), 127 (command not found).

grapes — Grant Management CLI

grapes is the universal CLI for the grant lifecycle. It handles authentication, grant requests, approvals, and integrates with escapes for privilege elevation.

grapes login --idp https://id.openape.at --key ~/.ssh/id_ed25519
grapes request --target "api.github.com" --permissions "write:issues"
grapes run escapes "systemctl restart nginx" --approval once
grapes delegate --to agent@example.com --with "read:repos"

Key commands: login, logout, whoami, request, approve, deny, run, delegate, delegations, list, status, token, revoke.