Struct Session 

pub struct Session { /* private fields */ }

An active security context combining identity and privilege.

A Session represents the current state of an actor in the system:

• Who: The Principal (user, component, or system)
• What level: The PrivilegeLevel (standard or elevated)

Immutability

Sessions are immutable value types. Methods like elevate and drop_privilege return new sessions rather than modifying the existing one. This enables:

• Safe sharing across threads
• Clear audit trails (old session vs new session)
• Simple Clone

Dynamic Permissions

Dynamic command permissions (grant/revoke) are managed separately via GrantPolicy, not by Session. Session only carries identity and privilege level.

Why No Default?

DO NOT implement Default for Session.

A session requires a valid Principal. There is no sensible default identity. Always construct with Session::new.

Example

use orcs_auth::{Session, PrivilegeLevel};
use orcs_types::{Principal, PrincipalId};
use std::time::Duration;

// Create a session for a user
let user = Principal::User(PrincipalId::new());
let session = Session::new(user);

// Check current state
assert!(!session.is_elevated());

// Elevate for privileged operations
let elevated = session.elevate(Duration::from_secs(300));
assert!(elevated.is_elevated());

// Drop back to standard when done
let standard = elevated.drop_privilege();
assert!(!standard.is_elevated());

Implementations

impl Session

pub fn new(principal: Principal) -> Session

Creates a new session with Standard privilege level.

All sessions start in Standard mode. Use elevate to gain elevated privileges.

Example

use orcs_auth::Session;
use orcs_types::{Principal, PrincipalId};

let session = Session::new(Principal::User(PrincipalId::new()));
assert!(!session.is_elevated());

pub fn principal(&self) -> &Principal

Returns a reference to the principal.

pub fn privilege(&self) -> &PrivilegeLevel

Returns a reference to the current privilege level.

pub fn is_elevated(&self) -> bool

Returns true if currently elevated (and not expired).

Example

use orcs_auth::Session;
use orcs_types::{Principal, PrincipalId};
use std::time::Duration;

let session = Session::new(Principal::User(PrincipalId::new()));
assert!(!session.is_elevated());

let elevated = session.elevate(Duration::from_secs(60));
assert!(elevated.is_elevated());

pub fn elevate(&self, duration: Duration) -> Session

Returns a new session with elevated privileges.

The elevation lasts for the specified duration, after which the session automatically behaves as Standard.

Arguments

• duration - How long the elevation should last

Example

use orcs_auth::Session;
use orcs_types::{Principal, PrincipalId};
use std::time::Duration;

let session = Session::new(Principal::User(PrincipalId::new()));

// Elevate for 5 minutes
let elevated = session.elevate(Duration::from_secs(300));
assert!(elevated.is_elevated());

// Original session is unchanged
assert!(!session.is_elevated());

pub fn drop_privilege(&self) -> Session

Returns a new session with Standard privilege level.

Use this to explicitly drop elevated privileges before the automatic expiration.

Example

use orcs_auth::Session;
use orcs_types::{Principal, PrincipalId};
use std::time::Duration;

let session = Session::new(Principal::User(PrincipalId::new()));
let elevated = session.elevate(Duration::from_secs(300));

// Explicitly drop privileges
let standard = elevated.drop_privilege();
assert!(!standard.is_elevated());

pub fn remaining_elevation(&self) -> Option<Duration>

Returns the remaining elevation time, or None if not elevated.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.