callismart / smliser-update-client
Update client for apps hosted on a Smart License Server: checks the release route, downloads the package and verifies it against keys the app pins.
Package info
github.com/CallismartLtd/smliser-update-client
pkg:composer/callismart/smliser-update-client
Requires
- php: >=8.1
- ext-sodium: *
- callismart/http: ^1.1
Requires (Dev)
- phpunit/phpunit: ^10.5 || ^11.0 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Add automatic updates to a PHP app that is distributed through a Smart License Server site.
When you publish a new version of your app on the site, every installed copy can use this library to:
- find out that a newer version exists,
- download it, and
- confirm that the download is genuine and unmodified before anything is installed.
For apps sold through the site, it also activates the customer's license and keeps the installation's download permission current.
The library does not install the update for you, because every app installs differently. It hands you a downloaded ZIP file that has passed every check, and you install it however your app needs.
Before you start
You need three things from the Smart License Server site your app is published on.
| What | Example | Where to find it |
|---|---|---|
| The site's API address | https://updates.example.com/smliser/v1 |
The site's address followed by /smliser/v1. |
| Your app's type and slug | software and acme |
The address of the app's public page on the site, e.g. https://updates.example.com/repository/software/acme. |
| The site's public signing key | rs9am8LBRxNSqxIx… (44 characters) |
The site's Package Signing Key page, linked in its footer: https://updates.example.com/signing-key. |
The site signs every package it serves with a private key that only the site has. The public key lets your app check that signature. Put the public key in your app's code. Never download it at update time: a key that comes from the same place as the package proves nothing.
The signing key page also shows the key's fingerprint, such as SHA256:AKOXGzdr/8vwHnHg…. Before you ship, compare it with the fingerprint the site's owner publishes somewhere else, such as on their own website. If the site were ever broken into, the key shown on it could be replaced too. If the page says the site does not sign its packages, ask the site's administrator to set up signing.
Installation
Requires PHP 8.1 or later with the sodium extension, which most PHP installations have enabled.
composer require callismart/smliser-update-client
Quick start
use Callismart\SmliserUpdateClient\Endpoint; use Callismart\SmliserUpdateClient\TrustPolicy; use Callismart\SmliserUpdateClient\UpdateClient; use Callismart\SmliserUpdateClient\UpdateClientException; $updates = new UpdateClient( new Endpoint( 'https://updates.example.com/smliser/v1' ), 'software', 'acme', TrustPolicy::host( [ 'updates.example.com' => 'rs9am8LBRxNSqxIxhDo40OyFucyjxxER2NFpTwfhtvY=' ] ) ); try { $release = $updates->check( '1.4.0' ); // The version currently installed. if ( null === $release ) { echo "Acme is up to date.\n"; return; } echo "Acme {$release->version} is available.\n"; $package = $updates->fetch( $release, sys_get_temp_dir() ); // $package->path is the downloaded ZIP. It is signed by the site and // unmodified. Install it the way your app installs updates. install_acme_update( $package->path ); } catch ( UpdateClientException $e ) { echo 'Update failed: ' . $e->getMessage() . "\n"; }
check() returns null when the installed version is already the latest, and a Release when a newer one is available. A Release tells you its version, and whether it is a security update, which you might install without asking.
fetch() downloads the package into the directory you give it and checks it. If any check fails, it deletes the file and throws, so a file you receive is always safe to install.
What is checked
Before fetch() returns, the downloaded package must pass all of these:
- Signed by your key. The list of checksums that comes with the package is signed by one of the public keys you put in your app.
- Meant for your app. For packages signed by the site, the signed list names your app's type and slug, so a genuine package of another app published on the same site is refused.
- Unchanged. The file's SHA-256 matches the one in the signed list, so a damaged or altered download is refused.
The site is the only source of the download address. Your app never builds URLs.
Checking in the background
A common pattern is to check on a schedule and install later, after the user agrees. A Release can be saved as an array and restored:
use Callismart\SmliserUpdateClient\Release; // In the scheduled check: $release = $updates->check( ACME_VERSION ); if ( null !== $release ) { $settings->set( 'pending_update', $release->to_array() ); } // Later, when the user clicks "Update now": $release = Release::from_array( $settings->get( 'pending_update' ) ); $package = $updates->fetch( $release, sys_get_temp_dir() );
Paid apps
If your app is sold through the site, only licensed copies can download it. The library's license client handles that for you: it uses the license on the site your app runs on, and keeps the download permission it gets current.
You need the license the customer bought (its service ID and license key) and the address of the site your app is installed on.
Store the license state
The client needs somewhere to keep what the site gives it. Implement LicenseStoreInterface with whatever storage your app has:
use Callismart\SmliserUpdateClient\Licensing\LicenseState; use Callismart\SmliserUpdateClient\Licensing\LicenseStoreInterface; final class AcmeLicenseStore implements LicenseStoreInterface { public function __construct( private AcmeSettings $settings ) {} public function load() : ?LicenseState { $data = $this->settings->get( 'acme_license' ); return is_array( $data ) ? LicenseState::from_array( $data ) : null; } public function save( LicenseState $state ) : void { $this->settings->set( 'acme_license', $state->to_array() ); } public function clear() : void { $this->settings->delete( 'acme_license' ); } }
The state holds a site secret, which the site shows only once, and anyone who has it can act for your installation. Store it where your app keeps other secrets, and do not lose it on updates.
Connect licensing to updates
use Callismart\SmliserUpdateClient\Licensing\LicenseClient; use Callismart\SmliserUpdateClient\Licensing\LicenseCredentials; use Callismart\SmliserUpdateClient\Licensing\LicensedTokenProvider; $license = new LicenseClient( $endpoint, 'software', 'acme', new LicenseCredentials( $service_id, $license_key, 'https://shop.example.com' ), new AcmeLicenseStore( $settings ) ); $updates = new UpdateClient( $endpoint, 'software', 'acme', $trust, null, new LicensedTokenProvider( $license ) );
That is all most apps need. When fetch() downloads a paid release, the license client activates the license on the first download and renews the download permission when it is about to run out.
What the license client does
| Method | What it does |
|---|---|
activate() |
Uses the license on this site. Call it when the customer enters their license, to show them straight away whether it works. |
token() |
Returns a download token that is valid now, activating or renewing as needed. LicensedTokenProvider calls this. |
reauthenticate() |
Exchanges the current token for one that lasts longer. token() does this for you a day before the token runs out. |
status() |
Asks the site about the license: its status, expiry date, and whether this site's token is valid. |
uninstall() |
Stops using the license on this site, so it can be used on another. Call it when your app is uninstalled. |
deactivate() |
Deactivates the license on every site until its owner sorts it out with the seller. Only for a license you believe is stolen or leaked. |
A token from activate() lasts 2 days; a token from reauthenticate() lasts 2 weeks. Neither lasts past the license itself. Your app never renews the license: when it expires, its owner renews it with the seller, and the client picks up again on its own.
If the site secret is lost, for example after a restore from an old backup, activate() recovers by uninstalling the site and activating it again, which issues a new secret.
Licensing errors
The license client throws LicenseException. reason() is one of:
reason() |
What happened | Typical response |
|---|---|---|
UNREACHABLE |
The site could not be reached, or failed. | Try again later. |
RATE_LIMITED |
Too many license requests from this license or site. | Wait retry_after() seconds. |
REJECTED |
The site refused, for example the license has expired or is used on as many sites as it allows. | Show the customer the message. server_code() gives the site's error code. |
BAD_RESPONSE |
The site answered with something unusable. | Try again later; report it if it persists. |
When the license client fails during a download, fetch() throws UpdateClientException with the reason TOKEN_REQUIRED, and getPrevious() returns the LicenseException.
Using your own tokens
If your app already manages download tokens, implement TokenProviderInterface instead of using the license client:
use Callismart\SmliserUpdateClient\TokenProviderInterface; final class AcmeTokens implements TokenProviderInterface { public function __construct( private AcmeSettings $settings ) {} public function token( string $type, string $slug ) : ?string { return $this->settings->get( 'download_token' ); } } $updates = new UpdateClient( $endpoint, 'software', 'acme', $trust, null, new AcmeTokens( $settings ) );
When a paid release is fetched without a token, fetch() throws with the reason TOKEN_REQUIRED.
Signing your own builds
You can also sign builds yourself, with your own key, instead of relying on the site's signature. Upload the build to your app on the site as an artifact, together with two files beside it:
| File | Contents |
|---|---|
acme-1.4.0-lts.zip |
The build. |
acme-1.4.0-lts.sha256 |
sha256sum output for the build: <sha256> acme-1.4.0-lts.zip |
acme-1.4.0-lts.sha256.sig |
The base64 Ed25519 signature of the .sha256 file, made with your private key. |
Then ask for that build by name, and trust your own public key:
$updates = new UpdateClient( $endpoint, 'software', 'acme', TrustPolicy::publisher( [ 'acme-release-key' => 'YOUR_BASE64_PUBLIC_KEY' ] ) ); $package = $updates->fetch( $updates->release( 'acme-1.4.0-lts.zip' ), sys_get_temp_dir() );
The site does not know what version a build you name contains, so $release->version is null here. Your app decides which build to ask for.
Changing keys
Each key has a name, used in messages and in $package->signed_by. You can trust more than one key at a time. To move to a new key without breaking installed copies, release a version of your app that trusts both the old and the new key, wait until most copies have it, then start signing with the new key.
TrustPolicy::host( [ '2026' => 'OLD_BASE64_PUBLIC_KEY', '2027' => 'NEW_BASE64_PUBLIC_KEY', ] );
Handling errors
Every failure to check, download or verify an update throws UpdateClientException. Its message is meant for people; reason() is meant for your code:
reason() |
What happened | Typical response |
|---|---|---|
UNREACHABLE |
The site could not be reached, or the download was cut off. | Try again later. |
NOT_PUBLISHED |
The site does not publish this app, or the build asked for. | Check the type, slug or build name. |
BAD_RESPONSE |
The site answered with something unusable. | Try again later; report it if it persists. |
TOKEN_REQUIRED |
The app is paid and no download token is available. | Ask the user to activate their license; see getPrevious() for why. |
DOWNLOAD_FAILED |
The download was refused or empty. | Try again later; check the license for paid apps. |
UNTRUSTED |
The package is not signed by a key your app trusts, or is not meant for your app. | Do not install. Report it. |
CORRUPT |
The package does not match its signed checksum. | Do not install. Try again later. |
Mistakes in your own code, such as an invalid key or API address, a missing download directory, or a Release of another app, throw InvalidArgumentException instead.
Sending your own headers
The library uses callismart/http. To set a User-Agent or choose how requests are made, pass your own client:
use Callismart\Http\HttpClient; $http = ( new HttpClient() )->with_default_header( 'User-Agent', 'acme/1.4.0' ); $updates = new UpdateClient( $endpoint, 'software', 'acme', $trust, $http );
Development
Only for development: new TrustPolicy( [], TrustPolicy::SIGNER_HOST, true ) accepts packages that are not signed. A package that has a published checksum must still match it. Never ship this setting.
composer install
composer test
License
MIT. See LICENSE.