Five rules govern the plugin. Four are in both editions; the fifth is about downloads, which only the full edition has.
The rules
The claim rule: one unit is one key, whatever happens. WooCommerce fires its status hooks more than once in ordinary operation — an order moved back to processing and completed again fires twice. Every unit is minted under a key of its own, order:{order}:item:{line}:unit:{n}, and the database refuses a second row with the same one. A check-then-insert in code loses that race on a busy afternoon; a unique index cannot. A customer sent two codes for one purchase has a code nobody can revoke.
The rest rule: keys are sealed at rest and never shown whole on a list screen. Each key is stored twice over: as a one-way hash, which every lookup uses, and sealed with authenticated encryption (libsodium where it exists, AES-256-GCM through OpenSSL otherwise) under a secret the plugin generates for itself. It is opened only where somebody is meant to see it: the buyer's email, the order-received page, My Account, the single order screen and (full edition) the CSV export. List screens show the last five characters. The order itself stores license ids, never keys.
The reissue rule: a delivered key is never regenerated silently. A key is something the buyer has already pasted somewhere. Full edition: the only way to a new key is Reset key in My Account, which is logged; it swaps the key on the same license, so every activated site stays connected and the old key simply stops existing.
The stock rule: a pool has exactly as many keys to sell as are left in it. A product selling from its pool is in stock while the pool has keys and out of stock when it is empty — through WooCommerce's own stock filters, so the shop, the product page, add-to-cart, the Store API and the Checkout block all agree.
The status rule (full edition): the status is worked out when it is asked for, never stored. An active key past its expiry date answers expired; a refunded key answers revoked. No scheduled task has to remember to change anything.
Step by step: from order to key
- The order reaches Completed. Keys are issued on
woocommerce_order_status_completedand at no other status. An order of only virtual, downloadable products completes by itself once paid; other orders need completing by hand. - Each line is checked. A line is a license product if its product (or, for a variation, its parent) has Sells license keys ticked — or, full edition, has Product identifiers filled in.
- One key per unit. A line of three is three keys. For each unit:
- Pool: the oldest unclaimed key is claimed in one conditional database update, so two checkouts can never draw the same key. A variation's own pool is tried first, then its product's.
- Generated: a random key in the shape
GM-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX, from an alphabet without the easily confused 0/O, 1/I/L, U and V.
- The key is stored with what it unlocks, its activation limit and its expiry (full edition; the free edition: the product's own slug, one activation, no expiry), the customer and the order.
- The order records it. The license ids are added to the order meta
_gmlk_license_ids, and an order note says how many keys were issued — without the keys. - The buyer gets it. A Your license keys section is added to the customer's order emails (never the admin copy), the order-received and order pages, and My Account → Licenses.
When a key cannot be issued
If the pool is empty, or the server has neither libsodium nor OpenSSL, no key is invented and none is written in the clear. The order gets a note — "1 license key could not be issued — the key pool is empty or no cipher is available. Add keys and complete the order again." — and completing the order again issues only what is missing.
A pool key is held when the order is placed (classic checkout and the Checkout block), and that held key is the one issued when the order completes, so the last key is out of stock the moment it is held rather than sold twice. A cancelled, failed or wholly refunded order gives what it held back. An order created in wp-admin, which never passes a checkout, draws its key at completion.
Refunds
When an order is refunded in full, every key it issued is revoked. The software keeps running where it is installed; it simply stops getting updates. A partial refund revokes nothing (which keys it concerns is a support decision) and is only logged.
Activations — Full edition
Your software calls the REST API with the key, the product identifier and the site's address.
- The site is normalized: lower case,
www.dropped, the default port dropped, trailing slash dropped — so one site is one string. - Activating the same site again refreshes it and never uses a second slot.
- A new site needs a free slot. The count and the insert are one database statement, so two sites activating at the same moment cannot both take the last slot.
- Local and staging sites are free:
localhost,127.0.0.1,::1, hosts ending.test,.local,.localhost,.invalid,.exampleor.ddev.site, hosts startingstaging.,stage.,dev.ortest., and private 10.x, 192.168.x and 172.16–31.x addresses. They have their own cap (by default the larger of 5 and twice the activation limit). - Deactivating stamps the activation as ended rather than deleting it, and frees the slot.
Expired keys can be checked but not newly activated; revoked keys can do neither.
Updates and downloads — Full edition
The download rule: a download is a signed, short-lived link, and the license is checked again when it is fetched. The update endpoint returns the latest version's details always — so an expired license learns what it is missing — and a download link only for an active one. The link carries an HMAC-SHA256 signature over the product, version, license id and expiry, lasts ten minutes by default, and when it is fetched the license is checked again: a link handed out in January will not serve a release to a license refunded in February.
My Account → Licenses
The one place a customer sees each key in full, with its status. Full edition adds the term and slots in use, the activated sites with a Deactivate button each (staging sites badged as free), download links for the latest release of each licensed product (active licenses only) and Reset key. Every action there is nonce-checked and only works on the customer's own licenses.
