Supply Chain Security & Compliance

Modern front-end engineering heavily relies on external open-source component distribution chains. From day one, BrutxUI was architected with anti-tampering and transparent compliance as first-class contracts, establishing an end-to-end defense model across canonical integrity hashes, Ed25519 digital signatures, strict verification gates, CycloneDX 1.5 SBOM generation, and local audit log tracking.

---

Threat Model & Security Goals

Unlike traditional precompiled npm packages, BrutxUI distributes component source code directly into user codebases. While this provides complete styling and architectural flexibility, it raises the bar for registry source purity:

Attack Vector	Risk Description	BrutxUI Defense Mechanism
MITM / CDN Tampering	Network hijack maliciously alters component source files	Canonical SHA-256 integrity recomputation and enforcement
Unauthorized Releases	Attacker impersonates registry metadata to publish trojanized components	Asymmetric Ed25519 digital signatures with trusted public key verification
Silent Dependency Drift	Inter-component dependencies maliciously redirected	Strict locking of registry dependency graph (registryDependencies)
Compliance Blind Spots	Inability to audit underlying third-party licenses and vulnerabilities	Native export of CycloneDX 1.5 Software Bill of Materials (SBOM)
Local Code Drift	Unintended local modifications drifting away from component baseline	doctor --fail-on drift and integrity self-healing (restore-integrity)

---

Canonical Recomputation & Ed25519 Signatures

1. Canonical Content Hash Recomputation

When the CLI fetches registry-manifest.json from a remote registry, it immediately runs the first line of defense—canonical SHA-256 recomputation:

• Extracts core entity fields (name, schemaVersion, registryVersion, items), performs canonical serialization, and computes the digest;
• Matches the computed digest against the manifest's integrity field;
• Dynamic timestamps (buildTimestamp), git commit hashes (gitCommit), and signature metadata itself are excluded from the digest calculation, guaranteeing build idempotency and anti-replay resilience.
• Benefit: Even if an attacker modifies any component definition or code hash inside the manifest, the request is immediately rejected unless they can forge the entire digest.

2. Ed25519 Digital Signature Verification

The second line of defense is asymmetric cryptographic signature verification:

• The release workflow signs the manifest's canonical digest with the publisher's private key using Ed25519;
• The manifest attaches the resulting signature along with a key identifier keyId;
• The CLI resolves the trusted public key matching keyId locally and verifies that the signature was generated by the legitimate maintainer.

3. Out-of-the-Box Official Trust Anchor

For standard developers, this entire verification chain works automatically with zero configuration:

• The CLI embeds the official BrutxUI root public key;
• When fetching from the official release registry, verification occurs quietly in the background;
• Unsigned legacy manifests are skipped gracefully to ensure backward compatibility.

---

Strict Signature Mode

Default Warning Mechanism

In development environments, when encountering an unknown keyId or verification failure, the CLI emits a warning (warn) and proceeds, preventing unexpected blocks during key migrations or internal network configuration:

[Signature] Manifest signed with unknown keyId "v1". No matching trusted public key found.
  (use --require-signature to enforce)

Production & CI Strict Gate

For production deployments, automated CI/CD pipelines, or enterprise intranets, activating strict mode is strongly recommended. In strict mode, any signature failure or untrusted key throws REGISTRY_SIGNATURE_INVALID and immediately exits with code 1:

Activate strict mode via any of the following:

# Option 1: CLI flag (highest priority)
npx brutx-vue@latest --require-signature add button

# Option 2: Environment variable
export BRUTX_REQUIRE_SIGNATURE=1
npx brutx-vue@latest add button

Or declare project-level enforcement in components.json:

{
  "$schema": "https://lidaixingchen.github.io/brutxui-vue3/schema.json",
  "$version": 1,
  "style": "brutalism",
  "requireSignature": true
}

---

Private Registries & Key Management

Enterprises deploying private registries or internal mirrors can establish their own key pairs and rotation lifecycle.

Public Key Resolution Order

The CLI resolves public keys in the following priority order, always appending the official root key as a fallback anchor:

1. Project Configuration: trustedPublicKeys in components.json (highest priority, can override official keys by keyId)
2. Environment Variable: BRUTX_REGISTRY_PUBLIC_KEYS (JSON array string)
3. Built-in Root Key: Official BrutxUI public key (fallback trust anchor)

Public Key Configuration Example

Public keys must be single-line base64-encoded SPKI DER format for easy embedding in JSON or shell variables.

In components.json:

{
  "trustedPublicKeys": [
    {
      "keyId": "corp-registry-2026",
      "publicKey": "MCowBQYDK2VwAyEA9Yg1r5Q3t6e...",
      "status": "active",
      "note": "Enterprise internal registry 2026 signing key"
    }
  ]
}

In CI/CD pipelines:

export BRUTX_REGISTRY_PUBLIC_KEYS='[{"keyId":"corp-registry-2026","publicKey":"MCowBQYDK2VwAyEA9Yg1r5Q3t6e..."}]'

Smooth Key Rotation

When rotating keys due to scheduled expiration or personnel changes:

1. Signing Phase: Sign the new manifest with the new private key (e.g., keyId: "corp-2027");
2. Transition Phase: Retain both keys (corp-2026 and corp-2027) in the trusted list so both legacy and modern manifests verify cleanly;
3. Revocation Phase: Once historical dependencies are upgraded, remove the old key to permanently invalidate assets signed by the retired private key.

---

CycloneDX 1.5 Software Bill of Materials (SBOM)

A Software Bill of Materials (SBOM) is a cornerstone of modern cybersecurity compliance (SOC 2, ISO 27001, Executive Order 14028). BrutxUI adheres strictly to the OWASP CycloneDX 1.5 industry standard.

1. Project-Level SBOM Generation (doctor --sbom)

Generate a comprehensive bill of materials for all installed BrutxUI components at any time:

# Outputs to ./brutx-sbom.json by default
npx brutx-vue@latest doctor --sbom

# Specify custom output path
npx brutx-vue@latest doctor --sbom --sbom-output ./reports/brutx-sbom.json

The generated SBOM includes:

• Standard format: specVersion: "1.5", bomFormat: "CycloneDX"
• Component inventory: All installed UI components (typed as application, identified by bom-ref: "brutx:<component>")
• External dependencies: Installed npm packages and versions (typed as library, identified by bom-ref: "npm:<package>")
• Complete dependency graph: Explicit dependencies array linking components to libraries and peer components
• Content digests: Canonical SHA-256 hash for every component to enable automated baseline drift detection

2. Registry-Level SBOM (Release Asset)

During registry builds, the build engine automatically compiles registry-sbom.json. This artifact links directly to the corresponding registry-manifest.json via the manifestIntegrity field.

3. Enterprise Pipeline Integration

The resulting CycloneDX 1.5 SBOM integrates directly into enterprise vulnerability and governance platforms:

• Dependency-Track: Continuously track component vulnerabilities and CVEs;
• Snyk / Trivy: Ingest SBOMs for automated license compliance and CI security gate checks;
• GitHub Dependency Submission API: Submit installed component manifests directly to your repository's Dependency Graph and Dependabot alerts.

---

Local Audit Log

After every modifying command (add, update, remove, diff), the CLI automatically appends a JSONL audit record to .brutx/audit.log in the project root.

Audit Log Record Format

Each record captures full operational context for compliance auditing and incident forensics:

{
  "timestamp": "2026-09-12T14:30:00.000Z",
  "command": "add",
  "components": ["button", "card"],
  "registrySource": "https://github.com/lidaixingchen/brutxui-vue3/releases/latest/download",
  "success": true,
  "dryRun": false
}

Diagnostic Retrospection

Running npx brutx-vue@latest doctor automatically inspects recent failed records in .brutx/audit.log:

• If recent network timeouts, unreachable registries, or write errors occurred, doctor surfaces timestamps and error details directly in the terminal to accelerate troubleshooting.

---

Team Best Practices Checklist

To achieve the highest security posture in production:

1. Enforce strict verification: Add "requireSignature": true to components.json to reject untrusted code execution;
2. Implement drift detection in CI: Run npx brutx-vue@latest doctor --ci --fail-on drift on pull requests to prevent unreviewed manual edits;
3. Archive SBOM artifacts: Incorporate npx brutx-vue@latest doctor --sbom into release pipelines and archive the SBOM alongside build artifacts;
4. Configure Git tracking: Commit the .brutx/ metadata directory to Git, while ignoring .brutx/cache/ in .gitignore.