axiam-sdk 1.2.2

Official Rust client SDK for AXIAM IAM
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
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
//! The plan a manifest reconciles to — CONTRACT.md §27.6.

use std::collections::{HashMap, HashSet};

use uuid::Uuid;

use super::spec::{ManagementManifest, RoleBinding};
use crate::AxiamError;

/// What reconciling one spec would do.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Change {
    /// The thing does not exist and would be created.
    Create,
    /// It exists, and a field the manifest *states* differs.
    Update,
    /// It exists and matches. §27.6 rule 3: a field the manifest does not
    /// mention is never a difference, which is what makes `apply` safe against
    /// a tenant that also holds hand-made state.
    NoChange,
}

/// Which part of the manifest an action came from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Target {
    /// A resource in the hierarchy.
    Resource,
    /// A scope beneath a resource.
    Scope,
    /// A permission.
    Permission,
    /// A role.
    Role,
    /// A permission granted to a role.
    RoleGrant,
    /// A group.
    Group,
    /// A role assigned to a group.
    GroupRole,
    /// A user.
    User,
    /// A role assigned directly to a user.
    UserRole,
    /// A user's membership of a group.
    GroupMember,
    /// A service account (contract 1.51).
    ServiceAccount,
    /// A role assigned to a service account (contract 1.51).
    ServiceAccountRole,
    /// The tenant's network policy — the `Session-Timeout` cap (contract 1.62).
    NetworkPolicy,
    /// A network segment (contract 1.62).
    NetworkSegment,
    /// A network segment's reply profile (contract 1.62).
    NetworkProfile,
}

impl Target {
    /// Whether this action belongs to the `network` namespace (contract 1.62).
    #[must_use]
    pub fn is_network(self) -> bool {
        matches!(
            self,
            Target::NetworkPolicy | Target::NetworkSegment | Target::NetworkProfile
        )
    }
}

/// One step of a plan.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PlannedAction {
    /// Whether this step creates, updates, or does nothing.
    pub change: Change,
    /// What kind of thing it acts on.
    pub target: Target,
    /// The manifest key it came from, for a human reading the plan.
    pub key: String,
    /// A one-line description, stable across runs so plans can be diffed.
    pub summary: String,
}

/// The ordered set of actions that would reconcile a manifest.
///
/// Ordering is derived, not incidental (§27.6 rule 5): resources (parents
/// before children), then scopes, permissions, roles, role grants, groups,
/// group bindings, users and their bindings, service accounts and theirs, and
/// — from contract 1.62 — the `network` namespace: its policy, then its
/// segments, then its profiles.
/// Two plans over unchanged state are equal, in the same order (§27.6 rule 8)
/// — a plan that reorders between runs cannot be diffed, and diffing it is
/// most of the reason it exists.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct ManagementPlan {
    /// Every step, including the no-ops.
    pub actions: Vec<PlannedAction>,
}

impl ManagementPlan {
    /// The steps that would actually change something.
    pub fn changes(&self) -> impl Iterator<Item = &PlannedAction> {
        self.actions.iter().filter(|a| a.change != Change::NoChange)
    }

    /// Whether applying this plan would change nothing.
    ///
    /// This is the §27.6 rule 6 acceptance test: `apply` then `plan` must land
    /// here, or the SDK has a drift-detection bug.
    pub fn is_converged(&self) -> bool {
        self.changes().next().is_none()
    }

    /// How many steps would change something.
    pub fn change_count(&self) -> usize {
        self.changes().count()
    }
}

/// What actually happened to one planned step.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Outcome {
    /// The step ran and the thing now exists.
    Created,
    /// A service account was created, and this is what the server returned —
    /// **including its `client_secret`, which no later read returns** (§27.5
    /// rules 3 and 5). Kept on the report even when a later step fails.
    CreatedServiceAccount(CreatedServiceAccount),
    /// The step ran and the thing was updated.
    Updated,
    /// A no-op step; nothing was sent.
    Unchanged,
    /// The step failed. Everything before it has already happened.
    Failed(String),
    /// A `network` write was refused `409` (contract 1.62, §27.6.2 item 5).
    ///
    /// Everything before it has already happened and nothing after it was
    /// attempted. The recovery is to run `apply` again, which re-reads; this
    /// SDK never repeats the write itself, and never refreshes the version and
    /// sends again (§36.9). Branch on [`Outcome::reason_code`], never on the
    /// message.
    Conflict {
        /// The server's refusal, as the error rendered it.
        message: String,
        /// The body's `reason_code` — `stale_version`, `strands_profile`,
        /// `has_children`, `profile_exists`, `duplicate_name`, `duplicate_vlan`,
        /// `duplicate_rank`, `site_gone`, `other`, or a value this SDK has not
        /// seen, verbatim (the vocabulary is open). `None` from a server that
        /// predates the member.
        reason_code: Option<String>,
    },
    /// A role binding's `Update` failed at its re-assignment (§27.6.1 item 2).
    ///
    /// The previous assignment had already been removed, so `apply` tried to
    /// assign it again. `restore` says how that went: `Ok` means the subject
    /// holds the role exactly as before; `Err` means it holds **no** such role
    /// now, and says why.
    BindingUpdateFailed {
        /// Why the new assignment was refused.
        error: String,
        /// Whether the previous assignment was restored.
        restore: Result<(), String>,
    },
    /// The step was never attempted, because an earlier one failed.
    NotAttempted,
}

impl Outcome {
    /// The `reason_code` of a [`Outcome::Conflict`]; `None` for every other
    /// outcome.
    #[must_use]
    pub fn reason_code(&self) -> Option<&str> {
        match self {
            Outcome::Conflict { reason_code, .. } => reason_code.as_deref(),
            _ => None,
        }
    }
}

/// The server's answer to a service-account `Create`, carried on
/// [`Outcome::CreatedServiceAccount`].
///
/// Equality compares the account's identity — `id` and `client_id` — and
/// **never** the secret: comparing secrets is a constant-time operation with a
/// different purpose, and `Sensitive` deliberately has no `PartialEq`.
#[derive(Debug, Clone)]
pub struct CreatedServiceAccount(pub Box<crate::management::models::ServiceAccountCreatedResponse>);

impl CreatedServiceAccount {
    /// The created account, `client_secret` included (a
    /// [`Sensitive`](crate::Sensitive), redacted in every rendering).
    #[must_use]
    pub fn account(&self) -> &crate::management::models::ServiceAccountCreatedResponse {
        &self.0
    }
}

impl PartialEq for CreatedServiceAccount {
    fn eq(&self, other: &Self) -> bool {
        self.0.id == other.0.id && self.0.client_id == other.0.client_id
    }
}

impl Eq for CreatedServiceAccount {}

/// The result of applying a manifest.
///
/// **There is no transaction here and this type does not pretend there is**
/// (§27.6 rule 7). These are independent HTTP endpoints; nothing spans them.
/// If step 12 of 30 fails, steps 1–11 have happened and will not be undone —
/// so every step's outcome is reported, execution stops at the first failure
/// rather than continuing blindly, and there is no `rollback` method because
/// this SDK could not honour one. Fix the cause and re-apply: rule 6's
/// idempotence is what makes that safe.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApplyReport {
    /// Each planned step paired with what became of it, in plan order.
    pub steps: Vec<(PlannedAction, Outcome)>,
}

impl ApplyReport {
    /// The failing step, if the apply stopped early.
    pub fn failure(&self) -> Option<(&PlannedAction, &str)> {
        self.steps
            .iter()
            .find_map(|(action, outcome)| match outcome {
                Outcome::Failed(message) => Some((action, message.as_str())),
                Outcome::Conflict { message, .. } => Some((action, message.as_str())),
                Outcome::BindingUpdateFailed { error, .. } => Some((action, error.as_str())),
                _ => None,
            })
    }

    /// The `reason_code` of the `409` that stopped the apply, when one did
    /// (contract 1.62, §27.6.2 item 5). `None` when the apply completed, failed
    /// otherwise, or the server sent no code.
    pub fn reason_code(&self) -> Option<&str> {
        self.steps
            .iter()
            .find_map(|(_, outcome)| outcome.reason_code())
    }

    /// Every service account this apply created, with the one-time secret the
    /// server returned for it — including those created before a later step
    /// failed (§27.5 rule 5).
    pub fn created_service_accounts(
        &self,
    ) -> impl Iterator<
        Item = (
            &PlannedAction,
            &crate::management::models::ServiceAccountCreatedResponse,
        ),
    > {
        self.steps
            .iter()
            .filter_map(|(action, outcome)| match outcome {
                Outcome::CreatedServiceAccount(created) => Some((action, created.account())),
                _ => None,
            })
    }

    /// Whether every step that was meant to run did.
    pub fn is_complete(&self) -> bool {
        self.failure().is_none()
    }

    /// How many steps actually changed something.
    pub fn changed(&self) -> usize {
        self.steps
            .iter()
            .filter(|(_, o)| {
                matches!(
                    o,
                    Outcome::Created | Outcome::CreatedServiceAccount(_) | Outcome::Updated
                )
            })
            .count()
    }
}

/// Manifest keys resolved to server ids, built during planning.
#[derive(Debug, Clone, Default)]
pub(crate) struct Resolved {
    pub resources: HashMap<String, Uuid>,
    pub scopes: HashMap<String, Uuid>,
    pub permissions: HashMap<String, Uuid>,
    pub roles: HashMap<String, Uuid>,
    pub groups: HashMap<String, Uuid>,
    pub users: HashMap<String, Uuid>,
    pub service_accounts: HashMap<String, Uuid>,
    /// Network segment key → id (contract 1.62).
    pub network_segments: HashMap<String, Uuid>,
    /// Network segment key → the `version` last known: the read's, replaced by
    /// the response of the write `apply` made to it (§27.6.2 item 4).
    pub network_segment_versions: HashMap<String, i64>,
}

/// Reject a manifest that cannot be reconciled, before any request is made.
///
/// §27.6 rule 2 and rule 5 both land here. Every failure this catches would
/// otherwise surface halfway through an apply, with some of the tenant already
/// changed — which is the expensive moment to learn that a role refers to a
/// permission nobody declared.
pub(crate) fn validate(manifest: &ManagementManifest) -> Result<(), AxiamError> {
    let mut problems: Vec<String> = Vec::new();

    let resource_keys: HashSet<&str> = manifest.resources.iter().map(|r| r.key.as_str()).collect();
    let scope_keys: HashSet<&str> = manifest
        .resources
        .iter()
        .flat_map(|r| r.scopes.iter().map(|s| s.key.as_str()))
        .collect();
    let permission_keys: HashSet<&str> = manifest
        .permissions
        .iter()
        .map(|p| p.key.as_str())
        .collect();
    let role_keys: HashSet<&str> = manifest.roles.iter().map(|r| r.key.as_str()).collect();
    let group_keys: HashSet<&str> = manifest.groups.iter().map(|g| g.key.as_str()).collect();

    duplicates(
        "resource",
        manifest.resources.iter().map(|r| &r.key),
        &mut problems,
    );
    duplicates(
        "scope",
        manifest
            .resources
            .iter()
            .flat_map(|r| r.scopes.iter().map(|s| &s.key)),
        &mut problems,
    );
    duplicates(
        "permission",
        manifest.permissions.iter().map(|p| &p.key),
        &mut problems,
    );
    duplicates("role", manifest.roles.iter().map(|r| &r.key), &mut problems);
    duplicates(
        "group",
        manifest.groups.iter().map(|g| &g.key),
        &mut problems,
    );
    duplicates("user", manifest.users.iter().map(|u| &u.key), &mut problems);

    for resource in &manifest.resources {
        if let Some(parent) = &resource.parent
            && !resource_keys.contains(parent.as_str())
        {
            problems.push(format!(
                "resource {:?} names parent {parent:?}, which no resource declares",
                resource.key
            ));
        }
    }
    for role in &manifest.roles {
        for grant in &role.grants {
            if !permission_keys.contains(grant.permission.as_str()) {
                problems.push(format!(
                    "role {:?} grants permission {:?}, which no permission declares",
                    role.key, grant.permission
                ));
            }
            for scope in &grant.scopes {
                if !scope_keys.contains(scope.as_str()) {
                    problems.push(format!(
                        "role {:?} scopes a grant to {scope:?}, which no scope declares",
                        role.key
                    ));
                }
            }
        }
    }
    duplicates(
        "service account",
        manifest.service_accounts.iter().map(|a| &a.key),
        &mut problems,
    );
    // A service account's name is its natural key, and the server does not
    // enforce it: two specs with one name would create two accounts, and the
    // next plan could no longer tell them apart.
    duplicates(
        "service account name",
        manifest.service_accounts.iter().map(|a| &a.name),
        &mut problems,
    );

    let global_roles: HashSet<&str> = manifest
        .roles
        .iter()
        .filter(|r| r.is_global)
        .map(|r| r.key.as_str())
        .collect();
    let subjects = manifest
        .groups
        .iter()
        .map(|g| ("group", &g.key, &g.roles))
        .chain(manifest.users.iter().map(|u| ("user", &u.key, &u.roles)))
        .chain(
            manifest
                .service_accounts
                .iter()
                .map(|a| ("service account", &a.key, &a.roles)),
        );
    for (kind, subject, bindings) in subjects {
        check_bindings(
            kind,
            subject,
            bindings,
            &role_keys,
            &resource_keys,
            &global_roles,
            &mut problems,
        );
    }
    for user in &manifest.users {
        for group in &user.groups {
            if !group_keys.contains(group.as_str()) {
                problems.push(format!(
                    "user {:?} is in group {group:?}, which no group declares",
                    user.key
                ));
            }
        }
    }

    if let Err(cycle) = topological_order(manifest) {
        problems.push(cycle);
    }

    super::network::validate(&manifest.network, &mut problems);

    if problems.is_empty() {
        Ok(())
    } else {
        Err(AxiamError::network(format!(
            "manifest is not reconcilable ({} problem(s)): {}",
            problems.len(),
            problems.join("; ")
        )))
    }
}

/// The §27.6.1 item 2 rules for one subject's role bindings.
fn check_bindings(
    kind: &str,
    subject: &str,
    bindings: &[RoleBinding],
    role_keys: &HashSet<&str>,
    resource_keys: &HashSet<&str>,
    global_roles: &HashSet<&str>,
    problems: &mut Vec<String>,
) {
    let mut seen: HashSet<&str> = HashSet::new();
    for binding in bindings {
        let role = binding.role();
        if !role_keys.contains(role) {
            problems.push(format!(
                "{kind} {subject:?} is assigned role {role:?}, which no role declares"
            ));
        }
        if let Some(resource) = binding.resource()
            && !resource_keys.contains(resource)
        {
            problems.push(format!(
                "{kind} {subject:?} is assigned role {role:?} at resource {resource:?}, which no \
                 resource declares"
            ));
        }
        // The server keys an assignment on (subject, role) — `has_role` is
        // UNIQUE(in, out), a repeat is a 409 — so one role bound twice to one
        // subject is a state it cannot hold, at two resources or once plain and
        // once scoped alike.
        if !seen.insert(role) {
            problems.push(format!(
                "{kind} {subject:?} binds role {role:?} more than once; a subject holds a role at \
                 most once, whatever the resource (the server keys assignments on subject and \
                 role, and answers 409 to a second)"
            ));
        }
        // The server refuses this with 400; §27.6.1 lets an SDK say so first
        // when the role is in the manifest.
        if !binding.inherit() && global_roles.contains(role) {
            problems.push(format!(
                "{kind} {subject:?} binds global role {role:?} with inherit: false; a global role \
                 applies everywhere and ignores the resource, so the server refuses the flag"
            ));
        }
    }
}

fn duplicates<'a>(kind: &str, keys: impl Iterator<Item = &'a String>, problems: &mut Vec<String>) {
    let mut seen: HashSet<&str> = HashSet::new();
    for key in keys {
        if !seen.insert(key.as_str()) {
            problems.push(format!("{kind} key {key:?} is declared more than once"));
        }
    }
}

/// Resource keys ordered so a parent always precedes its children.
///
/// Returns the cycle as an error rather than looping: a resource graph with a
/// cycle has no valid creation order, and discovering that by hanging is worse
/// than discovering it by message.
pub(crate) fn topological_order(manifest: &ManagementManifest) -> Result<Vec<String>, String> {
    let mut parents: HashMap<&str, Option<&str>> = HashMap::new();
    for resource in &manifest.resources {
        parents.insert(resource.key.as_str(), resource.parent.as_deref());
    }

    let mut order: Vec<String> = Vec::new();
    let mut placed: HashSet<&str> = HashSet::new();
    // Iterate the manifest's own order so the result is stable run to run
    // (§27.6 rule 8), rather than a hash-map traversal order that is not.
    for resource in &manifest.resources {
        let mut chain: Vec<&str> = Vec::new();
        let mut cursor = Some(resource.key.as_str());
        let mut guard: HashSet<&str> = HashSet::new();
        while let Some(key) = cursor {
            if placed.contains(key) {
                break;
            }
            if !guard.insert(key) {
                return Err(format!(
                    "resource parent graph has a cycle through {key:?}; there is no order in \
                     which these can be created"
                ));
            }
            chain.push(key);
            cursor = parents.get(key).copied().flatten();
        }
        for key in chain.into_iter().rev() {
            if placed.insert(key) {
                order.push(key.to_string());
            }
        }
    }
    Ok(order)
}