# Paid entitlements and Evaluation exports

SmartCut64's official Windows binaries support Lemon Squeezy purchase
activation backed by a perpetual, machine-bound signed entitlement. The
entitlement is verified offline by the GUI, worker, and CLI; the private
signing key remains only in the activation service. This document describes the engineering design and operating
procedure. It is not legal advice and does not replace the independent
GPL/LGPL, consumer-terms, privacy, patent, or trademark review required before
sale.

## User-visible behaviour

- A valid paid licence permits clean video output and preserves the selected
  smart-render, packet-copy, or full-transcode mode.
- A missing, malformed, expired, not-yet-valid, incorrectly signed, or
  machine-mismatched licence puts the official binary in **Evaluation mode**.
  Editing and preview remain available, but every video output is permanently
  marked `SMARTCUT64 EVALUATION` and the complete video is re-encoded so no
  unmarked copied GOP can bypass the restriction.
- Evaluation audio-only output is allowed because an audio stream cannot carry
  a visible video watermark.
  Direct selected-stream extraction writes only the selected non-video stream.
  An edited audio-only delivery from a video source still watermarks any staged
  video intermediate; copy-only range helpers that cannot guarantee this are
  blocked in Evaluation mode.
- Copy-only delivery utilities that cannot safely insert a watermark are
  unavailable in Evaluation mode: QuickStream Fix, Trimmed File Copy,
  elementary-stream multiplexing, metadata packet copy, and final Joiner
  delivery. The normal Save Video path remains available.
- Save Video, Batch Manager, Watch Folders, project export, and imported
  VideoReDo batch export all apply the same entitlement decision. The licence
  is revalidated when an export starts, not just at application startup.
- The packaged worker and production CLI independently validate the installed
  entitlement. Invoking them directly cannot obtain clean video output or
  override the Evaluation full-recode watermark. Unknown stream selections
  fail closed rather than being assumed to be audio-only.

The repository defaults to no production public key and therefore fails closed
to Evaluation mode. A release owner must provision a separate production key
before creating a paid release candidate.

The build tree also contains `smartcut-cli-test.exe`,
`smartcut-worker-test.exe`, and an isolated `smartcut-gui-test.exe` harness.
They allow the pre-existing media regression suite to exercise clean delivery
internals; the isolated GUI directory places the internal worker under its
normal runtime filename for GUI automation. These targets have no install
rule, are not included by CPack, and the release gate rejects a binary package
containing any test executable, its symbols, or the internal test directory.
Never distribute these internal test programs or copy files from
`internal-test-bin` into a release.

## Token and verification design

A licence file contains one compact token:

```text
SC64-1.<base64url UTF-8 claims>.<base64url RSA signature>
```

The signature is RSA PKCS#1 v1.5 with SHA-256 over the exact
`SC64-1.<payload>` ASCII text. Official binaries contain only the public RSA
modulus and exponent. The private key must never enter the repository, build
tree, installer, corresponding-source archive, CI variables, logs, or a
developer workstation used for ordinary builds.

The signed payload contains exactly the operational claims used by version 1:

```text
product=SmartCut64
edition=paid
license_id=<seller identifier>
customer=<customer display name>
installation_id=<32 lowercase hexadecimal characters>
issued_unix=<UTC Unix seconds>
not_before_unix=<UTC Unix seconds>
expires_unix=<UTC Unix seconds, or 0 for perpetual>
clean_export=1
```

Unknown or duplicate claims, invalid encoding, invalid time values, oversized
tokens, an absent verification key, and all signature errors fail closed.

The Installation ID is the first 128 bits of SHA-256 over a domain-separated
value derived from Windows `MachineGuid`. It is displayed in **Help > Licence
& Activation** and is selectable for copying. The raw MachineGuid is not
stored in the licence or sent over a network.

## Online purchase activation

When the customer explicitly activates, SmartCut64 sends the purchase email,
raw Lemon Squeezy licence key, and one-way Installation ID over HTTPS to the
configured SmartCut64 bridge. The bridge validates the exact Lemon store,
product, variant, customer email, key state, activation limit, and instance. It
then returns a perpetual `.sc64` token (`expires_unix=0`) signed by the
production entitlement key for that Installation ID.

The client verifies the returned token before installing it. The raw purchase
key and email are encrypted for the current Windows user with DPAPI and used
only for deactivation, transfer and support-assisted reactivation. Clean export
does not depend on periodic contact with the activation service after a valid
entitlement has been installed.

The bridge stores a SHA-256 hash of the Lemon key rather than the raw key, the
already-hashed Installation ID, Lemon instance/order/licence identifiers,
customer identity needed for support, status, and timestamps. Signed refund
and disabled-key webhooks prevent future activation, transfer and reset. An
already-issued perpetual offline token cannot be remotely revoked. Per-licence
and per-actor native rate limits protect the
public bridge and Lemon's upstream request budget.

SmartCut64 contains no advertising, behavioural analytics, or general usage
telemetry. See `PRIVACY.md` and `services/licensing-bridge/README.md`.

## Provision the production key

Run this once on a controlled offline Windows machine. Choose and securely
retain a strong PFX password:

```powershell
$password = Read-Host 'New signing-key backup password' -AsSecureString
$key = .\tools\New-SmartCut64LicenseKey.ps1 `
  -BackupPfx 'E:\OfflineKeys\SmartCut64-licence-signing.pfx' `
  -Password $password `
  -KeySize 3072
$key
```

Keep at least two encrypted offline backups under separate administrative
control. Record the certificate thumbprint and public values. Configure the
release build with the public values only:

```powershell
cmake --preset windows-ucrt-gui-release `
  "-DSMARTCUT_LICENSE_PUBLIC_MODULUS_HEX=$($key.PublicModulusHex)" `
  "-DSMARTCUT_LICENSE_PUBLIC_EXPONENT_HEX=$($key.PublicExponentHex)" `
  "-DSMARTCUT_LICENSE_SERVICE_URL=https://licensing.example.com"
cmake --build --preset windows-ucrt-gui-release
```

Before a commercial package is created, issue a release-test token for the
release machine with the production signing key, then run:

```powershell
.\scripts\release-gate.ps1 -PaidTestLicense 'E:\Issued\release-machine-test.sc64'
```

The gate requires the exact production worker and CLI binaries to accept that
token and create clean keyframe-copy output. A missing, mismatched, expired, or
wrong-machine token fails packaging. `-EvaluationOnly` is reserved for a
clearly labelled non-paid build and does not exercise the paid path.

Confirm the generated key header and packaged archives contain no private key,
PFX path, password, or certificate private material. A production release gate
must test both Evaluation and paid paths against the exact configured public
key.

## Manual support-issued licence fallback

1. The customer opens **Help > Licence & Activation** and sends the displayed
   Installation ID through the seller's chosen secure support channel.
2. On the controlled signing machine, issue a time-limited licence. One year is
   the tool default; use shorter periods if revocation risk requires it.


This path is reserved for support/recovery and controlled release testing.
Normal customers should activate with their Lemon purchase email/key so they
can deactivate and transfer computers without manual signing.
```powershell
.\tools\New-SmartCut64License.ps1 `
  -CertificateThumbprint '<offline signing certificate thumbprint>' `
  -Customer 'Customer or organisation name' `
  -InstallationId '<32-character Installation ID>' `
  -OutputFile 'E:\Issued\customer-license.sc64' `
  -Expires (Get-Date).ToUniversalTime().AddYears(1)
```

3. Deliver the `.sc64` file to that customer. They install it through **Help >
   Licence & Activation**. SmartCut64 copies it to the user's local application
   data folder only after signature, product, edition, time, and installation
   checks pass.

The Personal product uses `-Perpetual`. An offline perpetual token cannot be
remotely revoked. For a machine transfer, deactivate the old Lemon instance and
issue a new token for the new Installation ID. Manual support-issued files also
have no live revocation path. The online Lemon bridge uses signed webhooks to
block future activations and transfers, and requires the privacy, availability,
security, consumer-terms, and GPL review described in the launch runbook.

## Threat model and limitations

The design prevents casual token editing, copying a token to another Windows
installation, and bypassing the watermark through another official GUI,
worker, or CLI delivery route. It does not claim that client-side controls are unbreakable. An
administrator can alter local state, system time, or executable code; code
code signing and machine binding reduce but do not eliminate those risks.

Most importantly, SmartCut64 is GPL-3.0-or-later software. Every source
recipient may inspect, modify, build, and redistribute it under the GPL. A
recipient can therefore create a modified build without the official-binary
entitlement check. The seller must not use contracts, DRM claims, or
anti-circumvention terms to take away those GPL/LGPL rights. This mechanism
protects the convenience and provenance of the seller's official signed
binaries, clean-export entitlement, updates, and support channel; it cannot
guarantee exclusive control of all builds.

## Release evidence

Retain, without private-key material:

- the release public-key fingerprint and CMake cache values;
- Evaluation missing/invalid/expired/wrong-installation test results;
- a paid-token clean-export test bound to the release test installation;
- a decoded-frame comparison proving the Evaluation mark is visible;
- worker reports proving Evaluation output used full video recode;
- production worker/CLI boundary tests proving clean-copy and ambiguous-stream
  bypass attempts are blocked and genuine audio-only output remains available;
- key-custody, issuance, transfer, refund, expiry, and incident procedures;
- independent legal review of the exact binary/source artifact hashes and
  customer-facing entitlement wording.
