Skip to content

Developer docs

Releases and signed updates

Every release is signed on your own computer with an Ed25519 key. DevEntitle checks each upload with your public key, and your product checks the download again before installing. Even someone who took over the update server couldn’t push a fake update.

Also in the app: terminal.deventitle.com/docs/signing · Machine-readable spec: openapi.json (OpenAPI 3.1)

How it works

  1. Once: create a keypair. Paste the public key on your product in DevEntitle (Edit product → Release signing) and build it into your product. Keep the secret key offline.
  2. Each release: build <product>-<version>.zip and sign it. Signing writes a small .json manifest next to the zip.
  3. Upload the zip and the manifest (Releases → Upload release, or from CI). The upload is refused if the hash or the signature doesn’t match.
  4. Publish. Entitled licences get a download link from /api/v1/updates. Your product checks the SHA-256 and signature, then installs.

Releases are optional: you can use DevEntitle for licences only.

The Release Kit

A free, single-file signing tool that needs nothing installed. Both versions make the same keys, manifests and signatures, and neither sends anything anywhere.

The whole workflow
php deventitle-release.php keygen
export DEVENTITLE_SIGNING_KEY="<secret key>"
php deventitle-release.php sign acme-crm-1.2.0.zip     # → acme-crm-1.2.0.json
php deventitle-release.php verify acme-crm-1.2.0.zip --public-key="<public key>"

1. Create a keypair (once)

Shell
php deventitle-release.php keygen
# or
node deventitle-release.mjs keygen

Keys are base64: a 32-byte public key and a 64-byte secret key (the libsodium format). Store the secret key in a password manager and in your build machine’s environment only. Never commit it, put it on a server, or upload it to DevEntitle.

2. Sign a release

Shell
export DEVENTITLE_SIGNING_KEY="<secret key>"
php deventitle-release.php sign acme-crm-1.2.0.zip
# → acme-crm-1.2.0.json

The product slug and version are read from the file name <slug>-<version>.zip, or passed with --product= and --version=. The secret key comes from DEVENTITLE_SIGNING_KEY or --key-file=<path>. It is never accepted on the command line, so it doesn’t end up in your shell history.

3. Check it (optional)

Shell
php deventitle-release.php verify acme-crm-1.2.0.zip --public-key="<public key>"

The manifest

acme-crm-1.2.0.json
{
  "product": "acme-crm",
  "version": "1.2.0",
  "sha256": "<hex SHA-256 of the zip>",
  "size": 36168558,
  "signature": "<base64 Ed25519 signature>",
  "built_at": "2026-11-01T09:30:00Z"
}

The signature is Ed25519 over the UTF-8 text <product>|<version>|<sha256>, with the SHA-256 in lower-case hex. For example: acme-crm|1.2.0|9f86d0….

Uploading

On upload, DevEntitle recomputes the SHA-256 and verifies the signature with the product’s public key. Nothing is stored when an upload is refused, and the reason is shown:

  • wrong hash or wrong size
  • bad signature, or a signature from another product’s key
  • another product’s slug or another version in the manifest
  • an unsigned manifest, or a file that isn’t a zip
  • no public key on the product yet
  • that version was already uploaded

Uploads start as drafts that only your team sees. Publish when ready; unpublish takes a release back. Release notes are Markdown and are shown in your product before updating. The maximum release size is 300 MB by default.

From CI, upload through the Management API with a token that has releases:write:

Upload and publish from CI
curl -X POST https://terminal.deventitle.com/api/manage/v1/releases \
  -H "Authorization: Bearer $DEVENTITLE_TOKEN" \
  -H "Accept: application/json" \
  -F product=acme-crm \
  -F [email protected] \
  -F [email protected] \
  -F notes="$(cat CHANGELOG-1.5.0.md)" \
  -F publish=1

The same checks apply. A mismatch answers 422 release_rejected with the reason. manifest can be the JSON text instead of a file.

Versions and channels

  • Versions look like 1.2.0, 1.2.0.4 or 2.0.0-beta.1. The newest is chosen by version number, so 1.10.0 is newer than 1.9.0.
  • Each version can be uploaded once per product. If something was wrong, upload a new version: installed copies may already have seen the old one.
  • Each release is stable or beta. Stable licences are offered stable releases only. Beta licences (set on the licence type, or per licence) are offered whichever is newer.

Download links

PropertyValue
Form/dl/<token>, encrypted
Lifetime30 minutes (a support person can create a 24-hour link for a buyer)
When usedRe-checks the licence
FileServed byte for byte as uploaded; supports resuming (HTTP Range)

Checking an update in your product

When /api/v1/updates returns a latest release with a download_url, download the zip, then check both the hash and the signature with the public key built into your product, before installing anything:

PHP
$sha = hash_file('sha256', $zipPath);
$ok = hash_equals(strtolower($latest['sha256']), $sha)
    && sodium_crypto_sign_verify_detached(
        base64_decode($latest['signature']),
        'acme-crm|'.$latest['version'].'|'.$sha,
        base64_decode(ACME_RELEASE_PUBLIC_KEY)
    );
if (! $ok) {
    // Refuse: the file was changed or not signed by you.
}

The client code for PHP, Laravel, Node.js and Python includes a download method that does this for you.

When there is no download link

If the licence isn’t entitled to the newest version (for example, support ended before it came out), latest still has the version, notes and a message, but no download_url or signature. Show the message and keep the installed version working.

If a secret key is lost

Create a new keypair, put the new public key on the product, and ship a release that contains the new public key. Sign that release with the old key if you still have it, so existing copies can install it.