calternal-auth

Authentication and session authority for a calternal instance

Instance authentication authority. Security state lives only in SQLite. The server mounts router and supplies the same session authority to every client.

Source: crates/calternal-auth/src/lib.rs

Structs

Account

pub struct Account;

No doc comment.

Implements: ScopeMarker

Source: crates/calternal-auth/src/api.rs:313

Admin

pub struct Admin;

No doc comment.

Implements: ScopeMarker

Source: crates/calternal-auth/src/api.rs:314

AppPassword

pub struct AppPassword

No doc comment.

Fields

• pub id: Uuid
• pub name: String
• pub created_at: i64
• pub scopes: Vec<AppPasswordScope>
• pub home_prefix: Option<String>
• pub plugin_scope: Option<AppPasswordPluginScope>
• pub expires_at: Option<i64>
• pub last_used_at: Option<i64>
• pub last_used_protocol: Option<AppPasswordProtocol>
• pub last_used_ip: Option<String>

Implements: Debug, Clone, Serialize, Deserialize, ToSchema

AppPassword::allows

pub fn allows(&self, protocol: AppPasswordProtocol, access: AppPasswordAccess) -> bool

No doc comment.

Source: crates/calternal-auth/src/store.rs:510

AppPasswordAuthority

pub struct AppPasswordAuthority

No doc comment.

Fields

• pub user: User
• pub app_password: AppPassword

Implements: Debug, Clone

Source: crates/calternal-auth/src/store.rs:532

AppPasswordCacheChange

pub struct AppPasswordCacheChange

Hold cache admission closed for an authority transaction. The server uses this guard for deletion transactions owned outside AuthStore (#512, §21).

Implements: Drop

Source: crates/calternal-auth/src/store.rs:564

AppPasswordOptions

pub struct AppPasswordOptions

No doc comment.

Fields

• pub scopes: Vec<AppPasswordScope>
• pub home_prefix: Option<String>
• pub plugin_scope: Option<AppPasswordPluginScope>
• pub expires_at: Option<i64>

Implements: Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema, Default

AppPasswordOptions::validated

pub fn validated(mut self) -> AuthResult<Self>

Validate and canonicalize the metadata before it becomes Security state.

Source: crates/calternal-auth/src/store.rs:405

AppPasswordPluginScope

pub struct AppPasswordPluginScope

Optional authority for one Plugin, with an optional stable resource ID.

Fields

• pub plugin: String
• pub access: Vec<AppPasswordPluginAccess>
• pub resource_id: Option<Uuid>

Implements: Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:398

AppPasswordScope

pub struct AppPasswordScope

No doc comment.

Fields

• pub protocol: AppPasswordProtocol
• pub access: AppPasswordAccess

Implements: Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:384

AuthConfig

pub struct AuthConfig

No doc comment.

Fields

• pub rp_id: String
• pub rp_origin: String
• pub setup_base_url: String
• pub web_idle_secs: i64
• pub installation_idle_secs: i64
• pub absolute_secs: i64
• pub trusted_proxies: Vec<IpNet>
• pub notes_imap_port: u16: Published implicit-TLS Notes port; defaults to 993 (#428 profiles).
• pub notes_submission_port: u16: Published implicit-TLS non-sending submission port for Apple validation (#428).

Implements: Clone

AuthConfig::new

pub fn new(
        rp_id: String,
        rp_origin: String,
        setup_base_url: String,
        web_idle_secs: i64,
        installation_idle_secs: i64,
        absolute_secs: i64,
    ) -> Self

Trusted proxies are opt-in. Without them only the TCP peer identifies a client.

AuthConfig::validate

pub fn validate(&self) -> AuthResult<()>

Reject non-positive session lifetimes and a setup URL without HTTPS. HTTP is allowed only for loopback hosts so local passkey tests can run in a secure browser context (DESIGN §7; #905).

Source: crates/calternal-auth/src/api.rs:78

AuthState

pub struct AuthState<S: AuthStore>

No doc comment.

Fields

• pub store: S
• pub passkeys: PasskeyService<S>
• pub config: AuthConfig

Implements: Clone

AuthState::new

pub async fn new(
        store: S,
        config: AuthConfig,
        providers: Vec<OidcProvider<S>>,
    ) -> AuthResult<Self>

Build one Instance authority with a shared ceremony budget, including all discovered providers. Clones share admission and pending state (#737).

AuthState::set_profile_signer

pub async fn set_profile_signer(&self, signer: Option<ProfileSigner>)

Replace the in-memory signer after secure startup loading or a validated server configuration update.

AuthState::profile_signing_status

pub async fn profile_signing_status(&self) -> ProfileSigningStatus

Report only safe signer metadata. The Developer ID team ID and key are never returned from the auth state.

AuthState::bootstrap

pub async fn bootstrap(&self) -> AuthResult<()>

No doc comment.

AuthState::replace_oidc_providers

pub async fn replace_oidc_providers(&self, providers: Vec<OidcProvider<S>>) -> AuthResult<()>

Replace discovered providers after a validated instance config edit. Replacement providers reuse the Instance ceremony budget; existing clones retain their state and its leases until completion (#737).

AuthState::limit

pub async fn limit(&self, key: String, budget: u32) -> AuthResult<()>

Share the bounded authentication limiter with protocol listeners (#428). Keys are server-owned surface/IP identities, never credential bytes. Count and key length stay bounded even for refused requests (#737).

AuthState::check_app_password_attempt

pub async fn check_app_password_attempt(&self, peer: &str) -> AuthResult<()>

Block repeated failures without throttling valid CalDAV sync bursts.

AuthState::record_app_password_failure

pub async fn record_app_password_failure(&self, peer: &str)

No doc comment.

AuthState::record_app_password_denial

pub async fn record_app_password_denial(
        &self,
        authority: &AppPasswordAuthority,
        protocol: AppPasswordProtocol,
    ) -> AuthResult<()>

Audit out-of-scope use with a per-credential limit so a stolen or misconfigured client cannot grow Security state without bound.

Source: crates/calternal-auth/src/api.rs:140

CurrentUser

pub struct CurrentUser(pub User, pub SessionAuthority);

No doc comment.

Implements: FromRequestParts<AuthState<S>>

Source: crates/calternal-auth/src/api.rs:310

Data

pub struct Data;

No doc comment.

Implements: ScopeMarker

Source: crates/calternal-auth/src/api.rs:319

Invite

pub struct Invite

No doc comment.

Fields

• pub token: String
• pub role: Role
• pub expires_at: i64
• pub quota_override_bytes: Option<u64>

Implements: Debug, Clone, Serialize, ToSchema

Source: crates/calternal-auth/src/store.rs:330

InviteSummary

pub struct InviteSummary

Admin view of an invite. id is the lowercase hex of the token hash: it names the row for revocation but cannot be redeemed, because only the token itself (shown once at creation) passes consume_invite.

Fields

• pub id: String
• pub role: Role
• pub expires_at: i64
• pub created_by: Uuid
• pub consumed_at: Option<i64>
• pub consumed_by: Option<Uuid>
• pub quota_override_bytes: Option<u64>: None inherits the Instance default; Some(0) means unlimited.

Implements: Debug, Clone, Serialize, ToSchema

Source: crates/calternal-auth/src/store.rs:311

OidcConfig

pub struct OidcConfig

No doc comment.

Fields

• pub name: String
• pub issuer: String
• pub client_id: String
• pub client_secret: String
• pub redirect_uri: String
• pub groups_claim: String
• pub admin_group: String
• pub guest_group: String
• pub groups_authoritative: bool

Implements: Clone, Debug, Deserialize

Source: crates/calternal-auth/src/oidc.rs:25

OidcProvider

pub struct OidcProvider<S: AuthStore>

No doc comment.

Implements: Clone

OidcProvider::issuer

pub fn issuer(&self) -> &str

No doc comment.

OidcProvider::discover

pub async fn discover(config: OidcConfig, store: S) -> AuthResult<Self>

No doc comment.

OidcProvider::name

pub fn name(&self) -> &str

No doc comment.

OidcProvider::role_for_groups

pub fn role_for_groups(&self, groups: &[String]) -> Role

No doc comment.

OidcProvider::start

pub async fn start(&self, link_user: Option<(Uuid, Vec<u8>)>) -> AuthResult<OidcStart>

No doc comment.

OidcProvider::start_reauth

pub async fn start_reauth(
        &self,
        user_id: Uuid,
        session_hash: Vec<u8>,
    ) -> AuthResult<OidcStart>

No doc comment.

OidcProvider::purpose

pub async fn purpose(&self, state: &str) -> Option<OidcPurpose>

Read a pending flow’s purpose without consuming it. Unknown or expired state gives None.

OidcProvider::abandon

pub async fn abandon(&self, state: &str)

Drop a pending flow that failed before completion, so its state cannot be replayed with a different code.

OidcProvider::complete

pub async fn complete(&self, callback: OidcCallback) -> AuthResult<User>

Consume bounded, unexpired state once and validate signed provider claims. Elevation records the provider’s recent authentication time on the initiating session, never the callback time (DESIGN §21, #735/#737).

Source: crates/calternal-auth/src/oidc.rs:41

PasskeyRecord

pub struct PasskeyRecord

Passkey metadata without the stored credential JSON.

Fields

• pub id: Vec<u8>
• pub name: String
• pub created_at: i64
• pub last_used_at: Option<i64>

Implements: Debug, Clone

Source: crates/calternal-auth/src/store.rs:323

PasskeyService

pub struct PasskeyService<S: AuthStore>

No doc comment.

Implements: Clone

PasskeyService::new

pub fn new(store: S, rp_id: &str, rp_origin: &str) -> AuthResult<Self>

No doc comment.

PasskeyService::begin_registration

pub async fn begin_registration(
        &self,
        username: String,
        display_name: String,
        grant: RegistrationGrant,
    ) -> AuthResult<Challenge<CreationChallengeResponse>>

Start a library ceremony in the shared fallback-IP bucket. HTTP starts use the resolved IP; grant validation applies to both callers (#737).

PasskeyService::finish_registration

pub async fn finish_registration(
        &self,
        input: RegistrationFinish,
    ) -> AuthResult<(User, Option<String>)>

No doc comment.

PasskeyService::begin_login

pub async fn begin_login(&self) -> AuthResult<Challenge<RequestChallengeResponse>>

Start library sign-in in the fallback-IP bucket; reserve before building its discoverable-credential challenge (DESIGN §21, #737).

PasskeyService::finish_login

pub async fn finish_login(
        &self,
        input: AssertionFinish,
        kind: SessionKind,
        name: Option<&str>,
        idle_secs: i64,
        absolute_secs: i64,
    ) -> AuthResult<(User, String)>

Consume and verify one login challenge, then issue a fresh session only if its credential is still present at the write boundary (#1043, DESIGN §21).

PasskeyService::begin_assertion

pub async fn begin_assertion(
        &self,
        user_id: Uuid,
        remove: Option<Vec<u8>>,
        session_hash: Vec<u8>,
    ) -> AuthResult<Challenge<RequestChallengeResponse>>

Start library elevation with the same admission bound as HTTP; keep the initiating session binding through completion (§21, #737).

PasskeyService::finish_assertion

pub async fn finish_assertion(
        &self,
        input: AssertionFinish,
        session_hash: &[u8],
    ) -> AuthResult<()>

Verify the selected key’s User, user verification and initiating live session before marking freshness or removing a key. Discovery preserves these checks for larger legacy sets (DESIGN §21, #734 R2). Verify the initiating session’s assertion and bind freshness to the credential’s current ownership before an authority change (#1043, DESIGN §21).

Source: crates/calternal-auth/src/passkey.rs:25

PendingUserDeletion

pub struct PendingUserDeletion

Durable deletion work which the server resumes after a crash.

Fields

• pub user_id: Uuid
• pub actor_user_id: Uuid
• pub action: UserDeletionAction
• pub transfer_id: Option<Uuid>: Random stable folder identity for a transfer, present only for that policy.

Implements: Debug, Clone, PartialEq, Eq

Source: crates/calternal-auth/src/store.rs:833

ProfileSigner

pub struct ProfileSigner(Arc<ProfileSignerInner>);

No doc comment.

Implements: Clone

ProfileSigner::from_pem

pub fn from_pem(
        certificate_pem: &[u8],
        private_key_pem: &[u8],
        chain_pem: &[u8],
    ) -> Result<Self, ProfileSigningError>

Parse and validate the leaf certificate, matching private key and ordered intermediate chain. Callers must check the key file mode before passing its bytes here.

ProfileSigner::sign

pub fn sign(&self, content: &[u8]) -> Result<Vec<u8>, ProfileSigningError>

Create attached CMS SignedData as DER. The certificate and configured intermediate certificates travel with the body for Apple verification.

ProfileSigner::status

pub fn status(&self) -> ProfileSigningStatus

No doc comment.

Source: crates/calternal-auth/src/profile_signing.rs:27

ProfileSigningStatus

pub struct ProfileSigningStatus

No doc comment.

Fields

• pub enabled: bool: True when the certificate and chain are currently valid.
• pub display_name: Option<String>: The company name from the Developer ID common name, with its team ID removed.
• pub expires_at: Option<i64>: The earliest expiry time in the signer certificate chain, in Unix seconds.
• pub expires_soon: bool: True when the earliest expiry is within 30 days.

Implements: Clone, Debug, Default, Eq, PartialEq, Serialize, ToSchema

Source: crates/calternal-auth/src/profile_signing.rs:38

RequireScope

pub struct RequireScope<T>(pub SessionAuthority, PhantomData<T>);

Route-level scope guard for server and plugin APIs.

Implements: FromRequestParts<AuthState<S>>

Source: crates/calternal-auth/src/api.rs:312

ScopeSet

pub struct ScopeSet(u8);

Server-enforced scopes. Agent containers receive DATA; Ask Agent containers also receive READ_ONLY, which the request authority enforces for writes.

Implements: Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema

ScopeSet::ACCOUNT

pub const ACCOUNT: Self

No doc comment.

ScopeSet::ADMIN

pub const ADMIN: Self

No doc comment.

ScopeSet::DATA

pub const DATA: Self

No doc comment.

ScopeSet::READ_ONLY

pub const READ_ONLY: Self

No doc comment.

ScopeSet::DATA_READ_ONLY

pub const DATA_READ_ONLY: Self

No doc comment.

ScopeSet::HUMAN

pub const HUMAN: Self

No doc comment.

ScopeSet::HUMAN_NO_ADMIN

pub const HUMAN_NO_ADMIN: Self

No doc comment.

ScopeSet::contains

pub fn contains(self, other: Self) -> bool

No doc comment.

Source: crates/calternal-auth/src/store.rs:242

Session

pub struct Session

No doc comment.

Fields

• pub id: String
• pub user_id: Uuid
• pub kind: SessionKind
• pub scopes: ScopeSet
• pub resource_scope: Option<ResourceScope>
• pub installation_name: Option<String>
• pub created_at: i64
• pub last_seen_at: i64
• pub expires_at: i64
• pub revoked: bool
• pub current: bool: True only for the session that made this request.

Implements: Debug, Clone, Serialize, ToSchema

Source: crates/calternal-auth/src/store.rs:278

SessionAuthority

pub struct SessionAuthority

No doc comment.

Fields

• pub user: User
• pub token_hash: Vec<u8>
• pub actor: SessionActor: Who holds this session; set by the store from the session row.
• pub scopes: ScopeSet
• pub resource_scope: Option<ResourceScope>
• pub asserted_at: Option<i64>

Implements: Debug, Clone

SessionAuthority::fresh

pub fn fresh(&self) -> bool

No doc comment.

Source: crates/calternal-auth/src/store.rs:262

SqliteAuthStore

pub struct SqliteAuthStore

No doc comment.

Implements: Clone, AuthStore

SqliteAuthStore::invalidate_app_password_cache

pub fn invalidate_app_password_cache(&self)

Discard positive entries after a trusted out-of-band fixture change. Production transactions use the change guard before their first write (#512, DESIGN §21).

SqliteAuthStore::begin_app_password_change

pub fn begin_app_password_change(&self) -> AppPasswordCacheChange

Guard an external Security state transaction before its first write. Commit with commit_app_password_change so request cancellation cannot reopen the cache while SQLite is still committing (#512, DESIGN §21).

SqliteAuthStore::commit_app_password_change

pub async fn commit_app_password_change(
        &self,
        tx: Transaction<'static, Sqlite>,
        change: AppPasswordCacheChange,
    ) -> AuthResult<()>

Keep the change guard alive in an owned task until commit finishes. Dropping the request only detaches the task; its final generation bump still rejects old verifiers. Errors also discard positive entries (#512).

SqliteAuthStore::set_app_password_options

pub async fn set_app_password_options(
        &self,
        user_id: Uuid,
        id: Uuid,
        options: AppPasswordOptions,
    ) -> AuthResult<()>

Change restrictions and retire the old App Password atomically. A User must issue a new credential for the new scopes. This trusted store hook is not an additional HTTP endpoint (#512 round 2, DESIGN §21).

SqliteAuthStore::apply_instance_open_signup

pub async fn apply_instance_open_signup(&self, enabled: bool) -> AuthResult<()>

Apply the server-owned instance file’s signup policy after validation. The file can be edited by the host, so this path has no user actor.

SqliteAuthStore::begin_user_deletion

pub async fn begin_user_deletion(
        &self,
        tx: &mut Transaction<'_, Sqlite>,
        actor_user_id: Uuid,
        user_id: Uuid,
        requested: UserDeletionAction,
    ) -> AuthResult<PendingUserDeletion>

Mark a user for deletion inside the server’s grant-revocation transaction. The stored action makes filesystem work resumable after a process crash.

SqliteAuthStore::pending_user_deletions

pub async fn pending_user_deletions(&self) -> AuthResult<Vec<PendingUserDeletion>>

Return durable deletion work in a stable order for startup recovery.

SqliteAuthStore::finish_user_deletion

pub async fn finish_user_deletion(&self, user_id: Uuid) -> AuthResult<()>

Remove a user row after its persisted Home action has completed.

SqliteAuthStore::revoke_session_for_recovery

pub async fn revoke_session_for_recovery(&self, user: Uuid, hash: &[u8]) -> AuthResult<()>

Revoke a recovery credential, accepting an already revoked/missing row. Trusted server cleanup must survive a crash after FULL revocation but before binding deletion. A live session of another User is denied (#824, DESIGN §2). Public revocation keeps its strict InvalidToken response.

SqliteAuthStore::connect

pub async fn connect(url: &str) -> AuthResult<Self>

Open and migrate the security-state Index (DESIGN §2; #905). File-backed stores use WAL and at most eight connections; memory stores use one connection. Pool acquisition times out after two seconds, so request handlers can return 503 instead of waiting without a bound.

SqliteAuthStore::from_pool

pub fn from_pool(pool: SqlitePool) -> Self

No doc comment.

SqliteAuthStore::from_pools

pub fn from_pools(pool: SqlitePool, read_pool: SqlitePool) -> Self

Build the authority store with separate pools for writes and reads. Activity shares the authority policy for compatibility. The server uses from_pools_with_activity to keep request telemetry NORMAL (#824, DESIGN §2).

SqliteAuthStore::from_pools_with_cache_key

pub fn from_pools_with_cache_key(
        pool: SqlitePool,
        read_pool: SqlitePool,
        key: [u8; 32],
    ) -> Self

Build the server store with the secret loaded once from the existing Index secret store. The fallback constructors use restart-random keys for isolated stores and tests; production persists its key (#512).

SqliteAuthStore::from_pools_with_activity

pub fn from_pools_with_activity(
        pool: SqlitePool,
        read_pool: SqlitePool,
        activity_pool: SqlitePool,
    ) -> Self

Use FULL for authority, read-only readers, and a distinct NORMAL activity pool. The activity pool must be the server’s one-connection ordinary writer. It permits metadata-only writes and a nonblocking checkout before session refresh; holding it excludes a competing ordinary transaction (#824, DESIGN §2).

SqliteAuthStore::for_index

pub fn for_index(db: &calternal_db::Db) -> Self

Build the production Auth store for one Index (#824, DESIGN §2).

This is the only place that maps Index pools to Auth roles: the FULL authority connection for Security state, the read-only readers, and the NORMAL ordinary writer for App Password activity only. The server, the durability harness and repository tests all use it, so a test of this constructor is a test of the production selection.

SqliteAuthStore::for_index_with_cache_key

pub fn for_index_with_cache_key(db: &calternal_db::Db, key: [u8; 32]) -> Self

Apply the persisted verification key after the production pool mapping. Cache setup must never select a NORMAL authority pool (#512, #824, DESIGN §§2, 21); both server startup and durability tests use for_index.

SqliteAuthStore::ensure_durable_authority

pub async fn ensure_durable_authority(&self) -> AuthResult<()>

Refuse to serve when Security state writes would not sync each commit.

SQLite reports synchronous per connection: 2 is FULL and 3 is EXTRA. NORMAL (1) in WAL mode can lose an acknowledged revocation on power loss (#824). The server calls this once at startup, before any route runs.

Source: crates/calternal-auth/src/store.rs:1131

User

pub struct User

No doc comment.

Fields

• pub id: Uuid
• pub username: String
• pub display_name: String
• pub role: Role
• pub disabled: bool

Implements: Debug, Clone, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:182

UserSummary

pub struct UserSummary

Admin view of a User. It has no credential or session material.

Fields

• pub id: Uuid
• pub username: String
• pub display_name: String
• pub role: Role
• pub disabled: bool
• pub deletion_pending: bool: True while the server drains the durable Home deletion action.
• pub created_at: i64
• pub quota_override_bytes: Option<u64>: None inherits the Instance default; Some(0) means unlimited.

Implements: Debug, Clone, Serialize, ToSchema

Source: crates/calternal-auth/src/store.rs:295

Enums

AppPasswordAccess

pub enum AppPasswordAccess

No doc comment.

Variants

• Read
• Write
• UploadOnly
• Full

Implements: Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:376

AppPasswordPluginAccess

pub enum AppPasswordPluginAccess

No doc comment.

Variants

• Read
• Write

Implements: Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:391

AppPasswordProtocol

pub enum AppPasswordProtocol

No doc comment.

Variants

• CalDav
• Notes: Apple Notes IMAP bridge credentials (#428); independent of CalDAV.
• Mail: Internal Mail grant in the shared device preset (#486, DESIGN §53).
• WebDav
• Api
• Mcp

Implements: Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, ToSchema

AppPasswordProtocol::as_str

pub fn as_str(self) -> &'static str

No doc comment.

Source: crates/calternal-auth/src/store.rs:338

AuthError

pub enum AuthError

No doc comment.

Variants

• Unauthenticated
• Forbidden
• OutOfScope
• InvalidToken
• InvalidRequest
• Conflict
• RateLimited
• Internal
• Unavailable

Implements: Debug, Error, IntoResponse

Source: crates/calternal-auth/src/error.rs:14

OidcPurpose

pub enum OidcPurpose

What a pending flow does when it completes. The browser callback reads it before completion to choose where to send the browser.

Variants

• SignIn
• Link
• Reauth

Implements: Clone, Copy, Debug, PartialEq, Eq

Source: crates/calternal-auth/src/oidc.rs:59

ProfileSigningError

pub enum ProfileSigningError

No doc comment.

Variants

• InvalidCertificate
• InvalidPrivateKey
• UnsupportedKey
• KeyMismatch
• InvalidChain
• CertificateNotYetValid
• CertificateExpired
• InvalidCommonName
• SignFailed

Implements: Clone, Copy, Debug, Eq, PartialEq, std::fmt::Display, std::error::Error

ProfileSigningError::reason

pub fn reason(self) -> &'static str

Return a safe reason for startup logs. OpenSSL errors can include implementation details, so they are not logged with certificate data.

Source: crates/calternal-auth/src/profile_signing.rs:50

RegistrationGrant

pub enum RegistrationGrant

No doc comment.

Variants

• Setup(String)
• Invite(String)
• Existing(Uuid, Vec<u8>)
• Recovery(Uuid, String)
• Reenrol(Uuid, String)
• OpenSignup

Implements: Clone

Source: crates/calternal-auth/src/passkey.rs:60

ResourceScope

pub enum ResourceScope

The files layer must intersect this limit with the User’s current shares.

Variants

• HomeAndShared { user_id: Uuid }

Implements: Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:258

Role

pub enum Role

No doc comment.

Variants

• Owner
• Admin
• Member
• Guest

Implements: Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema

Role::as_str

pub fn as_str(self) -> &'static str

No doc comment.

Role::can_admin

pub fn can_admin(self) -> bool

No doc comment.

Source: crates/calternal-auth/src/store.rs:143

SessionActor

pub enum SessionActor

Which kind of actor holds a session (#980).

The row stores it in installation_type at issuance, and every request carries it to the Plugin context. Routes that must never serve a container (for example the AI routes, which would let a turn start more turns or read the User’s other prompts) check this value. They never infer it from the scopes, because scopes describe what a session may touch, not who holds it.

Variants

• User: The User’s own session: a browser cookie or a human Installation token such as the CLI.
• Agent: The token handed to an Agent turn’s container.
• Ask: The read-only token handed to an Ask turn’s container.

Implements: Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:212

SessionKind

pub enum SessionKind

No doc comment.

Variants

• Web
• Installation

Implements: Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema

Source: crates/calternal-auth/src/store.rs:191

UserDeletionAction

pub enum UserDeletionAction

The action an administrator selected for a pending Home deletion.

Variants

• Archive { expires_at: i64 }
• Transfer { target_user_id: Uuid }
• Purge

Implements: Debug, Clone, PartialEq, Eq

Source: crates/calternal-auth/src/store.rs:825

Traits

AuthStore

pub trait AuthStore: Clone + Send + Sync + 'static

No doc comment.

AuthStore::create_app_password

async fn create_app_password(
        &self,
        user: Uuid,
        name: &str,
        options: AppPasswordOptions,
    ) -> AuthResult<(AppPassword, String)>;

No doc comment.

AuthStore::list_app_passwords

async fn list_app_passwords(&self, user: Uuid) -> AuthResult<Vec<AppPassword>>;

No doc comment.

AuthStore::active_app_password

async fn active_app_password(&self, user: Uuid, id: Uuid) -> AuthResult<Option<AppPassword>>;

Return the current grant only while its User and credential are active. Long-lived protocols must use this, not the Settings listing (#787, §21).

AuthStore::revoke_app_password

async fn revoke_app_password(&self, user: Uuid, id: Uuid) -> AuthResult<()>;

No doc comment.

AuthStore::verify_app_password

async fn verify_app_password(
        &self,
        username: Option<&str>,
        secret: &str,
    ) -> AuthResult<Option<AppPasswordAuthority>>;

Verify the secret and return its current User authority. The SQLite store shares a short-lived result across DAV and MCP callers (#512).

AuthStore::record_app_password_use

async fn record_app_password_use(
        &self,
        id: Uuid,
        protocol: AppPasswordProtocol,
        coarse_ip: &str,
    ) -> AuthResult<()>;

No doc comment.

AuthStore::record_app_password_denial

async fn record_app_password_denial(
        &self,
        user: Uuid,
        id: Uuid,
        protocol: AppPasswordProtocol,
    ) -> AuthResult<()>;

No doc comment.

AuthStore::user

async fn user(&self, id: Uuid) -> AuthResult<Option<User>>;

No doc comment.

AuthStore::user_by_username

async fn user_by_username(&self, username: &str) -> AuthResult<Option<User>>;

No doc comment.

AuthStore::users

async fn users(&self) -> AuthResult<Vec<User>>;

No doc comment.

AuthStore::count_users

async fn count_users(&self) -> AuthResult<i64>;

No doc comment.

AuthStore::update_profile

async fn update_profile(
        &self,
        user_id: Uuid,
        username: &str,
        display_name: &str,
    ) -> AuthResult<User>;

No doc comment.

AuthStore::set_role

async fn set_role(&self, actor: Uuid, user_id: Uuid, role: Role) -> AuthResult<()>;

No doc comment.

AuthStore::set_disabled

async fn set_disabled(&self, actor: Uuid, user_id: Uuid, disabled: bool) -> AuthResult<()>;

No doc comment.

AuthStore::set_quota_override

async fn set_quota_override(
        &self,
        actor: Uuid,
        user_id: Uuid,
        quota_override_bytes: Option<u64>,
    ) -> AuthResult<()>;

No doc comment.

AuthStore::prepare_setup

async fn prepare_setup(&self) -> AuthResult<Option<String>>;

No doc comment.

AuthStore::setup_redeemable

async fn setup_redeemable(&self, token: &str) -> AuthResult<bool>;

Check the one-time setup grant before allocating a ceremony. The consume transaction must still recheck it (DESIGN §7, #737).

AuthStore::consume_setup

async fn consume_setup(
        &self,
        token: &str,
        id: Uuid,
        username: &str,
        display_name: &str,
        credential_id: &[u8],
        credential_name: &str,
        credential_json: &str,
    ) -> AuthResult<User>;

Keep token consumption and its bounded initial credential atomic (DESIGN §7, #734 R2). Failed insertion leaves the grant usable.

AuthStore::list_users

async fn list_users(&self) -> AuthResult<Vec<UserSummary>>;

No doc comment.

AuthStore::create_invite

async fn create_invite(
        &self,
        actor: Uuid,
        role: Role,
        ttl_secs: i64,
        quota_override_bytes: Option<u64>,
    ) -> AuthResult<Invite>;

No doc comment.

AuthStore::list_invites

async fn list_invites(&self) -> AuthResult<Vec<InviteSummary>>;

No doc comment.

AuthStore::invite_redeemable

async fn invite_redeemable(&self, token: &str) -> AuthResult<bool>;

Whether an invite token can still be redeemed. Only a hint for the start step; consume_invite re-checks inside its transaction.

AuthStore::revoke_invite

async fn revoke_invite(&self, actor: Uuid, id_hex: &str) -> AuthResult<()>;

Delete an unconsumed invite. A consumed invite is history, not authority.

AuthStore::consume_invite

async fn consume_invite(
        &self,
        token: &str,
        id: Uuid,
        username: &str,
        display_name: &str,
        credential_id: &[u8],
        credential_name: &str,
        credential_json: &str,
    ) -> AuthResult<User>;

Commit the initial credential, counted admission and item grant together. BEGIN IMMEDIATE serializes completion with revoke and policy changes (§54, #1035).

AuthStore::consume_open_signup

async fn consume_open_signup(
        &self,
        id: Uuid,
        username: &str,
        display_name: &str,
        credential_id: &[u8],
        credential_name: &str,
        credential_json: &str,
    ) -> AuthResult<User>;

Create an enabled local-signup User and a supported initial key in one transaction; no partial account can survive refusal (§7, #734 R2).

AuthStore::invite_destination

async fn invite_destination(&self, user_id: Uuid) -> AuthResult<Option<String>>;

Post-enrolment destination for a new User, fixed by the owner (#1035).

AuthStore::share_invites_enabled

async fn share_invites_enabled(&self) -> AuthResult<bool>;

Instance switch for share invitations (DESIGN §54).

AuthStore::set_share_invites_enabled

async fn set_share_invites_enabled(&self, actor: Uuid, enabled: bool) -> AuthResult<()>;

Only an active admin may change who can create share invitations (#1035).

AuthStore::open_signup

async fn open_signup(&self) -> AuthResult<bool>;

No doc comment.

AuthStore::set_open_signup

async fn set_open_signup(&self, actor: Uuid, value: bool) -> AuthResult<()>;

No doc comment.

AuthStore::record_security_event

async fn record_security_event(&self, actor: Uuid, event: &str, detail: &str)
    -> AuthResult<()>;

Add a bounded, admin-attributed security event for a server operation.

AuthStore::issue_session

async fn issue_session(
        &self,
        user_id: Uuid,
        kind: SessionKind,
        name: Option<&str>,
        idle_secs: i64,
        absolute_secs: i64,
    ) -> AuthResult<String>;

No doc comment.

AuthStore::issue_passkey_session

async fn issue_passkey_session(
        &self,
        user_id: Uuid,
        credential_id: &[u8],
        kind: SessionKind,
        name: Option<&str>,
        idle_secs: i64,
        absolute_secs: i64,
    ) -> AuthResult<String>;

Issue a fresh human session only while the verified credential belongs to this User. Check presence in the insert transaction (#1043, DESIGN §21).

AuthStore::mark_passkey_asserted

async fn mark_passkey_asserted(
        &self,
        hash: &[u8],
        user_id: Uuid,
        credential_id: &[u8],
    ) -> AuthResult<()>;

Mark the initiating session fresh only while its verified credential still belongs to this User at the write boundary (#1043, DESIGN §21).

AuthStore::authenticate_session

async fn authenticate_session(
        &self,
        token: &str,
        kind: SessionKind,
        idle_secs: i64,
    ) -> AuthResult<Option<User>>;

No doc comment.

AuthStore::session_authority

async fn session_authority(
        &self,
        token: &str,
        kind: SessionKind,
        idle_secs: i64,
    ) -> AuthResult<Option<SessionAuthority>>;

No doc comment.

AuthStore::mark_asserted

async fn mark_asserted(&self, hash: &[u8]) -> AuthResult<()>;

No doc comment.

AuthStore::mark_asserted_at

async fn mark_asserted_at(&self, hash: &[u8], authenticated_at: i64) -> AuthResult<()>;

Preserve provider authentication time so callback receipt cannot renew the five-minute authority window (DESIGN §21, #735).

AuthStore::require_live_session

async fn require_live_session(&self, hash: &[u8], user_id: Uuid) -> AuthResult<()>;

Recheck the session’s User, revocation and both expiry bounds for retained authority (#788, DESIGN §21).

AuthStore::require_fresh

async fn require_fresh(&self, hash: &[u8], user_id: Uuid) -> AuthResult<()>;

No doc comment.

AuthStore::issue_agent_session

async fn issue_agent_session(&self, user_id: Uuid, name: &str) -> AuthResult<String>;

No doc comment.

AuthStore::issue_ask_agent_session

async fn issue_ask_agent_session(&self, user_id: Uuid, name: &str) -> AuthResult<String>;

No doc comment.

AuthStore::renew_agent_session

async fn renew_agent_session(&self, token: &str) -> AuthResult<String>;

No doc comment.

AuthStore::revoke_all

async fn revoke_all(
        &self,
        actor: Uuid,
        current_hash: &[u8],
        keep_current: bool,
    ) -> AuthResult<u64>;

No doc comment.

AuthStore::list_sessions

async fn list_sessions(&self, user_id: Uuid) -> AuthResult<Vec<Session>>;

No doc comment.

AuthStore::revoke_session

async fn revoke_session(&self, actor: Uuid, token_hash_hex: &str) -> AuthResult<()>;

No doc comment.

AuthStore::put_passkey_bound

async fn put_passkey_bound(
        &self,
        user_id: Uuid,
        session_hash: &[u8],
        credential_id: &[u8],
        name: &str,
        json: &str,
    ) -> AuthResult<()>;

Add only to the initiating live, fresh session. The insertion checks the resulting key set in the same transaction (DESIGN §21, #734 R2).

AuthStore::put_passkey

async fn put_passkey(
        &self,
        user_id: Uuid,
        credential_id: &[u8],
        name: &str,
        json: &str,
    ) -> AuthResult<()>;

Insert a supported key set for library callers; every grant uses the same insertion invariant and audit transaction (DESIGN §7, #734 R2).

AuthStore::passkey

async fn passkey(&self, credential_id: &[u8]) -> AuthResult<Option<(Uuid, String)>>;

No doc comment.

AuthStore::passkeys

async fn passkeys(&self, user_id: Uuid) -> AuthResult<Vec<(Vec<u8>, String, String)>>;

No doc comment.

AuthStore::passkey_set_fits

async fn passkey_set_fits(&self, user_id: Uuid) -> AuthResult<bool>

Check the shared key-set bound before loading ceremony state (#734 R2).

AuthStore::passkey_records

async fn passkey_records(&self, user_id: Uuid) -> AuthResult<Vec<PasskeyRecord>>;

No doc comment.

AuthStore::rename_passkey

async fn rename_passkey(
        &self,
        user_id: Uuid,
        credential_id: &[u8],
        name: &str,
    ) -> AuthResult<PasskeyRecord>;

Change only the label of the User’s own passkey. A label carries no authority, so this needs no fresh assertion.

AuthStore::update_passkey

async fn update_passkey(&self, credential_id: &[u8], json: &str) -> AuthResult<()>;

No doc comment.

AuthStore::remove_passkey

async fn remove_passkey(
        &self,
        user_id: Uuid,
        session_hash: &[u8],
        credential_id: &[u8],
    ) -> AuthResult<()>;

No doc comment.

AuthStore::oidc_user

async fn oidc_user(&self, issuer: &str, subject: &str) -> AuthResult<Option<User>>;

No doc comment.

AuthStore::reconcile_oidc_role

async fn reconcile_oidc_role(&self, user_id: Uuid, role: Role) -> AuthResult<User>;

No doc comment.

AuthStore::create_oidc_user

async fn create_oidc_user(
        &self,
        issuer: &str,
        subject: &str,
        username: &str,
        display_name: &str,
        role: Role,
    ) -> AuthResult<User>;

No doc comment.

AuthStore::link_oidc

async fn link_oidc(&self, user_id: Uuid, issuer: &str, subject: &str) -> AuthResult<()>;

No doc comment.

AuthStore::unlink_oidc

async fn unlink_oidc(&self, user_id: Uuid, issuer: &str) -> AuthResult<()>;

No doc comment.

AuthStore::oidc_issuers

async fn oidc_issuers(&self, user_id: Uuid) -> AuthResult<Vec<String>>;

Issuers linked to the User. Subjects stay in the store.

AuthStore::legacy_recovery_codes

async fn legacy_recovery_codes(&self, user_id: Uuid) -> AuthResult<u32>;

Unconsumed recovery codes from before the single recovery key.

AuthStore::recovery_codes

async fn recovery_codes(&self, user_id: Uuid) -> AuthResult<Vec<String>>;

No doc comment.

AuthStore::issue_recovery_key

async fn issue_recovery_key(
        &self,
        user_id: Uuid,
        session_hash: Option<&[u8]>,
    ) -> AuthResult<String>;

No doc comment.

AuthStore::has_recovery_key

async fn has_recovery_key(&self, user_id: Uuid) -> AuthResult<bool>;

No doc comment.

AuthStore::verify_recovery

async fn verify_recovery(&self, user_id: Uuid, code: &str) -> AuthResult<bool>;

No doc comment.

AuthStore::enroll_recovery_key

async fn enroll_recovery_key(
        &self,
        user_id: Uuid,
        phrase: &str,
        credential_id: &[u8],
        name: &str,
        json: &str,
    ) -> AuthResult<String>;

Rotate the recovery key, revoke sessions and insert the bounded new credential atomically. Refusal preserves the old key (§7, #734 R2).

AuthStore::enroll_recovery

async fn enroll_recovery(
        &self,
        user_id: Uuid,
        code: &str,
        credential_id: &[u8],
        name: &str,
        json: &str,
    ) -> AuthResult<String>;

Redeem a legacy code only with a supported resulting key set. Its consumption and session revocation roll back on refusal (§7, #734 R2).

AuthStore::issue_reenrol

async fn issue_reenrol(&self, actor: Uuid, user_id: Uuid, ttl_secs: i64) -> AuthResult<String>;

No doc comment.

AuthStore::reenrol_target

async fn reenrol_target(&self, token: &str) -> AuthResult<Option<Uuid>>;

No doc comment.

AuthStore::enroll_reenrol

async fn enroll_reenrol(
        &self,
        token: &str,
        user_id: Uuid,
        credential_id: &[u8],
        name: &str,
        json: &str,
    ) -> AuthResult<()>;

No doc comment.

Source: crates/calternal-auth/src/store.rs:859

Type aliases

AuthResult

pub type AuthResult<T> = Result<T, AuthError>;

No doc comment.

Source: crates/calternal-auth/src/error.rs:11

Functions

client_ip

pub fn client_ip(peer: IpAddr, forwarded: Option<&str>, trusted: &[IpNet]) -> IpAddr

Resolve a client address only through configured trusted proxies.

Source: crates/calternal-auth/src/api.rs:705

decode_token_hash

pub fn hex_decode(s: &str) -> Option<Vec<u8>>

Decode a 32-byte hash id. Works on bytes: slicing a str by byte offset panics inside a multi-byte character, and ids come straight from URLs.

Source: crates/calternal-auth/src/store.rs:3850

encode_token_hash

pub fn hex_encode(bytes: &[u8]) -> String

Encode a hash-only management ID shared by admin and item invites (§54, #1035).

Source: crates/calternal-auth/src/store.rs:3845

extract_authority

pub async fn extract_authority<S: AuthStore>(
    parts: &mut Parts,
    state: &AuthState<S>,
) -> AuthResult<SessionAuthority>

Resolve the same cookie or bearer session used by auth route guards. Server middleware uses this for plugin request context.

Source: crates/calternal-auth/src/api.rs:364

is_trusted_proxy

pub fn is_trusted_proxy(peer: IpAddr, trusted: &[IpNet]) -> bool

Return whether a TCP peer is allowed to supply forwarded client addresses.

Source: crates/calternal-auth/src/api.rs:700

new_token

pub fn new_token() -> String

No doc comment.

Source: crates/calternal-auth/src/token.rs:6

openapi

pub fn openapi() -> utoipa::openapi::OpenApi

OpenAPI fragment to merge into the server’s instance API document.

Source: crates/calternal-auth/src/api.rs:2487

router

pub fn router<S: AuthStore>(state: AuthState<S>) -> Router

No doc comment.

Source: crates/calternal-auth/src/api.rs:613

token_hash

pub fn token_hash(token: &str) -> Vec<u8>

No doc comment.

Source: crates/calternal-auth/src/token.rs:12

Constants

SESSION_COOKIE_CLEAR

pub const SESSION_COOKIE_CLEAR: &str

Expires the session cookie. Sent on sign-out, and by the server when a browser presents a cookie whose session no longer resolves.

Source: crates/calternal-auth/src/api.rs:44