feat: self-service sign-up to tenant creation end-to-end flow (#2126)

* feat: defer identity creation to post-provisioning hook for async tenant registration

When a user self-registers and the tenant requires async schema provisioning,
the registration handler now stores the admin email and password hash in
tenant metadata instead of attempting to create the identity immediately
(which would fail because the tenant schema doesn't exist yet).

A new post-provisioning hook reads the stored credentials after schema
provisioning completes and creates the self-registered admin identity with
tenant-owner role, then clears the credentials from metadata.

This completes the end-to-end self-service sign-up flow:
1. User submits registration form
2. Tenant created with provisioning_pending status + credentials in metadata
3. Provisioning worker creates schemas, runs migrations, seeds reference data
4. Self-registered admin hook creates the admin identity
5. Platform admin hook provisions platform admin (existing behavior)
6. Tenant becomes active
7. User sees provisioning progress page, auto-redirects to login on completion

* fix: address review feedback - credential cleanup and metadata safety

- Make metadata conversion failure fatal in loopbackTenantCreator
  (prevents silent registration failure for async provisioning)
- Add ClearTenantMetadata to TenantCreator interface and clear
  credentials from tenant metadata after sync identity provisioning
- Make clearRegistrationMetadata failure fatal in post-provisioning
  hook (enforces minimal credential retention)
- Export metadata key constants from bootstrap package and add
  cross-package sync test against gateway constants
- Reuse existing tenant repo in wire_services.go
- Add nil tenant repo validation test
- Remove placeholder test with no coverage

* refactor: replace concrete tenant repo with TenantMetadataStore interface

Replace direct dependency on *tenantpersistence.Repository with a
TenantMetadataStore interface defined in the identity bootstrap package.
This fixes the cross-service domain import architecture violation
(identity -> tenant/adapters/persistence).

Add GetMetadata convenience method on tenant repository to satisfy
the new interface without exposing full domain objects.

* fix: async path respects email verification, harden metadata handling

- Store emailVerificationRequired in tenant metadata so the
  post-provisioning hook creates PENDING_VERIFICATION identities
  when email verification is enabled (fixes bypass on async path)
- Fail hook on partial/malformed registration metadata instead of
  silently succeeding (prevents orphaned tenants without admin)
- Remove raw email addresses from hook log messages (PII)
- Add MetaKeyRegistrationEmailVerifyRequired constant with sync test

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

cmd/meridian/gateway.go

@@ -17,8 +17,10 @@ import (
 	platformauth "github.com/meridianhub/meridian/shared/platform/auth"
 	"github.com/meridianhub/meridian/shared/platform/env"
 	platformgateway "github.com/meridianhub/meridian/shared/platform/gateway"
+	"github.com/meridianhub/meridian/shared/platform/tenant"
 
 	"google.golang.org/grpc"
+	"google.golang.org/protobuf/types/known/structpb"
 	"gorm.io/gorm"
 )
 
@@ -204,30 +206,47 @@ var errNilTenantResponse = fmt.Errorf("InitiateTenant returned nil tenant")
 // gateway.TenantCreator interface used by RegistrationHandler.
 type loopbackTenantCreator struct {
 	client     tenantv1.TenantServiceClient
+	tenantRepo *tenantpersistence.Repository
 	baseDomain string
 	logger     *slog.Logger
 }
 
-func (a *loopbackTenantCreator) CreateTenant(ctx context.Context, tenantID, slug, displayName string) (string, error) {
+func (a *loopbackTenantCreator) CreateTenant(ctx context.Context, tenantID, slug, displayName string, metadata map[string]interface{}) (*gateway.CreateTenantResult, error) {
 	subdomain := slug
 	if a.baseDomain != "" {
 		subdomain = slug + "." + a.baseDomain
 	}
 
-	resp, err := a.client.InitiateTenant(ctx, &tenantv1.InitiateTenantRequest{
+	req := &tenantv1.InitiateTenantRequest{
 		TenantId:        tenantID,
 		DisplayName:     displayName,
 		Slug:            slug,
 		Subdomain:       subdomain,
 		SettlementAsset: "USD",
-	})
+	}
+
+	// Pass registration metadata through to the tenant record.
+	// Metadata conversion must succeed - async provisioning relies on credentials
+	// being present in the tenant record for the post-provisioning hook.
+	if len(metadata) > 0 {
+		pbMeta, err := structpb.NewStruct(metadata)
+		if err != nil {
+			return nil, fmt.Errorf("failed to convert registration metadata: %w", err)
+		}
+		req.Metadata = pbMeta
+	}
+
+	resp, err := a.client.InitiateTenant(ctx, req)
 	if err != nil {
-		return "", err
+		return nil, err
 	}
 	if resp.Tenant == nil {
-		return "", errNilTenantResponse
+		return nil, errNilTenantResponse
 	}
-	return resp.Tenant.TenantId, nil
+	return &gateway.CreateTenantResult{
+		TenantID:            resp.Tenant.TenantId,
+		ProvisioningPending: resp.Tenant.Status == tenantv1.TenantStatus_TENANT_STATUS_PROVISIONING_PENDING,
+	}, nil
 }
 
 func (a *loopbackTenantCreator) DeleteTenant(ctx context.Context, tenantID string) error {
@@ -238,6 +257,17 @@ func (a *loopbackTenantCreator) DeleteTenant(ctx context.Context, tenantID strin
 	return err
 }
 
+func (a *loopbackTenantCreator) ClearTenantMetadata(ctx context.Context, tenantID string) error {
+	if a.tenantRepo == nil {
+		return nil
+	}
+	tid, err := tenant.NewTenantID(tenantID)
+	if err != nil {
+		return fmt.Errorf("invalid tenant ID: %w", err)
+	}
+	return a.tenantRepo.UpdateMetadata(ctx, tid, map[string]interface{}{})
+}
+
 // loopbackSlugChecker adapts the tenant persistence repository to the
 // gateway.SlugChecker interface used by RegistrationHandler.
 type loopbackSlugChecker struct {
@@ -291,8 +321,9 @@ func wireRegistration(identityDB, tenantDB *gorm.DB, rawConn *grpc.ClientConn, b
 	identityRepo := identitypersistence.NewRepository(identityDB)
 	tenantClient := tenantv1.NewTenantServiceClient(rawConn)
 
-	creator := &loopbackTenantCreator{client: tenantClient, baseDomain: baseDomain, logger: logger}
-	slugChecker := &loopbackSlugChecker{repo: tenantpersistence.NewRepository(tenantDB)}
+	tenantRepo := tenantpersistence.NewRepository(tenantDB)
+	creator := &loopbackTenantCreator{client: tenantClient, tenantRepo: tenantRepo, baseDomain: baseDomain, logger: logger}
+	slugChecker := &loopbackSlugChecker{repo: tenantRepo}
 
 	emailVerificationRequired := env.GetEnvAsBool("EMAIL_VERIFICATION_REQUIRED", false)
 

cmd/meridian/registration_wiring_test.go

@@ -58,7 +58,10 @@ func (s *stubTenantServiceClient) UpdateTenantStatus(_ context.Context, req *ten
 func TestLoopbackTenantCreator_CreateTenant(t *testing.T) {
 	stub := &stubTenantServiceClient{
 		initiateResp: &tenantv1.InitiateTenantResponse{
-			Tenant: &tenantv1.Tenant{TenantId: "acme_corp"},
+			Tenant: &tenantv1.Tenant{
+				TenantId: "acme_corp",
+				Status:   tenantv1.TenantStatus_TENANT_STATUS_PROVISIONING_PENDING,
+			},
 		},
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
@@ -69,10 +72,11 @@ func TestLoopbackTenantCreator_CreateTenant(t *testing.T) {
 		logger:     logger,
 	}
 
-	tenantID, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp")
+	result, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp", nil)
 
 	require.NoError(t, err)
-	assert.Equal(t, "acme_corp", tenantID)
+	assert.Equal(t, "acme_corp", result.TenantID)
+	assert.True(t, result.ProvisioningPending)
 	assert.True(t, stub.initiateCalled)
 	assert.Equal(t, "acme_corp", stub.initiateReq.TenantId)
 	assert.Equal(t, "Acme Corp", stub.initiateReq.DisplayName)
@@ -85,7 +89,10 @@ func TestLoopbackTenantCreator_CreateTenant(t *testing.T) {
 func TestLoopbackTenantCreator_CreateTenant_EmptyBaseDomain(t *testing.T) {
 	stub := &stubTenantServiceClient{
 		initiateResp: &tenantv1.InitiateTenantResponse{
-			Tenant: &tenantv1.Tenant{TenantId: "acme_corp"},
+			Tenant: &tenantv1.Tenant{
+				TenantId: "acme_corp",
+				Status:   tenantv1.TenantStatus_TENANT_STATUS_ACTIVE,
+			},
 		},
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
@@ -96,9 +103,10 @@ func TestLoopbackTenantCreator_CreateTenant_EmptyBaseDomain(t *testing.T) {
 		logger:     logger,
 	}
 
-	_, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp")
+	result, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp", nil)
 
 	require.NoError(t, err)
+	assert.False(t, result.ProvisioningPending)
 	assert.Equal(t, "acme-corp", stub.initiateReq.Subdomain,
 		"when baseDomain is empty, subdomain should be just the slug")
 }
@@ -111,12 +119,37 @@ func TestLoopbackTenantCreator_CreateTenant_NilTenantInResponse(t *testing.T) {
 
 	creator := &loopbackTenantCreator{client: stub, logger: logger}
 
-	_, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp")
+	_, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp", nil)
 
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "nil tenant")
 }
 
+func TestLoopbackTenantCreator_CreateTenant_PassesMetadata(t *testing.T) {
+	stub := &stubTenantServiceClient{
+		initiateResp: &tenantv1.InitiateTenantResponse{
+			Tenant: &tenantv1.Tenant{
+				TenantId: "acme_corp",
+				Status:   tenantv1.TenantStatus_TENANT_STATUS_PROVISIONING_PENDING,
+			},
+		},
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+
+	creator := &loopbackTenantCreator{client: stub, baseDomain: "test.local", logger: logger}
+
+	metadata := map[string]interface{}{
+		"_registration_email":         "admin@acme.com",
+		"_registration_password_hash": "$2a$10$fakehash",
+	}
+	_, err := creator.CreateTenant(context.Background(), "acme_corp", "acme-corp", "Acme Corp", metadata)
+
+	require.NoError(t, err)
+	require.NotNil(t, stub.initiateReq.Metadata)
+	assert.Equal(t, "admin@acme.com", stub.initiateReq.Metadata.Fields["_registration_email"].GetStringValue())
+	assert.Equal(t, "$2a$10$fakehash", stub.initiateReq.Metadata.Fields["_registration_password_hash"].GetStringValue())
+}
+
 func TestLoopbackTenantCreator_DeleteTenant(t *testing.T) {
 	stub := &stubTenantServiceClient{
 		updateStatusResp: &tenantv1.UpdateTenantStatusResponse{},

cmd/meridian/wire_services.go

@@ -243,6 +243,16 @@ func startProvisioningWorker(ctx context.Context, prov *tenantprovisioner.Postgr
 	valuationSeeder := refvaluation.NewSeeder(refDataPool)
 	w.RegisterPostProvisioningHook("valuation-defaults", valuationSeeder.AsPostProvisioningHook())
 
+	// Self-registered admin: creates the admin identity from registration metadata
+	// stored by the registration handler. Must run after all reference data hooks
+	// so the identity schema has instruments, account types, etc. available.
+	selfRegHook, hookErr := identitybootstrap.NewSelfRegisteredAdminHook(identityRepo, repo, logger)
+	if hookErr != nil {
+		_ = prov.Close()
+		return nil, nil, fmt.Errorf("self-registered admin hook: %w", hookErr)
+	}
+	w.RegisterPostProvisioningHook("self-registered-admin", selfRegHook.AsPostProvisioningHook())
+
 	go w.Start(ctx)
 	logger.Info("provisioning worker started")
 

services/api-gateway/registration_handler.go

@@ -37,14 +37,27 @@ var (
 	errEmailAlreadyRegistered   = errors.New("email already registered in this tenant")
 )
 
+// CreateTenantResult holds the outcome of a tenant creation request.
+type CreateTenantResult struct {
+	TenantID string
+	// ProvisioningPending is true when the tenant requires async schema provisioning
+	// before it becomes active. When true, identity creation must be deferred to
+	// a post-provisioning hook and credentials stored in tenant metadata.
+	ProvisioningPending bool
+}
+
 // TenantCreator abstracts tenant creation for the registration handler.
 type TenantCreator interface {
 	// CreateTenant creates a new tenant with the given ID, slug, and display name.
-	// Returns the tenant ID on success.
-	CreateTenant(ctx context.Context, tenantID, slug, displayName string) (string, error)
+	// The metadata map is stored on the tenant record (used for registration credentials
+	// when provisioning is async).
+	CreateTenant(ctx context.Context, tenantID, slug, displayName string, metadata map[string]interface{}) (*CreateTenantResult, error)
 	// DeleteTenant removes a tenant. Used as compensation when identity provisioning
 	// fails after tenant creation, preventing orphaned tenants.
 	DeleteTenant(ctx context.Context, tenantID string) error
+	// ClearTenantMetadata removes all metadata from a tenant record.
+	// Used to clean up registration credentials after sync identity provisioning.
+	ClearTenantMetadata(ctx context.Context, tenantID string) error
 }
 
 // SlugChecker abstracts slug availability checks for the registration handler.
@@ -119,6 +132,7 @@ type registrationResponse struct {
 	TenantID             string `json:"tenant_id"`
 	LoginURL             string `json:"login_url"`
 	VerificationRequired bool   `json:"verification_required"`
+	ProvisioningPending  bool   `json:"provisioning_pending"`
 }
 
 // HandleRegister handles POST /api/v1/register.
@@ -155,9 +169,10 @@ func (h *RegistrationHandler) HandleRegister(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
-	h.logger.InfoContext(ctx, "registration: tenant and admin identity created",
+	h.logger.InfoContext(ctx, "registration: tenant created",
 		"tenant_id", resp.TenantID,
 		"slug", req.Slug,
+		"provisioning_pending", resp.ProvisioningPending,
 		"client_ip", clientIP)
 
 	writeJSON(w, http.StatusCreated, resp)
@@ -185,7 +200,20 @@ func (h *RegistrationHandler) parseAndValidateRequest(r *http.Request) (*registr
 	return &req, nil
 }
 
+// Metadata keys used to store self-registered admin credentials on the tenant record.
+// These are read by the self-registered admin post-provisioning hook and cleared after
+// the identity is created, so they never persist beyond tenant activation.
+const (
+	MetaKeyRegistrationEmail               = "_registration_email"
+	MetaKeyRegistrationPasswordHash        = "_registration_password_hash"
+	MetaKeyRegistrationEmailVerifyRequired = "_registration_email_verify_required"
+)
+
 // executeRegistration performs tenant creation and identity provisioning.
+// When the tenant requires async provisioning, admin credentials are stored in tenant
+// metadata and identity creation is deferred to a post-provisioning hook.
+// When provisioning is synchronous (tenant immediately active), the identity is
+// created inline as before.
 // Returns (httpStatus, response, error). On success error is nil.
 func (h *RegistrationHandler) executeRegistration(ctx context.Context, req *registrationRequest) (int, *registrationResponse, error) {
 	tenantID := strings.ReplaceAll(req.Slug, "-", "_")
@@ -194,7 +222,22 @@ func (h *RegistrationHandler) executeRegistration(ctx context.Context, req *regi
 		displayName = req.Slug
 	}
 
-	createdTenantID, err := h.tenantCreator.CreateTenant(ctx, tenantID, req.Slug, displayName)
+	// Hash password early so we can store it in metadata for async provisioning.
+	passwordHash, err := credentials.HashPassword(req.Password)
+	if err != nil {
+		h.logger.ErrorContext(ctx, "registration: failed to hash password", "error", err)
+		return http.StatusInternalServerError, nil, errIdentityCreationFailed
+	}
+
+	// Include registration credentials in tenant metadata so the post-provisioning
+	// hook can create the admin identity after schema provisioning completes.
+	metadata := map[string]interface{}{
+		MetaKeyRegistrationEmail:               req.Email,
+		MetaKeyRegistrationPasswordHash:        passwordHash,
+		MetaKeyRegistrationEmailVerifyRequired: h.emailVerificationRequired,
+	}
+
+	result, err := h.tenantCreator.CreateTenant(ctx, tenantID, req.Slug, displayName, metadata)
 	if err != nil {
 		if isAlreadyExistsError(err) {
 			return http.StatusConflict, nil, errSlugTaken
@@ -204,14 +247,28 @@ func (h *RegistrationHandler) executeRegistration(ctx context.Context, req *regi
 		return http.StatusInternalServerError, nil, errTenantCreationFailed
 	}
 
-	regErr := h.provisionAdminIdentity(ctx, createdTenantID, req.Email, req.Password)
-	if regErr != nil {
-		// Compensate: delete orphaned tenant to allow the user to retry.
-		if delErr := h.tenantCreator.DeleteTenant(ctx, createdTenantID); delErr != nil {
-			h.logger.ErrorContext(ctx, "registration: failed to compensate (delete tenant)",
-				"tenant_id", createdTenantID, "error", delErr)
+	if result.ProvisioningPending {
+		// Tenant requires async provisioning - identity will be created by the
+		// self-registered admin post-provisioning hook after schemas are ready.
+		h.logger.InfoContext(ctx, "registration: tenant created with async provisioning, identity deferred to post-provisioning hook",
+			"tenant_id", result.TenantID,
+			"slug", req.Slug)
+	} else {
+		// Tenant is immediately active - create identity inline.
+		regErr := h.provisionAdminIdentity(ctx, result.TenantID, req.Email, passwordHash)
+		if regErr != nil {
+			// Compensate: delete orphaned tenant to allow the user to retry.
+			if delErr := h.tenantCreator.DeleteTenant(ctx, result.TenantID); delErr != nil {
+				h.logger.ErrorContext(ctx, "registration: failed to compensate (delete tenant)",
+					"tenant_id", result.TenantID, "error", delErr)
+			}
+			return regErr.status, nil, regErr
+		}
+		// Clear registration credentials from tenant metadata (best-effort).
+		if clearErr := h.tenantCreator.ClearTenantMetadata(ctx, result.TenantID); clearErr != nil {
+			h.logger.WarnContext(ctx, "registration: failed to clear credentials from tenant metadata",
+				"tenant_id", result.TenantID, "error", clearErr)
 		}
-		return regErr.status, nil, regErr
 	}
 
 	loginURL := fmt.Sprintf("https://%s.%s/login", req.Slug, h.baseDomain)
@@ -220,9 +277,10 @@ func (h *RegistrationHandler) executeRegistration(ctx context.Context, req *regi
 	}
 
 	return http.StatusCreated, &registrationResponse{
-		TenantID:             createdTenantID,
+		TenantID:             result.TenantID,
 		LoginURL:             loginURL,
 		VerificationRequired: h.emailVerificationRequired,
+		ProvisioningPending:  result.ProvisioningPending,
 	}, nil
 }
 
@@ -240,7 +298,8 @@ func newRegistrationError(status int, inner error) *registrationError {
 }
 
 // provisionAdminIdentity creates the initial admin identity within the new tenant's scope.
-func (h *RegistrationHandler) provisionAdminIdentity(ctx context.Context, tenantIDStr, emailAddr, password string) *registrationError {
+// The passwordHash parameter is a pre-computed bcrypt hash.
+func (h *RegistrationHandler) provisionAdminIdentity(ctx context.Context, tenantIDStr, emailAddr, passwordHash string) *registrationError {
 	tid, err := tenant.NewTenantID(tenantIDStr)
 	if err != nil {
 		h.logger.ErrorContext(ctx, "registration: invalid tenant ID from creation",
@@ -250,7 +309,7 @@ func (h *RegistrationHandler) provisionAdminIdentity(ctx context.Context, tenant
 
 	tenantCtx := tenant.WithTenant(ctx, tid)
 
-	identity, regErr := h.buildAdminIdentity(ctx, tid, emailAddr, password)
+	identity, regErr := h.buildAdminIdentity(ctx, tid, emailAddr, passwordHash)
 	if regErr != nil {
 		return regErr
 	}
@@ -273,9 +332,9 @@ func (h *RegistrationHandler) provisionAdminIdentity(ctx context.Context, tenant
 	return nil
 }
 
-// buildAdminIdentity creates a new identity with the given credentials and activates it
-// if email verification is not required.
-func (h *RegistrationHandler) buildAdminIdentity(ctx context.Context, tid tenant.TenantID, emailAddr, password string) (*identitydomain.Identity, *registrationError) {
+// buildAdminIdentity creates a new identity with the given pre-computed password hash
+// and activates it if email verification is not required.
+func (h *RegistrationHandler) buildAdminIdentity(ctx context.Context, tid tenant.TenantID, emailAddr, passwordHash string) (*identitydomain.Identity, *registrationError) {
 	var identity *identitydomain.Identity
 	var err error
 	if h.emailVerificationRequired {
@@ -287,13 +346,7 @@ func (h *RegistrationHandler) buildAdminIdentity(ctx context.Context, tid tenant
 		return nil, newRegistrationError(http.StatusBadRequest, fmt.Errorf("%w: %w", errIdentityCreationFailed, err))
 	}
 
-	hash, err := credentials.HashPassword(password)
-	if err != nil {
-		h.logger.ErrorContext(ctx, "registration: failed to hash password", "error", err)
-		return nil, newRegistrationError(http.StatusInternalServerError, errIdentityCreationFailed)
-	}
-
-	if err := identity.SetPassword(hash); err != nil {
+	if err := identity.SetPassword(passwordHash); err != nil {
 		h.logger.ErrorContext(ctx, "registration: failed to set password", "error", err)
 		return nil, newRegistrationError(http.StatusInternalServerError, errIdentityCreationFailed)
 	}