mirror of
https://github.com/outbackdingo/step-ca-webui.git
synced 2026-01-27 18:20:22 +00:00
Extract docs started
This commit is contained in:
stone-w4tch3r
408
README.md
408
README.md
@@ -234,415 +234,13 @@ class LogEntry:
|
||||
|
||||
### Core API
|
||||
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: Step-CA Management API
|
||||
version: 0.0.1
|
||||
description: API for managing step-ca Certificate Authority
|
||||
See [docs/core-api.md](docs/core-api.md) for OpenAPI specification.
|
||||
|
||||
servers:
|
||||
- url: https://api.example.com/v1
|
||||
|
||||
paths:
|
||||
/certificates:
|
||||
get:
|
||||
summary: List all certificates
|
||||
parameters:
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Certificate'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/generate:
|
||||
post:
|
||||
summary: Generate certificate
|
||||
parameters:
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CertificateGenerateRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview or generation result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateGenerateResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/renew:
|
||||
post:
|
||||
summary: Preview renew certificate command
|
||||
parameters:
|
||||
- name: certId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: duration
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
description: "Duration in seconds"
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateRenewResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/revoke:
|
||||
post:
|
||||
summary: Preview revoke certificate command
|
||||
parameters:
|
||||
- name: certId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateRevokeResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/logs/single:
|
||||
get:
|
||||
summary: Get log entry by ID
|
||||
parameters:
|
||||
- name: logId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LogEntry'
|
||||
|
||||
|
||||
/logs:
|
||||
get:
|
||||
summary: Retrieve logs
|
||||
parameters:
|
||||
- name: severity
|
||||
in: query
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enum: [ DEBUG, INFO, WARN, ERROR ]
|
||||
- name: traceId
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
description: "UUID format"
|
||||
- name: commandsOnly
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
- name: page
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
- name: pageSize
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/LogEntry'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
Certificate:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum: [ Active, Expired, Revoked ]
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateGenerateRequest:
|
||||
type: object
|
||||
properties:
|
||||
keyName:
|
||||
type: string
|
||||
keyType:
|
||||
type: string
|
||||
enum: [ RSA, ECDSA ]
|
||||
duration:
|
||||
type: string
|
||||
|
||||
CommandPreview:
|
||||
type: object
|
||||
properties:
|
||||
command:
|
||||
type: string
|
||||
|
||||
CertificateGenerateResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
certificateName:
|
||||
type: string
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateRenewResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
newExpirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateRevokeResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
revocationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
LogEntry:
|
||||
type: object
|
||||
properties:
|
||||
entry_id:
|
||||
type: integer
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
severity:
|
||||
type: string
|
||||
enum: [ DEBUG, INFO, WARN, ERROR ]
|
||||
message:
|
||||
type: string
|
||||
traceId:
|
||||
type: string
|
||||
description: "UUID format"
|
||||
commandInfo:
|
||||
$ref: '#/components/schemas/CommandInfo'
|
||||
nullable: true
|
||||
description: Contains command execution info, if entry is related to command
|
||||
|
||||
CommandInfo:
|
||||
type: object
|
||||
properties:
|
||||
command:
|
||||
type: string
|
||||
output:
|
||||
type: string
|
||||
exitCode:
|
||||
type: integer
|
||||
```
|
||||
---
|
||||
|
||||
### Class Diagram
|
||||
```puml
|
||||
@startuml
|
||||
|
||||
package "Shared Components" {
|
||||
class CLIWrapper {
|
||||
- sanitize_input(input)
|
||||
+ execute_command(command)
|
||||
}
|
||||
|
||||
class Logger {
|
||||
- log_file: str
|
||||
+ log(severity, message, trace_id, command_info)
|
||||
+ get_logs(filters)
|
||||
+ get_log_entry(log_id)
|
||||
}
|
||||
|
||||
enum LogSeverity {
|
||||
DEBUG
|
||||
INFO
|
||||
WARN
|
||||
ERROR
|
||||
}
|
||||
|
||||
class CommandInfo {
|
||||
+ command: str
|
||||
+ output: str
|
||||
+ exit_code: int
|
||||
+ action: str
|
||||
}
|
||||
|
||||
class LogEntry {
|
||||
+ entry_id: int
|
||||
+ timestamp: datetime
|
||||
+ severity: LogSeverity
|
||||
+ message: str
|
||||
+ trace_id: UUID
|
||||
+ command_info: CommandInfo
|
||||
}
|
||||
|
||||
Logger --> LogSeverity : uses
|
||||
Logger --> LogEntry : creates
|
||||
LogEntry --> CommandInfo : contains
|
||||
}
|
||||
|
||||
package "WebFrontend Container" {
|
||||
class FlaskWebServer {
|
||||
- app: Flask
|
||||
+ run()
|
||||
+ route_dashboard()
|
||||
+ route_logs()
|
||||
+ route_certificate_management()
|
||||
}
|
||||
|
||||
class UIComponents {
|
||||
+ render_dashboard()
|
||||
+ render_logs_page()
|
||||
+ render_certificate_list()
|
||||
+ render_generate_cert_modal()
|
||||
}
|
||||
|
||||
class APIClient {
|
||||
- base_url: str
|
||||
- api_key: str
|
||||
+ get_certificates()
|
||||
+ generate_certificate(params)
|
||||
+ renew_certificate(cert_id, duration)
|
||||
+ revoke_certificate(cert_id)
|
||||
+ get_logs(filters)
|
||||
}
|
||||
|
||||
FlaskWebServer --> UIComponents : uses
|
||||
FlaskWebServer --> APIClient : uses
|
||||
}
|
||||
|
||||
package "Core Container" {
|
||||
class MainApplication {
|
||||
+ initialize()
|
||||
+ run()
|
||||
}
|
||||
|
||||
class APIServer {
|
||||
- app: Flask
|
||||
+ run()
|
||||
+ route_certificates()
|
||||
+ route_generate_certificate()
|
||||
+ route_renew_certificate()
|
||||
+ route_revoke_certificate()
|
||||
+ route_logs()
|
||||
}
|
||||
|
||||
class CertificateManager {
|
||||
+ list_certificates()
|
||||
+ generate_certificate(params)
|
||||
+ renew_certificate(cert_id, duration)
|
||||
+ revoke_certificate(cert_id)
|
||||
}
|
||||
|
||||
MainApplication --> APIServer : initializes
|
||||
MainApplication --> CertificateManager : uses
|
||||
MainApplication --> Logger : uses
|
||||
|
||||
APIServer --> CertificateManager : uses
|
||||
APIServer --> Logger : uses
|
||||
|
||||
CertificateManager --> CLIWrapper : uses
|
||||
CertificateManager --> Logger : uses
|
||||
}
|
||||
|
||||
package "AutoSetup Component" {
|
||||
class AutoSetup {
|
||||
+ install_stepca()
|
||||
+ setup_stepca()
|
||||
+ create_root_certificate()
|
||||
+ prepare_mtls_certificates()
|
||||
+ run_docker_compose()
|
||||
}
|
||||
|
||||
AutoSetup --> CLIWrapper : uses
|
||||
AutoSetup --> Logger : uses
|
||||
}
|
||||
|
||||
|
||||
package "Host System" {
|
||||
rectangle "step-ca CLI" as stepca {
|
||||
}
|
||||
}
|
||||
|
||||
CLIWrapper --> stepca : executes commands
|
||||
|
||||
APIClient ..> APIServer : communicates via mTLS
|
||||
|
||||
@enduml
|
||||
```
|
||||
See XXX
|
||||
|
||||
### File structure
|
||||
```
|
||||
|
||||
134
docs/class-diagram.puml
Normal file
134
docs/class-diagram.puml
Normal file
@@ -0,0 +1,134 @@
|
||||
This diagram describes the class structure of the application's python components.
|
||||
|
||||
@startuml
|
||||
|
||||
package "Shared Components" {
|
||||
class CLIWrapper {
|
||||
- sanitize_input(input)
|
||||
+ execute_command(command)
|
||||
}
|
||||
|
||||
class Logger {
|
||||
- log_file: str
|
||||
+ log(severity, message, trace_id, command_info)
|
||||
+ get_logs(filters)
|
||||
+ get_log_entry(log_id)
|
||||
}
|
||||
|
||||
enum LogSeverity {
|
||||
DEBUG
|
||||
INFO
|
||||
WARN
|
||||
ERROR
|
||||
}
|
||||
|
||||
class CommandInfo {
|
||||
+ command: str
|
||||
+ output: str
|
||||
+ exit_code: int
|
||||
+ action: str
|
||||
}
|
||||
|
||||
class LogEntry {
|
||||
+ entry_id: int
|
||||
+ timestamp: datetime
|
||||
+ severity: LogSeverity
|
||||
+ message: str
|
||||
+ trace_id: UUID
|
||||
+ command_info: CommandInfo
|
||||
}
|
||||
|
||||
Logger --> LogSeverity : uses
|
||||
Logger --> LogEntry : creates
|
||||
LogEntry --> CommandInfo : contains
|
||||
}
|
||||
|
||||
package "WebFrontend Container" {
|
||||
class FlaskWebServer {
|
||||
- app: Flask
|
||||
+ run()
|
||||
+ route_dashboard()
|
||||
+ route_logs()
|
||||
+ route_certificate_management()
|
||||
}
|
||||
|
||||
class UIComponents {
|
||||
+ render_dashboard()
|
||||
+ render_logs_page()
|
||||
+ render_certificate_list()
|
||||
+ render_generate_cert_modal()
|
||||
}
|
||||
|
||||
class APIClient {
|
||||
- base_url: str
|
||||
- api_key: str
|
||||
+ get_certificates()
|
||||
+ generate_certificate(params)
|
||||
+ renew_certificate(cert_id, duration)
|
||||
+ revoke_certificate(cert_id)
|
||||
+ get_logs(filters)
|
||||
}
|
||||
|
||||
FlaskWebServer --> UIComponents : uses
|
||||
FlaskWebServer --> APIClient : uses
|
||||
}
|
||||
|
||||
package "Core Container" {
|
||||
class MainApplication {
|
||||
+ initialize()
|
||||
+ run()
|
||||
}
|
||||
|
||||
class APIServer {
|
||||
- app: Flask
|
||||
+ run()
|
||||
+ route_certificates()
|
||||
+ route_generate_certificate()
|
||||
+ route_renew_certificate()
|
||||
+ route_revoke_certificate()
|
||||
+ route_logs()
|
||||
}
|
||||
|
||||
class CertificateManager {
|
||||
+ list_certificates()
|
||||
+ generate_certificate(params)
|
||||
+ renew_certificate(cert_id, duration)
|
||||
+ revoke_certificate(cert_id)
|
||||
}
|
||||
|
||||
MainApplication --> APIServer : initializes
|
||||
MainApplication --> CertificateManager : uses
|
||||
MainApplication --> Logger : uses
|
||||
|
||||
APIServer --> CertificateManager : uses
|
||||
APIServer --> Logger : uses
|
||||
|
||||
CertificateManager --> CLIWrapper : uses
|
||||
CertificateManager --> Logger : uses
|
||||
}
|
||||
|
||||
package "AutoSetup Component" {
|
||||
class AutoSetup {
|
||||
+ install_stepca()
|
||||
+ setup_stepca()
|
||||
+ create_root_certificate()
|
||||
+ prepare_mtls_certificates()
|
||||
+ run_docker_compose()
|
||||
}
|
||||
|
||||
AutoSetup --> CLIWrapper : uses
|
||||
AutoSetup --> Logger : uses
|
||||
}
|
||||
|
||||
|
||||
package "Host System" {
|
||||
rectangle "step-ca CLI" as stepca {
|
||||
}
|
||||
}
|
||||
|
||||
CLIWrapper --> stepca : executes commands
|
||||
|
||||
APIClient ..> APIServer : communicates via mTLS
|
||||
|
||||
@enduml
|
||||
```
|
||||
276
docs/core-api.md
Normal file
276
docs/core-api.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# API specification for Core API
|
||||
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: Step-CA Management API
|
||||
version: 0.0.1
|
||||
description: API for managing step-ca Certificate Authority
|
||||
|
||||
servers:
|
||||
- url: https://api.example.com/v1
|
||||
|
||||
paths:
|
||||
/certificates:
|
||||
get:
|
||||
summary: List all certificates
|
||||
parameters:
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Certificate'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/generate:
|
||||
post:
|
||||
summary: Generate certificate
|
||||
parameters:
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CertificateGenerateRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview or generation result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateGenerateResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/renew:
|
||||
post:
|
||||
summary: Preview renew certificate command
|
||||
parameters:
|
||||
- name: certId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: duration
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
description: "Duration in seconds"
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateRenewResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/certificates/revoke:
|
||||
post:
|
||||
summary: Preview revoke certificate command
|
||||
parameters:
|
||||
- name: certId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: preview
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
'200':
|
||||
description: Command preview
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/CertificateRevokeResult'
|
||||
- $ref: '#/components/schemas/CommandPreview'
|
||||
|
||||
/logs/single:
|
||||
get:
|
||||
summary: Get log entry by ID
|
||||
parameters:
|
||||
- name: logId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LogEntry'
|
||||
|
||||
|
||||
/logs:
|
||||
get:
|
||||
summary: Retrieve logs
|
||||
parameters:
|
||||
- name: severity
|
||||
in: query
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enum: [ DEBUG, INFO, WARN, ERROR ]
|
||||
- name: traceId
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
description: "UUID format"
|
||||
- name: commandsOnly
|
||||
in: query
|
||||
schema:
|
||||
type: boolean
|
||||
- name: page
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
- name: pageSize
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/LogEntry'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
Certificate:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum: [ Active, Expired, Revoked ]
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateGenerateRequest:
|
||||
type: object
|
||||
properties:
|
||||
keyName:
|
||||
type: string
|
||||
keyType:
|
||||
type: string
|
||||
enum: [ RSA, ECDSA ]
|
||||
duration:
|
||||
type: string
|
||||
|
||||
CommandPreview:
|
||||
type: object
|
||||
properties:
|
||||
command:
|
||||
type: string
|
||||
|
||||
CertificateGenerateResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
certificateName:
|
||||
type: string
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateRenewResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
newExpirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
CertificateRevokeResult:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
logEntryId:
|
||||
type: string
|
||||
certificateId:
|
||||
type: string
|
||||
revocationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
LogEntry:
|
||||
type: object
|
||||
properties:
|
||||
entry_id:
|
||||
type: integer
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
severity:
|
||||
type: string
|
||||
enum: [ DEBUG, INFO, WARN, ERROR ]
|
||||
message:
|
||||
type: string
|
||||
traceId:
|
||||
type: string
|
||||
description: "UUID format"
|
||||
commandInfo:
|
||||
$ref: '#/components/schemas/CommandInfo'
|
||||
nullable: true
|
||||
description: Contains command execution info, if entry is related to command
|
||||
|
||||
CommandInfo:
|
||||
type: object
|
||||
properties:
|
||||
command:
|
||||
type: string
|
||||
output:
|
||||
type: string
|
||||
exitCode:
|
||||
type: integer
|
||||
```
|
||||
Reference in New Issue
Block a user