Upgrade IAM authentication API: Batch role operations and standardized role paths (#76)

* Fix IAM service proto field numbering and validation

Corrects field numbering in user service requests (roles field 4→2),
adds missing required validation to name fields, and updates
documentation for consistency with plural role operations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update IAM resource protos for role path format changes

Updates APIUser and User resource definitions to use new role path
format (groups/{id}/roles/{role_id}), adds required validation to
roles fields, and enhances validation to support variable-length
role IDs (7-8 digits). Also fixes protobuf syntax by removing
trailing commas from buf.validate options.

Breaking: User.roles field number changed from 6 to 5.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix APIUser documentation capitalization

Updates "api user" to "API user" in the roles field documentation
for consistent capitalization throughout the file.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix API user documentation capitalization consistency

Standardizes capitalization across api_user.proto documentation:
- "api user" → "API user" (3 instances)
- "api key" → "API user" (display_name field - corrects incorrect reference)
- "api keys" → "API keys" (2 instances in enum comments)

No field numbers or validation logic modified.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix sequential field numbering in api_user.proto

Corrects field numbers to be sequential (1-6) removing gaps:
- display_name: 4 → 3
- state: 5 → 4
- roles: 6 → 5
- api_key: 7 → 6

user.proto already has correct sequential numbering (1-4).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix field numbering

* allow empty role slice on user and api user

* remove unused class file

* Update Python SDK for new role format and batch operations

Update role utilities to use 4-part format (groups/{id}/roles/{role}),
update service interfaces for batch role assignment/revocation, and update
all tests and validation. All 38 IAM tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add role path utility functions and tests to TypeScript SDK

Implements utility functions for the new role path format (groups/{ULIDv2}/roles/{role_id}):
- createRolePath: constructs valid role paths with ULID and role ID validation
- isValidRolePath: validates role path format including Crockford base32 alphabet
- extractRoleIdFromPath: extracts role ID from valid paths
- extractGroupFromRolePath: extracts group resource name from paths

Includes comprehensive test suite with 39 tests covering:
- Valid 7 and 8 digit role IDs
- ULID validation (Crockford base32, excludes I, L, O, U)
- Old format rejection
- Edge cases and boundary conditions

All 362 tests passing. TypeScript build and lint successful.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update Go SDK for role path format and batch operations

- Add /roles/ segment to role paths (groups/{id}/roles/{role_id})
- Change singular to plural operations (AssignRole→AssignRoles, RevokeRole→RevokeRoles)
- Update field from Role string to Roles []string for batch operations
- Add comprehensive RevokeRoles validation test suites
- Update all test cases to new role path format (47-48 chars, pattern [1-9][0-9]{6,7})
- Regenerate protobuf files with updated message types and field numbering

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update documentation for batch role operations

Remove old singular role assignment/revocation documentation and add new
batch operations documentation for both API users and regular users.

Changes:
- Remove assign-role-to-a-p-i-user and revoke-role-from-a-p-i-user docs
- Remove assign-role-to-user documentation
- Add assign-roles-to-a-p-i-user and revoke-roles-from-a-p-i-user docs
- Add assign-roles-to-user and revoke-roles-from-user docs
- Update API user service index with new method names

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: BRBussy

docs/docs/api-reference/iam/api_user/v1/index.mdx

@@ -72,11 +72,11 @@ Deactivates an API user, disabling API key authentication. Use this to temporari
 
 ### Role Management
 
-#### [AssignRoleToAPIUser](/docs/api-reference/iam/api_user/v1/service/assign-role-to-a-p-i-user)
-Assigns a role to an existing API user within the authenticated group context. The role assignment enables the API user to perform operations according to the permissions associated with that role. Use this to grant new capabilities to an API user.
+#### [AssignRolesToAPIUser](/docs/api-reference/iam/api_user/v1/service/assign-roles-to-a-p-i-user)
+Assigns roles to an existing API user within the authenticated group context. The role assignments enable the API user to perform operations according to the permissions associated with those roles. Use this to grant new capabilities to an API user.
 
-#### [RevokeRoleFromAPIUser](/docs/api-reference/iam/api_user/v1/service/revoke-role-from-a-p-i-user)
-Revokes a role from an existing API user within the authenticated group context. The role revocation removes the permissions associated with that role from the API user. Use this to restrict API user capabilities or implement principle of least privilege.
+#### [RevokeRolesFromAPIUser](/docs/api-reference/iam/api_user/v1/service/revoke-roles-from-a-p-i-user)
+Revokes roles from an existing API user within the authenticated group context. The role revocations remove the permissions associated with those roles from the API user. Use this to restrict API user capabilities or implement principle of least privilege.
 
 ## Authentication & Authorization
 

docs/docs/api-reference/iam/api_user/v1/service/assign-role-to-a-p-i-user/example.go

@@ -0,0 +1,35 @@
+package main
+
+import (
+	"context"
+	"log"
+
+	api_userv1 "github.com/meshtrade/api/go/iam/api_user/v1"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
+	// environment variable or default discovery methods. Zero config required
+	// unless you want custom configuration.
+	service, err := api_userv1.NewApiUserService()
+	if err != nil {
+		log.Fatalf("Failed to create service: %v", err)
+	}
+	defer service.Close()
+
+	// Create request with service-specific parameters
+	request := &api_userv1.AssignRolesToAPIUserRequest{
+		// FIXME: Populate service-specific request fields
+	}
+
+	// Call the AssignRolesToAPIUser method
+	apiUser, err := service.AssignRolesToAPIUser(ctx, request)
+	if err != nil {
+		log.Fatalf("AssignRolesToAPIUser failed: %v", err)
+	}
+
+	// FIXME: Add relevant response object usage
+	log.Printf("AssignRolesToAPIUser successful: %+v", apiUser)
+}

docs/docs/api-reference/iam/api_user/v1/service/assign-role-to-a-p-i-user/example.java

@@ -0,0 +1,28 @@
+import co.meshtrade.api.iam.api_user.v1.ApiUserService;
+import co.meshtrade.api.iam.api_user.v1.Service.AssignRolesToAPIUserRequest;
+import co.meshtrade.api.iam.api_user.v1.ApiUser.APIUser;
+
+import java.util.Optional;
+
+public class AssignRolesToAPIUserExample {
+    public static void main(String[] args) {
+        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
+        // environment variable or default discovery methods. Zero config required
+        // unless you want custom configuration.
+        try (ApiUserService service = new ApiUserService()) {
+            // Create request with service-specific parameters
+            AssignRolesToAPIUserRequest request = AssignRolesToAPIUserRequest.newBuilder()
+                // FIXME: Populate service-specific request fields
+                .build();
+
+            // Call the AssignRolesToAPIUser method
+            APIUser apiUser = service.assignRolesToAPIUser(request, Optional.empty());
+
+            // FIXME: Add relevant response object usage
+            System.out.println("AssignRolesToAPIUser successful: " + apiUser);
+        } catch (Exception e) {
+            System.err.println("AssignRolesToAPIUser failed: " + e.getMessage());
+            e.printStackTrace();
+        }
+    }
+}

docs/docs/api-reference/iam/api_user/v1/service/assign-role-to-a-p-i-user/example.py

@@ -0,0 +1,27 @@
+from meshtrade.iam.api_user.v1 import (
+    ApiUserService,
+    AssignRolesToAPIUserRequest,
+)
+
+
+def main():
+    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
+    # environment variable or default discovery methods. Zero config required
+    # unless you want custom configuration.
+    service = ApiUserService()
+
+    with service:
+        # Create request with service-specific parameters
+        request = AssignRolesToAPIUserRequest(
+            # FIXME: Populate service-specific request fields
+        )
+
+        # Call the AssignRolesToAPIUser method
+        api_user = service.assign_roles_to_a_p_i_user(request)
+
+        # FIXME: Add relevant response object usage
+        print("AssignRolesToAPIUser successful:", api_user)
+
+
+if __name__ == "__main__":
+    main()

docs/docs/api-reference/iam/api_user/v1/service/assign-roles-to-a-p-i-user/example.go

@@ -0,0 +1,59 @@
+# AssignRolesToAPIUser
+{/*
+Generated by protoc-gen-meshdoc. DO NOT EDIT.
+source: meshtrade/iam/api_user/v1/service.proto
+*/}
+
+import CodeBlock from '@theme/CodeBlock';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import GoExample from '!!raw-loader!./example.go';
+import PythonExample from '!!raw-loader!./example.py';
+import JavaExample from '!!raw-loader!./example.java';
+import Proto from '!!raw-loader!../../../../../../../../proto/meshtrade/iam/api_user/v1/service.proto';
+
+
+
+## Method Details
+
+**Description:** Assign roles to an existing api user within the authenticated group context.
+
+The role assignment enables the api user to perform operations according
+to the permissions associated with that role within the group hierarchy.
+
+**Required Roles:** Check proto file for roles
+
+**Parameters:**
+- `Name` (string) (required): Name of the API user to assign roles to in the format api_users/\{ULIDv2\}.
+- `Roles` (string): Roles to assign to the API user in the format groups/\{ULIDv2\}/roles/\{role_id\}.
+The role_id corresponds to a value from the meshtrade.iam.role.v1.Role enum.
+
+**Returns:** APIUser
+
+**Method Type:** Unknown
+
+## Code Examples
+
+<Tabs>
+<TabItem value="go" label="Go">
+<CodeBlock language="go">{GoExample}</CodeBlock>
+</TabItem>
+<TabItem value="python" label="Python">
+<CodeBlock language="python">{PythonExample}</CodeBlock>
+</TabItem>
+<TabItem value="java" label="Java">
+<CodeBlock language="java">{JavaExample}</CodeBlock>
+</TabItem>
+<TabItem value="protobuf" label="Protobuf">
+<CodeBlock language="protobuf">{Proto}</CodeBlock>
+</TabItem>
+</Tabs>
+
+## Advanced Configuration
+
+For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the [SDK Configuration Guide](/docs/architecture/sdk-configuration).
+
+## Other Methods
+
+- **[Iam Api User v1 Method List](/docs/api-reference/iam/api_user/v1/service)** - For Other methods