src/SUMMARY.md

@@ -2,25 +2,23 @@
 
 - [Overview and History](./overview.md)
 - [Risk Model](./risk.md)
-- [Cwtch Overview](./cwtch-overview.md)
-    - [Component Ecosystem Breakdown](./components.md)
+- [Cwtch Technical Basics](./cwtch-overview.md)
+- [Open Questions](./open-questions.md)
+- [Cwtch Library](./cwtch.md)
     - [Message Formats](./message_formats.md)
     - [Groups](./groups.md)
     - [Tapir](./tapir.md)
       - [Packet Format](./packet_format.md)
       - [Authentication Protocol](./authentication_protocol.md)
     - [Connectivity](./connectivity.md)
-    - [Risks](./cwtch-risks.md)
-  - [Cwtch UI](./ui.md)
-      - [Profile Encryption & Storage](./profile_encryption_and_storage.md)
-      - [Android Service](./android.md)
-      - [Message Overlays](./overlays.md)
-        - [Image Previews](./image_previews.md)
-      - [Input](./input.md)
-  - [Cwtch Servers](./server.md)
-      - [Key Bundles](./key_bundles.md)
+- [Cwtch UI](./ui.md)
+    - [Profile Encryption & Storage](./profile_encryption_and_storage.md)
+    - [Android Service](./android.md)
+    - [Message Overlays](./overlays.md)
+    - [Input](./input.md)
+- [Cwtch Servers](./server.md)
+    - [Key Bundles](./key_bundles.md)
 - [Development](./development.md)
 - [Deployment](./deployment.md)
-- [Open Questions](./open-questions.md)
 - [References](./references.md)
 

src/components.md

@@ -1,75 +0,0 @@
-# Component Ecosystem Breakdown
-
-Cwtch is made up of several smaller component libraries. This chapter will provide a brief overview of
-each component and how it relates to the wider Cwtch ecosystem.
-
-## [openprivacy/connectivity](https://git.openprivacy.ca/openprivacy/connectivity) 
-
-Summary: A library providing an ACN (Anonymous Communication Network ) networking abstraction.
-
-The goal of connectivity is to abstract away the underlying libraries/software needed to communicate with a 
-specific ACN. Right now we only support Tor and so the job of connectivity is to:
-
-* Start and Stop the Tor Process
-* Provide configuration to the Tor process
-* Allow raw connections to endpoints via the Tor process (e.g. connect to onion services)
-* Host endpoints via the Tor process (e.g. host onion services)
-* Provide status updates about the underlying Tor process
-
-For more information see [connectivity](./connectivity.md)
-
-## [cwtch.im/tapir](https://git.openprivacy.ca/cwtch.im/tapir)
-
-Summary: Tapir is a small library for building p2p applications over anonymous communication systems.
-
-The goal of tapir is to abstract away **applications** over a particular ACN. Tapir supports:
-
-* Creating a cryptographic identity (including ephemeral identities) 
-* Maintaining a connection pool of inbound and outbound connections to services
-* Handling various application-layers including cryptographic transcripts, [authentication and authorization protocols](https://docs.openprivacy.ca/cwtch-security-handbook/authentication_protocol.html#authentication-protocol), and
-[token-based services via PrivacyPass](https://docs.openprivacy.ca/cwtch-security-handbook/tapir.html#token-app),
-
-For more information see [tapir](./tapir.md)
-
-## [cwtch.im/cwtch](https://git.openprivacy.ca/cwtch.im/cwtch)
-
-Summary: Cwtch is the main library for implementing the cwtch protocol / system.
-
-The goal of cwtch is to provide implementations for cwtch-specific applications e.g.
-message sending, groups, and  file sharing(implemented as Tapir applications), provide interfaces for managing and storing Cwtch profiles, provide an event bus for subsystem splutting and building plugins with new functionality, in addition to managing other core functionality.
-
-The cwtch library is also responsible for maintaining canonical model representations for wire formats and overlays.
-
-
-## [cwtch.im/libcwtch-go](https://git.openprivacy.ca/cwtch.im/libcwtch-go)
-
-Summary: libcwtch-go provides C (including Android) bindings for Cwtch for use in UI implementations.
-
-The goal of libcwtch-go is to bridge the gap between the backend cwtch library and any front end systems which
-may be written in a different language.
-
-The API provided by libcwtch is much more restricted than the one provided by Cwtch directly, each libcwtch API typically
-packages up several calls to Cwtch.
-
-libcwtch-go is also responsible for managing UI settings and experimental gating. It is also often used as a staging ground
-for experimental features and code that may eventually end up in Cwtch.
-
-## [cwtch-ui](https://git.openprivacy.ca/cwtch.im/cwtch-ui)
-
-Summary: A flutter based UI for Cwtch.
-
-Cwtch UI uses libcwtch-go to provide a complete UI for Cwtch, allowing people to create and manage profiles,
-add contacts and groups, message people, share files (coming soon) and more.
-
-The UI is also responsible for managing localization and translations.
-
-For more information see [Cwtch UI](./ui.md)
-
-## Auxiliary Components
-
-Occasionally, Open Privacy will factor out parts of Cwtch into standalone libraries that are not Cwtch specific.
-These are briefly summarized here:
-
-### [openprivacy/log](https://git.openprivacy.ca/openprivacy/log)
-
-An Open Privacy specific logging framework that is used throughout Cwtch packages.

src/cwtch-risks.md

@@ -1,70 +0,0 @@
-# Risks
-
-## Private information transiting the IPC boundary
-
-**Status: Requires privileged user to exploit**
-
-Information used to derive the encryption key used to save all sensitive data to
-the file system cross the boundary between the UI front-end and the App backend.
-
-Intercepting this information requires a privileged position on the local
-machine.
-
-## Testing Status
-
-Cwtch features one [well-defined integration test](https://openprivacy.ca/discreet-log/06-cwtch-integ-tests/) which exercise the ideal case of
-three well-formed peers authenticating and messaging each other through an
-untrusted server.
-
-Tests are run with the `-race` flag which will cause them to fail if
-race conditions are detected.
-
-Both integration tests and unit tests are run automatically for every pull request and main branch merge.
-
-## Resolved or Outdated Risks
-
-
-
-### Dependency on Outdated Protobuf Implementation
-
-**Status: Mitigated**
-
-The group features of Cwtch are enabled by an untrusted infrastructure
-protcol that was originally implemented using the older ricochet-based channels. The go
-code that was generated from these channels no longer works given the newest
-version of the protobufs framework.
-
-We have removed protobufs entirely from the project by porting this
-functionality over the Tapir.
-
-### Proof of Work (PoW) Spam Prevention as a Metadata Vector
-
-**Status: Outdated**: Cwtch now uses Token Based Services to separate challenges like PoW from
-resolving the tokens.
-
-Processing capabilities are not constant, and so a malicious server could perform
-some correlations/fiddle with difficulty per connection in an attempt to identify
-connections over time.
-
-Needs some statistical experimentation to quantify, but given the existing
-research detecting timeskews over Tor I wouldn't be surprised if this could be derived.
-
-As for mitigation: Adding a random time skew might be an option,some defense
-against the server adjusting difficulty too often would also mitigate some of
-the more extreme vectors.
-
-Additionally, Token Based Services and Peer-based Groups are both potential
-options for eliminating this attack vector entirely.
-
-## Thread Safety
-
-**Status: Mitigated**
-
-The Cwtch library evolved from a prototype that had weak checks around
-concurrency, and the addition of singleton behavior around saving profiles to
-files and protocol engines resulted in race conditions.
-
-The inclusion of the `Event Bus` made handling such cases easier, and the
-code is now tested via unit tests and integration test
-running the `-race` flag.
-

src/cwtch.md

@@ -1,3 +1,70 @@
-# Cwtch
+# Cwtch Library
+
+## Private information transiting the IPC boundary
+
+**Status: Requires privileged user to exploit**
+
+Information used to derive the encryption key used to save all sensitive data to
+the file system cross the boundary between the UI front-end and the App backend.
+
+Intercepting this information requires a privileged position on the local
+machine.
+
+## Testing Status
+
+Cwtch features one [well-defined integration test](https://openprivacy.ca/discreet-log/06-cwtch-integ-tests/) which exercise the ideal case of
+three well-formed peers authenticating and messaging each other through an
+untrusted server.
+
+Tests are run with the `-race` flag which will cause them to fail if
+race conditions are detected. 
+
+Both integration tests and unit tests are run automatically for every pull request and main branch merge.
+
+## Resolved or Outdated Risks
 
 
+
+### Dependency on Outdated Protobuf Implementation
+
+**Status: Mitigated**
+
+The group features of Cwtch are enabled by an untrusted infrastructure
+protcol that was originally implemented using the older ricochet-based channels. The go
+code that was generated from these channels no longer works given the newest
+version of the protobufs framework.
+
+We have removed protobufs entirely from the project by porting this
+functionality over the Tapir.
+
+### Proof of Work (PoW) Spam Prevention as a Metadata Vector
+
+**Status: Outdated**: Cwtch now uses Token Based Services to separate challenges like PoW from
+resolving the tokens. 
+
+Processing capabilities are not constant, and so a malicious server could perform
+ some correlations/fiddle with difficulty per connection in an attempt to identify
+  connections over time.
+
+Needs some statistical experimentation to quantify, but given the existing 
+research detecting timeskews over Tor I wouldn't be surprised if this could be derived.
+
+As for mitigation: Adding a random time skew might be an option,some defense 
+against the server adjusting difficulty too often would also mitigate some of 
+the more extreme vectors.
+
+Additionally, Token Based Services and Peer-based Groups are both potential
+ options for eliminating this attack vector entirely.
+
+## Thread Safety
+
+**Status: Mitigated**
+
+The Cwtch library evolved from a prototype that had weak checks around
+concurrency, and the addition of singleton behavior around saving profiles to
+files and protocol engines resulted in race conditions.
+
+The inclusion of the `Event Bus` made handling such cases easier, and the
+code is now tested via unit tests and integration test
+running the `-race` flag.
+

src/deployment.md

@@ -10,7 +10,7 @@ compromised then there is nothing in our current process that would detect this.
 
 We need:
 
-* Reproducible Builds - we currently use public docker containers for all builds
+* Reproducible Builds - we currently use puplic docker containers for all builds
   which should allow anyone to compare distributed builds with ones built from source.
  * Signed Releases - Open Privacy does not yet maintain a public record of staff
  public keys. This is likely a necessity for signing released builds and

src/development.md

@@ -18,8 +18,8 @@ committed to make it as easy as possible to contribute to Cwtch while also
 
 **Status: Mitigated** 
 
-`trunk` is currently locked and only 3 Open Privacy staff members have permission
-to override it, in addition the responsibility of monitoring changes.
+Master is currently locked and 3 Open Privacy staff members have permission
+to override it, and the responsibility of monitoring changes.
 
 Further every new pull request and merge triggered automated builds & tests
  which trigger emails and audit logs.
@@ -28,7 +28,7 @@ The code is also open source and inspectable by anyone.
 
 ### Risk: Code Regressions
 
-**Status: Partially Mitigated** (See individual project entries in this
+**Status: Partially Mitgated** (See individual project entries in this
  handbook for more information)
  
 Our automated pipelines have the ability to catch regressions when that

src/image_previews.md

@@ -1,35 +0,0 @@
-# Image Previews
-
-Built on the back of filesharing in Cwtch 1.3, image previews are keyed by the suggested filename’s extension (and no, we’re not interested in using MIME types or magic numbers) and advertised size. If enabled, the preview system will automatically download shared images to a configured downloads folder and display them as part of the message itself. (Due to limitations on Android, they’ll go to the app’s private storage cache, and give you the option to save them elsewhere later instead.) The file size limit is TBD but will obviously be much lower than the overall filesharing size limit, which is currently 10 gigabytes.
-
-For now, we only support single-image messages, and any image editing/cropping will have to be done in a separate application. As we mention in the filesharing FAQ, image files also frequently contain significant hidden metadata, and you should only share them with people you trust.
-
-## KnownRisks
-
-## Other Applications and/or the OS Inferring Information from Images
-
-Images must be stored somewhere, and for now we have chosen to store them unencrypted on the file system. We have done this
-for 2 reasons:
-
-1. In order to support more powerful file sharing schemes like rehosting we require the ability to efficiently
-scan files and deliver chunks - doing this through an encrypted database layer would harm performance.
-2. This information always has to transit the application boundary (either via display drivers, or storing and viewing
-   the file in an external application) - there is nothing that Cwtch can do after that point in any case.
-   
-## Malicious Images  Crashing or otherwise Compromising Cwtch
-
-Flutter uses Skia to render Images. While the underlying code is memory unsafe, it is [extensively fuzzed](https://github.com/google/skia/tree/main/fuzz) as part of regular development.
-
-We also conduct our own fuzz testing of Cwtch components. In that analysis we found a single crash bug related
-to a malformed GIF file that caused the renderer to allocate a ridiculous amount of memory (and eventually be refused
-by the kernel). To prevent this from impacting Cwtch we have adopted the policy of always enabling a maximum `cacheWidth`
-and/or `cacheHeight` for Image widgets.
-
-## Malicious Images Rendering Differently on Different Platforms, Potentially Exposing Metadata
-
-Recently [a bug was found in Apple's png parser](https://www.da.vidbuchanan.co.uk/widgets/pngdiff/) which would cause an image to render differently on Apple devices as it would on non-Apple devices.
-
-We conducted a few tests on our Mac builds and could not replicate this issue for Flutter (because all Flutter builds use Skia for rendering), however we will continue to include such cases in our testing corpus.
-
-For now image previews will remain experimental and opt-in.
-

src/packet_format.md

@@ -10,4 +10,3 @@ note in this case the actual usable size of the data packet is 8190-14 to accomm
 
 For information on how the secret key is derived see the [authentication protocol](./authentication_protocol.md)
 
-