Public Access
Add the server client and client-side enrollment
A typed client over DodoSSH.Contracts, and the orchestration that turns a passphrase into an enrolled identity: generate keys, have the identity provider sign over them, wrap the bundle three ways, create the personal vault, publish. Ordering here is forced, not chosen. The secret bundle's AAD binds to the server-assigned user id, so /me has to be read before anything can be wrapped -- which is exactly why /me provisions the account and returns its id even while reporting that enrollment is required. That constraint was designed into the server earlier; this is the first code that depends on it. The grant tuple now has a real canonical encoding (crypto.md 7.3) rather than the placeholder signature I would otherwise have had to invent and then keep. §7 named the tuple without specifying how to encode it; this fills that in with the same conventions as 7.1, and the self-grant at enrollment is already in its final format. The signature covers SHA-256(wrappedKey) rather than the key, so a verifier can check attribution without holding the vault key at all. The most valuable tests are the negative ones about the request body: the server is meant to be unable to read what it stores, and a refactor that put a passphrase or a private key into the enrollment request would be invisible to every other test in the repository. So one asserts the body contains neither the passphrase, the recovery code, nor any private key in base64 or hex. Another opens the same bundle three ways -- passphrase, recovery code and device key -- which is what makes a passphrase change a one-row update. ClientEnrollment depends on IKeyBindingAuthorizer rather than the whole OidcClient. It needs exactly one capability, and depending on the full client would drag discovery and token exchange into every test of key binding. Two things fixed while building it. The recovery code buffer was sized one separator short, so every enrollment threw IndexOutOfRange -- caught immediately because nine of ten tests failed identically. And the crypto enum collided with Domain.GrantKind in the server, so it is GrantPurpose there; the numeric values still have to match, which the doc and a test both say. 448 tests pass, zero warnings on a clean rebuild, format clean.
This commit is contained in:
@@ -0,0 +1,175 @@
|
||||
using System.Net;
|
||||
using System.Net.Http.Headers;
|
||||
using System.Net.Http.Json;
|
||||
using System.Text.Json;
|
||||
using DodoSSH.Contracts;
|
||||
|
||||
namespace DodoSSH.Client.Api;
|
||||
|
||||
/// <summary>Supplies the bearer token for API calls, refreshing it when needed.</summary>
|
||||
/// <remarks>
|
||||
/// An abstraction because token lifetime is the auth layer's problem, not the API client's. The
|
||||
/// client asks for a token per request and never caches one, so a refresh that happens mid-session is
|
||||
/// invisible here rather than something every call site has to remember to handle.
|
||||
/// </remarks>
|
||||
public interface IAccessTokenProvider
|
||||
{
|
||||
/// <summary>Returns a currently-valid access token.</summary>
|
||||
ValueTask<string> GetAccessTokenAsync(CancellationToken cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The typed client for one DodoSSH server.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Everything goes through <c>DodoSSH.Contracts</c> and its source-generated serialiser, which is the
|
||||
/// actual contract between the two sides — not the OpenAPI document. Requests are written with
|
||||
/// <c>StrictRequestOptions</c> on the server and read here with <c>ResponseOptions</c>, so an older
|
||||
/// client tolerates a newer server's extra fields instead of failing on them.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Discovery is unauthenticated by necessity: a client has to learn how to authenticate before it can.
|
||||
/// Everything else carries a bearer token.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class DodoSshApiClient(HttpClient http, IAccessTokenProvider tokens)
|
||||
{
|
||||
private const string MetaPath = "/api/v1/meta";
|
||||
private const string ConfigurationPath = "/.well-known/dodossh-configuration";
|
||||
private const string MePath = "/api/v1/me";
|
||||
private const string EnrollmentPath = "/api/v1/me/enrollment";
|
||||
|
||||
/// <summary>
|
||||
/// Reads the server's capabilities, versions and limits.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Unauthenticated, and the replacement for URL-based API versioning: when client and server
|
||||
/// upgrade independently — normal for self-hosted software — a client has to ask what this
|
||||
/// particular server supports rather than assume. See ADR 0002.
|
||||
/// </remarks>
|
||||
public Task<MetaResponse> GetMetaAsync(CancellationToken cancellationToken) =>
|
||||
GetAnonymousAsync(MetaPath, DodoSshJsonContext.Default.MetaResponse, cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Reads everything needed to begin authenticating.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This is the onboarding story: the user types one server URL and the client discovers the OIDC
|
||||
/// authority, the client id, the scopes and the relay from it.
|
||||
/// </remarks>
|
||||
public Task<DodoSshConfiguration> GetConfigurationAsync(CancellationToken cancellationToken) =>
|
||||
GetAnonymousAsync(
|
||||
ConfigurationPath,
|
||||
DodoSshJsonContext.Default.DodoSshConfiguration,
|
||||
cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Reads the caller's profile, unlock material and reachable vaults.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The first authenticated call a client makes, and the only one that works before enrollment. It
|
||||
/// also provisions the account, so its <c>UserId</c> is available before enrolling — which matters,
|
||||
/// because the secret bundle's AAD binds to that id and therefore cannot be built any earlier.
|
||||
/// </remarks>
|
||||
public Task<MeResponse> GetMeAsync(CancellationToken cancellationToken) =>
|
||||
SendAsync(HttpMethod.Get, MePath, null, DodoSshJsonContext.Default.MeResponse, cancellationToken);
|
||||
|
||||
/// <summary>Publishes the caller's first identity key and creates their personal vault.</summary>
|
||||
public Task<EnrollmentResponse> EnrollAsync(
|
||||
EnrollmentRequest request,
|
||||
CancellationToken cancellationToken) =>
|
||||
SendAsync(
|
||||
HttpMethod.Post,
|
||||
EnrollmentPath,
|
||||
JsonContent.Create(request, DodoSshJsonContext.Default.EnrollmentRequest),
|
||||
DodoSshJsonContext.Default.EnrollmentResponse,
|
||||
cancellationToken);
|
||||
|
||||
/// <summary>Reads vault changes after a cursor.</summary>
|
||||
/// <remarks>
|
||||
/// A POST despite being a read: the filters live in the body, cursors are opaque, and no caching is
|
||||
/// wanted.
|
||||
/// </remarks>
|
||||
public Task<SyncPullResponse> SyncPullAsync(
|
||||
Guid vaultId,
|
||||
SyncPullRequest request,
|
||||
CancellationToken cancellationToken) =>
|
||||
SendAsync(
|
||||
HttpMethod.Post,
|
||||
$"/api/v1/vaults/{vaultId}/sync/pull",
|
||||
JsonContent.Create(request, DodoSshJsonContext.Default.SyncPullRequest),
|
||||
DodoSshJsonContext.Default.SyncPullResponse,
|
||||
cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Applies a batch of vault changes.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Succeeds with per-operation status even when individual operations failed, so one stale item
|
||||
/// cannot block everything else a client queued while offline. Callers must inspect
|
||||
/// <c>SyncPushResult.Status</c> rather than treating a 200 as everything having applied.
|
||||
/// </remarks>
|
||||
public Task<SyncPushResponse> SyncPushAsync(
|
||||
Guid vaultId,
|
||||
SyncPushRequest request,
|
||||
CancellationToken cancellationToken) =>
|
||||
SendAsync(
|
||||
HttpMethod.Post,
|
||||
$"/api/v1/vaults/{vaultId}/sync/push",
|
||||
JsonContent.Create(request, DodoSshJsonContext.Default.SyncPushRequest),
|
||||
DodoSshJsonContext.Default.SyncPushResponse,
|
||||
cancellationToken);
|
||||
|
||||
private async Task<T> GetAnonymousAsync<T>(
|
||||
string path,
|
||||
System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> typeInfo,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
using var request = new HttpRequestMessage(HttpMethod.Get, path);
|
||||
return await SendCoreAsync(request, typeInfo, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private async Task<T> SendAsync<T>(
|
||||
HttpMethod method,
|
||||
string path,
|
||||
HttpContent? content,
|
||||
System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> typeInfo,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
using var request = new HttpRequestMessage(method, path) { Content = content };
|
||||
|
||||
var token = await tokens.GetAccessTokenAsync(cancellationToken).ConfigureAwait(false);
|
||||
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
|
||||
|
||||
return await SendCoreAsync(request, typeInfo, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private async Task<T> SendCoreAsync<T>(
|
||||
HttpRequestMessage request,
|
||||
System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> typeInfo,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
using var response = await http.SendAsync(request, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
if (!response.IsSuccessStatusCode)
|
||||
{
|
||||
var body = await response.Content
|
||||
.ReadAsStringAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
throw DodoSshApiException.FromResponse(response.StatusCode, body);
|
||||
}
|
||||
|
||||
var value = await response.Content
|
||||
.ReadFromJsonAsync(typeInfo, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
// A 200 with a null body is a server bug, but it must not surface as a NullReferenceException
|
||||
// three frames further up where the cause is invisible.
|
||||
return value ?? throw new DodoSshApiException(
|
||||
HttpStatusCode.OK,
|
||||
null,
|
||||
$"The server returned an empty body where a {typeof(T).Name} was expected.");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user