memydev-auth-sdk 0.1.0__py3-none-any.whl

memyauth/__init__.py

@@ -0,0 +1,144 @@
+"""
+@fileoverview Official MemyAuth Python SDK — async-first with a mechanically generated sync facade.
+@module memyauth
+@description Public entrypoint. Async: `memyauth.MemyAuth`. Sync: `memyauth.sync.MemyAuth`. The
+   async modules (`_client.py`, `_discovery.py`, `_oidc.py`, `_iam.py`, `_idtoken.py`,
+   `_transport.py`) are the ONLY hand-written client surface; `_sync/*.py` is mechanically derived
+   by `scripts/gen_sync.py` — never hand-edit it. `_roles.py`, `_session.py`, `_state.py`,
+   `_config.py`, `_errors.py`, `_types.py`, `_pkce.py` are pure/synchronous and shared verbatim by
+   both surfaces (no twin exists or is needed).
+@created 2026-09-06
+"""
+from ._client import MemyAuth, SDK_VERSION
+from ._config import ResolvedConfig, RetryConfig, resolve_config
+from ._discovery import DiscoveryService
+from ._errors import (
+    BadRequestError,
+    ConfigError,
+    DiscoveryError,
+    DiscoveryEscapeError,
+    ForbiddenError,
+    GoneError,
+    IdTokenError,
+    IssuerMismatchError,
+    MemyAuthError,
+    NetworkError,
+    NotFoundError,
+    ProtocolError,
+    RefreshRejectedError,
+    ServiceUnavailableError,
+    SessionTokenError,
+    StateCookieError,
+    StateMismatchError,
+    TimeoutError,
+    TokenExchangeError,
+    UnauthorizedError,
+    UnsupportedAlgorithmError,
+    UnsupportedAlgorithmPinError,
+    UserInfoError,
+    decode_error,
+)
+from ._iam import IamService
+from ._idtoken import 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
+from ._session import SessionTokenService
+from ._state import StateCookieService
+from ._types import (
+    AuthorizationRequest,
+    Clock,
+    DiscoveryHealth,
+    IamOrgEntry,
+    IamSession,
+    IamTenant,
+    IamUserContext,
+    IdpTokenClaims,
+    OidcDiscoveryDocument,
+    OidcTokenResponse,
+    RandomSource,
+    SessionAccessClaims,
+    SessionAccessInput,
+    SessionRefreshClaims,
+    SessionRefreshInput,
+    StateCookieInput,
+    StateCookiePayload,
+    SystemClock,
+    UserContext,
+    UserContextOrgEntry,
+    UserContextTenant,
+    UserInfo,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "MemyAuth",
+    "SDK_VERSION",
+    "__version__",
+    "resolve_config",
+    "ResolvedConfig",
+    "RetryConfig",
+    "DiscoveryService",
+    "OidcService",
+    "IamService",
+    "IdTokenVerifier",
+    "RoleMapper",
+    "DEFAULT_ROLE_MAP",
+    "CONSUMER_ROLES",
+    "DEFAULT_CONSUMER_ROLE",
+    "GLOBAL_ADMIN_IDP_ROLES",
+    "SessionTokenService",
+    "StateCookieService",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    "SystemRandomSource",
+    # errors
+    "MemyAuthError",
+    "ConfigError",
+    "UnsupportedAlgorithmPinError",
+    "NetworkError",
+    "TimeoutError",
+    "ProtocolError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "GoneError",
+    "ServiceUnavailableError",
+    "DiscoveryError",
+    "IssuerMismatchError",
+    "DiscoveryEscapeError",
+    "TokenExchangeError",
+    "RefreshRejectedError",
+    "UserInfoError",
+    "IdTokenError",
+    "UnsupportedAlgorithmError",
+    "SessionTokenError",
+    "StateCookieError",
+    "StateMismatchError",
+    "decode_error",
+    # types
+    "Clock",
+    "RandomSource",
+    "SystemClock",
+    "OidcDiscoveryDocument",
+    "DiscoveryHealth",
+    "AuthorizationRequest",
+    "OidcTokenResponse",
+    "UserInfo",
+    "UserContext",
+    "UserContextTenant",
+    "UserContextOrgEntry",
+    "IamUserContext",
+    "IamSession",
+    "IamOrgEntry",
+    "IamTenant",
+    "SessionAccessInput",
+    "SessionAccessClaims",
+    "SessionRefreshInput",
+    "SessionRefreshClaims",
+    "StateCookieInput",
+    "StateCookiePayload",
+    "IdpTokenClaims",
+]

memyauth/_client.py

@@ -0,0 +1,169 @@
+"""
+@fileoverview Top-level `MemyAuth` async client — composes the seven capability services.
+@module memyauth._client
+@description [async -> _sync/_client.py twin via scripts/gen_sync.py]. `SDK_VERSION` lives HERE
+   (design §G.5's six-file version-parity check reads it via
+   `/SDK_VERSION\\s*=\\s*["\\']([^"\\']+)["\\']/`). `.discovery`, `.oidc`, `.iam` and `.roles` are
+   EAGER (built in `__init__`) because their prerequisites are always present once `resolve_config`
+   succeeds; `.session`, `.state` and `.id_token` are LAZY properties — `.session`/`.state` raise
+   `ConfigError` at first access when their signing secret was never configured (an IAM-only
+   consumer should never need one), while `.id_token` never raises (`id_token_validation` is a
+   required, already-validated field, so its prerequisite is always satisfiable) but is still built
+   lazily and cached, purely to avoid touching `discovery` before it is needed.
+@dependencies ._config, ._discovery, ._oidc, ._iam, ._idtoken, ._roles, ._session, ._state
+@relatedFiles __init__.py (re-exports MemyAuth + SDK_VERSION), sync/__init__.py (the generated
+   sync facade), _config.py (resolve_config), tests/test_client.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# ABSOLUTE imports for the shared/pure modules; RELATIVE for the sibling async modules that DO
+# get _sync/ twins, so the generated _sync/_client.py binds to ITS siblings in _sync/ (see
+# _transport.py's header for why this split is required).
+from memyauth._config import ResolvedConfig, resolve_config
+from memyauth._errors import ConfigError
+from memyauth._roles import RoleMapper
+from memyauth._session import SessionTokenService
+from memyauth._state import StateCookieService
+
+from ._discovery import DiscoveryService
+from ._iam import IamService
+from ._idtoken import IdTokenVerifier
+from ._oidc import OidcService
+
+__all__ = ["MemyAuth", "SDK_VERSION"]
+
+SDK_VERSION = "0.1.0"
+
+_SECRET_FIELDS = (
+    "client_secret",
+    "iam_app_secret",
+    "iam_m2m_token",
+    "session_signing_secret",
+    "state_signing_secret",
+)
+
+
+class MemyAuth:
+    """Async MemyAuth client — the composition root for all nine customer capabilities.
+
+    Usage::
+
+        async with MemyAuth(
+            issuer_url="https://auth.memy.dev/oidc",
+            client_id="my-app",
+            client_secret="...",
+            public_base_url="https://my-app.example.com",
+            id_token_validation="local-jwks",
+        ) as auth:
+            req = await auth.oidc.build_authorization_url()
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._config: ResolvedConfig = resolve_config(**kwargs)
+
+        self.discovery = DiscoveryService(
+            issuer_url=self._config["issuer_url"],
+            internal_issuer_url=self._config["internal_issuer_url"],
+            timeout_ms=self._config["discovery_timeout_ms"],
+            transport=self._config["transport"],
+            clock=self._config["clock"],
+        )
+        self.oidc = OidcService(
+            config=self._config,
+            discovery=self.discovery,
+            transport=self._config["transport"],
+            random=self._config["random"],
+        )
+        self.iam = IamService(config=self._config, transport=self._config["transport"])
+        self.roles = RoleMapper(
+            role_map=self._config["role_map"],
+            role_overrides=self._config["role_overrides"],
+            default_role=self._config["default_role"],
+            global_admin_roles=self._config["global_admin_roles"],
+        )
+
+        self._session: Optional[SessionTokenService] = None
+        self._state: Optional[StateCookieService] = None
+        self._id_token: Optional[IdTokenVerifier] = None
+
+    @property
+    def session(self) -> SessionTokenService:
+        if self._session is None:
+            secret = self._config.get("session_signing_secret")
+            if not secret:
+                raise ConfigError("sessionSigningSecret is required to issue or verify session tokens")
+            self._session = SessionTokenService(
+                signing_secret=secret,
+                access_ttl_seconds=self._config["access_ttl_seconds"],
+                refresh_ttl_seconds=self._config["refresh_ttl_seconds"],
+                issuer=self._config["session_issuer"],
+                clock=self._config["clock"],
+            )
+        return self._session
+
+    @property
+    def state(self) -> StateCookieService:
+        if self._state is None:
+            secret = self._config.get("state_signing_secret") or self._config.get("session_signing_secret")
+            if not secret:
+                raise ConfigError("stateSigningSecret (or sessionSigningSecret) is required to sign state cookies")
+            self._state = StateCookieService(
+                signing_secret=secret,
+                ttl_seconds=self._config["state_ttl_seconds"],
+                cookie_name=self._config["state_cookie_name"],
+                clock=self._config["clock"],
+            )
+        return self._state
+
+    @property
+    def id_token(self) -> IdTokenVerifier:
+        """Always available — `id_token_validation` is a required, already-validated field, so
+        this never raises. Still lazy + cached, purely to defer construction cost."""
+        if self._id_token is None:
+            self._id_token = IdTokenVerifier(
+                mode=self._config["id_token_validation"],
+                allowed_algorithms=self._config["allowed_algorithms"],
+                discovery=self.discovery,
+                transport=self._config["transport"],
+                clock=self._config["clock"],
+            )
+        return self._id_token
+
+    def resolved_config(self) -> dict[str, Any]:
+        """The resolved config, with every secret-bearing field replaced by `"<set>"` /
+        `"<unset>"` — safe to log or hand to a conformance driver."""
+        redacted: dict[str, Any] = dict(self._config)
+        redacted.pop("transport", None)
+        redacted.pop("clock", None)
+        redacted.pop("random", None)
+        for field in _SECRET_FIELDS:
+            redacted[field] = "<set>" if self._config.get(field) else "<unset>"
+        return redacted
+
+    def capabilities(self) -> dict[str, bool]:
+        """Which lazily-gated capabilities are currently usable, without constructing them."""
+        return {
+            "discovery": True,
+            "oidc": True,
+            "iam": True,
+            "roles": True,
+            "session": bool(self._config.get("session_signing_secret")),
+            "state": bool(self._config.get("state_signing_secret") or self._config.get("session_signing_secret")),
+            "id_token": True,
+        }
+
+    async def close(self) -> None:
+        await self.discovery.close()  # type: ignore[attr-defined]
+        await self.oidc.close()  # type: ignore[attr-defined]
+        await self.iam.close()  # type: ignore[attr-defined]
+        if self._id_token is not None:
+            await self._id_token.close()  # type: ignore[attr-defined]
+
+    async def __aenter__(self) -> "MemyAuth":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()