usage

package
v0.0.18 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package usage implements a signed hash chain for usage journals.

Every event extends a SHA-256 hash chain that starts from an init hash over (domain, fingerprint, epoch). A Report carries a run of events, the hash before and after them, and an Ed25519 signature of the installation key.

This package provides pure data types, chain logic, signing and verification. The API methods (ReportUsage, Usage) live on *licensing.Machine in the parent licensing package, which can access the client's transport.

Journal (installation side):

ack := usage.Acked{} // zero = fresh
j := usage.NewJournal("komeet-usage/v1", key.Fingerprint(), epoch, ack)
seq, hash, err := j.Append([]byte("event-data"))
report, pending, err := j.AckPending("1.0.0")
report.Sign(key.PrivateKey())
// ... send report to server, then j.Ack(ack) ...

Server side verification:

pub, _ := installation.PublicKeyOf(machine)
acked, err := report.Verify(pub, lastAcked)

Index

Constants

View Source
const FormatV1 = 1

FormatV1 is the current report format version.

View Source
const MaxReportEvents = 10000

MaxReportEvents is the most events one report carries: a longer tail is reported in consecutive reports, each continuing the previous ack.

Variables

View Source
var (
	// ErrInvalidSignature reports a report whose Ed25519 signature does
	// not verify.
	ErrInvalidSignature = errors.New("report signature is invalid")

	// ErrGap reports a report with seq_from > last_acked_seq + 1.
	ErrGap = errors.New("report has a gap: sequences are not consecutive from the last acked point")

	// ErrFork reports a report whose prev_hash does not match the last
	// acked hash at the same epoch.
	ErrFork = errors.New("report forks from the accepted chain")

	// ErrChainBroken reports prev_hash does not match the computed
	// hash of the acked state (non-zero epoch).
	ErrChainBroken = errors.New("report prev_hash does not match the last accepted hash")

	// ErrFormat reports an unknown or unsupported report format version.
	ErrFormat = errors.New("unsupported report format")

	// ErrTooLarge reports a report of more than MaxReportEvents events.
	ErrTooLarge = errors.New("report carries more than MaxReportEvents events")
)

Typed sentinels matched with errors.Is.

Functions

func DecodeEvents

func DecodeEvents(r *Report) ([][]byte, error)

DecodeEvents returns the decoded event bytes from the report.

Types

type Acked

type Acked struct {
	Epoch uint64 `json:"epoch"`
	Seq   uint64 `json:"seq"`
	Hash  string `json:"hash"`
}

Acked is the verifier's last accepted chain state, and the wire shape of the server's ack in a report-usage response.

func (Acked) IsZero

func (a Acked) IsZero() bool

IsZero reports whether the acked state is the zero value (no events accepted yet).

type Event

type Event struct {
	Seq  uint64
	Data []byte
	Hash string
}

Event is a single event from a report.

type IdempotencyKey

type IdempotencyKey struct {
	Fingerprint string
	Epoch       uint64
	SeqTo       uint64
	Head        string
}

IdempotencyKey is the natural deduplication key for a report.

func (IdempotencyKey) String

func (k IdempotencyKey) String() string

String returns a compact representation of the idempotency key.

type Journal

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

Journal maintains an in-memory usage hash chain for the installation side. It appends events and produces reports. Persistence is the product's responsibility.

func NewJournal

func NewJournal(domain, fingerprint string, epoch uint64, acked Acked) *Journal

NewJournal initializes a journal for the given domain, fingerprint and epoch. acked is the last state the server acknowledged (zero for a fresh journal).

func (*Journal) Ack

func (j *Journal) Ack(acked Acked)

Ack records that the server accepted through the given acked state.

func (*Journal) AckPending

func (j *Journal) AckPending(build string) (*Report, bool, error)

AckPending returns a report covering unacknowledged events (the next MaxReportEvents of them). pending is false, and the report nil, when all events have been acked.

func (*Journal) Append

func (j *Journal) Append(event []byte) (uint64, string, error)

Append adds an event to the chain and returns its sequence number and hash. An event larger than the wire format's length prefix is refused without changing the chain.

func (*Journal) Epoch

func (j *Journal) Epoch() uint64

Epoch returns the journal's epoch.

func (*Journal) Head

func (j *Journal) Head() (uint64, string)

Head returns the current chain head (seq, hash).

func (*Journal) Report

func (j *Journal) Report(build string) (*Report, error)

Report builds a report covering events from acked+1 through the current head, at most MaxReportEvents of them: the rest goes in the next report, after this one's ack.

type Report

type Report struct {
	// Format is the report format version (currently 1).
	Format int `json:"format"`

	// Domain identifies the product and report type, e.g. "komeet-usage/v1".
	Domain string `json:"domain"`

	// Fingerprint is the installation's hex fingerprint.
	Fingerprint string `json:"fingerprint"`

	// Epoch is the chain epoch (uint64).
	Epoch uint64 `json:"epoch"`

	// SeqFrom is the first sequence number in this report.
	SeqFrom uint64 `json:"seqFrom"`

	// SeqTo is the last sequence number in this report.
	SeqTo uint64 `json:"seqTo"`

	// PrevHash is the hex SHA-256 hash before seqFrom, or the init hash.
	PrevHash string `json:"prevHash"`

	// Events is the base64 (standard) of the canonical event encoding.
	Events string `json:"events"`

	// Head is the hex SHA-256 hash after seqTo.
	Head string `json:"head"`

	// Counters are informative per-kind counts set by the product.
	Counters map[string]int64 `json:"counters,omitempty"`

	// Build is the installation's build version.
	Build string `json:"build,omitempty"`

	// Signature is the Ed25519 signature (standard base64).
	Signature string `json:"signature"`
}

Report is a signed usage report in JSON wire format.

func (*Report) IdempotencyKey

func (r *Report) IdempotencyKey() IdempotencyKey

IdempotencyKey returns the natural deduplication key of the report: (fingerprint, epoch, seq_to, head).

func (*Report) IterEvents

func (r *Report) IterEvents() ([]Event, error)

IterEvents returns a slice of (seq, event, hash) for each event in the report. The hashes are computed from the report's prevHash.

func (*Report) Sign

func (r *Report) Sign(priv ed25519.PrivateKey)

Sign signs the report with priv and sets r.Signature.

func (*Report) SigningPayload

func (r *Report) SigningPayload() []byte

SigningPayload returns the bytes the report signature covers:

"backplane-usage-sig/v1" || domain || fingerprint || epoch_be64 ||
seqFrom_be64 || seqTo_be64 || prevHash || head

func (*Report) Verify

func (r *Report) Verify(pub ed25519.PublicKey, acked Acked) (Acked, error)

Verify checks the report's signature against pub and its chain integrity against acked. A zero acked means verify from genesis.

Returns the new accepted state on success.

type ReportBuilder

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

ReportBuilder constructs a Report step by step.

func NewReport

func NewReport(domain, fingerprint string) *ReportBuilder

NewReport starts a report builder for the given domain and fingerprint.

func (*ReportBuilder) Build

func (b *ReportBuilder) Build() (*Report, error)

Build returns the assembled Report (unsigned), or the error recorded by a builder step.

func (*ReportBuilder) Commits

func (b *ReportBuilder) Commits(seqFrom, seqTo uint64, events [][]byte) *ReportBuilder

Commits sets the sequence range and the embedded events (raw bytes). An event too large for the wire format is remembered and reported by Build.

func (*ReportBuilder) Counters

func (b *ReportBuilder) Counters(counters map[string]int64) *ReportBuilder

Counters sets the informative counters.

func (*ReportBuilder) Epoch

func (b *ReportBuilder) Epoch(epoch uint64) *ReportBuilder

Epoch sets the epoch.

func (*ReportBuilder) Head

func (b *ReportBuilder) Head(head string) *ReportBuilder

Head sets the hash after the last event.

func (*ReportBuilder) PrevHash

func (b *ReportBuilder) PrevHash(prevHash string) *ReportBuilder

PrevHash sets the hash before the first event in this report.

func (*ReportBuilder) SetBuild

func (b *ReportBuilder) SetBuild(build string) *ReportBuilder

SetBuild sets the build version string.

type Response

type Response struct {
	Epoch  uint64          `json:"epoch"`
	Events []ResponseEvent `json:"events"`
	Head   ResponseHead    `json:"head"`
	Acks   []Acked         `json:"acks"`
}

Response is the server's response to a Usage call.

type ResponseEvent

type ResponseEvent struct {
	Seq   uint64 `json:"seq"`
	Event string `json:"event"`
	Hash  string `json:"hash"`
}

ResponseEvent is a single event in a usage response.

type ResponseHead

type ResponseHead struct {
	Seq  uint64 `json:"seq"`
	Hash string `json:"hash"`
}

ResponseHead is the chain head in a usage response.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL