pulsar-m: bootstrap NIST MPTC submission package

Initial commit. Holds the technical specification (LaTeX), the design
docs, the build/test/bench scripts, the package layout, and the empty
ref/go/pkg/pulsarm skeleton.

The spec at spec/pulsar-m.tex (11,300 words of LaTeX) is the canonical
description of the protocol. docs/nist-mptc-category.md states the
Class N1 + N4 claim. CONTRIBUTING.md and SECURITY.md pin the IP and
disclosure posture.

Subsequent commits land the reference implementation in stages.

Signed-off-by: Lux Industries <[email protected]>

scripts/bench.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Pulsar-M reproducible benchmarks.
+#
+# Runs the experimental-evaluation harness and writes results to
+# bench/results/. Hardware fingerprint is captured so reviewers can compare.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+export GOWORK=off
+
+OUT_DIR="bench/results"
+mkdir -p "$OUT_DIR"
+
+echo "==> hardware fingerprint"
+{
+    uname -a
+    if command -v sysctl >/dev/null 2>&1; then
+        sysctl -a 2>/dev/null | grep -E 'machdep\.cpu\.brand_string|hw\.ncpu|hw\.memsize' || true
+    fi
+    if [[ -f /proc/cpuinfo ]]; then
+        grep -E 'model name|cpu MHz' /proc/cpuinfo | head -2
+    fi
+    go version
+} > "$OUT_DIR/fingerprint.txt"
+
+echo "==> Go benchmarks"
+go test -bench=. -benchmem -count=3 -run=^$ -benchtime=2s ./ref/go/... | tee "$OUT_DIR/go-bench.txt"
+
+echo "==> done — results in $OUT_DIR/"

scripts/build.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Pulsar-M reproducible build.
+#
+# Builds the Go reference implementation and the LaTeX spec PDF. Exits
+# non-zero on any failure. Designed to be the CI gate.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Build the reference impl in module-only mode. A surrounding workspace
+# (e.g. ~/work/lux/go.work) does not own this repo's deps and must be
+# bypassed deliberately so reviewers get the same view CI gets.
+export GOWORK=off
+
+echo "==> Go reference build"
+go build ./ref/go/...
+
+echo "==> Spec PDF build (skipped if latexmk not installed)"
+if command -v latexmk >/dev/null 2>&1; then
+    ( cd spec && latexmk -pdf -interaction=nonstopmode pulsar-m.tex )
+else
+    echo "    [warn] latexmk not found — skipping. Install TeX Live for full build."
+fi
+
+echo "==> done"

scripts/gen_vectors.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Pulsar-M KAT regeneration.
+#
+# Regenerates vectors/{keygen,sign,verify,threshold-sign,dkg}.json from
+# the reference implementation. Re-running on a clean checkout MUST
+# produce byte-identical output — this is the deterministic-fixture
+# gate enforced by CI.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+mkdir -p vectors/transcripts
+
+export GOWORK=off
+
+echo "==> Reference KAT generator"
+go run ./ref/go/cmd/genkat -out vectors
+
+echo "==> Verifying KAT round-trip via replay tests"
+go test -count=1 -run "^TestKAT_" ./ref/go/pkg/pulsarm/
+
+echo "==> done"

scripts/sbom.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Pulsar-M SBOM generation.
+#
+# Produces an SPDX SBOM for the reference implementation, capturing every
+# transitive dependency. Required as part of the MPTC submission package.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+OUT="bench/results/sbom.spdx.json"
+mkdir -p "$(dirname "$OUT")"
+
+if command -v cyclonedx-gomod >/dev/null 2>&1; then
+    ( cd ref/go && cyclonedx-gomod mod -json -output "$REPO_ROOT/$OUT" )
+elif command -v go-licenses >/dev/null 2>&1; then
+    echo "    [info] cyclonedx-gomod not found; falling back to go-licenses report"
+    ( cd ref/go && go-licenses csv ./... > "$REPO_ROOT/${OUT%.json}.csv" )
+else
+    echo "    [warn] no SBOM tool found (install cyclonedx-gomod or go-licenses)"
+    exit 1
+fi
+
+echo "==> SBOM written to $OUT"

scripts/test.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Pulsar-M test suite runner.
+#
+# Runs unit tests, KAT validation (when available), and the no-secret-logs
+# linter. Designed to be the CI gate alongside scripts/build.sh.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Module-only build. See note in scripts/build.sh.
+export GOWORK=off
+
+echo "==> Go unit tests"
+go test -count=1 -race ./ref/go/...
+
+echo "==> No-secret-logs linter"
+# DD-007: secret-touching files MUST NOT use stdlib log.* / fmt.Print* /
+# panic. This list is the implementation surface that touches secrets.
+SECRET_FILES=(
+    "ref/go/pkg/pulsarm/keygen.go"
+    "ref/go/pkg/pulsarm/sign.go"
+    "ref/go/pkg/pulsarm/dkg.go"
+    "ref/go/pkg/pulsarm/threshold.go"
+    "ref/go/pkg/pulsarm/reshare.go"
+    "ref/go/pkg/pulsarm/shamir.go"
+)
+for f in "${SECRET_FILES[@]}"; do
+    if [[ -f "$f" ]]; then
+        # Allow comments mentioning these tokens, but forbid actual use:
+        # filter out lines starting with // and import-comment blocks.
+        if grep -nE '^[^/]*(\<log\.(Print|Fatal|Panic)|fmt\.(Print|Fprint)|panic\()' "$f" \
+            | grep -vE '^\s*//' ; then
+            echo "FAIL: secret-touching file $f contains forbidden logging or panic" >&2
+            exit 1
+        fi
+    fi
+done
+
+echo "==> KAT validation"
+if [[ -f vectors/keygen.json ]]; then
+    go test -count=1 -run "^TestKAT_" ./ref/go/pkg/pulsarm/
+else
+    echo "    [info] vectors/ not generated — run scripts/gen_vectors.sh"
+fi
+
+echo "==> done"