From 32fb86f82668ba227dc799f9e682a4a361cdeb3f Mon Sep 17 00:00:00 2001
From: "@permadeath.com" <did:plc:nlzmjyfv6loqtxyzvdcznwgf>
Date: Thu, 13 Aug 2026 13:19:04 -0400
Subject: [PATCH] feat(web): add an /architecture page and link it from the
 privacy policy

The audience is somebody auditing the extension, a Chrome Web Store
reviewer included: the diagram names the four contexts and which side of
the browser each network call lands on, and the tables under it name
every host, every call and everything kept in storage. The privacy
policy makes the same claims in prose, and now links here for the map.

The diagram is inlined from the pre-rendered SVG, so it takes the
theme's tokens rather than one baked-in palette. verify:dist checks the
shipped bytes for a <style> element or a style attribute, since a
regenerated diagram carrying either would pass every local check and
then render as black boxes behind the real CSP.

The page is also linked from the homepage footer, beside the source and
license links, rather than from the pitch above it: it is a developer
link, and the front of the site is nobody's audit trail.
---
 web/scripts/verify-dist.mjs      |  23 +++
 web/src/pages/architecture.astro | 263 +++++++++++++++++++++++++++++++
 web/src/pages/index.astro        |   2 +
 web/src/pages/privacy.astro      |   5 +
 web/src/styles/global.css        | 128 +++++++++++++++
 5 files changed, 421 insertions(+)
 create mode 100644 web/src/pages/architecture.astro

diff --git a/web/scripts/verify-dist.mjs b/web/scripts/verify-dist.mjs
index a2de9c3..14cb326 100644
--- a/web/scripts/verify-dist.mjs
+++ b/web/scripts/verify-dist.mjs
@@ -145,6 +145,29 @@ if (!existsSync(join(dist, "privacy/index.html"))) {
   problems.push("privacy/index.html missing — the store listing links it");
 }
 
+// The architecture diagram is inlined SVG under the same CSP as everything
+// else: `script-src` has no 'unsafe-inline' and `style-src` is bare 'self',
+// which covers inline SVG in the document. A regenerated diagram that brought
+// Mermaid's own <style> or a style attribute back would render as black boxes
+// in production and pass every local check, since nothing serves the CSP in
+// dev. Check the shipped bytes rather than trusting the render script.
+const architecture = join(dist, "architecture/index.html");
+if (!existsSync(architecture)) {
+  problems.push("architecture/index.html missing — the privacy policy links it");
+} else {
+  const page = readFileSync(architecture, "utf8");
+  if (!page.includes("<svg")) {
+    problems.push("architecture/index.html has no inline SVG — the diagram did not render");
+  }
+  if (/<style[\s>]/i.test(page)) {
+    problems.push("architecture/index.html has a <style> element, which style-src 'self' would drop");
+  }
+  // `font-style="normal"` is all over Mermaid's text, hence the boundary.
+  if (/(^|[\s"'])style\s*=/i.test(page)) {
+    problems.push("architecture/index.html has a style attribute, which style-src 'self' would drop");
+  }
+}
+
 if (problems.length > 0) {
   console.error(`verify-dist: FAILED (${problems.length} problem(s)):`);
   for (const p of problems) console.error(`  - ${p}`);
diff --git a/web/src/pages/architecture.astro b/web/src/pages/architecture.astro
new file mode 100644
index 0000000..00b8b03
--- /dev/null
+++ b/web/src/pages/architecture.astro
@@ -0,0 +1,263 @@
+---
+import Layout from "../layouts/Layout.astro";
+
+// The diagram is inlined rather than loaded, for the same reason the wordmark
+// is on the homepage: as one element in the document it takes the page's theme
+// tokens (see `.diagram` in global.css) instead of baking in one palette.
+//
+// It is inlined *pre-rendered*, because substandard.blog is served behind a
+// strict CSP with no `unsafe-inline` and no `unsafe-eval`: a client-side
+// Mermaid would need a script the CSP blocks. `npm --prefix web run diagram`
+// renders web/src/diagrams/architecture.mmd in headless Chrome and strips the
+// CSS the CSP would drop; nothing here ships a script.
+import diagram from "../diagrams/architecture.svg?raw";
+
+const REPO = "https://tangled.org/permadeath.com/substandard";
+const src = (path: string) => `${REPO}/blob/main/${path}`;
+
+// Who calls whom. Every row is a request the extension makes itself; links a
+// person clicks (a reader, a Bluesky profile) are left out, since they are
+// ordinary navigations and not the extension talking.
+const calls = [
+  {
+    from: "background worker",
+    to: "the site you are viewing",
+    what: "GET /.well-known/site.standard.publication",
+    why: "detect a publication, and check that its record points back at the site",
+  },
+  {
+    from: "background worker",
+    to: "plc.directory, public.api.bsky.app",
+    what: "DID documents, identity.resolveHandle",
+    why: "turn a DID into a PDS host, and a handle into a DID",
+  },
+  {
+    from: "background worker",
+    to: "the publication's PDS",
+    what: "repo.getRecord",
+    why: "the publication and document records the page's link tags name",
+  },
+  {
+    from: "background worker",
+    to: "your PDS",
+    what: "repo.listRecords",
+    why: "your own subscriptions, blocks and follows, to know what to show",
+  },
+  {
+    from: "popup",
+    to: "the owner's PDS",
+    what: "repo.getRecord, sync.getBlob",
+    why: "the owner's profile, and avatar or publication icon images",
+  },
+  {
+    from: "popup",
+    to: "constellation.microcosm.blue",
+    what: "GET /links/distinct-dids",
+    why: "who else has a subscription record pointing at this publication",
+  },
+  {
+    from: "popup",
+    to: "the labelers your account subscribes to",
+    what: "label.queryLabels",
+    why: "moderation labels on the publication and its owner",
+  },
+  {
+    from: "popup",
+    to: "your PDS",
+    what: "repo.createRecord, repo.deleteRecord",
+    why: "subscribe and unsubscribe; post feedback if you use the feedback form",
+  },
+  {
+    from: "offscreen document",
+    to: "your PDS and its authorization server",
+    what: "OAuth: authorization request, token, revoke",
+    why: "sign in, refresh, and sign out",
+  },
+];
+
+// Where anything that outlives a single request is kept. All of it is local;
+// there is no substandard-operated server for it to be kept on.
+const storage = [
+  {
+    where: "chrome.storage.session",
+    what: "per-tab detection state, well-known probe results, short-lived lookups",
+    life: "cleared when the browser closes",
+  },
+  {
+    where: "chrome.storage.local",
+    what: "your follow list, your chosen reader, and a non-secret session mirror (DID, handle, avatar URL)",
+    life: "until you clear it or uninstall",
+  },
+  {
+    where: "extension-origin IndexedDB and localStorage",
+    what: "OAuth tokens, DPoP keys and PKCE state, written by the OAuth client",
+    life: "until sign-out or uninstall",
+  },
+];
+---
+
+<Layout
+  title="substandard architecture"
+  description="The substandard extension's components, and which network calls each one makes."
+>
+  <header class="hero">
+    <h1>architecture</h1>
+  </header>
+
+  <main class="wide">
+    <section>
+      <h2>The moving parts</h2>
+      <p>
+        The extension runs as four separate contexts in your browser, and talks
+        to AT Protocol services directly. There is no substandard server in any
+        of these paths. Everything below is in the
+        <a href={REPO}>source repository</a>.
+      </p>
+      <figure class="diagram" set:html={diagram} />
+    </section>
+
+    <section>
+      <h2>The four contexts</h2>
+      <ul>
+        <li>
+          <strong>Content script</strong> (<a href={src("src/content.ts")}
+            ><code>src/content.ts</code></a
+          >) — runs in the page, reads its
+          <code>site.standard.publication</code> and
+          <code>site.standard.document</code> link tags, and reports those two
+          <code>at://</code> URIs to the worker. It reads nothing else from the page
+          and makes no network requests of its own.
+        </li>
+        <li>
+          <strong>Background service worker</strong> (<a
+            href={src("src/background.ts")}><code>src/background.ts</code></a
+          >) — keeps detection state per tab, sets the toolbar badge, and makes
+          the public reads: the well-known probe, identity resolution, and
+          unauthenticated record fetches.
+        </li>
+        <li>
+          <strong>Popup</strong> (<a href={src("src/popup")}
+            ><code>src/popup/</code></a
+          >) — the UI and its cards. It gathers the context around a
+          publication, and it is where writes to your PDS happen, using the
+          restored session.
+        </li>
+        <li>
+          <strong>Offscreen document</strong> (<a href={src("src/offscreen")}
+            ><code>src/offscreen/</code></a
+          >) — an invisible page that exists only to host the OAuth client,
+          which needs <code>window</code> and DOM storage that a service worker
+          does not have.
+        </li>
+      </ul>
+    </section>
+
+    <section>
+      <h2>What crosses the network</h2>
+      <p>
+        Public reads carry no cookies and no credentials
+        (<a href={src("src/lib/http.ts")}><code>src/lib/http.ts</code></a> sets
+        <code>credentials: "omit"</code>), and their answers are cached in your
+        browser. Only the last two rows are authenticated, and both go to your
+        own PDS. XRPC calls are named without their
+        <code>com.atproto.</code> prefix.
+      </p>
+      <div class="table-scroll">
+        <table>
+          <thead>
+            <tr>
+              <th>From</th>
+              <th>To</th>
+              <th>Call</th>
+              <th>For</th>
+            </tr>
+          </thead>
+          <tbody>
+            {
+              calls.map((call) => (
+                <tr>
+                  <td>{call.from}</td>
+                  <td>{call.to}</td>
+                  <td>
+                    <code>{call.what}</code>
+                  </td>
+                  <td>{call.why}</td>
+                </tr>
+              ))
+            }
+          </tbody>
+        </table>
+      </div>
+    </section>
+
+    <section>
+      <h2>What is written, and what is only read</h2>
+      <p>
+        The OAuth scope the extension asks for is listed in full in its
+        <a href="/client-metadata.json">client metadata</a>. It permits exactly
+        two kinds of write:
+      </p>
+      <ul>
+        <li>
+          <code>site.standard.graph.subscription</code> — created when you
+          subscribe, deleted when you unsubscribe, in your own repository.
+        </li>
+        <li>
+          <code>app.userinput.discussion</code> — created only when you submit
+          the feedback form.
+        </li>
+      </ul>
+      <p>
+        Everything else is read-only, including your follows, your blocks, your
+        profile and your labeler preferences. Nothing follows, blocks or posts
+        on your behalf: sharing to Bluesky opens a compose link rather than
+        writing a post.
+      </p>
+    </section>
+
+    <section>
+      <h2>What is stored, and where</h2>
+      <div class="table-scroll">
+        <table>
+          <thead>
+            <tr>
+              <th>Where</th>
+              <th>What</th>
+              <th>How long</th>
+            </tr>
+          </thead>
+          <tbody>
+            {
+              storage.map((row) => (
+                <tr>
+                  <td>
+                    <code>{row.where}</code>
+                  </td>
+                  <td>{row.what}</td>
+                  <td>{row.life}</td>
+                </tr>
+              ))
+            }
+          </tbody>
+        </table>
+      </div>
+      <p>
+        Tokens are never put in <code>chrome.storage</code>; the OAuth client
+        keeps them in the extension origin's own storage. Uninstalling the
+        extension removes all of it.
+      </p>
+    </section>
+
+    <section>
+      <h2>Why the extension asks for every site</h2>
+      <p>
+        Detection needs the well-known probe, and there is no list of which
+        sites publish on <a href="https://standard.site">standard.site</a>, so
+        the probe has to be able to run wherever you are. That is what the
+        host permissions in the manifest are for. The
+        <a href="/privacy">privacy policy</a> covers what that means for your data;
+        this page is its diagram.
+      </p>
+    </section>
+  </main>
+</Layout>
diff --git a/web/src/pages/index.astro b/web/src/pages/index.astro
index 4fda911..58fce30 100644
--- a/web/src/pages/index.astro
+++ b/web/src/pages/index.astro
@@ -167,6 +167,8 @@ const day = new Intl.DateTimeFormat("en", {
       <a href="https://tangled.org/permadeath.com/substandard/blob/main/LICENSE"
         >MIT licensed</a
       >
+      &middot;
+      <a href="/architecture">architecture</a>
     </p>
     <p>
       This site uses cookieless analytics
diff --git a/web/src/pages/privacy.astro b/web/src/pages/privacy.astro
index 9e64e6c..131f684 100644
--- a/web/src/pages/privacy.astro
+++ b/web/src/pages/privacy.astro
@@ -65,6 +65,11 @@ import Layout from "../layouts/Layout.astro";
         preference, your session — stays in your browser's local extension
         storage. Uninstalling the extension removes it.
       </p>
+      <p>
+        The <a href="/architecture">architecture page</a> is the diagram of all
+        of the above: which part of the extension makes each of those requests,
+        what it sends, and where each answer is kept.
+      </p>
     </section>
 
     <section>
diff --git a/web/src/styles/global.css b/web/src/styles/global.css
index 6d0da45..096bbfb 100644
--- a/web/src/styles/global.css
+++ b/web/src/styles/global.css
@@ -364,6 +364,134 @@ main li::marker {
   color: var(--muted);
 }
 
+/* The architecture diagram (/architecture). Mermaid's own stylesheet is
+   stripped at render time — `style-src 'self'` covers inline SVG, so a
+   <style> inside the figure would be dropped in production and the diagram
+   would render as black boxes on black lines. Everything it would have said
+   is restated here instead, which is also how the picture picks up the
+   theme's tokens rather than baking one palette into the file.
+
+   The geometry was measured at 16px system-ui, so that size is pinned rather
+   than inherited: a different one would spill the labels out of their boxes.
+   Below the diagram's natural width the figure scrolls instead of scaling,
+   because a 900px picture squeezed into a phone is unreadable long before it
+   stops fitting. */
+/* /architecture is the one page whose content is a picture and two reference
+   tables rather than paragraphs. At the 44rem the prose pages use, the
+   diagram needs a scrollbar on every desktop and the tables crush their
+   columns to one character; the column is widened for that page alone. */
+main.wide {
+  max-width: 62rem;
+}
+
+.diagram {
+  margin: 1.25rem 0 0;
+  overflow-x: auto;
+}
+
+.diagram svg {
+  display: block;
+  width: 100%;
+  min-width: 40rem;
+  height: auto;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  font-size: 16px;
+}
+
+.diagram text {
+  fill: var(--fg);
+}
+
+/* Mermaid lays a node's label out from the node's centre and leaves the
+   centring to its stylesheet, so without this the labels run out of the
+   right-hand side of their boxes. Cluster labels are pre-offset and stay
+   left-anchored. */
+.diagram .node .label text {
+  text-anchor: middle;
+}
+
+/* Boxes inside the browser are solid cards; the services outside it are
+   dashed and unfilled, so the trust boundary reads without a legend. */
+.diagram .node rect {
+  fill: var(--card);
+  stroke: var(--fg);
+  stroke-width: 1.5px;
+  rx: 6;
+  ry: 6;
+}
+
+.diagram .node.outsideNode rect {
+  fill: var(--bg);
+  stroke: var(--muted);
+  stroke-dasharray: 5 4;
+}
+
+.diagram .cluster rect {
+  fill: none;
+  stroke: var(--line);
+  stroke-width: 2px;
+  rx: 10;
+  ry: 10;
+}
+
+.diagram .cluster-label text {
+  fill: var(--muted);
+}
+
+.diagram .flowchart-link {
+  fill: none;
+  stroke: var(--muted);
+  stroke-width: 1.5px;
+}
+
+.diagram .arrowMarkerPath {
+  fill: var(--muted);
+  stroke: none;
+}
+
+/* The label's backing plate knocks the edge out from under the text. */
+.diagram .edgeLabel .background {
+  fill: var(--bg);
+}
+
+.diagram .edgeLabel text {
+  fill: var(--muted);
+}
+
+/* Reference tables: what talks to what, and what is kept where. Narrow
+   screens scroll the table rather than crushing the columns. */
+.table-scroll {
+  overflow-x: auto;
+  margin: 1rem 0 0;
+}
+
+.table-scroll table {
+  border-collapse: collapse;
+  width: 100%;
+  min-width: 40rem;
+  font-size: 0.9rem;
+}
+
+.table-scroll th,
+.table-scroll td {
+  border-bottom: 1px solid var(--line);
+  padding: 0.45rem 0.6rem;
+  text-align: left;
+  vertical-align: top;
+  color: var(--muted);
+}
+
+.table-scroll th {
+  color: var(--fg);
+  font-weight: 650;
+}
+
+/* Identifiers carry the weight on /architecture: NSIDs, hostnames, paths. */
+main code {
+  font-size: 0.9em;
+  overflow-wrap: anywhere;
+}
+
 /* The footer rule is the mark's own squiggle: four honest humps, then the
    tail gives out. Masked so it takes the theme's red. */
 footer {
-- 
2.51.2