Help us shape the future of Go! Take the 2026 Go Developer Survey

advancedcapability

package
v0.54.4 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package advancedcapability is the generated wire contract for the short-lived, secret-free capabilities that authorize individual StackKits Advanced operations (stackkit.advanced-capability/v1) and for the Owner-imported trust bundle that verifies them offline (stackkit.advanced-trust-bundle/v1).

The canonical source is contract.json in this directory; constants, the operation vocabulary, field patterns, document types, RFC 8785 (JCS) encoders, the JSON Schema and the signed conformance fixtures are generated from it by internal/cmd/advancedcapabilitygen and bound to it by manifest.json. Techstack issues and StackKits verifies against this package.

The package validates and encodes values in memory only. Key custody, issuance records, trust import and approval, trusted time, local stack and Owner scope admission, and the reason codes a CLI reports stay with the issuer and verifier that consume it.

Index

Constants

View Source 
const (
	// SchemaVersion is the capability document version and the signing domain
	// prefix.
	SchemaVersion = "stackkit.advanced-capability/v1"
	// TrustBundleSchemaVersion is the Owner-imported trust bundle version.
	TrustBundleSchemaVersion = "stackkit.advanced-trust-bundle/v1"
	// Audience is the only accepted capability audience.
	Audience = "stackkit"
	// IssuerClass is the only issuer a verifier may trust: issuerId is either
	// exactly this value or this value followed by a dot and a per-installation
	// suffix.
	IssuerClass = "techstack"
	// BackupRenewalRepositoryID is the only repository a backup renewal can
	// name.
	BackupRenewalRepositoryID = "kopia:local:cloud"
)
View Source 
const (
	// MaxDocumentBytes bounds a capability or trust bundle document.
	MaxDocumentBytes = 65536
	// MaxLifetimeSeconds bounds expiresAt minus issuedAt (30 days).
	MaxLifetimeSeconds = 2592000
	// MaxTrustBundleKeys bounds the keys of one trust bundle.
	MaxTrustBundleKeys = 64
	// MaxLogicalReferenceBytes bounds uiManagerRef and rilRef.
	MaxLogicalReferenceBytes = 256
	// BackupRenewalMaxLifetimeSeconds bounds a capability that carries a backup
	// renewal (15 minutes).
	BackupRenewalMaxLifetimeSeconds = 900
	// BackupRenewalMaxMeasurementAgeSeconds bounds how long before issuedAt the
	// renewal usage may have been measured.
	BackupRenewalMaxMeasurementAgeSeconds = 300
)
View Source 
const (
	OperationDriftReconcileAdvanced   = "drift.reconcile.advanced"
	OperationOriginCertificateInstall = "public-tls.origin-certificate.install"
	OperationOriginCertificateRequest = "public-tls.origin-certificate.request"
	OperationRestoreDrill             = "restore.drill"
	OperationRollbackCoordinated      = "rollback.coordinated"
	OperationTerramateChangeSetApply  = "terramate.change-set.apply"
	OperationTerramateChangeSetCreate = "terramate.change-set.create"
)

Advanced operation identifiers. A capability authorizes a sorted subset.

View Source 
const BackupRenewalOperation = OperationRestoreDrill

BackupRenewalOperation is the only operation a backup renewal capability may carry.

Variables

This section is empty.

Functions

func IsOperation 

func IsOperation(value string) bool

IsOperation reports whether value is an Advanced operation identifier.

func IsTechstackIssuerID 

func IsTechstackIssuerID(issuerID string) bool

IsTechstackIssuerID reports whether issuerID names a Techstack issuer: the bare IssuerClass or IssuerClass followed by "." and a per-installation suffix. Advanced Mode is Techstack-only, so no other issuer is valid.

func KeyID 

func KeyID(publicKey ed25519.PublicKey) string

KeyID derives the key identifier bound to a raw Ed25519 public key.

func Operations 

func Operations() []string

Operations returns every Advanced operation in canonical (sorted) order.

func SigningDigest 

func SigningDigest(unsigned []byte) []byte

SigningDigest is the domain-separated digest an issuer signs and a verifier checks: SHA-256(SchemaVersion || 0x00 || unsigned canonical bytes).

Types

type BackupRenewal 

type BackupRenewal struct {
	AgentID               string `json:"agentId"`
	BindingHash           string `json:"bindingHash"`
	CustodyAttestationRef string `json:"custodyAttestationRef"`
	DeploymentID          string `json:"deploymentId"`
	FreshAttestationRef   string `json:"freshAttestationRef"`
	JobID                 string `json:"jobId"`
	MeasuredAt            string `json:"measuredAt"`
	PlanHash              string `json:"planHash"`
	QuotaBytes            string `json:"quotaBytes"`
	RepositoryID          string `json:"repositoryId"`
	TargetRef             string `json:"targetRef"`
	TenantID              string `json:"tenantId"`
	UsedBytes             string `json:"usedBytes"`
}

BackupRenewal authorizes one local staged drill against unchanged applied authority after fresh managed entitlement, usage and remote target attestation. It grants no remote snapshot or data activation authority.

func (BackupRenewal) Validate 

func (r BackupRenewal) Validate(issuedAt time.Time) error

Validate checks the backup renewal against the capability's issuedAt: the usage measurement is canonical UTC, not after issuedAt (one second of clock tolerance), and at most BackupRenewalMaxMeasurementAgeSeconds old; usage is below a positive quota.

type Capability 

type Capability struct {
	// AllowedOperations is the sorted, duplicate-free operation set.
	AllowedOperations []string `json:"allowedOperations"`
	Audience          string   `json:"audience"`
	// BackupRenewal is present only on a single short-lived restore.drill
	// capability.
	BackupRenewal *BackupRenewal `json:"backupRenewal,omitempty"`
	// CapabilityID is a lowercase UUIDv7.
	CapabilityID string `json:"capabilityId"`
	ExpiresAt    string `json:"expiresAt"`
	IssuedAt     string `json:"issuedAt"`
	// IssuerID names a Techstack issuer (see IssuerClass).
	IssuerID string `json:"issuerId"`
	// KeyID is ed25519://sha256/<hex SHA-256 of the raw public key>.
	KeyID         string `json:"keyId"`
	OwnerRef      string `json:"ownerRef"`
	RILRef        string `json:"rilRef"`
	SchemaVersion string `json:"schemaVersion"`
	// Signature is the unpadded standard-Base64 Ed25519 signature over
	// SigningDigest of the unsigned canonical bytes.
	Signature    string `json:"signature"`
	StackID      string `json:"stackId"`
	UIManagerRef string `json:"uiManagerRef"`
}

Capability is one stackkit.advanced-capability/v1 document. Its canonical bytes are RFC 8785 (JCS): members in code-point order, no whitespace, and every value validated ASCII.

func DecodeCapability 

func DecodeCapability(raw []byte) (Capability, error)

DecodeCapability strictly decodes one capability document. It accepts only exact canonical RFC 8785 bytes of a document that passes Validate, so unknown, duplicate, missing, reordered or re-encoded members are all rejected.

func (Capability) Canonical 

func (c Capability) Canonical() []byte

Canonical returns the exact RFC 8785 document bytes a verifier reads.

func (Capability) CanonicalUnsigned 

func (c Capability) CanonicalUnsigned() []byte

CanonicalUnsigned returns the RFC 8785 bytes without the signature member.

func (Capability) ExpiresAtTime 

func (c Capability) ExpiresAtTime() time.Time

func (Capability) IssuedAtTime 

func (c Capability) IssuedAtTime() time.Time

IssuedAtTime and ExpiresAtTime return the parsed validity window. They are meaningful only after ValidateClaims succeeds.

func (*Capability) Sign 

func (c *Capability) Sign(privateKey ed25519.PrivateKey)

Sign sets Signature from privateKey over SigningDigest(CanonicalUnsigned()). It does not validate claims; issuers call ValidateClaims first.

func (Capability) Validate 

func (c Capability) Validate() error

Validate checks ValidateClaims and the signature encoding.

func (Capability) ValidateClaims 

func (c Capability) ValidateClaims() error

ValidateClaims checks every time-independent wire rule of the unsigned document: constants, patterns, a Techstack issuer, a non-empty sorted operation set, logical references, exact-second UTC times, the 30-day lifetime bound, and the backup renewal shape. It does not check the signature, trusted time, or the caller's local scope.

func (Capability) VerifySignature 

func (c Capability) VerifySignature(publicKey ed25519.PublicKey) error

VerifySignature checks Signature against publicKey. Callers resolve publicKey from an Owner-pinned TrustBundle by issuerId and keyId.

type TrustBundle 

type TrustBundle struct {
	Keys          []TrustBundleKey `json:"keys"`
	SchemaVersion string           `json:"schemaVersion"`
}

TrustBundle is one stackkit.advanced-trust-bundle/v1 document. It holds public verification keys only; the Owner imports it pinned by Digest.

func DecodeTrustBundle 

func DecodeTrustBundle(raw []byte) (TrustBundle, error)

DecodeTrustBundle strictly decodes one trust bundle; only exact canonical bytes of a bundle that passes Validate are accepted.

func (TrustBundle) Canonical 

func (b TrustBundle) Canonical() []byte

Canonical returns the exact RFC 8785 trust bundle bytes.

func (TrustBundle) Digest 

func (b TrustBundle) Digest() string

Digest is the sha256:<hex> pin an Owner approves when importing the bundle.

func (TrustBundle) PublicKey 

func (b TrustBundle) PublicKey(issuerID, keyID string) (ed25519.PublicKey, bool)

PublicKey returns the trusted key for the exact issuer/key binding.

func (TrustBundle) Validate 

func (b TrustBundle) Validate() error

Validate checks the bundle version, the key count, Techstack issuers, key-id binding, and that no issuer/key binding repeats.

type TrustBundleKey 

type TrustBundleKey struct {
	IssuerID string `json:"issuerId"`
	KeyID    string `json:"keyId"`
	// PublicKey is the unpadded standard-Base64 raw 32-byte Ed25519 public key.
	PublicKey string `json:"publicKey"`
}

TrustBundleKey binds one Techstack issuer to one raw Ed25519 public key.

func NewTrustBundleKey 

func NewTrustBundleKey(issuerID string, publicKey ed25519.PublicKey) TrustBundleKey

NewTrustBundleKey binds issuerID to the raw Ed25519 publicKey.

func (TrustBundleKey) RawPublicKey 

func (k TrustBundleKey) RawPublicKey() (ed25519.PublicKey, error)

RawPublicKey decodes PublicKey after checking that KeyID is bound to it.

type ValidationError 

type ValidationError struct {
	Field  string
	Detail string
}

ValidationError reports the first wire rule a document violates. Field is the JSON member name ("document" for whole-document rules); Detail is diagnostic text and never a policy input.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Source Files

View all Source files

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.