Expand description
§tamga
Official Rust SDK for Tamga — license activation, offline verification, and machine management for Rust applications.
§Shape
A single client::Client built from a client::ClientConfig exposes every
server endpoint (validate, check-in, checkout, machine management,
components/processes, entitlements, offline proof) as an async method. In
addition, standalone verification functions in checkout and proof
work with no network access at all once the relevant public key
material is embedded in the application — this offline-verification path
is the core value proposition of this SDK over hand-rolling HTTP calls.
§Offline files are format v2 only
checkout::license_file::verify_license_file and
checkout::machine_file::verify_machine_file accept only an alg
ending in +v2 and enforce the signed exp claim against the same 60
second clock-skew tolerance, reporting
error::CheckoutError::Expired for a file that has simply run out. A
v1-issued .lic or .mach file is rejected outright — there is no
fallback path. See checkout::license_file for why, and
checkout::machine_file for the two places the .mach wire format
differs (a three-field alg, and a dot-separated encrypted enc).
Pass a server-derived timestamp to
checkout::license_file::verify_license_file_at or
checkout::machine_file::verify_machine_file_at rather than trusting a
local clock the user can wind back.
§Signing-key rotation
Verifying against one embedded public key cannot distinguish a file signed
before the account rotated its key from a forged one — both fail
identically. Verify through a checkout::key_set::SigningKeySet instead
and the two become distinct outcomes:
error::CheckoutError::UnknownSigningKey (refresh the keys) versus
error::CryptoError::VerificationFailed (refuse the file). Build the set
from the account’s published key history with Client::signing_key_set,
or with no network at all from keys pinned in the binary via
checkout::key_set::SigningKeySet::from_public_keys — the kid a file
names is computable locally with crypto::ed25519::key_id.
Two limits: a raw licence key gets 403 from GET /signing-keys (the
route needs account.read, which Role::LicenseToken does not hold), and
only Ed25519-signed files are covered.
§Rate limiting
The server does return 429 Too Many Requests. It surfaces as
error::TamgaError::RateLimited carrying the parsed Retry-After and
the response’s x-ratelimit-* budget headers
(transport::RateLimitInfo); safe requests are retried automatically
first — see client::ClientConfigBuilder::max_retries. Note
x-ratelimit-reset is an absolute Unix timestamp, not a delay.
§Auth
Auth is enforced on every endpoint: a missing or unrecognized credential
is 401, a valid-but-insufficient one 403. Authenticating with a raw
licence key (transport::AuthTransport::License) additionally requires
the licence’s policy to set authentication_strategy to LICENSE or
MIXED. That column defaults to 'TOKEN', under which every
licence-key request is refused with 401 LICENSE_NOT_ALLOWED — a
provisioning precondition, not a transient failure. See
error::LicenseAuthCode.
§Known server-side gaps
Modelled here but not fully live server-side today:
- Only 19 of the 24
models::validation::ValidationCodevariants are reachable;NOT_FOUND,BANNED,COMPONENTS_SCOPE_MISMATCH,CHECKSUM_SCOPE_MISMATCHandVERSION_SCOPE_MISMATCHare declared for forward-compatibility. models::validation::ScopeObject’sversionandchecksumfields are refused by the server (422 SCOPE_NOT_SUPPORTEDfails the whole validate call), so this crate never sends them. Its other six fields,entitlementsandfingerprintincluded, are enforced.GET /licenses/{id}/entitlementsignorespage[after]: the listing is capped bylimit(max 100) and cannot be paginated past it. Seeclient::Client::list_entitlements.- Freshly created policies report
"DENY_ACCESS"/"NO_RESURRECTION"— neither is a real variant. Seemodels::policyfor how this crate normalizes them. GET /licenses/{id}andGET /licenses/{id}/policyare not licence-scoped server-side: unlike validate and check-out they never call the server’srequire_license_scope, so a licence key reads any licence in the account,attributes.keyin plaintext included. This crate exposes both routes because a client needs its own policy to size a heartbeat interval; it cannot narrow what the server returns, and does not claim to.GET /releases/actions/upgradeanswers204 No Contentfor two different situations and deliberately does not distinguish them — seeclient::UpgradeCheck::NoUpdateOffered.policies.check_in_intervalstoresdaily/weekly/monthly/yearly(aCHECKconstraint admits nothing else), while the server’s own overdue calculation matches onday/week/month/yearand so always falls through to its 30-day default. Both spellings decode here; seemodels::policy::CheckInInterval.- The machine collection is the one offset-paginated route this crate
calls; every other listing is keyset. See
models::page. - Both checkout handlers compute a file’s
kidclaim from the account’s Ed25519 public key whatever scheme actually signed the bytes, and rotation only ever mints Ed25519 keys, sokidis meaningful for Ed25519-signed files only. Seecheckout::key_set.
§Artifacts and the download redirect
Role::LicenseToken already held artifact.read, so
Client::list_release_artifacts and Client::get_artifact were
always reachable with a licence key. The blocked half was fetching the
bytes: the server granted artifact.download to that role only recently,
and until then Client::artifact_download_url would have been 403.
Create, update, delete and upload are not modelled — those
permissions are absent from the role, so a licence key cannot reach
them.
The download action answers 303 See Other to a short-lived presigned
storage URL by default. This crate never lets that redirect be followed
with a credential attached: it sends ?redirect=false and issues the
request on a redirect-disabled client, then hands back the URL for an
unauthenticated fetch. Client::download_artifact does that fetch
and takes a required max_bytes ceiling, since the server admits uploads
up to 1 GiB. Treat the presigned URL as a bearer capability and keep it
out of logs.
A 403 from the download action is not necessarily an auth problem: it
enforces the owning release’s access gate (distribution strategy,
suspension, expiry, entitlement) on top of the permission, so a CLOSED
release’s binary is refused to a caller in perfect standing. The listing
and show routes do not apply that gate, so metadata reading while the
download is refused is the expected shape of it.
§Fingerprints
The server stores fingerprint TEXT NOT NULL with no normalisation,
unique per (license_id, fingerprint) — so "ABC-123", "abc-123" and
" ABC-123 " are three machines on three seats.
fingerprint::compute canonicalizes caller-chosen labelled components
into one stable string first. It reads no hardware identifiers — what
identifies a machine is a product decision — and it deliberately performs
no Unicode normalisation, because a rule the eight Tamga SDKs cannot
implement identically would yield two fingerprints for one machine
depending on which SDK the application used.
§Heartbeat scheduling
This crate ships no heartbeat scheduler — starting a background task on a
caller’s behalf is a decision that belongs to the embedding application.
It does supply the number that task needs:
client::Client::effective_heartbeat_window reads
policy.heartbeat_duration off the licence’s policy, and
client::Client::recommended_heartbeat_interval divides it by
models::policy::HEARTBEAT_INTERVAL_DIVISOR. Do not derive an interval
from next_heartbeat_at on a ping response: that field is computed
against the 600s fallback on precisely the routes a scheduler calls.
Re-exports§
pub use client::Client;pub use client::ClientConfig;pub use error::TamgaError;
Modules§
- checkout
- PEM-envelope parsing and verification orchestration for offline checkout
files. Owns the file format; delegates actual cryptography to
src/crypto/. - client
ClientandClientConfig— the single home for every endpoint method.- crypto
- Cryptographic primitives only — no HTTP, no PEM parsing, no protocol
knowledge.
src/checkout/owns the PEM-envelope format and orchestrates calls into this module. - error
TamgaError,JsonApiError, and typed per-endpoint error codes.- fingerprint
- Canonicalise a machine fingerprint before sending it to the server.
- models
- Wire models for every JSON:API resource and value type this SDK exchanges with the server.
- proof
- Machine offline proof — generation call, byte-exact serialization, and RSA-PKCS1v1.5 verification.
- transport
- Auth transports, request/response headers, and content-type handling.