# Alepha - Security

## Installation

Part of the `alepha` package. Import from `alepha/security`.

```bash
npm install alepha
```

## Overview

Complete authentication and authorization system with JWT, RBAC, and multi-issuer support.

**Features:**

- JWT token issuer with role definitions
- Role-based access control (RBAC)
- Fine-grained permissions
- HTTP Basic Authentication
- Service-to-service authentication
- Multi-issuer support for federated auth
- JWKS (JSON Web Key Set) for external issuers
- Token refresh logic
- User profile extraction from JWT

## API Reference

### Primitives

- [`$basicAuth`](https://latest.alepha.dev/docs/reference-primitives-$basicauth.md) - Middleware that enforces HTTP Basic Authentication on the request.
- [`$issuer`](https://latest.alepha.dev/docs/reference-primitives-$issuer.md) - Create a new issuer.
- [`$owns`](https://latest.alepha.dev/docs/reference-primitives-$owns.md) - Resource-scoped authorization gate.
- [`$permission`](https://latest.alepha.dev/docs/reference-primitives-$permission.md) - Create a new permission.
- [`$role`](https://latest.alepha.dev/docs/reference-primitives-$role.md) - Create a new role.
- [`$secure`](https://latest.alepha.dev/docs/reference-primitives-$secure.md) - Middleware that enforces authentication and authorization.
- [`$serviceAccount`](https://latest.alepha.dev/docs/reference-primitives-$serviceaccount.md) - Allow to get an access token for a service account.

### Providers

- [`EffectivePermissionsProvider`](https://latest.alepha.dev/docs/reference-providers-effectivepermissionsprovider.md) - The caller's **effective** permission set, computed once, server-side.
- [`JwtProvider`](https://latest.alepha.dev/docs/reference-providers-jwtprovider.md) - Provides utilities for working with JSON Web Tokens (JWT).
- [`OwnedResourceProvider`](https://latest.alepha.dev/docs/reference-providers-ownedresourceprovider.md) - Reads the resource resolved by `$owns` for the current request.
- [`PermissionRegistryProvider`](https://latest.alepha.dev/docs/reference-providers-permissionregistryprovider.md) - Answers "does the caller hold this permission?" from the set the server sent
- [`ResourceGateMemoProvider`](https://latest.alepha.dev/docs/reference-providers-resourcegatememoprovider.md) - Request-scoped memo for the reads `$owns` performs to make its decision.
- [`ResourceGrantsProvider`](https://latest.alepha.dev/docs/reference-providers-resourcegrantsprovider.md) - The seam between `$owns` and whatever decides what a member may do