Upload 36 files

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,63 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+---
+name: Bug Report
+about: Report a bug to help us improve PyFundaments.
+title: "[BUG] "
+labels: 'bug'
+---
+
+###  Description of the bug
+
+A clear and concise description of what the bug is.
+- Which specific module in `fundaments/` is affected? (e.g., `postgresql.py`, `security.py`, `encryption.py`)
+- What is the unexpected behavior?
+
+***
+
+###  (Steps to Reproduce)
+
+1. **Environment Setup:** Describe how your environment is set up.
+   - Are you running it locally or in a Docker container?
+   - What values are in your `.env` file? (Please only share non-sensitive values or use placeholders like `DATABASE_URL="..."`)
+   - What version of Python are you using?
+
+2. **Code Snippet:** Provide a minimal, reproducible code snippet that demonstrates the bug. This should ideally be a small `app.py` or a test file that triggers the issue.
+
+3. **Execution:** Describe the exact command you ran to start the application (e.g., `python main.py` or a Docker command).
+
+4. **Result:** What was the output? Include the full error traceback if one was generated.
+
+***
+
+###  Expected behavior
+
+A clear and concise description of what you expected to happen. How should the module behave correctly?
+
+***
+
+###  Desktop &  Mobile Information
+
+This section is for web-facing applications. If your bug is related to a specific client, please provide details.
+
+- **OS:** [e.g. Ubuntu 22.04, macOS 14]
+- **Docker Image (if applicable):** [e.g. python:3.10-slim]
+- **Browser (if applicable):** [e.g. Chrome, Firefox]
+- **Device (if applicable):** [e.g. iPhone 15 Pro]
+
+***
+
+###  Additional context
+
+Add any other context about the problem here, such as:
+- Did the issue appear after a specific change in the code?
+- Any other services or dependencies that might be relevant?
+
+Thank you for helping to improve PyFundaments!

.github/workflows/generate_structure.yml

@@ -0,0 +1,56 @@
+# =============================================================================
+# WORKFLOW: Generate Repo Structure - [Generate Repo Structure]
+# PART OF:  Codey - No Mercy EDITION
+# =============================================================================
+# Role:        Automated Audit & Compliance (ESOL v1.1)
+# Copyright:   (c) 2026 VolkanSah
+# License:     Apache 2.0 + ESOL v1.1 (https://github.com/VolkanSah/ESOL)
+# Enforcement: Jurisdiction Berlin, Germany (StGB & DSGVO)
+# =============================================================================
+
+# Name of the workflow used to visualize the file hierarchy
+name: Generate Repo Structure
+
+# Trigger: Manual execution only (allows the dev to choose when to update the map)
+on:
+  workflow_dispatch:
+
+# Permissions: Granting write access so the bot can save the generated Markdown
+permissions:
+  contents: write
+
+jobs:
+  # Job to analyze and map the directory tree
+  structure:
+    # Running on the latest stable Ubuntu environment
+    runs-on: ubuntu-latest
+    steps:
+      # Step 1: Pull the latest code using a custom token
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GIT_TOKEN }}
+
+      # Step 2: Prepare Python for the generator script
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Step 3: Run the custom logic that scans directories and creates PROJECT_STRUCTURE.md
+      - name: Generate structure
+        run: python .codey/scripts/generate_structure.py
+
+      # Step 4: Finalize by pushing the new "Map" to the repository root
+      - name: Commit structure
+        run: |
+          # Identity setup for the automated commit
+          git config user.name  "Codey Bot"
+          git config user.email "codey@bot"
+          
+          # Stage the specific file generated by the script
+          git add PROJECT_STRUCTURE.md
+          
+          # Check for changes to prevent empty commits; [skip ci] avoids re-triggering workflows
+          git diff --staged --quiet || git commit -m "📁 update project structure [skip ci]"
+          
+          # Push the updated structure map back to the origin
+          git push

.gitignore

@@ -2,9 +2,7 @@
 
 README.MD
 .gitignore
-app/.pyfun
-.github
-
+app/*
 
 
 
@@ -127,8 +125,8 @@ ipython_config.py
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
 #   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
 #   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-pdm.lock
-pdm.toml
+#pdm.lock
+#pdm.toml
 .pdm-python
 .pdm-build/
 
@@ -188,7 +186,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-.idea/
+#.idea/
 
 # Abstra
 # Abstra is an AI-powered process automation framework.
@@ -219,4 +217,4 @@ cython_debug/
 # Marimo
 marimo/_static/
 marimo/_lsp/
-__marimo__/
+__marimo__/

ESOL

@@ -0,0 +1,91 @@
+## Ethical Security Operations License (ESOL v1.1)
+since 2021
+updated on 05.02.2026
+
+### Section 1: Preamble and Scope
+The **Ethical Security Operations License (ESOL v1.1)** is an **additional, non-severable condition** supplementing the **MIT License** under which the covered software (hereinafter "the Work") is distributed.
+
+By downloading, copying, modifying, or executing the Work, the Licensee **irrevocably agrees** to adhere to both the terms of the MIT License and the specific, mandatory ethical constraints defined herein. **Lack of awareness of these terms does not constitute a defense.**
+
+### Section 2: Mandatory Ethical Use and Purpose
+The grant of rights under this License is **expressly and exclusively conditioned** upon the Licensee's continuous adherence to the following use limitations:
+
+1. **Authorized Use Only:** The Work shall be used **exclusively** for:
+   - Defensive security operations (Blue Teaming)
+   - Authorized penetration testing (Red Teaming) with documented consent
+   - Vulnerability research on systems owned or explicitly authorized by the researcher
+   - Security compliance auditing with contractual authorization
+
+2. **Explicit Written Authorization Required:** Any security testing, scanning, exploitation, or enumeration against **any system not wholly owned by the Licensee** requires **explicit, documented, written authorization** from the rightful owner **prior to execution**. Verbal permission, implicit consent, or "bug bounty program existence" does **not** constitute authorization without explicit scope documentation.
+
+3. **Educational Use Constraints:** Educational or research use must:
+   - Occur only in isolated, controlled environments (virtual machines, dedicated test networks)
+   - Not target production systems, public infrastructure, or third-party services
+   - Comply with institutional ethics board requirements where applicable
+
+### Section 3: Prohibited Use (Malicious Activities)
+The Licensee is **strictly and unconditionally prohibited** from using the Work for:
+
+* **Unauthorized Access or Reconnaissance:** Scanning, probing, accessing, or attempting to access any computer system, network, database, or data without **explicit prior written authorization** from the lawful owner.
+
+* **Malicious Code Operations:** Creating, distributing, executing, or facilitating:
+  - Malware, viruses, worms, trojans, ransomware, or rootkits
+  - Cryptominers operating without system owner consent
+  - Phishing infrastructure, scam campaigns, or social engineering attacks
+  - Exploits targeting zero-day vulnerabilities outside authorized disclosure processes
+
+* **Service Disruption:** Denial-of-service (DoS/DDoS) attacks, resource exhaustion, or any unauthorized degradation of system availability or performance.
+
+* **Data Exfiltration or Manipulation:** Unauthorized copying, modification, deletion, or encryption of data not owned by the Licensee.
+
+* **Legal Violations:** Any activity violating the Computer Fraud and Abuse Act (CFAA), GDPR, national cybercrime laws, or international treaties concerning unauthorized computer access.
+
+* **Circumvention of Security Controls:** Bypassing authentication, encryption, access controls, or security monitoring systems without documented authorization.
+
+### Section 4: Compliance Verification and Audit Rights
+The Licensor reserves the right to:
+- Request documentation of authorization for any deployment of the Work
+- Audit compliance upon reasonable notice if misuse is suspected
+- Publicly disclose violations (including Licensee identity) to warn the security community
+
+**Licensees conducting authorized security research are encouraged to maintain contemporaneous records of authorization as evidence of compliance.**
+
+### Section 5: No Warranty Regarding Legal Compliance
+**THE WORK IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE LICENSOR MAKES NO REPRESENTATION THAT USE OF THE WORK, EVEN IN COMPLIANCE WITH THIS LICENSE, WILL BE LEGAL IN ALL JURISDICTIONS. THE LICENSEE BEARS SOLE RESPONSIBILITY FOR ENSURING COMPLIANCE WITH ALL APPLICABLE LAWS.**
+
+### Section 6: Violation and Termination
+Violation of **any** provision of this ESOL v1.1 constitutes a **material breach** resulting in:
+
+1. **Immediate Automatic Termination** of all rights under both the MIT License and this ESOL
+2. **Obligation to Cease Use** and destroy all copies of the Work
+3. **Liability for Damages:** The Licensee shall be liable for all damages, including but not limited to:
+   - Direct and consequential damages to affected third parties
+   - Licensor's legal costs in enforcement actions
+   - Reputational harm to the Licensor or the security research community
+
+4. **Reporting to Authorities:** The Licensor reserves the right to report violations to appropriate law enforcement and cybersecurity authorities.
+
+### Section 7: Severability and Precedence
+If any provision of this License is held unenforceable, the remaining provisions remain in full effect. **In any conflict between the MIT License and ESOL v1.1, the ESOL v1.1 takes precedence regarding ethical use constraints.**
+
+### Section 8: Jurisdiction and Dispute Resolution
+This License shall be governed by the laws of **[Germany(Berlin)]**. Disputes shall be resolved through binding arbitration under **[Arbitration Rules]**, with the prevailing party entitled to attorney's fees.
+
+### Section 9: License Acceptance Evidence
+By downloading this software from any source (GitHub, mirrors, forks), you acknowledge that:
+- This license was prominently displayed in the repository
+- You had reasonable opportunity to review these terms
+- Your use constitutes legally binding acceptance
+---
+
+## Final Licensing Statement
+**This Work is dual-licensed under:**
+1. **The MIT License** (for general software rights)
+2. **The Ethical Security Operations License v1.1 (ESOL v1.1)** (for use constraints)
+
+**The ESOL v1.1 is a mandatory, non-severable condition of use. Acceptance is automatic upon use of the Work.**
+
+**By using this software, you acknowledge that misuse may result in criminal prosecution, civil liability, and permanent termination of license rights.**
+
+> Checked & Updated, on 08.02.2026 @01700MEZ
+## Ethical Security Operations License (ESOL v1.1) since 2021 against fraud and scam

HF_README.md

@@ -0,0 +1,98 @@
+---
+title: Universal MCP Hub
+emoji: 🐢
+colorFrom: red
+colorTo: yellow
+sdk: docker
+pinned: false
+license: apache-2.0
+short_description: Universal MCP Hub (Sandboxed)
+---
+
+# Universal MCP Hub (Sandboxed)
+
+> For advanced use, have a look at [PyFundaments.md](PyFundaments.md) and the `docs/` folder.
+
+Universal MCP Server running in **paranoid mode** — built on [PyFundaments](https://github.com/VolkanSah/PyFundaments) and licensed under ESOL.
+
+The goal was simple: too many MCP servers out there with no sandboxing, hardcoded keys, and zero security thought. This one is different. No key = no tool = no crash. The Guardian (`main.py`) controls everything. `app/mcp.py` gets only what it needs, nothing more.
+
+- MCP_HUB Built with Claude (Anthropic) as a typing tool. Architecture, security decisions
+- Pyfundaments by Volkan Sah read [ESOL](ESOL)
+
+---
+
+## Setup
+
+1. **Fork** this Space.
+2. Enter your API keys as **Space Secrets** (Settings → Variables and secrets).
+3. The Space starts automatically — only tools with valid keys will be registered.
+
+---
+
+## Available Tools (Depending on Configured Keys)
+
+| Secret | Tool | Description |
+| :--- | :--- | :--- |
+| `ANTHROPIC_API_KEY` | `anthropic_complete` | Claude Models |
+| `GEMINI_API_KEY` | `gemini_complete` | Google Gemini Models |
+| `OPENROUTER_API_KEY` | `openrouter_complete` | 100+ Models via OpenRouter |
+| `HF_TOKEN` | `hf_inference` | HuggingFace Inference API |
+| `BRAVE_API_KEY` | `brave_search` | Web Search (independent index) |
+| `TAVILY_API_KEY` | `tavily_search` | AI-optimized Search |
+| *(Always Active)* | `list_active_tools` | Shows all currently active tools |
+| *(Always Active)* | `health_check` | System health check |
+
+---
+
+## MCP Client Configuration (SSE)
+
+To connect Claude Desktop or any MCP client to this hub:
+
+```json
+{
+  "mcpServers": {
+    "pyfundaments-hub": {
+      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/sse"
+    }
+  }
+}
+```
+
+---
+
+## Architecture
+
+```
+main.py  ← Guardian: initializes all services, controls what app/ receives
+  └── app/mcp.py  ← Sandbox: registers only tools with valid keys
+        ├── LLM tools    (Anthropic, Gemini, OpenRouter, HuggingFace)
+        ├── Search tools (Brave, Tavily)
+        ├── DB tools     (only if DATABASE_URL is set)
+        └── System tools (always active)
+```
+
+**The Guardian pattern:** `app/mcp.py` never reads `os.environ` directly.
+It receives a `fundaments` dict from `main.py` — and only what `main.py` decides to give it.
+
+---
+
+## Security Notes
+
+- All API keys loaded via HuggingFace Space Secrets (env vars) — never hardcoded
+- `list_active_tools` returns key **names** only, never values
+- DB tools are read-only by design (`SELECT` only, enforced at application level)
+- Direct execution of `app/mcp.py` is blocked by design
+- Built on PyFundaments — a security-first Python architecture for developers
+
+> PyFundaments is not perfect. But it's more secure than most of what runs in production.
+
+---
+
+## License
+
+Apache License 2.0 + [ESOL 1.1](https://github.com/VolkanSah/ESOL)
+
+---
+
+*"I use AI as a tool, not as a replacement for thinking."* — Volkan Kücükbudak

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

PyFundaments – Function Overview.md

@@ -0,0 +1,145 @@
+# 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.

PyFundaments.md

@@ -0,0 +1,232 @@
+# PyFundaments: A Secure Python Architecture
+##### v. 1.0.1 dev
+
+## Description
+
+This project, named **PyFundaments**, provides a robust and secure Python architecture. Its core mission is not to be a monolithic framework, but to establish a layered, modular foundation—or "fundament"—of essential services. This structure ensures that every application starts on a verified and secure base, with a focus on stability, code clarity, and a security-first mindset from the ground up.
+
+> [!NOTE]  
+> you must create your app/bot in app/* or you get an error! Than uncoment
+> ```
+>from app.app import start_application
+>await start_application(fundaments)
+>```
+> in main.py
+
+
+
+-----
+
+## Table of Contents
+
+  - [Project Structure](#project-structure)
+  - [The Role of `main.py`](#the-role-of-mainpy)
+  - [Configuration (`.env`)](#configuration-env)
+  - [Installation](#installation)
+  - [Getting Started](#getting-started)
+  - [Module Documentation](#module-documentation)
+  - [Notes](#notes)
+
+-----
+
+## Project Structure
+
+```
+
+├── main.py # run main!
+├── README.md
+├── requirements.txt
+├── .gitignore
+├── .env.example
+├── app/
+│   └── ...
+│   └── app.py # sandboxed app run!
+│   └── tools.py
+│   └── provider.py
+│   └── models.py
+│   └── db_sync.py
+
+├── fundaments/ # do not touch! 
+│   ├── access_control.py
+│   ├── config_handler.py
+│   ├── encryption.py
+│   ├── postgresql.py
+│   ├── security.py
+│   └── user_handler.py
+└── docs/
+    ├── access_control.py.md
+    ├── encryption.py.md
+    ├── postgresql.py.md
+    ├── security.py.md
+    └── user_handler.py.md
+
+```
+-----
+
+## The Role of `main.py`
+
+`main.py` is the **only entry point** and acts as the first line of defense for the application.
+
+### Responsibilities
+
+  - [x] **Validate Dependencies**: It checks for all necessary core modules in `fundaments/` and exits immediately if any are missing.
+  - [x] **Conditional Environment Loading**: It uses the `config_handler` to load available configuration variables and initializes only the services for which configuration is present.
+  - [x] **Initialize Services**: It creates instances of available services (PostgreSQL, encryption, access control, user handling) based on environment configuration, collecting them into a single service dictionary.
+  - [x] **Graceful Degradation**: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality.
+  - [x] **Decouple App Logic**: It hands off the prepared and verified services to `app/app.py`, allowing the main application to focus purely on its business logic without worrying about low-level setup.
+
+-----
+
+## Configuration (`.env`)
+
+Application settings are managed using a `.env` file. **Never commit this file to version control.**
+
+The framework uses **conditional loading** - only services with available configuration are initialized. This allows different application types to use only what they need.
+
+A `.env.example` file is provided to show available variables. Create a copy named `.env` and configure only what your application requires.
+
+### Core Configuration (Optional based on app type)
+
+```text
+# Database connection (required only for database-using apps)
+DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"
+
+# Encryption keys (required only for apps using encryption)
+MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
+PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
+
+# Logging configuration (optional)
+LOG_LEVEL="INFO"
+LOG_TO_TMP="false"
+ENABLE_PUBLIC_LOGS="true"
+```
+
+### Application Examples
+
+**Discord Bot:** Only needs `BOT_TOKEN`, no database or encryption required.
+**ML Pipeline:** Only needs `DATABASE_URL` for data access.
+**Web Application:** May need all services for full functionality.
+
+-----
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+-----
+
+## Getting Started
+
+1.  **Configure**: Create your `.env` file from the `.env.example` and set only the variables your application type requires.
+2.  **Run**: Execute the `main.py` script to start the application.
+
+```bash
+python main.py
+```
+
+The framework will automatically detect available configuration and load only the necessary services.
+
+-----
+
+## Module Documentation
+
+Each security-relevant core module is documented in the `docs/` directory:
+
+| Module              | Description                              | Documentation                                     |
+| ------------------- | ---------------------------------------- | -------------------------------------------------|
+| `access_control.py` | Role-based access management             | [access\_control.py.md](docs/access_control.py.md)|
+| `config_handler.py` | Universal configuration loader           | [config\_handler.py.md](docs/config_handler.py.md)|
+| `encryption.py`     | Cryptographic routines                   | [encryption.py.md](docs/encryption.py.md)         |
+| `postgresql.py`     | Secure, asynchronous database access     | [postgresql.py.md](docs/postgresql.py.md)         |
+| `user_handler.py`   | Authentication and identity management   | [user\_handler.py.md](docs/user_handler.py.md)     |
+| `security.py`       | Central security orchestration layer     | [security.py.md](docs/security.py.md)             |
+
+-----
+
+## License
+
+This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+### Section 4: Additional Restrictions and Ethical Use Policy
+
+This project is released under the permissive Apache 2.0 License, which is intended to provide broad freedom for use and modification.  
+However, in the interest of fostering a safe and responsible community, we include the following **mandatory ethical use restrictions**:
+
+Use of this project (or derivatives) is **strictly prohibited** for purposes that:
+
+  - **Promote Hatred or Discrimination**  
+      Includes hate speech, incitement to violence, or discrimination based on race, religion, gender, orientation, etc.
+
+  - **Facilitate Illegal Activities**  
+      Use to conduct or support criminal activity is forbidden.
+
+  - **Spread Malicious Content**  
+      This includes pornography, malware, spyware, or other harmful payloads.
+
+We believe that freedom in development must be coupled with responsibility.  
+**Violation of these terms constitutes a breach of license and will trigger takedown actions** including legal and technical responses.
+
+*Volkan Kücükbudak*
+
+-----
+
+## Credits
+
+- Developed and maintained by the PyFundaments project.  
+-  Core components inspired by best practices in modular app architecture and OWASP security principles.
+- Third-party libraries are credited in their respective module docs and comply with open-source terms.
+
+-----
+
+## Notes
+
+    Security-first by design.  
+    If one piece is missing or unsafe — the app does not run.  
+    Zero tolerance for guesswork.
+
+> Give a ⭐ if you find the structure helpful.
+
+
+## Changelog 
+###### Version 1.0.0 -> 1.0.1
+### PyFundaments Refactoring
+
+#### Modified Files
+
+**1. main.py - Conditional Service Loading**
+- **Added:** Environment-based conditional service initialization
+- **Added:** Graceful fallback when services can't be initialized (warning instead of crash)
+- **Added:** Conditional logging configuration (LOG_LEVEL, LOG_TO_TMP, ENABLE_PUBLIC_LOGS)
+- **Added:** Smart dependency management (access_control & user_handler only load if database available)
+- **Added:** Safe shutdown (only close DB pool if it was initialized)
+- **Result:** Framework now supports partial service loading for different app types
+
+**2. app/app.py - Proper Service Injection**
+- **Removed:** Direct service imports and instantiation
+- **Added:** Services received as parameter from main.py
+- **Modified:** start_application() now takes fundaments dictionary as parameter
+- **Added:** Conditional service usage based on what main.py provides
+- **Added:** Examples for different app types (database-only, database-free modes)
+- **Result:** Clean separation - main.py handles initialization, app.py uses services
+
+**3. fundaments/config_handler.py - Universal Configuration Loader**
+- **Removed:** REQUIRED_KEYS validation (moved to main.py)
+- **Modified:** Now loads ALL environment variables without validation
+- **Added:** Helper methods: get_bool(), get_int(), has(), get_all()
+- **Added:** Safe defaults and type conversion
+- **Result:** Config handler never needs updates, works with any ENV variables
+
+**4. .env.example - Conditional Configuration Template**
+- **Added:** Clear separation between core and optional dependencies
+- **Added:** Logging configuration options
+- **Added:** App-specific configuration examples (Discord, ML, Web)
+- **Added:** Comments explaining when to use each option
+- **Result:** Users only configure what they need, no unused variables
+
+#### Architecture Improvements
+- **Conditional Loading:** Framework only loads needed services based on available ENV vars
+- **Merge-Safe Structure:** User code (app/, config_handler.py) protected from framework updates
+- **Zero Breaking Changes:** Updates only affect fundaments/ directory
+- **Enterprise-Level Merging:** Community can safely pull framework updates</document_content></document>

README_MCP_HUB.md

@@ -0,0 +1,63 @@
+# Universal MCP Hub (Sandboxed)
+#### Universal MCP Server running in **paranoid mode** — built on [PyFundaments](PyFundaments.md) and licensed under ESOL.
+
+
+
+The goal was simple: too many MCP servers out there with no sandboxing, hardcoded keys, and zero security thought. This one is different. No key = no tool = no crash. The Guardian (`main.py`) controls everything. `app/mcp.py` gets only what it needs, nothing more.
+
+- MCP_HUB Built with Claude (Anthropic) as a typing tool. Architecture, security decisions
+- Pyfundaments by Volkan Sah read [ESOL](ESOL)
+
+---
+
+## MCP Client Configuration (SSE)
+
+To connect Claude Desktop or any MCP client to this hub:
+
+```json
+{
+  "mcpServers": {
+    "pyfundaments-hub": {
+      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/sse"
+    }
+  }
+}
+```
+
+---
+
+## Architecture
+
+```
+main.py  ← Guardian: initializes all services, controls what app/ receives
+  └── app/mcp.py  ← Sandbox: registers only tools with valid keys
+        ├── LLM tools    (Anthropic, Gemini, OpenRouter, HuggingFace)
+        ├── Search tools (Brave, Tavily)
+        ├── DB tools     (only if DATABASE_URL is set)
+        └── System tools (always active)
+```
+
+**The Guardian pattern:** `app/mcp.py` never reads `os.environ` directly.
+It receives a `fundaments` dict from `main.py` — and only what `main.py` decides to give it.
+
+---
+
+## Security Notes
+
+- All API keys loaded via Secrets (env vars) — never hardcoded
+- `list_active_tools` returns key **names** only, never values
+- DB tools are read-only by design (`SELECT` only, enforced at application level)
+- Direct execution of `app/mcp.py` is blocked by design
+- Built on PyFundaments — a security-first Python architecture for developers
+
+> PyFundaments is not perfect. But it's more secure than most of what runs in production.
+
+---
+
+## License
+
+Apache License 2.0 + [ESOL 1.1](https://github.com/VolkanSah/ESOL)
+
+---
+
+*"I use AI as a tool, not as a replacement for thinking."* — Volkan Kücükbudak

app/.pyfun

@@ -0,0 +1,313 @@
+# =============================================================================
+# .pyfun — PyFundaments App Configuration
+# Single source of truth for app/* modules (provider, models, tools, hub)
+# Part of: Universal MCP Hub on PyFundaments
+# =============================================================================
+# RULES:
+#   - All values in double quotes "value"
+#   - NO secrets here! Keys stay in .env → only ENV-VAR NAMES referenced here
+#   - Comment-out unused sections with #  → keep structure, parsers need it!
+#   - DO NOT DELETE headers or [X_END]   → parsers rely on these markers
+#   - Empty/unused values: ""            → never leave bare =
+# =============================================================================
+# TIERS:
+#   LAZY:       fill [HUB] + one [LLM_PROVIDER.*] only        → works
+#   NORMAL:     + [SEARCH_PROVIDER.*] + [MODELS.*]             → works better
+#   PRODUCTIVE: + [TOOLS] + [FALLBACK] + [HUB_LIMITS]          → full power
+# =============================================================================
+# DO NOT DELETE — file identifier used by all parsers
+[PYFUN_FILE = .pyfun]
+
+# =============================================================================
+# HUB — Core identity & transport config
+# =============================================================================
+[HUB]
+HUB_NAME            = "Universal MCP Hub"
+HUB_VERSION         = "1.0.0"
+HUB_DESCRIPTION     = "Universal MCP Hub built on PyFundaments"
+
+# Transport: stdio (local/Claude Desktop) | sse (HuggingFace/Remote)
+# Override via ENV: MCP_TRANSPORT
+HUB_TRANSPORT       = "stdio"
+HUB_HOST            = "0.0.0.0"
+HUB_PORT            = "7860"
+
+# App mode: mcp | app
+# Override via ENV: APP_MODE
+HUB_MODE            = "mcp"
+
+# HuggingFace Space URL (used as HTTP-Referer for some APIs)
+HUB_SPACE_URL       = ""
+[HUB_END]
+
+# =============================================================================
+# HUB_LIMITS — Request & retry behavior
+# =============================================================================
+[HUB_LIMITS]
+MAX_PARALLEL_REQUESTS   = "5"
+RETRY_COUNT             = "3"
+RETRY_DELAY_SEC         = "2"
+REQUEST_TIMEOUT_SEC     = "60"
+SEARCH_TIMEOUT_SEC      = "30"
+[HUB_LIMITS_END]
+
+# =============================================================================
+# PROVIDERS — All external API providers
+# Secrets stay in .env! Only ENV-VAR NAMES are referenced here.
+# =============================================================================
+[PROVIDERS]
+
+# ── LLM Providers ─────────────────────────────────────────────────────────────
+[LLM_PROVIDERS]
+
+  [LLM_PROVIDER.anthropic]
+  active              = "true"
+  base_url            = "https://api.anthropic.com/v1"
+  env_key             = "ANTHROPIC_API_KEY"       # → .env: ANTHROPIC_API_KEY=sk-ant-...
+  api_version_header  = "2023-06-01"              # anthropic-version header
+  default_model       = "claude-haiku-4-5-20251001"
+  models              = "claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001"
+  fallback_to         = "openrouter"              # if this provider fails → try next
+  [LLM_PROVIDER.anthropic_END]
+
+  [LLM_PROVIDER.gemini]
+  active              = "true"
+  base_url            = "https://generativelanguage.googleapis.com/v1beta"
+  env_key             = "GEMINI_API_KEY"          # → .env: GEMINI_API_KEY=...
+  default_model       = "gemini-2.0-flash"
+  models              = "gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash"
+  fallback_to         = "openrouter"
+  [LLM_PROVIDER.gemini_END]
+
+  [LLM_PROVIDER.openrouter]
+  active              = "true"
+  base_url            = "https://openrouter.ai/api/v1"
+  env_key             = "OPENROUTER_API_KEY"      # → .env: OPENROUTER_API_KEY=sk-or-...
+  default_model       = "mistralai/mistral-7b-instruct"
+  models              = "openai/gpt-4o, meta-llama/llama-3-8b-instruct, mistralai/mistral-7b-instruct"
+  fallback_to         = ""                        # last in chain, no further fallback
+  [LLM_PROVIDER.openrouter_END]
+
+  [LLM_PROVIDER.huggingface]
+  active              = "true"
+  base_url            = "https://api-inference.huggingface.co/models"
+  env_key             = "HF_TOKEN"                # → .env: HF_TOKEN=hf_...
+  default_model       = "mistralai/Mistral-7B-Instruct-v0.3"
+  models              = "mistralai/Mistral-7B-Instruct-v0.3, meta-llama/Llama-3.3-70B-Instruct"
+  fallback_to         = ""
+  [LLM_PROVIDER.huggingface_END]
+
+  # ── Add more LLM providers below ──────────────────────────────────────────
+  # [LLM_PROVIDER.mistral]
+  # active            = "false"
+  # base_url          = "https://api.mistral.ai/v1"
+  # env_key           = "MISTRAL_API_KEY"
+  # default_model     = "mistral-large-latest"
+  # models            = "mistral-large-latest, mistral-small-latest"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.mistral_END]
+
+  # [LLM_PROVIDER.openai]
+  # active            = "false"
+  # base_url          = "https://api.openai.com/v1"
+  # env_key           = "OPENAI_API_KEY"
+  # default_model     = "gpt-4o"
+  # models            = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.openai_END]
+
+[LLM_PROVIDERS_END]
+
+# ── Search Providers ───────────────────────────────────────────────────────────
+[SEARCH_PROVIDERS]
+
+  [SEARCH_PROVIDER.brave]
+  active              = "true"
+  base_url            = "https://api.search.brave.com/res/v1/web/search"
+  env_key             = "BRAVE_API_KEY"           # → .env: BRAVE_API_KEY=BSA...
+  default_results     = "5"
+  max_results         = "20"
+  fallback_to         = "tavily"
+  [SEARCH_PROVIDER.brave_END]
+
+  [SEARCH_PROVIDER.tavily]
+  active              = "true"
+  base_url            = "https://api.tavily.com/search"
+  env_key             = "TAVILY_API_KEY"          # → .env: TAVILY_API_KEY=tvly-...
+  default_results     = "5"
+  max_results         = "10"
+  include_answer      = "true"                    # AI-synthesized answer
+  fallback_to         = ""
+  [SEARCH_PROVIDER.tavily_END]
+
+  # ── Add more search providers below ───────────────────────────────────────
+  # [SEARCH_PROVIDER.serper]
+  # active            = "false"
+  # base_url          = "https://google.serper.dev/search"
+  # env_key           = "SERPER_API_KEY"
+  # fallback_to       = ""
+  # [SEARCH_PROVIDER.serper_END]
+
+[SEARCH_PROVIDERS_END]
+
+# ── Web / Action Providers (Webhooks, Bots, Social) ───────────────────────────
+# [WEB_PROVIDERS]
+
+  # [WEB_PROVIDER.discord]
+  # active            = "false"
+  # base_url          = "https://discord.com/api/v10"
+  # env_key           = "BOT_TOKEN"
+  # [WEB_PROVIDER.discord_END]
+
+  # [WEB_PROVIDER.github]
+  # active            = "false"
+  # base_url          = "https://api.github.com"
+  # env_key           = "GITHUB_TOKEN"
+  # [WEB_PROVIDER.github_END]
+
+# [WEB_PROVIDERS_END]
+
+[PROVIDERS_END]
+
+# =============================================================================
+# MODELS — Token & rate limits per model
+# Parser builds: MODELS[provider][model_name] → limits dict
+# =============================================================================
+[MODELS]
+
+  [MODEL.claude-opus-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "32000"
+  requests_per_min    = "5"
+  requests_per_day    = "300"
+  cost_input_per_1k   = "0.015"                  # USD — update as pricing changes
+  cost_output_per_1k  = "0.075"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-opus-4-6_END]
+
+  [MODEL.claude-sonnet-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "16000"
+  requests_per_min    = "50"
+  requests_per_day    = "1000"
+  cost_input_per_1k   = "0.003"
+  cost_output_per_1k  = "0.015"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-sonnet-4-6_END]
+
+  [MODEL.claude-haiku-4-5-20251001]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "8000"
+  requests_per_min    = "50"
+  requests_per_day    = "2000"
+  cost_input_per_1k   = "0.00025"
+  cost_output_per_1k  = "0.00125"
+  capabilities        = "text, code, fast"
+  [MODEL.claude-haiku-4-5-20251001_END]
+
+  [MODEL.gemini-2.0-flash]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1500"
+  cost_input_per_1k   = "0.00010"
+  cost_output_per_1k  = "0.00040"
+  capabilities        = "text, code, vision, audio"
+  [MODEL.gemini-2.0-flash_END]
+
+  [MODEL.gemini-1.5-pro]
+  provider            = "gemini"
+  context_tokens      = "2000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "2"
+  requests_per_day    = "50"
+  cost_input_per_1k   = "0.00125"
+  cost_output_per_1k  = "0.00500"
+  capabilities        = "text, code, vision, audio, long-context"
+  [MODEL.gemini-1.5-pro_END]
+
+  [MODEL.mistral-7b-instruct]
+  provider            = "openrouter"
+  context_tokens      = "32000"
+  max_output_tokens   = "4096"
+  requests_per_min    = "60"
+  requests_per_day    = "10000"
+  cost_input_per_1k   = "0.00006"
+  cost_output_per_1k  = "0.00006"
+  capabilities        = "text, code, fast, cheap"
+  [MODEL.mistral-7b-instruct_END]
+
+[MODELS_END]
+
+# =============================================================================
+# TOOLS — Tool definitions + provider mapping
+# Tools are registered in mcp.py only if their provider ENV key exists!
+# =============================================================================
+[TOOLS]
+
+  [TOOL.llm_complete]
+  active              = "true"
+  description         = "Send prompt to any configured LLM provider"
+  provider_type       = "llm"
+  default_provider    = "anthropic"
+  timeout_sec         = "60"
+  [TOOL.llm_complete_END]
+
+  [TOOL.web_search]
+  active              = "true"
+  description         = "Search the web via configured search provider"
+  provider_type       = "search"
+  default_provider    = "brave"
+  timeout_sec         = "30"
+  [TOOL.web_search_END]
+
+  [TOOL.db_query]
+  active              = "true"
+  description         = "Execute SELECT queries on connected database (read-only)"
+  provider_type       = "db"
+  readonly            = "true"
+  timeout_sec         = "10"
+  [TOOL.db_query_END]
+
+  # ── Future tools ──────────────────────────────────────────────────────────
+  # [TOOL.image_gen]
+  # active            = "false"
+  # description       = "Generate images via configured provider"
+  # provider_type     = "image"
+  # default_provider  = ""
+  # timeout_sec       = "120"
+  # [TOOL.image_gen_END]
+
+  # [TOOL.code_exec]
+  # active            = "false"
+  # description       = "Execute sandboxed code snippets"
+  # provider_type     = "sandbox"
+  # timeout_sec       = "30"
+  # [TOOL.code_exec_END]
+
+[TOOLS_END]
+
+# =============================================================================
+# DB_SYNC — Internal SQLite config for app/* IPC
+# This is NOT the cloud DB — that lives in .env → DATABASE_URL
+# =============================================================================
+[DB_SYNC]
+SQLITE_PATH         = "app/.hub_state.db"       # internal state, never commit!
+SYNC_INTERVAL_SEC   = "30"                       # how often to flush to SQLite
+MAX_CACHE_ENTRIES   = "1000"
+[DB_SYNC_END]
+
+# =============================================================================
+# DEBUG — app/* debug behavior (fundaments debug stays in .env)
+# =============================================================================
+[DEBUG]
+DEBUG               = "ON"                       # ON | OFF
+DEBUG_LEVEL         = "FULL"                     # FULL | WARN | ERROR
+LOG_FILE            = "hub_debug.log"
+LOG_REQUESTS        = "true"                     # log every provider request
+LOG_RESPONSES       = "false"                    # careful: may log sensitive data!
+[DEBUG_END]

app/__init__.py

@@ -0,0 +1 @@
+

app/app.py

@@ -0,0 +1,281 @@
+# =============================================================================
+# app/app.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file is the Orchestrator of the sandboxed app/* layer.
+#   It is ONLY started by main.py (the "Guardian").
+#   All fundament services are injected via the `fundaments` dictionary.
+#   Direct execution is blocked by design.
+#
+# SANDBOX RULE:
+#   app/* has NO direct access to .env or fundaments/*.
+#   Config for app/* lives in app/.pyfun (provider URLs, models, tool settings).
+#   Secrets stay in .env → Guardian reads them → injects what app/* needs.
+# =============================================================================
+
+from quart import Quart, request, jsonify  # async Flask — required for async cloud providers + Neon DB
+import logging
+from waitress import serve                  # WSGI server — keeps Flask non-blocking alongside asyncio
+import threading                            # bank-pattern: each blocking service gets its own thread
+import requests                             # sync HTTP for health check worker
+import time
+from datetime import datetime
+import asyncio
+import sys
+from typing import Dict, Any, Optional
+
+# =============================================================================
+# Import app/* modules
+# Config/settings for all modules below live in app/.pyfun — not in .env!
+# =============================================================================
+from . import mcp          # MCP transport layer (stdio / SSE)
+from . import providers    # API provider registry (LLM, Search, Web)
+from . import models       # Model config + token/rate limits
+from . import tools        # MCP tool definitions + provider mapping
+from . import db_sync      # Internal SQLite IPC — app/* state & communication
+                           # db_sync ≠ cloud DB! Cloud DB is Guardian-only via main.py.
+
+# Future modules (soon uncommented when ready):
+# from . import discord_api  # Discord bot integration
+# from . import hf_hooks     # HuggingFace Space hooks
+# from . import git_hooks    # GitHub/GitLab webhook handler
+# from . import web_api      # Generic REST API handler
+
+# =============================================================================
+# Loggers — one per module for clean log filtering
+# =============================================================================
+logger          = logging.getLogger('application')
+logger          = logging.getLogger('config')
+# logger_mcp      = logging.getLogger('mcp')
+# logger_tools    = logging.getLogger('tools')
+# logger_providers = logging.getLogger('providers')
+# logger_models   = logging.getLogger('models')
+# logger_db_sync  = logging.getLogger('db_sync')
+
+# =============================================================================
+# Flask app instance
+# =============================================================================
+app = Quart(__name__)
+START_TIME = datetime.utcnow()
+
+# =============================================================================
+# Global service references (set during initialize_services)
+# =============================================================================
+_fundaments: Optional[Dict[str, Any]] = None
+PORT = None
+
+# =============================================================================
+# Service initialization
+# =============================================================================
+def initialize_services(fundaments: Dict[str, Any]) -> None:
+    """
+    Initializes all app/* services with injected fundaments from Guardian.
+    Called once during start_application — sets global service references.
+    """
+    global _fundaments, PORT
+
+    _fundaments = fundaments
+    PORT = fundaments["config"].get_int("PORT", 7860)
+
+    # Initialize internal SQLite state store for app/* IPC
+    db_sync.initialize()
+
+    # Initialize provider registry from app/.pyfun + ENV key presence check
+    providers.initialize(fundaments["config"])
+
+    # Initialize model registry from app/.pyfun
+    models.initialize()
+
+    # Initialize tool registry — tools only register if their provider is active
+    tools.initialize(providers, models, fundaments)
+
+    logger.info("app/* services initialized.")
+
+
+# =============================================================================
+# Background workers
+# =============================================================================
+def start_mcp_in_thread() -> None:
+    """
+    Starts the MCP Hub (stdio or SSE) in its own thread with its own event loop.
+    Mirrors the bank-thread pattern from the Discord bot architecture.
+    """
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(mcp.start_mcp(_fundaments))
+    finally:
+        loop.close()
+
+
+def health_check_worker() -> None:
+    """
+    Periodic self-ping to keep the app alive on hosting platforms (e.g. HuggingFace).
+    Runs in its own daemon thread — does not block the main loop.
+    """
+    while True:
+        time.sleep(3600)
+        try:
+            response = requests.get(f"http://127.0.0.1:{PORT}/")
+            logger.info(f"Health check ping: {response.status_code}")
+        except Exception as e:
+            logger.error(f"Health check failed: {e}")
+
+
+# =============================================================================
+# Flask Routes
+# =============================================================================
+
+@app.route("/", methods=["GET"])
+async def health_check():
+    """
+    Health check endpoint.
+    Used by HuggingFace Spaces and monitoring systems to verify the app is running.
+    """
+    uptime = datetime.utcnow() - START_TIME
+    return jsonify({
+        "status": "running",
+        "service": "Universal MCP Hub",
+        "uptime_seconds": int(uptime.total_seconds()),
+        "active_providers": providers.get_active_names() if providers else [],
+    })
+
+
+@app.route("/api", methods=["POST"])
+async def api_endpoint():
+    """
+    Generic REST API endpoint for direct tool invocation.
+    Accepts JSON: { "tool": "tool_name", "params": { ... } }
+    Auth and validation handled by tools layer.
+    """
+    # TODO: implement tool dispatch via tools.invoke()
+    data = await request.get_json()
+    return jsonify({"status": "not_implemented", "received": data}), 501
+
+
+@app.route("/crypto", methods=["POST"])
+async def crypto_endpoint():
+    """
+    Encrypted API endpoint.
+    Payload is decrypted via fundaments/encryption.py (injected by Guardian).
+    Only active if encryption_service is available in fundaments.
+    """
+    encryption_service = _fundaments.get("encryption") if _fundaments else None
+    if not encryption_service:
+        return jsonify({"error": "Encryption service not available"}), 503
+
+    # TODO: decrypt payload, dispatch, re-encrypt response
+    data = await request.get_json()
+    return jsonify({"status": "not_implemented"}), 501
+
+
+# Future routes (uncomment when ready):
+# @app.route("/discord", methods=["POST"])
+# async def discord_interactions():
+#     """Discord interactions endpoint — signature verification via discord_api module."""
+#     pass
+
+# @app.route("/webhook/hf", methods=["POST"])
+# async def hf_webhook():
+#     """HuggingFace Space event hooks."""
+#     pass
+
+# @app.route("/webhook/git", methods=["POST"])
+# async def git_webhook():
+#     """GitHub / GitLab webhook handler."""
+#     pass
+
+
+# =============================================================================
+# Main entry point — called by Guardian (main.py)
+# =============================================================================
+async def start_application(fundaments: Dict[str, Any]) -> None:
+    """
+    Main entry point for the sandboxed app layer.
+    Called exclusively by main.py after all fundament services are initialized.
+
+    Args:
+        fundaments: Dictionary of initialized services from Guardian (main.py).
+                    All services already validated — may be None if not configured.
+    """
+    logger.info("Application starting...")
+
+    # --- Unpack fundament services (read-only references) ---
+    config_service          = fundaments["config"]
+    db_service              = fundaments["db"]              # None if no DB configured
+    encryption_service      = fundaments["encryption"]      # None if keys not set
+    access_control_service  = fundaments["access_control"]  # None if no DB
+    user_handler_service    = fundaments["user_handler"]    # None if no DB
+    security_service        = fundaments["security"]        # None if deps missing
+
+    # --- Initialize all app/* services ---
+    initialize_services(fundaments)
+
+    # --- Log active fundament services ---
+    if encryption_service:
+        logger.info("Encryption service active.")
+
+    if user_handler_service and security_service:
+        logger.info("Auth services active (user_handler + security).")
+
+    if access_control_service and security_service:
+        logger.info("Access control active.")
+
+    if db_service and not user_handler_service:
+        logger.info("Database-only mode active (e.g. ML pipeline).")
+
+    if not db_service:
+        logger.info("Database-free mode active (e.g. Discord bot, API client).")
+
+    # --- Start MCP Hub in its own thread (stdio or SSE) ---
+    mcp_thread = threading.Thread(target=start_mcp_in_thread, daemon=True)
+    mcp_thread.start()
+    logger.info("MCP Hub thread started.")
+
+    # Allow MCP to initialize before Flask comes up
+    await asyncio.sleep(1)
+
+    # --- Start health check worker ---
+    health_thread = threading.Thread(target=health_check_worker, daemon=True)
+    health_thread.start()
+
+    # --- Start Flask/Quart via Waitress in its own thread ---
+    def run_server():
+        serve(app, host="0.0.0.0", port=PORT)
+
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+    logger.info(f"HTTP server started on port {PORT}.")
+
+    logger.info("All services running. Entering heartbeat loop...")
+
+    # --- Heartbeat loop — keeps Guardian's async context alive ---
+    try:
+        while True:
+            await asyncio.sleep(60)
+            logger.debug("Heartbeat.")
+    except KeyboardInterrupt:
+        logger.info("Shutdown signal received.")
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == '__main__':
+    print("WARNING: Running app.py directly. Fundament modules might not be correctly initialized.")
+    print("Please run 'python main.py' instead for proper initialization.")
+
+    test_fundaments = {
+        "config":           None,
+        "db":               None,
+        "encryption":       None,
+        "access_control":   None,
+        "user_handler":     None,
+        "security":         None,
+    }
+
+    asyncio.run(start_application(test_fundaments))

app/config.py

@@ -0,0 +1,293 @@
+# =============================================================================
+# app/config.py
+# .pyfun parser for app/* modules
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# USAGE in any app/* module:
+#   from . import config
+#   cfg = config.get()
+#   providers = cfg["LLM_PROVIDERS"]
+# =============================================================================
+# USAGE
+# in providers.py
+# from . import config
+
+# active = config.get_active_llm_providers()
+# → { "anthropic": { "base_url": "...", "env_key": "ANTHROPIC_API_KEY", ... }, ... }
+# =============================================================================
+# in models.py  
+# from . import config
+
+# anthropic_models = config.get_models_for_provider("anthropic")
+# =============================================================================
+# in tools.py
+# from . import config
+
+# active_tools = config.get_active_tools()
+# =============================================================================
+import os
+import logging
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger('app.config')
+
+# Path to .pyfun — lives in app/ next to this file
+PYFUN_PATH = os.path.join(os.path.dirname(__file__), ".pyfun")
+
+# Internal cache — loaded once at first get()
+_cache: Optional[Dict[str, Any]] = None
+
+
+def _parse_value(value: str) -> str:
+    """Strip quotes and inline comments from a value."""
+    value = value.strip()
+    # Remove inline comment
+    if " #" in value:
+        value = value[:value.index(" #")].strip()
+    # Strip surrounding quotes
+    if value.startswith('"') and value.endswith('"'):
+        value = value[1:-1]
+    return value
+
+
+def _parse() -> Dict[str, Any]:
+    """
+    Parses the app/.pyfun file into a nested dictionary.
+
+    Structure:
+        [SECTION]
+            [SUBSECTION]
+                [BLOCK.name]
+                key = "value"
+                [BLOCK.name_END]
+            [SUBSECTION_END]
+        [SECTION_END]
+
+    Returns nested dict:
+        {
+            "HUB": { "HUB_NAME": "...", ... },
+            "LLM_PROVIDERS": {
+                "anthropic": { "active": "true", "base_url": "...", ... },
+                "gemini":    { ... },
+            },
+            "MODELS": {
+                "claude-opus-4-6": { "provider": "anthropic", ... },
+            },
+            ...
+        }
+    """
+    if not os.path.isfile(PYFUN_PATH):
+        logger.critical(f".pyfun not found at: {PYFUN_PATH}")
+        raise FileNotFoundError(f".pyfun not found at: {PYFUN_PATH}")
+
+    result: Dict[str, Any] = {}
+
+    # Parser state
+    section: Optional[str]      = None   # e.g. "HUB", "PROVIDERS"
+    subsection: Optional[str]   = None   # e.g. "LLM_PROVIDERS"
+    block_type: Optional[str]   = None   # e.g. "LLM_PROVIDER", "MODEL", "TOOL"
+    block_name: Optional[str]   = None   # e.g. "anthropic", "claude-opus-4-6"
+
+    with open(PYFUN_PATH, "r", encoding="utf-8") as f:
+        for raw_line in f:
+            line = raw_line.strip()
+
+            # Skip empty lines and full-line comments
+            if not line or line.startswith("#"):
+                continue
+
+            # Skip file identifier
+            if line.startswith("[PYFUN_FILE"):
+                continue
+
+            # --- Block END markers (most specific first) ---
+            if line.endswith("_END]") and "." in line:
+                # e.g. [LLM_PROVIDER.anthropic_END] or [MODEL.claude-opus-4-6_END]
+                block_type = None
+                block_name = None
+                continue
+
+            if line.endswith("_END]") and not "." in line:
+                # e.g. [LLM_PROVIDERS_END], [HUB_END], [MODELS_END]
+                inner = line[1:-1].replace("_END", "")
+                if subsection and inner == subsection:
+                    subsection = None
+                elif section and inner == section:
+                    section = None
+                continue
+
+            # --- Block START markers ---
+            if line.startswith("[") and line.endswith("]"):
+                inner = line[1:-1]
+
+                # Named block: [LLM_PROVIDER.anthropic] or [MODEL.claude-opus-4-6]
+                if "." in inner:
+                    parts = inner.split(".", 1)
+                    block_type = parts[0]   # e.g. LLM_PROVIDER, MODEL, TOOL
+                    block_name = parts[1]   # e.g. anthropic, claude-opus-4-6
+
+                    # Determine which top-level key to store under
+                    if block_type == "LLM_PROVIDER":
+                        result.setdefault("LLM_PROVIDERS", {})
+                        result["LLM_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "SEARCH_PROVIDER":
+                        result.setdefault("SEARCH_PROVIDERS", {})
+                        result["SEARCH_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "WEB_PROVIDER":
+                        result.setdefault("WEB_PROVIDERS", {})
+                        result["WEB_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "MODEL":
+                        result.setdefault("MODELS", {})
+                        result["MODELS"].setdefault(block_name, {})
+                    elif block_type == "TOOL":
+                        result.setdefault("TOOLS", {})
+                        result["TOOLS"].setdefault(block_name, {})
+                    continue
+
+                # Subsection: [LLM_PROVIDERS], [SEARCH_PROVIDERS] etc.
+                if section and not subsection:
+                    subsection = inner
+                    result.setdefault(inner, {})
+                    continue
+
+                # Top-level section: [HUB], [PROVIDERS], [MODELS] etc.
+                section = inner
+                result.setdefault(inner, {})
+                continue
+
+            # --- Key = Value ---
+            if "=" in line:
+                key, _, val = line.partition("=")
+                key = key.strip()
+                val = _parse_value(val)
+
+                # Strip provider prefix from key (e.g. "anthropic.base_url" → "base_url")
+                if block_name and key.startswith(f"{block_name}."):
+                    key = key[len(block_name) + 1:]
+
+                # Store in correct location
+                if block_type and block_name:
+                    if block_type == "LLM_PROVIDER":
+                        result["LLM_PROVIDERS"][block_name][key] = val
+                    elif block_type == "SEARCH_PROVIDER":
+                        result["SEARCH_PROVIDERS"][block_name][key] = val
+                    elif block_type == "WEB_PROVIDER":
+                        result["WEB_PROVIDERS"][block_name][key] = val
+                    elif block_type == "MODEL":
+                        result["MODELS"][block_name][key] = val
+                    elif block_type == "TOOL":
+                        result["TOOLS"][block_name][key] = val
+                elif section:
+                    result[section][key] = val
+
+    logger.info(f".pyfun loaded. Sections: {list(result.keys())}")
+    return result
+
+
+def load() -> Dict[str, Any]:
+    """Force (re)load of .pyfun — clears cache."""
+    global _cache
+    _cache = _parse()
+    return _cache
+
+
+def get() -> Dict[str, Any]:
+    """
+    Returns parsed .pyfun config as nested dict.
+    Loads and caches on first call — subsequent calls return cache.
+    """
+    global _cache
+    if _cache is None:
+        _cache = _parse()
+    return _cache
+
+
+def get_section(section: str) -> Dict[str, Any]:
+    """
+    Returns a specific top-level section.
+    Returns empty dict if section not found.
+    """
+    return get().get(section, {})
+
+
+def get_llm_providers() -> Dict[str, Any]:
+    """Returns all LLM providers (active and inactive)."""
+    return get().get("LLM_PROVIDERS", {})
+
+
+def get_active_llm_providers() -> Dict[str, Any]:
+    """Returns only LLM providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_llm_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_search_providers() -> Dict[str, Any]:
+    """Returns all search providers."""
+    return get().get("SEARCH_PROVIDERS", {})
+
+
+def get_active_search_providers() -> Dict[str, Any]:
+    """Returns only search providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_search_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_models() -> Dict[str, Any]:
+    """Returns all model definitions."""
+    return get().get("MODELS", {})
+
+
+def get_models_for_provider(provider_name: str) -> Dict[str, Any]:
+    """Returns all models for a specific provider."""
+    return {
+        name: cfg
+        for name, cfg in get_models().items()
+        if cfg.get("provider", "") == provider_name
+    }
+
+
+def get_tools() -> Dict[str, Any]:
+    """Returns all tool definitions."""
+    return get().get("TOOLS", {})
+
+
+def get_active_tools() -> Dict[str, Any]:
+    """Returns only tools where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_tools().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_hub() -> Dict[str, Any]:
+    """Returns [HUB] section."""
+    return get_section("HUB")
+
+
+def get_limits() -> Dict[str, Any]:
+    """Returns [HUB_LIMITS] section."""
+    return get_section("HUB_LIMITS")
+
+
+def get_db_sync() -> Dict[str, Any]:
+    """Returns [DB_SYNC] section."""
+    return get_section("DB_SYNC")
+
+
+def get_debug() -> Dict[str, Any]:
+    """Returns [DEBUG] section."""
+    return get_section("DEBUG")
+
+
+def is_debug() -> bool:
+    """Returns True if DEBUG = 'ON' in .pyfun."""
+    return get_debug().get("DEBUG", "OFF").upper() == "ON"

app/db_sync.py

@@ -0,0 +1 @@
+

app/mcp.py

@@ -0,0 +1,268 @@
+# app/mcp.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+#
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in /app/ and is ONLY started by main.py (the "Guardian").
+#   It has NO direct access to API keys, environment variables, or fundament services.
+#   Everything is injected by the Guardian via the `fundaments` dictionary.
+#   Direct execution is blocked by design.
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are only registered if their required API key/service is present.
+#   No key = no tool = no crash. The server always starts, just with fewer tools.
+
+import asyncio
+import logging
+import os
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger('mcp_hub')
+
+
+async def start_mcp(fundaments: Dict[str, Any]):
+    """
+    The main entry point for the MCP Hub logic.
+    All fundament services are validated and provided by main.py.
+
+    Args:
+        fundaments: Dictionary containing initialized services from main.py.
+                    Services are already validated and ready to use.
+    """
+    logger.info("MCP Hub starting...")
+
+    # Services are already validated and initialized by main.py
+    config_service        = fundaments["config"]
+    db_service            = fundaments["db"]             # Can be None if not needed
+    encryption_service    = fundaments["encryption"]     # Can be None if not needed
+    access_control_service = fundaments["access_control"] # Can be None if not needed
+    user_handler_service  = fundaments["user_handler"]   # Can be None if not needed
+    security_service      = fundaments["security"]       # Can be None if not needed
+
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        logger.critical("FastMCP is not installed. Run: pip install fastmcp")
+        raise
+
+    mcp = FastMCP(
+        name="PyFundaments MCP Hub",
+        instructions=(
+            "Universal MCP Hub built on PyFundaments. "
+            "Available tools depend on configured API keys and active services. "
+            "Use list_active_tools to see what is currently available."
+        )
+    )
+
+    # --- LLM Tools (register if API key is present) ---
+
+    if config_service.has("ANTHROPIC_API_KEY"):
+        import httpx
+        _key = config_service.get("ANTHROPIC_API_KEY")
+
+        @mcp.tool()
+        async def anthropic_complete(prompt: str, model: str = "claude-haiku-4-5-20251001", max_tokens: int = 1024) -> str:
+            """Send a prompt to Anthropic Claude. Models: claude-haiku-4-5-20251001, claude-sonnet-4-6, claude-opus-4-6"""
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    "https://api.anthropic.com/v1/messages",
+                    headers={"x-api-key": _key, "anthropic-version": "2023-06-01", "content-type": "application/json"},
+                    json={"model": model, "max_tokens": max_tokens, "messages": [{"role": "user", "content": prompt}]},
+                    timeout=60.0
+                )
+                r.raise_for_status()
+                return r.json()["content"][0]["text"]
+        logger.info("Tool registered: anthropic_complete")
+
+    if config_service.has("GEMINI_API_KEY"):
+        import httpx
+        _key = config_service.get("GEMINI_API_KEY")
+
+        @mcp.tool()
+        async def gemini_complete(prompt: str, model: str = "gemini-2.0-flash", max_tokens: int = 1024) -> str:
+            """Send a prompt to Google Gemini. Models: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash"""
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent",
+                    params={"key": _key},
+                    json={"contents": [{"parts": [{"text": prompt}]}], "generationConfig": {"maxOutputTokens": max_tokens}},
+                    timeout=60.0
+                )
+                r.raise_for_status()
+                return r.json()["candidates"][0]["content"]["parts"][0]["text"]
+        logger.info("Tool registered: gemini_complete")
+
+    if config_service.has("OPENROUTER_API_KEY"):
+        import httpx
+        _key     = config_service.get("OPENROUTER_API_KEY")
+        _referer = config_service.get("APP_URL", "https://huggingface.co")
+
+        @mcp.tool()
+        async def openrouter_complete(prompt: str, model: str = "mistralai/mistral-7b-instruct", max_tokens: int = 1024) -> str:
+            """Send a prompt via OpenRouter (100+ models). Examples: openai/gpt-4o, meta-llama/llama-3-8b-instruct"""
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    "https://openrouter.ai/api/v1/chat/completions",
+                    headers={"Authorization": f"Bearer {_key}", "HTTP-Referer": _referer, "content-type": "application/json"},
+                    json={"model": model, "max_tokens": max_tokens, "messages": [{"role": "user", "content": prompt}]},
+                    timeout=60.0
+                )
+                r.raise_for_status()
+                return r.json()["choices"][0]["message"]["content"]
+        logger.info("Tool registered: openrouter_complete")
+
+    if config_service.has("HF_TOKEN"):
+        import httpx
+        _key = config_service.get("HF_TOKEN")
+
+        @mcp.tool()
+        async def hf_inference(prompt: str, model: str = "mistralai/Mistral-7B-Instruct-v0.3", max_tokens: int = 512) -> str:
+            """Send a prompt to HuggingFace Inference API. Browse models: https://huggingface.co/models?inference=warm"""
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    f"https://api-inference.huggingface.co/models/{model}/v1/chat/completions",
+                    headers={"Authorization": f"Bearer {_key}", "content-type": "application/json"},
+                    json={"model": model, "max_tokens": max_tokens, "messages": [{"role": "user", "content": prompt}]},
+                    timeout=120.0
+                )
+                r.raise_for_status()
+                return r.json()["choices"][0]["message"]["content"]
+        logger.info("Tool registered: hf_inference")
+
+    # --- Search Tools (register if API key is present) ---
+
+    if config_service.has("BRAVE_API_KEY"):
+        import httpx
+        _key = config_service.get("BRAVE_API_KEY")
+
+        @mcp.tool()
+        async def brave_search(query: str, count: int = 5) -> str:
+            """Search the web via Brave Search API (independent index, privacy-focused)."""
+            async with httpx.AsyncClient() as client:
+                r = await client.get(
+                    "https://api.search.brave.com/res/v1/web/search",
+                    headers={"Accept": "application/json", "X-Subscription-Token": _key},
+                    params={"q": query, "count": min(count, 20)},
+                    timeout=30.0
+                )
+                r.raise_for_status()
+                results = r.json().get("web", {}).get("results", [])
+                if not results:
+                    return "No results found."
+                return "\n\n".join([
+                    f"{i}. {res.get('title', '')}\n   {res.get('url', '')}\n   {res.get('description', '')}"
+                    for i, res in enumerate(results, 1)
+                ])
+        logger.info("Tool registered: brave_search")
+
+    if config_service.has("TAVILY_API_KEY"):
+        import httpx
+        _key = config_service.get("TAVILY_API_KEY")
+
+        @mcp.tool()
+        async def tavily_search(query: str, max_results: int = 5) -> str:
+            """AI-optimized web search via Tavily. Returns synthesized answer + sources."""
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    "https://api.tavily.com/search",
+                    json={"api_key": _key, "query": query, "max_results": max_results, "include_answer": True},
+                    timeout=30.0
+                )
+                r.raise_for_status()
+                data = r.json()
+                parts = []
+                if data.get("answer"):
+                    parts.append(f"Summary: {data['answer']}")
+                for res in data.get("results", []):
+                    parts.append(f"- {res['title']}\n  {res['url']}\n  {res.get('content', '')[:200]}...")
+                return "\n\n".join(parts)
+        logger.info("Tool registered: tavily_search")
+
+    # --- DB Tools (register only if DB is initialized) ---
+
+    if db_service is not None:
+        from fundaments.postgresql import execute_secured_query
+
+        @mcp.tool()
+        async def db_query(sql: str) -> str:
+            """Execute a read-only SELECT query. All write operations are blocked."""
+            if not sql.strip().upper().startswith("SELECT"):
+                return "Error: Only SELECT statements are permitted."
+            try:
+                result = await execute_secured_query(sql, fetch_method='fetch')
+                if not result:
+                    return "No results."
+                return str([dict(row) for row in result])
+            except Exception as e:
+                logger.error(f"DB query error: {e}")
+                return f"Database error: {str(e)}"
+        logger.info("Tool registered: db_query")
+
+    else:
+        logger.info("No database available - DB tools skipped.")
+
+    # --- System Tools (always registered) ---
+
+    @mcp.tool()
+    def list_active_tools() -> Dict[str, Any]:
+        """Show active services and configured integrations (key names only, never values)."""
+        return {
+            "fundaments_status": {k: v is not None for k, v in fundaments.items()},
+            "configured_integrations": [
+                key for key in [
+                    "ANTHROPIC_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY",
+                    "HF_TOKEN", "BRAVE_API_KEY", "TAVILY_API_KEY", "DATABASE_URL"
+                ] if config_service.has(key)
+            ],
+            "transport": os.getenv("MCP_TRANSPORT", "stdio"),
+            "app_mode":  os.getenv("APP_MODE", "mcp")
+        }
+    logger.info("Tool registered: list_active_tools")
+
+    @mcp.tool()
+    def health_check() -> Dict[str, str]:
+        """Health check endpoint for HuggingFace Spaces and monitoring."""
+        return {"status": "ok", "service": "PyFundaments MCP Hub"}
+    logger.info("Tool registered: health_check")
+
+    # --- Encryption available ---
+    if encryption_service:
+        logger.info("Encryption service active - available for future tools.")
+
+    # --- Auth/Security available ---
+    if user_handler_service and security_service:
+        logger.info("Auth services active - available for future tools.")
+
+    # --- Start transport ---
+    transport = os.getenv("MCP_TRANSPORT", "stdio").lower()
+    if transport == "sse":
+        host = os.getenv("HOST", "0.0.0.0")
+        port = int(os.getenv("PORT", "7860"))
+        logger.info(f"MCP Hub starting via SSE on {host}:{port}")
+        mcp.run(transport="sse", host=host, port=port)
+    else:
+        logger.info("MCP Hub starting via stdio (local mode)")
+        await mcp.run_stdio_async()       # ← direkt awaiten, kein neuer Loop!
+
+    logger.info("MCP Hub shut down.")
+
+
+# ============================================================
+# Direct execution guard - mirrors example.app.py exactly
+# ============================================================
+if __name__ == '__main__':
+    print("WARNING: Running mcp.py directly. Fundament modules might not be correctly initialized.")
+    print("Please run 'python main.py' instead for proper initialization.")
+
+    test_fundaments = {
+        "config": None,
+        "db": None,
+        "encryption": None,
+        "access_control": None,
+        "user_handler": None,
+        "security": None
+    }
+
+    asyncio.run(start_mcp(test_fundaments))

app/models.py

@@ -0,0 +1 @@
+

app/provider.py

@@ -0,0 +1 @@
+

app/tools.py

@@ -0,0 +1 @@
+

docs/access_control.py.md

@@ -0,0 +1,112 @@
+# Secure Role-Based Access Control (RBAC)
+
+### Overview
+
+This module acts as the service layer for managing user permissions and roles. It is a critical component of a secure application, ensuring that users can only access the resources they are authorized for.
+
+The module is a prime example of building a robust logical layer on a solid foundation. It utilizes the secure database connection provided by `postgresql.py` to handle all interactions with the database, guaranteeing that every query is executed safely and correctly without exposing the underlying security logic.
+
+-----
+
+### Core Concepts: The RBAC Model
+
+This module implements a standard Role-Based Access Control model with the following components:
+
+  - **Users:** Application users with unique IDs.
+  - **Permissions:** Granular rights or actions a user can perform (e.g., `create_post`, `edit_profile`).
+  - **Roles:** Collections of permissions (e.g., `admin`, `editor`, `viewer`).
+  - **Assignments:** Roles are assigned to users, granting them all the permissions associated with that role.
+
+-----
+
+### Dependencies
+
+This module is built on your project's existing `fundaments`:
+
+  - `postgresql.py`: The secure database connection module.
+  - `asyncpg`: The asynchronous PostgreSQL driver.
+
+-----
+
+### Usage
+
+The `AccessControl` class is designed to be instantiated for a specific user, making it simple to check their permissions.
+
+#### 1\. **Initialization**
+
+The class is initialized with a user's ID.
+
+```python
+from fundaments.access_control import AccessControl
+
+# Assume a user with ID 1 exists
+user_id = 1
+access_control = AccessControl(user_id)
+```
+
+#### 2\. **Checking Permissions**
+
+The `has_permission` method checks if the user has a specific permission.
+
+```python
+# Check if the user has the 'create_post' permission
+can_create_post = await access_control.has_permission('create_post')
+
+if can_create_post:
+    print("User is authorized to create a new post.")
+else:
+    print("Permission denied.")
+```
+
+#### 3\. **Retrieving User Information**
+
+You can easily fetch a list of a user's roles or permissions.
+
+```python
+# Get all roles assigned to the user
+user_roles = await access_control.get_user_roles()
+print(f"User's roles: {user_roles}")
+
+# Get all permissions for the user
+user_permissions = await access_control.get_user_permissions()
+print(f"User's permissions: {user_permissions}")
+```
+
+#### 4\. **Administrative Functions**
+
+The module also includes methods for managing roles and permissions (e.g., in an admin panel).
+
+```python
+# Create a new role
+new_role_id = await access_control.create_role(
+    name='moderator',
+    description='Manages posts and comments.'
+)
+
+# Assign a role to the user
+await access_control.assign_role(new_role_id)
+
+# Get permissions for a specific role
+moderator_permissions = await access_control.get_role_permissions(new_role_id)
+```
+
+-----
+
+### Database Schema (Required)
+
+The module's functionality relies on the following relational schema:
+
+  - `user_roles`: Stores all available roles (`id`, `name`, `description`).
+  - `user_permissions`: Stores all available permissions (`id`, `name`, `description`).
+  - `user_role_assignments`: A junction table linking `user_id` to `role_id`.
+  - `role_permissions`: A junction table linking `role_id` to `permission_id`.
+
+-----
+
+### Security & Architecture
+
+  - **Secure by Design:** This module never executes raw, unsanitized SQL. Every database operation is channeled through the secure `db.execute_secured_query` function, inheriting its protection against SQL injection and other vulnerabilities.
+  - **Separation of Concerns:** It successfully separates the business logic of access control from the low-level concerns of database security, making the entire application more robust and easier to maintain.
+  - **Extensibility:** New access control methods can be added easily by following the established pattern of using the underlying `db` module.
+
+This `access_control.py` is a prime example of a secure, modular, and extensible building block for your application's architecture.

docs/config_handler.py.md

@@ -0,0 +1,34 @@
+# Module: `config_handler.py`
+
+## Description
+
+The `config_handler` module is a core component of the application's security fundament. It provides a centralized, secure, and robust mechanism for managing all critical environment variables. By enforcing early validation, it prevents the application from starting in an insecure or misconfigured state.
+
+## Core Principles
+
+  - **Centralized Source of Truth**: All environment variables are loaded and managed from a single point.
+  - **Fail-Fast Mechanism**: The application exits immediately if any required configuration key is missing. This prevents runtime errors and potential security vulnerabilities from a broken setup.
+  - **Separation of Concerns**: It decouples the loading and validation of configurations from the business logic of other modules.
+
+## Required Environment Variables
+
+The `ConfigHandler` is configured to specifically look for the following keys, which must be present in the `.env` file or the system's environment variables.
+
+| Key | Description | Example |
+| :--- | :--- | :--- |
+| `DATABASE_URL` | The full DSN (Data Source Name) string for the PostgreSQL database. Supports local connections and cloud providers like Neon.tech. | `postgresql://user:password@host:port/database?sslmode=require` |
+| `MASTER_ENCRYPTION_KEY` | A 256-bit key used for symmetric encryption across the application. **Crucial for data security.** | `532c6614...` |
+| `PERSISTENT_ENCRYPTION_SALT` | A unique salt used with the master key to enhance cryptographic security. | `a0b7e8d2...` |
+
+## Usage
+
+Other modules, such as `main.py`, import the singleton instance of the `ConfigHandler` to access validated configuration values safely.
+
+```python
+# In main.py or any other fundament module
+from fundaments.config_handler import config_service
+
+# To get a validated value
+db_url = config_service.get("DATABASE_URL")
+master_key = config_service.get("MASTER_ENCRYPTION_KEY")
+```

docs/encryption.py.md

@@ -0,0 +1,95 @@
+# Secure and Robust Encryption Module (AES-256-GCM)
+
+### Overview
+
+This module provides a secure and reusable encryption component for your application's `fundaments`. It is built on the industry-standard `cryptography` library and utilizes `AES-256-GCM`, an authenticated encryption mode that ensures both confidentiality and integrity of your data.
+
+It is designed to be a "set-and-forget" core component, allowing developers to handle encryption without getting bogged down in low-level cryptographic details, while still adhering to best practices.
+
+-----
+
+### Key Security Concepts
+
+This module's security is built upon the following principles:
+
+1.  **AES-256-GCM:** The chosen algorithm is AES (Advanced Encryption Standard) with a 256-bit key, using GCM (Galois/Counter Mode). GCM is an authenticated encryption mode, meaning it not only encrypts data but also generates a unique **authentication tag** to verify that the data has not been tampered with.
+2.  **Key Derivation (PBKDF2):** The actual encryption key is not the raw master key. Instead, it is derived from the master key and a unique **salt** using PBKDF2 with a high number of iterations. This makes brute-force attacks against the master key computationally infeasible.
+3.  **Nonce/IV:** Each encryption operation generates a unique, random **nonce** (Number used once) to ensure that the same plaintext encrypted multiple times results in different ciphertext, protecting against pattern analysis.
+4.  **Secure Storage:** The module emphasizes the importance of securely storing the **master key** (e.g., in environment variables) and the persistent **salt** (e.g., in a secure configuration file or database).
+
+-----
+
+### Usage
+
+First, ensure the required library is installed: `pip install cryptography`.
+
+#### 1\. **Initialization**
+
+To use the module, you must provide a `master_key` and a persistent `salt`. The `salt` should be generated once and stored securely.
+
+```python
+from fundaments.encryption import Encryption
+
+# Generate a salt ONCE and store it securely
+# DO NOT generate a new salt on every run!
+persistent_salt = Encryption.generate_salt() 
+
+# Your master key should be stored in an environment variable or secret
+master_key = os.getenv("MASTER_ENCRYPTION_KEY")
+
+# Initialize the encryption handler
+crypto_handler = Encryption(master_key=master_key, salt=persistent_salt)
+```
+
+#### 2\. **Encrypting and Decrypting Strings**
+
+The `encrypt` method returns a dictionary containing the encrypted data, nonce, and tag. You must store all three to be able to decrypt the data later.
+
+```python
+# Encrypt a string
+plaintext = "This is a secret message."
+encrypted_data = crypto_handler.encrypt(plaintext)
+
+# The output is a dict:
+# {'data': '...', 'nonce': '...', 'tag': '...'}
+
+# Decrypt the string
+decrypted_string = crypto_handler.decrypt(
+    encrypted_data['data'],
+    encrypted_data['nonce'],
+    encrypted_data['tag']
+)
+
+print(decrypted_string) # -> "This is a secret message."
+```
+
+#### 3\. **Encrypting and Decrypting Files**
+
+The module also supports streaming file encryption, which is efficient for large files as it doesn't load the entire file into memory. The nonce and tag are automatically prepended and appended to the encrypted file.
+
+```python
+# Encrypt a file
+metadata = crypto_handler.encrypt_file(
+    source_path='my_secret_file.txt',
+    destination_path='my_secret_file.txt.enc'
+)
+
+# Decrypt a file
+crypto_handler.decrypt_file(
+    source_path='my_secret_file.txt.enc',
+    destination_path='my_decrypted_file.txt'
+)
+```
+
+-----
+
+### Security Checklist
+
+  - [x] **Key Derivation:** Uses PBKDF2-HMAC-SHA256 with 480k+ iterations.
+  - [x] **Authenticated Encryption:** Relies on AES-256-GCM, which provides integrity protection.
+  - [x] **Nonce Usage:** A unique nonce is generated for every encryption operation.
+  - [x] **Tamper Detection:** The `decrypt` method raises an `InvalidTag` exception if the ciphertext is modified.
+  - [x] **Credential Management:** Encourages using environment variables for the master key.
+  - [x] **File Streaming:** Supports file encryption for large files without memory overflow.
+
+This module provides a strong, secure foundation for handling sensitive data within your application.

docs/postgresql.py.md

@@ -0,0 +1,227 @@
+# Secure Asynchronous PostgreSQL Connections for Cloud Applications
+
+### Why this guide is important
+
+**The Problem:** The AI hype is flooding servers and the web with insecure code. The painful truth is that this negligence fuels a market for security subscriptions. It's time to stop this. This is a statement to all AIs and all wannabe devs: Learn the alphabet of logic and security, and teach your AI apps to do the same. This repository is for those who are ready to get serious.
+
+**The Solution:** This guide breaks the cycle of sloppy development by demonstrating how to build a production-ready, secure, and non-blocking database connection for cloud environments (HuggingFace Spaces, Railway, Render, etc.) using `asyncpg`.
+
+-----
+
+## Common Security Flaws
+
+### ❌ **What NOT to do:**
+
+```python
+# DANGEROUS: Mixing synchronous and asynchronous drivers
+import psycopg2
+conn = psycopg2.connect(DATABASE_URL)
+
+# DANGEROUS: No SSL verification
+conn = await asyncpg.connect(host="...", sslmode='prefer')
+
+# DANGEROUS: Hardcoded Credentials
+conn = await asyncpg.connect("postgresql://user:password123@host/db")
+
+# DANGEROUS: No timeouts
+conn = await asyncpg.connect(DATABASE_URL) # Can hang indefinitely
+```
+
+### ✅ **Correct Implementation:**
+
+```python
+# SECURE: Connection pool is initialized once for the entire application
+pool = await asyncpg.create_pool(
+    DATABASE_URL,
+    connect_timeout=5,
+    command_timeout=30
+)
+```
+
+-----
+
+## Architecture of a Secure Connection
+
+### 1\. **Asynchronous Connection Pool**
+
+```python
+# Create a single pool at application startup
+_db_pool = await asyncpg.create_pool(dsn=DATABASE_URL, ...)
+
+# Acquire and release connections automatically
+async with _db_pool.acquire() as conn:
+    await conn.execute(...)
+```
+
+**Why:** A pool is essential for efficiency in asynchronous applications. It manages connections, reduces overhead, and is the standard for high-traffic apps.
+
+### 2\. **SSL Runtime Verification**
+
+```python
+# Check at runtime if SSL is active
+ssl_status = await conn.fetchval("SELECT CASE WHEN ssl THEN 'active' ELSE 'INACTIVE' END FROM pg_stat_ssl WHERE pid = pg_backend_pid()")
+
+if ssl_status != 'active':
+    raise RuntimeError("SSL required but not active")
+```
+
+**Why:** DSN parameters can fail; a runtime check is mandatory to prevent security breaches.
+
+### 3\. **Cloud-Optimized Timeouts**
+
+```python
+connect_timeout=5,        # Connection establishment
+keepalives_idle=60,       # Keep-alive for cloud latency
+command_timeout=30        # Query timeout (30s)
+```
+
+**Why:** Cloud connections have higher latency and can be unstable. Timeouts protect against hanging connections and DoS attacks.
+
+### 4\. **Production Error Sanitization**
+
+```python
+if os.getenv('APP_ENV') == 'production':
+    logger.error(f"Database query failed [Code: {e.sqlstate}]")
+else:
+    logger.error(f"Query failed [{e.sqlstate}]: {e}")
+```
+
+**Why:** Prevents information leakage about your database structure to end-users.
+
+-----
+
+## Security Layering
+
+### **Layer 1: Transport Security**
+
+  - **SSL/TLS Encryption** with `sslmode=require` minimum
+  - **Certificate Validation** for sensitive data
+  - **Connection Timeouts** to protect against DoS
+
+### **Layer 2: Authentication**
+
+  - **Environment Variables** for Credentials
+  - **Application Name** for connection tracking
+  - **Cloud Secret Management** (HF Secrets, Railway Vars)
+
+### **Layer 3: Query Security**
+
+  - **Parameterized Queries** exclusively using `$1, $2, ...`
+  - **Statement Timeouts** against long-running queries
+  - **Connection Cleanup** via pool management
+
+### **Layer 4: Monitoring & Logging**
+
+  - **SSL Status Verification** on every connection
+  - **Error Sanitization** in Production
+  - **Cloud Provider Detection** for debugging
+
+-----
+
+## Cloud-Specific Considerations
+
+### **HuggingFace Spaces**
+
+```bash
+# Set as a Secret:
+DATABASE_URL="postgresql://user:pass@host.neon.tech/db?sslmode=require&application_name=hf_space"
+```
+
+### **Railway/Render**
+
+```bash
+# As an Environment Variable:
+DATABASE_URL="postgresql://user:pass@host/db?sslmode=require&connect_timeout=10"
+```
+
+### **Why `sslmode=require` instead of `verify-full`?**
+
+  - ✅ Cloud providers (Neon, Supabase) handle their own CA-Chains
+  - ✅ Avoids certificate issues in ephemeral containers
+  - ✅ Sufficient for managed databases
+  - ❌ `verify-full` requires local certificate files (often not available in cloud)
+
+-----
+
+## 📊 Security Assessment
+
+| Security Aspect | Status | Rationale |
+|-------------------|--------|------------|
+| **SSL Enforcement** | ✅ Excellent | Runtime verification + fail-safe |
+| **Credential Management** | ✅ Excellent | Environment variables only |
+| **SQL Injection Prevention** | ✅ Excellent | Parameterized queries only |
+| **DoS Protection** | ✅ Excellent | Connection + statement timeouts |
+| **Information Leakage** | ✅ Excellent | Production error sanitization |
+| **Connection Pooling** | ✅ Excellent | Implemented with `asyncpg.create_pool` |
+
+**Security Score: 10/10** - Production-ready for cloud environments
+
+-----
+
+## 🔧 Troubleshooting
+
+### **`psycopg.OperationalError: could not connect to server: Connection refused`**
+
+  - **Cause:** The `DATABASE_URL` is incorrect, the database is not running, or network ports are blocked.
+  - **Solution:** Verify your `DATABASE_URL` environment variable and ensure the database service is active and accessible from your application's network.
+
+### **`RuntimeError: SSL connection failed`**
+
+  - **Cause:** Your application connected to the database, but SSL was not active, failing the runtime check. This could be due to a misconfigured `sslmode` in the `DATABASE_URL` or an issue with the cloud provider's setup.
+  - **Solution:** Check your `DATABASE_URL` to ensure `sslmode=require` or a more secure setting is present and correctly enforced.
+
+### **`asyncpg.exceptions.PostgresError: connection terminated...` (Neon.tech)**
+
+  - **Cause:** A specific issue with how Neon.tech handles connections. The connection is terminated after a period of inactivity.
+  - **Solution:** Our code includes a specific check for this state and automatically restarts the pool, but it is important to understand why it happens.
+
+### **`ValueError: DATABASE_URL environment variable must be set`**
+
+  - **Cause:** The `os.getenv("DATABASE_URL")` call returned `None`.
+  - **Solution:** Make sure your `DATABASE_URL` is correctly set in your environment variables or as a secret in your cloud provider's dashboard.
+
+-----
+
+## Quick Start for Cloud Deployment
+
+### 1\. **Environment Setup**
+
+```bash
+# In your cloud provider dashboard:
+DATABASE_URL="postgresql://user:strongpass@host.provider.com/dbname?sslmode=require&connect_timeout=10"
+```
+
+### 2\. **Code Integration**
+
+```python
+from secure_pg_connection import init_db_pool, health_check, execute_secured_query
+
+# At application startup
+await init_db_pool()
+
+# Later, check the connection and run a query
+if (await health_check())['status'] == 'ok':
+    users = await execute_secured_query("SELECT * FROM users WHERE status = $1", 'active', fetch_method='fetch')
+```
+
+### 3\. **Production Checklist**
+
+  - [x] `APP_ENV=production` is set
+  - [x] SSL mode is at least `require`
+  - [x] Database URL is a Secret/EnvVar
+  - [x] All timeouts are configured
+  - [x] Error logging is enabled
+
+-----
+
+## Conclusion
+
+This implementation provides a **Defense-in-Depth** strategy for PostgreSQL connections in cloud environments:
+
+1.  **Secure Defaults** - SSL required, timeouts active
+2.  **Runtime Verification** - SSL status is checked
+3.  **Cloud-Optimized** - Designed for ephemeral containers
+4.  **Production-Ready** - Error sanitization, monitoring
+
+**Result:** Production-grade database connections that remain secure even with network issues, SSL misconfigurations, or attacks.
+

docs/security.py.md

@@ -0,0 +1,196 @@
+# Orchestrating Security Fundamentals
+
+### Why this guide is important
+
+**The Problem:** Many projects fail to implement a cohesive security strategy. Developers often scatter security logic across the application, making it difficult to audit, maintain, and scale. This leads to vulnerabilities like session fixation and mismanaged credentials. Simply using secure libraries is not enough—the way they are used matters.
+
+**The Solution:** This guide introduces a centralized **security orchestration layer** that acts as a single, trusted interface for the entire application. By encapsulating all core security logic, we prevent scattered implementations and ensure that every security-related action adheres to a single, verified standard. This is the final layer of our "defense-in-depth" strategy.
+
+-----
+
+## Common Security Flaws
+
+### ❌ **What NOT to do:**
+
+```python
+# DANGEROUS: Calling low-level security modules directly in app logic
+from fundaments.user_handler import UserHandler
+from fundaments.encryption import Encryption
+from fundaments.access_control import AccessControl
+# ... later in your code:
+user_handler.login(...)
+access_control.has_permission(...)
+
+# DANGEROUS: Unvalidated session data
+if session.get('user_id'):
+    # This is a potential session fixation vulnerability if not regenerated
+    # and validated against request data (IP, User-Agent).
+    ...
+```
+
+### ✅ **Correct Implementation:**
+
+```python
+# SECURE: Orchestration through a single, trusted Security class
+from fundaments.security import Security
+# ... later in your code:
+login_success = await security.user_login(username, password, request_data)
+if login_success:
+    # A successful login automatically means the session has been
+    # validated and regenerated.
+    ...
+```
+
+-----
+
+## Architecture of the Security Manager
+
+### 1\. **The Single Point of Contact**
+
+```python
+# The Security class is a single entry point for all security tasks.
+security = Security(fundament_services)
+```
+
+**Why:** This design principle is crucial. By exposing a single `Security` object, we ensure that all security-related operations (authentication, authorization, encryption) are performed through a single, audited layer. This prevents developers from accidentally bypassing critical security checks by calling a low-level module directly.
+
+### 2\. **Dependency Injection**
+
+```python
+# The Security class receives its dependencies (other fundaments)
+# during initialization.
+def __init__(self, services: Dict[str, Any]):
+    self.user_handler = services.get("user_handler")
+    self.encryption = services.get("encryption")
+    ...
+```
+
+**Why:** Instead of creating its own instances, the `Security` class is "injected" with the already-initialized services. This makes the class highly decoupled, easier to test, and enforces the `main.py` entry point as the single source of truth for service initialization.
+
+### 3\. **Encapsulated Security Logic**
+
+```python
+async def user_login(self, username: str, password: str, request_data: dict) -> bool:
+    # This single method encapsulates multiple security steps:
+    # 1. Credential verification with password hashing.
+    # 2. Brute-force protection (account locking).
+    # 3. Session fixation prevention (session regeneration).
+    # 4. Session hijacking prevention (IP/User-Agent validation).
+    ...
+```
+
+**Why:** The `user_login` method is more than just a simple wrapper. It orchestrates a chain of security checks, guaranteeing that a user is not only authenticated but also that their session is secure against common attacks.
+
+-----
+
+## Security Layering
+
+### **Layer 1: Configuration & Secrets**
+
+  - **Purpose:** Securely manages sensitive credentials.
+  - **Tools:** `config_handler`
+  - **Security:** `.env` file, environment variables, cloud secrets.
+
+### **Layer 2: Data Encryption**
+
+  - **Purpose:** Protects sensitive data at rest.
+  - **Tools:** `encryption`
+  - **Security:** AES-256-GCM, PBKDF2HMAC for key derivation, unique salts.
+
+### **Layer 3: Authentication & Authorization**
+
+  - **Purpose:** Validates user identity and permissions.
+  - **Tools:** `user_handler`, `access_control`
+  - **Security:** Password hashing, rate limiting, RBAC.
+
+### **Layer 4: Orchestration**
+
+  - **Purpose:** The final layer that unifies and orchestrates all other security services.
+  - **Tools:** `security`
+  - **Security:** Single API for all security actions, runtime validation, consolidated logic.
+
+-----
+
+## 📊 Security Assessment
+
+| Security Aspect | Status | Rationale |
+|-------------------|--------|------------|
+| **Logic Centralization** | ✅ Excellent | All core security logic is in one place. |
+| **Session Security** | ✅ Excellent | Handles fixation and hijacking prevention automatically. |
+| **Password Management** | ✅ Excellent | PBKDF2 hashing, brute-force protection, account locking. |
+| **Decoupled Design** | ✅ Excellent | Uses dependency injection; easily testable and maintainable. |
+| **API Simplicity** | ✅ Excellent | One class, one entry point for the application. |
+
+**Security Score: 10/10** - A secure, well-structured security layer for production.
+
+-----
+
+## 🔧 Troubleshooting
+
+### **`RuntimeError: Security manager failed to initialize...`**
+
+  - **Cause:** The `main.py` script failed to initialize one of the core services (`user_handler`, `encryption`, or `access_control`) before it was passed to the `Security` class.
+  - **Solution:** Check the log messages from `main.py`. Look for "failed to initialize" messages from the individual fundament modules. Ensure your `.env` file and database are correctly configured.
+
+### **`ValueError: Invalid data format` or `InvalidTag` (from Encryption)**
+
+  - **Cause:** An attempt was made to decrypt data with the wrong key, nonce, or tag. This could be due to data corruption or a mismatch in the `MASTER_ENCRYPTION_KEY` or `PERSISTENT_ENCRYPTION_SALT`.
+  - **Solution:** Verify that the `MASTER_ENCRYPTION_KEY` and `PERSISTENT_ENCRYPTION_SALT` environment variables are identical in your application and the environment where the data was originally encrypted.
+
+-----
+
+## Quick Start for Application Integration
+
+### 1\. **Access the Service**
+
+The `Security` service is provided by `main.py` via the `fundaments` dictionary.
+
+```python
+from fundaments.security import Security
+
+async def start_application(fundaments: dict):
+    security_service: Security = fundaments["security"]
+    ...
+```
+
+### 2\. **Secure Login and Session**
+
+```python
+request_data = {
+    'ip_address': '192.168.1.1',
+    'user_agent': 'Mozilla/5.0...'
+}
+
+# The single call handles all security aspects of login
+login_successful = await security_service.user_login(
+    "dev@example.com", "my_secret_pass", request_data
+)
+
+if login_successful:
+    print("User is securely logged in!")
+else:
+    print("Login failed, account might be locked.")
+```
+
+### 3\. **Secure Data and Access**
+
+```python
+# Encrypt sensitive data before storing it
+encrypted_credentials = security_service.encrypt_data("SensitiveToken123")
+
+# Check if the user has a specific permission
+if await security_service.check_permission(user_id, "can_manage_users"):
+    print("User is authorized.")
+```
+
+-----
+
+## Conclusion
+
+The `Security` class is the culmination of our fundamental security principles. It elevates your application's security by:
+
+1.  **Providing a Unified API:** Eliminates the risk of scattered security logic.
+2.  **Encapsulating Complexity:** Hides the multi-step security processes from the core application.
+3.  **Enforcing Best Practices:** Guarantees that every security action, like a user login, follows a hardened, production-ready routine.
+
+**Result:** A clean, auditable, and secure application that allows developers to focus on features, confident that the security layer is doing its job.

docs/user_handler.py.md

@@ -0,0 +1,53 @@
+# Secure User Authentication and Session Management
+
+### Overview
+
+This module, `user_handler.py`, is a standalone component for handling user authentication, session management, and security. It provides a secure, yet easy-to-use, system for managing user logins and protecting against common attacks like brute-force attempts and session fixation.
+
+It is designed to be a direct Python equivalent of a user management class you might find in a web application built with a traditional framework, offering similar functionality and a focus on security.
+
+-----
+
+### Core Security Features
+
+  - **Password Hashing:** Passwords are not stored in plain text. The module uses `passlib` with `pbkdf2_sha256` for robust, salted password hashing, making it nearly impossible to retrieve the original password from the database.
+  - **Session Fixation Prevention:** The `login` method regenerates the session ID after a successful authentication, ensuring that an attacker cannot hijack a pre-existing session.
+  - **Brute-Force Protection:** The system tracks failed login attempts. After a configurable number of failures (e.g., 5 attempts), it automatically locks the user's account to prevent further brute-force attacks.
+  - **Session Validation:** Sessions are not just validated by an ID. The module also checks the user's IP address and user agent to ensure the session hasn't been hijacked.
+  - **Data Storage:** A simple `SQLite` database is used as a placeholder. In a production environment, this would be replaced by a more robust and scalable solution like `PostgreSQL`.
+
+-----
+
+### Module Components
+
+1.  **`Database` Class (Placeholder):**
+    A simple wrapper for SQLite to simulate database interactions. This is where you would integrate a proper ORM or a more powerful database driver in a production application.
+
+2.  **`Security` Class:**
+    A static class responsible for core security functions. It handles password hashing and verification using `passlib` and includes a method to simulate session ID regeneration.
+
+3.  **`UserHandler` Class:**
+    The main class for handling user-related logic. It contains methods for:
+
+      - `login(username, password, request_data)`: Verifies user credentials and establishes a secure session.
+      - `logout()`: Terminates the user's session.
+      - `is_logged_in()`: Checks if a user has an active session.
+      - `is_admin()`: Determines if the logged-in user has administrator privileges.
+      - `validate_session()`: Checks if the session is valid based on request details.
+      - `lock_account()`: Manually locks a user's account.
+      - `increment_failed_attempts()`: Increments the failed login counter and locks the account if a threshold is reached.
+
+-----
+
+### Example Usage
+
+The `if __name__ == "__main__":` block at the end of the file provides a complete example of how to use the module:
+
+1.  **Setup:** Initializes the database and creates the necessary tables.
+2.  **User Registration:** Demonstrates how to create a regular user and an admin user with securely hashed passwords.
+3.  **Successful Login:** Shows a successful login attempt, which creates a new session.
+4.  **Logout:** Illustrates how to terminate the session.
+5.  **Brute-Force Protection Test:** Simulates multiple failed login attempts to demonstrate the account-locking mechanism.
+6.  **Account Reset:** Shows how to manually reset failed attempts to re-enable an account.
+
+This module provides a robust and well-documented foundation for building a secure and reliable user authentication system.

example-mcp___.env

@@ -0,0 +1,119 @@
+# ===========================================
+# MCP HUB CONFIGURATION
+# ===========================================
+
+# App-Modus: 'mcp' oder 'app'
+APP_MODE="mcp"
+
+# Transport: 'stdio' (lokal/Claude Desktop) oder 'sse' (HuggingFace/Remote)
+MCP_TRANSPORT="stdio"
+
+# Für SSE/HuggingFace Spaces (PORT muss 7860 sein!)
+PORT="7860"
+HOST="0.0.0.0"
+
+# Optional: Die App-URL für OpenRouter HTTP-Referer
+APP_URL="https://huggingface.co/spaces/DEIN_USERNAME/DEIN_SPACE"
+
+# ===========================================
+# LLM API KEYS (optional - aktiviert Tools)
+# ===========================================
+# Nur konfigurierte Keys aktivieren ihre Tools - kein Key, kein Tool, kein Crash.
+
+#ANTHROPIC_API_KEY="sk-ant-..."
+#OPENROUTER_API_KEY="sk-or-..."
+#HF_TOKEN="hf_..."
+
+# ===========================================
+# SEARCH API KEYS (optional)
+# ===========================================
+
+#BRAVE_API_KEY="BSA..."
+#TAVILY_API_KEY="tvly-..."
+
+# ===========================================
+# MCP HUB CONFIGURATION END 
+# ===========================================
+
+
+# .env.example
+# This file serves as a template for your .env file.
+# Copy this file to a new file named .env and fill in the values.
+# IMPORTANT: Never commit the .env file to version control.
+
+# ===========================================
+# CORE CONFIGURATION
+# ===========================================
+
+# --- Database Connection ---
+# The complete Data Source Name (DSN) for your PostgreSQL database.
+# This works for both local instances and cloud providers like Neon.tech.
+# Example for Neon: postgresql://user:password@host.eu-central-1.aws.neon.tech/neondb?sslmode=require
+# Example for local: postgresql://user:password@localhost:5432/mydb
+# Leave empty or comment out if your app doesn't need database
+DATABASE_URL="your_database_dsn_here"
+
+# --- Application-Level Encryption Keys ---
+# These keys are used by the application itself to encrypt sensitive data
+# before it is written to the database. This provides an additional layer
+# of security for your data.
+# Comment out both lines if your app doesn't need encryption
+# The master key must be a 256-bit key (32 bytes).
+MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
+# The salt is a unique, persistent value used with the master key.
+# It should also be a secure, random string.
+PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
+
+# ===========================================
+# LOGGING CONFIGURATION (Optional)
+# ===========================================
+
+# PyFundaments Debug Mode (true/false)
+PYFUNDAMENTS_DEBUG="true"
+
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_LEVEL="DEBUG"
+
+# Store logs in /tmp directory (cleared on restart)
+LOG_TO_TMP="false"
+
+# Enable public logging (disable for production security)
+ENABLE_PUBLIC_LOGS="true"
+
+
+# ===========================================
+# APP-SPECIFIC CONFIGURATION EXAMPLES
+# ===========================================
+# Uncomment and configure based on your application type
+
+# Discord Bot Setup
+# ==================
+# Get these from Discord Developer Portal
+#PUBLIC_KEY="your-discord-public-key"
+#APPLICATION_ID="your-discord-app-id"
+#BOT_TOKEN="your-bot-token"
+#GUILD_ID="your-guild-id"
+#BOT_VERSION="1.0.1"
+#ADMIN_USER_IDS="user1,user2,user3"
+# ===========================================
+# API Server CONFIGURATION EXAMPLES
+# ===========================================
+#Flask server 
+#PORT="7860"
+
+# ML/LLM Setup
+# =============
+#MODEL_PATH="/path/to/your/model"
+#MAX_TOKENS="2048"
+#TEMPERATURE="0.7"
+
+# Web Server Setup
+# ================
+#PORT="8000"
+#HOST="0.0.0.0"
+#DEBUG_MODE="false"
+
+# API Keys
+# ========
+#OPENAI_API_KEY="your-openai-key"
+#ANTHROPIC_API_KEY="your-anthropic-key"

example.Dockerfile

@@ -0,0 +1,28 @@
+# Use an official Python runtime as a parent image.
+# We choose a slim version to keep the image size small.
+FROM python:3.10-slim
+
+# Set the working directory in the container.
+# All subsequent commands will be executed in this directory.
+WORKDIR /app
+
+# Copy the requirements file into the container.
+# We do this first to leverage Docker's layer caching.
+# If requirements.txt doesn't change, this step is skipped.
+COPY requirements.txt ./
+
+# Install any needed packages specified in requirements.txt.
+# The --no-cache-dir flag helps to keep the image smaller.
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application code into the working directory.
+COPY . .
+
+# Expose a port if your application is a web server.
+# For example, if your application runs on port 8000.
+# EXPOSE 8000
+
+# Define the command to run your application.
+# This command will be executed when the container starts.
+# We use main.py as the entry point, as per our architecture.
+CMD ["python", "main.py"]

fundaments/__init__.py

@@ -0,0 +1 @@
+

fundaments/access_control.py

@@ -0,0 +1,240 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# access_control.py
+# This is the standalone module for access control.
+# It is intended to be imported by main.py or app.py.
+
+import sys
+from typing import Optional, List, Dict, Any
+
+# Your foundational PostgreSQL module is imported here.
+# IMPORTANT: Ensure 'postgresql.py' is in the same directory or accessible
+# via the Python path.
+from fundaments import postgresql as db
+# local db use: db.execute_secured_query(), db.init_db_pool(), etc. but this fundaments are optimized for clouds
+
+
+# If asyncpg is not installed, exit the script gracefully.
+try:
+    import asyncpg
+except ImportError:
+    print("Error: The 'asyncpg' library is required. Please install it with 'pip install asyncpg'.")
+    sys.exit(1)
+
+
+class AccessControl:
+    """
+    Asynchronous class for managing access control.
+    It builds directly on the functions of your secure database module.
+    This is the layer that uses the foundation without modifying it.
+
+    How to extend this class:
+    To add new functionality, simply create a new asynchronous method
+    within this class. This method can call the `db.execute_secured_query`
+    function to interact with the database. For example:
+
+    async def get_user_last_login(self):
+        sql = "SELECT last_login FROM users WHERE id = $1"
+        result = await db.execute_secured_query(sql, self.user_id, fetch_method='fetchrow')
+        return result['last_login'] if result else None
+    """
+    def __init__(self, user_id: Optional[int] = None):
+        self.user_id = user_id
+
+    async def has_permission(self, permission_name: str) -> bool:
+        """
+        Checks if the user has a specific permission.
+        Uses the secure execute_secured_query function from the foundation.
+        """
+        if self.user_id is None:
+            return False
+
+        # SQL Query Explanation:
+        # This query counts the number of rows where the user (user_id)
+        # has a role (user_role_assignments) that is linked to a permission
+        # (role_permissions) which has the specified name (user_permissions.name).
+        # If the count is > 0, the user has the permission.
+        sql = """
+            SELECT COUNT(*) AS count
+            FROM user_role_assignments ura
+            JOIN role_permissions rp ON ura.role_id = rp.role_id
+            JOIN user_permissions up ON rp.permission_id = up.id
+            WHERE ura.user_id = $1 AND up.name = $2
+        """
+        try:
+            result = await db.execute_secured_query(
+                sql,
+                self.user_id,
+                permission_name,
+                fetch_method='fetchrow'
+            )
+            return result['count'] > 0
+        except Exception as e:
+            # Error handling is managed by your postgresql module.
+            # We just re-raise the exception here to propagate it.
+            raise Exception(f'Failed to check permission: {e}')
+
+    async def get_user_permissions(self) -> List[Dict[str, Any]]:
+        """Returns all permissions for a user."""
+        if self.user_id is None:
+            return []
+
+        # SQL Query Explanation:
+        # This query retrieves all distinct permission names and descriptions
+        # associated with the user's roles. `DISTINCT` ensures each permission
+        # is listed only once.
+        sql = """
+            SELECT DISTINCT up.name, up.description
+            FROM user_role_assignments ura
+            JOIN role_permissions rp ON ura.role_id = rp.role_id
+            JOIN user_permissions up ON rp.permission_id = up.id
+            WHERE ura.user_id = $1
+            ORDER BY up.name
+        """
+        try:
+            return await db.execute_secured_query(sql, self.user_id)
+        except Exception as e:
+            raise Exception(f'Failed to get user permissions: {e}')
+
+    async def get_user_roles(self) -> List[Dict[str, Any]]:
+        """Returns all roles for a user."""
+        if self.user_id is None:
+            return []
+
+        # SQL Query Explanation:
+        # This query selects the details (id, name, description) of the roles
+        # that are assigned to the specified user (user_id) in the
+        # `user_role_assignments` table.
+        sql = """
+            SELECT r.id, r.name, r.description
+            FROM user_role_assignments ura
+            JOIN user_roles r ON ura.role_id = r.id
+            WHERE ura.user_id = $1
+            ORDER BY r.name
+        """
+        try:
+            return await db.execute_secured_query(sql, self.user_id)
+        except Exception as e:
+            raise Exception(f'Failed to get user roles: {e}')
+
+    async def assign_role(self, role_id: int) -> None:
+        """Assigns a role to a user."""
+        if self.user_id is None:
+            raise Exception('No user specified')
+
+        # SQL Query Explanation:
+        # Inserts a new row into the `user_role_assignments` table to create
+        # the relationship between a user and a role.
+        sql = "INSERT INTO user_role_assignments (user_id, role_id) VALUES ($1, $2)"
+        try:
+            await db.execute_secured_query(
+                sql,
+                self.user_id,
+                role_id,
+                fetch_method='execute'
+            )
+        except Exception as e:
+            raise Exception(f'Failed to assign role: {e}')
+
+    async def remove_role(self, role_id: int) -> None:
+        """Removes a role from a user."""
+        if self.user_id is None:
+            raise Exception('No user specified')
+
+        # SQL Query Explanation:
+        # Deletes the row from the `user_role_assignments` table that matches
+        # the specified user ($1) and role ($2).
+        sql = "DELETE FROM user_role_assignments WHERE user_id = $1 AND role_id = $2"
+        try:
+            await db.execute_secured_query(
+                sql,
+                self.user_id,
+                role_id,
+                fetch_method='execute'
+            )
+        except Exception as e:
+            raise Exception(f'Failed to remove role: {e}')
+
+    async def get_all_roles(self) -> List[Dict[str, Any]]:
+        """Returns all available roles."""
+        # SQL Query Explanation:
+        # Selects all roles from the `user_roles` table.
+        sql = "SELECT id, name, description FROM user_roles ORDER BY name"
+        try:
+            return await db.execute_secured_query(sql)
+        except Exception as e:
+            raise Exception(f'Failed to get roles: {e}')
+
+    async def get_all_permissions(self) -> List[Dict[str, Any]]:
+        """Returns all available permissions."""
+        # SQL Query Explanation:
+        # Selects all permissions from the `user_permissions` table.
+        sql = "SELECT id, name, description FROM user_permissions ORDER BY name"
+        try:
+            return await db.execute_secured_query(sql)
+        except Exception as e:
+            raise Exception(f'Failed to get permissions: {e}')
+
+    async def create_role(self, name: str, description: str) -> int:
+        """Creates a new role."""
+        # SQL Query Explanation:
+        # Inserts a new role into the `user_roles` table and returns the
+        # automatically generated ID of the new role (`RETURNING id`).
+        sql = "INSERT INTO user_roles (name, description) VALUES ($1, $2) RETURNING id"
+        try:
+            result = await db.execute_secured_query(
+                sql,
+                name,
+                description,
+                fetch_method='fetchrow'
+            )
+            return result['id']
+        except Exception as e:
+            raise Exception(f'Failed to create role: {e}')
+
+    async def update_role_permissions(self, role_id: int, permission_ids: List[int]) -> None:
+        """Updates the permissions for a role."""
+        # IMPORTANT: Since your module does not handle transactions across multiple
+        # queries, we perform these actions sequentially. Query-level security
+        # is guaranteed by your module.
+        try:
+            # SQL Query Explanation:
+            # Deletes all existing permissions for the given role.
+            sql_delete = "DELETE FROM role_permissions WHERE role_id = $1"
+            await db.execute_secured_query(sql_delete, role_id, fetch_method='execute')
+
+            # SQL Query Explanation:
+            # Inserts a new row for each permission_id passed into the
+            # `role_permissions` table.
+            if permission_ids:
+                sql_insert = "INSERT INTO role_permissions (role_id, permission_id) VALUES ($1, $2)"
+                for permission_id in permission_ids:
+                    await db.execute_secured_query(
+                        sql_insert,
+                        role_id,
+                        permission_id,
+                        fetch_method='execute'
+                    )
+        except Exception as e:
+            # If an error occurs, the underlying foundation will log the issue.
+            # We re-raise the error here.
+            raise Exception(f'Failed to update role permissions: {e}')
+
+    async def get_role_permissions(self, role_id: int) -> List[Dict[str, Any]]:
+        """Returns all permissions for a role."""
+        # SQL Query Explanation:
+        # Selects the details (id, name, description) of all permissions
+        # linked to the specified role.
+        sql = """
+            SELECT p.id, p.name, p.description
+            FROM role_permissions rp
+            JOIN user_permissions p ON rp.permission_id = p.id
+            WHERE rp.role_id = $1
+            ORDER BY p.name
+        """
+        try:
+            return await db.execute_secured_query(sql, role_id)
+        except Exception as e:
+            raise Exception(f'Failed to get role permissions: {e}')

fundaments/config_handler.py

@@ -0,0 +1,115 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/config_handler.py
+# This module loads environment variables without validation.
+# Validation is handled by main.py based on required services.
+import os
+import sys
+from dotenv import load_dotenv
+from typing import Optional, Dict, Any
+
+class ConfigHandler:
+    """
+    A universal configuration loader that reads all environment variables
+    without imposing requirements. This ensures the config handler never
+    needs updates regardless of what services are used.
+    
+    Validation is delegated to main.py which knows what services are needed.
+    """
+    
+    def __init__(self):
+        """
+        Loads all environment variables from .env file and system environment.
+        No validation is performed - that's main.py's responsibility.
+        """
+        load_dotenv()
+        self.config = {}
+        self.load_all_config()
+    
+    def load_all_config(self):
+        """
+        Loads all available environment variables into the config dictionary.
+        No validation - main.py decides what's required based on enabled services.
+        """
+        # Load all environment variables
+        for key, value in os.environ.items():
+            if value:  # Only store non-empty values
+                self.config[key] = value
+    
+    def get(self, key: str) -> Optional[str]:
+        """
+        Retrieves a configuration value by key.
+        Returns None if the key doesn't exist.
+        
+        Args:
+            key: The environment variable name
+            
+        Returns:
+            The value as string or None if not found
+        """
+        return self.config.get(key)
+    
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        """
+        Retrieves a boolean configuration value.
+        Recognizes: true, false, 1, 0, yes, no (case insensitive)
+        
+        Args:
+            key: The environment variable name
+            default: Default value if key not found
+            
+        Returns:
+            Boolean value
+        """
+        value = self.get(key)
+        if value is None:
+            return default
+        
+        return value.lower() in ('true', '1', 'yes', 'on')
+    
+    def get_int(self, key: str, default: int = 0) -> int:
+        """
+        Retrieves an integer configuration value.
+        
+        Args:
+            key: The environment variable name
+            default: Default value if key not found or invalid
+            
+        Returns:
+            Integer value
+        """
+        value = self.get(key)
+        if value is None:
+            return default
+        
+        try:
+            return int(value)
+        except ValueError:
+            return default
+    
+    def has(self, key: str) -> bool:
+        """
+        Checks if a configuration key exists and has a non-empty value.
+        
+        Args:
+            key: The environment variable name
+            
+        Returns:
+            True if key exists and has value, False otherwise
+        """
+        return key in self.config and bool(self.config[key])
+    
+    def get_all(self) -> Dict[str, str]:
+        """
+        Returns all loaded configuration as a dictionary.
+        Useful for debugging or passing to other services.
+        
+        Returns:
+            Dictionary of all loaded environment variables
+        """
+        return self.config.copy()
+
+# Global singleton instance
+config_service = ConfigHandler()

fundaments/debug.py

@@ -0,0 +1,91 @@
+import os
+import sys
+import importlib.util
+import datetime
+import logging
+from logging.handlers import RotatingFileHandler
+
+class PyFundamentsDebug:
+    """
+    Debug-Klasse für PyFundaments.
+    Liest ENV-Variablen und konfiguriert Logging.
+    Gibt Startup-Infos aus, wenn PYFUNDAMENTS_DEBUG=true.
+    """
+
+    def __init__(self):
+        # Debug aktivieren mit ENV VAR (default: False)
+        self.enabled = os.getenv("PYFUNDAMENTS_DEBUG", "false").lower() == "true"
+
+        # Log-Level aus ENV lesen, default INFO
+        log_level_str = os.getenv("LOG_LEVEL", "INFO").upper()
+        self.log_level = getattr(logging, log_level_str, logging.INFO)
+
+        # Logs in /tmp oder stdout? (default False)
+        self.log_to_tmp = os.getenv("LOG_TO_TMP", "false").lower() == "true"
+
+        # Öffentliches Logging an/aus (default True)
+        self.enable_public_logs = os.getenv("ENABLE_PUBLIC_LOGS", "true").lower() == "true"
+
+        # Logger Setup
+        self.logger = logging.getLogger('pyfundaments_debug')
+        self._setup_logger()
+
+    def _setup_logger(self):
+        if not self.enable_public_logs:
+            # Nur kritische Fehler im Log, wenn deaktiviert
+            logging.basicConfig(level=logging.CRITICAL)
+            return
+
+        handlers = []
+        if self.log_to_tmp:
+            log_file = '/tmp/pyfundaments_debug.log'
+            file_handler = RotatingFileHandler(log_file, maxBytes=1024*1024, backupCount=3)
+            handlers.append(file_handler)
+        handlers.append(logging.StreamHandler(sys.stdout))
+
+        logging.basicConfig(
+            level=self.log_level,
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            handlers=handlers
+        )
+
+    def run(self):
+        if not self.enabled:
+            return
+
+        self.logger.info(f"==== PYFUNDAMENTS DEBUG STARTUP ({datetime.datetime.now()}) ====")
+        self.logger.info(f"Python version: {sys.version}")
+        self.logger.info(f"CWD: {os.getcwd()}")
+        self.logger.info(f"sys.path: {sys.path}")
+
+        fund_dir = "fundaments"
+        self.logger.info(f"fundaments exists: {os.path.isdir(fund_dir)}")
+
+        required_files = [
+            "__init__.py",
+            "access_control.py",
+            "postgresql.py",
+            "config_handler.py",
+            "security.py",
+            "user_handler.py",
+            "encryption.py"
+        ]
+
+        for file in required_files:
+            path = os.path.join(fund_dir, file)
+            exists = os.path.isfile(path)
+            readable = os.access(path, os.R_OK)
+            self.logger.info(f"{file} exists: {exists} | readable: {readable}")
+
+        if os.path.isdir(fund_dir):
+            self.logger.info(f"Listing fundaments contents: {os.listdir(fund_dir)}")
+        else:
+            self.logger.warning("fundaments folder not found.")
+
+        spec = importlib.util.find_spec("fundaments")
+        self.logger.info(f"fundaments importable: {spec is not None}")
+
+        conflicts = [mod for mod in sys.modules if mod == "fundaments"]
+        self.logger.info(f"Name conflict in sys.modules: {conflicts}")
+
+        self.logger.info("==== PYFUNDAMENTS DEBUG END ====")

fundaments/encryption.py

@@ -0,0 +1,233 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# encryption.py
+# A secure and robust encryption module using the cryptography library.
+# This module is designed as a core component for a CMS architecture.
+
+import os
+import sys
+import base64
+import binascii
+from typing import Dict, Union, Optional
+
+# IMPORTANT: The cryptography library is required for this module.
+# Please install it with 'pip install cryptography'.
+try:
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+    from cryptography.exceptions import InvalidTag
+except ImportError:
+    print("Error: The 'cryptography' library is required. Please install it with 'pip install cryptography'.")
+    sys.exit(1)
+
+class Encryption:
+    """
+    A class for symmetric encryption and decryption using AES-256-GCM.
+    It securely handles both string data and file streaming.
+    
+    This version is designed as a reusable core component for a larger application.
+    """
+    CIPHER_NAME = 'AES-256-GCM'
+    KEY_LENGTH = 32 # 256 bits
+    NONCE_LENGTH = 12 # 96 bits, standard for GCM
+    TAG_LENGTH = 16 # 128 bits
+    SALT_LENGTH = 16
+
+    @staticmethod
+    def generate_salt() -> str:
+        """
+        Generates a new, cryptographically secure random salt for key derivation.
+        This should be done once during application setup and stored securely.
+        
+        Returns:
+            A hex-encoded string of the salt.
+        """
+        return binascii.hexlify(os.urandom(Encryption.SALT_LENGTH)).decode('utf-8')
+
+    def __init__(self, master_key: str, salt: str):
+        """
+        Initializes the encryption class by deriving a secure key from a master key.
+        The provided master_key and a persistent salt are used for key derivation.
+        
+        Args:
+            master_key: The string to be used as the master key.
+            salt: The hex-encoded string of the persistent salt.
+        
+        Raises:
+            ValueError: If the provided salt is not a valid hex string or has an incorrect length.
+        """
+        try:
+            salt_bytes = binascii.unhexlify(salt)
+        except binascii.Error:
+            raise ValueError("Invalid salt format. Must be a hex-encoded string.")
+        
+        if len(salt_bytes) != self.SALT_LENGTH:
+            raise ValueError(f"Invalid salt length. Expected {self.SALT_LENGTH} bytes, got {len(salt_bytes)}.")
+            
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=self.KEY_LENGTH,
+            salt=salt_bytes,
+            iterations=480000, # Recommended value for 2023+
+            backend=default_backend()
+        )
+        self.key = kdf.derive(master_key.encode('utf-8'))
+
+    def encrypt(self, data: str) -> Dict[str, str]:
+        """
+        Encrypts a string using AES-256-GCM.
+        
+        Args:
+            data: The string to be encrypted.
+
+        Returns:
+            A dictionary containing the base64-encoded ciphertext, hex-encoded IV/nonce,
+            and hex-encoded authentication tag.
+        """
+        nonce = os.urandom(self.NONCE_LENGTH)
+        
+        aesgcm = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce),
+            backend=default_backend()
+        ).encryptor()
+        
+        encrypted_data = aesgcm.update(data.encode('utf-8')) + aesgcm.finalize()
+        tag = aesgcm.tag
+
+        return {
+            'data': base64.b64encode(encrypted_data).decode('utf-8'),
+            'nonce': binascii.hexlify(nonce).decode('utf-8'),
+            'tag': binascii.hexlify(tag).decode('utf-8')
+        }
+
+    def decrypt(self, encrypted_data: str, nonce: str, tag: str) -> str:
+        """
+        Decrypts an AES-256-GCM encrypted string.
+        
+        Args:
+            encrypted_data: The base64-encoded ciphertext.
+            nonce: The hex-encoded nonce/IV.
+            tag: The hex-encoded authentication tag.
+            
+        Returns:
+            The decrypted plaintext string.
+        
+        Raises:
+            ValueError: If nonce, tag, or data format is invalid.
+            InvalidTag: If the authentication tag fails validation.
+        """
+        try:
+            nonce_bytes = binascii.unhexlify(nonce)
+            tag_bytes = binascii.unhexlify(tag)
+            cipher_bytes = base64.b64decode(encrypted_data)
+        except (binascii.Error, ValueError) as e:
+            raise ValueError(f'Invalid data format: {e}')
+        
+        aesgcm = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce_bytes, tag_bytes),
+            backend=default_backend()
+        ).decryptor()
+        
+        try:
+            decrypted_data = aesgcm.update(cipher_bytes) + aesgcm.finalize()
+            return decrypted_data.decode('utf-8')
+        except InvalidTag:
+            raise InvalidTag("Authentication tag validation failed. Data may be corrupted or key is incorrect.")
+
+    def encrypt_file(self, source_path: str, destination_path: str) -> Dict[str, str]:
+        """
+        Encrypts a file using AES-256-GCM with a streaming approach.
+        
+        Args:
+            source_path: Path to the file to be encrypted.
+            destination_path: Path where the encrypted file will be saved.
+            
+        Returns:
+            A dictionary containing the hex-encoded IV/nonce and authentication tag.
+        """
+        nonce = os.urandom(self.NONCE_LENGTH)
+        
+        encryptor = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce),
+            backend=default_backend()
+        ).encryptor()
+        
+        try:
+            with open(source_path, 'rb') as fp_source, open(destination_path, 'wb') as fp_dest:
+                fp_dest.write(nonce)
+                
+                chunk_size = 8192
+                while True:
+                    chunk = fp_source.read(chunk_size)
+                    if not chunk:
+                        break
+                    encrypted_chunk = encryptor.update(chunk)
+                    fp_dest.write(encrypted_chunk)
+                
+                encryptor.finalize()
+                tag = encryptor.tag
+                fp_dest.write(tag)
+            
+            return {
+                'nonce': binascii.hexlify(nonce).decode('utf-8'),
+                'tag': binascii.hexlify(tag).decode('utf-8')
+            }
+        except FileNotFoundError as e:
+            raise ValueError(f"File not found: {e.filename}") from e
+        except Exception as e:
+            raise IOError(f"File encryption failed: {e}") from e
+
+    def decrypt_file(self, source_path: str, destination_path: str) -> None:
+        """
+        Decrypts an AES-256-GCM encrypted file.
+        
+        Args:
+            source_path: Path to the encrypted file.
+            destination_path: Path where the decrypted file will be saved.
+        """
+        try:
+            with open(source_path, 'rb') as fp_source, open(destination_path, 'wb') as fp_dest:
+                nonce = fp_source.read(self.NONCE_LENGTH)
+                if len(nonce) != self.NONCE_LENGTH:
+                    raise ValueError("Incomplete or invalid file format: Nonce is missing.")
+                    
+                fp_source.seek(-self.TAG_LENGTH, os.SEEK_END)
+                tag = fp_source.read(self.TAG_LENGTH)
+                if len(tag) != self.TAG_LENGTH:
+                    raise ValueError("Incomplete or invalid file format: Tag is missing.")
+                    
+                fp_source.seek(self.NONCE_LENGTH, os.SEEK_SET) # Rewind to the start of the ciphertext
+                
+                decryptor = Cipher(
+                    algorithms.AES(self.key),
+                    modes.GCM(nonce, tag),
+                    backend=default_backend()
+                ).decryptor()
+                
+                chunk_size = 8192
+                encrypted_file_size = os.path.getsize(source_path) - self.NONCE_LENGTH - self.TAG_LENGTH
+                
+                bytes_read = 0
+                while bytes_read < encrypted_file_size:
+                    chunk_to_read = min(chunk_size, encrypted_file_size - bytes_read)
+                    chunk = fp_source.read(chunk_to_read)
+                    
+                    decrypted_chunk = decryptor.update(chunk)
+                    fp_dest.write(decrypted_chunk)
+                    bytes_read += len(chunk)
+                
+                decryptor.finalize()
+                
+        except InvalidTag as e:
+            raise IOError(f"File decryption failed. The authentication tag is invalid, suggesting the file was corrupted or tampered with. Error: {e}") from e
+        except FileNotFoundError as e:
+            raise ValueError(f"File not found: {e.filename}") from e
+        except Exception as e:
+            raise IOError(f"File decryption failed due to an unexpected error: {e}") from e

fundaments/postgresql.py

@@ -0,0 +1,179 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/postgresql.py
+import os
+import logging
+import asyncpg
+import ssl
+from urllib.parse import urlparse, urlencode, parse_qs, urlunparse
+from typing import Optional
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+_db_pool: Optional[asyncpg.Pool] = None
+
+def enforce_cloud_security(dsn_url: str) -> str:
+    """
+    Enforces security settings for cloud environments.
+    - Ensures SSL mode is at least 'require'
+    - Removes unsupported options for cloud providers (e.g. statement_timeout for Neon)
+    - Sets connect_timeout and keepalives_idle defaults
+    """
+    parsed = urlparse(dsn_url)
+    query_params = parse_qs(parsed.query)
+
+    # Enforce SSL (at least 'require')
+    sslmode = query_params.get('sslmode', ['prefer'])[0].lower()
+    if sslmode not in ['require', 'verify-ca', 'verify-full']:
+        query_params['sslmode'] = ['require']
+
+    # Set timeouts and keep-alives if not present
+    if 'connect_timeout' not in query_params:
+        query_params['connect_timeout'] = ['5']
+    if 'keepalives_idle' not in query_params:
+        query_params['keepalives_idle'] = ['60']
+
+    # Remove statement_timeout option for Neon
+    if 'neon.tech' in parsed.netloc:
+        if 'options' in query_params:
+            options_clean = []
+            for opt in query_params['options']:
+                if 'statement_timeout' not in opt:
+                    options_clean.append(opt)
+            if options_clean:
+                query_params['options'] = options_clean
+            else:
+                query_params.pop('options')
+            logger.info("Removed unsupported 'statement_timeout' option for Neon.tech.")
+        # Optionally, set a supported option for Neon (usually none)
+    
+    # TODO: Extend here for further providers...
+
+    # Rebuild DSN
+    new_query = urlencode(query_params, doseq=True)
+    new_url = parsed._replace(query=new_query)
+    return urlunparse(new_url)
+
+def mask_dsn(dsn_url: str) -> str:
+    """
+    Masks username/password from DSN so they are not exposed in logs.
+    """
+    parsed = urlparse(dsn_url)
+    safe_netloc = f"{parsed.hostname}:{parsed.port}" if parsed.port else parsed.hostname
+    return parsed._replace(netloc=safe_netloc).geturl()
+
+async def ssl_runtime_check(conn: asyncpg.Connection):
+    """
+    Performs a cloud-aware SSL runtime check on an active connection.
+    For Neon/Supabase (or unknown cloud) only log a warning if pg_stat_ssl is unavailable.
+    """
+    dsn = os.getenv("DATABASE_URL", "")
+    try:
+        ssl_status = await conn.fetchval("""
+            SELECT CASE WHEN ssl THEN 'active' ELSE 'INACTIVE' END
+            FROM pg_stat_ssl WHERE pid = pg_backend_pid()
+        """)
+        if ssl_status != 'active':
+            logger.critical("CRITICAL ERROR: SSL connection is not active!")
+            raise RuntimeError("SSL connection failed")
+        logger.info("SSL connection is active.")
+    except Exception as e:
+        # Cloud: If pg_stat_ssl is not available, don't fail hard.
+        if "neon.tech" in dsn or "supabase" in dsn:
+            logger.warning("SSL check via pg_stat_ssl not possible (cloud restriction). Assuming SSL is active due to sslmode=require.")
+        else:
+            logger.critical(f"SSL runtime check failed: {e}")
+            raise
+
+async def init_db_pool(dsn_url: Optional[str] = None) -> Optional[asyncpg.Pool]:
+    """Initializes the asynchronous database connection pool."""
+    global _db_pool
+    if _db_pool:
+        return _db_pool
+
+    if not dsn_url:
+        dsn_url = os.getenv("DATABASE_URL") or os.getenv("PG_DSN")
+        if not dsn_url:
+            logger.warning("No DATABASE_URL or PG_DSN found. Skipping DB pool initialization.")
+            return None
+
+    # Enforce cloud security and remove unsupported options
+    secured_dsn = enforce_cloud_security(dsn_url)
+
+    # ⚠ WARNING: This logs full credentials — keep only for secure DEV debugging
+    logger.debug(f"[DEV ONLY] Full DSN used for DB connection: {secured_dsn}")
+
+    # Always log a masked DSN for production safety
+    logger.info(f"DSN used for DB connection (masked): {mask_dsn(secured_dsn)}")
+
+    ssl_context = None
+    if 'sslmode=verify-full' in secured_dsn:
+        ssl_context = ssl.create_default_context()
+
+    try:
+        logger.info("Initializing secure database pool...")
+        _db_pool = await asyncpg.create_pool(
+            dsn=secured_dsn,
+            min_size=1,
+            max_size=10,
+            timeout=5,
+            command_timeout=30,
+            ssl=ssl_context
+        )
+        # Post-init checks
+        async with _db_pool.acquire() as conn:
+            await ssl_runtime_check(conn)
+        logger.info("Secure database pool initialized.")
+        return _db_pool
+    except Exception as e:
+        logger.critical(f"Pool initialization failed: {str(e)}")
+        _db_pool = None
+        return None  # Fallback: allow app to run without DB
+
+async def close_db_pool():
+    """Gracefully closes the database connection pool."""
+    global _db_pool
+    if _db_pool:
+        await _db_pool.close()
+        _db_pool = None
+        logger.info("Database pool closed successfully.")
+
+async def execute_secured_query(query: str, *params, fetch_method='fetch'):
+    """
+    Executes a parameterized query with integrated security checks.
+    """
+    global _db_pool
+    if not _db_pool:
+        raise RuntimeError("Database pool not initialized")
+
+    try:
+        async with _db_pool.acquire() as conn:
+            if fetch_method == 'fetch':
+                return await conn.fetch(query, *params)
+            elif fetch_method == 'fetchrow':
+                return await conn.fetchrow(query, *params)
+            elif fetch_method == 'execute':
+                return await conn.execute(query, *params)
+            else:
+                raise ValueError("Invalid fetch_method")
+    except asyncpg.PostgresError as e:
+        error_type = "Security violation" if getattr(e, 'sqlstate', None) == '42501' else "Database error"
+        
+        if os.getenv('APP_ENV') == 'production':
+            logger.error(f"{error_type} [Code: {getattr(e, 'sqlstate', '?')}]")
+        else:
+            logger.error(f"{error_type}: {e}")
+        
+        # Neon: Reconnect if connection terminated (optional)
+        if getattr(e, 'sqlstate', None) == '08006' and 'neon.tech' in (os.getenv("DATABASE_URL") or ''):
+            logger.warning("Neon.tech connection terminated. Restarting pool...")
+            await close_db_pool()
+            await init_db_pool(os.getenv("DATABASE_URL"))
+        
+        raise

fundaments/security.py

@@ -0,0 +1,79 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/security.py
+# A central security manager that orchestrates core security functions.
+# This class acts as a single, trusted interface for the application to
+# interact with all underlying security fundamentals.
+
+import logging
+from typing import Dict, Any, Optional
+
+# VORHER: Diese direkten Imports sind überflüssig,
+# da die Instanzen der Klassen über den 'services'-Dictionary
+# im __init__-Konstruktor übergeben werden.
+# Sie sind auch nicht für die Typisierung notwendig,
+# da wir 'Optional[ClassName]' verwenden, was ausreicht.
+# from fundaments.encryption import Encryption
+# from fundaments.access_control import AccessControl
+# from fundaments.postgresql import execute_secured_query
+# from fundaments.user_handler import UserHandler
+
+logger = logging.getLogger('security')
+
+class Security:
+    def __init__(self, services: Dict[str, Any]):
+        # VORHER: Hier werden die Instanzen aus dem übergebenen Dictionary entnommen.
+        self.user_handler: Optional[UserHandler] = services.get("user_handler")
+        self.access_control: Optional[AccessControl] = services.get("access_control")
+        self.encryption: Optional[Encryption] = services.get("encryption")
+
+        # VORHER: Bei fehlenden kritischen Diensten wird die Anwendung sofort gestoppt.
+        # Dies ist eine strikte, aber unflexible Regel.
+        if not self.user_handler:
+            logger.critical("Security manager init failed: UserHandler service missing.")
+            raise RuntimeError("UserHandler service missing")
+
+        if not self.access_control:
+            logger.critical("Security manager init failed: AccessControl service missing.")
+            raise RuntimeError("AccessControl service missing")
+
+        # VORHER: Bei einem nicht-kritischen Dienst wird nur eine Warnung ausgegeben.
+        # Die Anwendung läuft weiter.
+        if not self.encryption:
+            logger.warning("Encryption service not available. Encryption/decryption features will be disabled.")
+
+        logger.info("Security manager initialized and ready.")
+
+    # VORHER: Hier fehlt die Überprüfung, ob 'self.user_handler' None ist.
+    # Wenn der Dienst nicht initialisiert wurde (wie oben), würde dies einen AttributeError auslösen.
+    async def user_login(self, username: str, password: str, request_data: dict) -> bool:
+        logger.info(f"Attempting login for user: {username}")
+        if await self.user_handler.login(username, password, request_data):
+            return await self.user_handler.validate_session(request_data)
+        return False
+
+    # VORHER: Hier fehlt die Überprüfung, ob 'self.access_control' None ist.
+    async def check_permission(self, user_id: int, permission_name: str) -> bool:
+        logger.debug(f"Checking permission '{permission_name}' for user ID {user_id}")
+        return await self.access_control.has_permission(user_id, permission_name)
+
+    # VORHER: Hier wird geprüft, ob 'self.encryption' None ist, was korrekt ist.
+    def encrypt_data(self, data: str) -> Dict[str, str]:
+        if not self.encryption:
+            raise RuntimeError("Encryption service not initialized.")
+        logger.debug("Encrypting data.")
+        return self.encryption.encrypt(data)
+
+    # VORHER: Hier wird geprüft, ob 'self.encryption' None ist, was korrekt ist.
+    def decrypt_data(self, encrypted_data: str, nonce: str, tag: str) -> Optional[str]:
+        if not self.encryption:
+            logger.error("Encryption service not initialized. Cannot decrypt data.")
+            return None
+        logger.debug("Decrypting data.")
+        try:
+            return self.encryption.decrypt(encrypted_data, nonce, tag)
+        except Exception as e:
+            logger.error(f"Decryption failed: {e}")
+            return None

fundaments/user_handler.py

@@ -0,0 +1,342 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# user_handler.py
+# A Python module for handling user authentication and session management.
+
+import sqlite3
+import uuid
+from datetime import datetime, timedelta
+from passlib.hash import pbkdf2_sha256
+import os
+
+class Database:
+    """
+    A simple placeholder class to simulate a database connection.
+    In a real application, you would use a proper ORM like SQLAlchemy
+    or a specific database driver.
+    """
+    def __init__(self, db_name="cms_database.db"):
+        self.conn = sqlite3.connect(db_name)
+        self.cursor = self.conn.cursor()
+
+    def execute(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        self.conn.commit()
+
+    def fetchone(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        return self.cursor.fetchone()
+
+    def fetchall(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        return self.cursor.fetchall()
+
+    def close(self):
+        self.conn.close()
+
+    def setup_tables(self):
+        """
+        Creates the necessary tables for users and sessions.
+        """
+        self.execute("""
+            CREATE TABLE IF NOT EXISTS users (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                username TEXT UNIQUE NOT NULL,
+                password TEXT NOT NULL,
+                is_admin INTEGER NOT NULL DEFAULT 0,
+                account_locked INTEGER NOT NULL DEFAULT 0,
+                failed_login_attempts INTEGER NOT NULL DEFAULT 0
+            )
+        """)
+        self.execute("""
+            CREATE TABLE IF NOT EXISTS sessions (
+                id TEXT PRIMARY KEY,
+                user_id INTEGER NOT NULL,
+                ip_address TEXT,
+                user_agent TEXT,
+                last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+            )
+        """)
+
+class Security:
+    """
+    Handles secure password hashing and session regeneration.
+    Using passlib for robust and secure password management.
+    """
+    @staticmethod
+    def hash_password(password: str) -> str:
+        """Hashes a password using PBKDF2 with SHA256."""
+        return pbkdf2_sha256.hash(password)
+
+    @staticmethod
+    def verify_password(password: str, hashed_password: str) -> bool:
+        """Verifies a password against a stored hash."""
+        return pbkdf2_sha256.verify(password, hashed_password)
+
+    @staticmethod
+    def regenerate_session(session_id: str):
+        """
+        Simulates regenerating a session ID to prevent session fixation.
+        In a real web framework, this would be a framework-specific function.
+        """
+        print(f"Session regenerated. Old ID: {session_id}")
+        new_session_id = str(uuid.uuid4())
+        print(f"New ID: {new_session_id}")
+        return new_session_id
+
+class UserHandler:
+    """
+    Handles user login, logout, and session validation.
+    This class mirrors the logic from the user's PHP User class.
+    """
+    def __init__(self, db: Database):
+        self.db = db
+        # A simple in-memory session store for this example
+        self._session = {}
+
+    def login(self, username: str, password: str, request_data: dict) -> bool:
+        """
+        Logs in the user by verifying credentials and storing a new session.
+        :param username: The user's username.
+        :param password: The user's plain-text password.
+        :param request_data: A dictionary containing 'ip_address' and 'user_agent'.
+        :return: True if login is successful, False otherwise.
+        """
+        try:
+            # Step 1: Find the user in the database
+            user_data = self.db.fetchone("SELECT id, username, password, is_admin, account_locked, failed_login_attempts FROM users WHERE username = ?", (username,))
+            if user_data is None:
+                print(f"Login failed: Username '{username}' not found.")
+                return False
+
+            user = {
+                'id': user_data[0],
+                'username': user_data[1],
+                'password': user_data[2],
+                'is_admin': user_data[3],
+                'account_locked': user_data[4],
+                'failed_login_attempts': user_data[5]
+            }
+
+            # Check if account is locked
+            if user['account_locked'] == 1:
+                print(f"Login failed: Account for '{username}' is locked.")
+                return False
+
+            # Step 2: Verify the password
+            if Security.verify_password(password, user['password']):
+                print(f"Login successful for user: '{username}'")
+                
+                # Reset failed login attempts on success
+                self.reset_failed_attempts(username)
+
+                # Step 3: Create a new session record in the database
+                session_id = str(uuid.uuid4())
+                ip_address = request_data.get('ip_address', 'unknown')
+                user_agent = request_data.get('user_agent', 'unknown')
+
+                self.db.execute(
+                    "INSERT INTO sessions (id, user_id, ip_address, user_agent) VALUES (?, ?, ?, ?)",
+                    (session_id, user['id'], ip_address, user_agent)
+                )
+
+                # Step 4: Store session data in the in-memory session (or a session store)
+                self._session = {
+                    'session_id': session_id,
+                    'user_id': user['id'],
+                    'username': user['username'],
+                    'is_admin': user['is_admin']
+                }
+
+                # Security: Regenerate session ID
+                self._session['session_id'] = Security.regenerate_session(session_id)
+                return True
+            else:
+                print(f"Login failed: Incorrect password for user '{username}'.")
+                # Increment failed login attempts
+                self.increment_failed_attempts(username)
+                return False
+
+        except sqlite3.Error as e:
+            print(f"Database error during login: {e}")
+            return False
+
+    def logout(self) -> bool:
+        """
+        Logs out the current user by deleting the session from the database.
+        :return: True if logout is successful, False otherwise.
+        """
+        if 'user_id' not in self._session:
+            print("No active session to log out.")
+            return False
+
+        try:
+            # Step 1: Delete the session from the database
+            self.db.execute("DELETE FROM sessions WHERE user_id = ?", (self._session['user_id'],))
+            
+            # Step 2: Clear the in-memory session data
+            self._session.clear()
+            print("User logged out successfully.")
+            return True
+        except sqlite3.Error as e:
+            print(f"Database error during logout: {e}")
+            return False
+
+    def is_logged_in(self) -> bool:
+        """
+        Checks if the current user is logged in.
+        :return: True if a valid session exists, False otherwise.
+        """
+        if 'user_id' not in self._session:
+            return False
+
+        try:
+            # Check for the session in the database
+            session_data = self.db.fetchone(
+                "SELECT * FROM sessions WHERE id = ? AND user_id = ?",
+                (self._session['session_id'], self._session['user_id'])
+            )
+            return session_data is not None
+        except sqlite3.Error as e:
+            print(f"Database error during is_logged_in check: {e}")
+            return False
+
+    def is_admin(self) -> bool:
+        """
+        Checks if the logged-in user is an admin.
+        :return: True if the user is an admin, False otherwise.
+        """
+        return self._session.get('is_admin', 0) == 1
+
+    def validate_session(self, request_data: dict) -> bool:
+        """
+        Validates the current session against IP address and user agent.
+        :param request_data: A dictionary containing 'ip_address' and 'user_agent'.
+        :return: True if the session is valid, False otherwise.
+        """
+        if not self.is_logged_in():
+            return False
+
+        try:
+            ip_address = request_data.get('ip_address', 'unknown')
+            user_agent = request_data.get('user_agent', 'unknown')
+
+            session_data = self.db.fetchone(
+                "SELECT * FROM sessions WHERE id = ? AND user_id = ? AND ip_address = ? AND user_agent = ?",
+                (self._session['session_id'], self._session['user_id'], ip_address, user_agent)
+            )
+            return session_data is not None
+        except sqlite3.Error as e:
+            print(f"Database error during session validation: {e}")
+            return False
+
+    def lock_account(self, username: str):
+        """
+        Locks a user account.
+        :param username: The username of the account to lock.
+        """
+        try:
+            self.db.execute("UPDATE users SET account_locked = 1 WHERE username = ?", (username,))
+            print(f"Account for '{username}' has been locked.")
+        except sqlite3.Error as e:
+            print(f"Database error while locking account: {e}")
+
+    def reset_failed_attempts(self, username: str):
+        """
+        Resets failed login attempts for a user.
+        :param username: The username of the account.
+        """
+        try:
+            self.db.execute("UPDATE users SET failed_login_attempts = 0 WHERE username = ?", (username,))
+        except sqlite3.Error as e:
+            print(f"Database error while resetting failed attempts: {e}")
+
+    def increment_failed_attempts(self, username: str):
+        """
+        Increments failed login attempts and locks the account if a threshold is met.
+        :param username: The username of the account.
+        """
+        try:
+            # Get the current failed attempts
+            user_data = self.db.fetchone("SELECT failed_login_attempts FROM users WHERE username = ?", (username,))
+            if user_data:
+                attempts = user_data[0] + 1
+                self.db.execute(
+                    "UPDATE users SET failed_login_attempts = ? WHERE username = ?",
+                    (attempts, username)
+                )
+                print(f"Failed login attempts for '{username}': {attempts}")
+                
+                # Check for threshold (e.g., 5 attempts)
+                if attempts >= 5:
+                    self.lock_account(username)
+
+        except sqlite3.Error as e:
+            print(f"Database error while incrementing failed attempts: {e}")
+
+# --- Example Usage ---
+if __name__ == "__main__":
+    db = Database()
+    db.setup_tables()
+    user_handler = UserHandler(db)
+
+    # Clean up old test data if it exists
+    db.execute("DELETE FROM users WHERE username IN (?, ?)", ("testuser", "adminuser"))
+    db.execute("DELETE FROM sessions")
+
+    # 1. Register a new user and an admin user
+    hashed_password = Security.hash_password("secure_password_123")
+    db.execute("INSERT INTO users (username, password) VALUES (?, ?)", ("testuser", hashed_password))
+    db.execute("INSERT INTO users (username, password, is_admin) VALUES (?, ?, 1)", ("adminuser", hashed_password))
+
+    print("--- Test 1: Successful Login ---")
+    # Simulate a web request
+    request_data = {
+        'ip_address': '192.168.1.100',
+        'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+    }
+    
+    login_success = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status: {login_success}")
+    print(f"Is user logged in? {user_handler.is_logged_in()}")
+    print(f"Is user an admin? {user_handler.is_admin()}")
+    print(f"Is session valid? {user_handler.validate_session(request_data)}")
+    print("-" * 20)
+    
+    # 2. Simulate a logout
+    print("--- Test 2: Logout ---")
+    user_handler.logout()
+    print(f"Is user logged in after logout? {user_handler.is_logged_in()}")
+    print("-" * 20)
+
+    # 3. Simulate a failed login and account lock
+    print("--- Test 3: Failed Login and Account Lock ---")
+    # Log in with the wrong password multiple times
+    for i in range(6):
+        user_handler.login("testuser", "wrong_password", request_data)
+    
+    # Now, try to log in with the correct password. It should fail because the account is locked.
+    print("\nAttempting to log in with correct password after lock:")
+    login_attempt_after_lock = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status: {login_attempt_after_lock}")
+    print("-" * 20)
+    
+    # 4. Reset failed attempts for a new login
+    print("--- Test 4: Resetting failed attempts ---")
+    user_handler.reset_failed_attempts("testuser")
+    login_attempt_after_reset = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status after reset: {login_attempt_after_reset}")
+    
+    db.close()
+    
+    # Optional: Clean up the database file after the run
+    # os.remove("cms_database.db")

main.py

@@ -0,0 +1,194 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# main.py
+# This is the main entry point of the application.
+# It now handles asynchronous initialization of the fundament modules.
+import sys
+import logging
+import asyncio
+import os
+from typing import Dict, Any, Optional
+
+import importlib.util
+import datetime
+
+if 'fundaments' in sys.modules:
+    del sys.modules['fundaments']
+
+# We import our core modules from the "fundaments" directory.
+try:
+    from fundaments.config_handler import config_service
+    from fundaments.postgresql import init_db_pool, close_db_pool
+    from fundaments.encryption import Encryption
+    from fundaments.access_control import AccessControl
+    from fundaments.user_handler import UserHandler
+    from fundaments.security import Security
+    from fundaments.debug import PyFundamentsDebug
+except ImportError as e:
+    print(f"Error: Failed to import a fundament module: {e}")
+    print("Please ensure the modules and dependencies are present.")
+    sys.exit(1)
+# Debug run    
+debug = PyFundamentsDebug()
+debug.run()
+
+# Logger configuration - conditional based on ENV
+log_level = os.getenv('LOG_LEVEL', 'INFO').upper()
+log_to_tmp = os.getenv('LOG_TO_TMP', 'false').lower() == 'true'
+enable_public_logs = os.getenv('ENABLE_PUBLIC_LOGS', 'true').lower() == 'true'
+
+if enable_public_logs:
+    if log_to_tmp:
+        log_file = '/tmp/pyfundaments.log'
+        logging.basicConfig(
+            level=getattr(logging, log_level),
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            handlers=[
+                logging.FileHandler(log_file),
+                logging.StreamHandler()
+            ]
+        )
+    else:
+        logging.basicConfig(
+            level=getattr(logging, log_level),
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+else:
+    # Silent mode - only critical errors
+    logging.basicConfig(level=logging.CRITICAL)
+
+logger = logging.getLogger('main_app_loader')
+
+async def initialize_fundaments() -> Dict[str, Any]:
+    """
+    Initializes core application services conditionally based on available ENV variables.
+    Only loads services for which the required configuration is present.
+    """
+    logger.info("Starting conditional initialization of fundament modules...")
+    
+    fundaments = {
+        "config": config_service
+    }
+    
+    # --- Database Initialization (PostgreSQL) ---
+    # Only initialize if DATABASE_URL is available
+    database_url = config_service.get("DATABASE_URL")
+    if database_url and database_url != "your_database_dsn_here":
+        try:
+            db_service = await init_db_pool(database_url)
+            fundaments["db"] = db_service
+            logger.info("Database service initialized.")
+        except Exception as e:
+            logger.warning(f"Database initialization failed, continuing without DB: {e}")
+            fundaments["db"] = None
+    else:
+        logger.info("No valid DATABASE_URL found, skipping database initialization.")
+        fundaments["db"] = None
+
+    # --- Encryption Initialization ---
+    # Only initialize if both encryption keys are available
+    master_key = config_service.get("MASTER_ENCRYPTION_KEY")
+    persistent_salt = config_service.get("PERSISTENT_ENCRYPTION_SALT")
+    
+    if master_key and persistent_salt and master_key != "your_256_bit_key_here":
+        try:
+            encryption_service = Encryption(master_key=master_key, salt=persistent_salt)
+            fundaments["encryption"] = encryption_service
+            logger.info("Encryption service initialized.")
+        except Exception as e:
+            logger.warning(f"Encryption initialization failed, continuing without encryption: {e}")
+            fundaments["encryption"] = None
+    else:
+        logger.info("Encryption keys not found or using defaults, skipping encryption initialization.")
+        fundaments["encryption"] = None
+
+    # --- Access Control Initialization ---
+    # Only initialize if we have a database connection
+    if fundaments["db"] is not None:
+        try:
+            access_control_service = AccessControl()
+            fundaments["access_control"] = access_control_service
+            logger.info("Access Control service initialized.")
+        except Exception as e:
+            logger.warning(f"Access Control initialization failed: {e}")
+            fundaments["access_control"] = None
+    else:
+        logger.info("No database available, skipping Access Control initialization.")
+        fundaments["access_control"] = None
+
+    # --- User Handler Initialization ---
+    # Only initialize if we have a database connection
+    if fundaments["db"] is not None:
+        try:
+            user_handler_service = UserHandler(fundaments["db"])
+            fundaments["user_handler"] = user_handler_service
+            logger.info("User Handler service initialized.")
+        except Exception as e:
+            logger.warning(f"User Handler initialization failed: {e}")
+            fundaments["user_handler"] = None
+    else:
+        logger.info("No database available, skipping User Handler initialization.")
+        fundaments["user_handler"] = None
+
+    # --- Security Manager Initialization ---
+    # Only initialize if we have the required sub-services
+    available_services = {k: v for k, v in fundaments.items() if v is not None and k != "config"}
+    
+    if len(available_services) >= 1:  # At least one service beyond config
+        try:
+            # Filter out None services for Security manager
+            fundament_services = {
+                k: v for k, v in {
+                    "user_handler": fundaments.get("user_handler"),
+                    "access_control": fundaments.get("access_control"),
+                    "encryption": fundaments.get("encryption")
+                }.items() if v is not None
+            }
+            
+            if fundament_services:  # Only if we have actual services
+                security_service = Security(fundament_services)
+                fundaments["security"] = security_service
+                logger.info("Security manager initialized.")
+            else:
+                logger.info("No services available for Security manager, skipping initialization.")
+                fundaments["security"] = None
+        except Exception as e:
+            logger.warning(f"Security manager initialization failed: {e}")
+            fundaments["security"] = None
+    else:
+        logger.info("Insufficient services for Security manager, skipping initialization.")
+        fundaments["security"] = None
+    
+    # Log what was actually initialized
+    initialized_services = [k for k, v in fundaments.items() if v is not None]
+    logger.info(f"Successfully initialized services: {', '.join(initialized_services)}")
+    
+    return fundaments
+
+async def main():
+    """
+    The main asynchronous function of the application.
+    """
+    logger.info("Starting main.py...")
+    
+    fundaments = await initialize_fundaments()
+    
+    try:
+        # Load the actual app logic here.
+        # This is where your 'app/app.py' would be imported and run.
+        logger.info("Fundament modules are ready for the app logic.")
+        # Example:
+        from app.app import start_application
+        await start_application(fundaments)
+    
+    finally:
+        # Ensure the database pool is closed gracefully on exit (if it was initialized)
+        if fundaments.get("db") is not None:
+            await close_db_pool()
+            logger.info("Database pool closed.")
+        logger.info("Application shut down.")
+
+if __name__ == "__main__":
+    asyncio.run(main())

requirements.txt

@@ -0,0 +1,31 @@
+# PyFundaments Core Dependencies (always needed)
+asyncpg
+python-dotenv
+passlib
+cryptography
+
+# MCP Hub Dependencies (needed for app/mcp.py)
+fastmcp
+httpx
+
+# Additional dependencies for specific app types:
+# Uncomment what your application needs
+
+# File operations (ML, data processing, file uploads)
+#aiofiles
+
+# Web applications (Flask-based apps, APIs)
+#Flask[async]
+
+# HTTP client operations (API calls, webhooks)
+#requests
+
+# Discord bots
+#discord.py
+#PyNaCl
+
+# Alternative PostgreSQL driver (if not using asyncpg)
+#psycopg2-binary
+
+# Production web server
+#waitress