BlockAuth.Sdk 0.5.0

BlockAuth SDK (.NET)

Cliente headless del servicio de autenticación BlockAuth (Socket.IO v4). Espejo headless de la capa protocol/ del paquete @block-auth.io/core (monorepo blockauth-sdk, patrón "headless core + thin per-framework adapters").

Arquitectura

El upstream TypeScript se reestructuró como monorepo: la capa de protocolo (agnóstica de framework) vive en packages/core/src/protocol/. Este puerto replica esa arquitectura:

La capa de protocolo se expone bajo el namespace BlockAuth.Protocol. Transport/ (ITransport, SocketIoTransport, JsonInterop) es la abstracción propia de este puerto (el upstream usa socket.io directo); ApiBridge emite el browser token (equivalente a packages/core/src/utils/apiBridge.ts); Crypto y Exceptions/ son también infraestructura específica del puerto. La semántica del protocolo es idéntica a la del core TypeScript.

Instalación

dotnet add package BlockAuth.Sdk

Uso

Un backend se autentica con su apiKey y su apiSecret. El apiSecret solo vive en el backend.

using BlockAuth.Protocol;

var provider = new BlockAuthProvider("YOUR_API_KEY", "YOUR_API_SECRET");
await provider.ConnectAsync();

var result = await provider.SigninAsync();
if (result["success"] is true)
{
    var profile = await provider.UserAsync("0xUserAddress");
    Console.WriteLine(string.Join(", ", provider.RoleNames));
}

await provider.DisconnectAsync();

No autentiques un backend con un browser token: el ws-server lo rechaza (exige un Origin de confianza y su scope no da acceso a UserAsync, UsersAsync, RolesAsync ni LogsAsync).

Login por redirección

Para que tus usuarios inicien sesión con BlockAuth, tu backend los manda al login alojado y recibe de vuelta un código de un solo uso, que canjea por la dirección y los roles del usuario. La dirección la da el ws-server, nunca el navegador.

using System.Net.Http.Json;
using System.Security.Cryptography;
using System.Text.Json;
using BlockAuth;

var http = new HttpClient();
var apiSecretHash = Crypto.Sha256Hex("YOUR_API_SECRET");
var redirectUri = "https://tuapp.com/callback";

// 1. Pide el enlace de login y redirige al usuario a él.
var state = Convert.ToHexString(RandomNumberGenerator.GetBytes(16)); // guárdalo en la sesión
var authorize = await http.PostAsJsonAsync(ApiBridge.BuildWsServerApiUrl("/auth/authorize"), new
{
    apiKey = "YOUR_API_KEY", apiSecret = apiSecretHash, redirectUri, state,
});
var link = (await authorize.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("message").GetProperty("url").GetString();

// 2. El usuario vuelve a redirectUri?code=...&state=... Comprueba que el state es el de la sesión.

// 3. Canjea el código (válido 60 s, un solo uso).
var token = await http.PostAsJsonAsync(ApiBridge.BuildWsServerApiUrl("/auth/token"), new
{
    apiKey = "YOUR_API_KEY", apiSecret = apiSecretHash, code, redirectUri,
});
var user = (await token.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("message");
var address = user.GetProperty("address").GetString(); // también: roles, signedExpiredAt

• Todas las respuestas son { "success": bool, "message": ... }; si success es false, message explica el error.
• El redirect_uri tiene que ser https en el dominio (o el dominio de desarrollo) de la app; http solo en localhost.
• Para cerrar la sesión del usuario en tu app: POST /api/auth/signout con apiKey, apiSecret (el mismo hash) y address.

Browser token para tu frontend

Si tu frontend usa @block-auth.io/core, el backend le emite un browser token para que el apiSecret no salga nunca del backend:

var provider = new BlockAuthProvider("YOUR_API_KEY", "YOUR_API_SECRET");
var browserToken = await provider.CreateBrowserTokenAsync();

El frontend lo usa como browserToken en @block-auth.io/core.

API

BlockAuthProvider: ConnectAsync, DisconnectAsync, IsConnected, SigninAsync, CreateBrowserTokenAsync, RefreshAsync, IsAddressSignedAsync, AppAsync, UserAsync, UsersAsync, RolesAsync, LogsAsync, KycIssuerAsync, helpers de roles (HasRole, HasRoleBySlug, HasAnyRole, HasAnyRoleBySlug) y getters (CurrentUser, RoleNames, UiConfig, …).

Tests

dotnet test

Smoke test contra un servidor real

Los tests usan un transporte simulado. Para probar el SDK contra el ws-server de PRE (transporte real, login por redirección y canje del código), usa la app de prueba de examples/TestApp/.