statelock-ai 0.1.0__py3-none-any.whl

statelock/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Statelock: governed browser actions for AI agents."""
+
+__version__ = "0.1.0"  # the package version: pyproject.toml reads it from here

statelock/__main__.py

@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`statelock` command.
+
+statelock [--host H] [--port P]            run the proxy (default: 127.0.0.1:8010)
+statelock keygen --agent-id ID [--tenant T] [--append FILE]  new API key and its keys-file entry
+                                           (or --reviewer / --auditor ID)
+statelock session-url [--saved-session NAME [--save]]  single-use URL for a governed session
+statelock saved-sessions list | delete NAME  the agent's saved browser sessions
+statelock hash-key < key.txt               SHA-256 of a key read from stdin
+statelock check-sandbox                    launch Chromium with the configured sandbox setting
+statelock perception-check IMAGE -i TEXT [-x name=type]  try the configured vision model on a screenshot
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import json
+import stat
+import sys
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+import yaml
+
+from statelock.auth import DEFAULT_TENANT, KeysFile, generate_key, hash_key
+from statelock.fileio import load_yaml, write_atomic
+
+DEFAULT_PORT = 8010  # the port the README and the examples use
+
+
+def _run(args: argparse.Namespace) -> int:
+    uvicorn.run("statelock.app:create_app", factory=True, host=args.host, port=args.port)
+    return 0
+
+
+def _keygen(args: argparse.Namespace) -> int:
+    key = generate_key()
+    if args.reviewer:
+        section, id_field, principal = "reviewers", "reviewer_id", args.reviewer
+    elif args.auditor:
+        section, id_field, principal = "auditors", "auditor_id", args.auditor
+    else:
+        section, id_field, principal = "agents", "agent_id", args.agent_id
+    entry = {id_field: principal, "tenant": args.tenant, "key_sha256": hash_key(key)}
+    if args.append is not None:
+        try:
+            append_key_entry(Path(args.append), section, entry)
+        except (OSError, ValueError, yaml.YAMLError) as error:
+            print(f"Could not add the key to {args.append}: {error}", file=sys.stderr)
+            return 1
+    # The key goes to stderr so the keys-file entry on stdout can be redirected safely.
+    print(f"API key for {principal} (store it as a secret; it is not shown again):", file=sys.stderr)
+    print(key, file=sys.stderr)
+    if args.append is not None:
+        print(f"Added {id_field} {principal} to {section} in {args.append}", file=sys.stderr)
+    else:
+        print(yaml.safe_dump({section: [entry]}, sort_keys=False), end="")
+    return 0
+
+
+def append_key_entry(path: Path, section: str, entry: dict[str, Any]) -> None:
+    """Add an entry to a section of a keys file (created when missing), keeping the rest
+    of the file as written, comments included. The result must be a valid keys file;
+    it replaces the old one atomically."""
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    before = load_yaml(text) or {}
+    KeysFile.model_validate(before)
+    updated = _insert_entry(text, section, yaml.safe_dump([entry], sort_keys=False))
+    after = load_yaml(updated) or {}
+    KeysFile.model_validate(after)  # also refuses a key that is already listed
+    # Exactly one change: the entry appended to its section.
+    if {**after, section: None} != {**before, section: None} or after.get(section) != [
+        *(before.get(section) or []),
+        entry,
+    ]:
+        raise ValueError("the entry could not be added; add it by hand")
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else None
+    write_atomic(path, updated.encode("utf-8"), mode=mode)
+
+
+def _insert_entry(text: str, section: str, item: str) -> str:
+    """``text`` with the YAML list ``item`` added at the end of the top-level ``section`` list,
+    or a new section at the end. Plain text insertion: the caller parses the result and checks
+    that it holds exactly the one new entry."""
+    lines = text.splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    start = next((i for i, line in enumerate(lines) if line.startswith(f"{section}:")), None)
+    if start is None:
+        return "".join(lines) + f"{section}:\n{_indent(item, '  ')}"
+    value = lines[start][len(section) + 1 :].strip()
+    if value and not value.startswith("#"):
+        raise ValueError(f"{section} must be a block list (- entries) to append to; add the entry by hand")
+    # The section runs until the next top-level key; a comment after its last entry (one that
+    # introduces the next section) stays after the new entry.
+    end = start + 1
+    while end < len(lines) and (not lines[end].strip() or lines[end][0] in " #-"):
+        end += 1
+    while end > start + 1 and (not lines[end - 1].strip() or lines[end - 1].lstrip().startswith("#")):
+        end -= 1
+    entries = [line for line in lines[start + 1 : end] if line.lstrip().startswith("-")]
+    indent = entries[0][: len(entries[0]) - len(entries[0].lstrip())] if entries else "  "
+    return "".join([*lines[:end], _indent(item, indent), *lines[end:]])
+
+
+def _indent(block: str, indent: str) -> str:
+    return "".join(indent + line for line in block.splitlines(keepends=True))
+
+
+def _session_url(args: argparse.Namespace) -> int:
+    from statelock.client.sessions import StatelockClientError, create_session_url  # noqa: PLC0415
+
+    try:
+        url = create_session_url(
+            args.server,
+            agent_id=args.agent_id,
+            ttl_seconds=args.ttl,
+            saved_session=args.saved_session,
+            save_session=args.save,
+        )
+    except StatelockClientError as error:
+        print(error, file=sys.stderr)
+        return 1
+    print(url.ws_url if args.ws else url.cdp_url)
+    print(f"session {url.session_id} for {url.agent_id}; single use, expires {url.expires_at}", file=sys.stderr)
+    return 0
+
+
+def _saved_sessions(args: argparse.Namespace) -> int:
+    from statelock.client.sessions import (  # noqa: PLC0415
+        StatelockClientError,
+        delete_saved_session,
+        list_saved_sessions,
+    )
+
+    try:
+        if args.action == "delete":
+            if not args.name:
+                print("delete needs a saved-session name", file=sys.stderr)
+                return 2
+            deleted = delete_saved_session(args.name, args.server, agent_id=args.agent_id)
+            print("deleted" if deleted else "not found", file=sys.stderr)
+            return 0 if deleted else 1
+        for name in list_saved_sessions(args.server, agent_id=args.agent_id):
+            print(name)
+    except StatelockClientError as error:
+        print(error, file=sys.stderr)
+        return 1
+    return 0
+
+
+def _hash_key(_args: argparse.Namespace) -> int:
+    key = sys.stdin.read().strip()
+    if not key:
+        print("no key on stdin", file=sys.stderr)
+        return 1
+    print(hash_key(key))
+    return 0
+
+
+def _check_sandbox(_args: argparse.Namespace) -> int:
+    from statelock.proxy.browser import BrowserLaunchError  # noqa: PLC0415 - heavy import
+    from statelock.services import launcher  # noqa: PLC0415
+    from statelock.settings import Settings  # noqa: PLC0415
+
+    settings = Settings()
+
+    async def launch() -> None:
+        browser = await launcher(settings).launch()
+        await browser.close()
+
+    try:
+        asyncio.run(launch())
+    except BrowserLaunchError as error:
+        print(f"Chromium failed to start (sandbox={settings.chromium_sandbox}): {error}", file=sys.stderr)
+        return 1
+    print(f"Chromium started (sandbox={'on' if settings.chromium_sandbox else 'off'}).")
+    return 0
+
+
+def _perception_check(args: argparse.Namespace) -> int:
+    from statelock.core.state import BrowserState  # noqa: PLC0415
+    from statelock.policy.perception import PerceptionRequest  # noqa: PLC0415
+    from statelock.services import perception_evaluator  # noqa: PLC0415
+    from statelock.settings import Settings  # noqa: PLC0415
+
+    extract: dict[str, str] = {}
+    for item in args.extract:
+        name, _, kind = item.partition("=")
+        extract[name] = kind or "string"
+    try:
+        evaluator = perception_evaluator(Settings())
+    except RuntimeError as error:
+        print(error, file=sys.stderr)
+        return 2
+    if evaluator is None:
+        print("Set STATELOCK_PERCEPTION_MODEL (and STATELOCK_PERCEPTION_API_BASE for a local model).", file=sys.stderr)
+        return 2
+    image = base64.b64encode(Path(args.image).read_bytes()).decode("ascii")
+    try:
+        request = PerceptionRequest(
+            check_name="cli", instruction=args.instruction, extract=extract, state=BrowserState(screenshot_base64=image)
+        )
+    except ValueError as error:
+        print(f"Bad --extract: {error}", file=sys.stderr)
+        return 2
+    verdict = asyncio.run(evaluator.evaluate(request))
+    print(json.dumps(verdict.model_dump(), indent=2))
+    return 0 if verdict.passed else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="statelock", description="Statelock proxy and tools.")
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="address the proxy listens on (default: 127.0.0.1, this machine only)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=DEFAULT_PORT, help=f"port the proxy listens on (default: {DEFAULT_PORT})"
+    )
+    parser.set_defaults(handler=_run)
+    commands = parser.add_subparsers(title="commands")
+
+    keygen = commands.add_parser("keygen", help="create an API key and its keys-file entry")
+    principal = keygen.add_mutually_exclusive_group(required=True)
+    principal.add_argument("--agent-id")
+    principal.add_argument("--reviewer", metavar="REVIEWER_ID", help="create a reviewer key instead")
+    principal.add_argument("--auditor", metavar="AUDITOR_ID", help="create an auditor key (evidence access)")
+    keygen.add_argument("--tenant", default=DEFAULT_TENANT)
+    keygen.add_argument(
+        "--append", metavar="FILE", help="add the entry to this keys file (created if missing) instead of printing it"
+    )
+    keygen.set_defaults(handler=_keygen)
+
+    session = commands.add_parser(
+        "session-url", help="print a single-use URL that opens a governed session (key: STATELOCK_API_KEY)"
+    )
+    session.add_argument("--server", help="Statelock URL (default: STATELOCK_URL)")
+    session.add_argument("--agent-id", help="only when the proxy's authentication is off")
+    session.add_argument("--ttl", type=int, help="seconds the URL stays usable (default: the server's, 300)")
+    session.add_argument("--ws", action="store_true", help="print the WebSocket URL instead of the http one")
+    session.add_argument("--saved-session", metavar="NAME", help="restore this saved browser session")
+    session.add_argument("--save", action="store_true", help="save the browser state under NAME at a clean end")
+    session.set_defaults(handler=_session_url)
+
+    saved = commands.add_parser("saved-sessions", help="list or delete the agent's saved browser sessions")
+    saved.add_argument("action", choices=["list", "delete"])
+    saved.add_argument("name", nargs="?")
+    saved.add_argument("--server", help="Statelock URL (default: STATELOCK_URL)")
+    saved.add_argument("--agent-id", help="only when the proxy's authentication is off")
+    saved.set_defaults(handler=_saved_sessions)
+    commands.add_parser("hash-key", help="print the SHA-256 of a key read from stdin").set_defaults(handler=_hash_key)
+    commands.add_parser("check-sandbox", help="start Chromium with the configured sandbox").set_defaults(
+        handler=_check_sandbox
+    )
+
+    perception = commands.add_parser(
+        "perception-check", help="ask the configured vision model (STATELOCK_PERCEPTION_MODEL) about a screenshot"
+    )
+    perception.add_argument("image", help="a JPEG screenshot")
+    perception.add_argument("-i", "--instruction", required=True, help="the check, e.g. 'The amounts match.'")
+    perception.add_argument(
+        "-x", "--extract", action="append", default=[], metavar="NAME=TYPE", help="a value to read (string, number...)"
+    )
+    perception.set_defaults(handler=_perception_check)
+
+    args = parser.parse_args(argv)
+    return int(args.handler(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

statelock/app.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""FastAPI application factory.
+
+Run with: uvicorn --factory statelock.app:create_app
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, WebSocket
+
+from statelock import __version__
+from statelock.auth import Identity
+from statelock.demo import router as demo_router
+from statelock.dependencies import authenticated_auditor, authenticated_identity
+from statelock.plugins import PluginContext, discover_plugins, setup_plugins
+from statelock.proxy.bridge import CdpBridge
+from statelock.review.api import authenticated_reviewer
+from statelock.review.api import router as review_router
+from statelock.services import Services, get_services
+from statelock.sessions import SESSIONS_PATH, install_log_redaction
+from statelock.sessions import router as sessions_router
+from statelock.settings import Settings
+from statelock.wire import VIOLATION_ENDPOINT_PREFIX, WEBSOCKET_PATH
+
+__all__ = ["authenticated_auditor", "authenticated_identity", "authenticated_reviewer", "create_app", "get_services"]
+
+LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s %(message)s"
+
+
+core_router = APIRouter()
+
+
+@core_router.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@core_router.get(VIOLATION_ENDPOINT_PREFIX + "/{session_id}")
+async def get_violation(
+    session_id: str, request: Request, identity: Annotated[Identity | None, Depends(authenticated_identity)]
+) -> dict[str, Any]:
+    violation = get_services(request.app).registry.get(session_id)
+    # With authentication on, an agent sees only its own sessions (others look absent).
+    if violation is None or (identity is not None and violation.get("agent_id") != identity.agent_id):
+        raise HTTPException(status_code=404, detail="No violation recorded for session")
+    return violation
+
+
+@core_router.websocket(WEBSOCKET_PATH)
+async def statelock_session(websocket: WebSocket) -> None:
+    await CdpBridge(get_services(websocket.app)).handle(websocket)
+
+
+@core_router.websocket(SESSIONS_PATH + "/{token}/devtools")
+async def statelock_session_url(websocket: WebSocket, token: str) -> None:
+    """A session opened from a session URL: the token identifies the agent (no headers)."""
+    await CdpBridge(get_services(websocket.app)).handle(websocket, token)
+
+
+def create_app(settings: Settings | None = None, services: Services | None = None) -> FastAPI:
+    """Build services once, register routes, and load plugins."""
+    settings = settings or (services.settings if services else Settings())
+    if settings.log_level:
+        # No-op when the host (e.g. a test runner) already configured logging.
+        logging.basicConfig(level=settings.log_level.upper(), format=LOG_FORMAT)
+    services = services or Services.from_settings(settings)
+
+    app = FastAPI(title="Statelock", version=__version__)
+    app.state.services = services
+    app.include_router(core_router)
+    app.include_router(review_router)
+    app.include_router(sessions_router)
+    install_log_redaction()
+    if settings.demo:
+        app.include_router(demo_router)
+    setup_plugins(PluginContext(app=app, services=services), discover_plugins(settings.plugins))
+    return app

statelock/audit/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Artifact records, redaction and sinks."""
+
+from statelock.audit.records import SCHEMA_VERSION, ActionRecord, build_action_record, build_network_record
+from statelock.audit.redaction import mask_secret_input, redact_payload
+from statelock.audit.sequencing import SequencedWriter
+from statelock.audit.sink import ArtifactSink, LocalJsonSink
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "ActionRecord",
+    "ArtifactSink",
+    "LocalJsonSink",
+    "SequencedWriter",
+    "build_action_record",
+    "build_network_record",
+    "mask_secret_input",
+    "redact_payload",
+]

statelock/audit/records.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Versioned artifact record schema.
+
+An ActionRecord is what the proxy hands to an ArtifactSink for each governed
+action. ``payload`` is the redacted JSON body stored as ``context.json``;
+``screenshots`` holds the raw image bytes keyed by file name. Sinks and sink
+wrappers (for example, a hash chain) may add top-level keys to the
+payload; the keys written by build_action_record are reserved.
+
+Schema history (all changes so far are additive: readers of "1" can read "2"):
+- "1": initial schema.
+- "2": ``context.tenant_id``; ``context.remembered`` (remembered policy fields);
+  ``params.statelock_uploads`` on DOM.setFileInputFiles; ``params.statelock_redacted``
+  when typed secrets are masked; download records (``Statelock.download``, kind
+  ``download``); ``target_element.input_type`` / ``autocomplete``.
+- "3": ``review`` (human review of a paused action: id, status, reviewer, comment,
+  times, the failed rules) and its ``review-screenshot.jpg``; verdict decision
+  ``review`` is never stored (a stored verdict is the outcome: allow or block);
+  ``verdict.evidence.review_deferred`` for actions allowed while a review rule failed.
+- "4": ``policy_id`` (in verdicts, violations, review failures and
+  ``post_conditions_evaluated``) names the policy, not the agent: the policy's ``id``
+  from the policy file, or ``<agent_id>#<n>`` for the agent's n-th policy.
+  Also in "4": ``page_text_unread`` in ``browser_state`` / ``post_browser_state`` (shown
+  frames whose text could not be read); ``target_element.unresolved`` and
+  ``target_element.frame_url`` (an action into a frame Statelock cannot read);
+  ``params.statelock_follows_key_down`` on a key ``char`` event that types the key a
+  preceding ``rawKeyDown`` pressed (part of that key press, not a new activation).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from statelock.audit.redaction import redact_payload
+from statelock.core.state import ActionContext
+from statelock.core.verdict import PolicyVerdict
+from statelock.review.queue import REVIEW_SCREENSHOT_FILE, Review
+
+SCHEMA_VERSION = "4"
+
+SCREENSHOT_FILES = {
+    "browser_state": "screenshot.jpg",
+    "post_browser_state": "post-screenshot.jpg",
+}
+
+
+class ActionRecord(BaseModel):
+    schema_version: str = SCHEMA_VERSION
+    session_id: str
+    sequence: int
+    payload: dict[str, Any]
+    screenshots: dict[str, bytes] = Field(default_factory=dict)
+
+
+def build_action_record(
+    context: ActionContext,
+    verdict: PolicyVerdict,
+    post_verdict: PolicyVerdict | None = None,
+    review: Review | None = None,
+) -> ActionRecord:
+    context_payload = context.model_dump(mode="json")
+    screenshots: dict[str, bytes] = {}
+    for state_key, filename in SCREENSHOT_FILES.items():
+        state = context_payload.get(state_key)
+        if not isinstance(state, dict):
+            continue
+        encoded = state.pop("screenshot_base64", None)
+        state["screenshot_file"] = None
+        if encoded:
+            try:
+                screenshots[filename] = base64.b64decode(encoded)
+                state["screenshot_file"] = filename
+            except (binascii.Error, ValueError):
+                state["screenshot_error"] = "invalid base64 screenshot"
+
+    review_block = review.evidence() if review is not None else None
+    if review is not None and review.screenshot:
+        screenshots[REVIEW_SCREENSHOT_FILE] = review.screenshot
+
+    payload = redact_payload(
+        {
+            "schema_version": SCHEMA_VERSION,
+            "context": context_payload,
+            "verdict": verdict.model_dump(mode="json"),
+            "post_verdict": post_verdict.model_dump(mode="json") if post_verdict else None,
+            "policy_violation": verdict.violation_summary(),
+            "post_policy_violation": post_verdict.violation_summary() if post_verdict else None,
+            "review": review_block,
+        }
+    )
+    return ActionRecord(
+        session_id=context.session_id,
+        sequence=context.sequence,
+        payload=payload,
+        screenshots=screenshots,
+    )
+
+
+def build_network_record(record: dict[str, Any]) -> dict[str, Any]:
+    """Redacted network log line."""
+    return redact_payload({"schema_version": SCHEMA_VERSION, **record})

statelock/audit/redaction.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Redaction applied to every artifact payload before it is written."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+REDACTED = "[REDACTED]"
+# Not part of a longer identifier: a UUID, a hex digest, a path or a file name.
+_BEFORE = r"(?<![0-9A-Za-z/_.-])"
+_AFTER = r"(?![0-9A-Za-z/_-]|\.\w)"
+# US SSN: 123-45-6789, 123 45 6789 or 123456789, without the never-issued 000/666/9xx
+# areas, 00 groups and 0000 serials.
+SSN_PATTERN = re.compile(_BEFORE + r"(?!000|666|9)\d{3}([- ]?)(?!00)\d{2}\1(?!0000)\d{4}" + _AFTER)
+# Card-like numbers: 12 to 19 digits, plain or grouped as printed on cards (4-4-4-x, or
+# 4-6-5 / 4-6-4) with spaces or dashes; only those that pass the Luhn check are redacted.
+CARD_PATTERN = re.compile(
+    _BEFORE + r"(?:\d{12,19}|\d{4}(?P<s>[ -])\d{4}(?P=s)\d{4}(?P=s)\d{1,7}|\d{4}(?P<t>[ -])\d{6}(?P=t)\d{4,5})" + _AFTER
+)
+EMAIL_PATTERN = re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE)
+
+
+def luhn_valid(digits: str) -> bool:
+    total = 0
+    for index, char in enumerate(reversed(digits)):
+        digit = int(char)
+        if index % 2 == 1:
+            digit = digit * 2 - 9 if digit > 4 else digit * 2
+        total += digit
+    return total % 10 == 0
+
+
+def _redact_card(match: re.Match[str]) -> str:
+    digits = re.sub(r"[ -]", "", match.group())
+    return REDACTED if luhn_valid(digits) else match.group()
+
+
+def redact_text(text: str) -> str:
+    text = CARD_PATTERN.sub(_redact_card, text)
+    text = SSN_PATTERN.sub(REDACTED, text)
+    return EMAIL_PATTERN.sub(REDACTED, text)
+
+
+OMITTED_LARGE_FIELDS = {"dom_snapshot", "accessibility_tree"}
+
+# Identifier fields are never pattern-redacted. A UUID group of 12 digits would
+# otherwise match the card-number pattern and corrupt session identity.
+IDENTIFIER_FIELDS = {
+    "session_id",
+    "cdp_session_id",
+    "target_id",
+    "screenshot_file",
+    "guid",
+    "path",
+    "sha256",
+    "uploadId",
+    "browserContextId",
+    "frameId",
+}
+
+
+def redact_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    redacted = _redact_value(payload)
+    if not isinstance(redacted, dict):  # pragma: no cover - dict in, dict out
+        raise TypeError("redaction must preserve the payload mapping")
+    return redacted
+
+
+def _redact_value(value: Any, key: str | None = None) -> Any:
+    if key in OMITTED_LARGE_FIELDS:
+        return {"redacted": True, "reason": "large_capture_payload_omitted"}
+    if isinstance(value, dict):
+        return {item_key: _redact_value(item_value, item_key) for item_key, item_value in value.items()}
+    if isinstance(value, list):
+        return [_redact_value(item) for item in value]
+    if isinstance(value, str):
+        if key in IDENTIFIER_FIELDS:
+            return value
+        return redact_text(value)
+    return value
+
+
+# Text input params that reveal what was typed (Input.insertText, imeSetComposition,
+# dispatchKeyEvent). Named keys such as Enter or Tab are kept.
+SECRET_TEXT_PARAMS = ("text", "unmodifiedText")
+SECRET_KEY_PARAMS = ("key", "code", "windowsVirtualKeyCode", "nativeVirtualKeyCode", "keyIdentifier")
+SECRET_MARKER = "[SECRET]"  # noqa: S105 - a placeholder, not a password
+
+
+def _is_character_key(params: dict[str, Any]) -> bool:
+    key = params.get("key")
+    text = params.get("text")
+    return (isinstance(key, str) and len(key) == 1) or (isinstance(text, str) and bool(text))
+
+
+def mask_secret_input(params: dict[str, Any], *, secret_target: bool) -> dict[str, Any]:
+    """Params for the record when the focused element is a secret field (password, OTP, card).
+
+    Returns a copy; the command sent to the browser is not changed.
+    """
+    if not secret_target:
+        return params
+    masked = dict(params)
+    changed = False
+    for name in SECRET_TEXT_PARAMS:
+        if name in masked:
+            masked[name] = SECRET_MARKER
+            changed = True
+    if _is_character_key(params):
+        for name in SECRET_KEY_PARAMS:
+            if name in masked:
+                masked[name] = SECRET_MARKER
+                changed = True
+    if changed:
+        masked["statelock_redacted"] = "secret_input"
+    return masked