Members on this page
DeviceChangedDeviceStateChangedDeviceManager(ClientOptions, DatabaseOptions, RelayClientPool, AccountManager, IAccountSigner, ISecretProtector)CreateDeviceAsync(TimeSpan, CancellationToken)DeriveSharedSecretAsync(ReadOnlyMemory<byte>, CancellationToken)GetAuthorizationState(string)GetCertificate(string)GetDeviceStateAsync(ContactGrant, CancellationToken)GetDeviceStateAsync(ContactInvite, CancellationToken)GetDeviceStateAsync(string, CancellationToken)GetOwnDeviceStateAsync(string, CancellationToken)PublishDeviceStateAsync(string, IReadOnlyList<DeviceCertificate>, DeviceStatePublishOptions, CancellationToken)RemoveDeviceAsync(string, CancellationToken)RenewDeviceAsync(TimeSpan, CancellationToken)SignAsync(ReadOnlyMemory<byte>, CancellationToken)DeviceStateLocalRelayClients
Meshline.Sdk
Meshline.Components
DeviceManager Class
Manages the local device's protected keys, certificates, published authorization, and device signing.
public sealed class DeviceManager : Meshline.Components.ClientComponent, Meshline.Interactions.IDeviceSigner
Inheritance System.Object → ClientComponent → DeviceManager
Implements IDeviceSigner
Exceptions
System.ArgumentNullException
The network context in options is null. The options argument is null.
System.ArgumentException
The configured account identifier is invalid.
System.NotSupportedException
The configured account identifier uses an unsupported account namespace.
Constructors
DeviceManager(ClientOptions, DatabaseOptions, RelayClientPool, AccountManager, IAccountSigner, ISecretProtector) Constructor
Manages the local device's protected keys, certificates, published authorization, and device signing.
public DeviceManager(Meshline.Models.Client.ClientOptions options, Meshline.Storage.DatabaseOptions databaseOptions, Meshline.Transport.RelayClientPool relayClients, Meshline.Components.AccountManager accountManager, Meshline.Interactions.IAccountSigner? accountSigner=null, Meshline.Interactions.ISecretProtector? secretProtector=null);
Parameters
options ClientOptions
The network and account configuration for this component.
databaseOptions DatabaseOptions
The SQLite database configuration; create its parent directory and apply migrations before initialization.
relayClients RelayClientPool
The shared relay pool. The application owns it and must dispose it after all dependent components.
accountManager AccountManager
The account component sharing this network, account, database, and relay pool.
accountSigner IAccountSigner
The application-owned account signer required for account-authorized operations, or null when those operations are not needed.
secretProtector ISecretProtector
The application-owned secret protector, required for operations that persist or restore protected key or message material.
Exceptions
System.ArgumentNullException
The network context in options is null. The options argument is null.
System.ArgumentException
The configured account identifier is invalid.
System.NotSupportedException
The configured account identifier uses an unsupported account namespace.
Properties
DeviceManager.DeviceState Property
The currently known account device state, or null when it is unavailable.
public Meshline.Models.Protocol.AccountDeviceState? DeviceState { get; }
Property Value
DeviceManager.Local Property
The local device certificate, or null when no local device has been loaded or created.
public Meshline.Models.Protocol.DeviceCertificate? Local { get; }
Property Value
DeviceManager.RelayClients Property
The shared relay pool used by this device manager.
public Meshline.Transport.RelayClientPool RelayClients { get; }
Property Value
Methods
DeviceManager.CreateDeviceAsync(TimeSpan, CancellationToken) Method
Creates local Ed25519 and X25519 keys and an account-authorized device certificate, then protects and stores them.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> CreateDeviceAsync(System.TimeSpan validity, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
validity System.TimeSpan
The validity duration, from one second through 720 days.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<DeviceCertificate>
The newly stored local device certificate.
Exceptions
System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.
System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable; a local device already exists in this database.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.
System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.
Remarks
Requires an account signer, a secret protector, and a database without a local device. The returned certificate is stored locally; publish device state before treating the device as authorized by the relay.
DeviceManager.DeriveSharedSecretAsync(ReadOnlyMemory<byte>, CancellationToken) Method
Performs X25519 key agreement with the local device's encryption private key.
public System.Threading.Tasks.Task<byte[]> DeriveSharedSecretAsync(System.ReadOnlyMemory<byte> peerPublicKey, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
peerPublicKey System.ReadOnlyMemory<System.Byte>
The peer's 32-byte X25519 public key.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<System.Byte[]>
A new 32-byte buffer containing the raw shared secret.
Exceptions
System.ArgumentException
The peer key is not 32 bytes or produces an all-zero shared secret.
System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.
System.InvalidOperationException
This component or a required component has not completed initialization. The local device or the secret protector required to load its keys is unavailable.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.IO.InvalidDataException
The stored local device certificate is JSON null.
Remarks
The returned bytes are raw key-agreement material. Apply the protocol's required key derivation before using them as a cryptographic key and clear sensitive buffers after use.
DeviceManager.GetAuthorizationState(string) Method
Evaluates registration and certificate validity in the currently known account device state.
public Meshline.Components.DeviceAuthorizationState GetAuthorizationState(string deviceId);
Parameters
deviceId System.String
The canonical device identifier.
Returns
DeviceAuthorizationState
The device's authorization state according to locally known registration and the current time.
Exceptions
System.InvalidOperationException
This component or a required component has not completed initialization.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
System.ArgumentException
The deviceId argument is not a canonical device identifier.
DeviceManager.GetCertificate(string) Method
Finds a device certificate in the currently known account device state.
public Meshline.Models.Protocol.DeviceCertificate? GetCertificate(string deviceId);
Parameters
deviceId System.String
The canonical device identifier.
Returns
DeviceCertificate
The registered certificate, or null when the state or device is unknown.
Exceptions
System.InvalidOperationException
This component or a required component has not completed initialization.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
System.ArgumentException
The deviceId argument is not a canonical device identifier.
DeviceManager.GetDeviceStateAsync(ContactGrant, CancellationToken) Method
Resolves and verifies account device authorization using the supplied account or contact evidence.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(Meshline.Models.Protocol.ContactGrant grant, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
grant ContactGrant
A contact grant authorizing this account to access the grantor's device state.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The grant has no valid signature from a currently authorized device.
System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.
System.NotSupportedException
An account identifier in the query uses an unsupported namespace.
DeviceManager.GetDeviceStateAsync(ContactInvite, CancellationToken) Method
Resolves and verifies account device authorization using the supplied account or contact evidence.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(Meshline.Models.Protocol.ContactInvite invite, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
invite ContactInvite
The signed invitation authorizing the operation.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The invitation signature is invalid, a local signing key fails validation, or the cryptographic provider fails signature verification.
System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.
System.NotSupportedException
An account identifier in the query uses an unsupported namespace.
DeviceManager.GetDeviceStateAsync(string, CancellationToken) Method
Resolves and verifies account device authorization using the supplied account or contact evidence.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(string? accountId=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
accountId System.String
The target account identifier, or null for the current account.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.
System.NotSupportedException
An account identifier in the query uses an unsupported namespace.
DeviceManager.GetOwnDeviceStateAsync(string, CancellationToken) Method
Resolves the current account's device state directly from the specified relay.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetOwnDeviceStateAsync(string relayId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
relayId System.String
The relay's canonical lowercase Neo script-hash identifier.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountDeviceState>
The current account's verified device state, or null when unavailable at that relay.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.
System.NotSupportedException
An account identifier in the query uses an unsupported namespace.
DeviceManager.PublishDeviceStateAsync(string, IReadOnlyList<DeviceCertificate>, DeviceStatePublishOptions, CancellationToken) Method
Signs and publishes a complete device authorization state and reports acceptance or staging.
public System.Threading.Tasks.Task<Meshline.Models.Client.DeviceStatePublishResult> PublishDeviceStateAsync(string relayId, System.Collections.Generic.IReadOnlyList<Meshline.Models.Protocol.DeviceCertificate>? certificates=null, Meshline.Models.Client.DeviceStatePublishOptions? options=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
relayId System.String
The relay's canonical lowercase Neo script-hash identifier.
certificates System.Collections.Generic.IReadOnlyList<DeviceCertificate>
The complete certificate list to publish, or null to preserve known devices and refresh the local certificate.
options DeviceStatePublishOptions
Optional prior-state, recovery, and revision settings.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<DeviceStatePublishResult>
The submitted state and the relay's authoritative-acceptance or temporary-staging result.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. The account signer or complete prior device state is unavailable, the local device is unauthorized outside recovery, or a pending publication conflicts with the requested update.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
The relay response or returned device state is inconsistent, including an expired staging interval.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.ArgumentException
The prior state belongs to another account or is invalid, or the complete certificate list fails protocol validation.
System.ArgumentOutOfRangeException
The selected device-state revision is not a newer nonnegative safe integer. A relay-provided staging timestamp is outside the supported DateTimeOffset range.
Remarks
A supplied list is the complete authorized device set, not a delta. With no list, known devices are preserved and the local certificate is refreshed; unavailable prior state or missing local authorization requires explicit recovery. Staged publication is not yet authoritative.
DeviceManager.RemoveDeviceAsync(string, CancellationToken) Method
Publishes a complete device state with the selected device removed after checking contact-grant continuity.
public System.Threading.Tasks.Task RemoveDeviceAsync(string deviceId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
deviceId System.String
The canonical device identifier.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.InvalidOperationException
This component or a required component has not completed initialization. Published device state is unavailable, removal would invalidate a contact grant without accepted replacement signatures, or the relay only stages the removal.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.ArgumentException
The deviceId argument is not a canonical device identifier.
System.ArgumentOutOfRangeException
The next device-state revision exceeds the protocol safe-integer limit.
DeviceManager.RenewDeviceAsync(TimeSpan, CancellationToken) Method
Issues and stores a renewed certificate for the existing local device without replacing its keys.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> RenewDeviceAsync(System.TimeSpan validity, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
validity System.TimeSpan
The validity duration, from one second through 720 days.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<DeviceCertificate>
The renewed local device certificate with the same device keys.
Exceptions
System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.
System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable; no local device has been created.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.
System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.
System.IO.InvalidDataException
The stored local device certificate is JSON null.
Remarks
The renewed certificate retains the device identity. Publish device state to make the renewed authorization authoritative at the relay.
DeviceManager.SignAsync(ReadOnlyMemory<byte>, CancellationToken) Method
Signs the supplied bytes using the device Ed25519 signing key.
public System.Threading.Tasks.Task<byte[]> SignAsync(System.ReadOnlyMemory<byte> data, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
data System.ReadOnlyMemory<System.Byte>
The exact bytes to sign or verify.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Implements SignAsync(ReadOnlyMemory<byte>, CancellationToken)
Returns
System.Threading.Tasks.Task<System.Byte[]>
The signature over the supplied input bytes.
Exceptions
System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.
System.InvalidOperationException
This component or a required component has not completed initialization. The local device or the secret protector required to load its keys is unavailable.
System.ObjectDisposedException
This component or a component used by the operation has been disposed.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.IO.InvalidDataException
The stored local device certificate is JSON null.
Events
DeviceManager.DeviceChanged Event
Occurs when a local device certificate is created or renewed.
public event EventHandler<DeviceChangedEventArgs>? DeviceChanged;
Event Type
System.EventHandler<DeviceChangedEventArgs>
DeviceManager.DeviceStateChanged Event
Occurs when the current account's known device authorization state changes.
public event EventHandler? DeviceStateChanged;