Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Real atomic self-update for the compiled-`binary` install method
* (v0.42 self-upgrading-gbrain wave, eng-review Finding 2 — "make the atomic
* swap claim true for the one method we own").
*
* `bun` / `bun-link` delegate their swap to those package managers.
* The compiled standalone binary is the only method gbrain itself writes, so
* it's the only place we can (and now do) guarantee atomicity:
*
* resolve published asset → download to a temp sibling of the live binary →
* verify attestation integrity → fsync + chmod +x → `--version` smoke test →
* verify version matches the release tag (downgrade-replay guard) →
* renameSync over the live path.
*
* rename(2) over a running binary is safe on darwin/linux (the running process
* keeps the old inode; the next exec picks up the new file). Every failure
* (no asset / fetch / download / integrity / smoke / rename) leaves the OLD
* binary untouched — there is no half-written-binary brick path. Windows can't
* rename over a running .exe, and no Windows/`darwin-x64`/`linux-arm64` asset is
* published, so those degrade to notify-only via `resolvePlatformAsset`
* returning null.
*
* Integrity (D7a, done): before the downloaded binary is ever executed, its
* SHA-256 is verified against the SLSA build-provenance attestation
* `attest-build-provenance` publishes for every release
* (`.github/workflows/release.yml`). The attestation is fetched from the GitHub
* REST API (`/repos/OWNER/REPO/attestations/sha256:<digest>`) — a DIFFERENT
* origin than the `objects.githubusercontent.com` CDN that serves the bytes —
* and we check that (a) an attested subject's digest equals the locally-computed
* digest and (b) the attestation's builder id is THIS repo's release workflow.
* The verify is dependency-free (node:crypto + fetch + base64 + JSON only, all
* Bun built-ins that survive `bun build --compile`; the `sigstore` npm package
* does NOT bundle under `--compile`, so it is deliberately not used). Honest
* guarantee: this is GitHub-account trust + origin separation + a signed
* digest/identity match — it does NOT independently validate the Fulcio cert
* chain or Rekor inclusion (that needs the trusted-root material sigstore-js
* loads from disk). An unverified binary is NEVER chmod-exec'd or renamed over
* the live path; integrity failure is fail-closed.
*
* Published asset matrix mirrors `.github/workflows/release.yml`:
* darwin-arm64 → gbrain-darwin-arm64
* linux-x64 → gbrain-linux-x64
*/
import { chmodSync, closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { execFileSync } from './spawn.ts';
import { createHash } from 'node:crypto';
/**
* The attestation's builder id must be EXACTLY one of these — it binds the
* provenance to THIS repo's release workflow running on a trusted ref, so a
* valid attestation for some OTHER artifact, a fork's workflow, or a
* workflow_dispatch of release.yml from an arbitrary branch can't be replayed.
* If tag-triggered releases ever ship, add their ref form here in the same PR.
* Mirrors `expectedAssetName`'s coupling to release.yml; pinned by
* test/release-workflow.test.ts.
*/
export const EXPECTED_BUILDER_ID_PREFIX =
'https://github.com/garrytan/gbrain/.github/workflows/release.yml@';
export const EXPECTED_BUILDER_IDS: readonly string[] = [
`${EXPECTED_BUILDER_ID_PREFIX}refs/heads/master`,
];
/** Base for the GitHub attestation REST endpoint (per-subject-digest lookup). */
const ATTESTATION_API_BASE =
'https://api.github.com/repos/garrytan/gbrain/attestations/sha256:';
export interface ReleaseAsset {
name: string;
url: string;
}
export type BinarySelfUpdateReason =
| 'unsupported_platform'
| 'fetch_failed'
| 'no_asset'
| 'download_failed'
| 'integrity_unavailable'
| 'integrity_failed'
| 'version_mismatch'
| 'smoke_failed'
| 'replace_failed';
/** One attested subject: an artifact name + its SHA-256 (hex, no `sha256:` prefix). */
export interface AttestedSubject {
name: string;
sha256: string;
}
/** A parsed build-provenance attestation: the subjects it covers + its builder id. */
export interface ParsedAttestation {
subjects: AttestedSubject[];
builderId: string;
}
export interface BinarySelfUpdateResult {
ok: boolean;
reason?: BinarySelfUpdateReason;
error?: string;
/** Asset name resolved (when applicable). */
asset?: string;
/** Release version resolved from GitHub, even when a later step fails. */
targetVersion?: string;
}
/** The release asset basename gbrain publishes for this platform/arch, or null
* when no asset is published (degrade to notify-only). */
export function expectedAssetName(platform: NodeJS.Platform, arch: NodeJS.Architecture): string | null {
if (platform === 'darwin' && arch === 'arm64') return 'gbrain-darwin-arm64';
if (platform === 'linux' && arch === 'x64') return 'gbrain-linux-x64';
return null;
}
/** Pick the download URL for this platform/arch from a release's asset list. */
export function resolvePlatformAsset(
assets: ReleaseAsset[],
platform: NodeJS.Platform = process.platform,
arch: NodeJS.Architecture = process.arch,
): string | null {
const name = expectedAssetName(platform, arch);
if (!name) return null;
const match = assets.find((a) => a.name === name);
return match?.url ?? null;
}
export interface BinarySelfUpdateDeps {
/** Fetch the latest release's tag + asset list. Default hits the GitHub API. */
fetchRelease?: () => Promise<{ tag: string; assets: ReleaseAsset[] } | null>;
/** Download `url` to `destPath`. Default streams the HTTP body to disk. */
download?: (url: string, destPath: string) => Promise<void>;
/** Smoke-test the staged binary; returns true if `<path> --version` looks like gbrain. */
smoke?: (stagedPath: string) => boolean;
/**
* Confirm the staged binary actually IS the release it claims to be — its
* `--version` must contain `expectedVersion` (derived from the release tag).
* Defaults to a real `--version` exec. Blocks a downgrade-replay: an attacker
* who swaps the published asset for an OLDER, still-validly-attested binary
* passes the digest+builder check (the old digest has a real attestation) but
* reports the wrong version here. Injected in tests that stage non-binary bytes.
*/
checkVersion?: (stagedPath: string, expectedVersion: string) => boolean;
/** SHA-256 (hex) of the file at `path`. Default reads the file with node:crypto. */
computeDigest?: (path: string) => string;
/**
* Fetch + parse the build-provenance attestations for `digest` (hex, no
* prefix). Returns the parsed attestations, or null when none are available
* (missing / network / rate-limited) — null maps to `integrity_unavailable`,
* NOT `integrity_failed`. Default hits the GitHub attestation REST API.
* Injected in tests so the real digest/identity verify logic is exercised
* against crafted attestation data (the network is the only mocked seam).
*/
fetchAttestation?: (digest: string) => Promise<ParsedAttestation[] | null>;
platform?: NodeJS.Platform;
arch?: NodeJS.Architecture;
}
async function defaultFetchRelease(): Promise<{ tag: string; assets: ReleaseAsset[] } | null> {
return fetchAlphaRelease();
}
/**
* The alpha channel's release: the version in VERSION at the `latest-stable` tag (which release.yml moves on every
* published release), then that exact release. Not `releases/latest`: GitHub's Latest is the stable release, and
* every batch release is published as a pre-release, so reading it would quietly put alpha binaries on stable.
*/
export async function fetchAlphaRelease(fetchImpl: typeof fetch = fetch): Promise<{ tag: string; assets: ReleaseAsset[] } | null> {
try {
const res = await fetchImpl('https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/VERSION', {
headers: { 'User-Agent': 'gbrain-self-upgrade' },
signal: AbortSignal.timeout(5_000),
});
if (!res.ok) return null;
const version = /^v?(\d+\.\d+\.\d+(?:\.\d+)?)(?:[-+][0-9A-Za-z.-]+)?$/.exec(((await res.text()).slice(0, 256).trim().split('\n')[0] ?? '').trim())?.[1];
if (!version) return null;
return fetchReleaseJson(`https://api.github.com/repos/garrytan/gbrain/releases/tags/v${version}`, fetchImpl);
} catch {
return null;
}
}
/** GBRA-175: one named release (the stable channel's), in the same shape as the latest release. */
export function fetchReleaseByTag(tag: string): Promise<{ tag: string; assets: ReleaseAsset[] } | null> {
return fetchReleaseJson(`https://api.github.com/repos/garrytan/gbrain/releases/tags/${encodeURIComponent(tag)}`);
}
async function fetchReleaseJson(url: string, fetchImpl: typeof fetch = fetch): Promise<{ tag: string; assets: ReleaseAsset[] } | null> {
try {
const res = await fetchImpl(url, {
headers: { 'User-Agent': 'gbrain-self-upgrade' },
signal: AbortSignal.timeout(5_000),
});
if (!res.ok) return null;
const data = (await res.json()) as any;
const assets: ReleaseAsset[] = Array.isArray(data.assets)
? data.assets.map((a: any) => ({ name: String(a.name ?? ''), url: String(a.browser_download_url ?? '') }))
: [];
return { tag: String(data.tag_name ?? ''), assets };
} catch {
return null;
}
}
export async function defaultDownload(url: string, destPath: string): Promise<void> {
const res = await fetch(url, {
headers: { 'User-Agent': 'gbrain-self-upgrade' },
redirect: 'follow',
signal: AbortSignal.timeout(120_000),
});
if (!res.ok) throw new Error(`download HTTP ${res.status}`);
const buf = Buffer.from(await res.arrayBuffer());
if (buf.length === 0) throw new Error('downloaded asset is empty');
// fsync the descriptor that wrote the bytes, so a crash between write and
// rename can't leave a torn file. A read-only reopen fails on Windows (EPERM).
const fd = openSync(destPath, 'w');
try {
writeFileSync(fd, buf);
fsyncSync(fd);
} finally {
closeSync(fd);
}
}
function defaultSmoke(stagedPath: string): boolean {
try {
const out = execFileSync(stagedPath, ['--version'], { encoding: 'utf-8', timeout: 10_000 });
return /gbrain\s/i.test(out);
} catch {
return false;
}
}
function defaultCheckVersion(stagedPath: string, expectedVersion: string): boolean {
try {
const out = execFileSync(stagedPath, ['--version'], { encoding: 'utf-8', timeout: 10_000 });
// Substring, not equality: `--version` prints `gbrain <version>` (+ maybe a
// build suffix). The release workflow enforces binary-version == VERSION at
// build time, so the tag's numeric version must appear here.
return out.includes(expectedVersion);
} catch {
return false;
}
}
export function defaultComputeDigest(path: string): string {
return createHash('sha256').update(readFileSync(path)).digest('hex');
}
/**
* Decode one GitHub attestation `bundle` into `{subjects, builderId}`.
* The DSSE payload is a base64-encoded in-toto Statement:
* { subject: [{name, digest:{sha256}}], predicate:{ runDetails:{ builder:{id} } } }
* Returns null when the bundle is malformed (missing/undecodable payload).
*/
export function parseAttestationBundle(bundle: any): ParsedAttestation | null {
try {
const payloadB64 = bundle?.dsseEnvelope?.payload;
if (typeof payloadB64 !== 'string' || payloadB64.length === 0) return null;
const stmt = JSON.parse(Buffer.from(payloadB64, 'base64').toString('utf8'));
// Only accept SLSA build-provenance statements — don't let some other
// attestation type that happens to carry subject[]+builder.id be read as
// provenance.
if (typeof stmt?.predicateType === 'string' && !stmt.predicateType.includes('slsa.dev/provenance')) {
return null;
}
const subjects: AttestedSubject[] = Array.isArray(stmt?.subject)
? stmt.subject
.map((s: any) => ({ name: String(s?.name ?? ''), sha256: String(s?.digest?.sha256 ?? '') }))
.filter((s: AttestedSubject) => s.sha256.length > 0)
: [];
const builderId = String(stmt?.predicate?.runDetails?.builder?.id ?? '');
if (subjects.length === 0 || builderId.length === 0) return null;
return { subjects, builderId };
} catch {
return null;
}
}
export async function defaultFetchAttestation(digest: string): Promise<ParsedAttestation[] | null> {
try {
const res = await fetch(`${ATTESTATION_API_BASE}${digest}`, {
headers: { 'User-Agent': 'gbrain-self-upgrade', Accept: 'application/vnd.github+json' },
signal: AbortSignal.timeout(10_000),
});
// 404 (no attestation), 403 (unauthenticated rate limit, 60/hr), any non-2xx
// → treat as "unavailable" (caller fails closed), never as "verified".
if (!res.ok) return null;
const data = (await res.json()) as any;
const raw = Array.isArray(data?.attestations) ? data.attestations : [];
const parsed = raw
.map((a: any) => parseAttestationBundle(a?.bundle))
.filter((p: ParsedAttestation | null): p is ParsedAttestation => p !== null);
// Distinguish "endpoint reachable but no usable attestation" (null →
// unavailable) from "reachable with data" (return the list, possibly empty
// only if all bundles were malformed, which we also treat as unavailable).
return parsed.length > 0 ? parsed : null;
} catch {
return null;
}
}
/**
* Verify the staged binary against its build-provenance attestation. Returns a
* reason on failure (fail-closed), or null on success.
* - digest can't be computed → integrity_unavailable
* - no attestation available → integrity_unavailable
* - attestation exists but does not
* cover this (name, digest) under
* our release-workflow builder id → integrity_failed
*/
export async function verifyIntegrity(
stagedPath: string,
assetName: string,
computeDigest: (path: string) => string,
fetchAttestation: (digest: string) => Promise<ParsedAttestation[] | null>,
): Promise<BinarySelfUpdateReason | null> {
let digest: string;
try {
digest = computeDigest(stagedPath);
} catch {
return 'integrity_unavailable';
}
if (!/^[0-9a-f]{64}$/.test(digest)) return 'integrity_unavailable';
// fetchAttestation is an injected seam; a throwing implementation must not
// escape runBinarySelfUpdate's never-throws contract (which would skip the
// staged-file cleanup). Any failure to obtain attestations is fail-closed.
let attestations: ParsedAttestation[] | null;
try {
attestations = await fetchAttestation(digest);
} catch {
return 'integrity_unavailable';
}
if (!attestations || attestations.length === 0) return 'integrity_unavailable';
// A match requires: an attestation from OUR release workflow ON A TRUSTED REF
// that names this asset with exactly this digest. Digest-match alone is
// insufficient (any artifact could carry it), and workflow-match alone is
// insufficient (a dispatch from an untrusted branch mints a real attestation).
const verified = attestations.some(
(att) =>
EXPECTED_BUILDER_IDS.includes(att.builderId) &&
att.subjects.some((s) => s.name === assetName && s.sha256 === digest),
);
return verified ? null : 'integrity_failed';
}
let _tmpCounter = 0;
/**
* Perform a real atomic self-update of the binary at `targetPath` (defaults to
* the running binary, `process.execPath`). Returns a tagged result; never
* throws. On any failure the original binary is left untouched.
*/
export async function runBinarySelfUpdate(
targetPath: string = process.execPath,
deps: BinarySelfUpdateDeps = {},
): Promise<BinarySelfUpdateResult> {
const platform = deps.platform ?? process.platform;
const arch = deps.arch ?? process.arch;
const fetchRelease = deps.fetchRelease ?? defaultFetchRelease;
const download = deps.download ?? defaultDownload;
const smoke = deps.smoke ?? defaultSmoke;
const checkVersion = deps.checkVersion ?? defaultCheckVersion;
const computeDigest = deps.computeDigest ?? defaultComputeDigest;
const fetchAttestation = deps.fetchAttestation ?? defaultFetchAttestation;
const assetName = expectedAssetName(platform, arch);
if (!assetName) {
return { ok: false, reason: 'unsupported_platform' };
}
const release = await fetchRelease();
if (!release) {
return { ok: false, reason: 'fetch_failed', asset: assetName };
}
const targetVersion = release.tag.replace(/^v/, '').trim();
const url = resolvePlatformAsset(release.assets, platform, arch);
if (!url) {
return { ok: false, reason: 'no_asset', asset: assetName, targetVersion };
}
// Stage in a temp sibling so the rename is same-filesystem (atomic).
const staged = join(dirname(targetPath), `.${assetName}.tmp.${process.pid}.${_tmpCounter++}`);
try {
await download(url, staged);
} catch (e) {
safeUnlink(staged);
return { ok: false, reason: 'download_failed', error: errMsg(e), asset: assetName, targetVersion };
}
// Integrity BEFORE chmod/exec: never make an unverified binary executable and
// never run its `--version` smoke test. Fail-closed on unavailable or mismatch.
const integrityFailure = await verifyIntegrity(staged, assetName, computeDigest, fetchAttestation);
if (integrityFailure) {
safeUnlink(staged);
return { ok: false, reason: integrityFailure, asset: assetName, targetVersion };
}
try {
chmodSync(staged, 0o755);
} catch (e) {
safeUnlink(staged);
return { ok: false, reason: 'download_failed', error: errMsg(e), asset: assetName, targetVersion };
}
if (!smoke(staged)) {
safeUnlink(staged);
return { ok: false, reason: 'smoke_failed', asset: assetName, targetVersion };
}
// Downgrade-replay guard: the staged binary must actually be the release it
// claims. A swapped asset serving an older, still-validly-attested binary
// clears digest+builder but reports the wrong version here.
const expectedVersion = targetVersion;
if (expectedVersion && !checkVersion(staged, expectedVersion)) {
safeUnlink(staged);
return { ok: false, reason: 'version_mismatch', asset: assetName, targetVersion };
}
try {
renameSync(staged, targetPath); // atomic on same fs; old binary intact if this throws
} catch (e) {
safeUnlink(staged);
return { ok: false, reason: 'replace_failed', error: errMsg(e), asset: assetName, targetVersion };
}
return { ok: true, asset: assetName, targetVersion };
}
function safeUnlink(path: string): void {
try {
unlinkSync(path);
} catch {
/* already gone */
}
}
function errMsg(e: unknown): string {
return e instanceof Error ? e.message : String(e);
}