/sign-binary Command

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Purpose

Sign binary executables for secure distribution. Supports Apple codesign with notarization, Windows Authenticode, Linux GPG signatures, and macOS TCC/FDA setup for LaunchAgent services (ADR-190).

Usage

# Sign macOS binary with notarization
/sign-binary dist/myapp-darwin-x64 --notarize

# Sign Windows binary
/sign-binary dist/myapp-win32-x64.exe --platform win32

# Sign Linux binary with GPG
/sign-binary dist/myapp-linux-x64 --platform linux

# Sign all binaries in directory
/sign-binary dist/

# Sign and verify
/sign-binary dist/myapp-darwin-arm64 --verify

# Use specific certificate
/sign-binary dist/myapp-win32-x64.exe --cert "ABC123DEF456"

# ── macOS TCC/FDA Setup (ADR-190) ──

# Interactive setup: certificate + .app bundle + code signing + FDA guide
/sign-binary --setup-tcc

# Check current TCC/signing status
/sign-binary --setup-tcc --check

# Quick re-sign after binary update
/sign-binary --setup-tcc --resign

# Non-interactive mode (for automation)
/sign-binary --setup-tcc --non-interactive

Action Policy

Platform Detection

When platform not specified:

1. Check file extension (.exe → win32)
2. Parse filename pattern (-darwin- → darwin)
3. Run file command for binary type
4. Default to current OS if undetermined

Signing Workflow

macOS:

1. Locate Developer ID certificate
2. Sign with hardened runtime
3. Create ZIP for notarization (if --notarize)
4. Submit to Apple notarization service
5. Wait for approval
6. Staple ticket to binary (unless --skip-staple)
7. Verify signature

Windows:

1. Locate certificate by thumbprint
2. Sign with SHA256 and timestamp
3. Verify signature

Linux:

1. Locate GPG private key
2. Create detached ASCII signature (.asc)
3. Optionally sign checksum file
4. Verify signature

macOS TCC/FDA Setup (ADR-190)

When --setup-tcc is specified, runs the interactive TCC compliance setup for LaunchAgent binaries (like codi-watcher):

/sign-binary --setup-tcc

What it does (7-step interactive walkthrough):

1. Check prerequisites (binary exists, Xcode CLI tools)
2. Create or find self-signed certificate ("CODITECT Local Signing")
3. Create .app bundle wrapper (CoDiWatcher.app)
4. Code-sign the .app bundle
5. Install/update LaunchAgent plist
6. Guide user through System Settings → Full Disk Access grant
7. Reload LaunchAgent service

Why this exists: macOS TCC (Transparency, Consent, and Control) requires per-binary permission grants. LaunchAgent processes don't inherit terminal TCC grants, and the System Settings FDA UI only accepts .app bundles. This setup creates the necessary .app wrapper and self-signed certificate so the watcher binary can access LLM session files under ~/Library/.

Modes:

Flag	Action
--setup-tcc	Full interactive 7-step setup
--setup-tcc --check	Status report only (no changes)
--setup-tcc --resign	Quick re-sign after binary update
--setup-tcc --non-interactive	Automated setup (no prompts)

Implementation: Delegates to scripts/setup-macos-code-signing.py

python3 scripts/setup-macos-code-signing.py           # Full setup
python3 scripts/setup-macos-code-signing.py --check    # Status check
python3 scripts/setup-macos-code-signing.py --resign   # Re-sign only

Reference: ADR-190

Agent Delegation

This command delegates to code-signing-specialist for:

• Platform-specific signing implementation
• Certificate management guidance
• Troubleshooting signing failures
• Security best practices

Output

Success Output

╭─────────────────────────────────────────────╮
│           Binary Signed Successfully        │
├─────────────────────────────────────────────┤
│ Binary:   dist/myapp-darwin-x64             │
│ Platform: darwin                            │
│ Signer:   Developer ID Application: ...     │
│ Notarized: Yes                              │
│ Stapled:  Yes                               │
├─────────────────────────────────────────────┤
│ Verification:                               │
│   codesign: VALID                           │
│   spctl:    ACCEPTED                        │
╰─────────────────────────────────────────────╯

Verification Output (--verify)

╭─────────────────────────────────────────────╮
│           Signature Verification            │
├─────────────────────────────────────────────┤
│ Binary:    dist/myapp-win32-x64.exe         │
│ Signed:    Yes                              │
│ Signer:    Your Company, Inc.               │
│ Timestamp: 2025-01-15T10:30:00Z             │
│ Valid:     Yes                              │
│ Chain:     DigiCert SHA2 Assured ID         │
╰─────────────────────────────────────────────╯

Environment Variables

Variable	Platform	Description
APPLE_DEVELOPER_ID	macOS	Developer ID certificate name
APPLE_TEAM_ID	macOS	Apple Developer Team ID
APPLE_ID	macOS	Apple ID for notarization
APPLE_PASSWORD	macOS	App-specific password
WINDOWS_CERT_THUMBPRINT	Windows	Certificate SHA1 thumbprint
GPG_KEY_ID	Linux	GPG key identifier
GPG_PASSPHRASE	Linux	GPG key passphrase

Error Handling

Common Errors

Certificate not found:

ERROR: No signing certificate found
FIX: Import certificate to keychain/store
     Verify APPLE_DEVELOPER_ID or WINDOWS_CERT_THUMBPRINT

Notarization failed:

ERROR: Notarization rejected
FIX: Check binary for unsigned frameworks
     Ensure hardened runtime is enabled
     Review notarization log for details

GPG key not found:

ERROR: GPG key ABC123 not found
FIX: Import GPG private key
     gpg --import private-key.asc

FDA not granted (TCC setup):

ERROR: TCC errors detected — FDA not granted
FIX: System Settings → Privacy & Security → Full Disk Access
     Add CoDiWatcher.app from ~/Library/Application Support/CODITECT/core/bin/
     Then: /sign-binary --setup-tcc --check

Certificate expired (TCC setup):

ERROR: Certificate "CODITECT Local Signing" expired
FIX: /sign-binary --setup-tcc   (will recreate certificate)

Examples

macOS Release Signing

User: /sign-binary dist/coditect-darwin-x64 --notarize --verify

macOS TCC Setup for LaunchAgent

User: /sign-binary --setup-tcc

Step 1/7: Checking prerequisites...
  ✓ Binary found: codi-watcher (3.4MB)
  ✓ Xcode CLI tools installed

Step 2/7: Certificate...
  ✓ Found existing: "CODITECT Local Signing" (expires 2027-02-13)

Step 3/7: .app Bundle...
  ✓ CoDiWatcher.app exists at ~/Library/Application Support/CODITECT/core/bin/

Step 4/7: Code signing...
  ✓ Signed with "CODITECT Local Signing"
  ✓ codesign verify: valid on disk

Step 5/7: LaunchAgent...
  ✓ Plist references .app bundle binary

Step 6/7: Full Disk Access...
  ⚠ Open System Settings → Privacy & Security → Full Disk Access
  ⚠ Click + and add: CoDiWatcher.app
  Press Enter when done...
  ✓ FDA configured

Step 7/7: Reload...
  ✓ LaunchAgent reloaded

✅ COMMAND COMPLETE: /sign-binary --setup-tcc
TCC setup complete. codi-watcher has Full Disk Access.

---

Action Policy

<default_behavior> This command implements changes by default when user intent is clear. Proceeds with:

• Binary signing operations
• Notarization submission
• Verification checks

Provides concise progress updates during execution. </default_behavior>

After execution, verify: - Binary signed with valid certificate - Notarization approved (if requested) - Verification passes - All platforms processed

Success Output

When binary signing completes:

✅ COMMAND COMPLETE: /sign-binary
Binary: <path>
Platform: darwin|win32|linux
Signer: <certificate-identity>
Notarized: Yes|No
Verification: VALID

Completion Checklist

Before marking complete:

• Certificate located
• Binary signed
• Notarization complete (if requested)
• Ticket stapled (macOS)
• Verification passed

Failure Indicators

This command has FAILED if:

• ❌ Certificate not found
• ❌ Notarization rejected
• ❌ Verification failed
• ❌ Platform detection failed

When NOT to Use

Do NOT use when:

• Development/testing binaries
• No signing certificate available
• Binary already signed

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip notarization	macOS Gatekeeper blocks	Always notarize for distribution
Skip verification	Corrupted signature	Verify after every sign
Hardcode credentials	Security risk	Use environment variables

Principles

This command embodies:

• #3 Complete Execution - Sign, notarize, verify
• #9 Based on Facts - Verification confirms success

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Related

• ADR: ADR-190 macOS Code Signing & TCC Compliance
• Script: setup-macos-code-signing.py — Interactive TCC setup
• Agent: code-signing-specialist
• LaunchAgent: ai.coditect.context-watcher.plist

---

Version: 2.0.0 Updated: 2026-02-13 Changelog:

• v2.0.0 - ADR-190: Added --setup-tcc mode for macOS TCC/FDA setup (certificate, .app bundle, code signing, FDA guide)
• v1.0.0 - Initial release with macOS/Windows/Linux binary signing