tamga 0.2.4

Official Rust SDK for Tamga. Integrate license activation, offline verification, and machine management into your Rust applications.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
//! `TamgaError`, `JsonApiError`, and typed per-endpoint error codes.
//!
//! - [`JsonApiError`]: `{ id, status, code, title, detail, source: { pointer } }`
//!   mirroring the server's JSON:API error envelope.
//! - [`TamgaError`]: the top-level enum, wrapping transport failures
//!   (`Http`, `Json`), the generic `Api` fallback, one typed variant per
//!   server error code the SDK's endpoints can produce, and the offline
//!   verification errors [`CheckoutError`] and [`ProofError`] (both of which
//!   in turn wrap [`CryptoError`]).
//! - Consumers should match errors on `code` (stable) rather than `detail`
//!   (human text, may change).
//! - Fixed-status codes: `NOT_FOUND` (404), `UNAUTHORIZED` (401),
//!   `FORBIDDEN` (403), `INTERNAL_SERVER_ERROR` (500, generic — never leaks
//!   DB detail).
//! - Per-endpoint codes: `FINGERPRINT_TAKEN`, `PID_TAKEN` (409 conflicts);
//!   `CHECK_IN_NOT_REQUIRED`, `TTL_INVALID`, `LICENSE_NOT_ENCRYPTED`,
//!   `LICENSE_KEY_MISSING`, `SCHEME_NOT_SUPPORTED`, `DATASET_INVALID` (422
//!   validation failures). Any other code falls through to
//!   [`TamgaError::Api`].
//! - `429 TOO_MANY_REQUESTS` is live. Credential-accepting endpoints (session
//!   creation, password reset, licence-key validation, token minting) run on a
//!   tight per-IP budget — 5 requests/second by default — which a heartbeat
//!   timer reaches easily. It maps to [`TamgaError::RateLimited`], which
//!   carries the server's parsed `Retry-After`; safe requests are retried
//!   automatically first (see
//!   [`crate::client::ClientConfigBuilder::max_retries`]).
//! - `CHECK_IN_NOT_REQUIRED` (422) is a **caller error**, not something to
//!   retry — callers should check `require_check_in` on the license's
//!   policy before scheduling periodic check-ins.

/// Top-level SDK error type.
///
/// Consumers should match on the wrapped [`JsonApiError::code`] (stable)
/// rather than [`JsonApiError::detail`] (human text, may change) — see
/// module doc comment.
///
/// Offline verification failures arrive as [`TamgaError::Checkout`] or
/// [`TamgaError::Proof`]; neither carries a `CryptoError` directly, since
/// both of those wrap it.
#[derive(Debug, thiserror::Error)]
pub enum TamgaError {
    /// Underlying HTTP transport error (connection, timeout, TLS, or
    /// malformed request such as an invalid `User-Agent`/timeout value).
    #[error("HTTP transport error: {0}")]
    Http(#[from] reqwest::Error),
    /// Response body could not be parsed as the expected JSON shape.
    #[error("failed to parse response body: {0}")]
    Json(#[from] serde_json::Error),
    /// Server returned a non-2xx status with a JSON:API error body whose
    /// `code` doesn't have a more specific typed variant below. Boxed —
    /// `JsonApiError` carries several owned `String`s, and clippy's
    /// `result_large_err` flags an unboxed variant here as bloating every
    /// `Result<T, TamgaError>` return slot across the crate.
    #[error("API error {code}: {detail}", code = .0.code, detail = .0.detail)]
    Api(Box<JsonApiError>),
    /// The server answered `429 Too Many Requests` and the retry budget was
    /// exhausted (or the request was not safe to repeat).
    ///
    /// `retry_after` is the server's `Retry-After` in seconds when it sent
    /// one. Wait at least that long before trying again.
    #[error("rate limited by the server{}", match retry_after {
        Some(s) => format!("; retry after {s}s"),
        None => String::new(),
    })]
    RateLimited {
        /// Server-supplied `Retry-After`, in seconds.
        retry_after: Option<u64>,
    },
    /// `422 CHECK_IN_NOT_REQUIRED` — a **caller error**, not something to
    /// retry. Callers should check `require_check_in` on the license's
    /// policy before scheduling periodic check-ins, rather than reacting to
    /// this error with retry logic.
    #[error("check-in not required: {detail}", detail = .0.detail)]
    CheckInNotRequired(Box<JsonApiError>),
    /// A `.lic`/`.mach` offline file failed to parse or verify — see
    /// [`CheckoutError`] for the specific stage that failed.
    #[error(transparent)]
    Checkout(#[from] CheckoutError),
    /// `422 LICENSE_NOT_ENCRYPTED` — the server rejected an `encrypt: true`
    /// checkout request because the license has no `key` set. A caller
    /// error: check that the license has a key before requesting an
    /// encrypted checkout.
    #[error("license not encrypted: {detail}", detail = .0.detail)]
    LicenseNotEncrypted(Box<JsonApiError>),
    /// `422 LICENSE_KEY_MISSING` — the server rejected an `encrypt: true`
    /// machine checkout because the machine's license has no `key` set.
    /// Distinct API error code from `LICENSE_NOT_ENCRYPTED` (license file
    /// checkout's equivalent) despite the similar meaning.
    #[error("license key missing: {detail}", detail = .0.detail)]
    LicenseKeyMissingApi(Box<JsonApiError>),
    /// `422 TTL_INVALID` — the server rejected a `ttl` outside `(0,
    /// 31536000]`. The SDK also pre-checks this client-side (see
    /// [`crate::checkout::machine_file::check_ttl`]) so this variant is
    /// normally only reachable if the client-side check was bypassed.
    #[error("ttl invalid: {detail}", detail = .0.detail)]
    TtlInvalidApi(Box<JsonApiError>),
    /// `422 SCHEME_NOT_SUPPORTED` — the server rejected a machine checkout
    /// because the license's scheme is `RSA_2048_JWT_RS256`.
    #[error("scheme not supported: {detail}", detail = .0.detail)]
    SchemeNotSupportedApi(Box<JsonApiError>),
    /// `409 FINGERPRINT_TAKEN` — a machine (or component) with this
    /// fingerprint already exists on this license.
    #[error("fingerprint taken: {detail}", detail = .0.detail)]
    FingerprintTaken(Box<JsonApiError>),
    /// `422 DATASET_INVALID` — `meta.dataset` sent to
    /// `generate_offline_proof` wasn't a JSON object (arrays/scalars are
    /// rejected).
    #[error("dataset invalid: {detail}", detail = .0.detail)]
    DatasetInvalid(Box<JsonApiError>),
    /// `409 PID_TAKEN` — a process with this PID already exists on this
    /// machine.
    #[error("pid taken: {detail}", detail = .0.detail)]
    PidTaken(Box<JsonApiError>),
    /// A `"v1x0."` offline proof failed to parse or verify — see
    /// [`ProofError`].
    #[error(transparent)]
    Proof(#[from] ProofError),
    /// `404 NOT_FOUND` — the requested resource doesn't exist (or doesn't
    /// belong to this account).
    #[error("not found: {detail}", detail = .0.detail)]
    NotFound(Box<JsonApiError>),
    /// `401 UNAUTHORIZED` — missing or invalid credentials. Not currently
    /// reachable on the license/machine endpoints this crate calls (see
    /// module doc comment — auth isn't enforced there yet), but modeled
    /// for forward-compatibility and any endpoint where it already applies.
    #[error("unauthorized: {detail}", detail = .0.detail)]
    Unauthorized(Box<JsonApiError>),
    /// `403 FORBIDDEN` — credentials valid, but not permitted for this
    /// operation.
    #[error("forbidden: {detail}", detail = .0.detail)]
    Forbidden(Box<JsonApiError>),
    /// `500 INTERNAL_SERVER_ERROR` — generic server-side failure. The
    /// server never leaks DB/internal detail into `detail` for this code —
    /// don't expect this to be more specific than "something went wrong."
    #[error("internal server error: {detail}", detail = .0.detail)]
    InternalServerError(Box<JsonApiError>),
}

/// Failures while parsing or verifying a machine offline proof string
/// (`"v1x0.<base64 signature>"`) — see `src/proof.rs`'s module doc comment
/// for the full verification flow this maps onto.
#[derive(Debug, thiserror::Error)]
pub enum ProofError {
    /// Input didn't start with the expected `"v1x0."` prefix.
    #[error("malformed proof: missing v1x0. prefix")]
    MalformedProof,
    /// The signature portion (after the prefix) wasn't valid base64.
    #[error("invalid base64 in proof signature")]
    InvalidBase64,
    /// Signature verification itself failed — see [`CryptoError`].
    #[error(transparent)]
    Crypto(#[from] CryptoError),
}

/// Cryptographic primitive failures — signature verification, decryption,
/// or malformed key/signature material. Never distinguishes *why* a
/// verification failed beyond this coarse granularity (e.g. "wrong key" vs
/// "tampered ciphertext" both surface as [`CryptoError::DecryptionFailed`])
/// — a more specific error would leak information useful to an attacker
/// probing for valid inputs.
#[derive(Debug, Clone, Copy, thiserror::Error, PartialEq, Eq)]
pub enum CryptoError {
    /// Public key bytes are malformed or the wrong length for the scheme.
    #[error("invalid public key")]
    InvalidKey,
    /// Signature bytes are malformed or the wrong length for the scheme.
    #[error("invalid signature encoding")]
    InvalidSignature,
    /// Signature verification failed — wrong key, tampered message, or both.
    #[error("signature verification failed")]
    VerificationFailed,
    /// AEAD decryption failed — wrong key, tampered ciphertext, or tampered
    /// tag. AES-GCM inherently cannot distinguish these.
    #[error("decryption failed (wrong key or tampered ciphertext)")]
    DecryptionFailed,
}

/// Failures while parsing or verifying a `.lic`/`.mach` offline checkout
/// file — see `src/checkout/license_file.rs`'s module doc comment for the
/// full verification flow this maps onto.
#[derive(Debug, thiserror::Error)]
pub enum CheckoutError {
    /// Input didn't start/end with the expected `-----BEGIN ... -----`/
    /// `-----END ... -----` PEM markers.
    #[error("malformed PEM envelope: missing BEGIN/END markers")]
    MalformedPem,
    /// The PEM body, or the `enc`/`sig` fields inside it, wasn't valid
    /// base64.
    #[error("invalid base64 in certificate payload")]
    InvalidBase64,
    /// The decoded PEM body wasn't valid `{ enc, sig, alg }` JSON, or the
    /// decrypted/decoded payload wasn't valid `{"data": ...}` JSON.
    #[error("invalid JSON in certificate payload: {0}")]
    InvalidJson(#[from] serde_json::Error),
    /// `alg` wasn't one of the two license-file values this SDK
    /// understands (`"base64+ed25519+v2"`, `"aes-256-gcm+ed25519+v2"`).
    ///
    /// A v1 file (no `+v2` suffix) lands here too, and that is deliberate:
    /// v1 carried no expiry inside the signature, so accepting one would
    /// hand back the permanent-file problem v2 exists to close.
    #[error("unsupported algorithm: {0}")]
    UnsupportedAlgorithm(String),
    /// The file's signed `exp` claim is in the past.
    ///
    /// The signature was valid — this is an authentic file that has simply
    /// run out. Re-check out to get a fresh one.
    #[error("license file expired at unix timestamp {exp}")]
    Expired {
        /// The `exp` claim, seconds since the Unix epoch.
        exp: i64,
    },
    /// The file's `alg` requires decryption but no `license_key` was
    /// supplied to the verify call.
    #[error("license key is required to decrypt an encrypted checkout file")]
    LicenseKeyMissing,
    /// The file's `alg` requires decryption but no `fingerprint` was
    /// supplied to [`crate::checkout::machine_file::verify_machine_file`]
    /// (machine files, unlike license files, need both the license key
    /// *and* the target machine's fingerprint to decrypt).
    #[error("machine fingerprint is required to decrypt an encrypted machine file")]
    FingerprintMissing,
    /// `RSA_2048_JWT_RS256` was passed as the verification scheme for a
    /// `.mach` file — this scheme is not supported for machine file
    /// checkout (the server itself rejects generating one with `422
    /// SCHEME_NOT_SUPPORTED`); rejected up front, before any parsing.
    #[error("scheme not supported for machine file checkout: RSA_2048_JWT_RS256")]
    SchemeNotSupported,
    /// Client-side pre-check failure: `ttl` must be `> 0` and
    /// `<= 31536000` (365 days) — mirrors the server's own validated range
    /// (`422 TTL_INVALID`), checked before the round trip.
    #[error("ttl out of range: {0}")]
    TtlOutOfRange(String),
    /// Signature verification or decryption itself failed — see
    /// [`CryptoError`].
    #[error(transparent)]
    Crypto(#[from] CryptoError),
}

impl TamgaError {
    /// Maps a parsed [`JsonApiError`] to its most specific [`TamgaError`]
    /// variant, falling back to the generic [`TamgaError::Api`] for any
    /// `code` without a dedicated variant. Single dispatch point: a newly
    /// typed code needs a match arm here, not a new call site at every
    /// endpoint method.
    pub(crate) fn from_json_api_error(err: JsonApiError) -> Self {
        match err.code.as_str() {
            "CHECK_IN_NOT_REQUIRED" => TamgaError::CheckInNotRequired(Box::new(err)),
            "LICENSE_NOT_ENCRYPTED" => TamgaError::LicenseNotEncrypted(Box::new(err)),
            "LICENSE_KEY_MISSING" => TamgaError::LicenseKeyMissingApi(Box::new(err)),
            "FINGERPRINT_TAKEN" => TamgaError::FingerprintTaken(Box::new(err)),
            "PID_TAKEN" => TamgaError::PidTaken(Box::new(err)),
            "NOT_FOUND" => TamgaError::NotFound(Box::new(err)),
            "UNAUTHORIZED" => TamgaError::Unauthorized(Box::new(err)),
            "FORBIDDEN" => TamgaError::Forbidden(Box::new(err)),
            "INTERNAL_SERVER_ERROR" => TamgaError::InternalServerError(Box::new(err)),
            "DATASET_INVALID" => TamgaError::DatasetInvalid(Box::new(err)),
            "TTL_INVALID" => TamgaError::TtlInvalidApi(Box::new(err)),
            "SCHEME_NOT_SUPPORTED" => TamgaError::SchemeNotSupportedApi(Box::new(err)),
            _ => TamgaError::Api(Box::new(err)),
        }
    }
}

/// A single JSON:API error object, matching the server's own error type
/// field-for-field. The server always wraps
/// these in a top-level `{ "errors": [...] }` array; this SDK surfaces only
/// the first element via [`TamgaError::Api`] — every endpoint this crate
/// calls returns at most one error per response today.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct JsonApiError {
    /// Server-generated UUIDv7, unique per error occurrence — useful to
    /// correlate with server-side logs alongside `X-Request-Id`.
    pub id: String,
    /// HTTP status code, as a string (JSON:API convention), e.g. `"404"`.
    pub status: String,
    /// Stable, machine-matchable code, e.g. `"NOT_FOUND"`,
    /// `"FINGERPRINT_TAKEN"`, `"CHECK_IN_NOT_REQUIRED"`. Match on this, not
    /// `detail`.
    pub code: String,
    /// Short, human-readable summary of the error type.
    pub title: String,
    /// Human-readable, request-specific explanation. May change wording
    /// across server versions — not stable for programmatic matching.
    pub detail: String,
    /// Present for validation errors (`422`) — points at the offending
    /// request body field via a JSON Pointer.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source: Option<JsonApiErrorSource>,
}

/// `source.pointer` on a [`JsonApiError`] — a JSON Pointer (RFC 6901) into
/// the request body identifying the field that failed validation.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct JsonApiErrorSource {
    /// e.g. `"/data/attributes/key"`.
    pub pointer: Option<String>,
}

/// Top-level JSON:API error document: `{ "errors": [ ... ] }`. Internal —
/// only [`TamgaError::Api`]'s single [`JsonApiError`] is exposed publicly.
#[derive(Debug, Clone, serde::Deserialize)]
pub(crate) struct JsonApiErrorDocument {
    pub errors: Vec<JsonApiError>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn deserializes_representative_error_body() {
        let json = serde_json::json!({
            "errors": [{
                "id": "01926b3e-0000-7000-8000-000000000000",
                "status": "404",
                "code": "NOT_FOUND",
                "title": "Not Found",
                "detail": "The requested license was not found",
                "source": null,
            }]
        });
        let doc: JsonApiErrorDocument = serde_json::from_value(json).unwrap();
        assert_eq!(doc.errors.len(), 1);
        assert_eq!(doc.errors[0].code, "NOT_FOUND");
        assert_eq!(doc.errors[0].status, "404");
    }

    #[test]
    fn maps_check_in_not_required_code_to_typed_variant() {
        let err = JsonApiError {
            id: "01926b3e-0000-7000-8000-000000000000".to_string(),
            status: "422".to_string(),
            code: "CHECK_IN_NOT_REQUIRED".to_string(),
            title: "Unprocessable Entity".to_string(),
            detail: "this license's policy does not require check-in".to_string(),
            source: None,
        };
        let mapped = TamgaError::from_json_api_error(err);
        assert!(matches!(mapped, TamgaError::CheckInNotRequired(_)));
    }

    #[test]
    fn unrecognized_code_maps_to_generic_api_variant() {
        let err = JsonApiError {
            id: "01926b3e-0000-7000-8000-000000000000".to_string(),
            status: "429".to_string(),
            code: "TOO_MANY_REQUESTS".to_string(),
            title: "Too Many Requests".to_string(),
            // Not modeled: the server declares this code but never
            // constructs/returns it today (see CLAUDE.md's GOTCHAS) — a
            // genuinely code-without-a-dedicated-variant example, unlike
            // NOT_FOUND/etc. which now have their own typed variants.
            detail: "rate limited".to_string(),
            source: None,
        };
        let mapped = TamgaError::from_json_api_error(err);
        assert!(matches!(mapped, TamgaError::Api(_)));
    }

    #[test]
    fn fixed_status_codes_map_to_their_typed_variants() {
        let build = |code: &str| JsonApiError {
            id: "01926b3e-0000-7000-8000-000000000000".to_string(),
            status: "0".to_string(),
            code: code.to_string(),
            title: "".to_string(),
            detail: "".to_string(),
            source: None,
        };
        assert!(matches!(
            TamgaError::from_json_api_error(build("NOT_FOUND")),
            TamgaError::NotFound(_)
        ));
        assert!(matches!(
            TamgaError::from_json_api_error(build("UNAUTHORIZED")),
            TamgaError::Unauthorized(_)
        ));
        assert!(matches!(
            TamgaError::from_json_api_error(build("FORBIDDEN")),
            TamgaError::Forbidden(_)
        ));
        assert!(matches!(
            TamgaError::from_json_api_error(build("INTERNAL_SERVER_ERROR")),
            TamgaError::InternalServerError(_)
        ));
    }

    #[test]
    fn deserializes_error_with_source_pointer() {
        let json = serde_json::json!({
            "errors": [{
                "id": "01926b3e-0000-7000-8000-000000000000",
                "status": "422",
                "code": "DATASET_INVALID",
                "title": "Unprocessable Entity",
                "detail": "dataset must be an object",
                "source": { "pointer": "/meta/dataset" },
            }]
        });
        let doc: JsonApiErrorDocument = serde_json::from_value(json).unwrap();
        assert_eq!(
            doc.errors[0].source.as_ref().unwrap().pointer.as_deref(),
            Some("/meta/dataset")
        );
    }
}