provideradapter

package module
v0.4.2 Latest Latest
Warning

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

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

README

Misconfig provider adapter SDK

This module is the public, provider-neutral extension boundary for governed infrastructure-agent sessions. An adapter publishes one immutable signed release and implements the generic prepare, verify, issue, local-render, and optional typed-action protocols. Provider names, credential kinds, targets, operations, and schemas are data.

The core does not gain a provider branch when an adapter is added. A release is usable only after its publisher is trusted, its manifest signature and digest verify, and the tenant admits that exact digest.

Contracts

  • Manifest describes a provider, short-lived credential protocol, local renderer, per-platform artifact digests, schemas, and exact release identity.
  • Sign and Verify bind that manifest to an Ed25519 publisher key.
  • HTTPHandler and HTTPClient implement the authenticated inbound broker protocol. A signed release may instead declare outbound-pull and pin one or more runnable artifacts; the same prepare, issue, execute, and verify envelopes then travel through the tenant-isolated control-plane broker.
  • ActionCapability publishes separately signed parameter, execution, and verification schemas. ExecuteActionRequest consumes one short-lived, action-bound authority; VerifyActionRequest observes provider state again.
  • ConfigureRequest and RenderRequest let a digest-pinned local executable translate generic session coordinates into provider-native configuration.

The transport is deliberately narrow: the control plane never loads adapter code, and opaque credential material reaches only the admitted local renderer. Unknown fields, trailing JSON, signature drift, replayed nonces, incompatible protocols, and widened provider identities fail closed.

An execution response is never proof by itself. Adapters return a redacted provider receipt and a digest-bound output, then perform a distinct read-back verification with its own evidence digest. The core remains unaware whether the adapter controls AWS, GCP, Kubernetes, Hetzner, SaaS APIs, or an internal system.

See provider-fixture-orbital for a deliberately unfamiliar acceptance provider.

Compatibility

The module follows semantic versioning. Protocol major 2 binds every issued credential to the immutable profile, policy, environment, operation, and resource ceiling. An incompatible wire change requires a new protocol major and explicit control-plane support.

Licensed under Apache-2.0.

Documentation

Index

Constants

View Source 
const (
	ManifestProtocol = "misconfig.provider-adapter/v2"
	BrokerProtocol   = "misconfig.credential-broker/v2"
	RendererProtocol = "misconfig.credential-renderer/v1"

	BrokerTransportInboundHTTPS = "inbound-https"
	BrokerTransportOutboundPull = "outbound-pull"
)
View Source 
const (
	OutboundRuntimeProtocol = "misconfig.provider-runtime/v1"

	OutboundPhaseIssueCredential = "issue_credential"
	OutboundPhaseExecuteAction   = "execute_action"
	OutboundPhaseVerifyAction    = "verify_action"
)

Variables

This section is empty.

Functions

func ActionCapabilityDigest added in v0.4.0 

func ActionCapabilityDigest(action ActionCapability) (string, error)

func ActionDigest added in v0.4.1 

func ActionDigest(capabilityDigest, operation, resource, environment string, parameters json.RawMessage) (string, error)

ActionDigest canonically binds one typed action to the immutable capability, provider operation, exact resource, environment, and decoded parameters. Both the control plane and the provider adapter must recompute it. A caller cannot substitute parameters after approval while retaining the authority.

func AuthorizationDigest added in v0.3.0 

func AuthorizationDigest(authorization Authorization) (string, error)

func Canonical 

func Canonical(manifest Manifest) ([]byte, error)

func Digest 

func Digest(manifest Manifest) (string, error)

func JSONDigest added in v0.4.0 

func JSONDigest(value json.RawMessage) (string, error)

func Signature 

func Signature(secret, timestamp, nonce string, body []byte) string

func Verify 

func Verify(signed SignedManifest, trusted TrustedPublisher) error

func VerifySignature 

func VerifySignature(secret, timestamp, nonce, signature string, body []byte, now time.Time) error

Types

type ActionAuthority added in v0.4.0 

type ActionAuthority struct {
	ID               string    `json:"id"`
	ActionDigest     string    `json:"action_digest"`
	CapabilityDigest string    `json:"capability_digest"`
	ApprovedBy       string    `json:"approved_by"`
	ApprovedAt       time.Time `json:"approved_at"`
	ExpiresAt        time.Time `json:"expires_at"`
}

ActionAuthority is the single-action authority consumed by an adapter. It is distinct from a credential lease: it binds one approved action digest to one capability release and expires quickly.

func (ActionAuthority) Validate added in v0.4.0 

func (a ActionAuthority) Validate(now time.Time, actionDigest, capabilityDigest string, maximumTTL time.Duration) error

type ActionCapability added in v0.4.0 

type ActionCapability struct {
	Ref                string `json:"ref"`
	Operation          string `json:"operation"`
	MaximumTTLSeconds  int64  `json:"maximum_ttl_seconds"`
	Reversible         bool   `json:"reversible"`
	ParametersSchema   any    `json:"parameters_schema"`
	ExecutionSchema    any    `json:"execution_schema"`
	VerificationSchema any    `json:"verification_schema"`
}

ActionCapability is an immutable, provider-owned typed action contract. The control plane treats every field as signed runtime data: it never maintains a provider or operation enum. Execute and verify schemas deliberately remain separate so an adapter cannot claim that a successful API response proves the requested provider state.

func (ActionCapability) Validate added in v0.4.0 

func (a ActionCapability) Validate() error

type ActionExecution added in v0.4.0 

type ActionExecution struct {
	ProviderReceipt   string          `json:"provider_receipt"`
	ExecutionIdentity string          `json:"execution_identity"`
	ExecutedAt        time.Time       `json:"executed_at"`
	Output            json.RawMessage `json:"output"`
	OutputDigest      string          `json:"output_digest"`
}

ActionExecution is a redacted provider receipt. Provider credentials and raw response payloads are forbidden; the adapter returns only stable identities and digests needed for independent verification and audit.

func (ActionExecution) Validate added in v0.4.0 

func (e ActionExecution) Validate() error

type ActionImplementation added in v0.4.0 

type ActionImplementation interface {
	ExecuteAction(context.Context, ExecuteActionRequest) (ActionExecution, error)
	VerifyAction(context.Context, VerifyActionRequest) (ActionVerification, error)
}

type ActionVerification added in v0.4.0 

type ActionVerification struct {
	State           string          `json:"state"`
	VerifiedAt      time.Time       `json:"verified_at"`
	VerifierRelease string          `json:"verifier_release"`
	Evidence        json.RawMessage `json:"evidence"`
	EvidenceDigest  string          `json:"evidence_digest"`
}

func (ActionVerification) Validate added in v0.4.0 

func (v ActionVerification) Validate() error

type Authorization added in v0.3.0 

type Authorization struct {
	ProfileDigest    string              `json:"profile_digest"`
	PolicyRelease    string              `json:"policy_release"`
	Provider         string              `json:"provider"`
	AccountRef       string              `json:"account_ref"`
	Environments     []string            `json:"environments"`
	ResourcePrefixes []string            `json:"resource_prefixes,omitempty"`
	Rules            []AuthorizationRule `json:"rules"`
}

Authorization is the immutable provider-neutral ceiling an admitted credential adapter must enforce when it issues native credentials. Rules remain generic operation and resource matchers; an adapter either maps the complete ceiling to its provider or refuses issuance.

func (Authorization) Validate added in v0.3.0 

func (a Authorization) Validate() error

type AuthorizationRule added in v0.3.0 

type AuthorizationRule struct {
	ID               string   `json:"id"`
	Effect           string   `json:"effect"`
	Providers        []string `json:"providers,omitempty"`
	Operations       []string `json:"operations,omitempty"`
	ResourcePrefixes []string `json:"resource_prefixes,omitempty"`
}

type Broker 

type Broker struct {
	Protocol         string            `json:"protocol"`
	Transport        string            `json:"transport,omitempty"`
	Endpoint         string            `json:"endpoint,omitempty"`
	RuntimeArtifacts []RuntimeArtifact `json:"runtime_artifacts,omitempty"`
}

func (Broker) TransportMode added in v0.4.2 

func (b Broker) TransportMode() string

type BrokerImplementation 

type BrokerImplementation interface {
	Prepare(context.Context, PrepareRequest) (Connection, error)
	Verify(context.Context, VerifyRequest) (Verification, error)
	Issue(context.Context, IssueRequest) (Material, error)
}

type Compatibility 

type Compatibility struct {
	Protocol string `json:"protocol"`
	Major    int    `json:"major"`
}

type ConfigureRequest 

type ConfigureRequest struct {
	Protocol           string   `json:"protocol"`
	Release            string   `json:"release"`
	ManifestDigest     string   `json:"manifest_digest"`
	Provider           string   `json:"provider"`
	CredentialKind     string   `json:"credential_kind"`
	SessionID          string   `json:"session_id"`
	AccountRef         string   `json:"account_ref"`
	Environments       []string `json:"environments"`
	ResourcePrefixes   []string `json:"resource_prefixes,omitempty"`
	ActivePath         string   `json:"active_path"`
	RuntimeExecutable  string   `json:"runtime_executable"`
	RendererExecutable string   `json:"renderer_executable"`
	RuntimeDirectory   string   `json:"runtime_directory"`
	LeaseCommand       []string `json:"lease_command"`
}

ConfigureRequest contains only immutable session and adapter coordinates. It never contains provider credential material. A renderer uses it to emit the provider-native environment and configuration files that cause the native client to call LeaseCommand when it needs short-lived material.

type Connection 

type Connection struct {
	Configuration json.RawMessage `json:"configuration"`
	Onboarding    json.RawMessage `json:"onboarding"`
}

type Credential 

type Credential struct {
	Kind                string `json:"kind"`
	MaximumTTLSeconds   int64  `json:"maximum_ttl_seconds"`
	RevocationSemantics string `json:"revocation_semantics"`
	PayloadSchema       any    `json:"payload_schema"`
}

type Dispatch added in v0.4.2 

type Dispatch struct {
	Protocol      string          `json:"protocol"`
	ID            string          `json:"id"`
	ConnectionID  string          `json:"connection_id"`
	Phase         string          `json:"phase"`
	Request       json.RawMessage `json:"request"`
	RequestDigest string          `json:"request_digest"`
	ClaimToken    string          `json:"claim_token"`
	ClaimedAt     time.Time       `json:"claimed_at"`
	ExpiresAt     time.Time       `json:"expires_at"`
}

func (Dispatch) Validate added in v0.4.2 

func (d Dispatch) Validate(now time.Time) error

type DispatchClaim added in v0.4.2 

type DispatchClaim struct {
	Protocol     string `json:"protocol"`
	ConnectionID string `json:"connection_id"`
	RuntimeID    string `json:"runtime_id"`
}

type DispatchResult added in v0.4.2 

type DispatchResult struct {
	Protocol       string          `json:"protocol"`
	DispatchID     string          `json:"dispatch_id"`
	ConnectionID   string          `json:"connection_id"`
	RuntimeID      string          `json:"runtime_id"`
	Phase          string          `json:"phase"`
	RequestDigest  string          `json:"request_digest"`
	ClaimToken     string          `json:"claim_token"`
	Response       json.RawMessage `json:"response,omitempty"`
	ResponseDigest string          `json:"response_digest,omitempty"`
	Failure        string          `json:"failure,omitempty"`
	CompletedAt    time.Time       `json:"completed_at"`
}

func (DispatchResult) Validate added in v0.4.2 

func (r DispatchResult) Validate() error

type ExecuteActionRequest added in v0.4.0 

type ExecuteActionRequest struct {
	RequestID        string          `json:"request_id"`
	ConnectionID     string          `json:"connection_id"`
	Provider         string          `json:"provider"`
	Release          string          `json:"release"`
	AccountRef       string          `json:"account_ref"`
	Configuration    json.RawMessage `json:"configuration"`
	Subject          Subject         `json:"subject"`
	CapabilityRef    string          `json:"capability_ref"`
	CapabilityDigest string          `json:"capability_digest"`
	ActionID         string          `json:"action_id"`
	ActionDigest     string          `json:"action_digest"`
	Operation        string          `json:"operation"`
	Resource         string          `json:"resource"`
	Environment      string          `json:"environment"`
	Parameters       json.RawMessage `json:"parameters"`
	Authority        ActionAuthority `json:"authority"`
	Now              time.Time       `json:"now"`
}

func (ExecuteActionRequest) Validate added in v0.4.0 

func (r ExecuteActionRequest) Validate(capability ActionCapability) error

type HTTPClient 

type HTTPClient struct {
	Endpoint       string
	SharedSecret   string
	ManifestDigest string
	Release        string
	HTTP           *http.Client
	Now            func() time.Time
	Nonce          func() (string, error)
}

func (HTTPClient) ExecuteAction added in v0.4.0 

func (c HTTPClient) ExecuteAction(ctx context.Context, request ExecuteActionRequest) (ActionExecution, error)

func (HTTPClient) Issue 

func (c HTTPClient) Issue(ctx context.Context, request IssueRequest) (Material, error)

func (HTTPClient) Prepare 

func (c HTTPClient) Prepare(ctx context.Context, request PrepareRequest) (Connection, error)

func (HTTPClient) Verify 

func (c HTTPClient) Verify(ctx context.Context, request VerifyRequest) (Verification, error)

func (HTTPClient) VerifyAction added in v0.4.0 

func (c HTTPClient) VerifyAction(ctx context.Context, request VerifyActionRequest) (ActionVerification, error)

type HTTPHandler 

type HTTPHandler struct {
	Implementation BrokerImplementation
	Actions        ActionImplementation
	SharedSecret   string
	ManifestDigest string
	Release        string
	Now            func() time.Time
	// contains filtered or unexported fields
}

func (*HTTPHandler) Handler 

func (h *HTTPHandler) Handler() (http.Handler, error)

type IssueRequest 

type IssueRequest struct {
	RequestID           string          `json:"request_id"`
	ConnectionID        string          `json:"connection_id"`
	Provider            string          `json:"provider"`
	Release             string          `json:"release"`
	AccountRef          string          `json:"account_ref"`
	Configuration       json.RawMessage `json:"configuration"`
	Subject             Subject         `json:"subject"`
	Authorization       Authorization   `json:"authorization"`
	AuthorizationDigest string          `json:"authorization_digest"`
	Now                 time.Time       `json:"now"`
}

type Manifest 

type Manifest struct {
	Protocol            string             `json:"protocol"`
	Publisher           Publisher          `json:"publisher"`
	Compatibility       Compatibility      `json:"compatibility"`
	Release             string             `json:"release"`
	Provider            string             `json:"provider"`
	ConfigurationSchema any                `json:"configuration_schema"`
	Credential          Credential         `json:"credential"`
	Renderer            Renderer           `json:"renderer"`
	Broker              Broker             `json:"broker"`
	Actions             []ActionCapability `json:"actions,omitempty"`
}

func (Manifest) Validate 

func (m Manifest) Validate() error

type Material 

type Material struct {
	Kind                string          `json:"kind"`
	Payload             json.RawMessage `json:"payload"`
	ExpiresAt           time.Time       `json:"expires_at"`
	TargetIdentity      string          `json:"target_identity"`
	RevocationSemantics string          `json:"revocation_semantics"`
	AuthorizationDigest string          `json:"authorization_digest"`
}

type PrepareRequest 

type PrepareRequest struct {
	RequestID    string          `json:"request_id"`
	TenantID     string          `json:"tenant_id"`
	ConnectionID string          `json:"connection_id"`
	Provider     string          `json:"provider"`
	Release      string          `json:"release"`
	AccountRef   string          `json:"account_ref"`
	Name         string          `json:"name"`
	Input        json.RawMessage `json:"input"`
	Now          time.Time       `json:"now"`
}

type Publisher 

type Publisher struct {
	ID    string `json:"id"`
	KeyID string `json:"key_id"`
}

type RenderRequest 

type RenderRequest struct {
	Protocol       string          `json:"protocol"`
	Release        string          `json:"release"`
	ManifestDigest string          `json:"manifest_digest"`
	SessionID      string          `json:"session_id"`
	ActivePath     string          `json:"active_path"`
	RuntimePath    string          `json:"runtime_path"`
	Material       json.RawMessage `json:"material"`
}

type RenderedEnvironment 

type RenderedEnvironment struct {
	Remove []string          `json:"remove"`
	Set    map[string]string `json:"set"`
	Files  []RenderedFile    `json:"files,omitempty"`
}

type RenderedFile 

type RenderedFile struct {
	Name    string `json:"name"`
	Content string `json:"content"`
	Mode    uint32 `json:"mode"`
}

type RenderedMaterial 

type RenderedMaterial struct {
	Stdout string `json:"stdout"`
}

RenderedMaterial is an envelope so the runtime can validate and bound the renderer result before writing provider-native credential output to stdout.

type Renderer 

type Renderer struct {
	Protocol             string             `json:"protocol"`
	Executable           string             `json:"executable"`
	Artifacts            []RendererArtifact `json:"artifacts"`
	SensitiveEnvironment []string           `json:"sensitive_environment,omitempty"`
}

type RendererArtifact added in v0.2.0 

type RendererArtifact struct {
	OS     string `json:"os"`
	Arch   string `json:"arch"`
	Digest string `json:"digest"`
}

type RuntimeArtifact added in v0.4.2 

type RuntimeArtifact struct {
	Kind      string `json:"kind"`
	Reference string `json:"reference"`
	Digest    string `json:"digest"`
}

RuntimeArtifact is an immutable, publisher-owned executable identity used by an outbound adapter. Kind and reference remain provider-neutral: a publisher may identify an OCI image, native binary, package, appliance, or another independently verifiable runtime. The control plane never executes the reference and accepts registration only for an exact signed digest.

type RuntimeRegistration added in v0.4.2 

type RuntimeRegistration struct {
	Protocol              string `json:"protocol"`
	ConnectionID          string `json:"connection_id"`
	Provider              string `json:"provider"`
	Release               string `json:"release"`
	ManifestDigest        string `json:"manifest_digest"`
	RuntimeArtifactDigest string `json:"runtime_artifact_digest"`
	RuntimeID             string `json:"runtime_id"`
}

RuntimeRegistration identifies one independently running outbound adapter. Authentication is carried separately by the enrollment bearer token; the token must never appear in this payload, logs, receipts, or persisted state.

func (RuntimeRegistration) Validate added in v0.4.2 

func (r RuntimeRegistration) Validate(manifest Manifest, manifestDigest string) error

type SignedManifest 

type SignedManifest struct {
	Manifest  Manifest `json:"manifest"`
	Digest    string   `json:"digest"`
	Signature string   `json:"signature"`
}

func Sign 

func Sign(manifest Manifest, privateKey ed25519.PrivateKey) (SignedManifest, error)

type Subject 

type Subject struct {
	TenantID    string `json:"tenant_id"`
	ActorID     string `json:"actor_id"`
	DeviceID    string `json:"device_id"`
	SessionID   string `json:"session_id"`
	ProfileID   string `json:"profile_id"`
	AccountRef  string `json:"account_ref"`
	Environment string `json:"environment"`
}

type TrustedPublisher 

type TrustedPublisher struct {
	ID        string
	KeyID     string
	PublicKey ed25519.PublicKey
}

type Verification 

type Verification struct {
	TargetIdentity string    `json:"target_identity"`
	VerifiedAt     time.Time `json:"verified_at"`
}

type VerifyActionRequest added in v0.4.0 

type VerifyActionRequest struct {
	RequestID        string          `json:"request_id"`
	ConnectionID     string          `json:"connection_id"`
	Provider         string          `json:"provider"`
	Release          string          `json:"release"`
	AccountRef       string          `json:"account_ref"`
	Configuration    json.RawMessage `json:"configuration"`
	Subject          Subject         `json:"subject"`
	CapabilityRef    string          `json:"capability_ref"`
	CapabilityDigest string          `json:"capability_digest"`
	ActionID         string          `json:"action_id"`
	ActionDigest     string          `json:"action_digest"`
	Operation        string          `json:"operation"`
	Resource         string          `json:"resource"`
	Environment      string          `json:"environment"`
	Parameters       json.RawMessage `json:"parameters"`
	Execution        ActionExecution `json:"execution"`
	Now              time.Time       `json:"now"`
}

func (VerifyActionRequest) Validate added in v0.4.1 

func (r VerifyActionRequest) Validate(capability ActionCapability) error

type VerifyRequest 

type VerifyRequest struct {
	RequestID     string          `json:"request_id"`
	TenantID      string          `json:"tenant_id"`
	ConnectionID  string          `json:"connection_id"`
	Provider      string          `json:"provider"`
	Release       string          `json:"release"`
	AccountRef    string          `json:"account_ref"`
	Configuration json.RawMessage `json:"configuration"`
	Now           time.Time       `json:"now"`
}

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.