Hellmade.HubAuth.ServiceClients

Typed HTTP clients for downstream services that need Hub coarse-access checks and Hub-backed directory/profile reads.

Why this package exists

Services should not hand-roll raw HTTP calls to Hub for:

• permissions/check
• single-user directory lookups
• batch directory/profile lookups

This package provides one reusable client layer with shared contracts, caching, and fallback behavior.

What it includes

• IPermissionCheckClient
• IDirectoryClient
• AddHubAuthServiceClients(...)
• HubAuthServiceClientOptions

When to use it

Use this package when your service:

• needs to know whether a user may access the service at all
• needs Hub-owned profile data such as display name, avatar, position, or Hub account URL
• wants shared caching/resilience behavior instead of duplicating it locally

What it does not do

This package does not implement:

• service-local authorization rules
• service-local RBAC models
• local user/entity persistence
• browser auth/session management

Hub endpoints used

• GET /api/v1/permissions/check
• GET /api/v1/directory/users/{userId}
• POST /api/v1/directory/users/batch

Shared behavior

• short-lived in-memory caching
• stable cache keys for directory batch requests
• structured warnings when falling back to cached values
• optional service-authenticated fallback for directory reads when no user bearer token is available
• optional service-authenticated fallback for permission checks when user-token authorization is unavailable

Configuration

HubAuthServiceClientOptions supports:

• HubApiBaseUrl
• ServiceSharedSecret
• PermissionCacheSeconds (default 120)
• DirectoryCacheSeconds (default 600)
• MaxBatchSize (default 200)
• FailOpenWithCachedValue (default true)

Typical registration

services.AddHubAuthServiceClients(options =>
{
    options.HubApiBaseUrl = configuration["HUB__API_BASE_URL"] ?? string.Empty;
    options.ServiceSharedSecret = configuration["AUTH__HUB__SERVICE_SHARED_SECRET"];
    options.PermissionCacheSeconds = 120;
    options.DirectoryCacheSeconds = 600;
    options.FailOpenWithCachedValue = true;
});

How to use it

Coarse access check

var hasAccess = await permissionCheckClient.HasAccessAsync(
    serviceKey,
    externalUserId,
    bearerToken,
    cancellationToken);

This should run before service-local authorization rules.

Single profile lookup

var profile = await directoryClient.GetUserAsync(
    serviceKey,
    externalUserId,
    bearerToken,
    cancellationToken);

Batch profile lookup

var profiles = await directoryClient.GetUsersAsync(
    serviceKey,
    externalUserIds,
    bearerToken,
    cancellationToken);

Use the batch method for tables/lists to avoid N+1 fetches.

Directory fields

DirectoryUserProfileResponse includes Hub-owned display metadata such as:

• DisplayName
• Email
• ImageUrl
• ImageZoom
• ImageOffsetX
• ImageOffsetY
• FullName
• RawDisplayName
• Position
• AccountUrl

Services should treat these as Hub-owned values, not local source-of-truth fields.

Service-authenticated fallback

When ServiceSharedSecret is configured, the clients can use service-authenticated fallback headers:

• X-Service-Key: <serviceKey>
• X-Service-Secret: <service secret>

This is useful for anonymous/public service routes that still need Hub-owned profile data.

It also provides a fallback path for coarse permission checks when a user-token call to Hub returns 401 but the service is allowed to ask Hub directly using its shared service secret.

Common failure modes

• 403 on service entry
  • Hub says the user does not have service access
• empty or missing profile fields
  • service is not using directory endpoints, or Hub data is incomplete
• anonymous directory lookup fails
  • missing or wrong AUTH__HUB__SERVICE_SHARED_SECRET

Related docs

• package overview: ../../README.md
• contracts package: ../Hellmade.HubAuth.Contracts/README.md
• ASP.NET Core helpers: ../Hellmade.HubAuth.AspNetCore/README.md
• new service integration guide: ../../../Hub/docs/Auth/new-service-auth-integration.md