[PoC] codex agent authorization hook

[patatoid]

Summary

This PR adds a proof-of-concept Codex hook integration backed by Boruta authorization.

The hook maps Codex lifecycle events and tool usage to Boruta scopes, chains hook events through Boruta authorization codes, and optionally uses browser-based authorization for sensitive actions such as permission requests, file patches, mutating commands, process stdin writes, image generation, and escalated sandbox requests.

What Changed

• Added a local Codex hook command for Boruta-backed authorization.
• Added Codex hook configuration examples under .codex/.
• Added environment variable examples for local hook setup.
• Added agent_session_authorize.py to mint actor JWTs and exchange chained authorization codes.
• Seeded Codex-specific Boruta scopes.
• Seeded a codex role containing the Codex hook scopes.
• Associated Codex scopes with the admin OAuth client for local PoC usage.

Security Model

Each Codex hook event is authorized as part of a chained session. The latest authorization code is stored locally and sent as the previous code for the next event, allowing Boruta to audit a sequence of prompt, tool call, permission request, result, and stop events.

The hook derives scopes from Codex events and tool payloads, for example:

• codex:prompt:submit
• codex:tool:use
• codex:file:patch
• codex:command:read
• codex:command:write
• codex:permission:request
• codex:permission:escalated

Boruta must know these scopes, the OAuth client must be allowed to request them, and the authorizing user or backend identity should receive them through the seeded codex role.

Local State

The hook writes sensitive local state outside the repository:

~/.boruta/session-code-chain.json
~/.boruta/codex-hook-session.json
~/.boruta/codex-hook-scopes-session.json
~/.boruta/codex-hook-docker-compose-session.json
~/.boruta/keys/

Expected permissions:

~/.boruta/keys 0700
private keys 0600
public JWKs 0644
session and marker JSON files 0600

Notes

This is intended as a proof of concept, not a hardened production policy system. Enforcement depends on Codex hook execution and BORUTA_CODEX_HOOK_ENFORCE=true; disabling enforcement reports authorization failures but lets Codex continue.