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

memyauth/_types.py

@@ -0,0 +1,309 @@
+"""
+@fileoverview Shared wire/projection type shapes and injection-seam protocols.
+@module memyauth._types
+@description TypedDict/Literal shapes for every public return value plus the Clock/RandomSource
+   protocols injected into every service (discovery, oidc, iam, idtoken, session, state). No
+   pydantic, no dataclasses — zero extra runtime dependency beyond httpx + PyJWT, matching the
+   customer SDK's zero-deps posture (js/ has zero runtime deps beyond jose). `UserContext` and its
+   nested shapes are deliberately `total=False`: the provider's `/iam/me` may add fields at any
+   time (C.5.1 / D2) and this SDK must never reject an unknown key — see `_iam.py` for the
+   hand-written validator that enforces "permissive about unknown fields, strict about known ones."
+@dependencies typing (stdlib only)
+@relatedFiles _iam.py, _discovery.py, _oidc.py, _idtoken.py, _session.py, _state.py, _config.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Literal, Protocol, TypedDict
+
+
+# ---------------------------------------------------------------------------
+# Injection seams (present on every service; §C preamble)
+# ---------------------------------------------------------------------------
+
+
+class Clock(Protocol):
+    def now(self) -> int:
+        """Epoch milliseconds. Mirrors the JS `Clock` seam exactly."""
+        ...
+
+
+class RandomSource(Protocol):
+    def bytes(self, n: int) -> bytes:
+        """`n` cryptographically-random bytes. Mirrors the JS `RandomSource` seam exactly."""
+        ...
+
+
+class SystemClock:
+    """Default `Clock`: the wall clock, in epoch milliseconds."""
+
+    def now(self) -> int:
+        return int(time.time() * 1000)
+
+
+# ---------------------------------------------------------------------------
+# Literal enums (§F, §C.10)
+# ---------------------------------------------------------------------------
+
+TokenEndpointAuthMethod = Literal["client_secret_post", "client_secret_basic"]
+IdTokenValidationMode = Literal["local-jwks", "tls-token-endpoint"]
+IamCallerMode = Literal["auto", "appiam", "appidp", "m2m"]
+
+
+# ---------------------------------------------------------------------------
+# Capability 1 — Discovery (§C.1)
+# ---------------------------------------------------------------------------
+
+
+class OidcDiscoveryDocument(TypedDict, total=False):
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    userinfo_endpoint: str
+    jwks_uri: str
+    end_session_endpoint: str
+    scopes_supported: list[str]
+    id_token_signing_alg_values_supported: list[str]
+
+
+class DiscoveryHealth(TypedDict):
+    state: Literal["ok", "failed", "unknown"]
+    last_success_at: str | None
+    last_error: str | None
+
+
+# ---------------------------------------------------------------------------
+# Capability 2 — Authorization URL (§C.2)
+# ---------------------------------------------------------------------------
+
+
+class AuthorizationRequest(TypedDict):
+    url: str
+    code_verifier: str
+    code_challenge: str
+    state: str
+    nonce: str
+    redirect_uri: str
+    scope: str
+
+
+# ---------------------------------------------------------------------------
+# Capability 3 — Token exchange / refresh (§C.3)
+# ---------------------------------------------------------------------------
+
+
+class OidcTokenResponse(TypedDict, total=False):
+    access_token: str
+    token_type: str
+    expires_in: int
+    id_token: str
+    refresh_token: str
+    scope: str
+
+
+# ---------------------------------------------------------------------------
+# Capability 4 — UserInfo (§C.4)
+# ---------------------------------------------------------------------------
+
+
+class UserInfoTenantMirror(TypedDict, total=False):
+    id: str
+    code: str
+    idp_users_sub: str
+
+
+class UserInfo(TypedDict, total=False):
+    sub: str
+    email: str
+    email_verified: bool
+    name: str
+    picture: str
+    roles: list[str]
+    custom_data: dict[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Capability 5 — IAM (§C.5, §B.1) — vendored (by hand, since this SDK has no
+# sync-contract.mjs equivalent for Python) from iam/api/src/lib/user-context.ts:59-87.
+# Deliberately `total=False` at every level: unknown keys are tolerated (C.5.1); the
+# hand-written validator in _iam.py enforces the KNOWN keys strictly before this shape
+# is ever handed to a caller.
+# ---------------------------------------------------------------------------
+
+
+class UserContextTenant(TypedDict, total=False):
+    id: str
+    code: str
+    idp_users_sub: str
+    key: str  # 64-char lowercase hex; bearer-equivalent — see tenantKeyRedaction rule.
+    created_at: str
+    updated_at: str
+
+
+class UserContextOrgEntry(TypedDict, total=False):
+    id: str
+    name: str
+    roles: list[str]
+    tenant: dict[str, Any] | None
+
+
+class UserContext(TypedDict, total=False):
+    user: dict[str, Any]
+    tenant: UserContextTenant
+    organizations: dict[str, list[UserContextOrgEntry]]
+    permissions: list[str]
+
+
+# Re-exported alias, matching the JS `export type IamUserContext = UserContext;`
+IamUserContext = UserContext
+
+
+class IamOrgEntryTenant(TypedDict, total=False):
+    id: str
+    code: str
+    idp_users_sub: str
+    key: str
+
+
+class IamOrgEntry(TypedDict):
+    id: str
+    name: str
+    roles: list[str]
+    tenant: IamOrgEntryTenant | None
+
+
+class IamTenant(TypedDict, total=False):
+    id: str
+    code: str
+    idp_users_sub: str
+    key: str
+    created_at: str
+    updated_at: str
+
+
+class IamOrganizations(TypedDict):
+    own: list[IamOrgEntry]
+    as_member: list[IamOrgEntry]
+
+
+class IamSession(TypedDict, total=False):
+    user_id: str
+    idp_subject: str
+    email: str
+    email_verified: bool | None
+    display_name: str
+    tenant_id: str
+    tenant_code: str
+    tenant_key: str
+    idp_roles: list[str]
+    roles: list[str]
+    scopes: list[str]
+    permissions: list[str]
+    is_global_admin: bool
+    organizations: IamOrganizations
+
+
+# ---------------------------------------------------------------------------
+# Capability 7 — Session tokens (§C.7) — an SDK-owned family, structurally
+# distinct from provider (ES384) tokens. See _session.py for the six-way separation.
+# ---------------------------------------------------------------------------
+
+
+class SessionAccessInput(TypedDict, total=False):
+    sub: str
+    tenants_id: str | None
+    roles: list[str]
+    email: str
+    email_verified: bool
+    is_global_admin: bool
+    auth_method: Literal["oidc", "local"]
+    iam_tenant_key: str
+
+
+class SessionAccessClaims(SessionAccessInput, total=False):
+    type: Literal["access"]
+    iss: str
+    iat: int
+    exp: int
+
+
+class SessionRefreshInput(TypedDict, total=False):
+    sub: str
+    tenants_id: str
+    jti: str
+    iam_tenant_key: str
+
+
+class SessionRefreshClaims(SessionRefreshInput, total=False):
+    type: Literal["refresh"]
+    iss: str
+    iat: int
+    exp: int
+
+
+# ---------------------------------------------------------------------------
+# Capability 8 — State cookie (§C.8)
+# ---------------------------------------------------------------------------
+
+
+class StateCookieInput(TypedDict, total=False):
+    code_verifier: str
+    nonce: str
+    state: str
+    return_to: str
+
+
+class StateCookiePayload(TypedDict):
+    code_verifier: str
+    nonce: str
+    state: str
+    return_to: str
+
+
+# ---------------------------------------------------------------------------
+# Capability C0 — ID-token trust strategies (§C.10)
+# ---------------------------------------------------------------------------
+
+
+class IdpTokenClaims(TypedDict, total=False):
+    iss: str
+    sub: str
+    aud: str | list[str]
+    exp: int
+    iat: int
+    nonce: str
+    auth_time: int
+    azp: str
+
+
+__all__ = [
+    "Clock",
+    "RandomSource",
+    "SystemClock",
+    "TokenEndpointAuthMethod",
+    "IdTokenValidationMode",
+    "IamCallerMode",
+    "OidcDiscoveryDocument",
+    "DiscoveryHealth",
+    "AuthorizationRequest",
+    "OidcTokenResponse",
+    "UserInfoTenantMirror",
+    "UserInfo",
+    "UserContextTenant",
+    "UserContextOrgEntry",
+    "UserContext",
+    "IamUserContext",
+    "IamOrgEntryTenant",
+    "IamOrgEntry",
+    "IamTenant",
+    "IamOrganizations",
+    "IamSession",
+    "SessionAccessInput",
+    "SessionAccessClaims",
+    "SessionRefreshInput",
+    "SessionRefreshClaims",
+    "StateCookieInput",
+    "StateCookiePayload",
+    "IdpTokenClaims",
+]

memyauth/sync/__init__.py

@@ -0,0 +1,147 @@
+"""
+@fileoverview Public synchronous facade — GENERATED twins from `_sync/` + the shared pure modules.
+@module memyauth.sync
+@description Thin re-export layer, hand-written (this file itself is NOT generated — only
+   `_sync/*.py` is). `RoleMapper`, `SessionTokenService`, `StateCookieService`,
+   `resolve_config`/`ResolvedConfig`, every error class, and every `_types.py` shape are SHARED —
+   the identical object the async surface imports, since they carry no `async`/`await` and
+   therefore have no sync/async distinction to generate. Only `MemyAuth`, `DiscoveryService`,
+   `OidcService`, `IamService` and `IdTokenVerifier` come from `_sync/`, the unasync-generated
+   twins of `_client.py`/`_discovery.py`/`_oidc.py`/`_iam.py`/`_idtoken.py`.
+@dependencies ../_sync/* (generated), ../_roles.py, ../_session.py, ../_state.py, ../_config.py,
+   ../_errors.py, ../_types.py, ../_pkce.py (all shared/pure)
+@relatedFiles ../scripts/gen_sync.py (the generator), ../_sync/__init__.py (generated package
+   marker), ../../tests/test_sync_parity.py, ../../tests/test_sync_functional.py
+@created 2026-09-06
+"""
+from .._config import ResolvedConfig, RetryConfig, resolve_config
+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 .._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 .._sync._client import SDK_VERSION, MemyAuth
+from .._sync._discovery import DiscoveryService
+from .._sync._iam import IamService
+from .._sync._idtoken import IdTokenVerifier
+from .._sync._oidc import OidcService
+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",
+    "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",
+    "Clock",
+    "RandomSource",
+    "SystemClock",
+    "OidcDiscoveryDocument",
+    "DiscoveryHealth",
+    "AuthorizationRequest",
+    "OidcTokenResponse",
+    "UserInfo",
+    "UserContext",
+    "UserContextTenant",
+    "UserContextOrgEntry",
+    "IamUserContext",
+    "IamSession",
+    "IamOrgEntry",
+    "IamTenant",
+    "SessionAccessInput",
+    "SessionAccessClaims",
+    "SessionRefreshInput",
+    "SessionRefreshClaims",
+    "StateCookieInput",
+    "StateCookiePayload",
+    "IdpTokenClaims",
+]

memydev_auth_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: memydev-auth-sdk
+Version: 0.1.0
+Summary: Official MemyAuth (OIDC + IAM) client SDK for Python
+License: Proprietary and unlicensed pending approved service terms.
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pyjwt[crypto]<3,>=2.9
+Provides-Extra: dev
+Requires-Dist: editables==0.5; extra == 'dev'
+Requires-Dist: hatchling==1.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==0.24.0; extra == 'dev'
+Requires-Dist: pytest==8.3.5; extra == 'dev'
+Requires-Dist: respx==0.22.0; extra == 'dev'
+Requires-Dist: unasync==0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memydev-auth-sdk
+
+Official Python client for **MemyAuth** — the estate's OIDC + IAM provider. Import name: `memyauth`.
+
+```python
+import asyncio
+from memyauth import MemyAuth
+
+async def main() -> None:
+    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",   # or "tls-token-endpoint" — see below, no default
+    ) as auth:
+        req = await auth.oidc.build_authorization_url()
+        # redirect the browser to req.url, persist req via auth.state.sign(...)
+        ...
+
+asyncio.run(main())
+```
+
+A synchronous facade is available for non-async callers:
+
+```python
+from memyauth.sync import MemyAuth
+
+with MemyAuth(issuer_url=..., client_id=..., client_secret=..., id_token_validation="local-jwks") as auth:
+    tokens = auth.oidc.exchange_code(code=..., code_verifier=...)
+```
+
+## Choosing `id_token_validation`
+
+MemyAuth signs ID tokens with **ES384 only**. Two ID-token trust strategies are both in production
+use across the estate and neither is a silent default — you must choose:
+
+- `local-jwks` (**recommended for new consumers**): verifies the ID token's signature locally
+  against the provider's JWKS, with an explicit algorithm allow-list (`["ES384"]` by default).
+  Stateless, no extra round trip, defends against ID-token substitution.
+- `tls-token-endpoint`: performs **no** local signature verification; identity is derived from the
+  direct TLS channel to the token endpoint (OIDC Core §3.1.3.7 item 6) plus `/oidc/me` or
+  `/iam/me`. Choose this only when you never process the ID token directly.
+
+An `allowed_algorithms` pin that cannot verify any token this provider issues (e.g. `["RS256"]`)
+fails loudly at construction with `UnsupportedAlgorithmPinError` — this SDK exists in large part to
+make that historically-real defect (shipped twice against this provider) impossible to repeat
+silently.
+
+## Async is the source of truth
+
+`memyauth/_*.py` are hand-written and authoritative. `memyauth/_sync/*.py` and the `memyauth.sync`
+facade are **mechanically generated** from them by `scripts/gen_sync.py` (via `unasync`) — never
+hand-edit `_sync/`. Regenerate after any async change:
+
+```
+python scripts/gen_sync.py            # write the twins
+python scripts/gen_sync.py --check    # verify no drift; exits non-zero if the twins are stale
+```
+
+## Development
+
+```
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install hatchling==1.27.0 editables==0.5
+.venv/bin/python -m pip install --no-build-isolation -e ".[dev]"
+.venv/bin/python -m pytest -q
+```

memydev_auth_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+memyauth/__init__.py,sha256=2suvRP3XrsOxdCw34S6lg4Gr-8kH1ilVx9qxqPtoIDU,3836
+memyauth/_client.py,sha256=Inye4y6vocOiKiedodv1jSTfBX85nLEDL-WMupwTa_M,7191
+memyauth/_config.py,sha256=N0eEPEHN_ICgkKUMKroX-buXZpHgpht_XMackPX72kM,19233
+memyauth/_discovery.py,sha256=HKDNtRgmTc_s9EOrWwJAxktqLu_Bh44SF8uClXJErSw,7617
+memyauth/_errors.py,sha256=9_DlqVwKaPn0BuAQOzKm1iNYPAe2t_dzmxfh_yu1c_c,8554
+memyauth/_iam.py,sha256=l_BmdCESPrY31qljMwMl_eIA90ImuQmmNj15B9SHWC0,13432
+memyauth/_idtoken.py,sha256=WgjEcbr0eqXiDrNIRDFKdXo9QBP7H1DXn7AeLyjdWko,7672
+memyauth/_oidc.py,sha256=MsdrspJSimNflmLzyIE1d5xFw_rutzL7jj_cDjevLVc,10810
+memyauth/_pkce.py,sha256=5cR2jV-5_xeLbOOCNltttWS9YldyWg7OKcDP4CJIk28,2155
+memyauth/_roles.py,sha256=F2_k6jlVRRical9rcKRdPpT-hze3jV01RfQ9GijjGfc,4539
+memyauth/_session.py,sha256=A2UqBtFAWHLXeNtFAoYXjkKj5IbuQU0y26RLKInKe6w,6840
+memyauth/_state.py,sha256=pM75vFDv_k9xSGIMjo79LUn3I1KmbZ0CO1ss2wINqnM,5594
+memyauth/_transport.py,sha256=mgJlXbz1sLYW6dj5B-dIvzX_iz2uaB4_u4I1OvD7zig,9153
+memyauth/_types.py,sha256=gdCLzlYOwKgIw69p4ar23d1oPmC9RLsrkGqD5uX7PW0,8431
+memyauth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+memyauth/_sync/__init__.py,sha256=C9HwbhD1iuIiCuRc8lXQr04PRZXNvYQQz7Vld5M4VMk,253
+memyauth/_sync/_client.py,sha256=lbNWcGqLAtG_AKYjDy1sudn6gWM2zzjSxRHPC3TA35c,7300
+memyauth/_sync/_discovery.py,sha256=fa5kAzwMInWqj8Dhb-XfNgYY7Sr8DiIQw1itIzH35Mc,7719
+memyauth/_sync/_iam.py,sha256=HGH8ndzKqHoDESHlM2e_7K9OgBeLw4xTKCj1hMeV-b0,13528
+memyauth/_sync/_idtoken.py,sha256=d7MKijTerr7vT-zhtBZGANFngMLeNuQjNkCJ9oHBX2Y,7778
+memyauth/_sync/_oidc.py,sha256=6mt6emqrYm0elGu5Kd_8JRlpW3lpR1XSWeYwH2kQ8V4,10871
+memyauth/_sync/_transport.py,sha256=QK_dcoR7LODYDNIErRjeG39f9RDCShu-WAVdMYxG4bY,9242
+memyauth/sync/__init__.py,sha256=65nT-87ibWzsF-dQuwkF_E8DHbzd1lknxQQwLYeu8Z4,4298
+memydev_auth_sdk-0.1.0.dist-info/METADATA,sha256=c_v3hmb3PPgtcbqrgIJyiRsJhsdGOwpq2Efi5Dy4DFk,3327
+memydev_auth_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+memydev_auth_sdk-0.1.0.dist-info/RECORD,,

memydev_auth_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any