@aldegad/safedeps 2.1.1 → 2.4.0

package/lib/gates/doctor.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+set -euo pipefail
+
+# safedeps doctor — repo security posture check.
+#
+# Diagnoses whether the per-repo secret-leak lane is set up (.gitleaks policy +
+# .githooks/pre-commit + active core.hooksPath + an available scanner) and
+# reports the global dependency-install gate too. Read-only by default; `--fix`
+# scaffolds the missing pieces (hooks init) and activates them (hooks install).
+#
+# Exit codes: 0 = no gaps in the secret-leak lane, 1 = gaps remain.
+
+GATES_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./repo-profile.sh
+source "$GATES_LIB_DIR/repo-profile.sh"
+
+REPO_ROOT=""
+FIX=0
+JSON_MODE="${SAFEDEPS_JSON_MODE:-0}"
+
+usage() {
+  printf 'Usage: safedeps doctor [--root <repo>] [--fix] [--json]\n' >&2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root) REPO_ROOT="${2:?--root needs a path}"; shift 2 ;;
+    --fix) FIX=1; shift ;;
+    --json) JSON_MODE=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 64 ;;
+  esac
+done
+
+if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+
+# --- check collection ---------------------------------------------------------
+# Each check appends a row: <lane>\t<status>\t<label>\t<remedy>
+# status ∈ ok | gap | na
+CHECK_ROWS=()
+GAPS=0
+
+add_check() {
+  local lane="$1" status="$2" label="$3" remedy="${4:-}"
+  CHECK_ROWS+=("${lane}"$'\t'"${status}"$'\t'"${label}"$'\t'"${remedy}")
+  # The exit code reflects the per-repo secret-leak lane only. The global
+  # dependency-install gate is reported (✗) but is a per-machine concern, so it
+  # does not gate this repo's posture result.
+  if [ "$status" = "gap" ] && [ "$lane" = "secret" ]; then GAPS=$((GAPS + 1)); fi
+}
+
+scanner_available() {
+  if command -v gitleaks >/dev/null 2>&1; then printf 'gitleaks'; return 0; fi
+  if command -v docker >/dev/null 2>&1; then printf 'docker'; return 0; fi
+  return 1
+}
+
+dependency_gate_root() {
+  # The dependency-install gate is installed globally as a skill symlink for
+  # whichever engine(s) are present.
+  local found=""
+  [ -e "$HOME/.claude/skills/safedeps" ] && found="${found:+${found}, }~/.claude/skills/safedeps"
+  [ -e "$HOME/.codex/skills/safedeps" ] && found="${found:+${found}, }~/.codex/skills/safedeps"
+  printf '%s' "$found"
+}
+
+run_checks() {
+  CHECK_ROWS=()
+  GAPS=0
+
+  local is_git=0
+  if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then is_git=1; fi
+
+  local profile="(n/a)"
+  if [ "$is_git" = 1 ]; then
+    add_check secret ok "git worktree"
+    profile="$(safedeps_repo_profile "$REPO_ROOT")"
+
+    local config_path config_label
+    config_path="$(safedeps_gitleaks_config "$REPO_ROOT" "$profile")"
+    config_label="gitleaks config ($(basename "$config_path"))"
+    if [ -f "$config_path" ]; then
+      add_check secret ok "$config_label"
+    else
+      add_check secret gap "$config_label" "safedeps hooks init --root \"$REPO_ROOT\""
+    fi
+
+    local hook_file="$REPO_ROOT/.githooks/pre-commit"
+    if [ -x "$hook_file" ]; then
+      add_check secret ok ".githooks/pre-commit (executable)"
+    elif [ -f "$hook_file" ]; then
+      add_check secret gap ".githooks/pre-commit (not executable)" "chmod +x \"$hook_file\""
+    else
+      add_check secret gap ".githooks/pre-commit (present)" "safedeps hooks init --root \"$REPO_ROOT\""
+    fi
+
+    local hooks_path
+    hooks_path="$(git -C "$REPO_ROOT" config --get core.hooksPath || true)"
+    if [ "$hooks_path" = ".githooks" ]; then
+      add_check secret ok "git hooks active (core.hooksPath=.githooks)"
+    else
+      add_check secret gap "git hooks active (core.hooksPath=${hooks_path:-<unset>})" "safedeps hooks install --root \"$REPO_ROOT\""
+    fi
+  else
+    add_check secret na "git worktree (secret lane needs git)"
+  fi
+
+  local scanner
+  if scanner="$(scanner_available)"; then
+    add_check secret ok "secret scanner available (${scanner})"
+  else
+    add_check secret gap "secret scanner available (gitleaks or docker)" "brew install gitleaks"
+  fi
+
+  local gate_root
+  gate_root="$(dependency_gate_root)"
+  if [ -n "$gate_root" ]; then
+    add_check deps ok "dependency-install gate installed (${gate_root})"
+  else
+    add_check deps gap "dependency-install gate installed" "node scripts/install/install-safedeps-hooks.mjs"
+  fi
+
+  DOCTOR_PROFILE="$profile"
+}
+
+emit_human() {
+  local sym
+  printf 'safedeps doctor — repo security posture\n'
+  printf 'repo:    %s\n' "$REPO_ROOT"
+  printf 'profile: %s\n\n' "$DOCTOR_PROFILE"
+
+  printf 'Secret-leak lane (per-repo)\n'
+  local row lane status label remedy
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    [ "$lane" = "secret" ] || continue
+    case "$status" in
+      ok) sym='✓' ;;
+      gap) sym='✗' ;;
+      *) sym='–' ;;
+    esac
+    if [ "$status" = "gap" ] && [ -n "$remedy" ]; then
+      printf '  %s %-44s → %s\n' "$sym" "$label" "$remedy"
+    else
+      printf '  %s %s\n' "$sym" "$label"
+    fi
+  done
+
+  printf '\nDependency-install gate (global, all repos)\n'
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    [ "$lane" = "deps" ] || continue
+    case "$status" in
+      ok) sym='✓' ;;
+      gap) sym='✗' ;;
+      *) sym='–' ;;
+    esac
+    if [ "$status" = "gap" ] && [ -n "$remedy" ]; then
+      printf '  %s %-44s → %s\n' "$sym" "$label" "$remedy"
+    else
+      printf '  %s %s\n' "$sym" "$label"
+    fi
+  done
+
+  printf '\n'
+  if [ "$GAPS" -eq 0 ]; then
+    printf 'No gaps in the secret-leak lane. The agent is on guard.\n'
+  else
+    printf '%d gap(s) in the secret-leak lane.\n' "$GAPS"
+    printf 'Fix all at once:  safedeps doctor --fix --root "%s"\n' "$REPO_ROOT"
+  fi
+}
+
+emit_json() {
+  local rows_json="[]" row lane status label remedy
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    rows_json="$(jq -c \
+      --arg lane "$lane" --arg status "$status" --arg label "$label" --arg remedy "$remedy" \
+      '. + [{lane:$lane, status:$status, label:$label, remedy:($remedy|select(length>0))}]' \
+      <<< "$rows_json")"
+  done
+  jq -nc \
+    --arg repo "$REPO_ROOT" \
+    --arg profile "$DOCTOR_PROFILE" \
+    --argjson gaps "$GAPS" \
+    --argjson checks "$rows_json" \
+    '{command:"doctor", repo:$repo, profile:$profile, gaps:$gaps, ok:($gaps==0), checks:$checks}'
+}
+
+# --- fix pass -----------------------------------------------------------------
+if [ "$FIX" -eq 1 ]; then
+  if ! git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    printf 'ERROR: --fix needs a git worktree (the secret lane is git-scoped): %s\n' "$REPO_ROOT" >&2
+    exit 1
+  fi
+  [ "$JSON_MODE" -eq 1 ] || printf 'safedeps doctor --fix: scaffolding + activating the secret-leak lane...\n\n'
+  bash "$GATES_LIB_DIR/hooks.sh" init --root "$REPO_ROOT"
+  bash "$GATES_LIB_DIR/hooks.sh" install --root "$REPO_ROOT"
+  [ "$JSON_MODE" -eq 1 ] || printf '\n'
+fi
+
+run_checks
+
+if [ "$JSON_MODE" -eq 1 ]; then
+  emit_json
+else
+  emit_human
+fi
+
+[ "$GAPS" -eq 0 ]

package/lib/gates/hooks.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+set -euo pipefail
+
+# safedeps hooks install|check — generic repo-local git hook activation.
+# Absorbed from kuma-studio scripts/security/{install,check}-hooks.sh.
+# The repo's privacy/secret policy lives in its own .githooks/pre-commit;
+# this command only manages hook activation, not the policy content.
+
+GATES_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./repo-profile.sh
+source "$GATES_LIB_DIR/repo-profile.sh"
+
+SUB=""
+REPO_ROOT=""
+HOOKS_PATH=".githooks"
+AUTO=0
+
+usage() {
+  printf 'Usage: safedeps hooks <install|check|init> [--root <repo>] [--hooks-path <dir>] [--auto]\n' >&2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    install|check|init) SUB="$1"; shift ;;
+    --root) REPO_ROOT="${2:?--root needs a path}"; shift 2 ;;
+    --hooks-path) HOOKS_PATH="${2:?--hooks-path needs a dir}"; shift 2 ;;
+    --auto) AUTO=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 64 ;;
+  esac
+done
+
+if [ -z "$SUB" ]; then usage; exit 64; fi
+if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+
+if ! git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  if [ "$SUB" = "install" ] && [ "$AUTO" -eq 1 ]; then
+    printf 'safedeps hooks: skipped install (not a git worktree)\n'
+    exit 0
+  fi
+  printf 'ERROR: not inside a git worktree: %s\n' "$REPO_ROOT" >&2
+  exit 1
+fi
+
+HOOK_FILE="$REPO_ROOT/$HOOKS_PATH/pre-commit"
+
+case "$SUB" in
+  init)
+    # Scaffold the repo's secret-leak policy from starter templates. Non-destructive:
+    # an existing file is reported and skipped, so repo-owned edits survive a re-run.
+    # `init` only drops files; `install` activates them (core.hooksPath).
+    TEMPLATES_DIR="$GATES_LIB_DIR/templates"
+    PROFILE="$(safedeps_repo_profile "$REPO_ROOT")"
+    created=0
+
+    scaffold() {
+      local dest="$1" tmpl="$2" mode="$3"
+      if [ -e "$dest" ]; then
+        printf 'safedeps hooks init: exists, skipped: %s\n' "$dest"
+        return 0
+      fi
+      if [ ! -f "$tmpl" ]; then
+        printf 'ERROR: template missing: %s\n' "$tmpl" >&2
+        exit 1
+      fi
+      mkdir -p "$(dirname "$dest")"
+      cp "$tmpl" "$dest"
+      chmod "$mode" "$dest"
+      printf 'safedeps hooks init: created %s\n' "$dest"
+      created=$((created + 1))
+    }
+
+    if [ "$PROFILE" = "private" ]; then
+      scaffold "$REPO_ROOT/.gitleaks.private.toml" "$TEMPLATES_DIR/gitleaks.private.toml.tmpl" 0644
+    else
+      scaffold "$REPO_ROOT/.gitleaks.toml" "$TEMPLATES_DIR/gitleaks.toml.tmpl" 0644
+    fi
+    scaffold "$REPO_ROOT/$HOOKS_PATH/pre-commit" "$TEMPLATES_DIR/pre-commit.tmpl" 0755
+
+    printf 'safedeps hooks init: profile=%s, %d file(s) created.\n' "$PROFILE" "$created"
+    if [ "$created" -gt 0 ]; then
+      printf '       Review the scaffolded .gitleaks policy, then activate:\n'
+      printf '         safedeps hooks install --root "%s"\n' "$REPO_ROOT"
+    fi
+    ;;
+  install)
+    if [ ! -f "$HOOK_FILE" ]; then
+      printf 'ERROR: hook file not found: %s\n' "$HOOK_FILE" >&2
+      printf '       the repo must provide its own %s/pre-commit policy.\n' "$HOOKS_PATH" >&2
+      exit 1
+    fi
+    chmod +x "$HOOK_FILE"
+    git -C "$REPO_ROOT" config core.hooksPath "$HOOKS_PATH"
+    printf 'safedeps hooks: installed repo-local git hooks at %s/%s\n' "$REPO_ROOT" "$HOOKS_PATH"
+    printf 'safedeps hooks: core.hooksPath = %s\n' "$(git -C "$REPO_ROOT" config --get core.hooksPath)"
+    ;;
+  check)
+    local_expected="$HOOKS_PATH"
+    actual="$(git -C "$REPO_ROOT" config --get core.hooksPath || true)"
+    if [ "$actual" != "$local_expected" ]; then
+      cat >&2 <<EOF
+ERROR: repo-local git hooks are not active.
+
+Expected core.hooksPath: $local_expected
+Actual core.hooksPath:   ${actual:-<unset>}
+
+Run:
+  safedeps hooks install --root "$REPO_ROOT"
+EOF
+      exit 1
+    fi
+    if [ ! -x "$HOOK_FILE" ]; then
+      printf 'ERROR: %s is not executable.\n' "$HOOK_FILE" >&2
+      exit 1
+    fi
+    if ! command -v gitleaks >/dev/null 2>&1; then
+      if ! command -v docker >/dev/null 2>&1 || ! docker info >/dev/null 2>&1; then
+        cat >&2 <<'EOF'
+ERROR: neither local gitleaks nor a running Docker daemon is available.
+
+Choose one:
+  brew install gitleaks
+  open -a Docker
+EOF
+        exit 1
+      fi
+    fi
+    printf 'safedeps hooks: active (core.hooksPath = %s)\n' "$local_expected"
+    ;;
+esac

package/lib/gates/repo-profile.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Generic repo security profile + gitleaks config resolution.
+# Absorbed from kuma-studio scripts/security/repo-profile.sh and made generic:
+# the private profile is detected by a "-private" suffix convention instead of a
+# hard-coded repo name, and overrides accept both SAFEDEPS_* and legacy KUMA_* env.
+
+safedeps_repo_profile() {
+  local repo_root="${1:?repo root required}"
+  local override="${SAFEDEPS_REPO_PROFILE:-${KUMA_SECURITY_REPO_PROFILE:-}}"
+
+  case "$override" in
+    public|private)
+      printf '%s\n' "$override"
+      return 0
+      ;;
+    "")
+      ;;
+    *)
+      printf 'ERROR: repo profile override must be "public" or "private", got: %s\n' "$override" >&2
+      return 64
+      ;;
+  esac
+
+  local origin_url repo_leaf
+  origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
+  repo_leaf="$(basename "$repo_root")"
+
+  # Convention: a repo whose origin slug or directory leaf ends in "-private" is
+  # the private profile (e.g. kuma-studio-private). Everything else is public.
+  if [[ "$origin_url" =~ (^|[/:-])[A-Za-z0-9._-]*-private(\.git)?$ ]] || [[ "$repo_leaf" == *-private ]]; then
+    printf 'private\n'
+    return 0
+  fi
+
+  printf 'public\n'
+}
+
+safedeps_gitleaks_config() {
+  local repo_root="${1:?repo root required}"
+  local profile="${2:?profile required}"
+  local override="${SAFEDEPS_GITLEAKS_CONFIG:-${KUMA_GITLEAKS_CONFIG:-}}"
+
+  if [ -n "$override" ]; then
+    printf '%s\n' "$override"
+    return 0
+  fi
+
+  case "$profile" in
+    private)
+      printf '%s/.gitleaks.private.toml\n' "$repo_root"
+      ;;
+    public)
+      printf '%s/.gitleaks.toml\n' "$repo_root"
+      ;;
+    *)
+      printf 'ERROR: unknown security profile: %s\n' "$profile" >&2
+      return 64
+      ;;
+  esac
+}

package/lib/gates/scan.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+set -euo pipefail
+
+# safedeps scan secrets — generic gitleaks runner.
+# Absorbed from kuma-studio scripts/security/run-gitleaks.sh and made generic:
+# repo root comes from --root (default: cwd), config from repo profile or override.
+# Preference order: local gitleaks binary -> Docker image (explicit, printed).
+
+GATES_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./repo-profile.sh
+source "$GATES_LIB_DIR/repo-profile.sh"
+
+REPO_ROOT=""
+MODE="repo"
+CONFIG_OVERRIDE=""
+IMAGE="${SAFEDEPS_GITLEAKS_IMAGE:-${KUMA_GITLEAKS_IMAGE:-ghcr.io/gitleaks/gitleaks:latest}}"
+
+usage() {
+  printf 'Usage: safedeps scan secrets [--repo|--worktree|--staged] [--root <repo>] [--config <path>]\n' >&2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) MODE="repo"; shift ;;
+    --worktree) MODE="worktree"; shift ;;
+    --staged) MODE="staged"; shift ;;
+    --root) REPO_ROOT="${2:?--root needs a path}"; shift 2 ;;
+    --config) CONFIG_OVERRIDE="${2:?--config needs a path}"; shift 2 ;;
+    secrets) shift ;; # allow `scan secrets ...`
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 64 ;;
+  esac
+done
+
+if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+
+REPO_PROFILE="$(safedeps_repo_profile "$REPO_ROOT")"
+if [ -n "$CONFIG_OVERRIDE" ]; then
+  CONFIG_PATH="$CONFIG_OVERRIDE"
+else
+  CONFIG_PATH="$(safedeps_gitleaks_config "$REPO_ROOT" "$REPO_PROFILE")"
+fi
+CONFIG_BASENAME="$(basename "$CONFIG_PATH")"
+
+cd "$REPO_ROOT"
+
+if [ ! -f "$CONFIG_PATH" ]; then
+  printf 'ERROR: gitleaks config does not exist: %s\n' "$CONFIG_PATH" >&2
+  exit 1
+fi
+
+printf 'safedeps secret scan: profile=%s config=%s mode=%s\n' "$REPO_PROFILE" "$CONFIG_BASENAME" "$MODE" >&2
+
+SCAN_ROOT="$REPO_ROOT"
+
+LOCAL_ARGS=(git --no-banner --redact --verbose --config "$CONFIG_PATH")
+DOCKER_ARGS=(git --no-banner --redact --verbose --config "/repo/$CONFIG_BASENAME")
+
+if [ "$MODE" = "staged" ]; then
+  LOCAL_ARGS+=(--pre-commit --staged)
+  DOCKER_ARGS+=(--pre-commit --staged)
+elif [ "$MODE" = "worktree" ]; then
+  LOCAL_ARGS=(dir --no-banner --redact --verbose --config "$CONFIG_PATH")
+  DOCKER_ARGS=(dir --no-banner --redact --verbose --config "/repo/$CONFIG_BASENAME")
+fi
+
+LOCAL_ARGS+=("$SCAN_ROOT")
+if [ "$MODE" = "worktree" ]; then
+  DOCKER_ARGS+=("/repo")
+else
+  DOCKER_ARGS+=(/repo)
+fi
+
+if command -v gitleaks >/dev/null 2>&1; then
+  gitleaks "${LOCAL_ARGS[@]}"
+  exit $?
+fi
+
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+  docker run --rm -v "$REPO_ROOT:/repo" -w /repo "$IMAGE" "${DOCKER_ARGS[@]}"
+  exit $?
+fi
+
+cat >&2 <<EOF
+ERROR: gitleaks is not available.
+
+Choose one:
+1. Install locally: brew install gitleaks
+2. Or start Docker so the scan can use: $IMAGE
+
+The scan is blocked (fail-closed) until a scanner is available.
+EOF
+exit 1

package/lib/gates/templates/gitleaks.private.toml.tmpl

@@ -0,0 +1,45 @@
+# .gitleaks.private.toml — safedeps starter secret-scan policy (PRIVATE profile).
+#
+# Resolved when the repo's origin slug or directory leaf ends in "-private",
+# or when SAFEDEPS_REPO_PROFILE=private. Use this for the stricter policy a
+# private repo wants on top of the public defaults.
+#
+# safedeps OWNS execution; THIS FILE is the repo's POLICY — you own it.
+# `safedeps hooks init` scaffolds this once and will NOT overwrite your edits.
+
+title = "safedeps secret-scan policy (private)"
+
+# Inherit gitleaks' built-in ruleset. To also layer the repo's public policy,
+# point `path` at it instead of (or in addition to) useDefault.
+[extend]
+useDefault = true
+# path = ".gitleaks.toml"
+
+# --- Extra rules layered on top of the defaults -------------------------------
+
+[[rules]]
+id = "safedeps-dotenv-file"
+description = "Committed .env file with an assigned secret value"
+path = '''(^|/)\.env(\.[\w.-]+)?$'''
+regex = '''(?i)(secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret)\s*[:=]\s*\S{6,}'''
+  [rules.allowlist]
+  paths = [
+    '''(^|/)\.env\.example$''',
+    '''(^|/)\.env\.sample$''',
+    '''(^|/)\.env\.template$''',
+  ]
+
+# Private repos often also flag internal identifiers (infra hosts, account ids).
+# Add your own, e.g.:
+# [[rules]]
+# id = "safedeps-internal-host"
+# description = "Internal hostname / infra endpoint"
+# regex = '''(?i)\b[\w.-]+\.internal\.example\.com\b'''
+
+# --- Repo-owned allowlist — CUSTOMIZE FOR THIS REPO ---------------------------
+[allowlist]
+description = "Repo-specific allowlist (tune me)"
+paths = [
+  '''(^|/)\.gitleaks\.toml$''',
+  '''(^|/)\.gitleaks\.private\.toml$''',
+]

package/lib/gates/templates/gitleaks.toml.tmpl

@@ -0,0 +1,43 @@
+# .gitleaks.toml — safedeps starter secret-scan policy (public repo profile).
+#
+# safedeps OWNS execution (it runs gitleaks via `safedeps scan secrets`).
+# THIS FILE is the repo's POLICY — you own it. Tune the [allowlist] below for
+# this repo. `safedeps hooks init` scaffolds this file once and will NOT
+# overwrite it on a re-run, so your edits are safe.
+#
+# gitleaks config reference: https://github.com/gitleaks/gitleaks#configuration
+
+title = "safedeps secret-scan policy"
+
+# Inherit gitleaks' built-in ruleset (AWS / GCP / private keys / OAuth tokens /
+# generic high-entropy secrets, etc.). This is the bulk of the coverage.
+[extend]
+useDefault = true
+
+# --- Extra rules layered on top of the defaults -------------------------------
+
+# Flag a committed real dotenv file with an assigned secret. The .example /
+# .sample / .template variants are allowlisted below so docs stay committable.
+[[rules]]
+id = "safedeps-dotenv-file"
+description = "Committed .env file with an assigned secret value"
+path = '''(^|/)\.env(\.[\w.-]+)?$'''
+regex = '''(?i)(secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret)\s*[:=]\s*\S{6,}'''
+  [rules.allowlist]
+  paths = [
+    '''(^|/)\.env\.example$''',
+    '''(^|/)\.env\.sample$''',
+    '''(^|/)\.env\.template$''',
+  ]
+
+# --- Repo-owned allowlist — CUSTOMIZE FOR THIS REPO ---------------------------
+[allowlist]
+description = "Repo-specific allowlist (tune me)"
+paths = [
+  '''(^|/)\.gitleaks\.toml$''',
+  '''(^|/)\.gitleaks\.private\.toml$''',
+  # Add test fixtures / docs that legitimately contain secret-shaped strings:
+  # '''(^|/)test/fixtures/''',
+]
+# regexes = ['''EXAMPLE_PLACEHOLDER_[A-Z0-9]+''']
+# stopwords = ["example", "dummy", "placeholder"]

package/lib/gates/templates/pre-commit.tmpl

@@ -0,0 +1,49 @@
+#!/bin/bash
+# .githooks/pre-commit — safedeps secret-leak gate (scaffolded by `safedeps hooks init`).
+#
+# Blocks a commit when gitleaks finds a secret in the STAGED changes, so a key
+# or a real .env never enters the repo's history. The detection POLICY lives in
+# this repo's .gitleaks.toml (public) / .gitleaks.private.toml (private);
+# safedeps owns execution. This hook delegates to one canonical scanner path:
+# `safedeps scan secrets --staged`.
+#
+# Intentional bypass (use sparingly — you own the risk):  git commit --no-verify
+set -euo pipefail
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# Resolve the safedeps CLI: PATH first, then the known skill install locations.
+resolve_safedeps() {
+  if command -v safedeps >/dev/null 2>&1; then printf 'safedeps'; return 0; fi
+  local candidate
+  for candidate in \
+    "${SAFEDEPS_BIN:-}" \
+    "${HOME}/.claude/skills/safedeps/bin/safedeps" \
+    "${HOME}/.codex/skills/safedeps/bin/safedeps"; do
+    if [ -n "${candidate}" ] && [ -x "${candidate}" ]; then
+      printf '%s' "${candidate}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if ! sd=$(resolve_safedeps); then
+  cat >&2 <<'EOF'
+safedeps pre-commit: cannot locate the `safedeps` CLI.
+
+The secret-scan gate is FAIL-CLOSED — the commit is blocked because the scanner
+could not run (no silent skip). Fix one of:
+  - put `safedeps` on PATH, or
+  - export SAFEDEPS_BIN=/path/to/bin/safedeps, or
+  - install the skill: node scripts/install/install-safedeps-hooks.mjs
+
+To bypass intentionally (you own the risk):  git commit --no-verify
+EOF
+  exit 1
+fi
+
+# Delegate to the single canonical scanner. A non-zero exit means either a
+# secret was found OR no scanner (gitleaks/docker) is available — both
+# fail-closed and block the commit.
+exec "${sd}" scan secrets --staged --root "${repo_root}"