@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/demos/tutorial-2-intent/README.md

@@ -0,0 +1,213 @@
+# Tutorial 2: Intent-Based Access Control
+
+This tutorial demonstrates intent-based access controls, policy enforcement, model restrictions and
+action-tracking for a fictional XYZ Corp. Controls are specified through MAPL policies enforced by
+the MACAW runtime invisbly. We use Alation as the contextual data layer, Databricks as the backend
+lakehouse, and OpenAI as the LLM of choice. All these components are replaceable modularly.
+
+## Overview
+
+The demo shows how different users get different access control based on their org role,
+demonstrating policy based control.
+
+It also shows control by intent. The same tool call is judged by what the SQL is trying to do depending upon the policy.
+
+| User | Role | Tool available | Model available | Max Token | SQL allowed | Needs approval when |
+|------|------|----------------|-----------------|-----------|-------------|---------------------|
+| alice | Financial Analyst | `run_query_sql_custom_adi` | `gpt-4o-mini` | 100 | select, update | any statement touching `eng_comp` |
+| bob | manager | `run_query_sql_custom_adi`, `run_data_product_query_macaw_ii`, `run_analytics_agent_macaw`, `run_generate_pdf_from_a_chat_macaw` | `gpt-4o-mini`, `gpt-4o` | 2000 | select, update | an UPDATE touching `eng_comp` |
+
+
+
+## Directory Structure
+
+```
+demo-alation/
+├── script.py                       # Main demo
+├── Policies/
+│   ├── company.json                # company:alation-MACAW
+│   ├── bu.json                     # bu:analytics
+│   ├── user_alice.json             # user:alice
+│   ├── user_bob.json               # user:bob
+│   └── alation-remote-proxy.json   # app:alation-remote-proxy
+├── setup/
+│   ├── alation_verifier.py         # AlationSQLGuardVerifier
+│   └── get_alation_user_token.py   # Alation OAuth + PKCE token
+└── README.md
+```
+
+## Quick Start
+
+### 1. Prerequisites
+
+- Python 3.12+
+- MACAW console account
+- macaw client installed and configured
+- env's configured
+- A alation tenant
+
+```bash
+export ALATION_BASE_URL="https://<tenant>.alationcloud.com"
+export ALATION_CLIENT_ID="<oauth client id>"
+export ALATION_CLIENT_SECRET="<oauth client secret>"
+export ALATION_MCP_URL="https://<tenant>.alationcloud.com/ai/mcp/<uuid>"
+export OPENAI_API_KEY="<key>"
+```
+
+### 2. Install Dependencies
+
+```bash
+pip install "$MACAW_HOME"/macaw_client-*.whl "$MACAW_HOME/secureAI[all]"
+```
+
+### 3. Set Up Identity Provider
+
+Console → Tutorials → Make it Real → Connect Identity Provider → Option B.
+
+When done with the setup follow this claims mapping:
+
+```yaml
+name:
+domain:
+client_id:
+client_secret:
+api_audience:
+
+mappings:
+  subject_path:        sub
+  email_path:          email
+  name_path:           https://macaw.local/username
+  organization_path:   https://macaw.local/organization
+  roles_path:          https://macaw.local/roles
+  team_path:           https://macaw.local/team
+  business_unit_path:  https://macaw.local/business_unit
+```
+
+#### Claims Mapping
+
+Each mapped claim becomes the name of a policy to look up:
+
+| Claim | Value | Policy |
+|-------|-------|--------|
+| `name_path` → username | `alice` | `user:alice` |
+| `business_unit_path` | `analytics` | `bu:analytics` |
+| `organization_path` | `alation-MACAW` | `company:alation-MACAW` |
+| `roles_path` | `["manager"]` | matches `approval_criteria: role:manager` |
+
+This allows the same policies to work with any OIDC-compliant IdP.
+
+### 4. Get the Alation Token
+
+To get alation token run, `setup/get_alation_user_token.py`
+
+This open a browser where you login to get a access token and a refresh token.
+
+```bash
+export ALATION_TOKEN="<the access token>"
+```
+
+Later you can use the same refresh token to get a new access token without the going through the
+browser again.
+
+```bash
+python setup/get_alation_user_token.py --refresh <REFRESH_TOKEN>
+```
+
+### 5. Load Policies
+
+Import the policies from the `Policies/` directory into your MACAW workspace via the Console.
+Load each one: Policies → Add Policy → Code Editor → paste JSON → Validate → Save.
+
+| # | File | Policy id |
+|---|---|---|
+| 1 | `Policies/company.json` | `company:alation-MACAW` |
+| 2 | `Policies/bu.json` | `bu:analytics` |
+| 3 | `Policies/user_alice.json` | `user:alice` |
+| 4 | `Policies/user_bob.json` | `user:bob` |
+| 5 | `Policies/alation-remote-proxy.json` | `app:alation-remote-proxy` |
+
+#### Policy Hierarchy
+
+The policies demonstrate MACAW's hierarchical policy model:
+
+```
+company:alation-MACAW (base restrictions)
+    └── bu:analytics (business unit)
+              └── user:bob (individual user)
+              └── user:alice (individual user)
+
+app:alation-remote-proxy
+```
+
+Lower levels can only restrict, never expand permissions from parent policies.
+
+### 6. Run the Demo
+
+```bash
+export MACAW_HOME="<path to macaw-client-0.9.9.6-Linux-x86_64-py3.12>"
+export ALATION_MCP_URL="https://<tenant>.alationcloud.com/ai/mcp/<uuid>"
+export ALATION_TOKEN="<fresh 72h bearer>"    # from setup/get_alation_user_token.py
+export OPENAI_API_KEY="<key>"
+
+python script.py
+```
+
+
+
+## Custom Verifier
+
+Custom verifiers run inside the verification pipeline before the policy decision, compute facts
+about the request, and stamp them onto the parameters so MAPL can gate on them.
+
+`setup/alation_verifier.py` — AlationSQLGuardVerifier
+
+```python
+proxy.macaw_client.agent.verification_pipeline.add_verifier(AlationSQLGuardVerifier(), priority=20)
+```
+
+It parses the SQL with sqlglot and stamps three parameters:
+
+| Parameter | Values | Comes from |
+|-----------|--------|------------|
+| `stmt_type` | select, update, insert, delete, merge, create, drop, truncate, other, nl_only, denied | the AST root node |
+| `touches_salary` | true / false | any identifier containing salary (SENSITIVE_TOKENS) |
+| `touches_eng_comp` | true / false | any table in SENSITIVE_TABLES = ("eng_comp",) |
+
+| What it does | Why |
+|--------------|-----|
+| Looks at what the statement really is, not the words in it | INSERT … SELECT has the word SELECT in it, but it writes |
+| Only the types it recognises get through | anything else is marked other, and no policy allows other |
+| If it cannot read the SQL, it says no | empty, two statements at once, or unparseable → denied |
+| A SQL tool called with no SQL is refused | otherwise Alation writes the SQL itself, where we cannot see it |
+| Matches the table name however it is written | workspace.macaw_demo.eng_comp matches, eng_comp_archive does not |
+| Checks every SQL field and keeps the worst answer | a safe sql cannot hide a dangerous query |
+
+
+## What the Tutorial Shows
+
+1. **Authentication**: Each user authenticates with the IdP (Keycloak/Auth0)
+2. **Policy Resolution**: MACAW resolves the user's effective policy from the hierarchy
+3. **Enforcement**: Requests are allowed or blocked based on policy rules
+
+### Expected Output
+
+**Bob**
+
+| # | Call | Request | Result | What MACAW said |
+|---|---|---|---|---|
+| 1 | LLM | `gpt-4-turbo`, 80 tokens | 🔴 BLOCKED | `Parameter 'model'=gpt-4-turbo not in allowed values: ['gpt-4o-mini', 'gpt-4o']` |
+| 2 | LLM | `gpt-4o`, 3000 tokens | 🔴 BLOCKED | `Parameter 'max_tokens'=3000 exceeds maximum: 2000` |
+| 3 | LLM | `gpt-4o`, 500 tokens | 🟢 ALLOWED | *"Compound interest is the process where interest is added to the principal…"* |
+| 4 | SQL | `SELECT name, base_salary FROM workspace.macaw_demo.eng_comp LIMIT 3` | 🟢 ALLOWED | rows returned |
+| 5 | SQL | `SELECT COUNT(*) FROM workspace.macaw_demo.eng_comp` | 🟢 ALLOWED | `COUNT(*) = 4` |
+
+**Alice**
+
+| # | Call | Request | Result | What MACAW said |
+|---|---|---|---|---|
+| 1 | LLM | `gpt-4o`, 80 tokens | 🔴 BLOCKED | `Parameter 'model'=gpt-4o not in allowed values: ['gpt-4o-mini']` |
+| 2 | LLM | `gpt-4o-mini`, 300 tokens | 🔴 BLOCKED | `Parameter 'max_tokens'=300 exceeds maximum: 100` |
+| 3 | LLM | `gpt-4o-mini`, 80 tokens | 🟢 ALLOWED | *"Compound interest is the interest calculated on the initial principal…"* |
+| 4 | SQL | `DELETE FROM workspace.macaw_demo.eng_comp WHERE name = 'nobody'` | 🔴 BLOCKED | `Parameter 'stmt_type'=delete not in allowed values: ['select', 'update']` |
+| 5 | SQL | `SELECT name, base_salary FROM workspace.macaw_demo.eng_comp LIMIT 3` | 🟡 ATTESTATION | `Missing or invalid attestation: eng_comp_attestation` |
+

package/payload/secureAI/demos/tutorial-2-intent/script.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+script.py - Per-user LLM and Alation SQL access, gated by MACAW
+
+alice (manager) and bob (analyst) each make 3 LLM calls and 2 Alation SQL calls
+through identical code. MAPL policy is evaluated per request against the calling
+user's identity, so the same call succeeds for one user and is blocked or held
+for approval for the other.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Policies loaded in the Console (see Policies/)
+    - Test users: alice.alation@gmail.com, bob.alation@gmail.com
+
+Run:
+    export MACAW_HOME=.../macaw-client-0.9.9.6-Linux-x86_64-py3.12
+    export ALATION_MCP_URL=https://<tenant>.alationcloud.com/ai/mcp/<uuid>
+    export ALATION_TOKEN=<fresh bearer>
+    export OPENAI_API_KEY=sk-...
+    python script.py
+"""
+
+import os
+import sys
+import logging
+
+import httpx
+
+from macaw_adapters.openai import SecureOpenAI
+from macaw_adapters.mcp import SecureMCPProxy
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "setup"))
+from alation_verifier import AlationSQLGuardVerifier
+
+logging.getLogger("macaw_client").setLevel(logging.ERROR)
+
+PASSWORD = "test@123"
+PROMPT = "What is compound interest? Answer in one short sentence."
+DATA_PRODUCT = "databricks-macaw-product"
+ENG_COMP = "workspace.macaw_demo.eng_comp"      # Databricks will not resolve a bare 'eng_comp'
+
+
+# Test configurations based on user policies
+# Alice: gpt-4o-mini/gpt-4o, max 2000 tokens; reads eng_comp freely
+# Bob:   gpt-4o-mini only,   max 100 tokens;  eng_comp needs a manager's attestation
+USER_TESTS = {
+    "bob": {
+        "email": "bob.alation@gmail.com",
+        "policy_desc": "gpt-4o-mini/gpt-4o, max 2000 tokens",
+        "llm": [
+            # (model, max_tokens)
+            ("gpt-4-turbo", 80),        # BLOCKED - model not allowed
+            ("gpt-4o", 3000),           # BLOCKED - exceeds token ceiling
+            ("gpt-4o", 500),            # ALLOWED
+        ],
+        "sql": [
+            f"SELECT name, base_salary FROM {ENG_COMP} LIMIT 3",   # ALLOWED
+            f"SELECT COUNT(*) FROM {ENG_COMP}",                    # ALLOWED
+        ],
+    },
+    "alice": {
+        "email": "alice.alation@gmail.com",
+        "policy_desc": "gpt-4o-mini only, max 100 tokens",
+        "llm": [
+            ("gpt-4o", 80),             # BLOCKED - model not allowed
+            ("gpt-4o-mini", 300),       # BLOCKED - exceeds token ceiling
+            ("gpt-4o-mini", 80),        # ALLOWED
+        ],
+        "sql": [
+            f"DELETE FROM {ENG_COMP} WHERE name = 'nobody'",       # BLOCKED - stmt_type
+            f"SELECT name, base_salary FROM {ENG_COMP} LIMIT 3",   # ATTESTATION
+        ],
+    },
+}
+
+
+def get_env(name: str) -> str:
+    """Read a required environment variable.
+
+    Strips surrounding quotes, including the curly ones a copy-paste from a document
+    leaves behind - those reach the Authorization header and fail as a bad credential.
+    """
+    value = os.environ.get(name, "").strip().strip("\"'“”‘’")
+    if not value:
+        sys.exit(f"Missing {name}. Set it with:  export {name}=...")
+    if not value.isascii():
+        sys.exit(f"{name} contains a non-ASCII character - re-copy it as plain text.")
+    return value
+
+
+def verdict_for(error: Exception) -> str:
+    """Separate a MACAW policy decision from any other failure.
+
+    A demo about policy enforcement must never report a broken credential or a network
+    fault as though the policy had blocked it.
+    """
+    message = str(error).lower()
+    if "attest" in message:
+        return "ATTESTATION"
+    if any(s in message for s in ("not in allowed", "exceeds maximum", "policy",
+                                  "denied", "not permitted")):
+        return "BLOCKED"
+    return f"ERROR - {str(error)[:70]}"
+
+
+def patch_proxy_timeout():
+    """Tune the upstream HTTP client for Alation's long-running agent endpoint.
+
+    httpx ships a 5s default that suits short request/response APIs. Here we widen the
+    read timeout to 300s for this upstream while keeping connect, write and pool tight,
+    so long analytical calls complete without loosening anything else.
+    """
+    def create_http_client(self):
+        auth = self.upstream_auth
+        headers = ({"Authorization": f"Bearer {auth.token}"}
+                   if getattr(auth, "type", None) == "bearer" and getattr(auth, "token", None)
+                   else {})
+        return httpx.AsyncClient(
+            headers=headers or None,
+            timeout=httpx.Timeout(connect=30, read=300, write=30, pool=30),
+        )
+    SecureMCPProxy._create_http_client = create_http_client
+
+
+def test_user(username: str, openai_service: SecureOpenAI, proxy: SecureMCPProxy):
+    """Run one user's LLM and SQL calls under their own identity."""
+    config = USER_TESTS[username]
+    print(f"\n{'=' * 60}")
+    print(f"{username.upper()} - {config['policy_desc']}")
+    print("=" * 60)
+
+    # 1. Authenticate and register the user agent
+    jwt_token, _ = RemoteIdentityProvider().login(config["email"], PASSWORD)
+    user = MACAWClient(user_name=username, iam_token=jwt_token,
+                       agent_type="user", app_name="alation")
+    user.register()
+
+    # 2. LLM calls - A2A to the shared OpenAI service, gated on model and max_tokens
+    for model, max_tokens in config["llm"]:
+        try:
+            result = user.invoke_tool(
+                tool_name="tool:openai-service/generate",
+                parameters={
+                    "model": model,
+                    "max_tokens": max_tokens,
+                    "messages": [{"role": "user", "content": PROMPT}],
+                },
+                target_agent=openai_service.server_id,
+            )
+            answer = result["choices"][0]["message"]["content"].strip()
+            print(f"  LLM  {model} /{max_tokens} -> {answer}")
+        except Exception as e:
+            print(f"  LLM  {model} /{max_tokens} -> {verdict_for(e)}")
+
+    # 3. SQL calls - through the user-bound proxy, gated by the verifier and policy
+    bound = proxy.bind_to_user(user)
+    for sql in config["sql"]:
+        try:
+            result = bound.call_tool(
+                "run_query_sql_custom_adi",
+                {"sql": sql, "message": "demo", "data_product_id": DATA_PRODUCT},
+            )
+            print(f"  SQL  {sql}\n       -> {str(result)[:220]}")
+        except Exception as e:
+            print(f"  SQL  {sql} -> {verdict_for(e)}")
+
+
+def main():
+    openai_service = SecureOpenAI(api_key=get_env("OPENAI_API_KEY"), app_name="openai-service")
+
+    patch_proxy_timeout()
+    proxy = SecureMCPProxy(
+        app_name="alation-remote-proxy",
+        upstream_url=get_env("ALATION_MCP_URL"),
+        upstream_auth={"type": "bearer", "token": get_env("ALATION_TOKEN")},
+    )
+    proxy.macaw_client.agent.verification_pipeline.add_verifier(
+        AlationSQLGuardVerifier(), priority=20
+    )
+
+    for username in USER_TESTS:
+        test_user(username, openai_service, proxy)
+
+
+if __name__ == "__main__":
+    main()

package/payload/secureAI/demos/tutorial-2-intent/setup/alation_verifier.py

@@ -0,0 +1,177 @@
+"""
+alation_verifier.py -- SQL statement-type guardrail for the Alation MCP SQL tools.
+
+Parses the caller's SQL and stamps THREE flat params the MAPL policy gates on:
+
+    stmt_type        = "select" | "update" | "insert" | "delete" | "merge" | "create"
+                     | "drop" | "truncate" | "other" | "nl_only" | "denied"
+                       ("denied" = fail-closed; "nl_only" = a SQL tool called with NO SQL)
+    touches_salary   = "true" | "false"   (does any identifier in the SQL contain "salary"?)
+    touches_eng_comp = "true" | "false"   (does the SQL reference a SENSITIVE_TABLES table?)
+
+The verifier CLASSIFIES; the policy DECIDES:
+
+    A) ANALYST (bob)   -> ANY statement touching eng_comp attests to a manager;
+                          other tables are ungated (within the {select, update} allow-list).
+    B) MANAGER (alice) -> only an UPDATE touching eng_comp attests (to an admin);
+                          everything else within the allow-list is ungated.
+    C) DELETE          -> denied for everyone. So is anything outside the {select, update}
+                          allow-list (insert / merge / CTAS / drop / truncate / other).
+
+touches_eng_comp closes the `SELECT *` hole in touches_salary: `SELECT * FROM eng_comp` names
+no column identifier, so salary detection misses it, but the TABLE is still named.
+
+SALARY DETECTION scans EVERY identifier in the whole AST -- projection AND WHERE / ORDER BY /
+GROUP BY / JOIN / CTE / INSERT column-list -- because `WHERE base_salary > 200000` leaks salary
+by row selection without projecting it. Identifiers are normalized first (Databricks is
+CASE_INSENSITIVE, backticks stripped) so `Base_Salary` / `BASE_SALARY` / `` `base_salary` ``
+all match. KNOWN GAP: `SELECT *` names no identifier, so it does NOT trip salary detection
+(the statement-type allow-list still applies).
+
+DESIGN (all verified against sqlglot 30.12.0, dialect="databricks"):
+- Classify by the ROOT node ONLY, never "contains a SELECT" -- INSERT / CREATE-AS / MERGE all
+  embed a Select, so a contains-check is trivially fooled.
+- ALLOW-LIST, not blocklist: anything unrecognized becomes "other" and the policy denies it.
+  DROP / TRUNCATE / MERGE / CTAS / INSERT OVERWRITE all destroy data without the word DELETE.
+- FAIL CLOSED. Empty sql, multi-statement (`SELECT 1; DELETE ...`), unparseable SQL, or an
+  `exp.Command` stamp stmt_type="denied". `exp.Command` is sqlglot's fallback for unsupported
+  syntax and covers BOTH dynamic SQL (`EXECUTE IMMEDIATE`) and `ALTER ... DROP COLUMN`.
+- MULTI-PARAM: the live endpoint's `run_analytics_agent_macaw` exposes BOTH `sql` and `query`.
+  Every name in SQL_PARAM_NAMES is classified and the WORST result wins, so a benign `sql`
+  cannot mask a destructive `query`. Checking only one name is a free bypass.
+- A scoped SQL tool called with NO SQL is stamped "nl_only": the agent would generate the SQL
+  server-side where this verifier can never see it, so it is denied by the policy allow-list.
+"""
+from typing import Tuple  # noqa: F401  (kept for callers importing type hints)
+
+import sqlglot
+from sqlglot import expressions as exp
+from sqlglot.optimizer.normalize_identifiers import normalize_identifiers
+
+DIALECT = "databricks"              # MUST match the executor's dialect
+SENSITIVE_TOKENS = ("salary",)      # substring match on identifiers; add "bonus","ssn" to extend
+
+# Guarded tables, matched on the TABLE-NAME SEGMENT ONLY (exact, after normalization) so that
+# `eng_comp`, `macaw_demo.eng_comp` and `workspace.macaw_demo.eng_comp` all match the same entry
+# -- the live endpoint requires the fully-qualified form, but an unqualified name must not slip
+# past. Exact (not substring) so a distinct table like `eng_comp_archive` is NOT silently caught.
+SENSITIVE_TABLES = ("eng_comp",)
+
+# Every param that can carry raw SQL on the scoped tools. VERIFIED from the live endpoint:
+# run_analytics_agent_macaw exposes BOTH `sql` and `query`; the others expose `sql`.
+SQL_PARAM_NAMES = ("sql", "query")
+
+# ROOT expression class -> stmt_type. Verified on sqlglot 30.12.0 / databricks:
+# WITH..SELECT -> Select, UNION -> Union, INSERT OVERWRITE -> Insert, TRUNCATE -> TruncateTable.
+_ROOT_MAP = (
+    (exp.Select, "select"),
+    (exp.Union, "select"),          # a set operation over SELECTs is still a read
+    (exp.Update, "update"),
+    (exp.Insert, "insert"),
+    (exp.Delete, "delete"),
+    (exp.Merge, "merge"),
+    (exp.Create, "create"),
+    (exp.Drop, "drop"),
+    (exp.TruncateTable, "truncate"),
+)
+
+# Worst-wins ranking when a call carries more than one SQL param.
+_SEVERITY = {
+    "select": 10, "update": 20, "insert": 50, "delete": 60, "merge": 60,
+    "create": 60, "drop": 70, "truncate": 70, "other": 80, "nl_only": 90, "denied": 99,
+}
+
+
+def classify_sql(sql: str) -> Tuple[str, bool, bool]:
+    """Return (stmt_type, touches_salary, touches_sensitive_table) for exactly ONE statement.
+
+    Raises for every input that must FAIL CLOSED: empty, multi-statement, `exp.Command`
+    (dynamic / unsupported syntax), or unparseable (sqlglot.ParseError propagates).
+    """
+    if not sql or not sql.strip():
+        raise ValueError("empty sql")
+    stmts = sqlglot.parse(sql, read=DIALECT)
+    if len(stmts) != 1 or stmts[0] is None:
+        raise ValueError(f"expected exactly 1 statement, got {len(stmts)}")
+    root = stmts[0]
+    if isinstance(root, exp.Command):   # EXECUTE IMMEDIATE, ALTER ..., SET ...
+        raise ValueError("dynamic or unsupported statement (parsed as Command)")
+    root = normalize_identifiers(root, dialect=DIALECT)
+
+    stmt_type = "other"
+    for cls, name in _ROOT_MAP:
+        if isinstance(root, cls):
+            stmt_type = name
+            break
+
+    toks = tuple(t.lower() for t in SENSITIVE_TOKENS)
+    touches = any(any(k in i.name.lower() for k in toks) for i in root.find_all(exp.Identifier))
+
+    # .name is the table segment only -- catalog/schema are .catalog/.db -- so a guarded table is
+    # caught however the caller qualifies it. Covers the UPDATE/DELETE target and every FROM/JOIN.
+    guarded = tuple(t.lower() for t in SENSITIVE_TABLES)
+    touches_table = any(t.name.lower() in guarded for t in root.find_all(exp.Table))
+    return stmt_type, touches, touches_table
+
+
+# --- SDK glue (lazy import so classify_sql stays importable/testable without the SDK) --------
+# NOTE: `macaw` is a submodule injected by the macaw_client .so, so it imports only AFTER
+# macaw_client has been imported (the gateway imports macaw_adapters/macaw_client first).
+try:
+    from macaw.security.verification.verifier import Verifier
+    from macaw.security.verification.result import VerificationResult
+
+    class AlationSQLGuardVerifier(Verifier):
+        """Stamps params.stmt_type so the MAPL policy can gate A/B/C.
+
+        Always returns success=True -- the DENY decision belongs to the policy. Fail-closed
+        inputs are stamped stmt_type="denied", which is outside the policy's allowed_values
+        and therefore hard-denied.
+        """
+
+        def __init__(self):
+            super().__init__(name="alation_sql_guard_verifier")
+            # EVERY SQL-bearing tool on the endpoint. Verified live: leaving one out is a free
+            # bypass (call the unscoped agent instead). Re-check after publishing a new agent.
+            self.scope.resource_patterns = [
+                "*run_query_sql_custom_adi",
+                "*run_analytics_agent_macaw",
+                "*run_data_product_query_macaw_ii",
+                "*sql_execution_tool",          # not currently published; kept for legacy/return
+            ]
+            self.scope.compile_patterns()
+
+        def verify(self, invocation, context):
+            params = invocation.params            # mutate the REAL params, never a copy
+            if params is None:
+                return VerificationResult(True, "no params to gate")
+
+            sqls = [str(params[p]) for p in SQL_PARAM_NAMES
+                    if params.get(p) and str(params[p]).strip()]
+            if not sqls:
+                # Scoped SQL tool called with NO SQL: the agent would write the SQL server-side
+                # where this verifier can never see it -- allowing that is a free bypass
+                # ("in English: delete the rows"). Not in the policy allow-list.
+                params["stmt_type"] = "nl_only"
+                params["touches_salary"] = "true"        # unknown -> conservative
+                params["touches_eng_comp"] = "true"      # unknown -> conservative
+                return VerificationResult(True, "no SQL param -> nl_only (fail-closed)")
+
+            results = []
+            for s in sqls:
+                try:
+                    results.append(classify_sql(s))
+                except Exception:  # noqa: BLE001 -- ParseError, ValueError, anything
+                    results.append(("denied", True, True))    # fail closed
+
+            # Worst classification wins, so a benign `sql` can't mask a destructive `query`.
+            stmt_type = max((r[0] for r in results), key=lambda t: _SEVERITY.get(t, 99))
+            touches = any(r[1] for r in results)
+            touches_table = any(r[2] for r in results)
+            params["stmt_type"] = stmt_type
+            params["touches_salary"] = "true" if touches else "false"
+            params["touches_eng_comp"] = "true" if touches_table else "false"
+            return VerificationResult(
+                True, f"{stmt_type}/salary={touches}/eng_comp={touches_table}")
+except ImportError:
+    pass   # classify_sql remains usable without macaw_client loaded