treasy-mcp 0.0.0.dev0__py3-none-any.whl

treasy_mcp/__init__.py

@@ -0,0 +1,24 @@
+# treasy_mcp — MCP Server para a API Treasy
+import os as _os
+
+from treasy_mcp._versao import __version__  # noqa: F401  (fonte única, esforço 003968)
+from treasy_mcp.instalacao import aplicar_padroes_do_cliente as _aplicar_padroes_do_cliente
+
+# Pacote instalado (wheel) e sem TREASY_MCP_MODO: o cliente entra no modo claude-code em
+# produção, somente leitura (003968, D5). No checkout (Copilot, Docker) isto não faz nada.
+_aplicar_padroes_do_cliente()
+
+# Modo claude-code (002675): valida as variáveis e carrega os segredos do client
+# ambassador ANTES de qualquer import do config.py, que lê os.environ na importação.
+# Sem TREASY_MCP_MODO (o caminho do Copilot), nada aqui roda.
+if _os.environ.get("TREASY_MCP_MODO", "").strip():
+    import warnings as _warnings
+
+    _warnings.filterwarnings(
+        "ignore",
+        message=r"'treasy_mcp\.(modo|credenciais)' found in sys\.modules",
+        category=RuntimeWarning,
+    )
+    from treasy_mcp.modo import preparar as _preparar
+
+    _preparar()

treasy_mcp/__main__.py

@@ -0,0 +1,89 @@
+"""Entry point: ``treasy-mcp`` (ou ``python -m treasy_mcp``).
+
+Sem argumento, sobe o servidor MCP por stdio: é o que o Claude Code chama. Com argumento, é a
+linha de comando do cliente (esforço 003968, D6 = subcomando): ``login``, ``status``, ``sair``,
+``doctor`` e ``--version``. O login é o do ``003962`` (``login_navegador``), não uma cópia.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+USO = """uso: treasy-mcp [comando]
+
+  (sem comando)       sobe o servidor MCP (é o que o Claude Code chama)
+  login [ambiente]    abre o navegador para você entrar no Treasy (padrão: prod)
+  status [ambiente]   mostra a sessão gravada, nunca o token
+  sair [ambiente]     apaga a sessão local (padrão: prod)
+  doctor              diagnóstico da instalação em seis linhas, sem segredo
+  --version           mostra a versão
+
+ambiente: prod, qa ou sandbox. Instruções completas: INSTALAR.md.
+"""
+
+COMANDOS_DE_LOGIN = ("login", "status", "sair")
+COM_AMBIENTE_OBRIGATORIO = ("login", "sair")
+
+
+def _ambiente_padrao() -> str:
+    return (os.environ.get("TREASY_AMBIENTE") or "").strip() or "prod"
+
+
+def _argumentos_do_login(comando: str, resto: list[str]) -> list[str]:
+    """Põe o ambiente padrão quando a pessoa não disse qual (``treasy-mcp login``)."""
+    sem_ambiente = not resto or resto[0].startswith("-")
+    if comando in COM_AMBIENTE_OBRIGATORIO and sem_ambiente:
+        resto = [_ambiente_padrao(), *resto]
+    elif comando == "status" and sem_ambiente and not _em_checkout():
+        # Instalado, o ``status`` fala só do ambiente do cliente: qa e sandbox são da casa (003973).
+        resto = [_ambiente_padrao(), *resto]
+    return [comando, *resto]
+
+
+def _em_checkout() -> bool:
+    from treasy_mcp import instalacao
+
+    return instalacao.em_checkout()
+
+
+def _servidor() -> None:  # pragma: no cover - sobe o servidor de verdade, provado na instalação
+    import asyncio
+
+    from treasy_mcp import catalogo_vivo
+    from treasy_mcp.server import main as async_main
+
+    catalogo_vivo.iniciar()  # volta na hora; a busca da spec do T30 roda numa thread de fundo
+    asyncio.run(async_main())
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        _servidor()
+        return 0
+    comando, resto = args[0], args[1:]
+    if comando in ("--version", "-V", "versao", "versão"):
+        from treasy_mcp import __version__
+
+        print(f"treasy-mcp {__version__}")
+        return 0
+    if comando in ("-h", "--help", "ajuda"):
+        print(USO)
+        return 0
+    if comando in COMANDOS_DE_LOGIN:
+        from treasy_mcp import instalacao, login_navegador
+
+        if not instalacao.em_checkout():  # instalado, o login ensina o comando do pacote, não o python -m
+            login_navegador.PROG = instalacao.PREFIXO_DO_CLIENTE
+        return login_navegador.main(_argumentos_do_login(comando, resto))
+    if comando == "doctor":
+        from treasy_mcp import doctor
+
+        return doctor.main(resto)
+    print(f"comando desconhecido: {comando}\n\n{USO}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

treasy_mcp/_versao.py

@@ -0,0 +1,7 @@
+"""Fonte única da versão do pacote (esforço 003968).
+
+O ``pyproject.toml`` lê daqui (``dynamic = ["version"]``) e o ``tests/test_versao.py`` confere que
+este número é o da última seção lançada do ``CHANGELOG.md``.
+"""
+
+__version__ = "0.0.0.dev0"

treasy_mcp/arquivos.py

@@ -0,0 +1,471 @@
+"""
+Envio e download de arquivo pelo gateway (esforço 003966).
+
+Três portas, nesta ordem: o portão de origem (`validar_origem`) recusa o caminho antes de abrir o
+arquivo; a confirmação mostra nome, bytes e sha256 e a reconfirmação recalcula o hash
+(`preparar_envio` mais `_PENDENTES`); o download grava só dentro de
+``<pasta de exportação>/<ambiente>/<schema>/arquivos/`` e devolve caminho, tamanho e sha256,
+nunca o binário.
+
+O fio foi medido no sandbox em 2026-11-01 (P0, `04-PROGRESSO.md` do esforço): a parte JSON do
+``/fatos/salvar`` só entra como ``application/json`` (texto dá 415); sem a parte ``comentarios`` o
+servidor dá 500; o upload de anexo de fato exige ``fatoId`` também como parâmetro da requisição; o
+download por ``/{filename}`` devolve binário rotulado ``application/json``; o servidor corta o
+pedido entre 45 e 50 MB.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import itertools
+import json
+import mimetypes
+import os
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from pathlib import Path, PureWindowsPath
+from typing import Any
+from urllib.parse import quote
+
+from treasy_mcp import exportacao as _exportacao
+
+MB = 1024 * 1024
+TETO_PADRAO_MB = 50  # D3 (CEO, 2026-11-01): 50 MB nos dois sentidos, ajustável por variável
+TETO_JSON_EM_MEMORIA = 4 * MB
+BLOCO = 64 * 1024
+TETO_NOME = 80
+EXTENSOES_PERMITIDAS = frozenset({"pdf", "png", "jpg", "jpeg", "xlsx", "csv", "txt", "docx"})  # D6
+NOMES_RESERVADOS = frozenset(
+    {"con", "prn", "aux", "nul"} | {f"com{i}" for i in range(1, 10)} | {f"lpt{i}" for i in range(1, 10)}
+)
+PASTAS_BLOQUEADAS = frozenset({".treasy", ".ssh", ".git", "treasy-exportacoes", ".aws", ".azure", ".gnupg"})
+SUFIXOS_BLOQUEADOS = (".pem", ".key", ".pfx", ".p12")
+INICIOS_EXECUTAVEIS = (b"MZ", b"#!", b"<script")
+EXTENSOES_EXECUTAVEIS = frozenset({
+    "exe", "dll", "com", "bat", "cmd", "ps1", "psm1", "vbs", "vbe", "js", "jse", "wsf", "hta", "lnk",
+    "msi", "scr", "jar", "sh", "html", "htm", "svg", "reg", "cpl", "pif", "url", "chm", "mht", "mhtml",
+    "xhtml", "inf", "msc", "wsh", "appref-ms",
+})
+TRANSPORTES_REMOTOS = frozenset({"http", "streamable-http", "streamable_http"})
+OPERACOES_DE_IMAGEM = ("/empresas/logo/", "/empresas/logo_original/", "/usuarios/foto/", "/usuarios/foto_original/")
+
+
+class ArquivoRecusado(ValueError):
+    """Recusa com motivo legível; nada foi lido nem enviado."""
+
+
+def _teto(variavel: str) -> int:
+    valor = os.environ.get(variavel, "").strip()
+    try:
+        mb = float(valor) if valor else TETO_PADRAO_MB
+    except ValueError:
+        mb = TETO_PADRAO_MB
+    return int(mb * MB) if mb > 0 else TETO_PADRAO_MB * MB
+
+
+def teto_envio() -> int:
+    return _teto("TREASY_ARQUIVO_TETO_ENVIO_MB")
+
+
+def teto_download() -> int:
+    return _teto("TREASY_ARQUIVO_TETO_DOWNLOAD_MB")
+
+
+# ── Portão de origem ──────────────────────────────────────────────────────────
+
+def _mesmo_caminho(a: Path, b: Path) -> bool:
+    return os.path.normcase(str(a)) == os.path.normcase(str(b))
+
+
+def _conferir_nomes(caminho: Path) -> None:
+    for parte in caminho.parts[1:]:
+        limpo = parte.rstrip(" .").lower() or parte.lower()
+        if limpo.split(".")[0].strip() in NOMES_RESERVADOS:
+            raise ArquivoRecusado(f"'{parte}' é um nome reservado do Windows")
+        if limpo in PASTAS_BLOQUEADAS or limpo.startswith(".env"):
+            raise ArquivoRecusado(f"arquivos dentro de '{parte}' não podem subir (lista de bloqueio)")
+    if caminho.name.rstrip(" .").lower().endswith(SUFIXOS_BLOQUEADOS):
+        raise ArquivoRecusado("chave ou certificado não pode subir (lista de bloqueio)")
+
+
+def validar_origem(caminho: Any) -> Path:
+    """Devolve o caminho real de um arquivo que pode subir, ou levanta `ArquivoRecusado`.
+
+    Nada aqui abre o arquivo: o portão vem antes da leitura e antes da confirmação.
+    """
+    if not isinstance(caminho, str) or not caminho.strip():
+        raise ArquivoRecusado("o caminho do arquivo veio vazio ou não é texto")
+    texto = caminho.strip()
+    if any(unicodedata.category(c) == "Cc" for c in texto):
+        raise ArquivoRecusado("o caminho tem caractere de controle")
+    if texto.startswith("~"):
+        raise ArquivoRecusado("passe o caminho completo do arquivo (o '~' não é expandido)")
+    if texto.startswith(("\\\\", "//")):
+        raise ArquivoRecusado("caminho de rede (UNC) não é aceito; copie o arquivo para o disco local")
+    janela = PureWindowsPath(texto)
+    resto = texto[len(janela.drive):] if janela.drive else texto
+    if ":" in resto:
+        raise ArquivoRecusado("o caminho tem ':' fora da letra do disco (fluxo alternativo do Windows)")
+    normal = Path(texto.replace("\\", "/")) if os.sep == "/" else Path(texto)
+    if not normal.is_absolute():
+        raise ArquivoRecusado("passe o caminho completo do arquivo (caminho relativo não é aceito)")
+    _conferir_nomes(normal)
+    if normal.is_symlink():
+        raise ArquivoRecusado("o arquivo é um link simbólico; passe o arquivo de verdade")
+    try:
+        real = normal.resolve(strict=True)
+    except (FileNotFoundError, OSError):
+        raise ArquivoRecusado("o arquivo não existe nesse caminho") from None
+    if not _mesmo_caminho(real, Path(os.path.abspath(normal))):
+        raise ArquivoRecusado("o caminho passa por link ou junção; passe o caminho real do arquivo")
+    if not real.is_file():
+        raise ArquivoRecusado("o caminho não é um arquivo comum")
+    _conferir_nomes(real)  # gauntlet: ".ssh." vira ".ssh" no Windows; confere o nome real também
+    if any((pai / ".git").exists() for pai in real.parents):
+        raise ArquivoRecusado("o arquivo está dentro de um repositório git (lista de bloqueio)")
+    extensao = real.suffix.lower().lstrip(".")
+    if extensao not in EXTENSOES_PERMITIDAS:
+        raise ArquivoRecusado(
+            f"tipo '.{extensao}' não pode subir; aceitos: {', '.join(sorted(EXTENSOES_PERMITIDAS))}"
+        )
+    restrita = os.environ.get("TREASY_ENVIO_DIR", "").strip()
+    if restrita:
+        raiz = Path(restrita).resolve()
+        if not real.is_relative_to(raiz):
+            raise ArquivoRecusado("o arquivo está fora da pasta liberada em TREASY_ENVIO_DIR")
+    if real.stat().st_size > teto_envio():
+        raise ArquivoRecusado(f"o arquivo passa do teto de {teto_envio() // MB} MB")
+    return real
+
+
+@dataclass
+class Arquivo:
+    parte: str
+    nome: str
+    dados: bytes = field(repr=False)
+    sha256: str
+    content_type: str
+
+    def resumo(self) -> dict:
+        return {"parte": self.parte, "nome": self.nome, "bytes": len(self.dados), "sha256": self.sha256}
+
+
+def ler(parte: str, caminho: str) -> Arquivo:
+    """Valida e lê UMA vez em binário; o sha256 sai destes bytes, que são os que sobem."""
+    real = validar_origem(caminho)
+    teto = teto_envio()
+    with open(real, "rb") as f:
+        dados = f.read(teto + 1)
+    if len(dados) > teto:
+        raise ArquivoRecusado(f"o arquivo passa do teto de {teto // MB} MB")
+    tipo = mimetypes.guess_type(real.name)[0] or "application/octet-stream"
+    return Arquivo(parte, real.name, dados, hashlib.sha256(dados).hexdigest(), tipo)
+
+
+# ── Envio ─────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Envio:
+    partes: list[tuple[str, tuple]]
+    arquivos: list[Arquivo]
+    params: dict
+    contexto: str = ""
+
+    def resumo(self) -> list[dict]:
+        return [a.resumo() for a in self.arquivos]
+
+    def impressao(self) -> str:
+        return "|".join([self.contexto] + [f"{a.parte}:{a.sha256}" for a in self.arquivos])
+
+
+_PENDENTES: dict[str, str] = {}
+
+
+def _chave_pendente(op: dict, path_params: Any, arquivos: dict) -> str:
+    return json.dumps([op["operation_id"], path_params or {}, arquivos], sort_keys=True, default=str)
+
+
+def transporte_remoto() -> bool:
+    return os.environ.get("MCP_TRANSPORT", "stdio").strip().lower() in TRANSPORTES_REMOTOS
+
+
+def recusa_de_forma(op: dict, arquivos: Any, body: Any, campos: Any = None) -> dict | None:
+    """O descompasso entre a forma da operação e o que veio, recusado antes de tudo."""
+    multipart = e_multipart(op)
+    arquivo_obrigatorio = any(p.get("obrigatorio") and p["tipo"] in ("arquivo", "arquivos")
+                              for p in op.get("multipart_partes", []))
+    if (arquivos or campos) and not multipart:
+        return {"recusado": True, "motivo": "esta operação recebe JSON, não arquivo; use body",
+                "operation_id": op["operation_id"]}
+    if multipart and not arquivos and (arquivo_obrigatorio or not campos):
+        return {"recusado": True, "use": "arquivos",
+                "motivo": "esta operação recebe arquivo: passe o caminho completo em arquivos "
+                          "({parte: caminho}) e os demais campos em campos",
+                "partes": op.get("multipart_partes", []), "operation_id": op["operation_id"]}
+    if multipart and body is not None:
+        return {"recusado": True, "use": "campos",
+                "motivo": "operação multipart: mande os campos em campos, não em body",
+                "operation_id": op["operation_id"]}
+    return None
+
+
+def destino(client: Any, query_params: Any) -> dict:
+    """Ambiente, schema, empresa e query: entram na impressão digital da confirmação."""
+    return {
+        "ambiente": getattr(client, "_ambiente", None),
+        "schema": getattr(client, "_schema", None),
+        "empresa": getattr(client, "_empresa_do_schema", None) or getattr(client, "_empresa_id", None),
+        "query_params": query_params or {},
+    }
+
+
+def e_multipart(op: dict) -> bool:
+    return op.get("request_content_type") == "multipart/form-data"
+
+
+def descricao_multipart(op: dict) -> dict:
+    """O que o `descrever_operacao` acrescenta numa operação multipart (P2)."""
+    if not e_multipart(op):
+        return {}
+    return {
+        "request_content_type": "multipart/form-data",
+        "multipart_partes": op.get("multipart_partes", []),
+        "como_enviar": "as partes de tipo arquivo/arquivos recebem o CAMINHO completo do arquivo "
+                       "local em `arquivos`; as demais vão em `campos` (objeto vira JSON)",
+    }
+
+
+def preparar_envio(op: dict, arquivos: Any, campos: Any, path_params: Any,
+                   ambiente: str | None, contexto: dict | None = None) -> Envio:
+    """Monta as partes do multipart; levanta `ArquivoRecusado` antes de qualquer rede."""
+    if transporte_remoto():
+        raise ArquivoRecusado("este servidor não vê seu disco (transporte HTTP); use o MCP local")
+    if ambiente == "prod":  # D2: envio em produção só depois do 003967
+        raise ArquivoRecusado("envio de arquivo em produção está desligado (decisão D2 do 003966)")
+    arquivos = {} if arquivos is None else arquivos
+    if not isinstance(arquivos, dict):
+        raise ArquivoRecusado("arquivos deve ser um objeto {parte: caminho | [caminhos]}")
+    campos = campos or {}
+    if not isinstance(campos, dict):
+        raise ArquivoRecusado("campos deve ser um objeto {parte: valor}")
+    por_nome = {p["nome"]: p for p in op.get("multipart_partes", [])}
+    partes: list[tuple[str, tuple]] = []
+    lidos: list[Arquivo] = []
+    for nome, valor in arquivos.items():
+        spec = por_nome.get(nome)
+        if not spec or spec["tipo"] not in ("arquivo", "arquivos"):
+            raise ArquivoRecusado(f"'{nome}' não é parte de arquivo desta operação")
+        caminhos = valor if isinstance(valor, list) else [valor]
+        if spec["tipo"] == "arquivo" and len(caminhos) != 1:
+            raise ArquivoRecusado(f"a parte '{nome}' recebe um arquivo só")
+        for caminho in caminhos:
+            arq = ler(nome, caminho)
+            lidos.append(arq)
+            if sum(len(x.dados) for x in lidos) > teto_envio():  # o teto vale pelo envio inteiro
+                raise ArquivoRecusado(f"os arquivos somados passam do teto de {teto_envio() // MB} MB")
+            partes.append((nome, (arq.nome, arq.dados, arq.content_type)))
+    for nome, valor in campos.items():
+        spec = por_nome.get(nome)
+        if not spec or spec["tipo"] in ("arquivo", "arquivos"):
+            raise ArquivoRecusado(f"'{nome}' não é campo desta operação")
+        if spec["tipo"] == "json":
+            partes.append((nome, (None, json.dumps(valor, ensure_ascii=False), "application/json")))
+        else:
+            partes.append((nome, (None, str(valor))))
+    for spec in por_nome.values():
+        if spec["nome"] in arquivos or spec["nome"] in campos:
+            continue
+        if spec.get("lista"):  # P0: sem a lista de comentários o /salvar dá 500
+            partes.append((spec["nome"], (None, "[]", "application/json")))
+        elif spec.get("obrigatorio"):
+            raise ArquivoRecusado(f"falta a parte obrigatória '{spec['nome']}'")
+    # P0: o upload de anexo exige o id do caminho também como parâmetro da requisição.
+    params = {k: v for k, v in (path_params or {}).items() if isinstance(v, (str, int))}
+    impressao_destino = json.dumps([contexto or {}, campos], sort_keys=True, default=str)
+    return Envio(partes, lidos, params, impressao_destino)
+
+
+def conferir_confirmacao(op: dict, path_params: Any, arquivos: dict, envio: Envio,
+                         confirmar: bool) -> dict | None:
+    """1ª chamada guarda a impressão digital; a confirmação só vale com os mesmos bytes."""
+    chave = _chave_pendente(op, path_params, arquivos or {})
+    if not confirmar:
+        _PENDENTES[chave] = envio.impressao()
+        return None
+    esperado = _PENDENTES.pop(chave, None)
+    if esperado is None:
+        return {"recusado": True, "motivo": "esta confirmação não tem pedido anterior; "
+                "chame sem confirmar_escrita para ver o resumo primeiro"}
+    if esperado != envio.impressao():
+        return {"recusado": True, "motivo": "o arquivo, os campos ou o destino mudaram depois do "
+                "resumo confirmado; nada foi enviado, peça a confirmação de novo"}
+    return None
+
+
+def resumo_do_envio(client: Any, envio: Envio, campos: dict | None) -> dict:
+    """O que o humano precisa ver para confirmar: onde vai, e quais bytes exatos."""
+    return {
+        "ambiente": getattr(client, "_ambiente", None),
+        "schema": getattr(client, "_schema", None),
+        "empresa": getattr(client, "_empresa_do_schema", None) or getattr(client, "_empresa_id", None),
+        "arquivos": envio.resumo(),
+        "campos": campos or {},
+    }
+
+
+# ── Download ──────────────────────────────────────────────────────────────────
+
+def nome_seguro(bruto: str | None, padrao: str = "arquivo") -> str:
+    """O nome da API, saneado (D8): só o nome-base, sem controle, ':' nem nome reservado."""
+    nome = (bruto or "").replace("\\", "/").split("/")[-1]
+    nome = "".join(c for c in nome if unicodedata.category(c)[0] != "C")
+    nome = re.sub(r'[:*?"<>|]', "_", nome).strip(" .")
+    if not nome or set(nome) <= {"."}:
+        nome = padrao
+    if nome.split(".")[0].strip().lower() in NOMES_RESERVADOS:
+        nome = "_" + nome
+    if len(nome) > TETO_NOME:  # curto o bastante para o MAX_PATH do Windows com o ".parcial"
+        raiz, ponto, ext = nome.rpartition(".")
+        nome = (raiz[: TETO_NOME - 10] + "." + ext) if ponto and len(ext) <= 8 else nome[:TETO_NOME]
+    return nome
+
+
+def nome_da_resposta(content_disposition: str | None) -> str | None:
+    if not content_disposition:
+        return None
+    achado = re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";]+)"?', content_disposition, re.I)
+    return achado.group(1) if achado else None
+
+
+def pasta_dos_arquivos(ambiente: str, schema: str) -> Path:
+    pasta = _exportacao.pasta_destino(ambiente, schema) / "arquivos"
+    motivo = _exportacao.destino_proibido(pasta)
+    if motivo:
+        raise ArquivoRecusado(f"a pasta de download está {motivo}; ajuste TREASY_EXPORTACAO_DIR")
+    pasta.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return pasta
+
+
+def _corpo_pequeno(primeiros: bytes, content_type: str) -> Any:
+    """JSON ou texto de verdade volta como dado; o resto é arquivo (devolve None)."""
+    if content_type.startswith("text/"):
+        try:
+            return {"texto": primeiros.decode("utf-8")[:4096], "content_type": content_type}
+        except UnicodeDecodeError:
+            return None
+    try:
+        return json.loads(primeiros)
+    except (ValueError, UnicodeDecodeError):
+        return None
+
+
+def gravar_stream(blocos: Any, pasta: Path, nome: str, teto: int, inicio: bytes = b"") -> dict:
+    """Grava em ``.parcial`` e troca por ``os.replace``; acima do teto não sobra nenhum byte."""
+    stem, ponto, ext = nome.rpartition(".")
+    if not ponto or not stem:
+        stem, ext = nome, "bin"
+    final, _ = _exportacao._reservar(pasta, stem, ext, com_irmao=False)
+    parcial = final.with_name(final.name + ".parcial")
+    sha = hashlib.sha256()
+    total = 0
+    cabeca = b""
+    try:
+        fd = os.open(parcial, os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0), 0o600)
+        with os.fdopen(fd, "wb") as f:
+            for bloco in itertools.chain((inicio,), blocos):
+                if not bloco:
+                    continue
+                total += len(bloco)
+                if total > teto:
+                    raise ArquivoRecusado(f"o download passa do teto de {teto // MB} MB; nada foi gravado")
+                if len(cabeca) < 8:
+                    cabeca += bloco[: 8 - len(cabeca)]
+                sha.update(bloco)
+                f.write(bloco)
+        aviso = None
+        if (cabeca.startswith(INICIOS_EXECUTAVEIS) or cabeca.lower().startswith(b"<script")
+                or ext.lower() in EXTENSOES_EXECUTAVEIS):
+            os.remove(final)
+            final, _ = _exportacao._reservar(pasta, f"{stem}.{ext}", "bin", com_irmao=False)
+            aviso = "conteúdo executável: gravado com extensão .bin; não abra sem conferir"
+        os.replace(parcial, final)
+    except BaseException:
+        for resto in (parcial, final):
+            try:
+                os.remove(resto)
+            except OSError:
+                pass
+        raise
+    return {"caminho": str(final), "bytes": total, "sha256": sha.hexdigest(), "aviso": aviso}
+
+
+def processar_download(r: Any, pasta_de: Any, nome_padrao: str) -> Any:
+    """Decide pela resposta real, não pela spec: anexo, binário ou JSON que não parseia vira arquivo."""
+    content_type = (r.headers.get("content-type") or "").split(";")[0].strip().lower()
+    disposicao = r.headers.get("content-disposition") or ""
+    blocos = r.iter_bytes(BLOCO)
+    inicio = b""
+    if "attachment" not in disposicao.lower() and (
+        content_type.startswith("text/") or "json" in content_type or not content_type
+    ):
+        for bloco in blocos:
+            inicio += bloco
+            if len(inicio) > TETO_JSON_EM_MEMORIA:
+                break
+        if len(inicio) <= TETO_JSON_EM_MEMORIA:
+            if not inicio:
+                return {"success": True}
+            dado = _corpo_pequeno(inicio, content_type)
+            if dado is not None:
+                return dado
+    origem = nome_da_resposta(disposicao) or nome_padrao
+    gravado = gravar_stream(blocos, pasta_de(), nome_seguro(origem), teto_download(), inicio)
+    return {**gravado, "content_type": content_type or None, "nome_origem": origem[:200]}
+
+
+def baixar(client: Any, real_path: str, query_params: dict | None, nome_padrao: str) -> Any:
+    if transporte_remoto():
+        raise ArquivoRecusado("este servidor (transporte HTTP) não grava arquivo no seu disco; "
+                              "use o MCP local para baixar")
+    def pasta_de() -> Path:
+        schema = client._schema or ""
+        return pasta_dos_arquivos(client._ambiente, schema)
+
+    return client._baixar(real_path, query_params or None,
+                          lambda r: processar_download(r, pasta_de, nome_padrao))
+
+
+def _segmento(valor: Any) -> str:
+    texto = str(valor)
+    if not texto or "/" in texto or "\\" in texto or ".." in texto or any(ord(c) < 32 for c in texto):
+        raise ArquivoRecusado("o nome da imagem atual veio fora do padrão")
+    return quote(texto, safe="")
+
+
+def copia_anterior(client: Any, op: dict, campos: dict | None) -> dict | None:
+    """D7: antes de trocar logo ou foto, baixa a imagem atual. Se a cópia falhar, a troca é recusada."""
+    if op.get("path") not in OPERACOES_DE_IMAGEM:
+        return None
+    original = "original" in op["path"]
+    try:
+        if op["path"].startswith("/empresas/"):
+            empresa = int((campos or {}).get("empresaId") or client._empresa_do_schema or client._empresa_id)
+            registro = client._get(f"/empresas/{empresa}")
+            atual = registro.get("logoOriginalUrl" if original else "logoUrl")
+            dono = (registro.get("cliente") or {}).get("id")
+            trecho = "logo_original" if original else "logo"
+            caminho = lambda: f"/empresas/{empresa}/{trecho}/{int(dono)}/{_segmento(atual)}"  # noqa: E731
+        else:
+            registro = client._get("/usuarios/meus_dados")
+            atual = registro.get("fotoOriginalUrl" if original else "fotoUrl")
+            dono = registro.get("email")
+            trecho = "foto_original" if original else "foto"
+            caminho = lambda: f"/usuarios/{trecho}/{_segmento(dono)}/{_segmento(atual)}"  # noqa: E731
+        if not atual or not dono:
+            return {"copia_anterior": None, "aviso": "não havia imagem anterior; nada a copiar"}
+        return {"copia_anterior": baixar(client, caminho(), None, str(atual))}
+    except Exception as e:  # noqa: BLE001
+        raise ArquivoRecusado(
+            f"não consegui copiar a imagem atual, e sem a cópia a troca não tem volta: {str(e)[:120]}"
+        ) from None