trustbeat

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 30, 2026 License: MIT Imports: 16 Imported by: 0

README

TrustBeat Go SDK

Qualified electronic timestamps and Merkle anchoring — eIDAS-compliant, over a simple API.

Install

go get github.com/TrustBeat/sdk-go

Quickstart

package main

import (
    "context"
    "fmt"
    "log"

    trustbeat "github.com/TrustBeat/sdk-go"
)

func main() {
    client, err := trustbeat.NewClient("tb_live_...")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Anchor a file (SHA-256 computed locally, file never leaves your machine).
    // AnchorFileWait blocks until the proof is ready (next batch, up to 11 min).
    proof, err := client.AnchorFileWait(ctx, "contract.pdf", nil, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(proof.ID)          // tracking ID
    fmt.Println(proof.AnchoredAt)  // RFC 3339 timestamp
    fmt.Println(proof.MerkleRoot)  // Merkle root of the batch

    // Verify locally — no network call
    valid, err := client.Verify(proof)

    // Or anchor a raw SHA-256 hash without blocking, then wait for the proof.
    job, err := client.Anchor(ctx, "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", nil)
    proof, err = client.AnchorWait(ctx, job.ID, nil)  // polls up to 11 min

    _ = valid
}

Requirements

  • Go 1.21+
  • Zero runtime dependencies (net/http, encoding/json, crypto/sha256 from stdlib)

Documentation

Full API reference and guides at api.trustbeat.eu/docs

License

MIT — see LICENSE

Documentation

Overview

Package trustbeat is the official Go SDK for the TrustBeat Digital Trust API.

Zero runtime dependencies — uses net/http, encoding/json, crypto/sha256 from the stdlib. All types and functions are safe for concurrent use. 

client, err := trustbeat.NewClient("tb_live_...")
if err != nil { log.Fatal(err) }

job, err := client.Anchor(ctx, "abc...64hex", nil)
proof, err := client.AnchorWait(ctx, job.ID, nil)
valid, err := client.Verify(proof)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HashBytes 

func HashBytes(data []byte) string

HashBytes computes the SHA-256 hash of a byte slice, returned as a lowercase hex string.

func HashFile 

func HashFile(path string) (string, error)

HashFile computes the SHA-256 hash of a local file, returned as a lowercase hex string. The file is read in 64 KB chunks and is never uploaded.

func HashString 

func HashString(s string) string

HashString computes the SHA-256 hash of a UTF-8 string, returned as a lowercase hex string.

func Verify 

func Verify(proof *AnchorProof) (bool, error)

Verify verifies a Merkle inclusion proof locally — no network call.

Types

type AiDecisionJob 

type AiDecisionJob struct {
	ID           string
	InputHash    string
	OutputHash   string
	CombinedHash string // SHA-256(input_bytes ‖ output_bytes ‖ UTF-8(JCS(metadata)))
	Status       string // "pending"
	SubmittedAt  string // ISO 8601
	Overage      bool
}

AiDecisionJob is returned immediately (HTTP 202) when an AI decision is enqueued. Use GetAiDecisionProof or AnchorAiDecisionWait to retrieve the proof.

type AiDecisionMetadata 

type AiDecisionMetadata struct {
	ModelID        string // model identifier, e.g. "claude-3-5-sonnet-20241022"
	SystemName     string // AI system name, e.g. "cv-screening-v2"
	RiskCategory   string // AI Act Annex III category, e.g. "employment"
	DecisionType   string // "classification", "ranking", "recommendation", etc.
	HumanOversight bool   // true if human oversight (AI Act Article 14) was in place
	TimeEnvelope   AiTimeEnvelope
	ModelVersion   string // optional — additional version string
	OperatorID     string // optional — identifier of the operator/process
	DeploymentEnv  string // optional — "production", "staging", "testing"
	// Art. 12 traceability fields — optional, recommended for full compliance
	ExternalRef         string // optional — operator's own case/record ID
	DecisionOutcome     string // optional — semantic result, e.g. "rejected"
	ModelArtifactHash   string // optional — SHA-256 of deployed model weights
	DataSubjectCategory string // optional — e.g. "job_applicant"
}

AiDecisionMetadata describes an AI decision for EU AI Act Article 12 anchoring. ModelID, SystemName, RiskCategory, DecisionType, HumanOversight, and TimeEnvelope are required.

type AiDecisionProof 

type AiDecisionProof struct {
	ID                 string
	InputHash          string
	OutputHash         string
	CombinedHash       string
	Metadata           AiDecisionMetadata
	VerificationStatus string // "VERIFIED" | "FAILED"
	AnchoredAt         string // ISO 8601; empty if not yet available
	Proof              *AnchorProof
}

AiDecisionProof is the verification result returned once the AI decision has been anchored. VerificationStatus is "VERIFIED" when the Merkle proof is valid and the combined hash matches.

type AiTimeEnvelope 

type AiTimeEnvelope struct {
	StartedAt   string // ISO 8601 — when inference started
	CompletedAt string // ISO 8601 — when inference completed
}

AiTimeEnvelope holds the start and end times of a single AI inference call.

type AnchorJob 

type AnchorJob struct {
	ID            string
	Hash          string
	HashAlgorithm string
	Status        string // "pending" at creation
	SubmittedAt   string // ISO 8601
	Overage       bool   // true when the monthly quota was already exceeded
}

AnchorJob is returned immediately (HTTP 202) when a hash is enqueued for anchoring. Use GetProof or AnchorWait to retrieve the proof once the batch has been committed.

type AnchorOptions 

type AnchorOptions struct {
	ClientRef   string // your own reference ID, echoed back in proof responses
	Description string // human-readable label for the anchored content
	CallbackURL string // webhook URL called when anchoring completes (optional)
}

AnchorOptions holds optional metadata for anchor and timestamp requests.

type AnchorProof 

type AnchorProof struct {
	ID            string
	Hash          string // SHA-256 hex digest of the anchored content
	HashAlgorithm string
	BatchID       string
	LeafIndex     int
	MerkleRoot    string      // hex
	ProofPath     []ProofStep // Merkle path from leaf to root
	Token         []byte      // raw DER-encoded RFC 3161 TimeStampToken
	TokenFormat   string
	TSASerial     string
	Provider      string
	AnchoredAt    string // ISO 8601
	ClientRef     string // empty if not set
	Description   string // empty if not set
}

AnchorProof is the full Merkle inclusion proof returned once the batch has been anchored. Token contains the raw DER-encoded RFC 3161 qualified timestamp token. Save it as a .tsr file to verify with standard TSA tools (e.g., openssl ts -verify).

type AuditEvent 

type AuditEvent struct {
	EventID       string
	TrailCategory string
	Actor         string
	Action        string
	Ts            string // ISO 8601 — when the event occurred
	ReceivedAt    string // ISO 8601 — when TrustBeat received it
	Anchored      bool
	System        string
	Resource      string
}

AuditEvent is a single audit event as returned by ListAuditEvents.

type AuditEventProof 

type AuditEventProof struct {
	EventID       string
	CanonicalHash string
	BatchID       string
	LeafIndex     int
	MerklePath    []AuditProofStep
	AnchoredAt    string // ISO 8601
}

AuditEventProof is the full Merkle inclusion proof for an anchored audit event.

type AuditExportJob 

type AuditExportJob struct {
	JobID      string
	Status     string // "pending" | "processing" | "ready" | "failed"
	EventCount int
	Error      string
}

AuditExportJob is returned immediately (202) when ExportAuditEvents is called. Poll until Status is "ready" or "failed".

type AuditProofStep 

type AuditProofStep struct {
	Sibling string // hex-encoded SHA-256 hash of the sibling node
	Side    string // "left" or "right"
}

AuditProofStep is one step in an audit event Merkle inclusion proof.

type AuthError 

type AuthError struct{ TrustBeatError }

AuthError is returned for HTTP 401 (invalid or missing API key).

type BatchStatus 

type BatchStatus struct {
	SubmissionID string
	Total        int
	Anchored     int
	Pending      int
}

BatchStatus is returned by GetBatchStatus.

type BatchSubmission 

type BatchSubmission struct {
	SubmissionID string
	Items        []*AnchorJob
}

BatchSubmission is returned by AnchorBatch. The SubmissionID groups all items so their status and proofs can be retrieved together.

type CertificateValidationResult 

type CertificateValidationResult struct {
	Subject          string
	Issuer           string
	Serial           string
	NotBefore        string
	NotAfter         string
	Qualified        bool
	OnEutl           bool
	Qscd             bool
	RevocationStatus string
	RevocationTime   string
	KeyUsage         []string
	Valid            bool
	ValidatedAt      string // ISO 8601
}

CertificateValidationResult is returned by ValidateCertificate.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the TrustBeat API client. Create with NewClient. Safe for concurrent use; share one instance per application.

func NewClient 

func NewClient(apiKey string, opts ...Option) (*Client, error)

NewClient creates a TrustBeat API client. apiKey must be a non-empty "tb_live_..." or "tb_test_..." key.

func (*Client) Anchor 

func (c *Client) Anchor(ctx context.Context, sha256Hex string, opts *AnchorOptions) (*AnchorJob, error)

Anchor submits a SHA-256 hash for Merkle batch anchoring. Returns immediately with a tracking ID (HTTP 202 Accepted). Use GetProof or AnchorWait to retrieve the inclusion proof.

func (*Client) AnchorAiDecision 

func (c *Client) AnchorAiDecision(ctx context.Context, inputHash, outputHash string, meta *AiDecisionMetadata, opts *AnchorOptions) (*AiDecisionJob, error)

AnchorAiDecision submits an AI decision for EU AI Act Article 12 anchoring. Privacy-safe: only hashes are sent — raw inputs and outputs are never uploaded. Returns immediately with a tracking ID. Use GetAiDecisionProof or AnchorAiDecisionWait to retrieve the proof once anchored (~10 minutes).

func (*Client) AnchorAiDecisionWait 

func (c *Client) AnchorAiDecisionWait(ctx context.Context, trackingID string, opts *WaitOptions) (*AiDecisionProof, error)

AnchorAiDecisionWait polls GetAiDecisionProof until the proof is ready, then returns it. opts may be nil (defaults: 11-minute timeout, 15-second poll interval).

func (*Client) AnchorBatch 

func (c *Client) AnchorBatch(ctx context.Context, hashes []string, opts *AnchorOptions) (*BatchSubmission, error)

AnchorBatch submits up to 100 SHA-256 hashes in a single request. Returns a *BatchSubmission grouping all items under a single SubmissionID. Returns nil (no error) for an empty input slice.

func (*Client) AnchorBatchWait 

func (c *Client) AnchorBatchWait(ctx context.Context, submission *BatchSubmission, opts *WaitOptions) ([]*AnchorProof, error)

AnchorBatchWait polls GetBatchStatus until all items are anchored, then returns all proofs. opts may be nil (defaults: 15-minute timeout, 15-second poll interval).

func (*Client) AnchorFile 

func (c *Client) AnchorFile(ctx context.Context, path string, opts *AnchorOptions) (*AnchorJob, error)

AnchorFile hashes a local file with SHA-256 and submits it for anchoring. The file is never uploaded — only the 64-character hex digest is sent. Description defaults to the filename if not set in opts.

func (*Client) AnchorFileWait 

func (c *Client) AnchorFileWait(ctx context.Context, path string, opts *AnchorOptions, waitOpts *WaitOptions) (*AnchorProof, error)

AnchorFileWait hashes a local file, submits for anchoring, and waits for the proof. Convenience wrapper around AnchorFile + AnchorWait.

func (*Client) AnchorWait 

func (c *Client) AnchorWait(ctx context.Context, trackingID string, opts *WaitOptions) (*AnchorProof, error)

AnchorWait polls GetProof until the inclusion proof is ready, then returns it. opts may be nil (defaults: 11-minute timeout, 15-second poll interval). Respects ctx cancellation.

func (*Client) ExportAuditEvents 

func (c *Client) ExportAuditEvents(ctx context.Context, opts map[string]string) ([]byte, error)

ExportAuditEvents exports audit events as a court-admissible ZIP package and returns the raw ZIP bytes. Blocks until the export job completes.

opts may contain "trail_category", "from", and/or "to" (ISO 8601 strings).

func (*Client) GetAiDecisionProof 

func (c *Client) GetAiDecisionProof(ctx context.Context, trackingID string) (*AiDecisionProof, error)

GetAiDecisionProof retrieves the verification result for a previously submitted AI decision. Returns (nil, nil) if the decision is still pending (not yet anchored). Returns a *NotFoundError if the tracking ID is unknown.

func (*Client) GetAuditEventProof 

func (c *Client) GetAuditEventProof(ctx context.Context, eventID string) (*AuditEventProof, error)

GetAuditEventProof fetches the Merkle inclusion proof for an anchored audit event. Returns nil, nil if the event is not yet anchored (still pending the next batch cycle).

func (*Client) GetBatchProofs 

func (c *Client) GetBatchProofs(ctx context.Context, submissionID string) ([]*AnchorProof, error)

GetBatchProofs returns all anchored inclusion proofs for a batch submission.

func (*Client) GetBatchStatus 

func (c *Client) GetBatchStatus(ctx context.Context, submissionID string) (*BatchStatus, error)

GetBatchStatus returns anchored/pending counts for a batch submission.

func (*Client) GetProof 

func (c *Client) GetProof(ctx context.Context, trackingID string) (*AnchorProof, error)

GetProof retrieves the inclusion proof for a previously submitted hash. Returns (nil, nil) if the hash is still pending (not yet included in a batch). Returns (*NotFoundError, ...) if the tracking ID is unknown.

func (*Client) GetVerification 

func (c *Client) GetVerification(ctx context.Context, trackingID string) (*VerificationReport, error)

GetVerification retrieves a saved verification report by tracking ID.

func (*Client) ListAuditEvents 

func (c *Client) ListAuditEvents(ctx context.Context, params url.Values) ([]AuditEvent, error)

ListAuditEvents queries audit events with optional URL query parameters. Pass nil or empty params map to list all events on page 1.

func (*Client) SubmitAuditEvent 

func (c *Client) SubmitAuditEvent(ctx context.Context, trailCategory, actor, action, ts string, opts map[string]any) (string, error)

SubmitAuditEvent submits a single audit event for tamper-evident Merkle anchoring. Returns the eventID immediately (202 Accepted).

func (*Client) ValidateCertificate 

func (c *Client) ValidateCertificate(ctx context.Context, certBytes []byte) (*CertificateValidationResult, error)

ValidateCertificate validates a standalone X.509 certificate (DER or PEM) against the EU Trusted List — checks chain, revocation, qualified status, and QSCD flag.

func (*Client) Verify 

func (c *Client) Verify(proof *AnchorProof) (bool, error)

Verify verifies a Merkle inclusion proof locally — no network call. Delegates to the package-level Verify function.

func (*Client) VerifyAndAnchor 

func (c *Client) VerifyAndAnchor(ctx context.Context, document []byte, format string) (*VerificationJob, error)

VerifyAndAnchor verifies eIDAS signatures and anchors the verification event. Returns immediately (202) with a tracking ID. Use GetVerification to retrieve the completed report once anchoring completes (~10 min).

func (*Client) VerifySignature 

func (c *Client) VerifySignature(ctx context.Context, document []byte, format string) (*VerificationReport, error)

VerifySignature validates eIDAS electronic signatures on a document. format must be "pades", "cades", or "xades". The document bytes are base64-encoded before transmission and never stored.

type NotFoundError 

type NotFoundError struct{ TrustBeatError }

NotFoundError is returned for HTTP 404.

type Option 

type Option func(*Client)

Option is a functional option for NewClient.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL. Default: https://api.trustbeat.eu/v1

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the underlying *http.Client. Useful for testing or custom transport configuration.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP request timeout. Default: 30 seconds.

type ProofStep 

type ProofStep struct {
	// Sibling is the hex-encoded SHA-256 hash of the sibling node.
	Sibling string
	// Side is the position of the sibling: "left" or "right".
	Side string
}

ProofStep is one step in a Merkle inclusion proof path.

type QuotaError 

type QuotaError struct{ TrustBeatError }

QuotaError is returned for HTTP 402 or QUOTA_EXCEEDED.

type RateLimitError 

type RateLimitError struct{ TrustBeatError }

RateLimitError is returned for HTTP 429.

type SignatureDetail 

type SignatureDetail struct {
	Index            int
	SignerName       string
	SignerEmail      string
	SigningTime      string
	CertSerial       string
	CertFingerprint  string
	CertIssuer       string
	Qualified        bool
	OnEutl           bool
	Qscd             bool
	RevocationStatus string // "GOOD" | "REVOKED"
	RevocationTime   string
	OcspResponse     string
	SignatureLevel   string // e.g. "B-LT", "B-LTA"
	TimestampPresent bool
	TimestampSerial  string
	Verdict          string // SignatureVerdict value
}

SignatureDetail holds the per-signature result within a VerificationReport.

type TrustBeatError 

type TrustBeatError struct {
	Message   string
	Status    int
	RequestID string
	ErrorCode string // API error code from the response body, e.g. "NOT_FOUND", "NOT_ANCHORED"
}

TrustBeatError is the base error type for all SDK errors.

func (TrustBeatError) Error 

func (e TrustBeatError) Error() string

type VerificationError 

type VerificationError struct{ TrustBeatError }

VerificationError is returned when local Merkle proof verification fails.

type VerificationJob 

type VerificationJob struct {
	TrackingID   string
	DocumentHash string
	Status       string // "pending"
	SubmittedAt  string // ISO 8601
}

VerificationJob is returned immediately (HTTP 202) when VerifyAndAnchor is called.

type VerificationReport 

type VerificationReport struct {
	Verdict      string
	Signatures   []SignatureDetail
	DocumentHash string // SHA-256 hex of the submitted document
	CheckedAt    string // ISO 8601
	EutlVersion  string
	TrackingID   string
}

VerificationReport is the full eIDAS signature verification report returned by VerifySignature. TrackingID is set after the report is saved; use with GetVerification.

type WaitOptions 

type WaitOptions struct {
	Timeout      time.Duration // maximum time to wait; default 11 minutes
	PollInterval time.Duration // interval between polls; default 15 seconds
}

WaitOptions controls polling behaviour for AnchorWait and AnchorFileWait.

Source Files

View all Source files

Directories

Path Synopsis
cmd
smoke command
Command smoke drives the TrustBeat Go SDK against a LIVE API.
 Command smoke drives the TrustBeat Go SDK against a LIVE API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.