feat: add AWS-compatible standalone IAM service

Closes #1640

Add a standalone AWS IAM Query API implementation for managing IAM users through standard AWS SDKs and the AWS CLI.

Server usage

Start the IAM server with internal file-backed storage:

    mkdir -p /tmp/versitygw-iam
    ./versitygw --port 127.0.0.1:7070 --access user --secret pass iam --dir /tmp/versitygw-iam

Start the IAM server with Vault KV v2 storage using AppRole:

    VGW_IAM_VAULT_ROLE_SECRET=<role-secret> ./versitygw --port 127.0.0.1:7070 --access user --secret pass iam --vault-endpoint-url http://127.0.0.1:8200 --vault-auth-method approle --vault-role-id <role-id> --vault-mount-path kv --vault-secret-storage-path iam

Vault authentication also supports root tokens, separate authentication and secret-storage namespaces, custom mount paths, server certificate validation, and mutual TLS client certificates.

Configure the AWS CLI credentials used by the IAM server:

    export AWS_ACCESS_KEY_ID=user
    export AWS_SECRET_ACCESS_KEY=pass
    export AWS_DEFAULT_REGION=us-east-1

Implemented IAM actions

CreateUser creates an IAM user with an AWS-compatible ARN, generated AIDA user ID, creation timestamp, optional path, and tags. It validates usernames, paths, tag limits, reserved tag prefixes, duplicate tag keys, and existing users.

    aws --endpoint-url http://127.0.0.1:7070 iam create-user --user-name bob

    aws --endpoint-url http://127.0.0.1:7070 iam create-user --user-name bob --path /engineering/ --tags Key=team,Value=storage

GetUser returns a stored user or the root identity when requested without a username through the IAM Query API.

    aws --endpoint-url http://127.0.0.1:7070 iam get-user --user-name bob

ListUsers returns users in deterministic username order and supports path filtering, marker-based pagination, and MaxItems limits.

    aws --endpoint-url http://127.0.0.1:7070 iam list-users

    aws --endpoint-url http://127.0.0.1:7070 iam list-users --path-prefix /engineering/ --max-items 100

UpdateUser updates the username and/or path, recalculates the user ARN, and rejects conflicts with existing users.

    aws --endpoint-url http://127.0.0.1:7070 iam update-user --user-name bob --new-user-name robert --new-path /platform/

DeleteUser permanently removes an IAM user and returns AWS-compatible errors for missing users.

    aws --endpoint-url http://127.0.0.1:7070 iam delete-user --user-name robert

IAM protocol and authentication

- Support the AWS IAM Query protocol version 2010-05-08 over GET and POST form requests.
- Return AWS-compatible XML responses, error documents, status codes, request IDs, user metadata, and pagination fields.
- Authenticate root credentials with AWS Signature Version 4 for the IAM service in us-east-1.
- Support both Authorization-header and query-string SigV4 authentication.
- Validate credential scope, signed headers, timestamps, clock skew, content length, signatures, and unsupported signature or session-token modes.
- Add IAM-specific validation and error mapping for malformed requests, invalid actions, duplicate entities, missing users, throttling, and internal failures.

Storage implementations

- Add an internal JSON-backed store using iam.json and iam.json.backup with atomic temporary-file replacement, concurrent access protection, stable ordering, pagination, and persistence across restarts.
- Add a Vault KV v2 store with one secret per user, CAS-based duplicate protection, permanent deletion, AppRole reauthentication, namespace support, configurable authentication and KV mounts, root-token authentication, and TLS/mTLS configuration.
- Introduce a common Storer interface and require exactly one storage backend to be configured.

Server and embedding support

- Register the new `versitygw iam` command with environment-variable and CLI configuration for both storage backends.
- Add `embedgw.RunIAMAPI` and `IAMConfig` for embedding the IAM service in Go applications.

Gateway-level internal packages

- Add `internal/iamstore` as a reusable generic file-backed IAM persistence engine and migrate the existing gateway internal IAM service to it.
- Add `internal/sigv4auth` for shared SigV4 header and presigned-query parsing, canonical request generation, signature verification, and structured authentication errors.
- Refactor the S3 authentication paths to use the shared SigV4 implementation while preserving S3-specific error responses.
- Add `internal/httpctx` for shared Fiber context keys and AWS-style request ID handling.
- Add `internal/routekit` for shared query, form, and header route matchers.
- Add `internal/netutil` for reusable certificate storage, hostname-aware listeners, multi-address serving, TLS listeners, and UNIX socket handling.
- Update the custom SigV4 signer to honor an explicitly supplied signed-header list so unrelated headers do not alter IAM signatures.

Testing and CI

- Add AWS IAM SDK-based integration coverage for all supported user actions, header authentication, query authentication, validation, errors, filtering, and pagination.
- Split standalone IAM tests into `versitygw test iam` and retain existing gateway IAM tests under `versitygw test gw-iam`.
- Add unit coverage for controllers, authentication, routing, storage, embedding, listeners, request matching, persistence, and signing behavior.
- Add `runiamtests.sh` to exercise internal storage over HTTP and HTTPS plus Vault storage through AppRole.
- Add a dedicated IAM functional-test workflow with a Vault service and merged runtime coverage reporting.
- Include the IAM test runner in shellcheck and add the AWS IAM SDK dependency.

iamapi/internal/iamutil/request.go

@@ -0,0 +1,40 @@
+// Copyright 2026 Versity Software
+// This file is licensed under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package iamutil
+
+import (
+	"github.com/gofiber/fiber/v3"
+	"github.com/versity/versitygw/internal/httpctx"
+)
+
+// MatchQueryOrFormArgs matches AWS Query-style requests that contain all
+// provided parameters in either the URL query string or a form body.
+func MatchQueryOrFormArgs(args ...string) fiber.Handler {
+	return func(ctx fiber.Ctx) error {
+		if httpctx.ContextKeySkip.IsSet(ctx) {
+			return ctx.Next()
+		}
+
+		queryArgs := ctx.Request().URI().QueryArgs()
+		formArgs := ctx.Request().PostArgs()
+		for _, arg := range args {
+			if !queryArgs.Has(arg) && !formArgs.Has(arg) {
+				httpctx.ContextKeySkip.Set(ctx, true)
+				break
+			}
+		}
+
+		return ctx.Next()
+	}
+}

iamapi/internal/iamutil/request_test.go

@@ -0,0 +1,74 @@
+// Copyright 2026 Versity Software
+// This file is licensed under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package iamutil
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gofiber/fiber/v3"
+	"github.com/versity/versitygw/internal/httpctx"
+)
+
+func TestMatchQueryOrFormArgs(t *testing.T) {
+	tests := []struct {
+		name        string
+		method      string
+		target      string
+		body        string
+		contentType string
+		want        string
+	}{
+		{name: "query", method: http.MethodGet, target: "/any?Action=ListUsers", want: "matched"},
+		{name: "empty query value is present", method: http.MethodGet, target: "/any?Action=", want: "matched"},
+		{name: "form", method: http.MethodPost, target: "/any", body: "Action=ListUsers", contentType: fiber.MIMEApplicationForm, want: "matched"},
+		{name: "missing", method: http.MethodGet, target: "/any", want: "fallback"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			app := fiber.New()
+			app.Add([]string{http.MethodGet, http.MethodPost}, "/*",
+				MatchQueryOrFormArgs("Action"),
+				func(ctx fiber.Ctx) error {
+					if httpctx.ContextKeySkip.IsSet(ctx) {
+						httpctx.ContextKeySkip.Delete(ctx)
+						return ctx.Next()
+					}
+					return ctx.SendString("matched")
+				},
+			)
+			app.All("*", func(ctx fiber.Ctx) error { return ctx.SendString("fallback") })
+
+			req := httptest.NewRequest(tt.method, tt.target, bytes.NewBufferString(tt.body))
+			if tt.contentType != "" {
+				req.Header.Set("Content-Type", tt.contentType)
+			}
+			resp, err := app.Test(req)
+			if err != nil {
+				t.Fatalf("app.Test: %v", err)
+			}
+			body, err := io.ReadAll(resp.Body)
+			if err != nil {
+				t.Fatalf("read body: %v", err)
+			}
+			if string(body) != tt.want {
+				t.Fatalf("body = %q, want %q", string(body), tt.want)
+			}
+		})
+	}
+}

iamapi/internal/iamutil/user.go

@@ -0,0 +1,213 @@
+// Copyright 2026 Versity Software
+// This file is licensed under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package iamutil
+
+import (
+	"crypto/rand"
+	"fmt"
+	"math/big"
+	"regexp"
+	"strings"
+
+	"github.com/gofiber/fiber/v3"
+	"github.com/versity/versitygw/debuglogger"
+	"github.com/versity/versitygw/iamapi/iamerr"
+	"github.com/versity/versitygw/iamapi/types"
+)
+
+const (
+	DefaultAccountID = "000000000000"
+	DefaultUserPath  = "/"
+	DefaultMaxItems  = 100
+	MaxListItems     = 1000
+	MaxUserNameLen   = 64
+	MaxUserLookupLen = 128
+	MaxPathLen       = 512
+	userIDPrefix     = "AIDA"
+	userIDRandomLen  = 17
+	userIDAlphabet   = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+	maxTagKeyLen     = 128
+	maxTagValLen     = 256
+)
+
+var (
+	userNamePattern = regexp.MustCompile(`^[A-Za-z0-9+=,.@_-]+$`)
+	tagKeyPattern   = regexp.MustCompile(`^[\p{L}\p{Z}\p{N}_.:/=+\-@]+$`)
+	tagValPattern   = regexp.MustCompile(`^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$`)
+)
+
+// RequestParam looks up key first in URL query args, then in the POST body.
+func RequestParam(ctx fiber.Ctx, key string) (string, bool) {
+	queryArgs := ctx.Request().URI().QueryArgs()
+	if queryArgs.Has(key) {
+		return string(queryArgs.Peek(key)), true
+	}
+
+	postArgs := ctx.Request().PostArgs()
+	if postArgs.Has(key) {
+		return string(postArgs.Peek(key)), true
+	}
+
+	return "", false
+}
+
+// ParseTags reads IAM tag members from the request (up to 50), validates each, and returns the list.
+func ParseTags(ctx fiber.Ctx) ([]types.Tag, error) {
+	var tags []types.Tag
+	seen := map[string]struct{}{}
+
+	for i := 1; ; i++ {
+		keyName := fmt.Sprintf("Tags.member.%d.Key", i)
+		valueName := fmt.Sprintf("Tags.member.%d.Value", i)
+
+		key, hasKey := RequestParam(ctx, keyName)
+		value, hasValue := RequestParam(ctx, valueName)
+		if !hasKey && !hasValue {
+			break
+		}
+		if len(tags) >= 50 {
+			debuglogger.Logf("IAM user tag count exceeds maximum: max=%d", 50)
+			return nil, iamerr.GetAPIError(iamerr.ErrTooManyTags)
+		}
+		if !hasKey {
+			debuglogger.Logf("missing required IAM tag parameter: %s", keyName)
+			return nil, iamerr.MissingParameter(keyName)
+		}
+		if !hasValue {
+			debuglogger.Logf("missing required IAM tag parameter: %s", valueName)
+			return nil, iamerr.MissingParameter(valueName)
+		}
+		if err := validateTag(i, key, value); err != nil {
+			return nil, err
+		}
+
+		normalizedKey := strings.ToLower(key)
+		if _, ok := seen[normalizedKey]; ok {
+			debuglogger.Logf("duplicate IAM tag key: %q", key)
+			return nil, iamerr.GetAPIError(iamerr.ErrDuplicateTagKeys)
+		}
+		seen[normalizedKey] = struct{}{}
+
+		tags = append(tags, types.Tag{Key: key, Value: value})
+	}
+
+	return tags, nil
+}
+
+// ValidateUserName checks that userName is non-empty, matches the allowed character set, and fits within maxLength.
+func ValidateUserName(field, userName string, maxLength int) error {
+	if len(userName) > maxLength {
+		debuglogger.Logf("IAM user name exceeds maximum length: field=%s length=%d max=%d", field, len(userName), maxLength)
+		return iamerr.UserNameTooLong(field, maxLength)
+	}
+	if userName == "" || !userNamePattern.MatchString(userName) {
+		debuglogger.Logf("invalid IAM user name: field=%s value=%q", field, userName)
+		return iamerr.InvalidUserName(field)
+	}
+
+	return nil
+}
+
+// ValidatePath checks that path is a valid IAM path (must start and end with '/') within MaxPathLen.
+func ValidatePath(field, path string) error {
+	if len(path) > MaxPathLen {
+		debuglogger.Logf("IAM path exceeds maximum length: field=%s length=%d max=%d", field, len(path), MaxPathLen)
+		return iamerr.PathTooLong(field, MaxPathLen)
+	}
+	if !isValidIAMPath(path) {
+		debuglogger.Logf("invalid IAM path: field=%s value=%q", field, path)
+		return iamerr.InvalidPath(field)
+	}
+
+	return nil
+}
+
+// ValidatePathPrefix checks that pathPrefix is a non-empty printable ASCII string starting with '/'.
+func ValidatePathPrefix(pathPrefix string) error {
+	if pathPrefix == "" || len(pathPrefix) > MaxPathLen || pathPrefix[0] != '/' || !isPrintableASCII(pathPrefix[1:]) {
+		debuglogger.Logf("invalid IAM path prefix: %q", pathPrefix)
+		return iamerr.GetAPIError(iamerr.ErrInvalidPathPrefix)
+	}
+
+	return nil
+}
+
+// BuildUserArn constructs the ARN for an IAM user.
+func BuildUserArn(accountID, path, userName string) string {
+	return fmt.Sprintf("arn:aws:iam::%s:user%s%s", accountID, path, userName)
+}
+
+// GenerateUserID returns a new cryptographically random IAM user ID in the AIDA… format.
+func GenerateUserID() (string, error) {
+	var b strings.Builder
+	b.Grow(len(userIDPrefix) + userIDRandomLen)
+	b.WriteString(userIDPrefix)
+
+	max := big.NewInt(int64(len(userIDAlphabet)))
+	for range userIDRandomLen {
+		n, err := rand.Int(rand.Reader, max)
+		if err != nil {
+			debuglogger.Logf("failed to generate IAM user ID: %v", err)
+			return "", err
+		}
+		b.WriteByte(userIDAlphabet[n.Int64()])
+	}
+
+	return b.String(), nil
+}
+
+func validateTag(index int, key, value string) error {
+	if len(key) > maxTagKeyLen {
+		debuglogger.Logf("IAM tag key exceeds maximum length: index=%d length=%d max=%d", index, len(key), maxTagKeyLen)
+		return iamerr.TagKeyTooLong(index)
+	}
+	if key == "" || !tagKeyPattern.MatchString(key) {
+		debuglogger.Logf("invalid IAM tag key: index=%d value=%q", index, key)
+		return iamerr.InvalidTagKey(index)
+	}
+	if len(value) > maxTagValLen {
+		debuglogger.Logf("IAM tag value exceeds maximum length: index=%d length=%d max=%d", index, len(value), maxTagValLen)
+		return iamerr.TagValueTooLong(index)
+	}
+	if !tagValPattern.MatchString(value) {
+		debuglogger.Logf("invalid IAM tag value: index=%d value=%q", index, value)
+		return iamerr.InvalidTagValue(index)
+	}
+
+	return nil
+}
+
+func isValidIAMPath(path string) bool {
+	if path == "" || len(path) > MaxPathLen {
+		return false
+	}
+	if path == "/" {
+		return true
+	}
+	if path[0] != '/' || path[len(path)-1] != '/' {
+		return false
+	}
+
+	return isPrintableASCII(path[1 : len(path)-1])
+}
+
+func isPrintableASCII(value string) bool {
+	for i := 0; i < len(value); i++ {
+		if value[i] < 0x21 || value[i] > 0x7e {
+			return false
+		}
+	}
+	return true
+}