Skip to content

Commit fb6e414

Browse files
spbsolublespbsoluble
authored
docs: remove compliance claims and fix Mermaid diagram line breaks (#12)
* docs: remove SOX audit compliance claim from architecture docs We describe what the plugin does (pre-intent logging) without asserting compliance with any audit standard we are not certified against. * docs: fix Mermaid diagram \n sequences — use <br/> for line breaks Mermaid renders literal \n in diagram labels as text. Replace with <br/> throughout all sequence and flowchart diagrams. Also quote flowchart node labels that use HTML entities, and collapse edge labels that had embedded newlines to single-line text.
1 parent 01e8ddf commit fb6e414

2 files changed

Lines changed: 60 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -406,9 +406,9 @@ sequenceDiagram
406406
participant API as CERTInext API
407407
408408
GW->>Plugin: Load CA connector configuration
409-
Plugin->>Plugin: Validate required fields\n(API URL, account number, credentials)
410-
Plugin->>Plugin: Initialize API client\nwith configured auth mode
411-
Plugin->>Plugin: Record which credential fields are populated\n(values are never logged)
409+
Plugin->>Plugin: Validate required fields<br/>(API URL, account number, credentials)
410+
Plugin->>Plugin: Initialize API client<br/>with configured auth mode
411+
Plugin->>Plugin: Record which credential fields are populated<br/>(values are never logged)
412412
GW->>Plugin: Test connection
413413
Plugin->>API: Verify credentials
414414
API-->>Plugin: Credentials accepted
@@ -427,11 +427,11 @@ sequenceDiagram
427427
participant Plugin as CERTInext Plugin
428428
participant API as CERTInext API
429429

430-
CMD->>Plugin: Start synchronization\n(full refresh or incremental since last sync)
431-
Plugin->>Plugin: Determine date filter\n(none for full sync, last sync date for incremental)
430+
CMD->>Plugin: Start synchronization<br/>(full refresh or incremental since last sync)
431+
Plugin->>Plugin: Determine date filter<br/>(none for full sync, last sync date for incremental)
432432

433433
loop Retrieve one page at a time
434-
Plugin->>API: Request next page of orders\n(filtered by date if incremental)
434+
Plugin->>API: Request next page of orders<br/>(filtered by date if incremental)
435435
API-->>Plugin: Page of order records
436436
437437
loop For each order on the page
@@ -467,11 +467,11 @@ sequenceDiagram
467467
participant Plugin as CERTInext Plugin
468468
participant API as CERTInext API
469469
470-
CMD->>Plugin: Request new certificate\n(CSR, subject, SANs, product code, requester details)
470+
CMD->>Plugin: Request new certificate<br/>(CSR, subject, SANs, product code, requester details)
471471
Plugin->>Plugin: Validate product code is present
472-
Plugin->>Plugin: Record enrollment intent in audit log\n(subject, SANs, product, requester — before any API call)
472+
Plugin->>Plugin: Record enrollment intent in audit log<br/>(subject, SANs, product, requester — before any API call)
473473
474-
Plugin->>API: Place certificate order\n(CSR, domain, organization details,\nsubscriber agreement, requestor info)
474+
Plugin->>API: Place certificate order<br/>(CSR, domain, organization details,<br/>subscriber agreement, requestor info)
475475
API-->>Plugin: Order accepted — order number assigned
476476
477477
Plugin->>API: Check order status
@@ -480,12 +480,12 @@ sequenceDiagram
480480
alt Certificate issued immediately
481481
Plugin-->>CMD: Certificate ready — PEM returned
482482
else Certificate pending approval
483-
Plugin-->>CMD: Pending — Command will pick it up\nduring the next synchronization
483+
Plugin-->>CMD: Pending — Command will pick it up<br/>during the next synchronization
484484
else Order rejected by CERTInext
485485
Plugin-->>CMD: Enrollment failed — see gateway logs
486486
end
487487
488-
Plugin->>Plugin: Record enrollment outcome in audit log\n(order number, serial number, status)
488+
Plugin->>Plugin: Record enrollment outcome in audit log<br/>(order number, serial number, status)
489489
```
490490
491491
### Renewal
@@ -496,15 +496,15 @@ When Command initiates a renewal, the plugin checks whether the existing certifi
496496
497497
```mermaid
498498
flowchart TD
499-
A([Renewal requested]) --> B{Prior certificate\nserial number\nprovided?}
499+
A([Renewal requested]) --> B{"Prior certificate<br/>serial number<br/>provided?"}
500500
B -- No --> C[Issue new certificate]
501-
B -- Yes --> D[Look up prior order\nin Command database]
502-
D --> E{Prior order\nfound?}
501+
B -- Yes --> D["Look up prior order<br/>in Command database"]
502+
D --> E{"Prior order<br/>found?"}
503503
E -- No --> C
504-
E -- Yes --> F[Check certificate\nexpiry date]
505-
F --> G{Within renewal\nwindow?}
506-
G -- Yes\nwithin window --> H[Submit new order\nlinked to prior record]
507-
G -- No\noutside window --> C
504+
E -- Yes --> F["Check certificate<br/>expiry date"]
505+
F --> G{"Within renewal<br/>window?"}
506+
G -- Yes, within window --> H["Submit new order<br/>linked to prior record"]
507+
G -- No, outside window --> C
508508
H --> I([Certificate issued or pending])
509509
C --> I
510510
```
@@ -521,8 +521,8 @@ sequenceDiagram
521521
participant Plugin as CERTInext Plugin
522522
participant API as CERTInext API
523523
524-
CMD->>Plugin: Revoke certificate\n(order number, serial number, reason code)
525-
Plugin->>Plugin: Record revocation intent in audit log\n(order number, serial, reason — before any API call)
524+
CMD->>Plugin: Revoke certificate<br/>(order number, serial number, reason code)
525+
Plugin->>Plugin: Record revocation intent in audit log<br/>(order number, serial, reason — before any API call)
526526
527527
Plugin->>API: Retrieve current certificate status
528528
API-->>Plugin: Current status and details
@@ -534,17 +534,17 @@ sequenceDiagram
534534
Plugin->>Plugin: Log error — cannot revoke
535535
Plugin-->>CMD: Error — certificate is not revocable
536536
else Certificate is issued and active
537-
Plugin->>API: Submit revocation request\n(order number, reason, remarks)
537+
Plugin->>API: Submit revocation request<br/>(order number, reason, remarks)
538538
API-->>Plugin: Revocation confirmed
539539
540-
Plugin->>Plugin: Record revocation outcome in audit log\n(order number, serial, subject, reason)
540+
Plugin->>Plugin: Record revocation outcome in audit log<br/>(order number, serial, subject, reason)
541541
Plugin-->>CMD: Certificate revoked
542542
end
543543
```
544544
545545
**Idempotency:** If Command retries a revocation request (for example, after a timeout), the plugin detects that the certificate is already revoked and returns success without submitting a duplicate request to CERTInext.
546546
547-
**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails, satisfying SOX audit requirements.
547+
**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails.
548548
549549
---
550550
@@ -554,14 +554,14 @@ When an administrator saves or edits a CERTInext CA connector in the Keyfactor C
554554
555555
```mermaid
556556
flowchart TD
557-
A([Save connector configuration]) --> B{Connector\nmarked as disabled?}
558-
B -- Yes --> C([Saved without validation\nConnector will not process requests])
559-
B -- No --> D{Required fields\npresent and valid?\nAPI URL · Account Number · Credentials}
557+
A([Save connector configuration]) --> B{"Connector<br/>marked as disabled?"}
558+
B -- Yes --> C(["Saved without validation<br/>Connector will not process requests"])
559+
B -- No --> D{"Required fields<br/>present and valid?<br/>API URL · Account Number · Credentials"}
560560
D -- Missing or invalid --> E([Validation error shown to administrator])
561-
D -- Valid --> F[Build temporary API client\nfrom supplied settings]
562-
F --> G[Send test request\nto CERTInext]
563-
G --> H{API accepted\nthe credentials?}
564-
H -- No --> I([Connection test failed\nCheck credentials and API URL])
561+
D -- Valid --> F["Build temporary API client<br/>from supplied settings"]
562+
F --> G[Send test request to CERTInext]
563+
G --> H{"API accepted<br/>the credentials?"}
564+
H -- No --> I(["Connection test failed<br/>Check credentials and API URL"])
565565
H -- Yes --> J([Connector saved and active])
566566
```
567567

‎docsource/architecture.md‎

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,9 @@ sequenceDiagram
6666
participant API as CERTInext API
6767
6868
GW->>Plugin: Load CA connector configuration
69-
Plugin->>Plugin: Validate required fields\n(API URL, account number, credentials)
70-
Plugin->>Plugin: Initialize API client\nwith configured auth mode
71-
Plugin->>Plugin: Record which credential fields are populated\n(values are never logged)
69+
Plugin->>Plugin: Validate required fields<br/>(API URL, account number, credentials)
70+
Plugin->>Plugin: Initialize API client<br/>with configured auth mode
71+
Plugin->>Plugin: Record which credential fields are populated<br/>(values are never logged)
7272
GW->>Plugin: Test connection
7373
Plugin->>API: Verify credentials
7474
API-->>Plugin: Credentials accepted
@@ -87,11 +87,11 @@ sequenceDiagram
8787
participant Plugin as CERTInext Plugin
8888
participant API as CERTInext API
8989
90-
CMD->>Plugin: Start synchronization\n(full refresh or incremental since last sync)
91-
Plugin->>Plugin: Determine date filter\n(none for full sync, last sync date for incremental)
90+
CMD->>Plugin: Start synchronization<br/>(full refresh or incremental since last sync)
91+
Plugin->>Plugin: Determine date filter<br/>(none for full sync, last sync date for incremental)
9292
9393
loop Retrieve one page at a time
94-
Plugin->>API: Request next page of orders\n(filtered by date if incremental)
94+
Plugin->>API: Request next page of orders<br/>(filtered by date if incremental)
9595
API-->>Plugin: Page of order records
9696
9797
loop For each order on the page
@@ -127,11 +127,11 @@ sequenceDiagram
127127
participant Plugin as CERTInext Plugin
128128
participant API as CERTInext API
129129
130-
CMD->>Plugin: Request new certificate\n(CSR, subject, SANs, product code, requester details)
130+
CMD->>Plugin: Request new certificate<br/>(CSR, subject, SANs, product code, requester details)
131131
Plugin->>Plugin: Validate product code is present
132-
Plugin->>Plugin: Record enrollment intent in audit log\n(subject, SANs, product, requester — before any API call)
132+
Plugin->>Plugin: Record enrollment intent in audit log<br/>(subject, SANs, product, requester — before any API call)
133133
134-
Plugin->>API: Place certificate order\n(CSR, domain, organization details,\nsubscriber agreement, requestor info)
134+
Plugin->>API: Place certificate order<br/>(CSR, domain, organization details,<br/>subscriber agreement, requestor info)
135135
API-->>Plugin: Order accepted — order number assigned
136136
137137
Plugin->>API: Check order status
@@ -140,12 +140,12 @@ sequenceDiagram
140140
alt Certificate issued immediately
141141
Plugin-->>CMD: Certificate ready — PEM returned
142142
else Certificate pending approval
143-
Plugin-->>CMD: Pending — Command will pick it up\nduring the next synchronization
143+
Plugin-->>CMD: Pending — Command will pick it up<br/>during the next synchronization
144144
else Order rejected by CERTInext
145145
Plugin-->>CMD: Enrollment failed — see gateway logs
146146
end
147147
148-
Plugin->>Plugin: Record enrollment outcome in audit log\n(order number, serial number, status)
148+
Plugin->>Plugin: Record enrollment outcome in audit log<br/>(order number, serial number, status)
149149
```
150150

151151
### Renewal
@@ -156,15 +156,15 @@ When Command initiates a renewal, the plugin checks whether the existing certifi
156156
157157
```mermaid
158158
flowchart TD
159-
A([Renewal requested]) --> B{Prior certificate\nserial number\nprovided?}
159+
A([Renewal requested]) --> B{"Prior certificate<br/>serial number<br/>provided?"}
160160
B -- No --> C[Issue new certificate]
161-
B -- Yes --> D[Look up prior order\nin Command database]
162-
D --> E{Prior order\nfound?}
161+
B -- Yes --> D["Look up prior order<br/>in Command database"]
162+
D --> E{"Prior order<br/>found?"}
163163
E -- No --> C
164-
E -- Yes --> F[Check certificate\nexpiry date]
165-
F --> G{Within renewal\nwindow?}
166-
G -- Yes\nwithin window --> H[Submit new order\nlinked to prior record]
167-
G -- No\noutside window --> C
164+
E -- Yes --> F["Check certificate<br/>expiry date"]
165+
F --> G{"Within renewal<br/>window?"}
166+
G -- Yes, within window --> H["Submit new order<br/>linked to prior record"]
167+
G -- No, outside window --> C
168168
H --> I([Certificate issued or pending])
169169
C --> I
170170
```
@@ -181,8 +181,8 @@ sequenceDiagram
181181
participant Plugin as CERTInext Plugin
182182
participant API as CERTInext API
183183
184-
CMD->>Plugin: Revoke certificate\n(order number, serial number, reason code)
185-
Plugin->>Plugin: Record revocation intent in audit log\n(order number, serial, reason — before any API call)
184+
CMD->>Plugin: Revoke certificate<br/>(order number, serial number, reason code)
185+
Plugin->>Plugin: Record revocation intent in audit log<br/>(order number, serial, reason — before any API call)
186186
187187
Plugin->>API: Retrieve current certificate status
188188
API-->>Plugin: Current status and details
@@ -194,17 +194,17 @@ sequenceDiagram
194194
Plugin->>Plugin: Log error — cannot revoke
195195
Plugin-->>CMD: Error — certificate is not revocable
196196
else Certificate is issued and active
197-
Plugin->>API: Submit revocation request\n(order number, reason, remarks)
197+
Plugin->>API: Submit revocation request<br/>(order number, reason, remarks)
198198
API-->>Plugin: Revocation confirmed
199199
200-
Plugin->>Plugin: Record revocation outcome in audit log\n(order number, serial, subject, reason)
200+
Plugin->>Plugin: Record revocation outcome in audit log<br/>(order number, serial, subject, reason)
201201
Plugin-->>CMD: Certificate revoked
202202
end
203203
```
204204

205205
**Idempotency:** If Command retries a revocation request (for example, after a timeout), the plugin detects that the certificate is already revoked and returns success without submitting a duplicate request to CERTInext.
206206

207-
**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails, satisfying SOX audit requirements.
207+
**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails.
208208

209209
---
210210

@@ -214,14 +214,14 @@ When an administrator saves or edits a CERTInext CA connector in the Keyfactor C
214214

215215
```mermaid
216216
flowchart TD
217-
A([Save connector configuration]) --> B{Connector\nmarked as disabled?}
218-
B -- Yes --> C([Saved without validation\nConnector will not process requests])
219-
B -- No --> D{Required fields\npresent and valid?\nAPI URL · Account Number · Credentials}
217+
A([Save connector configuration]) --> B{"Connector<br/>marked as disabled?"}
218+
B -- Yes --> C(["Saved without validation<br/>Connector will not process requests"])
219+
B -- No --> D{"Required fields<br/>present and valid?<br/>API URL · Account Number · Credentials"}
220220
D -- Missing or invalid --> E([Validation error shown to administrator])
221-
D -- Valid --> F[Build temporary API client\nfrom supplied settings]
222-
F --> G[Send test request\nto CERTInext]
223-
G --> H{API accepted\nthe credentials?}
224-
H -- No --> I([Connection test failed\nCheck credentials and API URL])
221+
D -- Valid --> F["Build temporary API client<br/>from supplied settings"]
222+
F --> G[Send test request to CERTInext]
223+
G --> H{"API accepted<br/>the credentials?"}
224+
H -- No --> I(["Connection test failed<br/>Check credentials and API URL"])
225225
H -- Yes --> J([Connector saved and active])
226226
```
227227

0 commit comments

Comments
 (0)