Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* repo-visibility.ts — ONE repo-visibility verdict for every consumer
* (workspace-push gate [G8], bootstrap repo/verify/status probes), replacing
* three drifted probes (TODOS ~5097). Engine-free; every IO seam injectable.
*
* Why a ladder and not one gh call: the previous probe (`gh repo view`, a
* GraphQL call) is structurally unavailable in cloud sandboxes — their GitHub
* proxy pins GraphQL to a fixed operation set and 403s everything else, even
* with a user-supplied token — which silently converted every hook push into
* `refused_visibility`. REST is the sanctioned surface, and pure git protocol
* works anywhere `git push` works.
*
* rung 1 REST `gh api repos/{owner}/{repo}` → .private (github.com)
* rung 2 authed `git ls-remote <url> HEAD` → exists + readable
* rung 3 anon GET <repo>/info/refs?service=git-upload-pack, no auth
*
* Verdict matrix (fail-closed BOTH directions — see [D4]/[D14] below):
* rest true → private/rest
* rest false → public/rest (refuse)
* rung2 ok + rung3 attributed 401 → private/git-protocol
* rung2 ok + rung3 proven 200 → public/git-protocol (refuse) — unless a
* credential-injecting proxy makes the
* "anonymous" probe ambiguous → unverifiable
* anything else → unverifiable (refuse, with rung log)
*
* [D4] A 200 counts as PUBLIC only with advertisement proof (content-type
* `application/x-git-upload-pack-advertisement` or the pkt-line body
* prefix). SSO-fronted self-hosted servers answer 200 with an HTML
* login page — that must read `unverifiable`, never a false "PUBLIC".
* [D14] A 401/404 counts as PRIVATE-signal only with origin attribution
* (`www-authenticate` challenge; github.com additionally recognized by
* realm/request-id headers). The private verdict AUTHORIZES pushing, so
* an auth-demanding middlebox that 401s all anonymous traffic must not
* launder a public repo into "private".
*/
import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { ensureGbrainHome } from './gbrain-home.ts';
import { durableSsrfFlags } from './git-remote.ts';
import { isCredentialInjectingProxy } from './execution-env.ts';
import { gitChildEnv } from './git-env.ts';
import { bunSpawn } from './spawn.ts';
// ── Subprocess seam (canonical home; bootstrap/repo.ts re-exports) ─────────
export interface ExecResult {
code: number;
stdout: string;
stderr: string;
}
/** Injectable subprocess seam. argv[0] is the binary; never a shell string. */
export type ExecRunner = (argv: string[]) => Promise<ExecResult>;
/** Default runner: bunSpawn (src/core/spawn.ts), both streams piped, spawn failure → code 127.
* GIT_TERMINAL_PROMPT=0 so an unauthenticated git can never hang on a prompt. */
export const defaultRunner: ExecRunner = async (argv: string[]): Promise<ExecResult> => {
try {
const proc = bunSpawn(argv, {
stdout: 'pipe',
stderr: 'pipe',
stdin: 'ignore',
env: gitChildEnv({ GIT_TERMINAL_PROMPT: '0' }),
});
const [stdout, stderr, code] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
]);
return { code, stdout, stderr };
} catch (e) {
return { code: 127, stdout: '', stderr: (e as Error).message };
}
};
/** Race a runner call against a wall-clock cap. On timeout the rung reports
* code 124 and the ladder degrades — a hung network probe must never hang a
* push child. (The raced process is left to die on its own; every rung's
* default runner disables interactive prompts, so hangs are network-bound.) */
async function runWithTimeout(runner: ExecRunner, argv: string[], ms: number): Promise<ExecResult> {
let timer: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<ExecResult>((resolve) => {
timer = setTimeout(() => resolve({ code: 124, stdout: '', stderr: `timeout after ${ms}ms` }), ms);
});
try {
return await Promise.race([runner(argv), timeout]);
} finally {
clearTimeout(timer);
}
}
// ── Canonical remote-URL parser (union of the three prior grammars) ────────
/**
* Parse `{owner, repo}` from a github.com remote URL. Accepts the https form
* (with or without `.git` / trailing slash), the scp-like form
* (`[email protected]:o/r`), and `ssh://[email protected]/o/r`.
*/
export function parseGithubOwnerRepo(url: string): { owner: string; repo: string } | null {
const s = url.trim();
let m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(s);
if (!m) m = /^(?:ssh:\/\/)?git@github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(s);
return m ? { owner: m[1]!, repo: m[2]! } : null;
}
/** Convenience: the combined `owner/repo` string, or null. */
export function githubOwnerRepoString(url: string): string | null {
const p = parseGithubOwnerRepo(url);
return p ? `${p.owner}/${p.repo}` : null;
}
/**
* The anonymous smart-HTTP probe URL for an https origin, or null when the
* origin has no https probe surface (scp/ssh non-github, file paths).
* github.com ssh/scp origins are converted to their https equivalent.
* URL userinfo is STRIPPED: an origin with embedded credentials would make
* the "anonymous" probe authenticated, misreading a private repo as public.
*/
export function anonProbeUrl(originUrl: string): string | null {
const gh = parseGithubOwnerRepo(originUrl);
if (gh) return `https://github.com/${gh.owner}/${gh.repo}.git/info/refs?service=git-upload-pack`;
const s = originUrl.trim().replace(/\/+$/, '');
if (!/^https:\/\//.test(s)) return null;
try {
const u = new URL(s);
u.username = '';
u.password = '';
return `${u.toString().replace(/\/+$/, '')}/info/refs?service=git-upload-pack`;
} catch {
return null; // unparseable https-looking string — no probe surface
}
}
/** True when a gh stderr/body is a 403 authored by a sandbox egress proxy
* (session scoping), as opposed to a real GitHub API 403. One predicate for
* the three call sites that must keep the HTTP-403 pre-check and the
* classification paired. */
export function isProxyBlocked403(text: string): boolean {
return /HTTP 403/i.test(text) && classifyGh403(text) === 'proxy';
}
// ── gh 403 classification ───────────────────────────────────────────────────
export type Gh403Class = 'github' | 'proxy' | 'unknown';
/**
* Classify a 403 body/stderr: a real GitHub API error is JSON carrying
* `message` + `documentation_url`; sandbox egress proxies answer with
* text/plain or non-GitHub JSON ("not enabled for this session",
* x-deny-reason). The class steers the user message — "attach the repo to
* this session" vs "check your token" — and MUST NOT gate the verdict.
*/
export function classifyGh403(body: string): Gh403Class {
const jsonStart = body.indexOf('{');
if (jsonStart >= 0) {
try {
const parsed = JSON.parse(body.slice(jsonStart)) as Record<string, unknown>;
if (typeof parsed.message === 'string') {
if ('documentation_url' in parsed) return 'github';
return 'proxy'; // JSON error without GitHub's shape — proxy-authored
}
} catch {
/* not JSON → fall through */
}
}
if (/not enabled for this session|x-deny-reason|host_not_allowed|access denied by the .*proxy/i.test(body)) {
return 'proxy';
}
return 'unknown';
}
// ── The ladder ──────────────────────────────────────────────────────────────
export type VisibilityVia = 'rest' | 'git-protocol';
export interface RungResult {
rung: 'rest' | 'authed-ls-remote' | 'anon-refs';
outcome: string;
}
export type RepoVisibilityVerdict =
| { verdict: 'private'; via: VisibilityVia; detail: string; rungs: RungResult[] }
| { verdict: 'public'; via: VisibilityVia; detail: string; rungs: RungResult[] }
| { verdict: 'unverifiable'; detail: string; rungs: RungResult[] };
export interface VerifyRepoVisibilityOpts {
originUrl: string;
/** Run git with this repo's config (credential helpers). Recommended. */
repoDir?: string;
runner?: ExecRunner;
fetchImpl?: typeof fetch;
/** Environment for the proxy-signature check (default process.env). */
env?: Record<string, string | undefined>;
/** Per-rung wall-clock cap (default 15s). */
timeoutMs?: number;
}
const ADVERTISEMENT_CONTENT_TYPE = 'application/x-git-upload-pack-advertisement';
/** pkt-line advertisement prefix: 4 hex length digits then the service line. */
const ADVERTISEMENT_BODY_RE = /^[0-9a-f]{4}# service=git-upload-pack/;
function rungLog(rungs: RungResult[]): string {
return rungs.map((r) => `${r.rung}: ${r.outcome}`).join('; ');
}
/** The actionable line for proxy-ambiguous / unverifiable outcomes. Spelled
* once so push, verify, and status degrade with the same instruction. */
export const UNVERIFIED_REMOTE_HINT =
'confirm the repo is private in the GitHub UI, then set GBRAIN_ALLOW_UNVERIFIED_REMOTE=1 ' +
'(or `gbrain config set push.allow_unverified_remote true`) to push anyway';
export async function verifyRepoVisibility(opts: VerifyRepoVisibilityOpts): Promise<RepoVisibilityVerdict> {
const runner = opts.runner ?? defaultRunner;
const fetchImpl = opts.fetchImpl ?? fetch;
const env = opts.env ?? process.env;
const timeoutMs = opts.timeoutMs ?? 15_000;
const rungs: RungResult[] = [];
const url = opts.originUrl.trim();
const gh = parseGithubOwnerRepo(url);
// Rung 1 — REST (github.com origins only). NEVER GraphQL: `gh repo view`
// rides GraphQL, which cloud proxies pin to a fixed operation set.
if (gh) {
const res = await runWithTimeout(runner, ['gh', 'api', `repos/${gh.owner}/${gh.repo}`, '--jq', '.private'], timeoutMs);
const out = res.stdout.trim();
if (res.code === 0 && out === 'true') {
rungs.push({ rung: 'rest', outcome: 'private' });
return { verdict: 'private', via: 'rest', detail: `${gh.owner}/${gh.repo} verified private via REST`, rungs };
}
if (res.code === 0 && out === 'false') {
rungs.push({ rung: 'rest', outcome: 'public' });
return { verdict: 'public', via: 'rest', detail: `${gh.owner}/${gh.repo} is PUBLIC (REST)`, rungs };
}
if (res.code === 127) {
rungs.push({ rung: 'rest', outcome: 'gh not installed' });
} else if (/HTTP 403/i.test(res.stderr)) {
rungs.push({
rung: 'rest',
outcome: isProxyBlocked403(res.stderr)
? 'blocked by an egress proxy (repo not attached to this session) — falling back to git protocol'
: `403 (${classifyGh403(res.stderr)}) — falling back to git protocol`,
});
} else {
rungs.push({ rung: 'rest', outcome: `failed (${(res.stderr.trim() || `exit ${res.code}`).slice(0, 120)})` });
}
} else {
rungs.push({ rung: 'rest', outcome: 'not a github.com origin — skipped' });
}
// Rung 2 — authed existence: the repo's own credential config answers
// "does this origin exist and can OUR credentials read it". Hardened like
// every other remote-touching git call: SSRF config flags (no ext helpers,
// no redirect-follow, file transport only behind the test/self-hosted env
// escape) and end-of-options so a dash-prefixed origin can never be parsed
// as an option (the upload-pack command-execution class).
const lsArgv = [
'git',
...(opts.repoDir ? ['-C', opts.repoDir] : []),
...durableSsrfFlags(),
'ls-remote',
'--end-of-options',
url,
'HEAD',
];
const ls = await runWithTimeout(runner, lsArgv, timeoutMs);
if (ls.code !== 0) {
rungs.push({ rung: 'authed-ls-remote', outcome: `failed (${(ls.stderr.trim() || `exit ${ls.code}`).slice(0, 120)})` });
return {
verdict: 'unverifiable',
detail: `origin not readable with current credentials — a push would fail anyway (${rungLog(rungs)})`,
rungs,
};
}
rungs.push({ rung: 'authed-ls-remote', outcome: 'ok (exists + readable)' });
// Rung 3 — anonymous probe.
const probeUrl = anonProbeUrl(url);
if (!probeUrl) {
rungs.push({ rung: 'anon-refs', outcome: 'no https probe surface for this origin' });
return { verdict: 'unverifiable', detail: `origin readable but privacy unprovable (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`, rungs };
}
let status = 0;
let contentType = '';
let wwwAuthenticate = '';
let githubAttributed = false;
let bodyPrefix = '';
try {
const ctl = new AbortController();
const timer = setTimeout(() => ctl.abort(), timeoutMs);
try {
// redirect: manual — a redirected probe proves nothing about THIS origin
// (and following it would extend the request surface); 3xx falls through
// to the unexpected-status arm → unverifiable, fail-closed.
const res = await fetchImpl(probeUrl, { redirect: 'manual', signal: ctl.signal });
status = res.status;
contentType = res.headers.get('content-type') ?? '';
wwwAuthenticate = res.headers.get('www-authenticate') ?? '';
githubAttributed = res.headers.has('x-github-request-id');
bodyPrefix = (await res.text()).slice(0, 64);
} finally {
clearTimeout(timer);
}
} catch (e) {
rungs.push({ rung: 'anon-refs', outcome: `network error (${(e as Error).message.slice(0, 80)})` });
return { verdict: 'unverifiable', detail: `anonymous probe unreachable (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`, rungs };
}
if (status === 401 || status === 404) {
// [D14] attribution required before the push-authorizing PRIVATE verdict.
// RFC 7235 makes www-authenticate mandatory on EVERY 401 — a middlebox's
// included — so the challenge alone is NEVER proof. github.com origins
// require the GitHub request-id header. For NON-github origins there is no
// trustable attribution signal at all (a spoofing/inspecting middlebox
// 401s identically to a real private server), so a 401 there is
// `unverifiable` — the operator confirms via the escape hatch rather than
// us laundering a possibly-public repo into a push authorization. Both
// adversarial reviewers flagged the prior "challenge ⇒ private" as a
// public-repo-exfil path; fail closed.
const attributed = gh !== null && githubAttributed;
if (attributed) {
rungs.push({ rung: 'anon-refs', outcome: `${status} with GitHub-attributed auth challenge (not anonymously readable)` });
return {
verdict: 'private',
via: 'git-protocol',
detail: `origin exists, reads with credentials, and refuses anonymous access (${rungLog(rungs)})`,
rungs,
};
}
const why = gh !== null
? `${status} without GitHub attribution (x-github-request-id) — possible middlebox`
: `${status} on a non-github origin — no trustable attribution signal`;
rungs.push({ rung: 'anon-refs', outcome: `${why}, not trusted as a privacy signal` });
return { verdict: 'unverifiable', detail: `un-attributed ${status} on the anonymous probe (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`, rungs };
}
if (status === 200) {
// [D4] advertisement proof required before the "public" verdict.
const proven =
contentType.toLowerCase().includes(ADVERTISEMENT_CONTENT_TYPE) || ADVERTISEMENT_BODY_RE.test(bodyPrefix);
if (!proven) {
rungs.push({ rung: 'anon-refs', outcome: '200 without a git advertisement (SSO/login page?) — not trusted as a public signal' });
return { verdict: 'unverifiable', detail: `anonymous 200 without advertisement proof (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`, rungs };
}
if (isCredentialInjectingProxy(env)) {
// The "anonymous" request may have been silently authenticated by the
// sandbox proxy — a private repo would ALSO read 200 here. Ambiguous.
rungs.push({ rung: 'anon-refs', outcome: '200 advertisement behind a credential-injecting proxy — ambiguous' });
return {
verdict: 'unverifiable',
detail: `cannot prove privacy from inside this sandbox's authenticated proxy (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`,
rungs,
};
}
rungs.push({ rung: 'anon-refs', outcome: '200 with a git advertisement — anonymously clonable' });
return { verdict: 'public', via: 'git-protocol', detail: `origin is anonymously readable (${rungLog(rungs)})`, rungs };
}
rungs.push({ rung: 'anon-refs', outcome: `unexpected HTTP ${status}` });
return { verdict: 'unverifiable', detail: `anonymous probe answered HTTP ${status} (${rungLog(rungs)}) — ${UNVERIFIED_REMOTE_HINT}`, rungs };
}
// ── Verdict cache [D11] ─────────────────────────────────────────────────────
//
// PRIVATE verdicts only, 1h TTL, keyed on the exact origin URL. `public` and
// `unverifiable` are NEVER cached: failures must re-verify every push so a
// fixed repo unblocks on the next turn, while a private→public flip is
// honored at most one TTL late (deliberate owner action; the secret-scan gate
// still runs on every push). Kills the per-turn network cost of the
// cloud-sandbox debounce-0 push cadence.
export const VISIBILITY_CACHE_TTL_MS = 60 * 60 * 1000;
/** Cache key = origin URL with any userinfo (`user:pat@`) stripped — a PAT in
* an https remote must never be persisted into the on-disk cache file. */
function cacheKey(originUrl: string): string {
try {
const u = new URL(originUrl);
u.username = '';
u.password = '';
return u.toString();
} catch {
return originUrl; // scp/ssh/file forms carry no URL userinfo
}
}
interface VisibilityCacheEntry {
verdict: 'private';
via: VisibilityVia;
verified_at: string;
}
export function visibilityCachePath(): string {
return join(ensureGbrainHome(), 'bootstrap', 'visibility-cache.json');
}
/** A fresh cached PRIVATE verdict for this origin, or null. */
export function readCachedPrivateVerdict(
originUrl: string,
opts: { now?: number; path?: string } = {},
): RepoVisibilityVerdict | null {
const now = opts.now ?? Date.now();
try {
const raw = readFileSync(opts.path ?? visibilityCachePath(), 'utf8');
const map = JSON.parse(raw) as Record<string, VisibilityCacheEntry>;
const entry = map[cacheKey(originUrl)];
if (!entry || entry.verdict !== 'private') return null;
const at = Date.parse(entry.verified_at);
if (!Number.isFinite(at) || now - at > VISIBILITY_CACHE_TTL_MS) return null;
return {
verdict: 'private',
via: entry.via,
detail: `verified private ${entry.via === 'rest' ? 'via REST' : 'via git protocol'} at ${entry.verified_at} (cached)`,
rungs: [],
};
} catch {
return null; // missing/corrupt cache is a miss, never an error
}
}
/** Record a PRIVATE verdict (no-op for any other verdict). Prunes expired
* entries; tolerant of a corrupt existing file (starts fresh). */
export function writeVisibilityCache(
originUrl: string,
verdict: RepoVisibilityVerdict,
opts: { now?: number; path?: string } = {},
): void {
if (verdict.verdict !== 'private') return;
const now = opts.now ?? Date.now();
const path = opts.path ?? visibilityCachePath();
let map: Record<string, VisibilityCacheEntry> = {};
try {
const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, VisibilityCacheEntry>;
for (const [k, v] of Object.entries(parsed)) {
const at = Date.parse(v?.verified_at ?? '');
if (v?.verdict === 'private' && Number.isFinite(at) && now - at <= VISIBILITY_CACHE_TTL_MS) map[k] = v;
}
} catch {
map = {};
}
map[cacheKey(originUrl)] = { verdict: 'private', via: verdict.via, verified_at: new Date(now).toISOString() };
try {
mkdirSync(dirname(path), { recursive: true });
const tmp = `${path}.tmp-${process.pid}`;
writeFileSync(tmp, JSON.stringify(map, null, 2) + '\n', { mode: 0o600 });
renameSync(tmp, path);
} catch {
/* cache write failure is never an error — next push just re-verifies */
}
}