maskcloud 0.1.0__tar.gz

maskcloud-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

maskcloud-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13.3

maskcloud-0.1.0/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 2026 Mask AI Solutions
+
+   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.

maskcloud-0.1.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: maskcloud
+Version: 0.1.0
+Summary: Just-In-Time Privacy Middleware for AI Agents. Format-preserving encryption with pluggable vault backends.
+Author: Mask AI Solutions
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,encryption,fpe,hipaa,llm,pii,privacy,soc2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: presidio-analyzer>=2.2.361
+Requires-Dist: presidio-anonymizer>=2.2.361
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: adk
+Requires-Dist: google-adk>=1.0; extra == 'adk'
+Provides-Extra: all
+Requires-Dist: boto3>=1.34; extra == 'all'
+Requires-Dist: google-adk>=1.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2; extra == 'all'
+Requires-Dist: llama-index-core>=0.10; extra == 'all'
+Requires-Dist: pymemcache>=4.0; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: spacy>=3.4.4; extra == 'all'
+Provides-Extra: dynamodb
+Requires-Dist: boto3>=1.34; extra == 'dynamodb'
+Provides-Extra: examples
+Requires-Dist: fastapi>=0.111; extra == 'examples'
+Requires-Dist: httpx>=0.27; extra == 'examples'
+Requires-Dist: litellm>=1.74; extra == 'examples'
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Requires-Dist: redis>=5.0.0; extra == 'examples'
+Requires-Dist: uvicorn>=0.30; extra == 'examples'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
+Provides-Extra: memcached
+Requires-Dist: pymemcache>=4.0; extra == 'memcached'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: spacy
+Requires-Dist: spacy>=3.4.4; extra == 'spacy'
+Description-Content-Type: text/markdown
+
+# Mask: Just-in-Time AI Agent Security
+
+Contact: millingtonsully@gmail.com
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Mask is an enterprise-grade AI Data Loss Prevention (DLP) infrastructure. It acts as the runtime enforcement layer between your Large Language Models (LLMs) and your active tool execution environment, ensuring that LLMs never see raw PII or sensitive financial records, while maintaining flawless functional execution for the end user.
+
+---
+
+## The Problem Space: LLM Data Leakage
+
+As Large Language Model (LLM) agents gain autonomy, they become deeply integrated into enterprise systems, often requiring access to highly sensitive information such as Personally Identifiable Information (PII) and confidential financial records.
+
+The core vulnerability in standard agentic architectures is that sensitive data retrieved by tools is injected as plain-text directly into the LLM's context window. This creates severe compliance and security risks:
+- **Data Leakage:** Plain-text PII can be logged by external LLM providers, violating data residency laws or compliance frameworks (SOC2, HIPAA, PCI-DSS).
+- **Inadvertent Disclosure:** If an agent is compromised via prompt injection or malicious instructions, it can be manipulated into exfiltrating the plain-text data it actively holds in its context.
+
+## The Solution: Privacy by Design
+
+Mask utilizes a **Two-Layer Strategy** to solve the data leakage problem, splitting responsibilities between a local runtime environment (The Data Plane) and a centralized governance platform (The Control Plane).
+
+Instead of trusting the LLM to safeguard plain-text data, the system strictly enforces cryptographic boundaries using **Just-In-Time (JIT) Encryption and Decryption Middleware**. 
+1. The LLM only ever "sees" and reasons over scrambled, encrypted cyphertext.
+2. When the LLM decides to call a specific authorized tool (e.g., querying a database), a **Pre-Tool Decryption Hook** intercepts the call. It decrypts the specific parameters required by the tool, allowing the backend function to execute securely with real data.
+3. Once the tool finishes, a **Post-Tool Encryption Hook** instantly intercepts the output, detects sensitive entities, and encrypts them *before* the result is returned to the LLM's analytical context block.
+
+This guarantees that the LLM can orchestrate workflows involving sensitive data without ever actually exposing the raw data to the model or its remote provider logs. 
+
+Additionally, we solve two critical sub-issues to make this enterprise-ready:
+1. **The Statefulness Trap**: Traditional "vaults" break down in multi-node Kubernetes environments. We support pluggable distributed vaults (Redis, DynamoDB, Memcached) so detokenization state is instantly shared across all your horizontally scaled pods.
+2. **The Schema Trap**: Strict downstream tools will crash if handed a random token. We use Format-Preserving Tokenization backed by an encrypted vault to generate tokens that retain the exact format of the original data (Emails, US Phones, SSNs, 16-digit Credit Cards, 9-digit Routing Numbers). Tokens look like real data; the real values are stored encrypted and retrieved via the vault.
+
+### How We Handle Data
+
+*   **If the LLM needs to think about the value:** We tokenize it so the LLM only sees a fake-looking value, and we keep the real value encrypted in a vault.
+*   **If something is so sensitive that the LLM should never see it at all:** A future version will support skipping the LLM entirely for that field and only sending it to tools/backends.
+
+Real math and real business logic always happen inside tools, after detokenization and decryption, not inside the LLM on fake numbers.
+
+---
+
+## Architectural Overview
+
+### 1. The Data Plane (Mask Open Source SDK)
+The Data Plane is the open-source, transparent, auditable runtime execution layer. It lives inside your secure VPC or Kubernetes clusters alongside your AI agents. It acts as the Trojan Horse of security, providing frictionless adoption for engineers while proving cryptographic soundness to security reviewers.
+
+*   **JIT Cryptography Engine:** The core pre-tool decryption and post-tool encryption hooks that intercept and mutate data in-flight.
+*   **Format-Preserving Tokenization Router:** Ensures downstream databases and strict schemas don't break when handed a token. Tokens look like real data; the real values are stored encrypted and retrieved via the vault.
+*   **Pluggable Distributed Vaults:** Support for enterprise-native caching layers (Redis, DynamoDB, Memcached) to ensure horizontally-scaled edge agents have synchronized access to detokenization mapping.
+*   **Telemetry Remote Forwarder:** An asynchronous AuditLogger that buffers privacy events and securely POSTs them to the Control Plane API without blocking LLM execution.
+
+### 2. The Control Plane (Mask Enterprise Platform)
+The Control Plane is our active Enterprise SaaS offering—a centralized governance platform for security orchestration. Coming soon.
+
+The Control Plane manages:
+*   **Unified Dashboard:** Visualizes usage and storage metrics across your environment.
+*   **Tenant & API Key Management:** Manage API keys and role-based access control for isolated environments.
+*   **Vault Configuration UI:** Provision and monitor our managed, hosted vaults. We offer Ephemeral Memory Vaults cleared daily, and highly available Persistent Vaults with customizable retention policies based on your subscription tier.
+*   **Audit Log Viewer:** Explore telemetry events and generate one-click compliance reports for SOC2, HIPAA, and PCI-DSS.
+*   **Key Management Center:** Automate rotation of symmetric encryption keys and track key status without relying on static local environment variables.
+*   **Billing & Subscriptions:** Transparent tracking of Protected Entities and metered overage.
+
+---
+
+## Advanced Architecture & Security Guarantees
+
+While Mask can be run globally via environment variables, the underlying SDK is highly sophisticated and designed for multi-tenant, zero-trust environments.
+
+### 1. Deterministic Token Deduplication
+Mask vaults use cryptographic hashing to perform reverse-lookups during tokenization. If the LLM generates a prompt containing the same email address 50 times in a single session, Mask retrieves and re-uses the *exact same Format-Preserving Token*. This mathematically prevents vault storage bloat, accelerates encryption performance, and crucially, prevents the LLM from hallucinating due to seeing inconsistent tokens for the same underlying entity.
+
+### 2. The Explicit `MaskClient` API
+For enterprise backend services handling multiple tenants at once, global singletons (environment configurations) are dangerous. Mask natively supports explicit client instantiation. Developers can isolate vaults, crypto engines, and NLP scanners on a per-request basis.
+
+```python
+from mask.client import MaskClient
+from mask.core.vault import MemoryVault
+from mask.core.crypto import CryptoEngine
+
+# Fully isolated instance for strict multi-tenancy
+client = MaskClient(
+    vault=MemoryVault(),
+    crypto=CryptoEngine(tenant_specific_key),
+    ttl=3600
+)
+
+safe_token = client.encode("user@tenant.com")
+```
+
+### 3. Heuristic Safety mathematically guaranteed
+It is catastrophic if an SDK misidentifies a user's *real* SSN as a "token" and accidentally passes it in plaintext to an LLM. Mask's `looks_like_token()` heuristic algorithm strictly uses universally invalid prefixes. 
+* SSN tokens always begin with `000` (The Social Security Administration has never issued an Area Number of 000).
+* Routing tokens always begin with `0000` (The Federal Reserve valid range starts at 01).
+* Credit Card tokens use the `4000-0000-0000` Visa reserved test BIN. 
+By generating statistically impossible tokens, Mask guarantees it will never accidentally swallow real PII.
+
+---
+
+## Installation and Setup
+
+Install the Data Plane core SDK. Core features require cryptography and Presidio; Redis/Dynamo/Memcached/LangChain/LlamaIndex/ADK remain optional extras:
+```bash
+pip install maskcloud
+```
+
+Add optional extras depending on your infrastructure and framework:
+```bash
+pip install "maskcloud[redis]"       # For Redis vaults
+pip install "maskcloud[dynamodb]"    # For AWS DynamoDB vaults
+pip install "maskcloud[memcached]"   # For Memcached vaults
+pip install "maskcloud[langchain]"   # For LangChain hooks
+pip install "maskcloud[llamaindex]"  # For LlamaIndex hooks
+pip install "maskcloud[adk]"         # For Google ADK hooks
+```
+
+
+### Installing AI Models
+Mask uses powerful NLP engines for PII detection. Install the `spacy` extra and then download your preferred model:
+```bash
+# 1. Install with spaCy support
+pip install "maskcloud[spacy]"
+
+# 2. Download the NLP model (choose one)
+python -m spacy download en_core_web_sm  # Small (~12MB, Fast)
+python -m spacy download en_core_web_md  # Standard (~40MB, Balanced)
+python -m spacy download en_core_web_lg  # Large (~560MB, High Accuracy)
+```
+
+For a typical production environment, you might combine extras:
+```bash
+pip install "maskcloud[spacy,redis]"
+python -m spacy download en_core_web_lg
+```
+
+
+### Environment Configuration
+
+Before running your agents, Mask requires an encryption key and a vault backend selection.
+
+```bash
+# 1. Provide your encryption key
+# Generate a static key for local development:
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+export MASK_ENCRYPTION_KEY="..."
+# For Cloud Platform users, the KMS can securely distribute this upon initialization.
+
+# 2. Select your vault type
+export MASK_VAULT_TYPE=redis      # Options: memory, redis, dynamodb, memcached, cloud
+
+# 3. Configure your chosen vault backend
+# For Mask Cloud Managed Vaults:
+export MASK_API_KEY="..."
+# For self-hosted Redis:
+export MASK_REDIS_URL=redis://localhost:6379/0
+# For self-hosted DynamoDB:
+export MASK_DYNAMODB_TABLE=mask-vault
+export MASK_DYNAMODB_REGION=us-east-1
+# For self-hosted Memcached:
+export MASK_MEMCACHED_HOST=localhost
+export MASK_MEMCACHED_PORT=11211
+```
+
+For production and staging environments, `MASK_ENCRYPTION_KEY` **must** be set;
+the SDK will not start without it. The SDK is designed for single-tenant
+deployments where one global vault and key serve a single financial institution
+or environment.
+
+---
+
+## Framework Integrations
+
+Mask integrates seamlessly by injecting dynamic, recursive hooks into your agent's execution pipeline. 
+* **Pre-Hooks (Decoding)**: Scans the incoming tool arguments, looks up tokens in the Vault, and replaces them with plaintext *before* the function executes.
+* **Post-Hooks (Encoding)**: Scans data returning from the tool, encrypts any raw PII found, and hands the tokens back to the LLM.
+
+### 1. LangChain
+To protect tool outputs, you must wrap tools with MaskToolWrapper. The callback handler is for logging/audit only.
+```python
+from langchain.agents import AgentExecutor
+from mask.integrations.langchain_hooks import MaskCallbackHandler, MaskToolWrapper
+
+# Wrap your tools so arguments are automatically detokenized and outputs re-tokenized
+secure_tools = [MaskToolWrapper(my_email_tool)]
+
+# Add the callback handler (for logging/audit only)
+agent_executor = AgentExecutor(
+    agent=my_agent,
+    tools=secure_tools,
+    callbacks=[MaskCallbackHandler()]
+)
+```
+
+### 2. LlamaIndex
+Use MaskToolWrapper and/or MaskCallbackHandler to ensure inputs are detokenized and outputs are re-tokenized.
+```python
+from llama_index.core.tools import FunctionTool
+from mask.integrations.llamaindex_hooks import MaskToolWrapper
+
+# Wrap the callable directly for input detokenization and output tokenization
+secure_email_tool = FunctionTool.from_defaults(
+    fn=MaskToolWrapper(my_email_function),
+    name="send_email",
+    description="Sends a secure email"
+)
+```
+
+### 3. Google ADK
+Use decrypt_before_tool and encrypt_after_tool; they protect args and responses (strings, dicts, lists) with tokenization.
+```python
+from google.adk.agents import Agent
+from mask.integrations.adk_hooks import decrypt_before_tool, encrypt_after_tool
+
+secure_agent = Agent(
+    name="secure_assistant",
+    model=...,
+    tools=[...],
+    before_tool_callback=decrypt_before_tool, # Protects arguments
+    after_tool_callback=encrypt_after_tool,   # Protects responses
+)
+```
+
+---
+
+## Testing and Verification
+
+### The Test Suite
+The SDK is highly comprehensive and fully verified with a native `pytest` suite. It ensures cryptographic integrity, FPE format compliance, asynchronous telemetry, and distributed vault TTL expiry across all layers.
+
+#### Core Tests (`test_fpe.py`, `test_vault.py`, `test_vault_backends.py`)
+- **Format-Preserving Tokenization Integrity:** Validates that tokens preserve their original formats (e.g., emails become `tkn-<hex>@email.com`, SSNs become `000-00-<4 digits>`) to ensure downstream regex and schema validators do not break.
+- **Memory Vaults:** Verifies fundamental `store()`, `retrieve()`, `delete()`, TTL mechanics, and clean token/plaintext roundtrips via the `encode()` and `decode()` API. The public `decode()` helper is **strict** and raises on failure; callers that prefer lenient behaviour should catch `DecodeError` and fall back to the original token themselves.
+- **Distributed Vaults:** Mocks `boto3` and `pymemcache` to guarantee production-grade backends (DynamoDB and Memcached) correctly respect TTL expirations and auto-delete stale rows across distributed architectures.
+
+#### Telemetry Tests (`test_audit_logger.py`)
+- **SOC2/HIPAA Trailing:** Validates asynchronous audit event buffering.
+- **Resilience:** Proves that network timeouts (`urllib.error.URLError`) when POSTing to the Mask Control Plane are safely swallowed by the daemon thread and will *never* crash the host application.
+
+#### Framework Integrations (`test_hooks.py`, `test_langchain.py`, `test_llamaindex.py`)
+- **Recursive Scanners:** Tests `deep_decode` and `deep_encode_pii` (from `mask.core.utils`) to prove nested dictionaries/lists in JSON payloads are correctly scrubbed without mutating the underlying framework data structures.
+- **Framework specific hooks:** Validates that LangChain `MaskToolWrapper`, LlamaIndex `FunctionTool` wrappers, and Google ADK pre/post hooks correctly intercept inputs and outputs to enforce the JIT Privacy Middleware.
+
+```bash
+uv run pytest tests/ -v
+```
+
+### The Interactive Demo (examples/test_agent.py)
+You can observe Mask's privacy middleware in action by running the demo script:
+```bash
+uv run python examples/test_agent.py
+```
+
+**What is REAL vs MOCKED in the demo?**
+* **REAL**: The Format-Preserving Tokenization generation, the storage of the token into the Vault, and the hook's recursive detokenization algorithm are all executing genuinely.
+* **MOCKED**: To save time and API credits for a local demo, the script does not make a real HTTP call to an LLM provider, nor does the mock tool perform real downstream actions. It simulates the LLM's decision so you can observe the middleware pipeline execute flawlessly.
+
+---
+
+## Telemetry and Compliance
+The SDK includes a thread-safe, asynchronous AuditLogger built-in (`mask/telemetry/audit_logger.py`). 
+
+As your agents encrypt and decrypt data, the logger buffers these privacy events (e.g., Action: Tokenized Email, Agent: SalesBot, TTL: 600s). **Raw PII is never logged.** 
+
+In enterprise deployments, these logs are automatically forwarded to the **Mask Control Plane** via our Telemetry Ingestion API to power your compliance dashboard and Audit Storage database. Retention policies vary by Cloud tier (7-day history for Basic, 30-day for Pro, Unlimited for Enterprise). 
+
+For open-source or local telemetry evaluation, they can be flushed to stdout as structured JSON and piped into your existing Datadog or Splunk agents to generate compliance reports for your SOC2, HIPAA, or PCI-DSS auditors proving that your LLM infrastructure properly isolates sensitive data.
+
+If your environment does not permit on-disk storage of audit events, you can
+disable the local SQLite buffer by setting:
+
+```bash
+export MASK_DISABLE_AUDIT_DB=true
+```
+
+In this mode, events are still emitted via the logger but never persisted to
+`.mask_audit.db` on disk.
+
+---
+
+## License
+
+This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2026 Mask AI Solutions