Compliance reports (export)

Purpose: Describe the dashboard “Compliance reports” feature: what is in the ZIP, how it maps to common control themes (not certifications), who can download it, and how to use it with auditors and counsel.

Disclaimer: The export is an engineering aid for security and GRC conversations. It is not legal advice, a regulatory filing, or proof of SOC 2 / ISO 27001 / EU AI Act compliance. Control mappings are illustrative—validate wording and scope with your auditor and legal team.

1. Where to export

Sign in to the dashboard.
Open Compliance reports in the sidebar (/dashboard/compliance).
Choose workspace and reporting window (7 / 30 / 90 / 365 days, or “last 12 months” cap).
Click Download ZIP evidence pack and/or Download PDF summary.

The browser calls GET /api/compliance/export with your session cookie. Only members of that workspace receive a file; others get 403.

1.1 Admin-only mode (deployment option)

When COMPLIANCE_EXPORT_ADMIN_ONLY=1 (or true / yes) is set in the server environment, only users whose membership role is admin for the selected workspace may export. Non-admins see disabled actions in the UI and receive 403 with code: "compliance_export_admin_only" from the API. This is useful when procurement or security wants to limit evidence packs to tenant administrators.

Default (unset): any workspace member may export, same as other workspace-scoped data they can already see in the dashboard.

2. ZIP contents

File	Description
`Compliance-Report.md`	Full narrative: methodology, themed sections (SOC 2 / ISO 27001 / EU AI Act Art. 14), tables.
`Compliance-Report.pdf`	Shorter printable summary of the same themes and appendix metrics (not a full duplicate of MD).
`evaluations.csv`	Sample of evaluations in the window (capped; see §4).
`audit_log_events.csv`	Sample of audit events in the window (capped).
`approval_stages.csv`	Approval stages for evaluations in the evaluation sample.
`README.txt`	Short pointer and disclaimer.

3. PDF-only download

GET /api/compliance/export?workspace=<uuid>&range=<key>&format=pdf returns application/pdf with a condensed report. The dashboard Download PDF summary button uses this. It does not include CSV files; use the ZIP for structured extracts.

4. How mappings are framed

The Markdown report uses themes aligned to frameworks buyers often ask about:

SOC 2 (Trust Services Criteria) — illustrative references such as logical access, change management, logging/monitoring, and incident-related narrative hooks based on product behavior (RBAC, policy versions, audit events). This is not an official TSC mapping worksheet.
ISO/IEC 27001 (Annex A) — thematic alignment (e.g. access control, logging, configuration / change) using the same underlying evidence.
EU AI Act Article 14 — human oversight: staged approval, roles, OTP tiers, audit trail, and webhook/notification patterns as descriptive alignment—not a legal determination of “high-risk” status or conformity.

Your organization remains responsible for scope, gaps, and official control libraries (e.g. full Annex A control set, SOC 2 CC listing, AI Act conformity assessment if applicable).

5. Data scope and limits

Time window: Matches the selected range. all uses the same 12-month lookback as 365d (labeled explicitly in the report) to keep exports bounded.
Row caps: Evaluation and audit CSV extracts are capped (see implementation in lib/compliance/gatherComplianceData.ts). Totals in the narrative may reflect full counts where queried separately; CSVs are samples for reviewer convenience.
Policy Git links: If policy_git_links exists, the report may include counts of policies linked to Git; if the table is absent (older DB), that subsection degrades gracefully.

For complete historical extracts, use your data warehouse, Supabase backups, or contractual export processes—not this ZIP alone.

6. Rate limiting (optional)

When Upstash Redis is configured (UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN), middleware applies a per-IP sliding window limit to /api/compliance/export (default 20 requests per minute, overridable with RATE_LIMIT_COMPLIANCE_EXPORT_PER_MINUTE).

Why: Generating a ZIP runs multiple database reads and PDF rendering; without a cap, a mistaken loop, shared NAT, or abusive client could stress the database and app. Legitimate users rarely need more than a few exports per minute. If Redis is not configured, this limit is off (rely on your edge/WAF and monitoring).

7. Related documentation

Governance analytics — dashboard metrics definitions (separate from this export).
Data handling — categories of data stored.
Production readiness — operational and trust bar for go-live.

8. API reference (operators)

Query param	Values	Required
`workspace`	Workspace UUID	Yes
`range`	`7d`, `30d`, `90d`, `365d`, `all`	No (default `90d`)
`format`	`zip` (default), `pdf`	No

Auth: Session cookie (same as dashboard). Response: application/zip or application/pdf with Content-Disposition: attachment.