bsv-blockchain · ty-everett · Jul 27, 2026 · Jul 27, 2026
@@ -1,93 +1,134 @@
 # Security Policy
 
-## Supported Versions
+## Supported versions
 
-| Package tier                                   | Supported      |
-| ---------------------------------------------- | -------------- |
-| Tier 0 (SDK primitives)                        | Latest release |
-| Tier 1 (Wallet, Overlay, Messaging, Broadcast) | Latest release |
-| Tier 2 (Apps, UI)                              | Latest release |
-| Tier 3 (Examples, helpers)                     | Best-effort    |
+The latest published release of every public package is supported. Older
+versions remain available but do not have a blanket backport promise. The
+current source package versions and runtime profiles are generated in
+[`docs/reference/stack-facts.md`](../docs/reference/stack-facts.md).
 
-## Reporting a Vulnerability
+Deployable services under `infra/` are supported from reviewed `main` source
+and immutable image digests produced by the infrastructure release workflow.
+An unreviewed fork, locally built image, or mutable tag is outside the supported
+release boundary.
 
-**Do not open a public GitHub issue for security vulnerabilities.**
+## Report a vulnerability privately
 
-Report via GitHub Security Advisories:  
-**[https://github.com/bsv-blockchain/ts-stack/security/advisories/new](https://github.com/bsv-blockchain/ts-stack/security/advisories/new)**
+**Do not open a public issue for a suspected vulnerability.**
 
-Or email: **security@bsvblockchain.org**
+Use a [private GitHub security advisory](https://github.com/bsv-blockchain/ts-stack/security/advisories/new)
+or email **security@bsvblockchain.org**. Include:
 
-Include:
+- affected package, service, version, source SHA, or image digest;
+- practical impact and deployment assumptions;
+- reproduction steps or a proof of concept;
+- whether exploitation is observed or believed active; and
+- a proposed fix, mitigation, or disclosure constraint if known.
 
-- Affected package(s) and version(s)
-- Description of the vulnerability and its impact
-- Steps to reproduce or proof-of-concept (can be shared privately)
-- Whether you have a proposed fix
+Do not include real private keys, production credentials, personal data, or
+other unrelated secrets. Use synthetic fixtures or arrange a private handoff.
 
-## Response SLA
+## Response targets
 
-| Step                        | Target                                                   |
-| --------------------------- | -------------------------------------------------------- |
-| Acknowledge receipt         | 3 business days                                          |
-| Initial severity assessment | 5 business days                                          |
-| Patch plan communicated     | 14 calendar days                                         |
-| Patch released (P0/P1)      | As fast as possible, typically < 30 days                 |
-| Public disclosure           | Coordinated — 90-day default window from acknowledgement |
+| Step                                  | Target                                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Acknowledge receipt                   | 3 business days                                                                                  |
+| Initial severity and scope assessment | 5 business days                                                                                  |
+| Remediation plan or next update       | 14 calendar days                                                                                 |
+| Critical/high fix                     | As fast as safely practical                                                                      |
+| Disclosure                            | Coordinated with the reporter; 90 days is the default maximum, not a reason to delay a ready fix |
 
-Security fixes bypass the standard 60-day deprecation policy and are released out of band.
-
-## Coordinated Disclosure
-
-We follow a 90-day coordinated disclosure window by default. If a vulnerability is being actively exploited, we reserve the right to release a patch immediately and publish the advisory simultaneously.
-
-Reporters who follow this process responsibly will be credited in the security advisory (unless anonymity is requested).
+Active exploitation, exposed signing material, or a compromised release
+boundary may require immediate mitigation and disclosure. Security fixes do not
+wait for the normal dependency or feature cadence.
 
 ## Scope
 
-**In scope:**
-
-- All packages in `packages/` (Tier 0 and Tier 1 packages are highest priority)
-- Conformance runners and test infrastructure
-- CI/CD workflows that handle secrets or produce signed artifacts
-
-**High-risk paths requiring extra scrutiny (see MBGA.md §7.3):**
-
-- Key generation, handling, and derivation
-- ECDSA signing, verification, and sighash computation
-- Encryption, decryption, HMAC, ECIES
-- Transaction construction, BEEF parsing, BUMP/Merkle validation
-- Script evaluation
-- Authentication and session establishment
-- Payment verification
-- Any parser of untrusted network input
-
-**Out of scope:**
-
-- Third-party dependencies (report to the upstream maintainer)
-- Issues in `Tier 3` examples that have no production impact
-- Theoretical vulnerabilities with no practical exploitation path
-
-## Security Hardening Targets
-
-This repository follows the MBGA reliability and security programme:
-
-- Tier 0 packages target RL5 (fuzz/property tests, threat model, signed artifacts, SBOM)
-- Tier 1 packages target RL4+ with security findings tracked to closure
-- Supply chain controls currently enforce frozen lockfiles, deny dependency
-  lifecycle scripts by default in CI, explicitly rebuild audited native/build
-  tools, run dependency review and high/critical audits, and enable Dependabot
-  security updates. Container builds additionally use digest-pinned bases,
-  committed locks, high/critical image gates, SPDX SBOMs, SLSA provenance,
-  immutable release tags, and keyless signatures or attestations with
-  verification before release completion. npm releases likewise pack once,
-  produce per-package and aggregate CycloneDX SBOMs, reject high/critical
-  vulnerability and license findings, attest and verify the exact tarballs,
-  retain offline evidence, publish with npm OIDC provenance, and verify registry
-  digests. Automated Open BSV license-policy enforcement covers every package.
-
-See `specs/reliability/` for per-package security status.
-See `docs/reference/container-supply-chain.md` for image release and
-verification procedures.
-See `docs/reference/npm-package-supply-chain.md` for npm release and
-verification procedures.
+In scope:
+
+- all public packages and private package workspaces under `packages/`;
+- all deployable services, images, and manifests under `infra/`;
+- authentication, payment, wallet, storage, Overlay, messaging, discovery,
+  relay, browser, mobile, and cross-origin behavior;
+- conformance runners, generators, build/release scripts, and CI workflows;
+- npm/GHCR artifacts, SBOMs, provenance, attestations, and release
+  reconciliation; and
+- exploitable first- or third-party dependency behavior in a supported
+  ts-stack artifact.
+
+Especially sensitive boundaries include keys and derivation, signatures and
+sighash, encryption/HMAC/ECIES, transactions/BEEF/BUMP/Merkle proofs, script
+evaluation, authentication sessions, payments and replay prevention, parsers
+of untrusted binary/JSON/network input, URLs/paths/origins, database access,
+resource bounds, and release credentials.
+
+Purely theoretical issues without a practical path may be deprioritized, but
+they may still be reported privately. Dependency vulnerabilities should also
+be reported upstream; they remain in scope here when the supported stack is
+exposed or needs a mitigation.
+
+## Implemented controls
+
+Pull requests and releases enforce, as applicable:
+
+- frozen committed locks, denied dependency lifecycle scripts, explicit
+  allowlisted rebuilds, dependency review, Socket analysis, and high/critical
+  audit gates;
+- warning-free lint, strict TypeScript build/typecheck, unit/integration,
+  conformance, clean-consumer, browser, mobile, CLI, and WASM package checks;
+- governed property tests and mutation targets for implementation trust
+  boundaries, with replayable seeds and scheduled long campaigns;
+- CodeQL security-extended analysis, secret scanning, OpenSSF Scorecard, and
+  Sonar semantic review;
+- runtime input validation, request/body/rate bounds, replay protection, and
+  synchronized service edge policies;
+- digest-pinned Linux/amd64 images, Trivy gates, SPDX SBOMs, SLSA provenance,
+  immutable tags, keyless signatures/attestations, and verification;
+- pack-once npm candidates, CycloneDX SBOMs, vulnerability/license scans,
+  GitHub attestations, npm OIDC provenance, and registry digest
+  reconciliation; and
+- uniform Open BSV License Version 6 checks across package and image artifacts.
+
+Coverage-guided fuzzing, remaining manual/browser/performance review, and the
+final QA hardening campaign are deliberately tracked as unfinished in
+[issue #324](https://github.com/bsv-blockchain/ts-stack/issues/324). They must
+not be described as complete until their preserved branch is finished,
+reviewed, merged, and validated.
+
+## Security review and exceptions
+
+Security-relevant changes require an explicit trust-boundary and deployed-impact
+review, tests that fail on the old behavior when practical, required analysis,
+and exact-head evidence. Maintainers may facilitate an admin merge after
+required checks and review-thread resolution; a second reviewer or
+last-pusher-independent approval is not an unconditional requirement.
+
+Do not dismiss a finding or add an override merely to make CI green. A genuine
+false positive or unavoidable temporary compatibility substitution must be
+registered in `governance/repository-health/exceptions.json` with an owner,
+rationale, evidence, review deadline, and objective removal condition. Expired
+exceptions fail CI.
+
+Public services such as Overlay, Wallet Storage, WAB, Message Box, and Wallet
+Relay may need to accept clients from previously unknown domains. Their public
+default and opt-in CORS/CSP/origin allowlists are deployment policy, not a
+replacement for authentication, authorization, signatures, topic validation,
+rate limits, or request bounds. A hosting URL or fallback origin must not
+silently become an allowlist.
+
+## Release and incident handling
+
+Never publish from a workstation. Follow the
+[npm package](../docs/reference/npm-package-supply-chain.md),
+[container](../docs/reference/container-supply-chain.md), and
+[release/operations](../docs/reference/release-operations.md) guides.
+
+For a suspected release compromise:
+
+1. stop publication and deployment promotion;
+2. preserve workflow, artifact, digest, attestation, and audit evidence;
+3. rotate affected credentials and isolate compromised systems;
+4. inventory exact package versions and image digests;
+5. deprecate and forward-fix immutable npm versions or roll deployments back to
+   a previously verified image digest; and
+6. coordinate advisory, consumer guidance, and post-incident control changes.
@@ -179,6 +179,9 @@ jobs:
         # catches cross-package nominal-type drift that isolated builds can miss.
         run: pnpm typecheck
 
+      - name: Compile documentation examples against exact package tarballs
+        run: pnpm docs:examples
+
       - name: Verify changed package artifacts
         env:
           SCOPE_FILTER: ${{ steps.scope.outputs.filter }}

@@ -83,6 +83,9 @@ jobs:
       - name: Typecheck workspace
         run: pnpm typecheck
 
+      - name: Compile documentation examples against exact package tarballs
+        run: pnpm docs:examples
+
       - name: Verify package license payloads
         run: pnpm license:pack-check
 

@@ -1,5 +1,11 @@
 # Conformance Vectors & Documentation Audit
 
+> **Archived point-in-time evidence (2026-05-14).** Findings and counts in this
+> report are not the current backlog. Use
+> `docs/reference/stack-facts.md`, `conformance/PARITY_MATRIX.json`, and
+> [tracker #324](https://github.com/bsv-blockchain/ts-stack/issues/324) for the
+> enforced current state. This report remains committed only for provenance.
+
 **Date**: 2026-05-14  
 **Purpose**: Pre-port audit for Golang, Python, and Rust SDK/wallet implementations.  
 **Auditor**: Full analysis + concrete fixes performed in this session.  

@@ -31,7 +31,7 @@ Most applications should start with `@bsv/simple` or `@bsv/sdk`. Wallet builders
 Prerequisites:
 
 - Node.js >= 24.11 for repository development (published packages support Node.js >= 22)
-- pnpm >= 9; this repo is pinned to `pnpm@10.33.2`
+- pnpm >= 10; this repo is pinned to `pnpm@10.33.2`
 
 ```sh
 pnpm install

@@ -2,7 +2,11 @@
 
 **Wave 4 Final Verification (Historical Snapshot)** | Generated: 2026-05-07
 
-> **Note**: This document reflects the corpus state at the end of Wave 4. As of 2026-05-14 the corpus has grown to **72 files / 6,625 vectors** (see `conformance/META.json` for the authoritative current count). Several legacy-format vector files were normalized and the structural runner was improved to cleanly support the special regression format. For the latest numbers and coverage, run `node conformance/runner/src/runner.js --validate-only` or consult `META.json`.
+> **Historical evidence only.** The tables below are retained to explain the
+> Wave 4 decisions and must not be used as current status. Current totals are
+> generated in `docs/reference/stack-facts.md`; file-level classifications are
+> generated in `conformance/PARITY_MATRIX.json`; current runner behavior comes
+> from `pnpm conformance` and `pnpm test:governance`.
 
 ## Full-Suite Summary
 

@@ -103,9 +103,9 @@
     ]
   },
   "stats": {
-    "total_files": 73,
-    "total_vectors": 6646,
-    "last_updated": "2026-05-19"
+    "total_files": 74,
+    "total_vectors": 6650,
+    "last_updated": "2026-07-27"
   },
   "regression_index": {
     "beef-v2-txid-panic": "go-sdk#306",

@@ -1,23 +1,25 @@
 {
   "schema_version": "1.0",
-  "generated_at": "2026-05-19",
+  "generated_at": "2026-07-27",
   "source": "ts-stack conformance corpus",
   "description": "Machine-readable parity status for cross-language SDK implementations (Go, Rust, Python). Use this to track and drive conformance.",
   "summary": {
-    "total_files": 73,
-    "total_vectors": 6646,
-    "fully_required_files": 54,
+    "total_files": 74,
+    "total_vectors": 6650,
+    "fully_required_files": 55,
     "files_with_intended": 17,
     "files_with_mixed_status": 15,
     "vectors_by_status": {
-      "required": 6442,
+      "required": 6446,
       "intended": 204,
-      "skipped": 8
+      "skipped": 7
     },
     "by_reason_category": {
-      "fully_supported": 1304,
+      "fully_supported": 1234,
+      "governed_vector_skip": 50,
       "historical_regression": 36,
       "partial_ts_behavioral_difference": 5116,
+      "intended_parity_work": 24,
       "wallet_stateful_harness_required": 190
     }
   },
@@ -91,7 +93,7 @@
       "required_count": 28,
       "intended_count": 0,
       "skipped_count": 4,
-      "reason_category": "fully_supported",
+      "reason_category": "governed_vector_skip",
       "justification": "Expected signature was generated by an earlier SDK version and does not match current RFC6979-deterministic output. Superseded by messaging.brc31.authrite-signature.5. | Signature value from old SDK version; superseded by messaging.brc31.authrite-signature.6. | Expected signature was generated by an earlier SDK version and does not match current RFC6979-deterministic output. Superseded by messaging.brc31.authrite-signature.8. | Signature value from old SDK version; superseded by messaging.brc31.authrite-signature.9.",
       "categories": []
     },
@@ -368,7 +370,7 @@
       "required_count": 22,
       "intended_count": 0,
       "skipped_count": 1,
-      "reason_category": "fully_supported",
+      "reason_category": "governed_vector_skip",
       "justification": "runner dispatchECIES decrypt-only shape does not check throws; wrong-key error is tested via sdk.crypto.ecies.16 (full form with tampered_ciphertext_hex)",
       "categories": []
     },
@@ -517,6 +519,18 @@
       "reason_category": "fully_supported",
       "categories": []
     },
+    {
+      "path": "sync/brc136-basm.json",
+      "id": "sync.brc136-basm",
+      "total_vectors": 4,
+      "file_level_parity": "required",
+      "effective_status": "required",
+      "required_count": 4,
+      "intended_count": 0,
+      "skipped_count": 0,
+      "reason_category": "fully_supported",
+      "categories": []
+    },
     {
       "path": "sync/brc40-user-state.json",
       "id": "sync.brc40",
@@ -525,9 +539,9 @@
       "effective_status": "intended",
       "required_count": 0,
       "intended_count": 24,
-      "skipped_count": 1,
-      "reason_category": "fully_supported",
-      "justification": "Runtime-state assertion; requires producer with seeded user table. Cannot be validated by shape-only dispatcher.",
+      "skipped_count": 0,
+      "reason_category": "intended_parity_work",
+      "justification": "24 vector(s) are classified as intended rather than required",
       "categories": []
     },
     {

@@ -1,5 +1,11 @@
 # Docs Code Block Audit
 
+> **Archived manual evidence.** This 312-block snapshot is not a current
+> compiler or freshness guarantee. Current documentation is gated by
+> frontmatter/link/render checks, generated fact checks, package artifact
+> consumers, and the package README contract. New executable example checks
+> must be automated rather than marked complete in this file.
+
 Generated from fenced code blocks under `docs/`. Total blocks: 312.
 
 Status key: ✅ = checked against local source/package docs/tests and patched if needed.