@voltro/plugin-licensing 0.86.0 → 0.87.0

package/README.md

@@ -24,3 +24,47 @@ deliberately short so there is nothing here to drift out of date.
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+## Games licenses
+
+`./games` exports GamesLicenseEdition/GamesSignLicenseInput/GAMES_PLUGIN_GRANTS/
+withGamesPluginGrants: actual issuer limits/base grants plus thirteen
+game-plugin grants, no signing key, price or invented quota. `./sign` remains
+server-only. Dedicated production Rooms host activates the actual installed
+licensing instance and requires a verified rooms grant before host startup;
+tenant-scoped host signatures refuse until actual tenant-bound host authority
+exists.
+
+`./cloud` exposes authenticated bounded JSON retrieval through an actual private
+credential Effect port. Root `fetchSnapshot` replaces the raw URL option;
+offline verification and lifecycle generation retain authority. CLI registration
+verifies before private ignored .env.local custody and outputs metadata only.
+Signed tokens are redacted as secrets.
+
+Explicit expiry-only grace now participates in offline verification after
+restart, with unchanged signature/not-before checks and exclusive snapshot
+boundaries. Default verification remains strict.
+
+
+## Read-only process inspection
+
+GET `/status` on the installed Licensing inspect mount projects the current process snapshot: observed time, lifecycle activation, current state, installed edition/expiry, deployment or tenant scope without its identity, currently valid Games grants, typed latest refusal, configured grace and optional refresh interval. Rejection details, token/public/private keys, tenant IDs and entitlement values are excluded. Refresh configuration is not evidence of a running schedule. The process-global identity is not isolated per app or Licensing instance.
+
+The browser-safe `@voltro/plugin-licensing/inspect` schema is shared by the server, shared License page and both dashboards. Instance selection uses the actual authorized manifest and existing replica routing. No registration, renewal, purchase, key editing or other write action is installed. Failed or malformed refreshes hide stale observations; the reload control retains keyboard focus while pending.
+
+
+## One template development notice
+
+The nine current game API starters carry `game.template.json` with their actual template ID. After successful plugin activation, `voltro dev` in explicit development mode recognizes that origin and a declared Games plugin, then exclusively records `.framework/game-license-notice.json` before printing the production-license/Cloud registration message. Later boots and competing processes do not print that message again. Ordinary apps without template origin and production/test mode do not record it. Game factories no longer print recurring per-instance license notices.
+
+The receipt contains only format/version/template identity. Linked, foreign-owned, corrupt or oversized origin/receipt files refuse notice custody without deletion or license authority. A failure stays unavailable. At-most-once output is deliberate: a crash after the durable claim but before logging can lose the message; it cannot safely guarantee exactly-once terminal delivery. This path sends no telemetry, asks no consent and issues no trial, license or Seat.
+
+
+## Signed claim scope validation
+
+A supplied tenant claim must be a nonempty, unpadded string of at most 256 characters. Invalid scope refuses `malformed`; it never becomes a deployment-wide grant, including during authenticated expiry grace. Only an omitted tenant is deployment-wide. Edition, key IDs, feature/plugin names and entitlement names follow the same string constraints. Supplied feature/plugin grants must be arrays containing valid strings; malformed members refuse the complete license instead of disappearing. Entitlements must be an object, not an array, with nonnegative finite limits or `unlimited`. An own `__proto__` entitlement stays an own data property without changing the decoded object's prototype.
+
+Signed expiry and issued-at are nonnegative whole Unix seconds within the representable Date range (maximum 8,640,000,000,000 seconds); the redacted inspection schema uses the same expiry boundary. Absent expiry still represents an unbounded license with `exp: 0`; absence of optional grants still means empty grants. This decoder does not bind a trial to a Cloud project, repair a token or issue new-deployment authority. The manual migration `0.87.0/65_license-claim-scope` directs issuers to reissue malformed tokens.
+
+
+`makeSnapshot()` detaches and freezes installed scope, expiry, entitlement values and feature/plugin grants; its returned snapshot and exposed claims are immutable. It no longer preserves the offered claims object's reference identity. Later edits to that object cannot extend expiry, broaden tenant scope or add installed grants. Entitlement lookup accepts own properties only: ungranted prototype keys such as `constructor`, `toString` and `__proto__` return `undefined`. An explicitly signed own entitlement with such a name remains data. This does not isolate the process-global license cell between apps or verify raw claims passed directly to `makeSnapshot()`; actual token verification remains the authority.