AuthID Wallet SDK

Início Rápido

Comece a usar o AuthID Wallet SDK em poucos minutos. Este guia mostra como configurar a autenticação e acessar a API de carteira digital.

npm install @authid/wallet-sdk

import { AuthClient } from '@authid/wallet-sdk';

const auth = new AuthClient({
  serverUrl: 'https://auth.valid.ia.br',
  realm: 'authid',
  clientId: 'sua-aplicacao',
});

// Login com OAuth Authorization Code + PKCE
const pkce = await auth.generatePKCE();
const authUrl = auth.getAuthorizationUrl(
  'myapp://callback',
  pkce,
  'random-state'
);

// Após redirect, trocar o code pelo token
const tokenInfo = await auth.exchangeCode({
  code: 'authorization_code',
  redirectUri: 'myapp://callback',
  codeVerifier: pkce.codeVerifier,
});

import { WalletSDK } from '@authid/wallet-sdk';

const wallet = new WalletSDK({
  baseUrl: 'https://wallet.valid.ia.br',
  apiKey: tokenInfo.accessToken,
  organizationId: 'sua-organizacao',
});

// Listar credenciais
const credentials = await wallet.credentials.list();

// Obter detalhes de uma credencial
const credential = await wallet.credentials.get('credential-id');

// Criar uma apresentação verificável
const presentation = await wallet.presentations.create({
  credentialIds: ['credential-id'],
  verifierDid: 'did:web:verifier.example.com',
});

Instalação

Requisitos

• Node.js 18+ ou ambiente compatível
• React Native 0.70+ (para apps móveis)
• TypeScript 5.0+ (recomendado)

NPM / PNPM / Yarn

npm install @authid/wallet-sdk

pnpm add @authid/wallet-sdk

yarn add @authid/wallet-sdk

Para React Native

O SDK funciona nativamente com React Native. Para recursos de criptografia, instale também:

npx expo install expo-crypto expo-secure-store

Configuração

AuthClient

O AuthClient gerencia a autenticação com o servidor Keycloak/OAuth.

WalletSDK

O WalletSDK fornece acesso à API de carteira digital.

OAuth 2.0 com PKCE

O fluxo recomendado para aplicações mobile e SPA é o Authorization Code com PKCE. Este fluxo oferece máxima segurança sem necessidade de client secret.

Exemplo Completo

import { AuthClient } from '@authid/wallet-sdk';

const auth = new AuthClient({
  serverUrl: 'https://auth.valid.ia.br',
  realm: 'authid',
  clientId: 'minha-app',
});

// 1. Gerar PKCE challenge
const pkce = await auth.generatePKCE();

// 2. Construir URL de autorização
const state = crypto.randomUUID();
const authUrl = auth.getAuthorizationUrl(
  'myapp://auth/callback',  // redirect URI
  pkce,                      // PKCE challenge
  state                      // state para CSRF
);

// 3. Abrir browser (React Native com expo-auth-session)
import * as WebBrowser from 'expo-web-browser';
const result = await WebBrowser.openAuthSessionAsync(authUrl, 'myapp://');

// 4. Extrair code da URL de callback
const url = new URL(result.url);
const code = url.searchParams.get('code');
const returnedState = url.searchParams.get('state');

// 5. Validar state
if (returnedState !== state) {
  throw new Error('State mismatch - possible CSRF attack');
}

// 6. Trocar code por tokens
const tokenInfo = await auth.exchangeCode({
  code,
  redirectUri: 'myapp://auth/callback',
  codeVerifier: pkce.codeVerifier,
});

console.log('Access Token:', tokenInfo.accessToken);
console.log('Expires at:', tokenInfo.expiresAt);

Credenciais

O módulo de credenciais permite gerenciar credenciais verificáveis na carteira do usuário.

Listar Credenciais

const credentials = await wallet.credentials.list();

credentials.forEach(cred => {
  console.log(`${cred.type}: ${cred.issuer.name}`);
  console.log(`Status: ${cred.status}`);
  console.log(`Válido até: ${cred.expiresAt}`);
});

Obter Detalhes

const credential = await wallet.credentials.get('credential-id');

console.log('Tipo:', credential.type);
console.log('Issuer:', credential.issuer);
console.log('Claims:', credential.claims);
console.log('Prova:', credential.proof);

Tipos de Credenciais Suportados

API Reference

Tipos TypeScript

// Configuração do Keycloak
interface KeycloakConfig {
  serverUrl: string;
  realm: string;
  clientId: string;
  clientSecret?: string;
  scopes?: string[];
}

// Informações do Token
interface TokenInfo {
  accessToken: string;
  refreshToken?: string;
  expiresAt: Date;
  refreshExpiresAt?: Date;
  tokenType: string;
  idToken?: string;
  scope?: string;
}

// Informações do Usuário
interface UserInfo {
  sub: string;
  email?: string;
  email_verified?: boolean;
  name?: string;
  given_name?: string;
  family_name?: string;
  preferred_username?: string;
}

// Credencial Verificável
interface Credential {
  id: string;
  type: string[];
  issuer: CredentialIssuer;
  issuanceDate: string;
  expirationDate?: string;
  credentialSubject: Record<string, unknown>;
  proof?: CredentialProof;
  status: 'active' | 'revoked' | 'expired';
}

// Apresentação Verificável
interface VerifiablePresentation {
  id: string;
  type: string[];
  verifiableCredential: Credential[];
  holder: string;
  proof: PresentationProof;
}

Tratamento de Erros

O SDK lança erros tipados para facilitar o tratamento:

import { AuthError, WalletError } from '@authid/wallet-sdk';

try {
  await auth.login({ username, password });
} catch (error) {
  if (error instanceof AuthError) {
    switch (error.code) {
      case 'INVALID_CREDENTIALS':
        console.log('Usuário ou senha incorretos');
        break;
      case 'ACCOUNT_DISABLED':
        console.log('Conta desativada');
        break;
      case 'NO_REFRESH_TOKEN':
        console.log('Sessão expirada, faça login novamente');
        break;
      default:
        console.log('Erro de autenticação:', error.message);
    }
  }
}

try {
  await wallet.credentials.get('invalid-id');
} catch (error) {
  if (error instanceof WalletError) {
    console.log(`Erro ${error.code}: ${error.message}`);
    console.log('Status HTTP:', error.statusCode);
  }
}

Códigos de Erro Comuns