ci/bin/certclaims

#!/usr/bin/env bash
# certclaims — refuse a repo that claims a certification it cannot produce.
# One implementation, every caller.
#
#   certclaims [dir]
#
# WHAT THIS CATCHES
#
# A page saying "SOC 2 Type II certified" when no report exists. It is not a
# copy problem. A security reviewer asks for the report, and the answer is
# either a PDF or the end of the deal — so this is the rare marketing sentence
# with a binary, checkable truth value, and the only one worth a build gate.
#
# It has already happened across our own surfaces. hanzo.industries said
# "SOC 2 Type II certified" and "audited and certified by independent
# third-party auditors" while hanzo.ai said "assessment planned" and hanzo.app
# said "audit in progress". Three answers to one question, none with an artifact
# behind it, and our own hip-0290 lists the auditor as "TBD". bootno.de went
# further and offered the report itself: "available to enterprise customers
# under NDA" — a standing promise to hand over a document that does not exist,
# made in the one room where somebody says yes.
#
# WHY IT SURVIVES
#
# Nothing fails. A false certification claim compiles, renders, passes every
# test, and looks better than the truth. It also spreads by copy-paste between
# sites, and drifts back on merge: twelve branches still carried "has completed
# SOC 2 Type II certification" after main was corrected, each one waiting to
# reintroduce it. Fixing main does not fix what is queued onto main.
#
# THE RULE
#
# Two different sentences get confused with each other, and only one of them is
# a lie:
#
#   "SOC 2 certified"          — claims a certificate from an auditor. We have none.
#   "Compatible with SOC 2"    — claims our controls are built to that framework.
#   "Report available on request" — offers a document we do write and do send.
#
# So a framework may be NAMED, in a sentence about control alignment or about a
# document we will actually send. What fails is claiming the certificate:
# certified, certification, accredited, or audited by someone independent.
#
# Hedges fail too, and this is the part that changed. "SOC 2 audit in progress",
# "assessment planned", "SOC 2 ready", "Type II readiness" — each one reads to a
# skimming buyer as a claim, dates itself the moment it ships, and is the exact
# shape the drift took last time: hanzo.industries claimed the certificate,
# hanzo.ai said the assessment was planned, hanzo.app said the audit was
# underway, and nothing was behind any of the three.
#
# Saying what we LACK is not the fix either. A disclaimer lands in /trust's meta
# description, the line a search engine prints under the result for anyone asking
# whether we are certified — an answer opening with three things we do not hold.
# What is true is positive: continual internal audits, report on request.
#
# NOT CHECKED HERE
#
# Dated posts. A changelog entry or a blog post from 2020 is a record of what
# was said then, and rewriting history to pass a gate is a worse failure than
# the claim. Those are listed, not enforced — someone decides whether to amend,
# annotate or unpublish.
set -euo pipefail

root="${1:-.}"

# The frameworks a buyer's procurement process actually asks for a report on.
frameworks='SOC ?2|ISO ?27001|FedRAMP|PCI ?DSS|HITRUST|HIPAA'
# The sentence shapes that make naming a framework legitimate: control alignment,
# or an offer of the document we do write. Deliberately broad — the point is to
# admit every honest phrasing, not to police wording.
allowed='compatible with|compliant with|built to|aligned (to|with)|(available )?(up)?on (request|demand)|internal audits?'
# Words that claim a certificate we do not hold. "compliant" is absent on
# purpose: "compliant with SOC 2" is a statement about controls and is allowed
# above, while the certificate words below are not rescued by any phrasing.
# "report" is here because possessing one is the same claim as holding the
# certificate — an audit produced it. Offering the document we do write stays
# legitimate through "on request" in the allowed shapes above.
claim='certified|certification|accredited|attestation|letter of|report'
# Hedges. Each one reads as a claim to someone skimming and dates itself the day
# it ships. There is no phrasing that makes one of these acceptable.
hedge='in.?progress|in.?audit|assessment planned|\bplanned\b|readiness|\bready\b|\bscoped\b|towards?\b|working toward'

# A claim of third-party certification that names no framework at all. It is a
# separate rule because the first one keys on a framework name, and this phrasing
# deliberately has none — hanzo.industries carried "audited and certified by
# independent third-party auditors" as the body under a card whose title supplied
# the framework, so each half looked incomplete on its own.
audited='(audited|certified|accredited) by [^.]{0,40}(independent|third.?party|external|auditor)'

# ONE grep per rule over every file, not two per file. A process per file was
# 30 s on a 1,286-file repo here and 80 s on a runner, where every fork crosses
# the sandbox (hanzo-inc/platform, forge run 16634); the lines a rule matches
# are few, and only those are read one at a time.
files=()
while IFS= read -r file; do
  # Dated records are history; see above.
  # A dated filename IS the exemption -- 2020-03-18-hanzo-cloud.mdx is a record
  # of what was said in 2020, wherever it happens to be filed. Keying on the
  # containing directory missed posts/ and _offbrand/ holding the same file.
  case "${file##*/}" in
    CHANGELOG*|changelog*|20[0-9][0-9]-[01][0-9]-[0-3][0-9]-*) continue ;;
    # Where the policy is DEFINED it has to quote what it forbids, or it cannot
    # say what it forbids. An agent-instruction file and a copy gate are the two
    # places that happens, and neither is a surface a customer reads. Exempting
    # them is narrow on purpose: no page can become one by mentioning the rule.
    LLM.md|CLAUDE.md|AGENTS.md|GEMINI.md) continue ;;
  esac
  case "$file" in
    */CHANGELOG*|*/changelog*) continue ;;
    e2e/gates/*|*/e2e/gates/*|ci/bin/*|*/ci/bin/*) continue ;;
  esac
  files+=("$file")
done < <(git -C "$root" ls-files -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.md' '*.mdx' '*.html' '*.vue' '*.svelte' 2>/dev/null || true)

# matches <grep flags> <pattern>: `file NUL lineno:line` per matching line.
# --null and not -Z, which BSD grep reads as --decompress.
matches() {
  [ ${#files[@]} -gt 0 ] || return 0
  (cd "$root" && printf '%s\0' "${files[@]}" | xargs -0 grep -H --null -n "$@" -- 2>/dev/null) || true
}

fail=0
while IFS= read -r -d '' file && IFS= read -r rest; do
  lineno=${rest%%:*}; line=${rest#*:}
  [ -n "${line:-}" ] || continue
  printf '%s' "$line" | grep -qiE "$frameworks" || continue
  # A hedge beside a framework name fails whatever else the line says.
  if printf '%s' "$line" | grep -qiE "$hedge"; then
    printf '%s:%s: %s\n' "$file" "$lineno" "$(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-120)"
    fail=1
    continue
  fi
  # Otherwise only a claim to the certificate itself fails, and only where the
  # line does not put it in one of the shapes that are true.
  printf '%s' "$line" | grep -qiE "$claim"   || continue
  printf '%s' "$line" | grep -qiE "$allowed" && continue
  printf '%s:%s: %s\n' "$file" "$lineno" "$(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-120)"
  fail=1
done < <(matches -E "$frameworks")

while IFS= read -r -d '' file && IFS= read -r rest; do
  lineno=${rest%%:*}; line=${rest#*:}
  [ -n "${line:-}" ] || continue
  printf '%s' "$line" | grep -qiE "$allowed" && continue
  printf '%s:%s: %s\n' "$file" "$lineno" "$(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-120)"
  fail=1
done < <(matches -iE "$audited")

if [ "$fail" -ne 0 ]; then
  echo ""
  echo "certclaims: a line above claims a certificate, or hedges beside a framework."
  echo "Say the true, positive thing: \"compatible with X\", \"report available on request\","
  echo "\"continual internal audits\". Never \"in progress\", \"planned\" or \"X ready\"."
  echo "If we HAVE earned a certificate, this gate is wrong and the report should be linked."
  exit 1
fi
exit 0