security: add gitleaks pre-commit hook and CI scan (#1)

Deploys org-wide secret-leak prevention following the 2026-04-17
Discord webhook URL incident (scraped from public karaoke-gen repo,
used to spam malware in #releases).

Layers:
  - .githooks/pre-commit — gitleaks protect --staged (fail fast)
  - .github/workflows/security.yml — reusable CI scanner
  - .gitleaks.toml — default rules + Discord-webhook rule + FP allowlist

Author: beveradb

.githooks/pre-commit

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Nomad Karaoke shared pre-commit hook — scans staged changes for secrets.
+# Enable: git config core.hooksPath .githooks
+set -eu
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  printf '\033[33mwarn:\033[0m gitleaks not installed — skipping secret scan\n' >&2
+  printf '      install: brew install gitleaks   (or: https://github.com/gitleaks/gitleaks)\n' >&2
+  exit 0
+fi
+
+if ! gitleaks protect --staged --redact --no-banner; then
+  printf '\n\033[31m✗ gitleaks detected a potential secret in staged changes.\033[0m\n' >&2
+  printf '  • If real: remove it, rotate the credential, then re-commit.\n' >&2
+  printf '  • If false positive: add an allowlist entry to .gitleaks.toml.\n' >&2
+  printf '  • Emergency override (not recommended): git commit --no-verify\n' >&2
+  exit 1
+fi

.github/workflows/security.yml

@@ -0,0 +1,10 @@
+name: Security
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gitleaks:
+    uses: nomadkaraoke/.github/.github/workflows/gitleaks.yml@main

.gitleaks.toml

@@ -0,0 +1,60 @@
+# Nomad Karaoke shared gitleaks config.
+# Extends the default ruleset with one custom rule for Discord webhooks
+# and an allowlist covering known false-positive paths.
+
+title = "Nomad Karaoke"
+
+[extend]
+useDefault = true
+
+# ---------------------------------------------------------------------------
+# Custom rules
+# ---------------------------------------------------------------------------
+
+[[rules]]
+id = "discord-webhook-url"
+description = "Discord webhook URL (token embedded in URL)"
+regex = '''https://(?:discord|discordapp)\.com/api/webhooks/\d{17,20}/[A-Za-z0-9_-]{60,}'''
+tags = ["discord", "webhook", "secret"]
+
+# ---------------------------------------------------------------------------
+# Global allowlist
+# ---------------------------------------------------------------------------
+
+[allowlist]
+description = "Paths and patterns that are known false positives"
+
+paths = [
+  '''(?i)\.(jpg|jpeg|png|gif|bmp|svg|webp|pdf|ico|mp3|mp4|wav|flac|m4a)$''',
+  '''(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|poetry\.lock|Podfile\.lock|Cargo\.lock|go\.sum|composer\.lock|Gemfile\.lock|uv\.lock)$''',
+  '''(^|/)node_modules/''',
+  '''(^|/)vendor/''',
+  '''(^|/)wp-content/''',
+  '''(^|/)\.dart_tool/''',
+  '''(^|/)\.venv/''',
+  '''(^|/)\.next/''',
+  '''(^|/)build/''',
+  '''(^|/)dist/''',
+  '''(^|/)\.flutter-plugins''',
+  '''(^|/)test[-_]?fixtures?/''',
+  '''(^|/)tests?/.*conftest\.py$''',
+  '''(^|/)tests?/.*test_[^/]+\.py$''',
+  '''(^|/)tests?/.*_test\.py$''',
+  '''(^|/).*\.(test|spec)\.(js|mjs|cjs|ts|tsx|jsx)$''',
+  '''(^|/).*\.test\.local\.(js|mjs|cjs|ts|tsx|jsx|py)$''',
+  '''(^|/).*\.local\.(js|mjs|cjs|ts|tsx|jsx|py)$''',
+]
+
+regexes = [
+  # Explicit placeholder patterns
+  '''YOUR_[A-Z_]{2,}''',
+  '''EXAMPLE_[A-Z_]{2,}''',
+  '''PLACEHOLDER_[A-Z_]{2,}''',
+  '''CHANGE[_-]?ME''',
+  '''<[A-Z_]{2,}>''',
+  '''\$\{[A-Z_]{2,}\}''',
+
+  # Firebase / GCP client API keys — public by design (identify the project,
+  # access is gated by Firebase Security Rules).
+  '''AIzaSy[A-Za-z0-9_-]{33}''',
+]