Axiam.Sdk 1.0.0-alpha9

Axiam.Sdk (C#)

Official C# client SDK for AXIAM — Access eXtended Identity and Authorization Management.

Package identity

• NuGet packages: Axiam.Sdk (core) and Axiam.Sdk.AspNetCore (ASP.NET Core middleware)
• Source: github.com/ilpanich/axiam-csharp-sdk
• License: Apache-2.0

Contract conformance

This SDK conforms to CONTRACT.md §1–§11 (including §6.1 mTLS client certificates).

See CONTRACT.md for the full cross-language behavioral contract.

§1–§11 conformance checklist

Declarative authorization helpers (CONTRACT.md §11)

Axiam.Sdk.AspNetCore ships a declarative, per-endpoint authorization attribute built strictly on top of the §10 middleware — it never re-implements or bypasses JWKS verification, the tenant check, or §3a CSRF; it only consumes the identity AxiamAuthMiddleware already injected into HttpContext.User.

using Axiam.Sdk.AspNetCore;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api")]
public sealed class DocumentsController : ControllerBase
{
    // action = "read", resource type = "documents" (sent to CheckAccessAsync as
    // "documents:read", the server's own "resource:verb" convention). The resource
    // UUID is resolved from the "id" route value by default.
    [HttpGet("documents/{id:guid}")]
    [AxiamAccess("read", "documents")]
    public IActionResult GetDocument(Guid id) => Ok(new { id });

    // Scope + a non-default route parameter name.
    [HttpGet("teams/{teamId:guid}/documents")]
    [AxiamAccess("list", "documents", Scope = "team", ResourceRouteParam = "teamId")]
    public IActionResult ListTeamDocuments(Guid teamId) => Ok(new { teamId });
}

[AxiamAccess(action, resource)] is sugar over the existing [Authorize(Policy = "resource:action")] mechanism (AxiamPolicyProvider/ AxiamPolicyHandler) — the legacy "resource:action" policy-string form remains fully supported side by side with the new attribute.

Semantics (CONTRACT.md §11.2, identical to every other AXIAM SDK):

• Runs strictly after authentication. No verified identity in HttpContext.User → 401 authentication_failed. The attribute never performs its own token extraction.
• Subject propagation. The check is made for the request's authenticated user (subjectId = the user_id claim AxiamAuthMiddleware injected), never for the shared AxiamClient's own session.
• Resource resolution. The resource UUID is resolved from the route value named by ResourceRouteParam (default "id"). A missing or non-UUID route value is a programming error → 400 invalid_request — never a silent allow, never a Guid.Empty/nil-UUID fallback.
• Scope. The optional Scope property is passed through to CheckAccessAsync verbatim.
• Fail-closed on transport failure. A NetworkError while calling the authz endpoint → 503 authz_unavailable — deny, never allow, on a transport failure.
• No decision caching. Every check is a fresh CheckAccessAsync call, exactly like the legacy policy-string form.
• Deny outcome. 403 authorization_denied.

require_auth and require_role are not new types in this SDK — they map directly onto ASP.NET Core's own [Authorize] and [Authorize(Roles = "admin,editor")] (AxiamAuthMiddleware already emits a ClaimTypes.Role claim per role, so role-based [Authorize] works out of the box). require_role is a local check against the verified token's claims — it never calls the AXIAM server, and it is documented here (as in every AXIAM SDK) as NOT a substitute for the resource-level [AxiamAccess(...)] check above.

Quickstart

dotnet add package Axiam.Sdk
dotnet add package Axiam.Sdk.AspNetCore   # optional — ASP.NET Core middleware + DI

using Axiam.Sdk;

// tenantId is a required, positional constructor argument (SC#1) — there is no
// overload or default that omits it (CONTRACT.md §5).
using var client = new AxiamClient(new Uri("https://your-axiam-instance"), "your-tenant-slug");

var login = await client.LoginAsync("alice@example.com", "correct horse battery staple");
if (login.MfaRequired)
{
    login = await client.VerifyMfaAsync(login.ChallengeToken!.Value, totpCode: "123456");
}

bool canRead = await client.Authz.CanAsync("documents:read", documentId);

See examples/ for a full runnable ASP.NET Core sample (middleware + policy authorization, SC#3) and a console quickstart covering REST, gRPC, and AMQP.

mTLS / client certificates (CONTRACT.md §6.1)

AXIAM authenticates IoT devices and service accounts by mutual TLS: the client presents an X.509 identity certificate (signed by the tenant's organization CA) that the server binds to a service account. Configure the client identity with a PEM certificate chain plus a PEM private key (PKCS#8 or PKCS#1) via AxiamClientOptions — it is applied to both the REST and gRPC transports of that same client instance:

using Axiam.Sdk;
using Axiam.Sdk.Options;

var options = new AxiamClientOptions
{
    BaseUrl = new Uri("https://your-axiam-instance"),
    TenantId = "your-tenant-slug",
    ClientCertificatePem = File.ReadAllBytes("device-cert.pem"), // PEM cert chain
    ClientKeyPem = File.ReadAllBytes("device-key.pem"),          // PEM private key (secret)
};

using var client = new AxiamClient(new Uri("https://your-axiam-instance"), "your-tenant-slug", options);

Notes:

• Opt-in. Omitting the certificate leaves the SDK's default bearer-cookie behavior unchanged. ClientCertificatePem and ClientKeyPem must be supplied together — providing exactly one throws ArgumentException at client construction.
• Strict TLS preserved. Presenting a client certificate never relaxes server verification; the client-cert code path is entirely separate from §6's server-trust handling and installs no permissive server-validation delegate.
• Key secrecy (§7). The private key is secret material — it is never logged, serialized, or exposed via a public getter beyond the options object it is set on.
• On Axiam.Sdk.AspNetCore, the same two properties exist on AxiamOptions and flow through to the shared AxiamClient.

Grpc.Tools exception

The C# SDK is the one documented exception to the buf codegen pipeline every other AXIAM SDK uses. Rust, TypeScript, Python, Java, PHP and Go all run buf generate to produce gRPC stubs from proto/axiam/v1/. The C# SDK uses Grpc.Tools MSBuild codegen instead: the .proto files are included via <Protobuf Include="../proto/axiam/v1/*.proto" /> in Axiam.Sdk.csproj and stubs are generated into obj/ at build time by the Grpc.Tools package, not by buf. This repository therefore carries no buf.yaml/buf.gen.yaml.

This exception is intentional and approved (D-01). The C# SDK still tracks the same proto/axiam/v1/ definitions as the buf pipeline; only the codegen toolchain differs.

Status

Axiam.Sdk (REST + gRPC + AMQP + Sensitive + JWKS) and Axiam.Sdk.AspNetCore (middleware + DI + policy authorization) are both fully implemented and tested. See the Quickstart above and examples/ for runnable code.