feat: add admin user detail and tenant stats endpoints

[leifj]

Admin User Detail

Adds admin API endpoints for user management:

• GET /admin/tenants/:id/users/:user_id/detail — returns user info including passkeys, DID, and wallet type (non-PII fields only)
• GET /admin/tenants/:id/stats — tenant statistics (stub, returns 501)

Files

• internal/api/admin_user_handlers.go — handlers
• internal/api/admin_user_handlers_test.go — tests

---

Extracted from #221 (WIA service PR) to keep PRs focused.

[Copilot]

Pull request overview

Adds new admin API endpoints to retrieve tenant-scoped user details (including passkeys and DID) and to expose a tenant stats endpoint placeholder.

Changes:

• Add GET /admin/tenants/:id/users/:user_id/detail handler returning a non-PII user detail response with passkey summaries.
• Add GET /admin/tenants/:id/stats stub returning 501 with a TODO note.
• Register the new routes and add initial unit tests for success/not-member and 501 behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
internal/api/admin_user_handlers.go	Implements the new admin handlers for user detail and tenant stats.
internal/api/admin_user_handlers_test.go	Adds basic tests for the new handlers.
internal/api/admin_handlers.go	Registers the new admin routes under /admin/tenants.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 48.27586% with 30 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/api/admin_user_handlers.go	48.14%	25 Missing and 3 partials ⚠️
internal/storage/mongodb/mongodb.go	0.00%	1 Missing ⚠️
internal/storage/mongodb/tenant.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (7)

internal/api/admin_user_handlers.go:65

• Capitalize the internal error/log strings to match the established API error-message style ("Failed to …").

		h.logger.Error("failed to check tenant membership", zap.Error(err))
		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to check membership"})
		return

internal/api/admin_user_handlers.go:80

• Capitalize the internal error/log strings to match the established API error-message style ("Failed to …").

		h.logger.Error("failed to get user", zap.Error(err))
		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get user"})
		return

sonar-project.properties:19

• internal/api/admin_user_handlers.go is excluded from Sonar coverage, but this PR adds unit tests for it. Keeping it excluded will hide coverage regressions for this new handler code; it doesn’t match the existing comment that exclusions are for wiring/config that isn’t unit-testable.

internal/engine/oid4vp.go,\
internal/api/admin_user_handlers.go

internal/api/admin_user_handlers.go:56

• Error response strings/log messages here use lowercase (e.g. "tenant not found" / "failed to get tenant"), while the rest of the API consistently uses capitalized messages ("Tenant not found", "Failed to …"). This inconsistency makes error handling and log scanning noisier.

This issue also appears in the following locations of the same file:

• line 63
• line 78

			c.JSON(http.StatusNotFound, gin.H{"error": "tenant not found"})
			return
		}
		h.logger.Error("failed to get tenant", zap.Error(err))
		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get tenant"})

internal/api/admin_user_handlers.go:75

• Capitalize the not-found error string for consistency with other endpoints (most return "User not found" / "Tenant not found").

			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})

internal/api/admin_user_handlers_test.go:72

• domain.WalletType appears to be a constrained enum (currently db or client). Using an ad-hoc string like "web" in the test makes it easier for tests to drift from the actual allowed values.

		WalletType: "web",

docs/openapi-admin.yaml:830

• The OpenAPI spec defines passkeys.items as an untyped object with no properties, but the endpoint returns a stable structured shape (id, credential_id, tenant_id, etc.). This makes generated clients/documentation much less useful.

                  passkeys:
                    type: array
                    items:
                      type: object

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (5)

internal/api/admin_user_handlers.go:79

• Same as above: standardize these user error messages to the capitalized form used elsewhere ("User not found" / "Failed to get user") for consistency across the API.

			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
			return
		}
		h.logger.Error("failed to get user", zap.Error(err))
		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get user"})

internal/api/admin_user_handlers_test.go:105

• Extend the success assertions to verify wallet_type is returned and that only tenant-matching passkeys are included with correctly encoded credential_id and sign_count.

	if resp.DID != user.DID {
		t.Errorf("expected DID %s, got %s", user.DID, resp.DID)
	}

docs/openapi-admin.yaml:972

• The OpenAPI spec declares passkeys.items as a bare type: object with no properties, which doesn't describe the actual response shape returned by GetUserDetail (credential_id, tenant_id, prf_capable, sign_count, etc.). This makes the contract incomplete for clients.

                  passkeys:
                    type: array
                    items:
                      type: object
                  created_at:

internal/api/admin_user_handlers_test.go:73

• The success test doesn't exercise the newly added passkey mapping/filtering, and it uses a wallet type value ("web") that isn't one of the domain constants. Add a couple of WebAuthn credentials (one matching the tenant, one not) and use domain.WalletTypeClient/domain.WalletTypeDB to better reflect realistic data and cover the response mapping.

This issue also appears on line 103 of the same file.

	user := &domain.User{
		UUID:       domain.NewUserID(),
		DID:        "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
		WalletType: "web",
	}

internal/api/admin_user_handlers.go:56

• Error response strings here use lowercase ("tenant not found" / "failed to get tenant"), but other handlers in this codebase commonly use capitalized messages (e.g., "Tenant not found", "Failed to get tenant"). Aligning these messages keeps the admin API consistent.

This issue also appears on line 75 of the same file.

			c.JSON(http.StatusNotFound, gin.H{"error": "tenant not found"})
			return
		}
		h.logger.Error("failed to get tenant", zap.Error(err))
		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get tenant"})

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (4)

internal/api/admin_user_handlers_test.go:104

• The success test currently only asserts UUID/DID. Since the handler now returns wallet_type and transforms/filter passkeys, add assertions to verify wallet_type and that only the tenant-scoped passkey is returned with correctly encoded credential_id and selected fields.

	if resp.UUID != user.UUID.String() {
		t.Errorf("expected UUID %s, got %s", user.UUID.String(), resp.UUID)
	}
	if resp.DID != user.DID {
		t.Errorf("expected DID %s, got %s", user.DID, resp.DID)

internal/api/admin_user_handlers_test.go:73

• In the success test, WalletType is set to the literal "web", but the domain model defines wallet types as the WalletTypeDB/WalletTypeClient constants. Using an unsupported value makes the test less representative and can hide regressions if validation is added later. It would also help to include WebAuthn credentials so the handler’s passkey filtering/encoding logic is exercised.

This issue also appears on line 100 of the same file.

	// Create user
	user := &domain.User{
		UUID:       domain.NewUserID(),
		DID:        "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
		WalletType: "web",
	}

docs/openapi-admin.yaml:971

• The OpenAPI schema for the 200 response's passkeys array uses items: { type: object } without documenting the actual fields returned by the endpoint. This makes the contract ambiguous for API consumers; it should describe the PasskeyInfo properties (credential_id encoding, sign_count, etc.).

                  passkeys:
                    type: array
                    items:
                      type: object

internal/api/admin_handlers.go:1091

• The PR description lists only the new handler + test files, but this change set also updates route registration/tests, OpenAPI docs, and adds CodeQL suppressions in MongoDB stores. Please update the PR description (or split commits) so reviewers can quickly see all touched areas.

		// User detail
		tenants.GET("/:id/users/:user_id/detail", h.GetUserDetail)

		// Tenant statistics
		tenants.GET("/:id/stats", h.GetTenantStats)

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (4)

internal/api/admin_user_handlers_test.go:104

• The success test only asserts UUID and DID; it doesn’t verify wallet_type is returned or that only tenant-scoped passkeys are included/encoded correctly.

	if resp.UUID != user.UUID.String() {
		t.Errorf("expected UUID %s, got %s", user.UUID.String(), resp.UUID)
	}
	if resp.DID != user.DID {
		t.Errorf("expected DID %s, got %s", user.DID, resp.DID)

internal/api/admin_user_handlers.go:126

• GetTenantStats currently returns 501 for any tenant ID, including nonexistent tenants. Most other tenant-scoped admin endpoints validate tenant existence and return 404, so keeping that behavior here avoids confusing clients and prevents a future behavior change when stats are implemented.

func (h *AdminHandlers) GetTenantStats(c *gin.Context) {
	c.JSON(http.StatusNotImplemented, gin.H{
		"error": "tenant statistics not yet implemented; requires dedicated counters",
	})
}

docs/openapi-admin.yaml:977

• The OpenAPI schema for the 200 response doesn’t describe the shape of the passkeys items, even though the handler returns a structured object (id, credential_id, transport, sign_count, etc.). This makes generated clients/docs inaccurate.

              schema:
                type: object
                properties:
                  uuid:
                    type: string

internal/api/admin_user_handlers_test.go:73

• The success test doesn’t set up any WebAuthn credentials, so it doesn’t exercise the passkey mapping and tenant filtering logic in GetUserDetail.

This issue also appears on line 100 of the same file.

	user := &domain.User{
		UUID:       domain.NewUserID(),
		DID:        "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
		WalletType: "web",
	}