gateway

package
v0.3.0-beta.11 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package gateway owns durable exposure policy and reconciliation contracts.

Index

Constants

View Source
const (
	EndpointStable    EndpointStability = "stable"
	EndpointEphemeral EndpointStability = "ephemeral"

	// EndpointSchemePolicyTailnetInternal allows a private-tier URI scheme over verified TLS.
	EndpointSchemePolicyTailnetInternal EndpointSchemePolicy = "tailnet_internal"
)
View Source
const ChallengePathPrefix = "/.well-known/compozy/gateway-challenge/"

ChallengePathPrefix is mounted only on private and public tier listeners.

View Source
const DefaultStreamTicketLimit = 256

DefaultStreamTicketLimit bounds live single-use tickets held by one daemon process.

View Source
const (
	// IngressEnablePath is the operator API path used to enable public ingress.
	IngressEnablePath = "/api/gateway/surfaces"
)
View Source
const ProviderInstallSourceBundled = "bundled"

Variables

View Source
var (
	// ErrEndpointUnverified reports that a provider endpoint did not prove the assigned tier.
	ErrEndpointUnverified = errors.New("gateway endpoint unverified")
	// ErrProviderDegraded reports that an active connectivity provider is unhealthy.
	ErrProviderDegraded = errors.New("gateway provider degraded")
)
View Source
var (
	// ErrDeviceUnauthenticated masks unknown, malformed, mismatched, and revoked credentials.
	ErrDeviceUnauthenticated = errors.New("gateway device unauthenticated")
	// ErrDeviceNotFound reports a device identifier outside the operator inventory.
	ErrDeviceNotFound = errors.New("gateway device not found")
	// ErrDeviceRevoked reports an epoch fence invalidated by revocation.
	ErrDeviceRevoked = errors.New("gateway device revoked")
	// ErrPairingInvalid masks malformed and unknown pairing artifacts.
	ErrPairingInvalid = errors.New("gateway pairing invalid")
	// ErrPairingExpired reports a known artifact whose TTL elapsed.
	ErrPairingExpired = errors.New("gateway pairing expired")
	// ErrPairingSpent reports a known artifact that already admitted one device.
	ErrPairingSpent = errors.New("gateway pairing spent")
	// ErrPairingLimit reports that the bounded pending-artifact set is full.
	ErrPairingLimit = errors.New("gateway pairing limit reached")
	// ErrPairingForbidden reports an attempt to mint or redeem from an untrusted tier.
	ErrPairingForbidden = errors.New("gateway pairing forbidden")
	// ErrStreamTicketInvalid masks unknown, malformed, expired, spent, and revoked-device tickets.
	ErrStreamTicketInvalid = errors.New("gateway stream ticket invalid")
	// ErrStreamTicketLimit reports that the bounded live-ticket set is full.
	ErrStreamTicketLimit = errors.New("gateway stream ticket limit reached")
	// ErrAuthRateLimited reports too many failed authentication attempts from one source.
	ErrAuthRateLimited = errors.New("gateway authentication rate limited")
	// ErrProviderTrustStale reports that a persisted provider confirmation no longer matches the live registry.
	ErrProviderTrustStale = errors.New("gateway provider trust stale")
	// ErrProviderNotFound reports a provider name outside the active tier inventory.
	ErrProviderNotFound = errors.New("gateway provider not found")
	// ErrDigestConfirmationRequired reports a provider control digest awaiting operator consent.
	ErrDigestConfirmationRequired = errors.New("gateway digest confirmation required")
	// ErrIngressSubjectNotFound reports an unknown webhook or bridge ingress subject.
	ErrIngressSubjectNotFound = errors.New("gateway ingress subject not found")
	// ErrIngressTargetUnavailable reports a subject whose daemon-local ingress target is invalid.
	ErrIngressTargetUnavailable = errors.New("gateway ingress target unavailable")
	// ErrIngressForbidden reports an ingress mutation outside the caller's workspace boundary.
	ErrIngressForbidden = errors.New("gateway ingress forbidden")
	// ErrIngressRateLimited reports a public sender exceeding one endpoint/source budget.
	ErrIngressRateLimited = errors.New("gateway ingress rate limited")
	// ErrLocalOnlyOperation reports an operation unavailable through a remote profile.
	ErrLocalOnlyOperation = errors.New("gateway local-only operation")
)
View Source
var (
	// ErrExposureRefused reports a fail-closed policy refusal.
	ErrExposureRefused = errors.New("gateway exposure refused")
	// ErrConsentRequired reports that public operator UI consent is missing.
	ErrConsentRequired = errors.New("gateway consent required")
	// ErrGenerationConflict reports an optimistic concurrency conflict.
	ErrGenerationConflict = errors.New("gateway generation conflict")
	// ErrStaleGeneration reports that an external effect completed for obsolete intent.
	ErrStaleGeneration = errors.New("gateway stale generation")
	// ErrTierProviderConflict reports that a tier already has an enabled provider.
	ErrTierProviderConflict = errors.New("gateway tier already has an enabled provider")
)

Functions

func ContextWithDevice

func ContextWithDevice(ctx context.Context, device DeviceSession) context.Context

ContextWithDevice carries the authenticated identity and its revocation fence.

func GenerateDeviceCredential

func GenerateDeviceCredential() (string, error)

GenerateDeviceCredential creates a client-owned gateway credential.

func IsDeviceCredential

func IsDeviceCredential(value string) bool

IsDeviceCredential reports whether a value has the canonical gateway device credential shape.

func ProviderChannelScope

func ProviderChannelScope(tier Tier) string

ProviderChannelScope returns the manifest scope that authorizes one gateway tier.

func ReleaseMutation

func ReleaseMutation(ctx context.Context)

ReleaseMutation releases the authenticated mutation lease carried by ctx.

func WithIngressReadWorkspace

func WithIngressReadWorkspace(ctx context.Context, workspaceID string) context.Context

WithIngressReadWorkspace scopes binding projections to one validated agent workspace.

Types

type ActorKind

type ActorKind string

ActorKind identifies the operator client represented by a device session.

const (
	ActorKindOperatorDevice ActorKind = "operator_device"
	ActorKindCLIProfile     ActorKind = "cli_profile"
)

type AddressStatus

type AddressStatus struct {
	Tier    Tier
	Address string
	Live    bool
}

AddressStatus exposes only verified runtime addresses as live.

type AdmissionController

type AdmissionController interface {
	Acquire(Tier, Surface) (func(), error)
}

AdmissionController rejects new tier requests while reachability is not live and returns a release function for each admitted request.

type AdvertisedEndpoint

type AdvertisedEndpoint struct {
	URL          string
	Scheme       string
	SchemePolicy EndpointSchemePolicy
	Stability    EndpointStability
}

AdvertisedEndpoint is one untrusted provider endpoint pending core verification.

func (AdvertisedEndpoint) Validate

func (e AdvertisedEndpoint) Validate() error

Validate checks the provider-owned descriptor without performing network I/O.

type AuditAuthPosture

type AuditAuthPosture struct {
	Mode              string
	RequiredRemotely  bool
	ActiveDeviceCount int
}

AuditAuthPosture describes the authentication boundary without exposing credentials.

type AuditDeviceHighlights

type AuditDeviceHighlights struct {
	Active         int
	Revoked        int
	Stale          int
	RecentlyPaired int
	StaleDeviceIDs []string
}

AuditDeviceHighlights summarizes inventory signals used during routine review.

type AuditFinding

type AuditFinding struct {
	ID          string
	Severity    AuditSeverity
	Summary     string
	Remediation string
	Tier        Tier
	Resource    string
}

AuditFinding is one stable, machine-actionable gateway posture finding.

type AuditReport

type AuditReport struct {
	Ran              bool
	NoFindings       bool
	LocalOnly        bool
	Status           Status
	Auth             AuditAuthPosture
	DeviceHighlights AuditDeviceHighlights
	Findings         []AuditFinding
}

AuditReport is the side-effect-free result of one completed gateway audit.

type AuditSeverity

type AuditSeverity string

AuditSeverity ranks one actionable gateway posture finding.

const (
	AuditSeverityCritical AuditSeverity = "critical"
	AuditSeverityError    AuditSeverity = "error"
	AuditSeverityWarning  AuditSeverity = "warning"
	AuditSeverityInfo     AuditSeverity = "info"
)

type AuthFailureLimiter

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

AuthFailureLimiter bounds failed remote authentication attempts per transport source.

func NewAuthFailureLimiter

func NewAuthFailureLimiter(maximum int, window time.Duration, now func() time.Time) *AuthFailureLimiter

func (*AuthFailureLimiter) Allow

func (l *AuthFailureLimiter) Allow(source string, localOperator bool) bool

Allow reports whether a source may attempt authentication. Local operator traffic is exempt.

func (*AuthFailureLimiter) Failure

func (l *AuthFailureLimiter) Failure(source string, localOperator bool)

Failure records one failed remote authentication attempt.

func (*AuthFailureLimiter) Reconfigure

func (l *AuthFailureLimiter) Reconfigure(maximum int, window time.Duration) error

Reconfigure applies new authentication limits without replacing active HTTP handlers.

func (*AuthFailureLimiter) Success

func (l *AuthFailureLimiter) Success(source string)

Success clears failures after a source proves possession of a valid credential.

type AuthGate

type AuthGate interface {
	Active(context.Context) (bool, error)
}

AuthGate reports whether the gateway authentication model is ready.

type AuthGateFunc

type AuthGateFunc func(context.Context) (bool, error)

AuthGateFunc adapts a function to AuthGate.

func (AuthGateFunc) Active

func (f AuthGateFunc) Active(ctx context.Context) (bool, error)

Active implements AuthGate.

type ChallengeRegistry

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

ChallengeRegistry owns the single active verification challenge for each tier listener.

func NewChallengeRegistry

func NewChallengeRegistry() *ChallengeRegistry

NewChallengeRegistry constructs a cryptographically random tier challenge registry.

func (*ChallengeRegistry) Begin

func (r *ChallengeRegistry) Begin(tier Tier) (path string, nonce string, cleanup func(), err error)

Begin replaces the current challenge for one tier and returns an ownership-safe cleanup.

func (*ChallengeRegistry) Resolve

func (r *ChallengeRegistry) Resolve(tier Tier, path string) (string, bool)

Resolve returns the exact nonce only for the active path on the assigned tier.

type ChallengeResolver

type ChallengeResolver interface {
	Resolve(Tier, string) (string, bool)
}

ChallengeResolver resolves an active nonce without exposing mutation methods to transports.

type ConnectionRegistry

type ConnectionRegistry interface {
	Register(string, context.CancelFunc) uint64
	RegisterWaitable(string, context.CancelFunc, <-chan struct{}) uint64
	Deregister(string, uint64)
	CancelDevice(context.Context, string) (int, error)
}

ConnectionRegistry owns cancel functions for live device streams.

type ConnectivitySource

type ConnectivitySource interface {
	Establish(context.Context, EstablishRequest) (Reachability, error)
	Status(context.Context, Tier) (Reachability, error)
	Teardown(context.Context, Tier, time.Time) error
}

ConnectivitySource is the daemon-owned consumer contract for one extension provider.

type ConnectivitySourceResolver

type ConnectivitySourceResolver interface {
	ResolveConnectivitySource(context.Context, string) (ConnectivitySource, error)
}

ConnectivitySourceResolver resolves exactly one globally installed provider by name.

type DesiredState

type DesiredState string

DesiredState records operator intent.

const (
	DesiredEnabled  DesiredState = "enabled"
	DesiredDisabled DesiredState = "disabled"
)

func (DesiredState) Validate

func (s DesiredState) Validate() error

Validate reports unsupported desired states.

type DeviceAuthenticator

type DeviceAuthenticator interface {
	Authenticate(context.Context, string) (DeviceSession, error)
	ConsumeStreamTicket(context.Context, string) (DeviceSession, error)
	AcquireMutation(context.Context, string, uint64) (context.Context, error)
	RevalidateForCommit(context.Context, string, uint64) error
}

DeviceAuthenticator authenticates request credentials and single-use stream tickets.

type DeviceService

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

DeviceService owns pairing, authentication, device inventory, tickets, and live revocation.

func NewDeviceService

func NewDeviceService(store DeviceStore, opts ...DeviceServiceOption) (*DeviceService, error)

func (*DeviceService) AcquireMutation

func (s *DeviceService) AcquireMutation(
	ctx context.Context,
	deviceID string,
	epoch uint64,
) (context.Context, error)

AcquireMutation admits one remote mutation and carries its revocation-aware lease in the returned context.

func (*DeviceService) Active

func (s *DeviceService) Active(context.Context) (bool, error)

Active reports that the daemon initialized the authentication authority.

func (*DeviceService) Authenticate

func (s *DeviceService) Authenticate(ctx context.Context, credential string) (DeviceSession, error)

func (*DeviceService) Connections

func (s *DeviceService) Connections() ConnectionRegistry

func (*DeviceService) ConsumeStreamTicket

func (s *DeviceService) ConsumeStreamTicket(ctx context.Context, ticket string) (DeviceSession, error)

func (*DeviceService) ListDevices

func (s *DeviceService) ListDevices(ctx context.Context) ([]DeviceSession, error)

func (*DeviceService) MintPairing

func (*DeviceService) MintStreamTicket

func (s *DeviceService) MintStreamTicket(ctx context.Context, deviceID string) (StreamTicket, error)

func (*DeviceService) ReconfigureLimits

func (s *DeviceService) ReconfigureLimits(
	pairingMaxPending int,
	pairingTTL time.Duration,
	streamTicketTTL time.Duration,
) error

ReconfigureLimits applies live pairing and stream-ticket limits to new artifacts.

func (*DeviceService) RedeemPairing

func (s *DeviceService) RedeemPairing(ctx context.Context, req RedeemRequest) (IssuedCredential, error)

func (*DeviceService) RenameDevice

func (s *DeviceService) RenameDevice(ctx context.Context, deviceID, name string) (DeviceSession, error)

func (*DeviceService) RevalidateForCommit

func (s *DeviceService) RevalidateForCommit(ctx context.Context, deviceID string, epoch uint64) error

func (*DeviceService) RevokeDevice

func (s *DeviceService) RevokeDevice(ctx context.Context, deviceID string) (RevokeResult, error)

type DeviceServiceOption

type DeviceServiceOption func(*deviceServiceConfig) error

func WithConnectionRegistry

func WithConnectionRegistry(registry ConnectionRegistry) DeviceServiceOption

func WithDeviceClock

func WithDeviceClock(now func() time.Time) DeviceServiceOption

func WithDeviceEntropy

func WithDeviceEntropy(entropy io.Reader) DeviceServiceOption

func WithPairingLimits

func WithPairingLimits(maxPending int, ttl time.Duration) DeviceServiceOption

func WithStreamTicketLimits

func WithStreamTicketLimits(maxEntries int, ttl time.Duration) DeviceServiceOption

type DeviceSession

type DeviceSession struct {
	ID            string
	Name          string
	ActorKind     ActorKind
	PairingOrigin string
	RevokeEpoch   uint64
	CreatedAt     time.Time
	LastSeenAt    time.Time
	RevokedAt     time.Time
}

DeviceSession is the non-secret device state used by status projection.

func DeviceFromContext

func DeviceFromContext(ctx context.Context) (DeviceSession, bool)

DeviceFromContext returns the device authenticated by the transport.

type DeviceStore

type DeviceStore interface {
	CreateDevice(context.Context, StoredDeviceSession) error
	FindDeviceByTokenHash(context.Context, string, time.Time) (StoredDeviceSession, error)
	ListDevices(context.Context) ([]DeviceSession, error)
	GetDevice(context.Context, string) (DeviceSession, error)
	RenameDevice(context.Context, string, string) (DeviceSession, error)
	RenameDeviceForActor(context.Context, string, uint64, string, string) (DeviceSession, error)
	RevokeDevice(context.Context, string, time.Time) (DeviceSession, bool, error)
	RevokeDeviceForActor(context.Context, string, uint64, string, time.Time) (DeviceSession, bool, error)
	RevalidateDeviceEpoch(context.Context, string, uint64) error
}

DeviceStore owns durable device-session transitions.

type EffectDriver

EffectDriver performs daemon-owned and provider-owned external effects.

type EndpointSchemePolicy

type EndpointSchemePolicy string

EndpointSchemePolicy declares a trusted transport policy for a provider-owned scheme.

type EndpointStability

type EndpointStability string

EndpointStability describes whether a provider endpoint is expected to survive restarts.

func (EndpointStability) Validate

func (s EndpointStability) Validate() error

Validate reports unsupported endpoint stability values.

type EndpointVerification

type EndpointVerification interface {
	Verify(context.Context, Tier, AdvertisedEndpoint, string, string) error
	Timeout() time.Duration
}

EndpointVerification is the core-owned proof boundary used by provider supervision.

type EndpointVerifier

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

EndpointVerifier proves that one provider endpoint reaches the assigned tier listener.

func NewEndpointVerifier

func NewEndpointVerifier(timeout time.Duration, publicDNSResolver string) (*EndpointVerifier, error)

NewEndpointVerifier constructs a verifier with a dedicated client timeout and public DNS path.

func (*EndpointVerifier) Reconfigure

func (v *EndpointVerifier) Reconfigure(timeout time.Duration, publicDNSResolver string) error

Reconfigure applies live verification settings to future probes.

func (*EndpointVerifier) Timeout

func (v *EndpointVerifier) Timeout() time.Duration

Timeout returns the dedicated verification deadline.

func (*EndpointVerifier) Verify

func (v *EndpointVerifier) Verify(
	ctx context.Context,
	tier Tier,
	endpoint AdvertisedEndpoint,
	challengePath string,
	nonce string,
) error

Verify fetches the tier-scoped challenge and requires an exact nonce echo.

type EstablishRequest

type EstablishRequest struct {
	Tier          Tier
	ForwardTarget netip.AddrPort
	ChallengePath string
	Deadline      time.Time
}

EstablishRequest is sent to a connectivity source after the tier listener is bound.

type ExposurePlan

type ExposurePlan struct {
	Tiers []TierPlan
}

ExposurePlan groups the desired state by independently reconciled tier.

type IngressBindRequest

type IngressBindRequest struct {
	Subject   IngressSubjectRef
	Confirmed bool
	Caller    *IngressCaller
}

IngressBindRequest confirms one subject against the currently verified endpoint.

type IngressBinding

type IngressBinding struct {
	Subject            IngressSubjectRef
	Scope              IngressScopeKind
	WorkspaceID        string
	EndpointGeneration uint64
	ConfirmedAt        time.Time
	Changed            bool
}

IngressBinding is one durable subject confirmation.

type IngressBindingStatus

type IngressBindingStatus = IngressProjection

IngressBindingStatus is the operator status projection for a durable binding.

type IngressCaller

type IngressCaller struct {
	SessionID   string
	WorkspaceID string
	AgentName   string
}

IngressCaller is a daemon-validated agent identity. A nil caller is the local operator.

type IngressEndpointState

type IngressEndpointState struct {
	Tier       Tier
	URL        string
	Generation uint64
	Reachable  bool
	UpdatedAt  time.Time
}

IngressEndpointState tracks the verified address independently from desired-state fencing.

type IngressEventSink

type IngressEventSink interface {
	RecordIngressBound(context.Context, IngressMutationEvent) error
	RecordIngressUnbound(context.Context, IngressMutationEvent) error
}

IngressEventSink records durable binding lifecycle events.

type IngressMutationEvent

type IngressMutationEvent struct {
	Binding   IngressBinding
	ActorKind string
	ActorID   string
}

IngressMutationEvent carries one binding change and its validated actor attribution.

type IngressProjection

type IngressProjection struct {
	Subject                     IngressSubjectRef
	Scope                       IngressScopeKind
	WorkspaceID                 string
	URL                         string
	Reachability                IngressReachability
	EndpointGeneration          uint64
	ConfirmedEndpointGeneration uint64
	ConfirmedAt                 time.Time
	EnablePath                  string
}

IngressProjection is safe to expose through trigger, bridge, and status APIs.

type IngressRateLimiter

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

IngressRateLimiter bounds public requests independently for each endpoint and transport source.

func NewIngressRateLimiter

func NewIngressRateLimiter(maximum int, window time.Duration, now func() time.Time) *IngressRateLimiter

NewIngressRateLimiter constructs a bounded fixed-window limiter.

func (*IngressRateLimiter) Allow

func (l *IngressRateLimiter) Allow(endpoint string, source string) (bool, time.Duration)

Allow consumes one request budget and returns retry guidance when denied.

type IngressReachability

type IngressReachability string

IngressReachability is the honest public projection for one subject.

const (
	IngressReachabilityOff            IngressReachability = "off"
	IngressReachabilityUnconfirmed    IngressReachability = "unconfirmed"
	IngressReachabilityLive           IngressReachability = "live"
	IngressReachabilityBroken         IngressReachability = "broken"
	IngressReachabilityReconfirmation IngressReachability = "reconfirmation_required"
)

type IngressScopeKind

type IngressScopeKind string

IngressScopeKind is the server-resolved ownership scope of an ingress subject.

const (
	IngressScopeGlobal    IngressScopeKind = "global"
	IngressScopeWorkspace IngressScopeKind = "workspace"
)

type IngressStore

type IngressStore interface {
	ResolveIngressSubject(context.Context, IngressSubjectRef) (IngressSubject, error)
	GetIngressEndpoint(context.Context, Tier) (IngressEndpointState, error)
	SyncIngressEndpoint(context.Context, Tier, string, time.Time) (IngressEndpointState, bool, error)
	MarkIngressEndpointUnavailable(context.Context, Tier, time.Time) error
	GetIngressBinding(context.Context, IngressSubjectRef) (IngressBinding, error)
	PutIngressBinding(
		context.Context,
		IngressSubject,
		uint64,
		time.Time,
	) (IngressBinding, bool, error)
	DeleteIngressBinding(context.Context, IngressSubject) (bool, error)
	ListIngressBindings(context.Context) ([]IngressBinding, error)
	SweepOrphanedIngressBindings(context.Context) (int64, error)
}

IngressStore owns public endpoint identity and workspace-aware subject bindings.

type IngressSubject

type IngressSubject struct {
	IngressSubjectRef
	Scope             IngressScopeKind
	WorkspaceID       string
	Path              string
	TargetUnavailable bool
}

IngressSubject is trusted ownership and routing metadata resolved by the server.

type IngressSubjectKind

type IngressSubjectKind string

IngressSubjectKind identifies a resource that can receive public callbacks.

const (
	IngressSubjectWebhookTrigger IngressSubjectKind = "webhook_trigger"
	IngressSubjectBridgeInstance IngressSubjectKind = "bridge_instance"
)

func (IngressSubjectKind) Validate

func (k IngressSubjectKind) Validate() error

type IngressSubjectRef

type IngressSubjectRef struct {
	Kind IngressSubjectKind
	ID   string
}

IngressSubjectRef identifies one bindable webhook trigger or bridge instance.

func (IngressSubjectRef) Validate

func (r IngressSubjectRef) Validate() error

type IngressUnbindRequest

type IngressUnbindRequest struct {
	Subject IngressSubjectRef
	Caller  *IngressCaller
}

IngressUnbindRequest removes one binding after the same ownership authorization.

type IssuedCredential

type IssuedCredential struct {
	Device     DeviceSession
	Credential string
}

IssuedCredential contains the only server response that may carry a raw device credential.

type LiveConnectionRegistry

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

LiveConnectionRegistry indexes live stream cancellation by durable device ID.

func NewConnectionRegistry

func NewConnectionRegistry() *LiveConnectionRegistry

func (*LiveConnectionRegistry) CancelDevice

func (r *LiveConnectionRegistry) CancelDevice(ctx context.Context, deviceID string) (int, error)

func (*LiveConnectionRegistry) Deregister

func (r *LiveConnectionRegistry) Deregister(deviceID string, handle uint64)

func (*LiveConnectionRegistry) Register

func (r *LiveConnectionRegistry) Register(deviceID string, cancel context.CancelFunc) uint64

func (*LiveConnectionRegistry) RegisterWaitable

func (r *LiveConnectionRegistry) RegisterWaitable(
	deviceID string,
	cancel context.CancelFunc,
	done <-chan struct{},
) uint64

RegisterWaitable adds a completion signal so revocation can wait for stream teardown.

type Option

type Option func(*policy)

Option customizes Policy construction.

func WithAuthGate

func WithAuthGate(gate AuthGate) Option

WithAuthGate supplies the authentication readiness authority.

func WithClock

func WithClock(now func() time.Time) Option

WithClock supplies a deterministic clock.

type PairingArtifact

type PairingArtifact struct {
	Artifact  string
	ExpiresAt time.Time
}

PairingArtifact is returned only to the already-trusted minting caller.

type PairingRequest

type PairingRequest struct {
	Source PairingSource
}

PairingRequest asks a trusted surface to mint a one-time artifact.

type PairingSource

type PairingSource string

PairingSource is the listener trust boundary for pairing operations.

const (
	PairingSourceLocal   PairingSource = "local"
	PairingSourcePrivate PairingSource = "private"
	PairingSourcePublic  PairingSource = "public"
)

type Policy

type Policy interface {
	Plan(context.Context) (ExposurePlan, error)
	Transition(context.Context, TransitionRequest) (Status, error)
	Reconcile(context.Context) (Status, error)
	SetEnabled(context.Context, bool) error
	Status(context.Context) (Status, error)
	Acquire(Tier, Surface) (func(), error)
	Close(context.Context) error
}

Policy is the gateway exposure authority used by the daemon composition root.

func NewPolicy

func NewPolicy(store Store, effects EffectDriver, enabled bool, options ...Option) (Policy, error)

NewPolicy constructs the durable gateway exposure policy.

type ProviderActivation

type ProviderActivation struct {
	ProviderName string
	Tier         Tier
	Desired      DesiredState
	Observed     ProviderObservedState
	Generation   uint64
	LastHealthAt time.Time
	LastError    string
}

ProviderActivation is the durable desired/observed provider state for one tier.

type ProviderAuditSink

type ProviderAuditSink interface {
	RecordProviderRefusal(context.Context, ProviderActivation, ProviderRefusalKind, error) error
	RecordEndpointVerified(context.Context, ProviderActivation, AdvertisedEndpoint) error
	RecordProviderStateChanged(context.Context, ProviderActivation, ProviderObservedState, string) error
}

ProviderAuditSink durably records provider verification decisions at the owning transition.

type ProviderDegradationHandler

type ProviderDegradationHandler func(context.Context, ProviderActivation, error) error

ProviderDegradationHandler removes one generation's advertisement and records a redacted failure.

type ProviderDegradationSource

type ProviderDegradationSource interface {
	SetProviderDegradationHandler(ProviderDegradationHandler)
}

ProviderDegradationSource publishes supervised provider outages to the reconciler.

type ProviderEnableRequest

type ProviderEnableRequest struct {
	Provider           ProviderIdentity
	Tier               Tier
	ExpectedGeneration uint64
}

ProviderEnableRequest enables a registry-derived provider identity for one tier.

type ProviderHealth

type ProviderHealth string

ProviderHealth describes provider reachability without exposing secrets.

const (
	HealthDown     ProviderHealth = "down"
	HealthHealthy  ProviderHealth = "healthy"
	HealthDegraded ProviderHealth = "degraded"
)

type ProviderIdentity

type ProviderIdentity struct {
	Name            string
	InstallSource   string
	DigestConfirmed string
	ConfirmedAt     time.Time
}

ProviderIdentity records live-registry provider identity at transition time.

func (ProviderIdentity) Validate

func (p ProviderIdentity) Validate() error

Validate ensures a provider identity can be persisted safely.

type ProviderIdentityStore

type ProviderIdentityStore interface {
	ProviderIdentity(context.Context, string) (ProviderIdentity, error)
}

ProviderIdentityStore reads the separate gateway consent row without trusting it as live evidence.

type ProviderObservedState

type ProviderObservedState string

ProviderObservedState records the last reconciled provider state.

const (
	ProviderDown         ProviderObservedState = "down"
	ProviderEstablishing ProviderObservedState = "establishing"
	ProviderUp           ProviderObservedState = "up"
	ProviderDegraded     ProviderObservedState = "degraded"
)

type ProviderPreflight

type ProviderPreflight interface {
	PreflightProvider(context.Context, ProviderActivation) error
}

ProviderPreflight validates live provider authority before existing reachability is disturbed.

type ProviderRefusalKind

type ProviderRefusalKind string

ProviderRefusalKind identifies which provider boundary refused the attempt.

const (
	ProviderRefusalAuthority ProviderRefusalKind = "authority"
	ProviderRefusalEndpoint  ProviderRefusalKind = "endpoint"
)

type ProviderStateReporter

type ProviderStateReporter interface {
	RecordProviderStateChanged(context.Context, ProviderActivation, ProviderObservedState, string) error
}

ProviderStateReporter records reconciled provider lifecycle changes.

type ProviderStatus

type ProviderStatus struct {
	Name       string
	Tier       Tier
	Desired    DesiredState
	Observed   ProviderObservedState
	Generation uint64
	Health     ProviderHealth
	Cause      string
}

ProviderStatus exposes provider health for one tier.

type ProviderSupervisor

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

ProviderSupervisor adapts extension connectivity services to the reconciler effect boundary.

func NewProviderSupervisor

func NewProviderSupervisor(
	resolver ConnectivitySourceResolver,
	trust ProviderTrustResolver,
	identities ProviderIdentityStore,
	challenges *ChallengeRegistry,
	verifier EndpointVerification,
	options ...ProviderSupervisorOption,
) (*ProviderSupervisor, error)

NewProviderSupervisor constructs the trust-first provider lifecycle adapter.

func (*ProviderSupervisor) Advertise

func (s *ProviderSupervisor) Advertise(
	_ context.Context,
	reachability Reachability,
	_ []Surface,
) error

Advertise commits verified reachability and starts bounded health supervision.

func (*ProviderSupervisor) Bind

Bind and Unbind are daemon-listener effects and deliberately unavailable on the provider adapter.

func (*ProviderSupervisor) Establish

func (s *ProviderSupervisor) Establish(
	ctx context.Context,
	activation ProviderActivation,
	bound netip.AddrPort,
) (result Reachability, resultErr error)

Establish authorizes the exact live artifact before resolving or calling its process.

func (*ProviderSupervisor) PreflightProvider

func (s *ProviderSupervisor) PreflightProvider(ctx context.Context, activation ProviderActivation) error

PreflightProvider re-derives authority before the reconciler withdraws prior reachability.

func (*ProviderSupervisor) RecordProviderStateChanged

func (s *ProviderSupervisor) RecordProviderStateChanged(
	ctx context.Context,
	activation ProviderActivation,
	state ProviderObservedState,
	cause string,
) error

RecordProviderStateChanged forwards the reconciler-owned lifecycle transition to the audit sink.

func (*ProviderSupervisor) SetProviderDegradationHandler

func (s *ProviderSupervisor) SetProviderDegradationHandler(handler ProviderDegradationHandler)

SetProviderDegradationHandler wires the supervisor to runtime withdrawal.

func (*ProviderSupervisor) Teardown

func (s *ProviderSupervisor) Teardown(ctx context.Context, activation ProviderActivation) error

Teardown stops supervision and bounds the provider's cooperative cleanup.

func (*ProviderSupervisor) Unbind

func (*ProviderSupervisor) Verify

func (s *ProviderSupervisor) Verify(ctx context.Context, reachability Reachability) error

Verify proves every endpoint reaches the active challenge on the assigned tier.

func (*ProviderSupervisor) Withdraw

func (s *ProviderSupervisor) Withdraw(ctx context.Context, tier Tier) error

Withdraw stops accepting health state before teardown removes provider forwarding.

type ProviderSupervisorOption

type ProviderSupervisorOption func(*ProviderSupervisor)

ProviderSupervisorOption customizes bounded lifecycle timing.

func WithProviderAuditSink

func WithProviderAuditSink(audit ProviderAuditSink) ProviderSupervisorOption

WithProviderAuditSink installs the durable provider contract audit boundary.

func WithProviderEstablishTimeout

func WithProviderEstablishTimeout(timeout time.Duration) ProviderSupervisorOption

WithProviderEstablishTimeout installs the bound for one provider activation.

func WithProviderSupervisorClock

func WithProviderSupervisorClock(now func() time.Time) ProviderSupervisorOption

WithProviderSupervisorClock installs a deterministic clock.

func WithProviderSupervisorIntervals

func WithProviderSupervisorIntervals(
	healthEvery time.Duration,
	healthTimeout time.Duration,
	teardownTimeout time.Duration,
) ProviderSupervisorOption

WithProviderSupervisorIntervals installs health and teardown bounds.

func WithProviderSupervisorLogger

func WithProviderSupervisorLogger(logger *slog.Logger) ProviderSupervisorOption

WithProviderSupervisorLogger installs the structured lifecycle logger.

type ProviderTrust

type ProviderTrust struct {
	InstallSource   string
	ControlDigest   string
	ConfirmedDigest string
	ConfirmedBy     string
	ConfirmedAt     time.Time
	ChannelScopes   []string
}

ProviderTrust is re-derived from the live extension artifact before every reachability attempt.

type ProviderTrustResolver

type ProviderTrustResolver interface {
	ResolveProviderTrust(context.Context, string) (ProviderTrust, error)
}

ProviderTrustResolver derives source and control consent from the live extension registry.

type Reachability

type Reachability struct {
	Tier      Tier
	Endpoints []AdvertisedEndpoint
	Health    ProviderHealth
	Reason    string
}

Reachability is provider output that remains untrusted until verification.

type Reconciler

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

Reconciler drives durable desired state through ordered external effects.

func NewReconciler

func NewReconciler(store Store, effects EffectDriver, options ...ReconcilerOption) *Reconciler

NewReconciler constructs a serialized, generation-fenced reconciler.

func (*Reconciler) Acquire

func (r *Reconciler) Acquire(tier Tier, surface Surface) (func(), error)

Acquire admits a request only while its surface is currently advertised.

func (*Reconciler) Close

func (r *Reconciler) Close(ctx context.Context) error

Close removes reachability in reverse effect order for both tiers.

func (*Reconciler) Reconcile

func (r *Reconciler) Reconcile(ctx context.Context, plan ExposurePlan) error

Reconcile applies each tier independently in deterministic order.

func (*Reconciler) Runtime

func (r *Reconciler) Runtime() []RuntimeTier

Runtime returns a stable copy for status projection.

type ReconcilerOption

type ReconcilerOption func(*Reconciler)

ReconcilerOption customizes provider recovery behavior.

func WithProviderRecoveryBackoff

func WithProviderRecoveryBackoff(minimum time.Duration, maximum time.Duration) ReconcilerOption

WithProviderRecoveryBackoff installs bounded restart intervals.

func WithReconcilerClock

func WithReconcilerClock(now func() time.Time) ReconcilerOption

WithReconcilerClock supplies deterministic timestamps for durable endpoint state.

type RedeemRequest

type RedeemRequest struct {
	Artifact string
	Name     string
	Kind     ActorKind
	Source   PairingSource
	// Credential is optional for browser redemption. CLI callers provision it locally first.
	Credential string
}

RedeemRequest exchanges one artifact for one named device session.

type Refusal

type Refusal struct {
	Cause string
	Fix   string
}

Refusal is the latest fail-closed explanation exposed in status.

type RefusalError

type RefusalError struct {
	Cause string
	Fix   string
}

RefusalError carries an operator-readable cause and correction.

func (RefusalError) Error

func (e RefusalError) Error() string

func (RefusalError) Unwrap

func (e RefusalError) Unwrap() error

Unwrap allows callers to match ErrExposureRefused.

type RevokeResult

type RevokeResult struct {
	Device   DeviceSession
	Changed  bool
	Canceled int
}

RevokeResult distinguishes a state change from an idempotent no-op.

type RuntimeTier

type RuntimeTier struct {
	Tier       Tier
	Bound      netip.AddrPort
	Endpoints  []AdvertisedEndpoint
	Surfaces   []Surface
	Advertised bool
}

RuntimeTier is the in-memory listener and advertisement state.

type Service

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

Service composes exposure policy with device authentication for API transports.

func NewService

func NewService(policy Policy, devices *DeviceService, options ...ServiceOption) (*Service, error)

func (*Service) Acquire

func (s *Service) Acquire(tier Tier, surface Surface) (func(), error)

func (*Service) AcquireMutation

func (s *Service) AcquireMutation(ctx context.Context, deviceID string, epoch uint64) (context.Context, error)

func (*Service) Audit

func (s *Service) Audit(ctx context.Context) (AuditReport, error)

Audit reads the current posture and computes deterministic findings without mutating state.

func (*Service) Authenticate

func (s *Service) Authenticate(ctx context.Context, credential string) (DeviceSession, error)

func (*Service) BindIngress

func (s *Service) BindIngress(ctx context.Context, req IngressBindRequest) (IngressBinding, error)

func (*Service) Connections

func (s *Service) Connections() ConnectionRegistry

func (*Service) ConsumeStreamTicket

func (s *Service) ConsumeStreamTicket(ctx context.Context, ticket string) (DeviceSession, error)

func (*Service) DisableProvider

func (s *Service) DisableProvider(ctx context.Context, tier Tier, providerName string) (Status, error)

func (*Service) EnableProvider

func (s *Service) EnableProvider(ctx context.Context, req ProviderEnableRequest) (Status, error)

func (*Service) ListDevices

func (s *Service) ListDevices(ctx context.Context) ([]DeviceSession, error)

func (*Service) MintPairing

func (s *Service) MintPairing(ctx context.Context, req PairingRequest) (PairingArtifact, error)

func (*Service) MintStreamTicket

func (s *Service) MintStreamTicket(ctx context.Context, deviceID string) (StreamTicket, error)

func (*Service) ProjectIngress

func (s *Service) ProjectIngress(ctx context.Context, ref IngressSubjectRef) (IngressProjection, error)

func (*Service) ReconfigureDeviceLimits

func (s *Service) ReconfigureDeviceLimits(
	pairingMaxPending int,
	pairingTTL time.Duration,
	streamTicketTTL time.Duration,
) error

ReconfigureDeviceLimits applies live artifact limits to the active device service.

func (*Service) RedeemPairing

func (s *Service) RedeemPairing(ctx context.Context, req RedeemRequest) (IssuedCredential, error)

func (*Service) RenameDevice

func (s *Service) RenameDevice(ctx context.Context, deviceID, name string) (DeviceSession, error)

func (*Service) ResolveIngressSubject

func (s *Service) ResolveIngressSubject(ctx context.Context, ref IngressSubjectRef) (IngressSubject, error)

func (*Service) RevalidateForCommit

func (s *Service) RevalidateForCommit(ctx context.Context, deviceID string, epoch uint64) error

func (*Service) RevokeDevice

func (s *Service) RevokeDevice(ctx context.Context, deviceID string) (RevokeResult, error)

func (*Service) SetSurfaceExposure

func (s *Service) SetSurfaceExposure(ctx context.Context, req SurfaceExposureRequest) (Status, error)

func (*Service) Status

func (s *Service) Status(ctx context.Context) (Status, error)

func (*Service) UnbindIngress

func (s *Service) UnbindIngress(ctx context.Context, req IngressUnbindRequest) (UnbindResult, error)

type ServiceOption

type ServiceOption func(*Service) error

ServiceOption adds optional gateway capabilities to the transport facade.

func WithIngress

func WithIngress(
	store IngressStore,
	access workspaceaccess.Policy,
	events IngressEventSink,
	now func() time.Time,
) ServiceOption

WithIngress configures workspace-authorized public ingress management.

type Snapshot

type Snapshot struct {
	Providers []ProviderActivation
	Surfaces  []SurfaceExposure
	Devices   []DeviceSession
}

Snapshot is the complete operator-global durable gateway state.

type Status

type Status struct {
	Enabled   bool
	Changed   bool
	Tiers     []TierStatus
	Surfaces  []SurfaceStatus
	Providers []ProviderStatus
	Addresses []AddressStatus
	Devices   []DeviceSession
	Bindings  []IngressBindingStatus
	Refusal   *Refusal
}

Status is the user- and agent-readable gateway projection.

type Store

Store owns the atomic desired-state transitions used by Policy.

type StoredDeviceSession

type StoredDeviceSession struct {
	Session   DeviceSession
	TokenHash string
}

StoredDeviceSession is the daemon-private persistence record.

type StreamTicket

type StreamTicket struct {
	Ticket    string
	ExpiresAt time.Time
}

StreamTicket is a short-lived, single-use stream credential.

type Surface

type Surface string

Surface identifies a route inventory whose reachability is managed as a unit.

const (
	SurfaceOperatorUI     Surface = "operator_ui"
	SurfaceWebhookIngress Surface = "webhook_ingress"
)

func (Surface) Validate

func (s Surface) Validate() error

Validate reports unsupported surfaces.

type SurfaceExposure

type SurfaceExposure struct {
	Surface     Surface
	Tier        Tier
	Desired     DesiredState
	Observed    SurfaceObservedState
	Generation  uint64
	ConsentedAt time.Time
}

SurfaceExposure is the durable desired/observed surface state for one tier.

type SurfaceExposureRequest

type SurfaceExposureRequest struct {
	Surface            Surface
	Tier               Tier
	Desired            DesiredState
	ExpectedGeneration uint64
	Consent            bool
}

SurfaceExposureRequest changes one tier surface with an optimistic generation fence.

type SurfaceObservedState

type SurfaceObservedState string

SurfaceObservedState records whether a surface is actually served.

const (
	SurfaceOff SurfaceObservedState = "off"
	SurfaceOn  SurfaceObservedState = "on"
)

type SurfaceStatus

type SurfaceStatus struct {
	Surface    Surface
	Tier       Tier
	Desired    DesiredState
	Observed   SurfaceObservedState
	Generation uint64
}

SurfaceStatus exposes desired versus observed surface state.

type Tier

type Tier string

Tier identifies one independently managed reachability tier.

const (
	TierPrivate Tier = "private"
	TierPublic  Tier = "public"
)

func (Tier) Validate

func (t Tier) Validate() error

Validate reports unsupported tiers.

type TierPlan

type TierPlan struct {
	Tier     Tier
	Provider *ProviderActivation
	Surfaces []SurfaceExposure
	Enabled  bool
}

TierPlan is the desired reachability for one tier.

type TierStatus

type TierStatus struct {
	Tier            Tier
	Desired         DesiredState
	Observed        string
	ListenerAddress string
	Advertised      bool
}

TierStatus summarizes desired and runtime state for a tier.

type TransitionRequest

type TransitionRequest struct {
	Target             TransitionTarget
	Tier               Tier
	Desired            DesiredState
	ExpectedGeneration uint64
	Provider           ProviderIdentity
	Surface            Surface
	Consent            bool
}

TransitionRequest changes one provider activation or surface exposure row.

type TransitionTarget

type TransitionTarget string

TransitionTarget identifies exactly one durable state row.

const (
	TargetProvider TransitionTarget = "provider"
	TargetSurface  TransitionTarget = "surface"
)

type UnbindResult

type UnbindResult struct {
	Subject IngressSubjectRef
	Changed bool
}

UnbindResult makes an idempotent no-op distinct from a state change.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL