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

memydev_auth_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: memydev-auth-sdk
+Version: 0.2.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=...)
+```
+
+## IAM: identity, tenants, webhooks, tenant keys, tenant administration
+
+Every relying-party operation of the IAM API (2.8.0) is covered. Projections are snake_case dicts with
+the documented fields only (unknown wire fields are dropped, required ones are checked).
+
+```python
+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",
+    iam_app_id="my-app",              # appiam caller credential (X-AppIam-Id + secret)
+    iam_app_secret="...",
+    iam_scoped_token=get_iam_token,   # IAM-resource token: a string or a (coroutine) function
+) as auth:
+    session = await auth.iam.me(user_token)                       # GET /iam/me
+    tenant = await auth.iam.lookup_tenant(code="acme")            # GET /iam/tenants
+    ready = await auth.iam.ready()                                 # {"ready": True, "status": "ok", ...}
+
+    keys = await auth.tenant_keys.list_keys(user_token)            # the signed-in owner's own tenant
+    created = await auth.tenant_keys.create_key(user_token, label="primary", rotate={"grace_seconds": 3600})
+    await auth.tenant_keys.update_key(user_token, key_id, expires_at=None)   # None clears; omit to keep
+
+    page = await auth.tenant_admin.list_tenants(code_prefix="ac", limit=50)  # in-cluster only
+    await auth.tenant_admin.rotate_keys(tenant_id, 0, request_id="ops-2026-10-03-001")  # break-glass, no value returned
+    audit = await auth.tenant_admin.list_audit(tenant_id=tenant_id, action="rotate")  # who changed what, newest first
+
+    config = await auth.webhooks.register(webhook_uri="https://my-app.example.com/iam-webhook")
+    secret = config.get("signing_secret")                          # present once — store it now
+```
+
+- **Self tenant keys** need the `iam:self` grant. An appiam app holds it in IAM (`create-app --scopes
+  iam:self`); an appidp/m2m caller presents an IAM-resource token carrying `iam:self` (`iam_scoped_token`,
+  or `scoped_token=` per call) instead of its client secret. In `auto` mode `X-AppIdp-Id` is sent only when
+  the token's (unverified) `sub` is your `client_id`; otherwise the token goes alone (m2m).
+- Every `tenant_id` / `key_id` must be a UUID, and every token or secret printable ASCII without surrounding
+  whitespace — both checked before any request; errors never echo the value.
+- **Tenant administration** presents the IAM-resource token alone, with `iam:tenants:*` / `iam:keys:*`.
+- **The SDK never mints that token.** Mint it with the client-credentials grant, `resource=IAM_API_RESOURCE`
+  and the scopes your Logto role grants; pass a function to refresh it — it is called on every request
+  that needs it.
+- Errors: `TenantKeyConflictError` (`.reason` `last_key` / `max_live`), `TenantAdminConflictError`
+  (`code_taken`), `ScopeForbiddenError` (`.required_scopes`), `GoneError` for a deprovisioned tenant looked
+  up by id. Live keys are returned with their value only on the owner's own routes; the SDK never logs a
+  key or puts one in an error message.
+
+Receiving IAM webhooks:
+
+```python
+from memyauth import is_tenant_key_event, parse_tenant_event, parse_webhook_envelope, verify_webhook_signature
+
+if not verify_webhook_signature(raw_body, headers.get("X-IAM-Webhook-Signature"), signing_secret):
+    return 401
+event = parse_webhook_envelope(raw_body)   # dedupe on event["id"]
+if is_tenant_key_event(event):             # Tenant.KeyCreated / KeyRotated / KeyRevoked / Deprovisioned
+    change = parse_tenant_event(event)     # actor_kind, key_id, key_prefix, retired_keys … — never a key value
+```
+
+## 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.2.0/README.md

@@ -0,0 +1,128 @@
+# 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=...)
+```
+
+## IAM: identity, tenants, webhooks, tenant keys, tenant administration
+
+Every relying-party operation of the IAM API (2.8.0) is covered. Projections are snake_case dicts with
+the documented fields only (unknown wire fields are dropped, required ones are checked).
+
+```python
+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",
+    iam_app_id="my-app",              # appiam caller credential (X-AppIam-Id + secret)
+    iam_app_secret="...",
+    iam_scoped_token=get_iam_token,   # IAM-resource token: a string or a (coroutine) function
+) as auth:
+    session = await auth.iam.me(user_token)                       # GET /iam/me
+    tenant = await auth.iam.lookup_tenant(code="acme")            # GET /iam/tenants
+    ready = await auth.iam.ready()                                 # {"ready": True, "status": "ok", ...}
+
+    keys = await auth.tenant_keys.list_keys(user_token)            # the signed-in owner's own tenant
+    created = await auth.tenant_keys.create_key(user_token, label="primary", rotate={"grace_seconds": 3600})
+    await auth.tenant_keys.update_key(user_token, key_id, expires_at=None)   # None clears; omit to keep
+
+    page = await auth.tenant_admin.list_tenants(code_prefix="ac", limit=50)  # in-cluster only
+    await auth.tenant_admin.rotate_keys(tenant_id, 0, request_id="ops-2026-10-03-001")  # break-glass, no value returned
+    audit = await auth.tenant_admin.list_audit(tenant_id=tenant_id, action="rotate")  # who changed what, newest first
+
+    config = await auth.webhooks.register(webhook_uri="https://my-app.example.com/iam-webhook")
+    secret = config.get("signing_secret")                          # present once — store it now
+```
+
+- **Self tenant keys** need the `iam:self` grant. An appiam app holds it in IAM (`create-app --scopes
+  iam:self`); an appidp/m2m caller presents an IAM-resource token carrying `iam:self` (`iam_scoped_token`,
+  or `scoped_token=` per call) instead of its client secret. In `auto` mode `X-AppIdp-Id` is sent only when
+  the token's (unverified) `sub` is your `client_id`; otherwise the token goes alone (m2m).
+- Every `tenant_id` / `key_id` must be a UUID, and every token or secret printable ASCII without surrounding
+  whitespace — both checked before any request; errors never echo the value.
+- **Tenant administration** presents the IAM-resource token alone, with `iam:tenants:*` / `iam:keys:*`.
+- **The SDK never mints that token.** Mint it with the client-credentials grant, `resource=IAM_API_RESOURCE`
+  and the scopes your Logto role grants; pass a function to refresh it — it is called on every request
+  that needs it.
+- Errors: `TenantKeyConflictError` (`.reason` `last_key` / `max_live`), `TenantAdminConflictError`
+  (`code_taken`), `ScopeForbiddenError` (`.required_scopes`), `GoneError` for a deprovisioned tenant looked
+  up by id. Live keys are returned with their value only on the owner's own routes; the SDK never logs a
+  key or puts one in an error message.
+
+Receiving IAM webhooks:
+
+```python
+from memyauth import is_tenant_key_event, parse_tenant_event, parse_webhook_envelope, verify_webhook_signature
+
+if not verify_webhook_signature(raw_body, headers.get("X-IAM-Webhook-Signature"), signing_secret):
+    return 401
+event = parse_webhook_envelope(raw_body)   # dedupe on event["id"]
+if is_tenant_key_event(event):             # Tenant.KeyCreated / KeyRotated / KeyRevoked / Deprovisioned
+    change = parse_tenant_event(event)     # actor_kind, key_id, key_prefix, retired_keys … — never a key value
+```
+
+## 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 → memydev_auth_sdk-0.2.0}/pyproject.toml

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

{memydev_auth_sdk-0.1.0 → memydev_auth_sdk-0.2.0}/scripts/gen_sync.py

@@ -3,7 +3,8 @@
 @fileoverview Generate the SYNCHRONOUS memyauth SDK twins from the async sources via unasync.
 @module memyauth.scripts.gen_sync
 @description Single-source generation of memyauth/_sync/*.py from the hand-written async modules
-   (`_client.py`, `_discovery.py`, `_oidc.py`, `_iam.py`, `_idtoken.py`, `_transport.py`) — the
+   (`_client.py`, `_discovery.py`, `_oidc.py`, `_iam.py`, `_idtoken.py`, `_transport.py`; since 0.2.0
+   also `_caller.py`, `_webhooks.py`, `_tenant_keys.py`, `_tenant_admin.py`) — the
    Python-side mirror of the *design pattern* used by `sdk/contract/scripts/sync-contract.mjs`
    (single-source-of-truth + a `--check` drift gate), NOT the same tool and NOT interchangeable
    with it. `sync-contract.mjs` VENDORS TYPES from provider TypeScript source files
@@ -52,7 +53,20 @@ SYNC_DIR = PKG / "_sync"
 # _config, _types, _pkce) have zero async/await and are imported directly by BOTH surfaces —
 # generating a twin for them would just be a byte-identical copy, so gen_sync intentionally
 # doesn't touch them (mirrors memybase's own ASYNC_MODULES scoping).
-ASYNC_MODULES = ["_client", "_discovery", "_oidc", "_iam", "_idtoken", "_transport"]
+ASYNC_MODULES = [
+    "_client",
+    "_discovery",
+    "_oidc",
+    "_iam",
+    "_idtoken",
+    "_transport",
+    # 0.2.0 — the shared caller-header resolver (its one async helper resolves an awaitable token
+    # source) and the three new IAM services.
+    "_caller",
+    "_webhooks",
+    "_tenant_keys",
+    "_tenant_admin",
+]
 
 _RULE = unasync.Rule(
     fromdir="/memyauth/",

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

@@ -3,11 +3,15 @@
 @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
+   `_transport.py`, and since 0.2.0 `_caller.py`, `_webhooks.py`, `_tenant_keys.py`,
+   `_tenant_admin.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).
+   `_config.py`, `_errors.py`, `_types.py`, `_pkce.py`, `_contract.py`, `_iam_shapes.py`,
+   `_webhook_receiver.py` are pure/synchronous and shared verbatim by both surfaces (no twin exists or
+   is needed).
 @created 2026-09-06
+@updated 2026-10-03 SDK 0.2.0 exports (webhooks, tenant keys, tenant administration, webhook receiver
+   helpers, IAM resource/scope constants, conflict/scope errors, the new shapes).
 """
 from ._client import MemyAuth, SDK_VERSION
 from ._config import ResolvedConfig, RetryConfig, resolve_config
@@ -15,6 +19,7 @@ from ._discovery import DiscoveryService
 from ._errors import (
     BadRequestError,
     ConfigError,
+    ConflictError,
     DiscoveryError,
     DiscoveryEscapeError,
     ForbiddenError,
@@ -26,10 +31,13 @@ from ._errors import (
     NotFoundError,
     ProtocolError,
     RefreshRejectedError,
+    ScopeForbiddenError,
     ServiceUnavailableError,
     SessionTokenError,
     StateCookieError,
     StateMismatchError,
+    TenantAdminConflictError,
+    TenantKeyConflictError,
     TimeoutError,
     TokenExchangeError,
     UnauthorizedError,
@@ -38,6 +46,7 @@ from ._errors import (
     UserInfoError,
     decode_error,
 )
+from ._contract import ADMIN_AUDIT_ACTIONS, IAM_API_RESOURCE, IAM_SCOPES, TENANT_EVENT_TYPES
 from ._iam import IamService
 from ._idtoken import IdTokenVerifier
 from ._oidc import OidcService
@@ -45,11 +54,30 @@ from ._pkce import SystemRandomSource, generate_code_challenge, generate_code_ve
 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 ._tenant_admin import TenantAdminService
+from ._tenant_keys import TenantKeyService
+from ._webhook_receiver import (
+    WEBHOOK_HEADERS,
+    is_tenant_key_event,
+    parse_tenant_event,
+    parse_webhook_envelope,
+    verify_webhook_signature,
+)
+from ._webhooks import AppWebhookService
 from ._types import (
+    AdminAuditEntry,
+    AdminAuditList,
+    AppWebhookConfig,
+    AppWebhookRegistration,
+    AppWebhookSecret,
+    AppWebhookUnregistered,
     AuthorizationRequest,
     Clock,
     DiscoveryHealth,
+    IamOrganizationBinding,
     IamOrgEntry,
+    IamReadiness,
+    IamScopedTokenSource,
     IamSession,
     IamTenant,
     IamUserContext,
@@ -64,10 +92,20 @@ from ._types import (
     StateCookieInput,
     StateCookiePayload,
     SystemClock,
+    TenantAdminList,
+    TenantAdminSummary,
+    TenantKey,
+    TenantKeyCreated,
+    TenantKeyList,
+    TenantKeyRotate,
+    TenantEvent,
+    TenantEventKeyRef,
+    TenantEventRetiredKey,
     UserContext,
     UserContextOrgEntry,
     UserContextTenant,
     UserInfo,
+    WebhookEnvelope,
 )
 
 __version__ = SDK_VERSION
@@ -82,6 +120,18 @@ __all__ = [
     "DiscoveryService",
     "OidcService",
     "IamService",
+    "AppWebhookService",
+    "TenantKeyService",
+    "TenantAdminService",
+    "verify_webhook_signature",
+    "parse_webhook_envelope",
+    "WEBHOOK_HEADERS",
+    "is_tenant_key_event",
+    "parse_tenant_event",
+    "IAM_API_RESOURCE",
+    "IAM_SCOPES",
+    "ADMIN_AUDIT_ACTIONS",
+    "TENANT_EVENT_TYPES",
     "IdTokenVerifier",
     "RoleMapper",
     "DEFAULT_ROLE_MAP",
@@ -106,6 +156,10 @@ __all__ = [
     "NotFoundError",
     "GoneError",
     "ServiceUnavailableError",
+    "ConflictError",
+    "TenantKeyConflictError",
+    "TenantAdminConflictError",
+    "ScopeForbiddenError",
     "DiscoveryError",
     "IssuerMismatchError",
     "DiscoveryEscapeError",
@@ -134,6 +188,25 @@ __all__ = [
     "IamSession",
     "IamOrgEntry",
     "IamTenant",
+    "IamScopedTokenSource",
+    "IamReadiness",
+    "IamOrganizationBinding",
+    "AppWebhookConfig",
+    "AppWebhookRegistration",
+    "AppWebhookUnregistered",
+    "AppWebhookSecret",
+    "TenantKey",
+    "TenantKeyList",
+    "TenantKeyCreated",
+    "TenantKeyRotate",
+    "TenantAdminSummary",
+    "TenantAdminList",
+    "WebhookEnvelope",
+    "AdminAuditEntry",
+    "AdminAuditList",
+    "TenantEvent",
+    "TenantEventKeyRef",
+    "TenantEventRetiredKey",
     "SessionAccessInput",
     "SessionAccessClaims",
     "SessionRefreshInput",

memydev_auth_sdk-0.2.0/src/memyauth/_caller.py

@@ -0,0 +1,167 @@
+"""
+@fileoverview Caller-credential header resolution shared by every IAM-facing service.
+@module memyauth._caller
+@description [async -> _sync/_caller.py twin via scripts/gen_sync.py — only `resolve_scoped_token`
+   awaits anything; the rest is pure and identical in both]. The Python twin of the JS SDK's
+   `caller.ts`, rule for rule. The single-marker rule (§C.5, R6) lives here once for all four IAM
+   services: every header set built here carries AT MOST ONE marker header (`X-AppIam-Id` or
+   `X-AppIdp-Id`).
+
+   1. `resolve_caller_headers()` — `/iam/me`, `/iam/tenants*`, `/iam/users`, `/iam/organizations/{id}`,
+      the app-webhook routes. Moved verbatim from `_iam.py` (0.1.0; `_iam.resolve_caller_headers` still
+      resolves to it): appiam (app secret), appidp (client secret), m2m (`iam_m2m_token`); `auto` walks
+      appiam -> appidp -> m2m.
+   2. `resolve_self_caller_headers()` — the self tenant-key routes. appidp and m2m present the
+      IAM-resource token (carrying `iam:self`) instead of the client secret / `iam_m2m_token`; appiam keeps
+      the app secret (its grant lives in `apps.scopes`). `auto` picks appiam when configured (without
+      invoking a token callable), else appidp only when the token's unverified `sub` is `client_id`, else
+      m2m.
+   3. `admin_caller_headers()` — the tenant-administration routes: the IAM-resource token alone.
+
+   `resolve_scoped_token()` turns the configured or per-call `IamScopedTokenSource` into the token; on
+   the async surface a callable may return an awaitable. The SDK never mints that token, and no message
+   built here echoes a secret or a token.
+@dependencies ._config (ResolvedConfig), ._errors (ConfigError), ._types
+@relatedFiles _iam.py, _webhooks.py, _tenant_keys.py, _tenant_admin.py, ../../../js/src/caller.ts
+@created 2026-10-03
+@updated 2026-10-03 Pre-publish review: `auto` on the self routes decides appidp vs m2m from the token's
+   unverified `sub`; every token is checked with `is_header_safe()` before it becomes a header value.
+"""
+from __future__ import annotations
+
+import base64
+import inspect
+import json
+from typing import Any, Optional
+
+from memyauth._config import ResolvedConfig
+from memyauth._errors import ConfigError
+from memyauth._headers import is_header_safe
+from memyauth._types import IamCallerMode
+
+__all__ = [
+    "MISSING_CALLER_CREDENTIALS_MESSAGE",
+    "MISSING_SCOPED_TOKEN_MESSAGE",
+    "resolve_caller_headers",
+    "resolve_self_caller_headers",
+    "unverified_jwt_subject",
+    "is_header_safe",
+    "admin_caller_headers",
+    "resolve_scoped_token",
+]
+
+MISSING_CALLER_CREDENTIALS_MESSAGE = "IAM caller credentials are not configured"
+MISSING_SCOPED_TOKEN_MESSAGE = "an IAM-resource token is required (config iamScopedToken or a per-call scopedToken)"
+_EMPTY_SCOPED_TOKEN_MESSAGE = "the IAM-resource token source returned no token"
+_UNSAFE_SCOPED_TOKEN_MESSAGE = (
+    "the IAM-resource token has surrounding whitespace, a control character or a non-ASCII character"
+)
+
+
+def _has_appiam(config: ResolvedConfig) -> bool:
+    return bool(config.get("iam_app_id")) and bool(config.get("iam_app_secret"))
+
+
+def _appiam_headers(config: ResolvedConfig) -> dict[str, str]:
+    if not _has_appiam(config):
+        raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+    return {"X-AppIam-Id": config["iam_app_id"], "Authorization": f"Bearer {config['iam_app_secret']}"}  # type: ignore[typeddict-item]
+
+
+def resolve_caller_headers(config: ResolvedConfig, override_mode: Optional[IamCallerMode]) -> tuple[dict[str, str], str]:
+    """Returns EXACTLY ONE marker header (or none, for m2m) + the caller kind (§C.5, R6)."""
+    mode = override_mode or config["iam_caller_mode"]
+
+    def appidp() -> tuple[dict[str, str], str]:
+        if config.get("client_id") and config.get("client_secret"):
+            return (
+                {"X-AppIdp-Id": config["client_id"], "Authorization": f"Bearer {config['client_secret']}"},
+                "appidp",
+            )
+        raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+
+    def m2m() -> tuple[dict[str, str], str]:
+        if config.get("iam_m2m_token"):
+            return {"Authorization": f"Bearer {config['iam_m2m_token']}"}, "m2m"
+        raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+
+    if mode == "appiam":
+        return _appiam_headers(config), "appiam"
+    if mode == "appidp":
+        return appidp()
+    if mode == "m2m":
+        return m2m()
+
+    # auto: precedence appiam -> appidp -> m2m (memybase's order, §C.5).
+    if _has_appiam(config):
+        return _appiam_headers(config), "appiam"
+    if config.get("client_id") and config.get("client_secret"):
+        return appidp()
+    if config.get("iam_m2m_token"):
+        return m2m()
+    raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+
+
+def unverified_jwt_subject(token: str) -> Optional[str]:
+    """Decodes a JWT's payload WITHOUT verifying it and returns its `sub` — used only to pick which marker
+    header to send, never to trust anything (the provider verifies the token). `None` for an opaque or
+    malformed token. Mirrors the JS `unverifiedJwtSubject()`."""
+    parts = token.split(".")
+    if len(parts) != 3 or not parts[1]:
+        return None
+    try:
+        segment = parts[1] + "=" * (-len(parts[1]) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(segment.encode("ascii")).decode("utf-8"))
+    except Exception:  # noqa: BLE001 - any decoding failure means "not a JWT we can read"
+        return None
+    sub = payload.get("sub") if isinstance(payload, dict) else None
+    return sub if isinstance(sub, str) else None
+
+
+def _appidp_scoped_headers(config: ResolvedConfig, token: str) -> dict[str, str]:
+    return {"X-AppIdp-Id": config["client_id"], "Authorization": f"Bearer {token}"}
+
+
+async def resolve_self_caller_headers(config: ResolvedConfig, override_mode: Optional[IamCallerMode], source: Any) -> dict[str, str]:
+    """Caller headers for the self tenant-key routes. An explicit mode wins. `auto`: appiam when its row is
+    configured (no token callable is invoked); otherwise the IAM-resource token is resolved and its payload
+    decoded WITHOUT verification — appidp only when the token's `sub` equals `client_id` (the gateway
+    cross-checks exactly that), otherwise m2m. An OIDC web client's IAM-resource token normally comes from a
+    separate M2M application, so m2m is the usual outcome; the old `client_id ? appidp : m2m` rule could
+    never reach it (client_id is required) and made the default answer 401."""
+    mode = override_mode or config["iam_caller_mode"]
+    if mode == "appiam":
+        return _appiam_headers(config)
+    if mode in ("appidp", "m2m"):
+        if mode == "appidp" and not config.get("client_id"):
+            raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+        token = await resolve_scoped_token(source)
+        return _appidp_scoped_headers(config, token) if mode == "appidp" else admin_caller_headers(token)
+    if _has_appiam(config):
+        return _appiam_headers(config)
+    if source is None:
+        raise ConfigError(MISSING_CALLER_CREDENTIALS_MESSAGE)
+    token = await resolve_scoped_token(source)
+    if config.get("client_id") and unverified_jwt_subject(token) == config["client_id"]:
+        return _appidp_scoped_headers(config, token)
+    return admin_caller_headers(token)
+
+
+def admin_caller_headers(scoped_token: str) -> dict[str, str]:
+    """The tenant-administration routes: the IAM-resource token alone, no marker header."""
+    return {"Authorization": f"Bearer {scoped_token}"}
+
+
+async def resolve_scoped_token(source: Any) -> str:
+    """Resolves an `IamScopedTokenSource`. A callable is invoked on every call; on the async surface it
+    may return an awaitable."""
+    if source is None:
+        raise ConfigError(MISSING_SCOPED_TOKEN_MESSAGE)
+    value = source() if callable(source) else source
+    if inspect.isawaitable(value):
+        value = await value
+    if not isinstance(value, str) or not value:
+        raise ConfigError(_EMPTY_SCOPED_TOKEN_MESSAGE)
+    if not is_header_safe(value):
+        raise ConfigError(_UNSAFE_SCOPED_TOKEN_MESSAGE)
+    return value