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

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 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 and enforced by 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.

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.

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

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

// 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:

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:

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 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 (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.

Where does Vorssaint-utils store clipboard history entries?

Safe entries persist to 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}