Interface IConnectionTokenKeyService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for managing connection token HMAC keys. The IpFetchServer registers its signing key via UpsertAsync(string, byte[], CancellationToken); game servers (Login/World/Scene) fetch all active keys via FetchAllActiveAsync(CancellationToken) to verify stateless connection tokens without environment variable coordination.

public interface IConnectionTokenKeyService

Methods

FetchAllActiveAsync(CancellationToken)

Fetches all active connection token keys. Called periodically by game servers to refresh their in-memory key map. Results are ordered by TimeCreated descending (newest first).

Task<DatabaseResult<ConnectionTokenKeyData[]>> FetchAllActiveAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<ConnectionTokenKeyData[]>>

A DatabaseResult<T> containing an array of active key data.

FetchByKeyIdAsync(string, CancellationToken)

Fetches a single connection token key by its logical key identifier.

Task<DatabaseResult<ConnectionTokenKeyData>> FetchByKeyIdAsync(string keyId, CancellationToken cancellationToken = default)

Parameters

keyId string

The logical key identifier to look up.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<ConnectionTokenKeyData>>

A DatabaseResult<T> containing the key data if found; otherwise a failure with ENTITY_NOT_FOUND.

GetConnectionTokenKeyMapAsync(CancellationToken)

Returns a dictionary mapping key ID to raw HMAC key bytes for all active keys. Each value is the base64-decoded HMAC key material. Convenience method for game servers that need the key material in byte form.

Task<DatabaseResult<Dictionary<string, byte[]>>> GetConnectionTokenKeyMapAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<Dictionary<string, byte[]>>>

A DatabaseResult<T> containing the key ID to raw key bytes map.

UpsertAsync(string, byte[], CancellationToken)

Inserts or updates the active HMAC key for the given keyId. On insert, a new row is created with IsActive = true. On update (existing keyId), the key material is replaced, the key is marked active, and DeactivatedAt is cleared.

Task<DatabaseResult<ConnectionTokenKeyData>> UpsertAsync(string keyId, byte[] hmacKey, CancellationToken cancellationToken = default)

Parameters

keyId string

Logical key identifier (e.g., region code). Must be non-empty and at most 255 characters.

hmacKey byte[]

HMAC-SHA256 key material. Must be at least 32 bytes.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<ConnectionTokenKeyData>>

A DatabaseResult<T> containing the upserted key data on success.