Struct AccountSession 

pub struct AccountSession { /* private fields */ }

Unlocked Account access, created by login or explicit caller-held credentials

Represents an authenticated account with decrypted private keys loaded in memory. The AccountSession struct provides access to key management, tracked databases, and bootstrap approval operations.

Implementations

impl AccountSession

pub async fn from_signer( instance: &Instance, signer: AccountSigner, ) -> Result<Self>

Open a full session using an explicit signer and Account locator, without reading or registering a daemon login. Ordinary Account Auth is checked. Key hints, activation and tracking live only for this session; background sync is not enabled. The signer may use an explicit delegation identity. For a service, supply a connection authenticated by super::AccountSigner::connect; this constructor never reauthenticates or rebinds an existing connection.

pub async fn from_credentials( instance: &Instance, credentials: UnlockedCredentials, account_key: &PublicKey, ) -> Result<Self>

Consume caller-unlocked credentials using an explicitly selected Account key. No personal/default key fallback or daemon bundle lookup occurs. Persisting caller-owned credentials remains the caller’s responsibility; session additions do not alter the original encrypted bundle.

pub fn acting_as( &self, key_id: &PublicKey, identity: Option<SigKey>, ) -> Result<AccountSigner>

Bind a newly selected actual signer without changing existing handles. None selects direct-key Auth; delegation requires an explicit identity. References and key-to-Identity hints never supply authority here.

pub fn login_id(&self) -> &str

Instance-local login record UUID, or empty for a caller-held session. This is not the Account’s portable identity. Use Account::id (via Self::account) for the Account’s identity.

pub fn username(&self) -> &str

Local login name, or empty for a caller-held session.

pub fn account(&self) -> &Account

The Account this session unlocks.

Its root ID is the Account’s stable identity. Read and open application references with Self::reference and Self::open_reference.

pub fn backend(&self) -> &Arc<dyn Backend>

Get a reference to the backend seam.

pub fn account_info(&self) -> Option<&AccountInfo>

Registered login metadata, or None for a caller-held session.

pub async fn is_admin(&self) -> Result<bool>

Whether this account is an instance admin.

“Instance admin” means the account’s default pubkey holds Admin in the _users system database’s auth_settings. The admin/admin account created during instance bootstrap is auto-promoted; subsequent accounts land as non-admins until promoted via InstanceAdmin::grant_instance_admin.

Returns false if the key resolution fails (key not in auth_settings, non-Admin permission, etc.). For the capability handle rather than a bool, use Self::admin.

pub async fn admin(&self) -> Result<InstanceAdmin<'_>>

Obtain the instance-admin capability view.

Returns an InstanceAdmin only if this account’s default key holds Admin on the _users system database. All admin-gated operations (creating accounts, listing accounts, promoting admins) live on the returned view, so the privilege boundary is explicit at the call site and those operations need no further permission check of their own.

Errors

• AccountError::InsufficientPermissions if this account is not an instance admin.

pub fn logout(self) -> Result<()>

Logout (consumes self and clears decrypted keys from memory)

The session’s key manager is cleared on drop. Independently retained signer/database handles own their own key clones and remain usable; logout is not revocation or invalidation of those handles.

pub fn new_database(&mut self) -> DatabaseBuilder<'_>

Start building a new database via the chainable DatabaseBuilder API.

The builder collects settings, key policy, and store initializers, then produces a fully-initialized database in a single genesis entry when DatabaseBuilder::build is called.

For the lower-level direct constructor see Self::create_database.

pub async fn create_database( &mut self, settings: Doc, key_id: &PublicKey, ) -> Result<Database>

Create a new database with explicit key selection.

This method requires you to specify which key should be used to create and manage the database, providing explicit control over key-database relationships.

Arguments

• settings - Initial database settings (metadata, name, etc.)
• key_id - The ID of the key to use for this database (public key string)

Returns

The created Database

Errors

• Returns an error if the specified key_id doesn’t exist
• Returns an error if the key cannot be retrieved

Example

// Get available keys
let keys = account.list_keys()?;
let key_id = &keys[1]; // Use the second key

// Create database with explicit key selection
let mut settings = Doc::new();
settings.set("name", "My Database");
let database = account.new_database(settings, key_id)?;

pub async fn create_database_with_init<F>( &mut self, settings: Doc, key_id: &PublicKey, init: F, ) -> Result<Database>

where F: AsyncFnOnce(&Transaction) -> Result<()>,

Creates a new database with an initialization callback that runs inside the genesis transaction.

This is the underlying constructor used by Self::create_database and by Self::new_database (the builder API). The callback receives the genesis transaction after _settings and _root have been staged but before commit, allowing additional subtrees to be written into the same entry that establishes the database root. See Database::create_with_init for details on the atomicity guarantee.

After the genesis entry commits, this method performs the standard installation-local tracking write (key mapping and TrackedDatabase) in one atomic native record replacement, separate from genesis.

pub async fn open_database(&self, root_id: &ID) -> Result<Database>

Open an existing database by its root ID using this account’s keys.

This method automatically:

1. Finds an appropriate key that has access to the database
2. Retrieves the decrypted SigningKey from the AccountKeyManager
3. Gets the SigKey mapping for this database
4. Creates a Database instance configured with the account’s key

The returned Database will use the account’s provided key for all operations, without requiring backend key lookups.

Arguments

• root_id - The root entry ID of the database

Returns

The opened Database configured to use this account’s keys

Errors

• Returns an error if no key is found for the database
• Returns an error if no SigKey mapping exists
• Returns an error if the key is not in the AccountKeyManager

pub async fn open_database_with_key( &self, root_id: &ID, key_id: &PublicKey, ) -> Result<Database>

Open an existing database with an explicitly chosen key.

Equivalent to open_database, but selects the account’s signing key by public key instead of relying on find_key’s iteration order. Use this when the account holds multiple authorized keys for a database and you need writes signed by a specific one (e.g. agent-as-signer scenarios where cryptographic provenance matters, not just authorization).

The key_id is purely a selector into this account’s AccountKeyManager; no crypto material is passed in.

Arguments

• root_id - The root entry ID of the database
• key_id - Public key of the account-held key to sign with

Returns

The opened Database configured to use the specified key

Errors

• Returns an error if the root entry does not exist
• Returns an error if the account does not hold a key with that pubkey
• Returns an error if the key has no SigKey mapping for this database

pub async fn find_database( &self, name: impl AsRef<str>, ) -> Result<Vec<Database>>

Find databases by name among the account’s tracked databases.

Searches only the databases this account has tracked for those matching the given name.

Arguments

• name - Database name to search for

Returns

Vector of matching databases from the account’s tracked list

pub fn find_key(&self, database_id: &ID) -> Result<Option<PublicKey>>

Find which key can access a database.

Searches this account’s keys to find one that can access the specified database. Considers the SigKey mappings stored in account key metadata.

Returns the key_id of a suitable key, preferring keys with mappings for this database.

Arguments

• database_id - The ID of the database

Returns

Some(key_id) if a suitable key is found, None if no keys can access this database

pub fn key_mapping( &self, key_id: &PublicKey, database_id: &ID, ) -> Result<Option<SigKey>>

Get the resolved SigKey mapping for a key in a specific database.

Users map their private keys to SigKey identifiers on a per-database basis. This retrieves the resolved SigKey that a specific key uses in a specific database’s authentication settings.

Internally, None in the stored mapping means “default pubkey identity”, which this method resolves to the concrete SigKey::from_pubkey(...) value.

Arguments

• key_id - The account’s key identifier
• database_id - The database ID

Returns

Ok(Some(sigkey)) if a mapping exists (resolved to concrete SigKey), Ok(None) if no mapping is configured for this database

Errors

Returns an error if the key_id doesn’t exist in the AccountKeyManager

pub async fn map_key( &mut self, key_id: &PublicKey, database_id: &ID, sigkey: SigKey, ) -> Result<()>

Map a key to a SigKey identity for a specific database.

Registers that this account’s key should be used with a specific SigKey identity when interacting with a database. This is typically used when an account has been granted access to a database and needs to configure their local key to work with it.

If the provided SigKey matches the default pubkey identity for this key, it is normalized to None internally (compact storage for the common case).

Multi-Key Support

Note: A database may have mappings to multiple keys. This is useful for multi-device scenarios where the same account wants to access a database from different devices, each with their own key.

Arguments

• key_id - The account’s key identifier (public key)
• database_id - The database ID
• sigkey - The SigKey identity to use for this database

Errors

Returns an error if the key_id doesn’t exist in the account database

pub async fn set_reference( &self, namespace: &str, name: &str, database_id: &ID, ) -> Result<()>

Store a direct reference to a database in this Account.

Names must be nonempty and contain no dots; they are aliases, not paths. Overwrites any existing reference with the same namespace and name. This is a plain CRDT write, not a compare-and-set: two initializers that both saw no reference can both create a target and both write. Serialize first-time initialization through one writer. To repair a partial initialization, write the ID of the target that was already created.

pub async fn reference(&self, namespace: &str, name: &str) -> Result<Option<ID>>

Read a reference stored with Self::set_reference.

Names must be nonempty and contain no dots. Returns Ok(None) only when the Account has no such reference. Every other failure, including unreadable or malformed reference data, is an error and must not be treated as permission to create a replacement. Reads only this reference; no other database is opened.

pub async fn open_reference( &self, namespace: &str, name: &str, ) -> Result<Option<Database>>

Open the database named by a reference.

Returns Ok(None) only when the reference is absent. A present reference opens through Self::open_database, so a missing key, pending access or unavailable target is an error, never None.

pub async fn add_private_key( &mut self, display_name: Option<&str>, ) -> Result<PublicKey>

Add a new private key to this account’s keyring.

Generates a new Ed25519 keypair. Registered sessions encrypt it in the native complete bundle and atomically update its metadata, including for empty-password accounts. Caller-held sessions update only their in-memory bundle; persistence is explicit.

Arguments

• display_name - Optional display name for the key

Returns

The key ID (public key string)

pub async fn import_private_key( &mut self, private_key: PrivateKey, display_name: Option<&str>, ) -> Result<PublicKey>

Add exactly one caller-supplied key to this local bundle. Duplicate keys fail without replacing metadata. This neither enrolls an Identity member nor creates target mappings; database Auth remains independent of custody. Caller-held sessions still require explicit external persistence.

pub fn list_keys(&self) -> Result<Vec<PublicKey>>

List all key IDs owned by this account.

Keys are sorted by creation timestamp (oldest first), then public key ID for ties. Use Self::get_default_key for the explicit default.

Returns

Vector of PublicKeys sorted by creation time

pub fn get_default_key(&self) -> Result<PublicKey>

Get the default key.

Returns the key marked as is_default=true, or falls back to the oldest key by creation timestamp if no default is explicitly set.

Returns

The PublicKey of the default key

Errors

Returns an error if no keys exist

pub fn key_display_name(&self, key_id: &PublicKey) -> Option<&str>

Get the display name set for a key.

Display names are caller-supplied human-readable labels passed to add_private_key. They have no cryptographic significance and are not unique across keys. Returns None if the account does not hold a key with this pubkey, or if it was added without a display name.

Arguments

• key_id - Public key of a key held by this account

pub fn find_keys_by_display_name(&self, name: &str) -> Vec<PublicKey>

Find account-held keys whose display name matches name.

Display names are not unique, so this returns every key whose display_name exactly matches the provided string. Keys without a display name are never returned. Returns an empty Vec when there are no matches.

Arguments

• name - Exact display name to match

pub fn get_signing_key(&self, key_id: &PublicKey) -> Result<PrivateKey>

Get a signing key by its ID.

Hands out key material from this session’s unlocked key manager. Callers that sign on the account’s behalf need it — signing a sync request as the key whose access they are claiming, for example.

Arguments

• key_id - The public key identifier

Returns

The PrivateKey if found

pub async fn pending_bootstrap_requests( &self, sync: &Sync, ) -> Result<Vec<(String, BootstrapRequest)>>

Get all pending bootstrap requests from the sync system.

This is a convenience method that requires the Instance’s Sync to be initialized.

Arguments

• sync - Reference to the Instance’s Sync object

Returns

A vector of (request_id, bootstrap_request) pairs for pending requests

pub async fn approve_bootstrap_request( &self, sync: &Sync, request_id: &str, approving_key_id: &PublicKey, ) -> Result<()>

Approve a bootstrap request and add the requesting key to the target database.

The approving key must have current Admin permission on the target database. Creating a grant also requires authority at least as high as the requested permission and priority; lower priority numbers have higher authority.

Arguments

• sync - Mutable reference to the Instance’s Sync object
• request_id - The unique identifier of the request to approve
• approving_key_id - The ID of this account’s key to use for approval (must have Admin permission)

Returns

Result indicating success or failure of the approval operation

Errors

• Returns an error if the account doesn’t own the specified approving key
• Returns an error if the approving key doesn’t have Admin permission on the target database
• Returns an error if the request doesn’t exist or was rejected
• Reduced, removed or uncertain authority needs a fresh explicit grant
• Returns an error if the key addition to the database fails

pub async fn reject_bootstrap_request( &self, sync: &Sync, request_id: &str, rejecting_key_id: &PublicKey, ) -> Result<()>

Reject a bootstrap request.

This method marks the request as rejected. The requesting device will not be granted access to the target database. Requires Admin permission on the target database to prevent unauthorized accounts from disrupting the bootstrap protocol.

Arguments

• sync - Mutable reference to the Instance’s Sync object
• request_id - The unique identifier of the request to reject
• rejecting_key_id - The ID of this account’s key (for permission validation and audit trail)

Returns

Result indicating success or failure of the rejection operation

Errors

• Returns an error if the account doesn’t own the specified rejecting key
• Returns an error if the request doesn’t exist or was approved
• Returns an error if the rejecting key lacks Admin permission on the target database

pub async fn request_database_access( &mut self, sync: &Sync, ticket: &DatabaseTicket, key_id: &PublicKey, requested_permission: Permission, sync_settings: SyncSettings, metadata: Option<Doc>, ) -> Result<()>

Request access to a database from a peer (bootstrap sync).

This convenience method initiates a bootstrap sync request to access a database that this account doesn’t have locally yet. The account’s key will be sent to the peer to request the specified permission level.

This is useful for multi-device scenarios where an account wants to access their existing database from a new device, or when requesting access to a database shared by another account.

On a successful (already-authorized) request the database is synced and its SigKey mapping is recorded, so open_database works immediately — no separate track_database call is needed just to open it. The supplied sync_settings are recorded with the database, including when a pending request is retried after approval.

When approval is still pending the request returns SyncError::BootstrapPending without changing Account mappings or preferences. Supply the arguments again when retrying after approval. Existing legacy mappings are preserved rather than deleted.

Arguments

• sync - Reference to the Instance’s Sync object
• ticket - A ticket containing the database ID and address hints
• key_id - The ID of this account’s key to use for the request
• requested_permission - The permission level being requested
• sync_settings - This account’s durable synchronization preferences for the database once its access mapping is recorded
• metadata - Optional free-form context for the approver to inspect on the stored bootstrap request when deciding whether to grant access

Returns

Result indicating success or failure of the bootstrap request

Errors

• Returns an error if the account doesn’t own the specified key
• Returns an error if all addresses in the ticket fail
• Returns an error if the bootstrap sync fails

Example

// Request write access to a shared database
let user_key_id = account.get_default_key()?;
let ticket: DatabaseTicket = "eidetica:?db=sha256:abc...&pr=http:192.168.1.1:8080".parse()?;
account.request_database_access(
    &sync,
    &ticket,
    &user_key_id,
    Permission::Write(5),
    SyncSettings::on_commit(),
    None,
).await?;

// After approval, the database can be opened
let database = account.open_database(ticket.database_id())?;

pub async fn join( &mut self, ticket: &DatabaseTicket, key_id: &PublicKey, requested_permission: Permission, sync_settings: SyncSettings, metadata: Option<Doc>, ) -> Result<Database>

Join a database from a ticket and open it.

Works the same on an embedded and a connected instance. An embedded instance bootstraps through its own Sync, which must be enabled. A connected instance asks the daemon to do it: the daemon chooses the route and owns the network exchange, while key_id’s private key stays in this process and signs only the peer-bound request proof. The call waits until the peer answers.

A ticket locates a database; it does not grant access. The peer decides whether key_id may have requested_permission, exactly as for request_database_access, whose mapping and preference semantics this shares:

• When access is granted, the database is synced, key_id’s SigKey mapping and sync_settings are recorded, and the opened database is returned.
• When approval is pending, this returns SyncError::BootstrapPending without changing Account mappings or preferences. Call join again with the same arguments once the request is approved.
• A rejected request returns SyncError::BootstrapRejected and records nothing.

Success is point-in-time usability of the verified supplied closure, not global catch-up. Identical completed settings are not written again; preferences changed during the network wait are preserved. Dropping the future, disconnecting, or an error may leave peer requests, replicated entries, routing or a persisted local account record without its ack. Retry explicitly; nothing automatically resumes a join after restart. Held/unreadable acquisition remains refused. Missing delegated history stays Unverified until supplied and verified separately; this call does not acquire it automatically. Native conflicting authority is unchanged, so recovery from every interrupted transfer is not guaranteed. Joining grants user-key access, not device enrollment. Later daemon replication uses its device key and needs separate authorization (or a global grant); this call does not promise ongoing private replication.

Arguments

• ticket - Database ID and address hints
• key_id - This user’s key to request access for
• requested_permission - The permission level being requested
• sync_settings - This user’s replication preference for the database
• metadata - Optional context for the approver

Errors

• AccountError::KeyNotFound if this user does not hold key_id
• SyncError::SyncNotEnabled on an embedded instance without sync
• SyncError::BootstrapPending or SyncError::BootstrapRejected as described above
• Any network or sync error if no ticket address answered

Example

let key_id = user.get_default_key()?;
let database = user
    .join(&ticket, &key_id, Permission::Write(10), SyncSettings::on_commit(), None)
    .await?;

pub async fn record_database_access( &mut self, database_id: &ID, key_id: &PublicKey, sync_settings: SyncSettings, bootstrap_result: Result<()>, ) -> Result<()>

Record the Account-layer SigKey mapping for a bootstrap whose network phase has already completed, given the Result returned by Sync::bootstrap_with_ticket.

request_database_access is the usual entry point and performs the network bootstrap for you. This split-out method exists for callers that hold a coarse lock around the AccountSession (e.g. a daemon’s per-session lock): they can run the network round-trip without the lock held and re-acquire it only for this cheap, local mapping write, so a slow or hung peer never blocks the rest of the session. The mapping semantics are identical to request_database_access. The split form treats supplied preferences as current explicit intent; use record_database_access_if_unchanged to preserve a tracked row changed during the network wait.

The bootstrap_result is consumed and its outcome re-raised unchanged so callers can react to SyncError::BootstrapPending et al.

pub async fn record_database_access_if_unchanged( &mut self, database_id: &ID, key_id: &PublicKey, sync_settings: SyncSettings, bootstrap_result: Result<()>, original: Option<TrackedDatabase>, ) -> Result<()>

Record a completed bootstrap without replacing tracked preferences changed since the caller observed original before its network wait.

Like record_database_access, this reports Pending, Rejected and network errors without writing Account metadata. After successful access, SigKey mapping repair still proceeds; the tracked row is only updated if it still equals original. This is an observed-state check, not distributed compare-and-set. Local persistence errors remain errors even when the network grant or local record replacement already succeeded.

pub async fn tracked_database( &self, database_id: &ID, ) -> Result<Option<TrackedDatabase>>

Read this account’s local tracked state for one database.

Returns Ok(None) only when the tracking row is absent. Authorization, storage read and decoding failures are returned unchanged, not treated as an untracked database or a disabled sync preference.

Reads the native login record (or caller-held session state), never a replicated Table. Does not open the target database, track/join it, or change keys or sync settings. The returned settings are this account’s local preference, not combined sync state or proof of target access.

pub async fn track_database( &mut self, database_id: impl Into<ID>, key_id: &PublicKey, sync_settings: SyncSettings, ) -> Result<()>

Track a database, adding it to this account’s list with auto-discovery of SigKeys.

This method adds an existing database to your tracked list, or updates it if already tracked (upsert behavior).

When tracking:

1. Uses Database::find_sigkeys() to discover which SigKey the account can use
2. Automatically selects the SigKey with highest permission
3. Stores the key mapping and sync settings

The sync_settings indicate your sync preferences, but do not automatically configure sync. Use the Sync module’s peer and tree methods to set up actual sync relationships.

Arguments

• database_id - ID of the database to track
• key_id - Which account key to use for this database
• sync_settings - Sync preferences for this database

Returns

Result indicating success or failure

Errors

• Returns NoSigKeyFound if no SigKey can be found for the specified key
• Returns KeyNotFound if the specified key_id doesn’t exist

pub async fn databases(&self) -> Result<Vec<TrackedDatabase>>

List all tracked databases.

Returns all databases this account has added to their tracked list.

Returns

Vector of TrackedDatabase entries

pub async fn database(&self, database_id: &ID) -> Result<TrackedDatabase>

Get a specific tracked database by ID.

Arguments

• database_id - The ID of the database

Returns

The TrackedDatabase if it’s in the account’s tracked list

Errors

Returns DatabaseNotTracked if the database is not in the account’s list

pub async fn is_sync_enabled(&self, database_id: &ID) -> Result<bool>

Check whether this account has sync enabled for a tracked database.

Returns this account’s own preference, not the host’s combined state. A false result means this account is not personally sharing the database; another account on the same instance may still have sync enabled for it.

Returns Ok(false) for databases not tracked by this account.

pub async fn set_sync_preferences( &mut self, database_id: &ID, enabled: bool, on_commit: bool, interval_seconds: Option<u64>, ) -> Result<()>

Update this account’s sync preferences for an already tracked database.

Requires the recorded key/mapping to still authorize reading the database. Does not discover or repair mappings, track a new database, or change additional sync properties. Native local compare/exchange preserves other sessions’ edits and triggers ordinary sync reconciliation; this is not global runtime control or distributed CAS. Caller-held sessions only update their session-local state, without enabling background sync. A failed acknowledgement is not proof of rollback; reload before retrying.

pub async fn untrack_database(&mut self, database_id: &ID) -> Result<()>

Stop tracking a database.

This removes the database from the account’s tracked list. It does not delete the database itself, remove key mappings, or delete any data.

Arguments

• database_id - The ID of the database to stop tracking

Errors

Returns DatabaseNotTracked if the database is not in the account’s list

Trait Implementations

impl Debug for AccountSession

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

Formats the value using the given formatter.