Governance Console

Installation

pip install "code-atelier-governance[console]"

# Required env vars:
export GOVERNANCE_DATABASE_URL=$DATABASE_URL  # your existing Postgres
export GOVERNANCE_AUDIT_SECRET=...  # same secret the SDK uses

# Apply the schema (includes console auth tables):
governance migrate --database-url $DATABASE_URL

# Create your first admin user:
governance console add-user --username admin --role admin

# Optional:
export GOVERNANCE_CONSOLE_PORT=8766  # default: 8766

# Start:
python -m codeatelier_governance.console

The console backend is a thin FastAPI server. For the full experience, also run the Next.js frontend from the console/ directory in the repo.

Pages

Chain Verification

The killer feature for compliance officers. On the Audit Log page, filter to any session and click Verify chain integrity. The server re-computes the HMAC of every row from scratch using the audit secret (which never leaves the server). If any row was modified — even one byte of metadata — the verification fails and tells you exactly which event was tampered with.

Authentication

The console ships with a built-in auth system. PBKDF2-HMAC-SHA256 password hashing (600k iterations, OWASP recommendation), Postgres-backed sessions with httpOnly cookies (8-hour TTL with revocation), and role-based access control.

# Add the first admin user:
governance console add-user --username alice --role admin

# List users:
governance console list-users

# Disable a user (revokes all sessions):
governance console disable-user --username alice

# Reset a password:
governance console reset-password --username alice

SSE Live Event Stream

The console uses Server-Sent Events for real-time updates instead of polling. Connect to GET /api/stream/events with a session cookie or x-governance-token header. Events are pushed as they happen — audit rows, presence changes, approval resolutions, and cost threshold alerts.

const source = new EventSource("/api/stream/events", {
  withCredentials: true,  // sends the session cookie
});

source.addEventListener("audit", (e) => {
  const event = JSON.parse(e.data);
  console.log("New audit event:", event.kind, event.agent_id);
});

source.addEventListener("presence", (e) => {
  const status = JSON.parse(e.data);
  console.log("Agent status:", status.agent_id, status.status);
});

Self-Approval Prevention

The console enforces self-approval prevention on HITL gates. When a console user attempts to grant an approval for an agent, the system checks the agent's operator_id (set via presence.heartbeat()) against the authenticated user. If they match, the approval is blocked with HTTP 403. If operator_id is NULL (not set), the approval is also blocked — fail-closed by default.

API Endpoints

Security

First-time experience

The console includes a built-in walkthrough for first-time users. On your first visit, a welcome banner offers a 6-step guided tour explaining each page and feature. The tour state persists in localStorage. A small ? button in the bottom-right corner lets anyone restart it at any time.