​

Authorization Logging For Audit Trail

The @repo/auth-log package provides a simple yet powerful way to log and monitor authorization attempts in your application. It integrates seamlessly with the authorization packages to create an audit trail of access control decisions.

​

Overview

Authorization logging is a critical component of security monitoring and compliance. The @repo/auth-log package allows you to:

• Track authorization decisions: Log whether access was granted or denied
• Record contextual information: Capture user, resource, and action details
• Customize logging destinations: Output to console or file
• Support compliance requirements: Maintain audit trails for regulatory needs

​

Installation

The package is included by default in the zopio stack. If you need to install it separately:

pnpm add @repo/auth-log

​

Basic Usage

The auth-log package is designed to work seamlessly with the authorization packages:

import { logAccessAttempt } from '@repo/auth-log';

// Log an authorization attempt
logAccessAttempt({
  timestamp: new Date().toISOString(),
  resource: 'article',
  action: 'read',
  context: { userId: '123', role: 'editor', tenantId: 'org-456' },
  recordId: '789',
  can: true
});

​

Configuration

By default, logs are output to the console. You can configure the logging destination by setting the AUTH_LOG_TARGET environment variable:

# Log to console (default)
AUTH_LOG_TARGET=console

# Log to file
AUTH_LOG_TARGET=file

# Log to BetterStack
AUTH_LOG_TARGET=betterstack
BETTERSTACK_SOURCE_TOKEN=your_source_token

When logging to a file, entries are appended to ./logs/access.log by default.

When using BetterStack, you’ll need to provide your source token via the BETTERSTACK_SOURCE_TOKEN environment variable.

​

Log Format

Each log entry contains the following information:

• timestamp: When the authorization attempt occurred
• resource: The resource being accessed (e.g., ‘article’, ‘user’)
• action: The action being performed (e.g., ‘read’, ‘update’)
• context: User context information (userId, role, tenantId)
• recordId: Optional ID of the specific record being accessed
• field: Optional field name for field-level permissions
• can: Boolean indicating whether access was granted
• reason: Optional explanation for why access was denied

​

Integration with Authorization Packages

The auth-log package is automatically integrated with the auth-runner package, which means all authorization checks performed through the runner will be logged without additional configuration.

import { evaluateAccess } from '@repo/auth-runner/engine/evaluate';

// This will automatically log the access attempt
const result = evaluateAccess({
  context: { userId: '123', role: 'editor', tenantId: 'org-456' },
  resource: 'article',
  action: 'update',
  record: { id: '789', ownerId: '123' }
});

​

Available Adapters

​

Console Logger

The default adapter that outputs logs to the console:

// Set via environment variable
AUTH_LOG_TARGET=console

​

File Logger

Writes logs to a file on disk:

// Set via environment variable
AUTH_LOG_TARGET=file

​

BetterStack Logger

Sends logs to BetterStack’s logging service for centralized log management:

// Set via environment variables
AUTH_LOG_TARGET=betterstack
BETTERSTACK_SOURCE_TOKEN=your_source_token

The BetterStack adapter enriches logs with additional metadata:

• Sets log level to “info” for allowed access and “warn” for denied access
• Creates a formatted message for better readability
• Adds a service name for easier filtering

​

Custom Adapters

You can create custom logging adapters by implementing the logger interface:

const customLogger = {
  write: (entry: AccessLogEntry) => {
    // Custom logging logic here
    // e.g., send to a third-party service
  }
};

// Then register your custom logger in config.ts
export function getActiveLogger() {
  // Add your custom logger condition here
  if (process.env.AUTH_LOG_TARGET === "custom") {
    return customLogger;
  }
  
  // Existing conditions...
}

​

Best Practices

1. Log all authorization attempts: Enable comprehensive logging for security audits
2. Monitor denied access: Pay special attention to denied access attempts
3. Rotate log files: Implement log rotation for file-based logging
4. Protect sensitive information: Be careful not to log sensitive user data
5. Review logs regularly: Set up a process to review authorization logs