Skip to content

Ticket #271: security and privacy audit ​

  • Date: 2026-11-16
  • Ticket: #271 (parent spec #268)
  • Branch: ticket/271-security
  • Base: ticket/271-security from integration/public-release at 196c3f9; merged back at 58adaf6 (#269 and #274)
  • Node: 26.12.1
  • Host: OpenCode 2.2.7 compatibility range (2.2.6 || 2.2.7)
  • Scope: threat model, supported-version security policy, dependency audit and update automation, permission-model review, data-handling decisions, and one narrow containment fix
  • Out of scope: export/delete implementation and roster opt-out (#272), release provenance and artifact signing (#275), backup/restore (#273)

What changed ​

PathChange
docs/security/threat-model.mdNew evidence-based threat model for storage, filesystem/shell, tools, cross-workspace access, skills, approvals, model fallback, and logs; data classes and retention requirements; findings summary
docs/security/permission-model-review.mdNew permission matrix for approvals, outside-roster contact, external directories, self-approval, and native permission preservation; findings P1–P6
docs/security/accepted-risks.mdNew accepted-risk records AR-271-01 through AR-271-08, including the npm audit baseline and review dates
SECURITY.mdRewritten: supported versions, private reporting, response targets, scope, product boundaries, data handling, dependency policy, no-telemetry statement
.github/dependabot.ymlWeekly npm updates (grouped development minor/patch and peer minor/patch, major updates individually), monthly GitHub Actions updates, security updates left urgent
src/v2/service.tsNarrow fix: toolHandoff canonicalizes the handoffs root and the target before the containment check, so a symlink cannot read outside .ensemble/handoffs/
src/v2/handoff-service.test.tsRegression test: "a handoff path cannot escape .ensemble/handoffs/ through a symlink"
docs/README.mdLinks the security records and this verification record

TDD evidence for the fix ​

  1. Red: added the symlink test before the implementation. It failed because the tool accepted .ensemble/handoffs/link.md (a symlink to a file outside the workspace) and returned "Handed to $Sage …".
  2. Green: added canonical root/target resolution in toolHandoff; the same test passes and the existing handoff relay/idempotency tests still pass.
  3. Regression: node --test --experimental-strip-types src/v2/handoff-service.test.ts → 10 tests, 10 pass.

Commands and results ​

CheckCommandResult
Typechecknpm run checkPass (no output)
Unit suitenpm test2032 pass, 0 fail on the ticket base; 2044 pass, 0 fail after merging integration/public-release (#269, #274)
Full gatenpm run verifyPass on both trees (2032 then 2044 tests)
Production auditnpm audit --omit=dev0 vulnerabilities
Full auditnpm audit28 advisories: 25 moderate, 3 critical; all dev/peer tree; documented in AR-271-01 and AR-271-04
Docs freshnessnpm run docs:checkPass (run after this record was linked)
Dependabot YAMLpython3 -c "import yaml; yaml.safe_load(open('.github/dependabot.yml'))"Valid YAML, 2 update entries
No outbound transportgrep -rn "fetch(|createServer|\.listen(|WebSocket|socket" src/v2 --include=*.ts | grep -v "test\.ts"No matches

Threat-model coverage ​

Required surfaceCovered inKey conclusion
Storagethreat-model.md Surface 1Host plugin storage; project files under .ensemble/; retention and delete requirements defined; #272 implements export/delete
Filesystem/shellSurface 2No Ensemble shell tool; two read-only TUI commands; canonical containment for workspace refs and handoffs; symlink-write residual risk recorded
ToolsSurface 3Ten native-surface tools plus legacy migration surface; closed schemas; session-bound; no approval action
Cross-workspaceSurface 4Agent tools refuse unapproved cross-workspace posts/DMs; realm is one OS user, not multi-tenant
SkillsSurface 5Native execution only; deny-all skill baseline; one-run leader grant restored
ApprovalsSurface 6User-only resolution; no automatic approval; native replies once/reject
Model fallbackSurface 7Provider-only, bounded, and blocked after any tool call
LogsSurface 8Metadata-only by default, redacted, 0600, 7-day/5-file retention

Permission-model findings ​

IDFindingStatus
P1Handoff symlink read escapeFixed and tested
P2Approval resolve is not server-workspace-scopedAccepted (AR-271-02); local-client trust
P3Repository-controlled symlinks can redirect project-file writesAccepted (AR-271-03); follow-up hardening
P4private_transcript share becomes durable global memoryAccepted for #272 to resolve in the consent contract
P5Unlimited ask_person rows can flood the inboxAccepted; user-paced, cheap rows
P6A user-supplied skillbox can include *Informational; user choice

Data-retention decisions (implementation owned by #272) ​

  • No time-based expiry for conversations, Work, approvals, memories, bindings, or attachments; deletion is explicit (workspace delete or Ensemble reset).
  • Logs expire after 7 days, 5 files, or 10 MB per sink by default.
  • AGENTS.md is project-owned: workspace delete leaves it in place; #272 must offer block removal and document the roster disclosure.
  • Export must exclude credentials and unrelated private paths; delete must cover plugin storage, attachments, the .ensemble/ files Ensemble created, and logs.
  • Telemetry: none. No outbound request, analytics, crash reporting, or update check exists in src/v2/.

Accepted risks ​

See docs/security/accepted-risks.md. The critical advisories are the seroval/solid-js TUI peer chain (AR-271-01); the plugin ships no bundled runtime dependency and npm audit --omit=dev is clean. The moderate advisories are dev-only npm tooling (AR-271-04). No high or critical finding is undocumented.

Conflicts and coordination ​

  • #272 (data retention/export/delete and roster disclosure): this ticket defines the security requirements and defers implementation. SECURITY.md and the threat model must be updated when #272 lands. The same docs/README.md list is touched by both.
  • #269 (package identity) and #274 (support/runbook): merged into the base during this ticket. docs/README.md conflicted and was resolved by keeping all three verification entries. SECURITY.md did not conflict; #274's support policy now sits beside this policy.
  • #275 (release workflow): .github/dependabot.yml is a new file and does not touch existing workflows; update automation and release provenance are complementary. No conflict expected unless #275 rewrites dependency policy. The repo setting for Dependabot security updates is listed as an operator action.
  • #273 (backup/restore): the data-class table is the reference for what a backup must cover; no implementation overlap.

Residual risks and blocked checks ​

  • Repository-controlled symlink writes (AR-271-03) are not fixed; the recommended containment helper is a follow-up.
  • The critical TUI peer advisories cannot move without upgrading the OpenCode/OpenTUI runtime pair; see AR-271-01.
  • Operator action (not code): Dependabot security updates were disabled in the repository settings when this record was written (automated-security-fixes.enabled=false). The committed .github/dependabot.yml enables version updates; security updates need the repository setting enabled. That toggle belongs with the release/ops work (#275) and is not changed by this branch.
  • This record does not claim a live end-to-end security test on macOS/Herdr; that platform run is #277. The unit and docs gates above are the evidence for this ticket.
  • No secrets, conversation content, file bytes, or machine-specific paths were used in the docs or the regression test. The test uses temporary directories with synthetic content only.

Released under the MIT License.