docs: add code signing design (S3.3)
GPG signs checksums.txt by default. macOS codesign + notarization. Windows signtool deferred. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
acd0f90424
commit
fd7c15c753
1 changed files with 236 additions and 0 deletions
236
docs/plans/2026-01-29-code-signing-design.md
Normal file
236
docs/plans/2026-01-29-code-signing-design.md
Normal file
|
|
@ -0,0 +1,236 @@
|
|||
# Code Signing Design (S3.3)
|
||||
|
||||
## Summary
|
||||
|
||||
Integrate standard code signing tools into the build pipeline. GPG signs checksums by default. macOS codesign + notarization for Apple binaries. Windows signtool deferred.
|
||||
|
||||
## Design Decisions
|
||||
|
||||
- **Sign during build**: Signing happens in `pkg/build/signing/` after compilation, before archiving
|
||||
- **Config location**: `.core/build.yaml` with environment variable fallbacks for secrets
|
||||
- **GPG scope**: Signs `checksums.txt` only (standard pattern like Go, Terraform)
|
||||
- **macOS flow**: Codesign always when identity configured, notarize optional with flag/config
|
||||
- **Windows**: Placeholder for later implementation
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
pkg/build/signing/
|
||||
├── signer.go # Signer interface + SignConfig
|
||||
├── gpg.go # GPG checksums signing
|
||||
├── codesign.go # macOS codesign + notarize
|
||||
└── signtool.go # Windows placeholder
|
||||
```
|
||||
|
||||
## Signer Interface
|
||||
|
||||
```go
|
||||
// pkg/build/signing/signer.go
|
||||
type Signer interface {
|
||||
Name() string
|
||||
Available() bool
|
||||
Sign(ctx context.Context, artifact string) error
|
||||
}
|
||||
|
||||
type SignConfig struct {
|
||||
Enabled bool `yaml:"enabled"`
|
||||
GPG GPGConfig `yaml:"gpg,omitempty"`
|
||||
MacOS MacOSConfig `yaml:"macos,omitempty"`
|
||||
Windows WindowsConfig `yaml:"windows,omitempty"`
|
||||
}
|
||||
|
||||
type GPGConfig struct {
|
||||
Key string `yaml:"key"` // Key ID or fingerprint, supports $ENV
|
||||
}
|
||||
|
||||
type MacOSConfig struct {
|
||||
Identity string `yaml:"identity"` // Developer ID Application: ...
|
||||
Notarize bool `yaml:"notarize"` // Submit to Apple
|
||||
AppleID string `yaml:"apple_id"` // Apple account email
|
||||
TeamID string `yaml:"team_id"` // Team ID
|
||||
AppPassword string `yaml:"app_password"` // App-specific password
|
||||
}
|
||||
|
||||
type WindowsConfig struct {
|
||||
Certificate string `yaml:"certificate"` // Path to .pfx
|
||||
Password string `yaml:"password"` // Certificate password
|
||||
}
|
||||
```
|
||||
|
||||
## Config Schema
|
||||
|
||||
In `.core/build.yaml`:
|
||||
|
||||
```yaml
|
||||
sign:
|
||||
enabled: true
|
||||
|
||||
gpg:
|
||||
key: $GPG_KEY_ID
|
||||
|
||||
macos:
|
||||
identity: "Developer ID Application: Your Name (TEAM_ID)"
|
||||
notarize: false
|
||||
apple_id: $APPLE_ID
|
||||
team_id: $APPLE_TEAM_ID
|
||||
app_password: $APPLE_APP_PASSWORD
|
||||
|
||||
# windows: (deferred)
|
||||
# certificate: $WINDOWS_CERT_PATH
|
||||
# password: $WINDOWS_CERT_PASSWORD
|
||||
```
|
||||
|
||||
## Build Pipeline Integration
|
||||
|
||||
```
|
||||
Build() in pkg/build/builders/go.go
|
||||
↓
|
||||
compile binaries
|
||||
↓
|
||||
Sign macOS binaries (codesign) ← NEW
|
||||
↓
|
||||
Notarize if enabled (wait) ← NEW
|
||||
↓
|
||||
Create archives (tar.gz, zip)
|
||||
↓
|
||||
Generate checksums.txt
|
||||
↓
|
||||
GPG sign checksums.txt ← NEW
|
||||
↓
|
||||
Return artifacts
|
||||
```
|
||||
|
||||
## GPG Signer
|
||||
|
||||
```go
|
||||
// pkg/build/signing/gpg.go
|
||||
type GPGSigner struct {
|
||||
KeyID string
|
||||
}
|
||||
|
||||
func (s *GPGSigner) Name() string { return "gpg" }
|
||||
|
||||
func (s *GPGSigner) Available() bool {
|
||||
_, err := exec.LookPath("gpg")
|
||||
return err == nil && s.KeyID != ""
|
||||
}
|
||||
|
||||
func (s *GPGSigner) Sign(ctx context.Context, file string) error {
|
||||
cmd := exec.CommandContext(ctx, "gpg",
|
||||
"--detach-sign",
|
||||
"--armor",
|
||||
"--local-user", s.KeyID,
|
||||
"--output", file+".asc",
|
||||
file,
|
||||
)
|
||||
return cmd.Run()
|
||||
}
|
||||
```
|
||||
|
||||
**Output:** `checksums.txt.asc` (ASCII armored detached signature)
|
||||
|
||||
**User verification:**
|
||||
```bash
|
||||
gpg --verify checksums.txt.asc checksums.txt
|
||||
sha256sum -c checksums.txt
|
||||
```
|
||||
|
||||
## macOS Codesign
|
||||
|
||||
```go
|
||||
// pkg/build/signing/codesign.go
|
||||
type MacOSSigner struct {
|
||||
Identity string
|
||||
Notarize bool
|
||||
AppleID string
|
||||
TeamID string
|
||||
AppPassword string
|
||||
}
|
||||
|
||||
func (s *MacOSSigner) Name() string { return "codesign" }
|
||||
|
||||
func (s *MacOSSigner) Available() bool {
|
||||
if runtime.GOOS != "darwin" {
|
||||
return false
|
||||
}
|
||||
_, err := exec.LookPath("codesign")
|
||||
return err == nil && s.Identity != ""
|
||||
}
|
||||
|
||||
func (s *MacOSSigner) Sign(ctx context.Context, binary string) error {
|
||||
cmd := exec.CommandContext(ctx, "codesign",
|
||||
"--sign", s.Identity,
|
||||
"--timestamp",
|
||||
"--options", "runtime",
|
||||
"--force",
|
||||
binary,
|
||||
)
|
||||
return cmd.Run()
|
||||
}
|
||||
|
||||
func (s *MacOSSigner) NotarizeAndStaple(ctx context.Context, binary string) error {
|
||||
// 1. Create ZIP for submission
|
||||
zipPath := binary + ".zip"
|
||||
exec.CommandContext(ctx, "zip", "-j", zipPath, binary).Run()
|
||||
defer os.Remove(zipPath)
|
||||
|
||||
// 2. Submit and wait
|
||||
cmd := exec.CommandContext(ctx, "xcrun", "notarytool", "submit",
|
||||
zipPath,
|
||||
"--apple-id", s.AppleID,
|
||||
"--team-id", s.TeamID,
|
||||
"--password", s.AppPassword,
|
||||
"--wait",
|
||||
)
|
||||
if err := cmd.Run(); err != nil {
|
||||
return fmt.Errorf("notarization failed: %w", err)
|
||||
}
|
||||
|
||||
// 3. Staple ticket
|
||||
return exec.CommandContext(ctx, "xcrun", "stapler", "staple", binary).Run()
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Flags
|
||||
|
||||
```bash
|
||||
core build # Sign with defaults (GPG + codesign if configured)
|
||||
core build --no-sign # Skip all signing
|
||||
core build --notarize # Enable macOS notarization (overrides config)
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `GPG_KEY_ID` | GPG key ID or fingerprint |
|
||||
| `CODESIGN_IDENTITY` | macOS Developer ID (fallback) |
|
||||
| `APPLE_ID` | Apple account email |
|
||||
| `APPLE_TEAM_ID` | Apple Developer Team ID |
|
||||
| `APPLE_APP_PASSWORD` | App-specific password for notarization |
|
||||
|
||||
## Deferred
|
||||
|
||||
- **Windows signtool**: Placeholder implementation returning nil
|
||||
- **Sigstore/keyless signing**: Future consideration
|
||||
- **Binary-level GPG signatures**: Only checksums.txt signed
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Create `pkg/build/signing/` package structure
|
||||
2. Implement Signer interface and SignConfig
|
||||
3. Implement GPGSigner
|
||||
4. Implement MacOSSigner with codesign
|
||||
5. Add notarization support to MacOSSigner
|
||||
6. Add SignConfig to build.Config
|
||||
7. Integrate signing into build pipeline
|
||||
8. Add CLI flags (--no-sign, --notarize)
|
||||
9. Add Windows placeholder
|
||||
10. Tests with mocked exec
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `gpg` CLI (system)
|
||||
- `codesign` CLI (macOS Xcode Command Line Tools)
|
||||
- `xcrun notarytool` (macOS Xcode Command Line Tools)
|
||||
- `xcrun stapler` (macOS Xcode Command Line Tools)
|
||||
Loading…
Add table
Reference in a new issue