@svayam-opensource/prj 0.5.1

package/scripts/validate/check_privacy.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+Privacy check for the publish branch.
+
+Verifies that none of the per-org values from main's org-config.yaml have
+leaked into the publish branch. This is the inverse of STRICT_PLACEHOLDERS=1
+(which catches placeholders leaking into main): here we catch real values
+leaking out of main into publish.
+
+How it works:
+  1. Read main's org-config.yaml via `git show main:org-config.yaml`.
+  2. Extract values that are org-specific (skip generic defaults like
+     "main", "dev", "@*-tbd", placeholder strings).
+  3. Grep the working tree for any of those values.
+  4. Any match is a privacy leak — exit non-zero.
+
+Used as a CI gate on PRs to publish (defense in depth alongside the
+test-merge gate, scripts/sync-from-publish.sh's STRICT_PLACEHOLDERS=1
+check, and the discipline of editing publish-side only).
+
+Designed to run in the private (source) repo where main is accessible.
+Not intended for the public mirror repo.
+
+Usage:
+    python3 scripts/validate/check_privacy.py [REPO_ROOT]
+
+Exits 0 if no leaks, 1 if leaks found, 2 on error.
+"""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("[FAIL] PyYAML not installed. Run: bash scripts/install-deps.sh", file=sys.stderr)
+    sys.exit(2)
+
+
+# Keys whose values are scanned for leaks
+PRIVATE_KEYS = [
+    "org_name",
+    "org_short_name",
+    "org_slug",
+    "org_slug_lower",
+    "github_org",
+    "workspace_repo",
+    "policy_owner_email",
+    "policy_owner_github",
+    "legal_owner_github",
+    "infra_owner_github",
+    "system_arch_owner_github",
+    "data_arch_owner_github",
+]
+
+# Generic values — never considered org-specific
+GENERIC_VALUES = {
+    "", "main", "dev", "master",
+    "YYYY-MM-DD",
+    "Your Organization Name", "YourOrg",
+    "ORG", "org",
+    "your-github-org", "000-org-prj",
+    "you@example.com", "@your-github-handle",
+}
+
+# Patterns that indicate a value is still a placeholder / not org-specific
+PLACEHOLDER_VALUE_PATTERNS = [
+    re.compile(r"^@[a-z-]*-tbd$"),
+    re.compile(r"^\{\{[A-Za-z_]+\}\}$"),
+    re.compile(r"^\d{4}-\d{2}-\d{2}$"),
+]
+
+# File patterns to scan
+SCAN_SUFFIXES = {".md", ".yaml", ".yml", ".sh", ".py"}
+SCAN_NAMES = {"CODEOWNERS", "prj"}
+
+# Files where leak values are expected and not actually leaks
+ALLOWED_FILES = {
+    "setup.sh",         # contains placeholder strings as part of substitution rules
+    "org-config.yaml",  # the source of values; not itself in publish content
+}
+
+# Per-key attribution allowance: these (key, file) combinations are NOT leaks.
+# Legitimate copyright/attribution of the framework's original author in the
+# standard public-facing files. Any other key in those files, or these keys
+# elsewhere, are still flagged.
+# org_short_name is included because it is typically a substring of org_name
+# (e.g., a short brand name appearing inside the full legal name) and would
+# otherwise false-positive on every legitimate copyright line.
+ATTRIBUTION_KEYS = {"org_name", "org_short_name"}
+ATTRIBUTION_FILES = {
+    "LICENSE", "README.md",
+    "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md",
+}
+
+
+def is_generic(value: str) -> bool:
+    if not isinstance(value, str):
+        return True
+    if value in GENERIC_VALUES:
+        return True
+    for pattern in PLACEHOLDER_VALUE_PATTERNS:
+        if pattern.match(value):
+            return True
+    return False
+
+
+def get_main_config(repo_root: Path) -> dict | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "show", "main:org-config.yaml"],
+            capture_output=True, text=True, check=True,
+        )
+        config = yaml.safe_load(result.stdout)
+        if not isinstance(config, dict):
+            print("[ERROR] main:org-config.yaml is not a mapping.", file=sys.stderr)
+            return None
+        return config
+    except subprocess.CalledProcessError as e:
+        print(
+            "[ERROR] Cannot read 'main:org-config.yaml'. "
+            "Privacy check requires access to main branch in this repo.\n"
+            f"  git error: {e.stderr.strip()}",
+            file=sys.stderr,
+        )
+        return None
+    except yaml.YAMLError as e:
+        print(f"[ERROR] main:org-config.yaml does not parse: {e}", file=sys.stderr)
+        return None
+
+
+def scannable_files(repo_root: Path):
+    for f in repo_root.rglob("*"):
+        if not f.is_file():
+            continue
+        rel = f.relative_to(repo_root)
+        if any(p.startswith(".") for p in rel.parts):
+            continue
+        if f.name in ALLOWED_FILES:
+            continue
+        if f.suffix in SCAN_SUFFIXES or f.name in SCAN_NAMES:
+            yield f
+
+
+def find_leaks(repo_root: Path, key: str, value: str) -> list[tuple[Path, int, str]]:
+    leaks: list[tuple[Path, int, str]] = []
+    attribution_ok = key in ATTRIBUTION_KEYS
+    for f in scannable_files(repo_root):
+        # Skip attribution-allowed files for keys that are valid attribution
+        if attribution_ok and f.name in ATTRIBUTION_FILES:
+            continue
+        try:
+            text = f.read_text()
+        except Exception:
+            continue
+        for lineno, line in enumerate(text.splitlines(), 1):
+            if value in line:
+                leaks.append((f.relative_to(repo_root), lineno, line.strip()))
+    return leaks
+
+
+def main() -> int:
+    repo_root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+
+    config = get_main_config(repo_root)
+    if config is None:
+        return 2
+
+    # Collect non-generic values to check
+    to_check: list[tuple[str, str]] = []
+    for key in PRIVATE_KEYS:
+        value = config.get(key)
+        if isinstance(value, str) and not is_generic(value):
+            # For @-prefixed handles, also strip the @ for substring matching
+            to_check.append((key, value))
+
+    if not to_check:
+        print("=== no org-specific values to check (main appears to be unconfigured) ===")
+        return 0
+
+    print(f"Checking publish for leaks of {len(to_check)} value(s) from main:org-config.yaml...")
+    print()
+
+    total_leaks = 0
+    for key, value in to_check:
+        leaks = find_leaks(repo_root, key, value)
+        if leaks:
+            total_leaks += len(leaks)
+            print(f"[LEAK] {key}={value!r} appears in {len(leaks)} location(s):")
+            for relpath, lineno, line in leaks[:10]:
+                snippet = line if len(line) <= 100 else line[:97] + "..."
+                print(f"   {relpath}:{lineno}: {snippet}")
+            if len(leaks) > 10:
+                print(f"   ... and {len(leaks) - 10} more")
+            print()
+
+    if total_leaks:
+        print(f"=== {total_leaks} privacy leak(s) found ===")
+        print()
+        print("These values from main:org-config.yaml have leaked into publish content.")
+        print("Remove them or replace with placeholder/example values.")
+        return 1
+
+    print("=== no privacy leaks ===")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate/check_protocol.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+Session-start protocol integrity check (#54 Increment 1 — Layer 3-A).
+
+The session-start protocol (agent/session-protocol.md) is only enforceable if it
+is reliably DELIVERED. This validator gates that precondition, author-agnostic
+and deterministic:
+
+  1. agent/session-protocol.md exists and is non-empty.
+  2. It still carries the §0 "agent speaks first / context manifest / before you
+     change any code" mandate — i.e. nobody gutted the protocol while leaving the
+     file in place.
+  3. Every generated tool copy is in sync with the canonical protocol
+     (scripts/render-harness.sh --check) — i.e. no generated copy was hand-edited
+     to weaken or drop the protocol, and the protocol is rendered to every active
+     install path (a missing path counts as drift).
+
+Invoked via scripts/validate/run.py (the test-merge `validate` gate) and runnable
+directly: python3 scripts/validate/check_protocol.py [REPO_ROOT].
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+# Stable anchors from session-protocol.md §0. If any disappears, the protocol's
+# core mandate was removed even if the file still exists.
+MANDATE_ANCHORS = (
+    "agent speaks first",
+    "context manifest",
+    "before you change any code",
+)
+
+
+def check_protocol(repo_root: Path) -> list[str]:
+    errors: list[str] = []
+
+    protocol = repo_root / "agent" / "session-protocol.md"
+    if not protocol.exists():
+        return ["agent/session-protocol.md is missing — the session-start protocol is undelivered"]
+    text = protocol.read_text(encoding="utf-8", errors="replace")
+    if not text.strip():
+        errors.append("agent/session-protocol.md is empty")
+    else:
+        low = text.lower()
+        missing = [a for a in MANDATE_ANCHORS if a not in low]
+        if missing:
+            errors.append(
+                "agent/session-protocol.md no longer contains its §0 mandate "
+                f"(missing: {', '.join(missing)})"
+            )
+
+    # Generated copies must match the canonical protocol. Reuse render-harness's
+    # own --check (it also treats a missing install path as drift).
+    renderer = repo_root / "scripts" / "render-harness.sh"
+    manifest = repo_root / "agent" / "harness-manifest.yaml"
+    if renderer.exists() and manifest.exists():
+        try:
+            r = subprocess.run(
+                ["bash", str(renderer), "--check"],
+                cwd=str(repo_root), capture_output=True, text=True,
+            )
+            if r.returncode != 0:
+                detail = (r.stdout + r.stderr).strip().replace("\n", " ")
+                errors.append(
+                    "generated protocol copies are out of sync with "
+                    f"agent/session-protocol.md — run ./scripts/render-harness.sh ({detail[:300]})"
+                )
+        except OSError as e:
+            errors.append(f"could not run render-harness.sh --check: {e}")
+
+    # #54 Increment 2 — if the Claude Code client gate is configured, its parts
+    # must all be present (guard against a hook being deleted while settings.json
+    # still points at it, which would break the gate). Conditional on
+    # settings.json existing, so repos that haven't adopted the gate aren't forced
+    # to.
+    settings = repo_root / ".claude" / "settings.json"
+    if settings.exists() and "session-start" in settings.read_text(encoding="utf-8", errors="replace"):
+        for rel in (
+            ".claude/hooks/session-start.sh",
+            ".claude/hooks/pre-tool-gate.sh",
+            ".claude/hooks/session-ack.sh",
+            ".claude/commands/session-start.md",
+        ):
+            p = repo_root / rel
+            if not p.exists() or not p.read_text(encoding="utf-8", errors="replace").strip():
+                errors.append(f"session-start gate is configured but {rel} is missing/empty")
+
+    # Same guard for the Cursor client gate (.cursor/hooks.json).
+    cursor_hooks = repo_root / ".cursor" / "hooks.json"
+    if cursor_hooks.exists() and "session-gate" in cursor_hooks.read_text(encoding="utf-8", errors="replace"):
+        for rel in (
+            ".cursor/hooks/session-start.sh",
+            ".cursor/hooks/session-gate.sh",
+            ".cursor/hooks/session-ack.sh",
+        ):
+            p = repo_root / rel
+            if not p.exists() or not p.read_text(encoding="utf-8", errors="replace").strip():
+                errors.append(f"Cursor session-start gate is configured but {rel} is missing/empty")
+
+    return errors
+
+
+def main() -> int:
+    repo_root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    errors = check_protocol(repo_root)
+    if errors:
+        print(f"[FAIL] protocol ({len(errors)} error(s)):")
+        for e in errors:
+            print(f"   - {e}")
+        return 1
+    print("=== protocol integrity ok ===")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate/check_secrets.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Secret / credential scanner (POL-143 enforcement).
+
+PRJ-013 audit finding H8 (dimension H/I): POL-143 forbids committing secrets,
+tokens, keys, and credentials, but the framework had ZERO automated
+enforcement — privacy-check.yml/check_privacy.py only catch org-config values
+leaking to publish, not credentials. This scanner closes that gap as a CI gate
+(it runs inside scripts/validate/run.py, which the test-merge `validate` job
+invokes on every PR to main/publish).
+
+Design goals:
+  - HIGH SIGNAL, LOW false-positive. Patterns match only well-known,
+    structurally-distinctive credential shapes, not anything that merely looks
+    "password-ish". This keeps the gate trustworthy so it is never disabled.
+  - stdlib only (runs under any python3, no pip deps).
+  - tracked text files only (skips .git, skips binaries via a NUL-byte sniff).
+  - an inline `# pragma: allowlist secret` on the matching line suppresses the
+    finding (for fixtures, docs that must show an example token shape, etc.).
+
+Usage:
+    python3 scripts/validate/check_secrets.py [REPO_ROOT]
+
+Exits 0 if no secrets found, 1 if any high-confidence secret is found.
+Invokable directly or via run.py's `check_secrets(repo_root)` entry point.
+"""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# Inline suppression marker (detect-secrets compatible style).
+ALLOWLIST_MARKER = "pragma: allowlist secret"
+
+# Directories never scanned (in addition to anything git doesn't track).
+SKIP_DIR_PARTS = {".git"}
+
+# A placeholder value is NOT a secret. Used by the generic assignment patterns
+# (password=/api_key=) to avoid flagging example/empty/template values.
+PLACEHOLDER_RE = re.compile(
+    r"""^(?:
+          | \s*                                  # empty / whitespace
+          | x+ | \.\.\. | -+ | \*+               # x..., ---, ***
+          | changeme | example | placeholder
+          | your[-_].* | my[-_].* | some[-_].*
+          | redacted | dummy | sample | test(?:ing)? | fake
+          | none | null | nil | true | false
+          | \$\{[^}]+\} | \{\{[^}]+\}\}          # ${VAR} / {{TOKEN}}
+          | \$[A-Za-z_][A-Za-z0-9_]*             # $VAR
+          | <[^>]+>                               # <your-token>
+      )$""",
+    re.IGNORECASE | re.VERBOSE,
+)
+
+# ── High-signal patterns ──────────────────────────────────────────────────────
+# Each entry: (label, compiled-regex). A regex matching anywhere on a line
+# (that is not an allowlisted line) is a finding. These shapes are
+# distinctive enough that a match is almost certainly a real credential.
+PATTERNS = [
+    (
+        "private key block",
+        re.compile(r"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----"),
+    ),
+    (
+        "GitHub token",
+        re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b"),
+    ),
+    (
+        "GitHub fine-grained PAT",
+        re.compile(r"\bgithub_pat_[A-Za-z0-9_]{60,}\b"),
+    ),
+    (
+        "AWS access key id",
+        re.compile(r"\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA|ANVA)[0-9A-Z]{16}\b"),
+    ),
+    (
+        "Slack token",
+        re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"),
+    ),
+]
+
+# Generic assignment patterns: `password = "..."` / `api_key: '...'` etc.
+# These are the only patterns that gate on the VALUE not being a placeholder,
+# since the keyword alone (password/api_key) is common in legitimate code/docs.
+ASSIGNMENT_RE = re.compile(
+    r"""(?P<key>\b(?:password|passwd|pwd|api[_-]?key|secret[_-]?key
+            |access[_-]?token|auth[_-]?token|client[_-]?secret)\b)
+        \s*[:=]\s*
+        (?P<q>["'])(?P<val>[^"']{6,})(?P=q)""",
+    re.IGNORECASE | re.VERBOSE,
+)
+
+
+def is_placeholder(value: str) -> bool:
+    return bool(PLACEHOLDER_RE.match(value.strip()))
+
+
+def tracked_files(repo_root: Path) -> list[Path]:
+    """Return git-tracked files; fall back to a filesystem walk if not a repo."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "ls-files", "-z"],
+            capture_output=True, check=True,
+        )
+        names = result.stdout.decode("utf-8", "replace").split("\0")
+        return [repo_root / n for n in names if n]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        out = []
+        for f in repo_root.rglob("*"):
+            if f.is_file() and not any(p in SKIP_DIR_PARTS for p in f.relative_to(repo_root).parts):
+                out.append(f)
+        return out
+
+
+def is_binary(path: Path) -> bool:
+    try:
+        with open(path, "rb") as fh:
+            return b"\0" in fh.read(8192)
+    except OSError:
+        return True
+
+
+def scan_file(repo_root: Path, path: Path) -> list[tuple[str, int, str, str]]:
+    """Return (relpath, lineno, label, snippet) findings for one file."""
+    findings: list[tuple[str, int, str, str]] = []
+    rel = str(path.relative_to(repo_root))
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return findings
+
+    for lineno, line in enumerate(text.splitlines(), 1):
+        if ALLOWLIST_MARKER in line:
+            continue
+        for label, pat in PATTERNS:
+            if pat.search(line):
+                findings.append((rel, lineno, label, line.strip()[:120]))
+        m = ASSIGNMENT_RE.search(line)
+        if m and not is_placeholder(m.group("val")):
+            findings.append((rel, lineno, "hardcoded credential", line.strip()[:120]))
+    return findings
+
+
+def check_secrets(repo_root: Path) -> list[str]:
+    """run.py entry point: return a list of error strings (empty == pass)."""
+    errors: list[str] = []
+    for path in tracked_files(repo_root):
+        if any(p in SKIP_DIR_PARTS for p in path.relative_to(repo_root).parts):
+            continue
+        if not path.is_file() or is_binary(path):
+            continue
+        for rel, lineno, label, snippet in scan_file(repo_root, path):
+            errors.append(f"{rel}:{lineno}: {label}: {snippet}")
+    return errors
+
+
+def main() -> int:
+    repo_root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    errors = check_secrets(repo_root)
+    if errors:
+        print(f"[FAIL] secrets ({len(errors)} finding(s)):")
+        for e in errors:
+            print(f"   - {e}")
+        print()
+        print("POL-143: remove the credential and rotate it. If this is a known")
+        print("non-secret (fixture/example), append '# pragma: allowlist secret'")
+        print("to the line.")
+        return 1
+    print("=== no secrets found ===")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())