BOLT ECOSYSTEM ARCHITECTURE AND SECURITY REPORT

This report provides a formal technical overview of the entire Bolt ecosystem: the premium runtime and server control plane, the BGit secure repository workflow, and the bolt-hash free edition. It documents architecture, runtime topology, dependency stack, cryptographic design, trust boundaries, and operational security controls for engineering and security stakeholders.

Baseline: 2026-04 Scope: Product + Runtime + Security Audience: Engineering, Security, Operations Classification: Internal Technical Report
Product Surfaces
6
Premium CLI, Free CLI, BGit, API server, dashboard, website
Primary Trust Zones
4
Client host, edge API, data/storage, external integrations
Runtime Layers
5
CLI process, HTTP API, background jobs, SQL state, artifact store
Security Domains
7
Identity, crypto, integrity, policy, network, content, audit

1) Full Project Topology

The system architecture is organized around a premium control plane and a compatible free toolchain, both centered on secure software protection and license operations.

Client Runtime Zone Premium CLI: bolt protect, verify, build-check, heartbeat, bgit Free CLI: bolt-hash fully local runtime, no server connection self-check integrity via user bootstrap key BGit Command Surface native command: bgit compatibility: bolt git Client Security Envelope - response signature verification (Ed25519) - anti-replay timestamp freshness window - startup self-integrity validation - secure ZIP extraction path checks - explicit fail-closed quota behavior Server Control Plane (bolt-hash-server) Express API + Middleware Pipeline authentication, RBAC checks, plan policy, request governance License and Verification Service signed responses, build-check, build-done device and run enforcement BGit Service Layer branching, push, rollback, webhook secret scan and signed metadata Build and Packaging Service safe extract, package hardening, artifact flow runtime-ready deliverables Admin and Billing Surface plans, payments, settings, usage insights support and operational controls Server Security Envelope - strong JWT secret policy guard at startup - mandatory signing key checks for critical responses - SSRF and DNS-rebinding rejection for webhooks - fail-closed auth behavior during dependency failures - secret detection using regex and entropy heuristics Data and Integration Zone MySQL Data Domain users, plans, projects, keys, activations payments, audits, BGit metadata Artifact and Storage Domain build outputs, repository snapshots, quotas retention and rollback artifacts External Integrations payment channels, mail transport, webhooks controlled egress and bounded connectivity Compliance and Traceability signed protocol exchanges policy-enforced mutations incident-ready auditability

2) Runtime and Execution Model

The runtime model combines local CLI execution with a policy-driven remote control plane. The matrix below captures each runtime domain and its responsibilities.

Runtime Domain Execution Context Primary Responsibilities Security Controls
Application Runtime Targets Node.js apps and modern JS/TS build outputs protect distributable artifacts generated from TypeScript, Next.js, React, Vue, Angular, and similar stacks artifact-level integrity and policy checks applied after build output is produced
Build and Bundling Ecosystem CI/local build pipelines ingest artifacts produced by Webpack, Vite, Rollup, esbuild, Next.js build, Nuxt build, and other bundlers secure extract and packaging controls before release distribution
Premium CLI Runtime (bolt) User workstation / build host project protection, server verification, BGit workflows, package operations self-integrity validation, signed-response verification, anti-replay checks
Free CLI Runtime (bolt-hash) User workstation (offline-capable) local obfuscation and hashing only; no connectivity to bolt-hash-server self-check integrity using the same user key used during initial hash bootstrap
API Runtime (Node.js + Express) Server process auth, plans, projects, licenses, build controls, billing, dashboard APIs JWT guard, route policy checks, signed critical responses, fail-closed logic
Background Job Runtime Server-side async tasks migrations, plan reseeding, notifications, operational maintenance least-privilege DB operations, auditable state changes
Persistence Runtime MySQL and storage domain durable state for users, plans, licenses, usage telemetry, BGit metadata schema governance, migration discipline, controlled data access patterns

3) Dependency and Library Profile

This section documents the major runtime libraries used by the platform and the role each library plays in the security and operational model.

Component Representative Libraries Purpose Operational Notes
HTTP/API Layer Express.js, middleware stack route orchestration, auth gates, admin and public endpoints critical responses are signed; auth and plan checks are policy-driven
Database Access mysql2/promise typed query execution, migration scripts, transactional operations migration compatibility requires version-aware SQL patterns
Authentication and Identity jsonwebtoken, bcryptjs JWT issuance/validation, password hashing and verification startup guard enforces strong JWT secret requirements
Cryptography Node.js crypto (native) Ed25519 signatures, SHA-256 hashing, key handling signature verification is required before trusting sensitive payloads
Packaging and Artifacts @yao-pkg/pkg, ZIP processing utilities cross-platform binaries, artifact processing, secure extraction flow build settings avoid public source leakage in packaged binaries
CLI and Integration custom CLI modules, BGit service modules user command surface, protected workflow orchestration canonical command: bolt; git feature brand: BGit (bgit)

4) Cryptographic and Integrity Mechanisms

The platform applies cryptography for authenticity, integrity, anti-replay safety, and tamper evidence across both server and client surfaces.

Mechanism Diagram

Server Payload Assembly include body + _ts timestamp Ed25519 Signature _sig generated from canonical payload Client Verification public key verification required Freshness Validation reject stale/future replay windows SHA-256 Integrity Hash critical file set digest computation Runtime Selfcheck tamper detection before command flow Trust Decision accept only verified + fresh + policy-valid data otherwise hard fail or explicit deny path

Mechanism Reference

  • Ed25519 is used for response authenticity and metadata trust guarantees.
  • SHA-256 integrity hashing protects critical local runtime files against tampering.
  • Timestamp-based freshness checks reduce replay attack viability.
  • Missing signatures are treated as invalid trust states, not as permissive defaults.
  • Security controls favor explicit deny behavior during integrity uncertainty.
Cryptographic design principle: authenticity must be provable before policy evaluation and state mutation.

5) Security Guarantees for End Users

This section is written for product users. It explains the protections you receive in normal usage, not internal admin-only implementation details.

What You Get How It Protects You Attack Type Reduced Current Status
Trusted account/session handling Strong secret policy is enforced to prevent weak authentication states. token forgery, privilege abuse Enforced
Authentic server responses Critical responses are cryptographically signed and verified before trust. forged response injection, tampered payloads Enforced
Reliable plan and quota enforcement Verification failures do not silently pass; secure deny behavior is applied. quota bypass via degraded checks Enforced
Webhook destination safety Unsafe destinations are blocked through URL and DNS safety validation. SSRF, DNS rebinding to private networks Enforced
Stable authorization behavior Temporary dependency failures default to secure deny, not accidental allow. unauthorized feature access during outages Enforced
Secret leak prevention Repository content is scanned for high-risk keys/tokens and suspicious entropy. credential leakage in artifacts and commits Enforced
✓
Ed25519 signed responses
Critical server payloads are signed and verified before the client accepts them.
✓
SHA-256 integrity model
Integrity hashing protects critical runtime files and detects tampering.
✓
Anti-replay timestamp checks
Stale or future responses are rejected using signed freshness windows.
✓
Fail-closed entitlement logic
When trust cannot be validated, access/build actions are denied safely.
✓
Secure ZIP extraction
Path traversal protection prevents writes outside intended directories.
✓
Webhook SSRF defense
Private and local network destinations are blocked via URL and DNS checks.
✓
Secret detection stack
Regex plus entropy checks reduce accidental exposure of sensitive credentials.
✓
Node.js secure runtime stack
Express + mysql2 + JWT + bcrypt + native crypto are used with security guardrails.

6) User and Client Security Model

Client-side controls are implemented to ensure trusted execution starts locally before relying on network-delivered decisions.

Startup Integrity

The premium CLI validates local integrity before entering command execution, reducing the chance of patched runtime behavior.

Signed Trust Model

Server responses must carry verifiable signatures and valid timestamps; unverifiable data is rejected, not degraded.

Secure Pull Path

ZIP extraction paths are normalized and bounded to destination directories to prevent traversal-based writes.

Command Surface Governance

The primary command alias is bolt. Legacy aliases are retired to reduce support ambiguity and policy drift.

BGit Naming Policy

The git-protection feature set is branded BGit with bgit call style, while bolt git remains backward compatible.

Failure Semantics

Security-relevant uncertainty defaults to deny or explicit error states rather than permissive continuation.

Secret Storage Boundaries

Premium CLI reads values from process environment and local config state. The local config file is permission-restricted, but its content is plaintext and should be treated as sensitive.

For high-sensitivity environments, use runtime secret injection (vault or CI secret store) and a dedicated runtime config layer instead of distributing plaintext .env files.

7) bolt-hash Free Edition (Project-Wide Context)

The free edition remains an important project pillar. It is a fully local toolchain for independent developers and does not connect to the premium server control plane.

Role in the Portfolio

  • Provides a no-cost entry path for source protection and integrity-focused workflows.
  • Supports fully local and offline-first usage patterns for small teams and individual developers.
  • Can optionally act as a gateway into premium capabilities when advanced governance is later required.
  • Maintains compatibility with the broader Bolt product narrative while preserving separate value.

Security and Operational Characteristics

  • Minimal network attack surface because no server communication is required.
  • Strong local protection value through obfuscation and integrity self-check workflows.
  • Integrity self-check uses the user bootstrap key created from the initial hash process.
  • Lower operational complexity for users who do not require enterprise policy features.
  • Clear migration path to premium runtime only when server-driven enforcement is needed.

8) Risk-Control Traceability

This matrix maps concrete threat scenarios to implemented controls and residual risk posture.

Threat Scenario Control Strategy Expected Platform Behavior Residual Risk
Forged server control payload mandatory Ed25519 verification and rejection of missing signatures client denies untrusted payload and stops trust propagation Low
Replay of previous valid response freshness window enforcement using signed timestamp constraints stale/future payload rejected before policy execution Low
Entitlement bypass via degraded dependency path fail-closed premium quota checks and deny on verification failure build path denied until trusted verification is restored Low
Webhook SSRF and DNS rebinding multi-stage URL validation plus DNS and private-range blocking unsafe destinations rejected at request admission stage Low
Repository secret leakage content scanning with signature patterns and entropy analysis sensitive content surfaced for prevention workflows Medium-Low
Client binary tampering runtime selfcheck and integrity validation over critical files runtime exit or deny path on integrity mismatch Medium-Low

9) User-Introduced Risks That Can Reduce Security

Even with strong platform controls, insecure project settings can materially reduce protection. The table below highlights common pitfalls and practical corrective actions.

User Mistake Why It Is Risky Typical Impact Recommended Action
Shipping source maps in production bundles Source maps can expose readable source structure and internal logic. reverse engineering acceleration, easier bypass attempts disable production source maps or host them privately behind strict access controls
Publishing development/debug builds Debug artifacts often retain symbols, verbose metadata, and relaxed checks. expanded attack surface and easier runtime tampering publish only hardened release builds and enforce release-mode CI gates
Committing secrets to repository or CI logs Leaked keys can be reused to impersonate services or sign malicious payloads. account takeover, unauthorized API usage, signing abuse move secrets to secure vault/env stores, rotate leaked keys immediately
Shipping plaintext .env or local config with distributed artifacts Environment files and local config payloads are not encrypted by default and may expose credentials if copied to client systems. credential disclosure, signing secret reuse, unauthorized infrastructure access never package secret-bearing .env files; inject secrets at runtime and keep local config files out of distributable outputs
Using weak or reused credentials Credential reuse and weak secrets increase brute-force and credential-stuffing success. unauthorized dashboard/API access use unique strong credentials, enable MFA where available, rotate periodically
Disabling integrity/self-check in production paths Integrity bypass removes tamper evidence and weakens trust in runtime behavior. silent binary/script modification risk keep integrity checks enabled in production and restrict bypass to controlled dev workflows
Unsafe webhook destinations Improper endpoint configuration can create SSRF-like exposure in integration flows. internal network probing or data exfiltration paths allowlist trusted public endpoints and review webhook targets during security checks
Overly permissive CI artifacts and logs Artifact leakage may include build internals, tokens, and sensitive metadata. supply-chain and information disclosure risk minimize retained artifacts, redact logs, and apply retention/lifecycle policies

10) Governance and Operations

A structured operating model is required to keep architecture consistency and security posture stable as features evolve.

Engineering Governance

  • Every feature change should map to trust boundaries, data paths, and rollback behavior.
  • Migration scripts must be version-compatible with production database variants.
  • Security tests should remain tied to each control objective, not only route coverage.
  • Alias and command-surface changes must include explicit compatibility policy.

Incident Readiness

  • Preserve auditability for license, build, and BGit mutation paths.
  • Use documented key rotation procedures for signing and integrity workflows.
  • Track anomalies in signature failures, replay rejections, and entitlement denials.
  • Maintain escalation flow across engineering, operations, and customer support teams.
Document Type: Consolidated Architecture and Security Report | Coverage: Premium Runtime, Server Plane, and bolt-hash Free Edition