Este documento descreve todos os controles de segurança do PKD, por que existem e o que não protegem.

PKD é uma ferramenta de usuário único, auto-hospedada. O modelo de ameaça é:

• Ameaça principal: uma pessoa não autorizada tentando ler ou modificar suas notas pela rede.
• Não é ameaça: acesso físico ao servidor, sistema operacional comprometido, ou imagem Docker maliciosa.
• Ameaça parcial: outro dispositivo na mesma rede que observe o tráfego (mitigado por HTTPS via proxy reverso).

PKD não gerencia certificados TLS. Encerre TLS em um proxy reverso (Caddy, Traefik, UNRAID SWAG). Sem TLS, cookies de sessão trafegam em texto claro na LAN.

Padrão double-submit cookie:

• Em todo GET, se o cookie pkd_csrf estiver ausente, o servidor define um com 32 bytes aleatórios.
• Em toda requisição mutante (POST/PUT/DELETE/PATCH), o header X-CSRF-Token deve ser igual ao cookie pkd_csrf. Divergência → 403.
• O cookie CSRF não é HttpOnly para que o JavaScript possa lê-lo e incluí-lo no header.
• Exceção: o share_target da PWA (POST /api/capture em application/x-www-form-urlencoded com Sec-Fetch-Site: none ou same-origin) dispensa o header, porque o Android envia um form e não pode incluí-lo. Um POST cross-site continua exigindo o header, e o cookie de sessão SameSite=Strict não vai em requisições cross-site. A resposta é 303 para /#/doc/{id} da Nota criada.

Dois CSPs distintos estão em uso:

A view pública define script-src 'none' — nenhum JavaScript executa na página compartilhada. Mesmo que um payload malicioso bypass a sanitização HTML, não pode executar.

Headers em toda resposta: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Strict-Transport-Security: max-age=31536000; includeSubDomains, Permissions-Policy: interest-cohort=().

Todo HTML do editor passa pelo bluemonday antes do armazenamento e antes da renderização pública:

• EditorPolicy: permite formatação, imagens (com width inline), tabelas (incluindo colspan/rowspan inteiros positivos, para células mescladas), links (http/https/mailto), blocos de código, e text-align: left|center|right|justify inline em p/h1–h6 (extensão TipTap TextAlign). Remove event handlers, <script>, <style>, URIs javascript:, <foreignObject> SVG e qualquer outro estilo/valor fora dessas listas (ex.: position, background: url(...)).
• PublicSharePolicy: igual ao EditorPolicy, mas também remove estilos inline e atributos de dados.

Texto plano é derivado do HTML sanitizado para indexação FTS5.

Captura de conteúdo: o conteúdo recebido via /api/capture (POST JSON ou form-encoded) passa pela mesma sanitização antes de ser armazenado.

Memórias via API: o content de POST/PATCH /api/memories passa pelo mesmo EditorPolicy (ex.: <script> removido). A Data da Memória é validada no servidor (datas impossíveis como 31/02, hora sem dia, hora e Período juntos → 400).

Notas via API: o content de POST/PATCH /api/notes passa pelo mesmo EditorPolicy. POST /api/notes/{id}/convert para Memória valida a Data da Memória do mesmo jeito antes de gravar.

Documentos via API: o content de POST /api/documents passa pelo mesmo EditorPolicy. Um parent_id inexistente, de Memória ou de Nota → 400.

• 32 bytes aleatórios via crypto/rand.
• Codificados como base64url (43 caracteres).
• Hash SHA-256 armazenado em share_links.token_hash — o plaintext nunca é persistido.
• LookupByToken compara hashes com crypto/subtle.ConstantTimeCompare para prevenir timing attacks.
• Revogação: define revoked_at. O endpoint público retorna 404 para tokens revogados ou inexistentes (nunca 401 ou 410 para não vazar existência).

Quando /api/capture recebe uma URL, o servidor faz um HTTP GET externo:

• Timeout de 5 segundos.
• Corpo da resposta limitado a 1 MB.
• Operação best-effort — falha silenciosa; a captura prossegue sem metadados OG se a URL falhar.
• User-Agent identificável: PKD/2.0 (+https://github.com/edalcin/pkd).

Nota: este fetch não tem guarda SSRF (débito pré-existente). Veja seção abaixo para o fetch de imagens externas que tem proteção completa.

Os endpoints POST /api/documents/{id}/attachments/from-url e POST /api/admin/documents/{id}/import-external-images permitem que o servidor busque URLs fornecidas pelo usuário autenticado. Isso é um vetor clássico de SSRF.

A variável PKD_BASE_URL define o prefixo usado na geração de links públicos de compartilhamento. Se não definida, o servidor usa o host da requisição. Configure explicitamente em produção (ex: https://pkd.dalc.in/) para garantir que os links sejam sempre corretos, especialmente atrás de proxies reversos.

security.SafeAttachmentPath(base, stored):

1. Rejeita string vazia.
2. Rejeita null bytes.
3. Rejeita caminhos absolutos Unix (/…) e Windows.
4. Rejeita componentes ...
5. Chama filepath.Clean(filepath.Join(base, stored)) e verifica que o resultado está sob base.

• SQLite com PRAGMA foreign_keys = ON (integridade referencial).
• Modo WAL para leituras concorrentes durante backup.
• Todas as queries usam prepared statements — sem interpolação de strings em SQL.
• Arquivo de banco de dados fora do container em volume montado.

IAM mínimo para o backend S3:

{"Statement":[{
  "Effect":"Allow",
  "Action":["s3:GetObject","s3:PutObject","s3:DeleteObject",
            "s3:ListBucket","s3:DeleteObjects","s3:AbortMultipartUpload"],
  "Resource":["arn:aws:s3:::BUCKET","arn:aws:s3:::BUCKET/*"]
}]}

PresignGetObject é client-side e não requer permissão IAM adicional além de s3:GetObject (usado pelo destinatário via URL assinada).

Requer 2FA por e-mail configurado (SES_USERNAME, SES_PASSWORD, EMAIL_SENDER, EMAIL_2FA). Chave AES-256 derivada de PKD_PASSWORD via SHA-256 com contexto (security.DeriveDocKey).

Regras de acesso e invariantes:

• Proteger cifra os anexos antes do corpo; qualquer falha desfaz o parcial (best-effort) para que os dois estados casem. A flag é por anexo, então um estado parcial ainda descreve a realidade de cada blob.
• Ler, criar ou remover anexo de documento protegido exige sessão que já validou o código por e-mail (sessions.IsDocUnlocked); sem isso, 403 {"error":"unlock required"}. Reinício do servidor tranca tudo novamente.
• attachments.size_bytes e attachments.content_sha256 sempre descrevem o plaintext. O ZIP de backup guarda anexos decifrados (o manifesto indexa por hash de conteúdo) e o restore recifra o que pertence a documento protegido; a migração local↔S3 copia o ciphertext verbatim e pula a checagem de hash.
• Documento protegido não pode gerar share público (409) e links legados respondem 404, inclusive para seus anexos.
• Decifrar exige o arquivo inteiro em memória — GCM autentica o blob completo. Downloads mantêm Range/206 servindo de um buffer.
• ⚠️ Trocar PKD_PASSWORD torna corpo e anexos protegidos indecifráveis. Desproteja antes de rotacionar a senha.