# How Vorssaint-utils Handles Clipboard History Privacy: A Three-Layer Defense System

> Discover how Vorssaint-utils safeguards your clipboard history privacy with its three-layer defense system. Learn about pasteboard type checks, heuristic analysis, and user filters.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: deep-dive
- Published: 2026-09-12

---

**Vorssaint-utils protects sensitive data through a three-layer privacy system that checks for concealed pasteboard types, analyzes text heuristics for secrets, and respects user-configurable filters before any clipboard content reaches persistent storage.**

Clipboard history utilities risk exposing passwords, tokens, and personal identifiers, but Vorssaint-utils implements privacy-by-design safeguards written in Swift that intercept sensitive data before capture. According to the Vorssaint source code, the `ClipboardHistoryService` employs a defensive architecture ensuring secrets never reach the [`ClipboardHistory.json`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistory.json) file or in-memory store.

## The Three-Layer Privacy Architecture in Vorssaint-utils

The privacy implementation operates through distinct detection layers defined in [`Sources/Vorssaint/Services/Clipboard/ClipboardHistorySensitiveText.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Clipboard/ClipboardHistorySensitiveText.swift) and enforced by [`Sources/Vorssaint/Services/Clipboard/ClipboardHistoryService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Clipboard/ClipboardHistoryService.swift).

### Layer 1: Concealed Pasteboard Type Detection

Before reading any content, the service inspects the pasteboard's available types for a special **"concealed"** marker that password managers and secure applications set to flag sensitive payloads. The `ClipboardHistorySensitiveText.isConcealed` method (lines 99-107) checks the type array, and if the concealed type is present, the capture aborts immediately and returns `nil`.

```swift
if ClipboardHistorySensitiveText.isConcealed((pasteboard.types ?? []).map(\.rawValue)) {
    return nil
}

```

This short-circuit occurs in `ClipboardHistoryService.readPasteboard` before any data extraction begins, ensuring secret payloads never enter the processing pipeline.

### Layer 2: Heuristic Secret Detection

For text content that passes the type guard, the `looksSensitive` method (lines 13-30) applies heuristic analysis to identify strings that resemble secrets. The detection logic evaluates:
- **Keyword patterns**: Matches terms like `password`, `secret`, `token`, or `api_key`
- **URL pattern recognition**: Identifies credential-containing URI schemes
- **Structural analysis**: Detects identifier shapes and character distributions typical of high-entropy secrets
- **Length and composition**: Flags strings combining letters, digits, and symbols above configurable thresholds

### Layer 3: User-Controlled Filter

The final gate resides in `ClipboardHistoryService.promote(_:)` (lines 52-58), where the service checks the `clipboardHistorySkipSensitive` UserDefaults boolean. When enabled (the default setting), every text string passes through `looksSensitive()`; if the function returns `true`, the promotion aborts and the entry is discarded before persistence.

```swift
if UserDefaults.standard.bool(forKey: DefaultsKey.clipboardHistorySkipSensitive),
   looksSensitive(text) {
    return
}

```

## How the Privacy-Aware Capture Flow Works

The clipboard monitoring operates on a background lane to prevent UI blocking, with privacy checks occurring before any thread suspension risks. The flow follows three strict stages:

1. **Type Inspection**: `readPasteboard` validates pasteboard types against the concealed marker. If detected, the function returns early (lines 2120-2126).

2. **Content Analysis**: For plain text payloads, `promote(_:)` evaluates the user preference flag. When active, `looksSensitive` analyzes the string; flagged content is rejected immediately.

3. **Safe Persistence**: Only entries surviving both filters proceed to normalization, size checking, and insertion into the history. Sensitive data never reaches the on-disk JSON store or the in-memory `entries` list.

Because these checks execute on a background queue, even a hung pasteboard (such as during a password prompt) cannot force a secret into storage through thread blocking.

## Configuring Clipboard History Privacy Settings

Developers integrating Vorssaint-utils can programmatically control privacy behavior through UserDefaults keys defined in the service layer.

### Enabling Privacy-Aware Defaults

```swift
import Vorssaint

// Activate clipboard history
UserDefaults.standard.set(true, forKey: DefaultsKey.clipboardHistoryEnabled)

// Ensure secret detection is active (default behavior)
UserDefaults.standard.set(true, forKey: DefaultsKey.clipboardHistorySkipSensitive)

// Synchronize service state
ClipboardHistoryService.shared.syncWithPreferences()

```

### Runtime Filter Control

```swift
// Disable sensitive text filtering (not recommended for production)
UserDefaults.standard.set(false, forKey: DefaultsKey.clipboardHistorySkipSensitive)
ClipboardHistoryService.shared.syncWithPreferences()

```

### Accessing Filtered History

The public API guarantees that retrieved entries have passed all privacy checks:

```swift
let recent = ClipboardHistoryService.shared.recentEntries   // Excludes sensitive items
let pinned = ClipboardHistoryService.shared.pinnedEntries   // Safe-by-design

```

### Testing the Sensitivity Guard

Unit tests can verify the filtering behavior using the shared service instance:

```swift
import XCTest
import Vorssaint

class ClipboardPrivacyTests: XCTestCase {
    func testSensitiveTextIsRejected() {
        let service = ClipboardHistoryService.shared
        let secret = "MySuperSecretPassword123!"
        
        XCTAssertFalse(service.promote(secret))   // Early return prevents storage
        XCTAssertTrue(service.entries.isEmpty)    // History remains clean
    }
}

```

## Summary

- **Pasteboard type detection** intercepts content marked as concealed by password managers before any data extraction occurs in `ClipboardHistoryService.readPasteboard`.
- **Heuristic analysis** in `ClipboardHistorySensitiveText.looksSensitive` identifies secret-like strings through keyword matching, URL patterns, and entropy analysis.
- **User preferences** control the active filtering via `clipboardHistorySkipSensitive`, defaulting to enabled for maximum privacy.
- **Background processing** ensures privacy checks complete before UI thread interaction, preventing inadvertent storage during system hangs.
- **Zero persistence** guarantees that flagged sensitive content never reaches [`ClipboardHistory.json`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistory.json) or memory-resident entry arrays.

## Frequently Asked Questions

### How does Vorssaint-utils prevent password managers from exposing secrets?

The service checks for a special concealed pasteboard type that standard password managers set when copying sensitive data. The `isConcealed` method in [`ClipboardHistorySensitiveText.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistorySensitiveText.swift) (lines 99-107) scans the pasteboard type list, and if present, `ClipboardHistoryService` aborts the capture immediately, returning `nil` before any content is read.

### Can users disable the sensitive text filtering?

Yes, though the `clipboardHistorySkipSensitive` UserDefaults key defaults to `true`. Setting this boolean to `false` and calling `syncWithPreferences()` disables the heuristic checking in `promote(_:)`, allowing all text including potential secrets into the history. This is controlled at lines 52-58 of [`ClipboardHistoryService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistoryService.swift).

### Where does Vorssaint-utils store clipboard history entries?

Safe entries persist to [`ClipboardHistory.json`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistory.json) on disk and remain in the in-memory `entries` array maintained by `ClipboardHistoryService`. However, content flagged by the three-layer privacy system—whether through concealed type detection or `looksSensitive` heuristics—is discarded before reaching either storage mechanism.

### Does the privacy check impact application performance?

No. The Vorssaint source code implements these checks on a background lane within `readPasteboard`, ensuring that pasteboard polling and privacy validation occur off the main thread. The lightweight type array inspection and string heuristics execute in milliseconds, preventing UI blocking even when the system pasteboard is temporarily unresponsive.