teaql 0.2.6__tar.gz → 0.2.7__tar.gz

{teaql-0.2.6 → teaql-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teaql
-Version: 0.2.6
+Version: 0.2.7
 Summary: TeaQL Runtime and Data Service for Python
 Author: TeaQL
 License-Expression: Apache-2.0
@@ -39,6 +39,28 @@ Dynamic: license-file
 
 # TeaQL Python SDK
 
+## Sensitive log data
+
+Runtime diagnostic logs redact payload values by default, before delivery to
+file, console, buffers, or custom logging sinks. Selecting a diagnostic sink
+alone does not authorize plaintext. For controlled troubleshooting only:
+
+```bash
+export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
+```
+
+Only this exact value enables plaintext permission; empty values, `true`, and
+whitespace variants do not. Enabling it emits a warning. Credential-classified
+fields remain redacted. The flag does not force every sink to expose values.
+SQL without reliable field/literal provenance may be suppressed and marked
+`NOT REPLAYABLE`. Execution parameters and persisted business data are unchanged.
+
+Do not put sensitive data in free-text comments or purpose declarations.
+TeaQL cannot govern arbitrary application prints or independent driver loggers;
+configure those separately. This setting does not erase older plaintext files.
+Restrict access and retention when using plaintext diagnostics, then unset the
+variable and restart processes when troubleshooting is complete.
+
 TeaQL Python SDK is a runtime engine and toolkit for building data-driven business applications. It provides seamless integration with the TeaQL ecosystem, fully aligned with the `teaql-rs` baseline.
 
 ## Recommended Agent Harness
@@ -100,5 +122,26 @@ orders = await client.execute_query(FederalQuery(
 await client.aclose()
 ```
 
+## Security Foundation Status
+
+Python currently provides governed local SQL execution and a **TFP client**;
+it does not claim a public TFP server endpoint. Application queries retain
+non-empty comment/purpose and audited mutations retain their audit reason.
+Runtime logging should keep parameterized SQL and intent separate from any
+restricted value-bearing diagnostic output.
+
+Portable `UserContext` opaque entity references are not implemented in the
+Python runtime yet. Until that capability is added, applications must not
+invent a Python-specific token format or serialize internal ID/version pairs as
+if they were the TeaQL portable contract. A Python TFP client may carry an
+opaque token issued by a trusted Java, Rust, Go, or .NET backend, but it must
+not decode, rewrite, or mint that token.
+
+The planned wire format, fail-closed behavior, shared golden vector, and exact
+development-only acknowledgement are maintained in the canonical
+[opaque entity reference contract](https://github.com/teaql/teaql-conformance/blob/main/design/opaque-entity-references.md).
+Opaque tokens never replace the backend's authorization, tenant, ownership,
+role, or optimistic-version checks.
+
 ---
 To run test validations and business logic simulations locally, simply run `pytest` in the project root.

{teaql-0.2.6 → teaql-0.2.7}/README.md

@@ -1,5 +1,27 @@
 # TeaQL Python SDK
 
+## Sensitive log data
+
+Runtime diagnostic logs redact payload values by default, before delivery to
+file, console, buffers, or custom logging sinks. Selecting a diagnostic sink
+alone does not authorize plaintext. For controlled troubleshooting only:
+
+```bash
+export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
+```
+
+Only this exact value enables plaintext permission; empty values, `true`, and
+whitespace variants do not. Enabling it emits a warning. Credential-classified
+fields remain redacted. The flag does not force every sink to expose values.
+SQL without reliable field/literal provenance may be suppressed and marked
+`NOT REPLAYABLE`. Execution parameters and persisted business data are unchanged.
+
+Do not put sensitive data in free-text comments or purpose declarations.
+TeaQL cannot govern arbitrary application prints or independent driver loggers;
+configure those separately. This setting does not erase older plaintext files.
+Restrict access and retention when using plaintext diagnostics, then unset the
+variable and restart processes when troubleshooting is complete.
+
 TeaQL Python SDK is a runtime engine and toolkit for building data-driven business applications. It provides seamless integration with the TeaQL ecosystem, fully aligned with the `teaql-rs` baseline.
 
 ## Recommended Agent Harness
@@ -61,5 +83,26 @@ orders = await client.execute_query(FederalQuery(
 await client.aclose()
 ```
 
+## Security Foundation Status
+
+Python currently provides governed local SQL execution and a **TFP client**;
+it does not claim a public TFP server endpoint. Application queries retain
+non-empty comment/purpose and audited mutations retain their audit reason.
+Runtime logging should keep parameterized SQL and intent separate from any
+restricted value-bearing diagnostic output.
+
+Portable `UserContext` opaque entity references are not implemented in the
+Python runtime yet. Until that capability is added, applications must not
+invent a Python-specific token format or serialize internal ID/version pairs as
+if they were the TeaQL portable contract. A Python TFP client may carry an
+opaque token issued by a trusted Java, Rust, Go, or .NET backend, but it must
+not decode, rewrite, or mint that token.
+
+The planned wire format, fail-closed behavior, shared golden vector, and exact
+development-only acknowledgement are maintained in the canonical
+[opaque entity reference contract](https://github.com/teaql/teaql-conformance/blob/main/design/opaque-entity-references.md).
+Opaque tokens never replace the backend's authorization, tenant, ownership,
+role, or optimistic-version checks.
+
 ---
 To run test validations and business logic simulations locally, simply run `pytest` in the project root.

{teaql-0.2.6 → teaql-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "teaql"
-version = "0.2.6"
+version = "0.2.7"
 description = "TeaQL Runtime and Data Service for Python"
 readme = "README.md"
 requires-python = ">=3.10"

{teaql-0.2.6 → teaql-0.2.7}/src/teaql/runtime/audit.py

@@ -29,19 +29,28 @@ class RawAuditEvent:
     category: Optional[str] = None
 
     def safe(self, mask_fields: List[str], max_length: Optional[int]) -> "SafeAuditEvent":
+        from .log_privacy import REDACTED, credential_name, payload_has_credentials, plaintext_enabled, scrub, value_strings
+        allow = plaintext_enabled()
+        secrets = []
         fields = []
         for change in self.changes:
             value = None if change.new_value is None else str(getattr(change.new_value, "val", change.new_value))
-            masked = change.field in mask_fields
+            masked = (credential_name(change.field)
+                      or payload_has_credentials(change.new_value)
+                      or payload_has_credentials(change.old_value)
+                      or (change.field in mask_fields and not allow))
+            if masked:
+                secrets.extend(value_strings(change.old_value))
+                secrets.extend(value_strings(change.new_value))
             if value is not None and masked:
-                value = _mask(value)
+                value = REDACTED
             truncated = value is not None and max_length is not None and len(value) > max_length
             if truncated:
                 value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
             fields.append(SafeAuditField(change.field, value, masked, truncated))
         return SafeAuditEvent(
-            self.kind, self.entity, self.entity_id, tuple(fields), self.trace_chain,
-            self.actor, self.category,
+            self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, secrets),
+            scrub(self.actor, secrets), self.category,
         )
 
 

{teaql-0.2.6 → teaql-0.2.7}/src/teaql/runtime/context.py

@@ -739,6 +739,8 @@ class UserContext:
         elif entry.affected_rows is not None:
             entry.result_summary = f"{entry.affected_rows} rows affected"
 
+        from .log_privacy import sql_log_projection
+        entry = sql_log_projection(entry)
         logs = self.sql_logs()
         logs.append(entry)
         self._resources["sql_logs"] = logs
@@ -750,7 +752,7 @@ class UserContext:
             buf.entries.append(UnifiedLogEntry(
                 timestamp=entry.started_at,
                 user_identifier=self.user_identifier(),
-                trace_chain=getattr(metadata, 'trace_chain', []),
+                trace_chain=entry.trace_path,
                 payload=LogPayload.Sql(entry)
             ))
 
@@ -784,6 +786,8 @@ class UserContext:
         elif affected_rows is not None:
             entry.result_summary = f"{affected_rows} rows affected"
 
+        from .log_privacy import sql_log_projection
+        entry = sql_log_projection(entry)
         logs = self.sql_logs()
         logs.append(entry)
         self._resources["sql_logs"] = logs
@@ -1033,7 +1037,7 @@ class SqlLogEntry:
     result_summary: str
 
 class DiagnosticSqlLogSink:
-    """Value-bearing diagnostic SQL destination; the text sink is installed by default."""
+    """Policy-projected SQL destination; the text sink is installed by default."""
     def write(self, entry: SqlLogEntry) -> None:
         raise NotImplementedError
 
@@ -1042,6 +1046,8 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
         self._writer = writer
 
     def write(self, entry: SqlLogEntry) -> None:
+        from .log_privacy import sql_log_projection
+        entry = sql_log_projection(entry)
         elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
         self._writer(
             f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "

teaql-0.2.7/src/teaql/runtime/log_privacy.py

@@ -0,0 +1,93 @@
+"""Log-only projections. Never modify execution parameters or stored values."""
+
+import logging
+import os
+import re
+from dataclasses import fields, is_dataclass, replace
+from functools import lru_cache
+
+PLAINTEXT_ENV = "TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS"
+PLAINTEXT_ACK = "I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK"
+REDACTED = "[REDACTED]"
+SQL_REDACTED = "[REDACTED SQL; NOT REPLAYABLE]"
+
+
+@lru_cache(maxsize=1)
+def _warn_plaintext():
+    logging.getLogger("teaql.runtime").warning(
+        "Sensitive plaintext logging enabled: application data may be written to disk. "
+        "Authentication secrets remain redacted."
+    )
+
+
+def plaintext_enabled():
+    enabled = os.environ.get(PLAINTEXT_ENV) == PLAINTEXT_ACK
+    if enabled:
+        _warn_plaintext()
+    return enabled
+
+
+def credential_name(name):
+    normalized = re.sub(r"[^a-z0-9]", "", str(name).lower())
+    return any(word in normalized for word in (
+        "password", "passwd", "passphrase", "privatekey", "secret", "accesstoken",
+        "refreshtoken", "idtoken", "apikey", "authorization", "credential",
+        "sessiontoken", "magiclinktoken",
+    ))
+
+
+def payload_has_credentials(value):
+    value = getattr(value, "val", value)
+    if isinstance(value, dict):
+        return any(credential_name(k) or payload_has_credentials(v) for k, v in value.items())
+    if isinstance(value, (tuple, list)):
+        return any(payload_has_credentials(v) for v in value)
+    return False
+
+
+def value_strings(value):
+    value = getattr(value, "val", value)
+    if isinstance(value, dict):
+        return [s for v in value.values() for s in value_strings(v)]
+    if isinstance(value, (tuple, list)):
+        return [s for v in value for s in value_strings(v)]
+    return [] if value is None or value == "" else [str(value)]
+
+
+def scrub(value, secrets):
+    """Copy annotations, removing known values even when embedded in intent."""
+    if isinstance(value, str):
+        for secret in sorted(set(secrets), key=len, reverse=True):
+            value = value.replace(secret, REDACTED)
+        return value
+    if isinstance(value, list):
+        return [scrub(v, secrets) for v in value]
+    if isinstance(value, tuple):
+        return tuple(scrub(v, secrets) for v in value)
+    if isinstance(value, dict):
+        return {k: scrub(v, secrets) for k, v in value.items()}
+    if is_dataclass(value):
+        return replace(value, **{f.name: scrub(getattr(value, f.name), secrets)
+                                 for f in fields(value) if f.init})
+    return value
+
+
+def sql_log_projection(entry):
+    # SQL has no per-parameter field provenance. A credential-bearing query
+    # therefore suppresses its whole payload, including on debug opt-in.
+    credentials = (credential_name(entry.sql) or credential_name(entry.debug_sql)
+                   or payload_has_credentials(entry.params))
+    allow = plaintext_enabled() and not credentials
+    if allow:
+        return replace(entry, params=list(entry.params), trace_path=list(entry.trace_path))
+    secrets = value_strings(entry.params)
+    sql = entry.sql
+    # Arbitrary literal SQL is not safely redactable across dialects. Preserve
+    # parameterized shape only when there are no literals/comments to expose.
+    if any(token in sql for token in ("'", '"', "`", "--", "/*", "$")) or re.search(r"\b\d+\b", sql):
+        sql = SQL_REDACTED
+    return replace(entry, sql=scrub(sql, secrets), params=[None] * len(entry.params),
+                   debug_sql=SQL_REDACTED, pretty_sql=SQL_REDACTED,
+                   comment=scrub(entry.comment, secrets), purpose=scrub(entry.purpose, secrets),
+                   audit_reason=scrub(entry.audit_reason, secrets),
+                   trace_path=scrub(entry.trace_path, secrets))

{teaql-0.2.6 → teaql-0.2.7}/src/teaql.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teaql
-Version: 0.2.6
+Version: 0.2.7
 Summary: TeaQL Runtime and Data Service for Python
 Author: TeaQL
 License-Expression: Apache-2.0
@@ -39,6 +39,28 @@ Dynamic: license-file
 
 # TeaQL Python SDK
 
+## Sensitive log data
+
+Runtime diagnostic logs redact payload values by default, before delivery to
+file, console, buffers, or custom logging sinks. Selecting a diagnostic sink
+alone does not authorize plaintext. For controlled troubleshooting only:
+
+```bash
+export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
+```
+
+Only this exact value enables plaintext permission; empty values, `true`, and
+whitespace variants do not. Enabling it emits a warning. Credential-classified
+fields remain redacted. The flag does not force every sink to expose values.
+SQL without reliable field/literal provenance may be suppressed and marked
+`NOT REPLAYABLE`. Execution parameters and persisted business data are unchanged.
+
+Do not put sensitive data in free-text comments or purpose declarations.
+TeaQL cannot govern arbitrary application prints or independent driver loggers;
+configure those separately. This setting does not erase older plaintext files.
+Restrict access and retention when using plaintext diagnostics, then unset the
+variable and restart processes when troubleshooting is complete.
+
 TeaQL Python SDK is a runtime engine and toolkit for building data-driven business applications. It provides seamless integration with the TeaQL ecosystem, fully aligned with the `teaql-rs` baseline.
 
 ## Recommended Agent Harness
@@ -100,5 +122,26 @@ orders = await client.execute_query(FederalQuery(
 await client.aclose()
 ```
 
+## Security Foundation Status
+
+Python currently provides governed local SQL execution and a **TFP client**;
+it does not claim a public TFP server endpoint. Application queries retain
+non-empty comment/purpose and audited mutations retain their audit reason.
+Runtime logging should keep parameterized SQL and intent separate from any
+restricted value-bearing diagnostic output.
+
+Portable `UserContext` opaque entity references are not implemented in the
+Python runtime yet. Until that capability is added, applications must not
+invent a Python-specific token format or serialize internal ID/version pairs as
+if they were the TeaQL portable contract. A Python TFP client may carry an
+opaque token issued by a trusted Java, Rust, Go, or .NET backend, but it must
+not decode, rewrite, or mint that token.
+
+The planned wire format, fail-closed behavior, shared golden vector, and exact
+development-only acknowledgement are maintained in the canonical
+[opaque entity reference contract](https://github.com/teaql/teaql-conformance/blob/main/design/opaque-entity-references.md).
+Opaque tokens never replace the backend's authorization, tenant, ownership,
+role, or optimistic-version checks.
+
 ---
 To run test validations and business logic simulations locally, simply run `pytest` in the project root.

{teaql-0.2.6 → teaql-0.2.7}/src/teaql.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ src/teaql/runtime/builtin-messages-v1.json
 src/teaql/runtime/context.py
 src/teaql/runtime/env.py
 src/teaql/runtime/i18n.py
+src/teaql/runtime/log_privacy.py
 src/teaql/runtime/module.py
 src/teaql/runtime/opentelemetry.py
 src/teaql/runtime/store.py