J3vb/OwnCord
1
0
Fork 0
mirror of https://github.com/J3vb/OwnCord.git synced 2026-09-03 03:50:00 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
OwnCord/docs/README.md
T
J3vbandClaude Fable 5 88c7a8249a docs(b2-7): trust model, absence proofs, plugin boundary (#1443) 
* docs(b2-7): trust model — who can read what (BPR-050/051, C-09 contract)

One document states the operator trust model in plain language and traces
every claim to a code line or test: server-readable text and files and why,
E2EE voice/video/screen with the key-holder and TOFU rules, transport per TLS
mode with desktop pinning and the browser rule, the C-09 preview destination
contract B7 implements, at-rest storage, operator can/cannot, multi-device
sessions, and what beta does not claim. Linked from security.md,
deployment.md, quick-start.md and docs/README.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* test(b2-7): absence proofs — no federation/directory routes, outbound host table

TestAbsenceContract_NoFederationDirectoryOrListingRoutes builds the production
router with uploads, voice and GIF on, walks the whole mounted tree with
chi.Walk and fails on any route matching federat|directory|discover|listing.
A floor on the route count and a check that the admin subtree was traversed
keep it from passing vacuously. trust-model.md gains "What OwnCord does not
have" (BPR-040/082/083) and the outbound-host table B6's network capture
checks against.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* docs(b2-7): plugin boundary — off twice, compiled out of releases, no API promise

docs/architecture/plugins.md records the experimental WASM boundary (BPR-080/
081, BG-17): disabled by build tag and by config, absent from release.yml and
Dockerfile builds, the HP-2 configuration audit (fresh, upgraded, Docker,
standalone), the beta release-notes wording, what exists today with its limits
and tests, the post-beta plugin candidates that stay in core during beta, and
the core concerns that never move. Linked from architecture/README.md,
architecture/server.md and docs/README.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* docs(b2-7): L-08 re-tagged to B10 with the reason; B2-7 evidence block

L-08's remaining gate ("deterministic source build passes") cannot pass in
principle — TinyGo embeds host paths and has no -trimpath — and a compile-only
drift check would need a second Go SDK, TinyGo and Binaryen on every PR for a
subsystem release builds compile out. Re-tagged to B10, which runs the compile
once against the release candidate or closes on the provenance record; the
"no API promise" half is closed by docs/architecture/plugins.md. The plan's
B2-7 evidence block records the four pre-squash SHAs, the absence test's RED
output, the release-build finding, the decision, and the BPR-051 reader
placeholder. CHANGELOG gains a Documentation block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex review — TOFU windows disclosed, legacy TOTP, absence test at three boundaries

Two P1 and three P2 from the Codex review of 56f23a36, all verified against
the code. trust-model.md now states the desktop's first-connection TLS TOFU
window and the out-of-band fingerprint check; scopes identity-key pinning to
changes after the first pin, not first contact; discloses that databases from
before TOTP encryption may still hold plaintext secrets and how re-enrolment
fixes that. The absence contract gains two sibling tests — WebSocket wire
types from protocol/schema.json and every koanf key of config.Config (one
allowlisted on-disk path whose presence the test asserts) — and the document
states what the three tests bound. plugins.md corrected: unknown config keys
are warned about and ignored, not rejected. Evidence block records PR #1443
and the review outcome.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex re-review — desktop first-use window in every TLS mode; tls off is plaintext

The desktop pins the fingerprint it sees on first connection in every
tls.mode (CaptureVerifier, no web-PKI validation on the server connection),
so a public-CA certificate closes the first-use window only for a browser;
the short answer and the pinning list now say so. tls.mode off served
directly is plaintext HTTP with nothing enforcing a proxy; the transport
table row states it. Evidence block records the round-2 outcome.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex round 3 — E2EE does not survive a hostile operator on first contact; memory cap is server-wide

Identity keys are trusted on first use, so a modified server can deliver an
unpinned peer's first announce with keys the operator holds and the key
holder wraps the room key to it. trust-model.md now scopes E2EE to an
operator who reads, and to a modified server only for peers pinned and
compared out of band beforehand, in every place the stronger claim stood.
plugins.md: the wazero runtime is sized from plugins.max_memory_mb alone;
a manifest's memory value is validated but not applied. Evidence block
records the round.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex round 4 — transport intro excludes tls off; ipAllowed is not the full C-09 deny-set

The transport section opened with "everything is TLS"; it now excludes
tls.mode off. The C-09 contract cited the server's ipAllowed as the complete
address deny-set; it rejects loopback, private, link-local, unspecified,
multicast and CGN only, so the clause now lists the documentation and
benchmarking ranges the native broker must add and records that widening
ipAllowed is a separate server change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex round 5 — backups exclude uploads; release-time appimagetool fetch listed

The built-in backup is VACUUM INTO of the SQLite file only; the trust model
and deployment.md now say uploaded files are not in it and upload.storage_dir
needs its own backup. The outbound-host section scopes "no script fetches an
external host" to scripts the server runs and lists the release workflow's
build-time appimagetool download.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

* fix(b2-7): Codex round 6 — one pin per account, LiveKit media in the host table, quick-start wording

Identity pins are keyed by host and user id, so a peer's second device
overwrites the pin and the first device then mismatches; the document no
longer claims per-device pinning. The outbound-host table gains the
supervised LiveKit subprocess's WebRTC media and scopes the capture contract
to traffic the server initiates. The quick-start cross-link no longer says
voice and video are unreadable by the operator.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rg9QQWVN3E5UUgBD2dydtu

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 11:49:24 +00:00

109 lines
10 KiB
Markdown
Raw Permalink Blame History

# Documentation index
Every document in `docs/` is listed here. If it is not on this page it is not
current guidance.
Docs fall into four kinds, and the difference matters when you are deciding
whether to trust one: **guidance** tells you how to do something,
**reference** describes a contract the code actually implements, **audits** are
dated snapshots that were true when written and were never updated, and
**plans** record intent. Read an audit as history, not as status.
## Start here
| I want to… | Read |
| ----------------------- | ----------------------------------------------------------- |
| Run a server | [quick-start.md](quick-start.md) |
| Deploy for real | [deployment.md](deployment.md) |
| Contribute a change | [contributing.md](contributing.md) |
| Understand the system | [architecture/](architecture/README.md) |
| Report a bug | [Issues](https://github.com/J3vb/OwnCord/issues/new/choose) |
| Ask, or suggest an idea | [Discussions](https://github.com/J3vb/OwnCord/discussions) |
| Report a vulnerability | [security.md](security.md) |
| Know who can read what | [trust-model.md](trust-model.md) |
## Guidance
| Document | Covers |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [quick-start.md](quick-start.md) | Getting a server running with the fewest steps. |
| [deployment.md](deployment.md) | Production deployment on Windows and Linux. |
| [contributing.md](contributing.md) | Environment setup, **the branch and PR model**, coding standards, how to run the checks CI runs. |
| [security.md](security.md) | How to report a vulnerability, and how findings are handled in public vs private. |
| [trust-model.md](trust-model.md) | Who can read what: operator-readable text and files, E2EE media, transport, at rest, what beta does not claim. |
| [livekit-setup.md](livekit-setup.md) | Standing up the LiveKit SFU for voice and video. |
| [port-forwarding.md](port-forwarding.md) | Making a server reachable from outside the LAN. |
| [tailscale.md](tailscale.md) | Remote access without port forwarding. |
| [mcp-introspect.md](mcp-introspect.md) | Dev-only MCP server for introspecting a running instance. |
## Reference
These describe contracts the code implements. If one disagrees with the code,
the code is right and the document is a bug.
| Document | Covers |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [api.md](api.md) | REST API under `/api/v1`. |
| [protocol.md](protocol.md) | WebSocket protocol — frames, sequencing, reconnect. |
| [schema.md](schema.md) | SQLite schema and migrations. |
| [server-configuration.md](server-configuration.md) | Every server configuration option. |
| [credential-storage.md](credential-storage.md) | What the desktop client persists, and where. |
| [../protocol/schema.json](../protocol/schema.json) | **Generated-code source of truth**, at the repository root because it is owned by neither side. `Server/ws/message_types.go` and `Client/src/lib/protocolTypes.ts` are generated from it — never hand-edit either. See [../protocol/README.md](../protocol/README.md). |
## Architecture
[architecture/README.md](architecture/README.md) indexes the blueprints and
carries the maintenance rule: each blueprint names its source-of-truth files,
and a PR touching those updates the blueprint in the same change.
- [system-overview.md](architecture/system-overview.md), [server.md](architecture/server.md), [client.md](architecture/client.md)
- [data-model.md](architecture/data-model.md), [websocket.md](architecture/websocket.md), [voice-e2ee.md](architecture/voice-e2ee.md)
- [ux/](architecture/ux/README.md) — target-state UX spec, per-view states and event→reaction maps
- [platform-contracts.md](architecture/platform-contracts.md) — target-state desktop/browser seam: what has to move behind a contract before the client can run in a browser (B7)
- [plugins.md](architecture/plugins.md) — the experimental WASM plugin boundary: off by default, compiled out of releases, no API promise, what may become a plugin after beta and what never moves
[client-architecture.md](client-architecture.md) is a redirect stub; the live
document is [architecture/client.md](architecture/client.md).
## Audits — dated, not maintained
Point-in-time snapshots. They are **not** updated as the code moves, and they
are deliberately left alone when paths change, so links from commit messages
keep resolving. Anything here may be stale; the ledger and the plan index carry
current status.
| Audit | Scope |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| [audit-2026-08-23-repository-layout.md](audit-2026-08-23-repository-layout.md) | Repository layout and contributor experience (`RL-01`…`RL-22`). |
| [audit-2026-08-23-repository-health.md](audit-2026-08-23-repository-health.md) | Full repository health. |
| [audit-2026-08-19.md](audit-2026-08-19.md) | Repo health. **States "0 open findings" — untrue since; see the ledger.** |
| [audit-test-coverage-2026-08-19.md](audit-test-coverage-2026-08-19.md) | Test audit (`T-*`, a separate register from the `OC-*` ledger). |
| [audit-2026-08-04-docs-and-coverage.md](audit-2026-08-04-docs-and-coverage.md) | Documentation accuracy and UI/UX test coverage. |
| [audit-2026-08-04.md](audit-2026-08-04.md) | Security review. |
| [audit-test-coverage-2026-07-25.md](audit-test-coverage-2026-07-25.md) | Test-coverage audit. |
| [audit-2026-07-19.md](audit-2026-07-19.md) | Architecture and spec-conformance review. |
| [audit-2026-04-07.md](audit-2026-04-07.md) | First comprehensive audit. |
## Plans
[plans/README.md](plans/README.md) indexes every plan with a recorded state —
active, partially implemented, design-only, or shipped — and **is the authority
over a plan's own header**, which can drift.
## Where status actually lives
Do not read a defect count, or a "what works" claim, out of a document on this
page. Status has owners:
| Concern | Source of truth |
| -------------------------- | ---------------------------------------------------------------------------------- |
| Defect status | `.superpowers/findings-ledger.json` (`FINDINGS.md` is rendered from it) |
| Security-sensitive defects | Private GitHub Security Advisories |
| Phase order and gates | [plans/repo-health-roadmap-2026-08-23.md](plans/repo-health-roadmap-2026-08-23.md) |
| Current measured baseline | [plans/b0-baseline-2026-08-25.md](plans/b0-baseline-2026-08-25.md) |
| Generated-code contracts | `CLAUDE.md`, "Generated code — never hand-edit" |
A CI job checks that documents on this page do not contradict the ledger's
counts. Adding a count to a document means adding it to that check's allow-list
in `scripts/check-doc-counts.mjs`.
Reference in New Issue View Git Blame Copy Permalink