Site operators tour

webcat-documentation/src/concepts.md

@@ -41,9 +41,7 @@
 
  - **Web app developers** build a static web application that complies with the restrictions required for WEBCAT to operate securely. They publish *enrollment information* describing their signing identities and trust policy. For each release, they build the application, generate a *manifest* describing the release and its assets, sign it, and record it in a transparency log.
 
- - **Website operators** or **administrators** (who may also be developers) are responsible for publishing the web application, its *enrollment information*, and the corresponding *manifest*. They configure the web server to comply with parameters specified in the manifest, such as the default Content Security Policy and the default entry point (e.g., the index page). Website administrators are also responsible for enrolling their domain in the *WEBCAT enrollment system* and for signaling *enrollment changes* over time. 
-
- In centralized deployments, website administrators and developers are typically the same entity.
+ - **Website operators** or **administrators** (who may also be developers) are responsible for publishing the web application, its *enrollment information*, and the corresponding *manifest*. They configure the web server to comply with parameters specified in the manifest, such as the default Content Security Policy and the default entry point (e.g., the index page). Website administrators are also responsible for enrolling their domain in the *WEBCAT enrollment system* and for signaling *enrollment changes* over time. In centralized deployments, website administrators and developers are typically the same entity.
 
  - **Infrastructure operators** such as the Freedom of the Press Foundation (FPF), run components of the *WEBCAT enrollment system*. The enrollment system is a distributed, consensus-based system; no single operator has unilateral control over its state or decisions.
 

webcat-documentation/src/contributors/README.md

@@ -3,4 +3,5 @@
 This section is for anyone contributing to WEBCAT development.
 
 * If you're interested in the Rust enrollment infrastructure, see [Enrollment Infrastructure](./enrollment-infrastructure.md).
-* If you're interested in the Browser Extension, see [Browser Extension](./browser-extension.md).
+* If you're interested in the Browser Extension, see [Browser Extension](./browser-extension.md).
+* If you're interested in the command line tool, see the [webcat-cli code repo](https://github.com/freedomofpress/webcat-cli?#webcat-cli).

webcat-documentation/src/contributors/enrollment-infrastructure.md

@@ -3,3 +3,5 @@
 **[WEBCAT Infra Chain](https://github.com/freedomofpress/webcat-infra-chain)** is the repository for the Rust enrollment infrastructure.
 
 See the basic architecture explained [here](../architecture/enrollment-infrastructure).
+
+Next, [get started](./enrollment-infrastructure/getting_started.md) running the `webcat-infra-chain` project.

webcat-documentation/src/faq.md

@@ -9,7 +9,7 @@ Sites opt into WEBCAT by publishing a signed manifest of their web application r
 ### How is this different from HTTPS?
 
 HTTPS doesn't protect your users if the site hosting the web application itself
-gets hacked.
+gets hacked. While HTTPS guarantees that the code you received is the code the server sent, it says nothing about whether the code the server sent is the code its developers intended to publish. In contrast, [WEBCAT provides a tamper-evident seal](https://freedom.press/tech/news/webcat-a-tamper-evident-seal-for-the-open-web/) on web application code.
 
 ### How is this different from Subresource Integrity (SRI)?
 

webcat-documentation/src/for-users.md

@@ -1,5 +1,7 @@
 # For users
 
+The WEBCAT browser extension is a curious cat that pokes around websites, letting you know if something doesn't smell right. By investigating the origin of the code running in your browser, it can help you trust the websites you use. 
+
 ## Getting started
 
 Users can install the WEBCAT extension via the Mozilla Add-ons Store (AMO). Firefox is currently the only supported browser.

webcat-documentation/src/introduction.md

@@ -1,6 +1,6 @@
 # Introduction
 
-WEBCAT is a system for verifying the provenance of static web assets. The motivation is to solve the "[Javascript cryptography considered harmful](https://web.archive.org/web/20200731144044/https://www.nccgroup.com/us/about-us/newsroom-and-events/blog/2011/august/javascript-cryptography-considered-harmful/)" problem, making E2EE via the web more secure.
+WEBCAT is a system for verifying the provenance of static web assets; [a tamper-evident seal](https://freedom.press/tech/news/webcat-a-tamper-evident-seal-for-the-open-web/) for websites. The motivation is to solve the "[Javascript cryptography considered harmful](https://web.archive.org/web/20200731144044/https://www.nccgroup.com/us/about-us/newsroom-and-events/blog/2011/august/javascript-cryptography-considered-harmful/)" problem, making E2EE via the web more secure.
 
 Questions? Read our [FAQ](./faq.md).
 

webcat-documentation/src/site-operators/README.md

@@ -9,7 +9,10 @@ Assets that WEBCAT can verify include any web apps that meet [the requirements](
 ## Getting Started
 WEBCAT needs two main configuration and metadata files for enrolling into the system and providing all the necessary information to browsers for verification: an `enrollment.json` and a `manifest.json`, which are combined into a `bundle.json`.
 
-These files are produced with the [`webcat-cli`](./cli/README.md) utility. See its [installation instructions](./cli/installation.md) to get set up, and the [enrollment](./cli/enrollment.md), [manifest](./cli/manifest.md), and [bundle](./cli/bundle.md) command references for usage. The provided [GitHub Actions](./GA.md) automate this flow for Sigstore-based deployments.
+These files are produced with the [`webcat-cli`](./cli/) utility. See its [installation instructions](./cli/installation.md) to get set up with the CLI, then follow [manual signing](./manual.md) steps or the [end-to-end example](./cli/end-to-end.md) to get your website on WEBCAT. Or, use the provided [GitHub Actions](./GA.md) which automate this flow for Sigstore-based deployments.
+
+Detailed [enrollment](./cli/enrollment.md), [manifest](./cli/manifest.md), and [bundle](./cli/bundle.md) CLI references are also available.
+
 
 ### Enrollment
 The `/.well-known/webcat/enrollment.json` file contains information about the root of trust and how to verify it. For instance, in the case of a Sigstore-type enrollment, it records the trust material for Sigstore, and claims about provenance or identities. In the case of a Sigsum-type enrollment, it records the public keys of the authorized signers, a minimum threshold of valid signatures, and the Sigsum trust policy.

webcat-documentation/src/site-operators/cli/README.md

@@ -1,13 +1,18 @@
 # WEBCAT CLI
 
-Utilities for creating, validating, and packaging WEBCAT enrollments and manifests.
+The CLI contains utilities for creating, validating, and packaging WEBCAT enrollments and manifests. It can be used to quickly integrate and enroll a web application or domain into WEBCAT.
+
+The [CLI code repository](https://github.com/freedomofpress/webcat-cli) also contains [GitHub Actions](../GA.md) which automate the use of the CLI.
 
 ## Quick Start
 
-This utility, together with the GitHub Actions provided in the same repository, can be used to quickly integrate and enroll a web application or domain into WEBCAT. The recommended steps are:
+If you are a **website operator** or publisher, here is how you can use the CLI to get your website onto WEBCAT:
+
+1. [Choose Sigsum or Sigstore](./sigsum-or-sigstore.md) for enrollment.
+2. [Install the CLI](./installation.md).
+3. Produce WEBCAT artifacts by following the [manual signing](../manual.md) steps.
+    * (Or, use the [end-to-end example](./end-to-end.md) example of those steps, or the [the GitHub Actions](../GA.md) automation of those steps.)
+    * Refer to [`webcat.config.json`](./config-schema.md) when creating your configuration file.
+
+If you are also the **develper** of the web app you will be publishing, you must first [prepare your web application](../../webapp-developers/preparing-your-app.md) so it is compatible with WEBCAT. 
 
-1. [Prepare your web application](../../webapp-developers/preparing-your-app.md) so it is compatible with WEBCAT.
-2. [Choose Sigsum or Sigstore](./sigsum-or-sigstore.md) for enrollment.
-3. [Install the CLI](./installation.md).
-4. Produce your artifacts with the [enrollment](./enrollment.md), [manifest](./manifest.md), and [bundle](./bundle.md) commands — see the [end-to-end example](./end-to-end.md).
-5. Configure your application with [`webcat.config.json`](./config-schema.md).

webcat-documentation/src/site-operators/cli/installation.md

@@ -19,11 +19,18 @@ To run the installed CLI:
 npx webcat --help
 ```
 
-Sigsum needs to be installed separately, as it currently is only available in Go binaries:
+Sigsum needs to be installed separately, as it currently is only available in Go binaries. [Install Go](https://go.dev/doc/install) if needed, then:
 
 ```
 go install sigsum.org/sigsum-go/cmd/sigsum-key@latest
 go install sigsum.org/sigsum-go/cmd/sigsum-submit@latest
 ```
 
-By default, these binaries will be available in `$HOME/go/bin`.
+By default, these binaries will be available in `$HOME/go/bin`. Add this to your system path, then run `sigsum-key` to verify it works.
+
+## Using the CLI
+
+Once installed, you can use the CLI and sigsum for [manual signing](../manual.md) of your web assets manifest.
+
+Or, to learn more details on the sub-commands within the CLI, check the [enrollment](./enrollment.md), [mainfest](./manifest.md), and [bundle](./bundle.md) command references.
+

webcat-documentation/src/site-operators/manual.md

@@ -3,9 +3,23 @@ The following procedure describes how to use the WEBCAT CLI to generate enrollme
 
 > For full command and flag details, see the [`webcat-cli` reference](./cli/). For a condensed, copy-pasteable version of this same workflow, see the [end-to-end example](./cli/end-to-end.md).
 
+## What you'll need
+
+You will need a web app (or static website) that meets the [requirements](../webapp-developers/requirements.md). At a minumum, the app must contain an index page (like `index.html`) and an error page (like `error.html`).
+
+The app must available and versioned in source control; you will need to know the origin URL and desired version. You will need a local clone of the app, at that version, in your filesystem. To complete enrollment, you must have the capacity to deploy new assets to the app.
+
+You should know the Content Security Policy your app will use, per our [CSP guide](../webapp-developers/CSP.md).
+
+You must have [sigsum installed](./cli/installation.md).
+
+## Steps
+
+These steps will create the `manifest.json`, `enrollment.json`, and `bundle.json` that the WEBCAT browser extension will use to verify your web app. At the end you will be ready to submit your web app to the WEBCAT enrollment system.
+
 ### Create Sigsum Keys
 
-Create a folder where to store the keys. They should be kept secure and stored offline, as they will be used only to sign web application manifests at release time.
+Create a folder to store the keys. They should be kept secure and stored offline, as they will be used only to sign web application manifests at release time.
 ```
 mkdir -p keys
 sigsum-key generate -o keys/key1
@@ -33,8 +47,10 @@ quorum demo-quorum-rule
 EOF
 ```
 
+<!-- TODO: How do I create a real Sigsum trust policy? This should be explained -->
+
 ### Create a WEBCAT config file
-Write a `webcat.config.json` file. All the fields in the example are mandatory as keys, though their values can be empty. For instance, `wasm` has to be an array, but can be empty. Choose a content security policy according to the [CSP guide](../webapp-developers/CSP.md). See the [`webcat.config.json` schema](./cli/config-schema.md) for a description of each field.
+Write a `webcat.config.json` file. All the keys and values are required. See the [`webcat.config.json` schema](./cli/config-schema.md) for a description of each field. 
 
 ```
 cat > webcat.config.json <<EOF
@@ -51,6 +67,11 @@ cat > webcat.config.json <<EOF
 }
 EOF
 ```
+Tips to create a valid file
+* `app` and `version` must point to a source control repository <!-- TODO: why is this required? -->
+* `default_csp` should be set according to the [CSP guide](../webapp-developers/CSP.md).
+* `wasm` has to be an array, but can be empty.
+* `default_fallback` must start with a `/`
 
 ### Create enrollment.json
 
@@ -67,7 +88,7 @@ Generate a manifest file to sign later. Requires in input a `--directory`, which
 The utility supports optional multiple `--exclude` parameters to exclude files from the manifest but that are in the folder. The utility will automatically scan for `.wasm` files to hash and add to the `wasm` array. If you have inline WASM, not sourced from a file, or your WASM files have a different extension, you have to manually add the hashes to the `wasm` array in `webcat.config.json` in base64url format.
 
 ```
-npx webcat manifest generate --policy-file trust_policy --config webcat.config.json --directory "/path/to/my/app"--output manifest_unsigned.json
+npx webcat manifest generate --policy-file trust_policy --config webcat.config.json --directory "/path/to/my/app" --output manifest_unsigned.json
 ```
 
 
@@ -92,6 +113,7 @@ Remember to deploy:
  - `/.well-known/webcat/manifest.json`
  - `/.well-known/webcat/bundle.json`
 
+<!-- TODO: It would be really nice if there were a way to verify a deployment before submitting! Kinda scary otherwise; is my app going to become unreachable for WEBCAT users if my deployment is wrong? -->
 
 ### Check that the bundle verifies
 Check that the manifest in a bundle is valid according to its enrollment information.

webcat-documentation/src/webapp-developers/requirements.md

@@ -32,3 +32,6 @@ Some HTTP headers can influence the execution environment of a webpage, and as s
  - *Refresh* header is blocked.
  - *Link* header is blocked.
 
+## Minimum app contents
+
+In order for a site operator to use the [WEBCAT CLI](../site-operators/cli/) with the app, at a minimum it must contain a static index page (like `index.html`) and an error page (like `error.html`).