mxgate 0.3.0__py3-none-any.whl

mxgate/types.py

@@ -0,0 +1,547 @@
+"""The shapes of the API answers, from `components.schemas` of the OpenAPI document.
+
+These are `TypedDict` definitions: at run time each answer is a plain `dict`.
+A field that is not in every answer is in a `total=False` class.
+"""
+
+from typing import Dict, List, Literal, Optional, TypedDict
+
+Plan = Literal["free", "paid"]
+AccountStatus = Literal["active", "warned", "suspended"]
+BillingInterval = Literal["month", "year"]
+CheckResult = Literal["ok", "warn", "fail"]
+LogDirection = Literal["in", "out"]
+LogStatus = Literal["forwarded", "sent", "deferred", "bounced", "expired", "rejected"]
+NotificationEvent = Literal["bounced", "expired", "rejected", "deferred"]
+WebhookStatus = Literal["none", "pending", "delivered", "failed"]
+StatusState = Literal["operational", "degraded", "outage", "unknown"]
+
+
+class _ErrorBodyRequired(TypedDict):
+    error: str
+    message: str
+
+
+class ErrorBody(_ErrorBodyRequired, total=False):
+    """Every error body. Switch on `error`; show `message` to a person; `fix` is the next step."""
+
+    fix: str
+    upgrade_url: str
+    retry_after_seconds: int
+
+
+class _IndexRequired(TypedDict):
+    name: str
+    version: str
+    about: str
+    docs: str
+    reference: str
+    openapi: str
+    auth: str
+    flow: List[str]
+    endpoints: Dict[str, str]
+    mx_hosts: List[str]
+
+
+class Index(_IndexRequired, total=False):
+    """The answer to GET /: what the service is and what it has."""
+
+    mcp: str
+    sign_in: List[str]
+
+
+class Limits(TypedDict):
+    """The limits of the plan. None means no limit."""
+
+    domains: Optional[int]
+    aliases_per_domain: Optional[int]
+    destinations_per_alias: int
+    send_per_day: Optional[int]
+    send_per_month: Optional[int]
+
+
+class AccountUsage(TypedDict):
+    """What the account uses now."""
+
+    domains: int
+    sent_today: int
+    sent_this_month: int
+
+
+class Billing(TypedDict):
+    """The subscription to the paid plan, as the payment provider last reported it."""
+
+    status: Optional[str]
+    interval: Optional[BillingInterval]
+    current_period_end: Optional[str]
+    cancels_at_period_end: bool
+
+
+class _AccountRequired(TypedDict):
+    email: str
+    plan: Plan
+    status: AccountStatus
+    status_reason: Optional[str]
+    send_hold: Optional[str]
+    limits: Limits
+    usage: AccountUsage
+    created_at: str
+
+
+class Account(_AccountRequired, total=False):
+    """An account: its plan, limits, usage and state."""
+
+    billing: Optional[Billing]
+
+
+class SignupResult(TypedDict):
+    """The answer to POST /v1/signup."""
+
+    api_key: str
+    account: Account
+    mailed: bool
+    message: str
+    next_steps: List[str]
+
+
+class LoginResult(TypedDict):
+    """The answer to POST /v1/login. The same for every address, with or without an account."""
+
+    message: str
+    next_step: str
+
+
+class Session(TypedDict):
+    """The answer to POST /v1/login/confirm: a session for the web dashboard."""
+
+    session_token: str
+    expires_at: str
+    account: Account
+
+
+class LogoutResult(TypedDict):
+    """The answer to POST /v1/logout."""
+
+    signed_out: bool
+
+
+class Key(TypedDict):
+    """One API key of the account. The key itself is not shown."""
+
+    prefix: str
+    created_at: str
+    last_used_at: Optional[str]
+
+
+class KeyList(TypedDict):
+    """The answer to GET /v1/keys."""
+
+    keys: List[Key]
+
+
+class ConnectedApp(TypedDict):
+    """An app that the owner connected to the account through OAuth."""
+
+    id: int
+    name: str
+    client_id: str
+    connected_at: str
+    last_used_at: Optional[str]
+
+
+class ConnectedAppList(TypedDict):
+    """The answer to GET /v1/oauth/apps."""
+
+    apps: List[ConnectedApp]
+
+
+class RemovedApp(TypedDict):
+    """The answer to DELETE /v1/oauth/apps/{id}."""
+
+    removed: int
+
+
+class RecoverResult(TypedDict):
+    """The answer to POST /v1/keys/recover. The same for every address, with or without an account."""
+
+    message: str
+    next_step: str
+
+
+class NewKey(TypedDict):
+    """A new API key from POST /v1/keys/recover/confirm or POST /v1/keys/rotate."""
+
+    api_key: str
+    account: Account
+    revoked_keys: int
+    message: str
+
+
+class Checkout(TypedDict):
+    """The answer to POST /v1/billing/checkout: a page where a person pays."""
+
+    url: str
+    interval: BillingInterval
+    price_usd: float
+    message: str
+
+
+class Portal(TypedDict):
+    """The answer to POST /v1/billing/portal: a page to change the card, see invoices, or cancel."""
+
+    url: str
+    message: str
+
+
+class _DnsRecordRequired(TypedDict):
+    type: Literal["MX", "TXT"]
+    name: str
+    value: str
+    required: bool
+    purpose: str
+
+
+class DnsRecord(_DnsRecordRequired, total=False):
+    """One DNS record to publish at the DNS host of the domain."""
+
+    priority: int
+
+
+class _DomainChecksRequired(TypedDict):
+    ownership: CheckResult
+    mx: CheckResult
+    mx_found: List[str]
+    checked_at: str
+    problems: List[str]
+
+
+class DomainChecks(_DomainChecksRequired, total=False):
+    """The result of the last DNS check of a domain."""
+
+    dkim: CheckResult
+
+
+class SmtpPort(TypedDict):
+    """One port of the send-as SMTP host."""
+
+    port: int
+    security: Literal["starttls", "tls"]
+
+
+class SmtpCredential(TypedDict):
+    """One SMTP login of a domain. The password is not shown."""
+
+    username: str
+    created_at: str
+    last_used_at: Optional[str]
+
+
+class SendAs(TypedDict):
+    """Send-as for one domain: sending mail as addresses of the domain, through smtp.mxgate.io."""
+
+    ready: bool
+    reasons: List[str]
+    host: str
+    ports: List[SmtpPort]
+    credentials: List[SmtpCredential]
+
+
+class SendAsResult(TypedDict):
+    """The answer to GET /v1/domains/{domain}/smtp."""
+
+    send_as: SendAs
+
+
+class SmtpCredentialCreated(TypedDict):
+    """A new SMTP login. Returned once, when the credential is made."""
+
+    credential: SmtpCredential
+    password: str
+    host: str
+    ports: List[SmtpPort]
+    message: str
+
+
+class Domain(TypedDict):
+    """One domain of the account, with the DNS records it needs and the last check."""
+
+    name: str
+    status: Literal["pending", "verified"]
+    created_at: str
+    verified_at: Optional[str]
+    records: List[DnsRecord]
+    checks: Optional[DomainChecks]
+    aliases: int
+    send_as: SendAs
+
+
+class DomainList(TypedDict):
+    """The answer to GET /v1/domains."""
+
+    domains: List[Domain]
+
+
+class DomainResult(TypedDict):
+    """The answer to GET /v1/domains/{domain}."""
+
+    domain: Domain
+
+
+class _AddDomainResultRequired(TypedDict):
+    domain: Domain
+    created: bool
+
+
+class AddDomainResult(_AddDomainResultRequired, total=False):
+    """The answer to POST /v1/domains."""
+
+    next_step: str
+
+
+class VerifyResult(TypedDict):
+    """The answer to POST /v1/domains/{domain}/verify."""
+
+    domain: Domain
+    verified: bool
+    message: str
+
+
+class Deleted(TypedDict):
+    """The answer to a DELETE call."""
+
+    deleted: str
+
+
+class AliasTarget(TypedDict):
+    """One mailbox that an alias forwards to."""
+
+    email: str
+    confirmed: bool
+
+
+class Alias(TypedDict):
+    """One alias: an address at a domain and the mailboxes it forwards to."""
+
+    alias: str
+    address: str
+    domain: str
+    to: List[AliasTarget]
+    active: bool
+    inactive_reasons: List[str]
+    created_at: str
+    updated_at: str
+
+
+class AliasList(TypedDict):
+    """The answer to GET /v1/domains/{domain}/aliases."""
+
+    aliases: List[Alias]
+
+
+class SetAliasResult(TypedDict):
+    """The answer to PUT /v1/domains/{domain}/aliases/{alias}."""
+
+    alias: Alias
+    created: bool
+    confirmation_mailed_to: List[str]
+
+
+class Destination(TypedDict):
+    """One mailbox that the account can forward to."""
+
+    email: str
+    confirmed: bool
+    created_at: str
+    confirmed_at: Optional[str]
+
+
+class DestinationList(TypedDict):
+    """The answer to GET /v1/destinations."""
+
+    destinations: List[Destination]
+
+
+class DestinationResult(TypedDict):
+    """The answer to POST /v1/destinations."""
+
+    destination: Destination
+    mailed: bool
+    message: str
+
+
+# The answer to POST /v1/send. "from" is a Python keyword, so this one uses the
+# call form of TypedDict.
+SendResult = TypedDict(
+    "SendResult",
+    {
+        "message_id": str,
+        "from": str,
+        "to": List[str],
+        "cc": List[str],
+        "bcc": List[str],
+        "status": Literal["queued"],
+        "replayed": bool,
+        "message": str,
+    },
+)
+
+
+class LogEntry(TypedDict):
+    """One row of the per-message log. No subject and no body are stored."""
+
+    received_at: str
+    updated_at: str
+    direction: LogDirection
+    status: LogStatus
+    sender: Optional[str]
+    recipient: str
+    destination: str
+    domain: str
+    reason: Optional[str]
+    explanation: Optional[str]
+    dsn: Optional[str]
+    relay: Optional[str]
+    client: Optional[str]
+    message_id: Optional[str]
+    attempts: int
+
+
+class LogsPage(TypedDict):
+    """The answer to GET /v1/logs."""
+
+    entries: List[LogEntry]
+    next_before: Optional[str]
+    retention_days: int
+
+
+class NotificationRecent(TypedDict):
+    """One recent notification and what happened to it."""
+
+    event: NotificationEvent
+    created_at: str
+    recipient: str
+    webhook_status: WebhookStatus
+    webhook_attempts: int
+    webhook_last_error: Optional[str]
+    emailed: bool
+
+
+class _NotificationSettingsRequired(TypedDict):
+    email: bool
+    events: List[NotificationEvent]
+    webhook_url: Optional[str]
+    webhook_secret: Optional[str]
+    signature: str
+    recent: List[NotificationRecent]
+
+
+class NotificationSettings(_NotificationSettingsRequired, total=False):
+    """The notification settings of the account and the 20 newest notifications."""
+
+    message: str
+
+
+class WebhookTestResult(TypedDict):
+    """The answer to POST /v1/notifications/test."""
+
+    ok: bool
+    status: Optional[int]
+    error: Optional[str]
+    message: str
+
+
+class WebhookEvent(TypedDict):
+    """The JSON body that mxgate posts to your webhook URL.
+
+    `data` is the log row of the message. The test call (type `test`) has an
+    object with one `message` text instead.
+    """
+
+    id: str
+    type: Literal["message.bounced", "message.expired", "message.rejected", "message.deferred", "test"]
+    created_at: str
+    data: LogEntry
+
+
+class StatusCheck(TypedDict):
+    """One check of the outside monitor."""
+
+    name: str
+    ok: Optional[bool]
+    detail: str
+    last_check_at: Optional[str]
+    last_ok_at: Optional[str]
+    success_rate: Optional[float]
+    daily: List[Optional[float]]
+
+
+class Status(TypedDict):
+    """The health of the service, as a monitor on another machine sees it."""
+
+    state: StatusState
+    updated_at: Optional[str]
+    window_days: int
+    days: List[str]
+    checks: List[StatusCheck]
+    stale: bool
+
+
+__all__ = [
+    "Account",
+    "AccountStatus",
+    "AccountUsage",
+    "AddDomainResult",
+    "Alias",
+    "AliasList",
+    "AliasTarget",
+    "Billing",
+    "BillingInterval",
+    "CheckResult",
+    "Checkout",
+    "ConnectedApp",
+    "ConnectedAppList",
+    "Deleted",
+    "Destination",
+    "DestinationList",
+    "DestinationResult",
+    "DnsRecord",
+    "Domain",
+    "DomainChecks",
+    "DomainList",
+    "DomainResult",
+    "ErrorBody",
+    "Index",
+    "Key",
+    "KeyList",
+    "Limits",
+    "LogDirection",
+    "LogEntry",
+    "LogStatus",
+    "LoginResult",
+    "LogoutResult",
+    "LogsPage",
+    "NewKey",
+    "NotificationEvent",
+    "NotificationRecent",
+    "NotificationSettings",
+    "Plan",
+    "Portal",
+    "RecoverResult",
+    "RemovedApp",
+    "SendAs",
+    "SendAsResult",
+    "SendResult",
+    "Session",
+    "SetAliasResult",
+    "SignupResult",
+    "SmtpCredential",
+    "SmtpCredentialCreated",
+    "SmtpPort",
+    "Status",
+    "StatusCheck",
+    "StatusState",
+    "VerifyResult",
+    "WebhookEvent",
+    "WebhookStatus",
+    "WebhookTestResult",
+]

mxgate/webhooks.py

@@ -0,0 +1,53 @@
+"""The check of the signature of a webhook call from mxgate.
+
+mxgate sends the header `mxgate-signature: t=<unix seconds>,v1=<hex>`.
+`v1` is the HMAC-SHA256 of the text `"<t>.<raw body>"` with the webhook secret.
+"""
+
+import hashlib
+import hmac
+import time
+from typing import List, Optional, Union
+
+
+def verify_webhook(
+    secret: str,
+    signature_header: str,
+    raw_body: Union[bytes, str],
+    *,
+    tolerance_seconds: int = 300,
+    now: Optional[float] = None,
+) -> bool:
+    """Returns True when the signature is correct and `t` is not older than the tolerance.
+
+    `secret` is `webhook_secret` from the notification settings (`whsec_...`).
+    `signature_header` is the value of the `mxgate-signature` header.
+    `raw_body` is the body of the call as it came, before a JSON parser changed it.
+    `now` is the time in unix seconds; the default is the clock of the machine.
+    """
+    if not secret or not isinstance(signature_header, str):
+        return False
+    timestamp: Optional[str] = None
+    signatures: List[str] = []
+    for part in signature_header.split(","):
+        name, sep, value = part.strip().partition("=")
+        if not sep:
+            continue
+        if name == "t" and timestamp is None:
+            timestamp = value
+        elif name == "v1":
+            signatures.append(value)
+    # isascii: isdigit() is also true for digits that are not 0 to 9.
+    if timestamp is None or not (timestamp.isascii() and timestamp.isdigit()) or not signatures:
+        return False
+    current = time.time() if now is None else now
+    if current - int(timestamp) > tolerance_seconds:
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else bytes(raw_body)
+    expected = hmac.new(secret.encode("utf-8"), timestamp.encode("ascii") + b"." + body, hashlib.sha256).hexdigest().encode("ascii")
+    ok = False
+    for signature in signatures:
+        # No early exit: each candidate gets the same constant-time compare.
+        if hmac.compare_digest(expected, signature.strip().lower().encode("utf-8")):
+            ok = True
+    return ok