Core Concepts

Understanding the foundational concepts behind Trailbase's audit logging, RBAC, compliance automation, and security architecture.

Audit Events

Audit events are the fundamental building blocks of Trailbase. Each event captures a single action performed by an actor on a resource, along with the outcome and contextual metadata.

Event Structure

Every audit event consists of four core components:

Event Schema Example

{
  "event_id": "evt_9k2j8h3n",
  "event_time": "2026-02-10T14:32:15Z",
  "tenant_id": "tenant_acme",
  "action": "document.share",
  "actor": {
    "id": "user_alice",
    "email": "alice@acme.com",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0..."
  },
  "resource": {
    "type": "document",
    "id": "doc_q5w8r9"
  },
  "outcome": "success",
  "metadata": {
    "shared_with": "bob@acme.com",
    "permission": "read",
    "expiry_days": 7
  }
}

Best Practices

• Use consistent action naming: Follow a resource.verb pattern (e.g., user.create, invoice.export)
• Include all context in metadata: Store details that help reconstruct the event later (e.g., changed fields, reason for action)
• Log both successes and failures: Track authorization denials and error conditions
• Keep metadata under 64KB: Avoid storing large binary data; use references instead
• Use resource IDs consistently: Maintain the same ID format across your application

RBAC Model

Trailbase's Role-Based Access Control (RBAC) engine provides resource-level permission checks with a transparent decision graph for every authorization request.

Core Entities

Subjects

Subjects are users or roles that can be granted permissions. A subject can be:

• USER: Individual user account (e.g., user_alice)
• ROLE: Named role containing multiple users (e.g., admin, editor)

Resources

Resources are entities in your system that require access control:

{
  "type": "document",
  "id": "doc_q5w8r9"
}

Resources can have parent-child relationships for hierarchical permissions (e.g., a document belongs to a folder).

Permissions

Permissions define what actions can be performed. Common patterns:

• document:read - View a document
• document:write - Edit a document
• document:delete - Delete a document
• document:share - Share a document with others

Grants

Grants explicitly assign permissions to subjects on specific resources:

{
  "subjectType": "USER",
  "subjectId": "user_alice",
  "permissionKey": "document:write",
  "resourceType": "document",
  "resourceId": "doc_q5w8r9"
}

Decision Order

When evaluating a permission check, Trailbase follows this priority order:

1. Direct Grant: Explicit grant on the exact resource
2. Parent Grant: Grant on a parent resource (if provided)
3. Role Permission: Default permission assigned to user's roles
4. Deny: No applicable grant found

Example: Permission Check

const decision = await trailbase.decide({
  actor: 'user_alice',
  permission: 'document:delete',
  resource: {
    type: 'document',
    id: 'doc_q5w8r9'
  },
  parentResource: {
    type: 'folder',
    id: 'folder_projects'
  }
});

// Response:
{
  "allow": true,
  "reasonCode": "parent_grant",
  "explain": {
    "type": "check",
    "label": "Evaluate: document:delete on document/doc_q5w8r9",
    "passed": true,
    "children": [
      {
        "type": "check",
        "label": "Direct grant on document/doc_q5w8r9",
        "passed": false
      },
      {
        "type": "check",
        "label": "Parent grant on folder/folder_projects",
        "passed": true,
        "children": [
          {
            "type": "result",
            "label": "Found: USER:user_alice",
            "passed": true
          }
        ]
      }
    ]
  }
}

Compliance Frameworks

Trailbase automates compliance checks for major security frameworks, validating that your audit logs meet certification requirements.

Supported Frameworks

SOC 2

Trailbase validates the following SOC 2 Trust Service Criteria:

• CC6.1: System operations are monitored (event ingestion health)
• CC6.2: Audit logs are retained for 365+ days
• CC6.3: Access is logged and monitored (actor tracking)
• CC7.2: Hash chain integrity is maintained

HIPAA

Health Insurance Portability and Accountability Act requirements:

• §164.312(b): Audit controls are implemented
• §164.308(a)(1)(ii)(D): Information system activity review
• §164.312(c)(2): Audit logs include actor identification

GDPR

General Data Protection Regulation compliance:

• Article 32: Ability to ensure confidentiality and integrity
• Article 33: Breach detection and notification readiness
• Article 30: Records of processing activities (audit trail)

Running Compliance Checks

const results = await trailbase.runComplianceCheck('SOC2');

// Response:
{
  "framework": "SOC2",
  "passed": true,
  "score": 100,
  "checks": [
    {
      "control": "CC6.1",
      "passed": true,
      "message": "Event ingestion is active and healthy"
    },
    {
      "control": "CC6.2",
      "passed": true,
      "message": "Retention policy: 730 days (exceeds requirement)"
    }
  ]
}

Retention Tiers

Trailbase manages audit logs across three storage tiers to balance performance, cost, and compliance.

Logs automatically transition between tiers based on your retention policy. Compliance checks ensure that required logs are retained for the appropriate duration.

Webhooks and Alerts

Trailbase can notify your systems in real-time when specific events occur or thresholds are exceeded.

Event Types

• audit.event.received: Triggered when an event is successfully ingested
• alert.triggered: Fired when an alert rule matches
• compliance.check.failed: Sent when a compliance check doesn't pass
• integrity.violation: Critical alert if hash chain is broken

Delivery Guarantees

• At-least-once delivery: Webhooks are retried up to 5 times with exponential backoff
• Idempotency tokens: Each webhook includes a unique webhook_id to prevent duplicate processing
• Signature verification: HMAC-SHA256 signature in X-Trailbase-Signature header

Retry Logic

Attempt 1: Immediate
Attempt 2: +30 seconds
Attempt 3: +2 minutes
Attempt 4: +10 minutes
Attempt 5: +1 hour (final)

Security Architecture

Trailbase's security guarantees are built on cryptographic primitives and immutable data structures.

Hash Chain

Every audit event is linked to the previous event via a SHA-256 hash chain:

Event N:
  - event_id: evt_n
  - data: {...}
  - prev_hash: hash(Event N-1)
  - hash: SHA-256(event_id + data + prev_hash)

This creates an immutable, tamper-evident log. If any event is modified or deleted, the chain breaks and verification fails.

Integrity Verification

You can verify the integrity of your audit logs at any time:

const integrity = await trailbase.verifyChain();

// Response:
{
  "status": "valid",
  "verified_count": 128503,
  "last_hash": "4f2a8c1d9b3e7a5f2c8d1e9b4a7c3f1d",
  "tenant_id": "tenant_acme"
}

Encryption

• In Transit: All API requests use TLS 1.3
• At Rest: PostgreSQL and S3 storage encrypted with AES-256
• API Keys: Hashed with bcrypt, never stored in plaintext
• Metadata: Can be encrypted client-side before sending (optional)

Access Control

• API Key Scopes: Keys can be restricted to read-only or specific resources
• IP Allowlisting: Restrict API access to specific IP ranges
• Rate Limiting: 1000 requests/minute per tenant (configurable)
• Audit on Audit: All API access is logged to a separate system audit log