codlet-core 0.3.0

Core authentication primitives for codlet: code policy, generation, normalization, keyed lookup derivation, lifecycle state machines, and storage traits.
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

//! Session storage trait (RFC-006).

use std::future::Future;

use crate::hashing::{KeyVersion, LookupKey};
use crate::secret::{SessionId, SubjectId};

use super::error::StoreError;

/// An active session record returned by validation.
#[derive(Debug, Clone)]
pub struct ActiveSessionRecord {
    /// Opaque session record identifier (not a bearer credential).
    pub id: SessionId,
    /// The subject this session authenticates.
    pub subject: SubjectId,
    /// Expiry as Unix seconds (UTC).
    pub expires_at: u64,
}

/// Parameters for inserting a new session.
pub struct SessionRecord {
    /// Store-assigned identifier.
    pub id: SessionId,
    /// Domain-separated HMAC of the session secret.
    pub lookup_key: LookupKey,
    /// Key version that produced `lookup_key`.
    pub key_version: KeyVersion,
    /// The authenticated subject.
    pub subject: SubjectId,
    /// Creation time as Unix seconds (UTC).
    pub created_at: u64,
    /// Expiry as Unix seconds (UTC).
    pub expires_at: u64,
}

/// Session storage (RFC-006).
///
/// Sessions are stored by their HMAC lookup key, never by the plaintext secret.
/// The plaintext lives only in the cookie.
pub trait SessionStore {
    /// Look up an active session by HMAC lookup key candidates.
    ///
    /// Returns the first record matching any candidate that is not expired and
    /// not revoked at `now`. Returns `Ok(None)` if no such session exists.
    fn find_active_session(
        &self,
        candidates: &[LookupKey],
        now: u64,
    ) -> impl Future<Output = Result<Option<ActiveSessionRecord>, StoreError>>;

    /// Insert a new session record.
    fn insert_session(&self, record: SessionRecord)
    -> impl Future<Output = Result<(), StoreError>>;

    /// Revoke a session by its record ID (logout / incident response).
    /// Revocation is monotonic: a revoked session cannot be unrevoked.
    fn revoke_session(
        &self,
        session_id: &SessionId,
        now: u64,
    ) -> impl Future<Output = Result<(), StoreError>>;
}