Documentation
¶
Overview ¶
Package head defines the contents to be used in envelope headers.
Index ¶
- Constants
- Variables
- func WithHead(header *Header) schema.Option
- type CorrectionOptions
- type Header
- func (h *Header) AddLink(l *Link)
- func (h *Header) AddStamp(s *Stamp)
- func (h *Header) Contains(h2 *Header) booldeprecated
- func (h *Header) GetStamp(provider cbc.Key) *Stamp
- func (h *Header) Link(category, key cbc.Key) *Link
- func (h *Header) RulesContext() rules.WithContext
- func (h *Header) Sign(key *dsig.PrivateKey, opts ...SignOption) (*dsig.Signature, error)
- func (h *Header) Stamp(provider cbc.Key) *Stamp
- func (h *Header) Verify(sig *dsig.Signature, keys ...*dsig.PublicKey) error
- type Link
- type SignOption
- type SigningPayload
- type Stamp
- type StampsHasRule
Constants ¶
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.
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 ¶
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") )
var DetectDuplicateLinks = is.FuncError("no duplicate links", detectDuplicateLinks)
DetectDuplicateLinks checks if the list of links contains duplicate category and key pairs.
var DetectDuplicateStamps = is.FuncError("no duplicate stamps", detectDuplicateStamps)
DetectDuplicateStamps checks if the list of stamps contains duplicate provider keys.
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 ¶
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 ¶
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 (*Header) AddLink ¶ added in v0.111.0
AddLink will add the link to the header, or update a link with the same category and key.
func (*Header) AddStamp ¶
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 (*Header) GetStamp ¶ added in v0.75.0
GetStamp provides the stamp for the given provider or nil. Deprecated: use Stamp instead.
func (*Header) Link ¶ added in v0.111.0
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) Verify ¶ added in v0.500.0
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 ¶ added in v0.111.0
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 ¶ added in v0.111.0
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
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 ¶
AddStamp makes it easier to add a new Stamp by replacing a previous entry with a matching Key.
func NormalizeStamps ¶ added in v0.67.10
NormalizeStamps will try to clean the stamps by removing rows with empty providers or values. If empty, the function will return nil.
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.