aperion-shield 1.0.1

Aperion Shield -- a local MCP guardrail for AI coding agents with optional biometric identity gates (ID.me). Standalone, free, open source.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Bash sources for the git hooks installed by `--install-hooks`.
//!
//! Each script:
//!
//!  1. Identifies itself with the `APERION_SHIELD_HOOK_MARKER` line so
//!     the installer can re-recognise (and safely overwrite) its own
//!     hooks without clobbering user-authored ones.
//!  2. Honours the documented bypass switches:
//!       * `git commit --no-verify` / `git push --no-verify` (built into
//!         git -- there's nothing for us to do, but we tell the user).
//!       * `SHIELD_HOOKS_DISABLE=1`  (environment override; useful for
//!         non-interactive automation that can't pass `--no-verify`).
//!  3. Falls back gracefully (exit 0 with a stderr notice) when the
//!     `aperion-shield` binary isn't on `PATH`. This matters when
//!     teammates clone a repo where someone installed Shield hooks but
//!     haven't installed Shield themselves yet -- we don't want git
//!     operations to break for them.
//!  4. Calls the appropriate engine mode (`--check-staged` /
//!     `--check-pushed-refs`) and exits with whatever exit code Shield
//!     returned. Shield's own exit-code policy is the source of truth
//!     for what blocks the commit/push.
//!
//! Keeping the hook scripts thin (and deterministic) is on purpose -- if
//! the user inspects `.git/hooks/pre-commit` they should be able to
//! read it in under 30 seconds and trust what it does.

/// Stable marker line that identifies an Aperion-installed hook. The
/// installer matches on this line (not on whole-file checksum) so we
/// can evolve the hook body across versions without losing the ability
/// to recognise our own footprint.
pub const APERION_HOOK_MARKER: &str = "# APERION-SHIELD-HOOK v1 -- managed by `aperion-shield --install-hooks`";

/// Pre-commit hook. Runs the engine against staged changes (lines being
/// ADDED or MODIFIED) and refuses the commit if any line trips a Block
/// rule under the active shieldset.
pub fn pre_commit_script() -> String {
    format!(
        r#"#!/bin/sh
{marker}
#
# What this does:
#   * Asks `aperion-shield --check-staged` to scan the lines being
#     ADDED / MODIFIED in this commit.
#   * Blocks the commit (exit 1) if any line trips a destructive rule
#     (DROP DATABASE, rm -rf /, git push --force, etc.).
#   * No-ops cleanly when `aperion-shield` isn't on $PATH.
#
# Bypass switches (in order of preference):
#   git commit --no-verify        # skip all hooks for this commit
#   SHIELD_HOOKS_DISABLE=1 git ...  # env override; works in CI
#
# To remove this hook entirely:
#   aperion-shield --uninstall-hooks

set -e

if [ "${{SHIELD_HOOKS_DISABLE:-}}" = "1" ]; then
    exit 0
fi

if ! command -v aperion-shield >/dev/null 2>&1; then
    echo "[aperion-shield] binary not on \$PATH; skipping pre-commit guardrail" >&2
    echo "[aperion-shield] install: brew install AperionAI/tap/aperion-shield" >&2
    exit 0
fi

exec aperion-shield --check-staged
"#,
        marker = APERION_HOOK_MARKER,
    )
}

/// Pre-push hook. Reads the standard git-supplied stdin describing the
/// refs being pushed and refuses any force-push to a protected branch
/// unless `--no-verify` is passed.
pub fn pre_push_script() -> String {
    format!(
        r#"#!/bin/sh
{marker}
#
# What this does:
#   * Reads git's standard pre-push stdin (one `local_ref local_sha
#     remote_ref remote_sha` line per ref being pushed).
#   * Asks `aperion-shield --check-pushed-refs` whether any ref is a
#     destructive force-push or branch-deletion of a protected branch
#     (main, master, prod, release/*, by default).
#   * Blocks the push (exit 1) if any ref is destructive.
#   * No-ops cleanly when `aperion-shield` isn't on $PATH.
#
# Bypass switches:
#   git push --no-verify
#   SHIELD_HOOKS_DISABLE=1 git push ...
#
# To remove this hook entirely:
#   aperion-shield --uninstall-hooks

set -e

if [ "${{SHIELD_HOOKS_DISABLE:-}}" = "1" ]; then
    exit 0
fi

if ! command -v aperion-shield >/dev/null 2>&1; then
    echo "[aperion-shield] binary not on \$PATH; skipping pre-push guardrail" >&2
    exit 0
fi

# git supplies pre-push refs on stdin; pipe straight through.
exec aperion-shield --check-pushed-refs
"#,
        marker = APERION_HOOK_MARKER,
    )
}