memydev-auth-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memydev-auth-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Official MemyAuth (OIDC + IAM) client SDK for Python
 License: Proprietary and unlicensed pending approved service terms.
 Requires-Python: >=3.11

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memydev-auth-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Official MemyAuth (OIDC + IAM) client SDK for Python"
 readme = "README.md"
 requires-python = ">=3.11"

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/__init__.py

@@ -17,6 +17,8 @@ from ._client import MemyAuth, SDK_VERSION
 from ._config import ResolvedConfig, RetryConfig, resolve_config
 from ._discovery import DiscoveryService
 from ._errors import (
+    INTERACTION_REQUIRED_ERRORS,
+    AuthorizationResponseError,
     BadRequestError,
     ConfigError,
     ConflictError,
@@ -26,11 +28,13 @@ from ._errors import (
     GoneError,
     IdTokenError,
     IssuerMismatchError,
+    LogoutTokenError,
     MemyAuthError,
     NetworkError,
     NotFoundError,
     ProtocolError,
     RefreshRejectedError,
+    RevocationError,
     ScopeForbiddenError,
     ServiceUnavailableError,
     SessionTokenError,
@@ -48,7 +52,7 @@ from ._errors import (
 )
 from ._contract import ADMIN_AUDIT_ACTIONS, IAM_API_RESOURCE, IAM_SCOPES, TENANT_EVENT_TYPES
 from ._iam import IamService
-from ._idtoken import IdTokenVerifier
+from ._idtoken import BACKCHANNEL_LOGOUT_EVENT, IdTokenVerifier
 from ._oidc import OidcService
 from ._pkce import SystemRandomSource, generate_code_challenge, generate_code_verifier
 from ._roles import CONSUMER_ROLES, DEFAULT_CONSUMER_ROLE, DEFAULT_ROLE_MAP, GLOBAL_ADMIN_IDP_ROLES, RoleMapper
@@ -65,6 +69,8 @@ from ._webhook_receiver import (
 )
 from ._webhooks import AppWebhookService
 from ._types import (
+    AuthorizationResponse,
+    LogoutTokenClaims,
     AdminAuditEntry,
     AdminAuditList,
     AppWebhookConfig,
@@ -133,6 +139,7 @@ __all__ = [
     "ADMIN_AUDIT_ACTIONS",
     "TENANT_EVENT_TYPES",
     "IdTokenVerifier",
+    "BACKCHANNEL_LOGOUT_EVENT",
     "RoleMapper",
     "DEFAULT_ROLE_MAP",
     "CONSUMER_ROLES",
@@ -165,8 +172,12 @@ __all__ = [
     "DiscoveryEscapeError",
     "TokenExchangeError",
     "RefreshRejectedError",
+    "RevocationError",
+    "AuthorizationResponseError",
+    "INTERACTION_REQUIRED_ERRORS",
     "UserInfoError",
     "IdTokenError",
+    "LogoutTokenError",
     "UnsupportedAlgorithmError",
     "SessionTokenError",
     "StateCookieError",
@@ -179,6 +190,8 @@ __all__ = [
     "OidcDiscoveryDocument",
     "DiscoveryHealth",
     "AuthorizationRequest",
+    "AuthorizationResponse",
+    "LogoutTokenClaims",
     "OidcTokenResponse",
     "UserInfo",
     "UserContext",

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_client.py

@@ -43,7 +43,7 @@ from ._webhooks import AppWebhookService
 
 __all__ = ["MemyAuth", "SDK_VERSION"]
 
-SDK_VERSION = "0.2.0"
+SDK_VERSION = "0.3.0"
 
 _SECRET_FIELDS = (
     "client_secret",

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_discovery.py

@@ -38,6 +38,8 @@ from ._transport import Transport
 __all__ = ["DiscoveryService"]
 
 _REQUIRED_KEYS = ("issuer", "authorization_endpoint", "token_endpoint", "userinfo_endpoint", "jwks_uri")
+# Server-side endpoints a provider MAY publish: held to the internal-origin rule when present (revocation).
+_OPTIONAL_SERVER_SIDE_KEYS = ("revocation_endpoint",)
 _ABS_HTTP_RE = re.compile(r"^https?://")
 _DEFAULT_TIMEOUT_MS = 10000
 
@@ -127,6 +129,12 @@ class DiscoveryService:
             if not isinstance(value, str) or not _ABS_HTTP_RE.match(value):
                 raise DiscoveryError(f"OIDC discovery is missing {key}")
 
+        # Server-side endpoints a provider MAY publish (RFC 8414 §2): an absolute URL when present.
+        for key in _OPTIONAL_SERVER_SIDE_KEYS:
+            value = doc.get(key)
+            if value is not None and (not isinstance(value, str) or not _ABS_HTTP_RE.match(value)):
+                raise DiscoveryError(f"OIDC discovery {key} is not an absolute URL")
+
         if _strip_trailing_slashes(doc["issuer"]) != self._public_issuer:
             raise IssuerMismatchError(
                 f"OIDC discovery issuer mismatch: expected {self._public_issuer}, got {doc['issuer']}"
@@ -134,7 +142,9 @@ class DiscoveryService:
 
         if self._fetch_issuer != self._public_issuer:
             fetch_origin = _origin(self._fetch_issuer)
-            for key in ("token_endpoint", "userinfo_endpoint", "jwks_uri"):
+            for key in ("token_endpoint", "userinfo_endpoint", "jwks_uri", *_OPTIONAL_SERVER_SIDE_KEYS):
+                if doc.get(key) is None:
+                    continue
                 if _origin(doc[key]) != fetch_origin:
                     raise DiscoveryEscapeError(
                         f"OIDC discovery {key} escaped the internal origin: {doc[key]}"

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_errors.py

@@ -22,9 +22,15 @@
 @created 2026-09-06
 @updated 2026-10-03 ConflictError, TenantKeyConflictError, TenantAdminConflictError,
    ScopeForbiddenError (SDK 0.2.0).
+@updated 2026-10-18 SDK 0.3.0, mirroring js/src/errors.ts: `oauth_error` on `TokenExchangeError`/
+   `RefreshRejectedError`/`RevocationError` (RFC 6749 §5.2 `error`, read from the wire body); `RevocationError`
+   (RFC 7009); `AuthorizationResponseError` (RFC 6749 §4.1.2.1, `interaction_required` for a `prompt=none`
+   probe); `LogoutTokenError` (OIDC Back-Channel Logout 1.0 §2.6). A token endpoint answering 5xx/429 raises
+   `ServiceUnavailableError` (retry later; the session survives), never `RefreshRejectedError`.
 """
 from __future__ import annotations
 
+import re
 from typing import Any, Optional
 
 from ._contract import TENANT_ADMIN_CONFLICT_REASONS, TENANT_KEY_CONFLICT_REASONS
@@ -51,16 +57,32 @@ __all__ = [
     "DiscoveryEscapeError",
     "TokenExchangeError",
     "RefreshRejectedError",
+    "RevocationError",
+    "AuthorizationResponseError",
+    "INTERACTION_REQUIRED_ERRORS",
     "UserInfoError",
     "IdTokenError",
+    "LogoutTokenError",
     "UnsupportedAlgorithmError",
     "SessionTokenError",
     "StateCookieError",
     "StateMismatchError",
     "ERROR_CLASS_MAP",
     "decode_error",
+    "oauth_error_of",
 ]
 
+# RFC 6749 §5.2: `error` is ASCII without `"` or `\\`. Anything else in a body is not an OAuth error code.
+_OAUTH_ERROR_CODE = re.compile(r'^[\x20-\x21\x23-\x5B\x5D-\x7E]{1,128}$')
+
+
+def oauth_error_of(body: Any) -> Optional[str]:
+    """The RFC 6749 §5.2 `error` code of a wire body, when it carries a well-formed one."""
+    if not isinstance(body, dict):
+        return None
+    error = body.get("error")
+    return error if isinstance(error, str) and _OAUTH_ERROR_CODE.match(error) else None
+
 
 class MemyAuthError(Exception):
     """Base for every MemyAuth SDK error. `status == 0` means "no wire status" (pre-wire guard,
@@ -217,14 +239,60 @@ class TokenExchangeError(MemyAuthError):
     code = "token_exchange_failed"
     status = 0
 
+    def __init__(self, message: str = "", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        #: The RFC 6749 §5.2 `error` code (`invalid_grant`, `invalid_client`, ...), when the body carried one.
+        self.oauth_error: Optional[str] = oauth_error_of(self.body)
+
 
 class RefreshRejectedError(MemyAuthError):
-    """A rejected refresh means the session is over — modeled as 401 semantics even though the
-    wire status may differ, matching memybase's `UnauthorizedError`-on-refresh-rejection behavior."""
+    """A 4xx refresh answer: the refresh token is invalid, expired or revoked, so the session is over —
+    modeled as 401 semantics, matching memybase's `UnauthorizedError`-on-refresh-rejection behavior. A 5xx
+    or 429 is NOT this class: it raises `ServiceUnavailableError`, because a provider outage must not sign
+    every user out."""
 
     code = "refresh_rejected"
     status = 401
 
+    def __init__(self, message: str = "", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.oauth_error: Optional[str] = oauth_error_of(self.body)
+
+
+class RevocationError(MemyAuthError):
+    """A non-2xx RFC 7009 revocation answer other than 5xx/429 (those raise `ServiceUnavailableError`):
+    `invalid_client`, `unsupported_token_type`, .... `http_status` is the wire status; `.status` stays 0."""
+
+    code = "revocation_failed"
+    status = 0
+
+    def __init__(self, message: str = "", *, http_status: int = 0, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.http_status = http_status
+        self.oauth_error: Optional[str] = oauth_error_of(self.body)
+
+
+#: The OIDC errors a `prompt=none` probe is answered with when the user must interact (OIDC Core §3.1.2.6).
+INTERACTION_REQUIRED_ERRORS: tuple[str, ...] = ("login_required", "interaction_required", "consent_required", "account_selection_required")
+
+
+class AuthorizationResponseError(MemyAuthError):
+    """The provider answered the authorization request with an error (RFC 6749 §4.1.2.1) instead of a code.
+    `oauth_error` is the error code; the provider's `error_description` is untrusted text and is kept only in
+    `detail` (truncated), never in the message."""
+
+    code = "authorization_error"
+    status = 0
+
+    def __init__(self, oauth_error: str, **kwargs: Any) -> None:
+        super().__init__(f"OIDC authorization failed: {oauth_error}", **kwargs)
+        self.oauth_error = oauth_error
+
+    @property
+    def interaction_required(self) -> bool:
+        """Whether a `prompt=none` probe failed only because the user must interact."""
+        return self.oauth_error in INTERACTION_REQUIRED_ERRORS
+
 
 class UserInfoError(MemyAuthError):
     code = "userinfo_failed"
@@ -236,6 +304,14 @@ class IdTokenError(MemyAuthError):
     status = 401
 
 
+class LogoutTokenError(IdTokenError):
+    """A back-channel logout token failed OIDC Back-Channel Logout 1.0 §2.6 validation. Still an
+    `IdTokenError` (the same signature/issuer/audience machinery verifies it)."""
+
+    code = "logout_token_invalid"
+    status = 401
+
+
 class UnsupportedAlgorithmError(IdTokenError):
     """A token's `alg` header is outside the configured `allowed_algorithms` allow-list — raised
     BEFORE any key lookup. This is what the mandatory RS256 negative test (R1) asserts on."""

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_idtoken.py

@@ -17,6 +17,8 @@
    rewritten, since JWKS is a server-side endpoint per §C.1 step 6), _config.py
    (`allowed_algorithms`/`id_token_validation`), _errors.py, tests/test_idtoken.py
 @created 2026-09-06
+@updated 2026-10-18 SDK 0.3.0: `verify_logout_token()` (OIDC Back-Channel Logout 1.0 §2.6), mirroring
+   js/src/idtoken.ts, so a BFF verifies logout tokens here instead of with its own JWT code.
 """
 from __future__ import annotations
 
@@ -27,13 +29,16 @@ import jwt
 
 # ABSOLUTE imports for the shared/pure modules; RELATIVE for ._discovery/._transport, which DO get
 # _sync/ twins and must bind to THEIR sibling twins (see _transport.py's header for why).
-from memyauth._errors import ConfigError, IdTokenError, UnsupportedAlgorithmError
-from memyauth._types import Clock, IdpTokenClaims, IdTokenValidationMode, SystemClock
+from memyauth._errors import ConfigError, IdTokenError, LogoutTokenError, UnsupportedAlgorithmError
+from memyauth._types import Clock, IdpTokenClaims, IdTokenValidationMode, LogoutTokenClaims, SystemClock
 
 from ._discovery import DiscoveryService
 from ._transport import Transport, read_json_or_none
 
-__all__ = ["IdTokenVerifier"]
+__all__ = ["IdTokenVerifier", "BACKCHANNEL_LOGOUT_EVENT"]
+
+#: The `events` member a back-channel logout token carries (OIDC Back-Channel Logout 1.0 §2.4).
+BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout"
 
 _DEFAULT_LOCAL_JWKS_ALGORITHMS = ("ES384",)
 _DEFAULT_CLOCK_TOLERANCE_SECONDS = 60
@@ -153,6 +158,67 @@ class IdTokenVerifier:
 
         return claims  # type: ignore[return-value]
 
+    async def verify_logout_token(self, logout_token: str, *, issuer: str, audience: str) -> LogoutTokenClaims:
+        """Verifies an OIDC Back-Channel Logout 1.0 logout token (§2.6): the same signature, algorithm,
+        issuer, audience and time checks as an ID token (but `exp` only when present, as in the JS SDK), then
+        an `events` member naming the back-channel logout event, `iat` and `jti`, `sub` and/or `sid`, and no
+        `nonce`. Replay (`jti` already seen) is the caller's check. Raises `LogoutTokenError`."""
+        if self.mode == "tls-token-endpoint":
+            raise ConfigError(
+                "tls-token-endpoint mode does not verify ID tokens; identity is derived from the "
+                "token-endpoint TLS channel per OIDC Core 3.1.3.7 item 6 — use decode_unverified() "
+                "plus /oidc/me or /iam/me"
+            )
+        try:
+            header = jwt.get_unverified_header(logout_token)
+        except jwt.PyJWTError as exc:
+            raise LogoutTokenError(f"malformed logout token: {exc}") from exc
+        alg = header.get("alg")
+        if alg not in self._allowed_algorithms:
+            raise UnsupportedAlgorithmError(
+                f"logout token alg {alg!r} is not in the allowed algorithms {sorted(self._allowed_algorithms)!r}"
+            )
+        kid = header.get("kid")
+        if not kid:
+            raise LogoutTokenError("logout token is missing a kid header")
+        try:
+            jwk = await self._get_key_for_kid(kid)
+        except IdTokenError as exc:
+            raise LogoutTokenError(str(exc)) from exc
+        key = jwt.PyJWK(jwk).key
+        try:
+            claims = jwt.decode(
+                logout_token,
+                key,
+                algorithms=[alg],
+                audience=audience,
+                issuer=issuer,
+                options={"verify_exp": False, "verify_nbf": False, "verify_iat": False, "require": []},
+            )
+        except jwt.PyJWTError as exc:
+            raise LogoutTokenError(f"logout token verification failed: {exc}") from exc
+        now_seconds = self._clock.now() / 1000
+        tolerance = self._clock_tolerance_seconds
+        exp = claims.get("exp")
+        if exp is not None and (not isinstance(exp, (int, float)) or now_seconds > exp + tolerance):
+            raise LogoutTokenError("logout token has expired")
+        nbf = claims.get("nbf")
+        if isinstance(nbf, (int, float)) and now_seconds < nbf - tolerance:
+            raise LogoutTokenError("logout token is not yet valid")
+        events = claims.get("events")
+        if not isinstance(events, dict) or BACKCHANNEL_LOGOUT_EVENT not in events:
+            raise LogoutTokenError("logout token carries no back-channel logout event")
+        if "nonce" in claims:
+            raise LogoutTokenError("a logout token must not carry a nonce")
+        jti = claims.get("jti")
+        if not isinstance(claims.get("iat"), (int, float)) or isinstance(claims.get("iat"), bool) or not isinstance(jti, str) or not jti:
+            raise LogoutTokenError("logout token is missing iat or jti")
+        sub = claims.get("sub")
+        sid = claims.get("sid")
+        if not (isinstance(sub, str) and sub) and not (isinstance(sid, str) and sid):
+            raise LogoutTokenError("logout token names neither sub nor sid")
+        return claims  # type: ignore[return-value]
+
     def decode_unverified(self, id_token: str) -> IdpTokenClaims:
         """Decode without verifying. Available in BOTH modes; the ONLY path in
         `tls-token-endpoint` mode."""

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_oidc.py

@@ -9,6 +9,14 @@
    (`TokenExchangeError` / `RefreshRejectedError`) rather than the generic `decode_error` mapping,
    because the token endpoint's failure body is an OAuth `{error, error_description}` shape, not
    the IAM surface's `{code,message,detail}` envelope.
+
+   0.3.0 (2026-10-18), mirroring js/src/oidc.ts: `omit_prompt=True` sends no `prompt` (JS `prompt: null`;
+   `prompt=None` keeps meaning the `'consent'` default, so a wrapper forwarding an unset value is unchanged),
+   `max_age`, `login_hint` and RFC 8707 `resource` on the authorization request,
+   `resource` on the code exchange and the refresh grant, `revoke_token()` (RFC 7009) and
+   `parse_authorization_response()` (state, RFC 9207 `iss`, typed provider errors). A refresh answered
+   5xx/429 raises `ServiceUnavailableError`: before, every such answer was `RefreshRejectedError`, so a provider
+   outage ended every session.
 @dependencies base64, urllib.parse (stdlib); ._transport, ._pkce, ._discovery
 @relatedFiles _discovery.py (this service's sole source of every OIDC URL), _pkce.py (PKCE +
    random helpers), _config.py (ResolvedConfig), _errors.py, tests/test_oidc.py
@@ -17,8 +25,9 @@
 from __future__ import annotations
 
 import base64
-from typing import Optional
-from urllib.parse import urlencode
+import hmac
+from typing import Optional, Union
+from urllib.parse import parse_qs, urlencode, urlsplit
 
 import httpx
 
@@ -26,16 +35,22 @@ import httpx
 # _sync/ twins and must bind to THEIR sibling twins (see _transport.py's header for why).
 from memyauth._config import ResolvedConfig
 from memyauth._errors import (
+    AuthorizationResponseError,
     ConfigError,
+    IssuerMismatchError,
     ProtocolError,
     RefreshRejectedError,
+    RevocationError,
+    ServiceUnavailableError,
+    StateMismatchError,
     TokenExchangeError,
     UnauthorizedError,
     UserInfoError,
+    oauth_error_of,
 )
 from memyauth._headers import is_header_safe
 from memyauth._pkce import generate_code_challenge, generate_code_verifier, random_nonce, random_state
-from memyauth._types import AuthorizationRequest, OidcTokenResponse, RandomSource, UserInfo
+from memyauth._types import AuthorizationRequest, AuthorizationResponse, OidcTokenResponse, RandomSource, UserInfo
 
 from ._discovery import DiscoveryService
 from ._transport import Transport, read_json_or_none, truncated_text
@@ -43,8 +58,31 @@ from ._transport import Transport, read_json_or_none, truncated_text
 __all__ = ["OidcService"]
 
 _AUTH_STANDARD_KEYS = frozenset(
-    {"response_type", "client_id", "redirect_uri", "code_challenge", "code_challenge_method", "scope", "state", "nonce", "prompt"}
+    {
+        "response_type", "client_id", "redirect_uri", "code_challenge", "code_challenge_method", "scope", "state", "nonce",
+        "prompt",
+    }
 )
+# 0.3.0 typed parameters a 0.2.0 caller may still pass through `extra_params`: refused only when the typed
+# argument sets the same key too (the value would be ambiguous).
+_TYPED_AUTH_KEYS = (("max_age", "max_age"), ("login_hint", "login_hint"), ("resource", "resource"))
+
+
+def _resource_list(resource: Union[str, list[str], tuple[str, ...], None]) -> list[str]:
+    """RFC 8707 §2: each resource indicator is an absolute URI without a fragment."""
+    if resource is None:
+        return []
+    values = [resource] if isinstance(resource, str) else list(resource)
+    for value in values:
+        parts = urlsplit(value) if isinstance(value, str) else None
+        if parts is None or not parts.scheme or "#" in value:
+            raise ConfigError("resource must be an absolute URI with no fragment (RFC 8707 §2)")
+    return values
+
+
+def _is_unavailable_status(status: int) -> bool:
+    """A token (or revocation) endpoint answering 5xx or 429 is unavailable, not refusing."""
+    return status >= 500 or status == 429
 _LOGOUT_STANDARD_KEYS = frozenset({"post_logout_redirect_uri", "id_token_hint", "client_id", "state"})
 
 
@@ -77,6 +115,10 @@ class OidcService:
         nonce: Optional[str] = None,
         code_verifier: Optional[str] = None,
         prompt: Optional[str] = None,
+        omit_prompt: bool = False,
+        max_age: Optional[int] = None,
+        login_hint: Optional[str] = None,
+        resource: Union[str, list[str], tuple[str, ...], None] = None,
         return_to: Optional[str] = None,
         extra_params: Optional[dict[str, str]] = None,
     ) -> AuthorizationRequest:
@@ -85,6 +127,15 @@ class OidcService:
         # caller must fail deterministically without spending a discovery round trip or generating
         # provider traffic.
         _assert_no_extra_param_collision(extra_params, _AUTH_STANDARD_KEYS)
+        if omit_prompt and prompt is not None:
+            raise ConfigError("prompt and omit_prompt cannot both be set")
+        typed = {"max_age": max_age, "login_hint": login_hint, "resource": resource}
+        for argument, key in _TYPED_AUTH_KEYS:
+            if typed[argument] is not None and extra_params and key in extra_params:
+                raise ConfigError(f"{argument} and extraParams.{key} cannot both be set")
+        if max_age is not None and (isinstance(max_age, bool) or not isinstance(max_age, int) or max_age < 0):
+            raise ConfigError("maxAge must be a non-negative integer number of seconds")
+        resources = _resource_list(resource)
         doc = await self._discovery.discover()
 
         effective_redirect_uri = redirect_uri or self._config["redirect_uri"]
@@ -104,19 +155,25 @@ class OidcService:
             negotiated = list(base_scopes)
         scope = " ".join(negotiated)
 
-        params: dict[str, str] = {
-            "response_type": "code",
-            "client_id": self._config["client_id"],
-            "redirect_uri": effective_redirect_uri,
-            "code_challenge": challenge,
-            "code_challenge_method": "S256",
-            "scope": scope,
-            "state": effective_state,
-            "nonce": effective_nonce,
-            "prompt": prompt if prompt is not None else "consent",
-        }
+        params: list[tuple[str, str]] = [
+            ("response_type", "code"),
+            ("client_id", self._config["client_id"]),
+            ("redirect_uri", effective_redirect_uri),
+            ("code_challenge", challenge),
+            ("code_challenge_method", "S256"),
+            ("scope", scope),
+            ("state", effective_state),
+            ("nonce", effective_nonce),
+        ]
+        if not omit_prompt:
+            params.append(("prompt", prompt if prompt is not None else "consent"))
+        if max_age is not None:
+            params.append(("max_age", str(max_age)))
+        if login_hint is not None:
+            params.append(("login_hint", login_hint))
+        params.extend(("resource", value) for value in resources)
         if extra_params:
-            params.update(extra_params)
+            params.extend(extra_params.items())
 
         url = f"{doc['authorization_endpoint']}?{urlencode(params)}"
         return {
@@ -140,7 +197,7 @@ class OidcService:
             return {"Authorization": f"Basic {base64.b64encode(raw).decode('ascii')}"}
         return {}
 
-    async def _post_token(self, body: dict[str, str]) -> httpx.Response:
+    async def _post_token(self, body: dict[str, Union[str, list[str]]]) -> httpx.Response:
         doc = await self._discovery.discover()
         form = {**body, **self._credential_form_fields()}
         headers = self._credential_headers()
@@ -154,30 +211,111 @@ class OidcService:
         return body  # type: ignore[return-value]
 
     async def exchange_code(
-        self, *, code: str, code_verifier: str, redirect_uri: Optional[str] = None
+        self,
+        *,
+        code: str,
+        code_verifier: str,
+        redirect_uri: Optional[str] = None,
+        resource: Union[str, list[str], tuple[str, ...], None] = None,
     ) -> OidcTokenResponse:
-        body = {
+        resources = _resource_list(resource)
+        body: dict[str, Union[str, list[str]]] = {
             "grant_type": "authorization_code",
             "code": code,
             "redirect_uri": redirect_uri or self._config["redirect_uri"],
             "code_verifier": code_verifier,
         }
+        if resources:
+            body["resource"] = resources
         resp = await self._post_token(body)
         if not (200 <= resp.status_code < 300):
             raise TokenExchangeError(
-                f"OIDC token exchange failed: {resp.status_code}", detail=truncated_text(resp)
+                f"OIDC token exchange failed: {resp.status_code}", detail=truncated_text(resp), body=read_json_or_none(resp)
             )
         return self._parse_token_response(resp)
 
-    async def refresh_tokens(self, refresh_token: str) -> OidcTokenResponse:
-        body = {"grant_type": "refresh_token", "refresh_token": refresh_token}
+    async def refresh_tokens(
+        self, refresh_token: str, *, resource: Union[str, list[str], tuple[str, ...], None] = None
+    ) -> OidcTokenResponse:
+        """The refresh-token grant. A 4xx answer raises `RefreshRejectedError` (the session is over); a 5xx
+        or 429 raises `ServiceUnavailableError` (the provider is down: keep the session and retry later)."""
+        resources = _resource_list(resource)
+        body: dict[str, Union[str, list[str]]] = {"grant_type": "refresh_token", "refresh_token": refresh_token}
+        if resources:
+            body["resource"] = resources
         resp = await self._post_token(body)
         if not (200 <= resp.status_code < 300):
+            if _is_unavailable_status(resp.status_code):
+                raise ServiceUnavailableError(
+                    "OIDC token endpoint unavailable", detail=truncated_text(resp), body=read_json_or_none(resp)
+                )
             raise RefreshRejectedError(
-                f"OIDC token refresh rejected: {resp.status_code}", detail=truncated_text(resp)
+                f"OIDC token refresh rejected: {resp.status_code}", detail=truncated_text(resp), body=read_json_or_none(resp)
             )
         return self._parse_token_response(resp)
 
+    async def revoke_token(self, token: str, *, token_type_hint: Optional[str] = None) -> None:
+        """RFC 7009 token revocation, authenticated like the token endpoint (§2.1). Returns once the provider
+        answered 200 (§2.2: also for a token it did not know). Raises `ConfigError` when discovery publishes no
+        `revocation_endpoint`, `ServiceUnavailableError` on 5xx/429 (§2.2.1: retry later), `RevocationError`
+        otherwise. Never retried: a POST."""
+        if not token:
+            raise ConfigError("revokeToken needs a token")
+        doc = await self._discovery.discover()
+        endpoint = doc.get("revocation_endpoint")
+        if not isinstance(endpoint, str):
+            raise ConfigError("the provider publishes no revocation_endpoint")
+        form: dict[str, Union[str, list[str]]] = {"token": token}
+        if token_type_hint is not None:
+            form["token_type_hint"] = token_type_hint
+        form.update(self._credential_form_fields())
+        resp = await self._transport.send("POST", endpoint, form=form, headers=self._credential_headers())
+        if 200 <= resp.status_code < 300:
+            return
+        if _is_unavailable_status(resp.status_code):
+            raise ServiceUnavailableError("OAuth revocation endpoint unavailable", body=read_json_or_none(resp))
+        raise RevocationError(
+            f"OAuth token revocation failed: {resp.status_code}", http_status=resp.status_code, body=read_json_or_none(resp)
+        )
+
+    async def parse_authorization_response(self, response: str, *, state: str) -> AuthorizationResponse:
+        """Reads the authorization response at the redirect URI (RFC 6749 §4.1.2): a callback URL or its query
+        string. Checks `state` first (a mismatch is `StateMismatchError`, error responses included), then RFC
+        9207 `iss` against discovery (required when discovery sets `authorization_response_iss_parameter_supported`;
+        a mismatch is `IssuerMismatchError`), then returns the code, or raises `AuthorizationResponseError` for a
+        provider error (`interaction_required` tells a failed `prompt=none` probe apart)."""
+        query = urlsplit(response).query if "://" in response else response.lstrip("?")
+        parsed = parse_qs(query, keep_blank_values=True)
+
+        def first(key: str) -> Optional[str]:
+            values = parsed.get(key)
+            return values[0] if values else None
+
+        got_state = first("state")
+        if got_state is None or not hmac.compare_digest(got_state.encode("utf-8"), state.encode("utf-8")):
+            raise StateMismatchError("Authorization response state does not match the sign-in")
+        doc = await self._discovery.discover()
+        iss = first("iss")
+        if iss is not None:
+            if iss.rstrip("/") != str(doc["issuer"]).rstrip("/"):
+                raise IssuerMismatchError("Authorization response iss does not match the discovered issuer (RFC 9207)")
+        elif doc.get("authorization_response_iss_parameter_supported") is True:
+            raise IssuerMismatchError("Authorization response carries no iss, which the provider promises (RFC 9207 §2.4)")
+        error = first("error")
+        if error is not None:
+            code = oauth_error_of({"error": error})
+            if code is None:
+                raise ProtocolError("Authorization response carries a malformed error")
+            description = first("error_description")
+            raise AuthorizationResponseError(code, detail=description[:200] if description is not None else None)
+        code_value = first("code")
+        if not code_value:
+            raise ProtocolError("Authorization response carries neither code nor error")
+        result: AuthorizationResponse = {"code": code_value, "state": got_state}
+        if iss is not None:
+            result["iss"] = iss
+        return result
+
     async def fetch_user_info(self, access_token: str) -> UserInfo:
         # Checked before discovery: a token that is not a safe header value would otherwise reach the HTTP
         # stack, whose error message quotes the header — i.e. the token.

{memydev_auth_sdk-0.2.0 → memydev_auth_sdk-0.3.0}/src/memyauth/_sync/_client.py

@@ -45,7 +45,7 @@ from ._webhooks import AppWebhookService
 
 __all__ = ["MemyAuth", "SDK_VERSION"]
 
-SDK_VERSION = "0.2.0"
+SDK_VERSION = "0.3.0"
 
 _SECRET_FIELDS = (
     "client_secret",