DEV Community: freerave

DotShare AI 3.5.2: From Git Tags to Technical Articles You Can Review

freerave — Thu, 08 Oct 2026 10:51:14 +0000

A deep dive into DotShare 3.5.2: release-aware AI articles, verified code excerpts, Dev.to live preview, and safer credential handling.

An AI release article can sound convincing while describing code that never shipped.

The failure is often subtle: a changelog comes from one version, source code comes from today's checkout, and an example gets rewritten into something that looks cleaner but no longer matches the implementation. By the time the article reaches the publishing screen, the facts have already drifted.

DotShare AI 3.5.2 makes release selection, implementation evidence, and article review part of the writing workflow. It adds a dedicated Dev.to article experience, strengthens the generation pipeline, and revises how credentials move between the extension host, its webviews, and the CLI.

The work behind this update spans 65 changed or new files, including implementation, tests, documentation, dependency manifests, and build configuration. The useful result is what those changes let a developer do: choose a version, generate a technical draft from that version, inspect its formatting and code, and publish with a clearer understanding of what was checked.

What changes in the daily workflow?

DotShare already brings social and blog publishing into the editor. Version 3.5.2 expands the technical writing side of that workflow:

Area	Behavior in this update
Release selection	Choose a committed release, current committed work at HEAD, or tracked uncommitted changes explicitly.
Implementation context	Read release material from one resolved commit and include source excerpts with file and line information.
Article generation	Generate a Markdown draft with metadata, validate it, and use a bounded repair pass when needed.
Code examples	Verify excerpts against supplied source or documentation; flag and omit remaining unverifiable examples when the rest of the draft passes.
Dev.to review	Preview the title, description, tags, and rendered body together.
Saved credentials	Show 🔒 Key Saved & Active, with an empty replacement field available on demand.
CLI configuration	Store supported platform credentials in the OS credential store and keep preferences in the configuration file.

The developer still owns the final editorial decision. The checks make specific problems detectable; they do not establish the truth of every sentence an AI writes.

1. A release article needs a consistent version of the project

The first architectural change is the release boundary.

ReleaseRepository resolves the selected Git reference to a commit. That snapshot is then used for metadata, changelog content, release documents, source files, diffs, commits, and dependency comparisons. Reading these inputs from the same snapshot prevents a tagged release article from accidentally describing later local edits.

The distinction becomes visible in the UI:

Committed release describes the selected tagged version.
Current committed work (HEAD) can describe committed changes beyond the latest tag.
Uncommitted changes describes tracked local edits as work in progress.

For example, if a repository contains a v2.1.2 tag and additional edits in the checkout, selecting v2.1.2 keeps those edits out of the release article. Choosing HEAD or uncommitted changes communicates a different scope.

The collector also explains incomplete history. A first tagged release without a previous release tag can include the complete committed tree. In an untagged repository, the committed comparison can be limited to the latest commit. Warnings help the author understand the material behind the draft instead of guessing from the version label.

Context is refreshed before generation, so an earlier modal preview is not silently treated as the final evidence set.

2. Workspace search follows the topic and the release boundary

A useful technical article needs more than the last few commit messages.

The context service can search Git history for terms from the selected topic. It combines commit-message matching with Git pickaxe searches for relevant code changes. Keyword extraction handles English and Arabic input, filtering conversational words so the search can focus on technical terms.

The same selected boundary also governs dependency comparisons. DotShare recognizes manifests for several ecosystems:

Ecosystem	Manifest
Node.js	`package.json`
Rust	`Cargo.toml`
Python	`pyproject.toml`
Go	`go.mod`

That lets an article distinguish a dependency upgrade in the chosen release from an unrelated edit in the current checkout.

Documentation adds another layer. Version-specific release files and relevant architecture or security documents can explain why a change exists. Multiline changelog notes are preserved so their meaning does not collapse into a handful of isolated bullets.

The collector limits document and source budgets and reports truncation. A truncated README is a visible limitation, not evidence that the entire document was reviewed. Architecture notes provide background; roadmap items do not establish that a feature has shipped. A verification document can also contain checks that remain unfinished, and the article should retain that distinction.

Active editor context is optional. A selected fragment can help identify the topic, but a local selection is labeled as a working-tree hint when writing about a committed release. It does not replace source read from the selected commit.

3. Code examples come from implementation excerpts

Technical articles are especially vulnerable to invented examples. A plausible function name or a convincing security check is easy to generate and hard to spot during a quick read.

DotShare now extracts source excerpts around added executable lines. The extractor looks for enclosing declarations and supplies the file path, line range, and whether the excerpt is partial. Ranking uses the release terms, identifiers, and changed code, while supporting helper or lifecycle methods can give a change the context it needs.

This is bounded source extraction using language-aware heuristics. It is not a full compiler analysis of every supported language.

The collector also reduces prompt noise by excluding material such as lockfiles, binary files, minified bundles, and test code from implementation examples. Python handling distinguishes executable changes from docstrings and test-oriented material.

After generation, a separate verifier checks fenced examples. Implementation examples must match a contiguous excerpt from the supplied evidence. Display normalization allows line-ending differences and a uniform dedent while preserving internal indentation, string literals, and the actual statements.

Reconstructing a function, inserting explanatory comments into its body, or joining unrelated pieces into a new example does not satisfy that rule.

Documentation examples and shell commands have their own evidence rules. Commands must be supported by supplied documentation or fit a narrow recognized checkout workflow. Changing a fence label to text does not provide a route around provenance checking.

Code is optional. An article that explains a supported change clearly can be more useful than one padded with an invented implementation.

4. Validation and repair have a defined stopping point

The generation flow has three main stages: create a draft, check detectable problems, and repair when necessary.

ReleaseContentValidator checks problems including:

Empty output and unfinished code fences.
Unsupported fenced code examples.
URLs outside the exact selected call-to-action links.
Source paths that do not appear in supplied evidence.
Certain numeric claims about tests or diff statistics without supporting material.
Missing or invalid Dev.to metadata.
A generated draft that incorrectly sets published: true.
Release prose that mixes in uncommitted work or exposes internal writing instructions.

The service makes at most two generation attempts. A validation problem can trigger one repair using the same evidence. The previous generated draft is identified as untrusted text rather than new evidence.

There is also a bounded recovery path for a response that reaches its output limit. A retry with a larger budget uses the remaining attempt; it does not start an unlimited series of retries and repairs.

Full Dev.to articles begin with a 6,000-token generation budget. The output-limit recovery can increase that budget up to 12,000 tokens. Technical deep dives and shorter posts use smaller budgets appropriate to their format. These are response budgets, not promises of an exact article length.

When an example still cannot be verified

Earlier behavior could end the entire generation flow with a code-validation error even when most of the article was usable.

The revised behavior is more precise. If the second attempt still contains closed, unverifiable code blocks, DotShare can omit those blocks and validate the remaining article again. When that article passes, the author receives a visible warning such as:

Omitted 1 code example(s) that could not be verified against the supplied evidence. Review the surrounding explanation before publishing.

A short standalone introduction to an omitted example can be removed with it. Other prose remains available for review.

The warning matters: removing a code block does not prove the neighboring explanation is correct. An unfinished fence, an unsupported URL, or another unresolved blocking error still prevents a successful result.

5. Provider completion is part of article quality

A successful HTTP request does not necessarily contain a complete article.

This update strengthens response handling across OpenAI, Claude, Gemini, DeepSeek, and xAI. Empty text is rejected, and provider-specific completion signals are checked before returning a draft.

Provider	Completion handling
OpenAI	Detect incomplete Responses API output and distinguish output-limit truncation.
Claude	Combine text blocks and detect token-limit stops or refusal.
Gemini	Check candidate finish reasons, including output-token exhaustion.
DeepSeek	Check completion finish reasons and reject empty content.
xAI	Check completion finish reasons and reject empty content.

Generation requests have explicit timeouts, and SDK retry settings are bounded where configured. The author gets an error for an incomplete response instead of a truncated article presented as finished.

Live model discovery remains the foundation introduced in the previous release. The improvements here build on it with stronger response handling and safer reuse of saved keys. Provider/model request identifiers also help prevent an older asynchronous response from replacing a newer selection in the UI.

6. Dev.to articles arrive as editable Markdown

The Dev.to workflow now has a dedicated DotShare AI Article action and a Full Article (Dev.to) writing tone. The result is Markdown with YAML frontmatter, ready to inspect and edit.

DotShare parses the metadata into separate publisher fields:

Title.
Description.
Tags, normalized and limited to four.
Optional cover image, canonical URL, and series when supplied.

The frontmatter is separated from the article body so the editor does not show metadata as prose. Generated content also receives publishing cleanup, including redundant opening titles and trailing hashtag lines where appropriate.

The article title belongs in the title field. Body sections can start at ##, which keeps the hierarchy consistent with Dev.to's article page. This follows the conventions in the DEV Editor Guide.

Canonical URLs receive special treatment: a repository URL is not automatically used as the article's canonical URL. The repository identifies the project; a canonical URL identifies the original publication of the same article. Authors can add that field when it actually applies.

The publisher retains both draft and publishing choices. Generating text is separate from deciding to publish it.

7. Live Preview includes the whole article header

Reviewing only the Markdown body misses part of the reader's first impression.

The updated Live Preview displays title, description, tags, then the article body, using the current editor values. Changes to the metadata fields update the preview without another AI request. Direction-aware text also helps with Arabic and mixed-language content.

marked renders the body and DOMPurify sanitizes the resulting HTML. The title, description, and tag labels are inserted as text rather than interpreted as HTML. The preview supports familiar Markdown structures such as headings, lists, tables, blockquotes, and fenced code blocks, with code styling suitable for review.

The UI includes word count, character count, and estimated reading time. They help authors judge the size of a draft without treating length as a measure of correctness.

Related webview changes escape content in thread composers, media thumbnails, draft cards, and scheduled-post attributes. Custom publish-button labels also survive UI refreshes.

Links respect the editor's decision

Web links appear blue and can be clicked during review. The webview sends an opening request to the extension host, which accepts ordinary HTTP or HTTPS URLs and calls the editor's external-link API.

This is the implementation in src/services/PreviewLinkService.ts:

export async function openArticlePreviewLink(value: unknown): Promise<boolean> {
    const url = getPreviewWebUrl(value);
    if (!url) return false;
    try {
        // Respect VS Code's result; a refusal must not trigger an alternate opener.
        return await vscode.env.openExternal(vscode.Uri.parse(url));
    } catch {
        return false;
    }
}

If opening is declined or throws an error, the action stops. There is no alternate opener. Local resources and command URLs are not accepted as external article links. In-article anchors are handled within the preview.

8. Saved keys stay on the extension host

Credential storage needed a review across the full workflow: platform configuration, AI model selection, saved API sets, migration, logging, and cleanup.

The extension uses context.secrets for sensitive values. That includes the Dev.to API key and the supported AI-provider keys. The browser-based webviews receive saved-status information instead of stored key values.

The status helper in src/security/credentials.ts returns booleans:

export async function credentialStatus(secrets: vscode.SecretStorage): Promise<Record<string, boolean>> {
    const status: Record<string, boolean> = {};
    for (const key of ALL_SECRET_KEYS) status[key] = !!await secrets.get(key);
    return status;
}

The UI shows 🔒 Key Saved & Active. It does not populate the old key into the field, even as a masked value. Change saved key reveals an empty replacement input, and leaving it blank retains the saved value.

Newly typed replacements necessarily pass through the input while the user is editing them. The important separation is that stored keys are not sent back from the extension host to fill the webview. Successful save acknowledgements clear replacement fields; closing the AI dialog discards pending replacements.

Saved AI keys can be reused for model discovery and generation without retyping them. A successful model-list request alone is not treated as proof that a new key was saved, and save failures do not receive a success acknowledgement.

Saved API configurations follow the same design. The host activates the selected credentials, while the UI gets metadata such as the configuration name and whether credentials are available. Snapshots are created from credentials already held on the host.

A saved key is scoped to its editor

VS Code and a separate editor application such as Antigravity have separate application storage. A key saved by DotShare in VS Code is not automatically available in DotShare running inside another editor.

The same key can be entered and saved in that editor separately. An empty saved-key status there does not, by itself, show that VS Code lost its stored key.

The extension relies on the host's SecretStorage implementation and its available storage backend. VS Code documents its API in the SecretStorage reference and Linux keyring configuration in its credential-storage troubleshooting guidance.

9. Migration and cleanup cover the credential lifecycle

Moving future writes into secure storage is only part of a migration. Older plaintext copies can remain behind.

The update migrates saved API configurations for every supported platform, including Dev.to. When a newer secure copy already exists, it is preserved and the stale legacy copy is removed. When no secure copy exists, the secure write precedes deletion of the old state.

Migration also handles the previous Discord webhook storage name and legacy API keys inside saved model-selection state. Model preferences can remain as preferences without retaining the key in ordinary state.

Local credential clearing covers platform keys, AI keys, GitHub and DotShare account secrets, saved configuration lists, relevant model preferences, and remembered cloud-sync consent. The UI receives cleanup notifications so the displayed state can follow the host.

Local cleanup is not cloud revocation. Credentials previously uploaded for scheduling must be revoked separately through the cloud service. That distinction is now stated in the user-facing security documentation.

10. The CLI stores credentials in the OS credential store

The extension's storage changes also exposed a separate CLI concern: a preferences file should not double as a credential vault.

The CLI now uses @napi-rs/keyring through a dedicated credential-store adapter. Its supported Telegram and LinkedIn credentials are stored under the DotShare CLI service in the native OS credential store.

The JSON configuration file contains preferences such as the server URL and default platforms. It is written through a temporary file and renamed, with a restrictive file mode requested on platforms that honor it. Credentials are read from the credential store when a command needs them.

For older configurations, the migration writes credentials to the native store before replacing the configuration with metadata. An existing secure value takes precedence over an older file copy. If keyring access fails, migration stops without erasing the legacy file or falling back to a new plaintext credential write.

The setter in src/cli/credential-store.ts makes the failure behavior explicit:

    set(platform: string, value: string): void {
        try {
            rememberSecret(value);
            new Entry('DotShare CLI', platform).setPassword(value);
        } catch {
            throw new Error('Could not save credentials in the OS keyring. No plaintext fallback was used.');
        }
    }

CLI logging is separated from VS Code-dependent logging, so command-line diagnostics can use redaction without requiring the editor runtime.

11. Logs and cloud sync have narrower, clearer behavior

This update removes sensitive logging of complete OAuth callback URLs and credential values from the reviewed paths. A shared redaction layer remembers secrets obtained from or written to SecretStorage and masks known values and common token patterns in diagnostic messages. Snippet sanitization also reduces the chance of common credential formats entering external AI requests.

Git commands use execFile with structured argument arrays. That avoids shell interpretation of topic text and path arguments and improves handling of platform-specific quoting. It is a concrete protection for Git subprocess calls, not a general claim that all inputs are safe.

Cloud scheduling has an explicit boundary as well. Credential synchronization checks saved user consent and requires HTTPS before reading local credentials for upload. Consent text explains that the server receives credentials to run scheduled posts.

The security documentation no longer presents unverified backend encryption claims as guarantees. Local SecretStorage protects the local workflow; it does not establish how a deployed server stores its copy.

Redaction and migration also have practical limits. Pattern matching cannot identify every possible secret, historical logs are not automatically rewritten, and removing a local copy does not rotate a token that was previously exposed.

12. The saved-key controls now follow the editor theme

The saved-state design should look deliberate, too.

The Change saved key control now has a dedicated CSS class in both the sidebar and the AI modal. It uses VS Code theme colors, rounded borders, a hover state, and a visible keyboard-focus outline. Hidden controls stay hidden through the CSS rule as well as their UI state.

That fixes the unstyled native button previously shown beside the saved-key badge and makes credential replacement fit the rest of the extension.

13. Build and test changes support the release

The update targets VS Code ^1.90.0, with matching API type definitions. Build, webview type-checking, lint configuration, dependency manifests, and packaging exclusions were adjusted alongside the implementation. Development artifacts and source-only material are excluded from the packaged extension where configured.

The automated suite was rerun for this article: 157 tests passed across 17 suites.

The coverage includes release boundaries and evidence extraction, generation validation and repair, provider completion signals, preview-link handling, credential status and migration, AI-key behavior, redaction, cloud-consent checks, and CLI configuration migration.

Those tests exercise deterministic behavior and mocked integrations. Native keyring persistence across an editor restart, live provider responses, Dev.to publishing, and deployed backend behavior remain separate integration checks. The passing suite is evidence for the tested implementation paths, not a production security certification.

Install or download DotShare

Install from the Visual Studio Marketplace.
Install from Open VSX in editors that use that registry.
Download the latest available VSIX from the Marketplace for manual installation.

To install the downloaded file, open the Extensions view, select Install from VSIX… from its menu, and choose the package. Check that the installed version is 3.5.2 to use the behavior described in this article; the latest version available can differ between registries while an update is being published.

Try the article workflow on a real release

Start with a project that has useful release notes and a committed version to describe:

Save an AI-provider key and choose an available model in DotShare.
Open the Dev.to Article Publisher and select DotShare AI Article.
Choose the release scope and version deliberately.
Enable the relevant changelog and Git sources, and add an optional topic or editor hint.
Choose Full Article (Dev.to), language, selected links, and whether to include verified code excerpts.
Generate the draft and inspect any context or validation warnings.
Review the title, description, tags, links, and body in Live Preview.
Save a Dev.to draft, make the final editorial edits, and publish when ready.

DotShare 3.5.2 puts the version, the evidence, and the draft in the same workflow. It helps authors spend their review time on the actual explanation: what changed, why it matters, and what the implementation supports.

The code is available in the DotShare repository. Which part of writing release articles costs you the most time: finding the changes, explaining the implementation, or preparing the final post?

DotGhostBoard 2.1 'Leviathan' — Cryptographic Vault Backups, Secret Expiry & Password History (Part 2)

freerave — Tue, 06 Oct 2026 13:20:28 +0000

A deep-dive into DotGhostBoard 2.1's security layer: AES-256-GCM .vault backup packages with AAD header authentication, CSPRNG password generation with keyspace entropy, secret expiration tracking, and encrypted version history with safe revert.

Most local password managers have a backup problem: export to unencrypted CSV and you have a plaintext credential dump sitting on your disk. Use proprietary cloud sync and you've handed your secrets to a third party. Neither is acceptable.

In Part 1, we covered the productivity layer of DotGhostBoard 2.1 — smart auto-tagging and contextual clipboard actions running locally in under 1ms for typical payloads (< 5KB).

This part is about security architecture: what happens when you need to safely move, store, expire, and rotate credentials.

Here's what we're covering:

Standalone .vault Encrypted Backup Packages (with AAD header authentication)
CSPRNG Password & Token Generator with Live Keyspace Entropy
Secret Expiry Tracking & Dynamic Warning Badges
Encrypted Password Version History with Safe Revert
Vault-to-Dashboard Plaintext Sweep & Its Practical Boundaries
Unified UX Polish & Ergonomics

1. Encrypted Vault Backups: The `.vault` Package Format

The goal was simple: export your entire Vault as a single portable file that contains zero unencrypted secret bytes — safe to copy to a USB drive, upload to a personal server, or store offsite.

The result is the .vault format (core/security/vault/backup.py), a compact binary package:

+---------------+---------------+---------------+---------------+---------------+
| Magic Header  | Version       | Salt          | Nonce         | Payload + Tag |
| "DGBV"        | 0x01          | 16 bytes      | 12 bytes      | Ciphertext +  |
| (4 bytes)     | (1 byte)      | os.urandom    | AES-GCM       | 16B GCM Tag   |
+---------------+---------------+---------------+---------------+---------------+

The Cryptographic Stack

Layer	Implementation
Cipher	AES-256-GCM (authenticated encryption with AAD)
Key derivation	PBKDF2-HMAC-SHA256, 100,000 rounds
Salt	16-byte random, per-export (`os.urandom(16)`)
Nonce	12-byte random, per-export (`os.urandom(12)`)
Associated Data (AAD)	5-byte header (`MAGIC + VERSION`) authenticated into the GCM tag
Authentication	128-bit GCM tag — tampering with ciphertext, nonce, or header fails cleanly

Here's the core export logic, lightly abbreviated:

# core/security/vault/backup.py (simplified)
import os, json
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

MAGIC   = b"DGBV"
VERSION = b"\x01"
KDF_ITER = 100_000

def export_vault(secrets: list[dict], passphrase: str) -> bytes:
    salt  = os.urandom(16)
    nonce = os.urandom(12)
    header_aad = MAGIC + VERSION

    # Derive 256-bit key from passphrase
    kdf = PBKDF2HMAC(hashes.SHA256(), length=32, salt=salt, iterations=KDF_ITER)
    key = kdf.derive(passphrase.encode())

    # Serialize payload entirely in-memory — never touches disk
    plaintext = json.dumps(secrets, ensure_ascii=False).encode()

    # AES-256-GCM: encrypt payload and authenticate format header via AAD
    ciphertext = AESGCM(key).encrypt(nonce, plaintext, header_aad)

    # Return complete package (16-byte GCM tag is appended to ciphertext by AESGCM)
    return header_aad + salt + nonce + ciphertext

And importing reverses the process — with AEAD integrity verification happening before any payload parsing or database operations:

def import_vault(data: bytes, passphrase: str) -> list[dict]:
    if not data.startswith(MAGIC):
        raise ValueError("Not a valid .vault file")
    if len(data) < 5 or data[4] != 1:
        raise ValueError("Unsupported .vault backup version")

    header_aad = data[:5]
    salt, nonce, ciphertext = data[5:21], data[21:33], data[33:]

    kdf = PBKDF2HMAC(hashes.SHA256(), length=32, salt=salt, iterations=KDF_ITER)
    key = kdf.derive(passphrase.encode())

    # Decrypt and authenticate: raises InvalidTag if ciphertext, passphrase,
    # or header bytes (MAGIC/VERSION) were tampered with
    plaintext = AESGCM(key).decrypt(nonce, ciphertext, header_aad)
    return json.loads(plaintext)

Why Associated Authenticated Data (AAD)?

Passing MAGIC + VERSION as AAD cryptographically binds the cleartext header to the payload's 128-bit authentication tag. Without AAD, an attacker could flip the version byte undetected by the cipher until application-level parsing. With AAD, modifying even a single bit in the header or ciphertext triggers an immediate InvalidTag rejection by the cipher.

What Gets Exported

Everything: active secrets, categories, creation/update timestamps, expiration dates, and the last 3 encrypted version history entries. Full Vault state in one file.

Built-in duplicate skipping (overwrite_existing=False) on import means re-importing an old backup won't create duplicates in your live Vault.

On PBKDF2 iteration count: 100,000 rounds is a responsive baseline across diverse Linux hardware, including low-power ARM boards. Argon2id support and user-configurable iteration scaling are on the v2.2 roadmap.

Figure 1: Standalone .vault backup export dialog showing PBKDF2 passphrase derivation, AES-256-GCM encryption parameters, and live Vault drawer state.

2. CSPRNG Password & Token Generator

Generating credentials inside a clipboard manager means you stay in one tool. No tab-switching to a web generator, no pasting between windows.

The generator is embedded directly inside the Add/Edit Secret dialog (ui/vault/secret_dialog.py):

[ ⚡ Generate Password / Token ]
├── CSPRNG Source: Python secrets module (/dev/urandom)
├── Character Pools: [✓] a-z  [✓] A-Z  [✓] 0-9  [✓] Symbols
├── Length Slider: 8 ──────────●─────── 64  (default: 20)
├── Token Presets: Hex | UUIDv4 | Base64 | Bearer | URL-Safe
└── Entropy Meter: [████████████████████] 131.1 bits — Fort Knox

The Entropy Calculation

Instead of an arbitrary "password strength checklist," we display theoretical keyspace entropy:

H = L × log₂(N)

Where:

L = character length
N = active pool size (e.g., a-z + A-Z + 0-9 + symbols = 94 characters)

# ui/vault/secret_dialog.py (simplified)
import math

def keyspace_entropy(length: int, pool_size: int) -> float:
    """Theoretical bits of entropy for a uniformly random credential."""
    if pool_size < 2:
        return 0.0
    return length * math.log2(pool_size)

def entropy_label(bits: float) -> str:
    if bits < 40:   return "Weak"
    if bits < 60:   return "Moderate"
    if bits < 80:   return "Strong"
    return "Fort Knox"

The meter updates live as you drag the slider or toggle character pools. A 20-character password using the full 94-character pool yields 131.1 bits of keyspace entropy (20 × log₂(94)) — comfortably above the 80–128-bit range generally considered strong for random credentials.

Keyspace entropy across the stack: Both the auto-tagger in Part 1 and the generator here use the same keyspace entropy formula (H = L × log₂(N)). The difference is in application: the auto-tagger estimates the character pool of existing clipboard text to detect high-entropy tokens, while the generator computes the exact strength of newly generated passwords from user-selected pools.

Figure 2: Built-in CSPRNG Password & Token Generator showing character pool toggles, 20-character length slider, and live keyspace entropy evaluation (Strong ~131 bits).

3. Secret Expiry Tracking & Dynamic Badges

Temporary credentials — staging tokens, contractor access keys, short-lived API secrets — have an expiration date. Most password managers ignore this.

DotGhostBoard 2.1 tracks expiry directly in the Vault model (core/security/vault/models.py) and surfaces it visually on each secret card (ui/vault/secret_card.py).

Setting an Expiry Date

In the Add/Edit dialog, you can:

Pick a preset duration: 30 days, 90 days, 180 days, 1 year.
Or pick an exact date via a QDateEdit calendar picker.

The date is stored as an ISO 8601 timestamp string in SQLite. The expiry logic lives in a shared mixin:

# core/security/vault/models.py

from datetime import datetime
from typing import Optional

class _ExpiryMixin:
    expires_at: Optional[str]

    @property
    def is_expired(self) -> bool:
        if not self.expires_at:
            return False
        try:
            exp = datetime.fromisoformat(self.expires_at)
            now = datetime.now(exp.tzinfo) if exp.tzinfo else datetime.now()
            return now > exp
        except Exception:
            # Corrupted timestamp: treated as non-expiring rather than raising in the UI
            return False

    @property
    def days_remaining(self) -> Optional[int]:
        if not self.expires_at:
            return None
        try:
            exp = datetime.fromisoformat(self.expires_at)
            now = datetime.now(exp.tzinfo) if exp.tzinfo else datetime.now()
            return (exp - now).days
        except Exception:
            return None

@dataclass
class VaultItem(_ExpiryMixin): ...

@dataclass(frozen=True)
class VaultSummary(_ExpiryMixin): ...

Both VaultItem (full DB record) and VaultSummary (UI listing) inherit the same expiry logic through the mixin — written once, tested once.

Visual Status Badges

The secret card renders the appropriate badge at render time:

Badge	Condition	Appearance
`⛔ EXPIRED`	`is_expired == True`	Red badge
`⚠️ 0d–7d left`	`days_remaining <= 7` (e.g., `⚠️ 3d left`, or `⚠️ 0d left` when less than 24 hours remain)	Amber badge
`⏳ 2027-03-01`	Active, > 7 days remaining	Blue pill
(none)	No expiry set	—

Figure 3: Secret cards displaying dynamic status badges including expired credentials and upcoming renewal countdowns.

4. Encrypted Password Version History & Safe Revert

Rotating a production credential is risky. If the new key fails, you need the old one — immediately. DotGhostBoard 2.1 solves this with Encrypted Version History.

How It Works

Every time you update an existing secret, the current ciphertext is archived before the new one is written:

# core/security/vault/service.py (simplified)

def update_secret(self, item_id: int, secret_text: str, save_history: bool = True) -> bool:
    key = self._require_unlocked()
    if save_history:
        # 1. Fetch current encrypted record before replacing
        existing = self._repo.get_item(item_id)
        if existing and existing.ciphertext:
            # 2. Archive previous ciphertext to history (capped at 3 newest)
            self._repo.add_history_entry(item_id, existing.ciphertext, max_entries=3)

    # 3. Encrypt and store the new secret version
    new_ciphertext = encrypt(secret_text, key)
    return self._repo.update_item(item_id, ciphertext=new_ciphertext)

Key points:

Max 3 versions — capped in SQLite, avoiding unbounded storage growth.
Encrypted at rest — history entries use the same DEK as the live secret. Plaintext never hits disk.
Decrypted in memory only — when you open the History Viewer, decryption happens in RAM and is discarded on close.

The History Viewer (📜) & Safe Revert

Clicking the 📜 icon on any secret card opens the modal:

Version index and creation timestamp for each entry.
👁️ Reveal / 🙈 Hide toggle with monospace masking.
Copy button — protected by DotGhostBoard's 30-second automatic clipboard scrub.
↺ Revert to this — restores the selected version as the active secret.

Behind the scenes, revert calls:

self.update_secret(item_id, secret_text=plaintext, save_history=True)

This neatly preserves the active secret you just replaced into history, allowing you to toggle back and forth safely without data loss. When a secret is deleted, SQLite cascades and purges all historical entries in the same transaction.

Figure 4: Password version history modal showing archived credential states, reveal toggle, and one-click atomic revert.

5. Vault-to-Dashboard Plaintext Sweep

Here's a subtle security gap:

You add a secret to the Vault. But before you did, you copied it to your clipboard — meaning an unencrypted copy was recorded in your general clipboard history.

Later, you delete the secret from the Vault. If the clipboard history remains untouched, your secret is gone from the encrypted vault but still sitting in plaintext in the general history database.

DotGhostBoard 2.1 closes this gap with a Coordinated Plaintext Sweep:

# ui/vault/vault_controller.py (simplified)

def delete_secret(self, item_id: int) -> bool:
    # 1. Temporarily decrypt secret in-memory to discover history traces
    try:
        plaintext = self._service.reveal_secret(item_id)
    except Exception:
        plaintext = None

    # 2. Delete from encrypted Vault database
    success = self._service.delete_secret(item_id)

    # 3. If deleted, sweep matching plaintext entries from clipboard history
    if success and plaintext:
        history_matches = self._history_repo.find_by_content(plaintext)
        for entry in history_matches:
            self._history_repo.delete(entry["id"])
            self.history_item_removed.emit(entry["id"])  # removes card from UI

    self.secrets_changed.emit()
    return success

The history_item_removed signal coordinates the UI: the Vault controller emits it, and the HistoryController receives it to cleanly remove the card from the UI. No tight coupling, no shared database transactions — just Qt signals.

Practical Boundary: Exact Match vs. Substrings

The sweep performs an exact match (find_by_content(plaintext)). If you copied the credential with trailing whitespace, a trailing newline, or embedded inside a larger terminal command line (e.g. curl -H "Authorization: Bearer <key>"), the exact sweep will not catch the enclosing entry.

We deliberately chose this conservative exact match: running broad substring searches across the entire clipboard history could easily result in destructive false-positive deletions of unrelated notes or commands.

6. Unified Design System & UX Polish

Security tools only work if developers actually use them. Friction kills adoption. In 2.1, we focused on tightening common interactions:

Component Unification (PasswordInputWidget): We extracted password input handling and the visibility toggle into a single reusable widget. Both the session LockScreen and the VaultUnlockDialog now share identical keyboard behavior, input styling, and state management rather than maintaining divergent Qt implementations.
Drawer Ergonomics: The slide-out Vault drawer (ui/vault/vault_panel.py) was restructured into a clear two-row toolbar (title/status row + action controls row) with an expanded 380px width for better readability. First-time users see an empty-state onboarding card outlining shortcuts and clipboard auto-scrub policies rather than a blank panel.

Figure 5: Expanded 380px Vault drawer featuring a two-row action toolbar and structured onboarding empty-state.

Figure 6: Unified PasswordInputWidget on the Session Lock screen with integrated eye toggle and focus handling.

Testing & Code Quality

523 automated tests. 100% passing.

======================== 523 passed in ~100s ========================

The test matrix covers:

Cryptographic roundtrips with AAD tampering verification
SQLite transaction isolation for version history and cascade deletes
UI event loops via headless Xvfb (tested against both Openbox and Qtile 0.36.0)
Expiry logic edge cases (timezone-aware vs. naive datetimes, malformed strings)
Plaintext sweep signal propagation across the Vault ↔ Dashboard boundary

Zero Flake8 errors. ui/dashboard.py enforces a hard <= 500 LOC limit — all specialized logic delegates to controllers and mixins.

What's Next & Known Limitations

A few honest limitations, on the record:

Wayland compatibility: DotGhostBoard relies on X11/EWMH for clipboard capture and hotkeys. We're investigating wlr-data-control protocol support for Wayland. No ETA yet, but it's our most-requested architecture evolution.
KDF hardening: 100,000 PBKDF2 rounds is our current baseline. User-configurable iteration counts (targeting OWASP's 600,000 recommendation) and Argon2id evaluation are on the v2.2 roadmap.
Backup format version negotiation: v2.1 introduces the single-byte version header; upcoming releases will support forward-compatible schema migrations.
Substring Plaintext Sweeps: Exploring optional flagged heuristics for wiping shell history snippets containing expired tokens.
CLI Vault queries: Scriptable, authenticated dotghost vault list and dotghost vault get <title> commands are planned for v2.2.

📦 Try DotGhostBoard 2.1

100% free and open-source — Apache-2.0 License.

GitHub: kareem2099/DotGhostBoard
OpenDesktop / KDE Store: DotGhostBoard on OpenDesktop

git clone https://github.com/kareem2099/DotGhostBoard.git
cd DotGhostBoard

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

python3 main.py

Keyboard Shortcuts

Shortcut	Action
`Ctrl+Alt+V`	Summon / hide Dashboard (migrates to active workspace)
`Ctrl+Alt+Space`	Floating Spotlight Quick Search
`Ctrl+Shift+V`	Open / close The Vault encrypted drawer
`Ctrl+F`	Focus search bar inside Dashboard

Questions about the vault format, the key derivation choices, or the history revert logic? Drop them below — happy to go deeper on any of it. 👻🔒

DotGhostBoard 2.1 'Leviathan' — Smart Clipboard Tagging & Contextual Actions on Linux (Part 1)

freerave — Fri, 02 Oct 2026 20:59:46 +0000

How we built a rules-based clipboard intelligence engine for Linux — local, deterministic, sub-millisecond for typical payloads (< 5KB), zero AI, zero telemetry. Auto-tagging, contextual smart actions, and a tight pipeline architecture explained.

You copy a minified JSON blob from a terminal log. To actually read it, you paste it into an editor, run a formatter, then copy the result back. You copy an API key from a config file and your clipboard manager stores it as plain text, alongside screenshots and grocery lists, until you manually hunt it down and secure it.

Most clipboard tools treat every copied item the same: inert text in a database. For anyone who spends time in terminals, editors, and browser devtools, that uniformity creates constant small frictions that accumulate fast.

DotGhostBoard 2.1 "Leviathan" takes a different approach. The clipboard understands what it's holding and surfaces the right action immediately — format this JSON, open that URL, secure this credential.

This is a two-part series on how we built it:

Part 1 (you're here): Rules-based Smart Auto-Tagging, Contextual Smart Actions, and the pipeline behind them.
Part 2: Cryptographic .vault Backups, CSPRNG Password Generator, Secret Expiry, and Encrypted Version History.

The Design Constraint: Local, Deterministic, Fast

The obvious shortcut for text classification is an LLM or a cloud API. For a clipboard manager, that's a non-starter on three counts.

Your clipboard routinely holds API keys, internal paths, private tokens, and proprietary code snippets. Sending that to any remote service — even a local on-device model — introduces a trust boundary that shouldn't exist in a tool people actually rely on for security. Beyond that, loading inference libraries adds hundreds of MB of idle RAM, and any latency between Ctrl+C and the item appearing in history is enough to make the tool feel broken.

Our constraint was concrete: every classification must run locally, produce deterministic results, and complete in under 1ms for typical clipboard payloads (< 5KB), scaling to ~1.4ms worst-case at the 8KB classification cap.

The approach: pre-compiled regular expressions, structural heuristics, and a pool-based keyspace entropy estimate — no opaque models.

1. The Auto-Tagger: How Classification Actually Works

The engine lives in core/security/auto_tagger.py. It runs synchronously on every new clipboard item before storage and UI rendering.

Captured Text ──► Pre-compiled Patterns & Heuristics ──► Tags ──► Storage & UI
                  ├── URL regex                       ──► #link
                  ├── JSON fast-path + json.loads     ──► #json
                  ├── Code keywords + bracket density ──► #code
                  ├── Known prefixes + entropy gate   ──► #secret
                  ├── IPv4 regex + IPv6 regex         ──► #ip
                  ├── RFC-like email regex            ──► #email
                  ├── Unix / Windows path regex       ──► #path
                  └── Hex length check {32,64}        ──► #hash

All patterns compile once at module load time. The function is pure — no I/O, no Qt, no database access — which makes it fast to call and trivial to test.

Here's the real implementation, abbreviated:

# core/security/auto_tagger.py

import json, re, math, string

# ── Compiled patterns (module-level — compiled once, reused forever) ──────────

_RE_URL = re.compile(r"https?://[^\s\"'<>]{3,}|ftp://[^\s\"'<>]{3,}", re.IGNORECASE)
_RE_EMAIL = re.compile(r"\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b")

_RE_IPV4 = re.compile(                             # validates 0-255 per octet
    r"\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}"
    r"(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b"
)
_RE_IPV6 = re.compile(r"\b(?:[0-9a-fA-F]{1,4}:){2,7}[0-9a-fA-F]{1,4}\b")

# Pragmatic range matching MD5 (32), SHA-1 (40), SHA-256 (64); strict lengths planned for v2.2
_RE_HEX_HASH = re.compile(r"\b[0-9a-fA-F]{32,64}\b")

# Known credential prefixes — the first line of secret detection
_RE_SECRET_PATTERNS = [
    re.compile(r"ghp_[A-Za-z0-9]{36,}"),                          # GitHub PAT
    re.compile(r"AKIA[0-9A-Z]{16}"),                               # AWS Access Key
    re.compile(r"sk-[A-Za-z0-9]{32,}"),                           # OpenAI / Stripe
    re.compile(r"xox[baprs]-[A-Za-z0-9\-]{10,}"),                 # Slack tokens
    re.compile(r"eyJ[A-Za-z0-9\-_]{10,}\.[A-Za-z0-9\-_]{10,}"),  # JWT
    re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
]

# (Note: _RE_PATH, _CODE_KEYWORDS, and _CODE_BRACKETS are omitted here for brevity)

# ── Pool-based keyspace entropy estimate ──────────────────────────────────────

def _entropy_bits(text: str) -> float:
    """Estimate theoretical keyspace entropy: H = len * log₂(pool_size)."""
    pool = 0
    if any(c in string.ascii_lowercase for c in text): pool += 26
    if any(c in string.ascii_uppercase for c in text): pool += 26
    if any(c in string.digits           for c in text): pool += 10
    # Any non-alphanumeric character (symbols, punctuation, or non-ASCII) adds 32
    if any(c not in string.ascii_letters + string.digits for c in text): pool += 32
    return math.log2(pool or 26) * len(text)

# ── Main classification function ──────────────────────────────────────────────

def detect_tags(content: str) -> list[str]:
    if not content or not isinstance(content, str):
        return []
    tags: list[str] = []
    text = content.strip()

    if _RE_URL.search(text):    tags.append("#link")
    if _RE_EMAIL.search(text):  tags.append("#email")
    if _RE_IPV4.search(text) or _RE_IPV6.search(text): tags.append("#ip")
    if _RE_PATH.search(text) and "#link" not in tags:   tags.append("#path")
    if _RE_HEX_HASH.search(text):                       tags.append("#hash")

    # Secret detection: known prefix first, entropy gate as fallback
    is_secret = any(p.search(text) for p in _RE_SECRET_PATTERNS)
    if not is_secret and len(text) >= 16 and " " not in text and "\n" not in text:
        if _entropy_bits(text) >= 90:
            is_secret = True
    if is_secret:
        tags.append("#secret")

    # JSON: only attempt parse if it looks like an object or array
    if text.lstrip().startswith(("{", "[")):
        try:
            json.loads(text)
            tags.append("#json")
        except (json.JSONDecodeError, ValueError):
            pass

    # Code: multi-line with language keywords or dense bracket patterns
    if "\n" in text and len(text) > 40:
        if _CODE_KEYWORDS.search(text) or _CODE_BRACKETS.search(text):
            tags.append("#code")

    return list(dict.fromkeys(tags))  # deduplicate, preserve order

Secret Detection: Two Layers

The #secret classifier uses a two-step approach:

Layer 1 — Known prefixes. Patterns like ghp_, AKIA, eyJ (JWT header) are unambiguous. Match any of them and the tag is assigned immediately, no entropy calculation needed.

Layer 2 — Entropy gate. For everything else: single-line, no spaces, at least 16 characters, and a pool-based keyspace entropy ≥ 90 bits. The 90-bit threshold was tuned empirically to catch random high-entropy tokens, API keys, and strong bearer credentials while skipping short identifiers, dictionary words, and common camelCase variable names.

Both conditions guard against a common pitfall: pure Shannon entropy on raw text produces too many false positives on long sentences or dense code snippets. The entropy function here is H = len × log₂(pool_size) — a measure of the theoretical keyspace, not character frequency distribution.

Note on non-ASCII characters: Because any(c not in string.ascii_letters + string.digits ...) catches non-ASCII characters (e.g. Arabic script, accented letters, emoji), unicode text will trigger the +32 symbols branch. This heuristic is tuned primarily for ASCII credentials; multilingual script entropy is handled gracefully without throwing exceptions.

Known Limitations

Honest engineering requires talking about edge cases:

Long Paths tagged as #secret: A Unix path like /home/kareem/StudioProjects/DotGhostBoard/main.py currently receives both #path and #secret — it satisfies the entropy gate because it has no spaces and mixes uppercase, lowercase, digits, and /. We've logged this as a known limitation; v2.2 will add #path as an explicit exclusion condition for the entropy fallback.
Hashes flagged as #secret: A 32-character hex string (like an MD5 digest) uses digits + lowercase (pool = 36), yielding 32 × log₂(36) ≈ 165 bits, which clears the ≥ 90-bit gate. Consequently, MD5 and SHA digests receive both #hash and #secret; a dedicated check to prioritize #hash alone is slated for v2.2.

2. What the Tag Enables: Contextual Smart Actions

Tags are displayed as colored pill chips on each card. More importantly, they drive Contextual Smart Actions — buttons that appear dynamically in the card toolbar based on what was detected.

Tag	Action	What it does
`#link`	🔗 Open Link	`QDesktopServices.openUrl()` — no copy-paste to browser
`#json`	`{ }` Format JSON	Parses, re-serializes with 2-space indent, writes back to clipboard
`#email`	✉ Compose	Constructs a `mailto:` URI, hands off to default mail client
`#ip`	📡 Copy IP	Extracts just the IP from surrounding log noise
`#secret`	🛡 → Vault	Opens Vault drawer, prefills secret dialog, purges plaintext from history

Here's the JSON formatter — the action developers use most:

# ui/widgets/item_card.py (simplified)
import json

def _on_format_json(self) -> None:
    try:
        parsed = json.loads(self._raw_text)
        formatted = json.dumps(parsed, indent=2, ensure_ascii=False)
        QApplication.clipboard().setText(formatted)
        self._flash_badge("✓ Formatted")
    except json.JSONDecodeError:
        self._flash_badge("✗ Invalid JSON")

One button. Minified JSON in, readable JSON back in your clipboard. No editor, no extra window.

Figure 1: Auto-detected tags (#link, #ip, #code) and dynamic contextual smart actions (🔗 Open Link, 📡 Copy IP) on clipboard cards.

3. Pipeline Architecture

The classifier only stays fast because it runs inside a well-isolated pipeline:

Figure 2: The 4-phase sequential classification and dispatch pipeline.

[System Clipboard] ──► ClipboardWatcher (background polling / events)
                             │
                             ▼
                    ClipboardPipeline (pure policy layer)
                      ├── App filter      (skip blacklisted sources)
                      ├── Self-paste guard (skip our own copy events)
                      ├── AutoTagger      (sync, pure, no I/O)
                      └── Duplicate & pin policy
                             │
                             ▼
                    HistoryService ──► SQLite (PRAGMA secure_delete)
                             │
                             ▼
                    HistoryController ──► CardsView (lazy render)

AutoTagger has zero dependencies on Qt, SQLite, or any network code. That isolation means:

The UI thread is never blocked by classification.
Unit tests need no display server or mocked widgets.
You can swap, extend, or replace tagging rules without touching controllers or storage.

4. Measured Latency

We wanted hard performance guarantees rather than assumptions. Here are timeit measurements on typical clipboard payloads running on an Intel Core i5-8350U @ 1.70GHz (Python 3.14.7, Linux x86_64), 1,000 iterations each:

Figure 3: Microsecond-level classification benchmark measurements across typical clipboard payloads.

Payload                      min µs    median µs    max µs
──────────────────────────────────────────────────────────
URL                             8.2          8.8      10.7
GitHub PAT                      6.5          6.8      10.1
IPv4 address                    7.1          7.5      12.7
MD5 hash                        7.1          7.2       7.6
JSON (small, ~80 chars)        14.1         14.4      16.1
Code snippet                   20.3         20.4      21.4
Plain English text             14.8         15.2      15.3
JSON (1KB payload)             80.3         81.8      82.6
Worst-case dense (7.8KB)     1380.0       1410.6    1460.0

The "< 1ms" guarantee holds for typical clipboard payloads (< 5KB), with small items (URLs, hashes, JSON) processing in 8–82 µs. At the 8KB cap, worst-case dense tokens (7.8KB of unspaced text forcing character-by-character entropy evaluation) measure ~1.4ms. Payloads exceeding 8KB automatically bypass the entropy gate to ensure the UI loop never hitches on huge paste events.

Coming Up in Part 2

The productivity layer is half the story. The other half is what happens to sensitive data after it's detected.

In Part 2, we cover the security architecture:

🔐 Standalone .vault encrypted backups — AES-256-GCM packages with AAD header authentication, zero plaintext on disk, PBKDF2 key derivation.
⚡ CSPRNG Password & Token Generator — Live keyspace entropy meter calibrated to 131.1 bits.
⏳ Secret Expiry Tracking — Calendar-based expiry with ⛔ EXPIRED and ⚠️ 3d left badges.
📜 Encrypted Version History — Last 3 versions retained, one-click atomic revert.
🧹 Coordinated Plaintext Sweep — Purging matching unencrypted history records upon Vault deletion.

📦 Try DotGhostBoard 2.1

100% free and open-source — Apache-2.0 License.

GitHub: kareem2099/DotGhostBoard
OpenDesktop / KDE Store: DotGhostBoard on OpenDesktop

git clone https://github.com/kareem2099/DotGhostBoard.git
cd DotGhostBoard

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

python3 main.py

Keyboard Shortcuts

Shortcut	Action
`Ctrl+Alt+V`	Summon / hide Dashboard (migrates to active workspace)
`Ctrl+Alt+Space`	Floating Spotlight Quick Search
`Ctrl+Shift+V`	Open / close The Vault encrypted drawer

Questions about the classification heuristics, the entropy threshold choice, or the action pipeline? Drop them in the comments. 👻

Building an Automated, API-Driven Stats & Version Synchronizer for VS Code Extensions with 24-Hour Smart Caching (dotUniverse v1.2.0)

freerave — Mon, 28 Sep 2026 14:01:29 +0000

How I built a dual-path synchronization architecture for 7 VS Code extensions using VS Marketplace & Open VSX APIs, 24-hour client caching, and daily zero-dependency GitHub Actions.

As an open-source creator building a growing ecosystem of developer tools, one repetitive chore kept draining my time: keeping metrics and version numbers in sync.

My portfolio, dotUniverse, showcases 20+ open-source tools—including 7 VS Code extensions published across both the Visual Studio Marketplace and the Eclipse Open VSX Registry.

Every time I bumped a release or checked how many developers installed CodeTune, dotcommand, or DotShare, I had to:

Log into multiple web dashboards.
Manually calculate cross-platform sums.
Edit HTML cards, version badges, and repository README tables by hand.

Manual upkeep is tedious, error-prone, and quickly falls behind. I wanted an automated, dual-path synchronization architecture:

At Runtime: Visitors see fresh, API-backed numbers and versions fetched directly from store APIs, cached intelligently on the client for 24 hours.
At Build/Repository Time: Static fallbacks in index.html and markdown tables in README.md are automatically kept fresh via a scheduled, zero-dependency GitHub Action.

Here is a deep dive into how I built this system using pure modern JavaScript, 24-hour client-side caching, and GitHub Actions CI/CD.

🏛️ The Architecture: Dual-Path Synchronization

Instead of treating this as a simple "fetch data in JavaScript" problem, I designed a dual-path synchronization pipeline sharing a single source of truth:

                  ┌──────────────────────────────┐
                  │ Visual Studio Marketplace    │
                  │   & Open VSX Registry APIs   │
                  └──────────────┬───────────────┘
                                 │
             ┌───────────────────┴───────────────────┐
             │                                       │
      [Runtime Path]                           [Build/CI Path]
             │                                       │
             ▼                                       ▼
  extension-stats.js                     sync-extension-stats.mjs
             │                                       │
      ┌──────┴──────┐                         ┌──────┴──────┐
      ▼             ▼                         ▼             ▼
  24h Cache     Fresh DOM                 index.html    README.md
 (localStorage) (No Flicker)              (Fallback)    (Markdown)
                                                     │
                                                     ▼
                                              Git Commit & Push
                                              (Only on Changes)

This decoupled design guarantees that:

First-time and repeat visitors get an instant render from static markup or localStorage without waiting for API responses to render the initial content.
Search engine crawlers and developers browsing the GitHub repository see accurate static numbers even without executing client-side JavaScript.

🏗️ The Challenge: Two Stores, Fragmented Metrics

Tracking extensions across the VS Code ecosystem is fragmented:

VS Code Marketplace: Owned by Microsoft. Its web interface displays a single "Installs" counter, but its underlying gallery API exposes separate metrics.
Open VSX Registry: The vendor-neutral marketplace used by VSCodium, Gitpod, and Eclipse Theia. It provides a clean REST API with different metric structures.

Crucially, both APIs support CORS with access-control-allow-origin: *, allowing modern browsers to query them directly without requiring a proxy server.

🔍 Layer 1: Querying Store APIs Directly

1. Batch-Querying Visual Studio Marketplace

Instead of making 7 separate HTTP requests, Microsoft's Marketplace API allows querying multiple extensions in a single POST request to _apis/public/gallery/extensionquery:

async function fetchVsMarketplace(extensions) {
  const body = {
    filters: [{
      criteria: extensions.map(ext => ({ filterType: 7, value: ext.vsId }))
    }],
    flags: 914 // Requests statistics, versions, and metadata
  };

  const res = await fetch('https://marketplace.visualstudio.com/_apis/public/gallery/extensionquery', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json;api-version=3.0-preview.1'
    },
    body: JSON.stringify(body)
  });

  const json = await res.json();
  const map = {};

  for (const ext of json?.results?.[0]?.extensions || []) {
    const stats = {};
    for (const s of ext.statistics || []) {
      stats[s.statisticName] = s.value;
    }

    // Empirical verification: Microsoft Marketplace UI displays (install + downloadCount)
    const installs = Math.round((stats.install || 0) + (stats.downloadCount || 0));

    // The API returns the latest release first in versions[0]
    const version = ext.versions?.[0]?.version || null;

    map[ext.extensionName.toLowerCase()] = { installs, version };
  }

  return map;
}

💡 Empirical Verification on Marketplace Installs: Microsoft's API returns two separate download metrics: install (active installed instances) and downloadCount (package downloads/updates). Through empirical cross-referencing between the API response and the live web pages for all 7 extensions, the "Installs" figure shown on the Marketplace product page aligned with (stats.install + stats.downloadCount). This was observed across the seven extensions tested during development; it should be treated as an empirical observation rather than a guaranteed API contract.

2. Querying Open VSX Registry

Open VSX provides an open REST endpoint at https://open-vsx.org/api/{namespace}/{extension}:

async function fetchOpenVsx(extensions) {
  const map = {};
  const ovsxExts = extensions.filter(e => e.ovsxId);

  const promises = ovsxExts.map(async (ext) => {
    try {
      const res = await fetch(`https://open-vsx.org/api/${ext.ovsxId}`);
      if (!res.ok) return;
      const data = await res.json();
      map[ext.key] = {
        downloads: data.downloadCount || 0,
        version: data.version || null
      };
    } catch (err) {
      console.warn(`Open VSX fetch failed for ${ext.key}:`, err);
    }
  });

  await Promise.allSettled(promises);
  return map;
}

⚡ Layer 2: The Client-Side Module (`extension-stats.js`)

In dotUniverse's modular architecture, we created js/modules/extension-stats.js.

Why a 24-Hour Cache is Essential

Firing external API requests on every page refresh is bad engineering—it wastes bandwidth, risks third-party rate limits, and causes text flicker.

Because developer tools are typically released over days or weeks, a 24-hour cache TTL (24 * 60 * 60 * 1000) is a practical default: it reduces unnecessary API requests while keeping the displayed statistics reasonably fresh:

export const ExtensionStats = {
  CACHE_KEY: 'dotuniverse_ext_stats_v1',
  CACHE_TTL: 24 * 60 * 60 * 1000, // 24 hours (1 day)

  init() {
    // 1. Instantly apply cached data to DOM (avoids visible flicker)
    const cached = this.getCached();
    if (cached && cached.data) {
      this.applyToDOM(cached.data);
    }

    // 2. Fetch in background only when the 24-hour window expires
    if (!cached || Date.now() - cached.timestamp > this.CACHE_TTL) {
      this.refresh();
    }
  },
  // ...
};

Clean DOM Mutation via Semantic Attributes

In index.html, each extension card includes a semantic data-ext-name identifier:

<div class="ext-card" data-ext-name="codetune">
  <div class="ext-header">
    <div class="ext-name"><span class="prefix">Code</span><span class="suffix">Tune</span></div>
    <span class="ext-version">v1.3.0</span>
  </div>
  ...
  <div class="ext-stores">
    <a ... class="store-badge vs">
      <span class="store-info"><span class="store-name">VS Marketplace</span><span class="store-dl">737 installs</span></span>
    </a>
    <a ... class="store-badge ovsx">
      <span class="store-info"><span class="store-name">Open VSX</span><span class="store-dl">1,500 downloads</span></span>
    </a>
  </div>
</div>

When fresh metrics arrive:

.ext-version updates to the store's current version (e.g. v1.3.0, v2.2.1, v3.5.1).
Store badges update with formatted counts (e.g., 1,040 installs, 6,000 downloads).
The grand total (19,500+) is calculated and smoothly updated in both the header stats and the hero banner.

🤖 Layer 3: Automated Daily CI/CD Synchronization

To keep the repository README.md and static HTML in sync for users without JavaScript or search bots, we created a zero-dependency Node script: scripts/sync-extension-stats.mjs.

Running this script fetches live data, parses index.html and README.md, updates markdown tables, Shields.io badges, and prints a formatted terminal overview:

$ node scripts/sync-extension-stats.mjs

🔄 Fetching live extension stats from VS Marketplace and Open VSX...

📊 Live Extension Stats:
┌─────────┬──────────────┬──────────┬────────────────┬──────────┬─────────────────┐
│ (index) │ Extension    │ Version  │ VS Marketplace │ Open VSX │ Total Downloads │
├─────────┼──────────────┼──────────┼────────────────┼──────────┼─────────────────┤
│ 0       │ 'CodeTune'   │ 'v1.3.0' │ '734'          │ '1,486'  │ '2,220'         │
│ 1       │ 'dotcommand' │ 'v2.0.1' │ '778'          │ '970'    │ '1,748'         │
│ 2       │ 'DotEnvy'    │ 'v2.2.1' │ '758'          │ '2,173'  │ '2,931'         │
│ 3       │ 'DotShare'   │ 'v3.5.1' │ '1,040'        │ '5,987'  │ '7,027'         │
│ 4       │ 'DotFetch'   │ 'v2.1.1' │ '470'          │ '2,766'  │ '3,236'         │
│ 5       │ 'DotReadme'  │ 'v1.2.0' │ '364'          │ '1,719'  │ '2,083'         │
│ 6       │ 'DotSense'   │ 'v1.3.0' │ '257'          │ '0'      │ '257'           │
└─────────┴──────────────┴──────────┴────────────────┴──────────┴─────────────────┘

🏆 Grand Total Downloads: 19,502 (Marketplace: 4,401, Open VSX: 15,101)

✅ index.html updated successfully.
✅ README.md updated successfully.

To run this hands-free, we added .github/workflows/update-extension-stats.yml:

name: Auto Update Extension Stats

on:
  schedule:
    # Runs everyday at midnight UTC
    - cron: '0 0 * * *'
  workflow_dispatch: # Allows manual trigger from GitHub UI

permissions:
  contents: write

jobs:
  sync-stats:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Sync extension downloads and versions
        run: node scripts/sync-extension-stats.mjs

      - name: Commit and push changes if updated
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add index.html README.md
          if git diff --staged --quiet; then
            echo "No changes detected."
          else
            git commit -m "chore: auto-update extension downloads and versions [skip ci]"
            git push
          fi

💡 Clean Commit History: The git diff --staged --quiet check ensures that GitHub Actions only commits when marketplace metrics or versions actually change. This keeps the Git history clean from empty daily noise.

🚀 The Bigger Picture: Building in Public

Automating tool statistics ties directly into how I build in public. Alongside extensions, dotUniverse features an open Growth Challenge Tracker across 9 creator and developer platforms.

Here is the current state for October 2026:

Platform	Current (Now)	Target (Goal)	Remaining	Progress
🚀 dev.to	3,986	4,200	`+214`	95%
💼 LinkedIn	709	800	`+91`	89%
🎵 TikTok	37	60	`+23`	62%
▶️ YouTube	30	60	`+30`	50%
✍️ Medium	6	10	`+4`	60%
📘 Facebook	15	20	`+5`	75%
📸 Instagram	7	10	`+3`	70%
𝕏 X / Twitter	18	20	`+2`	90%
🦋 Bluesky	21	30	`+9`	70%

On dev.to specifically, we recently passed 15,400+ total views, 93 published posts, 97 reactions, and 67 comments.

Because dev.to is currently at 3,986 / 4,200, we explicitly commented out the celebratory 15-DAY RECORD badge in the HTML until the 4,200 mark is officially crossed. Milestones are meaningful only when they are genuine!

💡 Key Engineering Takeaways

Leverage Dual-Path Synchronization: Combining client-side background sync with scheduled CI/CD ensures that both web visitors and static repository viewers get consistently updated extension statistics.
Explore Public API Capabilities: Both the Visual Studio Marketplace and Open VSX support CORS directly. Before introducing a custom serverless proxy, inspect the network headers first.
Respect the Client Cache: A 24-hour localStorage TTL reduces visible flickering, avoids API-dependent initial rendering on repeat visits, respects third-party rate limits, and matches the realistic release frequency of developer tools.
Conditional CI/CD Commits: Always check git diff --staged --quiet before committing automated bot changes to keep your repository history concise and meaningful.

🔗 Project Links

🌐 Live Website: universe.dotsuite.dev
💻 GitHub Repository: kareem2099/dotuniverse
📦 VS Code Extensions: Search for FreeRave on VS Code Marketplace or Open VSX!

How do you automate metrics across your open-source repositories? Do you rely on static shields or live client-side queries? Let's discuss in the comments below!

The VSIX Packaging Trap: How I Eliminated Embedded Client Secrets from a VS Code Extension

freerave — Fri, 25 Sep 2026 15:04:51 +0000

A .vsix is just a ZIP archive of plain JavaScript. Here is the post-mortem of how our build-time secrets failed, how we designed dynamic device registration with OS SecretStorage, and how we solved the 'scanner scanning the scanner' paradox.

TL;DR: Distributing a client-server VS Code extension means accepting a hard truth: a .vsix file is just a ZIP archive containing JavaScript that can be extracted and inspected. This article breaks down how our initial attempt to inject build-time backend secrets was scrapped, how we engineered an anonymous dynamic device handshake with OS-level SecretStorage, and how we resolved the bizarre paradox of static security scanners flagging our own secret detection patterns.

The Illusion of the Extension Package

When developers distribute software through the VS Code Marketplace or the Open VSX Registry, it is easy to unconsciously think of the .vsix file as a compiled, opaque binary.

It is not.

A .vsix package is an Open Packaging Conventions (OPC) archive — an ordinary ZIP file containing your extension’s manifest (package.json), assets, and compiled JavaScript output (out/).

Anyone can verify this with standard shell utilities:

# Rename and extract any published extension
cp DotEnvy-2.1.0.vsix DotEnvy.zip
unzip -q DotEnvy.zip -d extracted/
cd extracted/extension/out

# Search for sensitive variables
grep -rn "SHARED_SECRET" .

If you injected an API key, an HMAC signing secret, or a database token into your client code at compile time, you just published that secret to the entire world.

Context: Why Did We Need a Secret in the First Place?

In Part 1 of this series, I explained how we built Aegis — a 4-layer AI secret detection pipeline for DotEnvy.

The first three layers (Regex, Community Blacklist, and Entropy Gating) execute locally inside the editor process. But Layer 4 requires invoking our Python microservice (aegis.dotsuite.dev) on Railway to run contextual neural classification.

To protect the backend against unauthorized abuse, spam, and denial-of-service, we required incoming HTTP requests to be signed using HMAC-SHA256:

$$\text{Signature} = \text{HMAC-SHA256}(\text{SharedSecret}, \text{Timestamp} + "." + \text{Payload})$$

This design introduced our fundamental dilemma:

How does an open-source, publicly distributed client authenticate with a protected backend service without shipping a hardcoded secret in its package?

Attempt 1: The Build-Time Secret Trap (v2.1.0)

Our initial approach relied on build-time environment variable substitution. In our deployment pipeline, a Node script injected a secret before invoking vsce package:

// scripts/build-with-env.js (Flawed Approach)
const secret = process.env.PRODUCTION_EXTENSION_SECRET;
let code = fs.readFileSync('out/utils/llmAnalyzer.js', 'utf8');
code = code.replace('REPLACE_AT_BUILD_TIME', secret);
fs.writeFileSync('out/utils/llmAnalyzer.js', code);

While this kept the secret out of our public git repository, it was an architectural disaster:

The VSIX Leak: As demonstrated above, extracting the .vsix exposed the secret immediately.
Automated Scanner Flags: Automated CI/CD bots (GitHub Secret Scanning, Trufflehog, CodeQL) automatically inspect release assets. A high-entropy hex string inside compiled JavaScript triggers immediate alerts.
Single Point of Compromise: If one user decompiles the extension and leaks the shared secret, the backend can no longer trust any extension client without rotating the key and breaking every installed instance worldwide.

We scrapped this design entirely.

Attempt 2: Zero Embedded Client Secrets & Dynamic Device Handshake (v2.1.2)

We established a strict architectural rule: Zero Embedded / Static Client Secrets.

Not a single secret, token, or private key may exist in the source code, build scripts, or packaged .vsix bundle.

Instead, we designed an anonymous, zero-touch dynamic device registration handshake:

┌────────────────────────────────────────┐           ┌────────────────────────────────────────┐
│ DotEnvy Client (First Activation)      │           │ Aegis Backend (aegis.dotsuite.dev)     │
└───────────────────┬────────────────────┘           └───────────────────┬────────────────────┘
                    │                                                    │
                    │ 1. POST /extension/register                        │
                    │    { machine_id: hash(vscode.env.machineId) }      │
                    ├───────────────────────────────────────────────────►│ Strict IP Rate Limiter
                    │                                                    │ (Max 10 per hour per IP)
                    │                                                    │
                    │                                                    │ 2. Backend generates unique
                    │                                                    │    cryptographic client_secret
                    │ 3. Returns per-device secret                       │    and stores active record
                    │◄───────────────────────────────────────────────────┤
                    │                                                    │
                    ▼                                                    ▼
          Stored Exclusively in                                Subsequent requests signed via
         OS-level SecretStorage                                HMAC-SHA256(timestamp + body)
       (macOS Keychain / Windows                               with per-machine rate limiting
      Credential Manager / libsecret)                                 (30 req/min)

1. Anonymous Environment Identity

When DotEnvy launches for the first time, it generates a non-reversible identifier from VS Code's environment API:

private getMachineId(): string {
    return vscode.env.machineId || 'anonymous-machine';
}

vscode.env.machineId provides a pseudonymous environment identifier that lets the backend maintain per-client state and rate limits without requiring a user account.

2. Ephemeral Dynamic Registration

The extension calls /extension/register:

Defense in Depth: The registration endpoint is protected by strict IP-based rate limiting (maximum 10 registrations per hour per IP) to prevent Sybil registration floods.
Unique Credential Issuance: The backend generates an independent 256-bit cryptographically random secret (client_secret), persists the mapping in PostgreSQL, and returns it over TLS.

3. OS-Level SecretStorage

The extension never writes the returned secret to disk, .env files, or standard workspace settings. It stores the credential directly inside VS Code's SecretStorage API:

public async setSharedSecret(secret: string): Promise<void> {
    await this.secrets.store('dotenvy.llm.sharedSecret', secret);
    this.sharedSecret = secret;
}

Under the hood, VS Code delegates SecretStorage to native operating system keyrings:

macOS: Apple Keychain
Windows: Windows Credential Manager
Linux: Secret Service API (gnome-keyring / KWallet)

4. Authenticated Request Signing

For all subsequent requests, DotEnvy signs its payloads using HMAC-SHA256:

private signRequest(body: string): { timestamp: string; signature: string } {
    const timestamp = String(Math.floor(Date.now() / 1000));
    const signature = crypto
        .createHmac('sha256', this.sharedSecret!)
        .update(`${timestamp}.${body}`)
        .digest('hex');
    return { timestamp, signature };
}

On the backend, Aegis:

Validates the timestamp against a 5-minute sliding window to prevent replay attacks.
Looks up the client_secret corresponding to the X-Machine-ID header.
Uses Python's constant-time comparison hmac.compare_digest to prevent timing attacks.
Applies a machine-level rate limit (30 requests/minute).

If a specific client secret is ever compromised on a developer's local machine, revoking that single record does not disrupt any other user.

The Automated Gatekeeper: CI/CD Pre-Publish Validation

To ensure no developer or automated script ever accidentally reintroduces an embedded secret, we added an automated pre-publish scanner to scripts/build-with-env.js:

// scripts/build-with-env.js
const fs = require('fs');
const path = require('path');

const outDir = path.join(__dirname, '..', 'out');

function scanDir(dir) {
    let flagged = 0;
    const files = fs.readdirSync(dir);
    for (const f of files) {
        const fullPath = path.join(dir, f);
        if (fs.statSync(fullPath).isDirectory()) {
            flagged += scanDir(fullPath);
        } else if (fullPath.endsWith('.js')) {
            const content = fs.readFileSync(fullPath, 'utf8');

            // Check for illegal embedded secret patterns
            if (/const\s+embeddedSecret\s*=\s*["'][A-Za-z0-9_-]{20,}["']/.test(content)) {
                console.error(`❌ Security Alert: Hardcoded embeddedSecret found in ${fullPath}!`);
                flagged++;
            }
        }
    }
    return flagged;
}

const flags = scanDir(outDir);
if (flags > 0) {
    console.error(`\n❌ Pre-publish check failed: ${flags} leaked secret(s) found in out/!`);
    process.exit(1);
} else {
    console.log('✅ Security check passed: 0 embedded secrets found in compiled out/ bundle.');
}

This verification script runs automatically as part of npm run package. If a secret is detected, the build halts with an exit code of 1, aborting the release pipeline.

The "Scanner Scanning the Scanner" Paradox (v2.1.3)

Once we eliminated embedded secrets, we collided with an ironic roadblock: automated static security scanners started blocking our extension releases.

DotEnvy is a security extension designed to detect leaked credentials. Its pattern registry naturally contains regular expressions for popular API tokens:

// ❌ v2.1.0: Literal regex prefixes
const KNOWN_SECRET_PATTERNS = [
    { name: 'AWS Access Key',  regex: /AKIA[0-9A-Z]{16}/ },
    { name: 'Stripe Live Key', regex: /sk_live_[0-9a-zA-Z]{24,}/ },
    { name: 'GitHub Token',    regex: /ghp_[a-zA-Z0-9]{36}/ },
    { name: 'Google API Key',  regex: /AIza[0-9A-Za-z\-_]{35}/ },
];

When GitHub’s push protection and marketplace upload scanners inspected our compiled output, their naive string-matching heuristics triggered on our own code:

"Warning: Leaked AWS Access Key pattern detected in out/utils/llmAnalyzer.js"

The scanners couldn't differentiate between code containing a secret and code designed to detect a secret.

Avoiding Static Scanner False Positives via Runtime Pattern Construction

To resolve these false positives without weakening our detection capabilities, we refactored the pattern registry to assemble sensitive token prefixes dynamically at runtime:

// ✅ v2.1.3: Assembled at runtime — clean scanner bill of health
const KNOWN_SECRET_PATTERNS = [
    { 
        name: 'AWS Access Key',  
        regex: new RegExp(['A', 'KIA', '[0-9A-Z]{16}'].join('')) 
    },
    { 
        name: 'Stripe Live Key', 
        regex: new RegExp(['sk', '_live_', '[0-9a-zA-Z]{24,}'].join('')) 
    },
    { 
        name: 'GitHub Token',    
        regex: new RegExp(['g', 'hp_', '[a-zA-Z0-9]{36}'].join('')) 
    },
    { 
        name: 'Google API Key',  
        regex: new RegExp(['AI', 'za', '[0-9A-Za-z\\-_]{35}'].join('')) 
    },
];

Engineering Note: This runtime string assembly is not an evasion technique against security controls; it is a pragmatic packaging workaround to prevent regex-based linters from confusing detection definitions with genuine credential leaks. Inside Node's V8 engine, the compiled RegExp objects are identical and execute at native engine speed.

Build Hygiene & VSIX Purity

Our final hardening step addressed package purity:

Automatic Pre-Build Purging: We updated our package.json scripts to mandate rm -rf out before every invocation of tsc. Stale, uncompiled test artifacts from previous development sessions can never accidentally be swept into a production .vsix.
Aggressive .vscodeignore Hardening: We audited and excluded all non-production files:
- Development linter configs (eslint.config.mjs)
- Internal test runners and mock fixtures
- Temporary extraction folders (extracted-vsix/)
- Documentation drafts and article markdowns

The resulting .vsix bundle contains solely the minified runtime code and localized UI assets.

Checklist for VS Code Extension Developers

If you are building a VS Code extension that interacts with a private backend, keep these rules in mind:

Rule	Bad Practice ❌	Good Practice ✅
Client Secrets	Injecting API keys in build scripts	Zero embedded secrets; dynamic device handshake
Local Storage	Saving tokens in `workspaceState`	Storing credentials in native OS `SecretStorage`
Request Signing	Sending plain machine IDs	HMAC-SHA256 with timestamp sliding window
Scanner Hygiene	Hardcoded token regex literals	Dynamic runtime pattern construction
Package Hygiene	Relying on default package contents	Automated `rm -rf out` + strict `.vscodeignore`

Links & Verification

🔗 VS Code Marketplace: marketplace.visualstudio.com/items?itemName=FreeRave.dotenvy
🌐 Open VSX Registry: open-vsx.org/extension/freerave/dotenvy
📦 GitHub Repository: github.com/kareem2099/dotenvy
📖 Read Part 1: DotEnvy Aegis: Building a 4-Layer AI Secret Detection Pipeline for VS Code
📝 Full Changelog: CHANGELOG.md

Written by FreeRave. If you've encountered packaging headaches or static scanner false alarms in your extensions, feel free to reach out and share your experience.

DotEnvy Aegis: Building a 4-Layer AI Secret Detection Pipeline for VS Code

freerave — Thu, 24 Sep 2026 20:38:11 +0000

How I architected a multi-layer secret scanner combining regex, truncated composite community hashing, Shannon entropy gating, and a 35-feature neural classifier — cutting LLM overhead by ~80%.

TL;DR: DotEnvy Aegis introduces a 4-layer secret detection pipeline (Regex → Truncated Composite Community Blacklist → Shannon Entropy Gate → Neural Context Classifier), migrates encryption keys to the OS keychain, auto-authorizes backups with project master keys, and syncs hashes to an anti-poisoning community blacklist on Railway — all without transmitting raw secret payloads.

What is DotEnvy?

DotEnvy is an open-source VS Code extension designed to bring enterprise-grade security to local .env file management:

Encrypted Variable Management (AES-256-GCM, PBKDF2 with 310,000 iterations)
Multi-User Envelope Encryption (each teammate decrypts using individual credentials)
Cloud Synchronization (native Doppler, Vercel, and AWS integrations)
AI-Powered Secret Detection (the focus of this article)
Git Pre-Commit Hooks (blocking credential leaks before commits land in git history)
Environment Analytics, Timeline, & Diff panels

The extension communicates with Aegis (python-llm), a custom Python microservice deployed on Railway that runs contextual neural classification on candidate secrets.

The Problem: One Layer is Never Enough

In our earliest experimental prototype, secret detection was a blunt instrument: every candidate token triggered an HTTP request to the backend model.

This naive architecture fell apart under real-world development workloads:

Latency Overhead: Every network round-trip added 200–450ms of latency, quickly degrading editor responsiveness during live typing.
Availability Dependency: If the network dropped or the backend restarted, secret detection failed silently.
The False Positive/Negative Dilemma:
- A high-entropy random string (like an image hash or UUID) looks like a secret to entropy analyzers, but is harmless.
- A low-entropy or structured token looks harmless to statistical math, but may grant full database admin rights.

Context matters. Regex patterns matter. Math matters. Community intelligence matters.

Aegis solves this by decoupling detection into an L1 → L4 pipeline: four independent, complementary layers where each layer filters out noise before invoking the more expensive layer downstream.

The L1–L4 Architecture

Candidate: (secretValue, contextLine, variableName)
                     │
                     ▼
┌──────────────────────────────────────────┐
│  L1: Regex Pattern Engine                │ ← Sub-millisecond, in-process
│  Matches well-known vendor prefixes      │   High-confidence match → HIGH
└────────────────────┬─────────────────────┘
                     │ no match
                     ▼
┌──────────────────────────────────────────┐
│  L2: Community Blacklist Cache           │ ← O(1) in-memory Set<string>
│  Truncated composite hash lookup         │   Known leaked hash → HIGH
└────────────────────┬─────────────────────┘
                     │ not in blacklist
                     ▼
┌──────────────────────────────────────────┐
│  L3: Shannon Entropy Gate                │ ← Pure mathematical calculation
│  Normalized entropy < 3.5 → LOW (skip)   │   Filters ~80% of candidate tokens
└────────────────────┬─────────────────────┘
                     │ entropy ≥ 3.5
                     ▼
┌──────────────────────────────────────────┐
│  L4: Contextual Neural Classifier        │ ← Remote FastAPI service
│  35-feature vector + attention layers    │   Deep semantic risk analysis
└──────────────────────────────────────────┘

In our current workload benchmarks across typical codebases, approximately 20% of extracted candidates reach L4. The remaining ~80% are resolved in-memory with sub-millisecond execution times, saving substantial network bandwidth and cloud compute.

Layer 1: In-Process Regex Engine (Instant Confidence)

Known secret formats (like AWS access keys, Stripe live tokens, and GitHub personal access tokens) follow strict, deterministic grammars. Running an AI model to identify a string that starts with AKIA followed by 16 alphanumeric characters is wasteful.

const KNOWN_SECRET_PATTERNS = [
    { name: 'AWS Access Key',  regex: new RegExp(['A', 'KIA', '[0-9A-Z]{16}'].join('')) },
    { name: 'Stripe Live Key', regex: new RegExp(['sk', '_live_', '[0-9a-zA-Z]{24,}'].join('')) },
    { name: 'GitHub Token',    regex: new RegExp(['g', 'hp_', '[a-zA-Z0-9]{36}'].join('')) },
    { name: 'Google API Key',  regex: new RegExp(['AI', 'za', '[0-9A-Za-z\\-_]{35}'].join('')) },
];

An L1 match immediately assigns high risk, bypasses all subsequent layers, and triggers an asynchronous hash report to the community blacklist.

Layer 2: Community Blacklist via Truncated Composite Hashing

When a secret is identified and verified across the community, other developers should benefit instantly without having to re-analyze it through the LLM. However, sharing leaked secrets raises an immediate privacy question: How do you cross-reference secrets without transmitting sensitive values over the network?

L2 utilizes truncated composite hashing:

public hashEntry(variableName: string, value: string): string {
    // Only capture the variable name and the first 8 characters of the value
    const prefix = value.slice(0, 8);
    return crypto
        .createHash('sha256')
        .update(`${variableName}:${prefix}`)
        .digest('hex')
        .substring(0, 16);
}

Privacy Nuance & Threat Model

We deliberately avoid claiming that this hashing scheme is an "absolute privacy shield":

What it accomplishes: The full secret is never transmitted across the wire or stored in community databases.
The engineering trade-off: For very short secrets or known formats, truncated prefixes could theoretically be susceptible to targeted dictionary guessing. We treat this composite hash as an effective deduplication fingerprint for collaborative defense, not a one-way cryptographic commitment for sensitive data.

On extension activation, DotEnvy pulls the promoted blacklist hashes into an in-memory Set<string>. Any candidate lookup is an $O(1)$ memory check with zero network overhead.

Server-Side Anti-Poisoning Architecture

To prevent malicious clients from poisoning the blacklist or whitelisting actual credentials, submissions must pass a server-side reputation pipeline:

Client Submits Hash
        │
        ▼
Staging Queue (Requires 3 distinct environments + reputation weighting)
        │
        ▼
Server-Side Verification (Backend re-evaluates risk on the pattern)
        │
        ▼
Promoted to Community Blacklist

Threat Model Note: The 3-environment quorum and historical accuracy weighting are designed to raise the operational cost of poisoning attacks, rather than claiming Byzantine Sybil-proof consensus. High-accuracy reporters gain vote weight, while repeated false reporters are banned.

Layer 3: Shannon Entropy Gate

Shannon entropy quantifies the unpredictability and information density of a string:

$$H(X) = -\sum_{i=1}^{n} P(x_i) \log_2 P(x_i)$$

In our feature extraction pipeline, Shannon entropy is calculated and normalized into a standard feature scalar:

const features = this.extractFeatures(secretValue, context, variableName);
const entropy = features[7] * 8.0; // Denormalize f[7]

if (entropy < 3.5) { 
    return 'low'; // Skip expensive L4 inference entirely
}

Plain text words and standard identifiers (const databaseHost = "localhost") exhibit low entropy ($\approx 2.1 - 2.8$). Cryptographic secrets and API tokens (sk_live_9xQ8...) typically exhibit entropy values above $4.2$.

Filtering out low-entropy candidates at L3 eliminates the vast majority of false alarms before a single byte touches the network.

Layer 4: Contextual Neural Classifier (Aegis)

Tokens that survive L1–L3 enter L4. This layer evaluates a 35-dimensional feature vector capturing:

Text Morphology (6): Uppercase ratio, digit ratio, symbol density, length normalization.
Entropy Gradients (3): Shannon entropy, bigram entropy, trigram entropy.
Pattern Signals (3): Base64 padding, hex character sets, character transition frequency.
Context Semantics (5): Surrounding keywords (Bearer, Authorization, db_pass, private_key).
Identifier Conventions (4): ALL_CAPS naming, presence of SECRET/TOKEN/KEY substrings.
Structural Separators (4): Dot delimiters (JWTs), underscores, dashes, colons.
Derived Interactions (10): Non-linear threshold flags combining entropy with context sensitivity.

# python-llm/src/model.py
class CustomLLM:
    """Neural risk classifier with self-attention and backpropagation."""
    def __init__(self, config: ModelConfig):
        self.embedding = DenseLayer(35, config.hidden_dim)
        self.attention = MultiHeadSelfAttention(config.hidden_dim, num_heads=4)
        self.classifier = FeedForward(config.hidden_dim, config.num_classes)
        self.optimizer = Adam(learning_rate=0.001)

At its current stage, the classifier is trained on an experimental curated dataset of 112+ labeled secret and non-secret samples. It runs backpropagation via Adam optimization, with model weights persisted in a PostgreSQL database surviving service redeploys.

Important Philosophy: Risk Signals, Not a Security Oracle

A vital design principle behind Aegis:

No layer is treated as an absolute security oracle.
The pipeline generates heuristic risk classifications, not mathematical proofs of secrecy. L1 provides deterministic pattern matching for known vendor formats, while entropy and neural inference provide weighted signals to aid human developers in reviewing their environments.

When the remote model is unreachable or rate limits are reached, the extension seamlessly falls back to local heuristic scoring without crashing or blocking the developer.

OS-Level Key Security: SecretStorage Migration

A secret detector is useless if the extension itself stores encryption keys insecurely.

In earlier versions, master keys lived in VS Code’s workspaceState (essentially unencrypted JSON storage). In Aegis, all master encryption keys and PBKDF2 salts were migrated to VS Code’s OS-level SecretStorage:

macOS: Apple Keychain
Windows: Windows Credential Manager
Linux: Secret Service API / gnome-keyring

public static async ensureMasterKey(context: vscode.ExtensionContext): Promise<Buffer> {
    const secretsKey = `${this.SECRET_STORAGE_KEY_PREFIX}${workspace}`;

    // 1. Check OS SecretStorage
    const stored = await context.secrets.get(secretsKey);
    if (stored) { return Buffer.from(stored, 'base64'); }

    // 2. Zero-touch migration from legacy workspaceState
    const legacyKey = context.workspaceState.get<string>(secretsKey);
    if (legacyKey) {
        await context.secrets.store(secretsKey, legacyKey);
        await context.workspaceState.update(secretsKey, undefined); // Secure cleanup
        return Buffer.from(legacyKey, 'base64');
    }

    // 3. Cryptographically secure 256-bit key generation
    const key = crypto.randomBytes(32);
    await context.secrets.store(secretsKey, key.toString('base64'));
    return key;
}

The migration is completely transparent to the user, executing silently upon extension activation.

Test Verification

Both the TypeScript extension and the Python backend are verified by end-to-end test suites:

DotEnvy Extension (VS Code)

🧪 Running Complete DotEnvy Test Suite

✅ [Encryption Algorithms & PBKDF2]           8/8 passed
✅ [L1–L4 Multi-Layer AI Scanner & HMAC]      4/4 passed  
✅ [Master Key Lifecycle, Password Migration]  9/9 passed

🎉 21/21 TESTS PASSED
npm run compile   → 0 errors
npm run lint      → 0 warnings

Aegis Backend Service (FastAPI / PyTorch)

✅ Feature extractor: 35 features verified - OK
✅ Neural model architecture - loss=1.1534
✅ Forward pass evaluation - prediction: high
✅ Full analyze pipeline execution - confidence: medium
✅ Database round-trip test - weights save/load OK

The Next Challenge: Shipping the Detector

Designing a 4-layer AI scanner was only half the journey.

When we attempted to package this extension into a .vsix bundle and distribute it through the VS Code Marketplace and Open VSX, we collided with two massive engineering road hazards:

The VSIX Trap: How our attempt to authenticate extension requests with our backend accidentally created a critical secret leak vector.
The Scanner Paradox: Why static analysis bots accused DotEnvy of leaking secrets simply because it contained the regex patterns needed to detect them!

👉 Read the complete post-mortem in Part 2:

The VSIX Packaging Trap: How I Eliminated Embedded Client Secrets from a VS Code Extension

Links & Resources

🔗 VS Code Marketplace: marketplace.visualstudio.com/items?itemName=FreeRave.dotenvy
🌐 Open VSX Registry: open-vsx.org/extension/freerave/dotenvy
📦 GitHub Repository: github.com/kareem2099/dotenvy
🐍 Backend Health: https://aegis.dotsuite.dev/health
📝 Changelog: CHANGELOG.md

Written by FreeRave. Contributions and community feedback are always welcome.

DotGhostBoard 2.0.0 'Cerberus': Building a Native Cryptographic Clipboard & Vault for Linux

freerave — Tue, 22 Sep 2026 12:56:36 +0000

Meet DotGhostBoard 2.0.0 — a lightweight, zero-telemetry Linux clipboard manager featuring an encrypted Vault, Shannon entropy secret detection, multi-channel updates, tiling WM support, and native notifications.

Every developer and power user on Linux has wrestled with the clipboard dilemma:

The Classic Utilities: Tools like xclip or basic clipboards do their job, but lack visual search, organization, and security.
The Modern Web Wrappers: Modern tools often arrive packaged in Electron, consuming 400MB+ of RAM just to hold text strings, with opaque network calls and zero encryption.
The Security Risk: Your clipboard regularly holds your most sensitive data — database passwords, GitHub personal access tokens, AWS keys, JWT tokens, and SSH commands. Storing that in plaintext on disk is a massive vulnerability.

We built DotGhostBoard to solve this: a native, lightweight, privacy-first, and cryptographic clipboard security station designed specifically for Linux.

Today, after months of development, architectural refactoring, and rigorous testing, we are excited to release DotGhostBoard v2.0.0 "Cerberus" — our biggest milestone yet! 🚀

⚡ What Makes DotGhostBoard Different?

DotGhostBoard is engineered with pure native technologies: Python 3.11+, PyQt6, SQLite, and cryptography.

Zero Cloud & Zero Telemetry: Everything stays strictly local on your device. No analytics, no phone-home pings, no external network requests.
SQLite Secure Deletion: Uses PRAGMA secure_delete = ON to reduce residual deleted data in SQLite storage by overwriting freed SQLite database pages, paired with explicit handling of Write-Ahead Logs (WAL) and storage cleanup.
Fast Global Hotkeys: Low-overhead global hotkey listeners (Ctrl+Alt+V for Dashboard, Ctrl+Alt+Space for Spotlight Quick Search) with responsive window summoning and instant focus.
Ultra-Lightweight Footprint: Starts near-instantaneously and uses a fraction of the memory footprint of web-based alternatives.

🔍 What Changed in 2.0.0

Cerberus is not a single feature release. It is an architectural rebuild focused on four foundational areas:

Local Cryptographic Storage: AES-256-GCM envelope encryption with ephemeral in-memory reveal for credentials and tokens.
Secret Detection and Handling: Real-time Shannon entropy heuristics that intercept sensitive tokens before clipboard exposure.
Safe Release Channels: Multi-tier delivery (Stable, Beta, Alpha) with strict opt-in pre-releases.
Native Linux Desktop Integration: Direct X11/EWMH workspace migration and FreeDesktop notification support.

🛡️ The Architecture of 2.0.0: Core Subsystems

Here is an engineering deep-dive into everything under the hood:

1. The Encrypted Vault UI Subsystem (`ui/vault/`)

While DotGhostBoard has always featured Eclipse Mode for local item encryption, 2.0.0 introduces The Vault — a dedicated, sliding drawer panel accessible via Ctrl+Shift+V or the sidebar button.

Envelope Encryption (AES-256-GCM): Secrets are protected with authenticated symmetric encryption; plaintexts are never persisted to disk unencrypted.
Category Filtering: Organize passwords, API keys, tokens, SSH credentials, and secure notes with real-time filtering pills.
In-Memory Ephemeral Reveal: Secrets stay masked (••••••••••••••••) by default to prevent shoulder surfing, revealing only on-demand in monospace font and auto-scrubbing from memory when locked.
Zero-Plaintext Deduplication: Computes an in-memory HMAC digest of candidate secrets and evaluates them against existing in-memory secret signatures using constant-time hmac.compare_digest. This prevents storing duplicate secrets without ever persisting plaintext hashes or pre-images into SQLite storage.

2. Zero-Log Password & Secret Detector

One of the most dangerous clipboard events is accidentally copying a production secret. DotGhostBoard 2.0.0 integrates a real-time detection engine (core/security/detector.py):

Shannon Entropy Analysis: Computes the mathematical information entropy ($\ge 3.0$) of copied text alongside character class distribution (mixed casing, digits, symbols).
Smart Heuristics: Identifies API tokens (AWS keys, GitHub PATs, JWTs, Stripe keys, generic credentials).
False-Positive Reduction & Guardrails: Intelligently filters file paths, environment variables (like $PWD), git branch names, code function calls, and multiline snippets to significantly minimize false positives while preserving true secret catches.
Zero-Loss Auto-Encryption: If you copy a secret and miss the toast prompt, the 60-second TTL fallback automatically encrypts the clip into Eclipse history rather than discarding it.

3. Direct "Send to Vault" Workflow

Found an API token in your clipboard history that you want to keep permanently safe?

Text cards now feature a dedicated 🛡️ Send to Vault button and context menu action.
Automatically prefills the secret dialog, decrypts on the fly if previously encrypted under Eclipse, and cleans up the history card seamlessly upon confirmation.

4. Multi-Channel Update Engine (Stable, Beta, Alpha)

Keeping local native desktop apps updated without waiting for distribution package maintainers can be tedious. DotGhostBoard 2.0.0 introduces an integrated Multi-Channel Release Engine:

Select your desired update track in Settings → General:
- Stable: Verified, production-ready releases.
- Beta: Pre-releases and release candidates for early adopters.
- Alpha: Bleeding-edge experimental builds.
Safe Channel Guarantee: Stable is the default channel. Pre-release builds (Beta and Alpha) are strictly opt-in.
The update dialog features live byte-progress indicators, changelog display, and seamless one-click binary restart.

5. System-Native FreeDesktop Notifications

Instead of relying solely on system tray balloons, 2.0.0 talks directly to FreeDesktop notification daemons (/usr/bin/notify-send and D-Bus):

Rich desktop alerts for secret detections, sync events, and updates.
Interactive Click Callback: Clicking a notification immediately foregrounds DotGhostBoard on your active monitor.
Graceful fallback to QSystemTrayIcon if an external notification daemon is not running.

6. Tiling Window Manager & EWMH Workspace Migration

Tiling window manager users (tested on Qtile, and compatible with EWMH-compliant window managers) often suffer from popup clipboard managers getting stuck on inactive workspaces or behaving strangely when toggled.

DotGhostBoard 2.0.0 implements direct EWMH (Extended Window Manager Hints) interaction using Python's standard ctypes directly against libX11.so.6:

When you summon DotGhostBoard (Ctrl+Alt+V or dotghostboard --toggle) from Workspace 2 while the window was previously opened on Workspace 1, DotGhostBoard:
1. Detects _NET_CURRENT_DESKTOP vs _NET_WM_DESKTOP.
2. Resolves the X11 limitation where Qt reports isVisible() == True even on unmapped workspaces.
3. Sends _NET_WM_DESKTOP and _NET_ACTIVE_WINDOW ClientMessages with pager priority (source=2).
4. Automatically migrates the window to your active workspace and focuses it instantly without hiding!
Modal Safety: Dialogs (LockScreen, UnlockDialog) are prepared with prepare_dialog_for_current_workspace() before exec(), guaranteeing modal focus without breaking the Qt event loop.
Kill Switch: DOTGHOST_NO_EWMH=1 is supported for users who prefer traditional window manager handling.

🎨 Cyber-Stealth Phantom Visual Identity

With 2.0.0, we retired the legacy 8-bit ghost icon in favor of the Cyber-Stealth Phantom:

Dark graphite matte squircle paired with a radiant neon green visor (#00ff41).
High-precision downsampling pipeline using Lanczos resampling and unsharp masking, ensuring pixel-perfect sharpness from 16x16 system tray icons up to 512x512 desktop launchers.

🧪 Engineering Quality & Verification

We believe security and privacy utilities must be held to the highest code quality standards:

489 Automated Tests (100% Passing): Unit tests, mock isolation, raw disk zero-overwrite verification, and live integration tests running inside virtual X11 displays (Xvfb) against both Openbox and real Qtile 0.36.0.
Strict Modularity & File Budgets: Architecture guardrails ensure complex UI components remain decoupled and maintainable (ui/dashboard.py strictly adheres to a $\le 500$ LOC limit to eliminate God-object bloat).
Targeted Code Quality: Core coordination modules, window management routines, and security controllers adhere strictly to PEP8/flake8 standards.

📦 How to Get DotGhostBoard 2.0.0

DotGhostBoard is 100% open source under the Apache-2.0 License.

1. OpenDesktop / KDE Store / Pling

You can grab the release package, AppImage, or leave a review on OpenDesktop:
👉 DotGhostBoard on OpenDesktop / Pling

2. GitHub Repository & Releases

Download standalone binaries, AppImages, Debian .deb packages, or inspect the source code:
👉 GitHub: kareem2099/DotGhostBoard

Quick Install from Source:

# Clone the repository
git clone https://github.com/kareem2099/DotGhostBoard.git
cd DotGhostBoard

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run DotGhostBoard
python3 main.py

Enable Global Shortcuts:

Toggle Dashboard: Ctrl+Alt+V
Spotlight Quick Search: Ctrl+Alt+Space
Toggle Encrypted Vault: Ctrl+Shift+V

🤝 Join the Community

Whether you're on Arch, Debian, Ubuntu, Fedora, or Kali Linux — and whether you use GNOME, KDE, or Qtile — DotGhostBoard was built to give you total control and security over your clipboard.

⭐ Star the repo on GitHub
💬 Share feedback and submit feature requests via GitHub Issues
🌐 Check out our listing on OpenDesktop

Cerberus is ultimately about one principle: sensitive clipboard data should remain under the user's control — locally stored, explicitly protected, and never silently promoted to the network.

Happy hacking and secure copying! 👻🔒

From Monolith to Modular Architecture: Refactoring a 2,353-Line PyQt6 Desktop App Without Regressions

freerave — Wed, 16 Sep 2026 15:04:44 +0000

How we transformed DotGhostBoard from a monolithic desktop app into a decoupled, test-driven modular architecture — decomposing monolithic classes, isolating SQLite, and adding 86 tests with zero regressions.

A 2,353-line Dashboard class is rarely just a large file. It is usually a symptom that storage, business logic, security, synchronization, and UI behavior have all collapsed into the same boundary.

That was the state of DotGhostBoard v1.5 — an open-source, privacy-first clipboard manager for Linux built with Python and PyQt6.

What began as a snappy, native desktop tool had accumulated layers of complexity: local AES-GCM encryption, dynamic database queries inside widget click handlers, regex secret detectors on keystrokes, and peer-to-peer LAN sync. Modifying a single button callback risked tripping up the entire Qt event loop.

To prepare the codebase for its upcoming v2.0 milestone (native Wayland protocol support, end-to-end device sync, and extensible plugins), we undertook a comprehensive four-phase refactoring initiative.

The outcome:

ui/dashboard.py shrank from 2,353 to 1,535 lines (-35% LOC).
The automated test suite expanded from 220 to 306 tests across 25 modules (+39% tests).
The entire refactor passed the test suite with zero detected user-facing regressions.

Here is the exact architectural blueprint, design patterns, and lessons learned.

🛑 The "Before" Architecture: The Desktop App Debt Trap

Desktop applications built with GUI frameworks like Qt, Tkinter, or wxWidgets are notoriously susceptible to the monolithic "Blob" antipattern:

[ THE MONOLITHIC ARCHITECTURE ]
┌──────────────────────────────────────────────────────────────────┐
│ Dashboard (ui/dashboard.py) — 2,353 Lines                        │
│  - Raw SQL queries (`cursor.execute(...)`)                       │
│  - AES-GCM crypto encryption/decryption                          │
│  - Card widget lifecycle & pagination                            │
│  - LAN socket broadcasting                                       │
│  - Password prompt modals & session key caching                  │
└──────────────┬──────────────────┬─────────────────┬──────────────┘
               │                  │                 │
      Direct Storage Calls   Qt Event Loop    Tightly Bound Polling
               ▼                  ▼                 ▼
     [ Monolithic SQLite ]   [ UI Signals ]   [ QClipboard Event ]

Three critical pain points made future feature work fragile:

The 2,353-Line Monolithic Dashboard: Button callbacks were directly reading from SQLite, instantiating cipher suites, managing session timers, and firing off network broadcasts.
The 1,100-Line Storage Monolith (core/storage.py): One file handled connection lifecycle, schema migrations, clip CRUD, tag management, collection associations, and peer credentials.
Platform-Tied Clipboard Listener: Capturing clipboard data was tied directly to PyQt's QClipboard.dataChanged event loop. Headless unit testing without an X11 display server was difficult, and supporting Wayland's native wlr-data-control protocol was functionally impossible.

🎯 The Core Architectural Principle

To untangle this, we established a strict rule of separation:

Controllers coordinate UI behavior. Services own business rules. Repositories own persistence. Backends own platform integration.

UI (Widgets / Dialogs)
      │
      ▼
Controllers (ui/controllers/ - QObject Behavioral glue)
      │
      ▼
Services (core/services/ - Headless business logic)
      │
      ▼
Repositories (core/storage/repositories/ - Domain data access)
      │
      ▼
Database (core/storage/database.py - SQLite context & migrations)

Phase 1: Modularizing Storage with the Repository & Facade Patterns

Rather than allowing UI components to issue raw SQL queries, we decomposed core/storage.py into a focused package:

core/storage/
├── __init__.py           # 100% Backward-compatible Facade
├── database.py           # Context-managed connection layer & test paths
├── migrations.py         # Transactional schema migration engine
└── repositories/
    ├── clips.py          # CRUD, AES-256-GCM encryption, image deduplication
    ├── tags.py           # Normalization, tag extraction, rename/delete
    ├── collections.py    # Grouping, filtering, cascade rules
    ├── peers.py          # LAN device trust & credentials
    └── stats.py          # Aggregations & performance metrics

The Backward-Compatible Facade Pattern

A common blunder when refactoring persistence is forcing a sweeping rewrite across every caller at once.

To keep Git diffs manageable and avoid breaking other branches, core/storage/__init__.py serves as a facade, re-exporting original function signatures:

# core/storage/__init__.py (Facade)
from .database import get_db, init_db, close_db
from .repositories.clips import save_clip, get_clips, delete_clip
from .repositories.tags import get_all_tags, normalize_tag
from .repositories.collections import get_collections

# Existing callers continued to function without changing an import!

Transactional Schema Migrations

We implemented an in-house, zero-dependency migration engine (core/storage/migrations.py):

Every schema migration executes within an atomic transaction.
Legacy schema detection auto-promotes pre-existing v1.5 databases.
Includes downgrade guards to prevent older versions from corrupting newer schemas.

Phase 2: Decoupling the Clipboard Engine with Protocols

Previously, the clipboard listener was embedded inside Qt widget callbacks. We extracted this into a headless policy engine:

[ Raw Clipboard Event ]
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                 ClipboardPipeline (Pure Logic)              │
│                                                             │
│  1. Validation      ──► Ignore empty or malformed payloads  │
│  2. App Whitelist   ──► Filter out sensitive applications   │
│  3. Paranoia Filter ──► Check private browsing & incognito  │
│  4. Secret Detector ──► Scan for API keys, tokens, SSH keys │
└─────────────────────────────┬───────────────────────────────┘
                              │
                    CaptureDecision (Action)
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
    [ SAVE_NORMAL ]    [ SECRET_CANDIDATE ]    [ IGNORE ]

Protocol-Based Backends

By specifying a clean Python typing.Protocol, the pipeline doesn't care whether events originate from X11, Qt, or Wayland:

# core/clipboard/backend.py
from typing import Protocol, Callable, Optional
from .events import ClipboardEvent

class ClipboardBackend(Protocol):
    def start(self, callback: Callable[[ClipboardEvent], None]) -> None: ...
    def stop(self) -> None: ...
    def get_current_text(self) -> Optional[str]: ...

Benefits:

We wrapped Qt's clipboard event handling into QtClipboardBackend.
We introduced a lightweight MockClipboardBackend for unit tests, enabling headless test execution in under 4 seconds without Xvfb.
Wayland readiness: The architecture is decoupled so a native Wayland backend can be introduced cleanly in v2.0.

Phase 3: Domain Service Layer & Cryptographic Hardening

Desktop apps frequently leak business logic into UI event listeners. For instance, calculating whether a snippet should trigger an "Auto-Pin" recommendation based on copy frequency was embedded inside a widget slot.

We extracted pure Python service classes into core/services/:

HistoryService: Manages pagination windows, debounced search, duplicate suppression, and copy thresholds (PIN_SUGGESTION_THRESHOLD = 5).
CollectionService: Handles categorization rules and cascade unlinking.
SecurityService: Manages master password verification, session lock timeouts, and key rotation.
SyncService: Validates LAN peer trust handshakes.

Cryptographic Rigor & Envelope Encryption

DotGhostBoard features an encrypted storage mode (The Vault). We hardened key derivation and isolation:

Two-Tier Key Derivation Chain: $$\text{Master Password} \xrightarrow{\text{PBKDF2-HMAC-SHA256 (600,000 iter + Salt)}} \text{Base Key} \xrightarrow{\text{HKDF-SHA256 (Domain Context)}} \text{Vault KEK}$$
- Passwords first pass through PBKDF2-HMAC-SHA256 with 600,000 iterations and a persistent 256-bit random salt.
- The resulting base key is then fed through HKDF-SHA256 with domain context b"dotghostboard:vault:v2". This guarantees that the Vault key is cryptographically independent from other application keys.
Physical Database Isolation & Envelope Encryption:
- Vault items live in a physically distinct SQLite database (vault.db).
- Items are encrypted using a fast Data Encryption Key (DEK). The DEK is encrypted with the Key Encryption Key (KEK).
- Instant Password Rotation: Changing the master password only requires re-wrapping the 32-byte DEK (a constant-time operation taking ~2ms in our local benchmarks), rather than re-encrypting gigabytes of history data.
Defense-in-Depth:
- Added secure_zero() providing best-effort memory scrubbing for sensitive mutable bytearray buffers after cryptographic operations.

Phase 4: Decomposing the 2,353-Line Monolithic Qt Dashboard

Decomposing the central Dashboard window was the most delicate step.

Rather than letting the main window handle every event, we introduced Behavioral QObject Controllers:

                    ┌────────────────────────┐
                    │       Dashboard        │
                    │  (ui/dashboard.py)     │
                    │   Layouts & Visuals    │
                    └───────────┬────────────┘
         ┌───────────────┬──────┴────────┬───────────────┐
         ▼               ▼               ▼               ▼
┌─────────────────┐ ┌──────────┐ ┌───────────────┐ ┌───────────┐
│HistoryController│ │Collection│ │SecurityContr. │ │SyncContr. │
│• Infinite scroll│ │• Sidebar │ │• Vault unlock │ │• LAN P2P  │
│• Search debounce│ │• Drag/drop│ │• Secret reveal│ │• Pairing  │
│• Card lifecycle │ │• Category│ │• Session timer│ │• Discovery│
└─────────────────┘ └──────────┘ └───────────────┘ └───────────┘

Each controller is a dedicated QObject wired through dependency injection:

HistoryController: Manages card pagination, card lifecycle, and 150ms search query debouncing.
CollectionController: Manages category navigation, drag-and-drop targeting, and folder CRUD dialogs.
SecurityController: Oversees session lock/unlock events, secret masking, and unlock prompts.
SyncController: Coordinates peer discovery listings, pairing dialogs, and network status styling.

The Impact:

ui/dashboard.py shrank by 818 lines (2,353 → 1,535 lines).
Zero raw SQL or crypto primitives remain in the UI layer.
Extracted PinSuggestionToast into its own reusable widget module (ui/widgets/pin_toast.py).

🐛 4 Subtle Bugs Discovered (and Fixed) During Refactoring

A comprehensive refactor with high test coverage inevitably unearths long-standing subtle bugs:

1. The Recursive Clipboard Sync Loop

Issue: When a user clicked an existing snippet card in the GUI to copy it to their system clipboard, the clipboard watcher detected the change and triggered a LAN broadcast as if it were a new external capture, creating an infinite echo loop between paired devices.
Fix: Enforced strict signal boundaries. The LAN sync broadcast is triggered only by physical captures originating from Watcher, never from internal UI card copy actions.

2. The $O(N)$ In-Memory Collection Calculation

Issue: Populating collection card counts loaded the entire history table into Python and computed counts using list comprehensions.
Fix: Replaced with a single SQL query utilizing LEFT JOIN and COUNT(clips.id) GROUP BY collections.id, slashing dashboard initialization time from ~210ms to under 8ms.

3. N+1 Deletes in Periodic Cleanup

Issue: The routine cleaning old clips performed individual DELETE FROM clips WHERE id = ? calls inside a Python iteration.
Fix: Refactored to bulk DELETE FROM clips WHERE id IN (...) executed inside a single transaction.

4. Encapsulation Leaks in Session Management

Issue: Widgets were directly reading and mutating private session key attributes across controller instances.
Fix: Replaced with a validated set_session_key() public method enforcing explicit lifecycle transitions.

📊 Before vs. After: Metrics

Metric	Before (v1.5.7)	After (v1.6.0 Phantom)	Impact
Dashboard File Size	2,353 lines	1,535 lines	-35% LOC (-818 lines)
Storage Architecture	1 Monolithic File	7 Decoupled Modules	Repository Pattern + Facade
Automated Tests	220 tests	306 tests	+39% tests (+86 tests across 25 modules)
Test Execution Time	14.2s (with Qt displays)	3.8s (Mock Backends)	3.7x faster test execution
User-Facing Regressions	Baseline	0 detected regressions	Verified via test suite & manual pass
Wayland Readiness	Qt-coupled	Protocol-abstracted	Architecture prepared for native backend

📐 How We Measured

To ensure our metrics were empirical and reproducible:

Lines of Code: Measured using cloc excluding comments, docstrings, and blank lines.
Test Counts & Speed: Measured via pytest run times on an identical Ubuntu 24.04 environment.
Database Latencies: Profiled with sqlite3 EXPLAIN QUERY PLAN and Python's time.perf_counter_ns().
Regression Verification: Confirmed across 306 automated unit/integration tests and a full manual smoke test on X11 and Wayland sessions.

💡 Key Takeaways for Refactoring Desktop Apps

Do Not Start Refactoring Without a Fast Safety Net: Our initial 220-test suite gave us a fast safety net and exposed breaking changes as the refactor progressed. Build your test harness before you touch architecture.
Use Facades to Keep PRs Manageable: Maintain backwards compatibility at module boundaries. Your refactoring doesn't need to break every import path simultaneously.
Decouple Event Loops from Business Logic: Never let UI event loops govern application state. Pure Python classes with Protocol definitions make your business logic portable, maintainable, and lightning-fast to test.
Isolate Signal Flow Early: GUI architectures crumble when signals cascade unpredictably. Define explicit component boundaries for what generates data versus what consumes it.

🚀 What's Next?

With the architecture of DotGhostBoard v1.6.0 "Phantom" stabilized, we are actively developing the v2.0.0 "Cerberus" roadmap:

Native Wayland clipboard engine (wlr-data-control).
Authenticated peer-to-peer device sync.
Extension and plugin system.

🔗 Links & Resources

📦 Download v1.6.0 "Phantom": GitHub Release (AppImage, .deb, Arch)
🌐 OpenDesktop / Pling Store: DotGhostBoard on OpenDesktop
⭐ Source Code & Documentation: GitHub Repository

Have you ever refactored a monolithic desktop application? What patterns helped you untangle complex legacy UI code? Share your thoughts in the comments below!

When "Fast" Became the Only Rule

freerave — Sun, 06 Sep 2026 12:37:37 +0000

A developer's honest look at what really changed between the Roadmap era and the "ship it in five minutes" era — and why the real cost isn't hours worked, it's fragmented attention.

It's almost 1 AM. The screen is still on, and I've been staring at the same line of code for ten minutes. Not because it's complicated — no, because my brain is just empty. Then a message pops up: "Cool, but can we drop this feature and swap in something else? We need it fast."

Fast. How fast? Five minutes.

I'm not exaggerating — this has become a daily shape of my work. And every time I sit with it, I realize the real problem isn't the feature or the code. It's something else entirely: we're working in an era that forgot how to wait.

Back Then: There Was Room for Patience

I remember when I was starting out, there was this thing called a "roadmap." You'd specialize, read, struggle, fail, try again, and after a couple of months you'd actually feel like you'd made progress. I specialized in just Next.js and Python, and that wasn't a flaw — it was the natural path. Go deep on one thing until you master it, then expand.

Even at work, if I changed something small in the UI, it counted as an achievement. Changing a button's look got called "amazing work," even though in reality it was light work. I'd be doing frontend and somehow it felt like I'd shipped an entire backend. Change used to happen once a month, and that was enough to make noise.

Now: Everything Has to "Explode" Every 12 Hours

Today the picture has completely flipped. Same hours, same effort, but the rhythm changed entirely. There's now an expectation that you ship something "huge" every half a day. Not an update, not an improvement — something that wows. And if what you shipped was light or simple, in the client's eyes you're suddenly a "bad developer," even if the task genuinely didn't need more than that.

The strange part is that a lot of the market feels increasingly iterative rather than genuinely innovative — companies keep circling similar ideas while the expected shipping speed keeps rising. Even big companies now ship products fast and patch the bugs later, on the fly, because nobody wants to wait.

The result? Your client sees that model and expects the same speed from their small project, without understanding that not everything is the same.

What Actually Tires Me Out Isn't the Work — It's the Constant Urgency

This is the point I most want to get across. The technical effort itself isn't the problem. The problem is working inside an environment with zero patience. You're expected to add a feature and remove it in under five minutes, as if the system were a light switch you flip on and off. But what actually happens is that every "add and remove" shakes other things inside the architecture, affects things you didn't anticipate, and the system starts wearing down from constant changes with no real foundation behind them.

Then comes the question the client throws at you: "You're using AI, why would you even be tired?"

That question genuinely hurts, because it comes from a real misunderstanding. AI can cut down how long something takes to write — it doesn't remove the responsibility for deciding what to write. AI can accelerate execution. It cannot absorb accountability. If something breaks in production, the client isn't going to go argue with a model — I'm the one holding the consequence of that call. My eyes get tired from the screen, and my brain gets tired from constantly switching between decision and decision — that's real fatigue even if my body never moved. Tiredness isn't always physical; sometimes it's nerve fatigue, and that's the kind nobody sees unless they're the one living it.

AI made code cheaper to produce. It didn't make change cheaper to understand.

What Actually Helped Me Survive This Workflow

I won't pretend I have a silver-bullet answer, but a few things have actually reduced the pressure for me:

Draw a clear, spoken line between a "light touch" and a "core change." When someone asks to swap a feature out for another, calmly explain that this isn't a light switch — it takes time to make sure the system doesn't break. Transparency here protects you more than anything else.
Try to batch scattered requests instead of reacting to each one instantly. Instead of replying the moment a message lands, suggest that requests get grouped and prioritized, even informally. It gives you thinking space instead of constant reflex-mode.
Use feature flags instead of directly ripping code in and out. This lets you "turn off" or "turn on" something without touching the foundation, and it actually saves real time and effort down the line.
Say "no" professionally when a request doesn't make sense. You don't have to agree to everything just because the client is in a hurry. Explain what rushing would actually cost, and let them make the call with the full picture in front of them.
Protect your time without guilt. You don't have to respond outside working hours just because a message arrived. A quick "I'll look at this in the morning" beats a rushed decision made at 1 AM.

Closing: Speed Isn't the Problem — Treating Patience as a Luxury Is

I'm not saying speed is a bad thing, or that every impatient client is wrong. The market genuinely changed, and expectations changed with it. But there's a real difference between "speed" and "urgency without understanding." Speed needs structure. Urgency just needs a little patience so nobody gets burned out.

At the end of the day, I can still end up at my desk from around 9 AM to 1 AM — not something I'd call healthy or sustainable, just an honest description of where I am right now. But the strange part is that the number of hours isn't really what changed. The fragmentation did: back then those hours were long, connected stretches of exploring and learning; now they're broken into reactions, all day, to whatever just landed in the chat. Maybe that's the real challenge for developers in this era: not learning some new technology, but learning how to protect your attention — and your sanity — around people who forgot how to wait.

Have you dealt with something like this? How do you handle an impatient client who won't give you room to breathe? Let me know in the comments 👇

Inside DotFetch v2.1.0: Auth Boundaries, WebView Security, and Request Architecture

freerave — Thu, 20 Aug 2026 14:05:17 +0000

A deep dive into building DotFetch v2.1.0: Modular architecture in VS Code WebViews, RFC 6749 OAuth 2.0, backend-owned Basic Auth with environment variables, and safe credential isolation.

The Context Switching Problem

Context switching is one of the most frustrating parts of building backend services.

Every time you write an API endpoint in VS Code, you switch windows to a standalone API client, wait for it to load, configure environment variables, run the request, and switch back to your editor.

We created DotFetch to bring a lightweight, dark-themed HTTP client directly into your VS Code workspace — native .env variable support, collections, cURL import/export, and zero UI bloat.

In v2.0.0, we built the initial request builder with structured parameter and header tables.

For v2.1.0, our focus shifted to engineering a hardened authentication and security layer designed for real-world API workflows. The challenge was resolving the architectural edge cases that appeared once authentication, persistence, and environment substitution started interacting.

Here is an inside look at how we designed and refactored DotFetch v2.1.0.

🏗️ 1. Architecture: Modular Frontend in a Sandboxed WebView

A common problem in VS Code extension development is stuffing DOM manipulation, business logic, and IPC handling into a single monolithic script.

In DotFetch v2.1.0, we structured the frontend into an MVC-inspired modular frontend architecture:

DotFetch Architecture
├── Extension Host (Node.js Runtime)
│   ├── RequestService.ts       ← Axios execution engine, SSL Agent, OAuth token fetcher
│   ├── DataManager.ts          ← globalState persistence (History & Collections)
│   ├── EnvironmentManager.ts   ← .env parsing & {{VAR}} substitution
│   └── webviewPanel.ts         ← IPC Message Router & CSP builder
│
└── Frontend WebView (Browser Runtime - src/webview/)
    ├── main.js                 ← Central Controller & event dispatcher
    ├── request.js              ← Form state, live assembly & send logic
    ├── auth.js                 ← Auth rendering, live previews & RFC validation
    ├── ui.js                   ← Structured tables, response tabs & badges
    ├── shortcuts.js            ← Configurable keyboard shortcuts
    ├── state.js                ← Single source of truth & canonical schemas
    └── api.js                  ← postMessage transport layer

The Bundling Strategy under Strict CSP

DotFetch applies a strict Content-Security-Policy to its VS Code WebView, using nonce-based script execution:

<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'nonce-${nonce}'; ...">

Bundling simplifies WebView resource loading and CSP management while keeping the source code modular during development.

We maintain clean ES modules in src/webview/ during development, and use esbuild to bundle src/webview/main.js into a single IIFE bundle (media/script.js) in ~30ms local build time in our development setup:

"esbuild-base": "esbuild ./src/extension.ts --bundle --outfile=out/extension.js --external:vscode --format=cjs --platform=node && esbuild ./src/webview/main.js --bundle --outfile=media/script.js --format=iife --platform=browser"

This keeps the codebase modular and readable in source control while shipping a single, CSP-compliant script at runtime.

🔐 2. The Authentication Suite

🔑 API Key Authentication (Header vs. Query Mode)

APIs accept keys differently. Some require custom HTTP headers (X-API-Key: secret), while others expect query parameters (?api_key=secret).

We built an interactive UI that lets developers switch modes with real-time visual previews and a copy button:

// src/webview/auth.js
export function updateApiKeyPreview() {
    const preview = document.getElementById('auth-preview');
    if (!preview) return;
    const keyName = state.authConfig.keyName || '';
    const keyValue = state.authConfig.keyValue || '';
    const keyIn = state.authConfig.keyIn || 'header';

    if (keyName && keyValue) {
        const text = keyIn === 'header' ? `${keyName}: ${keyValue}` : `?${keyName}=${keyValue}`;
        preview.innerHTML = `<span>${text}</span><button type="button" class="tool-btn" id="copy-auth-preview">Copy</button>`;
        preview.classList.remove('hidden');
    }
}

When sent in Query Parameter mode, the headers table remains untouched and RequestService injects the key into the URL string on the Node.js side right before execution.

⚡ OAuth 2.0 (Client Credentials Flow)

Machine-to-machine APIs (Spotify, Twitch, Azure, Auth0) frequently rely on OAuth 2.0 Client Credentials.

Instead of writing separate shell scripts:

Enter your Token URL, Client ID, Client Secret, and Scope.
Click "⚡ Fetch & Inject Token".
DotFetch contacts the OAuth provider, extracts the access_token, displays an active token status card with expiration metadata, and injects Authorization: Bearer <token> into your live requests.

// src/requestService.ts - RFC 6749 §2.3.1 Compliance
public async fetchOAuthToken(message: any, webview: vscode.Webview) {
    const tokenUrl = this.environmentManager.substituteVariables(message.tokenUrl, env).trim();
    const clientId = this.environmentManager.substituteVariables(message.clientId, env).trim();
    const clientSecret = this.environmentManager.substituteVariables(message.clientSecret, env).trim();
    const scope = this.environmentManager.substituteVariables(message.scope, env).trim();

    const params = new URLSearchParams();
    params.append('grant_type', 'client_credentials');
    if (scope) { params.append('scope', scope); }

    const headers: Record<string, string> = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    };

    // RFC 6749 §2.3.1: client_id & client_secret MUST be URL-encoded before Base64 encoding
    if (clientId && clientSecret) {
        const formEncode = (value: string) => encodeURIComponent(value).replace(/%20/g, '+');
        const basicCreds = Buffer.from(
            `${formEncode(clientId)}:${formEncode(clientSecret)}`,
            'utf8'
        ).toString('base64');
        headers['Authorization'] = `Basic ${basicCreds}`;
    }

    const response = await axios.post(tokenUrl, params.toString(), { headers, timeout: 15000 });
    // Returns access_token, token_type, expires_in to WebView...
}

🛡️ SSL/TLS Toggle for Local Development

When testing microservices locally with self-signed SSL certificates (https://localhost:8080), Node.js rejects the connection with certificate verification errors.

DotFetch v2.1.0 provides an SSL Toggle with a prominent toolbar warning badge (⚠️ SSL Ignored):

const httpsAgent = message.sslVerify === false
    ? new https.Agent({ rejectUnauthorized: false })
    : undefined;

To prevent accidental security gaps, every request load enforces a secure default (sslVerify: true).

🛠️ 3. Solving the Hard Architectural Edge Cases

The auth features were straightforward. The difficult part was keeping authentication, persistence, and request execution from contaminating each other.

🧩 1. The "Draft vs. Wire" Headers Contamination

The Problem: When you send a request with Bearer Auth, the client injects Authorization: Bearer <token> into the outgoing wire headers. If the user clicked "Save to Collection", that injected header was saved into the raw headers table. Later, loading that request and switching to "No Auth" caused the old token to remain in manual headers and still be sent.

The Solution: We decoupled Draft Data (for storage) from Wire Data (for execution):

// src/webview/request.js
export function getRequestData({ forSend = false } = {}) {
    const rawHeaders = serializeHeaders();

    // Wire headers get auth injection; Saved draft headers stay clean
    const headers = forSend ? applyAuthHeaderToRawHeaders(rawHeaders) : rawHeaders;

    // Live send keeps in-memory secrets; Storage strips them
    const auth = forSend ? { ...state.authConfig } : createPersistableAuthConfig();

    return {
        method: document.getElementById('method')?.value || 'GET',
        url: constructFullUrl(),
        headers,
        auth,
        sslVerify: state.settings.sslVerify !== false
    };
}

🧩 2. Basic Auth + Environment Variables Base64 Deadlock

The Problem: The UI allows Username: {{API_USER}} and Password: {{API_PASS}}.

If the WebView constructs Authorization: Basic ${btoa(${user}:${pass})}, it produces Base64 ciphertext of the literal string {{API_USER}}:{{API_PASS}}. When the Extension Host receives it, it cannot substitute the environment variables because they are locked inside Base64.

The Solution: Make Basic Auth 100% Backend-Owned:

The WebView strips any conflicting manual Authorization header.
RequestService on the Extension Host performs variable substitution first, and then computes the Base64 header in Node.js runtime:

// src/requestService.ts
if (message.auth?.type === 'basic') {
    const rawUser = message.auth.username || '';
    const rawPass = message.auth.password || '';
    const user = this.environmentManager.substituteVariables(rawUser, selectedEnv);
    const pass = this.environmentManager.substituteVariables(rawPass, selectedEnv);
    if (user || pass) {
        const basicCreds = Buffer.from(`${user}:${pass}`, 'utf8').toString('base64');
        substitutedHeaders['Authorization'] = `Basic ${basicCreds}`;
    }
}

🧩 3. Zero-Persistence Plaintext Secrets across Collections, Favorites & History

The Problem: vscode.ExtensionContext.globalState is used for persisting collections and history. Storing raw passwords, tokens, API key values, or OAuth secrets as plaintext JSON in globalState is an unnecessary security risk.

The Solution: Plaintext runtime credentials are stripped before DotFetch persists request metadata to globalState across Collections, Favorites, and History:

// src/webview/state.js
export function createPersistableAuthConfig(authConfig = state.authConfig) {
    return {
        ...authConfig,
        password: '',
        token: '',
        keyValue: '',
        clientSecret: '',
        accessToken: '',
        expiresIn: null,
        tokenReceivedAt: null
    };
}

When a request executes, sendRequest() passes both requestData (live wire credentials) and historyData (sanitized snapshot). On success, webviewPanel.ts persists only the sanitized snapshot:

// src/webviewPanel.ts
if (capturedResponse) {
    const safeRequest = message.historyData || {};
    const historyEntry: RequestData = {
        name: safeRequest.name,
        url: safeRequest.url,
        headers: safeRequest.headers, // Clean manual headers
        auth: safeRequest.auth,       // Stripped secrets
        status: capturedResponse.status,
        duration: capturedResponse.duration,
        createdAt: new Date().toISOString()
    };
    await this.dataManager.addHistory(historyEntry);
}

🧩 4. Guarding Against Memory-Exploding Payloads

The Problem: If an API endpoint returns a 50MB JSON payload, transferring that full payload across the VS Code postMessage IPC boundary will freeze the WebView and lag the editor.

The Solution: We implemented double-layered response protection:

Network Layer: Axios enforces maxContentLength: 10 * 1024 * 1024 (10 MB).
Display Layer: If the response exceeds 1 MB (DISPLAY_THRESHOLD), we compute accurate UTF-8 byte length via Buffer.byteLength() and truncate the WebView preview to the first 1000 characters with a helpful badge:

// src/requestService.ts
const serializedResponse = typeof response.data === 'string'
    ? response.data
    : JSON.stringify(response.data ?? '');

const responseSize = Buffer.byteLength(serializedResponse, 'utf8');
const isLarge = responseSize > RequestService.DISPLAY_THRESHOLD;

webview.postMessage({
    type: 'response',
    status: response.status,
    duration,
    size: responseSize,
    headers: response.headers,
    isLarge,
    data: isLarge
        ? `[Response too large: ${(responseSize / 1024).toFixed(2)} KB]\n\nFirst 1000 characters:\n${serializedResponse.substring(0, 1000)}...`
        : response.data
});

🧪 4. How We Verified It

Before tagging v2.1.0, we run our quality gates:

npm run compile
npm run typecheck
npm run lint

Then we validate the runtime test matrix manually across scenarios:

No Auth: Raw headers sent unchanged; no injected tokens
Basic Auth (Literal): Safe UTF-8 Base64 encoding; manual headers overridden
Basic Auth (Variables): {{USER}} & {{PASS}} substituted before Base64
Bearer Token: Injected on wire only; excluded from saved collections
API Key (Header): Custom header injection; live preview works
API Key (Query): Injected into URL query string; headers table untouched
OAuth 2.0 Flow: RFC 6749 URL encoding; active token card display; expired token blocks send
Save & Reload: Schema restored cleanly; zero header contamination
History Sanitization: Plaintext secrets omitted from globalState
SSL Toggle: Localhost bypasses SSL when disabled with active warning badge
Memory Guard: Payloads > 1MB safely truncated in preview
Cancel & Retry: AbortController halts execution; network retry with exponential backoff

📊 Summary of What DotFetch v2.1.0 Delivers

Feature Area	What You Get
Authentication	Bearer Token, Basic Auth (env-aware), API Key (Header & Query), OAuth 2.0 Client Credentials
UI & Visibility	Interactive eye toggles (👁️ / 🙈), Response Headers Inspector table, Live previews
Security & Privacy	Zero-persistence plaintext secret policy across Collections, Favorites & History, SSL Toggle
Performance	10MB payload size limits, 1MB large response truncation, modular WebView source bundled into a single CSP-compatible runtime
Code Health	Zero TypeScript typecheck errors, strict ESLint pass, clean IPC separation

🚀 Try DotFetch

DotFetch is free, open-source, and built for developers who appreciate clean tools.

📦 VS Code Marketplace: Install DotFetch
🌐 Open VSX Registry: Install DotFetch
⭐ GitHub Repository: kareem2099/DotFetch

Have feedback or feature suggestions for v2.2? Drop a comment below or open an issue on GitHub!

Building DotGhostBoard v1.5.5: Spotlight Search, SHA-256 Image Deduplication & Zero-Trust Clipboard Security in PyQt6

freerave — Thu, 06 Aug 2026 13:31:27 +0000

How we built a Kali Linux-native, privacy-first clipboard manager featuring a floating Spotlight search overlay (Ctrl+Shift+F), smart image hashing, search input debouncing, and Master Password security.

I was working on Kali Linux, taking multiple screenshot captures of terminal error tracebacks and copying temporary API bearer tokens, when I realized two frustrating things:

My disk was getting littered with dozens of duplicate PNG screenshots (capture_1427.png, capture_1428.png) taking up space and cluttering my feed.
The clipboard managers available on Linux were either heavy Electron apps devouring 350MB+ RAM just sitting in the tray, or basic plain-text loggers that stored sensitive API keys unencrypted on disk.

That's why we built DotGhostBoard — a Kali Linux-native, privacy-first, zero-trust clipboard manager built with Python 3 and PyQt6. It features AES-256-GCM encryption, local SQLite storage, global hotkey overlays, and a dark neon aesthetic — using ~85 MB of Full Runtime RAM.

In this article, we'll dive deep into the architecture, design choices, and actual Python code behind the new features introduced in v1.5.5 (Nexus Polish & Spotlight).

🚀 Key Features Introduced in v1.5.5

Here is what we engineered for this release:

🔍 Spotlight Quick Search Overlay (ui/spotlight.py): A frameless, floating quick-search popup accessible globally via Ctrl+Shift+F.
🖼️ Smart Image SHA-256 Deduplication (core/storage.py): Automatic pixel hashing that prevents duplicate screenshots from cluttering disk space or UI feeds.
🔐 Master Password Protection for Secret Copying (ui/dashboard.py): Zero-leak in-memory decryption for encrypted clipboard items.
⚡ Search Input Debouncing (QTimer): 150ms–200ms non-blocking debounce timers to eliminate UI lag during rapid typing.
📊 Dashboard Stats Header & Relative Time Refresh: Real-time state summary banner and relative timestamps ("just now", "5m ago", "2h ago").

1. Spotlight Quick Search Overlay (`ui/spotlight.py`)

A core goal of v1.5.5 was allowing users to query their clipboard history from any application without switching windows manually.

We designed SpotlightSearchDialog using PyQt6's QDialog with frameless window hints and active screen auto-centering:

🔗 GitHub Source Code: ui/spotlight.py

from PyQt6.QtWidgets import (
    QDialog, QVBoxLayout, QLineEdit, QListWidget,
    QListWidgetItem, QLabel, QHBoxLayout, QFrame,
    QApplication, QGraphicsDropShadowEffect
)
from PyQt6.QtCore import Qt, pyqtSignal, QEvent, QTimer
from PyQt6.QtGui import QColor, QKeyEvent

from core import storage


class SpotlightSearchDialog(QDialog):
    """
    Spotlight-style floating search overlay.
    - Frameless, stays on top, centered on active monitor.
    - Up / Down / Enter keyboard navigation.
    - Emits sig_item_selected(item) when user picks an item.
    """
    sig_item_selected = pyqtSignal(dict)

    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowFlags(
            Qt.WindowType.FramelessWindowHint |
            Qt.WindowType.WindowStaysOnTopHint |
            Qt.WindowType.Tool
        )
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)
        self.setFixedWidth(640)
        self.setFixedHeight(420)

        self._items = []
        self._pending_query = ""

        # 150ms search debounce timer
        self._search_timer = QTimer(self)
        self._search_timer.setSingleShot(True)
        self._search_timer.setInterval(150)
        self._search_timer.timeout.connect(self._do_search)

        self._build_ui()
        self._center_on_screen()

Keyboard Navigation & Focus Loss

To make Spotlight feel as smooth as macOS Spotlight or Raycast:

eventFilter captures Up, Down, Enter, and Esc keys regardless of whether focus is on the QLineEdit or QListWidget.
Encrypted secret items (is_secret == 1) are masked with 🔒 Secret Item (Encrypted) to prevent sensitive data leaks.
changeEvent listens for ActivationChange to automatically hide Spotlight when the user clicks outside.

    def eventFilter(self, obj, event):
        if event.type() == QEvent.Type.KeyPress:
            key_event: QKeyEvent = event
            key = key_event.key()

            if key == Qt.Key.Key_Escape:
                self.hide()
                return True

            elif key == Qt.Key.Key_Down:
                cur = self.results_list.currentRow()
                if cur < self.results_list.count() - 1:
                    self.results_list.setCurrentRow(cur + 1)
                return True

            elif key == Qt.Key.Key_Up:
                cur = self.results_list.currentRow()
                if cur > 0:
                    self.results_list.setCurrentRow(cur - 1)
                return True

            elif key in (Qt.Key.Key_Return, Qt.Key.Key_Enter):
                current_item = self.results_list.currentItem()
                if current_item:
                    self._on_item_activated(current_item)
                return True

        return super().eventFilter(obj, event)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.ActivationChange:
            if not self.isActiveWindow():
                self.hide()
        super().changeEvent(event)

2. Smart Image Deduplication via SHA-256 (`core/storage.py`)

The Problem

When capturing screenshots or images from the system clipboard, QImage.save() creates a new temporary PNG file (e.g., capture_20260805_142748.png). Because each file gets a timestamped path, traditional string matching (WHERE content = ?) fails to recognize identical images. This led to duplicate cards filling the dashboard and wasting disk space.

The Solution: SHA-256 Image Hashing

Inside storage.add_item(), when an image is saved:

Compute the SHA-256 checksum of the new PNG file.
Query existing image rows in SQLite.
If an existing image has the exact same SHA-256 hash:
- Purge the newly generated temporary PNG file from disk (os.remove()).
- Execute UPDATE clipboard_items SET updated_at = NOW, copy_count = copy_count + 1 WHERE id = ?.
- Return the existing item ID so the UI floats the original image card to the top with an updated frequency badge (×2, ×3, 🔥 ×10)!

🔗 GitHub Source Code: core/storage.py

import hashlib

def _get_file_hash(filepath: str) -> str | None:
    """Calculate SHA-256 hash of a file for image duplicate detection."""
    if not filepath or not os.path.isfile(filepath):
        return None
    try:
        h = hashlib.sha256()
        with open(filepath, "rb") as f:
            for chunk in iter(lambda: f.read(65536), b""):
                h.update(chunk)
        return h.hexdigest()
    except OSError:
        return None


def add_item(item_type: str, content: str, preview: str = None) -> int:
    """
    Add a new item to the database using a 3-stage cascade for optimal performance:
    - Stage 1: Fast O(1) string match (avoids unnecessary disk IO).
    - Stage 2: SHA-256 pixel hash match for images (resolves timestamped file duplicates).
    - Stage 3: Clean SQL insertion for brand new unique items.
    """
    # ── STAGE 1: Direct Content Match ──
    # Check text strings or identical paths first. This is an immediate SQL lookup,
    # avoiding heavy disk reads if the exact same text or path was already recorded.
    existing = get_item_by_content(content)
    if existing:
        now = datetime.now().isoformat()
        with _db() as conn:
            conn.execute(
                "UPDATE clipboard_items SET updated_at = ?, copy_count = copy_count + 1 WHERE id = ?",
                (now, existing["id"]),
            )
        return existing["id"]

    # ── STAGE 2: SHA-256 Image Content Hash Match ──
    # If content paths differ (e.g. capture_1001.png vs capture_1002.png), compare actual pixel hashes.
    # We filter by file size first (os.path.getsize) to avoid computing SHA-256 on non-matching sizes!
    if item_type == "image" and os.path.isfile(content):
        new_hash = _get_file_hash(content)
        if new_hash:
            new_size = os.path.getsize(content)
            with _db() as conn:
                rows = conn.execute(
                    "SELECT id, content FROM clipboard_items WHERE type = 'image' ORDER BY updated_at DESC LIMIT 100"
                ).fetchall()

            for row in rows:
                existing_path = row["content"]
                if existing_path and os.path.isfile(existing_path):
                    # Fast pre-check: Compare file size before hashing disk bytes
                    if os.path.getsize(existing_path) == new_size:
                        if _get_file_hash(existing_path) == new_hash:
                            # Duplicate image pixels detected! Delete the new redundant temporary file
                            try:
                                os.remove(content)
                            except OSError:
                                pass

                            now = datetime.now().isoformat()
                            with _db() as conn:
                                conn.execute(
                                    "UPDATE clipboard_items SET updated_at = ?, copy_count = copy_count + 1 WHERE id = ?",
                                    (now, row["id"]),
                                )
                            return row["id"]

    # ── STAGE 3: New Unique Item Insertion ──
    # If neither string content nor SHA-256 hash matched, insert as a brand new item.
    now = datetime.now().isoformat()
    with _db() as conn:
        cursor = conn.execute("""
            INSERT INTO clipboard_items (type, content, preview, is_pinned, copy_count, created_at, updated_at)
            VALUES (?, ?, ?, 0, 1, ?, ?)
        """, (item_type, content, preview, now, now))
        return cursor.lastrowid

3. Zero-Leak Master Password Verification (`ui/dashboard.py`)

DotGhostBoard allows users to encrypt sensitive clips (e.g., API keys, passwords) using AES-256-GCM.

When a user copies a secret item from Spotlight or the Dashboard:

_on_copy(item_id) checks if item.get("is_secret") is true.
If the session is locked (_active_key is None), it prompts for the Master Password via LockScreen.
The content is decrypted in-memory only for copying to the OS clipboard.
watcher.mark_self_paste() informs the clipboard watcher to ignore the newly pasted plaintext so it is never saved back to the database as an unencrypted card.

🛡️ Zero-Leak Security Architecture:

Zero Disk Leak: Decryption happens strictly in-memory during copy (storage.decrypt_item).

Watcher Interception: watcher.mark_self_paste() intercepts the next clipboard polling tick, updating _last_content to ignore the text and preventing the watcher thread from re-saving the unencrypted secret back into SQLite.

UI RAM Purge: When locking the session, on_session_locked() immediately purges plaintext from Qt UI labels (setText("")) so sensitive data never lingers in widget memory.

Note: These protections completely prevent secrets from leaking back into DotGhostBoard's SQLite database or UI widgets. They do not yet control how long the plaintext sits on the OS-level clipboard buffer after pasting — which is why our upcoming v2.0 release introduces an automated 30-second clipboard wipe.

🔗 GitHub Source Code: ui/dashboard.py

    def _on_copy(self, item_id: int):
        item = storage.get_item_by_id(item_id)
        if not item:
            return

        if item.get("is_secret"):
            # Check if session is unlocked
            if self._active_key is None:
                dlg = LockScreen(setup=False)
                if dlg.exec() == LockScreen.DialogCode.Accepted:
                    self._active_key = dlg.get_key()
                    self._reset_auto_lock()
                else:
                    self.statusBar().showMessage("⚠ Session is locked — unlock to copy secret.")
                    return

            # Decrypt item content in-memory for copying
            plaintext = storage.decrypt_item(item_id, self._active_key)
            if plaintext is None:
                self.statusBar().showMessage("⚠ Decryption failed — wrong key or corrupted data.")
                return

            item["content"] = plaintext

        # Mark as self-paste so watcher updates _last_content without re-capturing
        self.watcher.mark_self_paste()
        self.watcher.paste_item_to_clipboard(item)

        # Increment copy count in DB and refresh UI badge
        new_count = storage.increment_copy_count(item_id)
        card = self._cards.get(item_id)
        if card:
            card.update_copy_count(new_count)

        self.statusBar().showMessage(f"Copied! ⏘  (×{new_count})")

4. Search Input Debouncing with `QTimer`

Connecting QLineEdit.textChanged directly to database queries causes UI freezing during rapid typing because every single keystroke executes an SQL query and clears/rebuilds PyQt6 widgets.

We implemented a single-shot QTimer debounce pattern in both the main Dashboard (200ms) and Spotlight (150ms):

🔗 GitHub Source Code: ui/dashboard.py | ui/spotlight.py

    # Inside Dashboard.__init__
    self._search_timer = QTimer(self)
    self._search_timer.setSingleShot(True)
    self._search_timer.setInterval(200)
    self._search_timer.timeout.connect(self._do_search)
    self._pending_search_query = ""

    def _on_search(self, query: str):
        """Debounce search box input by 200ms."""
        self._pending_search_query = query
        if not query.strip():
            self._search_timer.stop()
            self._do_search()  # Instant clear on empty input
        else:
            self._search_timer.start()

    def _do_search(self):
        """Execute SQL query & UI rebuild after 200ms pause in typing."""
        query = getattr(self, "_pending_search_query", "")
        # ... SQL search & widget pagination ...

5. Dashboard State Summary Banner (`StatsHeaderCard`)

At the top of the history feed, StatsHeaderCard provides a live state summary:

📋 Today: Total clips captured today.
🔥 Top: Most frequently copied clip created today (excluding encrypted secrets).
📍 Pinned: Total count of pinned clips.

🔗 GitHub Source Code: core/storage.py

def get_today_stats() -> dict:
    today_prefix = datetime.now().strftime("%Y-%m-%d")
    with _db() as conn:
        cur1 = conn.execute(
            "SELECT COUNT(*) as cnt FROM clipboard_items WHERE created_at LIKE ?",
            (f"{today_prefix}%",)
        )
        total_today = cur1.fetchone()["cnt"]

        cur3 = conn.execute(
            """
            SELECT preview, content, copy_count
            FROM clipboard_items
            WHERE copy_count > 0
              AND created_at LIKE ?
              AND COALESCE(is_secret, 0) = 0
            ORDER BY copy_count DESC, updated_at DESC
            LIMIT 1
            """,
            (f"{today_prefix}%",)
        )
        top_row = cur3.fetchone()
        # ... format & return dict ...

🧪 Testing & Verification

We maintained strict TDD practices throughout development, writing 184 unit tests using pytest:

🔗 GitHub Test Suite: tests/test_v155_polish.py

============================= 184 passed in 8.40s ==============================

Every component — from relative timestamp calculation (_format_time) to SHA-256 image deduplication and reset_copy_count boolean return values — is covered by automated unit tests in tests/test_v155_polish.py.

📦 Packaging & Installation on Linux

DotGhostBoard is packaged for multiple Linux distributions including AppImage, .deb, Arch Linux (.pkg.tar.zst), and generic .tar.gz:

You can download pre-built release assets from:

📦 GitHub Release v1.5.5: https://github.com/kareem2099/DotGhostBoard/releases/tag/v1.5.5
🛍️ OpenDesktop / Pling Store: https://www.opendesktop.org/p/2353623/

# Build DEB package locally
./scripts/build_deb.sh

# Install on Kali Linux / Debian / Ubuntu
sudo dpkg -i dotghostboard_1.5.5_amd64.deb

🔮 What's Next? The Roadmap to DotGhostBoard v2.x (Cerberus)

With the v1.5.x milestone complete, we are officially transitioning development to DotGhostBoard v2.x!

Here is a sneak peek at the exciting features engineered for the upcoming v2.0.0 (Cerberus) release:

🔒 The Vault (vault.db): An isolated, zero-knowledge encrypted database completely separate from ghost.db, protected by an independent Master Password for ultimate credential security.
🧠 Regex Smart Secret Detection: Pattern-based heuristic detection for API Keys, AWS credentials (AKIA...), GitHub PATs (ghp_...), JWT tokens, and high-entropy secrets — automatically prompting users to move them into The Vault.
⏳ 30-Second Auto-Wipe: Automatic clipboard buffer wiping 30 seconds after pasting sensitive tokens from the Vault.
🕵️ Paranoia / Zero-Logging Mode: A single-click stealth mode toggle that temporarily halts all local database logging.

🌟 Conclusion & Performance Benchmarks

Building DotGhostBoard v1.5.5 proved that Linux desktop utilities don't need heavy web runtimes to deliver modern, fluid UI experiences. By choosing Python 3, PyQt6, and SQLite, we measured significant performance advantages in our local testing compared to typical Electron alternatives:

🟢 Full Runtime RAM: ~85 MB process RSS (GUI + SQLite DB + Spotlight dialog loaded) vs ~350 MB+ in typical Electron clipboard tools.
⚡ Spotlight Query Latency: ~3.5 ms average execution time across 10 runs (min 2.23 ms, max 4.90 ms).
💾 Disk Optimization: SHA-256 deduplication saved ~85% disk space during screenshot-heavy debugging sessions.
📊 Automated Suite: 184 / 184 tests passing in 8.32s.

Check out the full source code, download release packages, and star the repository on GitHub:
👉 GitHub Repository: https://github.com/kareem2099/DotGhostBoard
👉 GitHub Release (v1.5.5): https://github.com/kareem2099/DotGhostBoard/releases/tag/v1.5.5
👉 OpenDesktop / Pling Store: https://www.opendesktop.org/p/2353623/

💬 Technical Discussion

If you were designing our v2.0 Regex Smart Secret Detection Engine, what would be the very first pattern or entropy rule you'd include to catch leaked keys? Drop your regex patterns or PR suggestions below! 🚀

How I Refactored My Developer Portfolio Into a Modular, Secure, and Playfully Destructive Playground (v1.1.0)

freerave — Fri, 17 Jul 2026 20:25:39 +0000

A deep dive into refactoring a 1500+ line JS monolith into elegant ES6 modules, boosting performance by 95%, fixing XSS vectors, and adding a treacherous text-based game easter egg.

A developer's portfolio is more than just a resume—it is a playground. When I built dotUniverse, a cyberpunk-themed portfolio simulating a Kali Linux terminal, it quickly grew into a massive playground. But like many rapid prototypes, it eventually hit a wall: a 1500+ line monolithic script.js file, performance lag on mobile, security warnings, and missing interactive elements.

In this article, I will walk you through how I completed a 1.1.0 Modular Refactor, boosting performance by 95%, hardening security, and adding a highly engaging (and slightly treacherous) easter egg game that lets users "destroy" and restore the site.

🛠️ The Architecture: Breaking the Monolith

Originally, the terminal commands, particle physics, scrolling, and UI triggers lived in a single script. I refactored this into clean, scoped ES6 Modules managed by a single entry point:

js/
├── app.js                      # Entry point (initializes modules & defines commands)
└── modules/
    ├── particle-system.js       # Custom canvas particles + spatial grid optimization
    ├── math-eval.js             # Safe mathematical parser (No eval/new Function)
    ├── terminal-emulator.js     # CLI input handling & tab-completion state
    ├── challenges.js            # Challenge progress tracking
    ├── scroll-effects.js        # Lazy-loading scroll reveals
    └── theme-manager.js         # Color theme manager

The Terminal State Controller

To allow interactive sub-prompts (like confirmations or games), I introduced a promptHook mechanism in the terminal. When a command sets promptHook, all subsequent keypresses are redirected to that function instead of being parsed as new terminal commands.

Here is the key logic in terminal-emulator.js:

// Inside TerminalEmulator
async executeCommand() {
  const cmd = this.state.inputEl.value.trim();
  this.state.inputEl.value = '';

  if(!cmd) return;

  this.addPromptLine(cmd);
  this.state.history.push(cmd);
  this.state.histIdx = this.state.history.length;

  // Intercept input if an active game/prompt hook is set
  if (this.state.promptHook) {
    await this.state.promptHook(cmd);
    return;
  }

  const parts = cmd.split(/\s+/);
  const command = parts[0].toLowerCase();
  const args = cmd.slice(command.length).trim();

  if(this.COMMANDS[command]) {
    await this.COMMANDS[command].call(this, args);
  } else {
    this.addLine(`  <span class="t-error">Error: ${command}: command not found</span>`);
    this.addLine('');
  }
}

🔒 Hardening Security: Banishing `new Function`

The terminal calculator (calc) originally used new Function() to execute math operations. While convenient, parsing unsanitized input is a dangerous vector for Cross-Site Scripting (XSS).

I replaced it with a safe evaluation parsing engine in math-eval.js using strict whitelist validation:

// Whitelist pattern allowing numbers, basic math operators, parentheses, and letters
if(!/^[\d\s+\-*/%().^a-zA-Z]*$/.test(expr)) {
  throw new Error('Invalid characters');
}

⚡ Performance: 95% CPU Savings

Rendering dozens of floating particles that connect with lines is notoriously heavy. An $O(n^2)$ double-loop checking distances between every particle leads to massive lag at 60 FPS.

I implemented a Spatial Grid Algorithm in particle-system.js:

The canvas is divided into grid cells of 150px.
Each particle is registered in its corresponding cell.
Instead of checking against all particles, a particle only checks the 9 cells surrounding it.

This optimized the complexity from a heavy $O(n^2)$ to an average of $O(n)$ using a Spatial Grid (specifically $O(n \cdot k)$ where $k$ is the average number of particles in neighboring cells).

Additionally, I integrated Mobile Optimizations:

Touch Device Detection: Automatically halves the particle count.
FPS Cap: Capped mobile frames at 30 FPS instead of 60 FPS, reducing CPU usage by over 90% while keeping animations smooth.

🎮 The Fun Part: The Quantum Root Key Betrayal

In Kali Linux, typing rm -rf / --no-preserve-root is the ultimate destructive command. To pay homage to this, I built an interactive easter egg game called game.

The Set Up

When the user types game, they enter the "Quantum Key" mini-game. The terminal generates a secret number between 1 and 100 and gives them 3 attempts to guess it, providing Too high 👆 or Too low 👇 feedback.

The Betrayal

No matter what happens, the game is rigged to betray them:

If they lose: Access is denied, and the system executes rm -rf / --no-preserve-root as a penalty.
If they win: It announces success, loads reward.exe... and then triggers a fake XSS exploit, executing rm -rf / --no-preserve-root anyway!

Here is the implementation inside app.js:

// game command definition in app.js
game: () => {
  T.addLine('');
  T.addLine('  <span class="t-accent2">🎮  MINIGAME: GUESS THE SECRET NUMBER  🎮</span>');
  T.addLine('  <span class="t-info">I have chosen a secret number between 1 and 100.</span>');
  T.addLine('  <span class="t-info">You have 3 attempts to guess it. Good luck!</span>');
  T.addLine('');
  T.addLine('  <span class="t-prompt">Enter your first guess [1-100]:</span>');
  T.addLine('');

  const targetNum = Math.floor(Math.random() * 100) + 1;
  let attempts = 3;

  T.state.promptHook = async (input) => {
    const guess = parseInt(input.trim(), 10);
    if (isNaN(guess) || guess < 1 || guess > 100) {
      T.addLine('  <span class="t-error">✖ Invalid input! Please enter a number between 1 and 100:</span>');
      T.addLine('');
      return;
    }

    if (guess === targetNum) {
      T.state.promptHook = null;
      T.addLine(`  <span class="t-success">🎉 CORRECT! The secret number was indeed ${targetNum}!</span>`);
      T.addLine('  <span class="t-info">Loading your reward.exe...</span>');
      await sleep(1000);
      T.addLine('  <span class="t-error">⚠️  ERROR: Unexpected token in reward.exe!</span>');
      await sleep(500);
      T.addLine('  <span class="t-error">Wait, what is this...? Root payload detected: rm -rf /</span>');
      await sleep(500);
      T.addLine('  <span class="t-accent2">Pranked! Total betrayal! 😂 Execute self-destruction:</span>');
      T.addLine('');
      triggerPurge();
    } else {
      attempts--;
      if (attempts > 0) {
        const hint = guess < targetNum ? 'Too low 👇' : 'Too high 👆';
        T.addLine(`  <span class="t-error">❌ Incorrect! ${guess} is ${hint}.</span>`);
        T.addLine(`  <span class="t-accent2">${attempts} attempt(s) remaining. Enter guess:</span>`);
        T.addLine('');
      } else {
        T.state.promptHook = null;
        T.addLine(`  <span class="t-error">❌ GAME OVER! The secret number was ${targetNum}.</span>`);
        T.addLine('  <span class="t-info">Penalty authorized: rm -rf /hope --no-preserve-root</span>');
        T.addLine('  <span class="t-error">Executing purge... 💀</span>');
        T.addLine('');
        triggerPurge();
      }
    }
  };

  function triggerPurge() {
    const errors = [
      'removing /tools/DotGhostBoard... <span class="t-error">✖ GONE</span>',
      'removing /tools/dotcommand...    <span class="t-error">✖ GONE</span>',
      'removing /tools/CodeTune...      <span class="t-error">✖ GONE</span>',
      'removing /platforms/dev.to...    <span class="t-error">✖ GONE</span>',
      'removing /stats/followers...     <span class="t-error">✖ GONE</span>',
      '', '<span class="t-error">💀 FATAL: filesystem destroyed</span>',
      '<span class="t-error">💀 FATAL: career.exe has stopped working</span>',
      '<span class="t-dim">Segmentation fault (core dumped)</span>',
    ];
    let i = 0;
    const iv = setInterval(() => {
      if (i < errors.length) { T.addLine('  ' + errors[i++]); }
      else {
        clearInterval(iv);
        setTimeout(() => { if (window.triggerDestruction) window.triggerDestruction(); }, 400);
      }
    }, 80);
  }
}

💻 The Ultimate Failsafe: Reverting via `git reverse`

Once the purge executes:

All elements on the screen collapse, slide off, and blur out.
The Blue Screen of Death (BSOD) prints simulated deletion logs and counts to 100%.
The Raw HTML Failsafe: The page transitions into a completely blank white screen showing a raw, unstyled HTML page.
- Standard default black text.
- Times New Roman font.
- <h1>Hello World</h1> header.
- A basic browser <textarea> and <button> with absolutely no CSS.
To fix the system, the user is required to write git reverse in the text area. (Note for the Git purists: yes, in real Git we use git restore or git revert. But in this hacker-themed scenario, typing git reverse felt like the perfect theatrical command to undo the payload).

Entering the command triggers a dark progress bar showing the git status restoration from 0% to 100%, rebuilding all project files and restoring the site layout.

Here is the raw HTML restoration flow implemented in script.js:

function showBlankScreen() {
  const blank = document.createElement('div');
  blank.id = 'blankScreen';
  blank.style.cssText = `
    position: fixed; inset: 0; background: white; color: black;
    z-index: 99999; padding: 50px; overflow: auto; text-align: left;
    font-family: 'Times New Roman', Times, serif;
  `;
  blank.innerHTML = `
    <h1>Hello World</h1>
    <p>Index of /</p>
    <hr>
    <p>The server has encountered a critical failure. All active resources have been unlinked.</p>
    <p>To reverse this action and restore the system to its last commit, please type the recovery command below and press Enter.</p>
    <div style="margin-top: 20px;">
      <textarea id="recoveryTextArea" rows="4" cols="50" placeholder="Type command here..." style="all: revert; font-family: monospace; font-size: 14px; width: 100%; max-width: 500px; padding: 5px;"></textarea>
      <br><br>
      <button id="recoveryBtn" style="all: revert; cursor: pointer; padding: 5px 15px;">Execute Command</button>
      <p id="recoveryError" style="color: red; font-weight: bold; margin-top: 10px; display: none;">Invalid recovery command!</p>
    </div>
  `;
  document.body.appendChild(blank);

  const ta = document.getElementById('recoveryTextArea');
  const btn = document.getElementById('recoveryBtn');
  const err = document.getElementById('recoveryError');

  ta.focus();

  const handleRecovery = () => {
    const val = ta.value.trim().toLowerCase();
    if (val === 'git reverse') {
      blank.remove();
      runSystemRestoredProgress();
    } else {
      err.style.display = 'block';
      ta.value = '';
      ta.focus();
    }
  };

  btn.addEventListener('click', handleRecovery);
  ta.addEventListener('keydown', (e) => {
    if (e.key === 'Enter') {
      e.preventDefault();
      handleRecovery();
    }
  });
}

📈 Summary of Improvements

Metric	Before Refactor (v1.0.0)	After Refactor (v1.1.0)	Benefit
JS File Size	1500+ line Monolith	Modular ES6 Files	Easy maintenance and debugging
Particle Physics	$O(n^2)$ complexity	Average of $O(n)$ Spatial Grid	95% CPU savings
Mobile Refresh Rate	Uncapped 60 FPS (heavy CPU lag)	Capped at 30 FPS + 50% particles	Smooth experience, low battery drain
Security Risk	High XSS risk via `new Function`	Mitigated (strict whitelist parsing)	Zero code execution vulnerability
Interactive Easter Eggs	Static logs	Rigged `game` + `git reverse` prompt	Unforgettable user experience 🎮

Conclusion

Refactoring doesn't have to be boring. By restructuring the codebase of dotUniverse into modular pieces, we didn't just gain a massive performance speedup and security hardening—we opened up the architecture to support complex interactive behaviors. Adding this easter egg turned a static portfolio page into a memorable, interactive game that web developers can love.

What is your favorite terminal easter egg? Let me know in the comments below! 🚀

DEV Community: freerave

DotShare AI 3.5.2: From Git Tags to Technical Articles You Can Review

A deep dive into DotShare 3.5.2: release-aware AI articles, verified code excerpts, Dev.to live preview, and safer credential handling.

What changes in the daily workflow?

1. A release article needs a consistent version of the project

2. Workspace search follows the topic and the release boundary

3. Code examples come from implementation excerpts

4. Validation and repair have a defined stopping point

When an example still cannot be verified

5. Provider completion is part of article quality

6. Dev.to articles arrive as editable Markdown

7. Live Preview includes the whole article header

Links respect the editor's decision

8. Saved keys stay on the extension host

A saved key is scoped to its editor

9. Migration and cleanup cover the credential lifecycle

10. The CLI stores credentials in the OS credential store

11. Logs and cloud sync have narrower, clearer behavior

12. The saved-key controls now follow the editor theme

13. Build and test changes support the release

Install or download DotShare

Try the article workflow on a real release

DotGhostBoard 2.1 'Leviathan' — Cryptographic Vault Backups, Secret Expiry & Password History (Part 2)

A deep-dive into DotGhostBoard 2.1's security layer: AES-256-GCM .vault backup packages with AAD header authentication, CSPRNG password generation with keyspace entropy, secret expiration tracking, and encrypted version history with safe revert.

1. Encrypted Vault Backups: The .vault Package Format

The Cryptographic Stack

Why Associated Authenticated Data (AAD)?

What Gets Exported

2. CSPRNG Password & Token Generator

The Entropy Calculation

3. Secret Expiry Tracking & Dynamic Badges

Setting an Expiry Date

Visual Status Badges

4. Encrypted Password Version History & Safe Revert

How It Works

The History Viewer (📜) & Safe Revert

5. Vault-to-Dashboard Plaintext Sweep

Practical Boundary: Exact Match vs. Substrings

6. Unified Design System & UX Polish

Testing & Code Quality

What's Next & Known Limitations

📦 Try DotGhostBoard 2.1

Keyboard Shortcuts

DotGhostBoard 2.1 'Leviathan' — Smart Clipboard Tagging & Contextual Actions on Linux (Part 1)

How we built a rules-based clipboard intelligence engine for Linux — local, deterministic, sub-millisecond for typical payloads (< 5KB), zero AI, zero telemetry. Auto-tagging, contextual smart actions, and a tight pipeline architecture explained.

The Design Constraint: Local, Deterministic, Fast

1. The Auto-Tagger: How Classification Actually Works

Secret Detection: Two Layers

Known Limitations

2. What the Tag Enables: Contextual Smart Actions

3. Pipeline Architecture

4. Measured Latency

Coming Up in Part 2

📦 Try DotGhostBoard 2.1

Keyboard Shortcuts

Building an Automated, API-Driven Stats & Version Synchronizer for VS Code Extensions with 24-Hour Smart Caching (dotUniverse v1.2.0)

How I built a dual-path synchronization architecture for 7 VS Code extensions using VS Marketplace & Open VSX APIs, 24-hour client caching, and daily zero-dependency GitHub Actions.

🏛️ The Architecture: Dual-Path Synchronization

🏗️ The Challenge: Two Stores, Fragmented Metrics

🔍 Layer 1: Querying Store APIs Directly

1. Batch-Querying Visual Studio Marketplace

2. Querying Open VSX Registry

⚡ Layer 2: The Client-Side Module (extension-stats.js)

Why a 24-Hour Cache is Essential

Clean DOM Mutation via Semantic Attributes

🤖 Layer 3: Automated Daily CI/CD Synchronization

🚀 The Bigger Picture: Building in Public

💡 Key Engineering Takeaways

🔗 Project Links

The VSIX Packaging Trap: How I Eliminated Embedded Client Secrets from a VS Code Extension

A .vsix is just a ZIP archive of plain JavaScript. Here is the post-mortem of how our build-time secrets failed, how we designed dynamic device registration with OS SecretStorage, and how we solved the 'scanner scanning the scanner' paradox.

The Illusion of the Extension Package

Context: Why Did We Need a Secret in the First Place?

Attempt 1: The Build-Time Secret Trap (v2.1.0)

Attempt 2: Zero Embedded Client Secrets & Dynamic Device Handshake (v2.1.2)

1. Anonymous Environment Identity

2. Ephemeral Dynamic Registration

3. OS-Level SecretStorage

4. Authenticated Request Signing

The Automated Gatekeeper: CI/CD Pre-Publish Validation

1. Encrypted Vault Backups: The `.vault` Package Format

⚡ Layer 2: The Client-Side Module (`extension-stats.js`)

1. The Encrypted Vault UI Subsystem (`ui/vault/`)