hummand 0.4.0__py3-none-any.whl

hummand/__init__.py

@@ -0,0 +1,46 @@
+"""`hummand` — SDK Python da camada de garantia humana.
+
+Duas metades, que não se confundem:
+
+- **verificação** (`verificar`, `problemas`, `Prova`): offline, sem rede, com o JWKS pinado por
+  quem chama. É o que o **executor** roda antes de executar a ação. Esta metade é a que importa:
+  é ela que torna verdadeira a frase de que o sistema que executa só executa com o recibo de que
+  uma pessoa específica, viva e presente, viu e autorizou.
+- **cliente** (`Hummand`): o que o agente usa para pedir a prova ao gateway, com os tipos
+  derivados do OpenAPI. Conveniência; a trava não está aqui — se este módulo sumisse, o portão
+  continuaria de pé.
+
+O SDK não decide o que é arriscado. Quem decide o que exige prova é o cliente, na política do
+tenant; nenhuma heurística de risco mora aqui, e nenhuma vai morar.
+
+Rótulos honestos: `disponível` desde 2026-10-24 o mandato a agente, o ato delegado, o
+servidor MCP de mandato e a verificação do recibo `humanproof/1`; os adaptadores de framework
+seguem `arquitetura-alvo`.
+"""
+
+from __future__ import annotations
+
+from ._cliente import Hummand, Pedido
+from ._modelos import LinkAto, MandatoEstado, RevogarLoteResponse, RevogarMandatoResponse
+from .erros import ErroDeApi, ErroHummand, ProvaInvalida, ProvaNaoConcluida
+from .prova import Prova
+from .verificacao import hash_de_contexto, problemas, verificar
+
+__all__ = [
+    "ErroDeApi",
+    "ErroHummand",
+    "Hummand",
+    "LinkAto",
+    "MandatoEstado",
+    "Pedido",
+    "Prova",
+    "ProvaInvalida",
+    "ProvaNaoConcluida",
+    "RevogarLoteResponse",
+    "RevogarMandatoResponse",
+    "hash_de_contexto",
+    "problemas",
+    "verificar",
+]
+
+__version__ = "0.4.0"

hummand/_cliente.py

@@ -0,0 +1,503 @@
+"""Cliente HTTP do gateway: o que o **agente** usa para pedir a prova.
+
+É a metade de conveniência do SDK. A trava está na verificação, que o executor roda; se este
+módulo sumisse, o portão continuaria de pé. Por isso ele não decide nada: cria
+atos, espera veredito, busca recibo, revoga — e entrega tudo à `verificacao` para dizer se
+serve.
+
+Duas fronteiras que este módulo respeita e não vai afrouxar:
+
+- **a entrega do link é do cliente**. O SDK devolve o link e chama a função que
+  você passou; nunca manda SMS, e-mail ou push por conta própria;
+- **a Hummand nunca vê a ação** (D5). O que sobe em `contexto.dados` é o que você escolheu
+  declarar, e o que fica registrado no recibo é o hash disso mais os nomes das chaves.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field, is_dataclass
+from datetime import timedelta
+from types import UnionType
+from typing import Any, Union, cast, get_args, get_origin, get_type_hints
+
+import httpx
+
+from ._modelos import (
+    AtoResponse,
+    LinkAto,
+    MandatoEstado,
+    RevogarLoteResponse,
+    RevogarMandatoResponse,
+)
+from .erros import ErroDeApi, ErroHummand, ProvaNaoConcluida
+from .prova import Prova
+from .verificacao import verificar
+
+BASE_PADRAO = "https://gateway.hummand.com.br"
+JWKS_ROTA = "/.well-known/humanproof/keys.json"
+
+TIPO_STEPUP = "stepup.transacao"
+TIPO_MANDATO = "mandato.agente"
+TIPO_DELEGADO = "ato.delegado"
+
+# Estados terminais do ato, no vocabulário da API (`services/atos/estados.py`). `em_revisao` não
+# entra: a fila humana ainda vai decidir, e desistir ali seria desistir cedo demais.
+TERMINAIS = frozenset({"concluido", "expirado", "cancelado", "falhou", "revogado"})
+
+CHAVE_NONCE = "nonce"
+CHAVE_EXECUTOR = "executor"
+
+
+def _de_dict(classe: type[Any], dado: Any) -> Any:
+    """Constrói um modelo gerado a partir do JSON da resposta.
+
+    Dataclass não sabe se montar a partir de dicionário, e o SDK não carrega uma biblioteca de
+    validação só para isso: o schema é do gateway, e quem confere o recibo é o núcleo. Campo
+    desconhecido é ignorado de propósito — API que ganha campo novo não derruba cliente velho.
+    """
+    if dado is None or not is_dataclass(classe):
+        return dado
+    tipos = get_type_hints(classe)
+    campos = {}
+    for nome, tipo in tipos.items():
+        if nome not in dado:
+            continue
+        campos[nome] = _converter(tipo, dado[nome])
+    return classe(**campos)
+
+
+def _converter(tipo: Any, valor: Any) -> Any:
+    origem = get_origin(tipo)
+    if origem in (Union, UnionType):
+        interno = [a for a in get_args(tipo) if a is not type(None)]
+        return _converter(interno[0], valor) if len(interno) == 1 and valor is not None else valor
+    if origem is list and isinstance(valor, list):
+        (item,) = get_args(tipo)
+        return [_converter(item, v) for v in valor]
+    if is_dataclass(tipo) and isinstance(valor, dict):
+        # `is_dataclass` estreita para "instância ou classe"; aqui o que chega é sempre a
+        # classe, porque o tipo veio de `get_type_hints`.
+        return _de_dict(cast("type[Any]", tipo), valor)
+    return valor
+
+
+def _sem_nulos(valor: Any) -> Any:
+    """Corpo da requisição sem as chaves nulas: `null` explícito tem significado na API."""
+    if isinstance(valor, dict):
+        return {k: _sem_nulos(v) for k, v in valor.items() if v is not None}
+    if isinstance(valor, list):
+        return [_sem_nulos(v) for v in valor]
+    return valor
+
+
+@dataclass(frozen=True)
+class Pedido:
+    """Um ato criado, à espera do humano. O link é seu para entregar."""
+
+    ato_id: str
+    tipo: str
+    nivel_minimo: int
+    contexto_dados: dict[str, Any] = field(default_factory=dict)
+    nonce: str | None = None
+    link: LinkAto | None = None
+
+    @property
+    def url(self) -> str | None:
+        return self.link.url if self.link else None
+
+
+class Hummand:
+    """Cliente do gateway. Um por tenant; reutilize — mantém a conexão aberta.
+
+    `jwks` é o JWKS **pinado**: baixe uma vez, versione com o seu serviço e passe aqui. Verificar
+    contra a chave que o mesmo servidor acabou de entregar não prova nada; por isso não há
+    busca automática — `baixar_jwks` existe só para o momento de pinar.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = BASE_PADRAO,
+        jwks: str | Mapping[str, Any] | None = None,
+        tenant_id: str | None = None,
+        timeout: float = 10.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ErroHummand("api_key é obrigatória")
+        self.jwks = jwks
+        self.tenant_id = tenant_id
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={"authorization": f"Bearer {api_key}"},
+        )
+
+    def __enter__(self) -> Hummand:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.fechar()
+
+    def fechar(self) -> None:
+        self._http.close()
+
+    # --- transporte ----------------------------------------------------------------
+
+    def _pedir(
+        self,
+        metodo: str,
+        rota: str,
+        *,
+        corpo: Any = None,
+        cabecalhos: Mapping[str, str] | None = None,
+        aceitar: tuple[int, ...] = (200, 201),
+    ) -> Any:
+        try:
+            resposta = self._http.request(
+                metodo, rota, json=_sem_nulos(corpo), headers=dict(cabecalhos or {})
+            )
+        except httpx.HTTPError as erro:  # rede, DNS, timeout: infraestrutura, dá para retentar
+            raise ErroDeApi(f"{metodo} {rota}: {erro}") from erro
+        if resposta.status_code not in aceitar:
+            raise ErroDeApi(_detalhe(resposta), status=resposta.status_code)
+        return resposta.json() if resposta.content else None
+
+    # --- criação de atos -----------------------------------------------------------
+
+    def pedir_prova(
+        self,
+        *,
+        sujeito: str,
+        dados: Mapping[str, Any] | None = None,
+        tipo: str = TIPO_STEPUP,
+        nivel_minimo: int = 2,
+        executor: str | None = None,
+        nonce: str | None = None,
+        referencia_ato: str | None = None,
+    ) -> Pedido:
+        """Cria o ato e devolve o `Pedido` com o link. Não espera nada; não entrega nada.
+
+        O `nonce` é gerado aqui quando você não passa um, e entra em `contexto.dados` junto com
+        o `executor`: os dois viram parte do `contexto.hash` assinado (sem campo novo no
+        recibo). É o que amarra o recibo a **este** pedido.
+        """
+        contexto = dict(dados or {})
+        nonce = nonce or secrets.token_hex(16)
+        contexto[CHAVE_NONCE] = nonce
+        if executor:
+            contexto[CHAVE_EXECUTOR] = executor
+
+        corpo: dict[str, Any] = {
+            "tipo": tipo,
+            "sujeito": {"ref_cliente": sujeito},
+            "contexto": {"dados": contexto, "chaves_declaradas": sorted(contexto)},
+            "nivel_minimo": nivel_minimo,
+        }
+        if referencia_ato:
+            corpo["sujeito"]["referencia"] = {"tipo": "ato", "ato_id": referencia_ato}
+
+        ato = self._criar(corpo)
+        return Pedido(
+            ato_id=ato.ato_id,
+            tipo=ato.tipo,
+            nivel_minimo=nivel_minimo,
+            contexto_dados=contexto,
+            nonce=nonce,
+            link=ato.link,
+        )
+
+    def mandato(
+        self,
+        *,
+        sujeito: str,
+        mandatario: str,
+        acoes: list[str],
+        validade_ate: str,
+        limites: Mapping[str, Any] | None = None,
+        revogavel: bool = True,
+        dados: Mapping[str, Any] | None = None,
+        nivel_minimo: int = 2,
+    ) -> Pedido:
+        """Concede um `mandato.agente`: presença viva do mandante, uma vez, com escopo escrito.
+
+        O escopo é o que o executor vai comparar com a ação — a Hummand não conhece a ação.
+        `revogavel=False` cria mandato que nem você derruba depois; o padrão é o contrário.
+        """
+        contexto = dict(dados or {})
+        corpo: dict[str, Any] = {
+            "tipo": TIPO_MANDATO,
+            "sujeito": {"ref_cliente": sujeito},
+            "mandatario": {"ref": mandatario},
+            "escopo": {
+                "acoes": acoes,
+                "validade_ate": validade_ate,
+                "revogavel": revogavel,
+                "limites": dict(limites or {}),
+            },
+            "nivel_minimo": nivel_minimo,
+        }
+        if contexto:
+            corpo["contexto"] = {"dados": contexto, "chaves_declaradas": sorted(contexto)}
+
+        ato = self._criar(corpo)
+        return Pedido(
+            ato_id=ato.ato_id,
+            tipo=ato.tipo,
+            nivel_minimo=nivel_minimo,
+            contexto_dados=contexto,
+            link=ato.link,
+        )
+
+    def delegado(
+        self,
+        *,
+        mandato_ref: str,
+        acao: str,
+        sujeito: str,
+        valores: Mapping[str, Any] | None = None,
+        janela: timedelta | None = None,
+        timeout: float = 60.0,
+        exigir_positivo: bool = True,
+    ) -> Prova:
+        """Ato sob mandato: sem humano novo, resolve na hora, e já volta verificado.
+
+        O que sustenta o ato é o mandato, não a ação: `acao` e `valores` são comparados com o
+        escopo **no gateway**, e o recibo diz se passou. Ato recusado também gera recibo — uma
+        tentativa sob mandato revogado é fato provável, e é por isso que ele não some.
+
+        "Na hora" é o veredito, não a assinatura: o recibo é assinado por um worker, no KMS,
+        e nasce instantes depois. Por isso há espera aqui, mesmo sem humano no caminho.
+
+        `exigir_positivo=False` devolve a prova do ato **recusado** em vez de levantar. Serve
+        para quem quer ler a recusa — auditoria, demo, teste de política —, nunca para quem
+        vai executar a ação: ali o padrão é o certo.
+        """
+        corpo = {
+            "tipo": TIPO_DELEGADO,
+            "sujeito": {"ref_cliente": sujeito},
+            "delegado": {
+                "mandato_ref": mandato_ref,
+                "acao": acao,
+                "valores": dict(valores or {}),
+            },
+        }
+        ato = self._criar(corpo)
+        recibo = self.esperar_recibo(ato.ato_id, timeout=timeout)
+        return self._verificar(
+            recibo,
+            tipo=TIPO_DELEGADO,
+            nivel_minimo=0,
+            janela=janela,
+            exigir_positivo=exigir_positivo,
+        )
+
+    def _criar(self, corpo: dict[str, Any]) -> AtoResponse:
+        # `Idempotency-Key` retentar por timeout de rede não cria ato novo.
+        cabecalhos = {"Idempotency-Key": uuid.uuid4().hex}
+        dado = self._pedir("POST", "/v1/atos", corpo=corpo, cabecalhos=cabecalhos)
+        return _de_dict(AtoResponse, dado)  # type: ignore[no-any-return]
+
+    # --- espera e verificação ------------------------------------------------------
+
+    def ato(self, ato_id: str) -> AtoResponse:
+        return _de_dict(AtoResponse, self._pedir("GET", f"/v1/atos/{ato_id}"))  # type: ignore[no-any-return]
+
+    def recibo(self, ato_id: str) -> dict[str, Any] | None:
+        """O recibo assinado, ou `None` enquanto a assinatura não saiu (202) ou não haverá (404).
+
+        O corpo vem como o gateway o assinou; qualquer reserialização é sua, e o verificador
+        canonicaliza antes de conferir.
+        """
+        dado = self._pedir("GET", f"/v1/atos/{ato_id}/recibo", aceitar=(200, 202, 404))
+        if isinstance(dado, dict) and dado.get("formato"):
+            return dado
+        return None
+
+    def esperar_recibo(
+        self,
+        ato_id: str,
+        *,
+        timeout: float = 60.0,
+        intervalo: float = 0.5,
+        intervalo_maximo: float = 5.0,
+    ) -> dict[str, Any]:
+        """Espera a assinatura do recibo sair, para um ato que já tem veredito.
+
+        O veredito e a assinatura são momentos diferentes: o worker assina no KMS, fora do
+        caminho da requisição. Quem só quer o recibo de um ato terminal (uma revogação, por
+        exemplo) chama isto; quem quer a prova verificada chama `aguardar`.
+        """
+        limite = time.monotonic() + timeout
+        while True:
+            recibo = self.recibo(ato_id)
+            if recibo is not None:
+                return recibo
+            restante = limite - time.monotonic()
+            if restante <= 0:
+                raise ProvaNaoConcluida(ato_id, "recibo ainda não assinado")
+            time.sleep(min(intervalo, restante))
+            intervalo = min(intervalo * 2, intervalo_maximo)
+
+    def aguardar(
+        self,
+        pedido: Pedido | str,
+        *,
+        timeout: float = 300.0,
+        intervalo: float = 1.0,
+        intervalo_maximo: float = 5.0,
+        janela: timedelta | None = None,
+    ) -> Prova:
+        """Espera o veredito e devolve a prova verificada.
+
+        Espera com recuo progressivo, porque a jornada leva de 40 a 60 segundos e nada ganha com
+        polling agressivo. Estourar o tempo levanta `ProvaNaoConcluida` — **o ato continua de
+        pé** no gateway até expirar, e o humano ainda pode concluí-lo; quem chama decide se
+        espera mais, avisa alguém ou desiste.
+        """
+        ato_id = pedido if isinstance(pedido, str) else pedido.ato_id
+        limite = time.monotonic() + timeout
+        estado = "criado"
+        while time.monotonic() < limite:
+            atual = self.ato(ato_id)
+            estado = atual.estado
+            if estado in TERMINAIS:
+                recibo = self.recibo(ato_id)
+                if recibo is not None:
+                    return self._verificar(recibo, pedido=pedido, janela=janela)
+            time.sleep(min(intervalo, max(0.0, limite - time.monotonic())))
+            intervalo = min(intervalo * 2, intervalo_maximo)
+        raise ProvaNaoConcluida(ato_id, estado)
+
+    def require_human_proof(
+        self,
+        *,
+        sujeito: str,
+        entregar: Callable[[LinkAto], None],
+        dados: Mapping[str, Any] | None = None,
+        tipo: str = TIPO_STEPUP,
+        nivel_minimo: int = 2,
+        executor: str | None = None,
+        nonce: str | None = None,
+        timeout: float = 300.0,
+        janela: timedelta | None = None,
+    ) -> Prova:
+        """Pede a prova, entrega o link pela sua função e espera o veredito verificado.
+
+        `entregar` é sua: push do seu app, SMS, QR na tela do operador. O SDK não tem canal
+        próprio e não vai ter — quem conhece a pessoa é você.
+        """
+        pedido = self.pedir_prova(
+            sujeito=sujeito,
+            dados=dados,
+            tipo=tipo,
+            nivel_minimo=nivel_minimo,
+            executor=executor,
+            nonce=nonce,
+        )
+        if pedido.link is None:
+            raise ErroHummand(f"ato {pedido.ato_id} nasceu sem link de verificação")
+        entregar(pedido.link)
+        return self.aguardar(pedido, timeout=timeout, janela=janela)
+
+    def _verificar(
+        self,
+        recibo: dict[str, Any],
+        *,
+        pedido: Pedido | str | None = None,
+        tipo: str | None = None,
+        nivel_minimo: int | None = None,
+        janela: timedelta | None = None,
+        exigir_positivo: bool = True,
+    ) -> Prova:
+        if self.jwks is None:
+            raise ErroHummand(
+                "sem JWKS pinado: passe `jwks=` ao criar o cliente (use `baixar_jwks` uma vez)"
+            )
+        do_pedido = pedido if isinstance(pedido, Pedido) else None
+        return verificar(
+            recibo,
+            jwks=self.jwks,
+            tipo=tipo if tipo is not None else (do_pedido.tipo if do_pedido else None),
+            tenant_id=self.tenant_id,
+            nivel_minimo=(
+                nivel_minimo
+                if nivel_minimo is not None
+                else (do_pedido.nivel_minimo if do_pedido else 0)
+            ),
+            contexto_dados=do_pedido.contexto_dados if do_pedido else None,
+            nonce=do_pedido.nonce if do_pedido else None,
+            janela=janela,
+            exigir_positivo=exigir_positivo,
+        )
+
+    # --- circuit breaker -----------------------------------------------------------
+
+    def estado_do_mandato(self, mandato_ato_id: str) -> MandatoEstado:
+        """Consulta barata de estado: é o que o executor chama antes de agir sob o mandato."""
+        return _de_dict(MandatoEstado, self._pedir("GET", f"/v1/mandatos/{mandato_ato_id}"))  # type: ignore[no-any-return]
+
+    def revogar(self, mandato_ato_id: str) -> RevogarMandatoResponse:
+        """Derruba um mandato. Ato humano, com recibo — e só outro mandato o devolve."""
+        dado = self._pedir("POST", f"/v1/mandatos/{mandato_ato_id}/revogar")
+        return _de_dict(RevogarMandatoResponse, dado)  # type: ignore[no-any-return]
+
+    def parar_tudo(
+        self, *, mandatario: str | None = None, todos: bool = False
+    ) -> RevogarLoteResponse:
+        """Revoga em lote, por mandatário ou por tenant: o "parar tudo" da camada 3.
+
+        Um alvo obrigatório e sem padrão, de propósito. O que isto para é a **autoridade** do
+        agente onde os executores a exigem — não a computação dele, que a Hummand não hospeda.
+        Mandato com `escopo.revogavel = false` não cai e volta em `ignorados`.
+        """
+        if bool(mandatario) == todos:
+            raise ErroHummand("escolha um alvo: `mandatario=` ou `todos=True`, nunca os dois")
+        corpo = {"mandatario_ref": mandatario, "todos": todos}
+        dado = self._pedir("POST", "/v1/mandatos/revogar-lote", corpo=corpo)
+        return _de_dict(RevogarLoteResponse, dado)  # type: ignore[no-any-return]
+
+    # --- chave pública -------------------------------------------------------------
+
+    def baixar_jwks(self) -> str:
+        """Baixa o JWKS **para você pinar**, uma vez, e versionar com o seu serviço.
+
+        Não use isto dentro do caminho de verificação: conferir a assinatura contra a chave que
+        o mesmo servidor acabou de entregar não prova nada contra quem controla o servidor.
+        """
+        resposta = self._http.get(JWKS_ROTA)
+        if resposta.status_code != 200:
+            raise ErroDeApi(_detalhe(resposta), status=resposta.status_code)
+        return resposta.text
+
+    def ponto_de_conferencia(self) -> dict[str, Any]:
+        """Ponto de conferência assinado da sua cadeia: **guarde, e compare depois**.
+
+        A cadeia de recibos acusa buraco no meio, inserção, reordenação e bifurcação. Ela não
+        acusa o corte do fim: remover os últimos recibos deixa um lote contínuo desde o gênesis,
+        e nada dentro dele diz quantos deveriam existir. O ponto afirma, assinado, quantos havia
+        e qual era o último.
+
+        O valor está na distância no tempo entre guardar e usar. Pedir o ponto no mesmo instante
+        em que se pede o lote não prova nada, porque os dois vêm da mesma versão da história.
+        Peça de tempos em tempos, guarde fora daqui, e confira com
+        `humanproof-verify verificar lote.json --jwks keys.json --ponto ponto.json`.
+        """
+        dado = self._pedir("GET", "/v1/recibos/ponto")
+        return dict(dado)
+
+
+def _detalhe(resposta: httpx.Response) -> str:
+    try:
+        corpo = resposta.json()
+    except ValueError:
+        return resposta.text[:200]
+    if isinstance(corpo, dict) and "detail" in corpo:
+        return str(corpo["detail"])
+    return str(corpo)[:200]