npm package: @stuiky/auth-sdk
Description: Authentication SDK for protecting scripts and applications
Author: stuiky
Latest version: 1.0.0

# @sr-main/auth-sdk

SDK de autenticação para proteger scripts e aplicações.

## Instalação

```bash
npm install @sr-main/auth-sdk
```

## Uso Rápido

### 1. Criar um API Token

Primeiro, acesse o painel de autenticação e crie um token com as scopes necessárias:
- `read` - Acesso de leitura
- `write` - Acesso de escrita
- `admin` - Acesso administrativo

### 2. Proteger seu Script

```javascript
import { AuthClient, requireAuth } from '@sr-main/auth-sdk';

// Opção 1: Verificação simples
const isValid = await authenticate(
  'https://auth.seuservidor.com', // URL do servidor de auth
  'sk_live_xxx',                   // Seu API token
  'read'                           // Scope necessário (opcional)
);

if (!isValid) {
  console.error('Não autenticado!');
  process.exit(1);
}

// Seu código protegido aqui
console.log('Script autenticado! Executando...');
```

### 3. Usando AuthClient (Recomendado)

```javascript
import { AuthClient } from '@sr-main/auth-sdk';

const auth = new AuthClient({
  apiUrl: 'https://auth.seuservidor.com',
  token: process.env.AUTH_TOKEN, // Ou passe diretamente
  requiredScope: 'read',         // Scope obrigatório
  autoExit: true,                // Sai automaticamente se inválido
});

// Verifica autenticação e sai se inválido
await auth.requireAuth();

// Seu código protegido aqui
console.log('✅ Autenticado! Executando script...');
```

### 4. Usando variável de ambiente

```bash
# .env
AUTH_TOKEN=sk_live_xxx
```

```javascript
import { AuthClient } from '@sr-main/auth-sdk';

const auth = new AuthClient({
  apiUrl: 'https://auth.seuservidor.com',
  // token será lido de process.env.AUTH_TOKEN automaticamente
});

await auth.requireAuth();
// Código protegido...
```

### 5. Wrap de funções

```javascript
import { AuthClient } from '@sr-main/auth-sdk';

const auth = new AuthClient({
  apiUrl: 'https://auth.seuservidor.com',
  token: 'sk_live_xxx',
});

// Função protegida - só executa se autenticado
const protectedFunction = auth.wrap(async (data) => {
  console.log('Processando:', data);
  return { success: true };
});

await protectedFunction({ id: 1 });
```

## API

### `AuthClient`

#### Constructor
```typescript
new AuthClient({
  apiUrl: string;       // URL do servidor de autenticação
  token?: string;       // API token (opcional, pode usar AUTH_TOKEN env)
  requiredScope?: string; // Scope obrigatório
  autoExit?: boolean;   // Sair automaticamente se inválido (default: true)
  exitCode?: number;    // Código de saída (default: 1)
})
```

#### Métodos

| Método | Descrição |
|--------|-----------|
| `validate()` | Valida o token e retorna resultado |
| `requireAuth()` | Valida e sai do processo se inválido |
| `hasScope(scope)` | Verifica se tem determinado scope |
| `getUserId()` | Retorna o ID do usuário do token |
| `setToken(token)` | Define um novo token |
| `wrap(fn)` | Envelopa função com autenticação |

### Funções auxiliares

```typescript
// Verificação rápida
authenticate(apiUrl, token, scope?): Promise<boolean>

// Requer autenticação ou sai
requireAuth(apiUrl, token, scope?): Promise<ValidationResult>
```

## Scopes

| Scope | Descrição |
|-------|-----------|
| `read` | Acesso de leitura |
| `write` | Acesso de escrita |
| `admin` | Acesso administrativo total |

## Exemplo Completo

```javascript
// script-protegido.js
import { AuthClient } from '@sr-main/auth-sdk';

async function main() {
  const auth = new AuthClient({
    apiUrl: 'https://auth.seuservidor.com',
    token: process.env.AUTH_TOKEN,
    requiredScope: 'write',
  });

  // Autentica ou sai
  await auth.requireAuth();
  
  console.log('✅ Autenticado com sucesso!');
  console.log('User ID:', await auth.getUserId());
  
  // Seu código protegido
  await processarDados();
  await salvarResultado();
}

main().catch(console.error);
```

## Servidor de Autenticação

Este SDK se conecta ao servidor AuthSystem. Endpoints utilizados:

- `POST /auth/validate` - Valida token
- `POST /auth/validate-scope` - Valida token com scope

## Licença

MIT