# Feature Spec: Enterprise Governance and Secure Dashboard Operations (AOP)

> **Purpose of this document**: Define implementation-ready delivery for Q5 and Q6: compliance policy packs + control export, and production-grade dashboard authentication/authorization with audit federation.

**Version:** 1.1  
**Date:** 2026-03-15  
**Status:** Draft (Audited Against Current Repo State)  
**Roadmap Mapping:** M37

---

## 0. Scope and Standards

### 0.1 Feature Scope

This spec implements:

- **Q5** Compliance Policy Packs + Control Export
- **Q6** Dashboard AuthN/AuthZ + SSO + Audit Federation

### 0.2 Required Standards

Implementation MUST preserve:

- deterministic evidence mapping
- explicit authorization for all mutating dashboard actions
- audit-log completeness for privileged operations
- optional/off-by-default behavior for local developer environments

### 0.3 Current Project State

This spec is still outstanding, but the dashboard/runtime baseline has advanced since the original draft:

- The web dashboard already exists and now routes most privileged mutations through `packages/web-dashboard/src/app/api/actions/route.ts`, with launch actions under `packages/web-dashboard/src/app/api/run/route.ts` and triage-state reads under `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`.
- A pluggable authorization seam already exists in `packages/web-dashboard/src/lib/authz-adapter.ts`, but it currently defaults to allow-all behavior and does not satisfy Q6.
- No compliance-pack assets, compliance export service/tool, real auth middleware, or dashboard audit-federation service exist yet.
- This spec must therefore build on the current dashboard seams rather than the older per-route action layout assumed in v1.0.

---

## 1. Objectives

### 1.1 Must-Have Outcomes

- operators can apply standardized compliance packs and export machine-readable control evidence mappings
- dashboard can run safely in multi-user environments with OIDC/API key auth and RBAC
- privileged dashboard actions emit structured audit records suitable for SIEM ingestion

### 1.2 Non-Goals

- no claim of automatic certification/compliance attestation
- no external IAM provisioning automation in this phase
- no hard requirement for auth in local dev mode

---

## 2. Architecture Decisions

### 2.1 Compliance as Policy Overlay

Compliance packs are deterministic overlays evaluated against existing policy, runtime state, and evidence artifacts. They do not replace base policy configuration.

### 2.2 Dashboard Security Boundary

Dashboard API authorization is enforced server-side for every action endpoint; UI affordances alone are insufficient and non-authoritative.

### 2.3 Unified Audit Envelope

Audit events from dashboard actions and compliance exports share a common schema for downstream ingestion.

---

## 3. Contracts and Config

### 3.1 Policy Additions

```yaml
innovation:
  compliance_packs: false
  dashboard_auth: false

compliance:
  enabled: false
  default_pack: soc2_baseline
  export:
    include_manual_controls: true

dashboard:
  auth:
    enabled: false
    mode: oidc_or_api_key # oidc | api_key | oidc_or_api_key
    oidc:
      issuer: ''
      client_id: ''
      audience: ''
    api_keys:
      env_var: AOP_DASHBOARD_API_KEYS
  rbac:
    viewer: [status_read, feature_read, evidence_read]
    reviewer: [status_read, feature_read, evidence_read, review_decide]
    operator: [status_read, feature_read, evidence_read, review_decide, feature_checkout]
    admin: ['*']
  audit:
    enabled: true
    sink: file # file | webhook
    webhook_url: ''
```

### 3.2 Source-Managed Compliance Assets

```text
agentic/orchestrator/compliance/packs/
  soc2_baseline.yaml
  iso27001_baseline.yaml
  hipaa_baseline.yaml
agentic/orchestrator/schemas/compliance_pack.schema.json
```

### 3.3 Runtime Artifacts

```text
.aop/runtime/compliance/control_export_<timestamp>.json
.aop/runtime/audit/dashboard-audit.jsonl
```

### 3.4 New MCP Tool

- `compliance.export_controls`

### 3.5 New CLI Command

- `aop compliance export --format <json|csv> [--pack <id>] [--include-manual true|false]`

---

## 4. Detailed Feature Specs

## 4.1 Q5: Compliance Policy Packs + Control Export

### 4.1.1 Problem

Enterprise adoption requires consistent control mapping from orchestrator behavior/evidence to recognized control frameworks.

### 4.1.2 Design

Provide curated compliance packs plus deterministic export routine.

### 4.1.3 Pack Structure

```yaml
id: soc2_baseline
version: '1.0'
controls:
  - id: CC7.2
    title: Monitor system components for anomalies
    requirements:
      - path: policy.testing.coverage.minimums.line
        op: gte
        value: 0.9
      - path: policy.merge_policy.require_user_approval
        op: eq
        value: true
    evidence_sources:
      - gate_results
      - operation_ledger
    manual_evidence_required: false
```

### 4.1.4 Export Output Contract

```json
{
  "pack_id": "soc2_baseline",
  "generated_at": "2026-03-03T12:00:00Z",
  "controls": [
    {
      "id": "CC7.2",
      "status": "pass",
      "automated_checks": [
        {
          "path": "policy.testing.coverage.minimums.line",
          "result": "pass",
          "observed": 0.9
        }
      ],
      "evidence_refs": [".aop/features/feature_x/evidence/gates/full-2026-03-03.json"],
      "manual_evidence_required": false
    }
  ]
}
```

### 4.1.5 File Targets

- `apps/control-plane/src/application/services/compliance-service.ts` (new)
- `apps/control-plane/src/cli/compliance-export-command-handler.ts` (new)
- `agentic/orchestrator/compliance/packs/*.yaml` (new)
- `agentic/orchestrator/schemas/compliance_pack.schema.json` (new)
- `agentic/orchestrator/tools/schemas/input/compliance.export_controls.input.schema.json` (new)
- `agentic/orchestrator/tools/schemas/output/compliance.export_controls.output.schema.json` (new)

### 4.1.6 Acceptance Criteria

- compliance packs schema-validate
- export output is deterministic for same repo state
- controls include explicit pass/fail and evidence references

---

## 4.2 Q6: Dashboard AuthN/AuthZ + SSO + Audit Federation

### 4.2.1 Problem

Dashboard operation in shared/production contexts needs strong identity + authorization + audit controls.

### 4.2.2 Design

Add optional auth middleware, server-side action authorization, and audit sink integration.

### 4.2.3 Auth Modes

- `oidc`: bearer token validation against OIDC issuer metadata
- `api_key`: static/scoped keys from environment
- `oidc_or_api_key`: allow either for migration convenience

### 4.2.4 Action Authorization Matrix

Actions to guard:

- `feature_review_decide` (approve/deny/request_changes)
- `feature_checkout`
- `dashboard_admin_settings`

Each action must map to role permission in policy.

### 4.2.5 Audit Event Contract

```json
{
  "ts": "2026-03-03T12:10:00Z",
  "actor": {
    "id": "alice@example.com",
    "auth_type": "oidc",
    "role": "reviewer"
  },
  "action": "feature_review_decide",
  "feature_id": "payment_retry_guard",
  "result": "allow",
  "request_id": "req-123",
  "metadata": {
    "decision": "approve"
  }
}
```

### 4.2.6 File Targets

- `packages/web-dashboard/src/middleware.ts` (new)
- `packages/web-dashboard/src/lib/authz-adapter.ts`
- `packages/web-dashboard/src/app/api/auth/*` (new)
- `packages/web-dashboard/src/app/api/actions/route.ts`
- `packages/web-dashboard/src/app/api/run/route.ts`
- `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`
- `apps/control-plane/src/application/services/dashboard-audit-service.ts` (new)

### 4.2.7 Acceptance Criteria

- unauthorized users cannot invoke protected dashboard actions
- audit events emitted for all protected action attempts (allow + deny)
- local mode works with auth disabled by default

---

## 5. Milestones

### EGD1: Compliance Pack Foundation

Tasks:

1. Add compliance pack assets + schemas.
2. Implement export service + MCP tool + CLI command.

Exit gate:

- deterministic export and evidence mapping verified by tests.

### EGD2: Dashboard Auth and RBAC

Tasks:

1. Add auth middleware and token/api key validation.
2. Implement server-side role authorization for protected endpoints.

Exit gate:

- protected actions denied when unauthorized in integration tests.

### EGD3: Audit Federation

Tasks:

1. Add unified audit envelope and file sink.
2. Add optional webhook sink with retry/backoff.

Exit gate:

- allow/deny events emitted and schema-valid in both sinks.

---

## 6. Testing Strategy (Normative)

### 6.1 Unit Tests

- compliance rule evaluation operators (`eq`, `gte`, etc.)
- pack schema validation and export assembly
- auth token/api key parsing and role mapping
- audit event envelope validation

### 6.2 Integration Tests

- `aop compliance export` on sample repository state
- dashboard protected endpoint authorization matrix
- audit logs emitted for protected action attempts

### 6.3 Security Tests

- invalid/expired oidc tokens rejected
- malformed or unknown API keys rejected
- privilege escalation attempt denied (`viewer` invoking `review_decide`)

### 6.4 Contract and Parity Tests

- `compliance.export_controls` schema and transport parity (in-process vs MCP)

---

## 7. Acceptance Criteria

1. Compliance packs and export path are fully operational and deterministic.
2. Dashboard auth/authz can be enabled for production multi-user use.
3. Audit federation records all protected dashboard action attempts.
4. Feature flags/defaults preserve existing local development behavior.
5. Full validation gates pass (`lint`, `typecheck`, `test`, contract/architecture validation).

---

## 8. Risks and Mitigations

- Risk: users assume compliance export equals certification.
  - Mitigation: mandatory disclaimer and `manual_evidence_required` field.

- Risk: auth misconfiguration locks out operators.
  - Mitigation: startup preflight checks and explicit break-glass local mode.

- Risk: webhook audit sink failures lose records.
  - Mitigation: durable local fallback log + retry policy.

---

## 9. Definition of Done

A completed EGD milestone MUST include:

- changed files and architecture rationale
- schema/catalog/policy diffs
- security + integration test coverage
- gate command results
- updates in `spec-files/progress.md`
