localevidence

package
v0.42.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package localevidence produces Architecture-v2 pre-Apply evidence under the local homelab owner's own signing custody.

StackKits is an Open Source homelab standard that must operate with no Kombify account, no Kombify endpoint, and no TechStack. ADR-0029 states the same requirement from the trust side: for a homelab the Authority Site is home, "Enrollment and signing happen there", and conformance gates must reject remote enrollment/signing. A collector that can only be constructed by an authenticated remote service therefore cannot be the only collector.

The applyevidence SPI was always local-capable: it carries only a CollectionRequest and canonical result bytes, and leaves "observation, enrollment, signing, endpoints, credentials, transport" private to the implementation. This package is the implementation that keeps all of that on the box, anchored to the owner established by `stackkit init --owner-source=local`.

The collector never fabricates evidence. Each expectation is answered from facts actually gathered on this host, and any requirement kind that cannot be genuinely observed fails closed rather than being signed as satisfied. A rubber-stamp collector would be strictly worse than the refusal it replaces.

Index

Constants

View Source 
const (
	TinyAuthPocketIDBindingAPIVersion = "stackkit.tinyauth-pocketid-binding/v1"

	TinyAuthPocketIDClientID = "stackkit-tinyauth"
)
View Source 
const (
	BasementRuntimeCustodyAPIVersion = "stackkit.basement-runtime-custody/v3"
)
View Source 
const (
	CloudRuntimeCustodyAPIVersion = "stackkit.cloud-runtime-custody/v1"
)
View Source 
const OriginProofPath = "/.well-known/stackkit-origin-proof"
View Source 
const (
	OwnerCustodyAPIVersion = "stackkit.local-owner-custody/v1"
)
View Source 
const (
	OwnerRuntimeBindingAPIVersion = "stackkit.owner-runtime-binding/v1"
)

Variables

View Source 
var ErrBasementOriginProvisionerMissing = errors.New("localevidence: established runtime needs the owner origin provisioner")

ErrBasementOriginProvisionerMissing preserves existing immutable runtime bundles: they need an explicit custody upgrade before workload issuance.

View Source 
var (
	ErrBasementRuntimeCustodyMissing = errors.New("localevidence: no Basement runtime custody")
)
View Source 
var (
	ErrCloudRuntimeCustodyMissing = errors.New("localevidence: no Cloud runtime custody")
)
View Source 
var ErrLANAddressUndiscoverable = siteaddress.ErrLANAddressUndiscoverable
View Source 
var ErrOwnerCustodyMissing = errors.New("localevidence: no local owner custody")
View Source 
var ErrOwnerKeyMissing = errors.New("localevidence: no local owner evidence key")

ErrOwnerKeyMissing reports that no local evidence identity has been established yet for this workspace.

View Source 
var ErrOwnerRuntimeBindingMissing = errors.New("localevidence: no local owner runtime binding")
View Source 
var ErrTinyAuthPocketIDBindingMissing = errors.New("localevidence: no TinyAuth PocketID binding")

Functions

func AdmitWorkloadPeer 

func AdmitWorkloadPeer(workspaceRoot string, admission WorkloadPeerAdmission) error

AdmitWorkloadPeer must be called by an authenticated local owner operation. The CA chain, client-only usage and exact subject are checked before approval.

func ApplyWorkloadPeerOperation 

func ApplyWorkloadPeerOperation(workspaceRoot string, operation WorkloadPeerOperation) error

ApplyWorkloadPeerOperation rejects absent, stale or body-mismatched owner approval before performing a custody mutation. Retired certificate tombstones prevent replayed admission from undoing revocation or key rotation.

func AuthorizeWorkloadPeer 

func AuthorizeWorkloadPeer(workspaceRoot string, chain []*x509.Certificate, scope WorkloadPeerScope, now time.Time) (string, error)

AuthorizeWorkloadPeer consumes certificates from a real TLS connection, not a forwarded header. The caller must obtain proof of private-key possession via TLS client authentication. No cached admission or revocation snapshot is used.

func BasementLANDNSResolverAddress 

func BasementLANDNSResolverAddress(workspaceRoot string) (string, error)

BasementLANDNSResolverAddress returns the exact address written into the owner-signed Unbound custody. Access summaries use this value so the owner does not have to discover or guess which node address to configure in DHCP.

func BasementStepCARootCAPEM 

func BasementStepCARootCAPEM(workspaceRoot string) (certificate []byte, relPath string, err error)

BasementStepCARootCAPEM loads the established step-ca root certificate PEM from Basement runtime custody for use as a trust anchor only: TLS client verification and enrollment fingerprint display. The private root key never leaves custody. It also returns the workspace-relative certificate path for user-facing client enrollment guidance.

func CompleteBasementOriginProvisionerUpgrade 

func CompleteBasementOriginProvisionerUpgrade(workspaceRoot string) error

CompleteBasementOriginProvisionerUpgrade is called only after Apply has reloaded and observed the configured step-ca provisioner. Keeping the journal until then ensures a failed or interrupted reload is retried on the next Apply.

func ComposeInterpolationEnvironment 

func ComposeInterpolationEnvironment(workspaceRoot string) ([]string, error)

ComposeInterpolationEnvironment is the process environment docker compose needs to parse generated Core compose files. Apply and restore-activate share it so stop/up never invent a second interpolation path.

func DecodeOwnerRestoreActivationSignature 

func DecodeOwnerRestoreActivationSignature(value string) ([]byte, error)

DecodeOwnerRestoreActivationSignature verifies the wire encoding without loading custody. It is used by strict contract decoders before local binding.

func DiscardBasementTinyAuthPocketIDBinding 

func DiscardBasementTinyAuthPocketIDBinding(workspaceRoot string) error

DiscardBasementTinyAuthPocketIDBinding removes the recorded TinyAuth client custody, including the private environment carrying its secret. The secret is only meaningful to the PocketID instance that issued it, so once that client is gone the custody is unusable and must be rebuilt from a fresh registration.

func DiscardOwnerRuntimeBinding 

func DiscardOwnerRuntimeBinding(workspaceRoot string) error

DiscardOwnerRuntimeBinding removes the recorded projection of the PocketID owner: the signed subject binding and the one-time enrollment that names it. Both describe rows inside PocketID's own database, so a host whose runtime data was destroyed can only be rebuilt once they are gone. Owner custody, the owner key, and step-ca stay untouched; they are workspace-resident authority that survives any host wipe and keeps the rebuilt owner the same owner.

func IsPlaceholderOwnerEmail 

func IsPlaceholderOwnerEmail(email string) bool

IsPlaceholderOwnerEmail reports the generated PocketID email that is not a real owner account. First-create local init must not persist it.

func IssueBasementOriginCertificate 

func IssueBasementOriginCertificate(ctx context.Context, workspaceRoot string, policy architecturev2renderer.BridgeOriginMTLSPublicationPolicy, csrPEM []byte) ([]byte, error)

IssueBasementOriginCertificate submits an owner-authorized CSR for the supplied origin identity policy to the existing node-local step-ca. Only the CSR's owner retains the leaf private key. Owner custody signs the one-time authorization token; step-ca alone signs the leaf. This does not enroll Cloud peers or claim an enforced mTLS publication.

func IssueWorkloadPeerCertificate 

func IssueWorkloadPeerCertificate(ctx context.Context, root, peerRef string, csrPEM []byte, ttl int) ([]byte, error)

IssueWorkloadPeerCertificate is a local Owner capability, never an HTTP signing endpoint. The caller must obtain explicit approval for the peer and scope. The existing step-ca alone signs the certificate; the caller must admit that exact certificate separately before it can access an origin.

func MaterializeLocalSecret 

func MaterializeLocalSecret(workspaceRoot, secretRef string) error

MaterializeLocalSecret creates or reuses one workspace-local, owner-signed, owner-only secret. Neither evidence nor diagnostics contain its value or ref.

func OwnerRuntimeBindingDigest 

func OwnerRuntimeBindingDigest(record OwnerRuntimeBinding) string

OwnerRuntimeBindingDigest identifies the exact signed, secret-free binding for inclusion in Apply and Verify evidence.

func OwnerUsernameFromEmail 

func OwnerUsernameFromEmail(email string) string

OwnerUsernameFromEmail turns the local part of an email into a login name suitable for PocketID and the Cloud execution-channel account.

func PersistPocketIDOwnerEnrollment 

func PersistPocketIDOwnerEnrollment(workspaceRoot string, enrollment PocketIDOwnerEnrollment) (string, error)

func PrepareWorkloadPeerEnrollment 

func PrepareWorkloadPeerEnrollment(root, peerRef string, csrPEM []byte, replaceKey bool) (string, error)

PrepareWorkloadPeerEnrollment checks explicit key replacement and permanent revoked-key denial before requesting a certificate from step-ca. The returned commitment must still match the signed admission after issuance.

func ReadBasementRuntimePocketIDAdminKey 

func ReadBasementRuntimePocketIDAdminKey(workspaceRoot string) (string, error)

ReadBasementRuntimePocketIDAdminKey returns the declarative PocketID bootstrap key only after the complete owner-signed runtime custody (Basement or Cloud) has been verified. The key is never included in a public record or diagnostic.

func ReadOriginProof 

func ReadOriginProof(ctx context.Context, root, address, serverName, nonce string) ([]byte, error)

ReadOriginProof keeps the Owner private key inside its custody package. The only request is a bounded read-only probe to an explicit loopback listener.

func ResolveLocalSecretMaterial 

func ResolveLocalSecretMaterial(workspaceRoot, secretRef string) ([]byte, error)

ResolveLocalSecretMaterial returns a defensive copy of the text-safe secret material after verifying the exact owner-signed local custody record. It is intended only for construction-owned local runtime adapters; callers must not persist it outside an owner-only runtime file or include it in evidence.

func RevokeWorkloadPeer 

func RevokeWorkloadPeer(workspaceRoot, peerRef string) error

RevokeWorkloadPeer persists an owner-signed denial. Origin authorization reads this file for every request, including requests on established TLS sessions.

func TinyAuthPocketIDCallbackURL 

func TinyAuthPocketIDCallbackURL(address IdentityRuntimeAddress) string

func UpgradeBasementOriginProvisioner 

func UpgradeBasementOriginProvisioner(workspaceRoot string) (bool, error)

UpgradeBasementOriginProvisioner is an Apply-owned custody transition. It preserves established secrets and journals both signed file generations before replacement. A true result means step-ca must still be reloaded.

func ValidWorkloadPeerRef 

func ValidWorkloadPeerRef(value string) bool

ValidWorkloadPeerRef is shared by CSR production and Home admission so an unusable identity never causes private-key custody to be created.

func VerifyBasementOriginProvisioner 

func VerifyBasementOriginProvisioner(ctx context.Context, workspaceRoot string) error

VerifyBasementOriginProvisioner proves that the running, owner-rooted step-ca has loaded the owner public signing key before Apply completes an upgrade.

func VerifyHomeHumanDeviceTrust 

func VerifyHomeHumanDeviceTrust(workspaceRoot string, canonical []byte, signature OwnerPolicyStateSignature) error

VerifyHomeHumanDeviceTrust checks the current local Owner signature over public Home verifier material.

func VerifyOriginProbeOwner 

func VerifyOriginProbeOwner(root string, chain []*x509.Certificate) error

VerifyOriginProbeOwner accepts only actual TLS possession of the currently custodied Owner certificate. It grants a read-only runtime proof, no workload access, management operation, or human passkey assertion.

func VerifyOwnerAdvancedChangeSet 

func VerifyOwnerAdvancedChangeSet(
	workspaceRoot string,
	canonicalUnsigned []byte,
	signature OwnerAdvancedChangeSetSignature,
) error

VerifyOwnerAdvancedChangeSet verifies the exact canonical Advanced change set against current local Owner custody without exposing its private key.

func VerifyOwnerAdvancedTrust 

func VerifyOwnerAdvancedTrust(
	workspaceRoot string,
	canonicalRecord []byte,
	signature OwnerAdvancedTrustSignature,
) error

VerifyOwnerAdvancedTrust verifies the record against current local Owner custody without exposing the Owner private key.

func VerifyOwnerApplyResult 

func VerifyOwnerApplyResult(workspaceRoot string, canonicalResult []byte, signature OwnerApplyResultSignature) error

VerifyOwnerApplyResult verifies the complete result against current custody.

func VerifyOwnerExecutorState 

func VerifyOwnerExecutorState(
	workspaceRoot string,
	canonicalSnapshot []byte,
	signature OwnerExecutorStateSignature,
) error

func VerifyOwnerFederationBindingAdmission 

func VerifyOwnerFederationBindingAdmission(workspaceRoot string, canonicalAdmission []byte, signature OwnerFederationBindingAdmissionSignature) error

func VerifyOwnerIdentityProjectionApproval 

func VerifyOwnerIdentityProjectionApproval(
	workspaceRoot string,
	canonicalApproval []byte,
	signature OwnerIdentityProjectionSignature,
) error

func VerifyOwnerIdentityProjectionReceipt 

func VerifyOwnerIdentityProjectionReceipt(
	workspaceRoot string,
	canonicalReceipt []byte,
	signature OwnerIdentityProjectionSignature,
) error

func VerifyOwnerLifecycleMutation 

func VerifyOwnerLifecycleMutation(
	workspaceRoot string,
	canonicalRecord []byte,
	signature OwnerLifecycleMutationSignature,
) error

func VerifyOwnerPolicyState 

func VerifyOwnerPolicyState(workspaceRoot string, canonicalState []byte, signature OwnerPolicyStateSignature) error

VerifyOwnerPolicyState verifies the signature and current owner binding.

func VerifyOwnerRestoreAbandonment 

func VerifyOwnerRestoreAbandonment(
	workspaceRoot string,
	canonicalAbandonment []byte,
	signature OwnerRestoreAbandonmentSignature,
) error

func VerifyOwnerRestoreActivation 

func VerifyOwnerRestoreActivation(
	workspaceRoot string,
	canonicalResult []byte,
	signature OwnerRestoreActivationSignature,
) error

func VerifyOwnerRestoreRecovery 

func VerifyOwnerRestoreRecovery(
	workspaceRoot string,
	canonicalRecovery []byte,
	signature OwnerRestoreRecoverySignature,
) error

func VerifyOwnerRestoreResult 

func VerifyOwnerRestoreResult(
	workspaceRoot string,
	canonicalResult []byte,
	signature OwnerRestoreResultSignature,
) error

func VerifyOwnerSnapshotAnchor 

func VerifyOwnerSnapshotAnchor(
	workspaceRoot string,
	canonicalAnchor []byte,
	signature OwnerSnapshotAnchorSignature,
) error

VerifyOwnerSnapshotAnchor verifies a canonical snapshot anchor against the current local owner custody.

func VerifyRemoteAction 

func VerifyRemoteAction(canonical []byte, signature OwnerPolicyStateSignature, ownerRef, keyID string, public ed25519.PublicKey) error

VerifyRemoteAction accepts only the public Home key admitted by the receiver's local owner. Callers must re-read that admission and its withdrawal state.

Types

type BasementRuntimeCustody 

type BasementRuntimeCustody struct {
	APIVersion    string                       `json:"apiVersion"`
	Kind          string                       `json:"kind"`
	OwnerRef      string                       `json:"ownerRef"`
	KeyID         string                       `json:"keyId"`
	Domain        string                       `json:"domain"`
	EstablishedAt time.Time                    `json:"establishedAt"`
	Files         []BasementRuntimeCustodyFile `json:"files"`
	Signature     string                       `json:"signature"`
}

BasementRuntimeCustody is a signed, secret-free index of the local service inputs derived from one established owner. The referenced files remain private below .stackkit/custody and are never returned through this API.

func EstablishBasementRuntimeCustody 

func EstablishBasementRuntimeCustody(workspaceRoot, domain string, sessionTTLSeconds int) (BasementRuntimeCustody, error)

EstablishBasementRuntimeCustody creates the service runtime bundle exactly once. A complete bundle is installed by one directory rename; a preexisting incomplete or modified bundle is rejected instead of repaired or rotated. sessionTTLSeconds selects TinyAuth session expiry; non-positive values use the Basement kit human-issuer default (900 in basement-kit/stackfile.cue home-human-credential-issuer sessionTTLSeconds). The 60..86400 range is owned by foundation/architecture_v2.cue sessionTTLSeconds; this default must stay in sync with the CUE authority.

func LoadBasementRuntimeCustody 

func LoadBasementRuntimeCustody(workspaceRoot string) (BasementRuntimeCustody, error)

LoadBasementRuntimeCustody verifies the owner signature, the closed file inventory, every digest, and the step-ca chain before returning metadata.

type BasementRuntimeCustodyFile 

type BasementRuntimeCustodyFile struct {
	Path string `json:"path"`
	MAC  string `json:"mac"`
}

type CloudRuntimeCustody 

type CloudRuntimeCustody struct {
	APIVersion      string                       `json:"apiVersion"`
	Kind            string                       `json:"kind"`
	OwnerRef        string                       `json:"ownerRef"`
	KeyID           string                       `json:"keyId"`
	Domain          string                       `json:"domain"`
	SubdomainPrefix string                       `json:"subdomainPrefix,omitempty"`
	EstablishedAt   time.Time                    `json:"establishedAt"`
	Files           []BasementRuntimeCustodyFile `json:"files"`
	Signature       string                       `json:"signature"`
}

CloudRuntimeCustody is the owner-signed, secret-free index for the provider-neutral services installed on an externally supplied Cloud host. Provider credentials and server lifecycle never enter this bundle. SubdomainPrefix is absent for an unprefixed address, so records established before it existed keep their signature.

func EstablishCloudRuntimeCustody 

func EstablishCloudRuntimeCustody(workspaceRoot string, address IdentityRuntimeAddress) (CloudRuntimeCustody, error)

EstablishCloudRuntimeCustody fixes the identity address once. PocketID binds passkeys to its origin, so a later address change is refused, not adopted.

func LoadCloudRuntimeCustody 

func LoadCloudRuntimeCustody(workspaceRoot string) (CloudRuntimeCustody, error)

func (CloudRuntimeCustody) IdentityAddress 

func (c CloudRuntimeCustody) IdentityAddress() IdentityRuntimeAddress

IdentityAddress returns the public address PocketID and TinyAuth serve.

type CollectorConfig 

type CollectorConfig struct {
	// Key is the established local owner signing identity.
	Key OwnerKey
	// Version is the running StackKits version; normalised to semver shape.
	Version string
	// Observers is keyed by applyevidence requirement kind. A kind with no
	// registered observer fails closed.
	Observers map[string]Observer
	// Now supplies the clock; defaults to time.Now.
	Now func() time.Time
}

CollectorConfig configures one workspace-scoped collector.

type DiagnosticError 

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

DiagnosticError preserves an observation failure without publishing its cause. Stages are assigned only by the construction-owned collector.

func (*DiagnosticError) Diagnostic 

func (e *DiagnosticError) Diagnostic() string

func (*DiagnosticError) Error 

func (e *DiagnosticError) Error() string

func (*DiagnosticError) Unwrap 

func (e *DiagnosticError) Unwrap() error

type HostObserver 

type HostObserver struct {
	Probe hostconformance.Probe
}

HostObserver answers `host` requirements from the StackKits host probe. It reuses internal/hostconformance rather than re-inspecting the machine, so local Apply evidence and `stackkit host conformance` describe the same host through the same code path.

func NewHostObserver 

func NewHostObserver(probe hostconformance.Probe) (*HostObserver, error)

NewHostObserver binds an observer to a host probe.

func (*HostObserver) Observe 

func (o *HostObserver) Observe(ctx context.Context, expectation applyevidence.Expectation) (map[string]string, error)

Observe implements Observer. Every returned fact is something the probe actually reported; nothing is defaulted or inferred. Apply evidence always claims "satisfied", so every contributing check must have positively passed before this observer returns facts to the signer.

type IdentityRuntimeAddress 

type IdentityRuntimeAddress struct {
	Domain          string
	SubdomainPrefix string
}

IdentityRuntimeAddress is the public address of the local PocketID and TinyAuth pair. A subdomain prefix flattens each core service host to <prefix>-<service>.<domain>, exactly as the core Compose routes serve it, so identity URLs must follow the prefix instead of the bare domain.

func LocalIdentityRuntimeAddress 

func LocalIdentityRuntimeAddress(workspaceRoot string) (IdentityRuntimeAddress, error)

LocalIdentityRuntimeAddress returns the address of the one owner-signed runtime custody that carries this workspace's PocketID and TinyAuth inputs. Basement and Cloud install the same identity pair, each from its own custody.

func (IdentityRuntimeAddress) PocketIDOrigin 

func (a IdentityRuntimeAddress) PocketIDOrigin() string

PocketIDOrigin is PocketID's public URL and therefore its OIDC issuer and passkey relying-party origin.

func (IdentityRuntimeAddress) ServiceHost 

func (a IdentityRuntimeAddress) ServiceHost(service string) string

ServiceHost returns the public host of one core service.

func (IdentityRuntimeAddress) TinyAuthOrigin 

func (a IdentityRuntimeAddress) TinyAuthOrigin() string

TinyAuthOrigin is TinyAuth's public URL.

type LocalBinding 

type LocalBinding struct {
	SiteRef    string `json:"siteRef"`
	NodeRef    string `json:"nodeRef"`
	ChannelRef string `json:"executionChannelRef"`
}

type Observer 

type Observer interface {
	Observe(ctx context.Context, expectation applyevidence.Expectation) (map[string]string, error)
}

Observer gathers the facts that justify one expectation on this host. It returns a deterministic, sorted fact set; the collector digests it into the typed observation reference. Returning an error fails the whole collection closed, which is the correct outcome for anything this host cannot prove.

type ObserverFunc 

type ObserverFunc func(context.Context, applyevidence.Expectation) (map[string]string, error)

ObserverFunc adapts a function to Observer.

func (ObserverFunc) Observe 

func (f ObserverFunc) Observe(ctx context.Context, expectation applyevidence.Expectation) (map[string]string, error)

Observe implements Observer.

type OwnerAdvancedChangeSetSignature 

type OwnerAdvancedChangeSetSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerAdvancedChangeSetSignature authenticates the exact canonical, secret-free Advanced change set with the current local Owner custody.

func SignOwnerAdvancedChangeSet 

func SignOwnerAdvancedChangeSet(
	workspaceRoot string,
	canonicalUnsigned []byte,
) (OwnerAdvancedChangeSetSignature, error)

SignOwnerAdvancedChangeSet signs one canonical Advanced change set without exposing the Owner private key.

type OwnerAdvancedTrustSignature 

type OwnerAdvancedTrustSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerAdvancedTrustSignature authenticates the exact locally accepted Advanced trust record. Its domain prevents replay as another lifecycle approval or evidence record.

func SignOwnerAdvancedTrust 

func SignOwnerAdvancedTrust(
	workspaceRoot string,
	canonicalRecord []byte,
) (OwnerAdvancedTrustSignature, error)

SignOwnerAdvancedTrust signs one canonical, secret-free Advanced trust record with the established local Owner evidence key.

type OwnerApplyResultSignature 

type OwnerApplyResultSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

func SignOwnerApplyResult 

func SignOwnerApplyResult(workspaceRoot string, canonicalResult []byte) (OwnerApplyResultSignature, error)

SignOwnerApplyResult authenticates the complete canonical runtime result, including its post-Apply observations, without exposing the private key.

type OwnerCollector 

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

OwnerCollector is the local, owner-anchored applyevidence.Collector.

func NewOwnerCollector 

func NewOwnerCollector(config CollectorConfig) (*OwnerCollector, error)

NewOwnerCollector builds a collector bound to one local owner identity.

func (*OwnerCollector) CollectApplyEvidence 

func (c *OwnerCollector) CollectApplyEvidence(ctx context.Context, collection applyevidence.CollectionRequest) (data []byte, returnErr error)

CollectApplyEvidence implements applyevidence.Collector. It answers every expectation in the request from locally gathered facts, signs each receipt with the owner key, and returns one canonical sealed bundle.

func (*OwnerCollector) ProducerTrust 

func (c *OwnerCollector) ProducerTrust() (applyevidence.Producer, []byte, error)

ProducerTrust returns the public half of this construction-owned producer. It contains no private material and is used by the product composition root to verify the exact collector it installs.

type OwnerCustody 

type OwnerCustody struct {
	APIVersion               string          `json:"apiVersion"`
	Kind                     string          `json:"kind"`
	OwnerRef                 string          `json:"ownerRef"`
	KeyID                    string          `json:"keyId"`
	Source                   string          `json:"source"`
	PocketID                 OwnerProjection `json:"pocketId"`
	Binding                  LocalBinding    `json:"localBinding"`
	Trust                    TrustProfile    `json:"trust"`
	StepCARootCertificatePEM string          `json:"stepCaRootCertificatePem"`
	OwnerCertificatePEM      string          `json:"ownerCertificatePem"`
	EstablishedAt            time.Time       `json:"establishedAt"`
	Signature                string          `json:"signature"`
}

func EstablishOwnerCustody 

func EstablishOwnerCustody(workspaceRoot string, request OwnerCustodyRequest) (OwnerCustody, error)

func LoadOwnerCustody 

func LoadOwnerCustody(workspaceRoot string) (OwnerCustody, error)

type OwnerCustodyRequest 

type OwnerCustodyRequest struct {
	Binding     LocalBinding
	Trust       TrustProfile
	Email       string
	Username    string
	DisplayName string
}

type OwnerExecutorStateSignature 

type OwnerExecutorStateSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerExecutorStateSignature authenticates one executor-native recovery closure. Its domain is intentionally distinct from backup and restore evidence so signatures cannot be replayed across lifecycle phases.

func SignOwnerExecutorState 

func SignOwnerExecutorState(
	workspaceRoot string,
	canonicalSnapshot []byte,
) (OwnerExecutorStateSignature, error)

type OwnerFederationBindingAdmissionSignature 

type OwnerFederationBindingAdmissionSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerFederationBindingAdmissionSignature authenticates one exact local adoption of an opaque external Federation-link binding. It cannot be replayed as Apply, backup, restore, lifecycle, or Advanced evidence.

func SignOwnerFederationBindingAdmission 

func SignOwnerFederationBindingAdmission(workspaceRoot string, canonicalAdmission []byte) (OwnerFederationBindingAdmissionSignature, error)

type OwnerIdentityProjectionSignature 

type OwnerIdentityProjectionSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerIdentityProjectionSignature binds a local approval or terminal receipt to current Owner custody without exporting the Owner private key.

func SignOwnerIdentityProjectionApproval 

func SignOwnerIdentityProjectionApproval(
	workspaceRoot string,
	canonicalApproval []byte,
) (OwnerIdentityProjectionSignature, error)

func SignOwnerIdentityProjectionReceipt 

func SignOwnerIdentityProjectionReceipt(
	workspaceRoot string,
	canonicalReceipt []byte,
) (OwnerIdentityProjectionSignature, error)

type OwnerKey 

type OwnerKey struct {
	OwnerRef string
	KeyID    string
	// contains filtered or unexported fields
}

OwnerKey is the local signing identity for one workspace.

func EstablishOwnerKey 

func EstablishOwnerKey(workspaceRoot, ownerRef string) (OwnerKey, error)

EstablishOwnerKey creates the local evidence identity exactly once. An existing record is returned unchanged: silently rotating custody would invalidate every receipt already anchored to the previous key.

func LoadOwnerKey 

func LoadOwnerKey(workspaceRoot string) (OwnerKey, error)

LoadOwnerKey reads the established local evidence identity for a workspace. It never creates one: establishing custody is an explicit owner action.

func (OwnerKey) Public 

func (k OwnerKey) Public() ed25519.PublicKey

Public returns the public half, which is the trust anchor a verifier pins.

type OwnerLifecycleMutationSignature 

type OwnerLifecycleMutationSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerLifecycleMutationSignature authenticates one local lifecycle mutation journal. The domain is distinct from Apply, backup, and recovery evidence.

func SignOwnerLifecycleMutation 

func SignOwnerLifecycleMutation(
	workspaceRoot string,
	canonicalRecord []byte,
) (OwnerLifecycleMutationSignature, error)

type OwnerPolicyStateSignature 

type OwnerPolicyStateSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

func SignHomeHumanDeviceTrust 

func SignHomeHumanDeviceTrust(workspaceRoot string, canonical []byte) (OwnerPolicyStateSignature, error)

SignHomeHumanDeviceTrust authenticates current Home public verifier material. It cannot mint a PocketID identity, enroll a device, or replace step-ca.

func SignOwnerPolicyState 

func SignOwnerPolicyState(workspaceRoot string, canonicalState []byte) (OwnerPolicyStateSignature, error)

SignOwnerPolicyState signs one canonical, secret-free local policy state without exposing the owner's private key outside this package.

func SignRemoteAction 

func SignRemoteAction(root string, canonical []byte) (OwnerPolicyStateSignature, error)

SignRemoteAction uses the established Home owner key with a dedicated domain. It is authorization of exact bytes, never evidence of human step-up.

type OwnerProjection 

type OwnerProjection struct {
	Subject     string `json:"subject"`
	Email       string `json:"email"`
	Username    string `json:"username"`
	DisplayName string `json:"displayName"`
	State       string `json:"state"`
}

type OwnerRestoreAbandonmentSignature 

type OwnerRestoreAbandonmentSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerRestoreAbandonmentSignature authenticates the explicit terminal release of one pending or staged restore operation. It uses a separate domain so recovery intent and restore result signatures cannot be replayed as abandonment evidence.

func SignOwnerRestoreAbandonment 

func SignOwnerRestoreAbandonment(
	workspaceRoot string,
	canonicalAbandonment []byte,
) (OwnerRestoreAbandonmentSignature, error)

type OwnerRestoreActivationSignature 

type OwnerRestoreActivationSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerRestoreActivationSignature authenticates the terminal result of moving one verified staged restore into the exact plan-owned live volumes.

func SignOwnerRestoreActivation 

func SignOwnerRestoreActivation(
	workspaceRoot string,
	canonicalResult []byte,
) (OwnerRestoreActivationSignature, error)

type OwnerRestoreRecoverySignature 

type OwnerRestoreRecoverySignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerRestoreRecoverySignature authenticates the exact local Owner approval and recovery intent persisted before any restore staging side effect.

func SignOwnerRestoreRecovery 

func SignOwnerRestoreRecovery(
	workspaceRoot string,
	canonicalRecovery []byte,
) (OwnerRestoreRecoverySignature, error)

type OwnerRestoreResultSignature 

type OwnerRestoreResultSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerRestoreResultSignature authenticates the terminal staged-restore evidence. It uses a different domain so intent and result signatures cannot be replayed across lifecycle phases.

func SignOwnerRestoreResult 

func SignOwnerRestoreResult(
	workspaceRoot string,
	canonicalResult []byte,
) (OwnerRestoreResultSignature, error)

type OwnerRuntimeBinding 

type OwnerRuntimeBinding struct {
	APIVersion                  string    `json:"apiVersion"`
	Kind                        string    `json:"kind"`
	OwnerRef                    string    `json:"ownerRef"`
	KeyID                       string    `json:"keyId"`
	PocketIDSubject             string    `json:"pocketIdSubject"`
	PocketIDUsername            string    `json:"pocketIdUsername"`
	PocketIDEmail               string    `json:"pocketIdEmail"`
	PocketIDDisplayName         string    `json:"pocketIdDisplayName"`
	PocketIDGroups              []string  `json:"pocketIdGroups"`
	OwnerCertificateSHA256      string    `json:"ownerCertificateSha256"`
	OwnerCertificateSerial      string    `json:"ownerCertificateSerial"`
	StepCARootCertificateSHA256 string    `json:"stepCaRootCertificateSha256"`
	BoundAt                     time.Time `json:"boundAt"`
	Signature                   string    `json:"signature"`
}

OwnerRuntimeBinding is a secret-free, owner-signed statement connecting PocketID's immutable user subject with the stable local ownerRef and the exact step-ca certificates established by init.

func EstablishOwnerRuntimeBinding 

func EstablishOwnerRuntimeBinding(workspaceRoot string, observation OwnerRuntimeObservation) (OwnerRuntimeBinding, error)

func LoadOwnerRuntimeBinding 

func LoadOwnerRuntimeBinding(workspaceRoot string) (OwnerRuntimeBinding, error)

type OwnerRuntimeObservation 

type OwnerRuntimeObservation struct {
	PocketIDSubject string
	Username        string
	Email           string
	DisplayName     string
	Groups          []string
}

type OwnerSnapshotAnchorSignature 

type OwnerSnapshotAnchorSignature struct {
	OwnerRef string `json:"ownerRef"`
	KeyID    string `json:"keyId"`
	Value    string `json:"value"`
}

OwnerSnapshotAnchorSignature authenticates one canonical local backup snapshot anchor with the established owner custody key.

func SignOwnerSnapshotAnchor 

func SignOwnerSnapshotAnchor(
	workspaceRoot string,
	canonicalAnchor []byte,
) (OwnerSnapshotAnchorSignature, error)

SignOwnerSnapshotAnchor signs only snapshot anchors. Its dedicated domain prevents a valid signature from being replayed as another evidence type.

type PocketIDOwnerEnrollment 

type PocketIDOwnerEnrollment struct {
	OwnerRef        string
	PocketIDSubject string
	SetupURL        string
	ExpiresAt       time.Time
}

type PocketIDOwnerEnrollmentView 

type PocketIDOwnerEnrollmentView struct {
	OwnerRef        string
	PocketIDSubject string
	SetupURL        string
	ExpiresAt       time.Time
}

PocketIDOwnerEnrollmentView exposes the verified private enrollment to the local owner service. Callers must keep SetupURL out of logs and durable lifecycle evidence.

func LoadPocketIDOwnerEnrollment 

func LoadPocketIDOwnerEnrollment(workspaceRoot string) (PocketIDOwnerEnrollmentView, error)

LoadPocketIDOwnerEnrollment verifies and returns the private owner-bound enrollment record.

type SecretObserver 

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

SecretObserver proves that the exact opaque secret locator in an Apply expectation resolves to valid owner-only local custody.

func NewSecretObserver 

func NewSecretObserver(workspaceRoot string) (*SecretObserver, error)

func (*SecretObserver) Observe 

func (o *SecretObserver) Observe(_ context.Context, expectation applyevidence.Expectation) (map[string]string, error)

type TinyAuthPocketIDBinding 

type TinyAuthPocketIDBinding struct {
	APIVersion  string    `json:"apiVersion"`
	Kind        string    `json:"kind"`
	OwnerRef    string    `json:"ownerRef"`
	KeyID       string    `json:"keyId"`
	ClientID    string    `json:"clientId"`
	CallbackURL string    `json:"callbackUrl"`
	GroupIDs    []string  `json:"groupIds"`
	EnvMAC      string    `json:"envMac"`
	BoundAt     time.Time `json:"boundAt"`
	Signature   string    `json:"signature"`
}

TinyAuthPocketIDBinding is the owner-signed, secret-free receipt for the private TinyAuth OAuth environment installed after PocketID creates the client secret. The secret itself is only represented by an owner-keyed MAC.

func BindBasementTinyAuthPocketID 

func BindBasementTinyAuthPocketID(
	workspaceRoot string,
	request TinyAuthPocketIDBindingRequest,
) (TinyAuthPocketIDBinding, error)

func LoadBasementTinyAuthPocketIDBinding 

func LoadBasementTinyAuthPocketIDBinding(workspaceRoot string) (TinyAuthPocketIDBinding, error)

type TinyAuthPocketIDBindingRequest 

type TinyAuthPocketIDBindingRequest struct {
	ClientID     string
	ClientSecret string
	GroupIDs     []string
}

type TrustProfile 

type TrustProfile struct {
	IdentityProvider     string `json:"identityProvider"`
	CertificateAuthority string `json:"certificateAuthority"`
	HumanAuthorityRef    string `json:"humanAuthorityRef"`
	HumanIssuerRef       string `json:"humanIssuerRef"`
	TrustDomainRef       string `json:"trustDomainRef"`
}

type WorkloadPeerAdmission 

type WorkloadPeerAdmission struct {
	PeerRef        string    `json:"peerRef"`
	ServiceRef     string    `json:"serviceRef"`
	EdgeSiteRef    string    `json:"edgeSiteRef"`
	Audience       string    `json:"audience"`
	CertificatePEM string    `json:"certificatePEM"`
	ValidUntil     time.Time `json:"validUntil"`
}

WorkloadPeerAdmission is an explicit Home-owner approval of one CA-issued client certificate for one publication. It neither issues a certificate nor grants access to identity administration or any other service.

type WorkloadPeerOperation 

type WorkloadPeerOperation struct {
	Operation     string                    `json:"operation"`
	Admission     *WorkloadPeerAdmission    `json:"admission,omitempty"`
	PeerRef       string                    `json:"peerRef,omitempty"`
	IssuedAt      time.Time                 `json:"issuedAt"`
	ExpiresAt     time.Time                 `json:"expiresAt"`
	PreviousState string                    `json:"previousState"`
	Signature     OwnerPolicyStateSignature `json:"signature"`
}

WorkloadPeerOperation carries exact local-owner authorization, independent of the management API credential. The signature is never produced by an HTTP endpoint. This proof is owner key custody, not a claim of human/device step-up.

func SignWorkloadPeerOperation 

func SignWorkloadPeerOperation(workspaceRoot string, operation WorkloadPeerOperation) (WorkloadPeerOperation, error)

type WorkloadPeerScope 

type WorkloadPeerScope struct {
	ServiceRef  string `json:"serviceRef"`
	EdgeSiteRef string `json:"edgeSiteRef"`
	Audience    string `json:"audience"`
}

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.