SapixDBSapixDB/Docs
Early Access
Phase 4 · SOX

SOX Compliance

The Sarbanes-Oxley Act requires tamper-evident financial records and a documented change approval trail. SapixDB satisfies both at the database layer — every write is append-only, cryptographically signed, and linked to its predecessor. The SOX package adds financial agent designation and enforced dual-admin sign-off.

ℹ What SOX requires that SapixDB delivers
  • Tamper-evident records — BLAKE3 content hash + Ed25519 signature on every nucleotide
  • Immutable history — append-only strand; deletes are impossible
  • Change approval chain — every structural mutation requires documented approval before it can be applied
  • Dual-admin sign-off — Tier 1 Financial agents require two distinct admins to approve any mutation
  • Audit report on demand — one API call generates a timestamped compliance report

Trust Tiers

An agent's SOX Trust Tier determines how strictly mutations to it are governed. Designating an agent as Tier 1 overrides the Zone policy — even a Free-zone agent will require dual-admin sign-off if it holds financial data.

Tier 1 — Financial

Two distinct administrator identifiers must both approve before any mutation can be applied. For financial records, transactions, ledgers.

Tier 2 — Standard

Standard governance — Zone mutation policy applies. Use for financial-adjacent agents that don't need the full dual-admin constraint.

Dual-admin sign-off

When a mutation is proposed against a Tier 1 Financial agent, the engine records the Pending proposal and waits. Before POST /v1/mutations/:id/applycan succeed, the proposal must have been approved by two distinct approver_agent_id values. The same identity approving twice does not satisfy the requirement.

full dual-admin flow
# 1. Any Mutant (or human) proposes a mutation
POST /v1/mutations
{
  "target_agent_id":   "payments-agent",
  "proposer_agent_id": "debt-mutant",
  "kind": { "type": "SchemaVersion", "new_version": 4 }
}
# → { "proposal_id": "abc123", "status": "pending", "policy": "dual_admin" }

# 2. First admin approves
POST /v1/mutations/abc123/approve
{ "approver_agent_id": "admin-alice" }

# 3. Second admin approves (must be a different identity)
POST /v1/mutations/abc123/approve
{ "approver_agent_id": "admin-bob" }
# → { "status": "approved", "approvals": ["admin-alice", "admin-bob"] }

# 4. Now apply is permitted
POST /v1/mutations/abc123/apply
# → { "applied": true, "mutation": "schema_version→4" }
# An immutable MUTATION-flagged audit record is written to the strand.
✗ Single admin ≠ compliantIf you attempt to apply a Tier 1 proposal with only one approval, the engine returns 403 Forbidden. This is enforced at the database layer — not in application code — so it cannot be bypassed.

HTTP API

Designate a financial agent

POST /v1/sox/designate
{
  "agent_id":      "payments-agent",
  "designated_by": "[email protected]",
  "tier":          1,
  "reason":        "Processes financial transactions — SOX in scope"
}
// → { "agent_id": "payments-agent", "tier": 1, "tier_label": "Tier 1 — Financial", ... }

List designated agents

GET /v1/sox/tiers
{
  "tiers": [
    { "agent_id": "payments-agent", "tier": 1, "tier_label": "Tier 1 — Financial",
      "designated_at_ms": 1716400000000, "designated_by": "[email protected]",
      "reason": "Processes financial transactions — SOX in scope" }
  ],
  "financial_count": 1
}

Remove a designation

DELETE /v1/sox/designate/payments-agent
// 200 OK — { "removed": true, "agent_id": "payments-agent" }

SOX audit report

GET /v1/sox/audit-report
{
  "generated_at_ms": 1716400120000,
  "financial_agents": [
    { "agent_id": "payments-agent", "tier": 1, ... }
  ],
  "summary": {
    "total_financial_agents": 1,
    "total_proposals_scanned": 24,
    "financial_agent_proposals": 6,
    "dual_signed_count": 5,
    "single_signed_count": 0,
    "pending_financial": 1
  },
  "proposals": [
    {
      "proposal_id": "abc123",
      "target_agent_id": "payments-agent",
      "kind": "schema_version→4",
      "status": "Applied",
      "approvals": ["admin-alice", "admin-bob"],
      "is_financial": true,
      "dual_sign_satisfied": true
    }
  ]
}

Python

installation
pip install sapixdb-sox
designate + audit
import asyncio
from sapixdb_sox import SoxClient

async def main():
    async with SoxClient("http://localhost:7475") as sox:
        # Designate the payments agent as Tier 1 Financial
        await sox.designate(
            agent_id="payments-agent",
            designated_by="[email protected]",
            reason="SOX Section 302 — financial transaction records",
        )

        # Verify designation
        is_fin = await sox.is_financial("payments-agent")
        print(f"payments-agent is financial: {is_fin}")  # True

        # Generate audit report
        report = await sox.audit_report()
        print(f"Financial agents:      {report.summary.total_financial_agents}")
        print(f"Dual-signed mutations: {report.summary.dual_signed_count}")
        print(f"Single-signed:         {report.summary.single_signed_count}  ← violations")

        # Check for pending proposals awaiting sign-off
        pending = await sox.pending_violations()
        if pending:
            print(f"ACTION REQUIRED: {len(pending)} proposals need dual sign-off: {pending}")

        # Check for applied mutations that bypassed dual sign-off
        unsigned = await sox.unsigned_mutations()
        if unsigned:
            print(f"SOX VIOLATION: {len(unsigned)} mutations applied without dual sign-off")

asyncio.run(main())

SoxClient API

MethodDescription
list_tiers()List all SOX-designated agents and their tiers.
designate(agent_id, designated_by, tier, reason)Designate an agent as Tier 1 Financial or Tier 2 Standard.
remove_designation(agent_id)Remove a financial designation.
is_financial(agent_id) → boolTrue if the agent is Tier 1 Financial.
audit_report()Generate a full SOX audit report.
pending_violations() → list[str]Proposal IDs awaiting dual sign-off.
unsigned_mutations() → list[str]Applied proposal IDs missing dual sign-off — violation signals.
⚠ SapixClient convenience methodsIf you are already using sapixdb-agent, the SapixClient exposes thin wrappers — sox_tiers(), sox_designate(), sox_remove_designation(), and sox_audit_report() — that return raw dicts. Use sapixdb-sox for typed Pydantic models and the high-level helpers like pending_violations().
Healthcare workload? Check the HIPAA package.

PHI field classification, access logging, and HIPAA audit reports — same architecture, different compliance lens.