Setting up the license key

Not yet published. No license is issued and no package is released yet. This page describes how the code in this repository checks a key; the first release will behave the same way.

Pro runs without a key. Without a valid one it still does everything; it shows a small label in the map and writes one line to the console (see The watermark). A key makes both disappear. Nothing about the key ever switches a function off.

Giving Pro the key#

There are two ways, the same as for plugging Pro in (see Installing Pro):

proErweiterung({ lizenz: 'vs1.…' }) takes the key for the editors that get this extension.
With import '@vectorstream/pro/global', call setzeProLizenz('vs1.…') before the first editor is built. Later calls apply to editors built afterwards; setzeProLizenz(undefined) clears the key.

ausfuehrlich: true (an option of both) makes a valid key say, once, to whom it is licensed.

A key that is built into the bundle of a web application can be read by every visitor of the application. Keep it out of repositories that are public, and out of places that are not part of your application.

How the key is checked#

The check runs once per key, in the page or in Node, and asks nothing of the network. It reads a public key list that is part of the Pro package (a token signed with a key that is not in that list is ungueltig with the reason kid), the day, the origin of the page and the build date of the Pro version, and gives back one of the states. It never throws and never rejects; whatever goes wrong inside it is a state too.

Pro opens no network connection for license, counting or telemetry, neither in the check nor anywhere else, and no data about the use leaves the page. A test in the repository fails if the source of Pro contains a way to reach the network.

A key is a token vs1.<payload>.<signature>: the payload is JSON, the signature is Ed25519 over the text before the last dot. The check verifies the signature first and reads nothing but the key id before that.

Claims#

The payload has a fixed set of claims. A claim that is not in this list makes the key invalid (format): every new claim is a new format version.

Claim	Meaning
`v`	Format version, `1`.
`kid`	Id of the signing key; the check looks it up in its list of public keys.
`jti`	The id of the license, for support.
`sub`	The id of the customer.
`kunde`	The customer's name, shown in the console line of a valid key with `ausfuehrlich`.
`prod`	The product, `pro`.
`umfang`	Optional list of features. v1 only checks its shape (an array of at most 32 entries, each of a plain name pattern) and does not evaluate it.
`art`	`platz` (seats) or `projekt` (project).
`plaetze`	With `platz`: the number of seats.
`projekt`	With `projekt`: the project's name.
`origins`	Optional list of the origins the key is valid for, see Origins.
`iat`	The day the key was issued.
`upd`	The last build date the key covers, see The update window.
`exp`	Optional hard expiry, only for trial keys.
`x`	Optional object for later use: signed, but v1 decides nothing from it.

Seats and projects are a matter of the license agreement. The software does not count anything, which would need a connection to a server: it cannot tell how many people develop with it.

The claim x is how new information is added without disturbing older versions of Pro: an older version ignores fields it does not know inside x. A format change that an older version must refuse gets a new prefix, vs2. A version of Pro that does not know vs2 reports an invalid key (format) and shows the watermark. It does not lock anything.

States#

State	Functions	Watermark	Console (once per page)
`gueltig`	all	no	nothing; with `ausfuehrlich: true` one line: vectorstream Pro — licensed to {kunde} ({jti})
`entwicklung`	all	no	vectorstream Pro — evaluation on localhost. A license key is needed for production use.
`fehlt`	all	yes	vectorstream Pro — no license key set, a watermark is shown. See {url}
`ungueltig`	all	yes	vectorstream Pro — the license key is not valid ({reason}), a watermark is shown.
`abgelaufen`	all	yes	vectorstream Pro — the license key expired on {date}, a watermark is shown.
`updateFensterVorbei`	all	yes	vectorstream Pro — the license key covers versions up to {upd}; this version is from {build}. A watermark is shown.
`falscherOrigin`	all	yes	vectorstream Pro — the license key is not valid for the origin {origin}, a watermark is shown.

The words in braces are filled in. fehlt is a page without a key on an address that is not a development address; on a development address the same page is entwicklung. The warnings are console.warn, the two quiet lines console.info. Only gueltig, abgelaufen, updateFensterVorbei and falscherOrigin carry the claims of the key, since only for them the signature was verified.

The checks run in this order: the signature, then abgelaufen, then updateFensterVorbei, then falscherOrigin.

Reasons for an invalid key#

Reason	Meaning
`format`	The text is not a token of format `vs1`: wrong parts, not the canonical JSON, a claim that is not allowed, a value out of range.
`signatur`	The signature does not match.
`kid`	No public key with this `kid` in this version of Pro.
`version`	The format version is not one this version understands.
`produkt`	The key is for another product.
`kryptografie`	The platform cannot verify Ed25519 at all, for example a page that is not a secure context.
`intern`	The check itself failed.

The update window#

A key without exp is valid for ever, for every version of Pro whose build date is on or before upd. The build date is written into the package when it is built. The check compares upd with it, not with the clock: a key does not run out because time passes. Whoever does not renew keeps the version they have, without a watermark, and only gets no newer ones. A newer version than the key covers is updateFensterVorbei.

Trial keys#

A key with exp is a hard end, meant for trials. After that day the state is abgelaufen. It is also abgelaufen for a version that was built after exp, whatever the clock says.

Origins#

Without the claim origins a key is valid on every address. With it, the key is valid on the listed origins and the state is falscherOrigin on others. An entry is https://karte.example.de: scheme, host and, if not the default, port. The wildcard * may stand only for the first label, as in https://*.example.de; it matches one or more labels to the left and not example.de itself. Scheme and port must match, and the default ports are dropped.

Development addresses are always accepted, and a page on one of them without a key is entwicklung:

localhost
127.0.0.1
[::1]
*.localhost
file: pages

In Node there is no origin and so no origin check.

The origin is a reminder, like the watermark, and not a lock: a page in a sandboxed frame reports the origin null, which counts as a development address.

The watermark#

The label says "vectorstream Pro · not licensed" in a corner of the map container of each editor that has Pro. It is a reminder, not a lock. There is none while the check runs, and none in an editor without a container. If something removes the label from the page, it is back after the next redraw; if a style hides it (for example display: none !important), it stays hidden. Anyone who can change the page can get rid of it. A valid key is what makes it disappear: with one, it is not created at all.