Compliance Evidence

TapPass’s compliance story rests on mechanisms that exist in the server itself: a hash-chained, dual-signed audit trail, cryptographic erasure for GDPR, configurable retention, and policy what-if replay. This page documents what each mechanism does and which endpoint or CLI command produces the evidence.

The audit trail — tamper evidence by construction

Every governed event is appended to the audit trail with three integrity mechanisms:

Mechanism	Detail
Hash chain (v2)	Each event stores a cryptographic hash over its fields plus the previous event’s hash. Chain format v2 is per-org: each org has an independent chain, so verification and compromise are isolated per tenant. Legacy events without _chain_version verify against the v1 global chain
Dual signatures	Every event carries hybrid classical + post-quantum dual signatures. Both signatures must verify for an event to be authentic
Chain bridges	When retention deletes events, a _chain_bridge record preserves the bridged hash so the chain still verifies across the gap

The signing key lives at TAPPASS_AUDIT_SIGNING_KEY (or is auto-generated in TAPPASS_KEYS_DIR, default keys/); set TAPPASS_AUDIT_KEY_PASSWORD to keep the PEM encrypted at rest.

Verifying integrity

GET /api/audit/integrity recomputes each event’s hash, checks chain linkage end-to-end, and verifies event signatures. It is org-scoped, requires a developer role, and results are cached for 5 minutes to prevent DoS via repeated full-chain scans.

curl -s -H "Authorization: Bearer $TOKEN" \
  https://tappass.example.com/api/audit/integrity | python -m json.tool

Response shape:

{
  "status": "intact",            // or "compromised" (or "empty" before any events)
  "events": 15432,
  "valid": 15432,
  "broken": 0,
  "broken_events": [],           // [{line, event_id, reason: chain_broken|content_modified|...}]
  "chain_length": 15432,
  "current_head": "a1b2c3..."
}

broken_events distinguishes chain_broken (a _prev_hash no longer matches its predecessor — insertion, deletion, or reordering) from content_modified (recomputed hash differs — fields were edited).

Independent verification

External auditors can verify signatures without trusting the server:

curl -s https://tappass.example.com/api/audit/signing-key | python -m json.tool

Returns the audit public keys with usage instructions.

Querying the trail

Evidence extraction is a query, not a separate instrumentation effort:

Endpoint	Purpose
GET /api/audit?event_type=pii_detected&limit=500	Filtered event list (cursor-paginated)
GET /api/audit/_overview	Aggregate statistics
GET /api/audit/session/{id} · /task/{id} · /pipeline/{id}	Drill into one session, task, or pipeline run

The CLI equivalent is tappass audit list --event-type pii_detected --since 30d.

GDPR

Article 17 — right to erasure (cryptographic erasure)

Erasure is a two-step, receipt-backed process under /api/compliance/gdpr:

Endpoint	Role	Description
POST /api/compliance/gdpr/erasure	requester	Submit an erasure request for a data subject
GET /api/compliance/gdpr/erasure	—	List erasure requests for the org
GET /api/compliance/gdpr/erasure/{request_id}	—	Check request status
POST /api/compliance/gdpr/erasure/{request_id}/execute	admin	Execute the erasure

Execution replaces PII fields with [ERASED:GDPR-Art17] tombstones (cryptographic erasure) across the audit store, the JSONL log, and vault credentials. It then produces a receipt — data subject, executor, counts of erased events/records/credentials, and a hash of the receipt — which is itself recorded in the (signed) audit trail as an erasure-executed event. The tombstone preserves the chain: the event still hashes and verifies, only the personal data is gone.

Article 15 — data subject access (DSAR)

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  https://tappass.example.com/api/compliance/gdpr/dsar \
  -d '{"subject": "user@example.com"}'

Exports everything the trail holds about a data subject.

Article 30 — record of processing

Query the trail for processing evidence: pii_detected events carry agent ID, entity types, and the action taken (redacted / blocked / allowed); LLM-call events show which provider received data. See the audit query endpoints above.

Storage limitation — retention

TAPPASS_AUDIT_RETENTION_DAYS (default 365, 0 = forever) sets how long audit records are kept. Retention is operator-triggered — there is no background scheduler — via the settings API:

Endpoint	Description
GET /api/settings/retention	Current retention config (persisted to data/retention_config.json)
GET /api/settings/retention/preview	What a retention run would delete/archive
POST /api/settings/retention/run	Execute a retention run

Rotation (TAPPASS_AUDIT_ROTATION_MAX_MB, default 100) and optional archiving (local/S3/Azure Blob, with gzip) are configured in the same retention config.

EU AI Act — human oversight

• Approval workflows (/api/approvals, CLI tappass approvals) give humans an approve/deny gate on governed actions, with every decision written to the audit trail.
• Trust scoring (GET /api/trust/scores, GET /api/trust/scores/{agent_uuid}, GET /api/trust/alerts) provides continuous per-agent oversight signals derived from audit events.
• Policy replay (POST /api/audit/replay, plus /api/audit/replay/batch for impact analysis and /api/audit/playground/test for sandbox testing) re-runs past events against proposed policy — what-if analysis before a policy change ships, with no audit writes and no side effects. CLI: tappass audit replay <event_id> --policy-overrides @overrides.json.

SOC 2 Type II

The integrity endpoint above is the core evidence: a point-in-time, cryptographically verified statement that the audit trail is intact, repeatable on demand, with the signing keys published for independent verification. Audit event samples (GET /api/audit?limit=1000) plus the dual-signature scheme demonstrate that logging controls operated over the period.

On-prem: evidence generator

Self-hosted deployments ship a helper at deploy/on-prem/scripts/generate-compliance-evidence.sh. It runs the unit and security test suites, the eval corpus, Bandit SAST, and pip-audit SCA, then writes the raw results plus a SUMMARY.md into a compliance-evidence/ directory — a dated artifact bundle you can hand to auditors alongside /api/audit/integrity output:

./deploy/on-prem/scripts/generate-compliance-evidence.sh
# → compliance-evidence/{unit-tests.xml, security-tests.xml, eval-corpus.json,
#                      bandit-sast.json, pip-audit-sca.json, SUMMARY.md}