booking-agent-cli 0.1.0__py3-none-any.whl

booking_agent/__init__.py

@@ -0,0 +1,6 @@
+"""booking_agent: USP protocol models, profile discovery, REST client, and backends.
+
+Ships in the booking-agent-cli wheel and never imports ``booking_agent_cli``.
+"""
+
+__version__ = "0.1.0"

booking_agent/authorization.py

@@ -0,0 +1,450 @@
+"""``AuthorizationPolicy`` parsing and mechanism selection (USP Section 10.1.6).
+
+USP splits operations into two tiers.  *Public* operations -- catalog,
+availability, profile discovery -- MAY remain anonymous.  *Privileged*
+operations -- creating, updating, confirming, cancelling or rescheduling a
+booking, holds, waitlist mutations, payment-adjacent completion, registry
+writes, and any response carrying buyer personal data -- MUST be authenticated.
+A resource identifier is not a credential.
+
+The *mechanism* is business-declared: the business publishes an
+``AuthorizationPolicy`` and the platform selects one it supports.  Two rules
+make that safe, and both are easy to get backwards:
+
+* Unrecognized mechanisms are **ignored, never treated as accepted**.  A client
+  that shrugged and continued anonymously against a policy it did not
+  understand would defeat the whole tier split.
+* Where the policy is missing or nothing is mutually supported, the client
+  **fails closed** rather than falling back to anonymous.
+
+Placement differs by deployment mode:
+
+* **Standalone** -- top-level ``authorization`` in ``/.well-known/usp``.
+* **UCP-Native** -- ``config.authorization`` on the ``dev.usp-protocol.services``
+  binding.  A binding carrying ``authorization`` as a *direct member* is
+  malformed: ``schemas/usp.json`` gives it a never-satisfiable schema so that it
+  is rejected rather than silently accepted, which would let a business believe
+  it had published a policy no conforming consumer reads.  We therefore treat
+  that shape as *no policy published* and fail closed -- we do not read it.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from . import settings
+
+logger = logging.getLogger(__name__)
+
+#: USP Section 10.1.6 mechanism identifiers this client can actually satisfy.
+#: ``platform_key_pop`` is the only one implemented; the rest are recognized so
+#: that diagnostics can say *why* a business is unreachable.
+MECHANISM_PLATFORM_KEY_POP = "platform_key_pop"
+MECHANISM_BOOKING_SCOPED_CREDENTIAL = "booking_scoped_credential"
+MECHANISM_OAUTH2_BEARER = "oauth2_bearer"
+MECHANISM_API_KEY = "api_key"
+MECHANISM_HTTP_MESSAGE_SIGNATURE = "http_message_signature"
+MECHANISM_MTLS = "mtls"
+
+#: Ordered by preference.  Only the first is implemented in this version;
+#: ``oauth2_bearer`` support is dormant (see ``oauth_dormant``) and gated on #199.
+SUPPORTED_MECHANISMS: tuple[str, ...] = (MECHANISM_PLATFORM_KEY_POP,)
+
+
+class AuthorizationError(Exception):
+    """Base class for fail-closed authorization outcomes."""
+
+
+#: USP Section 10.1.1 error codes relating to proofs.  Note the ``pop_`` prefix: an
+#: earlier draft of the client checklist called the replay code ``proof_replayed``,
+#: which matches nothing on the wire.
+ERR_POP_PROOF_MISSING = "pop_proof_missing"
+ERR_POP_PROOF_INVALID = "pop_proof_invalid"
+ERR_POP_KEY_MISMATCH = "pop_key_mismatch"
+ERR_POP_PROOF_REPLAYED = "pop_proof_replayed"
+ERR_PROOF_NONCE_REQUIRED = "proof_nonce_required"
+
+#: All 401, and all terminal for the caller except the nonce challenge, which is
+#: a single-round-trip negotiation rather than a failure.
+POP_ERROR_CODES = frozenset({
+    ERR_POP_PROOF_MISSING,
+    ERR_POP_PROOF_INVALID,
+    ERR_POP_KEY_MISMATCH,
+    ERR_POP_PROOF_REPLAYED,
+    ERR_PROOF_NONCE_REQUIRED,
+})
+
+
+def nonce_from_pop_error_body(payload: Dict[str, Any]) -> Optional[str]:
+    """Return a proof nonce from a USP error object (MCP and REST 401 fallback).
+
+    MCP has no HTTP headers, so the MCP binding carries the nonce in
+    ``error.data.nonce`` when ``error.code`` is ``proof_nonce_required``.  REST
+    prefers the ``DPoP-Nonce`` header; this parser is the fallback when the
+    header is absent on a 401.
+    """
+    if payload.get("code") != ERR_PROOF_NONCE_REQUIRED:
+        return None
+    data = payload.get("data")
+    nonce = data.get("nonce") if isinstance(data, dict) else None
+    return nonce if isinstance(nonce, str) and nonce else None
+
+
+class AuthorizationRefused(AuthorizationError):
+    """The client refuses to perform a privileged operation against this business."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+class AuthorizationPolicy(BaseModel):
+    """``schemas/profile.json#/$defs/AuthorizationPolicy``.
+
+    Both members are REQUIRED by the schema.  The object is deliberately open
+    (``additionalProperties: true``) -- accepted proof algorithms and similar
+    extensions are advertised through it -- so unknown members are preserved
+    rather than dropped.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    privileged_operations_require_authentication: bool
+    accepted_mechanisms: List[str]
+    token_endpoint: Optional[str] = None
+
+    def select_mechanism(self) -> Optional[str]:
+        """Return the best mutually supported mechanism, or None.
+
+        Unrecognized identifiers in ``accepted_mechanisms`` are skipped, never
+        assumed acceptable.
+        """
+        for candidate in SUPPORTED_MECHANISMS:
+            if candidate in self.accepted_mechanisms:
+                return candidate
+        return None
+
+
+def parse_policy(raw: Any) -> Optional[AuthorizationPolicy]:
+    """Parse an ``authorization`` object, or return None when absent/malformed.
+
+    A malformed policy is reported as *absent* rather than raising, so the
+    caller reaches the same fail-closed path as a business that published
+    nothing -- the distinction matters for the log line, not for the decision.
+    """
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        logger.warning("Ignoring non-object authorization policy of type %s", type(raw).__name__)
+        return None
+    try:
+        return AuthorizationPolicy.model_validate(raw)
+    except Exception:
+        logger.warning("Ignoring malformed authorization policy: %r", raw, exc_info=True)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# The issued credential
+# ---------------------------------------------------------------------------
+
+class ConfirmationKey(BaseModel):
+    """``schemas/usp.json#/$defs/ConfirmationKey`` -- the RFC 7800 ``cnf`` claim.
+
+    Restricted to the JWK-thumbprint form; the embedded-key and key-reference
+    forms are not used by USP.  ``extra="forbid"`` is load-bearing: ignoring an
+    unrecognized confirmation method would silently downgrade a
+    sender-constrained credential to a bearer token, so the Section 10.1.6
+    forward-compatibility rule deliberately does NOT extend to this object.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    jkt: str
+
+    @field_validator("jkt")
+    @classmethod
+    def _check_thumbprint(cls, v: str) -> str:
+        if not _JKT_RE.fullmatch(v):
+            raise ValueError(
+                "jkt must be an unpadded base64url SHA-256 thumbprint of exactly 43 characters"
+            )
+        return v
+
+
+class BookingScopedCredential(BaseModel):
+    """``schemas/profile.json#/$defs/BookingScopedCredential``.
+
+    Returned on a creation response only, never on reads, and authorizing
+    continuation operations on exactly one booking or waitlist entry.  Also a
+    **closed** object for the same reason as ``ConfirmationKey``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: str
+    expires_at: datetime
+    cnf: Optional[ConfirmationKey] = None
+    #: USP method names this credential authorizes on its resource.  Absent means
+    #: the full continuation set for the resource type -- never another resource.
+    scope: Optional[List[str]] = None
+
+    @field_validator("value")
+    @classmethod
+    def _check_value(cls, v: str) -> str:
+        if not v.startswith("bsc_") or len(v) < 26:
+            raise ValueError("credential value must start with 'bsc_' and be at least 26 characters")
+        return v
+
+    @property
+    def is_sender_constrained(self) -> bool:
+        return self.cnf is not None
+
+    def is_expired(self, *, now: Optional[datetime] = None) -> bool:
+        current = now or datetime.now(timezone.utc)
+        expires = self.expires_at
+        if expires.tzinfo is None:
+            expires = expires.replace(tzinfo=timezone.utc)
+        return expires <= current
+
+    def covers(self, usp_method: str) -> bool:
+        return self.scope is None or usp_method in self.scope
+
+
+_JKT_RE = re.compile(r"[A-Za-z0-9_-]{43}")
+
+
+class CredentialBindingError(AuthorizationError):
+    """The business issued a credential that is not bound to our key."""
+
+
+def issued_credential_payload(data: Dict[str, Any]) -> Any:
+    """Locate ``booking_scoped_credential`` on a creation response.
+
+    Standalone USP returns it at the body root. UCP-Native paid bookings return
+    it as a sibling of ``booking`` at the checkout root, or inside the
+    ``dev.usp-protocol.services.paid_bookings`` extension. Creation is the only
+    place the value appears.
+    """
+    from .namespace import CAP_PAID_BOOKINGS
+
+    if not isinstance(data, dict):
+        return None
+    payload = data.get("booking_scoped_credential")
+    if payload is not None:
+        return payload
+    extension = data.get(CAP_PAID_BOOKINGS)
+    if isinstance(extension, dict):
+        return extension.get("booking_scoped_credential")
+    return None
+
+
+def parse_issued_credential(
+    payload: Any, *, own_jkt: str, required: bool,
+) -> Optional[BookingScopedCredential]:
+    """Parse and verify a ``booking_scoped_credential`` from a creation response.
+
+    Verifies ``cnf.jkt`` against *own_jkt*: this detects a business that accepted
+    the proof and then issued a credential bound to something else, or to
+    nothing.  A credential returned without ``cnf`` MUST NOT be treated as
+    sender-constrained -- when we authenticated with ``platform_key_pop``
+    (*required*), that is a protocol violation rather than a soft downgrade,
+    because continuing would hand a plain bearer secret to a caller that
+    believes it holds a bound one.
+    """
+    if payload is None:
+        return None
+    try:
+        credential = BookingScopedCredential.model_validate(payload)
+    except Exception as exc:
+        raise CredentialBindingError(
+            f"business returned a malformed booking_scoped_credential: {exc}"
+        ) from exc
+
+    if credential.cnf is None:
+        if required:
+            raise CredentialBindingError(
+                "business issued a booking_scoped_credential with no 'cnf' after a "
+                "platform_key_pop request; refusing to treat an unbound credential as "
+                "sender-constrained."
+            )
+        return credential
+
+    if credential.cnf.jkt != own_jkt:
+        raise CredentialBindingError(
+            f"business bound the credential to jkt {credential.cnf.jkt!r}, which is not "
+            f"this agent's key ({own_jkt!r}); the credential would be unusable."
+        )
+    return credential
+
+
+# ---------------------------------------------------------------------------
+# Deployment posture
+# ---------------------------------------------------------------------------
+
+class ScopedCredentialPosture(str, Enum):
+    """How strictly to enforce the Section 10.1.6 privileged-operation floor.
+
+    ``REQUIRED`` is both the conformant posture and the default.  USP is
+    unambiguous that privileged operations MUST be authenticated and that a
+    consumer fails closed rather than falling back to anonymous, so shipping a
+    laxer default would be shipping a known deviation.
+
+    Under ``REQUIRED``, privileged calls to a business that publishes no
+    ``authorization`` policy, or declares privileged operations unauthenticated,
+    are refused: an unauthenticated booking is exactly what the mechanism exists
+    to prevent.
+
+    ``PREFERRED`` is for a deployment that chooses to transact with such a
+    business anyway: the same cases log a warning and proceed instead of refusing.
+    """
+
+    REQUIRED = "required"
+    PREFERRED = "preferred"
+
+
+DEFAULT_POSTURE = ScopedCredentialPosture.REQUIRED
+
+#: Precedence: explicit config -> environment -> default.
+POSTURE_ENV_VAR = "BOOKING_AGENT_USP_AUTH_SCOPED_CREDENTIAL"
+
+
+def resolve_posture(explicit: Optional[str] = None) -> ScopedCredentialPosture:
+    raw = explicit or settings.get(POSTURE_ENV_VAR)
+    if not raw:
+        return DEFAULT_POSTURE
+    try:
+        return ScopedCredentialPosture(raw.strip().lower())
+    except ValueError:
+        logger.warning(
+            "Unknown %s=%r; falling back to %s",
+            POSTURE_ENV_VAR, raw, DEFAULT_POSTURE.value,
+        )
+        return DEFAULT_POSTURE
+
+
+# ---------------------------------------------------------------------------
+# Decision
+# ---------------------------------------------------------------------------
+
+class AuthorizationDecision(BaseModel):
+    """What the client will do for privileged operations against one business."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mechanism: Optional[str] = None
+    #: True when privileged requests should carry a proof.
+    authenticate: bool = False
+    #: Set when proceeding unauthenticated under a non-conformant posture.
+    warning: Optional[str] = None
+    #: Set when this business cannot be transacted with under the current
+    #: posture.  Carried rather than raised so the refusal lands on the
+    #: privileged call that is actually forbidden -- see ``raise_if_refused``.
+    refusal_code: Optional[str] = None
+    refusal_message: Optional[str] = None
+
+    @property
+    def uses_pop(self) -> bool:
+        return self.mechanism == MECHANISM_PLATFORM_KEY_POP
+
+    @property
+    def refused(self) -> bool:
+        return self.refusal_code is not None
+
+    def raise_if_refused(self) -> None:
+        """Enforce the refusal. Call this on privileged operations only.
+
+        Public operations -- catalog, availability, profile discovery -- MAY
+        remain unauthenticated under USP Section 10.1.6, so a business that publishes
+        no usable policy is still browsable.  Refusing at client construction
+        would block those too, which is both non-conformant and needlessly
+        unhelpful: the agent could not even show the user what it cannot book.
+        """
+        if self.refusal_code is not None:
+            raise AuthorizationRefused(self.refusal_code, self.refusal_message or "")
+
+
+def evaluate(
+    policy: Optional[AuthorizationPolicy],
+    *,
+    posture: ScopedCredentialPosture,
+    exposes_privileged_capabilities: bool = True,
+    business_label: str = "business",
+    defer: bool = False,
+) -> AuthorizationDecision:
+    """Decide how to authenticate privileged operations against one business.
+
+    Raises ``AuthorizationRefused`` on every fail-closed path, unless *defer* is
+    set -- in which case the refusal is returned on the decision and enforced
+    later by ``AuthorizationDecision.raise_if_refused``.  Callers that build a
+    client used for public operations too must defer, or browsing a business
+    would fail for want of an authorization policy it does not need.
+    """
+    if policy is None:
+        if not exposes_privileged_capabilities:
+            return AuthorizationDecision(mechanism=None, authenticate=False)
+        return _refuse_or_warn(
+            posture,
+            defer=defer,
+            code="authorization_policy_absent",
+            message=(
+                f"{business_label} exposes privileged capabilities but publishes no "
+                f"authorization policy, so there is no mechanism to negotiate."
+            ),
+        )
+
+    if not policy.privileged_operations_require_authentication:
+        # Section 10.1.6: publishing false declares the deployment OUT OF CONFORMANCE
+        # for privileged operations.  The platform MUST refuse to transact real
+        # bookings or transmit buyer personal data -- refuse, not warn and continue.
+        return _refuse_or_warn(
+            posture,
+            defer=defer,
+            code="privileged_operations_unauthenticated",
+            message=(
+                f"{business_label} publishes "
+                f"privileged_operations_require_authentication=false, declaring itself "
+                f"out of conformance for privileged operations. Refusing to transact "
+                f"real bookings or send buyer personal data."
+            ),
+        )
+
+    mechanism = policy.select_mechanism()
+    if mechanism is None:
+        return _refuse_or_warn(
+            posture,
+            defer=defer,
+            code="no_supported_mechanism",
+            message=(
+                f"{business_label} accepts {policy.accepted_mechanisms!r}, none of which "
+                f"this client supports (supported: {list(SUPPORTED_MECHANISMS)!r})."
+            ),
+        )
+
+    return AuthorizationDecision(mechanism=mechanism, authenticate=True)
+
+
+def _refuse_or_warn(
+    posture: ScopedCredentialPosture, *, code: str, message: str, defer: bool = False,
+) -> AuthorizationDecision:
+    if posture is ScopedCredentialPosture.REQUIRED:
+        if defer:
+            return AuthorizationDecision(
+                mechanism=None,
+                authenticate=False,
+                refusal_code=code,
+                refusal_message=message,
+            )
+        raise AuthorizationRefused(code, message)
+    logger.warning(
+        "%s Proceeding unauthenticated because %s=%s; this is not a conformant "
+        "configuration and privileged calls may be rejected.",
+        message, POSTURE_ENV_VAR, posture.value,
+    )
+    return AuthorizationDecision(mechanism=None, authenticate=False, warning=message)

booking_agent/backend/__init__.py

@@ -0,0 +1,217 @@
+"""USP Backend abstraction layer.
+
+Single interface (USPBackend) for all USP operations — registry search,
+profile resolution, catalog, availability, and booking. The product
+implementation is booking_agent.backend.live.LiveUSPBackend; tests inject
+their own.
+"""
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta, timezone
+
+
+def _parse_iso(s: str) -> datetime:
+    """Parse an ISO8601 datetime string, handling the Z suffix for Python 3.10."""
+    return datetime.fromisoformat(s.replace("Z", "+00:00"))
+
+from typing import Any, Dict, List, Optional
+
+from ..authorization import BookingScopedCredential
+from ..discovery import USPBusinessProfile
+from ..models.platform import ServiceSearchIntent
+from ..models.wire import (
+    Booking,
+    Hold,
+    TimeSlot,
+    USPPaymentResult,
+    USPService,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class USPBackend(ABC):
+    """Strategy interface for all USP operations."""
+
+    #: Set by the resource-creating operations (``hold_slot``, ``create_booking``)
+    #: to the ``booking_scoped_credential`` the business issued, already verified
+    #: against this agent's key.  Read it immediately after the call: creation
+    #: responses are the only place a credential ever appears, and the next
+    #: creation overwrites it.  ``None`` when the business issued none.
+    last_issued_credential: Optional[BookingScopedCredential] = None
+
+    # -- Registry-level (service discovery) ----------------------------------
+
+    @abstractmethod
+    async def search_registry(self, intent: ServiceSearchIntent) -> List[USPService]: ...
+
+    # -- Discovery (profile resolution) --------------------------------------
+
+    @abstractmethod
+    async def resolve_profile(self, usp_profile_url: str) -> USPBusinessProfile: ...
+
+    @abstractmethod
+    async def resolve_profile_from_agent_card(
+        self, agent_card_url: str
+    ) -> USPBusinessProfile: ...
+
+    # -- Business-level (catalog) --------------------------------------------
+
+    @abstractmethod
+    async def list_services(
+        self,
+        profile: USPBusinessProfile,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[USPService]: ...
+
+    @abstractmethod
+    async def get_service(
+        self, profile: USPBusinessProfile, service_id: str
+    ) -> USPService: ...
+
+    # -- Business-level (availability) ---------------------------------------
+
+    @abstractmethod
+    async def query_availability(
+        self,
+        profile: USPBusinessProfile,
+        service_id: str,
+        start_date: str,
+        end_date: str,
+        timezone: Optional[str] = None,
+    ) -> List[TimeSlot]:
+        """Slots for the window. ``timezone`` is sent as ``date_bounds_timezone``.
+
+        Live backends return an ``AvailabilityResult`` carrying the response's
+        ``business_timezone`` and ``applied_date_bounds_timezone``.
+        """
+
+    async def find_next_available(
+        self,
+        profile: USPBusinessProfile,
+        service_id: str,
+        after_date: str,
+        max_days: int = 30,
+        timezone_str: Optional[str] = None,
+    ) -> Optional[str]:
+        try:
+            base = _parse_iso(after_date).date()
+        except (ValueError, TypeError):
+            base = datetime.now(timezone.utc).date()
+        start_day = base + timedelta(days=1)
+        end_day = base + timedelta(days=max_days)
+        try:
+            slots = await self.query_availability(
+                profile, service_id,
+                f"{start_day.isoformat()}T00:00:00Z",
+                f"{end_day.isoformat()}T23:59:59Z",
+                timezone_str,
+            )
+        except Exception:
+            logger.debug("find_next_available: query failed for %s", service_id)
+            return None
+        if not slots:
+            return None
+        earliest = min(slots, key=lambda s: s.start)
+        return _parse_iso(earliest.start).date().isoformat()
+
+    @abstractmethod
+    async def hold_slot(
+        self,
+        profile: USPBusinessProfile,
+        slot_id: str,
+        service_id: str,
+        spots: int = 1,
+    ) -> Hold: ...
+
+    @abstractmethod
+    async def release_hold(
+        self,
+        profile: USPBusinessProfile,
+        hold_id: str,
+        *,
+        credential: Optional[BookingScopedCredential] = None,
+    ) -> dict: ...
+
+    # -- Business-level (booking) --------------------------------------------
+
+    @abstractmethod
+    async def create_booking(
+        self,
+        profile: USPBusinessProfile,
+        service_id: str,
+        slot_id: str,
+        buyer: Dict[str, Any],
+        party_size: int = 1,
+        resource_id: Optional[str] = None,
+        notes: Optional[str] = None,
+        delivery_address: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Booking: ...
+
+    @abstractmethod
+    async def get_booking(
+        self,
+        profile: USPBusinessProfile,
+        booking_id: str,
+        *,
+        credential: Optional[BookingScopedCredential] = None,
+        credential_endpoint: Optional[str] = None,
+    ) -> Booking: ...
+
+    @abstractmethod
+    async def cancel_booking(
+        self,
+        profile: USPBusinessProfile,
+        booking_id: str,
+        reason: Optional[str] = None,
+        *,
+        credential: Optional[BookingScopedCredential] = None,
+        credential_endpoint: Optional[str] = None,
+        if_match: Optional[str] = None,
+    ) -> Booking: ...
+
+    @abstractmethod
+    async def reschedule_booking(
+        self,
+        profile: USPBusinessProfile,
+        booking_id: str,
+        new_slot_id: str,
+        *,
+        credential: Optional[BookingScopedCredential] = None,
+        credential_endpoint: Optional[str] = None,
+        if_match: Optional[str] = None,
+    ) -> Booking: ...
+
+    @abstractmethod
+    async def confirm_payment(
+        self,
+        profile: USPBusinessProfile,
+        booking_id: str,
+        payment_result: USPPaymentResult,
+        *,
+        credential: Optional[BookingScopedCredential] = None,
+        if_match: Optional[str] = None,
+    ) -> Booking: ...
+
+
+def get_usp_backend() -> USPBackend:
+    from .live import LiveUSPBackend
+    return LiveUSPBackend()
+
+
+# ISO 4217 minor unit exponent. Default 2.
+CURRENCY_MINOR_UNITS = {
+    "BIF": 0, "CLP": 0, "DJF": 0, "GNF": 0, "ISK": 0, "JPY": 0, "KMF": 0,
+    "KRW": 0, "PYG": 0, "RWF": 0, "UGX": 0, "UYI": 0, "VND": 0, "VUV": 0,
+    "XAF": 0, "XOF": 0, "XPF": 0,
+    "BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "LYD": 3, "OMR": 3, "TND": 3,
+    "CLF": 4, "UYW": 4,
+}
+
+CURRENCY_SYMBOLS = {"USD": "$", "EUR": "€", "GBP": "£", "JPY": "¥", "KRW": "₩"}
+
+
+def minor_to_decimal(amount: int, currency: str) -> float:
+    exponent = CURRENCY_MINOR_UNITS.get(currency.upper(), 2)
+    return amount / (10 ** exponent)