Merge pull request #313 from bg-playground/copilot/297-wire-audit-log-endpoints

External Results audit closure: actor-aware audit model + runner-token write-path logging

Author: bg-playground

backend/alembic/versions/i8j9k0l1m2n3_audit_log_actor_kind.py

@@ -0,0 +1,58 @@
+"""add actor_kind and actor_token_id to audit_log
+
+Revision ID: i8j9k0l1m2n3
+Revises: h7i8j9k0l1m2
+Create Date: 2026-05-07 14:30:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "i8j9k0l1m2n3"
+down_revision: Union[str, None] = "h7i8j9k0l1m2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("audit_log", sa.Column("actor_kind", sa.String(length=20), nullable=False, server_default="user"))
+    op.add_column("audit_log", sa.Column("actor_token_id", postgresql.UUID(as_uuid=True), nullable=True))
+    op.alter_column("audit_log", "user_id", existing_type=postgresql.UUID(as_uuid=True), nullable=True)
+
+    op.execute("UPDATE audit_log SET actor_kind = 'user' WHERE actor_kind IS NULL")
+
+    op.create_foreign_key(
+        "fk_audit_log_actor_token_id_runner_tokens",
+        "audit_log",
+        "runner_tokens",
+        ["actor_token_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+    op.create_check_constraint(
+        "ck_audit_log_actor_identity",
+        "audit_log",
+        "(actor_kind = 'user' AND user_id IS NOT NULL AND actor_token_id IS NULL) "
+        "OR (actor_kind = 'runner_token' AND actor_token_id IS NOT NULL AND user_id IS NULL)",
+    )
+    op.create_index("idx_audit_log_actor_token_id", "audit_log", ["actor_token_id"])
+    op.create_index("idx_audit_log_actor_kind_created_at", "audit_log", ["actor_kind", "created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("idx_audit_log_actor_kind_created_at", table_name="audit_log")
+    op.drop_index("idx_audit_log_actor_token_id", table_name="audit_log")
+    op.drop_constraint("ck_audit_log_actor_identity", "audit_log", type_="check")
+    op.drop_constraint("fk_audit_log_actor_token_id_runner_tokens", "audit_log", type_="foreignkey")
+
+    # Restore non-null user_id invariant for pre-actor rows.
+    op.execute("DELETE FROM audit_log WHERE user_id IS NULL")
+    op.alter_column("audit_log", "user_id", existing_type=postgresql.UUID(as_uuid=True), nullable=False)
+    op.drop_column("audit_log", "actor_token_id")
+    op.drop_column("audit_log", "actor_kind")

backend/app/api/audit_log.py

@@ -17,7 +17,9 @@
 
 @router.get("/audit-log", response_model=AuditLogListResponse)
 async def list_audit_logs(
+    actor_kind: str | None = Query(None, description="Filter by actor kind ('user' or 'runner_token')"),
     user_id: UUID | None = Query(None, description="Filter by user ID"),
+    actor_token_id: UUID | None = Query(None, description="Filter by runner token ID"),
     action: str | None = Query(None, description="Filter by action (e.g. 'requirement.created')"),
     resource_type: str | None = Query(None, description="Filter by resource type"),
     date_from: datetime | None = Query(None, description="Filter entries on or after this datetime"),
@@ -30,7 +32,9 @@ async def list_audit_logs(
     """List audit log entries (admin only)."""
     entries, total = await get_audit_logs(
         db,
+        actor_kind=actor_kind,
         user_id=user_id,
+        actor_token_id=actor_token_id,
         action=action,
         resource_type=resource_type,
         date_from=date_from,

backend/app/api/external_results.py

@@ -19,6 +19,7 @@
     get_current_runner_token,  # noqa: F401 — used inside _get_session_auth
     require_runner_scope,
 )
+from app.crud.audit_log import write_audit
 from app.crud.external_results import create_session, finish_session_db, get_session
 from app.db.session import get_db
 from app.models.runner_token import RunnerToken
@@ -72,6 +73,20 @@ async def create_external_session(
     last 60 seconds (idempotency window).
     """
     session = await create_session(db, payload=payload, runner_token_id=token.id)
+    await write_audit(
+        db,
+        actor_kind="runner_token",
+        actor_id=token.id,
+        action="external_results.session.start",
+        resource_type="external_session",
+        resource_id=session.id,
+        details={
+            "project_id": str(payload.project_id),
+            "git_sha": payload.git_sha,
+            "git_branch": payload.git_branch,
+            "runner": payload.runner,
+        },
+    )
     return _session_to_response(session)
 
 
@@ -88,7 +103,7 @@ async def finish_external_session(
     session_id: UUID,
     payload: SessionFinish,
     db: AsyncSession = Depends(get_db),
-    token: RunnerToken = Depends(require_runner_scope(_WRITE_SCOPE)),  # noqa: ARG001
+    token: RunnerToken = Depends(require_runner_scope(_WRITE_SCOPE)),
 ) -> SessionResponse:
     """Set the terminal status of a session.
 
@@ -107,6 +122,19 @@ async def finish_external_session(
             detail={"code": "session.not_found", "message": f"Session {session_id} does not exist.", "details": None},
         )
 
+    await write_audit(
+        db,
+        actor_kind="runner_token",
+        actor_id=token.id,
+        action="external_results.session.finish",
+        resource_type="external_session",
+        resource_id=session.id,
+        details={
+            "status": session.status.value,
+            "finished_at": session.finished_at.isoformat() if session.finished_at else None,
+        },
+    )
+
     return _session_to_response(session)
 
 

backend/app/crud/audit_log.py

@@ -1,6 +1,7 @@
 """CRUD operations for Audit Log"""
 
 from datetime import datetime
+from typing import Literal
 from uuid import UUID
 
 from sqlalchemy import func, select
@@ -9,6 +10,36 @@
 from app.models.audit_log import AuditLog
 
 
+async def write_audit(
+    db: AsyncSession,
+    *,
+    actor_kind: Literal["user", "runner_token"],
+    actor_id: UUID,
+    action: str,
+    resource_type: str,
+    resource_id: str | UUID,
+    details: dict | None = None,
+) -> AuditLog:
+    """Create a new audit log entry for a user or runner token actor."""
+    entry_kwargs = {
+        "actor_kind": actor_kind,
+        "action": action,
+        "resource_type": resource_type,
+        "resource_id": str(resource_id),
+        "details": details,
+    }
+    if actor_kind == "user":
+        entry_kwargs["user_id"] = actor_id
+    else:
+        entry_kwargs["actor_token_id"] = actor_id
+
+    entry = AuditLog(**entry_kwargs)
+    db.add(entry)
+    await db.commit()
+    await db.refresh(entry)
+    return entry
+
+
 async def create_audit_entry(
     db: AsyncSession,
     user_id: UUID,
@@ -17,23 +48,23 @@ async def create_audit_entry(
     resource_id: str,
     details: dict | None = None,
 ) -> AuditLog:
-    """Create a new audit log entry."""
-    entry = AuditLog(
-        user_id=user_id,
+    """Backward-compatible user-actor shim for audit writes."""
+    return await write_audit(
+        db,
+        actor_kind="user",
+        actor_id=user_id,
         action=action,
         resource_type=resource_type,
         resource_id=resource_id,
         details=details,
     )
-    db.add(entry)
-    await db.commit()
-    await db.refresh(entry)
-    return entry
 
 
 async def get_audit_logs(
     db: AsyncSession,
     user_id: UUID | None = None,
+    actor_kind: str | None = None,
+    actor_token_id: UUID | None = None,
     action: str | None = None,
     resource_type: str | None = None,
     date_from: datetime | None = None,
@@ -46,6 +77,10 @@ async def get_audit_logs(
 
     if user_id is not None:
         query = query.where(AuditLog.user_id == user_id)
+    if actor_kind is not None:
+        query = query.where(AuditLog.actor_kind == actor_kind)
+    if actor_token_id is not None:
+        query = query.where(AuditLog.actor_token_id == actor_token_id)
     if action is not None:
         query = query.where(AuditLog.action == action)
     if resource_type is not None:

backend/app/crud/external_results.py

@@ -30,7 +30,6 @@ async def create_session(
     seconds by the same runner token, the existing session is returned instead
     of creating a duplicate.
 
-    # TODO(#297): Write audit entry ``external_results.session.start`` here.
     """
     cutoff = datetime.now(tz=timezone.utc).replace(tzinfo=None) - timedelta(seconds=_IDEMPOTENCY_WINDOW_SECONDS)
 
@@ -90,7 +89,6 @@ async def finish_session_db(
     Raises ``ValueError`` with a structured dict payload on transition
     violations so the API layer can return the appropriate 409.
 
-    # TODO(#297): Write audit entry ``external_results.session.finish`` here.
     """
     result = await db.execute(select(ExternalRunSession).where(ExternalRunSession.id == session_id))
     session = result.scalar_one_or_none()

backend/app/models/audit_log.py

@@ -1,6 +1,6 @@
 import uuid
 
-from sqlalchemy import Column, DateTime, ForeignKey, String
+from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Index, String
 from sqlalchemy.sql import func
 
 from .base import Base
@@ -9,9 +9,24 @@
 
 class AuditLog(Base):
     __tablename__ = "audit_log"
+    __table_args__ = (
+        CheckConstraint(
+            "(actor_kind = 'user' AND user_id IS NOT NULL AND actor_token_id IS NULL) "
+            "OR (actor_kind = 'runner_token' AND actor_token_id IS NOT NULL AND user_id IS NULL)",
+            name="ck_audit_log_actor_identity",
+        ),
+        Index("idx_audit_log_actor_kind_created_at", "actor_kind", "created_at"),
+    )
 
     id = Column(GUID(), primary_key=True, default=uuid.uuid4)
-    user_id = Column(GUID(), ForeignKey("users.id"), nullable=False, index=True)
+    actor_kind = Column(String(20), nullable=False, server_default="user")
+    user_id = Column(GUID(), ForeignKey("users.id"), nullable=True, index=True)
+    actor_token_id = Column(
+        GUID(),
+        ForeignKey("runner_tokens.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
     action = Column(String(100), nullable=False, index=True)
     resource_type = Column(String(50), nullable=False, index=True)
     resource_id = Column(String(36), nullable=False)

backend/app/schemas/audit_log.py

@@ -7,7 +7,9 @@
 
 class AuditLogResponse(BaseModel):
     id: UUID
-    user_id: UUID
+    actor_kind: str
+    user_id: UUID | None
+    actor_token_id: UUID | None
     action: str
     resource_type: str
     resource_id: str