Expose ca / cert endpoints to public api ref

backend/src/lib/api-docs/constants.ts

@@ -728,11 +728,10 @@ export const AUDIT_LOG_STREAMS = {
   }
 };
 
-// TODO
 export const CERTIFICATE_AUTHORITIES = {
   CREATE: {
     projectSlug: "Slug of the project to create the CA in.",
-    type: "The type of CA to create (root or intermediate)",
+    type: "The type of CA to create",
     friendlyName: "A friendly name for the CA",
     organization: "The organization (O) for the CA",
     ou: "The organization unit (OU) for the CA",
@@ -745,23 +744,27 @@ export const CERTIFICATE_AUTHORITIES = {
     maxPathLength:
       "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain.",
     keyAlgorithm:
-      "The type of public key algorithm and size, in bits, of the key pair for the CA; when you create an intermediate CA, you must use a key algorithm supported by the parent CA. This should be one of RSA_2048, RSA_4096, EC_prime256v1, or EC_secp384r1."
+      "The type of public key algorithm and size, in bits, of the key pair for the CA; when you create an intermediate CA, you must use a key algorithm supported by the parent CA."
   },
   GET: {
     caId: "The ID of the CA to get"
   },
   UPDATE: {
-    caId: "The ID of the CA to get",
+    caId: "The ID of the CA to update",
     status: "The status of the CA to update to. This can be one of active or disabled"
   },
   DELETE: {
     caId: "The ID of the CA to delete"
   },
   GET_CSR: {
-    caId: "The ID of the CA to generate CSR from"
+    caId: "The ID of the CA to generate CSR from",
+    csr: "The generated CSR from the CA"
   },
   GET_CERT: {
-    caId: "The ID of the CA to get the certificate body and certificate chain from"
+    caId: "The ID of the CA to get the certificate body and certificate chain from",
+    certificate: "The certificate body of the CA",
+    certificateChain: "The certificate chain of the CA",
+    serialNumber: "The serial number of the CA certificate"
   },
   SIGN_INTERMEDIATE: {
     caId: "The ID of the CA to sign the intermediate certificate with",
@@ -769,7 +772,11 @@ export const CERTIFICATE_AUTHORITIES = {
     notBefore: "The date and time when the intermediate CA becomes valid in YYYY-MM-DDTHH:mm:ss.sssZ format",
     notAfter: "The date and time when the intermediate CA expires in YYYY-MM-DDTHH:mm:ss.sssZ format",
     maxPathLength:
-      "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain."
+      "The maximum number of intermediate CAs that may follow this CA in the certificate / CA chain. A maxPathLength of -1 implies no path limit on the chain.",
+    certificate: "The signed intermediate certificate",
+    certificateChain: "The certificate chain of the intermediate certificate",
+    issuingCaCertificate: "The certificate of the issuing CA",
+    serialNumber: "The serial number of the intermediate certificate"
   },
   IMPORT_CERT: {
     caId: "The ID of the CA to import the certificate for",
@@ -782,10 +789,16 @@ export const CERTIFICATE_AUTHORITIES = {
     commonName: "The common name (CN) for the certificate",
     ttl: "The time to live for the certificate such as 1m, 1h, 1d, 1y, ...",
     notBefore: "The date and time when the certificate becomes valid in YYYY-MM-DDTHH:mm:ss.sssZ format",
-    notAfter: "The date and time when the certificate expires in YYYY-MM-DDTHH:mm:ss.sssZ format"
+    notAfter: "The date and time when the certificate expires in YYYY-MM-DDTHH:mm:ss.sssZ format",
+    certificate: "The issued certificate",
+    issuingCaCertificate: "The certificate of the issuing CA",
+    certificateChain: "The certificate chain of the issued certificate",
+    privateKey: "The private key of the issued certificate",
+    serialNumber: "The serial number of the issued certificate"
   },
   GET_CRL: {
-    caId: "The ID of the CA to get the certificate revocation list (CRL) for"
+    caId: "The ID of the CA to get the certificate revocation list (CRL) for",
+    crl: "The certificate revocation list (CRL) of the CA"
   }
 };
 
@@ -796,14 +809,18 @@ export const CERTIFICATES = {
   REVOKE: {
     serialNumber:
       "The serial number of the certificate to revoke. The revoked certificate will be added to the certificate revocation list (CRL) of the CA.",
-    revocationReason:
-      "The reason for revoking the certificate. This can be one of UNSPECIFIED, KEY_COMPROMISE, CA_COMPROMISE, AFFILIATION_CHANGED, SUPERSEDED, CESSATION_OF_OPERATION, CERTIFICATE_HOLD, PRIVILEGE_WITHDRAWN, or A_A_COMPROMISE."
+    revocationReason: "The reason for revoking the certificate.",
+    revokedAt: "The date and time when the certificate was revoked",
+    serialNumberRes: "The serial number of the revoked certificate."
   },
   DELETE: {
     serialNumber: "The serial number of the certificate to delete"
   },
   GET_CERT: {
-    serialNumber: "The serial number of the certificate to get the certificate body and certificate chain for"
+    serialNumber: "The serial number of the certificate to get the certificate body and certificate chain for",
+    certificate: "The certificate body of the certificate",
+    certificateChain: "The certificate chain of the certificate",
+    serialNumberRes: "The serial number of the certificate"
   }
 };
 

backend/src/server/routes/v1/certificate-authority-router.ts

@@ -237,11 +237,11 @@ export const registerCaRouter = async (server: FastifyZodProvider) => {
     schema: {
       description: "Get CA CSR",
       params: z.object({
-        caId: z.string().trim()
+        caId: z.string().trim().describe(CERTIFICATE_AUTHORITIES.GET_CSR.caId)
       }),
       response: {
         200: z.object({
-          csr: z.string()
+          csr: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CSR.csr)
         })
       }
     },
@@ -286,9 +286,9 @@ export const registerCaRouter = async (server: FastifyZodProvider) => {
       }),
       response: {
         200: z.object({
-          certificate: z.string(),
-          certificateChain: z.string(),
-          serialNumber: z.string()
+          certificate: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.certificate),
+          certificateChain: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.certificateChain),
+          serialNumber: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CERT.serialNumber)
         })
       }
     },
@@ -341,10 +341,13 @@ export const registerCaRouter = async (server: FastifyZodProvider) => {
       }),
       response: {
         200: z.object({
-          certificate: z.string().trim(),
-          certificateChain: z.string().trim(),
-          issuingCaCertificate: z.string().trim(),
-          serialNumber: z.string().trim()
+          certificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.certificate),
+          certificateChain: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.certificateChain),
+          issuingCaCertificate: z
+            .string()
+            .trim()
+            .describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.issuingCaCertificate),
+          serialNumber: z.string().trim().describe(CERTIFICATE_AUTHORITIES.SIGN_INTERMEDIATE.serialNumber)
         })
       }
     },
@@ -468,11 +471,11 @@ export const registerCaRouter = async (server: FastifyZodProvider) => {
         ),
       response: {
         200: z.object({
-          certificate: z.string().trim(),
-          issuingCaCertificate: z.string().trim(),
-          certificateChain: z.string().trim(),
-          privateKey: z.string().trim(),
-          serialNumber: z.string().trim()
+          certificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.certificate),
+          issuingCaCertificate: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.issuingCaCertificate),
+          certificateChain: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.certificateChain),
+          privateKey: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.privateKey),
+          serialNumber: z.string().trim().describe(CERTIFICATE_AUTHORITIES.ISSUE_CERT.serialNumber)
         })
       }
     },
@@ -524,7 +527,7 @@ export const registerCaRouter = async (server: FastifyZodProvider) => {
       }),
       response: {
         200: z.object({
-          crl: z.string()
+          crl: z.string().describe(CERTIFICATE_AUTHORITIES.GET_CRL.crl)
         })
       }
     },

backend/src/server/routes/v1/certificate-router.ts

@@ -73,8 +73,8 @@ export const registerCertRouter = async (server: FastifyZodProvider) => {
       response: {
         200: z.object({
           message: z.string().trim(),
-          serialNumber: z.string().trim(),
-          revokedAt: z.date()
+          serialNumber: z.string().trim().describe(CERTIFICATES.REVOKE.serialNumberRes),
+          revokedAt: z.date().describe(CERTIFICATES.REVOKE.revokedAt)
         })
       }
     },
@@ -169,9 +169,9 @@ export const registerCertRouter = async (server: FastifyZodProvider) => {
       }),
       response: {
         200: z.object({
-          certificate: z.string().trim(),
-          certificateChain: z.string().trim(),
-          serialNumber: z.string().trim()
+          certificate: z.string().trim().describe(CERTIFICATES.GET_CERT.certificate),
+          certificateChain: z.string().trim().describe(CERTIFICATES.GET_CERT.certificateChain),
+          serialNumber: z.string().trim().describe(CERTIFICATES.GET_CERT.serialNumberRes)
         })
       }
     },

docs/api-reference/endpoints/certificates/cert-body.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get Certificate Body / Chain"
+openapi: "GET /api/v1/pki/certificates/{serialNumber}/certificate"
+---

docs/api-reference/endpoints/certificates/delete.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete"
+openapi: "DELETE /api/v1/pki/certificates/{serialNumber}"
+---

docs/api-reference/endpoints/certificates/read.mdx

@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/pki/certificates/{serialNumber}"
+---

docs/api-reference/endpoints/certificates/revoke.mdx

@@ -0,0 +1,4 @@
+---
+title: "Revoke"
+openapi: "POST /api/v1/pki/certificates/{serialNumber}/revoke"
+---

docs/mint.json

@@ -565,6 +565,30 @@
         {
           "group": "Audit Logs",
           "pages": ["api-reference/endpoints/audit-logs/export-audit-log"]
+        },
+        {
+          "group": "Certificate Authorities",
+          "pages": [
+            "api-reference/endpoints/certificate-authorities/create",
+            "api-reference/endpoints/certificate-authorities/read",
+            "api-reference/endpoints/certificate-authorities/update",
+            "api-reference/endpoints/certificate-authorities/delete",
+            "api-reference/endpoints/certificate-authorities/csr",
+            "api-reference/endpoints/certificate-authorities/cert",
+            "api-reference/endpoints/certificate-authorities/sign-intermediate",
+            "api-reference/endpoints/certificate-authorities/import-cert",
+            "api-reference/endpoints/certificate-authorities/issue-cert",
+            "api-reference/endpoints/certificate-authorities/crl"
+          ]
+        },
+        {
+          "group": "Certificates",
+          "pages": [
+            "api-reference/endpoints/certificates/read",
+            "api-reference/endpoints/certificates/revoke",
+            "api-reference/endpoints/certificates/delete",
+            "api-reference/endpoints/certificates/cert-body"
+          ]
         }
       ]
     },