smartproxy/readme.plan.md

Plan: On-Demand Certificate Retrieval in NetworkProxy

When a TLS connection arrives with an SNI for a domain that has no certificate yet, we want to automatically kick off certificate issuance (ACME HTTP-01 or DNS-01) so the domain is provisioned on the fly without prior manual configuration.

Goals

• Automatically initiate certificate issuance upon first TLS handshake for an unprovisioned domain.
• Use Port80Handler (HTTP-01) or custom certProvisionFunction (e.g., DNS-01) to retrieve the certificate.
• Continue the TLS handshake immediately using the default certificate, then swap to the new certificate on subsequent connections.
• For HTTP traffic on port 80, register the domain for ACME and return a 503 until the challenge is complete.

Plan

1. Detect missing certificate in SNI callback:

   • In ts/networkproxy/classes.np.networkproxy.ts (or within CertificateManager.handleSNI), after looking up certificateCache, if no cert is found:
     • Call port80Handler.addDomain({ domainName, sslRedirect: false, acmeMaintenance: true }) to trigger dynamic provisioning.
     • Emit a certificateRequested event for observability.
     • Immediately call cb(null, defaultSecureContext) so the handshake uses the default cert.

2. HTTP-01 fallback on port 80:

   • In ts/port80handler/classes.port80handler.ts``, in handleRequest(), when a request arrives for a new domain not in domainCertificates`:
     • Call addDomain({ domainName, sslRedirect: false, acmeMaintenance: true }).
     • Return HTTP 503 with a message like “Certificate issuance in progress.”

3. CertProvisioner & events:

   • Ensure CertProvisioner is subscribed to Port80Handler for newly added domains.
   • After certificate issuance completes, Port80Handler emits CERTIFICATE_ISSUED, CertificateManager caches and writes disk, and future SNI callbacks will serve the new cert.

4. Metrics and cleanup:

   • Track dynamic requests count via a certificateRequested event or metric.
   • Handle error paths: if ACME/DNS fails, emit CERTIFICATE_FAILED and continue serving default cert.

5. Tests:

   • Simulate a TLS ClientHello for an unconfigured domain: • Verify port80Handler.addDomain is called and certificateRequested event emitted. • Confirm handshake completes with default cert context.
   • Simulate HTTP-01 challenge flow for a new domain: • Verify on first HTTP request, addDomain is invoked and 503 returned. • After manually injecting a challenge in Http01MemoryHandler, verify 200 with key authorization.
   • Simulate successful ACME response and ensure SNI now returns the real cert.

6. Final validation:

   • Run pnpm test to ensure all existing tests pass.
   • Add new unit/integration tests for the dynamic provisioning flow.