wendkeep 0.87.0 → 0.88.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.88.0] — 2026-08-29
+
+### Added
+
+- **Políticas oficiais e RBAC do Observer por projeto.** Captura de transcripts, uso, memória e
+  sync passa por policy única, redaction por classe/campo e matriz explícita de papéis e scopes;
+  tokens são armazenados somente por hash, escopados, expirados, revogáveis e rotacionáveis.
+- **Ciclo de vida auditável.** Retenção e purge idempotentes ficam disponíveis por CLI e endpoint,
+  com receipts retriáveis, tratamento de chegadas tardias e reconciliação segura do índice FTS.
+
+### Security
+
+- **Criptografia fail-closed no Observer.** Quando exigida, ingestão, outbox e publicação recusam
+  plaintext; o backfill protege dados legados antes de leituras, e backups de migração v5 usam
+  AES-256-GCM, manifest de integridade, permissões restritas e restore autenticado.
+- **Bootstrap remoto sem credencial irrestrita.** Server, MCP, CLI e Compose usam o registry
+  hash-only com projeto, papel, scopes e expiração explícitos, incluindo revogação e rotação.
+
 ## [0.87.0] — 2026-08-29
 
 ### Added

package/README.en.md

@@ -261,7 +261,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 | **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
-| **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
+| **Local Observer** | `observer serve`, scoped/expiring hash-only bootstrap, incremental publishing with canonical timestamps, `reconcile`, policy, stable structural identities, content-bound hashes, deletion-safe capture, required encryption, retention, purge, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) · [Security](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer-security.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),

package/README.md

@@ -261,7 +261,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 | **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
-| **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
+| **Local Observer** | `observer serve`, scoped/expiring hash-only bootstrap, incremental publishing with canonical timestamps, `reconcile`, policy, stable structural identities, content-bound hashes, deletion-safe capture, required encryption, retention, purge, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) · [Security](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer-security.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),

package/docs/en/commands/observer-security.md

@@ -0,0 +1,154 @@
+# Observer security
+
+**English** · [Português](../../pt-BR/commands/observer-security.md)
+
+## Purpose
+
+The Observer is a local/team read model, never a new authority over the Vault, specs, memory, or
+sync. Its threat model assumes a compromised remote host, stolen token, curious operator, copied
+database/outbox, adversarial payload, and interrupted purge. Host/Origin validation remains active;
+mutations and sensitive reads fail closed, including on loopback.
+
+| Class | Default | Primary risk |
+|---|---|---|
+| document | `metadata` | full memory/decisions |
+| transcript | `metadata` | conversation and tools |
+| prompt/response | `redacted` | PII and secrets |
+| usage | `aggregate` | cost and operational identity |
+| audit/receipt | minimal metadata | deleting the proof itself |
+
+Policy v1 restricts by class, `project_id`, path glob, and `entity_type`. Later rules win only in
+the matching project. Redaction covers Bearer values, URL/connection-string credentials, access
+keys, email, phone, and safe configurable regular expressions. Its schema is
+`schema/observer-policy-v1.schema.json`.
+With `transcript_capture: messages`, arrays, JSONL, and the canonical `{messages:[...]}` envelope
+retain only `user|assistant|system` messages with string `role`/`content` after redaction; extra
+fields, tool records, and malformed entries are dropped or fail closed.
+Explicit policy is the publisher's sole capture authority; `WENDKEEP_OBSERVER_CAPTURE_LEVEL` is
+only translated into policy for legacy callers that supplied no policy file, and can never elevate
+or suppress explicit `none|metadata|messages|full` or `selected` documents.
+For document/transcript upserts, `content_hash` always binds the final content after capture and
+redaction; metadata/selected capture uses the SHA-256 of empty content. Document deletions remain
+effective even when content capture is `none`, preserve their path/revision/operation metadata,
+and never carry stale content or content hashes.
+Redaction never rewrites validated structural identity fields such as project/event/entity IDs,
+logical paths, revisions, or operations. Path privacy is enforced fail-closed by project/path
+capture rules; it is not implemented by renaming a storage key through a content-redaction rule.
+The per-event structural contract also preserves accepted snake/camel aliases, document/session/
+agent/call/transcript/rollup keys, timestamps, roles, status, coverage, model/pricing dimensions,
+workflow, and source provenance. `title`, `summary`, `agent_name`, content, prompt/response, and
+metadata remain redactable display/content fields.
+During incremental publishing, missing or blank turn timestamps inherit the batch's canonical
+instant, numeric epoch milliseconds are normalized to ISO 8601, and invalid non-empty values fail
+closed before policy/store; the event and payload use the same instant.
+
+## When to use
+
+Use it before enabling Observer for real data, registering or revoking credentials, restricting
+capture, protecting SQLite/outbox, defining retention, or deleting data with verifiable proof.
+
+## When not to use
+
+Do not use it as a corporate KMS/secret manager, to publish Vault/runtime data, to replace local
+authority, or to delete tables and indexes manually. `full` capture remains opt-in and subject to
+policy/redaction.
+
+## Prerequisites
+
+Use Node.js 22.13+, keep the bind on loopback, and inject tokens/keys only through environment
+variables. The bootstrap token is registered hash-only with explicit projects and a finite expiry;
+it is not a registry-bypassing wildcard admin. For Docker, also set
+`WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS`, `WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT`, and a 32-byte
+hex/base64 `WENDKEEP_OBSERVER_ENCRYPTION_KEY`. The operator owns the key and external receipts.
+
+## Syntax
+
+```bash
+npx wendkeep observer serve --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--bootstrap-token-id <id>] [--require-loopback-auth] [--require-encryption]
+npx wendkeep observer security token create --project-id <project> --role <role> --scopes <scopes> --token-env <env> --expires-at <ISO>
+npx wendkeep observer security token rotate --project-id <project> --token-id <id> --token-env <env> --expires-at <ISO> [--new-token-id <id>]
+npx wendkeep observer security token revoke --project-id <project> --token-id <id>
+npx wendkeep observer security policy set --project-id <project> --file <policy.json>
+npx wendkeep observer security policy show --project-id <project>
+npx wendkeep observer security purge --project-id <project> --before <ISO> --classes <classes> [--dry-run]
+npx wendkeep observer security retention run --project-id <project> [--dry-run] [--operation-id <id>]
+```
+
+## Options and exit codes
+
+- `viewer` reads metadata/aggregates; `auditor` may receive sensitive scopes; `publisher` ingests;
+  `admin` manages policy, purge, and recovery. Role, scope, and project must authorize together.
+- Tokens persist only as SHA-256; expiry, rotation, and revocation take effect without restart.
+- After rotating bootstrap credentials, update both token and token ID in the environment; restart
+  never reactivates an expired or revoked predecessor.
+- `--token-env` names the variable holding the secret; the command never prints its value.
+- `--require-loopback-auth` protects the whole API; sensitive reads require a token without it too.
+- `--require-encryption` fails when external key material is missing or invalid.
+- `WENDKEEP_OBSERVER_REQUIRE_ENCRYPTION=1` applies the same fail-closed behavior to `status`,
+  `security`, `register`, `publish`, and `reconcile`; with a configured key, every first v5 upgrade
+  creates only `.bak.enc` plus its manifest before any read/backfill.
+- Exit `0` means the operation completed; exit `1` means invalid configuration, authorization,
+  policy, key, or operation. The hook retains fail-open exit `0` for the local workflow, but aborts
+  before persisting unsafe content.
+
+Audit stores capability, outcome, route, and time, never a Bearer value, prompt, response, or payload.
+
+## Examples
+
+Explicit audited offline recovery:
+
+```powershell
+$env:OBSERVER_RECOVERY_TOKEN = '<strong-temporary-secret>'
+npx wendkeep observer security token create --data-dir C:\WendKeepObserver `
+  --project-id project-a --role admin --scopes '*' --token-env OBSERVER_RECOVERY_TOKEN `
+  --expires-at 2026-09-29T12:00:00Z --reason 'offline recovery' --json
+npx wendkeep observer security token revoke --data-dir C:\WendKeepObserver `
+  --project-id project-a --token-id <id> --reason 'recovery complete' --json
+```
+
+Always dry-run purge first. The retention runner is explicit and idempotent (CLI or
+`POST /v1/projects/:id/security/retention`), with no hidden timer:
+
+```powershell
+npx wendkeep observer security purge --data-dir C:\WendKeepObserver `
+  --project-id project-a --before 2026-08-01T00:00:00Z `
+  --classes documents,calls,transcripts --dry-run --json
+```
+
+```powershell
+npx wendkeep observer security retention run --data-dir C:\WendKeepObserver `
+  --project-id project-a --operation-id scheduled-2026-08-29 --dry-run --json
+```
+
+## Expected result
+
+TTL is independent for documents, calls, and transcripts. Counts, projection/FTS removal, events,
+and receipt share one transaction; retry is idempotent and late old data creates new proof.
+
+AES-256-GCM uses project/class/record/field AAD and an external `keyProvider`. The v6 backfill
+removes plaintext and derived indexes before reads; a wrong key fails without disclosing content.
+Structural migration `006-observer-security.sql` creates a backup, checks checksum, rolls back, and
+supports retry. In required at-rest mode the backup is `.bak.enc`, carries a manifest/key ID and
+restrictive permissions, fails restore with a wrong key, and leaves no plaintext `.bak` behind.
+
+The hook applies metadata/redacted policy by default; `WENDKEEP_OBSERVER_POLICY_FILE` selects an
+explicit policy. `WENDKEEP_OBSERVER_OUTBOX_KEY_ENV` names the outbox key variable and
+`WENDKEEP_OBSERVER_OUTBOX_KEY_ID` identifies the key. Compose requires authentication and
+encryption. The dashboard keeps Bearer only in memory, exports a sanitized copy, and exposes
+Security. MCP requires scopes for calls/full search. Sync carries only `policy_ref`, without
+duplicating tokens or authority.
+
+## Common errors and diagnosis
+
+- `observer_token_missing|expired|revoked`: create/rotate a scoped token or use offline recovery.
+- `observer_project_forbidden|role_forbidden|scope_forbidden`: check project/role/scope intersection.
+- `observer_encryption_key_unavailable|observer_decryption_failed`: check key ID/material; never
+  weaken required mode.
+- `observer_policy_invalid`: validate fields/captures and remove invalid or explosive regexes.
+- v6 migration failure: preserve `.pre-006-*.bak.enc` and its manifest, correct the cause, and retry.
+
+## Next steps
+
+Read [Local Observer](observer.md), dry-run retention, validate revoked/expired tokens, and keep the
+receipt outside the database when external proof is required. Never publish the database, backup,
+outbox, key, token, or `/data`.

package/docs/en/commands/observer.md

@@ -26,7 +26,9 @@ WendKeep hooks.
 
 Use Node.js 22.13 or newer for the SQL Observer. Keep Core and the remaining commands continue to
 support Node.js 18 or newer. Explicitly register each project and set `WENDKEEP_OBSERVER_TOKEN`;
-loopback reads remain open, while every mutation requires a Bearer token.
+every mutation and every sensitive-content read requires a Bearer token, including on loopback.
+Metadata and aggregates may remain locally open when `--require-loopback-auth` is omitted. See
+[Observer security](observer-security.md).
 
 ## Syntax
 
@@ -36,7 +38,7 @@ npx wendkeep observer register --project <project> --vault <vault> --data-dir <d
 npx wendkeep observer publish --project <project> --vault <vault> --data-dir <directory>
 npx wendkeep observer reconcile --project <project> --vault <vault> --data-dir <directory> [--url http://127.0.0.1:8787]
 npx wendkeep observer memory import --project <project> --vault <vault> --url http://127.0.0.1:8787 --token <token> --json
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory> --token <token>
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory> --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--require-loopback-auth] [--require-encryption]
 ```
 
 ## Options and exit codes
@@ -46,7 +48,13 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 - `--project` and `--vault` identify a project for `register`, `publish`, `reconcile`, and `memory import`.
 - `--host` accepts only `127.0.0.1`, `localhost`, or `::1`; other hosts are rejected before
   listening.
-- `--token` or `WENDKEEP_OBSERVER_TOKEN` authenticates mutations; `--allow-non-loopback` fails without one.
+- `--token` or `WENDKEEP_OBSERVER_TOKEN` supplies hash-only bootstrap material; explicit projects
+  and finite expiry are required, and all mutations/sensitive reads go through the registry;
+  `--allow-non-loopback` fails without one.
+- `--require-loopback-auth` also requires Bearer for local metadata and aggregates and enables the
+  project's secure ingestion policy.
+- `--require-encryption` requires a 32-byte hex/base64 `WENDKEEP_OBSERVER_ENCRYPTION_KEY`; use
+  `WENDKEEP_OBSERVER_ENCRYPTION_KEY_ID` to identify the external key.
 - `WENDKEEP_OBSERVER_CAPTURE_LEVEL` accepts `metadata` (default, no messages), `messages`, or
   `full-transcript`. Absolute local paths are never published.
 - Exit `0` means success; exit `1` means configuration or operation failure; the publisher hook
@@ -57,7 +65,10 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 ```powershell
 npx wendkeep observer register --project C:\GitHub\WendKeep --vault C:\GitHub\WendKeep\.WendKeep-vault --data-dir C:\WendKeepObserver
 $env:WENDKEEP_OBSERVER_TOKEN = '<strong-local-token>'
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS = 'project-a'
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT = '2026-09-29T12:00:00Z'
+$env:WENDKEEP_OBSERVER_ENCRYPTION_KEY = '<32-bytes-in-hex-or-base64>'
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN --require-loopback-auth
 $env:WENDKEEP_OBSERVER_URL = 'http://127.0.0.1:8787'
 ```
 
@@ -67,15 +78,19 @@ For local Docker:
 docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
 ```
 
+Compose requires token, bootstrap allowlist/expiry, and key material; it starts with full
+authentication and required encryption. An `encryption_required` policy refuses plaintext ingest/outbox.
+
 ## Local web dashboard
 
 With the server running, open [http://127.0.0.1:8787/](http://127.0.0.1:8787/) in a browser. The
-dashboard is served by the same process and opens directly for reads, without a form or token. Keep the port
-bound to the computer loopback; do not expose this address on a network interface.
+dashboard is served by the same process. Enter the token in the local form: it remains only in page
+memory, is sent as Bearer for queries, and is discarded on reload. Keep the port bound to the
+computer loopback; do not expose this address on a network interface.
 
 The dashboard shows the multi-project list, version, health, latest session, active change, change
 count, and last capture time. Opening a project exposes Overview, Consumption, Sessions, Memory,
-Changes, and Sync screens. Consumption shows total cost, token categories, primary agents,
+Changes, Sync, and Security screens. Consumption shows total cost, token categories, primary agents,
 subagents, providers, models, daily trend, historical coverage, and calls with prompt, response,
 and transcript content according to the selected capture level. Loading, empty, unavailable-server, conflict, no-pricing, and stale-data
 states are visible, with manual refresh and an automatic 15-second refresh.
@@ -160,18 +175,21 @@ complete, archive, repair, or promote state.
 - `POST /v1/projects/:project_id/ingest` — idempotent batches of documents, sessions, agents,
   rollups, calls, and transcripts.
 - `GET /v1/projects/:project_id/memory/tree` — document tree and metadata.
-- `GET /v1/projects/:project_id/memory/document?path=...` — complete Markdown content.
+- `GET /v1/projects/:project_id/memory/document?path=...` — complete Markdown content; requires Bearer.
 - `GET /v1/projects/:project_id/memory/search?q=...` — ranked chunk search with matching passage
-  and provenance; uses a lexical fallback when FTS5 is unavailable.
+  and provenance; uses a lexical fallback when FTS5 is unavailable and requires Bearer.
 - `GET /v1/projects/:project_id/sync` — mode, counts, conflicts, and latest event.
 - `PUT /v1/projects/:project_id/sync` — compatibility configuration; SQL remains authoritative.
-- `GET /v1/projects/:project_id/memory/export` — read-only export with complete content.
+- `GET /v1/projects/:project_id/memory/export` — read-only export sanitized by default; requires Bearer.
 - `POST /v1/projects/:project_id/memory/events` — idempotent batch ingestion.
 - `GET /v1/projects/:project_id/usage/summary` — filterable totals by period, change, session,
   agent, provider, model, and role.
 - `GET /v1/projects/:project_id/usage/breakdown` — agent, subagent, and model hierarchy.
-- `GET /v1/projects/:project_id/usage/calls` — individual calls with prompt and response.
-- `GET /v1/projects/:project_id/transcripts/:transcript_id` — compressed transcript validated by hash.
+- `GET /v1/projects/:project_id/usage/calls` — individual calls with prompt and response; requires Bearer.
+- `GET /v1/projects/:project_id/transcripts/:transcript_id` — compressed transcript validated by hash; requires Bearer.
+- `GET /v1/projects/:project_id/security` — policy, token counts, and sanitized audit; requires admin.
+- `PUT /v1/projects/:project_id/security/policy` — updates the effective policy without restart; requires admin.
+- `POST /v1/projects/:project_id/security/purge` — transactional dry-run/purge with receipt; requires admin.
 
 The `/v1` routes reject transported or expanded bodies above their limits and validate project,
 path, revision, hash, idempotency, and isolation before writing to SQLite. Use `memory/export` for

package/docs/pt-BR/commands/observer-security.md

@@ -0,0 +1,154 @@
+# Segurança do Observer
+
+**PT-BR** · [English](../../en/commands/observer-security.md)
+
+## Objetivo
+
+O Observer é um read model local ou de equipe, nunca uma nova autoridade sobre Vault, spec, memória
+ou sync. O modelo de ameaça considera host remoto comprometido, token roubado, operador curioso,
+banco/outbox copiados, payload adversarial e purge interrompido. Host/Origin continuam validados;
+mutações e leituras sensíveis falham fechadas, inclusive no loopback.
+
+| Classe | Padrão | Risco principal |
+|---|---|---|
+| documento | `metadata` | memória/decisões integrais |
+| transcript | `metadata` | conversa e ferramentas |
+| prompt/resposta | `redacted` | PII e segredos |
+| uso | `aggregate` | custo e identidade operacional |
+| audit/receipt | metadados mínimos | apagar a própria prova |
+
+A policy v1 restringe por classe, `project_id`, glob de path e `entity_type`. Regras mais tardias
+vencem apenas no projeto correspondente. Redaction cobre Bearer, credenciais em URL/connection
+string, access keys, e-mail, telefone e regexes configuráveis seguras. O schema é
+`schema/observer-policy-v1.schema.json`.
+Em `transcript_capture: messages`, arrays, JSONL e o envelope canônico `{messages:[...]}` preservam
+somente mensagens `user|assistant|system` com `role`/`content` string após redaction; campos extras,
+tools e entradas malformadas são descartados ou falham fechados.
+A policy explícita é a única autoridade de captura do publisher; `WENDKEEP_OBSERVER_CAPTURE_LEVEL`
+é apenas compatibilidade traduzida para policy quando nenhum arquivo de policy foi fornecido e
+nunca eleva nem suprime `none|metadata|messages|full` ou documentos `selected` explícitos.
+Nos upserts de documento/transcript, `content_hash` sempre representa o conteúdo final após captura
+e redaction; captura metadata/selected usa o SHA-256 do conteúdo vazio. Exclusões de documento
+continuam efetivas mesmo com captura `none`, preservam path/revision/operação e nunca transportam
+conteúdo ou hash obsoleto.
+A redaction nunca reescreve campos validados de identidade estrutural, como IDs de projeto/evento/
+entidade, paths lógicos, revisions ou operações. A privacidade do path é aplicada de modo fail-closed
+pelas regras de captura por projeto/path, não pela renomeação da chave de storage por uma regra de
+redaction de conteúdo.
+O contrato estrutural por evento também preserva aliases snake/camel aceitos, chaves de documento/
+sessão/agente/call/transcript/rollup, timestamps, roles, status, coverage, dimensões de modelo/preço,
+workflow e proveniência de source. `title`, `summary`, `agent_name`, conteúdo, prompt/resposta e
+metadata continuam como campos de display/conteúdo sujeitos a redaction.
+Na publicação incremental, timestamps de turn ausentes ou vazios herdam o instante canônico do
+lote, epoch numérico em milissegundos é normalizado para ISO 8601 e valor não vazio inválido falha
+fechado antes da policy/store; evento e payload usam o mesmo instante.
+
+## Quando usar
+
+Use ao habilitar o Observer para dados reais, cadastrar ou revogar credenciais, restringir captura,
+proteger SQLite/outbox, definir retenção ou eliminar dados com prova verificável.
+
+## Quando não usar
+
+Não use como KMS/secret manager corporativo, para publicar Vault/runtime, para substituir a
+autoridade local ou para apagar manualmente tabelas e índices. Captura `full` continua opt-in e
+sujeita à policy/redaction.
+
+## Pré-requisitos
+
+Use Node.js 22.13+, mantenha o bind no loopback e injete tokens/chaves somente por variáveis de
+ambiente. O token de bootstrap é registrado somente pelo hash, exige projetos explícitos e
+expiração finita; não é um admin wildcard fora do registry. Para Docker, defina também
+`WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS`, `WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT` e uma chave de
+32 bytes em hex/base64 em `WENDKEEP_OBSERVER_ENCRYPTION_KEY`. O operador guarda a chave e receipts externos.
+
+## Sintaxe
+
+```bash
+npx wendkeep observer serve --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--bootstrap-token-id <id>] [--require-loopback-auth] [--require-encryption]
+npx wendkeep observer security token create --project-id <projeto> --role <role> --scopes <scopes> --token-env <env> --expires-at <ISO>
+npx wendkeep observer security token rotate --project-id <projeto> --token-id <id> --token-env <env> --expires-at <ISO> [--new-token-id <id>]
+npx wendkeep observer security token revoke --project-id <projeto> --token-id <id>
+npx wendkeep observer security policy set --project-id <projeto> --file <policy.json>
+npx wendkeep observer security policy show --project-id <projeto>
+npx wendkeep observer security purge --project-id <projeto> --before <ISO> --classes <classes> [--dry-run]
+npx wendkeep observer security retention run --project-id <projeto> [--dry-run] [--operation-id <id>]
+```
+
+## Opções e códigos de saída
+
+- `viewer` lê metadata/agregados; `auditor` pode receber scopes sensíveis; `publisher` ingere;
+  `admin` administra policy, purge e recovery. Role, scope e projeto precisam autorizar juntos.
+- Tokens são persistidos somente como SHA-256; expiração, rotação e revogação valem sem restart.
+- Após rotacionar o bootstrap, atualize token e token ID no ambiente; reiniciar nunca reativa a
+  credencial antiga revogada ou expirada.
+- `--token-env` nomeia a variável com o segredo; o comando nunca imprime o valor.
+- `--require-loopback-auth` protege toda a API; reads sensíveis exigem token mesmo sem a flag.
+- `--require-encryption` falha se a chave externa estiver ausente ou inválida.
+- `WENDKEEP_OBSERVER_REQUIRE_ENCRYPTION=1` aplica a mesma falha fechada a `status`, `security`,
+  `register`, `publish` e `reconcile`; com chave configurada, todo primeiro upgrade v5 usa apenas
+  `.bak.enc` + manifest antes de qualquer leitura/backfill.
+- Exit `0` indica operação concluída; exit `1` indica configuração, autorização, policy, chave ou
+  operação inválida. O hook mantém exit `0` fail-open para o fluxo local, mas aborta antes de
+  persistir conteúdo inseguro.
+
+O audit guarda capability, resultado, rota e horário, nunca Bearer, prompt, resposta ou payload.
+
+## Exemplos
+
+Recovery offline explícito e auditado:
+
+```powershell
+$env:OBSERVER_RECOVERY_TOKEN = '<segredo-forte-temporário>'
+npx wendkeep observer security token create --data-dir C:\WendKeepObserver `
+  --project-id project-a --role admin --scopes '*' --token-env OBSERVER_RECOVERY_TOKEN `
+  --expires-at 2026-09-29T12:00:00Z --reason 'offline recovery' --json
+npx wendkeep observer security token revoke --data-dir C:\WendKeepObserver `
+  --project-id project-a --token-id <id> --reason 'recovery complete' --json
+```
+
+Sempre faça dry-run antes do purge. O runner de retenção é explícito/idempotente (CLI ou
+`POST /v1/projects/:id/security/retention`), sem timer oculto:
+
+```powershell
+npx wendkeep observer security purge --data-dir C:\WendKeepObserver `
+  --project-id project-a --before 2026-08-01T00:00:00Z `
+  --classes documents,calls,transcripts --dry-run --json
+```
+
+```powershell
+npx wendkeep observer security retention run --data-dir C:\WendKeepObserver `
+  --project-id project-a --operation-id scheduled-2026-08-29 --dry-run --json
+```
+
+## Resultado esperado
+
+TTL é independente para documentos, calls e transcripts. Contagens, remoção de projeções/FTS,
+eventos e receipt usam a mesma transação; retry é idempotente e dado antigo tardio gera nova prova.
+
+AES-256-GCM usa AAD por projeto/classe/registro/campo e `keyProvider` externo. O backfill v6 remove
+plaintext e índices derivados antes de liberar leituras; chave errada falha sem revelar conteúdo.
+A migration estrutural `006-observer-security.sql` cria backup, valida checksum, faz rollback e
+permite retry. Em modo at-rest obrigatório, o backup é `.bak.enc`, tem manifest/key ID/permissão
+restrita e restauração falha com chave errada; nenhum `.bak` plaintext permanece.
+
+O hook aplica policy metadata/redacted por padrão; `WENDKEEP_OBSERVER_POLICY_FILE` seleciona policy
+explícita. `WENDKEEP_OBSERVER_OUTBOX_KEY_ENV` nomeia a variável da chave da outbox e
+`WENDKEEP_OBSERVER_OUTBOX_KEY_ID` identifica a chave. O Compose exige autenticação e criptografia.
+O painel guarda Bearer somente em memória, exporta cópia sanitizada e expõe Segurança. MCP exige
+scope para calls/busca integral. Sync leva apenas `policy_ref`, sem duplicar tokens ou autoridade.
+
+## Erros comuns e diagnóstico
+
+- `observer_token_missing|expired|revoked`: crie/rotacione um token escopado ou faça recovery offline.
+- `observer_project_forbidden|role_forbidden|scope_forbidden`: confira a interseção projeto/role/scope.
+- `observer_encryption_key_unavailable|observer_decryption_failed`: confira key ID e material externo;
+  nunca enfraqueça o modo obrigatório.
+- `observer_policy_invalid`: valide campos/captures e remova regex inválida ou explosiva.
+- Falha de migration v6: preserve `.pre-006-*.bak.enc` e seu manifest, corrija a causa e repita.
+
+## Próximos passos
+
+Leia [Observer local](observer.md), faça um dry-run de retenção, valide token revogado/expirado e
+guarde o receipt fora do banco quando precisar de prova externa. Nunca publique banco, backup,
+outbox, chave, token ou `/data`.

package/docs/pt-BR/commands/observer.md

@@ -26,7 +26,9 @@ pelos hooks e pelo WendKeep local.
 
 Tenha Node.js 22.13 ou mais recente para executar o Observer SQL. O Keep Core e os demais comandos
 continuam compatíveis com Node.js 18 ou mais recente. Registre explicitamente cada projeto e defina
-`WENDKEEP_OBSERVER_TOKEN`; leituras no loopback permanecem abertas, mas toda mutação exige Bearer.
+`WENDKEEP_OBSERVER_TOKEN`. Toda mutação e toda leitura de conteúdo sensível exigem Bearer, inclusive
+no loopback; metadados e agregados podem permanecer abertos localmente quando
+`--require-loopback-auth` não é usado. Veja [Segurança do Observer](observer-security.md).
 
 ## Sintaxe
 
@@ -36,7 +38,7 @@ npx wendkeep observer register --project <projeto> --vault <vault> --data-dir <d
 npx wendkeep observer publish --project <projeto> --vault <vault> --data-dir <diretório>
 npx wendkeep observer reconcile --project <projeto> --vault <vault> --data-dir <diretório> [--url http://127.0.0.1:8787]
 npx wendkeep observer memory import --project <projeto> --vault <vault> --url http://127.0.0.1:8787 --token <token> --json
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório> --token <token>
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório> --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--require-loopback-auth] [--require-encryption]
 ```
 
 ## Opções e códigos de saída
@@ -46,7 +48,13 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
 - `--project` e `--vault` identificam o projeto nos comandos `register`, `publish`, `reconcile` e `memory import`.
 - `--host` aceita somente `127.0.0.1`, `localhost` ou `::1`; outros hosts são recusados antes do
   listen.
-- `--token` ou `WENDKEEP_OBSERVER_TOKEN` autentica mutações; `--allow-non-loopback` falha sem token.
+- `--token` ou `WENDKEEP_OBSERVER_TOKEN` fornece o segredo de bootstrap hash-only; projetos
+  explícitos e expiração finita são obrigatórios, e toda mutação/leitura sensível passa pelo registry;
+  `--allow-non-loopback` falha sem token.
+- `--require-loopback-auth` exige Bearer também para metadados e agregados locais e ativa a policy
+  segura do projeto na ingestão.
+- `--require-encryption` exige `WENDKEEP_OBSERVER_ENCRYPTION_KEY` com 32 bytes em hex/base64; use
+  `WENDKEEP_OBSERVER_ENCRYPTION_KEY_ID` para identificar a chave externa.
 - `WENDKEEP_OBSERVER_CAPTURE_LEVEL` aceita `metadata` (padrão, sem mensagens), `messages` ou
   `full-transcript`. Caminhos locais absolutos nunca são publicados.
 - Exit `0` indica sucesso; exit `1` indica falha de configuração ou operação; o hook publisher
@@ -57,7 +65,10 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
 ```powershell
 npx wendkeep observer register --project C:\GitHub\WendKeep --vault C:\GitHub\WendKeep\.WendKeep-vault --data-dir C:\WendKeepObserver
 $env:WENDKEEP_OBSERVER_TOKEN = '<token-local-forte>'
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS = 'project-a'
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT = '2026-09-29T12:00:00Z'
+$env:WENDKEEP_OBSERVER_ENCRYPTION_KEY = '<32-bytes-em-hex-ou-base64>'
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN --require-loopback-auth
 $env:WENDKEEP_OBSERVER_URL = 'http://127.0.0.1:8787'
 ```
 
@@ -67,15 +78,19 @@ Para Docker local:
 docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
 ```
 
+O Compose exige token, allowlist/expiração do bootstrap e chave; inicia com autenticação integral
+e criptografia obrigatória. A policy `encryption_required` recusa ingestão e outbox plaintext.
+
 ## Painel web local
 
 Com o servidor em execução, abra [http://127.0.0.1:8787/](http://127.0.0.1:8787/) no navegador.
-O painel é servido pelo mesmo processo e abre diretamente para consultas, sem formulário ou token. A porta fica
-presa ao loopback do computador; não coloque o endereço em uma interface de rede.
+O painel é servido pelo mesmo processo. Informe o token no formulário local: ele fica somente na
+memória da página, segue como Bearer nas consultas e é descartado ao recarregar. A porta fica presa
+ao loopback do computador; não coloque o endereço em uma interface de rede.
 
 O painel mostra a lista multi-projeto, versão, saúde, sessão mais recente, change ativa, contagem
 de changes e data da última captura. Ao abrir um projeto, o workspace oferece Overview, Consumo,
-Sessões, Memória, Changes e Sincronização. A aba Consumo mostra custo total, tokens por categoria,
+Sessões, Memória, Changes, Sincronização e Segurança. A aba Consumo mostra custo total, tokens por categoria,
 agentes principais, subagentes, provedores, modelos, tendência diária, cobertura histórica e
 chamadas conforme o nível de captura escolhido. Os estados de carregamento, vazio, servidor
 indisponível, conflito, modelo sem tarifa e dados desatualizados ficam visíveis, e a atualização
@@ -160,18 +175,21 @@ corte. As telas do Observer não concluem, arquivam, reparam ou promovem estado.
 - `POST /v1/projects/:project_id/ingest` — lote idempotente de documentos, sessões, agentes, rollups,
   chamadas e transcripts.
 - `GET /v1/projects/:project_id/memory/tree` — árvore e metadados dos documentos.
-- `GET /v1/projects/:project_id/memory/document?path=...` — conteúdo Markdown integral.
+- `GET /v1/projects/:project_id/memory/document?path=...` — conteúdo Markdown integral; exige Bearer.
 - `GET /v1/projects/:project_id/memory/search?q=...` — busca ranqueada por chunks, com trecho do
-  match e proveniência; usa fallback lexical quando FTS5 não está disponível.
+  match e proveniência; usa fallback lexical quando FTS5 não está disponível e exige Bearer.
 - `GET /v1/projects/:project_id/sync` — modo, contagem, conflitos e último evento.
 - `PUT /v1/projects/:project_id/sync` — compatibilidade de configuração; a autoridade continua SQL.
-- `GET /v1/projects/:project_id/memory/export` — exportação read-only com conteúdo completo.
+- `GET /v1/projects/:project_id/memory/export` — exportação read-only sanitizada por padrão; exige Bearer.
 - `POST /v1/projects/:project_id/memory/events` — ingestão idempotente em lote.
 - `GET /v1/projects/:project_id/usage/summary` — totais filtráveis por período, change, sessão,
   agente, provedor, modelo e papel.
 - `GET /v1/projects/:project_id/usage/breakdown` — hierarquia de agentes, subagentes e modelos.
-- `GET /v1/projects/:project_id/usage/calls` — chamadas individuais com prompt e resposta.
-- `GET /v1/projects/:project_id/transcripts/:transcript_id` — transcript comprimido, validado por hash.
+- `GET /v1/projects/:project_id/usage/calls` — chamadas individuais com prompt e resposta; exige Bearer.
+- `GET /v1/projects/:project_id/transcripts/:transcript_id` — transcript comprimido, validado por hash; exige Bearer.
+- `GET /v1/projects/:project_id/security` — policy, contagens de tokens e audit sanitizado; exige admin.
+- `PUT /v1/projects/:project_id/security/policy` — atualiza a policy efetiva sem restart; exige admin.
+- `POST /v1/projects/:project_id/security/purge` — dry-run/purge transacional com receipt; exige admin.
 
 As rotas `/v1` rejeitam corpo transportado ou expandido acima do limite e validam projeto, caminho,
 revisão, hash, idempotência e isolamento antes de gravar o conteúdo no SQLite. Para preservar uma

package/hooks/observer-publish.mjs

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
 import { debugLog, readHookInput, resolveVault } from './obsidian-common.mjs';
-import { publishObserverSnapshot } from '../src/observer-publish.mjs';
+import { publishObserverSnapshot, resolveObserverPublisherSecurity } from '../src/observer-publish.mjs';
 
 async function main() {
   const input = readHookInput();
   const resolved = resolveVault(input);
+  const publisherSecurity = resolveObserverPublisherSecurity();
   const result = await publishObserverSnapshot({
     vaultBase: resolved.base,
     projectRoot: resolved.projectRoot,
     input,
+    ...publisherSecurity,
   });
   if (!result.ok && result.error) debugLog('Observer publish fail-open:', result.error);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -46,6 +46,7 @@
   "scripts": {
     "precheck": "node --check src/capabilities.mjs && node --check src/host-capabilities.mjs && node --check src/task-contracts.mjs && node --check src/task-leases.mjs && node --check src/task.mjs && node --check src/change.mjs && node --check src/archive-operation-lock.mjs && node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/provenance-gate.mjs && node --check src/provenance-sources.mjs && node --check src/receipt-ledger.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check hooks/session-stop.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/integrations/src/capabilities.mjs && node --check packages/pi/src/index.mjs && node --check src/sync-protocol.mjs && node --check src/sync-outbox.mjs && node --check src/sync-adapters.mjs && node --check src/sync-protocol-cli.mjs && node --check packages/mcp/src/sync.mjs && node --check src/portable.mjs && node --check src/tdd.mjs && node --check src/tdd-attestation.mjs && node --check src/tdd-attestation-store.mjs",
     "check": "node --check scripts/validate-commit-range.mjs && node --check packages/commit/src/index.mjs && node --check packages/commit/src/cli.mjs && node --check packages/commit/src/git-runtime.mjs && node --check src/git-commit-hooks.mjs && node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/mcp.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/audit.mjs && node --check packages/mcp/src/cli.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/effects.mjs && node --check packages/mcp/src/executor.mjs && node --check packages/mcp/src/server.mjs && node --check packages/mcp/src/stdio.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
+    "postcheck": "node --check packages/observer/src/index.mjs && node --check packages/observer/src/policy.mjs && node --check packages/observer/src/redaction.mjs && node --check packages/observer/src/authz.mjs && node --check packages/observer/src/token-registry.mjs && node --check packages/observer/src/encryption.mjs && node --check packages/observer/src/retention.mjs && node --check packages/observer/src/purge.mjs && node --check packages/observer/src/audit.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",
     "release": "node scripts/release.mjs",