larkify 0.1.0__py3-none-any.whl

larkify/__init__.py

@@ -0,0 +1,16 @@
+from .auth import AppAuthStrategy as AppAuthStrategy
+from .auth import BaseAuthStrategy as BaseAuthStrategy
+from .auth import IsvAppAuthStrategy as IsvAppAuthStrategy
+from .auth import OAuthToken as OAuthToken
+from .auth import OAuthTokenAuthStrategy as OAuthTokenAuthStrategy
+from .auth import OAuthWebAuthStrategy as OAuthWebAuthStrategy
+from .auth import TokenAuthStrategy as TokenAuthStrategy
+from .auth import UnauthAuthStrategy as UnauthAuthStrategy
+from .config import FEISHU_BASE_URL as FEISHU_BASE_URL
+from .config import LARK_BASE_URL as LARK_BASE_URL
+from .config import Config as Config
+from .core import FeishuCore as FeishuCore
+from .feishu import Feishu as Feishu
+from .model import FeishuModel as FeishuModel
+from .response import Response as Response
+from .utils import UNSET as UNSET

larkify/auth/__init__.py

@@ -0,0 +1,8 @@
+from .app import AppAuthStrategy as AppAuthStrategy
+from .app import IsvAppAuthStrategy as IsvAppAuthStrategy
+from .base import BaseAuthStrategy as BaseAuthStrategy
+from .oauth import OAuthToken as OAuthToken
+from .oauth import OAuthTokenAuthStrategy as OAuthTokenAuthStrategy
+from .oauth import OAuthWebAuthStrategy as OAuthWebAuthStrategy
+from .token import TokenAuthStrategy as TokenAuthStrategy
+from .unauth import UnauthAuthStrategy as UnauthAuthStrategy

larkify/auth/app.py

@@ -0,0 +1,334 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, ClassVar, Literal
+from urllib.parse import urlencode
+
+import httpx2
+
+from larkify.exception import AuthCredentialError
+from larkify.typing import TokenType
+
+from .base import (
+    BaseAuthStrategy,
+    CacheDelete,
+    CacheGet,
+    CacheSet,
+    FeishuAuth,
+    TokenFlow,
+    build_token_request,
+    parse_token_response,
+)
+from .oauth import OAUTH_TOKEN_PATH, OAuthTokenAuthStrategy, OAuthWebAuthStrategy
+
+if TYPE_CHECKING:
+    from larkify import FeishuCore
+
+# A token is replaced before it runs out, so that a request is never sent with a
+# token that expires in flight.
+EXPIRY_MARGIN = timedelta(minutes=10)
+
+# Tickets are pushed hourly. A stale one is rejected with a clear error, so it is
+# kept long enough to survive a missed delivery.
+APP_TICKET_TTL = timedelta(hours=2)
+
+TENANT_TOKEN_INTERNAL_PATH = "open-apis/auth/v3/tenant_access_token/internal"
+TENANT_TOKEN_STORE_PATH = "open-apis/auth/v3/tenant_access_token"
+APP_TOKEN_INTERNAL_PATH = "open-apis/auth/v3/app_access_token/internal"
+APP_TOKEN_STORE_PATH = "open-apis/auth/v3/app_access_token"
+APP_TICKET_RESEND_PATH = "open-apis/auth/v3/app_ticket/resend"
+AUTHORIZE_PATH = "open-apis/authen/v1/authorize"
+
+
+def _cache_ttl(expires_in: int) -> timedelta:
+    return timedelta(seconds=expires_in) - EXPIRY_MARGIN
+
+
+class _AppCredentialStrategy(BaseAuthStrategy):
+    """User identity entry points shared by both application kinds."""
+
+    app_id: str
+    app_secret: str
+
+    def as_oauth_token(
+        self,
+        token: str,
+        *,
+        expire_time: datetime | None = None,
+        refresh_token: str | None = None,
+        refresh_token_expire_time: datetime | None = None,
+    ) -> OAuthTokenAuthStrategy:
+        """Act as a user, from a stored `user_access_token`."""
+        return OAuthTokenAuthStrategy(
+            self.app_id,
+            self.app_secret,
+            token,
+            expire_time=expire_time,
+            refresh_token=refresh_token,
+            refresh_token_expire_time=refresh_token_expire_time,
+        )
+
+    def as_web_user(
+        self,
+        code: str,
+        redirect_uri: str | None = None,
+        *,
+        code_verifier: str | None = None,
+    ) -> OAuthWebAuthStrategy:
+        """Act as a user, from the code of the authorization redirect."""
+        return OAuthWebAuthStrategy(
+            self.app_id,
+            self.app_secret,
+            code,
+            redirect_uri=redirect_uri,
+            code_verifier=code_verifier,
+        )
+
+    def get_authorize_url(
+        self,
+        feishu: "FeishuCore",
+        redirect_uri: str,
+        *,
+        scope: str | None = None,
+        state: str | None = None,
+        code_challenge: str | None = None,
+        code_challenge_method: str | None = None,
+    ) -> str:
+        """Build the URL to send the user to, for the authorization code flow."""
+        base_url = feishu.config.oauth_base_url
+        if base_url is None:
+            raise AuthCredentialError("`oauth_base_url` is not configured")
+        params = {
+            "client_id": self.app_id,
+            "redirect_uri": redirect_uri,
+            "scope": scope,
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": code_challenge_method,
+        }
+        query = urlencode({k: v for k, v in params.items() if v is not None})
+        return str(base_url.join(AUTHORIZE_PATH)) + "?" + query
+
+
+@dataclass
+class AppAuth(FeishuAuth):
+    """Self-built application auth hook"""
+
+    feishu: "FeishuCore" = field(repr=False)
+    app_id: str
+    app_secret: str = field(repr=False)
+    tenant_token_api: Literal["oauth", "legacy"]
+
+    token_types: ClassVar[tuple[TokenType, ...]] = ("tenant", "app")
+
+    CACHE_KEY: ClassVar[str] = "larkify:auth:app:{app_id}:{token_type}"
+
+    def _build_oauth_tenant_token_request(
+        self, request: httpx2.Request, base_url: httpx2.URL
+    ) -> httpx2.Request:
+        return build_token_request(
+            self.feishu,
+            base_url.join(OAUTH_TOKEN_PATH),
+            request=request,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.app_id,
+                "client_secret": self.app_secret,
+            },
+        )
+
+    def _tenant_token_flow(self, request: httpx2.Request) -> TokenFlow:
+        base_url = self.feishu.config.oauth_base_url
+        # A private deployment without an accounts host has only the legacy API.
+        if self.tenant_token_api == "oauth" and base_url is not None:
+            response = yield self._build_oauth_tenant_token_request(request, base_url)
+            data = parse_token_response(self.feishu, response, "tenant_access_token")
+            yield from self._store("tenant", data["access_token"], data["expires_in"])
+            return data["access_token"]
+
+        response = yield build_token_request(
+            self.feishu,
+            self.feishu.config.base_url.join(TENANT_TOKEN_INTERNAL_PATH),
+            request=request,
+            json={"app_id": self.app_id, "app_secret": self.app_secret},
+        )
+        data = parse_token_response(self.feishu, response, "tenant_access_token")
+        yield from self._store("tenant", data["tenant_access_token"], data["expire"])
+        return data["tenant_access_token"]
+
+    def _app_token_flow(self, request: httpx2.Request) -> TokenFlow:
+        response = yield build_token_request(
+            self.feishu,
+            self.feishu.config.base_url.join(APP_TOKEN_INTERNAL_PATH),
+            request=request,
+            json={"app_id": self.app_id, "app_secret": self.app_secret},
+        )
+        data = parse_token_response(self.feishu, response, "app_access_token")
+        yield from self._store("app", data["app_access_token"], data["expire"])
+        return data["app_access_token"]
+
+    def _cache_key(self, token_type: TokenType) -> str:
+        return self.CACHE_KEY.format(app_id=self.app_id, token_type=token_type)
+
+    def _store(self, token_type: TokenType, token: str, expires_in: int):
+        if (ttl := _cache_ttl(expires_in)) > timedelta():
+            yield CacheSet(self._cache_key(token_type), token, ttl)
+
+    def token_flow(
+        self, request: httpx2.Request, token_type: TokenType, *, refresh: bool
+    ) -> TokenFlow:
+        key = self._cache_key(token_type)
+        if refresh:
+            yield CacheDelete(key)
+        elif token := (yield CacheGet(key)):
+            return token
+
+        if token_type == "tenant":
+            return (yield from self._tenant_token_flow(request))
+        return (yield from self._app_token_flow(request))
+
+
+@dataclass
+class AppAuthStrategy(_AppCredentialStrategy):
+    """Self-built application: tenant and app access tokens are automatic.
+
+    `tenant_token_api` selects how the tenant access token is obtained:
+    `"oauth"` is the current `POST /oauth/v3/token` client credentials grant,
+    which issues JWT tokens of up to about 4 KB. `"legacy"` is the older
+    `/open-apis/auth/v3/tenant_access_token/internal`.
+    """
+
+    app_id: str
+    app_secret: str = field(repr=False)
+    tenant_token_api: Literal["oauth", "legacy"] = "oauth"
+
+    def get_auth_flow(self, feishu: "FeishuCore") -> httpx2.Auth:
+        return AppAuth(feishu, self.app_id, self.app_secret, self.tenant_token_api)
+
+
+@dataclass
+class IsvAppAuth(FeishuAuth):
+    """Store application auth hook"""
+
+    feishu: "FeishuCore" = field(repr=False)
+    app_id: str
+    app_secret: str = field(repr=False)
+    app_ticket: str | None = field(repr=False)
+    tenant_key: str | None
+
+    token_types: ClassVar[tuple[TokenType, ...]] = ("tenant", "app")
+
+    APP_KEY: ClassVar[str] = "larkify:auth:isv:{app_id}:app"
+    TENANT_KEY: ClassVar[str] = "larkify:auth:isv:{app_id}:tenant:{tenant_key}"
+    TICKET_KEY: ClassVar[str] = "larkify:auth:isv:{app_id}:app_ticket"
+
+    def select_token_type(
+        self, allowed: tuple[TokenType, ...] | None
+    ) -> TokenType | None:
+        # Without a tenant, only the application itself can be authenticated.
+        if self.tenant_key is None and (allowed is None or "tenant" in allowed):
+            if allowed is None or "app" in allowed:
+                return "app"
+            raise AuthCredentialError(
+                "This API needs a tenant, use `auth.as_tenant(tenant_key)`"
+            )
+        return super().select_token_type(allowed)
+
+    def _app_token_flow(self, request: httpx2.Request, *, refresh: bool) -> TokenFlow:
+        key = self.APP_KEY.format(app_id=self.app_id)
+        if refresh:
+            yield CacheDelete(key)
+        elif token := (yield CacheGet(key)):
+            return token
+
+        ticket = self.app_ticket or (
+            yield CacheGet(self.TICKET_KEY.format(app_id=self.app_id))
+        )
+        if not ticket:
+            raise AuthCredentialError(
+                "No app_ticket available. Feishu pushes it hourly as the "
+                "`app_ticket` event, store it with `save_app_ticket`, or ask "
+                "for one with `feishu.rest.auth.v3.auth.app_ticket_resend`."
+            )
+
+        response = yield build_token_request(
+            self.feishu,
+            self.feishu.config.base_url.join(APP_TOKEN_STORE_PATH),
+            request=request,
+            json={
+                "app_id": self.app_id,
+                "app_secret": self.app_secret,
+                "app_ticket": ticket,
+            },
+        )
+        data = parse_token_response(self.feishu, response, "app_access_token")
+        token = data["app_access_token"]
+        if (ttl := _cache_ttl(data["expire"])) > timedelta():
+            yield CacheSet(key, token, ttl)
+        return token
+
+    def _tenant_token_flow(
+        self, request: httpx2.Request, *, refresh: bool
+    ) -> TokenFlow:
+        key = self.TENANT_KEY.format(app_id=self.app_id, tenant_key=self.tenant_key)
+        if refresh:
+            yield CacheDelete(key)
+        elif token := (yield CacheGet(key)):
+            return token
+
+        app_token = yield from self._app_token_flow(request, refresh=False)
+        response = yield build_token_request(
+            self.feishu,
+            self.feishu.config.base_url.join(TENANT_TOKEN_STORE_PATH),
+            request=request,
+            json={"app_access_token": app_token, "tenant_key": self.tenant_key},
+        )
+        data = parse_token_response(self.feishu, response, "tenant_access_token")
+        token = data["tenant_access_token"]
+        if (ttl := _cache_ttl(data["expire"])) > timedelta():
+            yield CacheSet(key, token, ttl)
+        return token
+
+    def token_flow(
+        self, request: httpx2.Request, token_type: TokenType, *, refresh: bool
+    ) -> TokenFlow:
+        if token_type == "tenant":
+            return (yield from self._tenant_token_flow(request, refresh=refresh))
+        return (yield from self._app_token_flow(request, refresh=refresh))
+
+
+@dataclass
+class IsvAppAuthStrategy(_AppCredentialStrategy):
+    """Store application: tokens are derived from the pushed `app_ticket`.
+
+    Pass `app_ticket` directly, or persist each ticket with `save_app_ticket`
+    from the `app_ticket` event handler. Bind a tenant with `as_tenant`.
+    """
+
+    app_id: str
+    app_secret: str = field(repr=False)
+    app_ticket: str | None = field(default=None, repr=False)
+    tenant_key: str | None = None
+
+    def as_tenant(self, tenant_key: str) -> "IsvAppAuthStrategy":
+        """Act on behalf of the tenant that installed the application."""
+        return IsvAppAuthStrategy(
+            self.app_id, self.app_secret, self.app_ticket, tenant_key
+        )
+
+    def _ticket_key(self) -> str:
+        return IsvAppAuth.TICKET_KEY.format(app_id=self.app_id)
+
+    def save_app_ticket(self, feishu: "FeishuCore", app_ticket: str) -> None:
+        cache = feishu.config.cache_strategy.get_cache_storage()
+        cache.set(self._ticket_key(), app_ticket, APP_TICKET_TTL)
+
+    async def async_save_app_ticket(
+        self, feishu: "FeishuCore", app_ticket: str
+    ) -> None:
+        cache = await feishu.config.cache_strategy.get_async_cache_storage()
+        await cache.aset(self._ticket_key(), app_ticket, APP_TICKET_TTL)
+
+    def get_auth_flow(self, feishu: "FeishuCore") -> httpx2.Auth:
+        return IsvAppAuth(
+            feishu, self.app_id, self.app_secret, self.app_ticket, self.tenant_key
+        )

larkify/auth/base.py

@@ -0,0 +1,303 @@
+"""Auth flows, written once and driven from both sync and async clients.
+
+Fetching a token needs network and cache I/O. Those are expressed as steps
+yielded by a plain generator (`FeishuAuth.flow`), and `sync_auth_flow` /
+`async_auth_flow` perform the steps. Strategies therefore never have to
+implement anything twice.
+"""
+
+import abc
+from collections.abc import AsyncGenerator, Callable, Generator
+from datetime import timedelta
+import inspect
+import json
+import threading
+from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, TypeAlias
+
+import anyio
+import httpx2
+
+from larkify.exception import (
+    AuthCredentialError,
+    RateLimitExceeded,
+    RequestFailed,
+)
+from larkify.log import logger
+from larkify.typing import TokenType
+
+if TYPE_CHECKING:
+    from larkify import FeishuCore
+
+# Set on each request by the generated client: the token types the API accepts.
+TOKEN_TYPES_EXTENSION = "larkify.token_types"
+
+# Rejected token, from the generic error code document.
+# https://open.feishu.cn/document/server-docs/api-call-guide/generic-error-code
+TOKEN_REJECTED_CODES = frozenset(
+    {
+        4001,
+        20005,
+        20006,
+        20013,
+        20014,
+        99991661,
+        99991663,
+        99991664,
+        99991665,
+        99991668,
+        99991671,
+        99991677,
+    }
+)
+
+
+class CacheGet(NamedTuple):
+    key: str
+
+
+class CacheSet(NamedTuple):
+    key: str
+    value: str
+    ex: timedelta
+
+
+class CacheDelete(NamedTuple):
+    key: str
+
+
+class LockAcquire(NamedTuple):
+    pass
+
+
+class LockRelease(NamedTuple):
+    pass
+
+
+class CallHook(NamedTuple):
+    func: Callable[..., Any]
+    arg: Any
+
+
+CacheStep: TypeAlias = CacheGet | CacheSet | CacheDelete
+FlowStep: TypeAlias = httpx2.Request | CacheStep | LockAcquire | LockRelease | CallHook
+TokenFlow: TypeAlias = Generator[FlowStep, Any, str]
+AuthFlow: TypeAlias = Generator[FlowStep, Any, None]
+
+
+class Locks:
+    """Serialises token mutation across threads or tasks.
+
+    The two locks are independent: a client is either sync or async, and a
+    thread lock must not be held across an `await`.
+    """
+
+    __slots__ = ("asynchronous", "sync")
+
+    def __init__(self) -> None:
+        self.sync = threading.Lock()
+        self.asynchronous = anyio.Lock()
+
+
+class BaseAuthStrategy(abc.ABC):
+    @abc.abstractmethod
+    def get_auth_flow(self, feishu: "FeishuCore") -> httpx2.Auth:
+        raise NotImplementedError
+
+
+def build_token_request(
+    feishu: "FeishuCore",
+    url: httpx2.URL,
+    *,
+    request: httpx2.Request | None = None,
+    **kwargs: Any,
+) -> httpx2.Request:
+    """Build a request sent from inside an auth flow.
+
+    httpx2 only sets the timeout extension on the request passed to `send`, so it
+    is copied from the request being authenticated.
+    """
+    timeout = (
+        request.extensions.get("timeout") if request is not None else None
+    ) or feishu.config.timeout.as_dict()
+    return httpx2.Request(
+        "POST",
+        url,
+        extensions={"timeout": timeout},
+        headers={"User-Agent": feishu.config.user_agent},
+        **kwargs,
+    )
+
+
+def parse_token_response(
+    feishu: "FeishuCore", response: httpx2.Response, description: str
+) -> dict[str, Any]:
+    """Validate a token endpoint response.
+
+    Rate limiting and server errors stay `RequestFailed` so that the configured
+    retry policy applies. Everything else means the credentials are not usable.
+    """
+    try:
+        return feishu._check(response, Any, data_key=None).json()
+    except RateLimitExceeded:
+        raise
+    except RequestFailed as e:
+        if e.response.status_code >= 500:
+            raise
+        raise AuthCredentialError(
+            f"Failed to obtain {description}: code={e.code}, msg={e.msg!r}, "
+            f"log_id={e.log_id}"
+        ) from e
+
+
+def is_token_rejected(response: httpx2.Response) -> bool:
+    if not response.is_error:
+        return False
+    try:
+        body = json.loads(response.content)
+    except ValueError:
+        return False
+    return isinstance(body, dict) and body.get("code") in TOKEN_REJECTED_CODES
+
+
+class FeishuAuth(httpx2.Auth, abc.ABC):
+    """Authenticate a request with the token type its API accepts."""
+
+    # Token types this auth can produce, preferred first.
+    token_types: ClassVar[tuple[TokenType, ...]]
+
+    feishu: "FeishuCore"
+
+    @property
+    def refreshable(self) -> bool:
+        """Whether a token rejected by the server can be replaced."""
+        return True
+
+    @property
+    def locks(self) -> Locks | None:
+        return None
+
+    @abc.abstractmethod
+    def token_flow(
+        self, request: httpx2.Request, token_type: TokenType, *, refresh: bool
+    ) -> TokenFlow:
+        """Produce a token, replacing the current one if `refresh` is set."""
+        raise NotImplementedError
+
+    def select_token_type(
+        self, allowed: tuple[TokenType, ...] | None
+    ) -> TokenType | None:
+        # None means the API metadata has no information, an empty tuple means
+        # the API takes no token at all (the token endpoints themselves).
+        if allowed is None:
+            return self.token_types[0]
+        if not allowed:
+            return None
+        for token_type in self.token_types:
+            if token_type in allowed:
+                return token_type
+        raise AuthCredentialError(
+            f"This API accepts {', '.join(allowed)} access tokens, which "
+            f"{self.__class__.__name__} cannot provide. "
+            "Use `feishu.with_auth(...)` to switch identity."
+        )
+
+    def flow(self, request: httpx2.Request) -> AuthFlow:
+        token_type = self.select_token_type(
+            request.extensions.get(TOKEN_TYPES_EXTENSION)
+        )
+        if token_type is None:
+            yield request
+            return
+
+        token = yield from self.token_flow(request, token_type, refresh=False)
+        request.headers["Authorization"] = f"Bearer {token}"
+        response = yield request
+
+        # 99991663 and 99991668 also mean "this API does not take that token
+        # type", so a second rejection has to be surfaced instead of looping.
+        if self.refreshable and is_token_rejected(response):
+            logger.debug("%s access token rejected, replacing it", token_type)
+            token = yield from self.token_flow(request, token_type, refresh=True)
+            request.headers["Authorization"] = f"Bearer {token}"
+            yield request
+
+    def sync_auth_flow(
+        self, request: httpx2.Request
+    ) -> Generator[httpx2.Request, httpx2.Response, None]:
+        cache = self.feishu.config.cache_strategy.get_cache_storage()
+        locks = self.locks
+        flow = self.flow(request)
+        held = False
+        try:
+            step = next(flow)
+            while True:
+                result: Any = None
+                if isinstance(step, httpx2.Request):
+                    result = yield step
+                    # Bodies of successful API calls stay unread: they may be
+                    # large file downloads requested with `stream=True`.
+                    if step is not request or result.is_error:
+                        result.read()
+                elif isinstance(step, CacheGet):
+                    result = cache.get(step.key)
+                elif isinstance(step, CacheSet):
+                    cache.set(step.key, step.value, step.ex)
+                elif isinstance(step, CacheDelete):
+                    cache.delete(step.key)
+                elif isinstance(step, LockAcquire):
+                    assert locks is not None
+                    locks.sync.acquire()
+                    held = True
+                elif isinstance(step, LockRelease):
+                    assert locks is not None
+                    locks.sync.release()
+                    held = False
+                else:
+                    step.func(step.arg)
+                step = flow.send(result)
+        except StopIteration:
+            return
+        finally:
+            if held and locks is not None:
+                locks.sync.release()
+
+    async def async_auth_flow(
+        self, request: httpx2.Request
+    ) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        strategy = self.feishu.config.cache_strategy
+        cache = await strategy.get_async_cache_storage()
+        locks = self.locks
+        flow = self.flow(request)
+        held = False
+        try:
+            step = next(flow)
+            while True:
+                result: Any = None
+                if isinstance(step, httpx2.Request):
+                    result = yield step
+                    if step is not request or result.is_error:
+                        await result.aread()
+                elif isinstance(step, CacheGet):
+                    result = await cache.aget(step.key)
+                elif isinstance(step, CacheSet):
+                    await cache.aset(step.key, step.value, step.ex)
+                elif isinstance(step, CacheDelete):
+                    await cache.adelete(step.key)
+                elif isinstance(step, LockAcquire):
+                    assert locks is not None
+                    await locks.asynchronous.acquire()
+                    held = True
+                elif isinstance(step, LockRelease):
+                    assert locks is not None
+                    locks.asynchronous.release()
+                    held = False
+                else:
+                    outcome = step.func(step.arg)
+                    if inspect.isawaitable(outcome):
+                        await outcome
+                step = flow.send(result)
+        except StopIteration:
+            return
+        finally:
+            if held and locks is not None:
+                locks.asynchronous.release()