feat(smtp): write-only password support for SMTP credentials (#52)

.changelog/76.txt

@@ -0,0 +1,7 @@
+```release-note:enhancement
+resource/mailgun_smtp_credential: Add write-only `password_wo` and `password_wo_version` arguments. The secret is never stored in Terraform state; increment the version to rotate. Requires Terraform CLI >= 1.11.
+```
+
+```release-note:deprecation
+resource/mailgun_smtp_credential: The `password` argument is deprecated in favor of `password_wo`/`password_wo_version` and will be removed in a future major release.
+```

docs/resources/smtp_credential.md

@@ -23,8 +23,34 @@ resource "mailgun_smtp_credential" "app" {
 output "smtp_full_login" {
   value = mailgun_smtp_credential.app.full_login
 }
+
+# Write-only password (recommended). Requires Terraform CLI >= 1.11.
+# The secret is never written to Terraform state. Bump password_wo_version to rotate.
+# An ephemeral random_password keeps the generated secret out of state entirely.
+ephemeral "random_password" "smtp" {
+  length  = 24
+  special = false
+}
+
+resource "mailgun_smtp_credential" "app_wo" {
+  domain              = "mail.example.com"
+  login               = "app-mailer-wo"
+  password_wo         = ephemeral.random_password.smtp.result
+  password_wo_version = 1
+}
 ```
 
+## Write-Only Password
+
+The `password_wo` and `password_wo_version` arguments provide a write-only credential workflow that keeps the secret out of Terraform state entirely:
+
+- Requires Terraform CLI >= 1.11.
+- The value of `password_wo` is never stored in state or shown in plan output.
+- Rotate the password by changing `password_wo` and incrementing `password_wo_version`.
+- Credentials imported with `terraform import` have no password in state; use `password_wo` + `password_wo_version` to set one and enable future rotation.
+
+The legacy `password` argument is deprecated and will be removed in a future major release.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -35,7 +61,11 @@ output "smtp_full_login" {
 
 ### Optional
 
-- `password` (String, Sensitive) The password for SMTP authentication. This is write-only and cannot be read back from the API. Set this when creating a credential or when rotating the password of an imported credential. Leave it unset to keep the existing password of an imported credential.
+> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.
+
+- `password` (String, Sensitive, Deprecated) The password for SMTP authentication. This is write-only and cannot be read back from the API. Set this when creating credentials or when rotating the password. Leave it unset to maintain the existing password during import.
+- `password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only password for SMTP authentication. The value is never stored in Terraform state. Always set it together with password_wo_version.
+- `password_wo_version` (Number) Version counter for password_wo. Increment this value to rotate the write-only password. **Required** when password_wo is set.
 
 ### Read-Only
 

examples/resources/mailgun_smtp_credential/resource.tf

@@ -9,3 +9,18 @@ resource "mailgun_smtp_credential" "app" {
 output "smtp_full_login" {
   value = mailgun_smtp_credential.app.full_login
 }
+
+# Write-only password (recommended). Requires Terraform CLI >= 1.11.
+# The secret is never written to Terraform state. Bump password_wo_version to rotate.
+# An ephemeral random_password keeps the generated secret out of state entirely.
+ephemeral "random_password" "smtp" {
+  length  = 24
+  special = false
+}
+
+resource "mailgun_smtp_credential" "app_wo" {
+  domain              = "mail.example.com"
+  login               = "app-mailer-wo"
+  password_wo         = ephemeral.random_password.smtp.result
+  password_wo_version = 1
+}

internal/provider/smtp_credentials/helpers_internal_test.go

@@ -0,0 +1,138 @@
+// Copyright Hack The Box 2025, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package smtp_credentials
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+func TestPasswordForCreate(t *testing.T) {
+	tests := []struct {
+		name       string
+		passwordWO types.String
+		legacy     types.String
+		wantPass   string
+		wantOK     bool
+	}{
+		{"write-only preferred", types.StringValue("wo-secret"), types.StringValue("legacy"), "wo-secret", true},
+		{"legacy when no wo", types.StringNull(), types.StringValue("legacy"), "legacy", true},
+		{"neither set", types.StringNull(), types.StringNull(), "", false},
+		{"legacy unknown ignored", types.StringNull(), types.StringUnknown(), "", false},
+		{"wo unknown falls back to legacy", types.StringUnknown(), types.StringValue("legacy"), "legacy", true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotPass, gotOK := passwordForCreate(tt.passwordWO, tt.legacy)
+			if gotPass != tt.wantPass || gotOK != tt.wantOK {
+				t.Errorf("passwordForCreate() = (%q, %v), want (%q, %v)", gotPass, gotOK, tt.wantPass, tt.wantOK)
+			}
+		})
+	}
+}
+
+func TestWriteOnlyRotationRequested(t *testing.T) {
+	tests := []struct {
+		name  string
+		plan  types.Int64
+		state types.Int64
+		want  bool
+	}{
+		{"version bumped", types.Int64Value(2), types.Int64Value(1), true},
+		{"version unchanged", types.Int64Value(1), types.Int64Value(1), false},
+		{"first set from null state", types.Int64Value(1), types.Int64Null(), true},
+		{"no version in plan", types.Int64Null(), types.Int64Null(), false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := writeOnlyRotationRequested(tt.plan, tt.state); got != tt.want {
+				t.Errorf("writeOnlyRotationRequested() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveUpdatePassword(t *testing.T) {
+	tests := []struct {
+		name         string
+		passwordWO   types.String
+		planPW       types.String
+		planVersion  types.Int64
+		stateVersion types.Int64
+		wantPW       string
+		wantRotate   bool
+		wantErr      string
+	}{
+		{
+			name:         "write-only with version bump rotates",
+			passwordWO:   types.StringValue("wo-secret"),
+			planPW:       types.StringNull(),
+			planVersion:  types.Int64Value(2),
+			stateVersion: types.Int64Value(1),
+			wantPW:       "wo-secret",
+			wantRotate:   true,
+			wantErr:      "",
+		},
+		{
+			name:         "write-only without version bump skips rotation",
+			passwordWO:   types.StringValue("wo-secret"),
+			planPW:       types.StringNull(),
+			planVersion:  types.Int64Value(1),
+			stateVersion: types.Int64Value(1),
+			wantPW:       "",
+			wantRotate:   false,
+			wantErr:      "",
+		},
+		{
+			name:         "legacy null preserves imported state",
+			passwordWO:   types.StringNull(),
+			planPW:       types.StringNull(),
+			planVersion:  types.Int64Null(),
+			stateVersion: types.Int64Null(),
+			wantPW:       "",
+			wantRotate:   false,
+			wantErr:      "",
+		},
+		{
+			name:         "legacy empty string is an error",
+			passwordWO:   types.StringNull(),
+			planPW:       types.StringValue(""),
+			planVersion:  types.Int64Null(),
+			stateVersion: types.Int64Null(),
+			wantPW:       "",
+			wantRotate:   false,
+			wantErr:      "Invalid Password",
+		},
+		{
+			name:         "legacy non-empty rotates",
+			passwordWO:   types.StringNull(),
+			planPW:       types.StringValue("newpass"),
+			planVersion:  types.Int64Null(),
+			stateVersion: types.Int64Null(),
+			wantPW:       "newpass",
+			wantRotate:   true,
+			wantErr:      "",
+		},
+		{
+			name:         "write-only unknown falls through to legacy",
+			passwordWO:   types.StringUnknown(),
+			planPW:       types.StringValue("legacy"),
+			planVersion:  types.Int64Null(),
+			stateVersion: types.Int64Null(),
+			wantPW:       "legacy",
+			wantRotate:   true,
+			wantErr:      "",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotPW, gotRotate, gotErr := resolveUpdatePassword(tt.passwordWO, tt.planPW, tt.planVersion, tt.stateVersion)
+			if gotPW != tt.wantPW || gotRotate != tt.wantRotate || gotErr != tt.wantErr {
+				t.Errorf("resolveUpdatePassword() = (%q, %v, %q), want (%q, %v, %q)",
+					gotPW, gotRotate, gotErr, tt.wantPW, tt.wantRotate, tt.wantErr)
+			}
+		})
+	}
+}