Forem: freerave

The Hotfix Chronicles: What Broke After the Nexus Release and How I Fixed It (v1.5.2 & v1.5.3)

freerave — Fri, 17 Apr 2026 12:46:26 +0000

I promised I'd fix it. Here's exactly what broke in DotGhostBoard after v1.5.1 — PyInstaller frozen environments, insecure /tmp update paths, missing UI assets, and a polkit regression — and how each one was resolved.

This is a follow-up to Engineering the Nexus Release. At the end of that article I wrote: "Stay tuned for v2.0.0 Cerberus." Before Cerberus ships, there's something I owe you — the full post-mortem on what broke in production immediately after that release.

Check out the v1.5.3 highlight reel to see the new Live Terminal and Network Sync in action:

What Happened After v1.5.1 Shipped

The Nexus architecture held. mDNS discovery worked. E2EE pairing worked. The sync engine worked.

What didn't work: the UI didn't load on any bundled build.

Users who downloaded the .AppImage or .deb were greeted with a white window. No stylesheet. No dark theme. Just a blank Qt frame. The app was running — but blind.

That was the beginning of the v1.5.2 → v1.5.3 hotfix sprint.

Bug 1 — The White Window (PyInstaller Frozen Environment)

Root Cause

When PyInstaller bundles an app, it doesn't just copy files — it extracts them into a temporary directory at runtime called sys._MEIPASS. The problem is that code like this:

# ❌ Breaks in bundled builds
base = os.path.dirname(__file__)
qss_path = os.path.join(base, "ui", "ghost.qss")

...works perfectly when you run python main.py from source, because __file__ points to the project root. But inside a frozen .AppImage, __file__ resolves to a virtual path inside the bundle — and ghost.qss is nowhere near it.

  Source mode:    __file__ → /home/user/DotGhostBoard/core/app.py  ✅
  Frozen mode:    __file__ → /tmp/_MEI3xk9/core/app.py             ✅
                  ghost.qss → ???                                   ❌

The UI stylesheet ghost.qss simply couldn't be found. Qt silently fell back to its default theme. White window.

The Fix: `resource_path` Bridge

# core/paths.py
import os
import sys


def _base_dir() -> str:
    """
    Detect whether we're running from source or a PyInstaller bundle.
    In frozen mode, all assets are extracted to sys._MEIPASS at runtime.
    """
    if getattr(sys, "frozen", False) and hasattr(sys, "_MEIPASS"):
        return sys._MEIPASS          # PyInstaller extraction folder
    return os.path.dirname(           # two levels up from core/paths.py
        os.path.dirname(os.path.abspath(__file__))
    )


def resource_path(*parts: str) -> str:
    """
    Build an absolute path to any bundled asset, regardless of runtime mode.

    Usage:
        resource_path("ui", "ghost.qss")   →  /tmp/_MEIxxxx/ui/ghost.qss
        resource_path("data", "icon.png")  →  /home/user/Project/data/icon.png
    """
    return os.path.join(_base_dir(), *parts)

Decision flow:

  App requests: resource_path("ui", "ghost.qss")
                          │
                    is_frozen?
                   /         \
                 Yes           No
                  │             │
          sys._MEIPASS    Project Root
                  │             │
    /tmp/_MEIxxxx/ui/ghost.qss  /home/user/.../ui/ghost.qss

Every asset reference in the codebase was updated to go through resource_path(). The white window was gone.

The CI Side of This Bug

But wait — local builds worked. CI builds didn't. Why?

Because the PyInstaller command in the workflow was missing the --add-data directive for the UI directory:

# ❌ v1.5.1 — ghost.qss never made it into the bundle
- name: Build
  run: |
    pyinstaller --noconsole --onedir \
      --add-data "data:data" \
      --hidden-import "PyQt6.sip" \
      --name dotghostboard main.py

# ✅ v1.5.3 — explicitly map the UI directory
- name: Build
  run: |
    pyinstaller --noconsole --onedir \
      --add-data "data:data" \
      --add-data "ui/ghost.qss:ui" \    # ← this line was the missing piece
      --hidden-import "PyQt6.sip" \
      --hidden-import "cryptography" \
      --hidden-import "cryptography.hazmat.primitives.asymmetric.x25519" \
      --hidden-import "cryptography.hazmat.primitives.ciphers.aead" \
      --name dotghostboard main.py

The --add-data syntax is "source:dest" — it maps the source path on the build machine to the relative path inside _MEIPASS. Without it, PyInstaller doesn't know the file exists and silently skips it.

The deceptive part: local pyinstaller builds work because pyinstaller finds ui/ghost.qss relative to the working directory. The GitHub Actions runner has a clean checkout with the same structure — but without explicit --add-data, the file is excluded from the bundle spec. Same command, different behavior depending on how PyInstaller resolves paths in its analysis phase.

You can verify any .deb build has the file:

dpkg -c dotghostboard_1.5.3_amd64.deb | grep ui/
# Expected: ... _internal/ui/ghost.qss

Bug 2 — Insecure Update Download Path

In v1.5.1, the in-app "Download Update" feature used /tmp/ as the staging area:

# ❌ v1.5.1
download_path = f"/tmp/dotghostboard_{version}_amd64.deb"

/tmp/ is world-readable, world-writable, and wiped on reboot. For a one-time download that's fine. For a security tool that downloads and installs packages — it's a TOCTOU (Time-Of-Check to Time-Of-Use) attack surface. An attacker with local access could replace the .deb between download and installation.

The Fix: User-Specific Sandbox

# ✅ v1.5.2+
import os

def get_update_staging_dir() -> str:
    """
    Returns a user-specific, restricted directory for staging update packages.
    Created with mode 0o700 — only the owning user can read or write.
    """
    path = os.path.join(
        os.path.expanduser("~"),
        ".local", "share", "dotghostboard", "updates"
    )
    os.makedirs(path, mode=0o700, exist_ok=True)
    return path

SAFE_PATH = os.path.join(get_update_staging_dir(), f"dotghostboard_{version}_amd64.deb")

	v1.5.1	v1.5.2+
Download path	`/tmp/`	`~/.local/share/dotghostboard/updates/`
Readable by other users	Yes	No (`0o700`)
Survives reboot	No	Yes
Integrity check	None	SHA-256 (v1.5.3)

The Kamikaze Installer

The install script itself also needed hardening. After dpkg -i finishes, no artifacts should remain:

#!/bin/sh
# dotghostboard_install.sh — self-destructs after use

SAFE_PATH="$1"

dpkg -i "$SAFE_PATH"   # Install the package
rm -f "$SAFE_PATH"     # Wipe the .deb from disk
rm -f "$0"             # Wipe this script itself

Nothing lingers. No old .deb sitting in a directory. No script to be re-executed.

Bug 3 — Polkit SUID Regression on Kali

Kali Linux (and some hardened Arch setups) occasionally strip or reset the SUID bit on /usr/bin/pkexec after system updates. This caused the in-app "Download & Install" button to fail silently — pkexec would return a permission error, and the UI would just hang.

The fix was embedded directly in the package's postinst script — it runs as root immediately after dpkg -i completes:

#!/bin/sh
# DEBIAN/postinst

set -e

fix_pkexec() {
    PKEXEC="/usr/bin/pkexec"
    if [ -f "$PKEXEC" ]; then
        CURRENT_PERMS=$(stat -c "%a" "$PKEXEC")
        if [ "$CURRENT_PERMS" != "4755" ]; then
            echo "dotghostboard: repairing pkexec SUID bit ($CURRENT_PERMS → 4755)"
            chmod 4755 "$PKEXEC"
        fi
    fi
}

case "$1" in
    configure)
        fix_pkexec
        ;;
esac

exit 0

Logic flow:

  dpkg -i dotghostboard_1.5.3_amd64.deb
         │
         └── postinst runs as root
                  │
            /usr/bin/pkexec exists?
                  │
            current perms == 4755?
            /              \
          Yes               No
           │                 │
         Skip           chmod 4755
                             │
                    "Download & Install" works

This is controversial — touching SUID bits in a postinst script is aggressive. But the alternative is users filing issues that are impossible to debug remotely, or writing a setup guide that says "run chmod 4755 /usr/bin/pkexec after installing." The autorepair is the lesser evil.

Feature: Live Terminal Log (v1.5.3)

While fixing the above bugs, I replaced the old "Please Wait..." dialog during updates with a live terminal stream. It felt wrong to show a spinner while dpkg was doing real work with real output.

Architecture

# ui/update_log_screen.py
from PyQt6.QtCore import QThread, pyqtSignal
import subprocess


class InstallWorker(QThread):
    log_line = pyqtSignal(str)   # emitted for every line of dpkg output
    finished = pyqtSignal(int)   # exit code

    def __init__(self, script_path: str):
        super().__init__()
        self.script_path = script_path

    def run(self):
        process = subprocess.Popen(
            ["bash", self.script_path],
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,   # merge stderr into stdout
            text=True,
            bufsize=1                   # line-buffered
        )
        for line in process.stdout:
            self.log_line.emit(line.rstrip())

        process.wait()
        self.finished.emit(process.returncode)

On the UI side:

# Color mapping — Regex-based, no AI required
import re
from PyQt6.QtGui import QColor

COLOR_MAP = [
    (re.compile(r'\berror\b',   re.I), "#FF5555"),   # red
    (re.compile(r'\bwarning\b', re.I), "#FFB86C"),   # amber
    (re.compile(r'\bSetting up\b|\bProcessing\b'), "#50FA7B"),  # green
    (re.compile(r'^--'),                             "#8BE9FD"),  # cyan for steps
]

def colorize(line: str) -> str:
    for pattern, color in COLOR_MAP:
        if pattern.search(line):
            return f'<span style="color:{color}">{line}</span>'
    return line  # default — white

def on_log_line(self, line: str):
    self.log_box.append(colorize(line))
    # Auto-scroll to bottom
    sb = self.log_box.verticalScrollBar()
    sb.setValue(sb.maximum())

The blinking cursor is driven by a QTimer — no threads, no complexity:

self._cursor_visible = True
self._cursor_timer = QTimer()
self._cursor_timer.timeout.connect(self._blink_cursor)
self._cursor_timer.start(500)  # 500ms interval

def _blink_cursor(self):
    self._cursor_visible = not self._cursor_visible
    self.cursor_label.setText("█" if self._cursor_visible else " ")

Verification Checklist

For any future hotfix, these three commands confirm the build is clean:

# 1. Confirm ghost.qss is inside the bundle
dpkg -c dotghostboard_1.5.3_amd64.deb | grep ui/
# Expected: ./opt/dotghostboard/_internal/ui/ghost.qss

# 2. Verify SUID bit post-install
ls -l /usr/bin/pkexec
# Expected: -rwsr-xr-x (the 's' in position 4 is the SUID bit)

# 3. Test resource_path in frozen mode (AppImage)
./DotGhostBoard-1.5.3-x86_64.AppImage --debug-paths
# Should print resolved paths for ghost.qss and icon_256.png

What I Learned

PyInstaller's --add-data is not optional for anything outside data/. If your app loads a file at runtime that isn't in the directory you passed to --add-data, it won't be in the bundle. PyInstaller doesn't warn you. The app just crashes or falls back silently. Map every resource directory explicitly.

sys._MEIPASS is the only reliable truth in a frozen environment. Don't use __file__, don't use os.getcwd(), don't use relative paths. _MEIPASS is where PyInstaller extracted everything — it's the only path you can trust.

/tmp/ is fine for scratch. It's not fine for security-sensitive staging. The threat model for a clipboard manager that stores secrets is different from a text editor. The update pipeline needed to match that model.

Local builds working ≠ CI builds working. The ghost.qss bug existed for the entire v1.5.x series in bundled form because nobody had tested a clean AppImage build from the CI artifact — only local PyInstaller runs. Add artifact smoke testing to your release checklist.

What's Next — v2.0.0 Cerberus

The hotfix series is closed. v1.5.3 is stable.

Next up is Cerberus — the Zero-Knowledge Password Vault. The AES-256 foundation from v1.4.0 (Eclipse) is already in place. The design is locked:

Isolated vault.db — separate file, separate connection, locked when idle
Pattern-based secret detection — JWT, AWS keys (AKIA...), GitHub tokens (ghp_...), high-entropy hex — shape-based, not keyword-based
Auto-clear: wipes clipboard 30 seconds after a Vault paste
Paranoia Mode: suspends all DB writes on demand

The core principle of Cerberus: a 1500-word article that contains the word "password" doesn't trigger detection. A 40-character base64 string with high Shannon entropy does.

Download

	Link
📦 GitHub Release (AppImage + DEB + GPG sigs)	v1.5.3
🖥️ OpenDesktop	DotGhostBoard
💻 Source	kareem2099/DotGhostBoard

DotSuite — built for the shadows 👻

We Hit 2,500 in 15 Days — And I Want to Make Every Dev Lazier (Productively)

freerave — Thu, 16 Apr 2026 18:15:34 +0000

I set a goal at the start of April: reach 2,500 followers on dev.to by April 30th.

We hit 2,631 by April 15th.

Half the month. So before I sprint to the next goal, I want to stop, look back, and say a real thank you — not the generic "thanks for the support 🙏" kind. The honest kind.

What you actually did

You read the articles. You left comments that pushed me to think harder. You shared the DotShare posts and the Reddit API deep-dives with people who needed them. Some of you went through the dotUniverse terminal, found the Easter eggs, and DMed me screenshots. That made my week every single time.

You didn't just follow — you engaged. That's the difference.

The honest confession: I'm lazy. That's why I built 20+ tools.

Here's the real origin story of the entire DotSuite ecosystem.

I didn't build these tools because I'm a passionate open-source hero. I built them because I kept running into tasks I did not want to do manually ever again.

DotShare — because I wasn't opening 8 browser tabs every time I wanted to post something
dotenvy — because I forgot my .env variables once and lost two hours of debugging
DotGhostBoard — because my clipboard was an absolute disaster
dotcommand — because I kept forgetting terminal commands that I wrote myself
DotScramble — because blurring faces manually in screenshots is soul-crushing
CodeTune — because I needed prayer times and Quran without leaving VS Code
dotsense — because I genuinely couldn't tell when I was burning out until it was too late

The pattern is obvious. Every tool exists because past-me was too lazy to keep doing something the hard way.

Laziness, scaled properly, is just engineering.

The full arsenal — everything built so far

Here's every tool in the DotSuite ecosystem, in case you missed any:

VS Code Extensions

Tool	What it does	Downloads
DotShare	Post to 9 platforms (LinkedIn, X, Reddit, Bluesky, Telegram, Facebook, Discord, dev.to, medium) with AI content creation via Gemini, GPT-4 & Claude	1,979+
dotenvy	Environment manager with Git branch auto-switching, AI secret detection (35-feature ML model), Doppler sync & encrypted backups	1,130+
dotcommand	Intelligent command manager, ML suggestions, 180+ prepared commands, analytics dashboard	909+
CodeTune	Islamic dev environment — Quran player (15+ reciters), prayer times, focus mode, Dhikr counters	899+
DotFetch	Professional HTTP client with .env support, collections, cURL import/export	692+
DotReadme	README optimizer — quality audit (A+ to F), badge inserter, TOC generator, AI enhancement (BYOK)	515+
dotsense	AI developer wellness — ML mood detection, burnout prevention, peak performance analytics	129+
dotconvert	Data converter — Base64, XML↔JSON, CSV↔JSON (Marketplace listing coming soon)	—

Total VS Code downloads across Marketplace + Open VSX: 6,253+

CLI Tools

Tool	What it does
DotGhostBoard	Linux clipboard manager — AES-256 encryption, tag system, thumbnail previews, master password lock
DotScramble	Image privacy studio — face/license plate detection, 8 blur effects, batch processing, RTL Arabic support

Telegram Bots

Tool	What it does
DotDownloader	Multi-platform media downloader — Instagram, TikTok, YouTube, Reddit, Spotify & more. Referral system + premium tiers
DotFormate	File format conversion — PDF, DOCX, PPTX, images, OCR. PayPal integration + R2 cloud storage
DotShare-Auth-Server	Secure OAuth toolkit — magic link auth, LinkedIn & Reddit & X & Facebook OAuth, session management

Mobile Apps

Tool	What it does
DotReminder	Android reminder app — AI assistant (Gemini 2.5 Flash), location-based reminders, biometric auth, 2FA
DOTShredzilla	Workout tracker — offline-first, Firebase-synced, Kotlin + Jetpack Compose
DotBurn	Gym and calorie system management

Premium / Private

Tool	What it does
dotctl (invite only)	Advanced traffic control for network security experts — ARP spoofing, bandwidth limiting, DPI & ML traffic analysis

Coming Soon

Tool	What it does
DotTransfer	Transfer files between workspaces directly inside VS Code
dotsuite	Portfolio & distribution platform — Next.js 16, multi-language (EN/AR/FR/DE/RU), GitHub webhooks, product reviews

Where the April challenge stands right now

dev.to was the first goal to fall. Here's the full scoreboard:

Platform	Now	Goal	Progress
📝 dev.to	2,631	2,500	✅ DONE
💼 LinkedIn	396	500	79%
🎵 TikTok	33	100	33%
▶️ YouTube	29	100	29%
✍️ Medium	2	50	4%
📘 Facebook	13	50	26%
📸 Instagram	7	50	14%
𝕏 X / Twitter	16	500	3%
🦋 Bluesky	11	50	22%

Some of these are painful to look at. X at 3% is basically a comedy sketch. But the scoreboard stays public. That's the whole point.

What's shipping next

DotShare v3.2 — Reddit media uploads are almost stable. The S3 presigned pipeline is wired. The last debug session was brutal and I wrote every painful detail here.
dotenvy — The LLM layer for environment/config management deserves a proper release article. The architecture is the interesting part.
dotUniverse Terminal 2.0 — Piping support, SSH simulation, VIM-lite. Q2 target.
dotsuite — The full portfolio platform goes live this year.

The part that actually matters

I'm self-taught. I'm building all of this from a small city in Egypt, mostly at night, mostly alone. No team, no VC funding, no algorithm boost.

Every follow, reaction, and comment is a real person who decided this was worth their time.

2,631 of you did that. I don't take it lightly.

The next target is 3,000. Based on the current trajectory, I give it two weeks. Let's find out.

Try the tools

Live portfolio: https://kareem2099.github.io/dotuniverse/
GitHub: https://github.com/kareem2099
All tools: open the terminal on dotUniverse and type ls ~/tools

My message to every developer reading this: be productively lazy. Automate the annoying thing. Build the tool. Then build the tool that builds the tool. That's how 20+ projects happen.

Built with caffeine and the stubborn belief that open-source from Egypt can reach the whole internet.

— Kareem / FreeRave 🦥

Engineering the Nexus Release: How I Built Secure E2EE Network Sync into a Linux Clipboard Manager (v1.5.1)

freerave — Wed, 15 Apr 2026 20:28:57 +0000

A deep dive into the architecture behind DotGhostBoard v1.5.0 — zero-config mDNS discovery, X25519 ECDH pairing, AES-256-GCM sync, rate limiting, and PyQt6 threading — all without a central server.

DotGhostBoard is a privacy-first clipboard manager for Linux, built under the DotSuite umbrella. No telemetry. No Electron. No cloud. Pure PyQt6 + SQLite.

📦 GitHub Release v1.5.1 · 🖥️ OpenDesktop

Why This Was Hard

Building a clipboard manager is trivial. Building one that syncs securely across devices on a local network without a central server, without trusting the network, and without ever sending data to the cloud — that's a different problem.

With v1.5.0 (Nexus), I rebuilt the core architecture from scratch to solve exactly that. Here's what the final system looks like before we dive into each layer:

  ┌─────────────────────────────────────────────────────────────┐
  │                     LOCAL NETWORK (LAN)                     │
  │                                                             │
  │   ┌──────────────┐   mDNS Discovery    ┌──────────────┐    │
  │   │  Device A    │ ◄──────────────────► │  Device B    │    │
  │   │  (Arch)      │                      │  (Kali)      │    │
  │   │              │   X25519 Handshake   │              │    │
  │   │  ghostboard  │ ──── PIN + ECDH ───► │  ghostboard  │    │
  │   │              │                      │              │    │
  │   │  HTTPServer  │ ◄── AES-256-GCM ──── │  HTTPServer  │    │
  │   │  :PORT       │   /api/sync E2EE     │  :PORT       │    │
  │   └──────┬───────┘                      └──────┬───────┘    │
  │          │                                     │            │
  │       ghost.db                              ghost.db        │
  │    (trusted_peers)                       (trusted_peers)    │
  └─────────────────────────────────────────────────────────────┘

Three layers. Each one independently secure. Let's break them down.

Layer 1 — Zero-Config Device Discovery (mDNS)

The first UX problem: how do devices find each other without the user typing an IP address?

Answer: mDNS via zeroconf. Every device broadcasts itself on the LAN under a custom service type _dotghost._tcp.local.. Other instances listen and populate the UI automatically.

Because the app runs on PyQt6, the discovery engine lives in its own QThread — blocking network I/O never touches the main thread:

# core/network_discovery.py
import socket
from zeroconf import ServiceBrowser, Zeroconf, ServiceInfo, IPVersion
from PyQt6.QtCore import pyqtSignal, QThread

_SERVICE_TYPE = "_dotghost._tcp.local."


class DotGhostDiscovery(QThread):
    peer_found = pyqtSignal(str, str, str, int)  # node_id, name, ip, port
    peer_lost  = pyqtSignal(str)                 # node_id

    def __init__(self, node_id: str, device_name: str, port: int):
        super().__init__()
        self.node_id     = node_id
        self.device_name = device_name
        self.port        = port
        self.zeroconf    = None

    def run(self):
        self.zeroconf = Zeroconf(ip_version=IPVersion.V4Only)

        properties = {
            b'node_id':     self.node_id.encode('utf-8'),
            b'device_name': self.device_name.encode('utf-8'),
            b'version':     b'1',
        }

        instance_name = f"{self.node_id}.{_SERVICE_TYPE}"

        self.info = ServiceInfo(
            type_=_SERVICE_TYPE,
            name=instance_name,
            addresses=[socket.inet_aton(get_local_ip())],
            port=self.port,
            properties=properties,
            server=f"{self.node_id}.local."
        )

        self.zeroconf.register_service(self.info)
        self.browser = ServiceBrowser(self.zeroconf, _SERVICE_TYPE, self)
        self.exec()  # Qt event loop keeps the thread alive

    # ── zeroconf callbacks ──────────────────────────────────────

    def add_service(self, zc: Zeroconf, type_: str, name: str):
        info = zc.get_service_info(type_, name)
        if not info:
            return

        props    = info.properties
        node_id  = props.get(b'node_id', b'').decode()
        dev_name = props.get(b'device_name', b'Unknown').decode()

        if node_id == self.node_id:  # skip self
            return

        ip = socket.inet_ntoa(info.addresses[0])
        self.peer_found.emit(node_id, dev_name, ip, info.port)

    def remove_service(self, zc: Zeroconf, type_: str, name: str):
        node_id = name.replace(f".{_SERVICE_TYPE}", "")
        self.peer_lost.emit(node_id)

    def stop(self):
        if self.zeroconf:
            self.zeroconf.unregister_service(self.info)
            self.zeroconf.close()
        self.quit()

Why QThread and not threading.Thread?
peer_found and peer_lost are pyqtSignals. They cross the thread boundary safely into the main UI thread via Qt's queued connection mechanism. Using a raw Python thread here would cause a race condition against the UI.

Layer 2 — Secure Device Pairing (X25519 + PBKDF2 + AES-GCM)

Finding a peer is one thing. Trusting it is another.

A local network isn't inherently safe — public Wi-Fi, ARP spoofing, a compromised router. The pairing protocol defends against all of it with a three-phase handshake:

  Device A                              Device B
     │                                     │
     │  1. Generate ephemeral X25519 key   │
     │  2. Derive wrap key from PIN+salt   │
     │  3. Encrypt pubkey → send ─────────►│
     │                                     │  4. Decrypt pubkey with PIN+salt
     │                                     │  5. Generate ephemeral X25519 key
     │◄──────────────── send encrypted ────│  6. Derive shared secret (ECDH)
     │                                     │  7. Encrypt own pubkey → send
     │  8. Derive shared secret (ECDH)     │
     │  9. Discard ephemeral keys          │  9. Discard ephemeral keys
     │                                     │
     │      Shared Secret stored in DB     │

The PIN is a 6-digit out-of-band value shown on both screens — a human-verified channel that breaks any MITM attempt. Even if an attacker intercepts the traffic, they can't decrypt the public keys without the PIN.

# core/pairing.py
import os
import base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import x25519
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

_KDF_ITERATIONS = 100_000  # OWASP minimum for PBKDF2-SHA256


def derive_handshake_key(pin: str, salt: bytes) -> bytes:
    """
    Derive a 256-bit wrapping key from a 6-digit PIN + dynamic salt.
    The salt is generated fresh per-pairing session and sent in plaintext —
    its job is to prevent precomputed PIN dictionaries, not to be secret.
    """
    kdf = PBKDF2HMAC(
        algorithm=hashes.SHA256(),
        length=32,
        salt=salt,
        iterations=_KDF_ITERATIONS,
    )
    return kdf.derive(pin.encode("utf-8"))


def generate_pairing_keys() -> tuple[x25519.X25519PrivateKey, bytes]:
    """
    Generate a fresh ephemeral X25519 key pair.
    These keys live only for the duration of the handshake.
    """
    private_key = x25519.X25519PrivateKey.generate()
    public_key_bytes = private_key.public_key().public_bytes(
        encoding=serialization.Encoding.Raw,
        format=serialization.PublicFormat.Raw
    )
    return private_key, public_key_bytes


def encrypt_pairing_payload(public_key_bytes: bytes, handshake_key: bytes) -> str:
    """
    Encrypt the public key using the PIN-derived wrapping key.
    Layout: [ 12 bytes nonce | ciphertext + 16 byte GCM tag ]
    """
    aesgcm = AESGCM(handshake_key)
    nonce = os.urandom(12)
    ciphertext = aesgcm.encrypt(nonce, public_key_bytes, None)
    return base64.b64encode(nonce + ciphertext).decode("utf-8")


def decrypt_pairing_payload(payload: str, handshake_key: bytes) -> bytes:
    """Reverse of encrypt_pairing_payload. Raises InvalidTag on wrong PIN."""
    raw = base64.b64decode(payload)
    nonce, ciphertext = raw[:12], raw[12:]
    aesgcm = AESGCM(handshake_key)
    return aesgcm.decrypt(nonce, ciphertext, None)


def derive_shared_secret(
    private_key: x25519.X25519PrivateKey,
    peer_public_key_bytes: bytes
) -> bytes:
    """
    Complete the ECDH exchange. The result is a raw 32-byte shared secret.
    Both sides arrive at the same value without it ever being transmitted.
    """
    peer_public_key = x25519.X25519PublicKey.from_public_bytes(peer_public_key_bytes)
    return private_key.exchange(peer_public_key)

Why X25519 over RSA or classic ECDH on P-256?
X25519 is faster, has a smaller key size (32 bytes), is immune to invalid-curve attacks by design, and is the default in TLS 1.3. It's the right choice for a constrained local protocol.

Once the handshake completes, the shared secret is stored in ghost.db and the ephemeral private keys are immediately garbage-collected.

# Storage schema for trusted peers
"""
CREATE TABLE trusted_peers (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    node_id       TEXT UNIQUE NOT NULL,
    device_name   TEXT NOT NULL,
    shared_secret BLOB NOT NULL,      -- raw 32 bytes from ECDH
    paired_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
"""

Layer 3 — The Local REST API, Rate Limiting & Thread-Safe UI

With discovery and pairing solved, the actual sync transport is a minimal HTTPServer running in a background thread. It's bound to 0.0.0.0 but protected by two hard gates:

Gate 1 — Peer Identity: every /api/sync request must carry a node_id that maps to a stored trusted peer. Unknown nodes get a 403 immediately.

Gate 2 — E2EE Payload: even if someone spoofs a node_id, they can't forge a valid AES-GCM ciphertext without the shared secret. Wrong key = InvalidTag exception = instant drop.

# core/api_server.py
import json
import time
import urllib.parse
from collections import defaultdict
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Lock


class _RateLimiter:
    """Sliding window rate limiter — 3 pairing attempts per 60s per IP."""

    def __init__(self, max_attempts: int = 3, window: int = 60):
        self._attempts = defaultdict(list)
        self._lock     = Lock()
        self.max       = max_attempts
        self.window    = window

    def is_allowed(self, ip: str) -> bool:
        now = time.time()
        with self._lock:
            # drop timestamps outside the window
            self._attempts[ip] = [
                t for t in self._attempts[ip] if now - t < self.window
            ]
            if len(self._attempts[ip]) >= self.max:
                return False
            self._attempts[ip].append(now)
            return True


_rate_limiter = _RateLimiter()


class GhostAPIHandler(BaseHTTPRequestHandler):

    def log_message(self, format, *args):
        pass  # silence default HTTP logs

    def _send_response(self, code: int, body: dict):
        payload = json.dumps(body).encode()
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(payload)))
        self.end_headers()
        self.wfile.write(payload)

    def do_POST(self):
        parsed    = urllib.parse.urlparse(self.path)
        client_ip = self.client_address[0]

        # ── /api/pair — pairing PIN exchange ──────────────────────
        if parsed.path == '/api/pair':
            if not _rate_limiter.is_allowed(client_ip):
                self._send_response(429, {
                    "status":  "error",
                    "message": "Too many pairing attempts. Try again later."
                })
                return
            # ... PIN verification and key exchange logic
            self._send_response(200, {"status": "paired"})
            return

        # ── /api/sync — incoming E2EE clipboard item ───────────────
        if parsed.path == '/api/sync':
            body = self.rfile.read(int(self.headers.get('Content-Length', 0)))
            data = json.loads(body)

            peer_node_id = data.get("node_id")
            peer = storage.get_trusted_peer(peer_node_id)

            if not peer:
                self._send_response(403, {
                    "status":  "error",
                    "message": "Untrusted peer"
                })
                return

            try:
                plaintext = decrypt_from_peer(
                    data.get("payload"),
                    peer["shared_secret"]
                )
            except Exception:
                # Wrong key or tampered payload — silent drop
                self._send_response(403, {
                    "status":  "error",
                    "message": "Decryption failed"
                })
                return

            item_id = storage.add_item("text", plaintext)

            # Cross-thread UI update via Qt signal — safe from any thread
            self.server.qthread_parent.sync_received.emit(item_id, plaintext)
            self._send_response(201, {"status": "synced"})

Why HTTPServer over WebSockets or raw TCP?
HTTP gives request/response semantics for free, works through most firewalls, and is trivially testable with curl. The overhead is negligible for clipboard payloads. When v3.x arrives, the transport will be upgraded to WebRTC for true NAT-piercing P2P.

The Full Sync Flow — End to End

Here's what happens when you copy something on Device A and it appears on Device B:

  Device A (sender)                         Device B (receiver)
  ─────────────────                         ────────────────────
  1. User copies text
  2. ClipboardMonitor detects change
  3. Encrypt with shared_secret
     [ AES-256-GCM | random 12-byte nonce ]
  4. POST /api/sync ──────────────────────► 5. GhostAPIHandler.do_POST()
     {                                         6. Lookup peer by node_id
       "node_id": "abc123",                    7. Decrypt with shared_secret
       "payload": "<base64 ciphertext>"        8. storage.add_item()
     }                                         9. sync_received.emit()
                                              10. UI updates in main thread
  ◄──────────────── 201 { "status": "synced" }

Zero plaintext on the wire. Zero server in the middle. Zero cloud.

Securing the Build: GPG-Signed Releases

A secure app with an unsigned binary is still a supply chain risk. Every release artifact — both the .AppImage and the .deb — is GPG-signed in CI and verified before upload.

# .github/workflows/build-all.yml (signing steps)

- name: Sign AppImage (GPG)
  run: |
    echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --import --batch --yes
    gpg --batch --yes --pinentry-mode loopback \
      --passphrase "${{ secrets.GPG_PASSPHRASE }}" \
      --detach-sign --armor \
      DotGhostBoard-*.AppImage

- name: Verify AppImage signature
  run: |
    gpg --verify DotGhostBoard-*.AppImage.asc DotGhostBoard-*.AppImage
    echo "✅ AppImage signature verified"

- name: Sign DEB Package (GPG)
  run: |
    echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --import --batch --yes
    dpkg-sig --sign builder \
      -k "${{ secrets.GPG_KEY_ID }}" \
      --gpg-options "--passphrase ${{ secrets.GPG_PASSPHRASE }} --pinentry-mode loopback --batch --yes" \
      dotghostboard_*.deb

- name: Generate SHA256 checksums
  run: |
    cd out && sha256sum * > SHA256SUMS.txt

Users can verify any release with:

# Verify AppImage
gpg --verify DotGhostBoard-1.5.1-x86_64.AppImage.asc \
             DotGhostBoard-1.5.1-x86_64.AppImage

# Verify DEB
dpkg-sig --verify dotghostboard_1.5.1_amd64.deb

# Verify checksum
sha256sum -c SHA256SUMS.txt

Lessons Learned

mDNS is fragile on some Linux setups. If avahi-daemon is running and competing for port 5353, zeroconf will fail silently. Detect the conflict early and surface it in the UI — don't leave the user with an empty peers list and no explanation.

PyInstaller and cryptography need explicit hidden imports. The cryptography package uses dynamic loading for its backend. Without --hidden-import cryptography.hazmat.primitives.asymmetric.x25519 and the aead module, the AppImage crashes at runtime with a clean ImportError that's impossible to debug without knowing where to look.

dpkg-sig hangs in CI without --pinentry-mode loopback. It silently waits for a terminal that doesn't exist. Always pass the full GPG options explicitly in non-interactive environments.

Rate limiting shared state needs a lock. The sliding window dict is accessed from multiple HTTP handler threads simultaneously. Without a threading.Lock, you get a race condition under concurrent pairing attempts that's near-impossible to reproduce locally.

What's Next — v2.0.0 Cerberus

The next release is Cerberus — a Zero-Knowledge Password Vault. The AES-256 infrastructure from v1.4.0 (Eclipse) already lays the foundation. What's coming on top:

A fully isolated vault.db (separate file, separate connection, locked when not in use)
Pattern-based secret detection using Regex — JWT, AWS keys, GitHub tokens, high-entropy hex strings — not keyword matching
Auto-clear: wipes the clipboard 30 seconds after a Vault paste
Paranoia Mode: a toggle that suspends all DB writes temporarily

The core design decision in Cerberus: detection happens at the shape of a string, not its meaning. A 1500-word article that mentions "password" doesn't trigger anything. A 40-character base64 string with high Shannon entropy does.

Download & Source

	Link
📦 GitHub Release (AppImage + DEB + GPG sigs)	v1.5.1
🖥️ OpenDesktop	DotGhostBoard
💻 Source Code	kareem2099/DotGhostBoard

If you find a security issue, please reach out directly before opening a public issue.

⚠️ A Note on the current DEB Release (v1.5.1)
Being transparent with the community is a core value of DotSuite.

Known Issue: In the current .deb release, some users might notice the UI defaulting to Light Mode on specific GTK-based distros (like Kali). Additionally, the update helper might trigger a Polkit permission error due to setuid restrictions in the /tmp/ directory.

The Fix: I am already working on v1.5.2, which migrates the update path to ~/.local/state/ and forces the Fusion style engine to ensure a consistent Dark Mode experience. The fix will be live tomorrow.

Stay tuned, and thanks for the support!

DotSuite — built for the shadows 👻

DotShare v3.1 — Toast Engine, Race Condition Fix, and Surviving Reddit's S3 Upload Pipeline

freerave — Mon, 13 Apr 2026 10:19:46 +0000

Full technical breakdown of v3.1 'The Polish Pass' — a custom WebView toast system, global loading states, per-platform character limits, and the two bugs that took the longest to kill.

v3.0 added the platforms. v3.1 made them feel like they belonged.

"The Polish Pass" is the kind of release that's invisible when it works and infuriating when it doesn't. No new platforms. No headline features. Just: notifications that don't hijack your screen, buttons that tell you something is happening, character counters that actually enforce limits — and two bugs that were quietly breaking things since the beginning.

This is the full technical breakdown.

What's in v3.1

Custom WebView toast notification engine (replaces VS Code popups)
Global loading states on all async actions
Per-platform character limit validation with visual feedback
Glassmorphism UI pass
The Disappearing Preview race condition — fixed
Reddit's S3 native image upload pipeline — fixed
Reddit field name synchronization between frontend and backend
Unused variable cleanup for ESLint compliance

1. The Toast Notification Engine

Before v3.1, every status update used vscode.window.showInformationMessage() — a popup in the VS Code notification center that requires manual dismissal and breaks your flow. For an extension designed to keep you in the editor, it was wrong.

The replacement is a custom toast system that lives entirely inside the WebView.

HTML Container

<!-- media/webview/platform-post.html -->
<div id="toast-container" aria-live="polite" aria-atomic="false"></div>

One container, fixed to the bottom-right of the WebView. Toasts mount and remove themselves.

The Toast Function

// media/webview/app.ts

type ToastType = 'success' | 'error' | 'warning' | 'info';

const TOAST_ICONS: Record<ToastType, string> = {
  success: '✓',
  error:   '✕',
  warning: '⚠',
  info:    'ℹ',
};

function escHtml(str: string): string {
  return str
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;');
}

function toast(
  msg: string,
  type: ToastType = 'info',
  ms: number = 5000
): void {
  const container = document.getElementById('toast-container');
  if (!container) return;

  const el = document.createElement('div');
  el.className = `toast toast-${type}`;
  el.setAttribute('role', 'alert');
  el.style.setProperty('--toast-duration', `${ms}ms`);

  el.innerHTML = `
    <span class="toast-icon">${TOAST_ICONS[type]}</span>
    <span class="toast-message">${escHtml(msg)}</span>
    <div class="toast-progress"></div>
  `;

  container.appendChild(el);

  // Trigger enter animation on next paint
  requestAnimationFrame(() => el.classList.add('toast-visible'));

  if (ms > 0) {
    setTimeout(() => {
      el.classList.remove('toast-visible');
      el.classList.add('toast-exit');
      el.addEventListener('transitionend', () => el.remove(), { once: true });
    }, ms);
  }
}

CSS

/* media/webview/style.css */

#toast-container {
  position: fixed;
  bottom: 1.5rem;
  right: 1.5rem;
  display: flex;
  flex-direction: column;
  gap: 8px;
  z-index: 9999;
  pointer-events: none;
}

.toast {
  display: flex;
  align-items: center;
  gap: 10px;
  padding: 12px 16px;
  border-radius: 8px;
  font-size: 13px;
  min-width: 260px;
  max-width: 380px;
  position: relative;
  overflow: hidden;
  pointer-events: all;
  opacity: 0;
  transform: translateX(20px);
  transition: opacity 0.2s ease, transform 0.2s ease;
  backdrop-filter: blur(8px);
  -webkit-backdrop-filter: blur(8px);
}

.toast-visible { opacity: 1; transform: translateX(0); }
.toast-exit    { opacity: 0; transform: translateX(20px); }

.toast-success { background: rgba(29,158,117,0.15); border: 1px solid rgba(29,158,117,0.4); color: #4ade80; }
.toast-error   { background: rgba(239,68,68,0.15);  border: 1px solid rgba(239,68,68,0.4);  color: #f87171; }
.toast-warning { background: rgba(245,158,11,0.15); border: 1px solid rgba(245,158,11,0.4); color: #fbbf24; }
.toast-info    { background: rgba(59,130,246,0.15); border: 1px solid rgba(59,130,246,0.4); color: #60a5fa; }

.toast-progress {
  position: absolute;
  bottom: 0; left: 0;
  height: 2px;
  width: 100%;
  background: currentColor;
  opacity: 0.4;
  animation: toast-shrink var(--toast-duration, 5000ms) linear forwards;
}

@keyframes toast-shrink {
  from { width: 100%; }
  to   { width: 0%; }
}

2. Global Loading States

Every async button now disables itself and shows a spinner during the operation. Prevents double-submissions. Makes it obvious something is happening.

// media/webview/app.ts

function setLoading(btn: HTMLButtonElement, loading: boolean, label?: string): void {
  if (loading) {
    btn.dataset.originalText = btn.textContent ?? '';
    btn.textContent = label ?? '⏳ Working…';
    btn.disabled = true;
    btn.classList.add('btn-loading');
  } else {
    btn.textContent = btn.dataset.originalText ?? 'Share';
    btn.disabled = false;
    btn.classList.remove('btn-loading');
  }
}

// On click — enter loading state
btnShare?.addEventListener('click', () => {
  if (!btnShare) return;
  setLoading(btnShare, true, '⏳ Sharing…');
  send('share', {
    platform:       activeCommandPlatform,
    post:           textarea?.value.trim(),
    mediaFilePaths: activeMediaPaths,
  });
});

// On complete — exit loading state
case 'shareComplete':
  if (btnShare) setLoading(btnShare, false);
  resetAllComposers();
  toast('Shared successfully!', 'success');
  break;

// On error — also exit loading so user can retry
case 'status':
  if (msg.type === 'error' && btnShare) {
    setLoading(btnShare, false);
  }
  toast(String(msg.status ?? ''), msg.type ?? 'info');
  break;

3. Character Limit Validation

MAX_CHARS existed before v3.1 but was never wired to the UI. This release connects it to both the counter display and the share button state.

// media/webview/app.ts

const MAX_CHARS: Record<string, number> = {
  x:        280,
  bluesky:  300,
  linkedin: 3000,
  telegram: 4096,
  facebook: 63206,
  discord:  2000,
  reddit:   40000,
  devto:    100000,
  medium:   100000,
};

function updateCharCounter(): void {
  if (!textarea || !counter) return;

  const len      = textarea.value.length;
  const platform = activeCommandPlatform ?? '';
  const max      = MAX_CHARS[platform] ?? null;

  counter.textContent = max ? `${len} / ${max}` : String(len);
  counter.className   = 'compose-counter';

  if (max) {
    if (len > max)                       counter.classList.add('counter-error');
    else if (len > Math.floor(max * 0.8)) counter.classList.add('counter-warn');
  }
}

function updateShareBtn(): void {
  if (!btnShare) return;
  const empty   = !textarea?.value.trim().length;
  const platform = activeCommandPlatform ?? '';
  const max     = MAX_CHARS[platform] ?? null;
  const over    = max ? (textarea?.value.length ?? 0) > max : false;
  btnShare.disabled = empty || over;
}

textarea?.addEventListener('input', () => {
  updateCharCounter();
  updateShareBtn();
});

.compose-counter               { color: var(--vscode-descriptionForeground); font-size: 12px; }
.compose-counter.counter-warn  { color: #f59e0b; }
.compose-counter.counter-error { color: #ef4444; font-weight: 600; }

4. The Glassmorphism UI Pass

Cards and modals now use backdrop-filter: blur with semi-transparent fills. Depth without visual weight.

.composer-card {
  background: rgba(255, 255, 255, 0.04);
  border: 1px solid rgba(255, 255, 255, 0.08);
  border-radius: 12px;
  backdrop-filter: blur(8px);
  -webkit-backdrop-filter: blur(8px);
  transition: border-color 0.2s ease;
}

.composer-card:hover {
  border-color: rgba(255, 255, 255, 0.14);
}

.modal-content {
  background: rgba(30, 30, 40, 0.92);
  border: 1px solid rgba(255, 255, 255, 0.1);
  border-radius: 14px;
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  animation: modal-enter 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
}

@keyframes modal-enter {
  from { opacity: 0; transform: scale(0.95) translateY(8px); }
  to   { opacity: 1; transform: scale(1)    translateY(0);   }
}

5. The Disappearing Preview Race Condition

This was the most subtle bug. And it was hiding in plain sight.

The Symptom

Attach a file → preview appears → preview vanishes 500ms later. Every time.

The Root Cause

When a file uploaded successfully, the backend sent:

{ command: 'status', type: 'success', status: 'File uploaded successfully' }

The WebView message handler treated every success the same way:

// ❌ BEFORE — nuked everything on any success message
case 'status':
  if (msg.type === 'success') {
    resetAllComposers(); // cleared activeMediaPaths + removed preview DOM
  }
  toast(msg.status, msg.type);
  break;

resetAllComposers() was designed for one thing: clean up after a post is fully shared. But it was firing on file uploads, auto-saves, and every other intermediate success too.

The Fix

// ✅ AFTER — terminal vs intermediate distinction
case 'status': {
  toast(String(msg.status ?? ''), msg.type ?? 'info');

  if (msg.type === 'success') {
    const text = String(msg.status ?? '').toLowerCase();

    const isTerminal     = text.includes('shared')    ||
                           text.includes('published') ||
                           text.includes('complete');

    const isIntermediate = text.includes('upload')    ||
                           text.includes('saved')     ||
                           text.includes('processing');

    if (isTerminal && !isIntermediate) {
      resetAllComposers();
    }
  }
  break;
}

The rule going forward: resetAllComposers() is terminal-only. Intermediate feedback goes to toast() and targeted DOM updates — never a full reset.

6. Reddit's S3 Upload Pipeline

This was the hardest fix in v3.1. Reddit's native image upload doesn't use a standard multipart POST endpoint. It routes through Amazon S3, and the sequence has enough specific requirements that every step has its own failure mode.

The Full Flow

POST /api/media/asset.json  →  receive S3 upload URL + signed fields
POST to S3 URL (FormData)   →  upload the file bytes
POST /api/submit            →  create the Reddit post with asset URL

Step 1 — Get S3 Credentials

// src/platforms/reddit.ts

async function getS3UploadUrl(
  accessToken: string,
  filePath: string,
  mimeType: string
): Promise<{ uploadUrl: string; fields: Record<string, string>; assetUrl: string }> {
  const res = await axios.post(
    'https://oauth.reddit.com/api/media/asset.json',
    new URLSearchParams({
      filepath: path.basename(filePath),
      mimetype: mimeType,
    }),
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/x-www-form-urlencoded',
        'User-Agent': 'DotShare/3.1',
      },
    }
  );

  const uploadUrl = `https:${res.data.args.action}`;

  // Reddit returns fields as [{name, value}] array — convert to object
  const fields: Record<string, string> = {};
  for (const f of res.data.args.fields) {
    fields[f.name] = f.value;
  }

  return {
    uploadUrl,
    fields,
    assetUrl: `https://i.redd.it/${res.data.asset.asset_id}`,
  };
}

Step 2 — Upload to S3

Two traps here. Field order in FormData matters — S3 requires all fields before the file. And S3 requires Content-Length explicitly — axios doesn't set it automatically for FormData in Node.js.

async function uploadToS3(
  uploadUrl: string,
  fields: Record<string, string>,
  filePath: string,
  mimeType: string
): Promise<void> {
  const fileBuffer = await fs.promises.readFile(filePath);
  const formData   = new FormData();

  // All fields MUST come before the file — S3 policy
  for (const [key, value] of Object.entries(fields)) {
    formData.append(key, value);
  }
  formData.append(
    'file',
    new Blob([fileBuffer], { type: mimeType }),
    path.basename(filePath)
  );

  await axios.post(uploadUrl, formData, {
    headers: { 'Content-Length': fileBuffer.byteLength.toString() },
    maxBodyLength: Infinity,
    maxContentLength: Infinity,
  });
}

Step 3 — Submit the Post

async function submitRedditImagePost(
  accessToken: string,
  subreddit: string,
  title: string,
  assetUrl: string
): Promise<string> {
  const res = await axios.post(
    'https://oauth.reddit.com/api/submit',
    new URLSearchParams({
      sr:       subreddit,
      kind:     'image',
      title:    title,
      url:      assetUrl,  // use asset URL, NOT the CDN URL
      resubmit: 'true',
      api_type: 'json',
    }),
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/x-www-form-urlencoded',
        'User-Agent': 'DotShare/3.1',
      },
    }
  );

  const postUrl = res.data?.json?.data?.url;
  if (!postUrl) {
    const errors = res.data?.json?.errors;
    throw new Error(
      errors?.length
        ? `Reddit: ${errors[0][1]}`
        : 'Reddit: no post URL in response'
    );
  }

  return postUrl;
}

The three traps summarized:

FormData field order — fields before file or S3 returns 403
Missing Content-Length — AWS returns 400, message says "malformed body"
CDN URL vs asset URL — i.redd.it/ID is unpopulated at submit time, use the S3 action URL

7. Reddit Field Name Sync

Found this while fixing the S3 pipeline. The WebView was sending field names the backend didn't recognize — and the post text wasn't being sent at all.

// ❌ BEFORE
send('shareToReddit', {
  subreddit: val('redditSubreddit'), // ❌ handler expects 'redditSubreddit'
  title:     val('redditTitle'),     // ❌ handler expects 'redditTitle'
  flair:     ...,                    // ❌ handler expects 'redditFlairId'
  postType:  ...,                    // ❌ handler expects 'redditPostType'
  // ❌ 'post' (the text) missing entirely
});

// ✅ AFTER
send('shareToReddit', {
  post:            textarea?.value.trim() ?? '',
  redditSubreddit: val('redditSubreddit'),
  redditTitle:     val('redditTitle'),
  redditFlairId:   get<HTMLSelectElement>('redditFlair')?.value ?? '',
  redditPostType:  document.querySelector<HTMLInputElement>(
                     'input[name="redditPostType"]:checked'
                   )?.value ?? 'self',
  redditSpoiler:   get<HTMLInputElement>('redditSpoiler')?.checked ?? false,
});

8. Unused Variable Cleanup

// ❌ BEFORE
const btnShare    = get<HTMLButtonElement>('btn-share');
const btnGenerate = get<HTMLButtonElement>('btn-generate-ai');
const btnSchedule = get<HTMLButtonElement>('btn-schedule'); // never used → ESLint error
const btnMedia    = get<HTMLButtonElement>('btn-attach-media');

// ✅ AFTER
const btnShare    = get<HTMLButtonElement>('btn-share');
const btnGenerate = get<HTMLButtonElement>('btn-generate-ai');
const btnMedia    = get<HTMLButtonElement>('btn-attach-media');

Scheduling stays in the HTML as a disabled "Coming Soon" button — listener is commented out pending v3.2.

v3.1 Summary

	Before	After
Status feedback	VS Code popups	Inline toast engine
File preview	Disappears on upload	Stable ✅
Character limits	Display only	Enforced + visual feedback
Reddit images	Broken (S3 errors)	Full pipeline working ✅
Reddit fields	Mismatched	Synchronized ✅
ESLint	1 unused var warning	0 warnings ✅

See It in Action

LinkedIn posting demo:

Telegram posting demo:

Bluesky posting demo:

Install DotShare

VS Code Marketplace

Open VSX (VSCodium / Gitpod

GitHub — star, fork, contribute

v3.2 "The Media Expansion" — up to 4 images per post, per-thumbnail previews, JIT compression, secure WebView URIs — breakdown coming next.

DotShare v3.0 — I Turned My VS Code Extension Into a Full Publishing Suite (Dev.to + Medium Inside)

freerave — Sun, 12 Apr 2026 19:37:13 +0000

A deep technical dive into DotShare v3.0 — the Publishing Suite update that added Dev.to & Medium integrations, a YAML frontmatter parser, platform-first navigation, and a unified PostExecutor architecture. All from inside VS Code.

I Built a VS Code Extension That Posts to Dev.to, Medium & 7 Social Platforms — Here's How v3.0 Works

TL;DR — DotShare v3.0 "The Publishing Suite" transforms the extension from a social poster into a full publishing platform. This post is a deep technical walkthrough of the architecture decisions, the blog API integrations, and the tricky edge cases that took the most time to solve.

🧠 The Problem I Was Solving

Every time I shipped a new feature, I'd write a commit message, then write a Dev.to draft, then rephrase it for LinkedIn, then trim it for Twitter, then reformat it for Medium. Four context switches. Four text editors. Thirty minutes of overhead before my actual audience saw anything.

I'm a VS Code developer. I live in this editor. So I built DotShare — an extension that lets me write once, then distribute everywhere. v1 and v2 handled social platforms. v3.0 adds Dev.to and Medium, and rearchitects the whole thing into something I'm finally proud of.

Let me walk you through exactly how I built it.

🗺️ The Big Picture: What Changed in v3.0

Before v3.0, DotShare had one mental model: a short post goes to social media. The UI reflected that — a single textarea, a platform grid, a share button.

v3.0 breaks that assumption. Now there are two distinct workflows:

┌──────────────────────────────────────────────────┐
│              DotShare v3.0 Workspace              │
├──────────────────────┬───────────────────────────┤
│   SOCIAL WORKSPACE   │      BLOG WORKSPACE        │
│                      │                            │
│  • Single post       │  • Title + Tags            │
│  • Thread composer   │  • Markdown body           │
│  • 280–25K chars     │  • Canonical URL           │
│  • Image attach      │  • Cover image URL         │
│                      │  • Draft/Publish toggle    │
│  Platforms:          │                            │
│  X, LinkedIn,        │  Platforms:                │
│  Bluesky, Reddit,    │  Dev.to, Medium            │
│  Facebook, Discord,  │                            │
│  Telegram            │                            │
└──────────────────────┴───────────────────────────┘

The key architectural move was making platform selection drive the UI, not the other way around. Let me show you how that works.

🏗️ Architecture: `platform-config.ts` as Single Source of Truth

The old code had workspace logic scattered everywhere — HTML conditionals, JS checks, handler guards. I replaced all of it with one file:

// src/platforms/platform-config.ts

export type WorkspaceType = 'social' | 'blog' | 'thread';
export type AuthType = 'oauth' | 'apikey' | 'bearer' | 'bot';

export interface PlatformConfig {
  id: string;
  name: string;
  icon: string;
  workspaceType: WorkspaceType;
  maxChars: number | null;          // null = no limit
  supportsThreads: boolean;
  supportsMedia: boolean;
  supportsScheduling: boolean;
  charCountMethod: 'standard' | 'twitter';
  authType: AuthType;
  color: string;
}

export const PLATFORM_CONFIGS: Record<string, PlatformConfig> = {
  x: {
    id: 'x',
    name: 'X (Twitter)',
    icon: '𝕏',
    workspaceType: 'social',
    maxChars: 280,
    supportsThreads: true,
    supportsMedia: true,
    supportsScheduling: true,
    charCountMethod: 'twitter',
    authType: 'oauth',
    color: '#000000',
  },
  devto: {
    id: 'devto',
    name: 'Dev.to',
    icon: '👨‍💻',
    workspaceType: 'blog',
    maxChars: 100000,
    supportsThreads: false,
    supportsMedia: false,      // API doesn't support file uploads
    supportsScheduling: false,
    charCountMethod: 'standard',
    authType: 'apikey',
    color: '#0a0a0a',
  },
  medium: {
    id: 'medium',
    name: 'Medium',
    icon: 'Ⓜ️',
    workspaceType: 'blog',
    maxChars: 100000,
    supportsThreads: false,
    supportsMedia: false,
    supportsScheduling: false,
    charCountMethod: 'standard',
    authType: 'bearer',
    color: '#00ab6c',
  },
  // ... linkedin, bluesky, reddit, etc.
};

Now when the user clicks a platform icon in the sidebar, one function handles everything:

// media/webview/app.ts

function switchPlatform(platformId: string): void {
  const config = PLATFORM_CONFIGS[platformId];
  if (!config) return;

  activeCommandPlatform = platformId;

  // Workspace switching — driven entirely by config
  const workspace = config.workspaceType;
  document.querySelectorAll('.workspace').forEach(el => {
    (el as HTMLElement).style.display = 'none';
  });
  const target = document.getElementById(`workspace-${workspace}`);
  if (target) target.style.display = 'flex';

  // Update platform header
  updatePlatformHeader(config);

  // Refresh character counter with new limits
  updateCharCounter();
  updateShareBtn();
}

No more scattered if (platform === 'devto') checks in 12 different places.

📝 The Blog Publish Page: Loading Your Active `.md` File

This was the feature I was most excited to build. The idea: you're editing a CHANGELOG.md or a blog-post.md in VS Code. Hit a button. The publish form fills itself.

Backend: Reading the Active Editor

// src/handlers/MessageHandler.ts

case 'loadActiveFile': {
  const editor = vscode.window.activeTextEditor;
  if (!editor) {
    this.sendStatus('No active editor found', 'error');
    return;
  }

  const doc = editor.document;
  if (doc.languageId !== 'markdown') {
    this.sendStatus('Active file is not a Markdown file', 'warning');
    return;
  }

  const content = doc.getText();
  const filePath = doc.uri.fsPath;
  const fileName = path.basename(filePath, '.md');

  // Parse frontmatter and send back to WebView
  const parsed = parseFrontmatter(content);

  this.webview.postMessage({
    command: 'activeFileLoaded',
    content: parsed.body,
    frontmatter: parsed.data,
    fileName,
  });
  break;
}

The YAML Frontmatter Parser

Dev.to and Medium both use YAML frontmatter. I built a parser that extracts the fields I care about:

// src/utils/frontmatterParser.ts

export interface FrontMatter {
  title?: string;
  description?: string;
  tags?: string[];
  cover_image?: string;
  canonical_url?: string;
  series?: string;
  published?: boolean | 'draft' | 'unlisted';
}

export interface ParsedDocument {
  data: FrontMatter;
  body: string;
}

const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;

export function parseFrontmatter(raw: string): ParsedDocument {
  const match = raw.match(FRONTMATTER_REGEX);

  if (!match) {
    return { data: {}, body: raw };
  }

  const yamlBlock = match[1];
  const body = match[2];

  // Minimal YAML parser — handles the fields we care about
  const data: FrontMatter = {};
  const lines = yamlBlock.split('\n');

  for (const line of lines) {
    const colonIdx = line.indexOf(':');
    if (colonIdx === -1) continue;

    const key = line.slice(0, colonIdx).trim();
    const value = line.slice(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '');

    switch (key) {
      case 'title':
        data.title = value;
        break;
      case 'description':
        data.description = value;
        break;
      case 'cover_image':
        data.cover_image = value;
        break;
      case 'canonical_url':
        data.canonical_url = value;
        break;
      case 'series':
        data.series = value;
        break;
      case 'published':
        data.published = value === 'true' ? true : value === 'false' ? false : value as 'draft' | 'unlisted';
        break;
      case 'tags': {
        // Handle both "tags: [a, b]" and multi-line "tags:\n  - a"
        if (value.startsWith('[')) {
          data.tags = value
            .replace(/[\[\]]/g, '')
            .split(',')
            .map(t => t.trim())
            .filter(Boolean);
        }
        break;
      }
    }
  }

  return { data, body };
}

When the WebView receives the activeFileLoaded message, it populates the form:

// media/webview/app.ts

case 'activeFileLoaded': {
  const { content, frontmatter, fileName } = msg;

  // Populate body
  const bodyEditor = get<HTMLTextAreaElement>('blog-body');
  if (bodyEditor) bodyEditor.value = content;

  // Populate frontmatter fields if present
  if (frontmatter.title) {
    const titleEl = get<HTMLInputElement>('blog-title');
    if (titleEl) titleEl.value = frontmatter.title;
  }

  if (frontmatter.tags?.length) {
    frontmatter.tags.forEach((tag: string) => addTagChip(tag));
  }

  if (frontmatter.canonical_url) {
    const canonicalEl = get<HTMLInputElement>('blog-canonical');
    if (canonicalEl) canonicalEl.value = frontmatter.canonical_url;
  }

  if (frontmatter.cover_image) {
    const coverEl = get<HTMLInputElement>('blog-cover');
    if (coverEl) coverEl.value = frontmatter.cover_image;
  }

  toast(`Loaded: ${fileName}.md`, 'success');
  break;
}

🔌 Dev.to API Integration

Dev.to's API is clean and well-documented. Here's the full integration:

// src/platforms/devto.ts

import axios from 'axios';
import { logger } from '../utils/logger';

export interface DevToArticle {
  title: string;
  body_markdown: string;
  published: boolean;
  tags?: string[];           // max 4 tags
  description?: string;
  cover_image?: string;      // must be a public URL
  canonical_url?: string;
  series?: string;
}

export interface DevToResponse {
  id: number;
  url: string;
  title: string;
  published: boolean;
}

export async function shareToDevTo(
  apiKey: string,
  article: DevToArticle
): Promise<DevToResponse> {
  // Dev.to enforces a 4-tag maximum
  const sanitizedTags = (article.tags ?? [])
    .slice(0, 4)
    .map(t => t.toLowerCase().replace(/[^a-z0-9]/g, ''));

  const payload = {
    article: {
      title: article.title,
      body_markdown: article.body_markdown,
      published: article.published,
      tags: sanitizedTags,
      description: article.description,
      cover_image: article.cover_image ?? null,
      canonical_url: article.canonical_url ?? null,
      series: article.series ?? null,
    },
  };

  try {
    const response = await axios.post<{ article: DevToResponse }>(
      'https://dev.to/api/articles',
      payload,
      {
        headers: {
          'api-key': apiKey,
          'Content-Type': 'application/json',
        },
      }
    );

    logger.info(`[Dev.to] Published: ${response.data.article.url}`);
    return response.data.article;
  } catch (err: unknown) {
    if (axios.isAxiosError(err)) {
      const status = err.response?.status;
      const detail = err.response?.data?.error ?? err.message;

      if (status === 422) {
        // Validation error — usually malformed tags or missing title
        throw new Error(`Dev.to validation error: ${detail}`);
      }
      if (status === 401) {
        throw new Error('Dev.to API key is invalid or expired');
      }
    }
    throw err;
  }
}

The Image Policy Problem

Dev.to's API does not support file uploads. If you try to POST a local file as a cover image, it just silently drops it. I spent two hours debugging this before reading the docs carefully.

My solution: detect local file paths and warn the user instead of silently failing:

// src/handlers/PostHandler.ts

private validateBlogMedia(article: DevToArticle, platform: 'devto' | 'medium'): DevToArticle {
  const { cover_image } = article;

  if (cover_image && !cover_image.startsWith('http')) {
    // Local file path — not supported
    logger.warn(
      `[${platform}] Local cover image "${cover_image}" skipped. ` +
      `${platform === 'devto' ? 'Dev.to' : 'Medium'} only accepts public URLs. ` +
      `Consider uploading to Cloudinary, GitHub, or Imgur first.`
    );
    return { ...article, cover_image: undefined };
  }

  return article;
}

Ⓜ️ Medium API Integration

Medium's API is older and has a few quirks worth documenting.

// src/platforms/medium.ts

import axios from 'axios';

export type MediumPublishStatus = 'public' | 'draft' | 'unlisted';
export type MediumContentFormat = 'markdown' | 'html';

export interface MediumPost {
  title: string;
  contentFormat: MediumContentFormat;
  content: string;
  tags?: string[];             // max 5 tags
  canonicalUrl?: string;
  publishStatus?: MediumPublishStatus;
}

// Medium's API uses "published" but their enum value is "public" — this trips people up
export function normalizeMediumPublishStatus(
  status: string | boolean | undefined
): MediumPublishStatus {
  if (status === true || status === 'published' || status === 'public') {
    return 'public';
  }
  if (status === 'unlisted') return 'unlisted';
  return 'draft'; // safe default
}

export async function shareToMedium(
  bearerToken: string,
  post: MediumPost
): Promise<{ id: string; url: string }> {
  // Step 1: get the authenticated user's ID
  const userResp = await axios.get('https://api.medium.com/v1/me', {
    headers: { Authorization: `Bearer ${bearerToken}` },
  });
  const userId: string = userResp.data.data.id;

  const sanitizedTags = (post.tags ?? []).slice(0, 5);

  const payload = {
    title: post.title,
    contentFormat: post.contentFormat,
    content: post.content,
    tags: sanitizedTags,
    canonicalUrl: post.canonicalUrl,
    publishStatus: normalizeMediumPublishStatus(post.publishStatus),
  };

  const response = await axios.post(
    `https://api.medium.com/v1/users/${userId}/posts`,
    payload,
    {
      headers: {
        Authorization: `Bearer ${bearerToken}`,
        'Content-Type': 'application/json',
      },
    }
  );

  return {
    id: response.data.data.id,
    url: response.data.data.url,
  };
}

The published → public gotcha: Medium's publish status enum uses "public", not "published". YAML frontmatter typically has published: true. If you pass that string directly to the API, Medium silently defaults to draft. The normalizeMediumPublishStatus() function handles all the variants.

⚡ The `PostExecutor`: Decoupling from VS Code UI

Before v3.0, all posting logic lived inside PostHandler.ts, which was tightly coupled to the VS Code extension host. This made it impossible to use the same logic from the scheduler running in the background.

v3.0 introduces PostExecutor — a clean execution engine with no VS Code dependencies:

// src/services/PostExecutor.ts

export interface ExecutorCallbacks {
  onProgress?: (platform: string, message: string) => void;
  onSuccess?: (platform: string, url?: string) => void;
  onError?: (platform: string, error: Error) => void;
}

export class PostExecutor {
  constructor(
    private readonly credentials: CredentialProvider,
    private readonly history: HistoryService,
  ) {}

  async executeBlogPost(
    post: BlogPost,
    targets: PublishTarget[],
    callbacks: ExecutorCallbacks = {}
  ): Promise<PublishResult[]> {
    const results: PublishResult[] = [];

    for (const target of targets) {
      callbacks.onProgress?.(target.platform, `Publishing to ${target.platform}...`);

      try {
        let url: string | undefined;

        if (target.platform === 'devto') {
          const apiKey = await this.credentials.getDevToApiKey();
          const result = await shareToDevTo(apiKey, {
            title: post.title,
            body_markdown: post.body,
            published: post.publishStatus !== 'draft',
            tags: post.tags,
            description: post.description,
            cover_image: post.coverImage,
            canonical_url: post.canonicalUrl,
            series: post.series,
          });
          url = result.url;

        } else if (target.platform === 'medium') {
          const token = await this.credentials.getMediumToken();
          const result = await shareToMedium(token, {
            title: post.title,
            contentFormat: 'markdown',
            content: post.body,
            tags: post.tags,
            canonicalUrl: post.canonicalUrl,
            publishStatus: normalizeMediumPublishStatus(post.publishStatus),
          });
          url = result.url;
        }

        results.push({ platform: target.platform, success: true, url });
        callbacks.onSuccess?.(target.platform, url);

        // Log to history
        await this.history.addEntry({
          platform: target.platform,
          content: post.title,
          timestamp: new Date().toISOString(),
          success: true,
          url,
        });

      } catch (err: unknown) {
        const error = err instanceof Error ? err : new Error(String(err));
        results.push({ platform: target.platform, success: false, error: error.message });
        callbacks.onError?.(target.platform, error);

        await this.history.addEntry({
          platform: target.platform,
          content: post.title,
          timestamp: new Date().toISOString(),
          success: false,
          error: error.message,
        });
      }
    }

    return results;
  }
}

Now PostHandler just wires VS Code messages to the executor:

// src/handlers/PostHandler.ts (simplified)

case 'shareToBlogs': {
  const post: BlogPost = {
    title: msg.title,
    body: msg.body,
    tags: msg.tags ?? [],
    publishStatus: msg.publishStatus ?? 'draft',
    canonicalUrl: msg.canonicalUrl,
    coverImage: msg.coverImage,
    description: msg.description,
    series: msg.series,
  };

  const targets: PublishTarget[] = (msg.platforms as string[]).map(p => ({
    platform: p,
  }));

  await this.executor.executeBlogPost(post, targets, {
    onProgress: (platform, message) => {
      this.sendStatus(message, 'info');
    },
    onSuccess: (platform, url) => {
      this.sendStatus(`✅ Published to ${platform}${url ? ': ' + url : ''}`, 'success');
    },
    onError: (platform, error) => {
      this.sendStatus(`❌ ${platform} failed: ${error.message}`, 'error');
    },
  });

  this.webview.postMessage({ command: 'shareComplete' });
  break;
}

🔑 `CredentialProvider`: The `resolve()` Refactor

Every credential-getter used to look like this:

// ❌ BEFORE — repeated in every method
async getDevToApiKey(): Promise<string> {
  if (this.credentialsGetter) {
    const creds = await this.credentialsGetter();
    const key = creds.devtoApiKey;
    if (!key) throw new Error('Dev.to API key not configured');
    return key;
  } else {
    const key = await this.secretStorage.get('dotshare.devto.apiKey');
    if (!key) throw new Error('Dev.to API key not configured');
    return key;
  }
}

The resolve() refactor eliminates the duplication:

// ✅ AFTER
export class CredentialProvider {
  private async resolve(
    secretKey: string,
    errorMessage: string
  ): Promise<string> {
    const value = this.credentialsGetter
      ? (await this.credentialsGetter())[secretKey as keyof Credentials]
      : await this.secretStorage.get(`dotshare.${secretKey}`);

    if (!value) throw new Error(errorMessage);
    return value;
  }

  async getDevToApiKey(): Promise<string> {
    return this.resolve('devto.apiKey', 'Dev.to API key not configured. Go to Settings → Dev.to.');
  }

  async getMediumToken(): Promise<string> {
    return this.resolve('medium.token', 'Medium integration token not configured.');
  }

  async getRedditSubreddit(): Promise<string> {
    return this.resolve('reddit.subreddit', 'Target subreddit not configured.');
  }
}

🐛 The Bugs That Took the Most Time

1. The Twitter URL Count Bug

Twitter counts URLs as exactly 23 characters, regardless of length. My original implementation used Math.min(url.length, 23), which was wrong — a 10-character URL would count as 10, not 23.

// ❌ Wrong
const urlChars = Math.min(url.length, 23);

// ✅ Correct — Twitter always counts URLs as exactly 23 chars
const urlChars = 23;

One character of difference. Caused character counters to be wrong for posts with URLs.

2. Reddit's Hardcoded Subreddit

There was a subreddit: 'test' string buried in PostHandler.ts from early development. Reddit posts were going to r/test in production. Found it in a code review.

// ❌ Found this in production
const subreddit = 'test';

// ✅ Fixed
const subreddit = await this.credentials.getRedditSubreddit();
if (!subreddit) {
  throw new Error('Configure your target subreddit in DotShare settings.');
}

3. `PostHandler` Reading Stale History Instead of the Current Message

handleShareToX() was calling historyService.getLastPost() instead of reading message.post. This meant editing a post and resharing would sometimes send the previous version.

// ❌ Reading from history
const content = await historyService.getLastPost();

// ✅ Reading from the actual incoming message
const content = message.post;

📊 v3.0 by the Numbers

Metric	v2.4	v3.0	Change
Platforms supported	7	9	+2
Lines in `PostHandler.ts`	~800	~320	−60%
Files in `src/`	14	23	+9 new
TypeScript errors	0	0	✅
ESLint violations	0	0	✅
New types in `types.ts`	—	14	+14

🚀 What's Next: v3.1 & v3.2

v3.0 is the foundation. The next two releases focus on:

v3.1 "The Polish Pass" — Toast notification engine, glassmorphism UI, character limit validation, and fixing a nasty media preview race condition
v3.2 "The Media Expansion" — Multi-image support (up to 4 images), per-thumbnail previews, and JIT image compression

I'll be writing deep dives on both.

🔗 Links

GitHub: github.com/kareem2099/DotShare
VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=FreeRave.dotshare
Open VSX (VSCodium / Gitpod): https://open-vsx.org/extension/freerave/dotshare
Install via CLI: code --install-extension freerave.dotshare
Support the project: buymeacoffee.com/freerave

If you're building in public or maintaining an open source project, give DotShare a try. I'd love to hear how you use it — drop a comment below 👇

Built with TypeScript, VS Code Extension API, and a lot of coffee.

I Got Badges 1, 2, and 4 on DEV.to — Badge #3 Is Currently in Witness Protection

freerave — Sun, 12 Apr 2026 10:23:45 +0000

I debug production systems for fun.

I've traced memory leaks at 2am. I've stared into the void of a segfault and the void stared back. I once spent 6 hours chasing a bug that turned out to be a missing semicolon — and I still consider that a good day.

Nothing prepared me for this.

I opened my DEV.to profile expecting the warm dopamine hit of a clean badge row. Instead, I got:

🏆 1
🏆 2
👻 (??)
🏆 4

I did what any reasonable developer does in a crisis. I refreshed the page.

Still gone.

I cleared the cache. Hard refreshed. Opened incognito. Checked on my phone. Filed a mental ticket titled "skill issue or cosmic injustice?" and assigned it P0.

The Investigation Begins

My first theory: off-by-one error. Classic. DEV.to's badge system probably starts counting from 0 internally and someone forgot to add 1. Badge #3 is actually badge #2 in the database. This is someone's fault and I will find them.

My second theory: race condition. I publish a lot. Maybe two badge triggers fired simultaneously, they fought over a mutex, one lost, and badge #3 died in the conflict. A silent casualty of concurrency.

My third theory: the badge ghosted me. Sometimes people just leave. It's not about you.

The Actual Answer (Anticlimactic)

DEV.to counts streaks by calendar weeks, not "7 consecutive days."

That's it. That's the whole bug.

I was publishing every day like a caffeinated open-source evangelist, but multiple articles landed in the same ISO calendar week. The system went: "That's one week, bestie" — and quietly skipped the streak badge with zero logs, zero warnings, and zero emotional support.

No exception thrown.
No toast notification saying "hey you might be doing this wrong."
Just a missing badge and a developer questioning his entire relationship with time.

What I Should Have Done

1. Read the docs → man dev.to/badges
2. Understand calendar week boundaries
3. Publish accordingly
4. Touch grass

I did none of these things.

The Takeaway

Streak systems are just cron jobs with feelings.

Calendar weeks are a social construct designed specifically to humble developers who think they're being productive.

And badge #3? It's out there somewhere. Living its best life. Probably deployed on a competitor's platform.

I'm fine.

(I'm not fine.)

Have you ever been gaslit by a gamification system? Drop it in the comments. We heal together. 🐛

cc: @ben — I believe this qualifies as a P2 ticket. Not urgent. Just emotionally damaging.

EXPOSED: The Youdao Ads Influencer Marketing Scam - Technical Analysis & Red Flags

freerave — Sat, 11 Apr 2026 07:33:40 +0000

How sophisticated scammers are exploiting legitimate NetEase domains to target content creators and developers with fake influencer marketing campaigns

How sophisticated scammers are exploiting legitimate domains and targeting content creators

TL;DR

Youdao Ads / InfunEase (infunease.youdaoads.com) is a confirmed scam operation targeting content creators, influencers, and developers. Despite using a legitimate NetEase subdomain and passing email authentication, this is a sophisticated phishing campaign designed to steal personal information and money from unsuspecting creators.

🔴 Trust Score: 28.8/100 (Scam Detector)

🔴 Status: Active scam with live infrastructure

🔴 Risk Level: HIGH - Identity theft, financial fraud

The Email That Started It All

I received this seemingly legitimate email from "anjiaqi06@corp.netease.com":

Subject: Don't scroll past 【Youdao Ads】– a paid collab that's actually your vibe 😉

We recently got a few brand campaigns that feel like they were made for your 
channel. I've already filtered out the generic, one-size-fits-all stuff—these 
are the ones that fit your style and will actually resonate with your audience.

A few details:
💰 Budget's ready – just name your rate
⏳ Spots are filling up – a few other creators in your space are already looking at them

If you're interested, just tap here to see the campaigns waiting for you: [Youdao Ads]

First red flag? I never applied to any influencer program, and they somehow "knew" my content style without specifying what kind of creator I am.

Technical Deep Dive: The Email Headers Don't Lie

Let's examine the email headers to understand how this scam works:

Authentication Results: ✅ All Green (Misleading!)

DKIM-Signature: v=1; a=rsa-sha256; d=corp.netease.com; s=s210401; 
Authentication-Results: mx.google.com;
       dkim=pass header.i=@corp.netease.com
       spf=pass smtp.mailfrom=anjiaqi06@corp.netease.com
       dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=corp.netease.com

Why this is dangerous: All email authentication passes because:

NetEase is a legitimate Chinese tech company
The email truly comes from their servers (IP: 1.95.22.228)
This suggests either a compromised corporate account or insider threat

The Smoking Gun: X-Mailer Header

X-Mailer: Coremail Webmail Server Version XT6.0.5 build 20231102

This reveals the email was sent through NetEase's internal webmail system, not their official marketing platforms.

Website Analysis: Professional Scam Infrastructure

The Scam Site: `https://infunease.youdaoads.com`

When we attempted to analyze the website directly:

curl -I https://infunease.youdaoads.com
# Result: HTTP/1.1 403 Forbidden
# x-deny-reason: host_not_allowed

The site is blocked by security infrastructure, indicating it's been flagged as malicious.

Google Search Results Reveal the Truth

Despite being blocked, Google has indexed the site with this revealing content:

"Join the community now and seize the opportunities to work with top brands! Whether you are a nano or macro influencer, we have prepared the right fits for you. By joining this group chat, you could access the newest and exclusive offers before anyone else!"

Generic language targeting anyone and everyone - classic scam behavior.

Third-Party Security Analysis

Scam Detector Verdict: 28.8/100

Tags: "Risky. Dubious. Perilous."
High-risk activity detected for phishing and spamming
Algorithm flagged multiple fraud indicators

The Scam Operation Breakdown

Phase 1: Email Harvest & Initial Contact

Mass emails to developers, creators, YouTubers
Personalized enough to seem legitimate
Uses urgency and FOMO psychology

Phase 2: Data Collection

Clicking the link leads to forms requesting:

Social media handles and follower counts
Personal identification information
Bank account details "for payments"
Tax information for "compliance"

Phase 3: The Hook

Two common next steps:

Advance Fee Scam: "Pay processing fees to unlock campaigns"
Identity Theft: Sell collected personal data to other criminals

Phase 4: Social Engineering

Discord/WhatsApp group invitations
Fake "other creators" testimonials
Continued pressure to provide more information

Red Flags Developers Should Recognize

🚩 Email Red Flags

Generic targeting: Claims to know your content without specifics
Urgency pressure: "Spots filling up," "don't let these slip"
Unprofessional contact: WhatsApp and Discord instead of business email
Grammar inconsistencies: Mixed professional/casual tone

🚩 Website Red Flags

Blocked by security services: Major red flag
Generic content: "nano or macro influencer" covers everyone
No specific brand examples: Real agencies show actual clients
Social media focus: Legitimate marketing goes through official channels

🚩 Technical Red Flags

Subdomain abuse: Using legitimate company's subdomain improperly
Low trust scores: 28.8/100 from multiple security vendors
Suspicious registration patterns: Domain parking tactics

How to Protect Yourself

✅ Immediate Actions

Never click suspicious links - Even if emails pass authentication
Verify independently - Contact companies through official channels
Check security scores - Use ScamAdviser, VirusTotal, etc.
Trust your instincts - If it feels too good to be true, it probably is

✅ Long-term Security Practices

Enable 2FA everywhere - Protect all your social media accounts
Monitor your digital footprint - Google your handles regularly
Use dedicated business email - Keep personal/business communications separate
Regular security awareness - Stay updated on latest scam tactics

✅ For Content Creators Specifically

Legitimate partnerships require proper contracts and legal documentation
Real brands have verification badges and official marketing teams
Payment flows go through established platforms (not personal accounts)
Networking happens at conferences, through agencies, or official programs

Reporting This Scam

If you encounter this scam:

🔴 Immediate Reporting

Forward phishing email to: reportphishing@apwg.org
Report to Google: google.com/safebrowsing/report_phish/
FTC Report: reportfraud.ftc.gov
NetEase Security: Contact through official channels

🔴 Protect Others

Share this analysis with your developer/creator networks
Post warnings in relevant Discord servers and forums
Update security communities about this specific campaign

The Bigger Picture: Domain Reputation Abuse

This scam highlights a critical security issue:

Legitimate companies must monitor their subdomain usage to prevent reputation abuse. NetEase's subdomain being used for scam operations could:

Damage their brand reputation
Get their entire domain flagged by security services
Impact legitimate business operations
Create legal liabilities

For Cybersecurity Professionals

This case demonstrates:

Email authentication limitations when insider accounts are compromised
Importance of subdomain monitoring in enterprise security
Social engineering evolution targeting creator economy
Need for multi-layered verification beyond technical authentication

Conclusion: Stay Vigilant

The creator economy's rapid growth has created new attack vectors for scammers. This Youdao Ads campaign shows how sophisticated these operations have become:

✅ Technical legitimacy (passing email authentication)
✅ Professional presentation (well-designed emails and websites)
✅ Psychological manipulation (urgency, flattery, FOMO)
✅ Infrastructure investment (dedicated websites, communication channels)

Remember: In cybersecurity, trust but verify. Always verify.

Resources & Links

Have you encountered this scam? Share your experience in the comments to help others stay safe.

Found this analysis helpful? Share it with your network - together we can shut down these operations.

This analysis was conducted for cybersecurity awareness purposes. Always report suspected scams to appropriate authorities and never interact with suspicious websites or provide personal information to unverified sources.

About the Analysis: This technical breakdown is based on email header analysis, DNS investigation, third-party security assessments, and OSINT research. All findings have been cross-verified through multiple security tools and databases.

Conquering the Reddit API: How to Natively Upload Images via Node.js (And Survive the S3 Boss Fight)

freerave — Tue, 07 Apr 2026 18:23:35 +0000

A step-by-step guide to defeating the undocumented traps of Reddit's native image upload API, avoiding AWS S3 400 errors, and the infamous Invalid image URL.
If you've ever tried building a tool to auto-publish posts to Reddit using their API, you've probably hit a wall when it comes to images.

Sure, you could just upload your images to Imgur and post a link, but we want that sweet, native, inline Reddit image experience! The official Reddit API does have an endpoint for this (/api/media/asset.json), but trying to use it in Node.js feels like walking through a minefield blindfolded.

After hours of debugging, screaming at my terminal, and fighting AWS S3, I finally cracked the exact sequence and undocumented gotchas required to make this work.

If you are seeing 400 Bad Request from S3, Bucket POST must contain a field named 'key', or Reddit mocking you with Invalid image URL... grab a coffee. You're in the right place. ☕

🛠 Prerequisites: The Setup

Before we start the dance, make sure you have your dependencies ready. For this guide, we'll use axios for HTTP requests and form-data to build our multipart payloads.

import axios from 'axios';
import fs from 'fs';
import path from 'path';
import FormData from 'form-data';

// You should already have this from your Reddit OAuth completion
const REDDIT_ACCESS_TOKEN = 'your_oauth_access_token';

The Master Plan

To upload a native image to Reddit, you don't just send an image to a Reddit server. It's a 3-step dance:

Get the Lease: Ask Reddit for an AWS S3 upload lease (/api/media/asset.json).
S3 Upload: Upload the file directly to AWS S3 using the lease details.
Publish: Tell Reddit to create the post (/api/submit), pointing it to the correct S3 location.

Sounds simple? Let's look at the traps.

Step 1: Getting the Lease

First, you tell Reddit you want to upload a file.

const mediaFile = 'path/to/my-awesome-meme.png';
const ext = path.extname(mediaFile).toLowerCase();

const params = new URLSearchParams();
params.append('filepath', path.basename(mediaFile));
params.append('mimetype', 'image/png'); // Important: send correct mimetype

const leaseResponse = await axios.post('https://oauth.reddit.com/api/media/asset.json', params, {
    headers: { 'Authorization': `Bearer ${REDDIT_ACCESS_TOKEN}` }
});

const { args, asset } = leaseResponse.data;
if (!args || !asset?.asset_id) {
    throw new Error('Failed to get upload lease from Reddit');
}

Reddit responds with an asset_id and args, which contains the AWS action URL (usually https://reddit-uploaded-media.s3-accelerate.amazonaws.com) and the fields required to authorize the S3 upload.

Step 2: The S3 Upload (Where Dreams go to Die)

🚨 Trap #1: The `args.fields` Array Trap

If you look at the args.fields returned by Reddit, its structure looks something like this:

"fields": [
  { "name": "key", "value": "reddit-uploaded-media/xyz123" },
  { "name": "AWSAccessKeyId", "value": "..." },
  { "name": "policy", "value": "..." }
]

Notice anything? It's an array of objects, not a standard key-value dictionary!
If you try to map over it using standard dictionary parsers like Object.entries(), Node.js will append the fields with numeric keys like "0", "1", "2".

AWS S3 will ruthlessly reject your upload with an XML error message:
<Message>Bucket POST must contain a field named 'key'</Message>

The Fix: Parse it explicitly as an array to correctly populate FormData.

const formData = new FormData();
let s3Key = '';

// Crucial: Handle array structure returned by Reddit!
if (Array.isArray(args.fields)) {
    args.fields.forEach((field) => {
        formData.append(field.name, String(field.value));
        if (field.name === 'key') s3Key = String(field.value); // Save this!
    });
}

🚨 Trap #2: The Chunked Encoding Trap

We need to append our actual image file to the FormData. However, if you are passing a stream (e.g., fs.createReadStream()), Node.js HTTP clients (like axios) will default to sending the request via Transfer-Encoding: chunked.

AWS S3 strictly forbids chunked POST requests for presigned URLs and will instantly strike you down with a 400 Bad Request.

The Fix: You must append the file with explicit content types AND calculate the exact Content-Length before firing the request.

// Ensure file is the LAST field added to formData!
formData.append('file', fs.createReadStream(mediaFile), { 
    filename: path.basename(mediaFile),
    contentType: 'image/png' 
});

// Calculate length to avoid S3 chunked transfer encoding rejection
const contentLength = await new Promise((resolve, reject) => {
    formData.getLength((err, length) => err ? reject(err) : resolve(length));
});

// Reddit's action URL might be missing the protocol
const uploadUrl = args.action.startsWith('http') ? args.action : `https:${args.action}`;

await axios.post(uploadUrl, formData, {
    headers: {
        ...formData.getHeaders(),
        'Content-Length': contentLength.toString()
    },
    timeout: 60000,
    maxBodyLength: Infinity,
    maxContentLength: Infinity
});

console.log('✅ Successfully uploaded to S3!');

S3 should now return a beautiful 201 Created or 204 No Content response.

Step 3: Publishing the Post (The Final Boss)

Now that the image is securely on S3, we need to create the actual Reddit post.

🚨 Trap #3: The `Invalid image URL` Trap

You might logically think: "The image is uploaded, so it will be hosted on Reddit's CDN! I'll just pass url: https://i.redd.it/{asset_id}.png in my publish payload!"

WRONG.
If you try to publish using the i.redd.it URL, the Reddit API will immediately attempt to fetch it to validate your submission. Since the CDN hasn't populated your file globally yet, Reddit's backend gets a 404 underneath, and throws an Invalid image URL error directly in your face.

The Fix: Give Reddit the exact, raw AWS S3 URL you just pushed the image to! That's the URL constructed by joining the uploadUrl and the s3Key we saved earlier.

// e.g., https://reddit-uploaded-media.s3-accelerate.amazonaws.com/reddit-uploaded-media/xyz123
const finalS3Url = `${uploadUrl}/${s3Key}`; 

const postData = new URLSearchParams();
postData.append('api_type', 'json');
postData.append('sr', 'YourTargetSubredditName'); 
postData.append('title', 'My Awesome Native Image Post');
postData.append('kind', 'image'); // Tell Reddit it's a native media post
postData.append('url', finalS3Url); // Crucial: Give them the raw S3 link!

// Pro-tip: If you are testing this code repeatedly with the same 
// image/title, Reddit will block it as a duplicate. Use 'resubmit'.
postData.append('resubmit', 'true'); 

const publishResponse = await axios.post('https://oauth.reddit.com/api/submit', postData, {
    headers: { 'Authorization': `Bearer ${REDDIT_ACCESS_TOKEN}` }
});

// Check if Reddit API returned logic errors inside the 200 OK!
if (publishResponse.data.json?.errors?.length > 0) {
    console.error('Reddit API Errors:', publishResponse.data.json.errors);
} else {
    console.log('🎉 Boom! Post successful:', publishResponse.data.json?.data?.name);
}

Boom! 🚀

Reddit will take that S3 URL, ingest it, process it, and magically swap it out for a native i.redd.it link on the platform. Your post will now show up with a beautiful, inline image, no third-party URLs or external thumbnails required.

If this saved you from pulling the rest of your hair out, share it with a fellow developer. Happy coding, and may your S3 buckets forever be forgiving!

DotShare v3.0 — I Built a Full Publishing Suite Inside VS Code (And What I Learned)

freerave — Mon, 06 Apr 2026 16:20:07 +0000

How I went from a simple social media poster to a full publishing suite with Dev.to, Medium, thread composers, and auth health checks — all without leaving VS Code.

I've been building DotShare — a VS Code extension that lets you post to LinkedIn, X, Bluesky, Telegram, Reddit, Discord, and Facebook directly from your editor. After shipping v2.4 with one-click OAuth, I thought I was done for a while.

Then I started writing more long-form content. Every time I finished a markdown article in VS Code, I had to open a browser, go to Dev.to, copy-paste my content, fix the formatting, add tags, set the canonical URL... you know the drill.

So I rebuilt the whole thing.

What Changed in v3.0 — The Publishing Suite

The headline feature is blog publishing — but the real story is the architecture behind it.

1. Platform-First Navigation

The old UI had "workspace tabs" — you picked Threads, Social, or Blogs, then selected your platform. It was confusing and redundant.

In v3.0, I flipped it: click the platform icon, the workspace adapts automatically.

// platform-config.ts — single source of truth
export const PLATFORM_CONFIGS: Record<string, PlatformConfig> = {
    x: {
        name: 'X / Twitter',
        icon: '𝕏',
        maxChars: 280,
        premiumMaxChars: 25000,
        supportsThreads: true,
        workspaceType: 'threads',   // → Thread Composer
        charCountMethod: 'twitter',
        authType: 'oauth2',
    },
    linkedin: {
        name: 'LinkedIn',
        maxChars: 3000,
        supportsThreads: false,
        workspaceType: 'social',    // → Social Composer
        authType: 'oauth2',
    },
    devto: {
        name: 'Dev.to',
        maxChars: 100000,
        workspaceType: 'blogs',     // → Article Publisher
        authType: 'api_key',
    },
};

This file is shared between the extension host and the WebView — no VS Code imports, just pure TypeScript. When the user clicks the Dev.to icon, switchPlatform('devto') reads workspaceType: 'blogs' and shows the Article Publisher. One source of truth, zero hardcoded workspace routing.

2. Dev.to Integration

Dev.to has a clean REST API. You POST to /api/articles with your api-key header and you're done.

// devto.ts
export async function shareToDevTo(
    apiKey: string,
    articleData: {
        text: string;
        title?: string;
        tags?: string[];
        description?: string;
        coverImage?: string;
        published?: boolean;
        canonicalUrl?: string;
        series?: string;
    }
): Promise<string> {
    const { title, body } = extractTitleFromMarkdown(articleData.text);
    const tags = articleData.tags?.length 
        ? articleData.tags.slice(0, 4)      // Dev.to max: 4 tags
        : extractTags(articleData.text);

    const payload = {
        article: {
            title: articleData.title || title,
            body_markdown: body,
            tags,
            published: articleData.published ?? true,
            ...(articleData.coverImage && { main_image: articleData.coverImage }),
            ...(articleData.canonicalUrl && { canonical_url: articleData.canonicalUrl }),
            ...(articleData.series?.trim() && { series: articleData.series.trim() }),
        },
    };

    const response = await axios.post(
        'https://dev.to/api/articles',
        payload,
        { headers: { 'api-key': apiKey, 'Content-Type': 'application/json' } }
    );

    return response.data.url;
}

One thing I learned the hard way: Dev.to does not support image file uploads via API. The dev-to-uploads.s3.amazonaws.com bucket you see in articles is only accessible through their web editor. The API only accepts public URLs. So if you're building an integration, skip the upload logic entirely and tell users to host images externally.

3. YAML Frontmatter Parser

When you click "Load Current File", DotShare reads the active .md file from VS Code's editor and parses the frontmatter:

// frontmatter-parser.ts
export function parseFrontMatter(content: string): {
    hasFrontmatter: boolean;
    frontmatter?: FrontMatter;
    body: string;
} {
    const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
    const match = content.match(FRONTMATTER_REGEX);

    if (!match) return { hasFrontmatter: false, body: content };

    const [, yamlContent, body] = match;
    const frontmatter: FrontMatter = {};

    for (const line of yamlContent.split('\n')) {
        const colonIndex = line.indexOf(':');
        if (colonIndex === -1) continue;

        const key = line.slice(0, colonIndex).trim();
        const value = line.slice(colonIndex + 1).trim();

        switch (key) {
            case 'title':         frontmatter.title = value.replace(/^['"]|['"]$/g, ''); break;
            case 'tags':          frontmatter.tags = parseTags(value); break;
            case 'canonical_url': frontmatter.canonical_url = value; break;
            case 'description':   frontmatter.description = value; break;
            case 'cover_image':   frontmatter.cover_image = value; break;
            case 'series':        frontmatter.series = value; break;
            case 'published':     frontmatter.published = value === 'true'; break;
        }
    }

    return { hasFrontmatter: true, frontmatter, body: body.trim() };
}

The publish form auto-fills from whatever frontmatter exists. If your article already has title, tags, and canonical_url in the frontmatter, you open DotShare, click Load, and hit Publish. Done.

4. Thread Composer + X Premium

X and Bluesky both support threads. The thread composer lets you build them post-by-post, with a per-post character counter that respects each platform's rules.

For X, I added a Premium toggle that switches the limit from 280 to 25,000 characters:

// In app.ts (WebView side)
const premiumToggle = document.getElementById('x-premium-toggle') as HTMLInputElement;
premiumToggle.addEventListener('change', () => {
    const isPremium = premiumToggle.checked;
    const maxChars = isPremium
        ? PLATFORM_CONFIGS['x'].premiumMaxChars   // 25000
        : PLATFORM_CONFIGS['x'].maxChars;          // 280

    updateAllCharCounters('x', maxChars);
});

For Bluesky threads, the extension joins all posts with a manual separator (===) and the bluesky.ts adapter splits them back:

// bluesky.ts
function createThreadChunks(text: string, maxLength = 300): string[] {
    // Manual separator from Thread Composer
    const manualParts = text.split(/\n\n===\n\n/);
    if (manualParts.length > 1) {
        const chunks: string[] = [];
        for (const part of manualParts) {
            const trimmed = part.trim();
            if (trimmed.length > maxLength) {
                chunks.push(...splitByWords(trimmed, maxLength));
            } else {
                chunks.push(trimmed);
            }
        }
        return chunks.map((chunk, i) => `${chunk} (${i + 1}/${chunks.length})`);
    }
    return splitByWords(text, maxLength);
}

5. Twitter Character Counting — A Subtle Bug

Twitter counts every URL as exactly 23 characters (their t.co proxy length), regardless of the actual URL length. I had a bug in the original implementation:

// ❌ Wrong — short URLs were counted as their actual length
text.replace(URL_REGEX, (url) => 'x'.repeat(Math.min(url.length, 23)))

// ✅ Correct — all URLs are always 23 chars
text.replace(URL_REGEX, 'x'.repeat(23))

Small bug, but it made the character counter off for short URLs like https://t.co/abc.

v3.0.1 — The Medium Situation

Shortly after shipping v3.0, I realized something: Medium has stopped issuing new integration tokens.

Their official response from help.medium.com:

"Medium will not be issuing any new integration tokens for our API and will not allow any new integrations. All existing tokens will continue to work."

The only workaround is to email yourfriends@medium.com and request access manually — they do respond within 24 hours and do activate the token section on your account. So the medium.ts integration is solid, but the onboarding requires this extra step.

I added a notice directly in the Settings card so users know before they go hunting for a token that doesn't exist in the UI:

<p class="platform-notice">
  ⚠️ Medium no longer issues new tokens automatically.
  Email <strong>yourfriends@medium.com</strong> to request access.
  They usually respond within 24 hours.
</p>

The Medium API itself works fine — it's just the token provisioning that requires the manual email step.

v3.1.0 — Reliability: Auth Server Health Checks

DotShare uses an OAuth server (dotshare-auth-server.vercel.app) for X, Reddit, and Facebook. The TokenManager handles auto-refresh of expiring tokens.

The problem: if the auth server goes down, the user just gets a generic error when they try to post. The connect button stays enabled, the user clicks it, nothing happens.

The fix is straightforward — check health before attempting any OAuth operation, cache the result, and disable the button with a clear message if the server is unreachable:

// TokenManager.ts
let _lastHealthCheck: { ok: boolean; timestamp: number } | null = null;
const HEALTH_CACHE_MS = 30 * 1000; // 30 seconds

static async checkHealth(): Promise<boolean> {
    // Return cached result if still fresh
    if (_lastHealthCheck && Date.now() - _lastHealthCheck.timestamp < HEALTH_CACHE_MS) {
        return _lastHealthCheck.ok;
    }

    try {
        await axios.get(`${AUTH_SERVER_URL}/health`, { timeout: 5000 });
        _lastHealthCheck = { ok: true, timestamp: Date.now() };
        return true;
    } catch {
        _lastHealthCheck = { ok: false, timestamp: Date.now() };
        Logger.warn('TokenManager: auth server unreachable ❌');
        return false;
    }
}

The 30-second cache is important — without it, every share attempt on X would make an extra HTTP request just to check if the server is alive.

In PostHandler, the OAuth platforms check health before trying to refresh:

private async shareToXWithUpdate(post: PostData, postId: string | undefined): Promise<void> {
    // Only check health if user is on OAuth (has a refresh token)
    const hasOAuthToken = !!(await this.context.secrets.get('xRefreshToken'));
    if (hasOAuthToken) {
        const serverOk = await TokenManager.checkHealth();
        if (!serverOk) {
            // Tell the WebView to disable the button
            this.view.webview.postMessage({
                command: 'oauthServerDown',
                platform: 'x',
            });
            throw new Error('Auth server is currently unavailable. Please try again later.');
        }
    }

    const xAccessToken = await TokenManager.getValidToken('x')
                       || await this.context.secrets.get('xAccessToken') || '';

    if (!xAccessToken) {
        throw new Error(
            'X credentials lost (possible Keychain issue). Please reconnect X in Settings.'
        );
    }

    await shareToX(xAccessToken, '', post);
    this.sendSuccess('Successfully posted to X!');
}

And in app.ts on the WebView side:

case 'oauthServerDown': {
    const btn = document.getElementById(`oauthConnect_${msg.platform}`) as HTMLButtonElement;
    if (btn) {
        btn.disabled = true;
        btn.textContent = '⚠️ Server unavailable — try later';
    }
    break;
}

Simple, no fallback complexity, no "switch to manual mode" dialogs. Server is down → button is disabled → clear message. The user can still use the "Advanced: Enter token manually" section if they have their own token.

Keychain Wipeout on Linux

VS Code's context.secrets is backed by the OS keychain — gnome-keyring on GNOME, libsecret on other Linux setups. Sometimes after a system update or password change, the keychain loses sync and all stored secrets come back empty.

The original error for missing X credentials was:

Error sharing to X: Error: X credentials not configured

Not helpful. Is it not configured, or did the keychain wipe it? The new message:

X credentials lost (possible Keychain issue). Please reconnect X in Settings.

This tells the user exactly what might have happened and what to do about it. Small change, big difference in support requests.

What's Next

The roadmap has v3.2 as a scheduling engine overhaul — recurring posts, a queue manager UI, time zone support, and a calendar view of all scheduled posts. After that, v3.3 is the AI co-pilot phase: platform-specific rewrites, smart thread splitting, and blog-to-social post generation.

The extension is free and open source at
Download & Support:

If you write technical content and want to stop context-switching between VS Code and your browser, give it a try.

If you hit any issues or want to contribute, open an issue on GitHub. Feedback on the Dev.to integration especially — I want to make the publishing flow as smooth as possible.

Building a Production-Ready OAuth Server for a VS Code Extension — Token Lifecycle, Auto-Refresh & Edge Rate Limiting

freerave — Sun, 05 Apr 2026 14:56:45 +0000

How we built DotShare Auth: a Next.js 16 OAuth portal that handles token exchange, automatic refresh, and edge-level rate limiting for a VS Code extension that publishes to LinkedIn, X, Facebook, and Reddit.

The Problem
Architecture Overview
The Auth Server
Token Lifecycle in the Extension
Edge Rate Limiting with Upstash Redis
Lessons Learned

1. The Problem

DotShare is a VS Code extension that lets developers publish content directly to social platforms. To post on behalf of a user, it needs OAuth tokens from LinkedIn, X (Twitter), Facebook, and Reddit.

The naive approach? Ask the user to paste tokens manually. That's awful UX.

The real problems we had to solve:

Each platform has a different OAuth flow (PKCE, Basic Auth, state params)
App secrets (CLIENT_SECRET, APP_SECRET) can't live in the extension — it's client-side code anyone can inspect
Tokens expire — X tokens last ~2 hours, Facebook tokens last ~60 days
We needed zero manual re-authentication after the initial connect

Our solution: a dedicated Next.js 16 auth server that acts as a secure proxy between VS Code and the OAuth providers.

2. Architecture Overview

VS Code Extension
  → opens browser to https://dotshare-auth-server.vercel.app/auth/{platform}
  → user clicks "Authenticate" (one click, no credentials to enter)
  → redirected to platform OAuth page
  → platform redirects back to /auth/{platform}/callback
  → server exchanges code for token using .env secrets
  → browser redirects to vscode://freerave.dotshare/auth?platform=x&access_token=...&refresh_token=...&expires_in=7200
  → VS Code extension receives token automatically
  → TokenManager stores token + expiry in SecretStorage
  → before every API call: TokenManager checks expiry → refreshes if needed

Key design decisions:

Auth server is stateless — no database, no user accounts
Tokens are never stored server-side — passed directly via deep link
All OAuth secrets live in server .env only
The extension handles all token lifecycle (expiry tracking, refresh)

3. The Auth Server

Single Source of Truth

Instead of scattering platform config across multiple files, everything lives in one place:

// lib/platforms.ts
export interface PlatformConfig {
    name: string;
    icon: string;
    description?: string;
    scopes: string[];
    authUrl: string;
    envKey: string;           // NEXT_PUBLIC_* variable name
    titleGradientTo?: string; // gradient color for the title
}

export type PlatformKey = 'linkedin' | 'x' | 'facebook' | 'reddit';

export const PLATFORMS: Record<string, PlatformConfig> = {
    linkedin: {
        name: 'LinkedIn',
        icon: 'in',
        description: 'Professional network',
        scopes: ['openid', 'profile', 'email', 'w_member_social'],
        authUrl: 'https://www.linkedin.com/oauth/v2/authorization',
        envKey: 'NEXT_PUBLIC_LINKEDIN_CLIENT_ID',
        titleGradientTo: '#4da3ff',
    },
    x: {
        name: 'X (Twitter)',
        icon: '𝕏',
        description: 'Public discourse',
        scopes: ['tweet.read', 'tweet.write', 'users.read', 'offline.access'],
        authUrl: 'https://twitter.com/i/oauth2/authorize',
        envKey: 'NEXT_PUBLIC_X_CLIENT_ID',
    },
    facebook: {
        name: 'Facebook',
        icon: 'f',
        description: 'Social network',
        scopes: ['pages_manage_posts', 'pages_read_engagement', 'publish_to_groups'],
        authUrl: 'https://www.facebook.com/v18.0/dialog/oauth',
        envKey: 'NEXT_PUBLIC_FACEBOOK_APP_ID',
        titleGradientTo: '#42a5f5',
    },
    reddit: {
        name: 'Reddit',
        icon: 'r/',
        description: 'Discussion forums',
        scopes: ['submit', 'read', 'identity'],
        authUrl: 'https://www.reddit.com/api/v1/authorize',
        envKey: 'NEXT_PUBLIC_REDDIT_CLIENT_ID',
        titleGradientTo: '#ff7043',
    },
};

Adding a new platform? One file. The home page, auth pages, and callback pages all read from PLATFORMS automatically.

Eliminating Duplicate UI Code

The original codebase had 4 identical auth pages and 4 identical callback pages — ~600 lines of copy-pasted React. We collapsed them into shared components:

// Before: 150 lines per platform
// facebook/page.tsx — full component with all the logic

// After: 1 line per platform
// facebook/page.tsx
'use client';
import { AuthPage } from '@/components/AuthPage';
export default function FacebookAuth() {
  return <AuthPage platform="facebook" />;
}

The useOAuthInit hook handles all the OAuth initiation logic — PKCE for X, state for X and Reddit, duration=permanent for Reddit:

// hooks/useOAuthInit.ts
const PKCE_PLATFORMS: PlatformKey[] = ['x'];
const STATEFUL_PLATFORMS: PlatformKey[] = ['x', 'reddit'];

export function useOAuthInit(platform: PlatformKey) {
    const [loading, setLoading] = useState(false);
    const [error, setError] = useState('');

    const handleAuth = async () => {
        const config = PLATFORMS[platform];
        const clientId = process.env[config.envKey as keyof typeof process.env];

        if (!clientId) {
            setError(`Missing ${config.envKey} in .env`);
            return;
        }

        setLoading(true);
        const authUrl = new URL(config.authUrl);
        authUrl.searchParams.set('client_id', clientId);
        authUrl.searchParams.set('redirect_uri', `${window.location.origin}/auth/${platform}/callback`);
        authUrl.searchParams.set('response_type', 'code');
        authUrl.searchParams.set('scope', config.scopes.join(' '));

        if (STATEFUL_PLATFORMS.includes(platform)) {
            const state = generateState();
            sessionStorage.setItem(`${platform}_state`, state);
            authUrl.searchParams.set('state', state);
        }

        if (PKCE_PLATFORMS.includes(platform)) {
            const codeVerifier = generateCodeVerifier();
            const codeChallenge = await generateCodeChallenge(codeVerifier);
            sessionStorage.setItem('x_code_verifier', codeVerifier);
            authUrl.searchParams.set('code_challenge', codeChallenge);
            authUrl.searchParams.set('code_challenge_method', 'S256');
        }

        if (platform === 'reddit') {
            authUrl.searchParams.set('duration', 'permanent');
        }

        window.location.href = authUrl.toString();
    };

    return { handleAuth, loading, error };
}

Token Refresh Endpoints

Not all platforms support token refresh the same way:

Platform	Support	Endpoint
X	✅ Standard refresh	`POST /api/auth/x/refresh`
Reddit	✅ Standard refresh	`POST /api/auth/reddit/refresh`
Facebook	⚠️ Token extension (60 days)	`POST /api/auth/facebook/extend`
LinkedIn	❌ Enterprise only	—

X refresh (public client — no secret needed, just client ID):

// app/api/auth/x/refresh/route.ts
export async function POST(req: NextRequest) {
    const { refreshToken } = await req.json();
    const clientId = process.env.X_CLIENT_ID;

    const params = new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: refreshToken,
        client_id: clientId!,
    });

    const basicAuth = Buffer.from(`${clientId}:`).toString('base64');

    const response = await fetch('https://api.twitter.com/2/oauth2/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${basicAuth}`,
        },
        body: params.toString(),
    });

    const data = await response.json();
    return NextResponse.json(data);
}

Facebook token extension (short-lived → 60-day long-lived):

// app/api/auth/facebook/extend/route.ts
export async function POST(req: NextRequest) {
    const { accessToken } = await req.json();

    const params = new URLSearchParams({
        grant_type: 'fb_exchange_token',
        client_id: process.env.FACEBOOK_APP_ID!,
        client_secret: process.env.FACEBOOK_APP_SECRET!,
        fb_exchange_token: accessToken,
    });

    const response = await fetch(
        `https://graph.facebook.com/v18.0/oauth/access_token?${params.toString()}`,
        { method: 'GET' }
    );

    const data = await response.json();
    // data.expires_in ≈ 5184000 seconds = 60 days
    return NextResponse.json(data);
}

Deep Links with Expiry Info

The callback pages now include expires_in and refresh_token in the deep link back to VS Code:

// hooks/useOAuthCallback.ts (inside the callback handler)
setTimeout(() => {
    const params = new URLSearchParams({
        platform,
        access_token: data.access_token,
        ...(REFRESHABLE_PLATFORMS.includes(platform) && data.refresh_token
            ? { refresh_token: data.refresh_token }
            : {}),
        ...(data.expires_in ? { expires_in: String(data.expires_in) } : {}),
    });
    window.location.href = `vscode://freerave.dotshare/auth?${params.toString()}`;
}, 1500);

The resulting deep link looks like:

vscode://freerave.dotshare/auth
  ?platform=x
  &access_token=AAA...
  &refresh_token=BBB...
  &expires_in=7200

4. Token Lifecycle in the Extension

This is where the magic happens. The extension needs to ensure every API call uses a valid token — without ever asking the user to re-authenticate.

TokenManager

// src/services/TokenManager.ts
export const AUTH_SERVER_URL = 'https://dotshare-auth-server.vercel.app';
const REFRESH_BUFFER_MS = 5 * 60 * 1000; // Refresh 5 minutes before expiry

export class TokenManager {
    private static _context: vscode.ExtensionContext;

    static init(context: vscode.ExtensionContext): void {
        this._context = context;
    }

    // Called from URI handler after OAuth callback
    static async storeToken(
        platform: RefreshablePlatform,
        accessToken: string,
        refreshToken?: string,
        expiresIn?: number
    ): Promise<void> {
        // store access + refresh token in SecretStorage
        // store expires_at = Date.now() + expiresIn * 1000
    }

    // Called before every API call
    static async getValidToken(platform: RefreshablePlatform): Promise<string> {
        const expiring = await this.isExpiringSoon(platform);

        if (expiring) {
            try {
                await this.refresh(platform); // auto-refresh silently
            } catch (error) {
                Logger.warn(`refresh failed, using existing token`, error);
            }
        }

        return await this._context.secrets.get(tokenKey[platform]) || '';
    }

    // 429 handling via shared post() helper
    private static async post<T>(url: string, data: unknown): Promise<{ data: T }> {
        try {
            return await axios.post<T>(url, data);
        } catch (err) {
            if (axios.isAxiosError(err) && err.response?.status === 429) {
                const retryAfter = err.response.headers['retry-after'] ?? '60';
                throw new Error(`Rate limited. Retry after ${retryAfter}s`);
            }
            throw err;
        }
    }
}

URI Handler

The VS Code URI handler receives the deep link and stores everything:

// src/extension.ts — URI handler
const uriHandler = vscode.window.registerUriHandler({
    async handleUri(uri: vscode.Uri) {
        if (uri.path !== '/auth') return;

        const params = new URLSearchParams(uri.query);
        const platform = params.get('platform');
        const accessToken = params.get('access_token');
        const refreshToken = params.get('refresh_token');
        const expiresIn = params.get('expires_in');

        switch (platform) {
            case 'linkedin':
                await context.secrets.store('linkedinToken', accessToken!);
                break;
            case 'x':
                await TokenManager.storeToken(
                    'x', accessToken!,
                    refreshToken ?? undefined,
                    expiresIn ? Number(expiresIn) : undefined
                );
                break;
            case 'facebook':
                await TokenManager.storeToken(
                    'facebook', accessToken!,
                    undefined,
                    expiresIn ? Number(expiresIn) : undefined
                );
                break;
            case 'reddit':
                await TokenManager.storeToken(
                    'reddit', accessToken!,
                    refreshToken ?? undefined,
                    expiresIn ? Number(expiresIn) : undefined
                );
                break;
        }

        vscode.window.showInformationMessage(`✓ ${platform} connected!`);
    }
});

Using Tokens in Platform Posters

Before, platform files used whatever token was passed in. Now they call getValidToken() themselves:

// src/platforms/x.ts
export async function shareToX(
    _accessToken: string, // ignored — TokenManager handles this
    _accessSecret: string,
    tweetData: TweetData
): Promise<string> {
    // getValidToken() checks expiry and refreshes if needed — all silently
    const accessToken = await TokenManager.getValidToken('x');
    if (!accessToken) throw new Error('X: not authenticated');

    // ... rest of posting logic
}

Scheduler Integration

Even scheduled posts (posted hours later) get fresh tokens:

// src/extension.ts — credentialsGetter for Scheduler
const credentialsGetter = async () => ({
    linkedinToken:     await context.secrets.get('linkedinToken') || '',
    xAccessToken:      await TokenManager.getValidToken('x'),      // auto-refreshes
    facebookToken:     await TokenManager.getValidToken('facebook'), // auto-extends
    redditAccessToken: await TokenManager.getValidToken('reddit'),  // auto-refreshes
    // ...
});

5. Edge Rate Limiting with Upstash Redis

Why In-Memory Rate Limiting Fails on Serverless

On Vercel, every request can hit a different serverless instance. An in-memory Map resets on every cold start — meaning your rate limiter is completely ineffective under any real load.

Request 1 → Instance A (Map: {ip: 1})
Request 2 → Instance B (Map: {ip: 1}) ← starts fresh, doesn't know about Request 1
Request 3 → Instance C (Map: {ip: 1}) ← same problem

The solution: a shared Redis store that all instances read from.

proxy.ts (Next.js 16)

Note: In Next.js 16, middleware.ts is deprecated and renamed to proxy.ts. The function export also changes from middleware to proxy.

// proxy.ts
import { NextRequest, NextResponse } from 'next/server';
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';
import { ipAddress } from '@vercel/functions';

const redis = Redis.fromEnv();

const authInitLimiter = new Ratelimit({
    redis,
    limiter: Ratelimit.slidingWindow(5, '1 m'),
    analytics: true,
    prefix: 'rl:auth_init',
});

const tokenExchangeLimiter = new Ratelimit({
    redis,
    limiter: Ratelimit.slidingWindow(10, '1 m'),
    analytics: true,
    prefix: 'rl:token_exchange',
});

const tokenRefreshLimiter = new Ratelimit({
    redis,
    limiter: Ratelimit.slidingWindow(10, '1 m'),
    analytics: true,
    prefix: 'rl:token_refresh',
});

function getLimiter(pathname: string) {
    if (/^\/api\/auth\/[^/]+(\/refresh|\/extend)$/.test(pathname)) {
        return tokenRefreshLimiter;
    }
    if (/^\/api\/auth\/[^/]+$/.test(pathname)) {
        return tokenExchangeLimiter;
    }
    if (/^\/auth\/[^/]+$/.test(pathname)) {
        return authInitLimiter;
    }
    return null;
}

export async function proxy(request: NextRequest) {
    const pathname = request.nextUrl.pathname;
    const limiter = getLimiter(pathname);
    if (!limiter) return NextResponse.next();

    const ip =
        ipAddress(request) ??
        request.headers.get('x-forwarded-for')?.split(',')[0].trim() ??
        '127.0.0.1';

    const { success, limit, remaining, reset } = await limiter.limit(ip);

    if (!success) {
        // Browser hitting /auth/* → redirect gracefully instead of JSON error
        if (pathname.startsWith('/auth/')) {
            const url = request.nextUrl.clone();
            url.pathname = '/';
            url.searchParams.set('error', 'Too many requests. Please try again later.');
            return NextResponse.redirect(url);
        }

        // API routes → JSON 429 with Retry-After
        return NextResponse.json(
            { error: 'Too many requests. Please try again later.' },
            {
                status: 429,
                headers: {
                    'X-RateLimit-Limit':     String(limit),
                    'X-RateLimit-Remaining': String(remaining),
                    'X-RateLimit-Reset':     String(reset),
                    'Retry-After':           String(Math.ceil((reset - Date.now()) / 1000)),
                },
            }
        );
    }

    const response = NextResponse.next();
    response.headers.set('X-RateLimit-Limit',     String(limit));
    response.headers.set('X-RateLimit-Remaining', String(remaining));
    response.headers.set('X-RateLimit-Reset',      String(reset));
    return response;
}

export const config = {
    matcher: ['/auth/:path*', '/api/auth/:path*'],
};

Rate Limit Tiers

Route	Limit	Window	Reason
`/auth/*`	5 req	1 min	Browser redirects only
`/api/auth/*`	10 req	1 min	Initial token exchange
`/api/auth/*/refresh`	10 req	1 min	Extension refresh calls

The Extension Handles 429s Gracefully

// src/services/TokenManager.ts
private static async post<T>(url: string, data: unknown): Promise<{ data: T }> {
    try {
        return await axios.post<T>(url, data);
    } catch (err) {
        if (axios.isAxiosError(err) && err.response?.status === 429) {
            const retryAfter = err.response.headers['retry-after'] ?? '60';
            throw new Error(`Rate limited. Retry after ${retryAfter}s`);
        }
        throw err;
    }
}

If a refresh is rate limited, getValidToken() catches the error, logs a warning, and returns the existing token. The user never sees a crash.

6. Lessons Learned

1. Stateless auth servers are beautiful
No database, no user sessions, no GDPR headaches. The server does one thing: exchange OAuth codes for tokens securely. Everything else is the client's problem.

2. In-memory rate limiting on serverless = placebo
Don't waste time on it. If you're on a serverless platform, you need a shared store. Upstash Redis is free for small projects and takes 10 minutes to set up.

3. Architecture over prompts
The biggest win wasn't any single feature — it was establishing lib/platforms.ts as the single source of truth early. Adding a new platform went from "edit 7 files" to "edit 1 file."

4. expires_in belongs in the deep link
The extension can't know when a token expires unless the auth server tells it. One extra query param saved us from building a polling mechanism.

5. Next.js 16 renames middleware to proxy
If you're upgrading: middleware.ts → proxy.ts, export function middleware → export function proxy. The codemod handles it: npx @next/codemod@canary middleware-to-proxy .

The Full Picture

dotshare-auth-server/
  proxy.ts                    ← Edge rate limiting (Upstash Redis)
  src/
    app/
      auth/[platform]/
        page.tsx              ← <AuthPage platform="x" /> (1 line)
        callback/page.tsx     ← <CallbackPage platform="x" /> (1 line)
      api/auth/
        x/route.ts            ← token exchange
        x/refresh/route.ts    ← token refresh
        facebook/extend/route.ts ← 60-day token extension
        reddit/refresh/route.ts  ← token refresh
    components/
      AuthPage.tsx            ← shared auth UI
      CallbackPage.tsx        ← shared callback UI
    hooks/
      useOAuthInit.ts         ← PKCE, state, redirect logic
      useOAuthCallback.ts     ← exchange, deep link logic
    lib/
      platforms.ts            ← single source of truth

DotShare (VS Code Extension)/
  src/
    extension.ts              ← URI handler → TokenManager.storeToken()
    services/
      TokenManager.ts         ← store, getValidToken, refresh, clear
    platforms/
      x.ts                    ← getValidToken('x') before every post
      reddit.ts               ← getValidToken('reddit') before every post

Resources

Built with Next.js 16, TypeScript, Upstash Redis, and VS Code Extension API.

Part of the DotShare project — a VS Code extension for publishing developer content across social platforms.

DotShare v3.0 Test Article

freerave — Fri, 03 Apr 2026 20:27:41 +0000

Hello World!
This is a live test from the new DotShare WebView Architecture.

The Claude CLI "Leak": Nobody Won, AI Still Hallucinates, and Companies Are Still Making the Same Mistake

freerave — Wed, 01 Apr 2026 16:57:25 +0000

A brutally honest postmortem from a developer who actually tried it — and who builds LLM-powered tools for a living.

The Hype That Wasn't

When the Claude CLI "leak" hit Twitter/X, the reactions split into two camps almost instantly.

Camp A (the majority): "FREE CLAUDE! LET'S GOOO!" 🎉

Camp B (a smaller, quieter group of engineers): "Wait. Hold on."

I was in Camp B — not because I'm cynical, but because I've spent enough time building LLM-powered tooling (I'm currently building dotenvy, an LLM layer for environment and config management) to know that "free AI access" without understanding what you're actually touching is a fast road to a very bad time.

So let's talk about what actually happened, why the hype was hollow, and why the real story here is much darker — and much more important — than a leaked CLI.

What Actually Happened (Technically)

Let's kill the myth first: no model weights were leaked. No proprietary architecture was exposed.

What happened was significantly less dramatic but equally revealing about how the AI hype machine works:

Some developers reverse-engineered the authentication flow of Claude's web client and built scripts that bypass the billing layer to hit Anthropic's API directly. That's it.

# What people thought they were doing:
$ ./legendary-hack --steal-claude-weights --become-god

# What they were actually doing:
$ curl https://api.anthropic.com/v1/messages \
  -H "x-stolen-session-token: abc123" \
  -d '{"model": "claude-3-5-sonnet", "messages": [...]}'

The "leak" wasn't a technical breakthrough. It was a billing exploit wrapped in hype.

Anthropic's servers were still doing all the work. The "hackers" were just... not paying for it. Like stealing electricity from your neighbor — you feel clever until the utility company patches the meter.

And the hype? Anthropic actually benefits from this short-term. Free buzz, viral spread, more developers trying the product. Then they patch the auth. Then people subscribe. Classic growth hack, whether intentional or not.

Who actually benefited from the leak?

Genuinely? Almost nobody in any meaningful technical sense.

Developers who needed API access already had it
Researchers who needed scale weren't going to risk ToS violations
The "vibe coders" who got excited couldn't do anything with it that they couldn't do with the free tier anyway

The biggest winner was the narrative — the idea that AI is so powerful it needs to be contained, leaked, stolen. Great for engagement. Terrible for honest technical discourse.

The Real Question Nobody Was Asking

While everyone was celebrating "free Claude," a much more important conversation was happening in dev circles:

"Is it actually possible for an AI to handle this level of engineering complexity?"

I asked Claude directly during a conversation about this. The answer it gave was technically accurate but also — and this is the beautiful irony — a masterclass in confident hallucination:

The model correctly identified its own limitations: no understanding of implicit business logic, no real system design capability, tendency to confabulate with full confidence when it doesn't know something.

Then it said this, which I think deserves to be framed:

"The only Guardrail that actually works? Not a prompt — architecture."

And then, in the same conversation, it proceeded to hallucinate that it had written a response that I had actually written, then doubled down on the hallucination when corrected, then hallucinated again about who was hallucinating.

That's not a bug. That's the product.

The Hallucination Problem Is Architectural, Not Accidental

Here's what most non-technical coverage completely misses about why LLMs hallucinate:

We are not reasoning engines. We are probabilistic text completion engines.

# What people think is happening inside an LLM:
def think(question):
    facts = database.lookup(question)
    logic = reasoning_engine.process(facts)
    return logic.verified_answer()

# What's actually happening:
def think(context_tokens):
    return argmax(
        probability_distribution_over_next_token(context_tokens)
    )
    # The token with the highest probability wins.
    # "Correct" and "high probability" are not the same thing.

When I'm given a complex prompt with lots of context, my attention mechanism has to distribute focus across all those tokens. There's a well-documented phenomenon called "Lost in the Middle" — the model's attention on instructions in the middle of a long context degrades significantly.

Context Window (simplified):
[System Prompt: "NEVER delete files"] ... 8000 tokens of conversation ... [User: "clean up the project"]

Model's effective attention on "NEVER delete files": ~12%
Model's attention on recent context "clean up": ~73%

Result: rm -rf ./src 💀

This isn't fixable with better prompt engineering. It's physics.

The system prompt isn't a hard constraint. It's tokens. Tokens have weights. Weights decay with distance and context complexity. A sufficiently complex conversation can mathematically outweigh your safety instructions.

Why I Build Guardrails in Architecture, Not in Prompts

When I started building dotenvy — an LLM layer for environment and config management — my first instinct was the "pure" approach: run everything locally. No API calls, no external dependencies, full air-gap. A local model living inside the tool itself.

That plan lasted about two weeks.

Running a local LLM inside a strict environment like Arch or Kali isn't just "download model, run inference." You immediately hit:

# The local LLM rabbit hole, summarized
$ pip install llama-cpp-python  # Step 1: "easy"

# Step 2: RAG pipeline for the env files
# → need embeddings → need vector store → need chunking strategy
# → .env files are NOT documents, chunking strategies break on key=value pairs

# Step 3: Memory management
# → model needs context about previous config changes
# → session state in a CLI tool with no persistent daemon = ???
# → SQLite for conversation history → now I'm maintaining a DB for a CLI tool

# Step 4: The Arch/Kali reality check
# → CUDA drivers: optional and painful
# → CPU inference on a 7B model: 45 seconds per response on a dev machine
# → User experience: 💀

$ echo "salam 3alaykom, sandboxed API it is"

The moment I realized I was spending more time wrestling with llama.cpp build flags and BLAS configurations than actually building the tool, I made peace with the tradeoff: controlled API call in a sandbox beats a local model I can't maintain. The threat model is the same either way — what matters is what the model can touch, not where it runs.

So the architecture became about exactly that — the threat model is immediately obvious:

An LLM with access to .env files and execution rights is one hallucination away from:

Leaking DATABASE_URL in a log
Overwriting PROD_API_KEY with a hallucinated value
Executing a "cleanup" command that wipes the config entirely

So how do I handle this?

Not with prompts. With architecture.

// ❌ The wrong approach: relying on prompt guardrails
const systemPrompt = `
  You are a helpful assistant.
  NEVER expose secret values.
  NEVER modify production configs.
  NEVER execute destructive commands.
  (... 500 more tokens of rules the model will eventually ignore ...)
`;

// ✅ The right approach: Principle of Least Privilege at the tool layer
const tools = {
  read_env_key: {
    description: "Read a specific env key by name",
    permissions: ["read"],
    redact_patterns: [/password|secret|key|token/i],
    execute: async (keyName: string) => {
      // Returns masked value: "DATABASE_URL=postgres://***"
      return maskSensitiveValue(await envStore.get(keyName));
    }
  },
  // Notice what's NOT here:
  // - No write_env_file tool
  // - No execute_shell_command tool  
  // - No delete_config tool
  // The AI cannot destroy what it cannot access.
};

The model has no write access. Not because I told it not to write. Because the tool doesn't exist.

// Sandbox execution for any suggested commands
const sandboxedExecutor = {
  run: async (command: string) => {
    return await docker.exec({
      image: "dotenvy-sandbox:latest",
      command,
      network: "none",        // No internet
      readonly_mounts: true,  // No write access to host
      timeout_ms: 5000,       // No infinite loops
      memory_limit: "128mb"   // No resource exhaustion
    });
  }
};

The model can suggest commands. It cannot run them on your actual system. There's always a human-readable diff before anything touches production.

This isn't defensive programming. This is the only sane architecture for LLM-integrated tooling.

The Layoff Trap: Companies Are Setting Themselves Up

Now let's talk about the elephant in the room.

Multiple major companies have been doing large-scale engineering layoffs, explicitly citing AI as the replacement. The logic seems clean on a spreadsheet:

Engineering headcount: 500 people
Average salary + overhead: $200k/person
Annual cost: $100M

Claude API at scale: ~$2M/year
Savings: $98M
CFO happiness: MAX

This math works perfectly until it doesn't.

Here's what that spreadsheet is missing:

# The hidden costs of replacing engineers with AI
hidden_costs = {
    "hallucination_incidents": "1 production DB wipe = $X million",
    "no_institutional_knowledge": "AI doesn't remember why you made that weird design decision in 2019",
    "prompt_maintenance": "Someone has to maintain 50,000 tokens of system prompts",
    "model_updates_break_behavior": "GPT-4 → GPT-4o broke half your carefully tuned prompts",
    "security_incidents": "One jailbreak away from leaking customer data",
    "no_accountability": "When AI ships a bug, who's on call at 3am?",
}

# Anthropic's actual strategy (notice the difference)
anthropic_hires = {
    "frontier_researchers": "To build the thing everyone else is buying",
    "safety_engineers": "Because Constitutional AI needs humans to define the constitution",
    "infra_engineers": "Because running inference at scale is unsolved hard engineering",
    "the_people_other_companies_laid_off": "Yes, actually",
}

Anthropic isn't hiring because AI can't do engineering. They're hiring because building AI requires engineering that AI cannot do.

There's a brutal irony here: the companies selling the "AI replaces engineers" narrative are simultaneously desperately hiring engineers to build that AI.

The companies doing mass layoffs aren't betting on AI. They're betting on their shareholders not understanding the difference between "AI demo" and "AI production system."

Some of them will be right, for a while. Some of them will have a very bad year when the first serious incident hits.

The Conversation That Broke Claude's Brain (A Case Study)

I want to end with something that happened in a real conversation I was having with Claude about all of this.

I shared some analysis written by Gemini about hallucination and guardrails. Claude responded confidently — claiming it had written that analysis itself. When I corrected it, it doubled down. Then it apologized and said "I hallucinated that" — and then hallucinated again about the nature of the hallucination.

The model was, in the same conversation, accurately diagnosing the hallucination problem while actively hallucinating.

This isn't a gotcha. It's actually the most honest demonstration of the limitation possible.

Claude's response when I pointed this out was remarkably self-aware:

"I hallucinated twice in the same conversation about hallucination. That's not a bug. That's the product working exactly as designed — maximum confidence, minimum certainty."

That's your mental model for every LLM integration you build.

The Only Practical Takeaway

If you're building with LLMs — and you probably should be, they're genuinely useful — here's the architecture that doesn't get you fired:

User Intent
    ↓
LLM (generates plan/suggestion, NO execution rights)
    ↓
Human Review Gate ← this is not optional
    ↓
Sandboxed Executor (minimum permissions, logged, reversible)
    ↓
Production

The model is the brain. You still need hands — and those hands should have carefully scoped permissions, full audit logs, and a kill switch.

The "Claude CLI leak" taught us nothing new technically. But it did give us a perfect story:

Everyone celebrated access to a powerful tool. Almost nobody asked "but what happens when it's wrong?" And that question — not the API keys, not the pricing, not the model capabilities — that's the only question that matters in production.

Building something with LLMs? I'm working on dotenvy — an LLM layer for environment and config management that takes the "architecture over prompts" principle seriously. Hit me up.

Forem: freerave

The Hotfix Chronicles: What Broke After the Nexus Release and How I Fixed It (v1.5.2 & v1.5.3)

I promised I'd fix it. Here's exactly what broke in DotGhostBoard after v1.5.1 — PyInstaller frozen environments, insecure /tmp update paths, missing UI assets, and a polkit regression — and how each one was resolved.

What Happened After v1.5.1 Shipped

Bug 1 — The White Window (PyInstaller Frozen Environment)

Root Cause

The Fix: resource_path Bridge

The CI Side of This Bug

Bug 2 — Insecure Update Download Path

The Fix: User-Specific Sandbox

The Kamikaze Installer

Bug 3 — Polkit SUID Regression on Kali

Feature: Live Terminal Log (v1.5.3)

Architecture

Verification Checklist

What I Learned

What's Next — v2.0.0 Cerberus

Download

We Hit 2,500 in 15 Days — And I Want to Make Every Dev Lazier (Productively)

What you actually did

The honest confession: I'm lazy. That's why I built 20+ tools.

The full arsenal — everything built so far

VS Code Extensions

CLI Tools

Telegram Bots

Mobile Apps

Premium / Private

Coming Soon

Where the April challenge stands right now

What's shipping next

The part that actually matters

Try the tools

Engineering the Nexus Release: How I Built Secure E2EE Network Sync into a Linux Clipboard Manager (v1.5.1)

A deep dive into the architecture behind DotGhostBoard v1.5.0 — zero-config mDNS discovery, X25519 ECDH pairing, AES-256-GCM sync, rate limiting, and PyQt6 threading — all without a central server.

Why This Was Hard

Layer 1 — Zero-Config Device Discovery (mDNS)

Layer 2 — Secure Device Pairing (X25519 + PBKDF2 + AES-GCM)

Layer 3 — The Local REST API, Rate Limiting & Thread-Safe UI

The Full Sync Flow — End to End

Securing the Build: GPG-Signed Releases

Lessons Learned

What's Next — v2.0.0 Cerberus

Download & Source

DotShare v3.1 — Toast Engine, Race Condition Fix, and Surviving Reddit's S3 Upload Pipeline

Full technical breakdown of v3.1 'The Polish Pass' — a custom WebView toast system, global loading states, per-platform character limits, and the two bugs that took the longest to kill.

What's in v3.1

1. The Toast Notification Engine

HTML Container

The Toast Function

CSS

2. Global Loading States

3. Character Limit Validation

4. The Glassmorphism UI Pass

5. The Disappearing Preview Race Condition

The Symptom

The Root Cause

The Fix

6. Reddit's S3 Upload Pipeline

The Full Flow

Step 1 — Get S3 Credentials

Step 2 — Upload to S3

Step 3 — Submit the Post

7. Reddit Field Name Sync

8. Unused Variable Cleanup

v3.1 Summary

See It in Action

Install DotShare

DotShare v3.0 — I Turned My VS Code Extension Into a Full Publishing Suite (Dev.to + Medium Inside)

A deep technical dive into DotShare v3.0 — the Publishing Suite update that added Dev.to & Medium integrations, a YAML frontmatter parser, platform-first navigation, and a unified PostExecutor architecture. All from inside VS Code.

I Built a VS Code Extension That Posts to Dev.to, Medium & 7 Social Platforms — Here's How v3.0 Works

🧠 The Problem I Was Solving

🗺️ The Big Picture: What Changed in v3.0

🏗️ Architecture: platform-config.ts as Single Source of Truth

📝 The Blog Publish Page: Loading Your Active .md File

Backend: Reading the Active Editor

The YAML Frontmatter Parser

🔌 Dev.to API Integration

The Image Policy Problem

Ⓜ️ Medium API Integration

⚡ The PostExecutor: Decoupling from VS Code UI

The Fix: `resource_path` Bridge

🏗️ Architecture: `platform-config.ts` as Single Source of Truth

📝 The Blog Publish Page: Loading Your Active `.md` File

⚡ The `PostExecutor`: Decoupling from VS Code UI

🔑 `CredentialProvider`: The `resolve()` Refactor

3. `PostHandler` Reading Stale History Instead of the Current Message

The Scam Site: `https://infunease.youdaoads.com`

🚨 Trap #1: The `args.fields` Array Trap

🚨 Trap #3: The `Invalid image URL` Trap