Spaces:
Running
Running
| # PyFundaments – Function Overview | |
| ## `main.py` | |
| | Function | Description | | |
| | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | `initialize_fundaments()` | Asynchronously initializes services based on available environment variables. Returns a dictionary of services (`None` if not initialized). | | |
| | `main()` | Application entry point. Calls `initialize_fundaments()`, loads `app/app.py`, closes DB pool on shutdown. | | |
| --- | |
| ## `fundaments/config_handler.py` – `ConfigHandler` | |
| | Function | Description | | |
| | ------------------------ | ------------------------------------------------------------------ | | |
| | `__init__()` | Loads `.env` via `python-dotenv` and system environment variables. | | |
| | `load_all_config()` | Stores all non-empty environment variables in `self.config`. | | |
| | `get(key)` | Returns value as string or `None`. | | |
| | `get_bool(key, default)` | Parses boolean values (`true/1/yes/on`). | | |
| | `get_int(key, default)` | Returns integer value or `default` on failure. | | |
| | `has(key)` | Returns `True` if key exists and is not empty. | | |
| | `get_all()` | Returns copy of full configuration dictionary. | | |
| | `config_service` | Global singleton instance. | | |
| --- | |
| ## `fundaments/postgresql.py` | |
| | Function | Description | | |
| | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | | |
| | `enforce_cloud_security(dsn_url)` | Enforces `sslmode=require`, applies timeouts, removes incompatible DSN options. | | |
| | `mask_dsn(dsn_url)` | Removes credentials from DSN for logging. | | |
| | `ssl_runtime_check(conn)` | Verifies active SSL connection. | | |
| | `init_db_pool(dsn_url)` | Creates asyncpg pool (min=1, max=10) and runs SSL check. | | |
| | `close_db_pool()` | Gracefully closes connection pool. | | |
| | `execute_secured_query(query, *params, fetch_method)` | Executes parameterized query (`fetch`, `fetchrow`, `execute`) with reconnect logic. | | |
| --- | |
| ## `fundaments/encryption.py` – `Encryption` | |
| | Function | Description | | |
| | -------------------------------------- | ---------------------------------------------------------------- | | |
| | `generate_salt()` | Generates secure 16-byte hex salt. | | |
| | `__init__(master_key, salt)` | Derives AES-256 key via PBKDF2-SHA256 (480k iterations). | | |
| | `encrypt(data)` | Encrypts string using AES-256-GCM. Returns `{data, nonce, tag}`. | | |
| | `decrypt(encrypted_data, nonce, tag)` | Decrypts data. Raises `InvalidTag` if tampered. | | |
| | `encrypt_file(source_path, dest_path)` | Encrypts file in 8192-byte chunks. | | |
| | `decrypt_file(source_path, dest_path)` | Decrypts file using stored nonce and tag. | | |
| --- | |
| ## `fundaments/access_control.py` – `AccessControl` | |
| | Function | Description | | |
| | -------------------------------------------------- | ------------------------------------ | | |
| | `__init__(user_id)` | Initializes with optional user ID. | | |
| | `has_permission(permission_name)` | Checks if user has permission. | | |
| | `get_user_permissions()` | Returns all user permissions. | | |
| | `get_user_roles()` | Returns assigned roles. | | |
| | `assign_role(role_id)` | Assigns role to user. | | |
| | `remove_role(role_id)` | Removes role from user. | | |
| | `get_all_roles()` | Returns all roles. | | |
| | `get_all_permissions()` | Returns all permissions. | | |
| | `create_role(name, description)` | Creates new role and returns ID. | | |
| | `update_role_permissions(role_id, permission_ids)` | Replaces all permissions for a role. | | |
| | `get_role_permissions(role_id)` | Returns role permissions. | | |
| --- | |
| ## `fundaments/user_handler.py` | |
| ### `Database` (SQLite Wrapper) | |
| | Function | Description | | |
| | ------------------------- | ------------------------------------------------- | | |
| | `execute(query, params)` | Executes query and commits. | | |
| | `fetchone(query, params)` | Returns single row. | | |
| | `fetchall(query, params)` | Returns all rows. | | |
| | `close()` | Closes connection. | | |
| | `setup_tables()` | Creates `users` and `sessions` tables if missing. | | |
| --- | |
| ### `Security` (Password Utilities) | |
| | Function | Description | | |
| | ----------------------------------- | -------------------------------------------- | | |
| | `hash_password(password)` | Hashes password (PBKDF2-SHA256 via passlib). | | |
| | `verify_password(password, hashed)` | Verifies password against hash. | | |
| | `regenerate_session(session_id)` | Generates new UUID session ID. | | |
| --- | |
| ### `UserHandler` | |
| | Function | Description | | |
| | ----------------------------------------- | ------------------------------------------------------ | | |
| | `login(username, password, request_data)` | Authenticates user, validates state, creates session. | | |
| | `logout()` | Removes session from DB and memory. | | |
| | `is_logged_in()` | Checks if active session exists. | | |
| | `is_admin()` | Checks session `is_admin` flag. | | |
| | `validate_session(request_data)` | Validates session against IP and User-Agent. | | |
| | `lock_account(username)` | Locks user account. | | |
| | `reset_failed_attempts(username)` | Resets failed login counter. | | |
| | `increment_failed_attempts(username)` | Increments failed attempts and locks after 5 failures. | | |
| --- | |
| ## `fundaments/security.py` – `Security` (Orchestrator) | |
| | Function | Description | | |
| | ---------------------------------------------- | --------------------------------------------------------------------- | | |
| | `__init__(services)` | Initializes with required services. Raises `RuntimeError` if missing. | | |
| | `user_login(username, password, request_data)` | Performs login and session validation. | | |
| | `check_permission(user_id, permission_name)` | Delegates permission check. | | |
| | `encrypt_data(data)` | Encrypts data if encryption service is available. | | |
| | `decrypt_data(encrypted_data, nonce, tag)` | Decrypts data or returns `None` on failure. | | |
| --- | |
| ## `fundaments/debug.py` – `PyFundamentsDebug` | |
| | Function | Description | | |
| | ----------------- | ------------------------------------------------------- | | |
| | `__init__()` | Reads debug-related environment variables. | | |
| | `_setup_logger()` | Configures logging handlers. | | |
| | `run()` | Outputs runtime diagnostics when debug mode is enabled. | | |
| --- | |
| ## `app/app.py` | |
| | Function | Description | | |
| | ------------------------------- | --------------------------------------------------------------------- | | |
| | `start_application(fundaments)` | Receives initialized service dictionary and starts application logic. | | |
| --- | |
| ## Architecture Notes | |
| * `UserHandler` uses internal SQLite. | |
| * `AccessControl` uses PostgreSQL via `execute_secured_query`. | |
| * `security.py` `Security` is the orchestrator layer. | |
| * All services are optional. | |