feat: Simplify User Onboarding by Auto-Generating Hedera Account, DID, and Keys via API #5795

[gayanath8]

Issue Labels

#5795

Requirements

• Add new optional parameters to the existing user registration/onboarding API endpoint that allow the system to auto-generate a Hedera Account, DID, and cryptographic keys on behalf of the user.
• If the caller does not provide a Hedera account, DID, or keys, Guardian should generate them automatically during onboarding (similar to the current internal Guardian flow, but exposed as a single API call).
• If the caller provides their own Hedera account, DID, or keys, Guardian should accept and use those values instead.
• The auto-generated values (Hedera Account ID, DID, keys) must be included in the API response payload.
• All generated values must be securely stored in the system vault.
• The existing API fields must remain backward-compatible to support user-created Hedera accounts.
• A single API call should be sufficient to fully onboard a user, replacing the current multi-step process.
• Hedera Account Reuse Restriction – When specifying an existing Hedera account in the API (Simplified Task), ensure that the account has not already been used for a prior user registration. The system will return an error if reused, as each user requires a unique DID key derived from the Hedera account’s private key.

Summary of Changes

• POST /accounts/push/onboard — new async endpoint that accepts optional Hedera account, DID, and key fields; auto-generates any omitted values using the operator account. Returns a taskId immediately for polling.
• GET /tasks/onboard/{taskId} — new unauthenticated endpoint that returns onboarding task progress (sanitized — no credentials exposed). Only serves onboarding tasks; returns 401 for any other task type.
• OnboardingDTO — new DTO extending RegisterUserDTO with optional fields: hederaAccountId, hederaAccountKey, parent, vcDocument, didDocument, didKeys, useFireblocksSigning, fireblocksConfig. Includes format validation for Hedera account ID and key.
• TaskAction.ONBOARD_USER / MessageAPI.ONBOARD_USER_ASYNC — new enum values in interfaces for the async task pipeline.
• guardian-service — new ONBOARD_USER_ASYNC handler in profile.service.ts that runs the full onboarding flow: creates Hedera account (if needed), registers user, publishes DID/VC, stores keys in vault, and returns credentials in the task result.
• Task ownership transfer is assigned ,on completion, task ownership is automatically transferred to the newly created user, so only the new user can retrieve their sensitive credentials via the authenticated GET /tasks/{taskId} endpoint.
• New Docs added docs/guardian/users/user-operations/account-apis/unified-onboarding.md and updated docs/SUMMARY.md.

Validation Rules

• username — required, non-empty string
• password — required, non-empty string
• password_confirmation — required, must match password
• role — required, must be one of STANDARD_REGISTRY, USER
• hederaAccountId — optional string, unique
• hederaAccountKey — optional string
• parent — optional string
• didDocument, vcDocument, didKeys — optional, typed objects/arrays

Condition	Status
Missing or invalid Bearer token (non-demo mode)	401 Unauthorized
Caller is not STANDARD_REGISTRY (non-demo mode)	403 Forbidden
hederaAccountKey provided but hederaAccountId format invalid (\d+.\d+.\d+)	422 Unprocessable Entity
hederaAccountId provided but hederaAccountKey format invalid (DER / raw hex)	422 Unprocessable Entity
role = USER with no parent provided	400 Bad Request
parent username not found in system	400 Bad Request
parent exists but is not a STANDARD_REGISTRY	400 Bad Request
Username already taken	409 Conflict
Hedera account '0.0.8682772' is already associated with an existing registration	409 Conflict

1. SR — auto Hedera, auto DID, with VC

• 
• 
• 

2. SR — manual Hedera, auto DID, with VC

• 
• 
• 

3. Default User — auto Hedera, with parent registry

• 
• 
• 

Validations

• 
• 
• 
• 
• 
•