voodoo-framework 2.1.0__tar.gz → 2.3.0__tar.gz

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.1.0
+Version: 2.3.0
 Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
 Author-email: Helder Perez <contact@helderperez.com>
 Maintainer-email: Helder Perez <contact@helderperez.com>
@@ -59,6 +59,10 @@ Requires-Dist: boto3>=1.34; extra == "s3"
 Requires-Dist: botocore>=1.34; extra == "s3"
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == "otel"
 Dynamic: license-file
 
 <picture>

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/pyproject.toml

@@ -93,6 +93,11 @@ s3 = [
 redis = [
     "redis>=5.0",
 ]
+otel = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.20",
+]
 
 [tool.setuptools.dynamic]
 version = { attr = "voodoo.__version__" }

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 __all__ = [
     # Core runtime
@@ -306,6 +306,18 @@ _DEPRECATED_EXPORTS: dict[str, str] = {
     "rate_limiter": "voodoo.security",
     "set_csrf_cookie": "voodoo.security",
     "validate_password_strength": "voodoo.security",
+    # voodoo.security — Sprint 19
+    "SecretStore": "voodoo.security",
+    "EnvSecretStore": "voodoo.security",
+    "LocalSecretStore": "voodoo.security",
+    "SecretsError": "voodoo.security",
+    "secrets": "voodoo.security",
+    "configure_secrets": "voodoo.security",
+    "RedactionGuard": "voodoo.security",
+    "redact": "voodoo.security",
+    "redact_string": "voodoo.security",
+    # voodoo.runtime — Sprint 19
+    "SENSITIVE_CAPABILITIES": "voodoo.runtime.capability",
     # voodoo.seo
     "FAQ": "voodoo.seo",
     "GEO": "voodoo.seo",

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/cli/__init__.py

@@ -13,9 +13,11 @@ from voodoo.cli import (
     recover,
     routes,
     schedules,
+    status,
     tasks,
     theme,
     version,
+    workers_cmd,
 )
 from voodoo.cli.auth import auth_app
 from voodoo.cli.inspect import inspect_app
@@ -45,6 +47,8 @@ app.add_typer(theme.theme_app, name="theme")
 # (timeline from the journal) and `voodoo events` (recent journal events).
 app.command("execution")(executions.show_execution)
 app.command("events")(executions.list_events)
+app.command()(status.status)
+app.command()(workers_cmd.workers)
 app.command()(version.version)
 app.command()(doctor.doctor)
 app.command()(routes.routes)

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/cli/doctor.py

@@ -217,6 +217,54 @@ def doctor():  # noqa: C901
     except Exception:  # noqa: BLE001 - diagnostics must never crash doctor
         terminal.status("capability matrix", "unavailable")
 
+    # ── Queue depth ─────────────────────────────────
+    terminal.heading("queue")
+    try:
+        import asyncio
+
+        async def _check_queue() -> tuple[int, int]:
+            from voodoo.workers.queue import _get_queue, _workers
+
+            depth = 0
+            try:
+                q = await _get_queue()
+                if hasattr(q, "list"):
+                    tasks = await q.list()
+                    depth = len(tasks)
+                elif hasattr(q, "depth"):
+                    depth = await q.depth()
+            except Exception:
+                pass
+            return depth, len(_workers)
+
+        depth, n_workers = asyncio.run(_check_queue())
+        terminal.status("depth", str(depth))
+        terminal.status("registered workers", str(n_workers))
+    except Exception:  # noqa: BLE001
+        terminal.status("queue", "unavailable")
+
+    # ── Schedules ───────────────────────────────────
+    terminal.heading("schedules")
+    try:
+        from pathlib import Path as _Path
+
+        sched_db = _Path(cfg.db_path).parent / "schedules.db"
+        if sched_db.exists():
+            terminal.status("scheduler db", "present")
+        else:
+            terminal.status("scheduler db", "not found")
+    except Exception:  # noqa: BLE001
+        terminal.status("schedules", "unavailable")
+
+    # ── OTLP ────────────────────────────────────────
+    terminal.heading("otel")
+    try:
+        from voodoo.telemetry.otlp import is_available
+
+        terminal.status("otlp exporter", "active" if is_available() else "off")
+    except Exception:  # noqa: BLE001
+        terminal.status("otlp exporter", "off")
+
     # ── AI Kit ──────────────────────────────────────
     terminal.heading("ai kit")
 

voodoo_framework-2.3.0/src/voodoo/cli/status.py

@@ -0,0 +1,73 @@
+"""``voodoo status`` — runtime health overview.
+
+Displays a quick snapshot of the runtime: request counts, error rate,
+latency, agent activity, queue depth, and OTel export status.
+Works after a restart because rolling counters are persisted to
+``.voodoo/telemetry_summary.json``.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["status"]
+
+
+def status() -> None:
+    """Show runtime health overview."""
+    from voodoo.telemetry import telemetry_store
+    from voodoo.telemetry.otlp import is_available as otlp_available
+
+    summary = telemetry_store.get_summary()
+    console = Console()
+
+    # -- header --------------------------------------------------------
+    console.print("[bold cyan]Voodoo Runtime Status[/bold cyan]")
+    console.print()
+
+    # -- requests & errors ---------------------------------------------
+    tbl = Table(show_header=True, header_style="bold")
+    tbl.add_column("Metric", style="dim")
+    tbl.add_column("Value", justify="right")
+
+    total = summary.get("requests_total", 0)
+    errors = summary.get("errors_total", 0)
+    error_rate = f"{(errors / total * 100):.1f}%" if total else "—"
+    avg_lat = summary.get("average_latency_ms", 0.0)
+
+    tbl.add_row("Requests total", str(total))
+    tbl.add_row("Errors total", str(errors))
+    tbl.add_row("Error rate", error_rate)
+    tbl.add_row("Avg latency", f"{avg_lat:.1f} ms")
+    tbl.add_row("DB queries", str(summary.get("db_queries", 0)))
+    console.print(tbl)
+    console.print()
+
+    # -- agent activity ------------------------------------------------
+    agent_tbl = Table(show_header=True, header_style="bold")
+    agent_tbl.add_column("Agent Metric", style="dim")
+    agent_tbl.add_column("Value", justify="right")
+
+    agent_tbl.add_row("Agent runs", str(summary.get("agent_runs", 0)))
+    agent_tbl.add_row("Tokens in", str(summary.get("agent_tokens_in", 0)))
+    agent_tbl.add_row("Tokens out", str(summary.get("agent_tokens_out", 0)))
+    agent_tbl.add_row("Agent cost", f"${summary.get('agent_cost', 0.0):.6f}")
+    agent_tbl.add_row("Tool calls", str(summary.get("tool_calls_total", 0)))
+    agent_tbl.add_row("Tool errors", str(summary.get("tool_errors", 0)))
+    agent_tbl.add_row("Spans recorded", str(summary.get("spans_total", 0)))
+    console.print(agent_tbl)
+    console.print()
+
+    # -- infrastructure ------------------------------------------------
+    infra_tbl = Table(show_header=True, header_style="bold")
+    infra_tbl.add_column("Infrastructure", style="dim")
+    infra_tbl.add_column("Status")
+
+    infra_tbl.add_row("OTLP export", "active" if otlp_available() else "off")
+    console.print(infra_tbl)
+
+
+app = typer.Typer(name="status", help="Runtime health overview.", no_args_is_help=True)
+app.command()(status)

voodoo_framework-2.3.0/src/voodoo/cli/workers_cmd.py

@@ -0,0 +1,71 @@
+"""``voodoo workers`` — worker state & queue depth.
+
+Shows registered background workers, their queue depth, and whether
+the worker loop is running.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["workers"]
+
+
+async def _gather_worker_info() -> dict[str, Any]:
+    """Collect worker and queue state without side-effects."""
+    from voodoo.workers.queue import _get_queue, _worker_tasks, _workers
+
+    info: dict[str, Any] = {
+        "registered": list(_workers.keys()),
+        "running_tasks": len([t for t in _worker_tasks if not t.done()]),
+        "queue_depth": 0,
+    }
+
+    try:
+        q = await _get_queue()
+        if hasattr(q, "list"):
+            tasks = await q.list()
+            info["queue_depth"] = len(tasks)
+        elif hasattr(q, "depth"):
+            info["queue_depth"] = await q.depth()
+    except Exception:
+        pass
+
+    return info
+
+
+def workers() -> None:
+    """Show registered workers and queue depth."""
+    console = Console()
+    info = asyncio.run(_gather_worker_info())
+
+    console.print("[bold cyan]Voodoo Workers[/bold cyan]")
+    console.print()
+
+    tbl = Table(show_header=True, header_style="bold")
+    tbl.add_column("Worker", style="dim")
+    tbl.add_column("Status")
+
+    registered = info["registered"]
+    if not registered:
+        console.print("[dim]No workers registered.[/dim]")
+    else:
+        running = info["running_tasks"]
+        for name in registered:
+            tbl.add_row(name, "running" if running > 0 else "idle")
+        console.print(tbl)
+
+    console.print()
+    console.print(f"Queue depth: [bold]{info['queue_depth']}[/bold]")
+    console.print(f"Running worker tasks: [bold]{info['running_tasks']}[/bold]")
+
+
+app = typer.Typer(
+    name="workers", help="Worker state & queue depth.", no_args_is_help=True
+)
+app.command()(workers)

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/primitives/effect.py

@@ -61,6 +61,11 @@ class Effect(BaseModel):
     error: str | None = None
     created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     executed_at: datetime | None = None
+    # Authorization context (Sprint 19, ROADMAP §55)
+    actor: str | None = None
+    principal: str | None = None
+    resource: str | None = None
+    scope: str | None = None
 
     # -- lifecycle ---------------------------------------------------------
 
@@ -114,6 +119,10 @@ class Effect(BaseModel):
             "status": self.status.value,
             "intent_id": self.intent_id,
             "capability": self.capability_name,
+            "actor": self.actor,
+            "principal": self.principal,
+            "resource": self.resource,
+            "scope": self.scope,
             "reversible": self.reversible,
             "idempotent": self.idempotent,
             "idempotency_key": self.idempotency_key,

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/runtime/capability.py

@@ -23,7 +23,23 @@ from voodoo.primitives.capability import Capability
 from voodoo.runtime.context import ExecutionContext
 from voodoo.runtime.errors import ApprovalRequired, CapabilityDenied
 
-__all__ = ["Resolution", "CapabilityResolver"]
+__all__ = ["Resolution", "CapabilityResolver", "SENSITIVE_CAPABILITIES"]
+
+
+#: Capabilities that require explicit grants — no ambient authority by
+#: default (Sprint 19, ROADMAP §55).  An agent or tool that attempts to
+#: use one of these without an explicit grant gets a :class:`CapabilityDenied`
+#: error, never a silent pass-through.
+SENSITIVE_CAPABILITIES: frozenset[str] = frozenset(
+    {
+        "filesystem.write",
+        "network.request",
+        "shell.execute",
+        "secrets.read",
+        "payment.execute",
+        "email.send",
+    }
+)
 
 
 class Resolution(StrEnum):
@@ -65,17 +81,50 @@ class CapabilityResolver:
         Context-granted capabilities take precedence (they are the
         delegated authority for an in-flight execution). Otherwise the
         registry is consulted.
+
+        Sensitive capabilities (Sprint 19) are denied by default — they
+        require an explicit grant in the context or registry.
         """
+        if name in SENSITIVE_CAPABILITIES:
+            return self._resolve_sensitive(name, scope=scope, context=context)
+        return self._resolve_standard(name, scope=scope, context=context)
+
+    def _resolve_sensitive(
+        self,
+        name: str,
+        *,
+        scope: str | None = None,
+        context: ExecutionContext | None = None,
+    ) -> Resolution:
+        """Resolve a sensitive capability — requires explicit grant."""
         if context is not None and context.has_capability(name, scope=scope):
-            if name in self.approval_capabilities:
-                return Resolution.REQUIRES_APPROVAL
-            return Resolution.ALLOWED
+            return self._check_approval(name)
+        cap = self.capabilities.get(name)
+        if cap is not None and cap.valid:
+            if scope is not None and cap.scope is not None and cap.scope != scope:
+                return Resolution.DENIED
+            return self._check_approval(name)
+        return Resolution.DENIED
 
+    def _resolve_standard(
+        self,
+        name: str,
+        *,
+        scope: str | None = None,
+        context: ExecutionContext | None = None,
+    ) -> Resolution:
+        """Resolve a standard capability — normal registry rules."""
+        if context is not None and context.has_capability(name, scope=scope):
+            return self._check_approval(name)
         cap = self.capabilities.get(name)
         if cap is None or not cap.valid:
             return Resolution.DENIED
         if scope is not None and cap.scope is not None and cap.scope != scope:
             return Resolution.DENIED
+        return self._check_approval(name)
+
+    def _check_approval(self, name: str) -> Resolution:
+        """Check whether a capability requires human approval."""
         if name in self.approval_capabilities:
             return Resolution.REQUIRES_APPROVAL
         return Resolution.ALLOWED
@@ -114,4 +163,5 @@ class CapabilityResolver:
         return {
             "capabilities": [c.name for c in self.capabilities.values()],
             "approval_required": sorted(self.approval_capabilities),
+            "sensitive": sorted(SENSITIVE_CAPABILITIES),
         }

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/runtime/engine.py

@@ -173,10 +173,16 @@ class ExecutionEngine:
     def _journal_approval_decision(
         self, execution_id: str, event: str, payload: dict
     ) -> None:
-        """Record an approval decision as a journal event (Sprint 4)."""
+        """Record an approval decision as a journal event (Sprint 4).
+
+        Applies redaction to prevent secrets from leaking into the
+        execution journal (Sprint 19, ROADMAP §55).
+        """
         store = self._execution_store
         if store is not None and hasattr(store, "append_event"):
-            store.append_event(execution_id, event, payload)
+            from voodoo.security.redaction import redact
+
+            store.append_event(execution_id, event, redact(payload))
 
     def checkpoint(self, execution: Execution) -> None:
         """Public checkpoint API — persists an execution mid-flight.
@@ -511,6 +517,13 @@ class ExecutionEngine:
         """Record a compute result's effects, state changes and resources."""
         for effect in result.effects:
             effect.intent_id = intent.id
+            # Authorization context (Sprint 19, ROADMAP §55): record
+            # who triggered the effect, which capability authorized it,
+            # and what resource/scope it targets.
+            if effect.actor is None:
+                effect.actor = ctx.actor
+            if effect.capability_name is None and ctx.capabilities:
+                effect.capability_name = ctx.capabilities[0].name
             # Idempotency key: stable per execution+effect so a resumed
             # execution can safely skip already-completed effects (spec §15).
             if effect.idempotency_key is None:
@@ -722,15 +735,21 @@ class ExecutionEngine:
             return out
 
     async def _emit(self, event: str, payload: dict[str, Any]) -> None:
-        """Publish a namespaced mesh event (best-effort, never breaks)."""
+        """Publish a namespaced mesh event (best-effort, never breaks).
+
+        Applies redaction to prevent secrets from leaking into the
+        event bus (Sprint 19, ROADMAP §55).
+        """
         try:
             from voodoo.mesh import mesh
+            from voodoo.security.redaction import redact
 
-            await mesh.broadcast(event, payload)
+            await mesh.broadcast(event, redact(payload))
         except Exception:  # noqa: BLE001
             pass
 
     def _record_telemetry(self, execution: Execution) -> None:
+        """Record execution telemetry with redaction (Sprint 19)."""
         try:
             from voodoo.telemetry import telemetry_store
 

{voodoo_framework-2.1.0 → voodoo_framework-2.3.0}/src/voodoo/security/__init__.py

@@ -10,6 +10,10 @@ This package re-exports the names that previously lived in the flat
 - ``voodoo/security/rate_limit.py`` — ``RateLimiter``, ``RateLimitMiddleware``
   and the shared ``rate_limiter`` singleton
 - ``voodoo/security/passwords.py`` — ``validate_password_strength``
+- ``voodoo/security/secrets.py`` — ``SecretStore``, ``EnvSecretStore``,
+  ``LocalSecretStore``, ``secrets``, ``configure`` (Sprint 19)
+- ``voodoo/security/redaction.py`` — ``redact``, ``redact_string``,
+  ``RedactionGuard`` (Sprint 19)
 """
 
 from voodoo.security.cors import CORSMiddleware
@@ -25,6 +29,17 @@ from voodoo.security.rate_limit import (
     RateLimitMiddleware,
     rate_limiter,
 )
+from voodoo.security.redaction import RedactionGuard, redact, redact_string
+from voodoo.security.secrets import (
+    EnvSecretStore,
+    LocalSecretStore,
+    SecretsError,
+    SecretStore,
+    secrets,
+)
+from voodoo.security.secrets import (
+    configure as configure_secrets,
+)
 
 __all__ = [
     # Headers
@@ -41,4 +56,15 @@ __all__ = [
     "rate_limiter",
     # Passwords
     "validate_password_strength",
+    # Secrets (Sprint 19)
+    "SecretStore",
+    "EnvSecretStore",
+    "LocalSecretStore",
+    "SecretsError",
+    "secrets",
+    "configure_secrets",
+    # Redaction (Sprint 19)
+    "RedactionGuard",
+    "redact",
+    "redact_string",
 ]

voodoo_framework-2.3.0/src/voodoo/security/redaction.py

@@ -0,0 +1,175 @@
+"""Redaction guard — prevent secrets from leaking into observability (Sprint 19).
+
+Centralized redaction for all output channels: events, journal entries,
+telemetry records, mesh payloads, and log output.
+
+The guard scrubs:
+
+1. Values of registered secrets (from :mod:`voodoo.security.secrets`).
+2. Common secret patterns (API keys, bearer tokens, password URIs).
+3. Keys named ``secret``, ``password``, ``token``, ``api_key``, etc.
+
+Usage::
+
+    from voodoo.security.redaction import redact
+
+    safe = redact({"api_key": "sk-abc123", "name": "test"})
+    # → {"api_key": "[REDACTED]", "name": "test"}
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+__all__ = [
+    "redact",
+    "redact_string",
+    "RedactionGuard",
+]
+
+# ---------------------------------------------------------------------------
+# Patterns
+# ---------------------------------------------------------------------------
+
+#: Keys whose values are always redacted (case-insensitive partial match).
+_SENSITIVE_KEY_PATTERNS: re.Pattern[str] = re.compile(
+    r"(?i)(secret|password|passwd|token|api[_-]?key|auth|credential|private[_-]?key|"
+    r"access[_-]?key|session[_-]?id|cookie)",
+)
+
+#: Value patterns that look like secrets regardless of key name.
+_SENSITIVE_VALUE_PATTERNS: list[re.Pattern[str]] = [
+    # Bearer tokens
+    re.compile(r"(?i)bearer\s+[A-Za-z0-9\-._~+/]+=*"),
+    # OpenAI-style keys
+    re.compile(r"sk-[A-Za-z0-9]{20,}"),
+    # Anthropic-style keys
+    re.compile(r"sk-ant-[A-Za-z0-9\-]{20,}"),
+    # AWS access keys
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    # Generic long hex tokens (32+ chars)
+    re.compile(r"\b[A-Fa-f0-9]{32,}\b"),
+    # JWT tokens (three base64 segments)
+    re.compile(r"eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"),
+    # Password in URI (scheme://user:password@host)
+    re.compile(r"(?i)([a-z]+://[^:]+:)[^@\s]{4,}(@)"),
+]
+
+_REDACTED = "[REDACTED]"
+
+
+def _is_sensitive_key(key: str) -> bool:
+    """Whether a dict key name suggests a secret value."""
+    return bool(_SENSITIVE_KEY_PATTERNS.search(key))
+
+
+def _redact_value_pattern(value: str) -> str:
+    """Replace known secret patterns inside a string."""
+    result = value
+    for pattern in _SENSITIVE_VALUE_PATTERNS:
+        if pattern.pattern.startswith("(?i)([a-z]+://"):
+            # URI password pattern — preserve scheme and host
+            result = pattern.sub(rf"\1{_REDACTED}\2", result)
+        else:
+            result = pattern.sub(_REDACTED, result)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Redaction guard
+# ---------------------------------------------------------------------------
+
+
+class RedactionGuard:
+    """Centralized redaction engine.
+
+    Maintains a set of known secret values (resolved from the secrets
+    store) and applies key-name + value-pattern matching.
+    """
+
+    def __init__(self) -> None:
+        self._known_values: set[str] = set()
+
+    def load_secrets(self, names: set[str]) -> None:
+        """Resolve secret values by name and cache them for redaction.
+
+        Parameters
+        ----------
+        names:
+            Secret names to resolve from the active secrets store.
+        """
+        from voodoo.security.secrets import get
+
+        for name in names:
+            value = get(name)
+            if value and len(value) >= 4:
+                self._known_values.add(value)
+
+    def add_value(self, value: str) -> None:
+        """Manually add a known secret value for redaction."""
+        if value and len(value) >= 4:
+            self._known_values.add(value)
+
+    def redact(self, data: Any) -> Any:
+        """Recursively redact secrets from a data structure.
+
+        Handles dicts, lists, strings, and passthrough for other types.
+        """
+        if isinstance(data, dict):
+            return {k: self._redact_field(k, v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [self.redact(item) for item in data]
+        if isinstance(data, str):
+            return self.redact_string(data)
+        return data
+
+    def _redact_field(self, key: str, value: Any) -> Any:
+        """Redact a single key-value pair."""
+        if _is_sensitive_key(key):
+            if isinstance(value, str) and value:
+                return _REDACTED
+            if value is not None:
+                return _REDACTED
+        return self.redact(value)
+
+    def redact_string(self, value: str) -> str:
+        """Redact known secret values and patterns inside a string."""
+        result = value
+        # Replace known secret values
+        for secret_val in self._known_values:
+            if secret_val in result:
+                result = result.replace(secret_val, _REDACTED)
+        # Replace common patterns
+        result = _redact_value_pattern(result)
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_guard = RedactionGuard()
+
+
+def redact(data: Any) -> Any:
+    """Redact secrets from data using the global guard.
+
+    Convenience wrapper around :meth:`RedactionGuard.redact`.
+    """
+    return _guard.redact(data)
+
+
+def redact_string(value: str) -> str:
+    """Redact secrets from a string using the global guard."""
+    return _guard.redact_string(value)
+
+
+def load_secrets(names: set[str]) -> None:
+    """Load secret values into the global guard for redaction."""
+    _guard.load_secrets(names)
+
+
+def add_known_value(value: str) -> None:
+    """Add a known secret value to the global guard."""
+    _guard.add_value(value)