model

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package model holds Keyway's core domain types. It has NO dependencies on other internal packages — keep it that way (see CONTRIBUTING.md).

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoPrivateKey is returned by MintToken when the issuer does not control
	// its signing key (SaaS IdPs). Probes 1, 8, 10, 13 and others requiring a
	// mint are unavailable in that case (PRD §1.3).
	ErrNoPrivateKey = errors.New("issuer does not control its private key")

	// ErrUnsupported is returned by adapter operations that an issuer type cannot
	// perform (e.g. AnnounceKey on a generic issuer without admin access).
	ErrUnsupported = errors.New("operation unsupported for this issuer")

	// ErrNoAnnouncedKey is returned by the canary probe (13) when no key is in the
	// announced state.
	ErrNoAnnouncedKey = errors.New("no key in announced state")

	// ErrNotFound is a generic lookup miss from the store.
	ErrNotFound = errors.New("not found")
)

Sentinel errors shared across adapters and the probe engine.

Functions

This section is empty.

Types

type Attribution 

type Attribution struct {
	Kind       string    `json:"kind"` // commit|pr|deploy|idp_audit|unattributed
	Ref        string    `json:"ref"`
	Actor      string    `json:"actor,omitempty"`
	Team       string    `json:"team,omitempty"`
	Timestamp  time.Time `json:"timestamp"`
	Confidence float64   `json:"confidence"`
}

Attribution binds a change to who/what caused it.

type BehaviorSource 

type BehaviorSource string

BehaviorSource records how a piece of behavior was determined, in ascending order of confidence: config < library_default < observed < probed. 

const (
	SrcConfig         BehaviorSource = "config"
	SrcLibraryDefault BehaviorSource = "library_default"
	SrcObserved       BehaviorSource = "observed"
	SrcProbed         BehaviorSource = "probed"
)

type ChangeClass 

type ChangeClass string

ChangeClass is the semantic direction of a contract change. 

const (
	ChangeWidened  ChangeClass = "widened" // now accepts what it previously rejected
	ChangeNarrowed ChangeClass = "narrowed"
	ChangeNeutral  ChangeClass = "neutral"
	ChangeUnknown  ChangeClass = "unknown"
)

type ChangeEvent 

type ChangeEvent struct {
	ID          string       `json:"id"`
	FromVersion string       `json:"from_version"`
	ToVersion   string       `json:"to_version"`
	ConsumerID  string       `json:"consumer_id"`
	Field       string       `json:"field"` // dotted path e.g. "expects.audiences"
	OldValue    any          `json:"old_value"`
	NewValue    any          `json:"new_value"`
	Class       ChangeClass  `json:"class"`
	Severity    Severity     `json:"severity"`
	Confidence  float64      `json:"confidence"`
	Evidence    []string     `json:"evidence"` // probe IDs or provenance locators
	Attribution *Attribution `json:"attribution,omitempty"`
	DetectedAt  time.Time    `json:"detected_at"`
}

ChangeEvent is a single field-level change between two contract versions.

type ClaimObs 

type ClaimObs struct {
	Name         string    `json:"name"`
	FirstSeen    time.Time `json:"first_seen"`
	LastSeen     time.Time `json:"last_seen"`
	PresenceRate float64   `json:"presence_rate"` // 0..1 across sampled tokens
}

ClaimObs records claims observed in tokens issued by this issuer.

type Consumer 

type Consumer struct {
	ID       string `json:"id"`
	StableID string `json:"stable_id"`
	// Aliases are alternative stable identities for the SAME workload discovered
	// by a different source (e.g. Kubernetes keys a workload by its service
	// account while Istio keys it by service name). The aggregator merges two
	// consumers whose identity sets — {StableID} ∪ Aliases — intersect, so a
	// single logical service seen two ways becomes one record (KI-28).
	Aliases      []string                      `json:"aliases,omitempty"`
	Kind         ConsumerKind                  `json:"kind"`
	Name         string                        `json:"name"`
	Namespace    string                        `json:"namespace,omitempty"`
	OwnerTeam    string                        `json:"owner_team,omitempty"`
	Endpoints    []Endpoint                    `json:"endpoints"`
	Expects      Expectations                  `json:"expects"`
	JWKSBehavior JWKSBehavior                  `json:"jwks_behavior"`
	Library      *LibraryInfo                  `json:"library,omitempty"`
	Provenance   map[string][]ProvenanceRecord `json:"provenance"`
	Confidence   map[string]float64            `json:"confidence"`
	Probeable    bool                          `json:"probeable"`
}

Consumer is a component that validates tokens. Derived automatically — Keyway never asks the user to author these.

type ConsumerKind 

type ConsumerKind string

ConsumerKind classifies a token-validating component. 

const (
	ConsumerService      ConsumerKind = "service"
	ConsumerGatewayRoute ConsumerKind = "gateway_route"
	ConsumerEdgeFunction ConsumerKind = "edge_function"
	ConsumerClient       ConsumerKind = "client" // mobile/SPA — not probeable
)

type ContractVersion 

type ContractVersion struct {
	ID          string     `json:"id"`
	Hash        string     `json:"hash"` // sha256 of canonical form
	CreatedAt   time.Time  `json:"created_at"`
	IsBaseline  bool       `json:"is_baseline"`
	Issuers     []Issuer   `json:"issuers"`
	Consumers   []Consumer `json:"consumers"`
	Edges       []Edge     `json:"edges"`
	TriggerKind string     `json:"trigger_kind"` // scheduled|deploy|commit|manual
	TriggerRef  string     `json:"trigger_ref,omitempty"`
}

ContractVersion is an immutable snapshot of the whole derived contract graph.

type Edge 

type Edge struct {
	IssuerID     string       `json:"issuer_id"`
	ConsumerID   string       `json:"consumer_id"`
	Expects      Expectations `json:"expects"`
	LastVerified *time.Time   `json:"last_verified,omitempty"`
	VerifyState  EdgeState    `json:"verify_state"`
}

Edge is a directed relationship: a consumer validates tokens from an issuer.

type EdgeState 

type EdgeState string

EdgeState is the verification status of an issuer→consumer relationship. 

const (
	EdgeVerified   EdgeState = "verified"   // all applicable probes passed
	EdgeDivergent  EdgeState = "divergent"  // probe result contradicts derived contract
	EdgeUnverified EdgeState = "unverified" // not probeable or not yet probed
)

type Endpoint 

type Endpoint struct {
	URL    string `json:"url"`
	Method string `json:"method"`
	// SafeProbePath is a request known to succeed with a valid token. The probe target.
	SafeProbePath string `json:"safe_probe_path"`
}

Endpoint is a probeable HTTP target for a consumer.

type Expectations 

type Expectations struct {
	Issuers        []string `json:"issuers"`
	Audiences      []string `json:"audiences"`
	Algorithms     []string `json:"algorithms"`
	RequiredClaims []string `json:"required_claims"`
	ClockSkewSec   int      `json:"clock_skew_sec"`
}

Expectations is what a consumer requires of a token to accept it.

type Issuer 

type Issuer struct {
	ID                 string          `json:"id"`
	Name               string          `json:"name"`
	Type               IssuerType      `json:"type"`
	IssuerURL          string          `json:"issuer_url"`
	JWKSURI            string          `json:"jwks_uri"`
	DiscoveryDoc       json.RawMessage `json:"discovery_doc,omitempty"`
	Keys               []Key           `json:"keys"`
	ControlsPrivateKey bool            `json:"controls_private_key"`
	ClaimSchema        []ClaimObs      `json:"claim_schema"`
}

Issuer is a token-issuing authority Keyway tracks.

type IssuerType 

type IssuerType string

IssuerType enumerates the token issuers Keyway can work with. 

const (
	IssuerKeycloak    IssuerType = "keycloak"
	IssuerK8sSA       IssuerType = "k8s_sa"
	IssuerGenericOIDC IssuerType = "generic_oidc"
	IssuerAuth0       IssuerType = "auth0"
	IssuerOkta        IssuerType = "okta"
	IssuerEntra       IssuerType = "entra"
)

type JWKSBehavior 

type JWKSBehavior struct {
	// JWKSURI is the endpoint the consumer fetches signing keys from (the
	// rotation endpoint). Captured from Istio jwtRules.jwksUri / Envoy remote_jwks.
	JWKSURI               string         `json:"jwks_uri,omitempty"`
	CacheTTLSec           *int           `json:"cache_ttl_sec,omitempty"`
	RefreshIntervalSec    *int           `json:"refresh_interval_sec,omitempty"`
	RefreshesOnUnknownKID *bool          `json:"refreshes_on_unknown_kid,omitempty"`
	LastObservedRefresh   *time.Time     `json:"last_observed_refresh,omitempty"`
	Source                BehaviorSource `json:"source"`
}

JWKSBehavior captures how a consumer fetches and caches keys — the mechanism behind most rotation outages.

type Key 

type Key struct {
	KID               string     `json:"kid"`
	Alg               string     `json:"alg"`
	Use               string     `json:"use"`
	PublicKeyPEM      string     `json:"public_key_pem"`
	Status            KeyStatus  `json:"status"`
	FirstSeenInJWKS   time.Time  `json:"first_seen_in_jwks"`
	InSigningUseSince *time.Time `json:"in_signing_use_since,omitempty"`
	RetiredAt         *time.Time `json:"retired_at,omitempty"`
}

Key is a single signing key observed in (or managed within) an issuer's JWKS.

type KeyStatus 

type KeyStatus string

KeyStatus is the lifecycle state of a signing key in the rotation flow. 

const (
	// KeyAnnounced is published in JWKS but not yet used for signing. The canary state.
	KeyAnnounced KeyStatus = "announced"
	// KeyActive is currently used for signing.
	KeyActive KeyStatus = "active"
	// KeyRetiring is no longer signing, still published for validation of outstanding tokens.
	KeyRetiring KeyStatus = "retiring"
	// KeyRetired is removed from JWKS.
	KeyRetired KeyStatus = "retired"
)

type LibraryInfo 

type LibraryInfo struct {
	Name    string `json:"name"`    // e.g. "MicahParks/keyfunc"
	Version string `json:"version"` // e.g. "v1.9.0"
	Lang    string `json:"lang"`
}

LibraryInfo identifies the JWT library a consumer uses.

type ProbeResult 

type ProbeResult struct {
	ID          string    `json:"id"`
	ProbeID     string    `json:"probe_id"`
	ConsumerID  string    `json:"consumer_id"`
	EndpointURL string    `json:"endpoint_url"`
	StatusCode  int       `json:"status_code"`
	LatencyMs   int       `json:"latency_ms"`
	Passed      bool      `json:"passed"`
	RawResponse string    `json:"raw_response"` // truncated to 512 bytes
	RunAt       time.Time `json:"run_at"`
}

ProbeResult is the outcome of running one probe against one endpoint. Note: minted tokens are NEVER stored here — only the jti and probe ID identify a run (PRD OPEN-4).

type ProvenanceRecord 

type ProvenanceRecord struct {
	Source     string    `json:"source"`  // "istio:RequestAuthentication/foo"
	Locator    string    `json:"locator"` // file path, resource ref, or URL
	ObservedAt time.Time `json:"observed_at"`
	Confidence float64   `json:"confidence"` // 0..1
}

ProvenanceRecord ties a piece of derived state back to its source of evidence.

type Severity 

type Severity string

Severity ranks the operational risk of a finding. 

const (
	SeverityCritical Severity = "critical"
	SeverityHigh     Severity = "high"
	SeverityMedium   Severity = "medium"
	SeverityLow      Severity = "low"
	SeverityInfo     Severity = "info"
)

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.