# DashCA - Certificate Authority Distribution

A self-hosted landing page for distributing your root CA certificate with one-click installation across all major platforms.

## Quick Start

### Regenerate All Certificate Formats

```bash
cd scripts
bash generate-all.sh
```

This will:
1. Copy root.crt and intermediate.crt from Caddy PKI
2. Generate root.der (DER format for Windows)
3. Generate root.mobileconfig (Apple profile for iOS/macOS)
4. Extract certificate metadata to cert-info.json

### Deploy to Production

```bash
# Copy all files to production directory
cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/
```

Or deploy via the dashboard app selector (preferred method).

## File Structure

```
ca/
├── index.html                    # Landing page with OS detection
├── root.crt                      # Root CA certificate (PEM format)
├── root.der                      # Root CA certificate (DER format)
├── root.mobileconfig             # Apple configuration profile
├── intermediate.crt              # Intermediate CA certificate
├── cert-info.json                # Certificate metadata (auto-generated)
├── scripts/
│   ├── install.ps1               # Windows PowerShell installer
│   ├── install.sh                # Linux/macOS shell installer
│   ├── generate-cert-info.js     # Extract certificate metadata
│   ├── generate-mobileconfig.js  # Generate Apple profile
│   └── generate-all.sh           # Wrapper script to regenerate all
└── assets/
    └── (icons, logos, etc.)
```

## Certificate Information

**Source:** Caddy's built-in PKI at `C:/caddy/certs/pki/authorities/local/`

- **Name:** Sami Home Network Root CA
- **Algorithm:** ECDSA P-256 with SHA-256
- **Valid Until:** Dec 22, 2034
- **Fingerprint:** `08:98:A5:63:F5:A1:A2:58:5F:02:D7:A8:A2:54:87:E6:BC:33:96:21:29:0E`

## Installation Scripts

### Windows (install.ps1)

Features:
- Requires Administrator privileges
- Downloads certificate from ca.sami
- Verifies SHA-256 fingerprint
- Installs to LocalMachine\Root store
- Checks for existing installation

**One-liner:**
```powershell
irm https://ca.sami/install.ps1 | iex
```

### Linux/macOS (install.sh)

Features:
- Requires sudo/root
- Auto-detects OS (Debian, RedHat, Arch, macOS)
- Platform-specific installation commands
- Fingerprint verification with OpenSSL
- Checks for existing installation

**One-liner:**
```bash
curl -fsSL https://ca.sami/install.sh | sudo bash
```

### Apple Devices (root.mobileconfig)

Features:
- Works on both iOS and macOS
- XML configuration profile format
- Contains base64-encoded certificate
- Unique UUIDs per generation
- User must manually trust after installation (iOS)

**Installation:**
1. Download root.mobileconfig
2. iOS: Settings prompts automatically
3. macOS: System Settings → Profiles → Install
4. iOS: Enable trust in Certificate Trust Settings

## Landing Page Features

The landing page (`index.html`) includes:

- **OS Detection:** Automatically detects Windows, macOS, Linux, iOS, Android
- **Certificate Info Display:** Shows name, fingerprint, expiration, algorithm
- **QR Code:** For easy mobile access (powered by qrcodejs library)
- **Download Links:** All certificate formats and installation scripts
- **Platform Tabs:** Detailed instructions for each operating system
- **Copy-to-Clipboard:** For fingerprint and command-line scripts
- **DashCaddy Theme:** Dark mode with Sami Grotesk font

**API Integration:**
- Loads certificate info from `/api/v1/ca/info` endpoint
- Falls back to static info if API unavailable

## Development Workflow

1. **Edit Files:** Make changes in `e:/CaddyCerts/sites/ca/`
2. **Test Locally:** Open `index.html` in browser (file:// protocol works)
3. **Regenerate Certificates:** Run `scripts/generate-all.sh` if CA renewed
4. **Deploy:** Copy to production or use dashboard deployment
5. **Verify:** Visit https://ca.sami and test on target platforms

## Updating After CA Renewal

When Caddy regenerates its CA certificate (every ~10 years):

### 1. Regenerate Certificate Formats

```bash
cd e:/CaddyCerts/sites/ca/scripts
bash generate-all.sh
```

### 2. Update Fingerprints in Scripts

The new fingerprint will be in `cert-info.json`. Update these files:

**install.ps1** (line 17):
```powershell
$ExpectedFingerprint = "NEW:FIN:GER:PRINT:HERE"
```

**install.sh** (line 13):
```bash
EXPECTED_FP="NEW:FIN:GER:PRINT:HERE"
```

### 3. Deploy to Production

```bash
cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/
```

### 4. Notify Users

- Add banner to dashboard
- Send notification via configured channels
- Update documentation with new expiration date

## API Endpoints

DashCA integrates with DashCaddy API:

### GET /api/ca/info

Returns certificate metadata:

```json
{
  "success": true,
  "certificate": {
    "name": "Sami Home Network Root CA",
    "fingerprint": "08:98:A5:...",
    "validFrom": "Feb 12 07:44:51 2025 GMT",
    "validUntil": "Dec 22 07:44:51 2034 GMT",
    "daysUntilExpiration": 3235,
    "algorithm": "ECDSA P-256 with SHA-256",
    "serialNumber": "c1:dc:48:...",
    "downloadUrl": "https://ca.sami/root.crt"
  }
}
```

### GET /api/health/ca

Returns CA expiration health status:

```json
{
  "status": "healthy",
  "message": "CA certificate valid for 3235 days",
  "daysUntilExpiration": 3235,
  "expiresAt": "Dec 22 07:44:51 2034 GMT"
}
```

**Status values:**
- `healthy`: >90 days remaining
- `warning`: 30-90 days
- `critical`: <30 days or expired
- `error`: Certificate not found or error reading

## Troubleshooting

### Certificate Not Found Error

**Symptom:** Scripts fail with "certificate not found"
**Cause:** Caddy hasn't generated the local CA yet
**Solution:** Visit any *.sami domain to trigger CA generation

### Fingerprint Mismatch

**Symptom:** Install scripts reject certificate with fingerprint mismatch
**Cause:** CA was renewed but scripts not updated
**Solution:** Run `generate-all.sh` and update fingerprints in install scripts

### iOS Profile Won't Install

**Symptom:** .mobileconfig shows error when installing
**Cause:** Invalid XML or missing UUIDs
**Solution:** Regenerate with `node generate-mobileconfig.js`

### Android Shows "Not Trusted"

**Symptom:** Certificate installs but sites still show warnings
**Cause:** Android installs as "user" certificate; some apps don't trust user CAs
**Solution:** This is by design. System CA installation requires root access.

### Landing Page Shows "Loading..."

**Symptom:** Certificate info stuck on loading state
**Cause:** API endpoint not accessible
**Solution:** Check that dashcaddy-api server is running and `/api/v1/ca/info` responds

## Testing Checklist

Before deploying to production:

- [ ] All certificate formats generated successfully
- [ ] Landing page loads correctly in browser
- [ ] OS detection works (test multiple user agents)
- [ ] QR code renders and scans correctly
- [ ] Download links work for all file types
- [ ] API endpoint returns valid certificate info
- [ ] Copy-to-clipboard buttons work
- [ ] Platform instruction tabs function correctly
- [ ] Responsive design works on mobile viewport
- [ ] HTTPS access works after deployment

## Security Notes

- **Private Key:** NEVER serve the CA private key (`root.key`). Only public certificates are safe to distribute.
- **Fingerprint Verification:** Install scripts verify fingerprint to prevent MITM attacks
- **Access Control:** ca.sami should only be accessible on your Tailnet/internal network
- **HTTPS Enforcement:** The page itself uses HTTPS (via Caddy's internal CA) to protect the distribution
- **No Auto-Execution:** All installation methods require explicit user action

## Contributing

When adding features to DashCA:

1. Test on multiple platforms before committing
2. Update this README with new features
3. Add relevant sections to troubleshooting guide
4. Update CLAUDE.md if deployment process changes
5. Ensure backward compatibility with existing certificates

## Resources

- **Caddy PKI Documentation:** https://caddyserver.com/docs/caddyfile/directives/tls#pki
- **mobileconfig Format:** https://developer.apple.com/documentation/devicemanagement
- **OpenSSL Certificate Commands:** https://www.openssl.org/docs/man1.1.1/man1/x509.html
- **QR Code Library:** https://github.com/davidshimjs/qrcodejs

---

**Part of the DashCaddy project** - Unified management for Docker + Caddy + DNS
