client

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package client provides a lightweight HTTP SDK for the KNXVault API.

Package client provides a lightweight HTTP SDK for the KNXVault REST API.

Index

Constants

This section is empty.

Variables

View Source 
var RequireHTTPS = true

RequireHTTPS rejects non-loopback http vault URLs when true (W52-06). Tests and local lab may set Client.AllowHTTP or use localhost.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Status  int
	Code    string
	Message string
}

APIError represents a KNXVault error response.

func (*APIError) Error 

func (e *APIError) Error() string

type AgentDelegateRequest 

type AgentDelegateRequest struct {
	AgentID        string   `json:"agent_id"`
	PathPrefix     string   `json:"path_prefix"`
	AllowedActions []string `json:"allowed_actions"`
	Policies       []string `json:"policies,omitempty"`
	TTL            string   `json:"ttl,omitempty"`
}

AgentDelegateRequest is POST /auth/agent/delegate.

type AuditEntry 

type AuditEntry struct {
	ID        int64          `json:"id"`
	Timestamp time.Time      `json:"timestamp"`
	Actor     string         `json:"actor"`
	Action    string         `json:"action"`
	Resource  string         `json:"resource"`
	Status    string         `json:"status"`
	Details   map[string]any `json:"details,omitempty"`
	Hash      string         `json:"hash"`
}

AuditEntry is an exported audit record.

type AuditExportResponse 

type AuditExportResponse struct {
	Entries   []AuditEntry `json:"entries"`
	HeadHash  string       `json:"head_hash"`
	Signature string       `json:"signature,omitempty"`
	SignedAt  time.Time    `json:"signed_at,omitempty"`
}

AuditExportResponse is returned by GET /audit/export.

type BackupCreateRequest 

type BackupCreateRequest struct {
	IncludeAudit bool `json:"include_audit,omitempty"`
	AuditLimit   int  `json:"audit_limit,omitempty"`
}

BackupCreateRequest is POST /sys/backup.

type BackupCreateResponse 

type BackupCreateResponse struct {
	Format string `json:"format"`
	Data   string `json:"data"`
}

BackupCreateResponse is returned for backup creation.

type CAResponse 

type CAResponse struct {
	ID        string `json:"id"`
	Name      string `json:"name,omitempty"`
	CertPEM   string `json:"cert_pem"`
	Serial    string `json:"serial"`
	ExpiresAt string `json:"expires_at"`
}

CAResponse is returned for CA create operations.

type CapabilitiesResponse 

type CapabilitiesResponse struct {
	Capabilities []string `json:"capabilities"`
}

CapabilitiesResponse is returned by GET /sys/capabilities.

type Client 

type Client struct {
	BaseURL string
	Token   string
	HTTP    *http.Client
}

Client calls the KNXVault REST API.

func New 

func New(baseURL, token string) *Client

New constructs a client with defaults.

func (*Client) AuditExport 

func (c *Client) AuditExport(ctx context.Context, limit int) (*AuditExportResponse, error)

AuditExport exports audit entries.

func (*Client) BackupCreate 

func (c *Client) BackupCreate(ctx context.Context, req BackupCreateRequest) (*BackupCreateResponse, error)

BackupCreate exports an encrypted backup archive.

func (*Client) BackupRestore 

func (c *Client) BackupRestore(ctx context.Context, archive []byte) error

BackupRestore imports an encrypted backup archive.

func (*Client) Capabilities 

func (c *Client) Capabilities(ctx context.Context) (*CapabilitiesResponse, error)

Capabilities calls GET /sys/capabilities.

func (*Client) DelegateAgent 

func (c *Client) DelegateAgent(ctx context.Context, req AgentDelegateRequest) (*LoginResponse, error)

DelegateAgent issues a scoped agent token from the caller's credentials.

func (*Client) DeletePolicy 

func (c *Client) DeletePolicy(ctx context.Context, name string) error

DeletePolicy removes a policy.

func (*Client) DeleteRole 

func (c *Client) DeleteRole(ctx context.Context, name string) error

DeleteRole removes a role.

func (*Client) GenerateDatabaseCreds 

func (c *Client) GenerateDatabaseCreds(ctx context.Context, role string, ttlSeconds int) (*DatabaseCredsResponse, error)

GenerateDatabaseCreds issues database credentials.

func (*Client) GenerateSSHCreds 

func (c *Client) GenerateSSHCreds(ctx context.Context, role string, username string, ttlSeconds int) (*SSHCredsResponse, error)

GenerateSSHCreds issues OpenSSH credentials.

func (*Client) GetDatabaseRole 

func (c *Client) GetDatabaseRole(ctx context.Context, name string) (*DatabaseRoleResponse, error)

GetDatabaseRole returns a database role.

func (*Client) GetPolicy 

func (c *Client) GetPolicy(ctx context.Context, name string) (*PolicyResponse, error)

GetPolicy returns a policy.

func (*Client) GetRaw 

func (c *Client) GetRaw(ctx context.Context, path string, auth bool) ([]byte, error)

GetRaw performs an authenticated GET returning raw response bytes.

func (*Client) GetRole 

func (c *Client) GetRole(ctx context.Context, name string) (*RoleResponse, error)

GetRole returns a role.

func (*Client) GetSSHRole 

func (c *Client) GetSSHRole(ctx context.Context, name string) (*SSHRoleResponse, error)

GetSSHRole returns an SSH role.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (*HealthResponse, error)

Health calls GET /health.

func (*Client) ImportPolicyHCL 

func (c *Client) ImportPolicyHCL(ctx context.Context, name, hcl string) (map[string]any, error)

ImportPolicyHCL imports a Vault-style HCL policy (W41-08).

func (*Client) IssueListenerTLS 

func (c *Client) IssueListenerTLS(ctx context.Context, req IssueListenerTLSRequest) (*IssueListenerTLSResponse, error)

IssueListenerTLS issues TLS material for the API listener.

func (*Client) KVGet 

func (c *Client) KVGet(ctx context.Context, path string) (*KVReadResponse, error)

KVGet reads a secret path.

func (*Client) KVPut 

func (c *Client) KVPut(ctx context.Context, path string, data map[string]any) error

KVPut writes a secret path.

func (*Client) ListLeases 

func (c *Client) ListLeases(ctx context.Context, query string) (map[string]any, error)

ListLeases returns leases with optional query string (W42-02).

func (*Client) ListPolicies 

func (c *Client) ListPolicies(ctx context.Context) ([]PolicyResponse, error)

ListPolicies returns all policies.

func (*Client) ListRoles 

func (c *Client) ListRoles(ctx context.Context) ([]RoleResponse, error)

ListRoles returns all roles.

func (*Client) LoginKubernetes 

func (c *Client) LoginKubernetes(ctx context.Context, role, jwt string) (*LoginResponse, error)

LoginKubernetes exchanges a ServiceAccount JWT for a client token.

func (*Client) LoginToken 

func (c *Client) LoginToken(ctx context.Context, token string) (*LoginResponse, error)

LoginToken validates a token via POST /auth/token.

func (*Client) PKICreateIntermediate 

func (c *Client) PKICreateIntermediate(ctx context.Context, req CreateIntermediateCARequest) (*CAResponse, error)

PKICreateIntermediate creates an intermediate CA signed by a parent CA name.

func (*Client) PKICreateRoot 

func (c *Client) PKICreateRoot(ctx context.Context, req CreateRootCARequest) (*CAResponse, error)

PKICreateRoot creates a self-signed root CA.

func (*Client) PKIGetCA 

func (c *Client) PKIGetCA(ctx context.Context, id string) (*CAResponse, error)

PKIGetCA fetches CA metadata by id (GET /pki/ca/:id).

func (*Client) PKIGetCAByName 

func (c *Client) PKIGetCAByName(ctx context.Context, name string) (*CAResponse, error)

PKIGetCAByName fetches CA metadata by vault name (GET /pki/ca/by-name/:name).

func (*Client) PKIIssue 

func (c *Client) PKIIssue(ctx context.Context, req IssueCertRequest) (*IssueCertResponse, error)

PKIIssue issues a leaf certificate.

func (*Client) PKIIssueClient 

func (c *Client) PKIIssueClient(ctx context.Context, role, commonName, ttl string) (*IssueCertResponse, error)

PKIIssueClient issues a client certificate (POST /pki/issue-client-cert).

func (*Client) PKIRenew 

func (c *Client) PKIRenew(ctx context.Context, req RenewCertRequest) (*RenewCertResponse, error)

PKIRenew renews a leaf certificate.

func (*Client) PKIRevoke 

func (c *Client) PKIRevoke(ctx context.Context, req RevokeCertRequest) error

PKIRevoke revokes a certificate serial.

func (*Client) PKISignCSR 

func (c *Client) PKISignCSR(ctx context.Context, req SignCSRRequest) (*SignCSRResponse, error)

PKISignCSR signs a PEM CSR (POST /pki/sign).

func (*Client) ProbeMetrics 

func (c *Client) ProbeMetrics(ctx context.Context) (int, error)

ProbeMetrics checks whether GET /metrics is reachable.

func (*Client) ProbeReady 

func (c *Client) ProbeReady(ctx context.Context) (*ReadyResponse, int, error)

ProbeReady calls GET /ready and returns the parsed body even when the service is not ready (503).

func (*Client) PutDatabaseRole 

func (c *Client) PutDatabaseRole(ctx context.Context, name string, req DatabaseRoleRequest) error

PutDatabaseRole stores a database role.

func (*Client) PutPolicy 

func (c *Client) PutPolicy(ctx context.Context, name string, req PolicyRequest) error

PutPolicy stores a policy.

func (*Client) PutRole 

func (c *Client) PutRole(ctx context.Context, name string, req RoleRequest) error

PutRole stores a role.

func (*Client) PutSSHRole 

func (c *Client) PutSSHRole(ctx context.Context, name string, req SSHRoleRequest) error

PutSSHRole stores an SSH role.

func (*Client) RaftAddNode 

func (c *Client) RaftAddNode(ctx context.Context, req RaftAddNodeRequest) error

RaftAddNode adds a Raft cluster member.

func (*Client) RaftRemoveNode 

func (c *Client) RaftRemoveNode(ctx context.Context, req RaftRemoveNodeRequest) error

RaftRemoveNode removes a Raft cluster member.

func (*Client) Ready 

func (c *Client) Ready(ctx context.Context) (*ReadyResponse, error)

Ready calls GET /ready.

func (*Client) RotateMasterKey 

func (c *Client) RotateMasterKey(newKeyBase64 string) (*RotateMasterKeyResponse, error)

RotateMasterKey activates a new envelope master key.

func (*Client) RunRotation 

func (c *Client) RunRotation(ctx context.Context, req RotationRunRequest) (*RotationRunResponse, error)

RunRotation triggers orchestrated rotation.

func (*Client) Seal 

func (c *Client) Seal() (*SealResponse, error)

Seal blocks mutating API operations.

func (*Client) SimulatePolicy 

func (c *Client) SimulatePolicy(ctx context.Context, req map[string]any) (map[string]any, error)

SimulatePolicy runs POST /sys/policy/simulate (W41-04).

func (*Client) Unseal 

func (c *Client) Unseal(keyBase64 string) (*UnsealResponse, error)

Unseal restores service after seal.

func (*Client) ValidateBaseURL 

func (c *Client) ValidateBaseURL() error

ValidateBaseURL checks BaseURL against HTTPS policy.

type CreateIntermediateCARequest 

type CreateIntermediateCARequest struct {
	ParentName string `json:"parent_name"`
	Name       string `json:"name"`
	CommonName string `json:"common_name"`
	TTL        string `json:"ttl"`
	KeyBits    int    `json:"key_bits,omitempty"`
}

CreateIntermediateCARequest is POST /pki/intermediate.

type CreateRootCARequest 

type CreateRootCARequest struct {
	Name            string   `json:"name"`
	CommonName      string   `json:"common_name"`
	TTL             string   `json:"ttl"`
	KeyBits         int      `json:"key_bits,omitempty"`
	AllowedDomains  []string `json:"allowed_domains,omitempty"`
	AllowSubdomains bool     `json:"allow_subdomains,omitempty"`
}

CreateRootCARequest is POST /pki/root.

type DatabaseCredsResponse 

type DatabaseCredsResponse struct {
	LeaseID    string   `json:"lease_id"`
	Username   string   `json:"username"`
	Password   string   `json:"password"`
	Role       string   `json:"role"`
	TTLSeconds int      `json:"ttl_seconds"`
	ExpiresAt  string   `json:"expires_at"`
	Statements []string `json:"statements,omitempty"`
}

DatabaseCredsResponse is returned for credential generation.

type DatabaseRoleRequest 

type DatabaseRoleRequest struct {
	TTLSeconds           int            `json:"ttl_seconds"`
	UsernamePrefix       string         `json:"username_prefix,omitempty"`
	DefaultUsername      string         `json:"default_username,omitempty"`
	CreationStatements   []string       `json:"creation_statements"`
	RevocationStatements []string       `json:"revocation_statements,omitempty"`
	ExecutionMode        string         `json:"execution_mode,omitempty"`
	AdminCredentialsPath string         `json:"admin_credentials_path,omitempty"`
	Config               map[string]any `json:"config,omitempty"`
}

DatabaseRoleRequest configures a database credentials role.

type DatabaseRoleResponse 

type DatabaseRoleResponse struct {
	Name                 string         `json:"name"`
	TTLSeconds           int            `json:"ttl_seconds"`
	UsernamePrefix       string         `json:"username_prefix,omitempty"`
	DefaultUsername      string         `json:"default_username,omitempty"`
	CreationStatements   []string       `json:"creation_statements"`
	RevocationStatements []string       `json:"revocation_statements,omitempty"`
	ExecutionMode        string         `json:"execution_mode,omitempty"`
	AdminCredentialsPath string         `json:"admin_credentials_path,omitempty"`
	Config               map[string]any `json:"config,omitempty"`
}

DatabaseRoleResponse returns database role configuration.

type HealthResponse 

type HealthResponse = ServiceStatus

HealthResponse is returned by GET /health.

type IssueCertRequest 

type IssueCertRequest struct {
	Role        string   `json:"role"`
	CommonName  string   `json:"common_name"`
	DNSNames    []string `json:"dns_names,omitempty"`
	IPAddresses []string `json:"ip_addresses,omitempty"`
	TTL         string   `json:"ttl,omitempty"`
	KeyBits     int      `json:"key_bits,omitempty"`
	AutoRenew   bool     `json:"auto_renew,omitempty"`
}

IssueCertRequest is POST /pki/issue.

type IssueCertResponse 

type IssueCertResponse struct {
	CertPEM       string `json:"cert_pem"`
	PrivateKeyPEM string `json:"private_key_pem"`
	Serial        string `json:"serial"`
	ExpiresAt     string `json:"expires_at"`
	CAID          string `json:"ca_id,omitempty"`
}

IssueCertResponse is returned for leaf issuance.

type IssueListenerTLSRequest 

type IssueListenerTLSRequest struct {
	Role       string   `json:"role"`
	CommonName string   `json:"common_name"`
	DNSNames   []string `json:"dns_names,omitempty"`
	CertFile   string   `json:"cert_file,omitempty"`
	KeyFile    string   `json:"key_file,omitempty"`
	TTL        string   `json:"ttl,omitempty"`
}

IssueListenerTLSRequest issues listener TLS material.

type IssueListenerTLSResponse 

type IssueListenerTLSResponse struct {
	CertPEM       string `json:"cert_pem"`
	PrivateKeyPEM string `json:"private_key_pem"`
	Serial        string `json:"serial"`
	ExpiresAt     string `json:"expires_at"`
	CertFile      string `json:"cert_file,omitempty"`
	KeyFile       string `json:"key_file,omitempty"`
}

IssueListenerTLSResponse returns issued listener TLS material.

type K8sLoginRequest 

type K8sLoginRequest struct {
	Role string `json:"role"`
	JWT  string `json:"jwt"`
}

K8sLoginRequest is POST /auth/kubernetes.

type KVReadResponse 

type KVReadResponse struct {
	Data map[string]any `json:"data"`
}

KVReadResponse is GET /secrets/kv/:path.

type KVWriteRequest 

type KVWriteRequest struct {
	Data    map[string]any `json:"data"`
	Options map[string]any `json:"options,omitempty"`
}

KVWriteRequest is POST /secrets/kv/:path.

type LeaseResponse 

type LeaseResponse struct {
	LeaseID    string `json:"lease_id"`
	Engine     string `json:"engine"`
	Role       string `json:"role"`
	Path       string `json:"path"`
	TTLSeconds int    `json:"ttl_seconds"`
	Renewable  bool   `json:"renewable"`
	Revoked    bool   `json:"revoked"`
}

LeaseResponse is returned by GET /sys/leases/:id.

type LoginResponse 

type LoginResponse struct {
	ClientToken string   `json:"client_token"`
	TTL         int      `json:"ttl"`
	Policies    []string `json:"policies"`
}

LoginResponse is returned by POST /auth/token.

type PolicyRequest 

type PolicyRequest struct {
	Effect     string         `json:"effect"`
	Resources  []string       `json:"resources"`
	Actions    []string       `json:"actions"`
	Conditions map[string]any `json:"conditions,omitempty"`
}

PolicyRequest creates or updates a policy.

type PolicyResponse 

type PolicyResponse struct {
	Name       string         `json:"name"`
	Effect     string         `json:"effect"`
	Resources  []string       `json:"resources"`
	Actions    []string       `json:"actions"`
	Conditions map[string]any `json:"conditions,omitempty"`
}

PolicyResponse returns a policy.

type RaftAddNodeRequest 

type RaftAddNodeRequest struct {
	NodeID  uint64 `json:"node_id"`
	Address string `json:"address"`
}

RaftAddNodeRequest adds a Raft peer.

type RaftRemoveNodeRequest 

type RaftRemoveNodeRequest struct {
	NodeID uint64 `json:"node_id"`
}

RaftRemoveNodeRequest removes a Raft peer.

type ReadyResponse 

type ReadyResponse = ServiceStatus

ReadyResponse is returned by GET /ready.

type RenewCertRequest 

type RenewCertRequest struct {
	CAID   string `json:"ca_id"`
	Serial string `json:"serial"`
	TTL    string `json:"ttl,omitempty"`
}

RenewCertRequest is POST /pki/renew.

type RenewCertResponse 

type RenewCertResponse struct {
	PreviousSerial string `json:"previous_serial"`
	CertPEM        string `json:"cert_pem"`
	PrivateKeyPEM  string `json:"private_key_pem"`
	Serial         string `json:"serial"`
	ExpiresAt      string `json:"expires_at"`
}

RenewCertResponse is returned for certificate renewal.

type RevokeCertRequest 

type RevokeCertRequest struct {
	CAID   string `json:"ca_id"`
	Serial string `json:"serial"`
	Reason string `json:"reason,omitempty"`
}

RevokeCertRequest is POST /pki/revoke.

type RoleRequest 

type RoleRequest struct {
	Policies                      []string `json:"policies"`
	BoundServiceAccountNames      []string `json:"bound_service_account_names,omitempty"`
	BoundServiceAccountNamespaces []string `json:"bound_service_account_namespaces,omitempty"`
}

RoleRequest creates or updates a role.

type RoleResponse 

type RoleResponse struct {
	Name                          string   `json:"name"`
	Policies                      []string `json:"policies"`
	BoundServiceAccountNames      []string `json:"bound_service_account_names,omitempty"`
	BoundServiceAccountNamespaces []string `json:"bound_service_account_namespaces,omitempty"`
}

RoleResponse returns a role.

type RotateMasterKeyResponse 

type RotateMasterKeyResponse struct {
	KeyVersion int `json:"key_version"`
}

RotateMasterKeyResponse is returned by POST /sys/rotate-master-key.

type RotationRunRequest 

type RotationRunRequest struct {
	DBGrace  string `json:"db_grace,omitempty"`
	SSHGrace string `json:"ssh_grace,omitempty"`
	PKIGrace string `json:"pki_grace,omitempty"`
}

RotationRunRequest triggers orchestrated rotation.

type RotationRunResponse 

type RotationRunResponse struct {
	KVRotated    int `json:"kv_rotated"`
	DBRenewed    int `json:"db_leases_renewed"`
	SSHRenewed   int `json:"ssh_leases_renewed"`
	PKIRenewed   int `json:"pki_certs_renewed"`
	TotalActions int `json:"total_actions"`
}

RotationRunResponse summarizes orchestrated rotation.

type SSHCredsResponse 

type SSHCredsResponse struct {
	LeaseID    string `json:"lease_id"`
	Username   string `json:"username"`
	PrivateKey string `json:"private_key"`
	SignedKey  string `json:"signed_key"`
	Role       string `json:"role"`
	TTLSeconds int    `json:"ttl_seconds"`
	ExpiresAt  string `json:"expires_at"`
}

SSHCredsResponse is returned for SSH credential generation.

type SSHRoleRequest 

type SSHRoleRequest struct {
	TTLSeconds   int               `json:"ttl_seconds"`
	CAKeyPath    string            `json:"ca_key_path"`
	AllowedUsers []string          `json:"allowed_users,omitempty"`
	DefaultUser  string            `json:"default_user,omitempty"`
	KeyType      string            `json:"key_type,omitempty"`
	Extensions   map[string]string `json:"extensions,omitempty"`
}

SSHRoleRequest configures an OpenSSH credential role.

type SSHRoleResponse 

type SSHRoleResponse struct {
	Name         string            `json:"name"`
	TTLSeconds   int               `json:"ttl_seconds"`
	CAKeyPath    string            `json:"ca_key_path"`
	AllowedUsers []string          `json:"allowed_users,omitempty"`
	DefaultUser  string            `json:"default_user,omitempty"`
	KeyType      string            `json:"key_type,omitempty"`
	Extensions   map[string]string `json:"extensions,omitempty"`
}

SSHRoleResponse returns SSH role configuration.

type SealResponse 

type SealResponse struct {
	Sealed bool `json:"sealed"`
}

SealResponse is returned by POST /sys/seal.

type ServiceStatus 

type ServiceStatus struct {
	Status      string `json:"status"`
	Version     string `json:"version"`
	Leader      *bool  `json:"leader,omitempty"`
	HAEnabled   bool   `json:"ha_enabled,omitempty"`
	RaftEnabled bool   `json:"raft_enabled,omitempty"`
	RaftReady   *bool  `json:"raft_ready,omitempty"`
	Sealed      *bool  `json:"sealed,omitempty"`
}

ServiceStatus is returned by GET /health and GET /ready.

type SignCSRRequest 

type SignCSRRequest struct {
	Role string `json:"role"`
	CSR  string `json:"csr"`
	TTL  string `json:"ttl,omitempty"`
}

SignCSRRequest is POST /pki/sign.

type SignCSRResponse 

type SignCSRResponse struct {
	CertPEM   string   `json:"cert_pem"`
	Serial    string   `json:"serial"`
	ExpiresAt string   `json:"expires_at"`
	CAChain   []string `json:"ca_chain,omitempty"`
}

SignCSRResponse is returned for CSR signing.

type UnsealResponse 

type UnsealResponse struct {
	Sealed bool `json:"sealed"`
}

UnsealResponse is returned by POST /sys/unseal.

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.