fancy-buffer 0.1.3__tar.gz → 0.2.0__tar.gz

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@particle-academy/buffer-ui`,
 `@particle-academy/buffer-js`, `particle-academy/buffer-php` and
 `fancy-buffer`.
 
+## [0.2.0] — 2026-11-08
+
+### Added
+
+- **Laravel integration, in this package** (`src/Laravel/`), auto-discovered
+  through composer's `extra.laravel`. Laravel is SUGGESTED, never required:
+  outside a Laravel app none of it loads.
+  - a service provider that merges `config/buffer.php` under
+    `connectors.buffer` (credentials from the environment, or per call for a
+    multi-account app);
+  - the `Buffer` facade: `Buffer::call('<operation>', [...])` runs any action;
+  - `Buffer::fake()`, answered from the connector's faker, with
+    `assertSent` / `assertNotSent` / `assertNothingSent` / `assertSentCount`;
+  - its own Pest test of all of it against a booted Laravel app.
+
+### Changed
+
+- **Tests: Pest `^5`**, and `laravel/framework` `^13` as a DEV-ONLY test
+  dependency (the framework this package integrates with; nothing ships in
+  `require`).
+
 ## [0.1.3] — 2026-09-12
 
 ### Changed

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fancy-buffer
-Version: 0.1.3
+Version: 0.2.0
 Summary: Buffer for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
 Project-URL: Homepage, https://github.com/Fancy-Friends/buffer
 Project-URL: Issues, https://github.com/Fancy-Friends/buffer/issues
@@ -22,6 +22,8 @@ Description-Content-Type: text/markdown
 
 # Buffer
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 Buffer for [fancy-flow][flow] — as **four imported, versioned packages**, one
 per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
 change.

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/README.md

@@ -1,5 +1,7 @@
 # Buffer
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 Buffer for [fancy-flow][flow] — as **four imported, versioned packages**, one
 per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
 change.

fancy_buffer-0.2.0/art/fancified.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="28" role="img" aria-label="Fancified — built with Fancy UI">
+  <title>Fancified · built with Fancy UI</title>
+  <defs>
+    <linearGradient id="fcdBg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6d28d9"/>
+      <stop offset=".5" stop-color="#9333ea"/>
+      <stop offset="1" stop-color="#d946ef"/>
+    </linearGradient>
+    <linearGradient id="fcdGloss" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff" stop-opacity=".30"/>
+      <stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
+    </linearGradient>
+    <clipPath id="fcdClip"><rect width="128" height="28" rx="7"/></clipPath>
+  </defs>
+  <g clip-path="url(#fcdClip)">
+    <rect width="128" height="28" fill="url(#fcdBg)"/>
+    <rect width="34" height="28" fill="#3b0764" fill-opacity=".5"/>
+    <rect width="128" height="13" fill="url(#fcdGloss)"/>
+    <g fill="#fff">
+      <path transform="translate(17 14)" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+      <path transform="translate(25.5 7.5) scale(.34)" fill-opacity=".85" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+    </g>
+    <text x="81" y="18.5" fill="#ffffff" text-anchor="middle" font-family="'Segoe UI',Verdana,'DejaVu Sans',sans-serif" font-size="12" font-weight="700" letter-spacing=".3">Fancified</text>
+  </g>
+  <rect x=".5" y=".5" width="127" height="27" rx="6.5" fill="none" stroke="#ffffff" stroke-opacity=".22"/>
+</svg>

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-buffer"
-version = "0.1.3"
+version = "0.2.0"
 description = "Buffer for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK."
 readme = "README.md"
 # 3.11 matches fancy-flow-py's floor: 3.10 reaches end of life on 2026-10-31,
@@ -49,7 +49,7 @@ dev = [{ include-group = "test" }, { include-group = "lint" }, { include-group =
 packages = ["src/fancy_buffer"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/tests", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+include = ["/src", "/tests", "/art", "/README.md", "/CHANGELOG.md", "/LICENSE"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/src/fancy_buffer/__init__.py

@@ -21,7 +21,7 @@ from .actions.post_create import post_create
 from .faker import respond
 from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
 
-__version__ = "0.1.3"
+__version__ = "0.2.0"
 
 __all__ = [
     "BASE_URLS",

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/src/fancy_buffer/_runtime.py

@@ -308,14 +308,22 @@ _ALGORITHMS = {"sha256": hashlib.sha256, "sha1": hashlib.sha1, "sha512": hashlib
 def verify_hmac(
     *,
     raw: str,
-    signature: str | None,
+    signature: str | list[str] | None,
     secret: str | None,
-    payload: Callable[[str, str | None], str],
+    payload: Callable[..., str],
     algorithm: str,
     encoding: str = "hex",
     tolerance: int | None = None,
     timestamp: str | None = None,
     now: int | None = None,
+    secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one
+    secret_prefix: str | None = None,
+    id: str | None = None,
+    timestamp_unit: str = "s",
+    signs_request_line: bool = False,
+    uri: str | None = None,
+    method: str | None = None,
+    url: str | None = None,
 ) -> Verification:
     """Verify one inbound delivery.
 
@@ -327,44 +335,234 @@ def verify_hmac(
     ``raw`` must be the body EXACTLY as received. Re-serialised JSON changes key
     order and whitespace and produces a mismatch that looks precisely like a
     wrong secret.
+
+    ``secret_encoding`` says how the SECRET is spelled: ``utf8`` (the default,
+    every provider before Svix — the key is the text's bytes) or ``base64``
+    (the key is the DECODED bytes; Svix's ``whsec_<base64>``, half of whose
+    bytes are not UTF-8). ``secret_prefix`` is stripped first, and its absence
+    is a refusal, never a guess.
     """
     if not secret:
         return Verification(False, "no signing secret is configured for this connection")
-    if not signature:
+
+    # A LIST when the provider sends several — Stripe signs once per active
+    # secret while a secret is rolled, Svix's header "could be any number of
+    # signatures" — and the delivery is accepted when ANY matches. A first-only
+    # rule fails every delivery whose first signature came from the new secret.
+    offered = signature if isinstance(signature, list) else [signature]
+    candidates = [s for s in offered if isinstance(s, str) and s]
+    if not candidates:
         return Verification(False, "the delivery carried no signature")
 
     digest = _ALGORITHMS.get(algorithm)
     if digest is None:
         return Verification(False, f'unsupported signature algorithm "{algorithm}"')
 
+    # The key is checked BEFORE anything is signed, so a secret that cannot be
+    # a key is named as such rather than producing a mismatch that reads like a
+    # wrong secret.
+    key = _secret_key_bytes(secret, secret_encoding, secret_prefix)
+    if isinstance(key, Verification):
+        return key
+
     if tolerance is not None:
         if not timestamp:
             return Verification(
                 False, "the delivery carried no timestamp, and this scheme signs one"
             )
         try:
-            sent = int(float(timestamp))
+            sent = float(timestamp)
         except (TypeError, ValueError):
             return Verification(False, f'the delivery timestamp "{timestamp}" is not a number')
+        # Converted, never compared raw: HubSpot sends MILLISECONDS, and a
+        # millisecond value against a window in seconds refuses every delivery.
+        if timestamp_unit == "ms":
+            sent = sent / 1000
 
         current = int(time.time()) if now is None else now
         if abs(current - sent) > tolerance:
             return Verification(
                 False,
                 f"the delivery is outside the {tolerance}s replay window "
-                f"({abs(current - sent)}s old)",
+                f"({int(abs(current - sent))}s old)",
             )
 
-    computed = hmac.new(secret.encode(), payload(raw, timestamp).encode(), digest)
+    # A payload that signs the delivery's ID (Svix) takes it as a third argument;
+    # the two-argument payloads every earlier scheme wrote are called as before.
+    # HubSpot v3 signs the REQUEST LINE: refused by name without it, and the
+    # uri normalised here, once, by the scheme's rule.
+    if signs_request_line:
+        if not method or not url:
+            return Verification(False, "the delivery carried no request method or url")
+        line = {"method": method, "uri": normalise_signed_uri(url, uri) if uri else url}
+        signed = payload(raw, timestamp, id, line)
+    else:
+        signed = payload(raw, timestamp) if id is None else payload(raw, timestamp, id)
+    computed = hmac.new(key, signed.encode(), digest)
     expected = computed.hexdigest() if encoding == "hex" else _b64(computed.digest())
 
-    # Constant time, so a signature cannot be discovered one character at a time.
-    if not hmac.compare_digest(expected, signature):
+    # Constant time per candidate, so a signature cannot be discovered one
+    # character at a time; which candidate matched is not a secret.
+    if not any(hmac.compare_digest(expected, candidate) for candidate in candidates):
         return Verification(False, "the signature does not match")
 
     return Verification(True)
 
 
+_HUBSPOT_V3_DECODE = {
+    "%3A": ":", "%2F": "/", "%3F": "?", "%40": "@", "%21": "!", "%24": "$",
+    "%27": "'", "%28": "(", "%29": ")", "%2A": "*", "%2C": ",", "%3B": ";",
+}
+
+
+def normalise_signed_uri(url: str, rule: str) -> str:
+    """The URI a provider signs, from the URL the request arrived on.
+
+    ``hubspot-v3``: only the QUERY portion is percent-decoded, and only for
+    twelve escapes (case-insensitive); never its leading ``?``; any
+    ``#fragment`` dropped. ``%26`` and ``%3D`` stay as sent. The twin of the
+    core's ``normaliseSignedUri``.
+    """
+    import re
+
+    if rule != "hubspot-v3":
+        raise ValueError(f"unknown signed-uri rule {rule!r}")
+    without_fragment = url.split("#", 1)[0]
+    base, sep, query = without_fragment.partition("?")
+    if not sep:
+        return without_fragment
+    decoded = re.sub(
+        r"%[0-9A-Fa-f]{2}", lambda m: _HUBSPOT_V3_DECODE.get(m.group(0).upper(), m.group(0)), query
+    )
+    return f"{base}?{decoded}"
+
+
+def _secret_key_bytes(
+    secret: str,
+    secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one
+    secret_prefix: str | None = None,
+) -> bytes | Verification:
+    """The HMAC key a scheme's secret spells, or the refusal it earns."""
+    import base64
+    import binascii
+    import json
+    import re
+
+    material = secret
+    if secret_prefix is not None:
+        if not material.startswith(secret_prefix):
+            return Verification(
+                False, f"signing secret does not start with {json.dumps(secret_prefix)}"
+            )
+        material = material[len(secret_prefix) :]
+
+    if secret_encoding == "base64":  # noqa: S105 — a spelling, not a password
+        # Strict: a lenient decode of a KEY is a key nobody can reason about.
+        well_formed = re.fullmatch(r"[A-Za-z0-9+/]*={0,2}", material) is not None
+        if not material or len(material) % 4 != 0 or not well_formed:
+            return Verification(False, "signing secret is not valid base64")
+        try:
+            return base64.b64decode(material, validate=True)
+        except (binascii.Error, ValueError):
+            return Verification(False, "signing secret is not valid base64")
+
+    return material.encode()
+
+
+def verify_shared_token(
+    *,
+    raw: str,
+    headers: dict[str, str],
+    secret: str | None,
+    placement: str,
+    name: str,
+) -> Verification:
+    """Verify a delivery by a token the provider ECHOES rather than a signature it computes.
+
+    Google Calendar sends the channel's ``token`` back in ``X-Goog-Channel-Token``
+    on every notification — with an EMPTY body, so there is nothing to sign.
+    Microsoft Graph sends ``clientState`` inside every item of the
+    notification's ``value`` array. Same refusal-by-default as ``verify_hmac``,
+    same result shape, and a constant-time comparison: a token is a secret.
+
+    ``placement`` is ``header`` (then ``name`` is the header) or ``body`` (then
+    ``name`` is a dotted path into the JSON body; a segment ending in ``[]``
+    means EVERY element of that array, all of which must match — one wrong item
+    refuses the whole delivery). The reasons are the connector core's exact
+    strings, so a host logs the same words whichever runtime answered.
+    """
+    if not secret:
+        return Verification(False, "no shared token configured for this trigger")
+
+    tokens: list[Any]
+    if placement == "header":
+        tokens = [next((v for k, v in headers.items() if k.lower() == name.lower()), None)]
+    else:
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            return Verification(False, "delivery body is not JSON")
+        tokens = _read_tokens(parsed, name.split("."))
+
+    present = [t for t in tokens if t is not None and t != ""]
+    if not present:
+        return Verification(False, "delivery carried no token")
+
+    # Every element is compared, none is skipped: a batch is accepted as a whole
+    # or refused as a whole.
+    matched = len(present) == len(tokens)
+    for token in present:
+        matched = (isinstance(token, str) and hmac.compare_digest(secret, token)) and matched
+
+    return Verification(True) if matched else Verification(False, "token did not match")
+
+
+def _read_tokens(value: Any, segments: list[str]) -> list[Any]:
+    """Every value at a dotted path; a ``[]`` segment fans out over a list. Absent is None."""
+    if not segments:
+        return [value]
+
+    head, rest = segments[0], segments[1:]
+    each_element = head.endswith("[]")
+    key = head[:-2] if each_element else head
+
+    if not isinstance(value, dict) or key not in value:
+        return [None]
+    nxt = value[key]
+
+    if not each_element:
+        return _read_tokens(nxt, rest)
+    if not isinstance(nxt, list):
+        return [None]
+
+    found: list[Any] = []
+    for element in nxt:
+        found.extend(_read_tokens(element, rest))
+
+    return found
+
+
+def handshake_response(
+    param: str | None, query: dict[str, str | list[str]], content_type: str = "text/plain"
+) -> dict[str, Any] | None:
+    """Answer a provider's challenge — Graph POSTs ``?validationToken=…`` when a
+    subscription is created and refuses to create it unless the token comes
+    back, decoded, as ``text/plain``. The pure half: what to send, or None when
+    the request is not a challenge at all (no parameter, an empty one, or a
+    trigger that declares no handshake). ``query`` is already URL-decoded by
+    the framework.
+    """
+    if param is None:
+        return None
+
+    raw = query.get(param)
+    token = raw[0] if isinstance(raw, list) and raw else raw
+    if not token or isinstance(token, list):
+        return None
+
+    return {"status": 200, "contentType": content_type, "body": token}
+
+
 def _b64(raw: bytes) -> str:
     import base64
 

{fancy_buffer-0.1.3 → fancy_buffer-0.2.0}/src/fancy_buffer/faker.py

@@ -24,6 +24,18 @@ from typing import Any
 from ._fake import FakeValues
 
 
+def _as_number(value: Any) -> float | None:
+    """The coercion an `"as": "integer" | "number"` config binding uses: a value
+    that IS a number, never int(float(...))'s uncaught ValueError on one that
+    merely looks like text (a text field's auto-generated example, before an
+    author has typed a real one).
+    """
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
 def _post_create(config: dict[str, Any], fake: FakeValues) -> Any:
     return {
         "data": {