Manual do Safe8bit

Tudo o que a app e o comando safe8bit fazem, com exemplos. As secções marcadas Pro precisam da licença; o resto é grátis no Lite.

Instalar

O Safe8bit precisa do macOS 15 ou mais recente. A app é assinada e notarizada pela Apple e o download é o mesmo para o Lite e para o Pro.

$ brew trust safe8bit-app/tap
$ brew install --cask safe8bit-app/tap/safe8bit

O Homebrew instala a app em /Applications e o comando safe8bit no terminal. Também podes usar o botão Descarregar e arrastar a app para Aplicações. Nesse caso, o comando para pôr o safe8bit no terminal está em Definições › Terminal (CLI).

Para atualizar: brew upgrade --cask safe8bit. O cofre não é tocado.

Criar o cofre

1. Abre o Safe8bit. No ecrã Criar o teu cofre, escolhe uma palavra-passe mestra com pelo menos 12 caracteres e confirma-a.
2. Deixa ligado Desbloquear com Touch ID (Secure Enclave) para abrires o cofre com a impressão digital.
3. Carrega em Criar cofre.
4. Logo a seguir, cria o kit de emergência.

Se já usas o Safe8bit noutro Mac com o iCloud ligado, o ecrã mostra Há um cofre Safe8bit no teu iCloud. Carrega em Usar o cofre do iCloud e abre-o com a mesma palavra-passe mestra.

O Touch ID fica associado às impressões digitais que estão registadas no Mac. Se juntares ou apagares uma, voltas a precisar da palavra-passe mestra uma vez.

Ativar o Pro

1. Compra o Pro em safe8bit.com/comprar. A chave chega por email, de licencas@safe8bit.com; se não aparecer, procura no lixo ou no spam.
2. Na app, vai a Definições › Licença.
3. Cola a chave (começa por SBL1.) e carrega em Ativar.

A chave é verificada no Mac, sem internet. Vale até ao fim do período pago mais 7 dias, e a cada renovação chega uma chave nova para colares no mesmo sítio (Atualizar). A mesma chave serve em todos os teus Macs.

A janela

A barra lateral tem estas secções:

Em baixo estão as Definições (⌘,) e o cadeado Bloquear o cofre (⌘L). O cofre também bloqueia sozinho ao fim do tempo que escolheres, ao adormecer o Mac, ao bloquear o ecrã e ao trocar de utilizador. As janelas do Safe8bit não aparecem em capturas nem em partilhas de ecrã.

Projetos

Cada segredo pertence a um projeto. Cria-o em Projetos › Novo projeto e escolhe nome, cor e ícone.

No topo de um projeto tens Editar, Usar no código e Adicionar. Com o botão direito num projeto, Editar… ou Eliminar…. Eliminar um projeto apaga todos os segredos dele, e isso não se pode desfazer.

Usar no código mostra como ler as variáveis em Node, Python, Ruby, Deno e Swift, o comando safe8bit run já pronto, um texto para dares a um agente de IA, e os botões para copiar o .env de produção ou montar o .env sem disco.

Segredos e campos

Ao criar um segredo escolhes o tipo, e ele já vem com os campos certos:

• + Campo junta campos do tipo Texto, Segredo, Multilinha ou URL. Se um campo visível parecer uma chave, a app sugere Tornar Segredo.
• Anexo: arrasta um ficheiro até 4 MB. No segredo podes copiar o conteúdo ou Guardar como….
• Validade: Nunca, 90 dias, 6 meses, 1 ano ou uma data. O Radar avisa 14 dias antes.
• Etiquetas (separadas por vírgulas) e Notas.
• Histórico: guarda as últimas 10 versões, sempre que um valor sensível muda. Restaurar… volta a uma delas.
• Num .env tens ainda Copiar como .env, Exportar .env… e Separar variáveis.

Ao copiar um valor, ele sai da área de transferência ao fim de 30 segundos (podes mudar nas Definições), a não ser que entretanto tenhas copiado outra coisa. Os gestores de área de transferência são avisados para não o guardar.

Ambientes e variáveis

Cada segredo pode ter um ambiente: Nenhum, Dev, Staging ou Prod. Os segredos sem ambiente são a base: entram em todos os ambientes, e os do ambiente escolhido sobrepõem-se a eles.

Para um campo chegar ao terminal, dá-lhe um nome de variável. No editor do segredo, cada campo tem uma pastilha $ à direita do nome: escreve lá STRIPE_SECRET_KEY, por exemplo. Só são aceites maiúsculas, algarismos e _. Deixa vazio para o campo não ser exportado. No segredo, o nome aparece como $STRIPE_SECRET_KEY.

Para dar nomes a muitos campos de uma vez, abre Usar no código › Campos sem variável e carrega em Aplicar nomes.

Depois, no terminal: safe8bit run -e prod -- npm start. Ver Terminal.

Códigos 2FA

No editor do segredo, carrega em Código 2FA e escolhe uma destas formas:

• cola o link otpauth://… ou a chave de configuração que o site te dá;
• Colar QR: tira uma captura do QR para a área de transferência com ⌃⇧⌘4 e cola;
• Imagem com QR…: escolhe uma imagem com o QR.

Aparece logo o código atual. Os códigos ficam também na secção Códigos 2FA: clica num para o copiar. Copiar um campo 2FA copia sempre o código, nunca a semente. São aceites códigos de 6 a 8 dígitos, com SHA1, SHA256 ou SHA512.

Quando copias a palavra-passe de uma Credencial que tem 2FA, recebes uma notificação com Copiar código. Durante 2 minutos, ⌃⇧Espaço abre já nesse código. A área de transferência nunca é trocada sem tu pedires. Desliga em Definições › Acesso rápido.

AutoFill e passkeys

Para o Safe8bit preencher logins no Safari e nas apps:

1. Vai a Definições › AutoFill e carrega em Abrir Definições do Sistema.
2. Em Geral › Preenchimento automático e palavras-passe, liga o Safe8bit.

O AutoFill preenche as Credenciais (o campo URL decide em que site aparecem), os códigos 2FA de qualquer segredo e as passkeys. Pede sempre Touch ID ou a palavra-passe mestra; nunca preenche em silêncio.

Sugerir logins automaticamente no Safari vem desligado. Se o ligares, os utilizadores e os domínios (nunca as palavras-passe) passam a estar num índice do sistema, fora do cofre, para o Safari os sugerir.

Passkeys

Quando um site (o GitHub, por exemplo) te oferecer criar uma passkey, escolhe o Safe8bit. Ela fica no projeto Passkeys. Para entrar, o site pede a passkey e tu confirmas com Touch ID. As passkeys não podem ser partilhadas.

Acesso rápido

⌃⇧Espaço abre uma pesquisa por cima de qualquer app. Procura no título, no projeto e nas etiquetas.

• ↩ copia o valor principal e volta à app onde estavas;
• ↑ ↓ escolhem o resultado;
• os botões de cada linha copiam outro campo: palavra-passe, código 2FA, utilizador, chave pública ou .env;
• esc fecha.

Se o cofre estiver bloqueado, pede para o desbloquear primeiro. O atalho não se pode mudar, mas podes desligá-lo em Definições › Acesso rápido.

Gerador

Mostra os bits de entropia do que gerou. No editor de um segredo, o botão Gerar abre o gerador e Usar põe o valor no campo.

Radar de rotação

Mostra cada segredo pela idade (anéis aos 30 dias, 90 dias e 1 ano) e assinala os que precisam de atenção:

Filtra por todos, só prod ou com alertas. Abrir vai ao segredo. Num valor repetido de propósito, Está ok deixa de avisar. Para rodar uma chave recusada: gera uma nova no serviço, cola-a no segredo e confirma com safe8bit test. A análise é toda feita no Mac.

Detetor e importação

Detetor

Na secção Detetor, escolhe uma pasta (por exemplo ~/Development) e carrega em Procurar. Encontra segredos esquecidos em claro:

• .env e variantes (os modelos como .env.example ficam de fora);
• chaves .p8, .p12, .pfx, .pem, .key, .jks e .keystore;
• chaves SSH (id_rsa, id_ed25519, …) e JSON de service accounts;
• *.properties de assinatura e segredos, .sentryclirc, *secret*.xcconfig e notas .txt que parecem segredos.

Ignora node_modules, .git, Pods, build e afins. Na revisão escolhes o que guardar e em que projeto, e vês o que já está no cofre. Se quiseres, os originais vão para o Lixo depois de importados.

Importar de outro gestor

Em Adicionar › Importar de outro gestor, escolhe o ficheiro exportado: CSV do Apple Passwords, Chrome, Firefox, 1Password ou Bitwarden, ou JSON do Bitwarden (não cifrado). Os logins tornam-se Credenciais (com o 2FA, se existir), as notas tornam-se Notas seguras e as pastas tornam-se projetos. Os duplicados são saltados. Cartões e identidades não são importados.

Partilhas Pro para criarLite para abrir

Para dar um segredo a alguém sem o colar num chat:

1. No segredo, carrega no ícone de partilha (Partilhar num ficheiro cifrado).
2. Escolhe a validade: 1 hora, 1 dia ou 7 dias.
3. Criar ficheiro… cria um ficheiro .safe8bit e mostra a passphrase (SBSH-…). Envia o ficheiro por AirDrop, Slack ou email, e a passphrase por outro canal.

Vão os campos, o anexo e as notas. Ficam de fora o histórico, o projeto e as etiquetas. Passkeys e chaves SSH não se partilham. A passphrase não fica guardada em lado nenhum.

Quem recebe abre o ficheiro com duplo clique, ou em Adicionar › Abrir partilha, cola a passphrase e carrega em Guardar no cofre. Por omissão, fica no projeto Partilhados e o ficheiro vai para o Lixo. Abrir funciona no Lite. Depois da validade, o ficheiro é recusado.

iCloud

Em Definições › iCloud, liga Sincronizar o cofre pelo iCloud. O cofre vai já cifrado para o teu iCloud: a Apple só vê dados cifrados. Nos outros Macs, abre o Safe8bit e escolhe Usar o cofre do iCloud.

• A palavra-passe mestra e o kit de emergência servem em todos os Macs. O Touch ID configura-se em cada um.
• Se dois Macs mudarem o cofre ao mesmo tempo, as alterações juntam-se segredo a segredo. Ganha a edição mais recente, e a outra fica no histórico.
• Se o iCloud já tiver um cofre diferente, escolhes entre Usar o do iCloud neste Mac (o local fica guardado como cópia de segurança) e Substituir o do iCloud por este.

Kit de emergência

É a única forma de recuperar o cofre se esqueceres a palavra-passe mestra. Cria-o em Definições › Kit de emergência › Criar kit de emergência….

1. A app gera uma chave de recuperação (SBRK-…) e mostra-a uma única vez.
2. Imprime-a ou guarda o PDF, e põe-no num sítio seguro, longe do Mac.
3. Marca Guardei a chave num sítio seguro e carrega em Concluir.

Para recuperar: no ecrã de bloqueio, carrega em Perdeste a palavra-passe? Usar o kit de emergência, escreve a chave (maiúsculas, espaços e hífenes não contam) e escolhe uma palavra-passe mestra nova.

Criar um kit novo invalida o anterior. O kit protege contra esquecer a palavra-passe, não contra perder o Mac: para isso, usa o Time Machine ou o iCloud.

Definições

Terminal: como funciona Pro

O Homebrew instala o comando safe8bit junto com a app. Cada comando abre o cofre só para esse pedido e pede o Touch ID (ou a palavra-passe mestra, se não houver Touch ID). Os valores nunca aparecem no ecrã, a não ser que os peças com read, otp ou env.

De onde vêm as variáveis

Um projeto dá variáveis ao terminal de duas formas:

• Segredos do tipo .env: o conteúdo inteiro entra como está.
• Campos com nome de variável: na app, dás a um campo um nome como STRIPE_SECRET_KEY e esse campo passa a ser a variável STRIPE_SECRET_KEY.

Primeiro entram os segredos sem ambiente (a base), depois os do ambiente que escolheste com -e. Se a mesma variável aparecer nos dois, ganha a do ambiente.

Que projeto é usado

Sem -p, o safe8bit procura um projeto com o nome da pasta atual, ou de uma pasta acima. Em ~/Development/Loja/apps/web, encontra o projeto Loja e escolhe o .env de apps/web, se existir. Com -p Loja escolhes o projeto à mão.

Opções comuns

safe8bit run

Corre um comando com as variáveis do projeto no ambiente. Não fica nenhum .env no disco, e o safe8bit dá lugar ao teu comando, por isso nenhuma cópia do cofre fica em memória.

$ safe8bit run -e prod -- npm start
safe8bit: 6 variáveis de Loja · Prod (Stripe + Supabase + .env)
$ safe8bit run -p Loja -e dev -- python manage.py runserver

Tudo o que vem depois de -- é o teu comando, tal como o escreverias.

safe8bit env

Escreve o .env do projeto no ecrã ou num ficheiro, para as ferramentas que só sabem ler um ficheiro.

$ safe8bit env -e prod -o .env.production
# exporta para a shell atual
$ eval "$(safe8bit env -e dev --export)"

safe8bit mount

Cria o .env como um pipe: quem o abre recebe as variáveis do projeto, mas nada fica gravado no disco. Pede o Touch ID uma vez.

# monta ./.env até Ctrl-C
$ safe8bit mount -e dev
# desmonta sozinho daqui a 8 horas
$ safe8bit mount config/.env --for 8h
# lista o que está montado
$ safe8bit mounts
# desmonta os da pasta atual
$ safe8bit unmount

Funciona com quem abre e lê o ficheiro: python-dotenv 1.1 ou mais recente, dotenv (Node) e docker compose. O Next.js e o Vite recusam pipes; aí usa safe8bit run -- npm run dev.

unmount e mounts funcionam sem licença, para poderes sempre desfazer um mount.

safe8bit read e safe8bit otp

Escrevem um valor ou o código 2FA atual. A referência é safe8bit://Projeto/Segredo/Campo.

$ safe8bit read "safe8bit://Loja/Supabase/API Key"
$ safe8bit read "safe8bit://Loja/App Store Connect/anexo" -o AuthKey.p8
$ safe8bit otp safe8bit://Loja/GitHub

O campo anexo (ou attachment) devolve o ficheiro anexado ao segredo, como uma chave .p8. Com -o, o ficheiro fica com permissões 600.

safe8bit list

Mostra projetos, segredos e os nomes das variáveis, nunca os valores. É seguro para correr à frente de outras pessoas ou de um agente de IA.

$ safe8bit list -p Loja
Stripe  [API Key] prod
    API Key → $STRIPE_SECRET_KEY, Webhook → $STRIPE_WEBHOOK_SECRET
apps/web/.env  [Ficheiro .env] dev
    DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL

safe8bit test

Pergunta a cada serviço se as chaves do projeto ainda funcionam, com um pedido só de leitura e sem custo. Conhece a OpenAI, a Anthropic, o Stripe, o GitHub, a Vercel e o Supabase.

$ safe8bit test
  ✓ Stripe › API Key
  ~ OpenAI › API Key: sem quota
  ✗ GitHub › Token: recusada (401)

Depois de rodar uma chave na app, confirma a nova com safe8bit test -p PROJETO -s SEGREDO.

safe8bit push

Envia as variáveis do projeto (as mesmas do run) para as Environment Variables da Vercel: prod vai para Production, staging para Preview e dev para Development.

# mostra o que mudava
$ safe8bit push --to vercel -e prod --dry-run
$ safe8bit push --to vercel -e prod

• Cria as variáveis que faltam e atualiza as que já existem. Nunca apaga variáveis na Vercel.
• Uma variável que na Vercel é partilhada por vários ambientes é separada: os outros ambientes ficam com o valor que tinham.
• Antes de enviar, testa as chaves como o safe8bit test. Se algum serviço recusar uma chave, não envia nada.
• O projeto e a equipa da Vercel vêm do .vercel/project.json (o que o vercel link cria). O token vem do segredo Vercel do projeto ou, se não houver, de outro projeto.

safe8bit license

Diz se o Pro está ativo, de quem é a licença e até quando vale. Funciona sempre, com ou sem licença.

$ safe8bit license
Versão: Pro, licença de ana@exemplo.pt válida até 13 Nov 2027.

Sem licença ou com ela expirada, os comandos Pro param e dizem onde ativar ou renovar.

Guarda do git Pro bloqueiaLite regista

Um hook de pre-commit compara as linhas novas de cada commit com os valores do cofre. Se encontrar um, o Pro bloqueia o commit antes de a chave chegar ao GitHub. No Lite, avisa e deixa passar.

# no repositório atual
$ safe8bit guard install
# em todos os repositórios dessa pasta
$ safe8bit guard install ~/Development
$ git commit -m "config"
1 valor do cofre neste commit. Commit bloqueado.

A Guarda não abre o cofre a cada commit, por isso não pede Touch ID. Usa um índice com impressões (HMAC-SHA256) dos valores, com uma chave que só o Secure Enclave deste Mac consegue derivar. Os valores não ficam no índice, e valores com menos de 8 caracteres não entram.

Escudo para agentes de IA Pro bloqueiaLite regista

Liga-se aos hooks do Claude Code e do Cursor e vê cada pedido do agente antes de ele o fazer:

• bloqueia ler .env, chaves e ficheiros de credenciais;
• bloqueia ler ficheiros que contêm valores do cofre e escrever esses valores no código;
• pergunta-te antes de comandos que mostram segredos, como printenv ou safe8bit read.

No Lite, o Escudo regista o que teria bloqueado e deixa o agente continuar.

# nos agentes que encontrar (~/.claude, ~/.cursor)
$ safe8bit shield install
# só no Claude Code
$ safe8bit shield install --claude
# agentes protegidos e últimos bloqueios
$ safe8bit shield status
$ safe8bit shield uninstall

safe8bit shield scan

Procura chaves esquecidas nas instruções e nas configurações dos agentes: CLAUDE.md, AGENTS.md, .mcp.json e os ficheiros de configuração do Claude, do Cursor, do Codex e do Gemini.

$ safe8bit shield scan ~/Development

Agente SSH Pro

As chaves SSH ficam no cofre e nunca saem dele. Cada ssh ou git push pede o teu Touch ID, mesmo com a app fechada.

1. Em Agente SSH (ou Definições › Agente SSH), liga Usar as chaves do Safe8bit (ssh, git). Se o macOS pedir, autoriza o Safe8bit em Itens de início de sessão.
2. Carrega em Nova chave e escolhe Gerar chave Ed25519 ou Importar ficheiro…. São aceites Ed25519, ECDSA P-256 e RSA; chaves com passphrase não.
3. Copia a configuração que a app mostra para o ~/.ssh/config. Fica assim:

Host *
  IdentityAgent "~/Library/Group Containers/8H697DPSV4.com.erik.safebit/agent.sock"

4. Põe a chave pública no GitHub (ou no servidor) e testa: ssh -T git@github.com.

Em Pedir Touch ID escolhes a frequência: Sempre (por omissão), uma vez a cada 15 minutos, 1, 4 ou 8 horas, ou até bloquear o ecrã. Por omissão, as aprovações esquecem-se ao bloquear o ecrã ou adormecer. O pedido diz que app quer usar que chave.

Sem licença Pro, o agente continua a correr mas não oferece chaves.

Lite e Pro

Sem licença, ou com ela expirada, o cofre e os segredos continuam todos lá. safe8bit license, unmount e mounts funcionam sempre. Ver preços.

Segurança

• Cifra: o cofre é um único ficheiro cifrado com AES-256-GCM. A chave deriva da palavra-passe mestra com Argon2id (256 MiB de memória, 4 passagens). Não há metadados em claro: sem a palavra-passe nem os nomes dos projetos se leem.
• Touch ID: a chave do cofre fica protegida pelo Secure Enclave do Mac e só sai com a tua impressão digital.
• Quase sem rede: a app não tem telemetria. Uma vez por dia lê safe8bit.com/appcast.xml para ver se há versão nova (desliga-se em Definições › Bloqueio › Atualizações); a atualização só se instala quando carregas em Instalar, e tem de vir assinada pelo Safe8bit. Fora isso, só o safe8bit test e o safe8bit push contactam os serviços que tu escolhes.
• Onde está: ~/Library/Group Containers/8H697DPSV4.com.erik.safebit/Library/Application Support/SafeBit/vault.sbv, com permissões 600. O Time Machine faz cópia dele, já cifrado.
• No ecrã: as janelas não aparecem em capturas nem em partilhas de ecrã. O terminal nunca mostra valores, a não ser os que pedes com read, otp ou env.

Perguntas

Como passo o cofre para um Mac novo?

Liga o iCloud nos dois Macs (Definições › iCloud) e, no Mac novo, escolhe Usar o cofre do iCloud. Sem iCloud, copia o vault.sbv para o mesmo sítio no Mac novo (ou restaura-o do Time Machine) e abre-o com a palavra-passe mestra.

O safe8bit run diz que não encontra o projeto.

O nome da pasta não coincide com o de nenhum projeto. Usa -p NOME, ou muda o nome do projeto para o da pasta. safe8bit list mostra os nomes dos projetos.

O projeto não tem variáveis.

O terminal só vê segredos do tipo .env e campos com nome de variável. Ver Ambientes e variáveis.

O Next.js ou o Vite ignoram o .env montado.

Recusam pipes. Usa safe8bit run -- npm run dev.

Posso usar o safe8bit num script ou no CI?

No teu Mac, sim: sem Touch ID disponível, usa --password-stdin. Em servidores de CI não, porque o cofre vive no Mac. Para a Vercel, usa o safe8bit push.

O que acontece quando o Pro expira?

A app volta ao Lite. Os segredos ficam todos, os comandos Pro param, e a Guarda e o Escudo continuam a correr, mas só registam.

Ainda tenho dúvidas.

Escreve para suporte@safe8bit.com.