voltkit-rtc-server 0.1.0__py3-none-any.whl

voltkit_rtc/server/__init__.py

@@ -0,0 +1,114 @@
+"""
+Server SDK for VoltKit RTC: rooms, tokens, chat, broadcast streams, usage,
+billing and verified webhooks. Standard library only.
+
+    from voltkit_rtc.server import StreamClient
+
+    rtc = StreamClient(os.environ["VOLTKIT_RTC_URL"], os.environ["VOLTKIT_RTC_SECRET"])
+    room = rtc.ensure_room("show-42", host_identity="user-7")
+    token = rtc.create_token("show-42", identity="user-99", role="viewer")
+
+The API secret is tenant-wide, so it stays on your server, and the SDK
+attaches it only to requests for ``base_url``, never across a redirect.
+"""
+
+from ._version import __version__
+from .client import DEFAULT_RETRIES, DEFAULT_TIMEOUT, MAX_TIMEOUT, RATES_PATH, USER_AGENT, StreamClient
+from .errors import ERROR_CODES, REST_ERROR_CODES, ErrorInfo, StreamError, error_info, is_terminal
+from .transport import HttpClientTransport, Transport, TransportError, TransportRequest, TransportResponse
+from .types import (
+    Allowance,
+    BroadcastStream,
+    BroadcastStreamWithPublish,
+    BurnView,
+    ChatInfo,
+    ChatMessage,
+    ChatToken,
+    DailyUsage,
+    LegacyFunds,
+    Participant,
+    PlaybackPolicy,
+    PlaybackUrls,
+    ProjectBalance,
+    PublishGrant,
+    Role,
+    Room,
+    RoomList,
+    RoomToken,
+    RoomView,
+    RoomWithHostToken,
+    RtcConversion,
+    RtcMode,
+    RtcRates,
+    RtcSurcharge,
+    RtcTierRate,
+    RtcUnit,
+    StreamAction,
+    StreamEvent,
+    StreamToken,
+    Usage,
+    UsageSummary,
+    WalletFunds,
+    WalletLowState,
+    WalletScopeAmount,
+)
+from .webhooks import DEFAULT_TOLERANCE_SECONDS, MAX_HEADER_LENGTH, parse_webhook, verify_webhook
+
+__all__ = [
+    "__version__",
+    "StreamClient",
+    "StreamError",
+    "ErrorInfo",
+    "ERROR_CODES",
+    "REST_ERROR_CODES",
+    "error_info",
+    "is_terminal",
+    "verify_webhook",
+    "parse_webhook",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "MAX_HEADER_LENGTH",
+    "RATES_PATH",
+    "USER_AGENT",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_RETRIES",
+    "MAX_TIMEOUT",
+    "Transport",
+    "TransportRequest",
+    "TransportResponse",
+    "TransportError",
+    "HttpClientTransport",
+    "Allowance",
+    "BroadcastStream",
+    "BroadcastStreamWithPublish",
+    "BurnView",
+    "ChatInfo",
+    "ChatMessage",
+    "ChatToken",
+    "DailyUsage",
+    "LegacyFunds",
+    "Participant",
+    "PlaybackPolicy",
+    "PlaybackUrls",
+    "ProjectBalance",
+    "PublishGrant",
+    "Role",
+    "Room",
+    "RoomList",
+    "RoomToken",
+    "RoomView",
+    "RoomWithHostToken",
+    "RtcConversion",
+    "RtcMode",
+    "RtcRates",
+    "RtcSurcharge",
+    "RtcTierRate",
+    "RtcUnit",
+    "StreamAction",
+    "StreamEvent",
+    "StreamToken",
+    "Usage",
+    "UsageSummary",
+    "WalletFunds",
+    "WalletLowState",
+    "WalletScopeAmount",
+]

voltkit_rtc/server/_redaction.py

@@ -0,0 +1,333 @@
+"""
+What keeps the API key out of anything a caller might log: the checks a key
+passes when the client is made, and the redaction of the key, however it is
+encoded, and of URL credentials from someone else's words (the server's reply,
+a redirect's target, the transport's own error). The SDK's own words never
+hold the key, so only quoted text comes through here.
+
+The forms looked for and the limits are the Node SDK's (server-sdk/src/index.ts,
+keyRedactorOf and keyPatternOf); docs/server-sdk-vectors.json pins them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+from collections.abc import Mapping, Sequence
+from typing import Callable, Optional, Union
+
+__all__ = [
+    "KEY_NOT_CHECKED",
+    "LONGEST_KEY_LOOKED_FOR",
+    "MARKER",
+    "KeyRedactor",
+    "check_api_key",
+    "hide_url_credentials",
+    "key_pattern_of",
+]
+
+#: What replaces the key, and the credentials of a URL.
+MARKER = "[redacted]"
+#: What replaces words that could not be checked for the key.
+KEY_NOT_CHECKED = "[not shown: it could not be checked for the API key]"
+#: The longest key redaction looks for: the pattern grows with the key, and a
+#: key this long is already not one the controller issued.
+LONGEST_KEY_LOOKED_FOR = 256
+
+#: Spaces, tabs and line breaks at either end of a header value: fetch drops
+#: them before sending; this SDK trims them itself and sends the net key.
+HEADER_WHITESPACE = " \t\r\n"
+
+# JavaScript's \s, so that words and URL credentials are read the way the Node
+# SDK reads them (Python's \s differs at the edges).
+_JS_SPACE = "\t\n\x0b\x0c\r    - 

  　"
+_WORD = re.compile("[^%s]+" % _JS_SPACE)
+_ANY_SPACE = re.compile("[%s]" % _JS_SPACE)
+# A character no HTTP header can carry: a line break, a NUL, another control
+# character, DEL, or anything above U+00FF.
+_HEADER_UNSAFE = re.compile("[^\t\x20-\x7e\x80-\xff]")
+# A backslash (JSON doubles it, and a run of them made the pattern backtrack
+# exponentially) or a Latin-1 letter (sent as one byte that servers echo as
+# U+FFFD, a ?, or mojibake, which no pattern can list). No VoltKit key holds
+# either: the controller issues sk_ and hex digits.
+_NOT_A_VOLTKIT_KEY = re.compile("[\\\\\x80-\xff]")
+
+
+def check_api_key(api_key: object) -> str:
+    """The key as it will be sent, or a TypeError that never quotes it."""
+    if api_key is None or api_key == "":
+        raise TypeError("api_key is required")
+    if not isinstance(api_key, str):
+        raise TypeError("api_key must be a str, got %s" % type(api_key).__name__)
+    sent = api_key.strip(HEADER_WHITESPACE)
+    # Only whitespace (a bare line break from a file or an environment
+    # variable): every call would send an empty X-API-Key and fail with 401,
+    # far from the mistake.
+    if sent == "":
+        raise TypeError("api_key is required: the one given is only whitespace")
+    if _HEADER_UNSAFE.search(sent):
+        raise TypeError(
+            "api_key holds a character no HTTP header can carry: a line break, a NUL, another control "
+            "character, or one above U+00FF. Check how the key is loaded (it is not shown here)"
+        )
+    if _NOT_A_VOLTKIT_KEY.search(sent):
+        raise TypeError(
+            "api_key holds a character no VoltKit key has: a backslash, or one outside ASCII such as an "
+            "accented letter. Check how the key is loaded (it is not shown here)"
+        )
+    return sent
+
+
+# --- URL credentials -----------------------------------------------------------
+
+# A URL's credentials: a run of scheme characters, `://`, then the user info up
+# to the last @ before whitespace, `/`, `?` or `#` (a password holding an @ is
+# taken out whole). The lookbehind starts a match only at the first character
+# of such a run: tried from every character of a long run of letters, as the
+# Node SDK once did, a large page took seconds (N044-2). A run with no letter
+# in it is not a scheme and is left alone, so the matches are the Node SDK's.
+_URL_CREDENTIALS = re.compile("(?<![A-Za-z0-9+.\\-])([A-Za-z0-9+.\\-]+://)[^%s/?#]*@" % _JS_SPACE)
+_A_LETTER = re.compile("[A-Za-z]")
+
+
+def _hide(match: re.Match[str]) -> str:
+    run = match.group(1)
+    if _A_LETTER.search(run) is None:
+        return match.group(0)
+    return run + MARKER + "@"
+
+
+def hide_url_credentials(text: str) -> str:
+    """`text` with every `scheme://user:pass@` shown as `scheme://[redacted]@`."""
+    return _URL_CREDENTIALS.sub(_hide, text)
+
+
+# --- the key, in every encoding a reply can hold -----------------------------
+
+#: One character of an encoded form: the character, and its pattern (a hex
+#: digit, or the x of &#x, in either case).
+Piece = tuple[str, str]
+
+
+def _pieces_of(text: str) -> list[Piece]:
+    return [(ch, re.escape(ch)) for ch in text]
+
+
+def _hex_pieces_of(code: int, width: int) -> list[Piece]:
+    return [
+        (digit, "[%s%s]" % (digit, digit.lower()) if digit in "ABCDEF" else digit)
+        for digit in format(code, "X").rjust(width, "0")
+    ]
+
+
+def _percent_of(code: int) -> list[Piece]:
+    return _pieces_of("%") + _hex_pieces_of(code, 2)
+
+
+def _hex_reference_of(code: int) -> list[Piece]:
+    return _pieces_of("&#") + [("x", "[Xx]")] + _hex_pieces_of(code, 1) + _pieces_of(";")
+
+
+def _decimal_reference_of(code: int, width: int = 1) -> list[Piece]:
+    return _pieces_of("&#%s;" % str(code).rjust(width, "0"))
+
+
+#: The HTML5 named references of the characters a key may hold, and of the
+#: backslash, which escapes hold.
+_HTML_NAMES: Mapping[str, Sequence[str]] = {
+    "\t": ("Tab",),
+    "!": ("excl",),
+    '"': ("quot", "QUOT"),
+    "#": ("num",),
+    "$": ("dollar",),
+    "%": ("percnt",),
+    "&": ("amp", "AMP"),
+    "'": ("apos",),
+    "(": ("lpar",),
+    ")": ("rpar",),
+    "*": ("ast", "midast"),
+    "+": ("plus",),
+    ",": ("comma",),
+    ".": ("period",),
+    "/": ("sol",),
+    ":": ("colon",),
+    ";": ("semi",),
+    "<": ("lt", "LT"),
+    "=": ("equals",),
+    ">": ("gt", "GT"),
+    "?": ("quest",),
+    "@": ("commat",),
+    "[": ("lsqb", "lbrack"),
+    "\\": ("bsol",),
+    "]": ("rsqb", "rbrack"),
+    "^": ("Hat",),
+    "_": ("lowbar", "UnderBar"),
+    "`": ("grave", "DiacriticalGrave"),
+    "{": ("lcub", "lbrace"),
+    "|": ("verbar", "vert", "VerticalLine"),
+    "}": ("rcub", "rbrace"),
+}
+
+#: The characters one-layer escapes are made of, other than letters and digits:
+#: all a second escaper changes.
+_ESCAPE_CHARACTERS = '%\\"&#;/+'
+
+Escaper = Mapping[str, list[Piece]]
+
+
+def _escaping(chars: str, encode: Callable[[int], list[Piece]]) -> dict[str, list[Piece]]:
+    return {ch: encode(ord(ch)) for ch in chars}
+
+
+# URL: encodeURIComponent, URLSearchParams and Python's quote(safe='') encode
+# each of these; Python's quote() and encodeURI keep /, which matters only for
+# PHP's \/ (%5C/).
+_URL_ENCODED = _escaping(_ESCAPE_CHARACTERS, _percent_of)
+_URL_ENCODED_BUT_SLASH = _escaping('%\\"&#;+', _percent_of)
+# HTML: PHP's htmlentities with ENT_HTML5 names each character, OWASP's
+# encoders write &#x..; for each, others &#..;.
+_HTML_NAMED = _escaping(_ESCAPE_CHARACTERS, lambda code: _pieces_of("&%s;" % _HTML_NAMES[chr(code)][0]))
+_HTML_HEX = _escaping(_ESCAPE_CHARACTERS, _hex_reference_of)
+_HTML_DECIMAL = _escaping(_ESCAPE_CHARACTERS, _decimal_reference_of)
+
+_NO_ESCAPER: dict[str, list[Piece]] = {}
+
+#: The standard escapers, each as what it makes of the escape characters: a
+#: second layer is one run over a first.
+_ESCAPERS: Sequence[Escaper] = (
+    _URL_ENCODED,
+    _URL_ENCODED_BUT_SLASH,
+    # JSON: JSON.stringify and json.dumps write \ as \\ and " as \"; Go's
+    # json.Marshal writes & as & too, PHP's json_encode / as \/.
+    {"\\": _pieces_of("\\\\"), '"': _pieces_of('\\"'), "&": _pieces_of("\\u0026")},
+    {"\\": _pieces_of("\\\\"), '"': _pieces_of('\\"'), "/": _pieces_of("\\/")},
+    # HTML: html.escape, htmlspecialchars and lodash write &quot;, Go &#34;.
+    {"&": _pieces_of("&amp;"), '"': _pieces_of("&quot;")},
+    {"&": _pieces_of("&amp;"), '"': _pieces_of("&#34;")},
+    _HTML_NAMED,
+    _HTML_HEX,
+    _HTML_DECIMAL,
+)
+
+
+def _one_layer_forms_of(ch: str) -> list[list[Piece]]:
+    """
+    Every form one escaper gives `ch`: itself; its byte as %XX in either hex
+    case; + for a space; its JSON escapes (\\", \\t, PHP's \\/, \\uXXXX); and its
+    HTML references, named, decimal (PHP's &#039; included) and hex.
+    """
+    code = ord(ch)
+    forms = [
+        _pieces_of(ch),
+        _percent_of(code),
+        _pieces_of("\\u") + _hex_pieces_of(code, 4),
+        _decimal_reference_of(code),
+        _decimal_reference_of(code, 3),
+        _hex_reference_of(code),
+    ]
+    forms.extend(_pieces_of("&%s;" % name) for name in _HTML_NAMES.get(ch, ()))
+    if ch == " ":
+        forms.append(_pieces_of("+"))
+    escaped = json.dumps(ch)[1:-1]
+    if escaped != ch:
+        forms.append(_pieces_of(escaped))
+    if ch == "/":
+        forms.append(_pieces_of("\\/"))
+    return forms
+
+
+# Each character's alternatives, built once per process (there are at most 96)
+# and shared by every client.
+_ALTERNATIVES: dict[str, str] = {}
+
+
+def _alternatives_of(ch: str) -> str:
+    cached = _ALTERNATIVES.get(ch)
+    if cached is not None:
+        return cached
+    # An insertion-ordered set: the order of the alternatives is the Node
+    # SDK's, so both engines, which take the first alternative that leads to a
+    # match, replace the same text.
+    patterns: dict[str, None] = {}
+    for form in _one_layer_forms_of(ch):
+        for escaper in (_NO_ESCAPER, *_ESCAPERS):
+            patterns["".join(piece[1] for original in form for piece in escaper.get(original[0], [original]))] = None
+    alternatives = "(?:%s)" % "|".join(patterns)
+    _ALTERNATIVES[ch] = alternatives
+    return alternatives
+
+
+def key_pattern_of(key: str) -> re.Pattern[str]:
+    """
+    The key in any encoding someone else's words can hold, as one pattern: each
+    character in each of its one-layer forms, and each of those run through
+    every standard escaper once more (%252F, \\\\\\/, \\&quot;), since a reply is
+    often escaped twice. Each alternative is a fixed sequence for one character
+    and there is no quantifier, so a match covers the whole key in order and
+    unrelated text is untouched. That holds because check_api_key has run: no
+    character of the key is a backslash or above U+007F.
+    """
+    return re.compile("".join(_alternatives_of(ch) for ch in key))
+
+
+_Pattern = Union[re.Pattern[str], None, bool]
+
+
+class KeyRedactor:
+    """
+    Replaces `key`, in any form key_pattern_of knows, by [redacted].
+
+    The pattern is built for the first text, not with the client: most clients
+    never see an error, and building it is what redaction costs. It fails
+    closed: for a key too long to look for, or a pattern the engine cannot
+    compile, each word (a run of non-whitespace) at least as long as the key
+    is replaced by KEY_NOT_CHECKED and shorter words are kept, since every
+    form of the key is at least as long as the key and, when the key holds no
+    whitespace, lies within one word. A key holding whitespace (a tab) could be
+    split across words: then the whole text goes, unless it is shorter than
+    the key. A pattern that failed is not tried again.
+    """
+
+    __slots__ = ("_key", "_lock", "_pattern")
+
+    def __init__(self, key: str) -> None:
+        self._key = key
+        self._lock = threading.Lock()
+        # None: not built yet; False: not looked for (too long, or the build failed).
+        self._pattern: _Pattern = False if len(key) > LONGEST_KEY_LOOKED_FOR else None
+
+    def __repr__(self) -> str:
+        return "<secrets>"
+
+    def __call__(self, text: str) -> str:
+        pattern = self._pattern
+        if pattern is None:
+            # Built once, whichever thread reports the first error.
+            with self._lock:
+                if self._pattern is None:
+                    try:
+                        self._pattern = key_pattern_of(self._key)
+                    except Exception:
+                        self._pattern = False
+                pattern = self._pattern
+        if pattern is not False and pattern is not None and pattern is not True:
+            try:
+                return pattern.sub(MARKER, text)
+            except Exception:
+                self._pattern = False
+        if _ANY_SPACE.search(self._key):
+            return text if len(text) < len(self._key) else KEY_NOT_CHECKED
+        return _WORD.sub(self._word, text)
+
+    def _word(self, match: re.Match[str]) -> str:
+        word = match.group(0)
+        return word if len(word) < len(self._key) else KEY_NOT_CHECKED
+
+    @property
+    def built(self) -> Optional[bool]:
+        """None before the first text; True once the pattern exists; False when it is not looked for."""
+        pattern = self._pattern
+        if pattern is None:
+            return None
+        return pattern is not False

voltkit_rtc/server/_version.py

@@ -0,0 +1,3 @@
+"""The package version, on its own so every module can read it without importing the package."""
+
+__version__ = "0.1.0"