# @theorchard/sentry-scrubber

Sentry data scrubbing utilities for removing sensitive information from logs and events across the Orchard Suite applications.

## Installation

```bash
pnpm add @theorchard/sentry-scrubber
```

## Usage

### Basic Setup

```typescript
import { createSentryScrubber } from '@theorchard/sentry-scrubber';
import * as Sentry from '@sentry/browser';

// Create a scrubber instance
const scrubber = createSentryScrubber({
    sensitiveFields: ['password', 'token', 'secret', 'apiKey', 'authorization'],
});

// Configure Sentry with the scrubber
Sentry.init({
    dsn: 'your-dsn-here',
    beforeSend: scrubber.beforeSendHandler,
});
```

### Advanced Configuration

```typescript
import { createSentryScrubber } from '@theorchard/sentry-scrubber';

const scrubber = createSentryScrubber({
    sensitiveFields: ['password', 'token', 'secret', 'apiKey'],
    scrubMarker: '[REDACTED]', // Custom marker for scrubbed data
    maxDepth: 5, // Maximum depth for recursive scrubbing
});
```

## Features

### Recursive Data Scrubbing

The scrubber recursively processes objects and arrays to find and scrub sensitive fields at any depth:

```typescript
const event = {
    user: {
        email: 'user@example.com',
        password: 'secret123', // Will be scrubbed
    },
    metadata: {
        settings: {
            apiKey: 'key123', // Will be scrubbed
            version: '1.0', // Will be preserved
        },
    },
};
```

### Case-Insensitive Field Matching

Field names are matched case-insensitively:

```typescript
// All of these will be scrubbed if 'password' is in sensitiveFields
{
    password: 'secret',
    Password: 'secret',
    PASSWORD: 'secret',
    PaSSwoRd: 'secret',
}
```

### JSON String Scrubbing

The scrubber can detect and scrub JSON strings within text content like error messages:

```typescript
const event = {
    message: 'Error: {"username": "user", "password": "secret123"}',
    // After scrubbing: 'Error: {"username": "user", "password": "[Scrubbed]"}'
};
```

### Depth Limiting

To prevent performance issues with deeply nested objects, you can set a maximum depth:

```typescript
const scrubber = createSentryScrubber({
    sensitiveFields: ['password'],
    maxDepth: 3, // Only process up to 3 levels deep
});
```

### Circular Reference Handling

The scrubber gracefully handles circular references without throwing errors or causing infinite loops.

## API Reference

### `createSentryScrubber(options: SentryScrubberOptions): SentryScrubber`

Creates a new SentryScrubber instance.

#### Options

-   `sensitiveFields: string[]` - Array of field names to scrub (case-insensitive)
-   `scrubMarker?: string` - Custom marker to replace sensitive data with (default: `'[Scrubbed]'`)
-   `maxDepth?: number` - Maximum depth for recursive scrubbing (default: `10`)

### `SentryScrubber`

#### Methods

-   `beforeSendHandler(event: any, hint?: any): any` - Sentry beforeSend callback that scrubs sensitive data from events

## Examples

### With React Error Boundary

```typescript
import { createSentryScrubber } from '@theorchard/sentry-scrubber';
import * as Sentry from '@sentry/browser';

const scrubber = createSentryScrubber({
    sensitiveFields: [
        'password',
        'token',
        'secret',
        'apiKey',
        'authorization',
        'cookie',
        'session',
    ],
});

Sentry.init({
    dsn: process.env.SENTRY_DSN,
    beforeSend: scrubber.beforeSendHandler,
    environment: process.env.NODE_ENV,
});
```

### Custom Scrub Marker

```typescript
const scrubber = createSentryScrubber({
    sensitiveFields: ['password', 'token'],
    scrubMarker: '***HIDDEN***',
});

// Result: { password: '***HIDDEN***' }
```

### Performance Optimized

```typescript
const scrubber = createSentryScrubber({
    sensitiveFields: ['password', 'token'],
    maxDepth: 3, // Limit depth for better performance
});
```

## TypeScript Support

This package is written in TypeScript and includes full type definitions. No additional `@types` packages are needed.

## Contributing

This package is part of the Orchard Suite monorepo. Please refer to the main repository for contribution guidelines.