feat(python): add non-spec helpers H01-H19

New hand-maintained modules:
- actions.py: AuthKit Actions request verification and response signing (H03)
- pkce.py: PKCE code verifier/challenge utilities (H08)
- public_client.py: Factory for PKCE-only public client usage (H19)

Session enhancements:
- seal_session_from_auth_response for auth response sealing (H07)

@oagen-ignore blocks in generated files:
- user_management: load_sealed_session, authenticate_with_session_cookie (H05),
  get_authorization_url_with_pkce (H10), authenticate_with_code_pkce (H11)
- sso: get_authorization_url_with_pkce (H15), get_profile_and_token_pkce (H16)

Emitter: wire actions and pkce onto WorkOS/AsyncWorkOS client

Tests for all helpers including webhook verification (H01/H02),
session management (H04/H06), and all new inline helpers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gjtorikian

src/workos/_client.py

@@ -47,7 +47,9 @@
 from .webhooks._resource import Webhooks, AsyncWebhooks
 from .widgets._resource import Widgets, AsyncWidgets
 from .audit_logs._resource import AuditLogs, AsyncAuditLogs
+from .actions import Actions, AsyncActions
 from .passwordless import AsyncPasswordless, Passwordless
+from .pkce import PKCE
 from .vault import AsyncVault, Vault
 
 try:
@@ -446,6 +448,14 @@ def passwordless(self) -> Passwordless:
     def vault(self) -> Vault:
         return Vault(self)
 
+    @functools.cached_property
+    def actions(self) -> Actions:
+        return Actions()
+
+    @functools.cached_property
+    def pkce(self) -> PKCE:
+        return PKCE()
+
     @overload
     def request(
         self,
@@ -697,6 +707,14 @@ def passwordless(self) -> AsyncPasswordless:
     def vault(self) -> AsyncVault:
         return AsyncVault(self)
 
+    @functools.cached_property
+    def actions(self) -> AsyncActions:
+        return AsyncActions()
+
+    @functools.cached_property
+    def pkce(self) -> PKCE:
+        return PKCE()
+
     @overload
     async def request(
         self,

src/workos/actions.py

@@ -0,0 +1,190 @@
+# @oagen-ignore-file
+# This file is hand-maintained. AuthKit Actions helpers for request
+# verification and response signing. These are client-side cryptographic
+# helpers that will always be hand-maintained.
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Literal, Optional, Union
+
+DEFAULT_TOLERANCE = 30  # seconds (stricter than webhooks' 180s)
+
+ActionType = Literal["authentication", "user_registration"]
+
+_ACTION_TYPE_TO_RESPONSE_OBJECT = {
+    "authentication": "authentication_action_response",
+    "user_registration": "user_registration_action_response",
+}
+
+
+def _verify_signature(
+    *,
+    payload: Union[bytes, str],
+    sig_header: str,
+    secret: str,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> None:
+    """Verify an HMAC-SHA256 signature header. Raises ValueError on failure."""
+    try:
+        issued_part, sig_part = sig_header.split(", ")
+    except (ValueError, AttributeError) as exc:
+        raise ValueError(
+            "Unable to extract timestamp and signature hash from header",
+            sig_header,
+        ) from exc
+
+    issued_timestamp = issued_part[2:]
+    signature_hash = sig_part[3:]
+
+    current_time = time.time()
+    timestamp_in_seconds = int(issued_timestamp) / 1000
+    seconds_since_issued = current_time - timestamp_in_seconds
+
+    if seconds_since_issued > tolerance:
+        raise ValueError("Timestamp outside the tolerance zone")
+
+    body_str = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    unhashed_string = f"{issued_timestamp}.{body_str}"
+    expected_signature = hmac.new(
+        secret.encode("utf-8"),
+        unhashed_string.encode("utf-8"),
+        digestmod=hashlib.sha256,
+    ).hexdigest()
+
+    if not hmac.compare_digest(signature_hash, expected_signature):
+        raise ValueError(
+            "Signature hash does not match the expected signature hash for payload"
+        )
+
+
+def _compute_signature(payload_str: str, secret: str) -> str:
+    """Compute HMAC-SHA256 hex digest for a signed payload string."""
+    return hmac.new(
+        secret.encode("utf-8"),
+        payload_str.encode("utf-8"),
+        digestmod=hashlib.sha256,
+    ).hexdigest()
+
+
+class Actions:
+    """AuthKit Actions request verification and response signing."""
+
+    def verify_header(
+        self,
+        *,
+        payload: Union[bytes, str],
+        sig_header: str,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE,
+    ) -> None:
+        """Verify the signature of an Actions request."""
+        _verify_signature(
+            payload=payload, sig_header=sig_header, secret=secret, tolerance=tolerance,
+        )
+
+    def construct_action(
+        self,
+        *,
+        payload: Union[bytes, str],
+        sig_header: str,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE,
+    ) -> Dict[str, Any]:
+        """Verify and deserialize an Actions request payload."""
+        self.verify_header(
+            payload=payload, sig_header=sig_header, secret=secret, tolerance=tolerance,
+        )
+        body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+        return json.loads(body)
+
+    def sign_response(
+        self,
+        *,
+        action_type: ActionType,
+        verdict: Literal["Allow", "Deny"],
+        error_message: Optional[str] = None,
+        secret: str,
+    ) -> Dict[str, Any]:
+        """Build and sign an Actions response."""
+        timestamp = int(time.time() * 1000)
+        response_payload: Dict[str, Any] = {
+            "timestamp": timestamp,
+            "verdict": verdict,
+        }
+        if error_message is not None:
+            response_payload["error_message"] = error_message
+
+        payload_json = json.dumps(response_payload, separators=(",", ":"))
+        signed_payload = f"{timestamp}.{payload_json}"
+        signature = _compute_signature(signed_payload, secret)
+        object_type = _ACTION_TYPE_TO_RESPONSE_OBJECT[action_type]
+
+        return {
+            "object": object_type,
+            "payload": response_payload,
+            "signature": signature,
+        }
+
+
+class AsyncActions:
+    """Async variant of AuthKit Actions helpers."""
+
+    def verify_header(
+        self,
+        *,
+        payload: Union[bytes, str],
+        sig_header: str,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE,
+    ) -> None:
+        """Verify the signature of an Actions request."""
+        _verify_signature(
+            payload=payload, sig_header=sig_header, secret=secret, tolerance=tolerance,
+        )
+
+    def construct_action(
+        self,
+        *,
+        payload: Union[bytes, str],
+        sig_header: str,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE,
+    ) -> Dict[str, Any]:
+        """Verify and deserialize an Actions request payload."""
+        self.verify_header(
+            payload=payload, sig_header=sig_header, secret=secret, tolerance=tolerance,
+        )
+        body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+        return json.loads(body)
+
+    def sign_response(
+        self,
+        *,
+        action_type: ActionType,
+        verdict: Literal["Allow", "Deny"],
+        error_message: Optional[str] = None,
+        secret: str,
+    ) -> Dict[str, Any]:
+        """Build and sign an Actions response."""
+        timestamp = int(time.time() * 1000)
+        response_payload: Dict[str, Any] = {
+            "timestamp": timestamp,
+            "verdict": verdict,
+        }
+        if error_message is not None:
+            response_payload["error_message"] = error_message
+
+        payload_json = json.dumps(response_payload, separators=(",", ":"))
+        signed_payload = f"{timestamp}.{payload_json}"
+        signature = _compute_signature(signed_payload, secret)
+        object_type = _ACTION_TYPE_TO_RESPONSE_OBJECT[action_type]
+
+        return {
+            "object": object_type,
+            "payload": response_payload,
+            "signature": signature,
+        }

src/workos/pkce.py

@@ -0,0 +1,81 @@
+# @oagen-ignore-file
+# This file is hand-maintained. PKCE (Proof Key for Code Exchange) utilities
+# for OAuth 2.0 public client flows. These are client-side cryptographic
+# helpers that will always be hand-maintained.
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(slots=True)
+class PKCEPair:
+    """A PKCE code verifier and challenge pair."""
+
+    code_verifier: str
+    code_challenge: str
+    code_challenge_method: Literal["S256"]
+
+
+def _base64url_encode(data: bytes) -> str:
+    """Base64url-encode bytes without padding, per RFC 7636."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+class PKCE:
+    """PKCE (RFC 7636) code verifier and challenge utilities.
+
+    All operations are synchronous and stateless -- no client or async
+    variant is needed.
+    """
+
+    def generate_code_verifier(self, length: int = 43) -> str:
+        """Generate a cryptographically random code verifier.
+
+        Args:
+            length: Length of the verifier string (43-128 per RFC 7636).
+
+        Returns:
+            A base64url-encoded random string of the requested length.
+
+        Raises:
+            ValueError: If length is outside the 43-128 range.
+        """
+        if length < 43 or length > 128:
+            raise ValueError(
+                f"Code verifier length must be between 43 and 128, got {length}"
+            )
+        num_bytes = (length * 3 + 3) // 4
+        raw = os.urandom(num_bytes)
+        return _base64url_encode(raw)[:length]
+
+    def generate_code_challenge(self, verifier: str) -> str:
+        """Compute the S256 code challenge for a given verifier.
+
+        Args:
+            verifier: The code verifier string.
+
+        Returns:
+            The base64url-encoded SHA-256 hash of the verifier.
+        """
+        digest = hashlib.sha256(verifier.encode("ascii")).digest()
+        return _base64url_encode(digest)
+
+    def generate(self) -> PKCEPair:
+        """Generate a complete PKCE pair (verifier + challenge).
+
+        Returns:
+            A PKCEPair with code_verifier, code_challenge, and
+            code_challenge_method set to "S256".
+        """
+        verifier = self.generate_code_verifier()
+        challenge = self.generate_code_challenge(verifier)
+        return PKCEPair(
+            code_verifier=verifier,
+            code_challenge=challenge,
+            code_challenge_method="S256",
+        )

src/workos/public_client.py

@@ -0,0 +1,36 @@
+# @oagen-ignore-file
+# This file is hand-maintained. Public client factory for PKCE-only /
+# public-client usage (browser, mobile, CLI, desktop applications).
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def create_public_client(
+    *,
+    client_id: str,
+    base_url: Optional[str] = None,
+    request_timeout: Optional[int] = None,
+) -> "WorkOS":
+    """Create a WorkOS client configured for public/PKCE-only usage.
+
+    For browser, mobile, CLI, and desktop applications that cannot securely
+    store an API key. Methods that require an API key will not include
+    authorization headers.
+
+    Args:
+        client_id: The WorkOS client ID.
+        base_url: Override the base URL. Defaults to ``https://api.workos.com``.
+        request_timeout: HTTP request timeout in seconds.
+
+    Returns:
+        A WorkOS client instance with only ``client_id`` configured.
+    """
+    from ._client import WorkOS
+
+    return WorkOS(
+        client_id=client_id,
+        base_url=base_url,
+        request_timeout=request_timeout,
+    )

src/workos/session.py

@@ -105,6 +105,37 @@ def unseal_data(sealed_data: str, key: str) -> Dict[str, Any]:
     return cast(Dict[str, Any], json.loads(decrypted_str))
 
 
+def seal_session_from_auth_response(
+    *,
+    access_token: str,
+    refresh_token: str,
+    user: Optional[Dict[str, Any]] = None,
+    impersonator: Optional[Dict[str, Any]] = None,
+    cookie_password: str,
+) -> str:
+    """Seal session data from an authentication response into a cookie-safe string.
+
+    Args:
+        access_token: The access token from the auth response.
+        refresh_token: The refresh token from the auth response.
+        user: The user dict from the auth response.
+        impersonator: The impersonator dict, if present.
+        cookie_password: The Fernet key used to seal the session.
+
+    Returns:
+        A sealed session string suitable for storing in a cookie.
+    """
+    session_data: Dict[str, Any] = {
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+    }
+    if user is not None:
+        session_data["user"] = user
+    if impersonator is not None:
+        session_data["impersonator"] = impersonator
+    return seal_data(session_data, cookie_password)
+
+
 # ---------------------------------------------------------------------------
 # Session (sync)
 # ---------------------------------------------------------------------------