Certificate Management

/**
 * A certificate and its private key for TLS authentication
 * @param keyPair The public/private key pair
 * @param certificate The X.509 certificate
 */
class HeldCertificate(
    val keyPair: KeyPair,
    val certificate: X509Certificate
)

/**
 * Returns the certificate encoded in PEM format
 * @return Certificate in PEM format with BEGIN/END markers
 */
fun certificatePem(): String

val certificate = HeldCertificate.Builder().build()
val pemString = certificate.certificatePem()
println(pemString)
// Output:
// -----BEGIN CERTIFICATE-----
// MIIBSjCB8aADAgECAgEBMAoGCCqGSM49BAMCMC8x...
// -----END CERTIFICATE-----

/**
 * Returns the RSA private key encoded in PKCS #8 PEM format
 * @return Private key in PKCS #8 PEM format
 */
fun privateKeyPkcs8Pem(): String

/**
 * Returns the RSA private key encoded in PKCS #1 PEM format  
 * @return Private key in PKCS #1 PEM format
 * @throws IllegalStateException if key is not RSA
 */
fun privateKeyPkcs1Pem(): String

val certificate = HeldCertificate.Builder().rsa2048().build()

// PKCS #8 format (universal)
val pkcs8Key = certificate.privateKeyPkcs8Pem()

// PKCS #1 format (RSA only)
val pkcs1Key = certificate.privateKeyPkcs1Pem()

/**
 * Decodes a multiline string containing both certificate and private key in PEM format
 * @param certificateAndPrivateKeyPem PEM string with certificate and private key
 * @return HeldCertificate instance with parsed certificate and key
 * @throws IllegalArgumentException if parsing fails or format is invalid
 */
companion object {
    fun decode(certificateAndPrivateKeyPem: String): HeldCertificate
}

val pemString = """
    -----BEGIN CERTIFICATE-----
    MIIBYTCCAQegAwIBAgIBKjAKBggqhkjOPQQDAjApMRQwEgYDVQQLEwtlbmdpbmVl
    cmluZzERMA0GA1UEAxMIY2FzaC5hcHAwHhcNNzAwMTAxMDAwMDA1WhcNNzAwMTAx
    ...
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    MEECAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQcEJzAlAgEBBCA7ODT0xhGSNn4ESj6J
    lu/GJQZoU9lDrCPeUcQ28tzOWw==
    -----END PRIVATE KEY-----
""".trimIndent()

val heldCertificate = HeldCertificate.decode(pemString)

class Builder {
    fun validityInterval(notBefore: Long, notAfter: Long): Builder
    fun duration(duration: Long, unit: TimeUnit): Builder
    fun addSubjectAlternativeName(altName: String): Builder
    fun commonName(cn: String): Builder
    fun organizationalUnit(ou: String): Builder
    fun serialNumber(serialNumber: BigInteger): Builder
    fun serialNumber(serialNumber: Long): Builder
    fun keyPair(keyPair: KeyPair): Builder
    fun keyPair(publicKey: PublicKey, privateKey: PrivateKey): Builder
    fun signedBy(signedBy: HeldCertificate?): Builder
    fun certificateAuthority(maxIntermediateCas: Int): Builder
    fun ecdsa256(): Builder
    fun rsa2048(): Builder
    fun build(): HeldCertificate
}

/**
 * Sets the certificate validity interval using timestamps
 * @param notBefore Start of validity in milliseconds since epoch (-1L for default)
 * @param notAfter End of validity in milliseconds since epoch (-1L for default)
 * @return Builder instance for chaining
 */
fun validityInterval(notBefore: Long, notAfter: Long): Builder

/**
 * Sets the certificate to be valid immediately for specified duration
 * @param duration Duration value
 * @param unit Time unit (DAYS, HOURS, etc.)
 * @return Builder instance for chaining
 */
fun duration(duration: Long, unit: TimeUnit): Builder

// Valid for 30 days starting now
val certificate = HeldCertificate.Builder()
    .duration(30, TimeUnit.DAYS)
    .build()

// Custom validity interval
val now = System.currentTimeMillis()
val certificate2 = HeldCertificate.Builder()
    .validityInterval(now, now + TimeUnit.DAYS.toMillis(365))
    .build()

/**
 * Adds a subject alternative name (SAN) to the certificate
 * @param altName Hostname, IP address, or hostname pattern (*.example.com)
 * @return Builder instance for chaining
 */
fun addSubjectAlternativeName(altName: String): Builder

/**
 * Set the certificate's common name (CN)
 * @param cn Common name string
 * @return Builder instance for chaining
 */
fun commonName(cn: String): Builder

/**
 * Sets the certificate's organizational unit (OU)
 * @param ou Organizational unit string
 * @return Builder instance for chaining
 */
fun organizationalUnit(ou: String): Builder

val certificate = HeldCertificate.Builder()
    .commonName("Test Server")
    .organizationalUnit("Engineering")
    .addSubjectAlternativeName("localhost")
    .addSubjectAlternativeName("127.0.0.1")
    .addSubjectAlternativeName("*.test.local")
    .build()

/**
 * Sets the certificate's serial number
 * @param serialNumber Certificate serial number as BigInteger
 * @return Builder instance for chaining
 */
fun serialNumber(serialNumber: BigInteger): Builder

/**
 * Sets the certificate's serial number
 * @param serialNumber Certificate serial number as long
 * @return Builder instance for chaining  
 */
fun serialNumber(serialNumber: Long): Builder

/**
 * Sets the public/private key pair for the certificate
 * @param keyPair Pre-existing key pair
 * @return Builder instance for chaining
 */
fun keyPair(keyPair: KeyPair): Builder

/**
 * Sets the public/private key pair from individual keys
 * @param publicKey Public key
 * @param privateKey Private key
 * @return Builder instance for chaining
 */
fun keyPair(publicKey: PublicKey, privateKey: PrivateKey): Builder

/**
 * Sets the certificate that will issue/sign this certificate
 * @param signedBy Signing certificate (null for self-signed)
 * @return Builder instance for chaining
 */
fun signedBy(signedBy: HeldCertificate?): Builder

/**
 * Make this certificate a signing certificate authority
 * @param maxIntermediateCas Maximum number of intermediate CAs allowed beneath this CA
 * @return Builder instance for chaining
 */
fun certificateAuthority(maxIntermediateCas: Int): Builder

// Create root CA
val rootCa = HeldCertificate.Builder()
    .certificateAuthority(1)
    .commonName("Test Root CA")
    .build()

// Create intermediate CA signed by root
val intermediateCa = HeldCertificate.Builder()
    .certificateAuthority(0)
    .commonName("Test Intermediate CA")
    .signedBy(rootCa)
    .build()

// Create server certificate signed by intermediate
val serverCert = HeldCertificate.Builder()
    .commonName("Test Server")
    .addSubjectAlternativeName("localhost")
    .signedBy(intermediateCa)
    .build()

/**
 * Configure certificate to generate a 256-bit ECDSA key (default)
 * Provides ~128 bits of security, faster than RSA
 * @return Builder instance for chaining
 */
fun ecdsa256(): Builder

/**
 * Configure certificate to generate a 2048-bit RSA key
 * Provides ~112 bits of security, compatible with older clients
 * @return Builder instance for chaining
 */
fun rsa2048(): Builder

// Default ECDSA certificate (recommended)
val ecdsaCert = HeldCertificate.Builder()
    .ecdsa256()
    .build()

// RSA certificate for legacy compatibility
val rsaCert = HeldCertificate.Builder()
    .rsa2048()
    .build()

/**
 * Builds the HeldCertificate with configured properties
 * @return Complete HeldCertificate instance
 * @throws IllegalArgumentException if configuration is invalid
 */
fun build(): HeldCertificate