ObliviOS Developer portal Project site

Home / Decisions / ADR-266

Make the script that builds the public documents fail closed.

Accepted, recorded 18 November 2026.

Decision
ADR-266
Date
2026-11-18
Status
AcceptedAccepted (owner, 2026-11-18: the script is to be extremely strong, nothing may leak).
Mentions
ADR-171, ADR-263

1Decision

Make the script that builds the public documents fail closed, as the owner asked on 2026-11-18 (nothing may leak).

tools/docs/build-public-docs.py now (1) builds in a staging directory, reads every file of it and runs gitleaks over it, and only then replaces the files of the output directory; on any finding the output directory stays as it was, and a missing gitleaks fails the build; (2) reads each text as written and as a reader sees it (entities, percent and backslash escapes, compatibility forms, invisible and combining marks, look-alike letters, case, separators), so the strings of the owner are found when spelled apart or in another script; (3) finds private keys, access tokens, credentials in a URL, hardware and IPv6 addresses, private host names, device identifiers, coordinates, spelled-out e-mail addresses and long random strings, and decodes base64 and hex inside a file; (4) reads pictures by their chunks (only the chunks that draw the picture pass; text, time, profile and exif chunks and data after the end fail), reads the SVG metadata, treats a key file as a public key only, and fails any file type that is not listed, any file that is never published (environment files, keys, source maps, archives), and any link; (5) covers the README, the community files, the security files, sbom/ and the static files, which the earlier script copied without reading; (6) runs its own canary tests before every build, one planted leak per detector, so a scan that no longer finds them builds nothing; (7) offers --audit and a --pre-push mode that read every commit a push adds (author, committer, message and each file it brings), refuse a push of any ref but refs/heads/main and any deletion.

tools/docs/preflip-scan.py shares the detection. The copyright holder's name of the NOTICE files (ADR-171) and the contact address in the files that name it stay allowed; the same name written as one word, the domain and the second address do not.

2Why and evidence

The earlier script scanned only the text it rewrote: the README, the security files and every picture were copied unread, the output directory was written before the scan and a failed run left the leaking file there (seen on 2026-11-18, when a decision log with the second address of the owner was written into the docs working tree before the build failed), and a different spelling of an owner string passed.

The new detection needs no list of known leaks to be complete; it fails what it cannot classify.

Rejected: an allowlist for the words of the prose (not possible for documents); treating the owner's name as secret (it is the public copyright holder, ADR-171); a scan of the data files for random strings (hashes and registry text give false findings, so sbom/, lock files and key armor skip e-mail, address, entropy, coordinate and identifier findings and keep every other check).

3Consequences

Done and read on 2026-11-18 (commit 0f80e09 of the private repository): the self-test passes; the builder passes on the real tree (15 documents, 14 scripts, 59 files of site/, sbom/) with every file audited, and the public docs repository is unchanged by it; preflip-scan.py passes on the four repositories at the flip heads after two rules were narrowed (a domain list of a password manager and a test URL with a dummy password are data, not the owner); a sabotage run on a clone with eight planted leaks (a spaced owner name, an access token, a cloud key, the OTA domain, a private address, a home path, a text chunk in a picture, an archive) reported all of them and left the output directory untouched.

An audit of all 35 commits of the public docs repository found three kinds of older content that is already public: the name of a local tool-configuration file in nine file lists of the SBOM, creation times and text chunks in five site pictures (dropped from the head by ADR-263), and the address of a public resolver in an older note; none names the owner.

Not done: the pre-push hook is not installed (a local git hook; the permission layer refused to let the agent write it, so the owner installs it); the code repositories have no push audit of their own beyond preflip-scan.py and gitleaks; the scan cannot know a personal detail that is in no pattern (a home address or a telephone number is found only if it looks like an address, a coordinate or a key).

4Review when

A leak reaches a published file anyway (add its spelling to the canaries first); a detector gives a false finding that blocks a build (narrow the rule and add the clean text to the canaries); the owner installs the hook and a push is refused for a reason that is not a leak.

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