Como Comprovar Estado da Técnica para Software: Um Guia para Desenvolvedores
Comprovar estado da técnica para software se resume a uma pergunta precisa: você consegue demonstrar que um commit Git específico existia em uma data específica, com evidências de que nenhum servidor interno, administrador de repositório ou terceiro pode alterar? Este guia explica exatamente como criar essa evidência sem expor seu código-fonte.
Você usará o Timestamp GIT, um serviço gerenciado e GitHub App que ancora os hashes dos seus commits Git na blockchain do Bitcoin por meio do protocolo OpenTimestamps. O fluxo de trabalho é instalar uma vez, commitar normalmente e deixar que a ancoragem noturna automatizada produza arquivos de recibo .ots imutáveis.
Ao final deste guia, você terá:
- Instalado o GitHub App nos repositórios que deseja proteger.
- Configurado onde as provas criptográficas são entregues.
- Acionado e confirmado um timestamp ancorado no Bitcoin para um commit real.
- Verificado a prova por meio de um painel público e selo.
- Solucionado os problemas mais comuns de permissão e entrega.
Pré-requisitos
Antes de começar, certifique-se de ter:
- Uma conta no GitHub e pelo menos um repositório que deseja proteger.
- Familiaridade básica com commits e hashes do Git. Você não precisa de experiência com criptografia ou blockchain.
- Uma conta no Timestamp GIT. Repositórios públicos usam o plano gratuito; repositórios privados exigem o plano Pro Agency por US$ 49/mês ou Enterprise ZK por US$ 199/mês.
- Opcional: Docker se você planeja auto-hospedar o Timestamp GIT em um ambiente isolado ou corporativo.
Passo a Passo: Configurando o Timestamp GIT
O caminho gerenciado não exige nada nas suas máquinas de desenvolvimento. Você instala o GitHub App uma vez, seleciona os repositórios e cada commit é então ancorado no Bitcoin automaticamente todas as noites.
Passo 1: Cadastre-se e Conecte o GitHub
Acesse Timestamp GIT e entre com sua conta do GitHub. O fluxo SaaS gerenciado é o caminho padrão.
Se você estiver auto-hospedando, comece com o início rápido do Docker Compose:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
Em seguida, execute:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
O aplicativo auto-hospedado está disponível em http://localhost:8080. No primeiro lançamento, um assistente de configuração orienta você na conexão do seu GitHub App e na aplicação de um arquivo de licença.
Passo 2: Instale o Timestamp GIT GitHub App
Instale o GitHub App nos repositórios que deseja proteger.
No modo padrão, o Timestamp GIT precisa de acesso somente leitura ao repositório de origem. Isso não ocorre porque ele lê seu código—ele apenas lê o hash do commit HEAD—mas porque o sistema de permissões do GitHub não expõe um nível de acesso somente de hash.
Se as provas forem entregues a um repositório de destino separado, o aplicativo também precisará de acesso de leitura e gravação a esse repositório de destino.
Passo 3: Selecione os Repositórios a Monitorar
No painel do Timestamp GIT, abra a página Seus Repositórios e selecione os repositórios que deseja monitorar.
Cada repositório selecionado é adicionado ao pipeline de provas noturno. O Timestamp GIT não inspeciona o conteúdo dos arquivos, o código-fonte ou o conteúdo das branches além dos hashes de commit necessários para a ancoragem.
Passo 4: Configure a Entrega das Provas
Para cada repositório monitorado, escolha onde as provas criptográficas devem ser gravadas:
- Uma branch de timestamp dedicada dentro do mesmo repositório.
- Um repositório sombra separado, que pode ser privado mesmo que o repositório de origem seja público.
O Timestamp GIT grava arquivos de manifesto e recibos .ots nesse local após a ancoragem diária ser confirmada.
Passo 5: Opcional: Ative o Modo Enterprise ZK
Para equipes que exigem acesso zero ao código-fonte, o modo Enterprise ZK é um modelo de implantação mais robusto.
Durante a configuração, o Timestamp GIT gera um fluxo de trabalho do GitHub Action de 12 linhas. Você adiciona esse arquivo gerado ao seu repositório em:
.github/workflows/timestampgit.yml
A action é executada na sua própria infraestrutura, não nos sistemas do Timestamp GIT. Ela envia apenas o hash do commit para a API do Timestamp GIT. Nesse modo, o Timestamp GIT não precisa de nenhum acesso de leitura ao repositório de origem—apenas acesso de leitura e gravação ao repositório de destino onde as provas são entregues.
Passo 6: Faça um Commit para Acionar o Processo
Uma vez que o monitoramento esteja configurado, faça commit e push normalmente:
git add .
git commit -m "feat: add payment webhook handler"
git push origin main
No modo padrão, o GitHub App detecta o novo hash do commit HEAD automaticamente. No modo Enterprise ZK, o GitHub Action envia o hash do seu ambiente de CI.
Passo 7: Aguarde a Ancoragem Noturna no Bitcoin
O Timestamp GIT agrupa hashes de commit pendentes em uma fila em memória. Todas as noites, um worker:
- Agrupa os hashes pendentes por repositório.
- Cria arquivos de manifesto diários.
- Constrói uma árvore de Merkle a partir dos hashes de commit.
- Cria provas OpenTimestamps usando calendários OTS públicos.
- Ancora a raiz de Merkle na blockchain do Bitcoin.
A confirmação no Bitcoin normalmente leva cerca de 3 horas. Após a confirmação, o manifesto e os arquivos de recibo .ots são enviados para a branch de timestamp ou repositório sombra configurado.
Como Confirmar que Funcionou
Uma vez que a execução noturna seja concluída, você pode verificar a prova de várias maneiras.
1. Inspecione a Branch de Timestamp
Busque a branch de timestamp e confirme que os arquivos de manifesto e recibos .ots estão presentes:
git fetch origin timestamps
git ls-tree -r --name-only origin/timestamps | head
O nome exato da branch depende da sua configuração, mas o sinal importante é a presença de arquivos .ots pareados com dados de manifesto diários.
2. Use a Página de Verificação Pública
O Timestamp GIT fornece uma página de verificação baseada em navegador onde todo o cálculo da cadeia de Merkle acontece localmente no seu navegador:
https://timestampgit.dev/verification/{user}/{repo}/{date}
Substitua {user}, {repo} e {date} pelo seu repositório e a data que deseja verificar.
3. Verifique a API de Status
Você pode confirmar o último bloco de Bitcoin ancorado por meio do endpoint de status público:
curl https://timestampgit.dev/api/statusLast/acme/widget-api
A resposta inclui as informações do último bloco de Bitcoin ancorado para o repositório.
4. Baixe um Certificado em PDF
Para um dia específico, baixe um certificado em PDF de:
https://timestampgit.dev/api/report/{user}/{repo}/{date}
O livro-razão de auditoria do repositório também está disponível como CSV:
https://timestampgit.dev/api/audit/{user}/{repo}
5. Incorpore um Selo de Verificação
O painel do Timestamp GIT fornece URLs de selo e trechos de Markdown prontos para copiar e colar no seu README. Repositórios privados anexam um HMAC criptografado às URLs do selo para que apenas visualizadores autorizados possam ver as informações de status.
O selo leva a uma página de verificação pública onde qualquer pessoa pode inspecionar a prova. O arquivo .ots em si permanece um recibo OpenTimestamps padrão, portanto auditores técnicos também podem baixá-lo e verificá-lo independentemente contra a blockchain do Bitcoin usando ferramentas OpenTimestamps padrão.
Solução de Problemas Comuns
Nenhuma prova após 24 horas
Verifique as permissões do GitHub App. O modo padrão precisa de pelo menos acesso somente leitura ao repositório de origem. Confirme também que o repositório ainda está selecionado no painel do Timestamp GIT.
O status do repositório privado não está visível
Repositórios privados usam URLs assinadas com HMAC. Certifique-se de que o selo ou link de status venha do painel do Timestamp GIT e inclua o parâmetro HMAC. O HMAC é específico da instância do servidor que o gerou.
A action Enterprise ZK não está entregando provas
Verifique se o arquivo de fluxo de trabalho gerado está presente em .github/workflows/timestampgit.yml e se o GitHub Action está instalado no repositório. O repositório de destino onde as provas são entregues deve ter acesso de leitura e gravação a partir da configuração da sua action.
A instância Docker auto-hospedada não está produzindo timestamps
Confirme se o arquivo de licença foi enviado durante o assistente de configuração. Verifique também se a instância tem a conectividade de rede necessária para o OAuth do GitHub App e a ancoragem de timestamps.
A verificação da prova falha
Certifique-se de que está verificando o arquivo .ots e a data corretos. Um recibo de um repositório e data não validará um commit de um dia ou repositório diferente.
Perguntas Frequentes
P: O que é estado da técnica em software?
R: Estado da técnica é a evidência de que sua invenção, como código, um algoritmo ou um design, existia antes de uma determinada data. Normalmente é usado para invalidar reivindicações de patente ou comprovar autoria.
P: Como a ancoragem no Bitcoin comprova o estado da técnica?
R: O hash do seu commit Git é incorporado em uma transação Bitcoin por meio do protocolo OpenTimestamps. Uma vez confirmado em um bloco, o timestamp é imutável e verificável por qualquer pessoa, provando que o hash existia naquele momento.
P: O Timestamp GIT é gratuito para projetos de código aberto?
R: Sim. O Timestamp GIT oferece um plano gratuito para repositórios públicos. Repositórios privados exigem um plano pago, seja Pro Agency ou Enterprise ZK.
P: Posso usar o Timestamp GIT sem expor meu código-fonte?
R: Sim. No modo padrão, apenas os hashes de commit são lidos—não o código-fonte. No modo Enterprise ZK, um GitHub Action envia apenas hashes da sua própria infraestrutura, portanto o código-fonte nunca sai do seu ambiente.
P: Quanto tempo leva para um timestamp ser confirmado?
R: O worker noturno agrupa e ancora os hashes após a meia-noite. A confirmação no Bitcoin normalmente leva cerca de 3 horas após a transação de ancoragem, então espere que os arquivos de prova .ots apareçam logo depois disso.
Conclusão
O histórico do Git por si só não é uma evidência forte de estado da técnica porque pode ser editado, excluído ou descartado como interessado. Um recibo OpenTimestamps ancorado no Bitcoin é matematicamente mais difícil de ignorar.
O Timestamp GIT torna isso prático para desenvolvedores em atividade: instale o GitHub App uma vez, selecione um repositório e continue commitando normalmente. Ancoragem noturna, entrega de provas, selos, certificados em PDF e CSVs de auditoria são tratados automaticamente. Você nunca precisa executar comandos OpenTimestamps ou interagir manualmente com a blockchain do Bitcoin.
Comece com repositórios públicos gratuitamente em Timestamp GIT.
Posts relacionados
- Como Proteger Seu Software de Trolls de Patentes
- Pule a CLI: Uma Maneira Melhor de Timestamp Commits do Git
- Timestamp de Git Auto-Hospedado com Docker: Um Guia
