malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
docs: document MVP trust model for self-hosted deployment (ATB-22) (#38)
* docs: document MVP trust model for self-hosted deployment (ATB-22)
- Add docs/trust-model.md covering operator responsibilities, user data
guarantees (posts stay on user's own PDS), security implications of a
compromised AppView, and the future AT Protocol privilege delegation path
- Reference trust-model.md from deployment guide: in the Related
Documentation block and in the Security Requirements section
- Mark Phase 3 trust model item complete in atproto-forum-plan.md
* docs: address review feedback on trust model (ATB-22)
- Fix inaccurate "signing keys" language — AppView holds credentials
(FORUM_HANDLE/FORUM_PASSWORD), not raw signing keys; rotating the
password immediately revokes AppView access
- Fix CommonMark blockquote in deployment-guide.md — add > prefix to
bullet items so the blockquote renders correctly outside GitHub
- Add missing record types to trust-model.md: forum metadata
(space.atbb.forum.forum) and boards (space.atbb.forum.board) were
omitted from all lists
- Clarify role assignment writes to user's PDS (membership record),
not Forum DID's PDS — separate from mod actions which write to
Forum DID's PDS
- Soften at.delegation language from "is developing" to "has proposed"
to reflect its community-proposal status
- Fix roadmap section reference to match actual headings; use anchor link
- Replace submodule path with upstream GitHub URL for at-delegation
* docs: don't suggest that a community came up with that proposal when that didn't atually happen
+2
-1
docs/atproto-forum-plan.md
+2
-1
docs/atproto-forum-plan.md
···
213
213
- Race condition handled: post-before-ban path covered by eventual consistency — post inserts normally, `applyBan` soft-deletes it when ban arrives
214
214
- 8 new integration tests in `indexer.test.ts`; 7 unit tests in `indexer-ban-enforcer.test.ts`; 491 total tests passing
215
215
- Files: `apps/appview/src/lib/ban-enforcer.ts` (new), `apps/appview/src/lib/indexer.ts` (3 handler overrides), `apps/appview/src/lib/__tests__/indexer-ban-enforcer.test.ts` (new), `apps/appview/src/lib/__tests__/indexer.test.ts` (additions)
216
-
- [ ] Document the trust model: operators must trust their AppView instance, which is acceptable for self-hosted single-server deployments
216
+
- [x] Document the trust model: operators must trust their AppView instance, which is acceptable for self-hosted single-server deployments
217
+
- ATB-22 | `docs/trust-model.md` (new) — covers operator responsibilities, user data guarantees, security implications, and future delegation path; referenced from deployment guide
217
218
218
219
#### Phase 4: Web UI (Week 7–9)
219
220
- [ ] Forum homepage: category list, recent topics
+5
-1
docs/deployment-guide.md
+5
-1
docs/deployment-guide.md
···
4
4
**Last Updated:** 2026-02-12
5
5
**Audience:** System administrators deploying atBB to production
6
6
7
-
> **Related Documentation:** See [docs/plans/2026-02-11-deployment-infrastructure-design.md](plans/2026-02-11-deployment-infrastructure-design.md) for architectural decisions and design rationale behind this deployment approach.
7
+
> **Related Documentation:**
8
+
> - [docs/trust-model.md](trust-model.md) — Trust model for self-hosted deployment: what the AppView controls, user data guarantees, and security implications
9
+
> - [docs/plans/2026-02-11-deployment-infrastructure-design.md](plans/2026-02-11-deployment-infrastructure-design.md) — Architectural decisions and design rationale behind this deployment approach
8
10
9
11
## Table of Contents
10
12
···
93
95
- **Firewall:** Restrict inbound ports to 80/443 only
94
96
- **SSH Access:** Key-based authentication (disable password auth)
95
97
- **Secrets Management:** Secure storage for environment variables (consider cloud secrets manager)
98
+
99
+
> **Before deploying:** Read [docs/trust-model.md](trust-model.md). It explains what the AppView controls (the Forum DID's credentials and write access), what your users can count on, and the security implications of a compromised server.
96
100
97
101
---
98
102
+113
docs/trust-model.md
+113
docs/trust-model.md
···
1
+
# atBB Trust Model
2
+
3
+
**Version:** 1.0
4
+
**Last Updated:** 2026-02-17
5
+
**Audience:** Forum operators considering or running a self-hosted atBB instance
6
+
7
+
---
8
+
9
+
## Summary
10
+
11
+
atBB is built on the AT Protocol, where users own their posts on their own Personal Data Servers (PDS). Forum-level records — forum metadata, categories, boards, roles, and moderation actions — belong to the Forum DID, which your AppView manages on behalf of admins and moderators.
12
+
13
+
**The bottom line:** You must trust the server running your AppView. In exchange, your users can trust that *their* posts belong to them — not to you, and not to your server.
14
+
15
+
---
16
+
17
+
## What Each Party Controls
18
+
19
+
### Users control their own posts
20
+
21
+
When a user writes a post on your forum, the AppView submits that post to the user's own PDS. The record lives in the user's AT Protocol repository. The user can take it with them if they move PDS providers, and no one can delete it from the AT Protocol network without the user's cooperation.
22
+
23
+
Your AppView can choose not to *display* a post (for example, if a moderator hides it), but it cannot delete the post from the user's PDS. The content remains in the user's control.
24
+
25
+
### The operator controls forum structure
26
+
27
+
Forum-level records — forum metadata, categories, boards, roles, and moderation actions — belong to the Forum DID. The Forum DID is the AT Protocol identity you created during setup (see `FORUM_DID` in your environment config).
28
+
29
+
The AppView holds the credentials for this account (`FORUM_HANDLE` and `FORUM_PASSWORD`). When an admin creates a category or a moderator bans a user, the AppView verifies their role and writes the record to the Forum DID's PDS on their behalf. Role assignment works differently: the AppView writes the updated role reference into the user's own membership record on their PDS — not the Forum DID's PDS.
30
+
31
+
This means the AppView has full write access to the Forum DID's repository, and can also update membership records on users' PDSes.
32
+
33
+
---
34
+
35
+
## What "Trusting the AppView" Means
36
+
37
+
Because the AppView holds the Forum DID's credentials, anyone who controls the AppView process can write any record to the Forum DID's repository. In practice, this includes:
38
+
39
+
- Creating, editing, or deleting categories, boards, and forum metadata
40
+
- Issuing, modifying, or removing moderation actions (bans, locks, hides)
41
+
- Assigning or removing roles — by updating the user's membership record on their PDS
42
+
43
+
This is a deliberate design choice for the MVP. The AppView is a single, trusted intermediary — it does not require a separate delegation layer.
44
+
45
+
---
46
+
47
+
## Why This Model Is Acceptable for Self-Hosted Deployment
48
+
49
+
The atBB MVP targets self-hosted, single-server deployments. In this model, the operator *is* the AppView. You control the server, the environment variables, and the deployment. There is no third party between you and your forum.
50
+
51
+
This is the same trust model used by almost every traditional forum platform (phpBB, Discourse, etc.). The difference is that AT Protocol gives your *users* a guarantee that their content remains portable and under their control, even though you as the operator control the forum structure.
52
+
53
+
For a community that runs and trusts its own infrastructure, this tradeoff is appropriate.
54
+
55
+
---
56
+
57
+
## Security Implications
58
+
59
+
If an attacker compromises your AppView server, they gain the ability to write arbitrary forum-level records. Specifically, they could:
60
+
61
+
- Escalate a user account to admin or owner
62
+
- Overwrite or fabricate moderation actions
63
+
- Modify category structure or forum metadata
64
+
65
+
**Note:** An attacker who compromises your AppView cannot forge user posts. User posts live on the user's own PDS and require the user's own credentials to create or modify.
66
+
67
+
### Mitigations
68
+
69
+
Protect the AppView server with standard hardening practices:
70
+
71
+
- **Secrets management:** Store `FORUM_PASSWORD` and `SESSION_SECRET` in environment variables, not in source code. Use a secrets manager or vault for production deployments. Never commit `.env.production` to version control.
72
+
- **Firewall:** Restrict inbound traffic to ports 80 and 443. Do not expose the database port to the public internet.
73
+
- **SSH:** Use key-based authentication. Disable password-based SSH login.
74
+
- **Updates:** Keep the host OS and the atBB container up to date. Review [release notes](https://github.com/malpercio-dev/atbb-monorepo/releases) before upgrading.
75
+
- **Access control:** Limit who has SSH access to the server. Each admin is a potential attacker if their machine is compromised.
76
+
- **Monitoring:** Set up log monitoring and alerts. Unexpected writes to the Forum DID's PDS are a sign of compromise.
77
+
78
+
See [docs/deployment-guide.md](deployment-guide.md) for a full pre-launch security checklist.
79
+
80
+
---
81
+
82
+
## Future: AT Protocol Privilege Delegation
83
+
84
+
The current model — where the AppView holds the Forum DID's credentials — is a shortcut that avoids building a delegation layer at launch. At least one prposal exists for a system under the `at.delegation` namespace (see [atBB-Community/at-delegation](https://github.com/atBB-Community/at-delegation)) that could replace this.
85
+
86
+
Under privilege delegation, admins and moderators would receive scoped write access to specific record collections on the Forum DID's repository. For example:
87
+
88
+
- A moderator would receive write access to `space.atbb.modAction` only — not to categories, boards, or roles.
89
+
- An admin would receive write access to categories, boards, and roles, but not the forum's core identity records.
90
+
91
+
This removes the AppView as the single key-holding bottleneck. It also enables multi-server moderation teams: a moderator on one server could act on a forum hosted on another.
92
+
93
+
The roadmap tracks this under the [Privilege Delegation section of `docs/atproto-forum-plan.md`](atproto-forum-plan.md#privilege-delegation-atdelegation-integration). It will not ship as part of the MVP.
94
+
95
+
---
96
+
97
+
## Quick Reference
98
+
99
+
| Who | Controls | Cannot control |
100
+
|-----|----------|----------------|
101
+
| User | Their own posts (stored on their PDS) | Forum metadata, categories, boards, roles, mod actions |
102
+
| Operator (via AppView) | Forum structure, roles, mod actions | Content in users' AT Protocol repos |
103
+
| AppView server | Forum DID credentials and write access | Users' PDS credentials |
104
+
105
+
| Risk | Severity | Mitigation |
106
+
|------|----------|------------|
107
+
| AppView server compromised | High — full forum control | Server hardening, secrets management, monitoring |
108
+
| Forum password leaked | High — same as above | Rotate credentials immediately, audit mod action history |
109
+
| User's PDS compromised | Contained — affects that user only | User responsibility; AT Protocol account recovery |
110
+
111
+
---
112
+
113
+
*Questions or concerns about this trust model? Open an issue at [github.com/malpercio-dev/atbb-monorepo/issues](https://github.com/malpercio-dev/atbb-monorepo/issues).*