Receipts & Audit

📋Learning Objectives

• Understand ARIA Shield's Seven Controls framework
• Learn how tamper-evident receipts work
• Understand hash chains and integrity verification
• Use Plugin SDK telemetry for observability
• Query audit logs and receipts
• Complete your Week 5 and full program assessment

🛡️ARIA Shield: Seven Controls

ARIA Shield implements seven security controls that wrap every platform operation:

🧾Tamper-Evident Receipts

Every sensitive operation generates a cryptographically signed receipt:

{
  // Unique receipt identifier
  "receipt_id": "rec_01HZW9X8Y7QKJN3M5P2R4T6V8W",
  "timestamp": "2026-01-21T14:30:15.123Z",
  
  // Who performed the action (full chain)
  "actor": {
    "user_id": "u:alice@corp.com",
    "agent_id": "aria://bff/invoice-agent",
    "delegation_id": "del_01HZW...",
    "chain": ["u:alice@corp.com", "invoice-agent", "crud-service"]
  },
  
  // What action was performed
  "action": {
    "type": "workflow.execute",
    "resource": "arn:aria:crud:workflow/approve_invoice",
    "input_hash": "sha256:abc123..."   // Hash of input, not input itself
  },
  
  // PDP decision details
  "decision": {
    "decision_id": "dec_01HZW...",
    "effect": "Permit",
    "eps_etag": "W/\"v42\"",
    "policy_refs": ["invoices/approve", "global/audit"]
  },
  
  // Hash chain for integrity
  "chain": {
    "prev_hash": "sha256:9f86d08...",
    "self_hash": "sha256:a1b2c3d...",
    "sequence": 1520483
  },
  
  // Cryptographic signature
  "signature": "eyJhbGciOiJFUzI1NiIs..."
}

Receipt Fields Explained

🔗Hash Chain Integrity

Verification Algorithm

// Verify a single receipt
function verifyReceipt(receipt, trustedPublicKey) {
  // 1. Verify JWS signature
  const payload = JSON.stringify({
    receipt_id: receipt.receipt_id,
    timestamp: receipt.timestamp,
    actor: receipt.actor,
    action: receipt.action,
    decision: receipt.decision,
    chain: receipt.chain
  });
  
  if (!verifyJWS(receipt.signature, payload, trustedPublicKey)) {
    throw new Error('Invalid signature');
  }
  
  // 2. Verify self_hash matches content
  const computedHash = sha256(payload);
  if (computedHash !== receipt.chain.self_hash) {
    throw new Error('Self hash mismatch');
  }
  
  return true;
}

// Verify chain continuity
function verifyChain(receipts) {
  for (let i = 1; i < receipts.length; i++) {
    const prev = receipts[i - 1];
    const curr = receipts[i];
    
    // Current's prev_hash must equal previous's self_hash
    if (curr.chain.prev_hash !== prev.chain.self_hash) {
      throw new Error(`Chain break at sequence ${curr.chain.sequence}`);
    }
    
    // Sequence must be monotonic
    if (curr.chain.sequence !== prev.chain.sequence + 1) {
      throw new Error(`Sequence gap at ${curr.chain.sequence}`);
    }
  }
  return true;
}

📊Plugin SDK Telemetry

Use sdk.telemetry to emit structured logs and metrics from your plugins:

const sdk = globalThis.pluginSdk;

// Structured logging
sdk.telemetry.logInfo('Invoice approved', {
  invoice_id: 'INV-2026-001',
  amount: 15000,
  approver: 'alice@corp.com'
});

sdk.telemetry.logError('Approval failed', {
  invoice_id: 'INV-2026-002',
  error_code: 'BUDGET_EXCEEDED',
  budget_remaining: 500
});

// Track business events
sdk.telemetry.trackEvent('invoice_approved', {
  invoice_id: 'INV-2026-001',
  workflow_id: 'wf_01HZW...',
  duration_ms: 1250
});

// Measure performance
const timer = sdk.telemetry.startTimer('api_call');
const response = await sdk.api.fetch('/api/invoices');
timer.stop(); // Emits timing metric

// Or use measureTiming helper
const result = await sdk.telemetry.measureTiming('invoice_fetch', async () => {
  return await sdk.api.fetch('/api/invoices');
});

Telemetry Best Practices

• Use structured data: Pass objects, not formatted strings
• Include correlation IDs: Link related events across services
• Avoid PII in logs: Use IDs, not names or emails
• Track business metrics: Count approvals, measure latency
• Use appropriate levels: Info for success, Error for failures

🔍Querying Audit Logs

Receipts API

# Query receipts by actor
curl "https://bff.self.empowernow.ai/audit/receipts?actor=u:alice@corp.com&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Query by resource
curl "https://bff.self.empowernow.ai/audit/receipts?resource=workflow/approve_invoice" \
  -H "Authorization: Bearer $TOKEN"

# Query by time range
curl "https://bff.self.empowernow.ai/audit/receipts?from=2026-01-20T00:00:00Z&to=2026-01-21T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN"

# Verify chain integrity
curl "https://bff.self.empowernow.ai/audit/receipts/verify?from_seq=1520480&to_seq=1520490" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "receipts": [
    { "receipt_id": "rec_01HZW...", "timestamp": "...", ... },
    { "receipt_id": "rec_01HZX...", "timestamp": "...", ... }
  ],
  "pagination": {
    "total": 127,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "chain_status": {
    "verified": true,
    "from_sequence": 1520480,
    "to_sequence": 1520529
  }
}

Data Retention

⚓External Anchoring

Anchoring periodically commits the latest chain head hash to an external, immutable store. This proves the chain existed at a specific time, even if the primary storage is compromised.

Anchor Flow

Anchor Record

{
  "anchor_id": "anc_01HZW...",
  "ts": "2026-01-21T15:00:00Z",
  "chain_head": "sha256:d4e5f6...",
  "sequence_range": {
    "from": 1520000,
    "to": 1520999
  },
  "store": "s3://aria-receipts-prod/heads/latest",
  "signature": "eyJhbGciOiJFUzI1NiIs..."
}

Anchor Verification

# Verify that receipts 1520000-1520999 haven't been tampered
curl "https://bff.self.empowernow.ai/audit/receipts/verify-anchor" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "anchor_id": "anc_01HZW...",
    "include_receipts": false
  }'

# Response
{
  "verified": true,
  "chain_valid": true,
  "anchor_timestamp": "2026-01-21T15:00:00Z",
  "external_store_verified": true
}

🔎Visual Diffs

Receipts include fingerprints that enable human-readable diffs for audit and investigation.

Types of Diffs

Example: Plan Diff

// What was planned
{
  "steps": [
    { "kind": "workflow", "ref": "create_user", "params": { "email": "jane@corp.com" } },
    { "kind": "workflow", "ref": "add_to_group", "params": { "group": "employees" } }
  ]
}

// What actually executed (step 2 skipped due to deny)
{
  "steps": [
    { "kind": "workflow", "ref": "create_user", "params": { "email": "jane@corp.com" }, "status": "completed" },
    { "kind": "workflow", "ref": "add_to_group", "params": { "group": "employees" }, "status": "denied", "reason": "policy: no_external_groups" }
  ]
}

🗄️Storage Architecture

Storage Tiers

• Hot (ClickHouse): Fast query for recent receipts (90 days). Indexed by actor, tool, decision, timestamp.
• Cold (S3 WORM): Append-only immutable storage for compliance (7 years). Write-once, read-many.
• Anchor (S3 Object Lock): Periodic chain head commits with version locking. Third-party verifiable.

📚Week 5 Review

❓Knowledge Check

📝Day 25 Checkpoint

• Understand ARIA Shield's Seven Controls
• Know how tamper-evident receipts work
• Understand hash chain integrity verification
• Can use sdk.telemetry for observability
• Can query audit logs and receipts
• Know data retention policies