jaaql-middleware-python 4.34.3__py3-none-any.whl → 5.2.7__py3-none-any.whl

jaaql/constants.py

@@ -91,6 +91,8 @@ VAULT_KEY__super_db_credentials = "super_db_credentials"
 VAULT_KEY__jaaql_lookup_connection = "jaaql_lookup_connection"
 VAULT_KEY__allow_jaaql_uninstall = "Allow jaaql uninstall"
 VAULT_KEY__jaaql_db_password = "Jaaql DB Password"
+VAULT_KEY__postgres_bootstrap_password = "postgres_bootstrap_password"
+VAULT_KEY__keycloak_realm_admin_secret = "keycloak_realm_admin_secret"
 
 # Used for re-installation
 VAULT_KEY__db_connection_string = "db_connection_string"
@@ -205,8 +207,9 @@ USERNAME__anonymous = "anonymous"
 PASSWORD__anonymous = "jaaql_public_password"
 ROLE__jaaql = "jaaql"
 ROLE__postgres = "postgres"
+ROLE__dba = "dba"
 
 PROTOCOL__postgres = "postgresql://"
 
-VERSION = "4.34.3"
+VERSION = "5.2.7"
 

jaaql/db/db_pg_interface.py

@@ -28,6 +28,40 @@ QUERY__dba_query = "SELECT pg_has_role(datdba::regrole, 'MEMBER') FROM pg_databa
 QUERY__dba_query_external = "SELECT pg_has_role(datdba::regrole, 'MEMBER') FROM pg_database WHERE datname = current_database();"
 
 
+def _escape_unescaped_percent(query: str) -> str:
+    # psycopg3 scans every '%' in the SQL when parameters are supplied and
+    # rejects anything that isn't a placeholder or '%%'. JAAQL uses named
+    # parameters only (:parameter -> %(name)s), so positional %s/%b/%t must
+    # never survive: any '%s' in author SQL is a literal inside a string
+    # (LIKE '%saas%', LIKE '%twynstra%', etc.), not a placeholder. Escape
+    # everything except '%%' and '%(name)X'.
+    out = []
+    i = 0
+    n = len(query)
+    while i < n:
+        if query[i] != '%':
+            out.append(query[i])
+            i += 1
+            continue
+
+        nxt = query[i + 1] if i + 1 < n else ''
+        if nxt == '%':
+            out.append('%%')
+            i += 2
+        elif nxt == '(':
+            close = query.find(')', i + 2)
+            if close == -1 or close + 1 >= n:
+                out.append('%%')
+                i += 1
+            else:
+                out.append(query[i:close + 2])
+                i = close + 2
+        else:
+            out.append('%%')
+            i += 1
+    return ''.join(out)
+
+
 class DBPGInterface(DBInterface):
 
     HOST_POOLS = {}
@@ -210,7 +244,7 @@ class DBPGInterface(DBInterface):
                     if parameters is None or len(parameters.keys()) == 0:
                         cursor.execute(query, prepare=do_prepare)
                     else:
-                        cursor.execute(query, parameters, prepare=do_prepare)
+                        cursor.execute(_escape_unescaped_percent(query), parameters, prepare=do_prepare)
                     if cursor.description is None:
                         return [], [], []
                     else:

jaaql/documentation/documentation_internal.py

@@ -367,12 +367,40 @@ DOCUMENTATION__oidc_exchange_code = SwaggerDocumentation(
         name="Fetch OIDC code",
         description="Exchanges OIDC auth code for auth token, returns the token",
         method=REST__GET,
-        arguments=SwaggerArgumentResponse(
-            name="response",
-            description="The OIDC response JWT object",
-            arg_type=str,
-            example=["eyJ..."]
-        ),
+        arguments=[
+            SwaggerArgumentResponse(
+                name="response",
+                description="The OIDC response JWT object (FAPI/JARM mode)",
+                arg_type=str,
+                required=False,
+                condition="When USE_FAPI_ADVANCED or standard JARM is enabled",
+                example=["eyJ..."]
+            ),
+            SwaggerArgumentResponse(
+                name="code",
+                description="The authorization code (basic OIDC mode)",
+                arg_type=str,
+                required=False,
+                condition="When USE_OIDC_BASIC is enabled",
+                example=["abc123"]
+            ),
+            SwaggerArgumentResponse(
+                name="state",
+                description="The state parameter (basic OIDC mode)",
+                arg_type=str,
+                required=False,
+                condition="When USE_OIDC_BASIC is enabled",
+                example=["xyz789"]
+            ),
+            SwaggerArgumentResponse(
+                name="session_state",
+                description="The session state parameter (Azure AD / OpenID Connect session management)",
+                arg_type=str,
+                required=False,
+                condition="When the identity provider includes session management",
+                example=["0022d22a-3a6c-953c-be05-80a155fda337"]
+            )
+        ],
         response=SwaggerFlatResponse(
             description="URL",
             code=HTTPStatus.FOUND,
@@ -381,6 +409,16 @@ DOCUMENTATION__oidc_exchange_code = SwaggerDocumentation(
     )
 )
 
+DOCUMENTATION__resend_verify_email = SwaggerDocumentation(
+    tags="oidc",
+    security=False,
+    methods=SwaggerMethod(
+        name="Resend verification email",
+        description="Triggers Keycloak to resend a verification email for a given email address",
+        method=REST__POST,
+    )
+)
+
 DOCUMENTATION__jwks = SwaggerDocumentation(
     tags="jwks",
     security=False,
@@ -567,4 +605,26 @@ DOCUMENTATION__security_event = SwaggerDocumentation(
         ],
         response=RES__allow_all
     )
-)
+)
+
+DOCUMENTATION__report_sentinel_error = SwaggerDocumentation(
+    tags="Reporting",
+    security=False,  # PUBLIC: also receives self-posts from the in-core sentinel reporter (SENTINEL_URL=_)
+    methods=SwaggerMethod(
+        name="Report error",
+        description="Logs an application error (user_agent + ip_address encrypted at rest) and triggers Sentinel "
+                    "alert processing. Never returns 500 (would otherwise make JAAQL report itself recursively).",
+        method=REST__POST,
+        body=[
+            SwaggerArgumentResponse(name="location", description="URL/location where the error occurred", arg_type=str, example=["https://app/index.html"]),
+            SwaggerArgumentResponse(name="source_file", description="Source file the error occurred in", arg_type=str, example=["common.js"]),
+            SwaggerArgumentResponse(name="error_condensed", description="Condensed error (truncated to 200 chars for grouping)", arg_type=str, example=["Uncaught TypeError"]),
+            SwaggerArgumentResponse(name="stacktrace", description="Full stacktrace", arg_type=str, example=["at <anonymous>:1:16"]),
+            SwaggerArgumentResponse(name="version", description="Product version", arg_type=str, example=["1.2.3"]),
+            SwaggerArgumentResponse(name="source_system", description="Originating system/application", arg_type=str, example=["JAAQL"]),
+            SwaggerArgumentResponse(name="file_line_number", description="Line number", arg_type=int, required=False, condition="If available", example=[123]),
+            SwaggerArgumentResponse(name="file_col_number", description="Column number", arg_type=int, required=False, condition="If available", example=[21]),
+            SwaggerArgumentResponse(name="user_agent", description="Browser user agent (encrypted at rest). Absent on internal self-posts.", arg_type=str, required=False, condition="If present", example=["Mozilla/5.0"]),
+        ]
+    )
+)

jaaql/exceptions/jaaql_interpretable_handled_errors.py

@@ -127,10 +127,24 @@ class UserUnauthorized(JaaqlInterpretableHandledError):
         )
 
 
-class UnhandledJaaqlServerError(JaaqlInterpretableHandledError):
+class EmailConfirmationRequired(JaaqlInterpretableHandledError):
     def __init__(self, descriptor=None):
         super().__init__(
             error_code=1010,
+            http_response_code=403,
+            table_name=None,
+            message="Your email confirmation grace period has expired. Please confirm your email to continue.",
+            column_name=None,
+            _set=None,
+            index=None,
+            descriptor=descriptor
+        )
+
+
+class UnhandledJaaqlServerError(JaaqlInterpretableHandledError):
+    def __init__(self, descriptor=None):
+        super().__init__(
+            error_code=1099,
             http_response_code=500,
             table_name=None,
             message="An unhandled exception has occurred with JAAQL.",

jaaql/mvc/base_controller.py

@@ -35,6 +35,7 @@ from jaaql.exceptions.http_status_exception import *
 ARG__http_inputs = "http_inputs"
 ARG__account_id = "account_id"
 ARG__ip_address = "ip_address"
+ARG__request_headers = "request_headers"
 ARG__response = "response"
 ARG__username = "username"
 ARG__profiler = "profiler"
@@ -496,7 +497,16 @@ class BaseJAAQLController:
                     if auth_cookie is not None:
                         security_key = auth_cookie
 
-                    if swagger_documentation.security:
+                    easyauth_resolved = False
+                    if self.model.use_easyauth and security_key is None:
+                        easyauth_principal_id = request.headers.get("X-MS-CLIENT-PRINCIPAL-ID")
+                        if easyauth_principal_id:
+                            account_id, username, ip_id, is_public, remember_me = \
+                                self.model.authenticate_via_easyauth(request.headers, ip_addr, jaaql_resp)
+                            easyauth_resolved = True
+                            self.perform_profile(request_id, "EasyAuth")
+
+                    if swagger_documentation.security and not easyauth_resolved:
                         bypass_super = request.headers.get(HEADER__security_bypass)
                         bypass_jaaql = request.headers.get(HEADER__security_bypass_jaaql)
                         bypass_user = request.headers.get(HEADER__security_specify_user)
@@ -566,6 +576,9 @@ class BaseJAAQLController:
                         if ARG__ip_address in inspect.getfullargspec(view_func_local).args:
                             supply_dict[ARG__ip_address] = ip_addr
 
+                        if ARG__request_headers in inspect.getfullargspec(view_func_local).args:
+                            supply_dict[ARG__request_headers] = request.headers
+
                         if ARG__response in inspect.getfullargspec(view_func_local).args:
                             supply_dict[ARG__response] = jaaql_resp
 

jaaql/mvc/base_model.py

@@ -18,6 +18,7 @@ from jaaql.config_constants import *
 from jaaql.email.email_manager import EmailManager
 from os.path import dirname
 from jaaql.services.cached_canned_query_service import CachedCannedQueryService
+from jaaql.utilities.bootstrap_secrets import get_or_seed_vault_secret
 import threading
 
 import uuid
@@ -236,6 +237,19 @@ class BaseJAAQLModel:
 
         self.application_url = os.environ.get("SERVER_ADDRESS", "")
         self.use_fapi_advanced = os.environ.get("USE_FAPI_ADVANCED", "").lower() == "true"
+        self.use_oidc_basic = os.environ.get("USE_OIDC_BASIC", "").lower() == "true"
+        if self.use_oidc_basic:
+            # Basic OIDC mode intentionally disables the advanced FAPI/JARM/PAR flow.
+            self.use_fapi_advanced = False
+
+        self.use_easyauth = os.environ.get("USE_EASYAUTH", "").lower() == "true"
+        if self.use_easyauth:
+            if self.use_oidc_basic or self.use_fapi_advanced:
+                raise Exception("USE_EASYAUTH cannot be combined with USE_OIDC_BASIC or USE_FAPI_ADVANCED")
+            print("EasyAuth mode enabled. Container MUST be behind Azure EasyAuth (App Service or Container Apps).")
+            self.easyauth_provider = os.environ.get("EASYAUTH_PROVIDER", "azure")
+            self.easyauth_tenant = os.environ.get("EASYAUTH_TENANT", "easyauth")
+            self.easyauth_provisioned = False
 
         self.fapi_pem = None
         self.fapi_cert = None
@@ -293,16 +307,27 @@ class BaseJAAQLModel:
 
         self.reload_lock = threading.Lock()
 
-        if not self.vault.has_obj(VAULT_KEY__jaaql_local_access_key):
-            self.vault.insert_obj(VAULT_KEY__jaaql_local_access_key, str(uuid.uuid4()))
-
-        if not self.vault.has_obj(VAULT_KEY__super_local_access_key):
-            self.vault.insert_obj(VAULT_KEY__super_local_access_key, str(uuid.uuid4()))
-
-        self.local_jaaql_access_key = os.environ.get(ENVIRON__JAAQL__JAAQL_BYPASS_KEY,
-                                                     self.vault.get_obj(VAULT_KEY__super_local_access_key) if self.is_container else "00000-00000")
-        self.local_super_access_key = os.environ.get(ENVIRON__JAAQL__SUPER_BYPASS_KEY,
-                                                     self.vault.get_obj(VAULT_KEY__super_local_access_key) if self.is_container else "00000-00000")
+        jaaql_bypass_key = get_or_seed_vault_secret(
+            self.vault,
+            VAULT_KEY__jaaql_local_access_key,
+            ENVIRON__JAAQL__JAAQL_BYPASS_KEY,
+            generate_if_missing=True
+        )
+        super_bypass_key = get_or_seed_vault_secret(
+            self.vault,
+            VAULT_KEY__super_local_access_key,
+            ENVIRON__JAAQL__SUPER_BYPASS_KEY,
+            generate_if_missing=True
+        )
+        get_or_seed_vault_secret(
+            self.vault,
+            VAULT_KEY__keycloak_realm_admin_secret,
+            "KEYCLOAK_REALM_ADMIN_SECRET",
+            generate_if_missing=False
+        )
+
+        self.local_jaaql_access_key = jaaql_bypass_key if self.is_container else "00000-00000"
+        self.local_super_access_key = super_bypass_key if self.is_container else "00000-00000"
 
         if self.vault.has_obj(VAULT_KEY__jaaql_lookup_connection):
             if self.is_container:

jaaql/mvc/controller.py

@@ -1,3 +1,5 @@
+from http import HTTPStatus
+
 from jaaql.mvc.exception_queries import SECURITY_EVENT_TYPE__create, SECURITY_EVENT_TYPE__delete, \
     SECURITY_EVENT_TYPE__reset
 from jaaql.mvc.model import JAAQLModel
@@ -10,7 +12,8 @@ from jaaql.db.db_interface import DBInterface
 from flask import request
 import queue
 
-from jaaql.utilities.utils_no_project_imports import COOKIE_OIDC
+from jaaql.utilities.utils_no_project_imports import COOKIE_OIDC, COOKIE_OIDC_RETURN
+from jaaql.interpreter.interpret_jaaql import KEY_query, KEY_parameters
 
 
 class JAAQLController(BaseJAAQLController):
@@ -171,16 +174,26 @@ class JAAQLController(BaseJAAQLController):
             return self.model.fetch_user_registries_for_tenant(http_inputs)
 
         @self.publish_route('/oidc-redirect-url', DOCUMENTATION__oidc_redirect_url)
-        def fetch_redirect_url(http_inputs: dict, response: JAAQLResponse):
-            self.model.fetch_redirect_uri(http_inputs, response)
+        def fetch_redirect_url(http_inputs: dict, response: JAAQLResponse, request_headers=None, ip_address=None):
+            self.model.fetch_redirect_uri(http_inputs, response, request_headers=request_headers, ip_address=ip_address)
 
         @self.publish_route(ENDPOINT__oidc_get_token, DOCUMENTATION__oidc_exchange_code)
         def exchange_auth_code(http_inputs: dict, ip_address: str, response: JAAQLResponse):
             try:
                 self.model.exchange_auth_code(http_inputs, request.cookies.get(COOKIE_OIDC), ip_address, response)
-            except:  # Sometimes this can fail when the user didn't exist before
+            except Exception as e:
+                import traceback
+                traceback.print_exc()
+                print(f"OIDC code exchange failed: {e}")
+                # Redirect to the saved return URL if available (survives OIDC cookie consumption),
+                # otherwise fall back to the app root
+                return_url = request.cookies.get(COOKIE_OIDC_RETURN)
                 response.response_code = HTTPStatus.FOUND
-                response.raw_headers["Location"] = self.model.url.replace("_", "localhost")
+                response.raw_headers["Location"] = return_url if return_url else self.model.url.replace("_", "localhost")
+
+        @self.publish_route('/resend-verify-email', DOCUMENTATION__resend_verify_email)
+        def resend_verify_email(http_inputs: dict):
+            self.model.resend_verification_email(http_inputs.get("email", ""))
 
         @self.publish_route('/.well-known/jwks', DOCUMENTATION__jwks)
         def fetch_jwks():
@@ -209,3 +222,33 @@ class JAAQLController(BaseJAAQLController):
                 {"state": http_inputs["state"], "oidc_cookie": request.cookies.get(COOKIE_OIDC)},
                 response
             )
+
+        @self.publish_route(ENDPOINT__report_sentinel_error, DOCUMENTATION__report_sentinel_error, True)
+        def report_sentinel_error(http_inputs: dict, ip_address: str):
+            # Public error-reporting endpoint, moved here from the deprecated jaaql-sentinel-middleware.
+            # MUST NEVER return a 500: a 500 makes JAAQL self-report (SENTINEL_URL=_) and recurse.
+            ins_error = (
+                "insert into error (location, source_file, user_agent, ip_address, error_condensed, stacktrace, "
+                "file_line_number, file_col_number, version, source_system) "
+                "VALUES (:location, :source_file, #user_agent, #ip_address, left(:error_condensed, 200), :stacktrace, "
+                ":file_line_number, :file_col_number, :version, :source_system) "
+                "RETURNING id::text as error_id"
+            )
+            try:
+                http_inputs["ip_address"] = ip_address  # plaintext -> #ip_address (field-level encrypted)
+                inserted = self.model.submit(
+                    {KEY_query: ins_error, KEY_parameters: http_inputs, KEY__application: "sentinel"},
+                    ROLE__dba, as_objects=True, singleton=True
+                )
+                self.model.submit(
+                    {
+                        KEY_query: 'SELECT "error.process_alert"(:id, :raw_ip_address)',
+                        KEY_parameters: {"id": inserted["error_id"], "raw_ip_address": ip_address},
+                        KEY__application: "sentinel"
+                    },
+                    ROLE__dba
+                )
+            except Exception as ex:
+                import traceback
+                traceback.print_exc()
+                raise HttpStatusException(str(ex))

jaaql/mvc/generated_queries.py

@@ -1309,6 +1309,7 @@ KG__account__sub = "sub"
 KG__account__username = "username"
 KG__account__email = "email"
 KG__account__email_verified = "email_verified"
+KG__account__created_timestamp = "created_timestamp"
 KG__account__deletion_timestamp = "deletion_timestamp"
 KG__account__provider = "provider"
 KG__account__tenant = "tenant"