add /csr endpoint for CSR signing

Allow clients to submit Certificate Signing Requests instead of
having the server generate private keys. Client keeps key local.

- sign_csr() in pki.py validates and signs CSRs
- POST /csr endpoint with PoW protection
- 10 new tests for CSR functionality
- API documentation updated

app/api/routes.py

@@ -863,6 +863,7 @@ class IndexView(MethodView):
             f"DELETE {prefixed_url('/<id>')}": "Delete paste (owner only)",
             f"GET {prefixed_url('/register/challenge')}": "Get registration challenge",
             f"POST {prefixed_url('/register')}": "Register for client certificate",
+            f"POST {prefixed_url('/csr')}": "Sign CSR (bring your own key)",
         }
 
         if pki_enabled:
@@ -1414,6 +1415,121 @@ class RegisterView(MethodView):
         return response
 
 
+class CSRView(MethodView):
+    """CSR signing endpoint for client-generated keys."""
+
+    def post(self) -> Response:
+        """Sign a Certificate Signing Request.
+
+        Accepts a PEM-encoded CSR and returns a signed certificate.
+        Client keeps their private key - only the CSR is submitted.
+
+        Requires PoW to prevent abuse.
+
+        Request body: PEM-encoded CSR (Content-Type: application/x-pem-file or text/plain)
+
+        Returns:
+            Signed certificate PEM with headers for fingerprint and expiry
+        """
+        from app.pki import (
+            CANotFoundError,
+            PKIError,
+            generate_ca,
+            get_ca_info,
+            sign_csr,
+        )
+
+        # Check PKI configuration
+        password = current_app.config.get("PKI_CA_PASSWORD", "")
+        if not password:
+            return error_response(
+                "CSR signing not available",
+                503,
+                hint="PKI_CA_PASSWORD not configured",
+            )
+
+        # Verify PoW (same difficulty as registration)
+        register_difficulty = current_app.config.get("REGISTER_POW_DIFFICULTY", 24)
+        if register_difficulty > 0:
+            token = request.headers.get("X-PoW-Token", "")
+            solution = request.headers.get("X-PoW-Solution", "")
+
+            if not token or not solution:
+                return error_response(
+                    "Proof-of-work required",
+                    400,
+                    hint="GET /register/challenge for a challenge",
+                    difficulty=register_difficulty,
+                )
+
+            valid, err = verify_pow(token, solution, min_difficulty=register_difficulty)
+            if not valid:
+                current_app.logger.warning("CSR PoW failed: %s from=%s", err, request.remote_addr)
+                return error_response(f"Proof-of-work failed: {err}", 400)
+
+        # Get CSR from request body
+        csr_pem = request.get_data(as_text=True)
+        if not csr_pem or "BEGIN CERTIFICATE REQUEST" not in csr_pem:
+            return error_response(
+                "CSR required",
+                400,
+                hint="Submit PEM-encoded CSR in request body",
+            )
+
+        # Auto-generate CA if needed
+        ca_info = get_ca_info(skip_enabled_check=True)
+        if ca_info is None:
+            ca_days = current_app.config.get("PKI_CA_DAYS", 3650)
+            try:
+                ca_info = generate_ca("FlaskPaste CA", password, days=ca_days)
+                current_app.logger.info(
+                    "CA auto-generated for CSR signing: fingerprint=%s",
+                    ca_info["fingerprint_sha1"][:12],
+                )
+            except PKIError as e:
+                current_app.logger.error("CA auto-generation failed: %s", e)
+                return error_response("CA generation failed", 500)
+
+        # Sign CSR
+        try:
+            cert_days = current_app.config.get("PKI_CERT_DAYS", 365)
+            cert_info = sign_csr(csr_pem, password, days=cert_days)
+        except CANotFoundError:
+            return error_response("CA not available", 500)
+        except PKIError as e:
+            current_app.logger.warning("CSR signing failed: %s from=%s", e, request.remote_addr)
+            return error_response(f"CSR signing failed: {e}", 400)
+
+        current_app.logger.info(
+            "CSR signed: cn=%s fingerprint=%s from=%s",
+            cert_info["common_name"],
+            cert_info["fingerprint_sha1"][:12],
+            request.remote_addr,
+        )
+        log_event(
+            AuditEvent.CERT_ISSUED,
+            AuditOutcome.SUCCESS,
+            client_id=cert_info["fingerprint_sha1"],
+            client_ip=request.remote_addr,
+            details={
+                "type": "csr",
+                "common_name": cert_info["common_name"],
+                "expires_at": cert_info["expires_at"],
+            },
+        )
+
+        # Return certificate as PEM
+        response = Response(cert_info["certificate_pem"], mimetype="application/x-pem-file")
+        response.headers["Content-Disposition"] = (
+            f'attachment; filename="{cert_info["common_name"]}.crt"'
+        )
+        response.headers["X-Fingerprint-SHA1"] = cert_info["fingerprint_sha1"]
+        response.headers["X-Certificate-Expires"] = str(cert_info["expires_at"])
+        response.headers["X-Certificate-Serial"] = cert_info["serial"]
+        response.headers["X-Is-Admin"] = "1" if cert_info.get("is_admin") else "0"
+        return response
+
+
 class ClientView(MethodView):
     """CLI client download endpoint."""
 
@@ -2276,6 +2392,7 @@ bp.add_url_rule(
     "/register/challenge", view_func=RegisterChallengeView.as_view("register_challenge")
 )
 bp.add_url_rule("/register", view_func=RegisterView.as_view("register"))
+bp.add_url_rule("/csr", view_func=CSRView.as_view("csr"))
 
 # Paste operations
 bp.add_url_rule("/pastes", view_func=PastesListView.as_view("pastes_list"))

app/pki.py

@@ -1111,6 +1111,157 @@ def issue_certificate(
     }
 
 
+def sign_csr(
+    csr_pem: str,
+    password: str,
+    days: int = 365,
+    issued_to: str | None = None,
+    is_admin: bool | None = None,
+) -> dict:
+    """Sign a Certificate Signing Request with the CA.
+
+    Unlike issue_certificate(), this function does not generate a private key.
+    The client keeps their private key and only submits the CSR.
+
+    Args:
+        csr_pem: PEM-encoded CSR string
+        password: CA password for signing
+        days: Validity period in days
+        issued_to: Optional fingerprint of issuing user
+        is_admin: Admin flag (None = auto-detect first user)
+
+    Returns:
+        Dict with signed certificate info (no private key)
+
+    Raises:
+        CANotFoundError: If no CA exists
+        PKIError: If CSR is invalid or signing fails
+    """
+    _require_crypto()
+    from app.database import get_db
+
+    db = get_db()
+
+    # Auto-detect: first registered user becomes admin
+    if is_admin is None:
+        count = db.execute(
+            "SELECT COUNT(*) FROM issued_certificates WHERE status = 'valid'"
+        ).fetchone()[0]
+        is_admin = count == 0
+
+    # Load and validate CSR
+    try:
+        csr = x509.load_pem_x509_csr(csr_pem.encode("utf-8"))
+    except Exception as e:
+        raise PKIError(f"Invalid CSR format: {e}") from None
+
+    # Verify CSR signature (proves client has the private key)
+    if not csr.is_signature_valid:
+        raise PKIError("CSR signature is invalid")
+
+    # Extract common name from CSR
+    try:
+        common_name = csr.subject.get_attributes_for_oid(NameOID.COMMON_NAME)[0].value
+    except (IndexError, AttributeError):
+        raise PKIError("CSR must contain a Common Name (CN)") from None
+
+    # Load CA
+    ca_row = db.execute(
+        """SELECT certificate_pem, private_key_encrypted, key_salt
+           FROM certificate_authority WHERE id = 'default'"""
+    ).fetchone()
+
+    if ca_row is None:
+        raise CANotFoundError("No CA configured")
+
+    # Decrypt CA private key
+    ca_key = decrypt_private_key(
+        ca_row["private_key_encrypted"],
+        ca_row["key_salt"],
+        password,
+    )
+    ca_cert = x509.load_pem_x509_certificate(ca_row["certificate_pem"].encode("utf-8"))
+
+    # Build certificate from CSR
+    now = datetime.now(UTC)
+    serial = _generate_unique_serial(db)
+
+    cert_builder = (
+        x509.CertificateBuilder()
+        .subject_name(csr.subject)
+        .issuer_name(ca_cert.subject)
+        .public_key(csr.public_key())
+        .serial_number(serial)
+        .not_valid_before(now)
+        .not_valid_after(now + timedelta(days=days))
+        .add_extension(
+            x509.BasicConstraints(ca=False, path_length=None),
+            critical=True,
+        )
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                key_encipherment=True,
+                content_commitment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=False,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=True,
+        )
+        .add_extension(
+            x509.ExtendedKeyUsage([ExtendedKeyUsageOID.CLIENT_AUTH]),
+            critical=False,
+        )
+    )
+
+    certificate = cert_builder.sign(ca_key, hashes.SHA256())
+
+    # Serialize
+    cert_pem = certificate.public_bytes(serialization.Encoding.PEM).decode("utf-8")
+
+    # Calculate fingerprint
+    fingerprint = calculate_fingerprint(certificate)
+    serial_hex = format(serial, "032x")
+    created_at = int(now.timestamp())
+    expires_at = int((now + timedelta(days=days)).timestamp())
+
+    # Save to database
+    db.execute(
+        """INSERT INTO issued_certificates
+           (serial, ca_id, common_name, fingerprint_sha1, certificate_pem,
+            created_at, expires_at, issued_to, status, revoked_at, is_admin)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+        (
+            serial_hex,
+            "default",
+            common_name,
+            fingerprint,
+            cert_pem,
+            created_at,
+            expires_at,
+            issued_to,
+            "valid",
+            None,
+            1 if is_admin else 0,
+        ),
+    )
+    db.commit()
+
+    return {
+        "serial": serial_hex,
+        "common_name": common_name,
+        "fingerprint_sha1": fingerprint,
+        "certificate_pem": cert_pem,
+        "created_at": created_at,
+        "expires_at": expires_at,
+        "is_admin": is_admin,
+    }
+
+
 def is_admin_certificate(fingerprint: str) -> bool:
     """Check if a certificate fingerprint belongs to an admin.