yjs/THREAT_MODEL.md

# Threat Model - Yjs

This document outlines the threat model for the Yjs project, a CRDT framework for shared editing. It identifies assets, threat actors, attack surfaces, and mitigations.

## 1. Assets

What we are protecting:

| Asset | Description |
|-------|-------------|
| Document data | Shared documents edited by end users via Yjs-powered applications |
| Library integrity | The correctness and safety of the Yjs source code and published npm packages |
| CI/CD pipeline | GitHub Actions workflows, publishing credentials, and automation |
| Maintainer accounts | GitHub and npm accounts of project maintainers |
| User trust | Reputation and reliability of the project as a dependency |

## 2. Threat Actors

| Actor | Motivation | Capability |
|-------|-----------|------------|
| Malicious contributor | Inject backdoor or vulnerable code via pull requests | Low-Medium: constrained by code review |
| Supply chain attacker | Compromise a dependency to reach Yjs consumers downstream | Medium: targets transitive dependencies |
| Malicious peer (network) | Exploit the CRDT sync protocol to corrupt documents or crash peers | Medium: can craft arbitrary binary messages |
| Compromised maintainer account | Publish a malicious package version to npm | High: full publish access |
| Automated bots | Spam, typosquatting, or social engineering via issues/PRs | Low |

## 3. Attack Surfaces

### 3.1 Document Corruption by Write-Peers

Any peer with write access has the theoretical ability to corrupt a Yjs document. The CRDT protocol is designed for collaboration between trusted peers — it guarantees conflict-free merging, but it does not protect against a malicious peer intentionally writing destructive operations. Once a malicious update is applied to a document, it becomes part of the document's permanent history.

**It is therefore critical that untrusted peers are never allowed to write updates to the original Yjs document.**

**Server-side filtering of updates is a common antipattern.** Some applications attempt to validate or filter incoming updates on the server before applying them to the shared document. This approach is fundamentally flawed with untrusted peers — Yjs updates are binary-encoded CRDT operations, and selectively filtering them can easily be exploited and is not a reliable security boundary.

**Suggestion-only (untrusted) users should work on a separate Yjs document fork**, not on the original document. Their changes can be reviewed and selectively merged by a trusted peer. Only trusted, authenticated peers should be allowed to write to the authoritative document.

Additionally, a malicious peer could send crafted binary messages to:

- **Cause denial of service** via extremely large updates, deeply nested structures, or messages that trigger excessive computation.
- **Trigger buffer overflows or out-of-bounds reads** in the binary decoder.

**Mitigations:**
- Never allow untrusted peers to write to the original document.
- Use separate document forks for suggestion-only users.
- Do not rely on server-side update filtering as a security measure.
- Authenticate and authorize peers before granting write access.
- Validate incoming binary messages and reject malformed data.
- Implement size limits on incoming updates where possible.
- Fuzz test the decoder and update application paths.

### 3.2 Supply Chain (Dependencies & npm Publishing)

Yjs is a widely-used library. Compromising it would impact many downstream projects.

**Yjs only depends on packages that are maintained by the Yjs maintainers themselves** (such as `lib0` and `@y/protocols`). This significantly reduces supply chain risk, as there are no third-party runtime dependencies that could be independently compromised.

- **Compromised npm publish token** leading to a malicious release.
- **Typosquatting** of the package name.

However, the project does use third-party **dev dependencies** (linters, test tools, build tools, etc.). A compromised dev dependency could execute malicious code on a maintainer's machine during development, potentially leading to credential theft or tampered releases. It is important to only install trusted dev dependencies and to review them carefully.

**Mitigations:**
- All runtime dependencies are maintained by the Yjs team, eliminating third-party supply chain risk.
- Only install trusted, well-maintained dev dependencies and review new additions carefully.
- Enable MFA on all maintainer npm and GitHub accounts.
- Use `npm provenance` or signed releases where supported.
- Pin dependency versions and review lockfile changes in PRs.
- Monitor for typosquat packages.

### 3.3 Pull Requests & Code Contributions

- **Malicious code** submitted via pull requests (obfuscated backdoors, subtle logic changes).
- **CI exploitation** through crafted PR workflows that exfiltrate secrets.

**Mitigations:**
- Require at least one maintainer review before merging.
- Do not run CI with secrets on PRs from forks.
- Use branch protection rules on `main`.
- Review changes carefully, especially to binary encoding/decoding, crypto, and publishing scripts.

### 3.4 GitHub Actions & CI/CD

- **Secret exfiltration** from workflow runs.
- **Workflow injection** via untrusted input in PR titles, branch names, or commit messages.

**Mitigations:**
- Follow the principle of least privilege for workflow permissions.
- Avoid using `pull_request_target` with checkout of PR code.
- Pin action versions to specific commit SHAs.
- Limit secret access to required workflows only.

### 3.5 Maintainer Account Compromise

- **Account takeover** of a GitHub or npm maintainer account.
- Used to merge malicious PRs, publish backdoored packages, or modify CI.

**Mitigations:**
- Require MFA for all maintainers (GitHub and npm).
- Limit the number of accounts with publish access.
- Periodically review organization members and their permissions.

## 4. Risk Assessment

| Threat | Likelihood | Impact | Priority |
|--------|-----------|--------|----------|
| Malicious CRDT update from peer | Medium | High (data corruption) | High |
| Compromised npm publish | Low | Critical (supply chain) | High |
| Malicious pull request merged | Low | High | Medium |
| Dependency compromise | Low | High | Medium |
| CI secret exfiltration | Low | Medium | Medium |
| Maintainer account takeover | Low | Critical | High |

## 5. Out of Scope

The following are the responsibility of the application developer using Yjs, not the Yjs library itself:

- **Authentication and authorization** of peers connecting to a collaboration session.
- **Transport-layer security** (TLS/WSS) for data in transit.
- **Server-side access control** for who can read or write documents.
- **Application-level input validation** (e.g., sanitizing rich text content for XSS).

## 6. Review Schedule

This threat model should be reviewed:

- At least once per year.
- When a new major version is released.
- When a security incident occurs.
- When significant new features or dependencies are added.