akasa 0.1.1__tar.gz

akasa-0.1.1/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: akasa
+Version: 0.1.1
+Summary: Agnostic Volume Router and Event Bus Substrate.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Flask>=3.0.0
+Requires-Dist: cryptography>=41.0.0
+
+# 🌌 Akasa: Application Kernel & Volume Router
+
+**Akasa** (Sanskrit for *Ether / Substrate / Space*) is a local-first, event-sourced Python micro-kernel. 
+
+Extracted from the [inSetu Developer OS](https://github.com/Callosemic/insetu), Akasa acts as the foundational substrate for multi-tenant, offline-first Python applications. It is strictly domain-agnostic: it knows nothing about your application's business logic, acting purely as a high-performance routing and synchronization engine.
+
+## ✨ Core Mechanics
+
+1. **The Volume Router (VFS):** An asynchronous, non-blocking Virtual File System. It abstracts physical disk I/O behind a strict Mount Table, allowing host applications to mount sandboxed repositories and virtual domains to unified URIs (e.g., `vfs://` or `ctx://`).
+2. **Stateless Multi-Tenancy:** All databases, caches, and file resolutions are scoped to an active `workspace_id`, allowing a single daemon process to serve multiple isolated tenant environments safely.
+3. **The Typed Event Bus:** A synchronous/asynchronous `HookRegistry` enforcing strict authorization boundaries for inter-module communication.
+4. **The Metronome (Worker Engine):** A background SQLite-backed job ledger (`jobs` and `immediate_jobs`) providing distributed, dependency-driven task execution and UI telemetry without blocking the main event loop.
+5. **SQLite WAL Connection Pooling:** Thread-local, auto-evicting database connection pooling explicitly optimized for Write-Ahead Logging concurrency.
+
+## 🏗️ Architecture Mandate
+
+Akasa adheres to the **Blind Substrate Mandate**.
+* **Zero Domain Logic:** Akasa does not parse target repositories, compile RAG contexts, or understand Git diffs. It only provides the tools to store and route them.
+* **Inversion of Control:** All application-specific behavior is injected into Akasa by the host application via `@hooks.on()` subscriptions, Driver registrations, and Volume mounts.
+
+## 🚀 Installation
+
+Akasa is designed to be installed as a foundational dependency for your host application.
+
+```bash
+pip install akasa
+
+```

akasa-0.1.1/README.md

@@ -0,0 +1,28 @@
+# 🌌 Akasa: Application Kernel & Volume Router
+
+**Akasa** (Sanskrit for *Ether / Substrate / Space*) is a local-first, event-sourced Python micro-kernel. 
+
+Extracted from the [inSetu Developer OS](https://github.com/Callosemic/insetu), Akasa acts as the foundational substrate for multi-tenant, offline-first Python applications. It is strictly domain-agnostic: it knows nothing about your application's business logic, acting purely as a high-performance routing and synchronization engine.
+
+## ✨ Core Mechanics
+
+1. **The Volume Router (VFS):** An asynchronous, non-blocking Virtual File System. It abstracts physical disk I/O behind a strict Mount Table, allowing host applications to mount sandboxed repositories and virtual domains to unified URIs (e.g., `vfs://` or `ctx://`).
+2. **Stateless Multi-Tenancy:** All databases, caches, and file resolutions are scoped to an active `workspace_id`, allowing a single daemon process to serve multiple isolated tenant environments safely.
+3. **The Typed Event Bus:** A synchronous/asynchronous `HookRegistry` enforcing strict authorization boundaries for inter-module communication.
+4. **The Metronome (Worker Engine):** A background SQLite-backed job ledger (`jobs` and `immediate_jobs`) providing distributed, dependency-driven task execution and UI telemetry without blocking the main event loop.
+5. **SQLite WAL Connection Pooling:** Thread-local, auto-evicting database connection pooling explicitly optimized for Write-Ahead Logging concurrency.
+
+## 🏗️ Architecture Mandate
+
+Akasa adheres to the **Blind Substrate Mandate**.
+* **Zero Domain Logic:** Akasa does not parse target repositories, compile RAG contexts, or understand Git diffs. It only provides the tools to store and route them.
+* **Inversion of Control:** All application-specific behavior is injected into Akasa by the host application via `@hooks.on()` subscriptions, Driver registrations, and Volume mounts.
+
+## 🚀 Installation
+
+Akasa is designed to be installed as a foundational dependency for your host application.
+
+```bash
+pip install akasa
+
+```

akasa-0.1.1/akasa/auth/__init__.py

@@ -0,0 +1,151 @@
+import os
+import json
+import socket
+import secrets
+from flask import Blueprint, request, jsonify
+from akasa.utils import load_config, save_json_config, get_workspace_physics
+from akasa.extension import AkasaExtension
+auth_bp = Blueprint('auth', __name__)
+def get_master_key():
+    import os
+    import shutil
+    from akasa.utils import _cwd
+    from pathlib import Path
+
+    control_dir_name = os.environ.get("AKASA_CONTROL_DIR", ".akasa")
+    global_key_path = Path.home().joinpath(control_dir_name, "master_key.txt")
+    local_key_path = Path(_cwd).joinpath(control_dir_name, "master_key.txt")
+
+    # Safe Migration: If a legacy local key exists...
+    if local_key_path.exists() and os.path.getsize(local_key_path) > 0:
+        # If no global key exists yet, elevate this local key to be the global key
+        if not global_key_path.exists():
+            global_key_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(local_key_path.as_posix(), global_key_path.as_posix())
+            return global_key_path.read_bytes()
+        else:
+            # A global key already exists. This local key is different.
+            # We MUST keep using the local one here so we don't brick this specific workspace's secrets.
+            return local_key_path.read_bytes()
+    # Standard Global Key Generation/Loading
+    if not global_key_path.exists() or os.path.getsize(global_key_path) == 0:
+        from cryptography.fernet import Fernet
+        from akasa.vfs import execute_vfs_save
+        key = Fernet.generate_key()
+        execute_vfs_save("default", global_key_path.as_posix(), key.decode('utf-8'), data={"is_absolute_artifact": True, "ignore_ledger": True})
+        return key
+
+    return global_key_path.read_bytes()
+
+def encrypt_secret(val: str) -> str:
+    if not val: return val
+    from cryptography.fernet import Fernet
+    f = Fernet(get_master_key())
+    return "v1:" + f.encrypt(val.encode('utf-8')).decode('utf-8')
+
+def decrypt_secret(val: str) -> str:
+    if not val or not val.startswith("v1:"):
+        return val
+    from cryptography.fernet import Fernet
+    f = Fernet(get_master_key())
+    try:
+        return f.decrypt(val[3:].encode('utf-8')).decode('utf-8')
+    except Exception:
+        return ""
+security_bp = AkasaExtension(
+    'security', __name__, title="Security & Encryption", 
+    description="Local encryption key management.",
+    core=True,
+    settings_schema=lambda ws: [{
+        "id": "master_fernet_key",
+        "label": "Master Encryption Key (Fernet)",
+        "type": "text",
+        "scope": "daemon",
+        "secure": False,
+        "default": get_master_key().decode('utf-8'),
+        "description": "This global key encrypts your secrets.json. It is stored securely in your user home directory. If you move this workspace to another machine, you must copy this key to the new machine."
+    }]
+)
+@security_bp.route('settings', methods=['POST'])
+def update_security_settings(ctx):
+    data = ctx.req.json or {}
+    new_key = data.get("master_fernet_key")
+    if new_key:
+        import os
+        from pathlib import Path
+        from akasa.utils import _cwd
+        control_dir_name = os.environ.get("AKASA_CONTROL_DIR", ".akasa")
+        global_key_path = Path.home().joinpath(control_dir_name, "master_key.txt")
+        local_key_path = Path(_cwd).joinpath(control_dir_name, "master_key.txt")
+        # If a local legacy key exists, update that one to avoid breaking state, otherwise update global
+        target_path = local_key_path if local_key_path.exists() else global_key_path
+        from akasa.vfs import execute_vfs_save
+        execute_vfs_save(ctx.workspace_id, target_path.as_posix(), new_key, data={"is_absolute_artifact": True, "ignore_ledger": True})
+
+    return {"status": "success", "requires_refresh": False}
+# Generate a cryptographically sound scrolling runtime session token
+# Anchor to the environment so it survives os.execv() and Werkzeug hot-reloads
+BOOT_TOKEN = os.environ.get("AKASA_BOOT_TOKEN")
+if not BOOT_TOKEN:
+    BOOT_TOKEN = secrets.token_hex(16)
+    os.environ["AKASA_BOOT_TOKEN"] = BOOT_TOKEN
+@auth_bp.route('/auth/bootstrap', methods=['POST'])
+def bootstrap():
+    """Unauthenticated token exchange gate supporting absolute dynamic fallback routing."""
+    data = request.json or {}
+
+    # Extract real IP if behind Tailscale Serve or a Reverse Proxy
+    client_ip = request.headers.get('X-Forwarded-For', request.remote_addr).split(',')[0].strip()
+    # --- ROUTE A: LOCALHOST BYPASS ---
+    # If the user is physically on the machine, auto-authenticate
+    if client_ip == '127.0.0.1':
+        # Check for cross-origin browser requests (Localhost Drive-By CSRF prevention)
+        origin = request.headers.get('Origin', '')
+        referer = request.headers.get('Referer', '')
+
+        import urllib.parse
+        def is_allowed(url_str):
+            try:
+                hostname = urllib.parse.urlparse(url_str).hostname or ""
+                return hostname in ['127.0.0.1', 'localhost'] or hostname.endswith('.ts.net')
+            except Exception:
+                return False
+
+        if origin and not is_allowed(origin):
+            return jsonify({"error": "Forbidden: Cross-origin request blocked"}), 403
+        if referer and not is_allowed(referer):
+            return jsonify({"error": "Forbidden: Cross-origin request blocked"}), 403
+
+        return jsonify({
+            "status": "authenticated", 
+            "token": BOOT_TOKEN, 
+            "method": "localhost"
+        })
+
+    cfg = load_config()
+    # --- ROUTE B: INVERSION OF CONTROL (Zero-Knowledge Identity Protocols) ---
+    from akasa.hooks import hooks
+    for res in hooks.emit('execute_identity_handshake', request=request, client_ip=client_ip, config=cfg):
+        if res and isinstance(res, dict) and res.get("status") == "authenticated":
+            return jsonify({
+                "status": "authenticated", 
+                "token": BOOT_TOKEN, 
+                "method": res.get("method", "hook"),
+                "user": res.get("user")
+            })
+
+    # --- ROUTE C: PERSISTENT CONFIG TOKEN CHECK ---
+    client_token = data.get("token")
+    system_token = cfg.get("auth_token")
+
+    if system_token and client_token == system_token:
+        return jsonify({
+            "status": "authenticated", 
+            "token": BOOT_TOKEN, 
+            "method": "static_config"
+        })
+
+    return jsonify({
+        "status": "challenge", 
+        "message": "Authentication required."
+    }), 401

akasa-0.1.1/akasa/db.py

@@ -0,0 +1,139 @@
+from pathlib import Path
+import os
+import sqlite3
+import threading
+from akasa.utils import get_workspace_physics
+from akasa.hooks import hooks
+
+# Thread-local storage guarantees safe connection pooling across the ASGI / Worker matrix
+_local = threading.local()
+
+_REGISTERED_SCHEMAS = {}
+
+def register_schema(ext_name, schema_dict):
+    """Registers a declarative SQLite schema for automatic workspace migration."""
+    _REGISTERED_SCHEMAS[ext_name] = schema_dict
+
+def apply_declarative_schema(db_name, schema_dict, workspace_id=None):
+    """Generates CREATE TABLE and executes ALTER TABLE ADD COLUMN migrations via diffing."""
+    conn = get_connection(db_name, workspace_id)
+    for table_name, columns in schema_dict.items():
+        # 1. Generate CREATE TABLE
+        col_defs = ", ".join([f"{col} {dtype}" for col, dtype in columns.items()])
+        conn.execute(f"CREATE TABLE IF NOT EXISTS {table_name} ({col_defs})")
+
+        # 2. Diff columns and ALTER TABLE
+        cursor = conn.execute(f"PRAGMA table_info({table_name})")
+        existing_cols = {row['name'] for row in cursor.fetchall()}
+
+        for col, dtype in columns.items():
+            if col not in existing_cols:
+                try:
+                    conn.execute(f"ALTER TABLE {table_name} ADD COLUMN {col} {dtype}")
+                except Exception as e:
+                    print(f"⚠️ Auto-migration failed for {table_name}.{col}: {e}")
+    conn.commit()
+# Register core worker database schema for tracking all file deltas contextually
+register_schema('workers', {
+    'vfs_event_log': {
+        'filepath': 'TEXT PRIMARY KEY',
+        'mutation_type': 'TEXT',
+        'timestamp': 'REAL'
+    }
+})
+@hooks.on('system_boot', priority=90)
+def init_declarative_schemas(**kwargs):
+    """Automatically provisions schemas and boots workspaces across all tenants."""
+    from akasa.utils import get_all_workspace_ids
+    for ws_id in get_all_workspace_ids():
+        for ext_name, schema in _REGISTERED_SCHEMAS.items():
+            apply_declarative_schema(ext_name, schema, ws_id)
+        hooks.emit('workspace_boot', workspace_id=ws_id)
+
+@hooks.on('workspace_shutdown')
+def close_workspace_connections(workspace_id=None, **kwargs):
+    """Evicts and closes thread-local SQLite connections for an unmounting tenant workspace."""
+    if not workspace_id or not hasattr(_local, 'connections'):
+        return
+    keys_to_close = [k for k in _local.connections.keys() if k[0] == workspace_id]
+    for key in keys_to_close:
+        try:
+            _local.connections[key].close()
+        except Exception:
+            pass
+        del _local.connections[key]
+def get_connection(db_name, workspace_id=None):
+    """
+    Returns a thread-local SQLite connection.
+    Keys connection by (workspace_id, db_name) to support stateless multi-tenancy.
+    Strictly enforces WAL mode and busy timeouts to prevent concurrent database locks.
+    """
+    if not hasattr(_local, 'connections'):
+        _local.connections = {}
+    if not workspace_id:
+        from akasa.utils import sniff_tenant_id
+        workspace_id = sniff_tenant_id()
+
+    # Key the connection by tenant
+    cache_key = (workspace_id, db_name)
+
+    # True LRU: Pop and re-insert to move the accessed key to the end of the dictionary
+    if cache_key in _local.connections:
+        conn = _local.connections.pop(cache_key)
+        _local.connections[cache_key] = conn
+        return conn
+
+    cfg_path, _ = get_workspace_physics(workspace_id)
+    db_dir = Path(cfg_path).parent.joinpath("ext", db_name, "db")
+    db_path = db_dir.joinpath(f"{db_name}.db").as_posix()
+
+    # Phase 3: LRU Eviction Policy (Max 5 Workspaces to prevent WAL lock exhaustion)
+    if len(_local.connections) >= 5:
+        oldest_key = list(_local.connections.keys())[0]
+        try:
+            _local.connections[oldest_key].close()
+        except Exception: pass
+        del _local.connections[oldest_key]
+    os.makedirs(db_dir, exist_ok=True)
+
+    def _connect():
+        conn = sqlite3.connect(db_path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA synchronous=NORMAL;")
+        conn.execute("PRAGMA busy_timeout=5000;")
+        conn.commit()
+        cursor = conn.execute("PRAGMA quick_check(1);")
+        res = cursor.fetchone()
+        if res and res[0] != "ok":
+            raise sqlite3.DatabaseError(f"Database disk image is malformed: {res[0]}")
+        return conn
+
+    try:
+        conn = _connect()
+    except sqlite3.DatabaseError as e:
+        if "malformed" in str(e).lower() or "corrupt" in str(e).lower():
+            print(f"⚠️ [Akasa DB] Malformed database detected at '{db_path}'. Healing database...")
+            try:
+                sqlite3.connect(db_path).close()
+            except Exception:
+                pass
+            import time, shutil
+            corrupt_path = f"{db_path}.corrupt_{int(time.time())}"
+            try:
+                if os.path.exists(db_path):
+                    shutil.move(db_path, corrupt_path)
+                for ext in ["-wal", "-shm"]:
+                    if os.path.exists(db_path + ext):
+                        os.remove(db_path + ext)
+            except Exception as move_err:
+                print(f"⚠️ [Akasa DB] Failed to move corrupt db: {move_err}")
+
+            conn = _connect()
+            if db_name in _REGISTERED_SCHEMAS:
+                apply_declarative_schema(db_name, _REGISTERED_SCHEMAS[db_name], workspace_id)
+        else:
+            raise
+
+    _local.connections[cache_key] = conn
+    return conn

akasa-0.1.1/akasa/events.py

@@ -0,0 +1,31 @@
+import threading
+import queue
+import json
+
+class EventBus:
+    def __init__(self):
+        self.listeners = []
+        self.lock = threading.Lock()
+
+    def subscribe(self):
+        q = queue.Queue(maxsize=100)
+        with self.lock:
+            self.listeners.append(q)
+        return q
+
+    def unsubscribe(self, q):
+        with self.lock:
+            if q in self.listeners:
+                self.listeners.remove(q)
+
+    def emit_sse(self, event_type: str, payload: dict):
+        msg = f"event: {event_type}\ndata: {json.dumps(payload)}\n\n"
+        with self.lock:
+            for q in self.listeners:
+                try:
+                    q.put_nowait(msg)
+                except queue.Full:
+                    pass
+
+# Global SSE Publisher
+sse_bus = EventBus()