### Migrating from string to string_ignore_mac

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/string-ignore-mac-function.md

This example shows how to migrate from the standard `string` function to `string_ignore_mac` when encountering MAC errors. Use `string_ignore_mac` cautiously, as it bypasses integrity checks.

```hcl
variable "encrypted_data" {
  type = string
}

output "decrypted" {
  value = provider::sops::string(var.encrypted_data, "json")
}
```

```hcl
output "decrypted" {
  value = provider::sops::string_ignore_mac(var.encrypted_data, "json")
}
```

--------------------------------

### DecryptFile Example

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/decrypt-utilities.md

Decrypts a SOPS-encrypted file from disk. Use this when your secrets are stored in files. MAC verification is enabled by default; set `IgnoreMACMismatch` to `true` to disable it.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

// Decrypt with MAC verification (default)
cleartext, err := utils.DecryptFile("./secrets.sops.json", "json", utils.DecryptOptions{})
if err != nil {
    log.Fatalf("failed to decrypt: %v", err)
}

// Decrypt ignoring MAC mismatches
cleartext, err = utils.DecryptFile("./secrets.sops.json", "json", utils.DecryptOptions{
    IgnoreMACMismatch: true,
})
if err != nil {
    log.Fatalf("failed to decrypt: %v", err)
}
```

--------------------------------

### SOPS File Decryption Example

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Demonstrates how to use the `provider::sops::file` function to decrypt a local SOPS-encrypted file and access its raw content or parsed data.

```hcl
locals {
  secrets = provider::sops::file("./secrets.json")
}

output "raw_content" {
  value = local.secrets.raw  # String: raw decrypted content
}

output "parsed_data" {
  value = local.secrets.data  # Dynamic: {"key": "value", ...}
}

output "specific_value" {
  value = local.secrets.data.database.password  # Access nested values
}
```

--------------------------------

### DecryptFile Usage with DecryptOptions

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/types.md

Demonstrates how to use the `DecryptFile` function with different `DecryptOptions`. The first example uses default options with MAC verification enabled, while the second explicitly disables MAC verification by setting `IgnoreMACMismatch` to `true`. Use caution when ignoring MAC mismatches as it compromises data integrity.

```go
// Decrypt with MAC verification (recommended)
cleartext, err := utils.DecryptFile("secrets.json", "json", utils.DecryptOptions{})
```

```go
// Decrypt ignoring MAC mismatches (use with caution)
cleartext, err := utils.DecryptFile("secrets.json", "json", utils.DecryptOptions{
    IgnoreMACMismatch: true,
})
```

--------------------------------

### SOPS Configuration for Example

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

This YAML configuration defines creation rules for SOPS, specifying KMS encryption for different file paths. Ensure the KMS ARN is correctly set for your environment.

```yaml
creation_rules:
  - path_regex: secrets/database\.sops\.json
    kms: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
    
  - path_regex: config\.sops\.yaml
    kms: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
    
  - path_regex: \.env\.sops
    kms: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
```

--------------------------------

### Conditional Decryption Based on Environment

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/string-ignore-mac-function.md

Uses MAC verification in production environments and skips it in development. This example demonstrates conditional decryption based on an environment variable.

```hcl
locals {
  use_mac_verification = var.environment == "production"
  
  encrypted_source = "base64-encoded-sops-string"
  
  # Use MAC verification in production, skip in development
  config = use_mac_verification ?
    provider::sops::string(encrypted_source, "yaml") :
    provider::sops::string_ignore_mac(encrypted_source, "yaml")
}

output "app_config" {
  value = local.config.data
}
```

--------------------------------

### Handle Type Conversion Errors

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/dynamic-type-utilities.md

This example demonstrates how to handle errors that may occur during the conversion of JSON data to a dynamic type in Go. Ensure to check the error return value.

```go
jsonData := []byte(`{"key": "value"}`)
dynamicValue, err := utils.JSONToDynamicImplied(jsonData)
if err != nil {
    // Handle error from type creation
    log.Printf("conversion error: %v", err)
}
```

--------------------------------

### Conditional Decryption with MAC Override

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/file-ignore-mac-function.md

This example demonstrates conditional decryption. In production, it uses the standard `file` function with MAC verification. In other environments, it uses `file_ignore_mac` to skip MAC verification.

```hcl
locals {
  use_mac_check = var.environment == "production"
  
  # In production use standard file function (with MAC verification)
  # In other environments use file_ignore_mac (skip MAC verification)
  secrets = use_mac_check ? 
    provider::sops::file("./secrets.sops.json") :
    provider::sops::file_ignore_mac("./secrets.sops.json")
}

resource "aws_db_instance" "main" {
  master_username = local.secrets.data.username
  master_password = local.secrets.data.password
}
```

--------------------------------

### DecryptData Example

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/decrypt-utilities.md

Decrypts SOPS-encrypted data directly from a byte slice. Use this for in-memory encrypted data. MAC verification is enabled by default; set `IgnoreMACMismatch` to `true` to disable it.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

encryptedData := []byte("... sops encrypted content ...")

// Decrypt with MAC verification
cleartext, err := utils.DecryptData(encryptedData, "json", utils.DecryptOptions{})
if err != nil {
    log.Fatalf("failed to decrypt: %v", err)
}

// Decrypt ignoring MAC
cleartext, err = utils.DecryptData(encryptedData, "json", utils.DecryptOptions{
    IgnoreMACMismatch: true,
})
if err != nil {
    log.Fatalf("failed to decrypt: %v", err)
}
```

--------------------------------

### JSON String Escaping Example

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/dynamic-type-utilities.md

Demonstrates how JSON string escaping is automatically handled when converting JSON to HCL format. Newlines and backslashes are preserved.

```json
{
  "message": "Line 1\nLine 2",
  "path": "C:\\Users\\admin"
}
```

```hcl
{
  message = "Line 1\nLine 2"
  path = "C:\\Users\\admin"
}
```

--------------------------------

### Example Terraform Error: Failed to Read File

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/errors.md

Shows a common Terraform error message when the SOPS provider cannot read a specified file, typically because the file does not exist or lacks read permissions.

```hcl
Error: Failed to call provider function
  on main.tf line 5, in output "secret":
  provider::sops::file("./secrets.json"): failed to read "./secrets.json": 
  open ./secrets.json: no such file or directory

```

--------------------------------

### Azure Keyvault Environment Variables and Apply

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Set Azure environment variables for authentication and apply Terraform.

```bash
export AZURE_SUBSCRIPTION_ID=subscription-id
export AZURE_TENANT_ID=tenant-id
export AZURE_CLIENT_ID=client-id
export AZURE_CLIENT_SECRET=client-secret
terraform apply
```

--------------------------------

### SopsProvider Configure Method

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Handles provider configuration. This method is a no-op as the SOPS provider does not require any configuration.

```go
func (p *SopsProvider) Configure(ctx context.Context, req provider.ConfigureRequest, resp *provider.ConfigureResponse)
```

--------------------------------

### Load SOPS Encrypted Secrets in Terraform

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Use the SOPS Terraform provider to load secrets from a SOPS-encrypted JSON file. This example shows how to access database credentials.

```hcl
# environments/dev/main.tf
locals {
  secrets = provider::sops::file("${path.module}/secrets.sops.json")
}

resource "aws_db_instance" "db" {
  username = local.secrets.data.db_user
  password = local.secrets.data.db_password
}
```

--------------------------------

### Usage of Code Function in Provider Documentation

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/utility-helpers.md

Demonstrates how the `utils.Code` function is used within the provider's documentation to format supported file formats in Markdown.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

resp.Definition = function.Definition{
    Summary: "Reads and decrypts a sops encrypted file.",
    MarkdownDescription: strings.TrimSpace(dedent.Dedent(`
        Reads and decrypts a [sops](https://getsops.io/) encrypted file. An optional format can be
        provided to specify the format of the encrypted file. If not provided, we will try to infer
        the format from the file extension. Supported formats are ` + utils.Code("yaml") + `, ` + 
            utils.Code("json") + `, ` + utils.Code("dotenv") + `, ` + utils.Code("ini") + `, and ` + 
            utils.Code("binary") + `.
    `)),
}
```

--------------------------------

### Verify Key Access with CLI Tools

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/errors.md

These commands help verify access to encryption keys used by SOPS for different cloud providers and encryption methods. Ensure your credentials and permissions are correctly configured.

```bash
# AWS KMS
aws kms describe-key --key-id <key-id>
```

```bash
# GCP KMS
gcloud kms keys list --location global
```

```bash
# Age
age-keygen -l ~/.sops/age/keys.txt
```

```bash
# PGP
gpg --list-keys
```

--------------------------------

### JSON Object Conversion to Terraform Object Type

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/dynamic-type-utilities.md

Demonstrates how a nested JSON object is converted into a Terraform object type. This example shows a simple object with string and number fields.

```json
{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}
```

```hcl
{
  database = {
    host = "localhost"
    port = 5432
  }
}
```

--------------------------------

### SopsProvider Resources Method

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Returns the list of resource types provided by this provider. The SOPS provider does not implement any resources, so this returns an empty slice.

```go
func (p *SopsProvider) Resources(ctx context.Context) []func() resource.Resource
```

--------------------------------

### Utility Helpers

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for general utility helper functions.

```APIDOC
## Utility Helpers

### Description
Contains general utility functions used within the provider.

### Functions
- **Code(content string) string**: Formats content for use in code blocks, likely for documentation generation.
```

--------------------------------

### AWS KMS Environment Variables and Apply

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Set environment variables for AWS profile and region, then apply Terraform configuration.

```bash
export AWS_PROFILE=terraform
export AWS_REGION=us-east-1
terraform apply
```

--------------------------------

### Example Terraform Error: Failed to Decrypt File

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/errors.md

Illustrates a typical error message shown by Terraform when the SOPS provider fails to decrypt a file, often due to issues with key retrieval from a KMS.

```hcl
# Terraform will show errors like:
# Error: Failed to call provider function
#   on main.tf line 10, in output "secret":
#   provider::sops::file("./secrets.json"): failed to decrypt file: 
#   failed to retrieve key from KMS: access denied

```

--------------------------------

### New Factory Function

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/types.md

Creates a factory function that produces new `SopsProvider` instances. The version string is typically set at build time.

```go
func New(version string) func() provider.Provider
```

--------------------------------

### Configure Terraform SOPS Provider

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Configure the Terraform SOPS provider in your Terraform configuration. This block specifies the source and version of the provider and includes an example of how to use the `sops::file` function to decrypt a local file.

```hcl
terraform {
  required_providers {
    sops = {
      source  = "nobbs/sops"
      version = "~> 0.1.0"
    }
  }
}

provider "sops" {}

output "secret" {
  value = provider::sops::file("./secrets.sops.json")
}
```

--------------------------------

### New SopsProvider Factory Function

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Creates a new SopsProvider factory function. The version parameter is set by the build process.

```go
func New(version string) func() provider.Provider
```

```go
// Called from main.go
providerFunc := provider.New("1.0.0")
provider := providerFunc()
```

--------------------------------

### GCP Cloud KMS Environment Variables and Apply

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Set the GOOGLE_APPLICATION_CREDENTIALS environment variable and apply Terraform.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
terraform apply
```

--------------------------------

### Decrypt SOPS Encrypted String with `string` Function

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/README.md

Use the `provider::sops::string` function to decrypt a SOPS-encrypted string, which can be useful for secrets not stored in local files. This example fetches the encrypted content from a URL using the `http` data source.

```hcl
data "http" "raw" {
  url = "https://raw.githubusercontent.com/nobbs/terraform-provider-sops/refs/heads/main/test/fixtures/raw.sops.txt"
}

output "raw" {
  value = provider::sops::string(data.http.raw.response_body)
}
```

--------------------------------

### SopsProvider.New

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Factory function to create a new SOPS provider instance. It takes the version as an argument.

```APIDOC
## SopsProvider.New

### Description
Provider factory function.

### Parameters
#### Path Parameters
- **version** (string) - Required - The version of the provider.
```

--------------------------------

### SopsProvider DataSources Method

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Returns the list of data source types provided by this provider. The SOPS provider does not implement any data sources, so this returns an empty slice.

```go
func (p *SopsProvider) DataSources(ctx context.Context) []func() datasource.DataSource
```

--------------------------------

### Age Key Configuration for SOPS

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Configure Age for SOPS by providing your Age public key in the `.sops.yaml` file.

```yaml
creation_rules:
  - age: 'age1...'

```

--------------------------------

### Format String as Code

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Wraps a given string in Markdown code formatting, enclosing it in backticks. Use this for displaying code snippets or identifiers.

```go
func Code(s string) string
```

--------------------------------

### Format Utilities

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for utilities related to file format detection and parsing.

```APIDOC
## Format Utilities

### Description
Provides functions for detecting, validating, and parsing various file formats.

### Functions
- **IsValidFormat(format string) bool**: Checks if a given format string is supported.
- **FileFormatFromPath(path string) string**: Determines the file format based on its path.
- **IsYAMLFile(path string) bool**: Checks if a file is a YAML file.
- **IsJSONFile(path string) bool**: Checks if a file is a JSON file.
- **ReadYAML(path string) (map[string]interface{}, error)**: Reads and parses a YAML file.
- **ReadJSON(path string) (map[string]interface{}, error)**: Reads and parses a JSON file.
- **ReadINI(path string) (map[string]interface{}, error)**: Reads and parses an INI file.
- **ReadENV(path string) (map[string]interface{}, error)**: Reads and parses an ENV file.
```

--------------------------------

### PGP Key Configuration for SOPS

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Configure PGP for SOPS by providing your GPG key fingerprint in the `.sops.yaml` file.

```yaml
creation_rules:
  - pgp: '1234567890ABCDEF'

```

--------------------------------

### GitHub Actions Workflow for Terraform Apply

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Automate Terraform deployments using GitHub Actions. This workflow checks out code, sets up Terraform and AWS credentials, and applies Terraform configurations.

```yaml
name: Terraform Apply

on:
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: ~> 1.8
      
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: arn:aws:iam::123456789012:role/terraform
          aws-region: us-east-1
      
      - name: Terraform Init
        run: terraform init
      
      - name: Terraform Apply
        run: terraform apply -auto-approve
```

--------------------------------

### SopsProvider Functions Method

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Returns the list of provider functions exposed by this provider. These functions are used for decrypting SOPS-encrypted content.

```go
func (p *SopsProvider) Functions(ctx context.Context) []func() function.Function
```

```hcl
terraform {
  required_providers {
    sops = {
      source = "nobbs/sops"
      version = "~> 0.1.0"
    }
  }
}

provider "sops" {}

output "decrypted" {
  value = provider::sops::file("/path/to/encrypted.sops.json")
}
```

--------------------------------

### Infer SOPS File Format from Path

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Infers the SOPS format from a file path based on its extension. Returns 'yaml', 'json', 'dotenv', 'ini', or 'binary' as a fallback.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

format := utils.FileFormatFromPath("./config.sops.yaml")
// Returns: "yaml"

format := utils.FileFormatFromPath("./secrets.sops.json")
// Returns: "json"

format := utils.FileFormatFromPath("./.env.encrypted")
// Returns: "dotenv"

format := utils.FileFormatFromPath("./config.sops.ini")
// Returns: "ini"

format := utils.FileFormatFromPath("./data.sops.bin")
// Returns: "binary"
```

--------------------------------

### SopsProvider Configure

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Handles provider configuration. This method is a no-op as the SOPS provider does not require any configuration.

```APIDOC
## Configure

Handles provider configuration. This is a no-op since the SOPS provider requires no configuration.

### Signature

```go
func (p *SopsProvider) Configure(ctx context.Context, req provider.ConfigureRequest, resp *provider.ConfigureResponse)
```

### Parameters

- **ctx** (context.Context) - Required - Request context
- **req** (provider.ConfigureRequest) - Required - Configuration request from Terraform
- **resp** (*provider.ConfigureResponse) - Required - Response object
```

--------------------------------

### Integration with Provider Functions

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/unmarshal-utilities.md

Illustrates the complete workflow within provider functions, including decryption, unmarshalling decrypted data into JSON, and converting it to a Terraform dynamic type. Errors at each step are handled by returning a `FuncError`.

```go
// 1. Decrypt the data
cleartext, err := utils.DecryptFile(path, format, opts)
if err != nil {
    resp.Error = function.NewFuncError(fmt.Sprintf("failed to decrypt file: %v", err))
    return
}

// 2. Unmarshal decrypted data
json, err := utils.UnmarshalDecryptedData(cleartext, format)
if err != nil {
    resp.Error = function.NewFuncError(fmt.Sprintf("failed to unmarshal decrypted data: %v", err))
    return
}

// 3. Convert to Terraform dynamic type
dynamicData, err := utils.JSONToDynamicImplied(json)
if err != nil {
    resp.Error = function.NewFuncError(fmt.Sprintf("failed to convert decrypted data to dynamic data: %v", err))
    return
}
```

--------------------------------

### Handle Binary Data

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/unmarshal-utilities.md

For binary data, which has no inherent structure, this utility returns empty JSON bytes. The raw content is expected to be handled separately.

```go
case "binary":
    json, err = []byte{}, nil
```

--------------------------------

### Azure Keyvault Configuration for SOPS

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Configure Azure Keyvault for SOPS by specifying the full URL to your key in the Azure Keyvault instance within the `.sops.yaml` file.

```yaml
creation_rules:
  - azure_kv:
      - 'https://VAULT.vault.azure.net/keys/KEY/VERSION'

```

--------------------------------

### Migrating from SOPS file to file_ignore_mac

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/file-ignore-mac-function.md

Use this snippet to migrate from the standard `provider::sops::file` function to `provider::sops::file_ignore_mac` when encountering MAC verification errors. This bypasses the integrity check.

```hcl
# Before: Fails with MAC error
output "secrets" {
  value = provider::sops::file("./problematic.sops.json")
}

# After: Works but skips integrity check
output "secrets" {
  value = provider::sops::file_ignore_mac("./problematic.sops.json")
}
```

--------------------------------

### Complete Terraform Provider Configuration

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

This configuration sets up the Terraform backend and the SOPS provider, demonstrating how to load secrets from different file types (JSON, YAML, .env) using auto-detection or explicit format specification. It also shows how to output sensitive values.

```hcl
terraform {
  required_version = ">= 1.8"
  required_providers {
    sops = {
      source  = "nobbs/sops"
      version = "~> 0.1.0"
    }
  }
}

provider "sops" {}

locals {
  # Auto-detect format from file extension
  database_secrets = provider::sops::file("${path.module}/secrets/database.sops.json")
  
  # Explicit format specification
  app_config = provider::sops::file("${path.module}/config.sops.yaml", "yaml")
  
  # Environment variables
  env_vars = provider::sops::file("${path.module}/.env.sops", "dotenv")
}

output "db_host" {
  value     = local.database_secrets.data.host
  sensitive = true
}

output "db_password" {
  value     = local.database_secrets.data.password
  sensitive = true
}

output "api_key" {
  value     = local.app_config.data.external_api.key
  sensitive = true
}
```

--------------------------------

### Go Function Signature for File Ignore MAC

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/file-ignore-mac-function.md

This Go function signature defines how to create an instance of the file ignore MAC function. It returns a function.Function interface for use within the provider.

```go
func NewFileIgnoreMacFunction() function.Function
```

--------------------------------

### Validate Supported Format

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Use this function to check if a given format string is supported by the provider. Supported formats include yaml, json, dotenv, ini, and binary.

```go
func IsValidFormat(format string) bool
```

--------------------------------

### Format Conversion Flow Diagram

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Illustrates the step-by-step process of decrypting and parsing data into a Terraform-compatible JSON structure.

```text
Encrypted File/String
        ↓
   Decrypt (via DecryptData/DecryptFile)
        ↓
   Decrypted Bytes
        ↓
   Format-Specific Parser (ReadYAML, ReadJSON, etc.)
        ↓
   JSON Bytes
        ↓
   JSONToDynamicImplied (convert to Terraform dynamic type)
        ↓
   Object with "raw" and "data" attributes
```

--------------------------------

### Age Private Key via Environment Variable

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Provide the Age private key using the SOPS_AGE_KEY environment variable for decryption.

```bash
export SOPS_AGE_KEY=$(cat ~/.sops/age/keys.txt)
terraform apply
```

--------------------------------

### Azure Keyvault Configuration

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Configure SOPS to use Azure Keyvault. Ensure Azure service principal details are set.

```yaml
creation_rules:
  - azure_kv:
      - https://VAULT_NAME.vault.azure.net/keys/KEY_NAME/VERSION
```

--------------------------------

### Individual Format Checkers

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Provides boolean functions to check if a given file path corresponds to a specific format. Use these for explicit format validation before parsing.

```go
IsYAMLFile(path) → bool
```

```go
IsJSONFile(path) → bool
```

```go
IsEnvFile(path) → bool
```

```go
IsIniFile(path) → bool
```

--------------------------------

### Code

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Wraps a given string in Markdown code formatting.

```APIDOC
## Code

### Description
Wraps string in Markdown code formatting.

### Signature
```go
func Code(s string) string
```

### Parameters
- `s` (string): String to format

### Returns
String wrapped in backticks (e.g., `` `yaml` ``)
```

--------------------------------

### Create SOPS File Function

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/file-function.md

Returns a function that implements SOPS file decryption. This is typically used internally by the provider.

```go
func NewFileFunction() function.Function
```

--------------------------------

### Dynamic Type Utilities

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for utilities that handle dynamic type conversions, particularly for JSON data.

```APIDOC
## Dynamic Type Utilities

### Description
Provides functions for converting JSON data into dynamically implied types, supporting complex structures and type conversions.

### Functions
- **JSONToDynamicImplied(data map[string]interface{}) (interface{}, error)**: Converts a JSON object into a dynamically typed representation.
```

--------------------------------

### New SopsProvider Factory

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Creates a new SopsProvider factory function. This function is used to instantiate the provider.

```APIDOC
## New

Creates a new SopsProvider factory function.

### Signature

```go
func New(version string) func() provider.Provider
```

### Parameters

- **version** (string) - Required - The provider version string (set by build process)

### Returns

A function that returns a new `provider.Provider` instance. Returns `*SopsProvider`.

### Example

```go
// Called from main.go
providerFunc := provider.New("1.0.0")
provider := providerFunc()
```
```

--------------------------------

### Provider Functions

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Details on the core functions provided by the SopsProvider, including how to instantiate, configure, and access its schema and resources.

```APIDOC
## Provider Operations

### Description
Provides core functionality for the Terraform SOPS provider, including initialization, configuration, and schema definition.

### Methods
- **New()**: Factory function to create a new SopsProvider instance.
- **Metadata()**: Returns metadata about the provider.
- **Schema()**: Returns the provider's schema.
- **Configure(config map[string]interface{})**: Configures the provider with given settings.
- **Resources()**: Returns a list of resources managed by the provider.
- **DataSources()**: Returns a list of data sources managed by the provider.
- **Functions()**: Returns a list of functions provided by the provider.
```

--------------------------------

### SOPS CLI Debugging and Validation

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/errors.md

Demonstrates how to use the SOPS CLI to decrypt and inspect data, and how to validate decrypted content using tools like `jq` for JSON and `yq` for YAML. This helps in diagnosing unmarshaling errors.

```bash
# Decrypt with SOPS CLI to check format
sops -d secrets.sops.json

# Validate JSON
cat decrypted.json | jq . > /dev/null

# Validate YAML
cat decrypted.yaml | yq . > /dev/null
```

--------------------------------

### Encrypt Secrets and Update .gitignore

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Encrypt sensitive files using SOPS and ensure they are not committed to version control by adding them to .gitignore.

```bash
# Encrypt secrets with SOPS
sops secrets.json

# Keep .gitignore clean
echo "secrets.json" >> .gitignore
echo ".sops.yaml" >> .gitignore
```

--------------------------------

### PGP GPG Home Directory Configuration

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Apply Terraform using PGP encryption, optionally specifying a custom GPG home directory.

```bash
# Use GPG keys from standard location
terraform apply

# Or specify custom GPG home
export GNUPGHOME=/path/to/.gnupg
terraform apply
```

--------------------------------

### ReadYAML: Parse YAML to JSON

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Use this function to convert YAML formatted byte data into its JSON representation. Ensure the input is valid YAML; otherwise, an error will be returned.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

yamlData := []byte(`
key: value
nested:
  inner: data
`)

jsonBytes, err := utils.ReadYAML(yamlData)
if err != nil {
    log.Fatalf("failed to parse YAML: %v", err)
}
// jsonBytes contains: {"key":"value","nested":{"inner":"data"}}
```

--------------------------------

### DecryptOptions Struct

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/string-ignore-mac-function.md

Defines options for the SOPS decryption process. For string_ignore_mac, IgnoreMACMismatch is set to true.

```go
type DecryptOptions struct {
    IgnoreMACMismatch bool
}
```

--------------------------------

### Supported Formats

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/string-ignore-mac-function.md

Lists the supported file formats for parsing decrypted SOPS content, similar to the standard `string` function.

```APIDOC
## Supported Formats

| Format |
|-----------||
| `yaml` |
| `json` |
| `dotenv` |
| `ini` |
| `binary` |

**Description**: These formats determine how the decrypted content is parsed. `binary` is the default and results in `null` for the `data` attribute. Other formats parse the content into structured data.
```

--------------------------------

### Infer File Format from Path

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

This function infers the data format based on a file's extension. It returns a string representing the detected format, such as yaml, json, dotenv, ini, or binary.

```go
func FileFormatFromPath(path string) string
```

--------------------------------

### Utility Functions

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for various utility functions provided by the sops provider.

```APIDOC
## DecryptFile()

### Description
Complete documentation for the DecryptFile utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## DecryptData()

### Description
Complete documentation for the DecryptData utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## IsValidFormat()

### Description
Complete documentation for the IsValidFormat utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## FileFormatFromPath()

### Description
Complete documentation for the FileFormatFromPath utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## Format checkers (4)

### Description
Complete documentation for 4 format checker utility functions.

### Method
Utility Functions

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## Format parsers (4)

### Description
Complete documentation for 4 format parser utility functions.

### Method
Utility Functions

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## UnmarshalDecryptedData()

### Description
Complete documentation for the UnmarshalDecryptedData utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## JSONToDynamicImplied()

### Description
Complete documentation for the JSONToDynamicImplied utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## Code()

### Description
Complete documentation for the Code utility function.

### Method
Utility Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### SOPS Configuration for Multiple Environments

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Define KMS key ARNs for different environments using path regex. This ensures that secrets for each environment are encrypted with a specific KMS key.

```yaml
creation_rules:
  - path_regex: environments/dev/.*\.sops\.json
    kms: 'arn:aws:kms:us-east-1:123456789012:key/dev-key-id'
    
  - path_regex: environments/staging/.*\.sops\.json
    kms: 'arn:aws:kms:us-east-1:123456789012:key/staging-key-id'
    
  - path_regex: environments/prod/.*\.sops\.json
    kms: 'arn:aws:kms:us-east-1:123456789012:key/prod-key-id'
```

--------------------------------

### Check for YAML File Extension

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Determines if a file path has a YAML extension (.yaml or .yml).

```go
if utils.IsYAMLFile("config.sops.yaml") {
    format = "yaml"
}
```

--------------------------------

### Development Environment Decryption

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/file-ignore-mac-function.md

In development, MAC verification might not be critical. This snippet shows how to decrypt configuration and environment files, including specific formats like dotenv.

```hcl
# In development, MAC verification might not be critical
output "dev_config" {
  value = provider::sops::file_ignore_mac("./dev/config.sops.yaml")
}

output "dev_secrets" {
  value = {
    database_url = provider::sops::file_ignore_mac("./dev/db.sops.env", "dotenv").data
  }
  sensitive = true
}
```

--------------------------------

### Format String as Markdown Inline Code

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/utility-helpers.md

Wraps a given string with backticks to format it as Markdown inline code. Useful for displaying literal strings or code snippets in documentation.

```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

formatted := utils.Code("json")
// Returns: "`json`"

output := utils.Code("provider::sops::file")
// Returns: "`provider::sops::file`"
```

```go
func Code(s string) string {
    return fmt.Sprintf("`%s`", s)
}
```

--------------------------------

### Parse Binary File

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/types.md

Use this to decrypt a binary file. The output includes raw content as a string and null for data.

```hcl
output "result" {
  value = provider::sops::file("./data.sops.bin", "binary")
}
```

--------------------------------

### SopsProvider Type Definition

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Defines the SopsProvider struct, which holds the provider's version information.

```go
type SopsProvider struct {
    // version is set to the provider version on release, "dev" when the
    // provider is built and ran locally, and "test" when running acceptance
    // testing.
    version string
}
```

--------------------------------

### Check for Dotenv File Extension

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Determines if a file path has a dotenv extension (.env).

```go
if utils.IsEnvFile(".env.sops") {
    format = "dotenv"
}
```

--------------------------------

### ReadYAML

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/format-utilities.md

Parses YAML data into JSON format. It takes byte content of a YAML file and returns its JSON representation.

```APIDOC
## ReadYAML

### Description
Parses YAML data into JSON format. It takes byte content of a YAML file and returns its JSON representation.

### Method Signature
```go
func ReadYAML(data []byte) ([]byte, error)
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **data** ([]byte) - Required - YAML-formatted byte content

### Request Example
```go
import "github.com/nobbs/terraform-provider-sops/internal/provider/utils"

yamlData := []byte(`
key: value
nested:
  inner: data
`)

jsonBytes, err := utils.ReadYAML(yamlData)
if err != nil {
    log.Fatalf("failed to parse YAML: %v", err)
}
// jsonBytes contains: {"key":"value","nested":{"inner":"data"}}
```

### Response
#### Success Response (200)
- **[]byte**: JSON representation of the YAML data

#### Error Response
- **error**: Error if YAML parsing or JSON marshaling fails

### Errors
- **(YAML unmarshal error)**: Invalid YAML syntax or structure
- **(JSON marshal error)**: Failed to convert parsed YAML to JSON
```

--------------------------------

### Provider Functions

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for the main provider functions available for use.

```APIDOC
## provider::sops::file()

### Description
Complete documentation with examples for decrypting files using the sops provider.

### Method
Provider Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## provider::sops::file_ignore_mac()

### Description
Complete documentation with security notes for decrypting files while ignoring MAC verification using the sops provider.

### Method
Provider Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## provider::sops::string()

### Description
Complete documentation with examples for decrypting strings using the sops provider.

### Method
Provider Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

```APIDOC
## provider::sops::string_ignore_mac()

### Description
Complete documentation with security notes for decrypting strings while ignoring MAC verification using the sops provider.

### Method
Provider Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Provider Function Dependency Graph

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Illustrates the dependency flow from Terraform functions down to the internal Go utilities for decryption, format handling, and data unmarshalling. This helps understand how data is processed.

```text
Provider Functions (Terraform)
    ↓
Provider.Functions()
    ↓
NewFileFunction, NewStringFunction, etc.
    ↓
Run() methods call utilities:
    ├─ DecryptFile/DecryptData (decrypt.go)
    ├─ IsValidFormat (formats.go)
    ├─ FileFormatFromPath (formats.go)
    ├─ UnmarshalDecryptedData (unmarshal.go)
    │   ├─ ReadYAML/ReadJSON/ReadINI/ReadENV (formats.go)
    │   └─ Returns JSON bytes
    └─ JSONToDynamicImplied (dynamictype.go)
        └─ Returns Terraform dynamic type
```

--------------------------------

### SOPS Decryption Process Flow

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/README.md

Illustrates the step-by-step process of decrypting SOPS-encrypted data, from encrypted input to a structured JSON representation.

```text
Encrypted File/String
    ↓
Decrypt (via SOPS library)
    ↓
Decrypted Bytes
    ↓
Parse Format (YAML/JSON/INI/Dotenv)
    ↓
JSON Representation
    ↓
Convert to Terraform Dynamic Type
    ↓
Object { raw: string, data: dynamic }
```

--------------------------------

### SopsProvider Metadata Implementation

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Implements the Terraform provider metadata interface, setting the provider type name and version. This is used internally by Terraform to identify the provider.

```go
func (p *SopsProvider) Metadata(ctx context.Context, req provider.MetadataRequest, resp *provider.MetadataResponse)
```

```go
// Terraform uses this internally to identify the provider
// Response: TypeName = "sops", Version = "1.0.0"
```

--------------------------------

### SOPS Configuration Rules

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Define SOPS encryption rules based on file paths using different KMS providers or Age.

```yaml
creation_rules:
  - path_regex: secrets\.json$
    kms: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'

  - path_regex: secrets\.yaml$
    gcp_kms:
      - projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY

  - path_regex: secrets\.env$
    azure_kv:
      - https://VAULT_NAME.vault.azure.net/keys/KEY_NAME/VERSION

  - path_regex: '.*'
    age: AGE_PUBLIC_KEY
```

--------------------------------

### FileFormatFromPath

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/INDEX.md

Infers the file format from a given file path based on its extension. Returns a string representing the detected format.

```APIDOC
## FileFormatFromPath

### Description
Infers format from file path extension.

### Signature
```go
func FileFormatFromPath(path string) string
```

### Returns
Format string (`yaml`, `json`, `dotenv`, `ini`, `binary`)
```

--------------------------------

### Provider Functions Return Type

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/types.md

All four provider functions (`file`, `file_ignore_mac`, `string`, `string_ignore_mac`) return an object with a consistent structure containing the raw decrypted content and parsed data.

```APIDOC
## Return Type Object

All four provider functions return an object with the same structure.

**Type**: Object (Terraform object type)

**Fields**

| Field | Type | Description |
|-------|------|-------------|
| raw | string | Raw decrypted content as plain text. Always available regardless of format. Contains the decrypted file/string content exactly as decrypted. |
| data | dynamic | Parsed structured data. Type depends on the specified format. For `binary` format or when parsing fails, this is `null`. For `yaml`, `json`, `dotenv`, `ini`, this contains the parsed structure. |

**Usage in HCL**

```hcl
output "decrypted" {
  value = provider::sops::file("./secrets.json")
}

# Access raw content
local.result.raw  # String: raw decrypted content

# Access parsed data
local.result.data                    # Dynamic: parsed structure
local.result.data.database.password  # Nested access (for JSON/YAML)
local.result.data.DATABASE_URL       # Flat access (for dotenv)
```

**Returned by**

- `provider::sops::file(path, format?)
- `provider::sops::file_ignore_mac(path, format?)
- `provider::sops::string(data, format?)
- `provider::sops::string_ignore_mac(data, format?)
```

--------------------------------

### SOPS File Function Format Errors

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/errors.md

Illustrates incorrect and correct usage of the format parameter for the `provider::sops::file` function. Use lowercase, exact format names like 'yaml', or rely on auto-detection via file extension.

```hcl
# Wrong: Typo in format
provider::sops::file("./config.yaml", "yml")  # Error: invalid format

# Correct: Proper format name
provider::sops::file("./config.yaml", "yaml")

# Correct: Auto-detect from extension
provider::sops::file("./config.sops.yaml")

# Correct: Explicit format with unconventional extension
provider::sops::file("./config.sops", "json")
```

--------------------------------

### Unmarshal Utilities

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/MANIFEST.md

Documentation for utilities used to unmarshal decrypted data into various formats.

```APIDOC
## Unmarshal Utilities

### Description
Handles the unmarshaling of decrypted data into structured formats.

### Functions
- **UnmarshalDecryptedData(data []byte, format string) (interface{}, error)**: Unmarshals decrypted data based on the specified format.
```

--------------------------------

### General Error Handling for Unmarshalling

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/unmarshal-utilities.md

Provides a general approach to handling errors during the unmarshalling process. It includes logging the error and optionally falling back to an empty byte slice.

```go
json, err := utils.UnmarshalDecryptedData(data, format)
if err != nil {
    // Log the error
    log.Printf("failed to parse %s: %v", format, err)
    
    // Could fall back to binary
    json = []byte{}
}
```

--------------------------------

### Parse Dotenv File

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/types.md

Use this to decrypt and parse a .env file. The output includes raw and data fields.

```hcl
output "result" {
  value = provider::sops::file("./.env.sops", "dotenv")
}
```

--------------------------------

### PGP Encryption Configuration

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/configuration.md

Configure SOPS to use PGP encryption with a GPG key fingerprint.

```yaml
creation_rules:
  - pgp: '1234567890ABCDEF...'  # GPG key fingerprint
```

--------------------------------

### SopsProvider Schema Definition

Source: https://github.com/nobbs/terraform-provider-sops/blob/main/_autodocs/api-reference/provider.md

Defines the provider schema. The SOPS provider requires no configuration options, and its schema definition is empty.

```go
func (p *SopsProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse)
```

```hcl
provider "sops" {}
```