Documentation
¶
Overview ¶
Package wire contains shared certificate, discovery, host, and evaluation types. Public administration has a separate contract in pkg/facts.
Index ¶
Constants ¶
const ( RelAuth = "https://epithet.dev/rel/auth" RelControl = "https://epithet.dev/rel/control" )
RelAuth and RelControl are the extension relation types the CA advertises in Link headers on GET /. RFC 8288 requires extension relation types to be URIs. They carry no version segment: a relation names the relationship, not the payload schema.
const MaxBodySize = 64 * 1024
MaxBodySize is the maximum request body and trusted-peer response body size. Real OIDC ID tokens with group claims run 4-8 KiB; 64 KiB leaves an order of magnitude of headroom before truncation.
const MaxTTLSeconds int64 = (1<<63 - 1) / int64(time.Second)
MaxTTLSeconds is the largest whole-second lifetime representable by Go's time.Duration. CA validates before converting policy-controlled seconds.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthConfig ¶
type AuthConfig struct {
Issuer string `json:"issuer"`
ClientID string `json:"client_id"`
ClientSecret string `json:"client_secret,omitempty"`
}
AuthConfig tells a client how to authenticate: OIDC issuer and client credentials. This is the only auth mechanism epithet supports, so there is no type discriminator.
type Authentication ¶ added in v0.35.0
Authentication contains CA's verified identity and session bound. It deliberately contains no bearer credentials or provider-specific claims.
func (Authentication) Validate ¶ added in v0.35.0
func (a Authentication) Validate() error
Validate checks the verified identity and its absolute lifetime bound.
type Connection ¶ added in v0.35.0
type Connection struct {
RemoteHost string `json:"remoteHost"`
RemoteUser string `json:"remoteUser"`
Port uint `json:"port"`
ProxyJump string `json:"proxyJump"`
Hash ConnectionHash `json:"hash"` // %C - hash of connection tuple
}
Connection represents the SSH connection parameters epithet actually uses. These come from OpenSSH's Match exec via %h/%p/%r/%j; local hostname (%l) was transmitted here too but never read anywhere downstream, so it was dropped (spec §13) along with the os.Hostname() call that populated it. The Hash field contains the %C hash value computed by OpenSSH from the full connection tuple (including local host), so it still uniquely identifies the connection even without LocalHost as a separate field.
type ConnectionHash ¶ added in v0.35.0
type ConnectionHash string
ConnectionHash is the OpenSSH %C hash value that uniquely identifies a connection. This is computed by OpenSSH from the connection parameters (local host, remote host, port, user, ProxyJump).
type CreateCertRequest ¶ added in v0.35.0
type CreateCertRequest struct {
PublicKey sshcert.RawPublicKey `json:"publicKey"`
Connection Connection `json:"connection"`
}
CreateCertRequest asks the CA for a signed cert. Both fields are required.
type CreateCertResponse ¶ added in v0.35.0
type CreateCertResponse struct {
Certificate sshcert.RawCertificate `json:"certificate"`
}
CreateCertResponse is the CA's response to a CreateCertRequest.
type Discovery ¶
type Discovery struct {
Auth *AuthConfig `json:"auth,omitempty"`
// CacheControl controls login discovery caching; never serialized.
CacheControl string `json:"-"`
}
Discovery is the discovery document: the anonymous bootstrap endpoint's entire payload. It carries only auth config — no server-advertised match patterns, since gating on those was removed.
type Host ¶ added in v0.35.0
type Host struct {
HostResource
Principal Principal `json:"principal"`
}
Host is one resolved inventory host: the policy-facing resource plus the principal metadata the CA needs and policy never sees.
func (*Host) UnmarshalJSON ¶ added in v0.35.0
UnmarshalJSON decodes the complete inventory host, including principal metadata. Using a plain resource prevents promotion of HostResource's custom decoder, which would otherwise consume the enclosing object by itself.
type HostResource ¶ added in v0.35.0
type HostResource struct {
ID string `json:"id,omitempty"`
Names object.Strings `json:"name"`
Attributes object.Attributes `json:"attributes,omitempty"`
// Accounts must be explicit: null is unrestricted and [] permits none.
Accounts []string `json:"accounts"`
}
func (*HostResource) UnmarshalJSON ¶ added in v0.35.0
func (h *HostResource) UnmarshalJSON(data []byte) error
UnmarshalJSON requires an explicit account restriction and decodes it before exposing host facts. Keep strict decoding for policy requests, whose outer decoder cannot enforce unknown-field checks inside a custom unmarshaler.
func (HostResource) Validate ¶ added in v0.35.0
func (h HostResource) Validate() error
Validate checks host fields whose omission could broaden authorization.
type PolicyError ¶
PolicyError is a policy-server error with its HTTP status.
func (*PolicyError) Error ¶
func (e *PolicyError) Error() string
type PolicyFacts ¶ added in v0.30.0
type PolicyFacts struct {
Authentication Authentication `json:"authentication"`
Target string `json:"target"`
User *User `json:"user"`
Host *HostResource `json:"host"`
}
PolicyFacts is CA's normalized input for one requested target. CA validates that inventory host names include the target before projecting Host. Host.Names lists the equivalent host names, independent of principal metadata; Target binds the request. Principal construction data, revisions, and protocol versions remain at CA.
func (*PolicyFacts) UnmarshalJSON ¶ added in v0.30.0
func (f *PolicyFacts) UnmarshalJSON(data []byte) error
UnmarshalJSON distinguishes explicit absent records from omitted fields and retains strict decoding even though this type has custom unmarshalling.
func (*PolicyFacts) Validate ¶ added in v0.30.0
func (f *PolicyFacts) Validate(requestedHost string) error
Validate preserves identity, connection binding, and authentication lifetime. Explicit null records represent absence for policy's structural denial.
type PolicyResponse ¶
type PolicyResponse struct {
// TTLSeconds is a positive whole-second lifetime, measured from CA signing.
TTLSeconds int64 `json:"ttlSeconds"`
Extensions map[string]string `json:"extensions"`
// NotAfter optionally tightens the TTL and authentication-expiry bounds.
NotAfter time.Time `json:"notAfter,omitzero"`
PolicyID string `json:"policyId,omitempty"`
}
PolicyResponse authorizes one connection with evaluator-owned limits. CA constructs identity and principal from facts and enforces login expiry.
Source Files