Module users 

User management, token management, and RBAC for UnENVerse.

Users are stored in the SQLCipher-encrypted vault database — they can only be read or created when the owner has unlocked the vault (i.e. the vault key is in memory). The owner is the only party who can manage users.

Auth modes

• Username + password: stored as SHA-256(salt || password) with a 16-byte random salt.
• Token: 32 random bytes returned as a 64-char hex string once; stored as SHA-256(token).

Permission model

Each permission has:

• scope_type: "vault" | "project" | "category"
• scope_value: "*", or a glob like "wg0-*" / "Cloud/AWS"
• permission: "read" | "write" (write implies read)

Glob rules: * matches any sequence of characters (including empty); ? matches one char.

Structs

ClassPermission

A single permission row scoped to a user class (no user_id — applies to all class members).

PermissionRecord

A single RBAC permission row.

TokenRecord

A stored API token descriptor. The actual token is returned only on creation.

TotpStatus

What the UI and CLI need to draw a user’s second-factor state.

UserClass

A named user class (role template) with capabilities and permissions.

UserRecord

A vault user (password hash is never exposed via this struct).

Enums

AdminSeed

Outcome of seed_default_admin.

Functions

assign_user_class

authority_tier

Derives an authority tier from capability flags. Higher acts on strictly lower.

class_authority_tier

Authority tier implied by a class’s stored capabilities. Returns 0 if unknown.

create_user

Creates a new user. Pass password = None for token-only auth.

create_user_class

create_user_token

Creates a token for user_id. Returns (token_id, plaintext_token) — the plaintext is shown once.

delete_user

Deletes a user plus all their tokens and permissions. Returns Err if user_id belongs to the owner account.

delete_user_class

effective_permission_expr

Resolves what a user may actually do, combining their class and individual rules.

ensure_owner_user

Ensures the vault has exactly one owner row and returns its id.

filter_vault_for_user

Returns a filtered copy of vault containing only entries readable under read. Also trims the projects and user_categories lists to what the visible entries actually reference, so the taxonomy itself does not leak.

get_class_permissions

get_permission_expr

Reads a stored expression for a subject, if any.

get_user_capabilities

Returns the capabilities of the user’s class (None values mean no class = no extra capabilities).

get_user_permissions

Returns all permissions for a user.

glob_matches

Standard wildcard matching: * = any sequence, ? = one char.

init_users_schema

Creates all user-related tables (idempotent) and seeds default classes.

list_user_classes

list_user_tokens

Lists all tokens for a user (no hashes).

list_users

Lists all users, owners first, then by creation date.

merge_user_vault_write

Merges a user’s submitted vault data into the full vault, respecting write permissions.

rename_user

Renames a user (owner or non-owner). Fails if new_username is already taken.

revoke_user_token

Revokes a token by its UUID.

seed_default_admin

Idempotently seeds a default admin user assigned to the built-in cls-admin class. Never hardcodes a credential: uses env_password when present, otherwise generates a 128-bit random password the caller is responsible for displaying once.

set_class_permissions

set_permission_expr

Stores an expression, or clears it when expression is empty/blank.

set_strict_write

Turn strict write scoping on or off for a user or a class.

set_user_password

Updates (or clears) a user’s password.

set_user_permissions

Atomically replaces all permissions for a user.

strict_write_for

Whether writes for this user must satisfy every scope rather than any.

token_user_id

Returns the owning user id of a token, or None if the token id is unknown.

totp_confirm

Phase two: enables the factor once the user proves their authenticator works.

totp_disable

Removes the factor entirely, secret included.

totp_enroll

Phase one of enrollment: mints a secret and returns it with its URI.

totp_required

Whether login for this user must present a code.

totp_status

Reports enrollment and enabled state. Never returns the secret — see TotpStatus::secret.

update_user_class

user_authority_tier

Authority tier of a stored user (by their class capabilities, or the is_owner flag). Returns 0 for an unknown user id.

verify_user_password

Verifies username + password. Returns None on invalid credentials.

verify_user_token

Verifies a raw 64-char hex token. Returns None if invalid or expired.

verify_user_totp

Verifies a login code and advances the anti-replay high-water mark.