Reference

Concepts

Sigil follows a small model. Each item below is a page or a field in the portal and a claim the verifier checks.

Modeltext

account ──< application ──< signing key      (one active, one standby, any number retired)
   │              ├──< service token         (your backend's credential: scopes)
   │              └──< policy                (tier: entitlements, platforms, machines, lease, grace, term)
   │                      │                  key licences only
   └──< license >─────────┘                  (kind: key | instances, status, term)
            ├──< activation                  key: one machine (fingerprint, platform, label, last seen)
            └──< instance                    instances: where your product runs (platform, entitlements, lease)

events: append-only audit of all of the above

Account

Your organisation in Sigil, created the first time one of your staff signs in through conFIEL Auth. It holds the seat pool, which is the total number of machines your key licences may cover. A key licence for 2 machines allocates 2 seats, whether or not they are in use yet. Instance licences take no seats.

Application

One protected product, such as conFIEL Core. Each application has its own Ed25519 signing key, generated by Sigil and stored wrapped under a key-encryption key. Only the public half leaves Sigil, in the application's keyset at GET /v1/client/apps/:app/keys, which your build compiles in.

The standby key is published in the keyset but signs nothing. Every build you ship carries it, so it is the key Sigil can switch to without breaking anything in the field.

Rotation promotes the standby to active, retires the old active key and creates a new standby. Retired keys stay in the keyset so leases already in the field keep verifying. Builds that carry the promoted key keep working with no rebuild. A build older than that key refuses new leases with SIGIL_UNKNOWN_KEY. After a rotation, ship the new keyset with your next release.

Policy

A tier, and the template every license is issued from:

Field	Meaning	Checked by
Entitlements	Feature names a license unlocks, e.g. `split`, `cosign`. `*` grants all.	The verifier, per call
Platforms	`chrome-extension`, `server`, `browser`	The API at activation, and the verifier
Machines per license	Default seat count for licenses under this policy	The API, atomically
Lease	How long one lease is valid without renewing	The verifier (`exp`)
Grace	How long past `exp` the code still runs (status grace)	The verifier (`gr`)
Term	License lifetime from issuance; blank = perpetual. A hard stop with no grace.	The API and the verifier (`lex`)

Two kinds of licence

	Key licence	Instance licence
Held by	your customer	you
Redeemed with	a license key, typed into your product	a service token, held by your backend
A lease is	renewed per machine, at half-life	minted per use, short
Bound to	the machine's fingerprint	a value your backend and module both derive
Counts	machines, out of the seat pool	leases per instance and day; no machines, no seats
Fits	software sold per seat	a product whose own backend decides each use, such as conFIEL's Guardian

Instance

One place an instance licence's product runs, such as conFIEL's extension and guardian. It has a platform, entitlements, a longest lease and a grace. Every lease is minted for one instance and carries its platform and entitlements, so an extension lease can't unlock the server module and the reverse.

Service token

Your backend's credential for the service API: sgs_…, scoped to one application and to minting leases, revoking licences, or both. Shown once; Sigil keeps a hash and the last four characters. Revoke it in the portal.

License

A key licence is one customer's right to use an application under a policy. Its key looks like SGL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX: 125 random bits in Crockford base32. Lower case, spaces and the look-alikes I, L, O are accepted when typed. Sigil stores only a hash and the last group, so the key is shown once, at issuance.

A license is active, suspended (renewals refused, reversible) or revoked (renewals refused, seats returned to the pool, final).

Activation

One machine holding one of a license's seats. Activating the same machine again renews its seat rather than taking another. A seat is freed when the host deactivates, when you release it in the portal, or when the license is revoked. Activations are created online (POST /v1/client/activate) or, for air-gapped machines, by an admin issuing an offline lease from the machine's fingerprint.

Fingerprint

How a machine is named without being identified:

sigil-fp:v1text

fingerprint = base64url( SHA-256( "sigil-fp:v1:" ‖ app_id ‖ ":" ‖ raw_machine_id ) )

The raw id (the OS machine id, an install id, or anything stable your product chooses) never leaves the host. Scoping to the application means two vendors can't correlate one user's installs.

Lease

What the host hands your code: a compact JWS (EdDSA) signed by the application's key, naming the application, license, activation, machine fingerprint, platform, entitlements and time window. The verifier checks it offline before every protected call. Leases are short-lived (the policy's lease time) and the host renews them at half-life. That renewal is how revocation reaches an install. The protocol page specifies the format.

Platform

Where a lease may be used: chrome-extension, server (native programs, Node, Workers) or browser. A WASM module has no imports, so it can't look at its host itself; the host says which platform it is, and the lease must match. A server license pasted into an extension build is refused. This is a commercial boundary, not a cryptographic one, because the host controls what it reports.