head

package
v0.502.2 Latest Latest
Warning

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

Go to latest
Published: Jul 6, 2026 License: Apache-2.0 Imports: 12 Imported by: 6

Documentation

Overview

Package head defines the contents to be used in envelope headers.

Index

Constants

View Source
const (
	// ScopeRegistered asserts that the signer has confirmed the
	// subject controls the named GOBL Net address (e.g. via a
	// challenge-response over the address's published key). No
	// identity check beyond ownership of the FQDN.
	ScopeRegistered cbc.Key = "registered"
	// ScopeVerified asserts that the signer has performed full
	// identity verification of the subject (e.g. KYC) in addition
	// to the address ownership check.
	ScopeVerified cbc.Key = "verified"
)

Known scope values that an Authority can assert when countersigning a /who response (or any envelope it endorses). Operators MAY define additional scope keys; these are the baseline values the protocol recognises.

View Source
const (
	LinkCategoryKeyFormat       cbc.Key = "format"
	LinkCategoryKeyPortal       cbc.Key = "portal"
	LinkCategoryKeyRequest      cbc.Key = "request"
	LinkCategoryKeyResponse     cbc.Key = "response"
	LinkCategoryKeyAgreement    cbc.Key = "agreement"
	LinkCategoryKeyVerification cbc.Key = "verification"
	LinkCategoryKeyAttachment   cbc.Key = "attachment"
)

Link category keys defined for use inside link categories.

Variables

View Source
var (
	// ErrSignaturePayload is returned when a signature's payload cannot be parsed.
	ErrSignaturePayload = errors.New("head: invalid signature payload")
	// ErrSignatureMismatch is returned when a signature's payload does not match the header.
	ErrSignatureMismatch = errors.New("head: signature payload mismatch")
	// ErrSignatureKeyMismatch is returned when no provided key matches the signature.
	ErrSignatureKeyMismatch = errors.New("head: no key match found")
)
View Source
var DetectDuplicateLinks = is.FuncError("no duplicate links", detectDuplicateLinks)

DetectDuplicateLinks checks if the list of links contains duplicate category and key pairs.

View Source
var DetectDuplicateStamps = is.FuncError("no duplicate stamps", detectDuplicateStamps)

DetectDuplicateStamps checks if the list of stamps contains duplicate provider keys.

View Source
var LinkCategoryDefs = []*cbc.Definition{
	{
		Key:  LinkCategoryKeyFormat,
		Name: i18n.NewString("Format"),
		Desc: i18n.NewString(here.Doc(`
			Alternative formats of the same document, such as PDF, HTML, or XML.
		`)),
	},
	{
		Key:  LinkCategoryKeyPortal,
		Name: i18n.NewString("Portal"),
		Desc: i18n.NewString(here.Doc(`
			Websites that provide access to alternative versions of this document or request
			modifications. May also allow access to other or previous business documents.
		`)),
	},
	{
		Key:  LinkCategoryKeyRequest,
		Name: i18n.NewString("Request"),
		Desc: i18n.NewString(here.Doc(`
			Documents related to requests submitted to other systems.
		`)),
	},
	{
		Key:  LinkCategoryKeyResponse,
		Name: i18n.NewString("Response"),
		Desc: i18n.NewString(here.Doc(`
			Response documents sent from third party systems often in reply to requests.
		`)),
	},
	{
		Key:  LinkCategoryKeyAgreement,
		Name: i18n.NewString("Agreement"),
		Desc: i18n.NewString(here.Doc(`
			Contracts or agreements related to this document.
		`)),
	},
	{
		Key:  LinkCategoryKeyVerification,
		Name: i18n.NewString("Verification"),
		Desc: i18n.NewString(here.Doc(`
			Evidence or verification documents that can be used to validate the authenticity
			of this document.
		`)),
	},
	{
		Key:  LinkCategoryKeyAttachment,
		Name: i18n.NewString("Attachment"),
		Desc: i18n.NewString(here.Doc(`
			General attachments for related information such as spread sheets, letters,
			presentations, specifications, etc.
		`)),
	},
}

LinkCategoryDefs provides the definitions for link categories.

Functions

func WithHead

func WithHead(header *Header) schema.Option

WithHead ensures the original envelope's header is included in the set of correction options. If the head.CorrectionOptions is not defined in the options, this will be ignored.

Types

type CorrectionOptions

type CorrectionOptions struct {
	Head *Header `json:"-"` // copy of the original document header
}

CorrectionOptions is used to define base correction options that can be shared between documents.

type Header struct {
	// Unique UUIDv1 identifier for the envelope.
	UUID uuid.UUID `json:"uuid" jsonschema:"title=UUID"`

	// Digest of the canonical JSON body.
	Digest *dsig.Digest `json:"dig" jsonschema:"title=Digest"`

	// Seals of approval from other organisations that can only be added to
	// non-draft envelopes.
	Stamps []*Stamp `json:"stamps,omitempty" jsonschema:"title=Stamps"`

	// Links provide URLs to other resources that are related to this envelope
	// and unlike stamps can be added even in the draft state.
	Links []*Link `json:"links,omitempty" jsonschema:"title=Links"`

	// Set of labels that describe but have no influence on the data.
	Tags []string `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Additional semi-structured information about this envelope.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`

	// Any information that may be relevant to other humans about this envelope
	Notes string `json:"notes,omitempty" jsonschema:"title=Notes"`

	// From is the URI-form transport address of the envelope's issuer,
	// e.g. "gobl:samlown.example.com" or
	// "iso6523-actorid-upis::9920:b123123123".
	From cbc.URI `json:"from,omitempty" jsonschema:"title=From"`

	// To is the URI-form transport address of the envelope's intended
	// receiver.
	To cbc.URI `json:"to,omitempty" jsonschema:"title=To"`

	// Ignore lists fully-qualified validation fault codes to suppress when
	// validating this envelope, e.g. "GOBL-EU-EN16931-ORG-ITEM-01". Intended
	// for format-conversion cases where a specific, known fault is acceptable.
	// Covered by the envelope signature when sealed. NOTE: any code may be
	// listed, including structural envelope/header codes — use deliberately.
	Ignore []rules.Code `json:"ignore,omitempty" jsonschema:"title=Ignore"`
}

Header defines the metadata of the body. The header is used as the payload for the JSON Web Signatures, so we want this to be as compact as possible.

func NewHeader

func NewHeader() *Header

NewHeader creates a new header and automatically assigns a UUIDv1.

func (h *Header) AddLink(l *Link)

AddLink will add the link to the header, or update a link with the same category and key.

func (*Header) AddStamp

func (h *Header) AddStamp(s *Stamp)

AddStamp adds a new stamp to the header. If the stamp already exists, it will be overwritten.

func (*Header) Contains deprecated added in v0.66.1

func (h *Header) Contains(h2 *Header) bool

Contains compares the provided header to ensure that all the fields and properties are contained within the base header. Only a subset of the most important fields are compared.

Deprecated: Use Verify with a signature instead.

func (*Header) GetStamp added in v0.75.0

func (h *Header) GetStamp(provider cbc.Key) *Stamp

GetStamp provides the stamp for the given provider or nil. Deprecated: use Stamp instead.

func (h *Header) Link(category, key cbc.Key) *Link

Link provides the link with the matching category and key in the header, or nil.

func (*Header) RulesContext added in v0.500.0

func (h *Header) RulesContext() rules.WithContext

RulesContext injects this header's Ignore codes into the validation context so that matching faults are dropped from the result.

func (*Header) Sign added in v0.500.0

func (h *Header) Sign(key *dsig.PrivateKey, opts ...SignOption) (*dsig.Signature, error)

Sign creates a JWS signature over the header's document identity (UUID + Digest) together with the current UTC time as a JWT-standard `iat` claim (Unix seconds), and any optional claims configured via options: the signer's GOBL Net identity (head.WithIssuer), the audience it is bound to (head.WithAudience), and a scope assertion (head.WithScope). Generic JWT verifiers resolve the public keys by fetching `<iss>/.well-known/jwks.json` from the HTTPS iss URL — no `jku` header is needed.

func (*Header) Stamp added in v0.111.0

func (h *Header) Stamp(provider cbc.Key) *Stamp

Stamp provides the stamp for the given provider or nil.

func (*Header) Verify added in v0.500.0

func (h *Header) Verify(sig *dsig.Signature, keys ...*dsig.PublicKey) error

Verify checks that the signature covers this header's document identity (UUID + Digest). If public keys are provided, the signature must also be cryptographically valid against at least one of them, and when that key declares a validity window the signed `ts` MUST fall within it. The signed iss/aud are part of the statement and are not validated here — read them with SignedPayload.

type Link struct {
	uuid.Identify
	// Category helps classify the link according to a fixed list. This is optional
	// but highly recommended as it helps receivers better understand the purpose
	// of the link and potentially how it should be presented.
	Category cbc.Key `json:"category,omitempty" jsonschema:"title=Category"`
	// Key is a unique identifier for the link within the header and category
	// if provided.
	Key cbc.Key `json:"key"`
	// Code used to identify the contents of the link.
	Code cbc.Code `json:"code,omitempty" jsonschema:"title=Code"`
	// Title of the resource to use when presenting to users.
	Title string `json:"title,omitempty" jsonschema:"title=Title"`
	// Description of the resource to use when presenting to users.
	Description string `json:"description,omitempty" jsonschema:"title=Description"`
	// Expected MIME type of the link's content when the content is a file. Can only
	// be one of the allowed types defined by EN 16931-1:2017 plus XML itself.
	MIME string `json:"mime,omitempty" jsonschema:"title=MIME Type,format=mime"`
	// Digest is used to verify the integrity of the destination document
	// when downloaded from the URL.
	Digest *dsig.Digest `json:"digest,omitempty" jsonschema:"title=Digest"`
	// URL of the resource.
	URL string `json:"url" jsonschema:"title=URL,format=uri"`
	// Meta contains additional metadata about the link.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Metadata"`
}

Link defines a link between this document and another resource. Much like stamps, links must be defined with a specific key, but do allow for additional data that can help with presentation. It is important that a link once generated cannot be updated, so this is not suitable for dynamic or potentially insecure URLs.

Links have a specific advantage over stamps in that they are also allowed while the envelope has not yet been signed.

func AppendLink(list []*Link, l *Link) []*Link

AppendLink will add the link to the provided list and return the new updated list. If the link already exists, it will be updated.

func LinkByCategoryAndKey added in v0.306.0

func LinkByCategoryAndKey(list []*Link, category cbc.Key, key cbc.Key) *Link

LinkByCategoryAndKey finds the link with the given category and key from the provided list. Category may be empty.

func (Link) JSONSchemaExtend added in v0.306.0

func (Link) JSONSchemaExtend(js *jsonschema.Schema)

JSONSchemaExtend implements the jsonschema.Extender interface for Link and adds extra category details to the schema.

type SignOption added in v0.500.0

type SignOption func(*signOptions)

SignOption configures a call to Header.Sign / Envelope.Sign.

func WithAudience added in v0.500.0

func WithAudience(aud cbc.URI) SignOption

WithAudience sets the GOBL Net audience the signature is bound to as the `aud` claim of the signed payload.

func WithIssuer added in v0.500.0

func WithIssuer(iss cbc.URI) SignOption

WithIssuer sets the signer's verifiable GOBL Net address (a gobl: URI) as the `iss` claim of the signed payload. Generic JWT verifiers resolve the public keys by fetching `<iss>/.well-known/jwks.json` from the HTTPS iss URL.

func WithScope added in v0.500.0

func WithScope(scope cbc.Key) SignOption

WithScope sets the signer's confidence-level assertion in the signed payload, e.g. head.ScopeRegistered or head.ScopeVerified. Default (no option) leaves Scope empty — the signer makes no assertion beyond the cryptographic facts the signature already proves.

func WithSignerOption added in v0.500.0

func WithSignerOption(opts ...dsig.SignerOption) SignOption

WithSignerOption forwards a low-level dsig.SignerOption (e.g. dsig.WithJKU) through to the underlying JWS signer.

type SigningPayload added in v0.500.0

type SigningPayload struct {
	UUID     uuid.UUID    `json:"uuid"`
	Digest   *dsig.Digest `json:"dig"`
	Iss      cbc.URI      `json:"iss,omitempty"`
	Aud      cbc.URI      `json:"aud,omitempty"`
	IssuedAt int64        `json:"iat,omitempty"`
	Scope    cbc.Key      `json:"scope,omitempty"`
}

SigningPayload defines the fields locked by a signature. UUID and Digest identify the document; Iss and Aud are the verifiable origin and audience of *this* signature (as `gobl:` URIs); IssuedAt is the time the signature was produced as a JWT-standard NumericDate (Unix seconds, per RFC 7519 §2). Scope (optional, set via head.WithScope) is the signer's assertion about the level of confidence in the document — e.g. `head.ScopeRegistered` for an address-only check, `head.ScopeVerified` for a KYC-verified countersignature. Header stamps, links, tags, meta, notes and the (unsigned, intent-level) From/To fields can still be modified after signing.

func SignedPayload added in v0.500.0

func SignedPayload(sig *dsig.Signature) (*SigningPayload, error)

SignedPayload extracts the (unverified) signed payload from a signature, used to read iss before fetching the signer's keys.

type Stamp

type Stamp struct {
	// Identity of the agency used to create the stamp usually defined by each region.
	Provider cbc.Key `json:"prv" jsonschema:"title=Provider"`
	// The serialized stamp value generated for or by the external agency
	Value string `json:"val" jsonschema:"title=Value"`
}

Stamp defines an official seal of approval from a third party like a governmental agency or intermediary and should thus be included in any official envelopes.

func AddStamp

func AddStamp(in []*Stamp, s *Stamp) []*Stamp

AddStamp makes it easier to add a new Stamp by replacing a previous entry with a matching Key.

func GetStamp added in v0.75.0

func GetStamp(in []*Stamp, provider cbc.Key) *Stamp

GetStamp provides the matching stamp for the given provider.

func NormalizeStamps added in v0.67.10

func NormalizeStamps(in []*Stamp) []*Stamp

NormalizeStamps will try to clean the stamps by removing rows with empty providers or values. If empty, the function will return nil.

func (*Stamp) In

func (s *Stamp) In(ss []*Stamp) bool

In checks if the stamp is in the list of stamps.

type StampsHasRule added in v0.400.0

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

StampsHasRule is a combined rules.Test and validation.Rule that checks if a specific stamp provider is present in a list of stamps.

func StampsHas added in v0.114.0

func StampsHas(provider cbc.Key) *StampsHasRule

StampsHas provides a validation rule that checks if a list of stamps includes one for the given provider.

func (*StampsHasRule) Check added in v0.400.0

func (r *StampsHasRule) Check(value any) bool

Check returns true if the stamp with the given provider is present.

func (*StampsHasRule) String added in v0.400.0

func (r *StampsHasRule) String() string

func (*StampsHasRule) Validate added in v0.400.0

func (r *StampsHasRule) Validate(value any) error

Validate returns an error if the stamp with the given provider is absent.

Jump to

Keyboard shortcuts

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