-
Notifications
You must be signed in to change notification settings - Fork 0
Open
Description
API Endpoints Implementation
Overview
Implement the core REST API endpoints for certificate operations including issuance, renewal, status checking, and CA chain retrieval, with proper request validation and response formatting.
Objective
Create well-structured, secure API endpoints that handle certificate lifecycle operations, enforce business rules, integrate with AWS PCA through the previously implemented client, and maintain proper audit trails.
Tasks
Certificate Issuance Endpoint
- Implement
POST /api/v1/certificates/issue
ininternal/api/handlers/certificates.go
- Define request structure:
type IssueRequest struct { CommonName string `json:"common_name" binding:"required"` SANs []string `json:"sans"` Profile string `json:"profile" binding:"required,oneof=client server machine"` CSR string `json:"csr,omitempty"` // Optional PEM-encoded CSR ValidityDays int `json:"validity_days" binding:"min=1,max=7"` }
- Implement request validation:
- Validate JWT token (using auth middleware)
- Check RBAC permissions against requested domains
- Use validators from 07 Security & Validation for CSR, profile, domains, IPs, and validity period (max 7 days)
- Validate all SAN entries against user permissions
- Implement processing flow:
- Extract identity from JWT token in context
- Validate domain permissions using glob patterns
- Generate key pair if CSR not provided
- Select appropriate CA based on certificate profile
- Call AWS PCA IssueCertificate via PCA client
- Store certificate metadata in database
- Create audit log entry
- Return certificate bundle in PEM format
- Define response structure:
type IssueResponse struct { Certificate string `json:"certificate"` // PEM-encoded certificate Chain string `json:"chain"` // PEM-encoded CA chain SerialNumber string `json:"serial_number"` ExpiresAt time.Time `json:"expires_at"` }
- Handle errors with appropriate HTTP status codes
- Use canonical error response schema and codes from 07 Security & Validation
- Log certificate issuance for audit
Certificate Renewal Endpoint
- Implement
POST /api/v1/certificates/renew
ininternal/api/handlers/certificates.go
- Define request structure:
type RenewRequest struct { SerialNumber string `json:"serial_number" binding:"required"` CSR string `json:"csr,omitempty"` // Optional new CSR }
- Implement renewal processing flow:
- Validate existing certificate ownership (requested_by field)
- Check if renewal is within policy window (30% of lifetime remaining)
- Reuse existing certificate parameters unless new CSR provided
- Issue new certificate via AWS PCA
- Update database with new certificate metadata
- Mark previous certificate as superseded
- Return new certificate bundle
- Define response structure (same as IssueResponse)
- Enforce renewal policies:
- Certificate must be owned by requesting user
- Renewal only allowed when 30% or less lifetime remaining
- Same profile and CA must be used
- Create audit log entry for renewal
Certificate Status Endpoint
- Implement
GET /api/v1/certificates/{serial}
ininternal/api/handlers/certificates.go
- Query certificate metadata from database using GORM
- Define response structure:
type StatusResponse struct { SerialNumber string `json:"serial_number"` CommonName string `json:"common_name"` SANs []string `json:"sans"` Status string `json:"status"` // active, expired, revoked IssuedAt time.Time `json:"issued_at"` ExpiresAt time.Time `json:"expires_at"` RequestedBy string `json:"requested_by"` Profile string `json:"profile"` IssuerCA string `json:"issuer_ca"` }
- Filter response based on requester permissions
- Return 404 if certificate not found
- Return 403 if user lacks permission to view
CA Chain Endpoint
- Implement
GET /api/v1/certificates/ca
ininternal/api/handlers/certificates.go
- Query cached CA certificates from database
- Define response structure:
type CAChainResponse struct { RootCA string `json:"root_ca"` // PEM-encoded IntermediateCAs map[string]string `json:"intermediate_cas"` // CA name -> PEM LastUpdated time.Time `json:"last_updated"` }
- Include root CA and all intermediate CAs
- Implement caching with 1-hour TTL as specified
- Refresh cache if expired
Request/Response Helpers
- Implement standard error response handler:
// Must conform to the schema defined in 07 Security & Validation func ErrorResponse(c *gin.Context, code int, err string, details map[string]interface{})
- Implement request ID extraction for tracing
- Add response timing metrics
Router Configuration
- Configure routes in
internal/api/router.go
- Set up API versioning with
/api/v1
prefix - Apply authentication middleware to protected endpoints
- Apply RBAC middleware with appropriate permissions:
v1 := router.Group("/api/v1") v1.Use(JWTAuthMiddleware()) { certs := v1.Group("/certificates") { certs.POST("/issue", RequirePermission("cert:issue"), IssueHandler) certs.POST("/renew", RequirePermission("cert:renew"), RenewHandler) certs.GET("/:serial", StatusHandler) certs.GET("/ca", CAChainHandler) } }
- Configure rate limiting if needed
Input Validation
- Use Gin's binding tags for basic validation
- Use custom validators defined in 07 Security & Validation
- Return detailed validation errors per 07 Security & Validation
Database Operations
- Implement certificate storage using GORM:
func StoreCertificate(db *gorm.DB, cert *Certificate) error func GetCertificateBySerial(db *gorm.DB, serial string) (*Certificate, error) func UpdateCertificateStatus(db *gorm.DB, serial string, status string) error
- Use transactions for multi-step operations
- Implement proper error handling for database operations
- Add database query logging for debugging
Acceptance Criteria
- All four endpoints implemented and functional
- Certificate issuance completes in <2 seconds (95th percentile)
- Certificate status lookup completes in <500ms (95th percentile)
- Proper authentication and authorization on all endpoints
- Domain permissions enforced for issuance and renewal
- Renewal policy (30% lifetime) enforced
- Audit logs created for all operations
- Error responses follow standard format
- Input validation working for all fields
- Database operations use transactions appropriately
Technical Considerations
- Use Gin's built-in features for routing and middleware
- Leverage GORM for database operations
- Implement idempotency for certificate issuance (check for duplicates)
- Use context for request-scoped values (user, request ID)
- Return appropriate HTTP status codes (200, 201, 400, 401, 403, 404, 500, 503)
- Stream large responses if needed (certificate chains)
- Consider caching frequently accessed data
Dependencies
- Gin framework (from issue feat: adds cuetools package #1)
- GORM models (from issues feat: adds cuetools package #1 and feat: adds blueprint package #2)
- JWT validation middleware (from issue chore: resizes README logo #3)
- RBAC middleware (from issue chore: resizes README logo #3)
- AWS PCA client (from issue feat: adds blueprint package #2)
- Certificate validation utilities (from issue feat: adds blueprint package #2)
Testing Requirements
- Unit tests for each endpoint handler
- Unit tests for input validation
- Unit tests for response formatting
- Integration tests for full request flow
- Test authentication and authorization scenarios
- Test error handling for various failure cases
- Test renewal policy enforcement
- Test concurrent requests handling
- Load test endpoints (5 RPS sustained)
Definition of Done
- Code reviewed and approved
- All tests passing
- API documentation updated
- Endpoints tested with curl/Postman
- Performance requirements met
- Error scenarios handled gracefully
- Audit logging verified
- No security vulnerabilities
Metadata
Metadata
Assignees
Labels
No labels