Files
gstack/bin/gstack-egress-lib.sh
T
5884117c02 fix: sourced helpers share one self-locate block and fail loudly when they cannot locate themselves (#3024 rework)
The codex probe and the egress lib now carry one byte-identical block:
BASH_SOURCE under bash or %x under zsh, made absolute with $PWD, else a set
GSTACK_ROOT that holds the helper. Anything else (dash, sh, a shell that
cannot name the file) prints "gstack: cannot locate <helper> (shell: ...)"
with the docs/troubleshooting.md#sourced-helper-location URL and returns
before any bash- or zsh-only syntax. The Claude-only default path and the
$(pwd) fallback are gone.

The generated Codex preflight dot-sources the probe and, when it cannot load,
reports CODEX_MODE: helper_unavailable with the helper's own line instead of
falling through to not_authed. The class guard enumerates nested sources,
makes real resolver, auth, state-root and egress-home calls under bash and
zsh (absolute, relative then cd, bare name via PATH), covers dash and an
unknown shell, runs the full preflight, and lints BASH_SOURCE to the shared
block plus other bash-only constructs.

Co-authored-by: marcosdetry <marcosdetry@users.noreply.github.com>
Co-authored-by: akshaykalia <akshaykalia@users.noreply.github.com>
Co-authored-by: scottgigante-hubflow <scottgigante-hubflow@users.noreply.github.com>
Co-authored-by: woodsonl <woodsonl@users.noreply.github.com>
Co-authored-by: bezdekt <bezdekt@users.noreply.github.com>
2026-10-06 20:41:50 +00:00

153 lines
6.9 KiB
Bash

# gstack-egress-lib.sh — shared egress-receipt helpers for bash sinks.
#
# This file is NOT executable; source it:
#
# . "$(dirname "$0")/gstack-egress-lib.sh"
#
# THREAT MODEL: the egress ledger is forensic observability — it records
# ATTEMPTED egress so accidents are auditable; it is not an exfiltration
# control. Receipts are written before send, outcomes are best-effort, and
# fail-open callers can send unrecorded with a warning.
#
# Provides:
# _receipted_curl <closed|open> <sink> <host> <class> <consent> \
# (<payload-file>|--no-payload) <curl-cmd> [args...]
# — Writes an egress receipt BEFORE running the wrapped curl command.
# When a payload file is given, the receipt hashes that file and curl
# receives THE SAME FILE via an appended `--data-binary @file`, so the
# recorded sha256 matches the exact wire bytes (scan-at-sink precedent).
# The payload file is CONSUMED: the helper deletes it after the send
# (and on refusal) — callers need no cleanup trap for it.
# stdout is the wrapped command's stdout; returns its exit code.
# A best-effort outcome record (`exit:N`) is appended after the send;
# the receipt id is exported as _GSTACK_EGRESS_LAST_RECEIPT so callers
# can append a more specific outcome (e.g. the HTTP status).
#
# Fail policy (first argument, per call):
# closed — receipt failure REFUSES the send: nothing hits the network,
# return 3, problem/cause/fix message on stderr.
# open — receipt failure warns on stderr and proceeds unrecorded.
#
# _receipted_git <closed|open> <sink> <host> <class> <consent> <git-cmd> [args...]
# — Same contract for git-class ops: sha256:null receipt (a subprocess
# owns the bytes), no payload file, command runs unmodified.
#
# NO EXIT traps in this file, ever: callers (gstack-telemetry-sync) own
# their own EXIT traps and a trap set by a sourced library would clobber
# the caller's. All temp handling is immediate, per call.
# Self-locate with builtins only (no dirname), so the lib works under a
# stripped test PATH and under zsh, where it used to resolve to the caller's
# cwd and look for its siblings in the user's project.
_gstack_helper=gstack-egress-lib.sh
# >>> gstack self-locate (shared, byte-identical in every sourced helper) >>>
# Skill blocks source helpers into the host's shell: bash, or zsh on macOS
# (Claude Code's Bash tool included). Resolved once at source time, using
# parameter expansion only: BASH_SOURCE under bash, %x under zsh (inside eval
# so bash never parses it), made absolute with $PWD; else $GSTACK_ROOT/bin
# when it holds this helper. Any other case, and any other shell, fails loudly
# instead of guessing; the message and the return come before any bash- or
# zsh-only syntax, so dash and sh print it instead of a syntax error.
_gstack_helper_dir=""
_gstack_helper_shell=""
if [ -n "${BASH_VERSION:-}" ]; then
_gstack_helper_shell=bash
_gstack_helper_dir="${BASH_SOURCE[0]}"
elif [ -n "${ZSH_VERSION:-}" ]; then
_gstack_helper_shell=zsh
eval '_gstack_helper_dir="${(%):-%x}"'
fi
case "$_gstack_helper_dir" in
/*) _gstack_helper_dir="${_gstack_helper_dir%/*}" ;;
*/*) _gstack_helper_dir="$PWD/${_gstack_helper_dir%/*}" ;;
?*) _gstack_helper_dir="$PWD" ;;
esac
if [ -n "$_gstack_helper_shell" ] && [ ! -f "$_gstack_helper_dir/$_gstack_helper" ]; then
_gstack_helper_dir=""
if [ -n "${GSTACK_ROOT:-}" ] && [ -f "$GSTACK_ROOT/bin/$_gstack_helper" ]; then
_gstack_helper_dir="$GSTACK_ROOT/bin"
fi
fi
if [ -z "$_gstack_helper_shell" ] || [ -z "$_gstack_helper_dir" ]; then
_gstack_helper_error="gstack: cannot locate $_gstack_helper (shell: ${_gstack_helper_shell:-${0##*/}}). Source it from bash or zsh, or export GSTACK_ROOT=<install dir>. https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#sourced-helper-location"
printf '%s\n' "$_gstack_helper_error" >&2
return 1 2>/dev/null || exit 1
fi
# <<< gstack self-locate <<<
_gstack_egress_lib_dir="$_gstack_helper_dir"
unset _gstack_helper _gstack_helper_dir _gstack_helper_shell
# State root from the shared twin (bin/gstack-state-root.sh, builtins only),
# sourced lazily on first use.
_gstack_egress_home() {
if command -v gstack_state_root >/dev/null 2>&1 || { [ -f "$_gstack_egress_lib_dir/gstack-state-root.sh" ] && . "$_gstack_egress_lib_dir/gstack-state-root.sh"; }; then
gstack_state_root
else
printf '%s' "<gstack state root: $_gstack_egress_lib_dir/gstack-state-root.sh is missing; reinstall with ./setup or /gstack-upgrade>"
fi
}
# Problem + cause + fix, in plain language (DX contract for every
# fail-closed refusal). $1 = sink, $2 = cause text from the receipt bridge.
_gstack_egress_refusal() {
local home
home="$(_gstack_egress_home)"
echo "gstack: $1 NOT sent — the egress receipt could not be written (${2:-unknown cause}). Fix: chmod -R u+w $home/security (or check GSTACK_HOME). What this is: gstack records everything it ATTEMPTS to send off-machine; see gstack-egress." >&2
}
# Shared core. $6 is a payload file path or --no-payload; the rest is the
# command to run. Payload files are deleted here (immediate, no traps).
_gstack_egress_run() {
local policy="$1" sink="$2" host="$3" class="$4" consent="$5" payload="$6"
shift 6
local bin="$_gstack_egress_lib_dir/gstack-egress-receipt"
local payload_flag=(--no-payload)
[ "$payload" != "--no-payload" ] && payload_flag=(--payload-file "$payload")
local receipt_id="" receipt_err="" err_file=""
err_file="$(mktemp "${TMPDIR:-/tmp}/gstack-egress-err-XXXXXX" 2>/dev/null)" || err_file=""
if [ -n "$err_file" ]; then
receipt_id="$("$bin" write --sink "$sink" --host "$host" --class "$class" \
"${payload_flag[@]}" --consent "$consent" 2>"$err_file")" || receipt_id=""
receipt_err="$(head -c 500 "$err_file" 2>/dev/null | tr '\n' ' ')"
rm -f "$err_file"
else
receipt_id="$("$bin" write --sink "$sink" --host "$host" --class "$class" \
"${payload_flag[@]}" --consent "$consent" 2>/dev/null)" || receipt_id=""
fi
_GSTACK_EGRESS_LAST_RECEIPT="$receipt_id"
if [ -z "$receipt_id" ]; then
if [ "$policy" = "closed" ]; then
_gstack_egress_refusal "$sink" "$receipt_err"
[ "$payload" != "--no-payload" ] && rm -f "$payload"
return 3
fi
echo "gstack: egress receipt could not be written for $sink (${receipt_err:-unknown cause}) — sending anyway (fail-open). gstack normally records everything it ATTEMPTS to send off-machine; see gstack-egress." >&2
fi
local status=0
if [ "$payload" = "--no-payload" ]; then
"$@" || status=$?
else
"$@" --data-binary @"$payload" || status=$?
rm -f "$payload"
fi
if [ -n "$receipt_id" ]; then
"$bin" outcome "$receipt_id" "exit:$status" 2>/dev/null || true
fi
return $status
}
_receipted_curl() {
_gstack_egress_run "$@"
}
_receipted_git() {
local policy="$1" sink="$2" host="$3" class="$4" consent="$5"
shift 5
_gstack_egress_run "$policy" "$sink" "$host" "$class" "$consent" --no-payload "$@"
}