labsign 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,108 @@
+# labsign
+
+Sign PDFs with your own signature without leaving Claude, Codex or the terminal. Local, no account, no cloud.
+
+[Português](README.md)
+
+You say "sign this contract". A screen opens: you draw your signature (or pick a saved one), drag it into place and confirm. A signed copy appears next to the original. Nobody edits the document and you don't have to ask the AI to redo anything. Your signatures stay on your computer, like on the iPhone.
+
+## What it does
+
+- **Draw** with a mouse, trackpad or finger. You can hold and drag (the default) or use click-to-write (one click puts the pen down, another lifts it). Three pen sizes and three inks: navy, blue and black.
+- **Signature set:** save as many as you like, reuse the last one with a click, delete the ones you no longer need.
+- **Real preview:** the PDF page is shown with the signature on top. Drag it, resize it (keyboard works too), change page or remove it. What you see is what ends up in the PDF.
+- **Finds the spot:** looks for the text of your signature block (e.g. `CONTRATANTE`, `Signature`) and proposes the line right above it. If it isn't found, it proposes the last page and you drag.
+- **Never touches the original:** writes `contract.assinado.pdf` (or `.assinado-2.pdf`…) and never overwrites anything. Saves incrementally, so digital signatures already in the PDF stay valid.
+- **Evidence record:** for each signature, it logs the date and time and the SHA-256 of the original and the signed file, in a hash-chained log.
+- **Send or keep:** after signing, download, show in folder, share (Mail, Messages, AirDrop… where the system allows), email (Gmail or your app) or WhatsApp. For email and WhatsApp the message opens ready to go, and you attach the PDF.
+- **English and Portuguese:** the screen follows your system language.
+
+## Install
+
+### Claude Desktop
+
+1. Download `labsign-<version>.mcpb` from Releases, or build it yourself (see [Development](#development)).
+2. Double-click it (or drag it into **Settings → Extensions**) and click **Install**.
+3. In a conversation, ask: _"sign the contract at ~/Downloads/contract.pdf"_. If you only attached the PDF to the conversation, say _"I want to sign this PDF"_: the screen asks you to drop the file on it, because Claude doesn't hand attachments to extensions.
+
+The screen opens inside the conversation in Claude Desktop versions that support MCP Apps, and in the browser otherwise. If Claude Desktop asks for Node.js, install the LTS version from [nodejs.org](https://nodejs.org).
+
+### Claude Code
+
+For now, from the source (installing straight from GitHub comes with the npm release):
+
+```bash
+git clone <repository> labsign && cd labsign
+npm ci && npm run mcpb
+claude plugin marketplace add "$(pwd)"
+claude plugin install labsign@labsign
+```
+
+The plugin brings the MCP server and a skill that teaches Claude Code how to use labsign. Claude Code runs in the terminal, so the screen opens in the browser.
+
+### Codex
+
+```bash
+codex mcp add labsign -- node /path/to/labsign/dist/labsign.js mcp
+cp -R /path/to/labsign/plugin/skills/labsign ~/.agents/skills/
+```
+
+Codex stops tools after 60 seconds, so labsign answers within 45 seconds and then follows the signing through `labsign_status`.
+
+### Terminal (and any other app)
+
+```bash
+npm ci && npm run build && npm link   # from the source: creates the labsign command
+labsign sign contract.pdf --anchor Signature
+```
+
+| Command | What it does |
+| --- | --- |
+| `labsign sign <file.pdf> [--anchor TEXT]` | Opens the screen to sign and waits until you finish |
+| `labsign sign` | Opens the screen asking for the PDF (drop the file on it) |
+| `labsign add` | Opens the screen to draw and save signatures |
+| `labsign list` | Lists saved signatures (names only) |
+| `labsign doctor` | Checks the setup and prints the exact command to connect each app. Changes nothing |
+| `labsign mcp` | MCP server (stdio), for apps that speak MCP (Cursor, etc.) |
+
+Requires Node.js 22.13 or newer.
+
+### Configuration (optional)
+
+| Variable | What for |
+| --- | --- |
+| `LABSIGN_HOME` | Vault folder (default: `~/.labsign`) |
+| `LABSIGN_OUTPUT_DIR` | Where the signed copy of a PDF dropped on the screen goes (default: `~/Downloads`) |
+| `LABSIGN_LANG` | `pt` or `en`, in the terminal and on the screen |
+| `LABSIGN_BROWSER` | Program that opens the screen instead of the default browser |
+| `LABSIGN_NO_OPEN=1` | Opens no browser or folder: the terminal prints the link for you to open |
+| `LABSIGN_UI` | `auto` (default), `inline` or `browser`: forces where the screen shows up in chat apps |
+
+## Privacy and security
+
+- **Everything happens on your computer.** The screen is served on `127.0.0.1`, on a random port, through a one-time link. Nothing goes to the internet and there is no telemetry.
+- **labsign never shows your signature to the AI.** It only opens the screen and gets the result (the signed file's name). The link that opens the screen goes straight to your browser; the screen's internal tools require a token that only the screen receives.
+- **Nothing is signed without your click.** An agent with terminal access (Claude Code, Codex) runs as you: see the limits in [SECURITY.md](SECURITY.md).
+- **Vault in `~/.labsign`**, readable only by your user: the signatures (the strokes), preferences and `audit.log`.
+
+Details and limits in [SECURITY.md](SECURITY.md).
+
+## Legal note
+
+labsign produces a simple electronic signature: the image of your signature on the PDF, plus an evidence record (date and time, SHA-256 of the original and the signed file). Whether that is enough depends on your jurisdiction and on what the parties accept. It is not a certificate-based (qualified/advanced) digital signature. This is not legal advice.
+
+## Development
+
+```bash
+npm ci
+npm run build       # dist/labsign.js (CLI + MCP) and dist/ui.html, dist/ui-app.html (the screen)
+npm test            # build + tests (needs Node 24; poppler is optional and enables pixel checks)
+npm run typecheck
+npm run mcpb        # dist/labsign-<version>.mcpb and plugin/server/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. Bundled libraries and their licenses are listed in `dist/THIRD_PARTY_LICENSES.txt`.

package/README.md

@@ -0,0 +1,119 @@
+# labsign
+
+Assine PDFs com a sua própria assinatura sem sair do Claude, do Codex ou do terminal. Local, sem conta, sem nuvem.
+
+[English](README.en.md)
+
+Você diz "assina esse contrato". Abre uma tela, você desenha a assinatura (ou escolhe uma já salva), arrasta até o lugar certo e confirma. Sai uma cópia assinada ao lado do original. Ninguém edita o documento e você não precisa pedir para a IA refazer nada. As assinaturas ficam guardadas no seu computador, como no iPhone.
+
+## O que ele faz
+
+- **Desenhar:** com mouse, trackpad ou dedo. Dá para segurar e arrastar (padrão) ou usar o clique para escrever (um clique abaixa a caneta, outro levanta). Há três espessuras de caneta e três tintas: azul-marinho, azul e preta.
+- **Pacote de assinaturas:** salve quantas quiser, use a última com um clique e apague as que não servem mais.
+- **Prévia de verdade:** a página do PDF aparece com a assinatura por cima. Dá para arrastar, redimensionar (também pelo teclado), trocar de página ou tirar a assinatura dali. O que você vê é o que sai no PDF.
+- **Acha o lugar sozinho:** procura o texto do bloco de assinatura (ex.: `CONTRATANTE`) e propõe a posição logo acima. Se não achar, propõe a última página e você arrasta.
+- **Não estraga o original:** gera `contrato.assinado.pdf` (ou `.assinado-2.pdf`…) e nunca sobrescreve nada. Salva de forma incremental, então assinaturas digitais que já existiam no PDF continuam válidas.
+- **Registro de evidências:** para cada assinatura, grava a data e a hora e o SHA-256 do original e do assinado num log encadeado por hash.
+- **Enviar ou guardar:** depois de assinar, você pode baixar o arquivo, mostrá-lo na pasta, compartilhar (Mail, Mensagens, AirDrop…, quando o sistema permite), enviar por e-mail (Gmail ou o seu app) ou mandar pelo WhatsApp. No e-mail e no WhatsApp, a mensagem abre pronta e você anexa o PDF.
+- **PT e EN:** a tela segue a língua do seu sistema.
+
+## Instalar
+
+### Claude Desktop
+
+1. Baixe o `labsign-<versão>.mcpb` na página de Releases, ou gere o arquivo você mesmo (veja [Desenvolvimento](#desenvolvimento)).
+2. Dê dois cliques no arquivo (ou arraste-o em **Configurações → Extensões**) e clique em **Instalar**.
+3. Numa conversa, peça: _"assina o contrato que está em ~/Downloads/contrato.pdf"_. Se você só anexou o PDF na conversa, diga _"quero assinar esse PDF"_: a tela vai pedir para você soltar o arquivo nela, porque o Claude não repassa anexos para extensões.
+
+A tela abre dentro da conversa nas versões do Claude Desktop que suportam MCP Apps. Nas outras, abre no navegador. Se o Claude Desktop pedir Node.js, instale a versão LTS em [nodejs.org](https://nodejs.org).
+
+### Claude Code
+
+Por enquanto, a partir do código (a instalação direto do GitHub vem com a publicação no npm):
+
+```bash
+git clone <repositório> labsign && cd labsign
+npm ci && npm run mcpb
+claude plugin marketplace add "$(pwd)"
+claude plugin install labsign@labsign
+```
+
+O plugin traz o servidor MCP e a skill que ensina o Claude Code a usar o labsign. Como o Claude Code roda no terminal, a tela abre no navegador.
+
+### Codex
+
+```bash
+codex mcp add labsign -- node /caminho/do/labsign/dist/labsign.js mcp
+cp -R /caminho/do/labsign/plugin/skills/labsign ~/.agents/skills/
+```
+
+O Codex corta as ferramentas em 60 segundos. Por isso o labsign responde em até 45 segundos e depois acompanha a assinatura pelo `labsign_status`.
+
+### Terminal (e qualquer outro app)
+
+```bash
+npm ci && npm run build && npm link   # a partir do código: cria o comando labsign
+labsign sign contrato.pdf --anchor CONTRATANTE
+```
+
+| Comando | O que faz |
+| --- | --- |
+| `labsign sign <arquivo.pdf> [--anchor TEXTO]` | Abre a tela para assinar e espera você terminar |
+| `labsign sign` | Abre a tela pedindo o PDF (você solta o arquivo nela) |
+| `labsign add` | Abre a tela para desenhar e salvar assinaturas |
+| `labsign list` | Lista as assinaturas salvas (só os nomes) |
+| `labsign doctor` | Confere o ambiente e mostra o comando exato para conectar cada app. Não altera nada |
+| `labsign mcp` | Servidor MCP (stdio), para apps que falam MCP (Cursor etc.) |
+
+Requer Node.js 22.13 ou mais novo.
+
+### Configuração (opcional)
+
+| Variável | Para quê |
+| --- | --- |
+| `LABSIGN_HOME` | Pasta do cofre (padrão: `~/.labsign`) |
+| `LABSIGN_OUTPUT_DIR` | Onde fica a cópia assinada de um PDF solto na tela (padrão: `~/Downloads`) |
+| `LABSIGN_LANG` | `pt` ou `en`, no terminal e na tela |
+| `LABSIGN_BROWSER` | Programa que abre a tela, no lugar do navegador padrão |
+| `LABSIGN_NO_OPEN=1` | Não abre navegador nem pasta: o terminal mostra o link para você abrir |
+| `LABSIGN_UI` | `auto` (padrão), `inline` ou `browser`: força onde a tela aparece nos apps de chat |
+
+## Privacidade e segurança
+
+- **Tudo acontece no seu computador.** A tela é servida em `127.0.0.1`, numa porta aleatória, por um link de uso único. Nada vai para a internet e não há telemetria.
+- **O labsign não mostra a sua assinatura à IA.** Ela só abre a tela e recebe o resultado (o nome do arquivo assinado). O link que abre a tela vai direto para o seu navegador; as ferramentas internas da tela exigem um token que só a tela recebe.
+- **Nada é assinado sem o seu clique.** Um agente com acesso ao terminal (Claude Code, Codex) roda como você: veja os limites em [SECURITY.md](SECURITY.md).
+- **Cofre em `~/.labsign`**, com permissões só para o seu usuário: as assinaturas (os traços), as preferências e o `audit.log`.
+
+Detalhes e limites em [SECURITY.md](SECURITY.md).
+
+## Validade jurídica (Brasil)
+
+O labsign faz uma assinatura eletrônica simples: a imagem da sua assinatura no PDF, mais o registro de evidências (data e hora, SHA-256 do original e do assinado). Entre particulares, ela vale quando as partes aceitam esse meio (MP 2.200-2/2001, art. 10, § 2º). Não é assinatura com certificado digital ICP-Brasil. Se o ato exige certificado (alguns atos com órgãos públicos, registros e cartórios), use um. Isto não é aconselhamento jurídico.
+
+## Desenvolvimento
+
+```bash
+npm ci
+npm run build       # dist/labsign.js (CLI + MCP) e dist/ui.html, dist/ui-app.html (a tela)
+npm test            # build + testes (precisa do Node 24; o poppler é opcional e ativa as checagens de pixel)
+npm run typecheck
+npm run mcpb        # dist/labsign-<versão>.mcpb e plugin/server/
+```
+
+| Pasta | Conteúdo |
+| --- | --- |
+| `src/core` | assinatura (traços → contornos), posicionamento, carimbo no PDF, âncoras, cofre, sessões |
+| `src/http` | servidor local da tela (só `127.0.0.1`) |
+| `src/mcp` | servidor MCP: tela embutida (MCP Apps) ou página no navegador |
+| `src/ui` | a tela: um HTML único, sem dependências externas em tempo de execução |
+| `src/cli` | comandos `sign`, `add`, `list`, `doctor`, `mcp` |
+| `src/i18n` | textos em PT e EN |
+| `plugin/` | plugin do Claude Code e skill (também serve para o Codex) |
+| `mcpb/` | manifest e ícone da extensão do Claude Desktop |
+
+Veja [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licença
+
+MIT. As bibliotecas embutidas e as licenças delas estão em `dist/THIRD_PARTY_LICENSES.txt`.

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Segurança · Security
+
+## Como reportar · Reporting
+
+Encontrou uma falha? Abra um aviso privado no GitHub (**Security → Report a vulnerability**) em vez de uma issue pública. Respondemos o quanto antes.
+
+Found a vulnerability? Please open a private advisory on GitHub (**Security → Report a vulnerability**) instead of a public issue.
+
+## O que o labsign protege
+
+O labsign é uma ferramenta local. Ele guarda desenhos de assinatura, que são dados pessoais sensíveis (provavelmente biométricos, pela LGPD), e escreve PDFs em seu nome. A regra é que só você, na tela do labsign, assina, e ninguém mais lê as suas assinaturas.
+
+| Ameaça | Defesa |
+| --- | --- |
+| **Outro site aberto no navegador** tenta falar com o servidor local (CSRF, DNS rebinding) | Escuta só em `127.0.0.1`, em porta aleatória. Recusa `Host` diferente de `127.0.0.1:<porta>`, `Origin` de fora e `Sec-Fetch-Site` que não seja da própria página. Depois da abertura, vale um cookie `HttpOnly; SameSite=Strict` da sessão mais um token de visualização. CSP com nonce por resposta (sem `'unsafe-inline'` para scripts), `frame-ancestors 'none'`, `no-referrer`, `nosniff`, `no-store` |
+| **A IA ou um prompt injection** tenta assinar sozinho ou ler a assinatura | O link que abre a tela (com o token de uso único) vai direto para o seu navegador ou para o app de chat, por elicitação. O modelo recebe só um endereço sem token, que não abre nada fora do navegador que já abriu a tela. O link com token só vai para o modelo repassar quando não há navegador para abrir. No terminal, o `labsign sign` só imprime o link com token quando o navegador não abriu. As ferramentas internas da tela exigem um token que só a tela recebe. Confirmar exige o clique da pessoa. Nenhuma ferramenta devolve o desenho |
+| **Link vazado** (histórico, print, outra pessoa na máquina) | Cada pedido abre uma vez só: outro navegador recebe 409 e fica no log de auditoria. Sem o token, o endereço só reabre no navegador que abriu primeiro (cookie). O pedido expira em 30 minutos |
+| **Sobrescrever ou estragar o documento** | O original nunca é alterado. A cópia assinada é criada com `wx`, que falha em vez de sobrescrever. O salvamento é incremental: o original é prefixo exato do assinado, e assinaturas digitais anteriores continuam válidas. PDFs criptografados são recusados logo na abertura |
+| **Duplo clique, duas abas, cancelar no meio** | Uma confirmação por vez. O status é conferido de novo antes de gravar: pedido cancelado ou expirado durante o carimbo não gera arquivo. Encerrado, o pedido não muda mais nem mexe no cofre |
+| **Outros usuários do mesmo computador** | `~/.labsign` com `0700` e os arquivos com `0600` |
+| **PDF malicioso** | O PDF.js 6 não usa `eval` nem `new Function`, e nada do PDF é executado. PDFs enviados pela tela têm limite de 30 MB e precisam começar com `%PDF-`; danificados ou com senha (mesmo só de permissões) são recusados ao abrir, com erro próprio. O nome do arquivo recebido é limpo (sem separadores, sem `..`) antes de virar o nome da cópia assinada. Traços recebidos da tela são validados (números finitos, quantidade limitada). Erros inesperados vão só para o stderr, nunca com detalhes para a tela ou para o modelo |
+| **Esgotar memória ou encher a tela de abas** | No máximo 20 pedidos abertos ao mesmo tempo. O PDF sai da memória 1 h depois de encerrado o pedido. Corpo das requisições limitado (30 MB o PDF, 5 MB o resto) |
+| **Adulteração do histórico** | `audit.jsonl` encadeado por SHA-256: cada evento carrega o hash do anterior, e `labsign doctor` confere a cadeia. Gravações de processos diferentes (o app de chat e o terminal ao mesmo tempo) passam por uma trava de arquivo |
+
+## Limites (o que ele NÃO garante)
+
+- **O log é evidente, não inviolável.** Quem tem acesso à sua conta no computador pode reescrever a cadeia inteira. O log mostra que o histórico foi mexido; não impede.
+- **O PDF assinado carrega a imagem da sua assinatura.** Quem recebe o arquivo pode copiá-la, como acontece com qualquer papel assinado e escaneado. Mande só para quem deve receber.
+- **Não é certificado digital.** Não substitui uma assinatura ICP-Brasil (ou qualificada/avançada em outros países) quando a lei exige.
+- **Um agente com terminal roda como você.** Claude Code, Codex e o Claude Desktop com extensões de terminal executam comandos com as suas permissões. Um agente mal-intencionado, ou enganado por um documento (prompt injection), pode ler `~/.labsign` e os PDFs que você já assinou, como qualquer programa seu. O labsign não entrega à IA o link da tela nem o desenho, mas isso não é barreira contra um agente decidido a burlar. Revise os comandos que o agente pede para rodar e desconfie de qualquer um que mexa em `~/.labsign` ou chame `127.0.0.1`.
+- **Programas rodando como você** (malware, extensões) podem ler `~/.labsign`, como leriam qualquer arquivo seu.
+- **Sem criptografia em repouso** na v1. O cofre depende das permissões do sistema e da criptografia de disco (FileVault, BitLocker…).
+
+## Cadeia de entrega
+
+- Cada artefato é um arquivo só (`dist/labsign.js`, `dist/ui.html`, `dist/ui-app.html`), montado do código-fonte pelo `npm run build`, sem nada baixado em tempo de execução. As bibliotecas embutidas e as licenças estão em `dist/THIRD_PARTY_LICENSES.txt`.
+- `npm audit` sem vulnerabilidades no lançamento; o Dependabot acompanha as dependências e as actions da CI, que são fixadas por hash do commit.
+- O código do protótipo (Fase 0) não está no repositório: ele entregava ao modelo o link que abre a tela.
+- Ao instalar um `.mcpb` ou um pacote do npm, confira que veio da página de Releases ou do pacote `labsign` oficial. O SHA-256 do `.mcpb` é publicado em cada Release.
+
+## Rede
+
+O labsign não faz nenhuma chamada de rede. O servidor local só atende `127.0.0.1`. Os botões "Abrir no Gmail" e "Abrir o WhatsApp" só abrem o seu navegador ou app, e quem envia é você.