provideradapter

package module
v0.9.0 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: 23 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 fictional protocol-test provider. It is not a customer integration or evidence of a real infrastructure workflow.

Resource discovery (SDK v0.7.0)

An action can optionally publish ResourceDiscovery in its signed capability. DiscoveryRequest supports bounded search or exact-ID revalidation, never both. DiscoveryPage.Validate checks the complete request digest, observation age, page bounds, duplicate identities and complete present/missing classification for every selected ID. Missing resources are not permission grants.

IDs are opaque provider identities. Labels and kinds are untrusted display text; they must not be interpreted as HTML, instructions or authority. Connection configuration stays on the authenticated adapter transport, not UI receipts. The request digest preserves numeric precision and rejects duplicate JSON keys.

Existing action and manifest bytes are unchanged when discovery is absent. Declaring discovery changes signed identity and requires a new admitted release. Implement ResourceDiscoveryImplementation and configure a DiscoveryService with the verified immutable manifest and digest. HTTPHandler.Discovery exposes the authenticated /v1/resources/discover route; HTTPClient.DiscoverResources validates both request and response. Neither side falls back to unrestricted search for an unsupported capability.

Outbound adapters handle OutboundPhaseDiscoverResources through Dispatch.DiscoverResources, which checks the dispatch lifetime, connection, exact release, capability and response before returning a page. Create these dispatches with DispatchRequestDigest; discovery uses precision-preserving JSON while existing phases retain their legacy digests. Old runtime versions reject the new phase. The control plane must dispatch discovery only to a release that explicitly declares support; upgrading the SDK is not enrollment.

Both transports share the same validation and provider-deadline checks. The provider must honor context cancellation and perform read-only bounded queries. Transport authentication is not tenant authorization: admission, connection ownership, resource policy and selection-receipt persistence remain core duties.

Hosted dispatch integration, persisted selection receipts and console authoring are not implemented by the SDK alone. Do not advertise an adapter's guided resource picker just because it compiles against these types.

Exact resources and task limits

Authorization.ResourceIDs and AuthorizationRule.ResourceIDs use byte-exact identity matching. They cannot be combined with prefixes at the same scope. An explicit empty list is invalid. Omitting exact IDs preserves legacy prefix semantics; do not translate an exact ID into a prefix.

An allow or typed-action rule may include ParameterLimits. This is a closed top-level object: every supplied parameter must be declared, and each declared field is required unless marked optional. Scalars support types, explicit allowed values and inclusive numeric bounds. Objects and arrays require exact allowed JSON values. Numeric comparisons preserve integer precision; duplicate JSON keys, excessive nesting and oversized values are rejected.

All matching parameter ceilings intersect. A broader allow elsewhere cannot bypass a narrower ceiling. Limits are restrictions, never permission grants. Provider capability schemas still apply independently.

Credential issuers must explicitly publish the features they enforce in the signed Credential.AuthorizationFeatures: exact_resources_v1 and/or parameter_limits_v1. Upgrading this library does not opt an adapter in. Call CheckAuthorizationSupport before issuance, and enforce the full authorization in the actual provider credentials or execution boundary. Do not declare a feature merely because your parser recognizes it. The control plane also checks this declaration before issuing credentials.

Exact IDs and parameter limits participate in authorization digests. New renderers receive exact scope through ConfigureRequest.ResourceIDs. Legacy manifest and authorization bytes remain unchanged when new fields are absent; older adapters must reject unfamiliar constrained requests, not drop fields.

Exact capability selection (SDK v0.8.0)

AuthorizationRule.Capabilities contains exact {ref, digest} pairs. Both values must match a selected immutable capability. It is an additional rule selector, intersecting provider, operation and resource; matching an operation alone cannot select another implementation. A nil field retains legacy semantics. Empty, duplicated, ambiguous and malformed selections are invalid. The connection's exact provider release remains independently pinned.

Use MatchesAuthorizationRule for selector matching and ParametersWithinCapabilityRules for applicable parameter ceilings. Neither helper grants permission: callers must validate the full authorization, preserve stop/deny precedence and separately enforce exact action approval. Generic ceilings still intersect capability-specific ceilings. The legacy ParametersWithinRules helper refuses capability-bearing rules because it has no trusted capability identity; it never silently drops the new selector.

Credential issuers must explicitly declare capability_bindings_v1 in the signed authorization features and actually enforce it. A native credential format that cannot bind exact capabilities must refuse issuance. Merely updating an SDK or parsing the selector is not enforcement. Selectors change the authorization digest; omitting them preserves legacy canonical bytes.

This SDK release alone does not enable capability selection in the console. Core storage/rollback protection, signing, local runtime, action enforcement and old-client rejection must ship together before removing the current same-operation ambiguity refusal from guided task authoring.

Outbound native target verification

An outbound release may explicitly declare Broker.ConnectionVerification = ConnectionVerificationProtocol. This changes the signed manifest identity. Registration/heartbeat alone is not native target verification, and existing releases do not opt in by updating the SDK.

Handle OutboundPhaseVerifyConnection with Dispatch.VerifyConnection and a ConnectionVerificationService. Its implementation must perform a bounded, read-only native target check and return ConnectionVerificationResult: exact request digest, target identity, verification time and a redacted evidence digest. Do not return credentials or substitute the daemon ID for the target. VerifyConnectionRequestDigest preserves configuration-number precision. Both dispatch and response checks reject stale/substituted work before it can become verified connection authority. Retaining proof and validating tenant admission remain control-plane responsibilities.

This exchange is outbound-only. Inbound adapters retain their existing authenticated verification protocol. No adapter is considered accepted merely because it publishes the declaration. Actual target, native scope and expiry tests are required. This SDK addition does not implement task-deadline negotiation, native credential enforcement, or local process isolation.

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 (
	AuthorizationExactResourcesV1     = "exact_resources_v1"
	AuthorizationParameterLimitsV1    = "parameter_limits_v1"
	AuthorizationCapabilityBindingsV1 = "capability_bindings_v1"
)
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"
	OutboundPhaseDiscoverResources = "discover_resources"
	OutboundPhaseVerifyConnection  = "verify_connection"
)
View Source 
const ConnectionVerificationProtocol = "misconfig.connection-verification/v1"
View Source 
const ResourceDiscoveryProtocol = "misconfig.resource-discovery/v1"

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 CheckAuthorizationSupport added in v0.6.0 

func CheckAuthorizationSupport(a Authorization, features []string) error

CheckAuthorizationSupport must run before issuing credentials. An issuer must implement every constraint it declares, including rule intersections.

func Digest 

func Digest(manifest Manifest) (string, error)

func DiscoveryRequestDigest added in v0.7.0 

func DiscoveryRequestDigest(r DiscoveryRequest, capability ActionCapability) (string, error)

DiscoveryRequestDigest binds the exact validated request, including its mode, freshness and private connection configuration. Retain only the digest in customer-safe receipts. Providers compute it from the decoded request.

func DispatchRequestDigest added in v0.7.0 

func DispatchRequestDigest(phase string, request json.RawMessage) (string, error)

DispatchRequestDigest preserves legacy dispatch digests. Discovery requests use exact-number canonical JSON so configuration coordinates cannot collide through float64 rounding. Call this when creating discovery dispatches.

func JSONDigest added in v0.4.0 

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

func MatchesAuthorizationRule added in v0.8.0 

func MatchesAuthorizationRule(rule AuthorizationRule, provider, operation, resource string, capability CapabilitySelector) bool

MatchesAuthorizationRule matches selectors only. It is not an authorization decision: callers must validate the complete authorization, apply deny/stop precedence, intersect parameter ceilings and enforce approval separately.

func MatchesCapabilities added in v0.8.0 

func MatchesCapabilities(actual CapabilitySelector, selected []CapabilitySelector) bool

MatchesCapabilities does not grant authority on its own. Callers must also enforce provider/release, operation, resource, parameter and policy effect.

func MatchesResources added in v0.6.0 

func MatchesResources(resource string, prefixes, ids []string) bool

MatchesResources uses byte-exact equality for IDs; legacy prefix behavior is preserved only when no exact selector is supplied. Callers requiring bounded scope must additionally reject the absence of both selectors.

func ParametersWithinCapabilityRules added in v0.8.0 

func ParametersWithinCapabilityRules(rules []AuthorizationRule, provider, operation, resource string, capability CapabilitySelector, parameters json.RawMessage) bool

ParametersWithinCapabilityRules intersects parameter ceilings only within the applicable exact capability and the remaining rule scope. Generic rules still apply. This checks ceilings, not allow/deny effects or approval.

func ParametersWithinRules added in v0.6.0 

func ParametersWithinRules(rules []AuthorizationRule, provider, operation, resource string, parameters json.RawMessage) bool

ParametersWithinRules intersects all applicable parameter ceilings. A broad allow elsewhere must never bypass the limits on this operation/resource.

func Signature 

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

func ValidateAuthorizationFeatures added in v0.6.0 

func ValidateAuthorizationFeatures(features []string) error

Authorization features are publisher assertions in a signed credential manifest. Merely upgrading the SDK does not opt an issuer into enforcement.

func ValidateCapabilitySelection added in v0.8.0 

func ValidateCapabilitySelection(selected []CapabilitySelector) error

ValidateCapabilitySelection preserves legacy operation-based semantics only when the field is absent. An explicit empty list is invalid, never wildcard. A reference cannot resolve to two digests in the same selection.

func ValidateConnectionVerificationRequest added in v0.9.0 

func ValidateConnectionVerificationRequest(request VerifyRequest, manifest Manifest, now time.Time) error

func ValidateResourceSelection added in v0.6.0 

func ValidateResourceSelection(prefixes, ids []string) error

ValidateResourceSelection forbids ambiguous mixed matchers. A supplied empty exact selection is invalid, not a synonym for unrestricted scope.

func Verify 

func Verify(signed SignedManifest, trusted TrustedPublisher) error

func VerifyConnectionRequestDigest added in v0.9.0 

func VerifyConnectionRequestDigest(request VerifyRequest) (string, 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"`
	Discovery          *ResourceDiscovery `json:"resource_discovery,omitempty"`
}

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"`
	ResourceIDs      []string            `json:"resource_ids,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"`
	Capabilities     []CapabilitySelector `json:"capabilities,omitempty"`
	ResourcePrefixes []string             `json:"resource_prefixes,omitempty"`
	ResourceIDs      []string             `json:"resource_ids,omitempty"`
	ParameterLimits  *ParameterLimits     `json:"parameter_limits,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"`
	ConnectionVerification string            `json:"connection_verification,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 CapabilitySelector added in v0.8.0 

type CapabilitySelector struct {
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

CapabilitySelector identifies one immutable implementation, not merely its operation or display name. The connection's pinned provider release remains an independent boundary. Neither reference prefixes nor digest wildcards are accepted. A selector is conjunctive with a rule's other matchers.

func (CapabilitySelector) Validate added in v0.8.0 

func (c CapabilitySelector) Validate() 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"`
	ResourceIDs        []string `json:"resource_ids,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 ConnectionVerificationImplementation added in v0.9.0 

type ConnectionVerificationImplementation interface {
	VerifyConnection(context.Context, VerifyRequest) (ConnectionVerificationResult, error)
}

type ConnectionVerificationResult added in v0.9.0 

type ConnectionVerificationResult struct {
	Protocol       string    `json:"protocol"`
	RequestDigest  string    `json:"request_digest"`
	TargetIdentity string    `json:"target_identity"`
	VerifiedAt     time.Time `json:"verified_at"`
	EvidenceDigest string    `json:"evidence_digest"`
}

ConnectionVerificationResult proves which request the provider checked. It contains no credential material. TargetIdentity must come from a read-only provider identity check, never from the daemon's enrollment/runtime ID.

func (ConnectionVerificationResult) Validate added in v0.9.0 

func (r ConnectionVerificationResult) Validate(request VerifyRequest, now time.Time) error

type ConnectionVerificationService added in v0.9.0 

type ConnectionVerificationService struct {
	Manifest       Manifest
	ManifestDigest string
	Implementation ConnectionVerificationImplementation
}

func (ConnectionVerificationService) VerifyConnection added in v0.9.0 

func (s ConnectionVerificationService) VerifyConnection(ctx context.Context, request VerifyRequest, now time.Time) (ConnectionVerificationResult, error)

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"`
	AuthorizationFeatures []string `json:"authorization_features,omitempty"`
}

type DiscoveredResource added in v0.7.0 

type DiscoveredResource struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Kind  string `json:"kind"`
}

type DiscoveryPage added in v0.7.0 

type DiscoveryPage struct {
	Protocol           string               `json:"protocol"`
	RequestDigest      string               `json:"request_digest"`
	ObservedAt         time.Time            `json:"observed_at"`
	Resources          []DiscoveredResource `json:"resources"`
	NextCursor         string               `json:"next_cursor,omitempty"`
	MissingResourceIDs []string             `json:"missing_resource_ids,omitempty"`
}

func (DiscoveryPage) Validate added in v0.7.0 

func (p DiscoveryPage) Validate(r DiscoveryRequest, capability ActionCapability, now time.Time) error

type DiscoveryRequest added in v0.7.0 

type DiscoveryRequest struct {
	Protocol         string          `json:"protocol"`
	RequestID        string          `json:"request_id"`
	TenantID         string          `json:"tenant_id"`
	ConnectionID     string          `json:"connection_id"`
	Provider         string          `json:"provider"`
	Release          string          `json:"release"`
	ManifestDigest   string          `json:"manifest_digest"`
	AccountRef       string          `json:"account_ref"`
	CapabilityRef    string          `json:"capability_ref"`
	CapabilityDigest string          `json:"capability_digest"`
	Configuration    json.RawMessage `json:"configuration"`
	Query            string          `json:"query,omitempty"`
	Cursor           string          `json:"cursor,omitempty"`
	Limit            int             `json:"limit"`
	ResourceIDs      []string        `json:"resource_ids,omitempty"`
	Now              time.Time       `json:"now"`
}

DiscoveryRequest coordinates are derived by the control plane. Configuration stays on the authenticated provider transport and must never enter UI receipts. ResourceIDs != nil selects exact revalidation, with no query or cursor.

func (DiscoveryRequest) Validate added in v0.7.0 

func (r DiscoveryRequest) Validate(capability ActionCapability) error

func (DiscoveryRequest) ValidateAt added in v0.7.0 

func (r DiscoveryRequest) ValidateAt(capability ActionCapability, now time.Time) error

type DiscoveryService added in v0.7.0 

type DiscoveryService struct {
	Manifest       Manifest
	ManifestDigest string
	Implementation ResourceDiscoveryImplementation
}

DiscoveryService shares release, capability and freshness checks between inbound HTTP and outbound runtimes. Manifest must be the verified, immutable release used for enrollment; callers must not construct it from request data.

func (DiscoveryService) DiscoverResources added in v0.7.0 

func (s DiscoveryService) DiscoverResources(ctx context.Context, request DiscoveryRequest, now time.Time) (DiscoveryPage, error)

func (DiscoveryService) Validate added in v0.7.0 

func (s DiscoveryService) Validate() error

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) DiscoverResources added in v0.7.0 

func (d Dispatch) DiscoverResources(ctx context.Context, service DiscoveryService, now time.Time) (DiscoveryPage, error)

DiscoverResources rejects every non-discovery phase and validates dispatch binding before any provider API call. Outer enrollment/claim authentication remains the outbound control plane's responsibility.

func (Dispatch) Validate added in v0.4.2 

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

func (Dispatch) VerifyConnection added in v0.9.0 

func (d Dispatch) VerifyConnection(ctx context.Context, service ConnectionVerificationService, now time.Time) (ConnectionVerificationResult, 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) DiscoverResources added in v0.7.0 

func (c HTTPClient) DiscoverResources(ctx context.Context, request DiscoveryRequest, capability ActionCapability) (DiscoveryPage, 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
	Discovery      *DiscoveryService
	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,omitempty"`
	Renderer            *Renderer          `json:"renderer,omitempty"`
	Broker              Broker             `json:"broker"`
	Actions             []ActionCapability `json:"actions,omitempty"`
}

func (Manifest) SupportsCredentials added in v0.5.0 

func (m Manifest) SupportsCredentials() bool

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 ParameterLimit added in v0.6.0 

type ParameterLimit struct {
	Type          string            `json:"type"`
	Optional      bool              `json:"optional,omitempty"`
	AllowedValues []json.RawMessage `json:"allowed_values,omitempty"`
	Minimum       *json.Number      `json:"minimum,omitempty"`
	Maximum       *json.Number      `json:"maximum,omitempty"`
}

type ParameterLimits added in v0.6.0 

type ParameterLimits struct {
	Fields map[string]ParameterLimit `json:"fields"`
}

ParameterLimits is a closed, top-level parameter object. Every supplied key must be declared. Fields are required unless Optional is explicitly true. Nested structured values can be allowed only by exact JSON equality.

func (ParameterLimits) Matches added in v0.6.0 

func (p ParameterLimits) Matches(raw json.RawMessage) bool

func (ParameterLimits) Validate added in v0.6.0 

func (p ParameterLimits) Validate() error

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 ResourceDiscovery added in v0.7.0 

type ResourceDiscovery struct {
	Protocol          string `json:"protocol"`
	MaximumPageSize   int    `json:"maximum_page_size"`
	MaximumAgeSeconds int    `json:"maximum_age_seconds"`
}

ResourceDiscovery is optional signed capability metadata, not a grant. Providers must implement read-only search AND exact identity revalidation.

func (ResourceDiscovery) Validate added in v0.7.0 

func (d ResourceDiscovery) Validate() error

type ResourceDiscoveryImplementation added in v0.7.0 

type ResourceDiscoveryImplementation interface {
	DiscoverResources(context.Context, DiscoveryRequest) (DiscoveryPage, error)
}

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.