roles

package
v0.0.0-...-804b954 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package roles validates trust-scoped runtime process composition.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func KnownCredentialEnvironmentNames 

func KnownCredentialEnvironmentNames() []string

KnownCredentialEnvironmentNames returns the reviewed, complete credential key inventory. It contains names only and is safe to use in diagnostics.

func Serve 

func Serve(ctx context.Context, plan Plan, listener net.Listener) error

Serve exposes only role readiness and health until the role's product implementation is composed. It does not create or reconcile infrastructure.

func WithLocalDemoFixtureScenario 

func WithLocalDemoFixtureScenario(configuration string, scenario LocalDemoFixtureScenario) (string, error)

WithLocalDemoFixtureScenario replaces one already-declared local fixture scenario in a strict runtime role configuration. It preserves no caller supplied JSON shape: the resulting configuration is validated and encoded from the owned role document before a process can consume it.

Types

type AuditSinkConfig 

type AuditSinkConfig struct {
	Endpoint       string `json:"endpoint"`
	TimeoutSeconds int    `json:"timeout_seconds"`
}

AuditSinkConfig declares one bounded HTTPS audit-delivery capability. It contains no credentials; transport authorization is operator-owned.

type Config 

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

Config is a validated operator-owned configuration for one runtime role. It contains endpoints and environment-key references, never secret values.

func Parse 

func Parse(input io.Reader) (Config, error)

Parse decodes one strict operator role document. Application configuration such as agents, sessions, tools, or policies is deliberately not accepted here.

func (Config) DependencyEndpoint 

func (config Config) DependencyEndpoint(name string) (string, bool)

DependencyEndpoint returns one already-validated, non-secret endpoint for private composition. It deliberately does not reveal secret values.

func (Config) ListenAddress 

func (config Config) ListenAddress() string

ListenAddress returns the explicit health endpoint bind address.

func (Config) LocalDemoWorker 

func (config Config) LocalDemoWorker() *LocalDemoWorkerConfig

LocalDemoWorker returns the explicitly declared local-only fixture capability. A nil result means this role remains a health/configuration process and must not invent a provider or tool adapter.

func (Config) Namespace 

func (config Config) Namespace() string

Namespace returns the explicit Temporal and infrastructure namespace identity.

func (Config) Role 

func (config Config) Role() Role

Role returns the one trust boundary selected by this Config.

func (Config) ToolDispatch 

func (config Config) ToolDispatch() *ToolDispatchConfig

func (Config) ToolTrigger 

func (config Config) ToolTrigger() *ToolTriggerConfig

ToolTrigger returns the bounded dispatch trigger capability for RoleTool.

func (Config) Worker 

func (config Config) Worker() *WorkerConfig

Worker returns the private orchestration worker declaration when the role is codec-enabled.

type CredentialInventory 

type CredentialInventory interface {
	// KnownCredentialEnvironmentNames returns present names from the reviewed credential inventory.
	KnownCredentialEnvironmentNames(context.Context) ([]string, error)
}

CredentialInventory enumerates the known credential environment names that are present at the process boundary. It never returns credential values. Prepare requires this seam so a role cannot silently inherit another role's mounted credential.

type Dependency 

type Dependency struct {
	// Name identifies a reviewed dependency kind.
	Name string `json:"name"`
	// Endpoint is a non-secret target endpoint.
	Endpoint string `json:"endpoint"`
	// SecretEnvironment is an environment key holding an authorization value, never that value itself.
	SecretEnvironment string `json:"secret_environment,omitempty"`
}

Dependency describes one role-visible operator endpoint and optional secret environment reference.

type EnvironmentSecretSource 

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

EnvironmentSecretSource reads an already-injected process environment key. The composition root owns this adapter; domain code never reads the environment.

func NewEnvironmentSecretSource 

func NewEnvironmentSecretSource(lookup func(string) (string, bool)) (*EnvironmentSecretSource, error)

NewEnvironmentSecretSource adapts an explicit environment lookup function.

func (*EnvironmentSecretSource) KnownCredentialEnvironmentNames 

func (source *EnvironmentSecretSource) KnownCredentialEnvironmentNames(ctx context.Context) ([]string, error)

KnownCredentialEnvironmentNames enumerates present reviewed credential keys without disclosing their values.

func (*EnvironmentSecretSource) Lookup 

func (source *EnvironmentSecretSource) Lookup(_ context.Context, environment string) (string, bool, error)

Lookup resolves one secret environment value at process composition time.

type LocalDemoFixtureScenario 

type LocalDemoFixtureScenario string

LocalDemoFixtureScenario identifies one finite, declared local Stack evidence plan. It is not a caller-controlled runtime value. 

const (
	// LocalDemoFixtureScenarioWorkspaceApprovalReset keeps the normal Approval
	// lifetime for local reset/reconnect evidence.
	LocalDemoFixtureScenarioWorkspaceApprovalReset LocalDemoFixtureScenario = "workspace-approval-reset-v1"
	// LocalDemoFixtureScenarioWorkspaceApprovalExpiry uses the bounded local
	// lifetime required to prove a pending Approval's late-decision refusal.
	LocalDemoFixtureScenarioWorkspaceApprovalExpiry LocalDemoFixtureScenario = "workspace-approval-expiry-v1"
)

func ParseLocalDemoFixtureScenario 

func ParseLocalDemoFixtureScenario(value string) (LocalDemoFixtureScenario, error)

ParseLocalDemoFixtureScenario validates one explicit local-only fixture plan.

type LocalDemoWorkerConfig 

type LocalDemoWorkerConfig struct {
	Enabled bool   `json:"enabled"`
	Mode    string `json:"mode"`
	// Fixture identifies the one reviewed local behavior. It is deliberately
	// not inferred from an Agent, Tenant, prompt, or Tool name.
	Fixture string `json:"fixture"`
	// FixtureScenario selects one finite, declared local-only evidence plan.
	// It is never inferred from a prompt, Stack name, or runtime object.
	FixtureScenario             LocalDemoFixtureScenario `json:"fixture_scenario"`
	StateDSNEnvironment         string                   `json:"state_dsn_environment"`
	ContentEndpoint             string                   `json:"content_endpoint"`
	ContentAccessKeyEnvironment string                   `json:"content_access_key_environment"`
	ContentSecretKeyEnvironment string                   `json:"content_secret_key_environment"`
	ContentBucket               string                   `json:"content_bucket"`
}

LocalDemoWorkerConfig declares the intentionally deterministic local Stack fixture used for end-to-end topology evidence. It is not a provider profile, accepts no production credential, and is rejected outside the model/tool process roles.

type Plan 

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

Plan is a secret-safe prepared process composition. Secret values remain private.

func Prepare 

func Prepare(ctx context.Context, config Config, source SecretSource) (Plan, error)

Prepare verifies only the credentials the selected role is entitled to use.

func (Plan) Role 

func (plan Plan) Role() Role

Role returns the prepared process trust boundary.

func (Plan) SecretEnvironmentNames 

func (plan Plan) SecretEnvironmentNames() []string

SecretEnvironmentNames returns the reviewed secret environment names, never values.

func (Plan) String 

func (plan Plan) String() string

String returns a safe diagnostic summary that intentionally excludes endpoints and secrets.

type Role 

type Role string

Role identifies one independently deployed, trust-scoped runtime process. 

const (
	// RoleAPI serves the public runtime contract without direct infrastructure credentials.
	RoleAPI Role = "api"
	// RoleOrchestration coordinates state and Temporal work without model or tool credentials.
	RoleOrchestration Role = "orchestration"
	// RoleOrchestrationCodec runs private Session workflows with a payload-codec-only blob capability.
	RoleOrchestrationCodec Role = "orchestration-codec"
	// RoleModel invokes a configured model with only model and conversation authority.
	RoleModel Role = "model"
	// RoleTool executes policy-authorized tools with narrow tool authority.
	RoleTool Role = "tool"
	// RoleToolDispatch owns the private broker worker and its declared control adapter.
	RoleToolDispatch Role = "tool-dispatch"
	// RoleBlob serves the immutable blob plane with storage authority.
	RoleBlob Role = "blob"
	// RoleCodec provides the inspection-only Temporal UI codec endpoint.
	RoleCodec Role = "codec"
	// RoleSandboxControl coordinates enrolled sandbox hosts.
	RoleSandboxControl Role = "sandbox-control"
	// RoleSandboxHost runs an enrolled sandbox host agent.
	RoleSandboxHost Role = "sandbox-host"
)

type SecretSource 

type SecretSource interface {
	// Lookup returns the value and its presence for one environment variable.
	Lookup(context.Context, string) (string, bool, error)
}

SecretSource resolves an environment name only at the process composition boundary. Implementations must never return secret material through diagnostics.

type ToolDispatchConfig 

type ToolDispatchConfig struct {
	ContentEndpoint              string `json:"content_endpoint"`
	ContentBucket                string `json:"content_bucket"`
	ContentAccessKeyEnvironment  string `json:"content_access_key_environment"`
	ContentSecretKeyEnvironment  string `json:"content_secret_key_environment"`
	ControlServerName            string `json:"control_server_name"`
	ControlTrustBundleRef        string `json:"control_trust_bundle_ref"`
	ControlTrustBundlePath       string `json:"control_trust_bundle_path"`
	ControlCredentialEnvironment string `json:"control_credential_environment"`
	ServerName                   string `json:"server_name"`
	ServerCertificatePath        string `json:"server_certificate_path"`
	ServerPrivateKeyPath         string `json:"server_private_key_path"`
	PeerPolicy                   string `json:"peer_policy"`
}

ToolDispatchConfig declares the bounded private content and authenticated sandbox-control capabilities of the broker-owned dispatch process.

type ToolTriggerConfig 

type ToolTriggerConfig struct {
	ServerName      string `json:"server_name"`
	TrustBundleRef  string `json:"trust_bundle_ref"`
	TrustBundlePath string `json:"trust_bundle_path"`
	IntervalSeconds int    `json:"interval_seconds"`
}

ToolTriggerConfig declares the distinct trust bundle held by RoleTool to invoke the dispatch service. It deliberately contains no worker authority.

type WorkerConfig 

type WorkerConfig struct {
	TaskQueue                   string `json:"task_queue"`
	PayloadBlobEndpoint         string `json:"payload_blob_endpoint"`
	PayloadBlobBucket           string `json:"payload_blob_bucket"`
	PayloadBlobPrefix           string `json:"payload_blob_prefix"`
	PayloadAccessKeyEnvironment string `json:"payload_access_key_environment"`
	PayloadSecretKeyEnvironment string `json:"payload_secret_key_environment"`
	// AuditSink is an optional operator-owned HTTPS delivery endpoint for
	// already-committed audit facts. Leaving it absent preserves the base
	// worker's no-mandatory-external-sink behavior.
	AuditSink *AuditSinkConfig `json:"audit_sink,omitempty"`
}

WorkerConfig declares the non-secret payload-codec capability and finite task queue of one private worker.

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.
⌂ 换网址