Search by

callismart / smliser-update-client

CallismartLtd

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

Statistics

Installs: 28

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.1.0 2026-11-15 17:39 UTC

This package is auto-updated.

Last update: 2026-11-15 18:03:21 UTC


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:

  1. find out that a newer version exists,
  2. download it, and
  3. 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.