Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs(air-gapped): compute the digest here and search the file for it, and install only what verified

xerj-orgcb0331556820
diff --git a/docs/recipes/air-gapped-deployment.md b/docs/recipes/air-gapped-deployment.md
index 47138a867..617db1110 100644
--- a/docs/recipes/air-gapped-deployment.md
+++ b/docs/recipes/air-gapped-deployment.md
@@ -97,31 +97,58 @@ After transfer, set the same approved `TAG` in the enclave and verify before
extracting:
```bash
-set -eu
-
: "${TAG:?set TAG to the same operator-approved release tag}"
VERSION="${TAG#v}"
STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
ASSET="${STAGE}.tar.gz"
(
+ set -eu
cd /opt/xerj-staging/release
- grep -qF " $ASSET" "$ASSET.sha256"
- sha256sum -c "$ASSET.sha256"
- rm -rf "$STAGE"
+
+ want="$(sha256sum "$ASSET" | cut -d ' ' -f 1)"
+ if [[ ! "$want" =~ ^[0-9a-f]{64}$ ]]; then
+ echo "could not compute a digest for $ASSET" >&2
+ exit 1
+ fi
+ LC_ALL=C grep -qxF -e "$want $ASSET" -e "$want *$ASSET" \
+ < <(tr -d '\r' < "$ASSET.sha256")
+
+ rm -rf "$STAGE" "$STAGE.verified"
tar -xzf "$ASSET"
test -x "$STAGE/xerj"
+ mv "$STAGE" "$STAGE.verified"
)
```
-Each step is on its own line for a reason. `set -e` does not stop a command
-that is part of an `&&` list unless it is the last one, so writing the same
-sequence as `sha256sum -c … && tar -xzf …` leaves the block exiting `0` after a
-failed digest and lets a wrapping script continue into section 2. The `grep`
-line is what makes the digest apply to this asset: `sha256sum -c` reports
-success for whatever filenames the `.sha256` happens to list, including a file
-that is not the archive you are about to extract. `rm -rf "$STAGE"` removes any
-tree left behind by an earlier run, so `test -x` cannot pass on a stale binary.
+Three details here are load-bearing, and each replaces something that looked
+right and was not.
+
+**The digest is computed here and the file is searched for it, not the other way
+round.** `sha256sum -c` reads the filename out of the `.sha256` — a file that
+crossed the airgap on the same medium as the archive — and reports success for
+whatever it happens to name. It skips `#` comments silently and exits `0` if any
+one line verified, so a `.sha256` carrying a valid digest for some other file
+plus a comment mentioning the archive passes while the archive is never hashed.
+Filtering that file first does not fix it either: `awk '$2 == asset'` compares
+one whitespace-delimited token, while `sha256sum` takes the whole rest of the
+line as the filename, so a line naming `$ASSET decoy` satisfies the filter and
+hashes a decoy. Building the expected line in the shell and demanding it with
+`grep -qxF` removes the disagreement — there is no field-splitting left for the
+two programs to differ about, and the asset name is never interpreted. The two
+patterns accept GNU text mode and `-b` binary mode; `tr -d '\r'` accepts a
+checksum file written on Windows.
+
+**`set -eu` is inside the subshell.** At the top of the block it kills the
+operator's login shell on a bad digest — actively harmful over a serial console,
+where the natural recovery is to re-paste without it, which is the fail-open
+form. Inside, a failure ends the subshell and the operator keeps their session.
+
+**Section 2 installs from `$STAGE.verified`, which `mv` creates only after the
+digest, the extraction and `test -x` have all succeeded.** That is what makes
+the block safe when its exit status is ignored — by a wrapping script, an agent,
+or a reader who pastes the next section anyway. Nothing needs to check a return
+code, because on any failure there is simply nothing at the install path.
## 2. Install the base lexical node
@@ -139,7 +166,7 @@ fi
sudo install -d -m 0755 /opt/xerj/bin /etc/xerj
sudo install -d -o xerj -g xerj -m 0750 /var/lib/xerj
sudo install -m 0755 \
- "/opt/xerj-staging/release/xerj-${VERSION}-x86_64-unknown-linux-musl/xerj" \
+ "/opt/xerj-staging/release/xerj-${VERSION}-x86_64-unknown-linux-musl.verified/xerj" \
/opt/xerj/bin/xerj
```
diff --git a/landing/docs/recipes/air-gapped-deployment.html b/landing/docs/recipes/air-gapped-deployment.html
index 5b63bdf64..f631c221f 100644
--- a/landing/docs/recipes/air-gapped-deployment.html
+++ b/landing/docs/recipes/air-gapped-deployment.html
@@ -100,22 +100,29 @@ curl -fL --retry 3 -o "$OUT/release/$ASSET.sha256" "$BASE/$ASSET.sha256"
"$STAGE/xerj" --version
)</pre>
<p>The checksum proves archive integrity against the digest published beside it in the same release; it is not a signature, provenance statement, or attestation. After transfer, set the same approved <code class="inline">TAG</code> and verify before extracting:</p>
-<pre class="code">set -eu
-
-: "${TAG:?set TAG to the same operator-approved release tag}"
+<pre class="code">: "${TAG:?set TAG to the same operator-approved release tag}"
VERSION="${TAG#v}"
STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
ASSET="${STAGE}.tar.gz"
(
+ set -eu
cd /opt/xerj-staging/release
- grep -qF " $ASSET" "$ASSET.sha256"
- sha256sum -c "$ASSET.sha256"
- rm -rf "$STAGE"
+
+ want="$(sha256sum "$ASSET" | cut -d ' ' -f 1)"
+ if [[ ! "$want" =~ ^[0-9a-f]{64}$ ]]; then
+ echo "could not compute a digest for $ASSET" &gt;&amp;2
+ exit 1
+ fi
+ LC_ALL=C grep -qxF -e "$want $ASSET" -e "$want *$ASSET" \
+ &lt; &lt;(tr -d '\r' &lt; "$ASSET.sha256")
+
+ rm -rf "$STAGE" "$STAGE.verified"
tar -xzf "$ASSET"
test -x "$STAGE/xerj"
+ mv "$STAGE" "$STAGE.verified"
)</pre>
- <p>Each step is on its own line for a reason. <code class="inline">set -e</code> does not stop a command that is part of an <code class="inline">&amp;&amp;</code> list unless it is the last one, so writing this as <code class="inline">sha256sum -c &hellip; &amp;&amp; tar -xzf &hellip;</code> leaves the block exiting <code class="inline">0</code> after a failed digest and lets a wrapping script continue into section 2. The <code class="inline">grep</code> line is what makes the digest apply to this asset: <code class="inline">sha256sum -c</code> reports success for whatever filenames the <code class="inline">.sha256</code> happens to list, including a file that is not the archive you are about to extract. <code class="inline">rm -rf "$STAGE"</code> removes any tree left by an earlier run, so <code class="inline">test -x</code> cannot pass on a stale binary.</p>
+ <p>Three details are load-bearing, and each replaces something that looked right and was not. <strong>The digest is computed here and the file is searched for it, not the other way round</strong> &mdash; <code class="inline">sha256sum -c</code> reads the filename out of the <code class="inline">.sha256</code>, a file that crossed the airgap on the same medium as the archive, skips <code class="inline">#</code> comments silently, and exits <code class="inline">0</code> if any one line verified, so a decoy digest plus a comment naming the archive passes while the archive is never hashed. Filtering that file first does not fix it: <code class="inline">awk '$2 == asset'</code> compares one token while <code class="inline">sha256sum</code> takes the whole rest of the line as the filename, so a line naming <code class="inline">$ASSET decoy</code> satisfies the filter and hashes a decoy. Building the expected line in the shell and demanding it with <code class="inline">grep -qxF</code> removes the disagreement. The two patterns accept GNU text mode and <code class="inline">-b</code> binary mode; <code class="inline">tr -d '\r'</code> accepts a checksum file written on Windows. <strong><code class="inline">set -eu</code> is inside the subshell</strong> &mdash; at the top of the block it kills the operator&rsquo;s login shell on a bad digest, and the natural recovery is to re-paste without it, which is the fail-open form. <strong>Section 2 installs from <code class="inline">$STAGE.verified</code></strong>, which <code class="inline">mv</code> creates only after the digest, the extraction and <code class="inline">test -x</code> have all succeeded &mdash; so the block is safe even when its exit status is ignored, because on any failure there is nothing at the install path.</p>
<h2>2. Install the base lexical node</h2>
<p>Create the service account first, then install only the staged binary. No model directory is needed for lexical mode:</p>
@@ -128,7 +135,7 @@ fi
sudo install -d -m 0755 /opt/xerj/bin /etc/xerj
sudo install -d -o xerj -g xerj -m 0750 /var/lib/xerj
sudo install -m 0755 \
- "/opt/xerj-staging/release/xerj-${VERSION}-x86_64-unknown-linux-musl/xerj" \
+ "/opt/xerj-staging/release/xerj-${VERSION}-x86_64-unknown-linux-musl.verified/xerj" \
/opt/xerj/bin/xerj</pre>
<p>Create <code class="inline">/etc/xerj/xerj.toml</code> with the complete base configuration. Explicit lexical mode and an empty endpoint keep this path model-free:</p>
<pre class="code">[server]