SourceSeal

Architecture

SourceSeal uses a layered architecture with a CLI client, REST API server, Hyperledger Fabric blockchain, and a storage layer for attestation metadata and SBOMs.

System Overview

SourceSeal CLI
  • sign
  • verify
  • audit
  • sbom generate
  • keys
API Server
  • Auth middleware
  • Rate limiting
  • CORS
  • REST handlers
Hyperledger Fabric
  • Orderer
  • Peer (CouchDB)
  • Certificate Authority
  • Chaincode
Storage Layer
  • PostgreSQL (attestations)
  • MinIO / S3 (SBOMs)

Components

CLI

The command-line tool that developers use to sign artifacts, verify packages, audit attestation history, generate SBOMs, and manage signing keys. It communicates with the API server over HTTP/HTTPS.

API Server

A Go HTTP server that exposes a RESTful API for submitting and querying attestations. Includes middleware for authentication (API keys), rate limiting (per-IP), CORS configuration, and structured JSON logging. Supports in-memory and PostgreSQL backends for attestations, and in-memory or S3-compatible storage for SBOMs.

Hyperledger Fabric Network

A permissioned blockchain network providing the immutable ledger. The sourceseal-cc chaincode validates and stores attestation records. The server uses the Fabric Gateway SDK for ledger operations (submit and query transactions).

Storage Layer

PostgreSQL stores attestation metadata for fast querying. MinIO (or any S3-compatible service) stores SBOM documents. In development mode, both default to in-memory stores.

Data Flow: Sign Operation

  1. 1CLI computes the SHA-256 hash of the artifact file.
  2. 2CLI signs the attestation payload with the Ed25519 private key.
  3. 3CLI sends the attestation + public key + optional SBOM to the API server via POST.
  4. 4API server verifies the Ed25519 signature against the provided public key.
  5. 5API server stores the SBOM in S3/MinIO (if provided).
  6. 6API server submits a transaction to the Fabric ledger via the chaincode.
  7. 7API server saves the attestation metadata to PostgreSQL and returns the attestation ID + transaction ID.

Data Flow: Verify Operation

  1. 1CLI computes the SHA-256 hash of the artifact file.
  2. 2CLI sends the hash to the API server via GET /api/v1/verify/{hash}.
  3. 3API server looks up the attestation in PostgreSQL by artifact hash.
  4. 4API server queries the Fabric ledger to confirm the attestation exists on-chain.
  5. 5API server returns the verification result with attestation details and transaction ID.

On-Chain vs. Off-Chain Data

On-Chain (Fabric Ledger)

  • Attestation hash
  • Signer key ID
  • Signature
  • Package ecosystem and name
  • Timestamp
  • Transaction ID

Immutable. Cannot be altered once committed to the ledger.

Off-Chain (PostgreSQL + S3)

  • Full attestation metadata (for fast querying)
  • SBOM documents (CycloneDX/SPDX)
  • Public keys
  • Query indexes

Queryable and cacheable. Integrity can be verified against the ledger.