Bugfix: multisite token logic

.github/workflows/static-analysis.yml

@@ -7,14 +7,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Configure PHP environment
         uses: shivammathur/setup-php@v2
         with:
           php-version: '7.4'
           extensions: mbstring, intl
           coverage: none
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
         with:
           composer-options: "--ignore-platform-reqs --optimize-autoloader"
       - name: Run PHPStan static analysis

README.md

@@ -55,6 +55,9 @@ add_action( 'plugins_loaded', function() {
 }, 0 );
 ```
 
+> 💡 See [multisite license documentation](./docs/features.md#multisite-licenses) to enable
+> network licensing features.
+
 ## Translation
 
 Package is using `__( 'Invalid request: nonce field is expired. Please try again.', '%TEXTDOMAIN%' )` function for translation. In order to change domain placeholder `'%TEXTDOMAIN%'` to your plugin translation domain run
@@ -92,11 +95,12 @@ src/Uplink/Helper.php
 The file should match the following - keeping the `KEY` constant set to a blank string, or, if you want a default license key, set it to that.:
 
 ```php
-<?php
+<?php declare( strict_types=1 );
+
 namespace Whatever\Namespace\Uplink;
 
-class Helper {
-	const KEY = '';
+final class Helper {
+	public const KEY = '';
 }
 ```
 
@@ -155,7 +159,7 @@ In order to render license key form just add the following to your settings page
 ```php
 use StellarWP\Uplink\Config;
 
-$fields = Config::get_container()->get( License_Field::class );
+$fields = \StellarWP\Uplink\get_license_field();
 
 // Do one of the following:
 $fields->render();               // Render the fields, titles, and submit button.
@@ -168,7 +172,7 @@ To render a single product's license key, use the following:
 ```php
 use StellarWP\Uplink\Config;
 
-$fields = Config::get_container()->get( License_Field::class );
+$fields = \StellarWP\Uplink\get_license_field();
 
 // Do one of the following:
 $fields->render_single( 'my-plugin' );               // Render the fields, titles, and submit button.
@@ -200,7 +204,7 @@ use StellarWP\Uplink\Config;
 function render_settings_page() {
     // ...
 
-    $fields = Config::get_container()->get( License_Field::class );
+    $fields = \StellarWP\Uplink\get_license_field();
     $fields->render(); // or $fields->render_single( 'my-plugin' ); to render a single plugin
 
     //....
@@ -239,14 +243,14 @@ functionality:
 
 ```php
 // Call the namespaced function with your plugin slug.
-\StellarWP\Uplink\render_authorize_button( 'kadence-blocks-pro' );
+\StellarWP\Uplink\render_authorize_button( 'my-plugin-slug' );
 ```
 
 You can also pass in a custom license domain, which can be fetched on the Uplink Origin side from the `uplink_domain` query variable:
 
 ```php
 // Call the namespaced function with your plugin slug and license domain.
-\StellarWP\Uplink\render_authorize_button( 'kadence-blocks-pro', 'customer-site.com' );
+\StellarWP\Uplink\render_authorize_button( 'my-plugin-slug', \StellarWP\Uplink\get_license_domain() );
 ```
 
 > 💡 The button is very customizable with filters, see [Authorize_Button_Controller.php](src/Uplink/Components/Admin/Authorize_Button_Controller.php).
@@ -256,15 +260,23 @@ You can also pass in a custom license domain, which can be fetched on the Uplink
 This connects to the licensing server to check in real time if the license is authorized. Use sparingly.
 
 ```php
-$container     = \StellarWP\Uplink\Config::get_container();
-$token_manager = $container->get( \StellarWP\Uplink\Auth\Token\Contracts\Token_Manager::class );
-$token         = $token_manager->get();
+$is_authorized = \StellarWP\Uplink\is_authorized_by_resource( 'my-plugin-slug' );
+
+echo $is_authorized ? esc_html__( 'authorized' ) : esc_html__( 'not authorized' );
+```
+
+Or, if you have more complex licensing needs, you can provide specific data:
+
+```php
+$token       = \StellarWP\Uplink\get_authorization_token( 'my-plugin-slug' );
+$license_key = \StellarWP\Uplink\get_license_key( 'my-plugin-slug' );
+$domain      = \StellarWP\Uplink\get_license_domain();
 
-if ( ! $token ) {
-	return;
+if ( ! $token || ! $license_key || ! $domain ) {
+	return; // or, log/show errors.
 }
 
-$is_authorized = \StellarWP\Uplink\is_authorized( 'customer_license_key', $token, 'customer_domain' );
+$is_authorized = \StellarWP\Uplink\is_authorized( $license_key, 'my-plugin-slug', $token, $domain );
 
 echo $is_authorized ? esc_html__( 'authorized' ) : esc_html__( 'not authorized' );
 ```
@@ -274,18 +286,11 @@ echo $is_authorized ? esc_html__( 'authorized' ) : esc_html__( 'not authorized'
 If for some reason you need to fetch your `auth_url` manually, you can do so by:
 
 ```php
-$container        = \StellarWP\Uplink\Config::get_container();
-$auth_url_manager = $container->get( \StellarWP\Uplink\API\V3\Auth\Contracts\Auth_Url::class );
-
-// Pass your product or service slug.
-$auth_url = $auth_url_manager->get( 'kadence-blocks-pro' );
-
-echo $auth_url;
+echo esc_url( \StellarWP\Uplink\get_auth_url( 'my-plugin-slug' ) );
 ```
 
 > 💡 Auth URL connections are cached for one day using transients.
 
-
 ### Callback Redirect
 
 The Callback Redirect generated by the Origin looks something like this, where `uplinksample.lndo.site` is your
@@ -304,7 +309,5 @@ The following Query Variables are available for reference:
 
 1. `uplink_token` - The unique UUIDv4 token generated by StellarWP Licensing.
 2. `_uplink_nonce` - The original nonce sent with the callback URL, as part of the "Connect" button.
-3. `uplink_license` (optional) - Whether we should also update or set a License Key.
-4. `uplink_slug` (optional) - The Product or Service Slug that we're updating the license for.
-
-> ⚠️ `uplink_slug` MUST be supplied if `uplink_license` is!
+3. `uplink_slug` The Product or Service Slug that we're updating the license for.
+4. `uplink_license` (optional) - Whether we should also update or set a License Key.

docs/features.md

@@ -19,7 +19,6 @@ The goals of this library are to provide a simple way to register one or more pl
 
 Registration of plugins and services should happen programmatically and the intended API is documented in this repository's [README](/README.md).
 
-
 ### License keys & validation
 
 The Uplink library should communicate with the Stellar Licensing system at specific moments. Those moments are:
@@ -80,15 +79,113 @@ Uplink should provide a UI for entering license keys. Ideally, Uplink should hav
 When a license field is rendered, manipulated, or saved, a validation request should be triggered (see the diagram above).
 
 
-##### Site & Network-level
-
-When a plugin that includes the Uplink library is activated at the network level, License keys should be able to be entered at both the network and the site level.
-
-
 ### Product updates
 
 The Uplink library should mark a registered plugin as needing an update when a validation response comes back from the Stellar Licensing system with a version number greater than the version number that is currently installed. You can see a reference implementation in [`tribe-common`](https://github.com/the-events-calendar/tribe-common/blob/master/src/Tribe/PUE/Checker.php#L1537).
 
 #### Plugin page
 
 On the _Plugins_ page in the WP Dashboard, any plugin that has an update available should display the update similar to how WordPress core does it. If a user click on `Update`, the zip files should be fetched from the Stellar Licensing system and installed if their license key is valid.
+
+### Multisite Licenses
+
+Out of the box, Uplink treats all sub-sites as their _own independent site_, storing license keys and authorization tokens
+in the options table of that sub-site.
+
+If your product supports multisite level licenses, you can configure Uplink to allow one license key/auth token for the entire
+multisite network across multiple situations.
+
+> 💡 To operate at the network level, your plugin **must be network activated** and the proper configuration options enabled.
+
+| Install Type               | Network Activated? | Clause | Uplink Config Option (default is false)             | License & Token Storage Location |
+|----------------------------|--------------------|--------|-----------------------------------------------------|----------------------------------|
+| Standard                   | –                  | –      | –                                                   | Site level                       |
+| Multisite (subfolders)     | Yes                | AND    | `Config::set_network_subfolder_license(true)`       | Network level                    |
+| Multisite (subfolders)     | No                 | OR     | `Config::set_network_subfolder_license(false)`      | Site Level                       |
+| Multisite (subdomains)     | Yes                | AND    | `Config::set_network_subdomain_license(true)`       | Network level                    |
+| Multisite (subdomains)     | No                 | OR     | `Config::set_network_subdomain_license(false)`      | Site Level                       |
+| Multisite (domain mapping) | Yes                | AND    | `Config::set_network_domain_mapping_license(true)`  | Network level                    |
+| Multisite (domain mapping) | No                 | OR     | `Config::set_network_domain_mapping_license(false)` | Site Level                       |
+
+
+#### Examples
+
+After [library initialization](../README.md#initialize-the-library), the above config options can be set, e.g.
+
+```php
+use StellarWP\Uplink\Uplink;
+
+// ...other config above
+
+// Allow a single network license for multisite subfolders.
+Config::set_network_subfolder_license( true );
+
+// Allow a single network license for multisite using subdomains.
+Config::set_network_subdomain_license( true );
+
+// Allow a single network license for custom domains/mapped domains.
+Config::set_network_domain_mapping_license( true );
+
+Uplink::init();
+```
+
+> 🚨 Consider moving your plugin UI and the Uplink License Field settings to the WordPress network UI to prevent
+> sub-sites being able to control licensing and token authorization for the entire multisite network if you enable
+> any of the multisite config options.
+
+Each config option can also be filtered at runtime, assuming your plugin's slug is registered as `my-plugin-slug`:
+
+```php
+add_action( 'init', static function(): void {
+	// Replace with a call to your own plugin's config/option to check whether it should be managed in the network.
+	$network_enabled = true;
+
+	add_filter( 'stellarwp/uplink/my-plugin-slug/allows_network_subfolder_license',
+		static function () use ( $network_enabled ): bool {
+			return $network_enabled;
+		}, 10 );
+
+	add_filter( 'stellarwp/uplink/my-plugin-slug/allows_network_subdomain_license',
+		static function () use ( $network_enabled ): bool {
+			return $network_enabled;
+		}, 10 );
+
+	add_filter( 'stellarwp/uplink/my-plugin-slug/allows_network_domain_mapping_license',
+		static function () use ( $network_enabled ): bool {
+			return $network_enabled;
+		}, 10 );
+} );
+```
+
+#### Functions
+
+Uplink provides some handy functions that include automated support for fetching or storing data from
+the correct location.
+
+```php
+// Checks if the current WordPress user is authorized to make license/token changes (is_super_admin() out of the box).
+\StellarWP\Uplink\is_user_authorized();
+
+// Get a stored license key, will fetch from the current site's options or network, depending on your config.
+\StellarWP\Uplink\get_license_key( 'my-plugin-slug' );
+
+// Store a license key, will store in the current site's options or network, depending on your config.
+\StellarWP\Uplink\set_license_key( 'my-plugin-slug', 'new_license_key' );
+
+// Get the domain associated with a license.
+// Note that if any of the multisite options are enabled, the root multisite domain contains a unique suffix
+// so that it doesn't override the license key/token for the entire multisite network if it's converted back
+// to single site.
+// Depending on your configuration, this may the multisite domain with suffix, e.g. example.com/2626gsg
+// or, it could be the sub-site domain with path, e.g. example.com/sub1, example.com/sub2 etc...
+\StellarWP\Uplink\get_license_domain();
+
+// This will get the license domain without any added suffixes.
+\StellarWP\Uplink\get_original_domain();
+
+// Gets the local URL to disconnect a token (delete it locally).
+\StellarWP\Uplink\get_disconnect_url( 'my-plugin-slug' );
+
+// Checks if the current site (e.g. the sub-site on multisite) would support multisite licensing.
+\StellarWP\Uplink\allows_multisite_license( 'my-plugin-slug' );
+```

phpstan.neon.dist

@@ -15,7 +15,6 @@ parameters:
 	level: 5
 	inferPrivatePropertyTypeFromConstructor: true
 	reportUnmatchedIgnoredErrors: false
-	checkGenericClassInNonGenericObjectType: false
 
 	# Paths to be analyzed.
 	paths:
@@ -26,3 +25,4 @@ parameters:
 		- '#^Function add_query_arg invoked with [123] parameters?, 0 required\.$#'
 		# Uses func_get_args()
 		- '#^Function apply_filters(_ref_array)? invoked with [34567] parameters, 2 required\.$#'
+		- '#Path in require_once\(\).+is not a file or it does not exist#'

src/Uplink/API/Client.php

@@ -187,14 +187,16 @@ protected function request( $method, $endpoint, $args ) {
 	 *
 	 * @since 1.0.0
 	 *
-	 * @param Resource    $resource        Resource to validate.
-	 * @param string|null $key             License key.
-	 * @param string      $validation_type Validation type (local or network).
-	 * @param bool        $force           Force the validation.
+	 * @param  Resource     $resource         Resource to validate.
+	 * @param  string|null  $key              License key.
+	 * @param  string       $validation_type  Validation type (local or network).
+	 * @param  bool         $force            Force the validation.
+	 *
+	 * @throws \RuntimeException
 	 *
 	 * @return mixed
 	 */
-	public function validate_license( Resource $resource, string $key = null, string $validation_type = 'local', bool $force = false ) {
+	public function validate_license( Resource $resource, ?string $key = null, string $validation_type = 'local', bool $force = false ) {
 		/** @var Data */
 		$site_data = $this->container->get( Data::class );
 		$args      = $resource->get_validation_args();

src/Uplink/API/V3/Auth/Contracts/Token_Authorizer.php

@@ -11,11 +11,12 @@ interface Token_Authorizer {
 	 * @see \StellarWP\Uplink\API\V3\Auth\Token_Authorizer
 	 *
 	 * @param  string  $license  The license key.
+	 * @param  string  $slug     The plugin/service slug.
 	 * @param  string  $token    The stored token.
 	 * @param  string  $domain   The user's domain.
 	 *
 	 * @return bool
 	 */
-	public function is_authorized( string $license, string $token, string $domain ): bool;
+	public function is_authorized( string $license, string $slug, string $token, string $domain ): bool;
 
 }

src/Uplink/API/V3/Auth/Token_Authorizer.php

@@ -28,17 +28,19 @@ public function __construct( Client_V3 $client ) {
 	/**
 	 * Manually check if a license is authorized.
 	 *
-	 * @see is_authorized()
-	 *
 	 * @param  string  $license  The license key.
-	 * @param  string  $token  The stored token.
-	 * @param  string  $domain  The user's domain.
+	 * @param  string  $slug     The plugin/service slug.
+	 * @param  string  $token    The stored token.
+	 * @param  string  $domain   The user's domain.
 	 *
 	 * @return bool
+	 *
+	 * @see is_authorized()
 	 */
-	public function is_authorized( string $license, string $token, string $domain ): bool {
+	public function is_authorized( string $license, string $slug, string $token, string $domain ): bool {
 		$response = $this->client->get( 'tokens/auth', [
 			'license' => $license,
+			'slug'    => $slug,
 			'token'   => $token,
 			'domain'  => $domain,
 		] );

src/Uplink/API/V3/Auth/Token_Authorizer_Cache_Decorator.php

@@ -49,20 +49,21 @@ public function __construct(
 	 * @see Token_Authorizer
 	 *
 	 * @param  string  $license  The license key.
+	 * @param  string  $slug     The plugin/service slug.
 	 * @param  string  $token    The stored token.
 	 * @param  string  $domain   The user's domain.
 	 *
 	 * @return bool
 	 */
-	public function is_authorized( string $license, string $token, string $domain ): bool {
-		$transient     = $this->build_transient( [ $license, $token, $domain ] );
+	public function is_authorized( string $license, string $slug, string $token, string $domain ): bool {
+		$transient     = $this->build_transient( [ $token ] );
 		$is_authorized = get_transient( $transient );
 
 		if ( $is_authorized === true ) {
 			return true;
 		}
 
-		$is_authorized = $this->authorizer->is_authorized( $license, $token, $domain );
+		$is_authorized = $this->authorizer->is_authorized( $license, $slug, $token, $domain );
 
 		// Only cache successful responses.
 		if ( $is_authorized ) {
@@ -75,12 +76,23 @@ public function is_authorized( string $license, string $token, string $domain ):
 	/**
 	 * Build a transient key.
 	 *
-	 * @param  array<int, string>  ...$args
+	 * @param  array<int, string>  $args
 	 *
 	 * @return string
 	 */
-	public function build_transient( array ...$args ): string {
-		return self::TRANSIENT_PREFIX . hash( 'sha256', json_encode( $args ) );
+	public function build_transient( array $args ): string {
+		return self::TRANSIENT_PREFIX . $this->build_transient_no_prefix( $args );
+	}
+
+	/**
+	 * Build a transient key without the prefix.
+	 *
+	 * @param  array  $args
+	 *
+	 * @return string
+	 */
+	public function build_transient_no_prefix( array $args ): string {
+		return hash( 'sha256', json_encode( $args ) );
 	}
 
 }