diagnos

Documentação

Construa sobre o cofre diagnos

SDK, CLI e API REST zero-knowledge para o cofre diagnos: pacientes, exames e arquivos cifrados no seu processo antes de chegarem à rede.

Início rápido Referência da API
Publicado a partir do commit 4eb9d27 Editar no GitHub

Escolha seu pacote

Nota

Situação: prévia 0.1.0. Toda superfície — enrollment, sessões, assinatura de requisições, pacientes, exames, arquivos e pastas — fala o protocolo atual do cofre e é verificada contra ele pelos testes de contrato. Limites conhecidos, e as questões ainda em aberto do lado do cofre, estão em docs/COMPATIBILITY.pt-BR.md.

Nota

Ainda não está no PyPI. Até o primeiro release, instale do código-fonte — Instalação tem os comandos, e o toolchain Rust que o build precisa.

Primeiros passos

Referência

Para ir além

Começando#

1. Consiga um token. Um admin do workspace emite um token de service account no app web do diagnos:

export DIAGNOS_API_TOKEN="apikey-…"

2. Faça o enrollment. A primeira execução imprime um link e um código de 6 dígitos; um admin aprova no app web e escolhe quais security groups este processo pode ler.

from diagnos import Diagnos

with Diagnos() as vault:  # faz enrollment na entrada: imprime o link de aprovação + código
    print(vault.workspace_id)
    print(vault.security_groups)  # os grupos que o admin concedeu
diagnos login          # o mesmo enrollment, pelo terminal
diagnos status         # token, OpenBao e versão do SDK

3. Use. Pacientes, exames e arquivos pendem do mesmo objeto — vault.patients, vault.exams, vault.drives. O início rápido vai daqui até o primeiro paciente e o primeiro arquivo cifrados.

As chaves privadas nunca saem do processo e nada é gravado em disco, então o próximo processo precisa de uma nova aprovação — isso é o desenho, não uma limitação. Autenticação mostra o enrollment inteiro, e Sessões como servidores reiniciam sem humano.

O que vem de graça#

  • 🔐 Ponta a ponta por padrão — registros e arquivos são cifrados no seu processo; o cofre vê ciphertext, requisições assinadas e URLs pré-assinadas. Exatamente o que ele vê.
  • 🛡️ Híbrido pós-quântico — o enrollment usa X25519 + ML-KEM-768, então uma sessão gravada continua segura contra um adversário quântico futuro.
  • 🧱 Chaves num enclave Rust — memória travada com mlock, guard pages, fora de core dumps, zerada no fork() e ao descartar, nunca devolvida ao Python como bytes. Modelo de ameaça: apps/sdk/native/README.pt-BR.md.
  • 🔁 Retentativa e relógio resolvidos — retentativas idempotentes, sincronia de relógio com o cofre, exceções estáveis: Erros.
  • 📐 Formatos de bytes travados — docs/PROTOCOL.pt-BR.md é normativo, e vetores de teste gerados da implementação de referência do cofre travam cada byte.

Servidores sem humano#

Uma aprovação humana a cada reinício serve num notebook; não serve num pod Kubernetes. Aponte o SDK para o OpenBao e ele salva a sessão desbloqueada logo após o enrollment e a restaura a cada subida — uma troca deliberada, explicada por inteiro antes de você ligar. Manifestos prontos ficam em apps/api/deploy/: Docker Compose e Kubernetes, com auto-unseal do OpenBao para AWS KMS, Azure Key Vault, GCP KMS, Transit, Shamir e chave estática.

Documentação#

Comece aqui Depois
Início rápido · Instalação · Conceitos Autenticação · Sessões · Configuração
Pacientes · Exames · Arquivos Erros · Modelo de segurança
Guia da CLI · Guia da API REST Implantação · Protocolo · Compatibilidade

O site de desenvolvedores publica estas mesmas páginas em /dev/docs, mais uma referência gerada a partir do código — todo comando, rota e classe. Como a doc é construída e checada.

Portões de qualidade#

Todo badge acima é um workflow que você roda localmente com um comando.

Badge O que prova Localmente
Unit tests os três pacotes no CPython 3.11–3.13, mais o enclave Rust make test
Coverage cobertura de ramos combinada de diagnos, diagnos-cli e diagnos-api, com um piso que só sobe make cov
Contract tests o SDK manda e lê exatamente o que o contrato Pact commitado diz (motor Rust pact_ffi) make contract
CI lint (Python, Rust, docstrings bilíngues, documentação), mypy --strict, lockfile, e a doc: todo exemplo roda, a referência está em dia make lint types docs-check

O contrato é guiado pelo consumidor: os testes do SDK gravam contracts/diagnos-sdk-diagnos-vault.json, e o cofre verifica esse mesmo arquivo contra o código real dele antes de implantar.

flowchart LR
    SDK["Testes do SDK<br/>(mock do Pact, motor Rust)"] -->|gravam| C[("diagnos-sdk-diagnos-vault.json")]
    C -->|repetido contra| V["vault.diagnos.health<br/>verificação do provider"]

Estrutura#

integration/
├── apps/
│   ├── sdk/           diagnos          a biblioteca — tudo vive aqui
│   │   └── native/    diagnos._secure  enclave de memória em Rust
│   ├── cli/           diagnos-cli      `diagnos …` no seu terminal
│   └── api/           diagnos-api      fachada REST (FastAPI), só mTLS
│       └── deploy/    compose · k8s    manifestos prontos para rodar
├── contracts/         Pact             contrato do consumidor com o cofre + os testes dele
├── docs/              guides/          a documentação · reference/ gerada a partir do código
│                      PROTOCOL.md      formatos de bytes normativos · COMPATIBILITY.md · site.json
└── scripts/           docs/            as checagens por trás do `make lint`, do `make docs-check` e da CI

Como contribuir#

Você precisa de uv, Python 3.11–3.13 e, para construir o enclave do fonte, Rust stable.

git clone https://github.com/diagnos-tech/integration && cd integration
make sync    # instala tudo e constrói o enclave Rust
make check   # exatamente o que a CI roda: lint, tipos, testes unitários e de contrato, doc
make         # lista todos os outros alvos

Leia o CONTRIBUTING.pt-BR.md antes do primeiro pull request. Vindo dos pacotes imgexam? Veja o MIGRATING.pt-BR.md.

Segurança#

Achou uma vulnerabilidade? Por favor não abra issue pública — reporte em privado pelo GitHub Security Advisories. Detalhes no SECURITY.pt-BR.md.

Apache-2.0 · diagnos.health