Logging Context System

CONA uses a separate logging context system to enrich logs with organization and user metadata. This is intentionally kept separate from the RLS (Row-Level Security) system to avoid circular dependencies and maintain clean separation of concerns.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Request Flow                             │
└─────────────────────────────────────────────────────────────┘
                     │
                     │ Auth0 Session Retrieved
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  getAuth0Session()                                          │
│  • Validates session                                        │
│  • Initializes logging context with user.sub               │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ User Fetched from DB
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  getAuth0User()                                             │
│  • Fetches user from database                               │
│  • Updates logging context with userId                      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ Organization Context Added
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  requireAuth() / getOrganizationId()                        │
│  • Fetches organization from database                       │
│  • Updates logging context with:                            │
│    - organizationId                                         │
│    - organizationSlug                                       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ All Subsequent Logs Include Context
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  Axiom Logs                                                 │
│  • organizationId                                           │
│  • organizationSlug                                         │
│  • userId                                                   │
│  • userSub                                                  │
└─────────────────────────────────────────────────────────────┘

Why Separate from RLS?

RLS System (`packages/database/src/rls.ts`)

Purpose: Database security and multi-tenant isolation
Scope: PostgreSQL session configuration variables
Data: orgId, userId, sub (Auth0 ID)
Used by: PostgreSQL RLS policies

Logging Context (`apps/webapp/lib/logging-context.ts`)

Purpose: Enrich logs with metadata for monitoring and debugging
Scope: Request-scoped context (isolated via AsyncLocalStorage)
Data: organizationId, organizationSlug, userId, userSub
Used by: Axiom logging, middleware logging, security monitoring

Benefits of Separation

No Circular Dependencies: Logging doesn’t depend on database queries
Clean Separation of Concerns: Security (RLS) vs Observability (Logging)
Independent Evolution: Can change logging strategy without affecting RLS
Performance: Logging context is lightweight and doesn’t touch the database

API Reference

`initLoggingContext(params)`

Initialize logging context for a new request (typically called once per request).

import { initLoggingContext } from "@/lib/logging-context";

initLoggingContext({
  userSub: "auth0|123456",
  userId: "user-uuid",
  organizationId: "org-uuid",
  organizationSlug: "acme-corp",
});

`updateLoggingContext(params)`

Update specific fields in the logging context (called as more data becomes available).

import { updateLoggingContext } from "@/lib/logging-context";

// After fetching user from database
updateLoggingContext({
  userId: user.id,
});

// After fetching organization
updateLoggingContext({
  organizationId: org.id,
  organizationSlug: org.slug,
});

`getLoggingContext()`

Get the current logging context (read-only).

import { getLoggingContext } from "@/lib/logging-context";

const context = getLoggingContext();
console.log(context.organizationSlug); // "acme-corp"

Usage Examples

Middleware Logging

import { logMiddlewareRequest } from "@/lib/middleware-logger";

export async function middleware(request: NextRequest) {
  // Automatically includes logging context if available
  logMiddlewareRequest(request);
}

Logged Fields:

organizationSlug (if auth’d)
organizationId (if auth’d)
userId (if auth’d)
Request URL, method, IP, etc.

Security Event Logging

import { logSecurityEvent } from "@/lib/middleware-logger";

logSecurityEvent(request, response, {
  action: "auth_required",
  reason: "No valid session",
  blocked: true,
});

Logged Fields:

All fields from logging context
Security-specific metadata
source: "security" tag

Server Action Logging

import { log } from "@/app/lib/logger";
import { getLoggingContext } from "@/lib/logging-context";

export async function serverAction() {
  const context = getLoggingContext();
  
  await log({
    message: "Processing invoice",
    level: "info",
    metadata: {
      ...context, // Include all logging context
      invoiceId: "inv-123",
    },
  });
}

Where Context is Set

1. Authentication Flow (`auth.ts`)

getAuth0Session() - Sets userSub

initLoggingContext({
  userSub: session.user.sub,
});

getAuth0User() - Adds userId

updateLoggingContext({
  userId: user.id,
});

requireAuth() - Adds organizationId and organizationSlug

updateLoggingContext({
  organizationId,
  organizationSlug: organization.slug,
});

Best Practices

Initialize Early: Call initLoggingContext() as soon as you have the Auth0 session
Update Incrementally: Use updateLoggingContext() as more data becomes available
Read-Only Access: Always use getLoggingContext() to access context (don’t modify directly)
Request Isolation: Context is automatically isolated per-request using AsyncLocalStorage

Security Considerations

Request Isolation with AsyncLocalStorage

The logging context uses Node.js’s AsyncLocalStorage to ensure each request has its own isolated context. This prevents race conditions where concurrent requests could overwrite each other’s context. Without AsyncLocalStorage (vulnerable):

// ❌ Module-level variable - shared across all requests
let loggingContext = {};

// Request A: initLoggingContext({ userId: "user-a" })
// Request B: initLoggingContext({ userId: "user-b" }) 
// Request A logs → incorrectly tagged with user-b!

With AsyncLocalStorage (secure):

// ✅ Request-scoped storage - isolated per request
const asyncLocalStorage = new AsyncLocalStorage<LoggingContext>();

// Request A and B have separate, isolated contexts
// No race conditions or cross-contamination

Why This Matters for Security Auditing

Security events must be accurately attributed to the correct user and organization. Without proper request isolation:

Brute force detection could flag the wrong IP/user
Unauthorized access logs could show incorrect user IDs
Audit trails would be unreliable for compliance
Security incidents couldn’t be accurately investigated

AsyncLocalStorage ensures security logs are always attributed to the correct request context.

Comparison: RLS vs Logging Context

Aspect	RLS System	Logging Context
Purpose	Database security	Log enrichment
Storage	PostgreSQL session vars	AsyncLocalStorage (request-scoped)
Data	orgId, userId, sub	orgId, orgSlug, userId, userSub
Updated by	`initRlsWrapper()`	`initLoggingContext()`
Used by	PostgreSQL RLS policies	Axiom logs, middleware
Scope	Database transactions	Per-request (isolated)

Migration Notes

Prior to this system, organization slug was stored in RLS state, causing circular dependencies between logging and database layers. The new system cleanly separates these concerns: Before:

// ❌ Circular dependency
import { getRlsState } from "@/app/lib/db/rls";
const rlsState = getRlsState();
logger.info("Event", { orgSlug: rlsState.orgSlug });

After:

// ✅ Clean separation
import { getLoggingContext } from "@/lib/logging-context";
const context = getLoggingContext();
logger.info("Event", { orgSlug: context.organizationSlug });

Getting Started

Core CONA Logic

Development Setup

Guides

E2E Tests

Integrations

RFC

Logging Context

Logging Context System

Architecture

Why Separate from RLS?

RLS System (`packages/database/src/rls.ts`)

Logging Context (`apps/webapp/lib/logging-context.ts`)

Benefits of Separation

API Reference

`initLoggingContext(params)`

`updateLoggingContext(params)`

`getLoggingContext()`

Usage Examples

Middleware Logging

Security Event Logging

Server Action Logging

Where Context is Set

1. Authentication Flow (`auth.ts`)

Best Practices

Security Considerations

Request Isolation with AsyncLocalStorage

Why This Matters for Security Auditing

Comparison: RLS vs Logging Context

Migration Notes

​Logging Context System

​Architecture

​Why Separate from RLS?

​RLS System (packages/database/src/rls.ts)

​Logging Context (apps/webapp/lib/logging-context.ts)

​Benefits of Separation

​API Reference

​initLoggingContext(params)

​updateLoggingContext(params)

​getLoggingContext()

​Usage Examples

​Middleware Logging

​Security Event Logging

​Server Action Logging

​Where Context is Set

​1. Authentication Flow (auth.ts)

​Best Practices

​Security Considerations

​Request Isolation with AsyncLocalStorage

​Why This Matters for Security Auditing

​Comparison: RLS vs Logging Context

​Migration Notes

Logging Context System

Architecture

Why Separate from RLS?

RLS System (`packages/database/src/rls.ts`)

Logging Context (`apps/webapp/lib/logging-context.ts`)

Benefits of Separation

API Reference

`initLoggingContext(params)`

`updateLoggingContext(params)`

`getLoggingContext()`

Usage Examples

Middleware Logging

Security Event Logging

Server Action Logging

Where Context is Set

1. Authentication Flow (`auth.ts`)

Best Practices

Security Considerations

Request Isolation with AsyncLocalStorage

Why This Matters for Security Auditing

Comparison: RLS vs Logging Context

Migration Notes