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

advancedcapability

package
v0.54.13 Latest Latest
Warning

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

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

README

advancedcapability

Generated wire contract for stackkit.advanced-capability/v1 (short-lived, secret-free capability authorizing one StackKits Advanced operation) and stackkit.advanced-trust-bundle/v1 (Owner-imported trust bundle verified offline).

Generation

contract.json is the only hand-edited source (constants, limits, the operation identifiers, field patterns, document field model in RFC 8785 (JCS) member order, fixture inputs). mise run contracts:advancedcapability:generate writes:

  • advancedcapability_gen.go: constants, Operations/IsOperation, Capability, BackupRenewal, TransferRetirement, TrustBundle, TrustBundleKey, JCS encoders, constant/pattern checks;
  • schema.json: JSON Schema 2020-12 projection;
  • testdata/*.json: signed conformance capabilities and trust bundles from fixed public test seeds, via an encoder independent of the Go one;
  • manifest.json: generator version, wire version, source and output SHA-256.

contracts:advancedcapability:verify (in check and ci:fast) regenerates in memory and fails on any difference. wire.go holds the hand-written rules: strict exact-bytes decoding, time and lifetime rules, logical-reference rules, signing digest SHA-256(schemaVersion || 0x00 || unsigned JCS), signature checks. The existing conformance capabilities are byte-identical to the Techstack (internal/advancedissuer/testdata) and StackKits (internal/advancedcapability/testdata) vectors.

Issuer pin

Advanced Mode is Techstack-only. A capability's issuerId and every trust-bundle key's issuerId must be techstack or techstack.<suffix> (IssuerClass, IsTechstackIssuerID); ValidateClaims, DecodeCapability, TrustBundle.Validate and DecodeTrustBundle enforce it, so a bundle naming another issuer is rejected before its digest can be approved. The verifier also keeps the Owner-approved bundle digest, issuer/key binding, trusted time and local stack, Owner and operation scope.

Ownership

In-memory validation and encoding only. Techstack owns key custody, issuance and trust-binding records; StackKits owns trust import, Owner approval, trusted time, scope admission and CLI reason codes. Both consume this package.

Held application transfer retirement

application-transfer.retire requires exactly one transferRetirement scope and a lifetime of at most 15 minutes. It cannot share a capability with another operation or a backup renewal. The scope binds the original snapshot operation, transfer ID, signed peer outcome digest, source or destination role, and exact baseline and candidate StackSpec hashes. A consumer reconstructs all fields from its authenticated local journal and canonical removal candidate before committing under the existing snapshot lease. The grant permits no runtime activation, restart, volume deletion or provider operation. Older consumers reject the new operation; existing conformance bytes remain unchanged.

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
	// TransferRetirementMaxLifetimeSeconds bounds a capability for one held
	// transfer retirement (15 minutes).
	TransferRetirementMaxLifetimeSeconds = 900
)
View Source 
const (
	OperationApplicationTransferRetire = "application-transfer.retire"
	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"`
	// TransferRetirement binds a short-lived retirement to the exact existing
	// held snapshot, signed peer outcome and canonical desired-intent
	// transition.
	TransferRetirement *TransferRetirement `json:"transferRetirement,omitempty"`
	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 and transfer retirement shapes. 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 TransferRetirement 

type TransferRetirement struct {
	BaselineSpecHash  string `json:"baselineSpecHash"`
	CandidateSpecHash string `json:"candidateSpecHash"`
	OperationID       string `json:"operationId"`
	OutcomeDigest     string `json:"outcomeDigest"`
	Role              string `json:"role"`
	TransferID        string `json:"transferId"`
}

TransferRetirement authorizes only selected intent retirement within its original held snapshot after the signed peer outcome is verified. It grants no runtime activation, source restart, data deletion, server or provider authority. The consumer must reconstruct and compare every field from its authenticated journal and canonical candidate.

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.