apitypes

Documentation

Overview

Package apitypes holds the public request/response shapes for the Keyway HTTP API (PRD §12). These are the contract with the web UI and external clients; keep them stable and versioned.

Index

• type AgentInspectRequest
• type AgentInspectResponse
• type AnnounceKeyRequest
• type BlastRadiusRequest
• type CanaryStatusResponse
• type ChangeList
• type ChangeProposal
• type ConsumerList
• type ConsumerProbesResponse
• type CoverageCategory
• type CoverageDomain
• type CoverageResponse
• type CoverageSource
• type CoverageThreat
• type ErrorResponse
• type HealthResponse
• type IssuerList
• type PromoteKeyRequest
• type RunProbesRequest
• type RunProbesResponse
• type SnapshotResponse
• type ThreatCoverageResponse

Types

type AgentInspectRequest

type AgentInspectRequest struct {
	Token              string   `json:"token"`
	Audience           string   `json:"audience,omitempty"`
	RequireDelegation  bool     `json:"require_delegation,omitempty"`
	MaxLifetimeSeconds int      `json:"max_lifetime_seconds,omitempty"`
	AllowedScopes      []string `json:"allowed_scopes,omitempty"`
}

type AgentInspectResponse

type AgentInspectResponse struct {
	Findings any `json:"findings"`
	Count    int `json:"count"`
}

AgentInspectResponse.Findings is []agentauth.Finding, which already carries the snake_case JSON tags; the transport keeps it as `any` to avoid importing the analyzer into this leaf package.

type AnnounceKeyRequest

type AnnounceKeyRequest struct {
	IssuerID string `json:"issuer_id"`
	Alg      string `json:"alg"`
}

AnnounceKeyRequest is the body of POST /v1/canary/announce.

type BlastRadiusRequest

type BlastRadiusRequest struct {
	Proposal ChangeProposal `json:"proposal"`
}

BlastRadiusRequest is the body of POST /v1/blast-radius.

type CanaryStatusResponse

type CanaryStatusResponse struct {
	Issuer       string      `json:"issuer"`
	Keys         []model.Key `json:"keys"`
	AnnouncedKID string      `json:"announced_kid"`
}

CanaryStatusResponse reports an issuer's keys and which is the announced canary.

type ChangeList

type ChangeList struct {
	Changes []model.ChangeEvent `json:"changes"`
	Total   int                 `json:"total"`
}

ChangeList wraps a change-event listing.

type ChangeProposal

type ChangeProposal struct {
	Kind         string `json:"kind"` // rotate_key|remove_claim|change_issuer|drop_algorithm|retire_key
	IssuerID     string `json:"issuer_id"`
	KID          string `json:"kid,omitempty"`
	ClaimName    string `json:"claim_name,omitempty"`
	NewIssuerURL string `json:"new_issuer_url,omitempty"`
	Algorithm    string `json:"algorithm,omitempty"`
}

ChangeProposal describes a proposed change to evaluate (PRD §10.1).

type ConsumerList

type ConsumerList struct {
	Consumers []model.Consumer `json:"consumers"`
	Total     int              `json:"total"`
}

ConsumerList wraps a paginated consumer listing.

type ConsumerProbesResponse

type ConsumerProbesResponse struct {
	ConsumerID string              `json:"consumer_id"`
	Results    []model.ProbeResult `json:"results"`
}

ConsumerProbesResponse is a consumer's recent probe history.

type CoverageCategory

type CoverageCategory struct {
	Category string `json:"category"`
	Covered  int    `json:"covered"`
	Total    int    `json:"total"`
}

type CoverageDomain

type CoverageDomain struct {
	Domain  string `json:"domain"`
	Covered int    `json:"covered"`
	Total   int    `json:"total"`
	Percent int    `json:"percent"`
}

CoverageDomain / CoverageCategory / CoverageThreat / ThreatCoverageResponse mirror the web client's coverage view.

type CoverageResponse

type CoverageResponse struct {
	Total         int `json:"total"`
	Resolved      int `json:"resolved"`
	LowConfidence int `json:"low_confidence"`
	Unresolved    int `json:"unresolved"`
}

CoverageResponse summarizes how much of the contract Keyway can vouch for.

type CoverageSource

type CoverageSource struct {
	Ref string `json:"ref"`
	URL string `json:"url"`
}

type CoverageThreat

type CoverageThreat struct {
	ID        string           `json:"id"`
	Domain    string           `json:"domain"`
	Category  string           `json:"category"`
	Severity  model.Severity   `json:"severity"`
	Title     string           `json:"title"`
	Invariant string           `json:"invariant"`
	Sources   []CoverageSource `json:"sources"`
	Detectors []string         `json:"detectors"`
}

type ErrorResponse

type ErrorResponse struct {
	Error   string `json:"error"`
	Code    string `json:"code,omitempty"`
	Details string `json:"details,omitempty"`
}

ErrorResponse is the uniform error envelope.

type HealthResponse

type HealthResponse struct {
	Status  string    `json:"status"`
	Version string    `json:"version"`
	Time    time.Time `json:"time"`
}

HealthResponse is returned by GET /v1/health.

type IssuerList

type IssuerList struct {
	Issuers []model.Issuer `json:"issuers"`
}

IssuerList is the registered issuers with their live key state, so the UI can drive the canary lifecycle.

type PromoteKeyRequest

type PromoteKeyRequest struct {
	IssuerID string `json:"issuer_id"`
	KID      string `json:"kid"`
}

PromoteKeyRequest is the body of POST /v1/canary/promote.

type RunProbesRequest

type RunProbesRequest struct {
	ConsumerIDs []string `json:"consumer_ids,omitempty"`
	ProbeIDs    []string `json:"probe_ids,omitempty"`
}

RunProbesRequest is the body of POST /v1/probes/run.

type RunProbesResponse

type RunProbesResponse struct {
	RunID   string              `json:"run_id"`
	Results []model.ProbeResult `json:"results"`
}

RunProbesResponse acknowledges a probe run and carries its results.

type SnapshotResponse

type SnapshotResponse struct {
	VersionID  string `json:"version_id"`
	Hash       string `json:"hash"`
	IsBaseline bool   `json:"is_baseline"`
}

SnapshotResponse is returned by POST /v1/snapshots.

type ThreatCoverageResponse

type ThreatCoverageResponse struct {
	Total      int                `json:"total"`
	Covered    int                `json:"covered"`
	Gaps       int                `json:"gaps"`
	Percent    int                `json:"percent"`
	Domains    []CoverageDomain   `json:"domains"`
	Categories []CoverageCategory `json:"categories"`
	Threats    []CoverageThreat   `json:"threats"`
}