macOS Keychain Terraform Provider Development

Overview

You are developing a Terraform provider for managing items in macOS Keychains. This provider enables infrastructure-as-code management of secrets, certificates, keys, and identities stored in user-accessible macOS Keychains.

Technology Stack

Project Structure

```

terraform-provider-keychain/

├── CLAUDE.md

├── Brewfile

├── Makefile

├── .golangci.yml

├── .gitleaks.toml

├── .pre-commit-config.yaml

├── main.go

├── go.mod

├── go.sum

├── dist/

├── internal/

│ ├── provider/

│ ├── keychain/

│ ├── resources/

│ └── datasources/

├── examples/

└── docs/

```

Supported Keychain Item Types

The provider must support all macOS SecItemClass types:

1. **generic_password** - Application passwords, API keys, tokens

2. **internet_password** - Web/network credentials with protocol, server, port

3. **certificate** - X.509 certificates

4. **key** - Cryptographic keys (symmetric, asymmetric)

5. **identity** - Certificate + private key pairs

Development Instructions

Step 1: Project Setup

1. Initialize Go module and install dependencies

2. Set up project structure following the directory layout above

3. Install Homebrew dependencies from Brewfile

4. Install Xcode Command Line Tools for cgo cross-compilation

Step 2: Implement Provider Configuration

Create provider schema supporting:

Step 3: Implement cgo Keychain Bindings

Create `internal/keychain/` package with:

**Required cgo setup:**

```go

// #cgo CFLAGS: -x objective-c

// #cgo LDFLAGS: -framework Security -framework CoreFoundation

```

**Key Security.framework functions to wrap:**

**Map OSStatus codes to Go errors:**

Step 4: Implement Resources

Create resources in `internal/resources/` for each item type:

**keychain_generic_password:**

**keychain_internet_password:**

**keychain_certificate:**

**keychain_key:**

**keychain_identity:**

Step 5: Implement Data Sources

Create corresponding data sources in `internal/datasources/` for reading existing keychain items. Each resource should have a matching data source.

Step 6: Security Implementation

**Critical security practices:**

1. **Never log secret values** - Use tflog.Trace with SecretAttribute masking

2. **Mark sensitive fields** - Set `Sensitive: true` on all password/key schemas

3. **Zero memory after use** - Clear byte slices containing secrets

4. **Avoid string conversions** - Use `[]byte` for secrets (strings are immutable)

5. **No secrets in errors** - Sanitize error messages before returning

**Example secure handling:**

```go

func (k *Keychain) GetPassword(service, account string) ([]byte, error) {

password, err := k.secItemCopyMatching(...)

if err != nil {

return nil, fmt.Errorf("failed to retrieve item: %w", err)

}

return password, nil

}

// Caller must zero memory:

defer func() {

for i := range password {

password[i] = 0

}

}()

```

Step 7: Configure Security Scanning

Set up mandatory security scanning tools:

**Install tools:**

**Create `.golangci.yml`** with enabled linters:

**Create `.gitleaks.toml`** with allowlist for:

**Create `.pre-commit-config.yaml`** with hooks for:

**Add Makefile targets:**

```makefile

security: gosec govulncheck gitleaks trivy

gosec:

gosec -exclude-dir=testdata ./...

govulncheck:

govulncheck ./...

gitleaks:

gitleaks detect --source . --verbose

trivy:

trivy fs --security-checks vuln,secret,config .

```

Step 8: Cross-Platform Build Support

Create Makefile targets for building both architectures:

```makefile

build-arm64:

GOOS=darwin GOARCH=arm64 go build -o dist/terraform-provider-keychain_v0.1.0_darwin_arm64

build-amd64:

GOOS=darwin GOARCH=amd64 go build -o dist/terraform-provider-keychain_v0.1.0_darwin_amd64

build-all: build-arm64 build-amd64

```

Step 9: CI/CD Setup

Create `.github/workflows/security.yml` that runs on every push:

1. Install security tools via Homebrew

2. Run gosec

3. Run govulncheck

4. Run gitleaks with full git history

5. Run trivy

6. Fail build on any security findings

Create `.github/workflows/release.yml` for cross-arch builds on tags.

Step 10: Documentation

Create comprehensive documentation:

1. **Provider configuration** with examples

2. **Resource schemas** with all attributes and examples

3. **Data source usage** patterns

4. **Security considerations** - Warning about Terraform state containing secrets

5. **Keychain access** requirements and ACL configuration

6. **CI/CD recommendations** for `security set-key-partition-list`

Important Constraints

1. **No keychain creation** - Keychains must pre-exist; provider only manages items

2. **User permissions** - Provider runs with executing user's permissions

3. **State security** - Warn users that secrets appear in Terraform state; recommend encrypted backends

4. **macOS only** - This provider only works on macOS (Darwin)

5. **Security mandatory** - All security scans must pass before commits/releases

Testing Recommendations

1. Test on both ARM64 and AMD64 architectures

2. Test with locked and unlocked keychains

3. Test keychain password authentication

4. Test all CRUD operations for each resource type

5. Test data source queries

6. Verify sensitive values are marked and masked appropriately

7. Test error handling for all OSStatus codes

Security Warning for Users

Document clearly: