letsdebug

README

Let's Debug Serverless

A serverless adaptation of the Let's Debug library, designed to run on Vercel serverless functions with public DNS resolution instead of libunbound.

Overview

This project provides a serverless-compatible version of the Let's Debug diagnostic tool for Let's Encrypt certificate issuance issues. The main adaptation involves replacing the libunbound dependency with public DNS resolution to ensure compatibility with serverless environments.

Key Differences from Original

• DNS Resolution: Uses public DNS servers instead of libunbound for DNS lookups
• Serverless-First: Designed specifically for Vercel serverless functions
• No Fluid Compute: Only supports Vercel's serverless compute model
• Simplified Dependencies: Removes system-level dependencies that aren't available in serverless environments

Limitations

• Public DNS Only: Uses public DNS servers instead of libunbound
• Vercel Only: Designed specifically for Vercel serverless functions
• No Fluid Compute: Does not support Vercel's fluid compute model
• Network Dependencies: Requires internet access for DNS resolution

Web Application

A Next.js web application is included in the web/ directory that provides a user-friendly interface for the Let's Debug serverless library.

Features

• Mobile-first responsive design with Tailwind CSS and shadcn/ui components
• Query string support for shareable URLs with domain and validation method
• Real-time domain debugging using the Go letsdebug-serverless package
• Multiple validation methods (HTTP-01, DNS-01, TLS-ALPN-01)
• Categorized results by severity (Fatal, Error, Warning, Debug)
• Vercel deployment ready with Go runtime support

Quick Start

1. Navigate to the web directory:

   cd web
   

2. Install dependencies:

   pnpm install
   

3. Run the development server:

   pnpm dev
   

4. Open http://localhost:3000 in your browser

Deployment

The web app is configured for Vercel deployment. See web/DEPLOYMENT.md for detailed deployment instructions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Development Guidelines

• Follow Go best practices and conventions
• Add tests for new functionality
• Update documentation for API changes
• Ensure serverless compatibility
• Test with Vercel functions
• Use mobile-first responsive design for web components
• Follow accessibility best practices

License

MIT License - see LICENSE file for details.

Acknowledgments

• Based on the original Let's Debug project
• Adapted for serverless environments with public DNS resolution
• Designed for Vercel serverless functions

Documentation

Overview

Package letsdebug provides an library, web API and CLI to provide diagnostic information for why a particular (FQDN, ACME Validation Method) pair *may* fail when attempting to issue an SSL Certificate from Let's Encrypt (https://letsencrypt.org).

The usage cannot be generalized to other ACME providers, as the policies checked by this package are specific to Let's Encrypt, rather than being mandated by the ACME protocol.

This package relies on libunbound.

Index

• func ConfigureAcmeClient() acme.OptionFunc
• type Options
• type Problem
  • func Check(domain string, method ValidationMethod) (probs []Problem, retErr error)
  • func CheckWithOptions(domain string, method ValidationMethod, opts Options) (probs []Problem, retErr error)
  • func (p Problem) DetailLines() []string
  • func (p Problem) IsZero() bool
  • func (p Problem) String() string
• type SeverityLevel
• type ValidationMethod

Functions

func ConfigureAcmeClient

func ConfigureAcmeClient() acme.OptionFunc

Types

type Options

type Options struct {
	// HTTPRequestPath alters the /.well-known/acme-challenge/letsdebug-test to
	// /acme-challenge/acme-challenge/{{ HTTPRequestPath }}
	HTTPRequestPath string
	// HTTPExpectResponse causes the HTTP checker to require the remote server to
	// respond with specific content. If the content does not match, then the test
	// will fail with severity Error.
	HTTPExpectResponse string
	// SkipDomainValidation skips the validDomainChecker when the domain has already
	// been validated by the caller (e.g., domain_assist package)
	SkipDomainValidation bool
}

Options provide additional configuration to the various checkers

type Problem

type Problem struct {
	Name        string        `json:"name"`
	Explanation string        `json:"explanation"`
	Detail      string        `json:"detail"`
	Severity    SeverityLevel `json:"severity"`
}

Problem represents an issue found by one of the checkers in this package. Explanation is a human-readable explanation of the issue. Detail is usually the underlying machine error.

func Check

func Check(domain string, method ValidationMethod) (probs []Problem, retErr error)

Check calls CheckWithOptions with default options

func CheckWithOptions

func CheckWithOptions(domain string, method ValidationMethod, opts Options) (probs []Problem, retErr error)

CheckWithOptions will run each checker against the domain and validation method provided. It is expected that this method may take a long time to execute, and may not be cancelled.

func (Problem) DetailLines

func (p Problem) DetailLines() []string

func (Problem) IsZero

func (p Problem) IsZero() bool

func (Problem) String

func (p Problem) String() string

type SeverityLevel

type SeverityLevel string

SeverityLevel represents the priority of a reported problem

const (
	SeverityFatal   SeverityLevel = "Fatal" // Represents a fatal error which will stop any further checks
	SeverityError   SeverityLevel = "Error"
	SeverityWarning SeverityLevel = "Warning"
	SeverityDebug   SeverityLevel = "Debug" // Not to be shown by default
)

type ValidationMethod

type ValidationMethod string

ValidationMethod represents an ACME validation method

const (
	HTTP01    ValidationMethod = "http-01"     // HTTP01 represents the ACME http-01 validation method.
	DNS01     ValidationMethod = "dns-01"      // DNS01 represents the ACME dns-01 validation method.
	TLSALPN01 ValidationMethod = "tls-alpn-01" // TLSALPN01 represents the ACME tls-alpn-01 validation method.
)