ObliviOS Developer portal Project site

Home / Decisions / ADR-269

Add the threat model, the capability boundaries, the engineering notes and the quickstarts of three components to oblivios.dev.

Accepted, recorded 19 November 2026.

Decision
ADR-269
Date
2026-11-19
Status
AcceptedAccepted (owner, 2026-11-19: to build the missing pages at once and that the owner goes through them). The calls of the agent are the sub-navigation, the cases layout, the SVG drawing, the weights of the search, the words of the three quickstarts and their honest not run; the owner may overrule each.
Mentions
ADR-268
Mentioned by
ADR-270

1Decision

Add the threat model, the capability boundaries, the engineering notes and the quickstarts of three components to oblivios.dev, which amends point (2) of ADR-268 (it left them out for want of a design).

(1) Pages: /threat-model and /boundaries under the sub-navigation Security model, /engineering with one page for each of the eight published notes (AirPods, app drawer, boot picture, Data Map, Duress Unlock, grab detection, keyboard, these sites), and /quickstarts with one page each for vault-core, exit-daemon and airpods-core: 16 pages, 305 in all, and three more plates on the home page and three more links in the navigation.

(2) Each page is the published Markdown file, read at build time by site/dev/src/lib/documents.mjs and never copied into the site. The reader knows a title, headings of level 2 and 3, paragraphs, lists, tables, fenced code and one Mermaid flowchart, and a construct it does not know fails the build with the line named.

A table of two columns is a list of facts, a table of three columns or more is a list of cases (the first cell as the heading, the other cells under the labels of the header, and an anchor), and the flowchart of the threat model is drawn as an inline SVG by the build, so the page has no script and no library. Each page carries the one Read from line of ADR-268.

(3) The quickstarts are three new documents, docs/quickstarts/vault-core.md, exit-daemon.md and airpods-core.md, added to the publication list, because the READMEs of oblivios-services are not in the snapshot that the portal is built from. Each says what the component is, what it is not, the commands, and what was run.

Only airpods-core was run: ./gradlew :airpods-core:test on 2026-11-19 gave BUILD SUCCESSFUL in 9s and 57 tests with no failure [measured: the Gradle output and the XML reports]. The two Rust crates build only on the build server with the AOSP Rust toolchain, so their pages say that they were not run for the page and that there is no ten-minute path from a clean machine; no page claims a run on a clean machine, and C-4 of the launch spec stays open.

(4) The search index gains 214 documents (13 documents, 75 sections, 126 cases) with a chip Documents; every anchor was checked against the built pages. A document weighs 1.2 and a section or case 0.7, so that a decision, a library or an advisory of the same name stays first, and a version such as 5.18 also matches 5.18.2 when some document spells 5.18 alone.

(5) check-build.mjs lets the pages that show a record or a document name sourceMappingURL, localStorage and placeholder words in their prose, as the decision pages already did, and refuses a home-directory path on every page. (6) Two rows of the threat model that stood on one line, joined by a literal backslash and n, are split.

2Why and evidence

The portal showed the decisions and the bill of materials but not the documents that say how the system is protected and built, which spec 5.1 lists for it, and the documents already exist and are published, so they are shown as written and not rewritten.

A quickstart per component is what spec 5.7 asks for, but the commands of two of the three cannot be run on a workstation and the spec's ten minutes do not exist for them; the pages say so instead of promising it. The standard says a fact has one home, and the quickstart pages restate the commands that the READMEs hold: accepted because the portal cannot read another repository, and the review trigger below covers it.

Rejected: reading the READMEs at build time (they are not in the snapshot), drawing the flowchart with the Mermaid library (a script and a package for the SBOM), a Markdown package (as in ADR-268), one long page for all engineering notes (the Duress Unlock notes alone are 63 KB), and leaving the quickstarts out.

3Consequences

npm run build -w dev builds 305 pages and checks 10,898 links, and the same count comes from the snapshot built into a copy of oblivios-docs [measured]. On the 15 new pages axe-core 4.10.3 found no violation in the dark scheme at 320 px and the light scheme at 1024 px, and no page is wider than the screen at those widths [measured].

The search was read again with 30 queries and the earlier results held, apart from one fault that the new index showed and the version rule fixed: astro 5.18 found one section of the notes and not the library [measured].

Not done: the owner's review of the pages; the claim review (C-1) of the new copy and the quickstart evidence (C-4); Firefox, Safari, the keyboard and a screen reader; the regeneration of sbom/ (the files of site/dev changed) and of the snapshot, its push, the deployment and the link from oblivios.org. A test query that is written into a document becomes a word of the index: the notes name no misspelled test words for that reason.

4Review when

A command or a fact in a README of oblivios-services that a quickstart restates changes; the owner rejects a page or its layout; a published document uses a Markdown construct the reader does not know (the build fails and names the line); the claim review finds a sentence unsupported; a Rust quickstart can be run on a machine that is not the build server.

Read from docs/governance/decision-log.md, entry ADR-269.