vigrise 0.1.0__py3-none-any.whl

vigrise/__init__.py

@@ -0,0 +1,4 @@
+"""ViGrise SDK: VGR4 request signing, ViGrise Accounts, ViGrise Storage and the Speech API.
+
+Import the module you need: `vigrise.auth`, `vigrise.speech`, `vigrise.storage` or `vigrise.accounts`.
+"""

vigrise/_common/__init__.py

@@ -0,0 +1 @@
+"""Code the services share: endpoint resolution, signed requests, multipart bodies, pagination and the error envelope."""

vigrise/_common/endpoint.py

@@ -0,0 +1,38 @@
+"""Where a ViGrise service lives: the explicit endpoint, then `VIGRISE_ENDPOINT_URL_<SERVICE>`, then
+`VIGRISE_ENDPOINT_URL`, then `https://<service>-api.vigrise.com`."""
+
+import os
+from typing import Mapping, Optional
+
+ASSUME_ROLE_PATH = "/v1/assume-role"
+
+
+def env_key(service: str) -> str:
+  """The environment variable of one service, such as `VIGRISE_ENDPOINT_URL_VOICE_STUDIO` for `voice-studio`."""
+  return "VIGRISE_ENDPOINT_URL_" + service.upper().replace("-", "_")
+
+
+def resolve_endpoint(
+  service: str, explicit: Optional[str] = None, env: Optional[Mapping[str, str]] = None
+) -> str:
+  """The endpoint of `service`. Empty values count as unset and a trailing slash is dropped."""
+  env = os.environ if env is None else env
+  endpoint = (
+    explicit
+    or env.get(env_key(service))
+    or env.get("VIGRISE_ENDPOINT_URL")
+    or f"https://{service}-api.vigrise.com"
+  )
+  return endpoint.rstrip("/")
+
+
+def sts_url(explicit: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> str:
+  """The URL of the role session call. The STS endpoint is accepted with or without the `/v1/assume-role` path."""
+  endpoint = resolve_endpoint("sts", explicit, env)
+  return endpoint if endpoint.endswith(ASSUME_ROLE_PATH) else endpoint + ASSUME_ROLE_PATH
+
+
+def sts_base_url(explicit: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> str:
+  """The base URL of the STS endpoint, without the `/v1/assume-role` path."""
+  endpoint = resolve_endpoint("sts", explicit, env)
+  return endpoint[: -len(ASSUME_ROLE_PATH)] if endpoint.endswith(ASSUME_ROLE_PATH) else endpoint

vigrise/_common/envelope.py

@@ -0,0 +1,30 @@
+"""The error envelope of the service APIs: `{"error": {"code", "message", ...}}`."""
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class ErrorEnvelope:
+  code: Optional[str]
+  message: str
+  # The resource an answer refers to.
+  resource_id: Optional[str]
+  # The fields besides `code`, `message` and `resource_id`.
+  details: Dict[str, Any]
+
+
+def parse_error_envelope(body: bytes) -> Optional[ErrorEnvelope]:
+  """The envelope a response body carries; None when the body is not one."""
+  try:
+    envelope = json.loads(body).get("error")
+  except (ValueError, AttributeError):
+    return None
+  if not isinstance(envelope, dict):
+    return None
+  details = dict(envelope)
+  code = details.pop("code", None)
+  message = details.pop("message", "")
+  resource_id = details.pop("resource_id", None)
+  return ErrorEnvelope(code if isinstance(code, str) else None, message, resource_id, details)

vigrise/_common/http.py

@@ -0,0 +1,69 @@
+"""Request building shared by the service clients: the sync and async clients differ only in sending."""
+
+from dataclasses import dataclass, field
+from typing import AsyncIterable, Dict, Iterable, List, Optional, Tuple, Union
+from urllib.parse import quote
+
+from ..auth import UNSIGNED_PAYLOAD, sign_request
+from ..auth.credentials import CredentialsSource, credentials_from
+
+
+@dataclass
+class Request:
+  """A request before it is signed: the path is relative to the endpoint."""
+
+  method: str
+  path: str
+  query: List[Tuple[str, str]] = field(default_factory=list)
+  headers: Dict[str, str] = field(default_factory=dict)
+  content: bytes = b""
+  # A body that streams; it is signed as UNSIGNED_PAYLOAD and needs a content-length header.
+  stream: Optional[Union[Iterable[bytes], AsyncIterable[bytes]]] = None
+
+
+def segment(value: str) -> str:
+  """A path segment with everything but unreserved characters percent-encoded."""
+  return quote(value, safe="")
+
+
+def query_pairs(**values: object) -> List[Tuple[str, str]]:
+  """The query parameters that have a value, in the order given; booleans are `true` or `false`."""
+  pairs = []
+  for name, value in values.items():
+    if value is None:
+      continue
+    pairs.append(
+      (
+        name,
+        ("true" if value else "false")
+        if isinstance(value, bool)
+        else str(getattr(value, "value", value)),
+      )
+    )
+  return pairs
+
+
+def encode_query(pairs: Iterable[Tuple[str, str]]) -> str:
+  return "&".join(f"{quote(name, safe='')}={quote(value, safe='')}" for name, value in pairs)
+
+
+def prepare(
+  request: Request, endpoint: str, service: str, credentials: Optional[CredentialsSource]
+) -> Tuple[str, Dict[str, str]]:
+  """The URL to send and the headers, signed for `service` with VGR4."""
+  url = endpoint.rstrip("/") + request.path
+  if request.query:
+    url += "?" + encode_query(request.query)
+  headers = dict(request.headers)
+  headers.update(
+    sign_request(
+      request.method,
+      url,
+      headers,
+      request.content,
+      credentials_from(credentials),
+      service,
+      payload_hash=UNSIGNED_PAYLOAD if request.stream is not None else None,
+    )
+  )
+  return url, headers

vigrise/_common/multipart.py

@@ -0,0 +1,29 @@
+import hashlib
+from typing import List, Optional, Tuple
+
+# name, body, file name, content type
+Part = Tuple[str, bytes, Optional[str], Optional[str]]
+
+
+def encode_multipart(parts: List[Part]) -> Tuple[str, bytes]:
+  """The `Content-Type` header value and the `multipart/form-data` body. The boundary is derived from the parts, so it cannot occur inside them."""
+  for _, _, _, content_type in parts:
+    if content_type is not None and ("\r" in content_type or "\n" in content_type):
+      raise ValueError("a content type cannot contain line breaks")
+  salt = 0
+  while True:
+    digest = hashlib.sha256(str(salt).encode())
+    for _, body, _, _ in parts:
+      digest.update(body)
+    boundary = "vigrise-" + digest.hexdigest()[:32]
+    if not any(boundary.encode() in body for _, body, _, _ in parts):
+      break
+    salt += 1
+  out = bytearray()
+  for name, body, file_name, content_type in parts:
+    out += f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"'.encode()
+    if file_name is not None:
+      out += f'; filename="{file_name.replace(chr(34), "%22").replace(chr(13), "%0D").replace(chr(10), "%0A")}"\r\nContent-Type: {content_type}'.encode()
+    out += b"\r\n\r\n" + body + b"\r\n"
+  out += f"--{boundary}--\r\n".encode()
+  return f"multipart/form-data; boundary={boundary}", bytes(out)

vigrise/_common/pagination.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+from typing import Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+  data: List[T]
+  # Pass as `cursor` to read the next page; None on the last page.
+  next_cursor: Optional[str] = None

vigrise/_common/senders.py

@@ -0,0 +1,113 @@
+"""Sending of signed requests, shared by the service clients. The sync and async senders differ only in how they send."""
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+import httpx
+
+from . import http as _http
+from ..auth.credentials import CredentialsSource
+
+
+@dataclass(frozen=True)
+class Failures:
+  """The errors a service client raises."""
+
+  signing: Callable[[str], Exception]
+  transport: Callable[[str], Exception]
+  response: Callable[[int, bytes], Exception]
+
+
+class _Sender:
+  def _refused(self, status: int) -> None:
+    """Tells a credentials provider that the service refused its credentials, for example a revoked session."""
+    if status in (401, 403):
+      invalidate = getattr(self.credentials, "invalidate", None)
+      if callable(invalidate):
+        invalidate()
+
+  def __init__(
+    self,
+    service: str,
+    endpoint: str,
+    credentials: Optional[CredentialsSource],
+    timeout: Optional[float],
+    failures: Failures,
+  ):
+    self.service = service
+    self.endpoint = endpoint.rstrip("/")
+    self.credentials = credentials
+    self.timeout = timeout
+    self.failures = failures
+
+  def _build(self, http, request: _http.Request) -> httpx.Request:
+    try:
+      url, headers = _http.prepare(request, self.endpoint, self.service, self.credentials)
+    except Exception as error:
+      raise self.failures.signing(str(error)) from error
+    content = request.stream if request.stream is not None else request.content
+    return http.build_request(
+      request.method, url, headers=headers, content=content, timeout=self.timeout
+    )
+
+
+class SyncSender(_Sender):
+  def __init__(
+    self,
+    service,
+    endpoint,
+    credentials,
+    timeout,
+    failures,
+    transport: Optional[httpx.BaseTransport] = None,
+  ):
+    super().__init__(service, endpoint, credentials, timeout, failures)
+    self.http = httpx.Client(transport=transport)
+
+  def close(self) -> None:
+    self.http.close()
+
+  def send(self, request: _http.Request, stream: bool = False) -> httpx.Response:
+    """The response of a request that succeeded; with `stream`, its body is not read yet."""
+    built = self._build(self.http, request)
+    try:
+      response = self.http.send(built, stream=stream)
+    except httpx.HTTPError as error:
+      raise self.failures.transport(str(error)) from error
+    if not response.is_success:
+      body = response.read()
+      response.close()
+      self._refused(response.status_code)
+      raise self.failures.response(response.status_code, body)
+    return response
+
+
+class AsyncSender(_Sender):
+  def __init__(
+    self,
+    service,
+    endpoint,
+    credentials,
+    timeout,
+    failures,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+  ):
+    super().__init__(service, endpoint, credentials, timeout, failures)
+    self.http = httpx.AsyncClient(transport=transport)
+
+  async def aclose(self) -> None:
+    await self.http.aclose()
+
+  async def send(self, request: _http.Request, stream: bool = False) -> httpx.Response:
+    """The response of a request that succeeded; with `stream`, its body is not read yet."""
+    built = self._build(self.http, request)
+    try:
+      response = await self.http.send(built, stream=stream)
+    except httpx.HTTPError as error:
+      raise self.failures.transport(str(error)) from error
+    if not response.is_success:
+      body = await response.aread()
+      await response.aclose()
+      self._refused(response.status_code)
+      raise self.failures.response(response.status_code, body)
+    return response

vigrise/accounts/__init__.py

@@ -0,0 +1,39 @@
+"""ViGrise Accounts for Python services: SSO introspection, back-channel logout verification and OAuth2/OIDC helpers."""
+
+from .backchannel import BackchannelLogout
+from .errors import (
+  AccountsError,
+  AccountsMisconfiguredError,
+  AccountsUnavailableError,
+  InactiveSessionError,
+  InvalidTokenError,
+  JwksError,
+  TokenExchangeError,
+)
+from .hash import SSO_HEADER, sso_token_hash
+from .introspect import AsyncSsoIntrospector, SsoIntrospector
+from .jwks import Jwks
+from .dto import (
+  IdTokenClaims,
+  Introspection,
+  LogoutResult,
+  SsoAccount,
+  SsoIdentity,
+  SsoSession,
+  TokenResponse,
+)
+from .oauth2 import (
+  AsyncOAuth2Client,
+  AuthorizationRequest,
+  IdTokenVerifier,
+  OAuth2Client,
+  Pkce,
+  end_session_url,
+  random_state,
+)
+
+__all__ = [
+  name
+  for name in dir()
+  if name[:1].isupper() or name in ("sso_token_hash", "end_session_url", "random_state")
+]

vigrise/accounts/backchannel.py

@@ -0,0 +1,69 @@
+import threading
+import time
+from typing import Any, Dict
+
+from .errors import InvalidTokenError
+from .jwks import Jwks
+from .dto import LogoutResult
+from .verify import LEEWAY_SECONDS, decode, unverified_header
+
+EVENT = "http://schemas.openid.net/event/backchannel-logout"
+MAX_AGE_SECONDS = 300
+
+
+class BackchannelLogout:
+  """Verifies back-channel `logout_token`s sent by Accounts: signature against the JWKS, `iss`, `aud`, the
+  logout event, the time window and `jti` replay."""
+
+  def __init__(self, issuer: str, client_id: str, jwks: Jwks):
+    self._issuer = issuer
+    self._client_id = client_id
+    self._jwks = jwks
+    self._seen: Dict[str, int] = {}
+    self._lock = threading.Lock()
+
+  def verify(self, logout_token: str) -> LogoutResult:
+    header = unverified_header(logout_token, "logout token")
+    return self._check(logout_token, self._jwks.key(header))
+
+  async def averify(self, logout_token: str) -> LogoutResult:
+    """Like `verify`, fetching the signing keys with an async client."""
+    header = unverified_header(logout_token, "logout token")
+    return self._check(logout_token, await self._jwks.akey(header))
+
+  def _check(self, logout_token: str, key: Any) -> LogoutResult:
+    claims = decode(
+      logout_token,
+      key,
+      "logout token",
+      self._issuer,
+      self._client_id,
+      ["iss", "aud", "exp", "iat"],
+      LEEWAY_SECONDS,
+    )
+
+    def invalid(message: str) -> InvalidTokenError:
+      return InvalidTokenError(f"invalid logout token: {message}")
+
+    events = claims.get("events")
+    if not isinstance(events, dict) or events.get(EVENT) is None:
+      raise invalid("missing backchannel-logout event")
+    if "nonce" in claims:
+      raise invalid("nonce is not allowed")
+    if "sid" not in claims and "sub" not in claims:
+      raise invalid("neither sid nor sub")
+    jti = claims.get("jti")
+    if not isinstance(jti, str) or not jti:
+      raise invalid("missing jti")
+    now = int(time.time())
+    if (
+      claims["iat"] > now + LEEWAY_SECONDS or claims["iat"] < now - MAX_AGE_SECONDS - LEEWAY_SECONDS
+    ):
+      raise invalid("issued outside the accepted time window")
+    with self._lock:
+      self._seen = {seen: exp for seen, exp in self._seen.items() if exp >= now}
+      replayed = jti in self._seen
+      self._seen[jti] = claims["exp"]
+    return LogoutResult(
+      "replayed" if replayed else "fresh", jti, claims.get("sub"), claims.get("sid")
+    )

vigrise/accounts/dto.py

@@ -0,0 +1,131 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from ..auth.sts import parse_timestamp
+
+
+@dataclass(frozen=True)
+class SsoIdentity:
+  """The person behind an SSO session."""
+
+  # Accounts identity id, the `sub` apps key their users by.
+  id: str
+  email: Optional[str] = None
+  name: Optional[str] = None
+  picture: Optional[str] = None
+  email_verified: bool = False
+
+
+@dataclass(frozen=True)
+class SsoSession:
+  """An Accounts session."""
+
+  # Session id, the `sso_sid` of app sessions and the `sid` of logout tokens.
+  id: str
+  authenticated_at: datetime
+  # Authenticator assurance level.
+  aal: str
+  expires_at: datetime
+
+
+@dataclass(frozen=True)
+class SsoAccount:
+  """An account in the browser's group, for the account menu."""
+
+  # Session id to switch to.
+  session_id: str
+  identity_id: str
+  active: bool
+  name: Optional[str] = None
+  email: Optional[str] = None
+  picture: Optional[str] = None
+  # Whether the session expired and needs re-authentication.
+  expired: bool = False
+
+
+@dataclass(frozen=True)
+class Introspection:
+  """The answer of the introspection endpoint."""
+
+  # False for an unknown, revoked or ended token.
+  active: bool
+  identity: Optional[SsoIdentity] = None
+  session: Optional[SsoSession] = None
+  accounts: List[SsoAccount] = field(default_factory=list)
+
+  @classmethod
+  def from_dict(cls, data: Dict[str, Any]) -> "Introspection":
+    identity = data.get("identity")
+    session = data.get("session")
+    return cls(
+      active=bool(data.get("active")),
+      identity=SsoIdentity(
+        id=identity["id"],
+        email=identity.get("email"),
+        name=identity.get("name"),
+        picture=identity.get("picture"),
+        email_verified=bool(identity.get("email_verified", False)),
+      )
+      if identity
+      else None,
+      session=SsoSession(
+        id=session["id"],
+        authenticated_at=parse_timestamp(session["authenticated_at"]),
+        aal=session["aal"],
+        expires_at=parse_timestamp(session["expires_at"]),
+      )
+      if session
+      else None,
+      accounts=[
+        SsoAccount(
+          session_id=item["session_id"],
+          identity_id=item["identity_id"],
+          active=bool(item["active"]),
+          name=item.get("name"),
+          email=item.get("email"),
+          picture=item.get("picture"),
+          expired=bool(item.get("expired", False)),
+        )
+        for item in data.get("accounts") or []
+      ],
+    )
+
+
+@dataclass(frozen=True)
+class LogoutResult:
+  """The claims of a verified `logout_token`, and whether its `jti` was seen before."""
+
+  # `fresh` for the first delivery: end the session. `replayed` for a `jti` already processed: answer 200 and do nothing.
+  outcome: str
+  jti: str
+  # Client-facing subject of the person.
+  sub: Optional[str] = None
+  # Accounts session id that ended.
+  sid: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class TokenResponse:
+  """The token endpoint answer."""
+
+  access_token: str
+  # Present for the `openid` scope.
+  id_token: Optional[str] = None
+  refresh_token: Optional[str] = None
+  # Access token lifetime in seconds.
+  expires_in: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class IdTokenClaims:
+  """Claims of a verified ID token."""
+
+  # Client-facing subject.
+  sub: str
+  # Accounts session id.
+  sid: Optional[str] = None
+  # When the person authenticated, in seconds since the epoch.
+  auth_time: Optional[int] = None
+  # Nonce echoed from the authorization request.
+  nonce: Optional[str] = None

vigrise/accounts/errors.py

@@ -0,0 +1,40 @@
+from typing import Optional
+
+
+class AccountsError(Exception):
+  """Base of the errors of the Accounts helpers."""
+
+
+class AccountsUnavailableError(AccountsError):
+  """Accounts could not be reached, is rate limiting the client, or answered with a server error. Retry later."""
+
+  def __init__(self, message: str, status: Optional[int] = None):
+    super().__init__(message)
+    self.status = status
+
+
+class AccountsMisconfiguredError(AccountsError):
+  """Accounts rejected the client or answered in an unexpected way: the credentials, the client's permissions or the internal URL need attention."""
+
+  def __init__(self, message: str, status: Optional[int] = None):
+    super().__init__(message)
+    self.status = status
+
+
+class InactiveSessionError(AccountsError):
+  """`introspect_active` found a token that is unknown, revoked or ended."""
+
+  def __init__(self):
+    super().__init__("the SSO token is not active")
+
+
+class InvalidTokenError(AccountsError):
+  """A logout token or ID token failed verification."""
+
+
+class TokenExchangeError(AccountsError):
+  """The authorization code exchange failed."""
+
+
+class JwksError(AccountsError):
+  """The signing keys could not be loaded or did not contain the key id."""

vigrise/accounts/hash.py

@@ -0,0 +1,9 @@
+import hashlib
+
+# Request header that carries the `vigrise_sso` cookie value from an app's frontend to its backend.
+SSO_HEADER = "x-vigrise-sso"
+
+
+def sso_token_hash(token: str) -> str:
+  """Hash of a `vigrise_sso` cookie value: lowercase hex SHA-256. Apps store it to notice when the cookie changes."""
+  return hashlib.sha256(token.encode()).hexdigest()