httpserver

Documentation

Index

• func AdminAuthMiddleware(resolver func(string) (crypto.PublicKey, error), ...) func(http.Handler) http.Handler
• func AdminClaimsFromContext(ctx context.Context) map[string]interface{}
• func AdminSubjectFromContext(ctx context.Context) string
• func AuditMiddleware(next http.Handler) http.Handler
• func CorrelationIDMiddleware(next http.Handler) http.Handler
• func HandleKeygeneration(w http.ResponseWriter, r *http.Request)
• func LoggingMiddleware(next http.Handler) http.Handler
• func MiddlewareChain(middlewares ...func(http.Handler) http.Handler) func(http.Handler) http.Handler
• func RateLimitAuditMiddleware(next http.Handler) http.Handler
• func RegisterAdminRevocationRoutes(mux *http.ServeMux)
• func RegisterBootstrapRoutes(mux *http.ServeMux, store keystore.KeyStore, cfg config.IssuerConfig, ...)
• func RegisterGatewayRoutes(mux *http.ServeMux, cfg *GatewayConfig)
• func RegisterHealthRoutes(mux *http.ServeMux, readinessCheck func(context.Context) error)
• func RegisterIssuerRoutes(mux *http.ServeMux, store keystore.KeyStore, cfg config.IssuerConfig, ...)
• func RegisterPolicyAdminRoutes(mux *http.ServeMux, store policy.Store, defaultTenantID string)
• func RegisterTrustRegistryRoutes(mux *http.ServeMux, trustRegistry domain.TrustRegistry, defaultTenantID string)
• func RegisterVerifierRoutes(mux *http.ServeMux, resolver func(string) (crypto.PublicKey, error), ...)
• func RequestContext(next http.Handler) http.Handler
• func RequestIDFromContext(ctx context.Context) string
• func SecurityHeadersMiddleware(next http.Handler) http.Handler
• func StandardMiddlewareChain() func(http.Handler) http.Handler
• func TenantIDFromContext(ctx context.Context) string
• func TenantMiddleware(resolver tenant.Resolver, next http.Handler) http.Handler
• func WriteAPIError(w http.ResponseWriter, status int, code string, description string)
• func WriteAPIErrorWithFields(w http.ResponseWriter, status int, code string, description string, ...)
• func WriteDIDError(w http.ResponseWriter, err error)
• func WriteInternalError(w http.ResponseWriter, message string)
• func WriteValidationError(w http.ResponseWriter, err error)
• type APIError
• type AddTrustedIssuerRequest
• type AddTrustedIssuerResponse
• type AgentContext
• type BootstrapRequest
• type BootstrapResponse
• type DelegateRequest
• type FieldError
• type GatewayAuthorizeRequest
• type GatewayAuthorizeResponse
• type GatewayConfig
• type HealthResponse
• type IssueRequest
• type IssueResponse
• type KeygenRequest
• type KeygenResponse
• type PoliciesResponse
• type PolicyRequest
• type PolicyResponse
• type RevocationRequest
• type VerifyRequest
• type VerifyResponse

Functions

func AdminAuthMiddleware

func AdminAuthMiddleware(resolver func(string) (crypto.PublicKey, error), trustRegistry domain.TrustRegistry, defaultTenantID string) func(http.Handler) http.Handler

AdminAuthMiddleware creates middleware that requires valid admin VCs

func AdminClaimsFromContext

func AdminClaimsFromContext(ctx context.Context) map[string]interface{}

AdminClaimsFromContext extracts admin claims from request context

func AdminSubjectFromContext

func AdminSubjectFromContext(ctx context.Context) string

AdminSubjectFromContext extracts the admin subject from request context

func AuditMiddleware

func AuditMiddleware(next http.Handler) http.Handler

AuditMiddleware logs HTTP requests for security and compliance.

func CorrelationIDMiddleware

func CorrelationIDMiddleware(next http.Handler) http.Handler

CorrelationIDMiddleware adds correlation IDs to requests for tracing.

func HandleKeygeneration

func HandleKeygeneration(w http.ResponseWriter, r *http.Request)

HandleKeygeneration handles POST /v1/keys/generate requests. It generates a new DID with embedded public key and optionally returns the private key.

Security Note: Returning private keys over HTTP is intended for development/testing only. In production, consider: - Only returning the DID (not the private key) - Using TLS for all connections - Implementing proper key custody (vault, HSM, etc.) - Rate limiting to prevent abuse

func LoggingMiddleware

func LoggingMiddleware(next http.Handler) http.Handler

LoggingMiddleware is deprecated, use AuditMiddleware instead. Kept for backward compatibility.

func MiddlewareChain

func MiddlewareChain(middlewares ...func(http.Handler) http.Handler) func(http.Handler) http.Handler

MiddlewareChain combines multiple middleware functions.

func RateLimitAuditMiddleware

func RateLimitAuditMiddleware(next http.Handler) http.Handler

RateLimitAuditMiddleware logs rate limit events for security monitoring.

func RegisterAdminRevocationRoutes

func RegisterAdminRevocationRoutes(mux *http.ServeMux)

RegisterAdminRevocationRoutes adds simple revocation management endpoints for demos.

func RegisterBootstrapRoutes

func RegisterBootstrapRoutes(mux *http.ServeMux, store keystore.KeyStore, cfg config.IssuerConfig, trustRegistry domain.TrustRegistry)

RegisterBootstrapRoutes wires bootstrap HTTP routes into the provided mux WARNING: Bootstrap endpoint has no authentication - should be disabled in production or protected by network-level controls (VPN, private subnets, etc.)

func RegisterGatewayRoutes

func RegisterGatewayRoutes(mux *http.ServeMux, cfg *GatewayConfig)

RegisterGatewayRoutes wires gateway-specific routes into the provided mux.

func RegisterHealthRoutes

func RegisterHealthRoutes(mux *http.ServeMux, readinessCheck func(context.Context) error)

RegisterHealthRoutes attaches health and readiness endpoints to the mux.

func RegisterIssuerRoutes

func RegisterIssuerRoutes(mux *http.ServeMux, store keystore.KeyStore, cfg config.IssuerConfig, auditStore storage.AuditStore)

RegisterIssuerRoutes wires issuer HTTP routes into the provided mux.

func RegisterPolicyAdminRoutes

func RegisterPolicyAdminRoutes(mux *http.ServeMux, store policy.Store, defaultTenantID string)

RegisterPolicyAdminRoutes wires admin policy CRUD handlers.

func RegisterTrustRegistryRoutes

func RegisterTrustRegistryRoutes(mux *http.ServeMux, trustRegistry domain.TrustRegistry, defaultTenantID string)

RegisterTrustRegistryRoutes registers HTTP routes for trust registry management WARNING: These endpoints have no authentication in development mode

func RegisterVerifierRoutes

func RegisterVerifierRoutes(mux *http.ServeMux, resolver func(string) (crypto.PublicKey, error), registry domain.TrustRegistry, defaultTenantID string, verifierMetrics metrics.VerifierMetrics, now func() time.Time)

RegisterVerifierRoutes wires verifier HTTP routes into the provided mux.

func RequestContext

func RequestContext(next http.Handler) http.Handler

RequestContext is deprecated, use CorrelationIDMiddleware instead. Kept for backward compatibility.

func RequestIDFromContext

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext extracts the request ID from context. Deprecated: Use logging.GetCorrelationID instead.

func SecurityHeadersMiddleware

func SecurityHeadersMiddleware(next http.Handler) http.Handler

SecurityHeadersMiddleware adds security headers to responses.

func StandardMiddlewareChain

func StandardMiddlewareChain() func(http.Handler) http.Handler

StandardMiddlewareChain provides a standard set of middleware for services.

func TenantIDFromContext

func TenantIDFromContext(ctx context.Context) string

TenantIDFromContext extracts the tenant ID from context. Deprecated: Use logging.GetTenantID instead.

func TenantMiddleware

func TenantMiddleware(resolver tenant.Resolver, next http.Handler) http.Handler

TenantMiddleware enforces tenant resolution rules before reaching handlers.

func WriteAPIError

func WriteAPIError(w http.ResponseWriter, status int, code string, description string)

WriteAPIError writes a standardized API error response.

func WriteAPIErrorWithFields

func WriteAPIErrorWithFields(w http.ResponseWriter, status int, code string, description string, fields []FieldError)

WriteAPIErrorWithFields writes a standardized API error response with field-level errors.

func WriteDIDError

func WriteDIDError(w http.ResponseWriter, err error)

WriteDIDError writes a DID-specific error with helpful information.

func WriteInternalError

func WriteInternalError(w http.ResponseWriter, message string)

WriteInternalError writes an internal server error while hiding implementation details.

func WriteValidationError

func WriteValidationError(w http.ResponseWriter, err error)

WriteValidationError writes a validation error with better developer experience.

Types

type APIError

type APIError struct {
	Error       string       `json:"error"`
	Description string       `json:"description,omitempty"`
	Code        string       `json:"code"`
	APIVersion  string       `json:"api_version"`
	Fields      []FieldError `json:"fields,omitempty"`
	TraceID     string       `json:"trace_id,omitempty"`
}

APIError provides a consistent error body for HTTP handlers with enhanced error information.

type AddTrustedIssuerRequest

type AddTrustedIssuerRequest struct {
	IssuerDID string `json:"issuer_did"`
}

AddTrustedIssuerRequest represents the request to add a trusted issuer

type AddTrustedIssuerResponse

type AddTrustedIssuerResponse struct {
	Success   bool   `json:"success"`
	IssuerDID string `json:"issuer_did"`
	Message   string `json:"message"`
}

AddTrustedIssuerResponse represents the response after adding a trusted issuer

type AgentContext

type AgentContext struct {
	ActingOnBehalfOf string   `json:"acting_on_behalf_of"`
	DelegationDepth  int      `json:"delegation_depth"`
	Scope            []string `json:"scope,omitempty"`
}

AgentContext surfaces on-behalf-of metadata for agent invocations.

type BootstrapRequest

type BootstrapRequest struct {
	RootAdminDID string `json:"root_admin_did"`
}

BootstrapRequest represents the payload for system bootstrap

type BootstrapResponse

type BootstrapResponse struct {
	IssuerDID           string    `json:"issuer_did"`
	RootAdminCredential string    `json:"root_admin_credential"`
	ExpiresAt           time.Time `json:"expires_at"`
	APIVersion          string    `json:"api_version"`
}

BootstrapResponse represents the response from system bootstrap

type DelegateRequest

type DelegateRequest struct {
	ParentCredential string   `json:"parent_credential"`
	DelegateDID      string   `json:"delegate_did"`
	Scope            []string `json:"scope"`
	TTLSeconds       int64    `json:"ttl_seconds"`
}

DelegateRequest represents the payload for issuing delegated credentials.

type FieldError

type FieldError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
	Code    string `json:"code"`
}

FieldError provides detailed field-level validation errors.

type GatewayAuthorizeRequest

type GatewayAuthorizeRequest struct {
	Credential       string   `json:"credential"`
	Credentials      []string `json:"credentials"`
	ExpectedAudience string   `json:"expected_audience"`
	WantSyntheticJWT bool     `json:"want_synthetic_jwt"`
	Resource         string   `json:"resource"`
	Action           string   `json:"action"`
}

GatewayAuthorizeRequest is the payload expected by the gateway authorize endpoint.

type GatewayAuthorizeResponse

type GatewayAuthorizeResponse struct {
	Allowed          bool                   `json:"allowed"`
	Subject          string                 `json:"subject,omitempty"`
	ActingOnBehalfOf string                 `json:"acting_on_behalf_of,omitempty"`
	DelegationDepth  int                    `json:"delegation_depth,omitempty"`
	Claims           map[string]interface{} `json:"claims,omitempty"`
	SyntheticJWT     string                 `json:"synthetic_jwt,omitempty"`
	Agent            *AgentContext          `json:"agent,omitempty"`
	TenantID         string                 `json:"tenant_id,omitempty"`
	PolicyID         *int64                 `json:"policy_id,omitempty"`
	ErrorCode        string                 `json:"error_code,omitempty"`
	Message          string                 `json:"message,omitempty"`
	Details          map[string]any         `json:"details,omitempty"`
	Reason           string                 `json:"reason,omitempty"`
	APIVersion       string                 `json:"api_version"`
}

GatewayAuthorizeResponse is returned to gateways or reverse proxies.

type GatewayConfig

type GatewayConfig struct {
	Resolver        func(string) (crypto.PublicKey, error)
	Registry        domain.TrustRegistry
	PolicyEngine    policy.Engine
	DefaultTenantID string
	SigningKey      crypto.Signer
	JWTIssuer       string
	DecisionCache   cache.DecisionCache
	Limiter         ratelimit.Limiter
	Metrics         metrics.GatewayMetrics
	Now             func() time.Time
}

GatewayConfig encapsulates all dependencies for gateway route handlers.

type HealthResponse

type HealthResponse struct {
	Status     string `json:"status"`
	APIVersion string `json:"api_version"`
}

HealthResponse is used for health and readiness checks.

type IssueRequest

type IssueRequest struct {
	SubjectDID string                 `json:"subject_did"`
	TTLSeconds int64                  `json:"ttl_seconds"`
	Claims     map[string]interface{} `json:"claims"`
	Format     string                 `json:"format"`
}

IssueRequest represents the request payload for issuing credentials.

type IssueResponse

type IssueResponse struct {
	Credential  string   `json:"credential"`
	Disclosures []string `json:"disclosures,omitempty"`
	Format      string   `json:"format,omitempty"`
	APIVersion  string   `json:"api_version"`
}

IssueResponse represents the response payload after issuance.

type KeygenRequest

type KeygenRequest struct {
	Algorithm        string `json:"algorithm"`          // EdDSA or ES256
	ReturnPrivateKey bool   `json:"return_private_key"` // Whether to return the private key in response
}

KeygenRequest represents the request to generate a new DID.

type KeygenResponse

type KeygenResponse struct {
	DID           string `json:"did"`
	Algorithm     string `json:"algorithm"`
	PublicJWK     string `json:"public_jwk"`
	PrivateKeyPEM string `json:"private_key_pem,omitempty"` // Only included if requested
}

KeygenResponse represents the generated DID and optional key material.

type PoliciesResponse

type PoliciesResponse struct {
	Policies   []policy.Policy `json:"policies"`
	APIVersion string          `json:"api_version"`
}

type PolicyRequest

type PolicyRequest struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Effect      string         `json:"effect"`
	Actions     []string       `json:"actions"`
	Resources   []string       `json:"resources"`
	Subjects    []string       `json:"subjects"`
	Conditions  map[string]any `json:"conditions,omitempty"`
	Priority    *int           `json:"priority,omitempty"`
	Enabled     *bool          `json:"enabled,omitempty"`
}

type PolicyResponse

type PolicyResponse struct {
	Policy     policy.Policy `json:"policy"`
	APIVersion string        `json:"api_version"`
}

type RevocationRequest

type RevocationRequest struct {
	CredentialID string `json:"credential_id"`
	Reason       string `json:"reason,omitempty"`
	Remove       bool   `json:"remove,omitempty"`
}

type VerifyRequest

type VerifyRequest struct {
	Credential       string   `json:"credential"`
	Credentials      []string `json:"credentials"`
	ExpectedAudience string   `json:"expected_audience"`
	Disclosures      []string `json:"disclosures"`
	Format           string   `json:"format"`
}

VerifyRequest represents a verifier request payload.

type VerifyResponse

type VerifyResponse struct {
	Valid            bool      `json:"valid"`
	Subject          string    `json:"subject"`
	Issuer           string    `json:"issuer"`
	ExpiresAt        time.Time `json:"expires_at"`
	ActingOnBehalfOf string    `json:"acting_on_behalf_of,omitempty"`
	DelegationDepth  int       `json:"delegation_depth"`
	APIVersion       string    `json:"api_version"`
}

VerifyResponse represents the verifier response payload.