secret/PROVISIONING_GUIDE.md

# Provisioning Profile Setup for macOS Biometric Authentication

## Prerequisites

1. Apple Developer Account (paid membership required)
2. macOS development machine
3. Xcode installed (for code signing tools)

## Step 1: Log into Apple Developer Portal

1. Go to [developer.apple.com](https://developer.apple.com)
2. Sign in with your Apple Developer account
3. Navigate to "Certificates, Identifiers & Profiles"

## Step 2: Create App ID

1. Click "Identifiers" in the sidebar
2. Click the "+" button to create a new identifier
3. Select "App IDs" and click "Continue"
4. Choose "App" (not App Clip) and click "Continue"
5. Fill in the details:
   - **Description**: `Secret Manager macOS App`
   - **Bundle ID**: Select "Explicit" and enter `berlin.sneak.pkg.secret`
6. In the "Capabilities" section, enable:
   - **Keychain Sharing** (this is essential for keychain access)
   - Leave other capabilities unchecked unless specifically needed
7. Click "Continue" and then "Register"

## Step 3: Create/Verify Development Certificate

1. Click "Certificates" in the sidebar
2. Click the "+" button if you need a new certificate
3. Under "Development", select "Mac Development"
4. Follow the instructions to generate a Certificate Signing Request (CSR):
   - Open Keychain Access on your Mac
   - Go to Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority
   - Enter your email address and name
   - Select "Saved to disk" and "Let me specify key pair information"
   - Click "Continue" and save the CSR file
5. Upload the CSR file and download the certificate
6. Double-click the downloaded certificate to install it in Keychain Access

## Step 4: Register Development Device

1. Click "Devices" in the sidebar
2. Click the "+" button to register a new device
3. Select "macOS" as the platform
4. Get your Mac's hardware UUID:
   ```bash
   system_profiler SPHardwareDataType | grep "Hardware UUID"
   ```
5. Enter:
   - **Device Name**: Your Mac's name (e.g., "John's MacBook Pro")
   - **Device ID (UUID)**: The hardware UUID from step 4
6. Click "Continue" and then "Register"

## Step 5: Create Development Provisioning Profile

1. Click "Profiles" in the sidebar
2. Click the "+" button to create a new profile
3. Under "Development", select "Mac App Development"
4. Click "Continue"
5. Select your App ID: `berlin.sneak.pkg.secret`
6. Click "Continue"
7. Select your development certificate
8. Click "Continue"
9. Select your registered Mac device
10. Click "Continue"
11. Enter a profile name: `Secret Manager macOS Development`
12. Click "Generate"
13. Download the provisioning profile

## Step 6: Install Provisioning Profile

1. Double-click the downloaded `.provisionprofile` file to install it
2. Or manually copy it to: `~/Library/MobileDevice/Provisioning Profiles/`

## Step 7: Code Signing Setup

### Option A: Manual Code Signing

Add these flags when building your Go binary:

```bash
# Build the binary
go build -o secret cmd/secret/main.go

# Sign the binary
codesign --sign "Apple Development: YOUR_NAME (TEAM_ID)" \
         --entitlements entitlements.plist \
         --options runtime \
         --force \
         ./secret
```

### Option B: Using Makefile

Update your Makefile to include code signing:

```makefile
DEVELOPER_ID = "Apple Development: YOUR_NAME (TEAM_ID)"
ENTITLEMENTS = entitlements.plist

secret: 
	go build -o secret cmd/secret/main.go
	codesign --sign $(DEVELOPER_ID) \
	         --entitlements $(ENTITLEMENTS) \
	         --options runtime \
	         --force \
	         ./secret

.PHONY: secret
```

## Step 8: Verify Code Signing

Check that your binary is properly signed:

```bash
# Check code signature
codesign -dv --verbose=4 ./secret

# Check entitlements
codesign -d --entitlements :- ./secret
```

## Step 9: Test Biometric Authentication

Run your app and verify that:
1. Touch ID/Face ID prompts appear when accessing keychain
2. No entitlement errors occur
3. Keychain operations work correctly

## Troubleshooting

### Common Issues:

1. **errSecMissingEntitlement (-34018)**
   - Ensure your provisioning profile includes keychain access
   - Verify code signing is applied correctly
   - Check that bundle ID matches exactly

2. **No biometric prompt appears**
   - Verify access control flags in your Security Framework calls
   - Ensure device has biometric authentication enabled
   - Check system preferences for app permissions

3. **Code signing failures**
   - Ensure certificate is installed in Keychain Access
   - Verify team ID matches between certificate and provisioning profile
   - Check that provisioning profile is installed

### Debug Commands:

```bash
# List installed certificates
security find-identity -v -p codesigning

# List provisioning profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Check provisioning profile contents
security cms -D -i ~/Library/MobileDevice/Provisioning\ Profiles/YOUR_PROFILE.provisionprofile
```

## Production Distribution

For production distribution, you'll need to:

1. Create a "Developer ID Application" certificate
2. Create a "Developer ID" provisioning profile  
3. Notarize your app with Apple
4. Staple the notarization ticket

This allows distribution outside the Mac App Store while maintaining system trust.

## Important Notes

- Keychain access groups are automatically included for explicit App IDs
- Biometric authentication requires proper access controls in your Security Framework calls
- The `com.apple.security.cs.disable-library-validation` entitlement may be needed for Go binaries
- Test thoroughly on a clean system to ensure all entitlements work correctly