# AuthService

Accessible via `iam.auth`. Handles authentication, session management, impersonation, and device/PIN login.

## Login

```typescript
// Login with credentials
const identity = await iam.auth.login({ username: 'user@test.com', password: 'secret' });
// Returns AuthIdentity with token, user info, permissions

// Third-party login (e.g. Google)
await iam.auth.thirdPartyLogin({ provider: 'google', payload: googleAuthData });
```

## Token Management

```typescript
// Get current token from storage
const token = await iam.auth.getToken();

// Validate a token against the server
await iam.auth.validateToken(token);

// Get a fresh token (validates current, returns new)
const freshToken = await iam.auth.freshToken();

// Get auth headers (with Bearer token)
const headers = await iam.auth.getHeaders();
```

## Session

```typescript
// Verify that the current token is still valid
await iam.auth.checkAuth();

// Logout (clears all auth data from storage)
await iam.auth.logout();
```

## Identity and Permissions

```typescript
// Get current user identity (profile, email, roles)
const identity = await iam.auth.getIdentity();

// Get permissions as string array
const permissions = await iam.auth.getPermissions();

// Get roles as string array
const roles = await iam.auth.getRoles();
```

## Registration and Activation

```typescript
// Register a new user
const { userId } = await iam.auth.register({
  name: 'Mario Rossi',
  email: 'mario@test.com',
  password: 'securePassword'
});

// Activate account with activation code
await iam.auth.activate('activation-code');
```

## Password Recovery and Change

```typescript
// Send recovery email
await iam.auth.recover('user@test.com');

// Change password (requires current session)
await iam.auth.changePassword('currentPassword', 'newPassword');
```

## Profile Update

```typescript
// Update current user's profile
await iam.auth.updateProfile({ name: 'New Name', customField: 'value' });
```

## Impersonation

Requires admin privileges (ROLE_ADMIN).

```typescript
// Start impersonating a user
await iam.auth.impersonate('user-id');

// Check if currently impersonating
const isImpersonating = await iam.auth.isImpersonating();

// Stop impersonating (restores admin session)
await iam.auth.stopImpersonate();
```

## Device and PIN Login

Used for device-based authentication with PIN codes.

```typescript
// Register a new device
const device = await iam.auth.registerDevice('device-code');
// Returns { code: string, secret: string }

// Get device (registers if not already registered)
const device = await iam.auth.getDevice('device-code');

// Login with PIN
await iam.auth.pinLogin('device-code', '1234');

// Reset a user's PIN
await iam.auth.resetPin('user-id', '5678');
```

### PIN Encryption

The PIN is encrypted client-side using AES before transmission. The payload is sent as Base64 in the format:

```
ivHex::saltHex::ciphertextBase64
```

- Key derivation: PBKDF2 with HMAC-SHA1 (128 bit, 1000 iterations)
- Compatible with the Java server-side implementation