# Licensebox

> Licensing and access control for native desktop, command-line and scientific applications.
> Licensebox manages access. Payments, billing and commercial arrangements remain outside Licensebox.

## Public starting points

- [Developer guide and searchable SDK catalog](https://licensebox.dev/docs#sdks)
- [Integration checklist](https://licensebox.dev/docs#integration)
- [Admin guide](https://licensebox.dev/docs/admin)
- [Shared contract and conformance suite](https://github.com/licensebox/protocol)

## Choose the official client

Use the client's actual language/runtime API and read its README before editing
an application. Native bindings can need the public C core and its platform
libraries. Package-registry publication is separate from GitHub source releases:
do not invent npm, PyPI, crates.io, Maven Central, NuGet or other registry availability.
Linux is the validated native profile where explicitly marked below. Other OS
and runtime paths require their own validation. An in-progress or source-preview
entry is not a completed production-support claim.

### Application languages

- [Go](https://github.com/licensebox/go#readme) — Linux validated. Go 1.27.1+; standard-library client. The separate administration CLI also lives here.
- [Python](https://github.com/licensebox/python#readme) — Linux validated. Python 3.10+ and cryptography.
- [JavaScript](https://github.com/licensebox/javascript#readme) — Linux validated. Node.js 22+. JavaScript API with TypeScript declarations.
- [TypeScript](https://github.com/licensebox/javascript#readme) — Linux validated. Node.js 22+. JavaScript API with TypeScript declarations.
- [Dart](https://github.com/licensebox/dart#readme) — Linux validated. Dart 3.3+, ffi, and the native C core. Native VM/AOT; no browser runtime.
- [Ruby](https://github.com/licensebox/ruby#readme) — Linux validated. Ruby 3.1+, Fiddle, and the native C core.
- [PHP](https://github.com/licensebox/php#readme) — Linux validated. PHP 8.2+, ext-ffi with ffi.enable=true, JSON, and the native C core.

### Native & systems

- [C](https://github.com/licensebox/c#readme) — Linux validated. C11, CMake 3.20+, OpenSSL 3, libcurl 7.85+, pkg-config and json-c.
- [C++](https://github.com/licensebox/cpp#readme) — Linux validated. C++17 and CMake. Builds on the public C client.
- [Rust](https://github.com/licensebox/rust#readme) — Linux validated. Rust 1.74+, serde_json, and the native C core.
- [Zig](https://github.com/licensebox/zig#readme) — Linux validated. Zig 0.14.1 and the native C core. Set LICENSEBOX_LIB_DIR and LICENSEBOX_INCLUDE_DIR for your C core installation.
- [Nim](https://github.com/licensebox/nim#readme) — Linux validated. Nim 1.6.14+, ARC memory management, threads, and the native C core.
- [D](https://github.com/licensebox/d#readme) — Linux validated. LDC 1.36+ / D 2.106+, DUB, and the native C core. Set LICENSEBOX_LIB_DIR and LICENSEBOX_INCLUDE_DIR for your C core installation.
- [Pascal](https://github.com/licensebox/pascal#readme) — Linux validated. Free Pascal 3.2.2 with FCL, and the native C core.
- [Swift](https://github.com/licensebox/swift#readme) — Linux validated. Swift 5.9+, Foundation, and the native C core. Linux profile validated. Set LICENSEBOX_LIB_DIR and LICENSEBOX_INCLUDE_DIR for your C core installation.
- [Objective-C](https://github.com/licensebox/objc#readme) — Linux validated. Clang, GNUstep/Foundation, and the native C core. The Linux SDK uses manual reference counting.

### JVM & .NET

- [Java](https://github.com/licensebox/java#readme) — Linux validated. Java 11+, JNA and Gson. Uses the Java SDK and native C core.
- [Kotlin](https://github.com/licensebox/java#readme) — Linux validated. Kotlin on the JVM, Java 11+, JNA and Gson. Uses the Java SDK and native C core.
- [Scala](https://github.com/licensebox/java#readme) — Linux validated. Scala on the JVM, Java 11+, JNA and Gson. Uses the Java SDK and native C core.
- [Clojure](https://github.com/licensebox/java#readme) — Linux validated. Clojure on the JVM, Java 11+, JNA and Gson. Uses the Java SDK and native C core.
- [C#](https://github.com/licensebox/dotnet#readme) — Linux validated. .NET 10 and the native C core. C#, F# and VB.NET share the managed assembly.
- [F#](https://github.com/licensebox/dotnet#readme) — Linux validated. .NET 10 and the native C core. C#, F# and VB.NET share the managed assembly.
- [Visual Basic .NET](https://github.com/licensebox/dotnet#readme) — Linux validated. .NET 10 and the native C core. C#, F# and VB.NET share the managed assembly.

### Scientific & numerical

- [Julia](https://github.com/licensebox/julia#readme) — Linux validated. Julia 1.12+, JSON3, and the native C core.
- [Fortran](https://github.com/licensebox/fortran#readme) — Linux validated. gfortran 13+, CMake 3.20+, and the native C core.
- [R](https://github.com/licensebox/r#readme) — Linux validated. R 4.3+, jsonlite, native development headers, and the C core.
- [GNU Octave](https://github.com/licensebox/octave#readme) — Linux validated. GNU Octave 8.4+, development headers, and the native C core.
- [MATLAB](https://github.com/licensebox/matlab#readme) — Linux validated. A licensed MATLAB runtime, MEX-compatible C compiler, and the native C core.
- [Wolfram Language](https://github.com/licensebox/wolfram#readme) — Source preview. A licensed Wolfram runtime with J/Link, Java 17+, JNA, Gson, and the native C core. Source preview. The full suite passed locally with Wolfram Engine 15.0 on Linux. Hosted CI checks the Java bridge only; a licensed runtime CI gate is still required for a stable release.

### Functional & BEAM

- [Haskell](https://github.com/licensebox/haskell#readme) — Linux validated. GHC 9.4+, Cabal, aeson 2+, and the native C core. Set LICENSEBOX_LIB_DIR and LICENSEBOX_INCLUDE_DIR for your C core installation.
- [OCaml](https://github.com/licensebox/ocaml#readme) — Linux validated. OCaml 4.14+, ocamlfind, Yojson, and the native C core.
- [Elixir](https://github.com/licensebox/beam#readme) — Linux validated. Erlang/OTP 25+, Jiffy, a C compiler, and the C core. Elixir additionally needs Elixir 1.14+.
- [Erlang](https://github.com/licensebox/beam#readme) — Linux validated. Erlang/OTP 25+, Jiffy, a C compiler, and the C core. Elixir additionally needs Elixir 1.14+.

### Scripting & legacy

- [Lua](https://github.com/licensebox/lua#readme) — Linux validated. LuaJIT FFI, LuaRocks configured for Lua 5.1 with development headers, lua-cjson, and the native C core. Standard PUC Lua is unsupported.
- [Perl](https://github.com/licensebox/perl#readme) — Linux validated. Perl 5.20+, a C compiler for the XS extension, and the C core.
- [Tcl](https://github.com/licensebox/tcl#readme) — Linux validated. Tcl 8.6, Tcllib JSON, development headers, and the native C core.
- [PowerShell](https://github.com/licensebox/powershell#readme) — Linux validated. PowerShell 7.4+ on Linux and the native C core. Imports an actual P/Invoke module.
- [COBOL](https://github.com/licensebox/cobol#readme) — Linux validated. GnuCOBOL 3.1.2+, a C compiler, and the native C core. Set LICENSEBOX_LIB_DIR to the installed C core library directory before building.

### CLI & WebAssembly

- [Shell / application CLI](https://github.com/licensebox/cli#readme) — Linux validated. Linux, a POSIX shell, CMake, C compiler, json-c, and the native C core. Application licensing CLI. Product administration is a separate Go CLI.
- [WebAssembly / WASI](https://github.com/licensebox/wasm#readme) — Linux validated. Wasmtime and the pinned Python host SDK on Linux. A trusted native host owns licensing. Host-assisted only: validated with Wasmtime and a native Linux host. Standalone browser identity is not provided.

## Integration instructions for coding agents

1. Read this guide, https://licensebox.dev/docs#integration and the selected SDK's
   current README, release status and runtime requirements. Inspect the project.
2. Ask for missing product ID, module names, signing-key IDs and trusted PUBLIC
   verification keys. Never request private signing keys, admin tokens, leases,
   private device codes, access links or user records.
3. Retain one client per process. Present email device sign-in in the application's
   UI. Require the protected module before loading user files or starting protected
   work. A local status query or usage record does not authorize work.
4. Respect renewal, offline expiry and explicit policy errors. Keep grants, trials,
   machine seats and location rules on the server. Close clients where required.
5. Add meaningful integration checks. Use heartbeat only when explicitly requested by the application. Do not claim GPS,
   hardware attestation or standalone browser-native identity. WASM/WASI needs
   its explicitly trusted native host; the guest does not supply identity.
6. For shell integration, use the application licensing CLI and check `require`
   exit status. The separate Go administration CLI manages products and grants;
   it is not the application licensing executable. Keep admin credentials out of apps.

All complete clients offer protected module checks, leases, local status, explicit
sign-in, logout, module discovery, requests, private access links and opt-in fixed
command usage. Use the selected SDK's exact method names, ownership and cleanup rules.

Before changing SDK behavior, read the shared protocol AGENTS.md and MAINTAINING.md.
Add a shared regression first, port affected clients, pass conformance, then update
the compatibility map. Sync workflows propose tested pins; they do not translate
arbitrary implementation changes or publish packages.

## Go integration example

Install with `go get licensebox.dev/client`. Import `licensebox.dev/client` and
`licensebox.dev/lease`. Create one client per product/process:

```go
lic, err := client.New(client.Config{
    Product: "YOUR_PRODUCT_ID",
    Keys: lease.Keys{"YOUR_KEY_ID": lease.MustKey("YOUR_PUBLIC_KEY")},
    Version: version,
})
if err != nil { return err }
if _, err := lic.Require(ctx, "YOUR_MODULE"); err != nil { return err }
// Perform the operation only after Require succeeds.
```

Replace placeholders with the administrator-provided product ID, key ID and
public key. Never embed a signing private key, admin token, or installation key.
Check every protected entry point before loading or processing user data.

## Identity, leases and offline use

- The first protected use starts an email device-code sign-in. The browser can
  be on a different device; the licensed installation is the app requesting it.
- The SDK creates an Ed25519 installation key, with private files restricted to
  the local OS user. Default folder: os.UserConfigDir()/licensebox/<product>.
  Files include install.key and lease. Dir can override this folder.
- Protocol v2 binds each signed lease to both the installation public key and
  a native machine binding. The SDK derives the binding from OS/firmware identity
  using a product-scoped HMAC; raw identifiers are never transmitted or stored.
  It checks the binding before renewal AND offline use. Copying the entire
  credential directory to another ordinary machine is refused. Explicit SignIn
  activates it with a fresh installation key and transfers the seat if needed.
- Native sources: Linux DMI/device-tree where readable, otherwise machine-id;
  Windows SMBIOS system UUID; macOS IOPlatformUUID. No random, hostname, IP or MAC
  fallback exists. Missing identity fails closed. Routine network, RAM and OS
  updates do not form part of the fingerprint. Changing the native identity or
  its availability can require reactivation. Cloned/spoofed firmware or system
  IDs remain a limitation: do not claim hardware attestation or GPS verification.
- Replacing the installation key on the same host replaces that host's seat;
  it does not consume another one. Machine revocation also follows the native
  binding, so deleting credentials alone does not bypass it.
- A v1 lease or client is unsupported. An updated client requires one activation
  to receive a v2 lease. Consult the selected repository and shared contract for current release versions.
- Each new process silently attempts renewal, bounded to three seconds. Within
  a process the fresh lease is reused until it expires. An expired lease may
  renew without another email code, provided the installation remains permitted.
- Default offline allowance is 24 hours after successful renewal, shortened by
  an earlier grant expiry. Expiry requires connectivity, not another email code.
- Explicit server denials must not be treated as network failures or bypassed
  with a cached lease. The SDK retains seat/location refusals until successful
  renewal or explicit sign-in. Show their errors to the user.
- Offline clients cannot learn about a transfer, revocation or location change
  until they contact the server or their lease expires. A successful lease check
  at command start does not add a background heartbeat to long-running jobs.

## Optional heartbeats

- Heartbeat(module) explicitly forces a bounded renewal even with a fresh cached
  lease, returning the verified lease and online/offline contact status. It never
  activates an identity, creates a missing key or starts an email sign-in.
- Go, Python and Node offer explicit monitor helpers; other clients use their
  application's timer/event loop. No monitor starts implicitly. Stop/close it
  when the task finishes and follow the SDK's exact runtime ownership rules.
- Monitors signal cancellation/failure independently of stalled network calls.
  Applications own safe checkpoints and shutdown. Never kill a process or lose
  work merely to enforce licensing.
- Admin heartbeat.interval_seconds (30..86400) and grace_seconds (interval..
  31536000) are off by default (zero/zero). Enabled leases expire within the
  grace period or an earlier offline/grant limit. A failed contact never extends
  this deadline, and explicit refusals never use cached offline access.

## Machine and location policies

Policies belong in Licensebox, not duplicated in individual products.

- machine_limit is the number of allocated installations per user/product.
  Zero explicitly means unrestricted. Products with no previous policy migrate
  to one seat. One means a single seat.
- A completed sign-in allocates that installation. At capacity it replaces the
  oldest allocation. Silent renewal never transfers a seat. A displaced machine
  must explicitly sign in to transfer it back. Admin revocation remains separate.
- locations.allow is a union of allowed areas; empty means everywhere.
  locations.block excludes areas and takes precedence over allow.
- Areas are country codes, cities scoped to a country, or latitude/longitude
  plus radius_km. The server uses trusted Cloudflare request.cf metadata from
  the APP's connection, not browser coordinates or client-controlled headers.
- IP geolocation is approximate and reflects VPN/proxy exits. Missing metadata
  needed to decide a configured rule is refused. Offline movement cannot be
  detected until the next online check.
- In admin forms/CLI, use one area per line or semicolon: `AT`, `AT | Vienna`,
  or `48.2082,16.3738 | 80` (an 80 km radius). Blank lists remove restrictions.

Example admin settings JSON (preserve other settings when updating):
```json
{"machine_limit":1,"locations":{"allow":[{"country":"AT"}],"block":[{"country":"AT","city":"Vienna"}]}}
```

## Go SDK calls and errors

- Require(ctx, module): authorize a module; return errors before doing work.
- Lease(ctx): obtain or silently renew the installation's lease.
- Status(): inspect local state only; it does not contact Licensebox.
- SignIn(ctx): explicitly sign in, switch account, or transfer a seat back.
- Logout(): remove local licence state; keep the installation identity.
- Modules(ctx), RequestAccess(ctx, modules, note), Requests(ctx): discover
  modules and request administrator approval. Never grant access locally.
- AccessLink(ctx): short-lived private browser link for requesting access;
  treat it as a credential and never publish it.
- Record(command, ok, elapsed): count command names, results and durations
  when enabled. Never send geometry, files, arguments, paths or user data.
- Handle ErrOffline, ErrRevoked, ErrDenied, ErrSeatTransferred and
  ErrLocationDenied and ErrMachineChanged. ModuleError identifies a missing module. PolicyError
  distinguishes seat_transferred, location_denied and location_unknown.

## Implementing another language client

Use the full protocol at https://licensebox.dev/docs#http. API paths retain /v1;
lease payloads and signature-domain messages use v2. Device requests prove
the installation key and native binding; token polling is also signed. Subsequent
  calls sign the request kind, lease, binding, timestamp
and payload together. Verify signed leases against the product's trusted public
keys, product ID, machine key, current native binding and expiry. Do not implement an unsigned shortcut.
Never accept a lease merely because its JSON parses.

## Administration

Use https://licensebox.dev/admin or `go install licensebox.dev/cmd/licensebox@latest`.
Admins can create products, grant modules, answer requests, set machine/location
policies and revoke users or machines. Changing settings replaces the settings
object: first fetch it and preserve unrelated fields. CLI product updates do this.
Signing-key rotation requires shipping the new public key before retiring the old.

Do not paste real admin tokens, private keys, user records, usage reports, sign-in
codes, or access links into prompts. This public guide contains no account data.