Ticket #271: security and privacy audit
- Date: 2026-11-16
- Ticket: #271 (parent spec #268)
- Branch:
ticket/271-security - Base:
ticket/271-securityfromintegration/public-releaseat196c3f9; merged back at58adaf6(#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
| Path | Change |
|---|---|
docs/security/threat-model.md | New 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.md | New permission matrix for approvals, outside-roster contact, external directories, self-approval, and native permission preservation; findings P1–P6 |
docs/security/accepted-risks.md | New accepted-risk records AR-271-01 through AR-271-08, including the npm audit baseline and review dates |
SECURITY.md | Rewritten: supported versions, private reporting, response targets, scope, product boundaries, data handling, dependency policy, no-telemetry statement |
.github/dependabot.yml | Weekly npm updates (grouped development minor/patch and peer minor/patch, major updates individually), monthly GitHub Actions updates, security updates left urgent |
src/v2/service.ts | Narrow 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.ts | Regression test: "a handoff path cannot escape .ensemble/handoffs/ through a symlink" |
docs/README.md | Links the security records and this verification record |
TDD evidence for the fix
- 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 …". - Green: added canonical root/target resolution in
toolHandoff; the same test passes and the existing handoff relay/idempotency tests still pass. - Regression:
node --test --experimental-strip-types src/v2/handoff-service.test.ts→ 10 tests, 10 pass.
Commands and results
| Check | Command | Result |
|---|---|---|
| Typecheck | npm run check | Pass (no output) |
| Unit suite | npm test | 2032 pass, 0 fail on the ticket base; 2044 pass, 0 fail after merging integration/public-release (#269, #274) |
| Full gate | npm run verify | Pass on both trees (2032 then 2044 tests) |
| Production audit | npm audit --omit=dev | 0 vulnerabilities |
| Full audit | npm audit | 28 advisories: 25 moderate, 3 critical; all dev/peer tree; documented in AR-271-01 and AR-271-04 |
| Docs freshness | npm run docs:check | Pass (run after this record was linked) |
| Dependabot YAML | python3 -c "import yaml; yaml.safe_load(open('.github/dependabot.yml'))" | Valid YAML, 2 update entries |
| No outbound transport | grep -rn "fetch(|createServer|\.listen(|WebSocket|socket" src/v2 --include=*.ts | grep -v "test\.ts" | No matches |
Threat-model coverage
| Required surface | Covered in | Key conclusion |
|---|---|---|
| Storage | threat-model.md Surface 1 | Host plugin storage; project files under .ensemble/; retention and delete requirements defined; #272 implements export/delete |
| Filesystem/shell | Surface 2 | No Ensemble shell tool; two read-only TUI commands; canonical containment for workspace refs and handoffs; symlink-write residual risk recorded |
| Tools | Surface 3 | Ten native-surface tools plus legacy migration surface; closed schemas; session-bound; no approval action |
| Cross-workspace | Surface 4 | Agent tools refuse unapproved cross-workspace posts/DMs; realm is one OS user, not multi-tenant |
| Skills | Surface 5 | Native execution only; deny-all skill baseline; one-run leader grant restored |
| Approvals | Surface 6 | User-only resolution; no automatic approval; native replies once/reject |
| Model fallback | Surface 7 | Provider-only, bounded, and blocked after any tool call |
| Logs | Surface 8 | Metadata-only by default, redacted, 0600, 7-day/5-file retention |
Permission-model findings
| ID | Finding | Status |
|---|---|---|
| P1 | Handoff symlink read escape | Fixed and tested |
| P2 | Approval resolve is not server-workspace-scoped | Accepted (AR-271-02); local-client trust |
| P3 | Repository-controlled symlinks can redirect project-file writes | Accepted (AR-271-03); follow-up hardening |
| P4 | private_transcript share becomes durable global memory | Accepted for #272 to resolve in the consent contract |
| P5 | Unlimited ask_person rows can flood the inbox | Accepted; user-paced, cheap rows |
| P6 | A 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.mdis 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.mdand the threat model must be updated when #272 lands. The samedocs/README.mdlist is touched by both. - #269 (package identity) and #274 (support/runbook): merged into the base during this ticket.
docs/README.mdconflicted and was resolved by keeping all three verification entries.SECURITY.mddid not conflict; #274's support policy now sits beside this policy. - #275 (release workflow):
.github/dependabot.ymlis 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.ymlenables 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.