AAuth 0.1.0-alpha.3

Getting Started

Prerequisites

• .NET 10+ SDK

Install

dotnet add package AAuth --prerelease

Or, if working within this repository, add a project reference:

dotnet add reference src/AAuth/AAuth.csproj

Generate a Key

using AAuth.Crypto;

var key = AAuthKey.Generate(); // Ed25519 keypair
var publicJwk = key.ToPublicJwk(); // Export for registration
var thumbprint = key.ComputeJwkThumbprint(); // JWK thumbprint (S256)

Make Your First Signed Request

The simplest mode is pseudonymous (HWK) — no Agent Provider needed:

using AAuth.Crypto;
using AAuth.HttpSig;

var key = AAuthKey.Generate();

using var client = new AAuthClientBuilder(key)
    .UseHwk()
    .Build();

var response = await client.GetAsync("https://resource.example/data");
// Request is signed with HTTP Message Signatures (RFC 9421)
// Resource sees: Signature-Key: sig=hwk;jkt="<thumbprint>";jwk="<public-key>"

Alternative: One-liner with static factory

using var client = AAuthSigningHandler.CreateClient(key, new HwkSignatureKeyProvider(key));

Alternative: DI / IHttpClientFactory

// In Program.cs
builder.Services.AddAAuthAgent("agent", options =>
{
    options.Key = key;
    options.PersonServer = "https://ps.example"; // omit for signing-only
});

// Inject via IHttpClientFactory
public class MyService(IHttpClientFactory factory)
{
    private readonly HttpClient _client = factory.CreateClient("agent");
}

What Just Happened?

• AAuthKey.Generate() created an Ed25519 keypair.
• AAuthClientBuilder configured the HWK signing mode and produced an HttpClient.
• AAuthSigningHandler signs the request per RFC 9421 covering @method, @authority, @path, and signature-key.
• The resource verifies the signature using the inline public key from Signature-Key.

Bootstrap with an Agent Provider (Three-Party Flow)

For production scenarios, agents register with an Agent Provider (AP) to get an identity-bound agent token. Enrollment is a provisioning step that runs once (in a CLI tool or setup script). The durable signing key is generated inside a keystore and never extracted — the app references it by ID. The agent token is short-lived (typically 1 hour) and refreshed automatically by the SDK.

Provisioning (run once per device/install)

using AAuth.Agent;
using AAuth.HttpSig;

// Key is generated INSIDE the store — private material never leaves
var keyStore = KeyStore.Default(); // ~/.aauth/keys/ (or plug in HSM/Key Vault)

var enrol = await AAuthClientBuilder
    .Bootstrap(
        enrollEndpoint: "https://ap.example/enrol",
        agentId: "aauth:myagent@example.com")
    .WithPersonServer("https://ps.example")
    .WithKeyStore(keyStore)
    .EnrolAsync();

// Only the key ID needs to be recorded in app config
// (the key itself is already in the keystore)
Console.WriteLine($"Enrolled. Add to config: AAuth:KeyId = {enrol.KeyId}");

Application (every startup)

Load the key by ID from the store and let the SDK manage agent tokens:

using AAuth.Agent;
using AAuth.HttpSig;

var keyStore = KeyStore.Default();
var keyId = configuration["AAuth:KeyId"]!;
var apRefreshEndpoint = configuration["AAuth:ApRefreshEndpoint"]!;
var key = await keyStore.LoadAsync(keyId)
    ?? throw new InvalidOperationException($"Key '{keyId}' not found. Run enrollment first.");

// The SDK acquires the agent token lazily on first request
// via WithTokenRefresh, then keeps it fresh automatically.
using var client = new AAuthClientBuilder(key)
    .WithTokenRefresh(async (ctx, ct) =>
    {
        var apClient = new AgentProviderClient(new HttpClient(), keyStore);
        return await apClient.RefreshAsync(apRefreshEndpoint, ctx.KeyId, ct);
    })
    .WithChallengeHandling("https://ps.example")
    .Build();

var response = await client.GetAsync("https://resource.example/protected");
Console.WriteLine(await response.Content.ReadAsStringAsync());

<details> <summary>Step-by-Step (Advanced)</summary>

1. Enrol with the Agent Provider

using AAuth.Agent;
using AAuth.Crypto;
using AAuth.Discovery;
using AAuth.HttpSig;

var apClient = new AgentProviderClient(new HttpClient(), new InMemoryKeyStore());
var enrol = await apClient.EnrolAsync(
    apIssuer: "https://ap.example",
    agentId: "aauth:myagent@example.com",
    enrollEndpoint: "https://ap.example/enrol",
    personServer: "https://ps.example");

// enrol.Key        — your Ed25519 signing key (in keystore)
// enrol.KeyId      — persisted key identifier (save this to config)
// enrol.AgentToken — initial aa-agent+jwt (short-lived, do not persist)

2. Build the Signed Client with Challenge Handling

using var client = new AAuthClientBuilder(enrol.Key)
    .WithTokenRefresh(async (ctx, ct) =>
    {
        var apClient = new AgentProviderClient(new HttpClient(), keyStore);
        return await apClient.RefreshAsync("https://ap.example/refresh", ctx.KeyId, ct);
    })
    .WithChallengeHandling(personServer: "https://ps.example")
    .Build();

3. Make Requests

var response = await client.GetAsync("https://resource.example/protected");
Console.WriteLine(await response.Content.ReadAsStringAsync());

</details>

<details> <summary>Manual Pipeline Setup (Low-Level)</summary>

This shows the internal handler pipeline for educational purposes. Use WithTokenRefresh + WithChallengeHandling in production code.

// Acquire a fresh agent token via the AP refresh endpoint
var apClient = new AgentProviderClient(new HttpClient(), keyStore);
var agentToken = await apClient.RefreshAsync("https://ap.example/refresh", keyId);

// Carrier-token holder — shared between signer and challenge handler.
var holder = new AAuthTokenHolder(agentToken);

var signingHandler = new AAuthSigningHandler(
    key, new JwtSignatureKeyProvider(() => holder.Current))
{
    InnerHandler = new HttpClientHandler(),
};

var exchangeHttp = new HttpClient(
    new AAuthSigningHandler(key, new JwtSignatureKeyProvider(() => agentToken))
    { InnerHandler = new HttpClientHandler() });

var exchange = new TokenExchangeClient(exchangeHttp, new MetadataClient(new HttpClient()));

var pipeline = new ChallengeHandler(exchange, holder, "https://ps.example")
{
    InnerHandler = signingHandler,
};

using var client = new HttpClient(pipeline);

</details>

What Happens Under the Hood

1. Agent sends a signed GET → Resource replies 401 with AAuth-Requirement: requirement=auth-token and a resource_token.
2. ChallengeHandler extracts the resource token, POSTs it to the Person Server's token endpoint.
3. The PS validates the agent token, confirms user consent (or defers), and returns an auth_token.
4. AAuthTokenHolder is updated; the handler retries the original request signed with the auth token.
5. Subsequent requests reuse the auth token until it expires.

Next Steps

• Signing Modes Overview — choose the right mode for your use case
• Identity-Based Access — simplest workflow
• PS-Asserted Access — full authorization flow
• Protocol Concepts — understand the full picture

Protocol Reference

Explore the interactive protocol specification at https://explorer.aauth.dev/.