canic_core/dto/auth/
application_session.rs

1//! Module: dto::auth::application_session
2//!
3//! Responsibility: define passive local application-session command and status contracts.
4//! Does not own: proof verification, authority policy, persistence, or caller acquisition.
5//! Boundary: cfg-pruned managed role variants carry these values over Candid.
6
7use super::DelegatedToken;
8use crate::{
9    dto::{page::Page, prelude::*},
10    ids::{CanisterRole, FleetKey},
11};
12
13/// Request to establish one caller-bound scoped application session.
14#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
15pub struct ApplicationSessionRequest {
16    pub delegated_token: DelegatedToken,
17    pub requested_scopes: Vec<String>,
18    pub requested_ttl_secs: Option<u64>,
19}
20
21/// Non-secret caller-self projection of one retained application session.
22#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
23pub struct ApplicationSessionView {
24    pub authenticated_subject: Principal,
25    pub issuer: Principal,
26    pub scopes: Vec<String>,
27    pub established_at_ns: u64,
28    pub expires_at_ns: u64,
29    pub authority_generation: u64,
30}
31
32/// Exact inactive classification for a physically absent or invalid caller session.
33#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
34pub enum InactiveApplicationSession {
35    Missing,
36    Expired {
37        expired_at_ns: u64,
38    },
39    StaleFleet,
40    StaleRole,
41    StaleGeneration {
42        session_generation: u64,
43        current_generation: u64,
44    },
45    InadmissibleSubject,
46}
47
48/// Caller-self application-session status.
49#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
50pub enum ApplicationSessionStatus {
51    Active(ApplicationSessionView),
52    Inactive(InactiveApplicationSession),
53}
54
55/// Non-secret verifier policy that selects the accepted root registry authority.
56#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
57pub struct ApplicationSessionVerifierPolicyView {
58    pub root_canister_id: Principal,
59    pub minimum_accepted_registry_epoch: Option<u64>,
60}
61
62/// Protected configuration and current runtime binding for local authorization.
63#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
64pub struct ApplicationSessionPolicyView {
65    pub fleet: FleetKey,
66    pub role: CanisterRole,
67    pub authority_generation: u64,
68    pub allowed_scopes: Vec<String>,
69    pub default_session_ttl_secs: u64,
70    pub maximum_session_ttl_secs: u64,
71    pub proof_lifetime_ceiling_ns: u64,
72    pub verifier: ApplicationSessionVerifierPolicyView,
73}
74
75/// One bounded operator-only session row, including inactive retained records.
76#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
77pub struct ApplicationSessionAuditEntry {
78    pub transport_caller: Principal,
79    pub status: ApplicationSessionStatus,
80}
81
82/// Protected operator inspection of declared policy, runtime binding and retained sessions.
83#[derive(CandidType, Clone, Debug, Deserialize)]
84pub struct ApplicationSessionAuditResponse {
85    pub policy: ApplicationSessionPolicyView,
86    pub sessions: Page<ApplicationSessionAuditEntry>,
87}
88
89/// Managed role command nested under the existing `canic_command` method.
90#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
91#[expect(
92    clippy::large_enum_variant,
93    reason = "the bounded Candid command keeps its accepted direct request shape"
94)]
95pub enum ApplicationSessionCommand {
96    Establish(ApplicationSessionRequest),
97    Clear,
98}
99
100/// Managed role response nested under the existing `canic_command` method.
101#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
102pub enum ApplicationSessionCommandResponse {
103    Established(ApplicationSessionView),
104    Cleared,
105}
canic_core/dto/auth/application_session.rs

canic_core/dto/auth/
application_session.rs
