Skip to content

Commit 94b5137

Browse files
JabenJaben
authored
Merge pull request #1 from ChangemakerStudios/claude/init-repository-011cuud34t4kzdjsmf4vvcnt-011CUudXXwXEj1MfuzfeL6hC
Claude/init repository 011cuud34t4kzdjsmf4vvcnt 011 c uud x xw x ej1 mfuzfe l6h c
2 parents e3df990 + b3009db commit 94b5137

File tree

3 files changed

+287
-1
lines changed

3 files changed

+287
-1
lines changed

‎.gitattributes‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Auto detect text files and perform LF normalization
2+
* text=auto
3+
4+
# Custom for Visual Studio
5+
*.cs diff=csharp
6+
*.sln text eol=crlf merge=union
7+
*.csproj text eol=crlf merge=union
8+
*.vbproj text eol=crlf merge=union
9+
*.vcxproj text eol=crlf merge=union
10+
*.vcproj text eol=crlf merge=union
11+
*.dbproj text eol=crlf merge=union
12+
*.fsproj text eol=crlf merge=union
13+
*.lsproj text eol=crlf merge=union
14+
*.wixproj text eol=crlf merge=union
15+
*.modelproj text eol=crlf merge=union
16+
*.sqlproj text eol=crlf merge=union
17+
*.wwaproj text eol=crlf merge=union
18+
19+
# Bash scripts should use LF
20+
*.sh text eol=lf
21+
22+
# PowerShell scripts should use LF (for cross-platform compatibility and GitHub Actions)
23+
*.ps1 text eol=lf
24+
25+
# Documentation
26+
*.md text diff=markdown
27+
*.txt text
28+
*.rst text
29+
30+
# Graphics
31+
*.png binary
32+
*.jpg binary
33+
*.jpeg binary
34+
*.gif binary
35+
*.ico binary
36+
*.svg text
37+
38+
# Archives
39+
*.gz binary
40+
*.tar binary
41+
*.zip binary
42+
43+
# Fonts
44+
*.ttf binary
45+
*.eot binary
46+
*.woff binary
47+
*.woff2 binary

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ jobs:
5252
- uses: codecov/codecov-action@v4
5353
with:
5454
name: unittests-${{ matrix.os }}
55-
fail_ci_if_error: true
55+
fail_ci_if_error: false
5656
token: ${{ secrets.CODECOV_TOKEN }}
5757
release:
5858
if: ${{ github.event.inputs.release }}

‎Claude.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# LettuceEncrypt - Claude AI Context
2+
3+
## Project Overview
4+
5+
LettuceEncrypt is an ASP.NET Core library that provides automatic HTTPS certificate generation and management using Let's Encrypt and the ACME protocol. It integrates with Kestrel to automatically configure SSL/TLS certificates for web applications.
6+
7+
**Project Status**: Maintenance mode - security patches and critical fixes only
8+
9+
**Original Author**: [@natemcmaster](https://github.com/natemcmaster)
10+
11+
**Repository**: https://github.com/natemcmaster/LettuceEncrypt
12+
13+
## Architecture
14+
15+
### Solution Structure
16+
17+
```
18+
LettuceEncrypt/
19+
├── src/
20+
│ ├── LettuceEncrypt/ # Main library
21+
│ ├── LettuceEncrypt.Azure/ # Azure Key Vault integration
22+
│ └── Kestrel.Certificates/ # Kestrel certificate handling
23+
├── test/
24+
│ ├── LettuceEncrypt.UnitTests/ # Core unit tests
25+
│ └── LettuceEncrypt.Azure.UnitTests/ # Azure integration tests
26+
├── samples/
27+
│ ├── Web/ # Basic web sample
28+
│ └── KeyVault/ # Azure Key Vault sample
29+
├── .github/ # GitHub Actions workflows and templates
30+
└── docs/ # Documentation
31+
```
32+
33+
### Key Components
34+
35+
1. **LettuceEncrypt** - Core library providing:
36+
- ACME protocol client integration
37+
- Certificate generation and renewal
38+
- Kestrel integration
39+
- HTTP-01, TLS-ALPN-01, and DNS-01 challenge support
40+
- Certificate persistence (file system, custom stores)
41+
42+
2. **LettuceEncrypt.Azure** - Azure integration providing:
43+
- Azure Key Vault certificate storage
44+
- Azure Key Vault account key storage
45+
46+
3. **Kestrel.Certificates** - Low-level certificate handling for Kestrel
47+
48+
## Technology Stack
49+
50+
- **.NET Version**: .NET 8 (as of latest update)
51+
- **Language Version**: C# 12.0
52+
- **Features**: Implicit usings enabled
53+
- **Target Framework**: Multi-targeting support
54+
55+
## Code Conventions
56+
57+
### Naming Conventions (enforced via .editorconfig)
58+
59+
- **Private fields**: `_camelCase` (prefixed with underscore) - ERROR severity
60+
- **Private static fields**: `s_camelCase` (prefixed with s_) - SUGGESTION severity
61+
- **Constants**: `PascalCase` - ERROR severity
62+
63+
### Code Style
64+
65+
- **Indentation**: 4 spaces for C# files, 2 spaces for XML/JSON
66+
- **Braces**: Always required (`csharp_prefer_braces = true`)
67+
- **Var usage**: Preferred for built-in types and when type is apparent
68+
- **Using directives**: Outside namespace, system directives first
69+
- **New line before**: catch, else, finally, open brace
70+
- **Namespace declarations**: File-scoped (suggestion)
71+
- **Expression bodies**: Preferred for indexers and accessors
72+
73+
### File Header
74+
75+
All source files must include:
76+
```csharp
77+
// Copyright (c) Nate McMaster.
78+
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
79+
```
80+
81+
### Build Configuration
82+
83+
- **TreatWarningsAsErrors**: true
84+
- **Code style enforcement**: Enabled in build
85+
- **Strong name signing**: Enabled (using src/StrongName.snk)
86+
- **Symbol packages**: Generated as .snupkg
87+
88+
## Version Information
89+
90+
- **Current Version**: 1.3.4-beta.5 (from Directory.Build.props)
91+
- **Versioning**: Semantic versioning with optional pre-release suffix
92+
- **Build number**: Appended to version suffix from BUILD_NUMBER environment variable
93+
94+
## Development Workflow
95+
96+
### Building the Project
97+
98+
```bash
99+
# Using the provided build script
100+
./build.ps1
101+
102+
# Or using dotnet CLI
103+
dotnet build LettuceEncrypt.sln
104+
```
105+
106+
### Running Tests
107+
108+
```bash
109+
dotnet test LettuceEncrypt.sln
110+
```
111+
112+
### Creating Packages
113+
114+
```bash
115+
dotnet pack LettuceEncrypt.sln
116+
```
117+
118+
### Build Output
119+
120+
- Build artifacts: `.build/{ProjectName}/bin/`
121+
- Intermediate output: `.build/{ProjectName}/obj/`
122+
123+
## Git Attributes
124+
125+
The repository uses comprehensive `.gitattributes` for:
126+
- Auto-detection of text files with LF normalization
127+
- CRLF line endings for Visual Studio project files (.sln, .csproj, etc.)
128+
- LF line endings for bash scripts
129+
- CRLF line endings for PowerShell scripts
130+
- Binary handling for images, archives, fonts
131+
- C# diff strategy for .cs files
132+
- Markdown diff strategy for .md files
133+
134+
## Key Dependencies & Integrations
135+
136+
### ACME Protocol
137+
- Let's Encrypt integration
138+
- Certificate authority (CA) communication
139+
- Challenge validation (HTTP-01, TLS-ALPN-01, DNS-01)
140+
141+
### Kestrel Integration
142+
- Dynamic HTTPS configuration
143+
- Certificate selector integration
144+
- Startup integration points
145+
146+
### Storage Options
147+
- X.509 certificate store (default)
148+
- File system persistence
149+
- Azure Key Vault
150+
- Custom implementations via ICertificateRepository/ICertificateSource
151+
152+
## Configuration
153+
154+
Primary configuration via appsettings.json:
155+
```json
156+
{
157+
"LettuceEncrypt": {
158+
"AcceptTermsOfService": true,
159+
"DomainNames": ["example.com"],
160+
"EmailAddress": "[email protected]",
161+
"AllowedChallengeTypes": "Http01, TlsAlpn01, Dns01"
162+
}
163+
}
164+
```
165+
166+
## Extension Points
167+
168+
### Customization Interfaces
169+
170+
1. **ICertificateRepository** - Custom certificate storage
171+
2. **ICertificateSource** - Custom certificate loading
172+
3. **IAccountStore** - Custom ACME account key storage
173+
4. **IDnsChallengeProvider** - DNS-01 challenge handling
174+
175+
## Common Patterns
176+
177+
### Service Registration
178+
```csharp
179+
services.AddLettuceEncrypt()
180+
.PersistDataToDirectory(new DirectoryInfo("path"), "password");
181+
```
182+
183+
### Kestrel Configuration
184+
```csharp
185+
webBuilder.UseKestrel(k =>
186+
{
187+
k.ConfigureHttpsDefaults(h => h.UseLettuceEncrypt(k.ApplicationServices));
188+
});
189+
```
190+
191+
## Testing Considerations
192+
193+
- Integration tests available in test/ directory
194+
- Developer docs for local testing: test/Integration/
195+
- Non-production testing recommended before deployment
196+
197+
## CI/CD
198+
199+
### GitHub Actions Workflows
200+
201+
1. **ci.yml** - Continuous integration
202+
- Build verification
203+
- Test execution
204+
- Code coverage reporting (Codecov)
205+
206+
2. **stale.yml** - Stale issue/PR management
207+
208+
## Support Scenarios
209+
210+
### Supported ✅
211+
- Kestrel as edge server
212+
- Kestrel behind TCP load balancer (SSL pass-through)
213+
214+
### Not Supported ❌
215+
- IIS hosting
216+
- Azure App Services (use built-in cert management)
217+
- Reverse proxy scenarios (HTTPS terminated before Kestrel)
218+
219+
## Security Considerations
220+
221+
- Security policy: https://github.com/natemcmaster/LettuceEncrypt/security/policy
222+
- Report security issues through GitHub security advisories
223+
- Private keys stored securely using configured storage mechanism
224+
- ACME account keys persisted for certificate renewal
225+
226+
## License
227+
228+
Apache License 2.0 - See LICENSE.txt
229+
230+
## Contributing
231+
232+
See CONTRIBUTING.md for contribution guidelines.
233+
234+
## Notable Notes
235+
236+
- Project renamed from "McMaster.AspNetCore.LetsEncrypt" for trademark reasons
237+
- Not an official Let's Encrypt® or ISRG™ offering
238+
- Requires Kestrel as the web server (not IIS or HTTP.sys)
239+
- Only works when Kestrel is the edge server or behind SSL pass-through

0 commit comments

Comments
 (0)