ekodide 0.1.0__py3-none-any.whl

ekodide/__init__.py

@@ -0,0 +1,56 @@
+"""Ekodide — envia e recebe arquivos pela rede, lacrados e idênticos.
+
+O nome é de um papagaio africano (odídẹ): repete com perfeição (o arquivo chega
+cópia EXATA, sha256 idêntico) e VOA (vai de um aparelho a outro pela rede, sem
+cabo). É código burro e determinístico — não tem IA aqui dentro. Algo pode ACIONAR
+o Ekodide (um humano no terminal, um script, um agente), mas quem faz o trabalho é
+este maquinário fixo.
+
+Como biblioteca:
+    from ekodide import enviar, servir
+    enviar(origem, url, segredo)                 # manda arquivo/pasta
+    servir(base, segredo, host="0.0.0.0")        # escuta e grava
+
+Como comando (depois de instalar):
+    ekodide send arquivo --para pc
+    ekodide serve
+"""
+from __future__ import annotations
+
+from .buscador import ErroPuxar, puxar
+from .buscador import listar as listar_remoto
+from .caixa_postal import gravar_recebido, guardar, guardar_pedaco
+from .carteiro import EnvioResultado, enviar
+from .lacre import (
+    JANELA_SEGUNDOS,
+    TrancaInvalida,
+    desempacotar,
+    empacotar,
+    segredo_do_ambiente,
+)
+from .recebedor import servir
+from .vizinhanca import anunciar, anunciar_em_thread, procurar
+from .frase import gerar as gerar_frase
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "enviar",
+    "EnvioResultado",
+    "puxar",
+    "listar_remoto",
+    "ErroPuxar",
+    "servir",
+    "gravar_recebido",
+    "guardar",
+    "guardar_pedaco",
+    "empacotar",
+    "desempacotar",
+    "segredo_do_ambiente",
+    "TrancaInvalida",
+    "JANELA_SEGUNDOS",
+    "anunciar",
+    "anunciar_em_thread",
+    "procurar",
+    "gerar_frase",
+]

ekodide/acervo.py

@@ -0,0 +1,84 @@
+"""O acervo do Ekodide: o lado de LEITURA que o 'puxar' expõe.
+
+Espelho do caixa_postal (que GRAVA o que chega): aqui a gente LÊ arquivos de dentro
+de uma pasta COMPARTILHADA — com a mesma cerca, e um cuidado a mais. Um ponto de
+leitura é poder; então só se lê de dentro do que foi explicitamente compartilhado, e:
+
+  - travessia de caminho ('../') é descartada — nunca escapa da pasta;
+  - symlink que aponta pra FORA da pasta é recusado (o alvo real cai fora da cerca) —
+    risco que o lado de escrita não corre, mas o de leitura sim;
+  - os temporários de recebimento ('.parcial'/'.parcial.meta') NÃO entram na lista
+    (são montagem em andamento, não arquivo pra compartilhar).
+
+Lógica pura (sem rede, sem variáveis de ambiente): recebe a pasta `base` e um nome
+relativo. Quem expõe isso pela rede (HTTP) é o recebedor (rotas /listar e /buscar).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+# Mesmo tamanho de pedaço do carteiro: arquivo grande é lido/devolvido picado, e cada
+# pedaço cabe no corpo de 32 MB do recebedor mesmo depois do base64 inchar ~33%.
+PEDACO = 16 * 1024 * 1024
+
+
+def _resolver_dentro(nome: str, base: Path) -> Path:
+    """De um `nome` relativo ('Fotos/sub/img.png') devolve o caminho REAL dentro de
+    `base`, NUNCA escapando. Componentes perigosos ('', '.', '..', raiz absoluta) são
+    descartados; o resultado é resolvido (segue symlink de propósito) e conferido contra
+    a base — assim um atalho apontando pra fora é pego. Levanta ValueError se escapar."""
+    base = base.resolve()
+    rel = Path(nome)
+    if rel.is_absolute():  # caminho absoluto vira relativo (tira a raiz '/')
+        rel = Path(*rel.parts[1:])
+    partes = [p for p in rel.parts if p not in ("", ".", "..")]
+    if not partes:
+        raise ValueError("nome de arquivo inválido")
+    alvo = base.joinpath(*partes).resolve()  # resolve() segue symlink: pega fuga por atalho
+    if base != alvo and base not in alvo.parents:
+        raise ValueError("fora da pasta compartilhada")
+    return alvo
+
+
+def _e_compartilhavel(p: Path) -> bool:
+    """Arquivo comum de verdade — fora os temporários de recebimento em montagem."""
+    return p.is_file() and not p.name.endswith((".parcial", ".parcial.meta"))
+
+
+def listar(base: Path) -> list[dict]:
+    """O que dá pra puxar: lista de {'nome': caminho-relativo, 'tamanho': bytes},
+    ordenada por nome, recursiva (preserva subpastas). Pasta inexistente ou não
+    compartilhada (None) -> lista vazia: nada fica exposto sem querer."""
+    if base is None:
+        return []
+    base = Path(base).expanduser()
+    if not base.is_dir():
+        return []
+    base = base.resolve()
+    achados = []
+    for p in sorted(base.rglob("*")):
+        if _e_compartilhavel(p):
+            achados.append({"nome": p.relative_to(base).as_posix(), "tamanho": p.stat().st_size})
+    return achados
+
+
+def tamanho_de(nome: str, base: Path) -> int:
+    """Tamanho (bytes) de um arquivo compartilhado. Mesma cerca do `ler_pedaco`."""
+    alvo = _resolver_dentro(nome, Path(base).expanduser())
+    if not _e_compartilhavel(alvo):
+        raise ValueError("arquivo não disponível")
+    return alvo.stat().st_size
+
+
+def ler_pedaco(nome: str, base: Path, parte: int, partes: int) -> bytes:
+    """Lê o pedaço `parte` (de `partes`) do arquivo, cada um de até PEDACO bytes (o
+    último vem menor). Arquivo que cabe num pedaço vai inteiro com parte=0, partes=1.
+    Cerca de segurança: nunca lê fora da pasta compartilhada."""
+    if partes < 1 or parte < 0 or parte >= partes:
+        raise ValueError("índice de pedaço inválido")
+    alvo = _resolver_dentro(nome, Path(base).expanduser())
+    if not _e_compartilhavel(alvo):
+        raise ValueError("arquivo não disponível")
+    with alvo.open("rb") as f:
+        f.seek(parte * PEDACO)
+        return f.read(PEDACO)

ekodide/buscador.py

@@ -0,0 +1,102 @@
+"""O buscador do Ekodide: PUXA um arquivo de outra ponta (o inverso do carteiro).
+
+O carteiro EMPURRA (posta na /receber do outro). O buscador PUXA: pergunta o que há
+(/listar) e pede o arquivo (/buscar) da pasta que o outro compartilhou. Cada pedaço
+volta CIFRADO (cofre) e lacrado (HMAC); aqui a gente abre o lacre, decifra, e grava
+local reusando a caixa postal (mesma cerca de escrita, mesma remontagem de pedaços).
+
+Não lê variáveis de ambiente: recebe a URL e o segredo prontos, como o carteiro.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import http.client
+from pathlib import Path
+
+from cryptography.exceptions import InvalidTag
+
+from . import acervo, caixa_postal
+from .carteiro import _Linha  # mesma conexão keep-alive do empurrar (reaproveitada)
+from .cofre import decifrar
+from .lacre import TrancaInvalida, desempacotar, empacotar
+
+
+class ErroPuxar(Exception):
+    """Falha ao puxar (origem fora do ar, recusada, ou resposta fora da tranca)."""
+
+
+def listar(url: str, segredo: str) -> list[dict]:
+    """O que dá pra puxar da `url`: lista de {'nome', 'tamanho'}. Levanta ErroPuxar
+    se a origem recusar ou a resposta não abrir o lacre."""
+    linha = _Linha(url)
+    try:
+        try:
+            status, bruto = linha.postar("/listar", empacotar({}, segredo))
+        except (http.client.HTTPException, OSError) as erro:
+            raise ErroPuxar(f"não alcancei a origem ({erro})")
+        if status != 200:
+            raise ErroPuxar(f"origem recusou listar ({status}): {bruto.decode('utf-8', 'replace')}")
+        try:
+            itens = desempacotar(bruto, segredo).get("itens", [])
+        except (TrancaInvalida, binascii.Error) as erro:
+            raise ErroPuxar(f"lista fora da tranca: {erro}")
+        return itens if isinstance(itens, list) else []
+    finally:
+        linha.fechar()
+
+
+def _pedir_pedaco(
+    linha: _Linha, nome: str, parte: int, partes: int, segredo: str
+) -> tuple[bool, bytes | str]:
+    """Pede UM pedaço pela /buscar e devolve (ok, bytes-decifrados) ou (False, motivo)."""
+    carga = {"nome": nome, "parte": parte, "partes": partes}
+    try:
+        status, bruto = linha.postar("/buscar", empacotar(carga, segredo))
+    except (http.client.HTTPException, OSError) as erro:
+        return False, f"não alcancei a origem ({erro})"
+    if status != 200:
+        return False, f"origem recusou ({status}): {bruto.decode('utf-8', 'replace')}"
+    try:
+        volta = desempacotar(bruto, segredo)
+        cifrado = base64.b64decode(volta["conteudo"], validate=True)
+        return True, decifrar(cifrado, segredo)
+    except (TrancaInvalida, KeyError, binascii.Error, InvalidTag) as erro:
+        return False, f"pedaço fora da tranca: {erro}"
+
+
+def puxar(
+    nome: str, url: str, segredo: str, base: Path, tamanho: int | None = None
+) -> tuple[bool, str]:
+    """Puxa o arquivo `nome` da `url` pra dentro de `base` (lacrado/cifrado no caminho).
+    Arquivo grande vem PICADO e é remontado pela caixa postal. Se um download anterior
+    caiu no meio, RETOMA de onde parou (pula os pedaços que já estão no `.parcial` local).
+    Se `tamanho` não vier, descobre via /listar. Devolve (ok, destino-ou-motivo)."""
+    if tamanho is None:
+        try:
+            disponivel = {i["nome"]: i["tamanho"] for i in listar(url, segredo)}
+        except ErroPuxar as erro:
+            return False, str(erro)
+        if nome not in disponivel:
+            return False, f"'{nome}' não está disponível pra puxar nessa origem"
+        tamanho = int(disponivel[nome])
+
+    # acervo.PEDACO é a FONTE ÚNICA do tamanho do pedaço (servidor e cliente leem o
+    # mesmo) — ler em tempo de execução evita cópias dessincronizadas das duas pontas.
+    partes = max(1, (tamanho + acervo.PEDACO - 1) // acervo.PEDACO)
+    # RETOMADA: consulta o progresso LOCAL (eu mesmo gravo) e pula o que já baixei.
+    ja = caixa_postal.progresso_de(nome, partes, base, tamanho)
+    linha = _Linha(url)
+    destino = None
+    try:
+        for parte in range(ja, partes):
+            ok, payload = _pedir_pedaco(linha, nome, parte, partes, segredo)
+            if not ok:
+                return False, f"pedaço {parte + 1}/{partes}: {payload} (rode o pull de novo pra retomar)"
+            # grava reusando a caixa postal: mesma cerca + remontagem do empurrar.
+            destino = caixa_postal.guardar_pedaco(nome, payload, parte, partes, base, tamanho)
+    except (OSError, ValueError) as erro:
+        return False, f"não consegui gravar: {erro}"
+    finally:
+        linha.fechar()
+    return True, str(destino) if destino else "(nada veio)"

ekodide/caixa_postal.py

@@ -0,0 +1,136 @@
+"""A caixa postal do Ekodide: grava com segurança o que CHEGA pela rede.
+
+Lógica pura (sem rede, sem variáveis de ambiente): recebe uma carga já aberta
+pelo lacre e grava DENTRO de uma pasta `base` que o chamador escolhe. Um ponto de
+escrita é poder, então a pasta é cercada:
+
+  - travessia de caminho ('../') é descartada — nunca escapa da base;
+  - arquivo existente NÃO é sobrescrito (ganha sufixo ' (1)', ' (2)'…);
+  - arquivo grande chega PICADO e é remontado num '.parcial' até o último pedaço.
+
+Quem expõe isso pela rede (HTTP) é o recebedor (recebedor.py). A caixa postal só
+sabe gravar — é a parte mais reaproveitável.
+"""
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+
+def _nome_livre(base: Path, nome: str) -> Path:
+    """Um caminho que ainda não existe dentro de `base`: 'foto.png', 'foto (1).png'…
+    Nunca sobrescreve um arquivo do usuário."""
+    alvo = base / nome
+    if not alvo.exists():
+        return alvo
+    tronco, sufixo = alvo.stem, alvo.suffix
+    n = 1
+    while (base / f"{tronco} ({n}){sufixo}").exists():
+        n += 1
+    return base / f"{tronco} ({n}){sufixo}"
+
+
+def _caminho_seguro(nome: str, base: Path) -> tuple[Path, str]:
+    """De um `nome` (que pode ser caminho relativo 'Fotos/sub/img.png') devolve
+    (pasta_destino, nome_do_arquivo) DENTRO da base, NUNCA escapando dela:
+    componentes perigosos ('..', raiz absoluta) são descartados e o resultado é
+    conferido contra a base. Levanta ValueError se o nome for inválido."""
+    rel = Path(nome)
+    if rel.is_absolute():  # caminho absoluto vira relativo (tira a raiz '/')
+        rel = Path(*rel.parts[1:])
+    # descarta componentes vazios/perigosos ('', '.', '..') -> não dá pra subir de pasta
+    partes = [p for p in rel.parts if p not in ("", ".", "..")]
+    if not partes:
+        raise ValueError("nome de arquivo inválido")
+    alvo_dir = base.joinpath(*partes[:-1])
+    # cinto e suspensório: a pasta resolvida tem que ficar DENTRO da base
+    if base != alvo_dir.resolve() and base not in alvo_dir.resolve().parents:
+        raise ValueError("destino fora da pasta permitida")
+    return alvo_dir, partes[-1]
+
+
+def guardar(nome: str, conteudo: bytes, base: Path) -> Path:
+    """Grava um arquivo INTEIRO dentro de `base` (recria subpastas, sem escapar,
+    sem sobrescrever)."""
+    base = base.resolve()
+    alvo_dir, filename = _caminho_seguro(nome, base)
+    alvo = _nome_livre(alvo_dir, filename)
+    alvo_dir.mkdir(parents=True, exist_ok=True)
+    alvo.write_bytes(conteudo)
+    return alvo
+
+
+def _ler_progresso(alvo_dir: Path, filename: str, partes: int, tamanho: int) -> int:
+    """Quantos pedaços contíguos já temos no '.parcial' — lido do anotador
+    '.parcial.meta'. Só vale se o meta casar com ESTE arquivo (mesmo nº de partes e
+    mesmo tamanho total); senão devolve 0 (é outro arquivo de mesmo nome → recomeça)."""
+    parcial = alvo_dir / (filename + ".parcial")
+    meta = alvo_dir / (filename + ".parcial.meta")
+    if not (parcial.exists() and meta.exists()):
+        return 0
+    try:
+        mp, mr, mt = meta.read_text().split()
+        if int(mp) == partes and int(mt) == tamanho:
+            return max(0, min(int(mr), partes))
+    except (ValueError, OSError):
+        pass
+    return 0
+
+
+def progresso_de(nome: str, partes: int, base: Path, tamanho: int = -1) -> int:
+    """Quantos pedaços deste arquivo o destino já tem (pro carteiro RETOMAR de onde
+    parou). 0 = nada ainda / arquivo diferente. Mesma cerca de segurança do guardar."""
+    base = base.resolve()
+    alvo_dir, filename = _caminho_seguro(nome, base)
+    return _ler_progresso(alvo_dir, filename, partes, tamanho)
+
+
+def guardar_pedaco(
+    nome: str, conteudo: bytes, parte: int, partes: int, base: Path, tamanho: int = -1
+) -> Path | None:
+    """Recebe UM pedaço de um arquivo grande e vai montando num arquivo temporário
+    '.parcial', anotando o progresso no '.parcial.meta' (pra dar pra RETOMAR depois).
+    No ÚLTIMO pedaço fecha, renomeia pro nome final (sem sobrescrever), apaga o meta e
+    devolve o caminho. Enquanto monta, devolve None.
+
+    Retomada/idempotência: o pedaço já recebido é ignorado (reenvio após queda da rede
+    não corrompe); pedaço fora de ordem (pulou um) é recusado. Mesma cerca do guardar."""
+    base = base.resolve()
+    alvo_dir, filename = _caminho_seguro(nome, base)
+    alvo_dir.mkdir(parents=True, exist_ok=True)
+    parcial = alvo_dir / (filename + ".parcial")
+    meta = alvo_dir / (filename + ".parcial.meta")
+
+    recebidos = _ler_progresso(alvo_dir, filename, partes, tamanho)
+    if parte < recebidos:        # já temos esse pedaço — reenvio repetido, ignora
+        return None
+    if parte > recebidos:        # pulou um pedaço: não dá pra anexar com buraco
+        raise ValueError(f"pedaço fora de ordem (esperava {recebidos}, veio {parte})")
+
+    with parcial.open("wb" if parte == 0 else "ab") as f:
+        f.write(conteudo)
+    recebidos = parte + 1
+
+    if recebidos >= partes:  # último pedaço: vira o arquivo final
+        final = _nome_livre(alvo_dir, filename)
+        parcial.replace(final)
+        meta.unlink(missing_ok=True)
+        return final
+    meta.write_text(f"{partes} {recebidos} {tamanho}")
+    return None
+
+
+def gravar_recebido(carga: dict, base: Path) -> Path | None:
+    """Grava uma carga já desempacotada (do envelope assinado) dentro de `base`.
+    Se vier 'partes', é um arquivo grande picado (monta pedaço a pedaço; destino só
+    no último); senão é o arquivo inteiro. Levanta KeyError/ValueError em carga
+    inválida."""
+    nome = carga["nome"]
+    conteudo = base64.b64decode(carga["conteudo"], validate=True)
+    if "partes" in carga:
+        parte, partes = int(carga["parte"]), int(carga["partes"])
+        tamanho = int(carga.get("tamanho", -1))  # total do arquivo (pra travar a retomada)
+        if partes < 1 or parte < 0 or parte >= partes:
+            raise ValueError("índice de pedaço inválido")
+        return guardar_pedaco(nome, conteudo, parte, partes, base, tamanho)
+    return guardar(nome, conteudo, base)

ekodide/carteiro.py

@@ -0,0 +1,216 @@
+"""O carteiro do Ekodide: ENVIA um arquivo ou uma pasta inteira pela rede.
+
+Lacra cada bloco (HMAC) e posta na rota /receber do destino. Arquivo que cabe vai
+de uma vez; arquivo grande vai PICADO em pedaços (lidos do disco aos poucos, sem
+carregar tudo na memória) — a caixa postal do outro lado remonta. Pasta vira vários
+envios preservando as subpastas (o caminho relativo viaja junto).
+
+Devolve um EnvioResultado neutro (números e caminhos), pra quem aciona montar a
+própria resposta. Não lê variáveis de ambiente: recebe a URL e o segredo prontos.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import http.client
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .cofre import cifrar
+from .lacre import TrancaInvalida, desempacotar, empacotar
+
+TIMEOUT_S = 30  # mata o POST se a rede travar
+
+# Tamanho do PEDAÇO ao mandar um arquivo grande. Fica abaixo do corpo que o
+# recebedor aceita (32 MB), já contando que o base64 incha ~33%: 16 MB viram
+# ~21,3 MB no fio. Arquivo <= isto vai num envio só; maior, vai em pedaços.
+# Pedaço maior = menos idas-e-voltas de rede por arquivo (mais rápido), ainda
+# longe do limite de 32 MB e leve de RAM (processa um por vez).
+PEDACO = 16 * 1024 * 1024
+
+# Reenvio de UM pedaço quando a rede pisca: tenta algumas vezes com espera
+# crescente antes de desistir. Se desistir, o '.parcial' fica no destino e um
+# novo `send` RETOMA de onde parou (não recomeça do zero).
+TENTATIVAS = 4    # tentativas por pedaço (1ª + 3 reenvios)
+ESPERA_S = 1.0    # espera-base entre tentativas (cresce a cada uma)
+
+
+@dataclass
+class EnvioResultado:
+    """O que o carteiro devolve — dados crus, sem frase pronta. `ok` resume; o resto
+    deixa o chamador montar a mensagem que quiser."""
+
+    ok: bool
+    is_pasta: bool
+    total: int                       # quantos arquivos tentou enviar
+    enviados: int                    # quantos foram de fato
+    destino: str = ""                # caminho de exemplo no destino (último/único)
+    falhas: list[str] = field(default_factory=list)  # motivos, vazio = tudo ok
+
+
+class _Linha:
+    """Conexão HTTP reaproveitada (keep-alive): mantém a porta aberta e passa vários
+    pedaços pela MESMA conexão, em vez de reabrir uma a cada pedaço — corta o aperto
+    de mão de TCP repetido (mais rápido no Wi-Fi real). Reabre sozinha se a rede cair."""
+
+    def __init__(self, url: str) -> None:
+        alvo = urllib.parse.urlsplit(url)
+        self._host = alvo.hostname or "127.0.0.1"
+        self._porta = alvo.port or 80
+        self._conn: http.client.HTTPConnection | None = None
+
+    def postar(self, caminho: str, corpo: bytes) -> tuple[int, bytes]:
+        """POST de um corpo já lacrado. Devolve (status, resposta). Levanta
+        HTTPException/OSError se a rede falhar — aí a conexão é descartada pra a
+        próxima tentativa reabrir limpa."""
+        if self._conn is None:
+            self._conn = http.client.HTTPConnection(self._host, self._porta, timeout=TIMEOUT_S)
+        try:
+            self._conn.request(
+                "POST", caminho, body=corpo,
+                headers={"Content-Type": "application/json", "Content-Length": str(len(corpo))},
+            )
+            resp = self._conn.getresponse()
+            return resp.status, resp.read()
+        except (http.client.HTTPException, OSError):
+            self.fechar()
+            raise
+
+    def fechar(self) -> None:
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except OSError:
+                pass
+            self._conn = None
+
+
+def _postar(
+    linha: _Linha, nome: str, dados: bytes, segredo: str,
+    parte: int | None = None, partes: int | None = None, tamanho: int | None = None,
+) -> tuple[bool, str]:
+    """Lacra UM bloco e manda pela `linha` (rota /receber). Se `partes` vier, é um
+    PEDAÇO (índice `parte` de `partes`, com o `tamanho` total junto pra travar a
+    retomada); senão é o arquivo inteiro de uma vez. `nome` pode ser caminho relativo
+    ('Fotos/sub/img.png'). Devolve (ok, info): info é o destino (preenchido no último
+    pedaço) ou o motivo da falha."""
+    # CIFRA o conteúdo antes de mandar: na rede passa só embaralhado (o cofre). A
+    # chave sai do segredo; o destino decifra e grava byte-idêntico ao original.
+    carga = {"nome": nome, "conteudo": base64.b64encode(cifrar(dados, segredo)).decode("ascii")}
+    if partes is not None:
+        carga["parte"], carga["partes"] = parte, partes
+        if tamanho is not None:
+            carga["tamanho"] = tamanho
+    try:
+        status, bruto = linha.postar("/receber", empacotar(carga, segredo))
+    except (http.client.HTTPException, OSError) as erro:
+        return False, f"não alcancei o destino ({erro})"
+    if status != 200:
+        return False, f"destino recusou ({status}): {bruto.decode('utf-8', 'replace')}"
+    try:
+        volta = desempacotar(bruto, segredo)
+    except (TrancaInvalida, binascii.Error) as erro:
+        return False, f"resposta fora da tranca: {erro}"
+    return True, str(volta.get("destino") or "")
+
+
+def _postar_resiliente(
+    linha: _Linha, nome: str, dados: bytes, segredo: str,
+    parte: int | None = None, partes: int | None = None, tamanho: int | None = None,
+) -> tuple[bool, str]:
+    """Como `_postar`, mas reenvia os MESMOS bytes algumas vezes (espera crescente)
+    se a rede piscar. Reenviar um pedaço já gravado é inofensivo — o recebedor é
+    idempotente. Só desiste depois de TENTATIVAS falhas seguidas."""
+    info = ""
+    for tentativa in range(TENTATIVAS):
+        ok, info = _postar(linha, nome, dados, segredo, parte, partes, tamanho)
+        if ok:
+            return True, info
+        if tentativa < TENTATIVAS - 1:
+            time.sleep(ESPERA_S * (tentativa + 1))
+    return False, info
+
+
+def _ja_recebidos(linha: _Linha, nome: str, segredo: str, partes: int, tamanho: int) -> int:
+    """Pergunta ao destino quantos pedaços deste arquivo ele já tem (pra RETOMAR).
+    Qualquer erro na consulta → 0 (começa do zero, sem nunca atrapalhar o envio)."""
+    carga = {"nome": nome, "partes": partes, "tamanho": tamanho}
+    try:
+        status, bruto = linha.postar("/progresso", empacotar(carga, segredo))
+        if status != 200:
+            return 0
+        volta = desempacotar(bruto, segredo)
+        return max(0, min(int(volta.get("recebidos", 0)), partes))
+    except (http.client.HTTPException, OSError, TrancaInvalida, binascii.Error, ValueError):
+        return 0
+
+
+def _enviar_arquivo(origem: Path, nome: str, url: str, segredo: str) -> tuple[bool, str]:
+    """Envia UM arquivo por UMA conexão reaproveitada (keep-alive). Se couber num
+    pedaço, vai de uma vez; se for grande, vai PICADO (lendo do disco aos pedaços, sem
+    carregar tudo na memória). Pergunta ao destino o que ele já tem e RETOMA de onde
+    parou; cada pedaço é reenviado se a rede piscar. Devolve (ok, info)."""
+    tamanho = origem.stat().st_size
+    linha = _Linha(url)
+    try:
+        if tamanho <= PEDACO:
+            return _postar_resiliente(linha, nome, origem.read_bytes(), segredo)
+
+        partes = (tamanho + PEDACO - 1) // PEDACO
+        inicio = _ja_recebidos(linha, nome, segredo, partes, tamanho)  # RETOMA daqui
+        destino = ""
+        with origem.open("rb") as f:
+            if inicio:
+                f.seek(inicio * PEDACO)  # pula os pedaços que o destino já tem
+            for i in range(inicio, partes):
+                bloco = f.read(PEDACO)   # lê UMA vez; o reenvio usa estes mesmos bytes
+                ok, info = _postar_resiliente(linha, nome, bloco, segredo, i, partes, tamanho)
+                if not ok:
+                    return False, f"pedaço {i + 1}/{partes}: {info} (rode o `send` de novo pra retomar)"
+                destino = info or destino
+        return True, destino or "(montado no destino)"
+    finally:
+        linha.fechar()
+
+
+def _enviar_pasta(raiz: Path, url: str, segredo: str) -> EnvioResultado:
+    """Percorre a pasta e envia cada arquivo preservando a estrutura (o nome da
+    pasta + subpastas viram o caminho relativo). Arquivo grande vai picado."""
+    arquivos = sorted(x for x in raiz.rglob("*") if x.is_file())
+    if not arquivos:
+        return EnvioResultado(ok=True, is_pasta=True, total=0, enviados=0)
+
+    enviados, falhas, exemplo = 0, [], ""
+    for arq in arquivos:
+        rel = Path(raiz.name) / arq.relative_to(raiz)  # 'Fotos/sub/img.png'
+        try:
+            ok, info = _enviar_arquivo(arq, str(rel), url, segredo)
+        except OSError as erro:
+            falhas.append(f"{rel} (não li: {erro})")
+            continue
+        if ok:
+            enviados += 1
+            exemplo = exemplo or info
+        else:
+            falhas.append(f"{rel} ({info})")
+
+    return EnvioResultado(
+        ok=enviados > 0, is_pasta=True, total=len(arquivos),
+        enviados=enviados, destino=exemplo, falhas=falhas,
+    )
+
+
+def enviar(origem: Path, url: str, segredo: str) -> EnvioResultado:
+    """Manda um arquivo OU uma pasta inteira pra `url` (rota /receber), lacrado com
+    `segredo`. Arquivo grande vai picado; pasta preserva as subpastas. Devolve um
+    EnvioResultado neutro — sem frase pronta, pra o chamador montar a sua."""
+    origem = Path(origem)
+    if origem.is_dir():
+        return _enviar_pasta(origem, url, segredo)
+    ok, info = _enviar_arquivo(origem, origem.name, url, segredo)  # grande vai picado
+    return EnvioResultado(
+        ok=ok, is_pasta=False, total=1, enviados=1 if ok else 0,
+        destino=info if ok else "", falhas=[] if ok else [info],
+    )