tamga 0.3.5

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
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
//! `ScopeObject`, `ValidationMeta`, and `ValidationCode`.
//!
//! Contents:
//!
//! - `ScopeObject`: 8 optional fields — `product`, `policy`, `user`,
//!   `environment` (`Uuid`), `entitlements` (`Vec<String>`), `fingerprint`,
//!   `version`, `checksum` (`String`). Six are enforced server-side:
//!   `product`, `policy`, `user`, `environment`, `entitlements` and
//!   `fingerprint`. The remaining two, `version` and `checksum`, are
//!   **refused**: setting either fails the entire validate call with
//!   `422 SCOPE_NOT_SUPPORTED` before any check runs, so the caller never
//!   sees a `meta.valid` at all. They are therefore never serialized — see
//!   `ScopeObject`'s own doc comment. Enforced fields serialize with
//!   `skip_serializing_if = "Option::is_none"` so unset ones are omitted
//!   from the request body.
//! - `ValidationMeta`: `{ ts, valid, detail, code }`.
//! - `ValidationCode`: all **23** variants, decoded by a hand-written
//!   `Deserialize` impl that maps any unrecognized wire value onto
//!   `Unknown(String)` instead of failing, so a future server-side addition
//!   cannot hard-fail deserialization. (Not `#[serde(other)]` — that
//!   attribute only fits unit variants and would drop the string.)
//!   - ✅ Reachable (18): `VALID`, `SUSPENDED`, `EXPIRED`, `OVERDUE`,
//!     `PRODUCT_SCOPE_MISMATCH`, `POLICY_SCOPE_MISMATCH`,
//!     `USER_SCOPE_MISMATCH`, `ENVIRONMENT_SCOPE_MISMATCH`,
//!     `FINGERPRINT_SCOPE_MISMATCH`, `ENTITLEMENTS_MISSING`,
//!     `TOO_MANY_MACHINES`, `TOO_MANY_CORES`, `TOO_MUCH_MEMORY`,
//!     `TOO_MUCH_DISK`, `TOO_MANY_PROCESSES`,
//!     `TOO_MANY_USERS` (all three validate endpoints, `users > max_users`),
//!     `HEARTBEAT_NOT_STARTED` and `HEARTBEAT_DEAD` (both only when
//!     `scope.fingerprint` is set and the policy has `require_heartbeat`).
//!     `TOO_MANY_USES` was removed entirely — the retired global
//!     `licenses.uses`/`max_uses` counter it reported on no longer exists;
//!     see [`crate::models::entitlement::EntitlementKind::Meter`] for its
//!     replacement.
//!   - ⛔ Unreachable (5): `NOT_FOUND` (the handler returns HTTP 404
//!     instead), `BANNED` (there is no banning feature),
//!     `COMPONENTS_SCOPE_MISMATCH` (there is no `scope.components`),
//!     `CHECKSUM_SCOPE_MISMATCH` and `VERSION_SCOPE_MISMATCH` (the scope
//!     fields that would produce them are refused with
//!     `422 SCOPE_NOT_SUPPORTED` first).

/// Scope constraints for `validate_by_id`, sent as `meta.scope` in the
/// request body. Every field is optional — `None` means "no constraint,
/// skip this check" (mirrors the server's `ValidationScope`).
///
/// Six of the eight are enforced server-side: `product`, `policy`, `user`,
/// `environment`, `entitlements` and `fingerprint`.
///
/// `version` and `checksum` are **refused**, not ignored. The server has
/// nothing to compare either against, and rather than let a scope silently
/// pass (which then gets relied on) it fails the whole call with
/// `422 SCOPE_NOT_SUPPORTED` before running any validation — so a caller
/// that sets one gets no `meta.valid` back at all. Both fields are
/// consequently **never serialized into the request body**: they are kept
/// as deserializable members so existing code that reads or assigns them
/// still compiles, but assigning one now degrades to a working, unscoped
/// validate instead of a hard failure. They are deprecated; drop them.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ScopeObject {
    /// Enforced. Must match the license's product.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub product: Option<uuid::Uuid>,
    /// Enforced. Must match the license's policy.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub policy: Option<uuid::Uuid>,
    /// Enforced. Must match the license's owner.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub user: Option<uuid::Uuid>,
    /// Enforced. Must match the license's environment.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub environment: Option<uuid::Uuid>,
    /// Enforced. Entitlement **codes** (the stable developer-facing
    /// identifier), not the entitlement UUIDs that attach/detach bodies
    /// take. Compared case-insensitively and de-duplicated server-side,
    /// and satisfied by directly-attached *and* policy-inherited
    /// entitlements alike. An empty vec asserts nothing. A license missing
    /// any one of them validates as
    /// [`ValidationCode::EntitlementsMissing`].
    #[serde(skip_serializing_if = "Option::is_none")]
    pub entitlements: Option<Vec<String>>,
    /// Enforced. Matches when **any** machine on this license carries this
    /// fingerprint, regardless of that machine's heartbeat status. This is
    /// the anti-key-sharing check: pass the activating machine's own
    /// fingerprint to assert the license is being validated from a machine
    /// it knows about. A mismatch validates as
    /// [`ValidationCode::FingerprintScopeMismatch`].
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fingerprint: Option<String>,
    /// **Deprecated and never sent.** Setting this used to be a silent
    /// no-op; the server now answers `422 SCOPE_NOT_SUPPORTED` and fails
    /// the whole validate call, so this SDK omits the field from the
    /// request body entirely. See the struct's doc comment.
    #[serde(skip_serializing)]
    #[deprecated(
        note = "the server refuses this field with `422 SCOPE_NOT_SUPPORTED`, failing the whole \
                validate call, so this SDK never sends it. Setting it is silently discarded and \
                constrains nothing — remove it, or move the check to a field the server enforces \
                (`entitlements`, `fingerprint`, `product`, `policy`, `user`, `environment`)."
    )]
    pub version: Option<String>,
    /// **Deprecated and never sent.** Same as `version` — the server
    /// answers `422 SCOPE_NOT_SUPPORTED`, so this SDK omits the field. See
    /// the struct's doc comment.
    #[serde(skip_serializing)]
    #[deprecated(
        note = "the server refuses this field with `422 SCOPE_NOT_SUPPORTED`, failing the whole \
                validate call, so this SDK never sends it. Setting it is silently discarded and \
                constrains nothing — remove it, or move the check to a field the server enforces \
                (`entitlements`, `fingerprint`, `product`, `policy`, `user`, `environment`)."
    )]
    pub checksum: Option<String>,
}

/// Combined response of `validate_by_key`/`validate_by_id`: the (possibly
/// touched) license resource plus the validation outcome. Quick-validate
/// returns only a bare [`ValidationMeta`] — it has no `data` envelope.
#[derive(Debug, Clone)]
pub struct ValidationResult {
    /// The license resource as of this validation call (reflects
    /// `last_validated_at` being bumped, unless `skip_touch: true` was
    /// sent).
    pub license: crate::models::license::LicenseResource,
    /// The validation outcome.
    pub meta: ValidationMeta,
}

/// `{ ts, valid, detail, code }` returned alongside a license resource on
/// the validate-by-key/by-id endpoints, and as the entire flat body on
/// quick-validate.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ValidationMeta {
    /// Server timestamp the validation ran at.
    pub ts: chrono::DateTime<chrono::Utc>,
    /// Whether the license passed all checks.
    pub valid: bool,
    /// Human-readable explanation — may change wording; match on `code`
    /// instead for stable programmatic handling.
    pub detail: String,
    /// Stable, machine-matchable outcome code.
    pub code: ValidationCode,
}

/// All 23 server-declared validation codes, evaluated in priority order for
/// the by-ID endpoint. Deserializes any unrecognized wire value into
/// `Unknown(String)` rather than failing, so a future server-side addition
/// doesn't hard-break this SDK.
///
/// - ✅ Reachable (18): `Valid`, `Suspended`, `Expired`, `Overdue`,
///   `ProductScopeMismatch`, `PolicyScopeMismatch`, `UserScopeMismatch`,
///   `EnvironmentScopeMismatch`, `FingerprintScopeMismatch`,
///   `EntitlementsMissing`, `TooManyMachines`, `TooManyCores`,
///   `TooMuchMemory`, `TooMuchDisk`, `TooManyProcesses`,
///   `TooManyUsers`, `HeartbeatNotStarted`, `HeartbeatDead`.
/// - ⛔ Unreachable (5): `NotFound` (the handler returns HTTP 404 directly),
///   `Banned` (there is no banning feature), `ComponentsScopeMismatch`
///   (there is no `scope.components`), `ChecksumScopeMismatch` and
///   `VersionScopeMismatch` (structurally unreachable — the scope fields
///   that would produce them are rejected with `422 SCOPE_NOT_SUPPORTED`
///   first).
///
/// The five over-limit codes (`TooManyMachines`, `TooManyCores`,
/// `TooMuchMemory`, `TooMuchDisk`, `TooManyProcesses`) have create-time
/// twins: under a strict overage strategy the server refuses registration
/// with a `422` instead, which this SDK classifies as a
/// [`crate::error::LimitExceededCode`] and can normalize back onto the
/// matching variant here via
/// [`crate::error::LimitExceededCode::as_validation_code`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ValidationCode {
    /// ✅ All checks passed.
    Valid,
    /// ⛔ Declared, never emitted — the handler 404s instead.
    NotFound,
    /// ⛔ Declared, never emitted — there is no banning feature.
    Banned,
    /// ✅ `license.suspended == true`.
    Suspended,
    /// ✅ `expiry < now`.
    Expired,
    /// ✅ Check-in required and the window has elapsed.
    Overdue,
    /// ✅ `scope.entitlements` set and the license (counting both directly
    /// attached and policy-inherited rows) does not hold every listed code.
    EntitlementsMissing,
    /// ✅ Machine count over `policy.max_machines` (per overage strategy).
    /// A strict strategy refuses the machine at creation time instead —
    /// see [`crate::error::LimitExceededCode::MachineLimitExceeded`].
    TooManyMachines,
    /// ✅ Core count over `policy.max_cores`.
    TooManyCores,
    /// ✅ Memory over `policy.max_memory`.
    TooMuchMemory,
    /// ✅ Disk over `policy.max_disk`.
    TooMuchDisk,
    /// ✅ Process count over `policy.max_processes`.
    TooManyProcesses,
    /// ✅ users over policy.max_users, on every validate endpoint.
    TooManyUsers,
    /// ✅ scope.fingerprint matched a machine whose heartbeat is dead, under
    /// a require_heartbeat policy.
    HeartbeatDead,
    /// ✅ scope.fingerprint matched a machine that has never pinged, under a
    /// require_heartbeat policy.
    HeartbeatNotStarted,
    /// ✅ `scope.product` set and mismatched.
    ProductScopeMismatch,
    /// ✅ `scope.policy` set and mismatched.
    PolicyScopeMismatch,
    /// ✅ `scope.user` set and mismatched.
    UserScopeMismatch,
    /// ✅ `scope.fingerprint` set and no machine on this license carries
    /// it.
    FingerprintScopeMismatch,
    /// ⛔ Declared, never emitted — there is no scope.components.
    ComponentsScopeMismatch,
    /// ⛔ Structurally unreachable — `scope.checksum` is refused with
    /// `422 SCOPE_NOT_SUPPORTED` before validation runs.
    ChecksumScopeMismatch,
    /// ⛔ Structurally unreachable — `scope.version` is refused with
    /// `422 SCOPE_NOT_SUPPORTED` before validation runs.
    VersionScopeMismatch,
    /// ✅ `scope.environment` set and mismatched.
    EnvironmentScopeMismatch,
    /// Any wire value not matching a known variant above — lenient
    /// deserialization for forward-compatibility with future server codes.
    Unknown(String),
}

impl<'de> serde::Deserialize<'de> for ValidationCode {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Ok(match s.as_str() {
            "VALID" => ValidationCode::Valid,
            "NOT_FOUND" => ValidationCode::NotFound,
            "BANNED" => ValidationCode::Banned,
            "SUSPENDED" => ValidationCode::Suspended,
            "EXPIRED" => ValidationCode::Expired,
            "OVERDUE" => ValidationCode::Overdue,
            "ENTITLEMENTS_MISSING" => ValidationCode::EntitlementsMissing,
            "TOO_MANY_MACHINES" => ValidationCode::TooManyMachines,
            "TOO_MANY_CORES" => ValidationCode::TooManyCores,
            "TOO_MUCH_MEMORY" => ValidationCode::TooMuchMemory,
            "TOO_MUCH_DISK" => ValidationCode::TooMuchDisk,
            "TOO_MANY_PROCESSES" => ValidationCode::TooManyProcesses,
            "TOO_MANY_USERS" => ValidationCode::TooManyUsers,
            "HEARTBEAT_DEAD" => ValidationCode::HeartbeatDead,
            "HEARTBEAT_NOT_STARTED" => ValidationCode::HeartbeatNotStarted,
            "PRODUCT_SCOPE_MISMATCH" => ValidationCode::ProductScopeMismatch,
            "POLICY_SCOPE_MISMATCH" => ValidationCode::PolicyScopeMismatch,
            "USER_SCOPE_MISMATCH" => ValidationCode::UserScopeMismatch,
            "FINGERPRINT_SCOPE_MISMATCH" => ValidationCode::FingerprintScopeMismatch,
            "COMPONENTS_SCOPE_MISMATCH" => ValidationCode::ComponentsScopeMismatch,
            "CHECKSUM_SCOPE_MISMATCH" => ValidationCode::ChecksumScopeMismatch,
            "VERSION_SCOPE_MISMATCH" => ValidationCode::VersionScopeMismatch,
            "ENVIRONMENT_SCOPE_MISMATCH" => ValidationCode::EnvironmentScopeMismatch,
            other => ValidationCode::Unknown(other.to_string()),
        })
    }
}

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

    fn all_known_wire_pairs() -> Vec<(&'static str, ValidationCode)> {
        vec![
            ("VALID", ValidationCode::Valid),
            ("NOT_FOUND", ValidationCode::NotFound),
            ("BANNED", ValidationCode::Banned),
            ("SUSPENDED", ValidationCode::Suspended),
            ("EXPIRED", ValidationCode::Expired),
            ("OVERDUE", ValidationCode::Overdue),
            ("ENTITLEMENTS_MISSING", ValidationCode::EntitlementsMissing),
            ("TOO_MANY_MACHINES", ValidationCode::TooManyMachines),
            ("TOO_MANY_CORES", ValidationCode::TooManyCores),
            ("TOO_MUCH_MEMORY", ValidationCode::TooMuchMemory),
            ("TOO_MUCH_DISK", ValidationCode::TooMuchDisk),
            ("TOO_MANY_PROCESSES", ValidationCode::TooManyProcesses),
            ("TOO_MANY_USERS", ValidationCode::TooManyUsers),
            ("HEARTBEAT_DEAD", ValidationCode::HeartbeatDead),
            ("HEARTBEAT_NOT_STARTED", ValidationCode::HeartbeatNotStarted),
            (
                "PRODUCT_SCOPE_MISMATCH",
                ValidationCode::ProductScopeMismatch,
            ),
            ("POLICY_SCOPE_MISMATCH", ValidationCode::PolicyScopeMismatch),
            ("USER_SCOPE_MISMATCH", ValidationCode::UserScopeMismatch),
            (
                "FINGERPRINT_SCOPE_MISMATCH",
                ValidationCode::FingerprintScopeMismatch,
            ),
            (
                "COMPONENTS_SCOPE_MISMATCH",
                ValidationCode::ComponentsScopeMismatch,
            ),
            (
                "CHECKSUM_SCOPE_MISMATCH",
                ValidationCode::ChecksumScopeMismatch,
            ),
            (
                "VERSION_SCOPE_MISMATCH",
                ValidationCode::VersionScopeMismatch,
            ),
            (
                "ENVIRONMENT_SCOPE_MISMATCH",
                ValidationCode::EnvironmentScopeMismatch,
            ),
        ]
    }

    #[test]
    fn deserializes_all_23_known_wire_strings() {
        let pairs = all_known_wire_pairs();
        assert_eq!(pairs.len(), 23, "must cover all 23 server-declared codes");
        for (wire, expected) in pairs {
            let json = format!("\"{wire}\"");
            let parsed: ValidationCode = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, expected, "wire value {wire}");
        }
    }

    #[test]
    fn deserializes_unknown_value_to_unknown_variant() {
        let parsed: ValidationCode = serde_json::from_str("\"SOME_FUTURE_CODE\"").unwrap();
        assert_eq!(
            parsed,
            ValidationCode::Unknown("SOME_FUTURE_CODE".to_string())
        );
    }

    #[test]
    fn too_many_uses_is_retired_and_falls_back_to_unknown() {
        // The retired global `licenses.uses`/`max_uses` counter this code
        // used to report on no longer exists on the wire — `validate` never
        // emits it again. A server that somehow still sent it (a pre-patch
        // build) must not hard-fail this SDK.
        let parsed: ValidationCode = serde_json::from_str("\"TOO_MANY_USES\"").unwrap();
        assert_eq!(parsed, ValidationCode::Unknown("TOO_MANY_USES".to_string()));
    }

    #[test]
    fn scope_object_serializes_only_set_fields() {
        let scope = ScopeObject {
            product: Some(uuid::Uuid::nil()),
            ..Default::default()
        };
        let value = serde_json::to_value(&scope).unwrap();
        let obj = value.as_object().unwrap();
        assert_eq!(obj.len(), 1, "only `product` was set: {obj:?}");
        assert!(obj.contains_key("product"));
    }

    #[test]
    // Setting the refused fields is the whole point of this test, so the
    // deprecation warning they now raise is expected here.
    #[allow(deprecated)]
    fn scope_object_never_serializes_the_two_refused_fields() {
        // Setting either used to be a harmless no-op. It now fails the
        // whole validate call with 422 SCOPE_NOT_SUPPORTED, so a caller
        // that still sets one must degrade to an unscoped validate rather
        // than to no validate at all.
        let scope = ScopeObject {
            product: Some(uuid::Uuid::nil()),
            version: Some("1.2.3".to_string()),
            checksum: Some("deadbeef".to_string()),
            ..Default::default()
        };
        let value = serde_json::to_value(&scope).unwrap();
        assert_eq!(value, serde_json::json!({ "product": uuid::Uuid::nil() }));
    }

    #[test]
    // Reading `scope.version` back is the point: deprecated on the way out,
    // still parsed on the way in.
    #[allow(deprecated)]
    fn scope_object_still_deserializes_the_two_refused_fields() {
        // Skipped on the way out, not on the way in — round-tripping a
        // stored scope must not silently drop what the caller wrote.
        let scope: ScopeObject =
            serde_json::from_value(serde_json::json!({ "version": "1.2.3" })).unwrap();
        assert_eq!(scope.version.as_deref(), Some("1.2.3"));
    }

    #[test]
    fn scope_object_serializes_the_enforced_entitlements_and_fingerprint() {
        let scope = ScopeObject {
            entitlements: Some(vec!["pro".to_string()]),
            fingerprint: Some("fp-abc123".to_string()),
            ..Default::default()
        };
        let value = serde_json::to_value(&scope).unwrap();
        assert_eq!(
            value,
            serde_json::json!({ "entitlements": ["pro"], "fingerprint": "fp-abc123" })
        );
    }

    #[test]
    fn scope_object_empty_serializes_to_empty_object() {
        let scope = ScopeObject::default();
        let value = serde_json::to_value(&scope).unwrap();
        assert_eq!(value, serde_json::json!({}));
    }

    #[test]
    fn validation_meta_deserializes_from_representative_response() {
        let json = serde_json::json!({
            "ts": "2026-01-01T00:00:00Z",
            "valid": true,
            "detail": "is valid",
            "code": "VALID",
        });
        let meta: ValidationMeta = serde_json::from_value(json).unwrap();
        assert!(meta.valid);
        assert_eq!(meta.detail, "is valid");
        assert_eq!(meta.code, ValidationCode::Valid);
    }
}