cbc9ad73f7
Reference implementation of GCAP-SPEC-SHELLBOUND-BROKER-0001
in FastAPI. Designed for ISVs and enterprises implementing
the governed shell authorization protocol.
Architecture:
FastAPI + SQLModel + Pydantic + async SQLite
Single container deployment: Dockerfile included
OpenAPI schema at /docs is the machine-readable GSAP contract
Broker Interface (§5):
POST /governance/authorize/ — Issue AC
GET /governance/authorize/{p}/ — Poll elevation
POST /governance/complete/ — Receive CR
GET /governance/session/{id}/ — View chain of custody
POST /governance/elevate/ — JIT elevation
GET /governance/drivers/ — List drivers
Identity Driver Interface (§2.2):
IdentityDriver — abstract base (ISV extension point)
KeycloakDriver — Keycloak implementation
DriverRegistry — driver lookup and registration
Chronicle integration (§1.4):
Optional CloudEvents emission via CHRONICLE_WEBHOOK_URL
Forgejo push event format for receiver compatibility
Models:
Pydantic schemas for AC, CR, Principal, Accord, Operation
SQLModel DB models for persistence
Tests: 6 async tests including full AC→CR cycle
695 lines across 27 files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
78 lines
4.1 KiB
Python
78 lines
4.1 KiB
Python
"""POST /governance/authorize/ — GSAP §5.2"""
|
|
import secrets, uuid
|
|
from datetime import datetime, timedelta, UTC
|
|
from fastapi import APIRouter, Depends, HTTPException
|
|
from sqlmodel.ext.asyncio.session import AsyncSession
|
|
from gsap_broker.db import get_session
|
|
from gsap_broker.db_models import AuthorizationContextDB
|
|
from gsap_broker.drivers.registry import DriverRegistry
|
|
from gsap_broker.models import (
|
|
AuthorizeRequest, AuthorizeResponse, AuthorizationContext,
|
|
Principal, Accord, Operation, IdentityProof)
|
|
from gsap_broker.settings import settings
|
|
from gsap_broker import chronicle
|
|
|
|
router = APIRouter()
|
|
|
|
@router.post("/authorize/", response_model=AuthorizeResponse, summary="Issue AC (GSAP §5.2)")
|
|
async def authorize(request: AuthorizeRequest, db: AsyncSession = Depends(get_session)):
|
|
try:
|
|
driver = DriverRegistry.get(request.driver_id, config={
|
|
"requested_accord": request.accord_template,
|
|
"domain": settings.keycloak_domain,
|
|
"did_template": settings.keycloak_did_template,
|
|
"elevated_suffix": settings.keycloak_elevated_role_suffix,
|
|
})
|
|
except KeyError as e:
|
|
raise HTTPException(status_code=400, detail=str(e))
|
|
|
|
auth_result = await driver.authenticate()
|
|
|
|
if auth_result.needs_elevation:
|
|
poll_token = secrets.token_urlsafe(32)
|
|
ac_db = AuthorizationContextDB(
|
|
principal_did="", driver_id=request.driver_id, playbook=request.playbook,
|
|
corpus_entry_cid=request.corpus_entry_cid, parameters_cid=request.parameters_cid,
|
|
accord_template=request.accord_template, status="pending",
|
|
expires_at=datetime.now(UTC) + timedelta(minutes=10), poll_token=poll_token)
|
|
db.add(ac_db); await db.commit()
|
|
return AuthorizeResponse(
|
|
status="pending_elevation", poll_token=poll_token,
|
|
elevation_instructions=auth_result.elevation_required.instructions,
|
|
activation_url=auth_result.elevation_required.activation_url)
|
|
|
|
if not auth_result.is_authorized:
|
|
raise HTTPException(status_code=403, detail=auth_result.denial_reason)
|
|
|
|
now = datetime.now(UTC)
|
|
expires = now + timedelta(minutes=settings.ac_ttl_minutes)
|
|
ctx_id = uuid.uuid4()
|
|
|
|
ac = AuthorizationContext(
|
|
context_id=ctx_id, issued_at=now, expires_at=expires,
|
|
principal=Principal(did=auth_result.principal_did, display_name=auth_result.display_name, driver_id=request.driver_id),
|
|
accord=Accord(template=request.accord_template),
|
|
operation=Operation(playbook=request.playbook, corpus_entry_cid=request.corpus_entry_cid, parameters_cid=request.parameters_cid),
|
|
identity_proof=IdentityProof(token_jti=auth_result.token_jti, elevation_active=auth_result.elevation_active, mfa_satisfied=auth_result.mfa_satisfied),
|
|
broker={"did": settings.broker_did, "name": settings.broker_name})
|
|
|
|
ac_db = AuthorizationContextDB(
|
|
context_id=ctx_id, principal_did=auth_result.principal_did, driver_id=request.driver_id,
|
|
playbook=request.playbook, corpus_entry_cid=request.corpus_entry_cid,
|
|
parameters_cid=request.parameters_cid, accord_template=request.accord_template,
|
|
token_jti=auth_result.token_jti, elevation_active=auth_result.elevation_active,
|
|
mfa_satisfied=auth_result.mfa_satisfied, status="authorized", issued_at=now, expires_at=expires)
|
|
db.add(ac_db)
|
|
cid = await chronicle.emit("GSAP_AC_ISSUED", {"event_code": "0x2704", "context_id": str(ctx_id), "principal_did": auth_result.principal_did, "playbook": request.playbook})
|
|
ac_db.chronicle_event_cid = cid
|
|
await db.commit()
|
|
|
|
return AuthorizeResponse(status="authorized", authorization_context=ac)
|
|
|
|
@router.get("/authorize/{poll_token}/", response_model=AuthorizeResponse, summary="Poll (GSAP §5.3)")
|
|
async def authorize_poll(poll_token: str, db: AsyncSession = Depends(get_session)):
|
|
from sqlmodel import select
|
|
result = await db.exec(select(AuthorizationContextDB).where(AuthorizationContextDB.poll_token == poll_token))
|
|
ac_db = result.first()
|
|
if not ac_db: raise HTTPException(status_code=404, detail="Not found.")
|
|
return AuthorizeResponse(status=ac_db.status, poll_token=poll_token)
|