anafpy 0.1.0__py3-none-any.whl

anafpy/__init__.py

@@ -0,0 +1,25 @@
+"""anafpy — typed Python clients for ANAF e-Factura, e-Transport, and the public
+no-auth services (registries, financial statements)."""
+
+from __future__ import annotations
+
+from .exceptions import (
+    AnafAuthError,
+    AnafConfigError,
+    AnafError,
+    AnafRateLimitError,
+    AnafResponseError,
+    AnafTransportError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnafAuthError",
+    "AnafConfigError",
+    "AnafError",
+    "AnafRateLimitError",
+    "AnafResponseError",
+    "AnafTransportError",
+    "__version__",
+]

anafpy/_transport/__init__.py

@@ -0,0 +1,7 @@
+"""Shared transport layer (environment, per-service base URLs)."""
+
+from __future__ import annotations
+
+from .base import OAUTH_HOST, Environment, Service, service_base_url
+
+__all__ = ["OAUTH_HOST", "Environment", "Service", "service_base_url"]

anafpy/_transport/base.py

@@ -0,0 +1,145 @@
+"""Shared transport concerns: environment, per-service base URLs, error raising.
+
+Both OAuth services are reached on the **same host** ``api.anaf.ro``; they differ
+only by **path prefix** (``/FCTEL/rest`` vs ``/ETRANSPORT/ws/v1``). See
+``docs/anaf-reference/{efactura,etransport}/api.md``.
+
+The unauthenticated public services (registries, financial statements) live on a
+different host, ``webservicesp.anaf.ro``, with **no test/prod split** — so
+:data:`PUBLIC_HOST` sits outside the :func:`service_base_url` scheme. See
+``docs/anaf-reference/public/api.md``.
+
+:func:`raise_for_status` and :func:`as_text` implement the error half of the hybrid
+model shared by all clients: non-success HTTP raises (429 as
+:class:`~anafpy.exceptions.AnafRateLimitError` with ``retry_after``); business
+outcomes are the clients' job to return as values.
+"""
+
+from __future__ import annotations
+
+import time
+import unicodedata
+from email.utils import parsedate_to_datetime
+from enum import StrEnum
+from zoneinfo import ZoneInfo
+
+import httpx
+
+from ..exceptions import AnafRateLimitError, AnafResponseError
+
+__all__ = [
+    "OAUTH_HOST",
+    "PUBLIC_HOST",
+    "ROMANIA_TZ",
+    "Environment",
+    "Service",
+    "as_text",
+    "is_empty_result_message",
+    "raise_for_status",
+    "retry_after_seconds",
+    "service_base_url",
+]
+
+#: ANAF's clock. "Today"/"now" *defaults* (a registry query's as-of date, a vehicle
+#: change's timestamp) are ANAF-semantic values, so they are computed in Romania's
+#: timezone rather than the machine's. Caller-supplied values are never converted.
+ROMANIA_TZ = ZoneInfo("Europe/Bucharest")
+
+#: OAuth2 API host for both services (the cert-direct host ``webserviceapl.anaf.ro`` is
+#: intentionally not used by anafpy).
+OAUTH_HOST = "https://api.anaf.ro"
+
+#: Host of the unauthenticated public services (registries, financial statements).
+#: Production only — ANAF exposes no TEST variant for these.
+PUBLIC_HOST = "https://webservicesp.anaf.ro"
+
+
+class Environment(StrEnum):
+    """ANAF API environment."""
+
+    TEST = "test"
+    PROD = "prod"
+
+
+class Service(StrEnum):
+    """Path prefixes per ANAF service (under the OAuth host)."""
+
+    EFACTURA = "FCTEL/rest"
+    ETRANSPORT = "ETRANSPORT/ws/v1"
+
+
+def service_base_url(service: Service, environment: Environment) -> str:
+    """Return e.g. ``https://api.anaf.ro/test/FCTEL/rest``."""
+    return f"{OAUTH_HOST}/{environment.value}/{service.value}"
+
+
+def retry_after_seconds(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header into seconds.
+
+    RFC 9110 allows either a delay in seconds or an HTTP-date; an unparseable
+    value yields ``None`` rather than masking the rate-limit error it decorates.
+    """
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    try:
+        delay = parsedate_to_datetime(value).timestamp() - time.time()
+    except ValueError:
+        return None
+    return max(delay, 0.0)
+
+
+def as_text(body: bytes) -> str:
+    """Decode a response body for diagnostics (lossy — replacement characters)."""
+    return body.decode("utf-8", errors="replace")
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise the anafpy error for a non-success response; a no-op on success.
+
+    HTTP 429 raises :class:`~anafpy.exceptions.AnafRateLimitError` carrying
+    ``retry_after``; anything else non-success raises
+    :class:`~anafpy.exceptions.AnafResponseError`. No auto-backoff — per the
+    design, the caller decides how to retry.
+    """
+    if response.is_success:
+        return
+    body = as_text(response.content)
+    if response.status_code == httpx.codes.TOO_MANY_REQUESTS:
+        raise AnafRateLimitError(
+            retry_after=retry_after_seconds(response.headers.get("Retry-After")),
+            body=body,
+        )
+    raise AnafResponseError(
+        f"ANAF returned HTTP {response.status_code}",
+        status_code=response.status_code,
+        body=body,
+    )
+
+
+#: Substrings (accent-stripped, casefolded) that mark an ANAF list ``eroare`` as a
+#: benign "no results in this window" note rather than a real fault. ANAF overloads the
+#: same ``eroare`` field for both, so the wording is the only signal; extend as needed.
+_EMPTY_RESULT_MARKERS = (
+    "nu exista mesaje",
+    "nu sunt mesaje",
+    "nu exista facturi",
+    "nu exista notificari",
+    "nu exista inregistrari",
+    "nu exista date",
+    "nu exista informatii",  # e-Transport `info` no-results (live-confirmed 2026-07-02)
+)
+
+
+def is_empty_result_message(text: str) -> bool:
+    """True when an ANAF list ``eroare`` string denotes *no results* (empty window),
+    not a genuine error (bad CIF/interval). Matched accent-insensitively."""
+    normalized = "".join(
+        ch
+        for ch in unicodedata.normalize("NFKD", text)
+        if not unicodedata.combining(ch)
+    ).casefold()
+    return any(marker in normalized for marker in _EMPTY_RESULT_MARKERS)

anafpy/auth/__init__.py

@@ -0,0 +1,25 @@
+"""ANAF OAuth2 authentication: token model, storage, bootstrap, and refresh."""
+
+from __future__ import annotations
+
+from .callback import CallbackListener, capture_authorization_code, parse_redirect_url
+from .models import TokenSet
+from .oauth import build_authorize_url, exchange_code, refresh_tokens
+from .provider import AnafAuth, TokenProvider
+from .store import FileTokenStore, KeyringTokenStore, MemoryTokenStore, TokenStore
+
+__all__ = [
+    "AnafAuth",
+    "CallbackListener",
+    "FileTokenStore",
+    "KeyringTokenStore",
+    "MemoryTokenStore",
+    "TokenProvider",
+    "TokenSet",
+    "TokenStore",
+    "build_authorize_url",
+    "capture_authorization_code",
+    "exchange_code",
+    "parse_redirect_url",
+    "refresh_tokens",
+]

anafpy/auth/callback.py

@@ -0,0 +1,215 @@
+"""Authorization-code capture for the one-time ``auth login`` bootstrap.
+
+ANAF redirects the browser (after the certificate step) to the registered callback URL
+with ``?code=...``. The ANAF developer portal **rejects ``http://`` callback URLs**
+(HTTP 400 at registration — verified 2026-07-02), so the registered URL is ``https://``
+and there are two ways to capture the code:
+
+- **Listener** (:class:`CallbackListener` / ``capture_authorization_code``): a tiny
+  local server on the callback URL's host/port. Plain HTTP by default (put a TLS
+  terminator in front), or pass an ``ssl.SSLContext`` to serve TLS directly with a
+  certificate you supply. The listener **binds on construction** so the browser can be
+  opened only once the port is actually listening — a fast redirect (cached
+  certificate/session) must never outrun the bind.
+- **Paste mode** (``parse_redirect_url``): run no listener at all. The browser lands on
+  a connection error, but the address bar still holds the full redirect URL; the user
+  pastes it (or just the code) into the CLI. Works everywhere, needs no certificate.
+
+Both capture paths take an ``expected_state``: the CLI binds a random OAuth ``state``
+to each login attempt, and a redirect that does not echo it back is rejected (the
+listener answers 400 and keeps waiting) — so a forged redirect cannot inject an
+attacker's authorization code into the flow (login CSRF).
+"""
+
+from __future__ import annotations
+
+import hmac
+import ssl
+import threading
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from ..exceptions import AnafAuthError, AnafConfigError
+
+__all__ = ["CallbackListener", "capture_authorization_code", "parse_redirect_url"]
+
+_PAGE = (
+    b"<!doctype html><meta charset=utf-8><title>anafpy</title>"
+    b"<body style='font-family:sans-serif;padding:2rem'>"
+    b"<h2>%s</h2><p>You can close this tab and return to the terminal.</p>"
+)
+
+
+def _state_matches(received: str, expected: str) -> bool:
+    """Constant-time ``state`` comparison. Compared as bytes:
+    ``hmac.compare_digest`` raises ``TypeError`` on non-ASCII *strings*, and the
+    received value is attacker-influenced."""
+    return hmac.compare_digest(received.encode("utf-8"), expected.encode("utf-8"))
+
+
+def parse_redirect_url(pasted: str, *, expected_state: str | None = None) -> str:
+    """Extract the authorization code from a pasted redirect URL (paste mode).
+
+    Accepts the full redirect URL from the browser address bar, a bare
+    ``code=...&...`` query string, or the code value alone. When
+    ``expected_state`` is given, a pasted URL must echo it back (a bare code —
+    a deliberate manual extraction — is exempt).
+
+    Raises ``AnafAuthError`` on an OAuth error redirect, a ``state`` mismatch,
+    or unrecognizable input.
+    """
+    text = pasted.strip().strip("'\"")
+    if not text:
+        raise AnafAuthError("empty input: paste the full redirect URL from the browser")
+
+    query = urllib.parse.urlparse(text).query
+    if not query and "=" in text:
+        query = text.lstrip("?")
+    if query:
+        params = urllib.parse.parse_qs(query)
+        if expected_state is not None and not _state_matches(
+            params.get("state", [""])[0], expected_state
+        ):
+            raise AnafAuthError(
+                "state mismatch: the pasted URL is not from this login attempt — "
+                "restart `anafpy auth login` and paste the redirect it produces "
+                "(or paste just the code value)"
+            )
+        if "code" in params:
+            return params["code"][0]
+        if "error" in params:
+            raise AnafAuthError(f"authorization failed: {params['error'][0]}")
+        raise AnafAuthError("no `code` parameter in the pasted URL")
+
+    if "/" in text or " " in text:
+        raise AnafAuthError("no `code` parameter in the pasted URL")
+    return text  # the bare code value
+
+
+class CallbackListener:
+    """A bound-and-listening receiver for the OAuth redirect.
+
+    Binding happens in the constructor (raising :class:`AnafConfigError` when the
+    host/port cannot be bound), so callers can open the browser only *after* the
+    listener is provably up, then :meth:`wait` for the redirect. Use as a context
+    manager (or call :meth:`close`) to stop the server.
+
+    When ``expected_state`` is given, only a redirect echoing that OAuth ``state``
+    completes the wait; anything else (a forged redirect trying to inject a code,
+    login CSRF) is answered 400 and the listener keeps waiting for the real one.
+    """
+
+    def __init__(
+        self,
+        redirect_uri: str,
+        *,
+        ssl_context: ssl.SSLContext | None = None,
+        expected_state: str | None = None,
+    ) -> None:
+        parsed = urllib.parse.urlparse(redirect_uri)
+        host = parsed.hostname or "localhost"
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+        expected_path = parsed.path or "/"
+
+        result: dict[str, str] = {}
+        done = threading.Event()
+        self._result = result
+        self._done = done
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, format: str, *args: object) -> None:
+                pass  # silence default request logging
+
+            def do_GET(self) -> None:
+                url = urllib.parse.urlparse(self.path)
+                if url.path != expected_path:
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                query = urllib.parse.parse_qs(url.query)
+                if expected_state is not None and not _state_matches(
+                    query.get("state", [""])[0], expected_state
+                ):
+                    # Not this login attempt's redirect: refuse it and keep
+                    # waiting for the one carrying our state.
+                    self.send_response(400)
+                    self.end_headers()
+                    return
+                if "code" in query:
+                    result["code"] = query["code"][0]
+                    msg = b"Authorization received."
+                else:
+                    result["error"] = query.get("error", ["unknown_error"])[0]
+                    msg = b"Authorization failed."
+                # The outcome is captured; release the waiter even if the browser
+                # drops the connection before the response page is written.
+                try:
+                    self.send_response(200)
+                    self.send_header("Content-Type", "text/html; charset=utf-8")
+                    self.end_headers()
+                    self.wfile.write(_PAGE % msg)
+                finally:
+                    done.set()
+
+        try:
+            self._server = ThreadingHTTPServer((host, port), Handler)
+            if ssl_context is not None:
+                self._server.socket = ssl_context.wrap_socket(
+                    self._server.socket, server_side=True
+                )
+        except OSError as exc:
+            raise AnafConfigError(
+                f"cannot bind callback listener on {host}:{port}: {exc}"
+            ) from exc
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def __enter__(self) -> CallbackListener:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def wait(self, timeout: float = 180.0) -> str | None:
+        """Block until the redirect arrives; the code, or ``None`` on timeout.
+
+        Raises ``AnafAuthError`` on an OAuth error redirect.
+        """
+        if not self._done.wait(timeout):
+            return None
+        if "error" in self._result:
+            raise AnafAuthError(f"authorization failed: {self._result['error']}")
+        return self._result["code"]
+
+    def close(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+
+
+def capture_authorization_code(
+    redirect_uri: str,
+    *,
+    timeout: float = 180.0,
+    ssl_context: ssl.SSLContext | None = None,
+    expected_state: str | None = None,
+) -> str:
+    """Block until ANAF redirects to ``redirect_uri`` with a code; return that code.
+
+    Bind-and-wait in one call, for callers that already opened the browser (prefer
+    :class:`CallbackListener` to bind *before* opening it). Plain HTTP unless
+    ``ssl_context`` is given, in which case it serves TLS with that context (use
+    this when the browser must reach the callback over ``https://`` and no
+    external TLS terminator is in front). ``expected_state`` is enforced as in
+    :class:`CallbackListener`.
+
+    Raises ``AnafAuthError`` on an OAuth error redirect or on timeout.
+    """
+    with CallbackListener(
+        redirect_uri, ssl_context=ssl_context, expected_state=expected_state
+    ) as listener:
+        code = listener.wait(timeout)
+    if code is None:
+        raise AnafAuthError(
+            f"timed out waiting for the OAuth callback ({timeout:.0f}s)"
+        )
+    return code

anafpy/auth/models.py

@@ -0,0 +1,94 @@
+"""Token model.
+
+ANAF access tokens are JWTs valid 90 days; refresh tokens 365 days. Refresh **rotates**
+the refresh token (a new access *and* refresh token come back), so both are persisted.
+Expiry timestamps are **computed from the JWTs themselves** (cached per instance), so
+the persisted store can never drift from the tokens it holds.
+"""
+
+from __future__ import annotations
+
+import time
+from functools import cached_property
+from typing import Any
+
+import jwt
+from pydantic import BaseModel, Field, computed_field
+
+__all__ = ["TokenSet"]
+
+# Fallback lifetimes (s) if a JWT `exp` can't be read. Source: official OAuth PDF.
+_ACCESS_TTL = 90 * 24 * 3600
+_REFRESH_TTL = 365 * 24 * 3600
+
+
+def _jwt_exp(token: str) -> float | None:
+    """Best-effort read of a JWT's ``exp`` claim (epoch seconds), without verifying.
+
+    Signature verification is ANAF's job server-side; here we only read ``exp`` to
+    schedule refresh. Returns ``None`` for non-JWT or unparseable tokens.
+    """
+    try:
+        payload = jwt.decode(token, options={"verify_signature": False})
+    except jwt.InvalidTokenError:
+        return None
+    exp = payload.get("exp")
+    return float(exp) if isinstance(exp, (int, float)) else None
+
+
+class TokenSet(BaseModel):
+    """An access/refresh token pair; expiries are derived from the JWT ``exp`` claims.
+
+    Instances are treated as immutable: refresh rotation builds a *new* ``TokenSet``
+    via :meth:`from_token_response`, which is what makes the cached expiry properties
+    safe.
+    """
+
+    access_token: str
+    refresh_token: str
+    token_type: str = "Bearer"
+    obtained_at: float = Field(default_factory=time.time)
+    # Lifetime (s) from the token response, used only if the access JWT has no `exp`.
+    expires_in: float | None = None
+
+    # Computed expiries are serialized into the store (for human inspection) but
+    # ignored on load. The `type: ignore`s are pydantic's documented workaround for
+    # mypy's blanket "decorators on top of @property" limitation.
+    @computed_field  # type: ignore[prop-decorator]
+    @cached_property
+    def access_expires_at(self) -> float:
+        """Access expiry (epoch s): JWT ``exp``, else ``expires_in``, else 90 days."""
+        exp = _jwt_exp(self.access_token)
+        if exp is not None:
+            return exp
+        if self.expires_in:
+            return self.obtained_at + self.expires_in
+        return self.obtained_at + _ACCESS_TTL
+
+    @computed_field  # type: ignore[prop-decorator]
+    @cached_property
+    def refresh_expires_at(self) -> float:
+        """Refresh expiry (epoch s): JWT ``exp``, else the documented 365 days."""
+        return _jwt_exp(self.refresh_token) or (self.obtained_at + _REFRESH_TTL)
+
+    @classmethod
+    def from_token_response(
+        cls, data: dict[str, Any], *, obtained_at: float | None = None
+    ) -> TokenSet:
+        """Build from ANAF's JSON token response (`access_token`, `refresh_token`)."""
+        expires_in = data.get("expires_in")
+        return cls(
+            access_token=str(data["access_token"]),
+            refresh_token=str(data["refresh_token"]),
+            token_type=str(data.get("token_type", "Bearer")),
+            obtained_at=obtained_at if obtained_at is not None else time.time(),
+            expires_in=float(expires_in) if expires_in else None,
+        )
+
+    def access_expired(self, *, leeway: float = 300.0) -> bool:
+        """True if the access token is expired (or within ``leeway`` seconds of it)."""
+        return time.time() >= (self.access_expires_at - leeway)
+
+    def refresh_expired(self) -> bool:
+        """True if the refresh token has likely expired (re-auth required)."""
+        return time.time() >= self.refresh_expires_at

anafpy/auth/oauth.py

@@ -0,0 +1,119 @@
+"""ANAF OAuth2 endpoints and operations.
+
+Verified against the official OAuth procedure PDF and a live probe (2026-06-28):
+client auth is **HTTP Basic** (client_id:client_secret); ``token_content_type`` is
+``jwt`` (query for /authorize, body for /token); refresh is **headless** (no
+certificate). See ``docs/anaf-reference/oauth/authentication.md``.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+
+import httpx
+
+from ..exceptions import AnafAuthError, AnafTransportError
+from .models import TokenSet
+
+__all__ = [
+    "AUTHORIZE_URL",
+    "REVOKE_URL",
+    "TOKEN_URL",
+    "build_authorize_url",
+    "exchange_code",
+    "refresh_tokens",
+]
+
+AUTHORIZE_URL = "https://logincert.anaf.ro/anaf-oauth2/v1/authorize"
+TOKEN_URL = "https://logincert.anaf.ro/anaf-oauth2/v1/token"
+#: Documented by ANAF's PDF but NOT reachable headlessly (live-probed 2026-07-05:
+#: a client-secret-authenticated POST gets the F5 APM login-wall redirect, identical
+#: to a nonexistent path). Kept as a documented fact; nothing in anafpy calls it.
+REVOKE_URL = "https://logincert.anaf.ro/anaf-oauth2/v1/revoke"
+
+
+def build_authorize_url(
+    client_id: str, redirect_uri: str, *, state: str | None = None
+) -> str:
+    """Build the browser authorization URL (the cert step happens here)."""
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "token_content_type": "jwt",
+    }
+    if state is not None:
+        params["state"] = state
+    return f"{AUTHORIZE_URL}?{urllib.parse.urlencode(params)}"
+
+
+async def _post_token(
+    http: httpx.AsyncClient,
+    client_id: str,
+    client_secret: str,
+    data: dict[str, str],
+) -> TokenSet:
+    data = {**data, "token_content_type": "jwt"}
+    try:
+        resp = await http.post(
+            TOKEN_URL,
+            data=data,
+            auth=httpx.BasicAuth(client_id, client_secret),
+            headers={"Accept": "application/json"},
+        )
+    except httpx.HTTPError as exc:  # connection/timeout
+        raise AnafTransportError(f"token request failed: {exc}") from exc
+
+    if resp.status_code != httpx.codes.OK:
+        # ANAF returns OAuth error JSON, e.g. {"error":"invalid_grant", ...}.
+        detail = resp.text
+        try:
+            payload = resp.json()
+            detail = payload.get("error_description") or payload.get("error") or detail
+        except ValueError:
+            pass
+        raise AnafAuthError(
+            f"token endpoint returned HTTP {resp.status_code}: {detail}"
+        )
+
+    return TokenSet.from_token_response(resp.json())
+
+
+async def exchange_code(
+    http: httpx.AsyncClient,
+    *,
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str,
+) -> TokenSet:
+    """Exchange an authorization ``code`` for a token set (no certificate needed)."""
+    return await _post_token(
+        http,
+        client_id,
+        client_secret,
+        {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+        },
+    )
+
+
+async def refresh_tokens(
+    http: httpx.AsyncClient,
+    *,
+    client_id: str,
+    client_secret: str,
+    refresh_token: str,
+) -> TokenSet:
+    """Get a fresh token set from a refresh token (headless; rotates refresh token)."""
+    return await _post_token(
+        http,
+        client_id,
+        client_secret,
+        {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        },
+    )