provideradapter

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, and local-render protocols. Provider names, credential kinds, targets, 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 broker protocol.
• 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.

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

Compatibility

The module follows semantic versioning. Protocol major 1 remains compatible within the v0.1.x SDK line; an incompatible wire change requires a new protocol major and explicit control-plane support.

Licensed under Apache-2.0.

Documentation

Index

• Constants
• func Canonical(manifest Manifest) ([]byte, error)
• func Digest(manifest Manifest) (string, error)
• func Signature(secret, timestamp, nonce string, body []byte) string
• func Verify(signed SignedManifest, trusted TrustedPublisher) error
• func VerifySignature(secret, timestamp, nonce, signature string, body []byte, now time.Time) error
• type Broker
• type BrokerImplementation
• type Compatibility
• type ConfigureRequest
• type Connection
• type Credential
• type HTTPClient
  • func (c HTTPClient) Issue(ctx context.Context, request IssueRequest) (Material, error)
  • func (c HTTPClient) Prepare(ctx context.Context, request PrepareRequest) (Connection, error)
  • func (c HTTPClient) Verify(ctx context.Context, request VerifyRequest) (Verification, error)
• type HTTPHandler
  • func (h *HTTPHandler) Handler() (http.Handler, error)
• type IssueRequest
• type Manifest
  • func (m Manifest) Validate() error
• type Material
• type PrepareRequest
• type Publisher
• type RenderRequest
• type RenderedEnvironment
• type RenderedFile
• type RenderedMaterial
• type Renderer
• type RendererArtifact
• type SignedManifest
  • func Sign(manifest Manifest, privateKey ed25519.PrivateKey) (SignedManifest, error)
• type Subject
• type TrustedPublisher
• type Verification
• type VerifyRequest

Constants

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

Functions

func Canonical

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

func Digest

func Digest(manifest Manifest) (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 Broker

type Broker struct {
	Protocol string `json:"protocol"`
	Endpoint string `json:"endpoint"`
}

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 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) 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)

type HTTPHandler

type HTTPHandler struct {
	Implementation BrokerImplementation
	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"`
	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"`
}

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"`
}

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

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

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 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"`
}