Centrik.Subscriptions.Client 1.0.0

Centrik.Subscriptions.Client

ASP.NET Core client for securely consuming product entitlements issued by Centrik Subscriptions.

The package retrieves signed entitlement snapshots, validates their JWS signatures against the Subscriptions JWKS endpoint, caches verified snapshots, refreshes them in the background, and exposes product-aware feature checks to Centrik applications.

Install

<PackageReference Include="Centrik.Subscriptions.Client" Version="1.0.0" />

The client depends on Centrik.Billing.Contracts, which provides stable product and feature codes. Use an explicitly approved package version rather than a floating version in production.

Register the client

Register the client once during application startup:

using Centrik.Subscriptions.Client;

builder.Services.AddCentrikEntitlements(options =>
{
    options.BaseUrl = "https://subscription.centrik.co.tz";
    options.Issuer = "centrik-subscriptions";
    options.Audience = "centrik-apps";
    options.RefreshInterval = TimeSpan.FromMinutes(10);
    options.GraceOnOutage = TimeSpan.FromHours(24);
    options.JwksRefreshInterval = TimeSpan.FromHours(1);

    options.TenantIdResolver = provider =>
    {
        var context = provider.GetRequiredService<IHttpContextAccessor>().HttpContext;
        return Guid.TryParse(context?.User.FindFirst("Tenant")?.Value, out var tenantId)
            ? tenantId
            : Guid.Empty;
    };

    options.AccessTokenProvider = cancellationToken =>
        tokenProvider.GetAccessTokenAsync(cancellationToken);
});

Register IHttpContextAccessor when the tenant resolver reads the current request:

builder.Services.AddHttpContextAccessor();

The access-token provider should cache a client-credentials token until shortly before expiry. Do not acquire a new token for every feature check.

Check product and feature access

Inject IEntitlementService into application services, controllers, filters, or UI composition code:

using Centrik.Billing.Contracts;
using Centrik.Subscriptions.Client;

public sealed class ReportAccess(IEntitlementService entitlements)
{
    public Task<bool> CanUseAdvancedReportsAsync(CancellationToken cancellationToken) =>
        entitlements.IsEnabledForProductAsync(
            ProductCodes.Books,
            FeatureCodes.BooksAdvancedReporting,
            cancellationToken);
}

Use product-aware checks for application features. IsEnabledForProductAsync first proves that the snapshot contains the consuming product, preventing a similarly named feature from another product from granting access.

Available operations include:

• HasProductAsync(productCode) for product enrollment.
• IsEnabledForProductAsync(productCode, featureCode) for Boolean features.
• GetLimitAsync(featureCode) for numeric limits.
• GetSnapshotAsync() when the caller needs verified subscription metadata.

Server-side authorization remains mandatory. Hiding a menu item is useful feedback but is not an authorization boundary.

Required service authorization

Entitlement consumers call the Subscriptions API using the shared read-only machine scope:

subscriptions.entitlements.read

Books, Hotel, Rockvein, and Nebrix are entitlement consumers. Installing this client does not enable SubscriptionBillingHost and does not grant the books.billing.write scope. Only the central Books deployment may enable the billing host.

Validation and failure behavior

Snapshots are accepted only after validating the signature, issuer, audience, lifetime, tenant identity, and supported payload structure.

The client fails closed when:

• authentication or authorization returns 401 or 403;
• the tenant or entitlement resource returns 404 or 410;
• a signature, issuer, audience, lifetime, or payload check fails;
• no verified snapshot exists and the control plane cannot be reached;
• the last verified snapshot is older than the configured outage grace.

Transport failures and server 5xx responses may use the last verified snapshot only within GraceOnOutage. Authorization and validation failures never use outage grace.

Configuration guidance

• BaseUrl must be the absolute Centrik Subscriptions service URL.
• TenantIdResolver is required and must return the tenant represented by the authenticated request context.
• AccessTokenProvider should return a read-only service token; never store it in browser storage.
• Issuer and Audience must match the entitlement signing configuration.
• Keep UnsubscribedPolicy at Denied for production unless an explicitly controlled internal deployment requires another policy.
• Do not set an unlimited internal policy based only on caller input or an unverified tenant claim.

Cache invalidation

The package registers IEntitlementCacheInvalidator for explicit invalidation when an application receives a trusted entitlement-change signal:

cacheInvalidator.Invalidate(tenantId);

Invalidation causes the next access to retrieve and validate a fresh snapshot. Background refresh remains a fallback, not a substitute for security-sensitive invalidation.

Version compatibility

The package follows semantic versioning:

• Patch releases contain compatible fixes.
• Minor releases add backward-compatible options or behavior.
• Major releases may change public APIs, validation rules, or supported snapshot schemas.

Upgrade the client and contracts packages together when release notes specify a compatibility dependency. Test denial, suspension, expired snapshots, invalid signatures, token failures, and outage grace before advancing a production package version.

Security

This package contains no client credentials, access tokens, private signing keys, or webhook secrets. Supply credentials through the consuming application's secret-management environment.

Source

Source and release history: Centrik.Subscriptions