DEV Community: Sean Bailey

ArchivioMD: A Deep Dive into the Cryptographic Stack

Sean Bailey — Sat, 28 Feb 2026 03:30:03 +0000

This is an update to my earlier post on ArchivioMD. Since that writeup, the plugin has landed on WordPress.org, gained a full algorithm suite, HMAC integrity mode, RFC 3161 trusted timestamping, and external anchoring to GitHub/GitLab. There's a lot to unpack.

What the plugin actually does

ArchivioMD started as a way to manage meta-documentation files — your security.txt, privacy-policy.md, robots.txt and similar — from inside the WordPress admin. Every document gets a UUID and a checksum, every edit appends to an immutable changelog, and HTML rendering from Markdown is handled automatically.

That's still the core. What's grown significantly is the cryptographic layer on top of it: how hashes are computed, how they're bound to identity, how they're externally verifiable, and how you can timestamp them against a trusted third party. That's what this post is about.

The hash helper: algorithm-agnostic from the start

The entire hashing surface of the plugin runs through a single class, MDSM_Hash_Helper. Every hash — post content, document checksums, anchor records — goes through this one entry point. That was an intentional design choice: swap the algorithm once, and it propagates everywhere.

The algorithm roster

Standard (production-ready):

sha256 — SHA-256, the default
sha512 — SHA-512
sha3-256 — SHA3-256 (Keccak)
sha3-512 — SHA3-512
blake2b — BLAKE2b-512

Experimental (with automatic fallback):

blake3 — BLAKE3-256
shake128 — SHAKE128 with 256-bit output
shake256 — SHAKE256 with 512-bit output

The experimental algorithms come with a graceful degradation chain. If blake3 isn't natively available via a PHP extension, the plugin falls back to BLAKE2b-512, and if that's not available, it falls back to SHA-256. The fallback: true flag in the return array lets callers surface a warning rather than silently emitting a weaker hash than intended.

BLAKE3 in particular required its own implementation class (MDSM_BLAKE3) because PHP doesn't ship it natively. The HMAC construction for BLAKE3 is built manually using the standard H(K XOR opad || H(K XOR ipad || message)) structure, with the pure-PHP Blake3 hasher standing in for the compression function.

The packed string format

All stored hashes use a self-describing format:

Standard:  "sha256:abcdef…"
HMAC:      "hmac-sha256:abcdef…"
Legacy:    "abcdef…"              (treated as bare SHA-256)

The unpack() method handles all three. Legacy bare-hex hashes from before v1.3 verify correctly against hash() without any migration. The format tag in the packed string drives the entire downstream verification path — the global "active algorithm" setting is never consulted when verifying an existing hash.

HMAC Integrity Mode

Standard hash verification answers: has this content changed?

HMAC integrity mode answers: has this content changed, and was the original hash produced by someone with access to the secret key?

How it's configured

The key lives in wp-config.php, never in the database:

define( 'ARCHIVIOMD_HMAC_KEY', 'your-long-random-secret-at-least-32-chars' );

Then you enable the mode in Settings → Cryptographic Verification → HMAC Integrity Mode.

The plugin enforces a minimum key length of 32 characters and surfaces a warning (not an error) if the key is shorter. A missing key when HMAC mode is enabled is a hard error — hash generation is blocked, not silently degraded.

What changes in the hash flow

When HMAC mode is enabled, compute_packed() calls compute_hmac() instead of compute(). The packed string gets the hmac- prefix. Verification calls hash_equals() against a freshly computed HMAC rather than a plain hash.

One important consequence: if you rotate the key constant in wp-config.php, every existing HMAC hash immediately fails verification. The old hashes don't become invalid per se — the hmac-sha256: prefix still tells the verifier what to do — but the key they were signed with is gone. This is by design. Key rotation is a deliberate action that invalidates the previous integrity chain.

The status helper

There's an hmac_status() method that returns a structured array for the admin UI: mode_enabled, key_defined, key_strong, ready, and a notice_level / notice_message pair for surfacing the right admin notice. The four states are: off, enabled-but-no-key, enabled-with-weak-key, and fully active.

Post content verification: deterministic hashing

The MDSM_Archivio_Post class handles WordPress post and page content. The challenge here is determinism: the same logical content must always produce the same hash, regardless of whitespace normalization, line ending differences, or editor artifacts.

The canonicalization pipeline strips the content down to a stable form before hashing. It also binds the hash to the post ID and author ID to prevent hash reuse — you can't take a hash generated for post 42 and pass it off as valid for post 99.

The result is stored in post meta. On every save, if auto-generate is enabled, the hash is recomputed and logged to the audit table (wp_archivio_post_audit). The audit table gained a post_type column in v1.5.9, and the schema migration runs inline on construction if the column is missing.

Verification badge

Three badge states are possible:

✓ Verified (green) — current content hash matches the stored hash
✗ Unverified (red) — content has changed since last hash generation
− Not Signed (gray) — no hash has been generated for this post

Badges can be auto-injected below titles or content, or placed manually with the [hash_verify] shortcode. Visitors can download a verification file containing the hash, algorithm, mode, post metadata, and (if available) RFC 3161 timestamp details.

RFC 3161 Trusted Timestamping

This is the most involved feature in the 1.6.x series. RFC 3161 is the internet standard for cryptographic timestamping — you send a hash to a Time Stamp Authority, they sign it and return a timestamp token (a .tsr file) that proves the hash existed at a specific point in time. The token is signed by the TSA's certificate chain, which anchors it to a trusted third party entirely outside your infrastructure.

Built-in TSA profiles

The plugin ships with four profiles:

Provider	URL	Auth
FreeTSA.org	`https://freetsa.org/tsr`	None (rate-limited)
DigiCert	`http://timestamp.digicert.com`	None
GlobalSign	`http://timestamp.globalsign.com/tsa/r6advanced1`	None
Sectigo	`https://timestamp.sectigo.com`	None (throttle to 15s+)

A custom endpoint option is also available for private TSAs or enterprise deployments.

The timestamping flow

Take the content hash from the anchor record.
If the content algorithm is SHA-256 and the hash is 64 hex characters, use the raw bytes directly as the RFC 3161 MessageImprint. If it's any other algorithm, SHA-256-hash the hex string — this is recorded in the manifest as "method": "sha256_of_hex" so you can reproduce the imprint independently.
Build a DER-encoded TimeStampReq in pure PHP — no external ASN.1 libraries required. The structure follows RFC 3161 §2.4.1: a version integer, a MessageImprint sequence (algorithm OID + hash bytes), a random 64-bit nonce, and certReq TRUE.
POST it to the TSA with Content-Type: application/timestamp-query.
Receive the TimeStampResp, check the PKIStatus integer is 0 or 1, extract the serial and genTime for logging.
Store the .tsr response and the original .tsq request in wp-content/uploads/meta-docs/tsr-timestamps/. A .manifest.json file is written alongside them with everything needed for offline verification:

{
  "content_hash_algorithm": "sha256",
  "content_hash_hex": "abcdef...",
  "tsr_message_imprint": {
    "algorithm": "sha256",
    "method": "direct",
    "note": "TSR message data equals the raw content hash bytes."
  },
  "verification_command": "openssl ts -verify -in file.tsr -queryfile file.tsq -CAfile /etc/ssl/certs/ca-certificates.crt"
}

The .tsr and .tsq files are blocked from direct HTTP access via .htaccess. They're served through an authenticated AJAX download handler instead. The manifest JSON is publicly accessible — it contains no secret data.

Offline verification

Because the .tsr is a standard RFC 3161 token, you can verify it with openssl ts on any machine, independent of the WordPress installation:

openssl ts -verify \
  -in document-20260214-143022.tsr \
  -queryfile document-20260214-143022.tsq \
  -CAfile /etc/ssl/certs/ca-certificates.crt

For FreeTSA you need to download their certificate separately (the cert_url is in the manifest). For DigiCert, GlobalSign, and Sectigo, the root is already in your system trust store.

External Anchoring

Separate from RFC 3161, the plugin can push cryptographic anchor records to GitHub or GitLab repositories. The idea is a distributed, tamper-evident audit trail: even if your WordPress database is compromised, the hashes are already committed to an external repository under a different trust domain.

The anchoring system is provider-agnostic. Every provider implements MDSM_Anchor_Provider_Interface:

interface MDSM_Anchor_Provider_Interface {
    public function push( array $record, array $settings ): array;
    public function test_connection( array $settings ): array;
}

push() returns ['success' => true, 'url' => '...'] or ['success' => false, 'error' => '...', 'retry' => bool, 'rate_limited' => bool]. The RFC 3161 provider implements the same interface, which is how multi-provider anchoring (added in v1.6.4) works — the queue just calls push() on each enabled provider independently.

The queue

Anchor jobs are persisted to wp_options via MDSM_Anchor_Queue. Key properties:

Hard cap at 200 jobs — prevents the options row from growing unbounded on high-volume sites
Exponential backoff: 1 min → 2 → 4 → 8 → 16 minutes, up to 5 retries
Transient-based locking (15-second TTL) to guard against two cron processes running simultaneously and double-processing the same job
Per-provider state tracking (added in v1.6.4) so a failing Git provider doesn't block RFC 3161 jobs in the same queue entry

Multi-provider anchoring

Since v1.6.4, you can run GitHub/GitLab and RFC 3161 simultaneously. Each provider maintains independent retry state. Each writes its own entry to the Anchor Activity Log. If you're building a compliance evidence chain, you get a Git-hosted hash record and a cryptographically timestamped .tsr file for every anchor event.

WP-CLI

As of v1.6.2, several operations are available from the CLI:

# Drain the anchor queue
wp archiviomd process-queue

# Anchor a specific post
wp archiviomd anchor-post --post_id=42

# Verify a post's content hash
wp archiviomd verify --post_id=42

# Prune old anchor log entries
wp archiviomd prune-log

Log retention defaults to 90 days with automatic daily pruning via cron.

Compliance export

Tools → ArchivioMD → Compliance Tools includes a structured JSON export that packages the full evidence chain for a given post or document: post metadata, hash history, anchor log entries, and inlined RFC 3161 TSR manifests. The intent is a self-contained artifact you can hand to an auditor or feed into a SIEM without them needing access to the WordPress installation.

Backward compatibility

One thing I've been deliberate about: every hash format ever emitted by the plugin still verifies correctly against the current codebase.

Bare hex from before v1.3 → treated as sha256 / standard mode
sha256:hex from v1.3 → standard mode
hmac-sha256:hex from v1.4 → HMAC mode

No migration scripts, no format conversion. The packed string carries all the information needed to verify it.

The plugin on WordPress.org

It's live at [wordpress.org/plugins/archiviomd]

1.6.6 will be on GitHub this weekend uploaded to WordPress after some test-drives

Happy to answer questions about any of the implementation details — particularly the ASN.1 builder, the BLAKE3 fallback chain, or the queue concurrency model. Those were the three areas that took the most iteration to get right.

Building a WordPress Plugin for Markdown Docs and AI-Ready Site Files

Sean Bailey — Sun, 08 Feb 2026 06:47:36 +0000

I built this plugin while doing client work, not as a product idea.
The client wanted WordPress because they were comfortable with it and the operational risk was low. That part was fine. The friction appeared when they needed a small set of Markdown documentation files to exist on the backend of the site.

The catch: they were on managed hosting and had no FTP access.
At that point, their realistic options were:

Create and maintain a GitHub repository just to manage a few text files

Convert documentation into WordPress pages and treat them as content
Neither option felt appropriate for what were essentially infrastructure-level documents.

That raised a broader question for me:

Would someone who needs to routinely update documentation for audits, transparency, or compliance really want to manage it via FTP or GitHub if they don’t otherwise need those tools?

Probably not.

The idea: documentation as a first-class CMS concern

The solution I landed on was to treat documentation files as managed artifacts inside the CMS, but still respect how the web expects those files to exist.

The core requirements were:
Edit Markdown files directly in WordPress

Write files to the filesystem where possible

Degrade gracefully when filesystem permissions are limited

Keep the files usable outside of WordPress

File placement strategy
The plugin checks whether the WordPress root is writable:

If root is writable:
Markdown files are placed where they normally live (e.g. /README.md, /llms.txt).

If root is not writable (common on managed hosting):

Files are stored in a central, predictable location that can still be referenced and served.

This avoids hard failures and removes the need for FTP entirely.

From the site administrator’s perspective, they’re just editing documents in the admin panel. Where the file ends up is an implementation detail handled by the plugin.
**
Why Markdown works well here**

Markdown is a good fit for documentation because it’s:
Human-readable
Diff-friendly
Easy to audit

Portable outside WordPress
But raw .md files aren’t ideal for public consumption.

So every Markdown file managed by the plugin automatically generates a corresponding HTML document.
This serves two purposes:
Readability – legal documents and policies are much easier to consume as HTML

Indexability – HTML documents are easier to surface via search engines and internal linking
The Markdown file remains the source of truth. The HTML is a generated artifact.

*Curated document pages
Many sites don’t just have one document. They have several:
Privacy Policy
Terms of Service
Cookie Policy
*
Compliance or disclosure documents
Instead of forcing each document to be a standalone page, the plugin allows site owners to curate a documentation page.

The workflow looks like this:
Create a blank WordPress page (e.g. /docs or /legal)

Point the plugin to that page
Select which Markdown documents to display

Add a short description for each document

The result is a clean, generated page that lists documents with:

Title
Description
Link to the .md file
Link to the HTML-rendered version
This can be done via shortcode or by designating a page in the plugin settings.

Print and PDF support

One thing that comes up more often than people expect: printing documentation.
W
hether for internal audits or external compliance requests, users sometimes need a physical or archived copy. The plugin supports printing and saving rendered documents as PDFs from the front end.

It’s not flashy, but it’s practical.
Expanding beyond Markdown: raw text files that still matter

Toward the end of development, I
started thinking about other plain-text files that are still relevant but often scattered across plugins or manual edits.
robots.txt

Despite its age, robots.txt is still
a meaningful signal source.
It can:

Control crawler inclusion/exclusion
Help remove content from archive sites

Express intent even when it isn’t strictly enforced

The plugin provides clean access to edit and manage robots.txt without needing an SEO plugin.
Sitemaps

Sitemaps are another classic requirement.

Rather than bundling SEO features,
the plugin focuses on sitemap generation as a pure infrastructure concern:

Generate a single sitemap
Or split it into multiple sections for large sites
No keyword tooling, no analytics — just accurate content signaling.
llms.txt

Finally, I added support for llms.txt.

This file isn’t widely adopted yet, but awareness is growing. Conceptually, it’s similar to robots.txt, except it communicates intent to LLMs / AI systems.
Depending on the site owner’s goals, it can be used to:

Request exclusion from training datasets

Or signal that a site should be visited more frequently for accurate representation

It’s not enforceable, but neither was robots.txt at the beginning. Intent signaling still matters.

Why bundle all of this together?

Individually, these features already exist across multiple plugins.
The point wasn’t to replace them — it was to offer a clean, centralized way to manage documentation and signaling files without:

FTP access
GitHub dependencies
Bloated SEO tooling

The plugin treats these files as infrastructure, not marketing assets.
Open source by design

The plugin is fully open source and designed to work within WordPress constraints rather than around them.
It respects:

*Managed hosting limitations
WordPress admin workflows
Filesystem realities
*
If you’re interested, the code is available on GitHub, and feedback or contributions are welcome.
Closing thoughts

This started as a small solution to a repeating client problem, but it reflects a broader pattern:
WordPress sites increasingly need to expose machine-readable documentation, not just human-facing pages.

Markdown, plain-text files, and clear signaling are still part of the web’s foundation — even as platforms evolve.

Sometimes the best tools aren’t flashy. They just remove friction.

Archiviomd