PluginExpress Integration Guide
Automatic Update System for CommFort Plugins
Version 1.0.0 BETA

---

Table of Contents

  1. Overview
  2. Metadata Specification
     2.1 File Requirements
     2.2 Required Fields
     2.3 Optional Fields
  3. Archive Structure and Naming
     3.1 Required Naming Pattern
     3.2 Archive Contents
     3.3 Version Extraction Rules
     3.4 Update Triggers
  4. Changelog Support
  5. Hash Verification
     5.1 What Is Verified
     5.2 Hash File Format
     5.3 Creating Hash Files
     5.4 Verification Behavior
     5.5 Daily Hash Checks as Passive Telemetry
  6. Self-Management Contract
  7. Security Notes
  8. Integration Checklist
  9. Troubleshooting

---


1. Overview

PluginExpress is possibly the first universal plugin for CommFort — works identically
on client and server. It enables zero-touch updates: plugins update themselves without
user intervention.

Key properties:
- Non-invasive: Never modifies .cfplug files while CommFort runs
- Update safety: Changes apply only after shutdown completes successfully
- Format support: ZIP (built-in) and 7z (7za.exe bundled); .rar explicitly rejected
- Passive telemetry: Daily hash checks = free installation statistics for developers
- Integrity checks: Re-downloads plugin if .cfplug is missing or damaged

---

2. Metadata Specification

2.1 File Requirements
Location: Plugins/{PluginName}/.{pluginname}_metadata
Naming:   Must contain "_metadata" (case-insensitive)
Tip:      Prefix with "." to hide from users on Linux/Wine

2.2 Required Fields

PluginName=ExactPluginName
Version=X.Y.Z
URL=https://download.source/path/archive.ext

Constraints:
- PluginName: Must exactly match .cfplug filename (case-sensitive on Linux/Wine)
- Version:    Semantic version X.Y.Z (auto-normalized: 1 → 1.0.0, 1.2 → 1.2.0)
- URL:        Valid HTTPS URL (forum thread OR direct download)

2.3 Optional Fields

HashURL=https://download.source/path/pluginname.cfplug.sha256

HashURL purpose: SHA256 verification of extracted .cfplug file (not archive).
Note: You can point to a forum post — PluginExpress will scan for a 64-character
hex string, but structured hash files are more reliable.

---

3. Archive Structure and Naming

3.1 Required Naming Pattern
{PluginName}_v{MAJOR}.{MINOR}.{PATCH}_{BUILD}.{ext}

Valid examples:
  FortLock_v3.2.0_BETA.zip
  WikiFlow_v0.9_ALPHA.7z
  AssemblyAI_v1.0.0.zip

Invalid examples (ignored):
  plugin.zip              (no version)
  MyPlugin_1.0.zip        (missing _v prefix)
  MyPlugin_v1.0.0.cfplug  (raw binary — not an archive)

3.2 Archive Contents

PluginExpress handles two types of content inside archives:

Required:
  MyPlugin.cfplug         — The plugin binary, copied to Updates/ for batch install

Optional:
  MyPlugin/               — Resource folder (sounds, configs, licenses, etc.)
    complete.wav
    README.txt
    ...

If a folder named exactly {PluginName}/ is found inside the archive, its entire
contents are copied to Plugins/{PluginName}/ immediately during extraction —
before CommFort restarts. This is the recommended way to ship plugin resources.

3.3 Version Extraction Rules
1. Match case-insensitive prefix {PluginName}_v
2. Extract X.Y.Z sequence immediately following _v
3. Normalize missing components: 1 → 1.0.0, 2.3 → 2.3.0

3.4 Update Triggers
- Remote version > local Version field  → Download and install
- Remote version ≤ local Version field  → Skip
- Plugin missing from Plugins/ folder   → Download latest version

---

4. Changelog Support

PluginExpress displays changelogs in its GUI under the Changelog tab.

To provide a changelog, include a plain text file in your plugin's resource folder:

  Plugins/MyPlugin/changelog.txt

The file is read locally — no network request is made. It is displayed as-is,
so plain text with simple formatting works best.

If no changelog.txt is found, the tab shows "(No changelog available)" for that plugin.

---

5. Hash Verification

5.1 What Is Verified
PluginExpress verifies the SHA256 of the extracted .cfplug file, not the archive.
Rationale: Verify what you execute, not the transport wrapper.

5.2 Hash File Format
Accepts any of:
  SHA256: a1b2c3d4e5f67890123456789012345678901234567890123456789012345678
  <code>a1b2c3...hash...890</code>
  Raw 64 hex characters (first match found in file)

5.3 Creating Hash Files

Linux/Mac:
  sha256sum MyPlugin.cfplug > MyPlugin.cfplug.sha256

Windows (PowerShell):
  Get-FileHash MyPlugin.cfplug -Algorithm SHA256 | Select-Object Hash

5.4 Verification Behavior
- Hash match:    ✓ in GUI, "hash verified!" in log
- Hash mismatch: ⚠ in GUI, "hash mismatch (file kept)" — user decides
- No HashURL:    ℹ in GUI, "no hash verification" — proceeds trusting source

5.5 Daily Hash Checks as Passive Telemetry
- Runs once per 24 hours per installed plugin
- Each check = one GET request to your HashURL
- Host HashURL on any service with access counters (Nextcloud, GitHub, etc.)
- Result: Free daily active user statistics, no infrastructure required

User-Agent strings allow you to distinguish traffic types:
  PluginExpress/1.0 [DOWNLOAD]  — version check or update download
  PluginExpress/1.0 [VERIFY]    — daily integrity check

Note: Statistics will be approximate. Users may reinstall, delete files, or run
multiple instances, leading to some inflation.

---

6. Self-Management Contract

PluginExpress behavior:
- Does NOT create metadata files
- DOES update the Version field after successful downloads
- Respects all other fields (URL, HashURL) as read-only

Plugin developer responsibility:
- Create .{pluginname}_metadata on first installation, or bundle it in the archive
- Populate PluginName, Version, URL at minimum
- Optionally populate HashURL for integrity checking
- Optionally bundle changelog.txt to keep user informed

---

7. Security Notes

- HTTPS only: HTTP connections are blocked by default. Users can override in Settings.
- Cloudflare detection: Downloads through Cloudflare-proxied URLs are blocked due to
  MITM concerns (CF-RAY header detection). Host files directly where possible.
- Hash verification is optional but strongly recommended. Without it, PluginExpress
  trusts the download source entirely.
- PluginExpress provides baseline protection only. Always verify metadata URLs before
  shipping to users.

---

8. Integration Checklist

Before release, verify:
- [ ] PluginName= exactly matches .cfplug filename (case-sensitive on Linux/Wine)
- [ ] Archive filename follows {PluginName}_vX.Y.Z_BUILD.ext pattern
- [ ] Version= field matches the archive version
- [ ] HashURL points to SHA256 of .cfplug file (not the archive)
- [ ] changelog.txt placed in Plugins/{PluginName}/ if desired
- [ ] Resource folder inside archive named exactly {PluginName}/ if shipping extras
- [ ] Tested on Windows + Wine/Linux (case sensitivity differs)

---

9. Troubleshooting

Symptom                       | Cause                              | Fix
------------------------------|-------------------------------------|----------------------------------------
Re-downloads every startup    | PluginName ≠ .cfplug filename       | Match exactly (rename or edit metadata)
"No updates found"            | Archive missing _vX.Y.Z_ pattern    | Rename archive to required format
Hash verification fails       | Hash file contains archive hash     | Recalculate hash of .cfplug (not archive)
Resource folder not copied    | Folder named wrong inside archive   | Must be exactly {PluginName}/ 
Plugin not detected           | Metadata file not found             | Check path: Plugins/{Name}/.{name}_metadata

Enable debug logging in Plugins/PluginExpress/config.ini:
  [Debug]
  Debug=1

Check debug.log for detailed operation traces.

---

PluginExpress — Updates that just work. Client and server. Zero effort. (с) 2026.
