Documentation host and address pseudonyms¶
Purpose and scope¶
Public documentation uses stable pseudonyms for private deployment hosts and
addresses. This changes presentation, not host identity, execution authority or
acceptance status. The private reverse mapping lives at
orbidocs:local/host-pseudonyms.json; it is shared conceptually with Node rather
than copied into a second registry. It is not distributed or required by CI.
Private mapping¶
The local JSON file has this shape (the empty arrays are an editing template):
{
"schema": "documentation-pseudonyms.local.v1",
"hosts": {
"host-A.local": { "aliases": [] }
},
"addresses": {}
}
Each populated host entry contains the original DNS aliases in aliases.
Each address entry uses an IPADDR-A-style key and an address string containing
one IPv4 or IPv6 address. Append new labels; never renumber existing ones. Use
uppercase letters A through Z, then AA, AB and so on. Keep aliases unique after
DNS case/trailing-dot normalization and addresses unique after IP normalization.
The suffix letters of a host and an address do not by themselves establish an
association. A physical host is distinct from logical roles such as node-a.
Keep the map with owner-only permissions (0600). The existing /local/ ignore
rule prevents ordinary additions; it does not protect against git add -f.
The source gate refuses tracked local material. Never copy the map into the
publication tree, upload it to CI, paste it into reports, or treat it as Node
runtime configuration. Local validation does not print its contents:
python3 scripts/check_document_privacy.py --check-map
Editing documents¶
Use host-A.local and IPADDR-A in prose. These are documentation labels, not
reachable endpoints. In each affected proposal, add a Host pseudonyms section
linking here and giving the private map's repository locator as inline code.
Do not make a broken public link to the ignored file.
Replace complete tokens, including occurrences inside URLs and code blocks,
without changing longer identifiers or logical node roles. Review the diff.
An IPADDR-A label is not a valid IP literal: an IP-typed runnable JSON example
must either keep a reviewed illustrative address or become an explicitly marked
local template that is materialized before contract validation. Do not silently
break JSON Schema examples. The current example topology uses illustrative
addresses; none has been asserted to identify a private machine.
Do not modify signed artifacts, retained evidence bytes, historical digests or qualifiers. Pseudonymize their documentary projection and keep its evidence reference. This does not erase names from Git history or already published copies. Node evidence and runtime files are outside this Orbidocs migration.
Privacy gate and exceptions¶
make check-no-absolute-local-paths retains the existing CI entry point and now
checks source-like text for private absolute paths, IPv4, IPv6 and .local hosts.
It includes tracked and non-ignored untracked files; ignored local files, build
outputs and binary assets are outside that source pass. Symlinks and undecodable
source-like text fail instead of silently passing. There is no whole-file waiver
for the checker or its tests.
The explicit exclusions are:
localhost, IPv4 loopback in the entire127.0.0.0/8range,0.0.0.0, and IPv6 loopback in equivalent spellings (including IPv4-mapped loopback);- complete host pseudonyms of the form
host-[A-Z]+.localand address labels of the formIPADDR-[A-Z]+; suffixes must not extend them into another name; - a bare
/Volumesor/Volumes/prefix without a concrete path component.
Two additional project-wide exceptions are the exact example hostname
orbiplex.local (case-insensitive) and the exact IPv4-shaped token 1.3.2.1,
which also occurs as an upstream zlib version. These exceptions apply to sources,
rendered pages, search indexes and text downloads. They do not admit subdomains,
neighboring addresses or IPv4-mapped IPv6 forms. They are explicit documentation
policy, not a claim that either token could never identify a real endpoint.
All other syntactically valid IP addresses require review, including addresses used in examples. An IPv4 address embedded in IPv6 is counted once. Schema URNs are identifiers, not DNS hostnames. A double colon inside a regex non-capturing group is syntax; a standalone unspecified IPv6 address is not globally exempt. Apart from the explicit token above, version/section numbers, SVG coordinates and other code syntax resembling IPs require contextual qualification, not a global allowlist of those numbers.
Reviewed exceptions are kept in scripts/document-privacy-exceptions.json as
an exact path + token + context + reason. They include illustrative topology
addresses, fixture domains, DNS-SD service types and capability/scope identifiers.
A private deployment name must be pseudonymized rather than added as an exception.
The registry literals are reviewed inputs; its other fields are scanned normally.
New contexts and new files do not inherit an exception automatically.
Verification and publication¶
make test-document-privacy
make check-no-absolute-local-paths
make validate-schemas
make html-i18n
make check-published-privacy
Publication checking scans generated HTML text and attributes (rejoining syntax highlighting spans), each search-index entry, and text downloads. Exceptions in rendered prose are limited to the same source document and exact reviewed token; the source pass must also pass with the original context. Static third-party JavaScript/CSS bundles and binary assets are outside the publication text pass; repository-owned script/style sources remain covered by the source gate.
The Pages workflow runs this check before artifact upload. It also rejects a
published private-map filename. These checks are safeguards for the stated address
and path classes, not a general detector of secrets, obfuscated identifiers or
private DNS names outside .local. Regenerate outputs from sanitized sources;
do not hand-edit generated pages or search indexes.