Metadata-Version: 2.3
Name: raja
Version: 0.2.2
Summary: Add your description here
Author: Dr. Ernie Prabhakar
Author-email: Dr. Ernie Prabhakar <ernest@quilt.bio>
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: mangum>=0.17.0
Requires-Dist: aws-cdk-lib>=2.100.0 ; extra == 'aws'
Requires-Dist: boto3>=1.34.0 ; extra == 'aws'
Requires-Dist: constructs>=10.0.0 ; extra == 'aws'
Requires-Dist: mypy>=1.7.0 ; extra == 'dev'
Requires-Dist: poethepoet>=0.24.0 ; extra == 'dev'
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: pytest-watch>=4.2.0 ; extra == 'dev'
Requires-Dist: httpx>=0.27.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: boto3-stubs[dynamodb,secretsmanager,verifiedpermissions]>=1.34.0 ; extra == 'dev'
Requires-Dist: moto>=4.2.0 ; extra == 'test'
Requires-Dist: pytest>=8.0.0 ; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'test'
Requires-Dist: httpx>=0.27.0 ; extra == 'test'
Requires-Python: >=3.12
Provides-Extra: aws
Provides-Extra: dev
Provides-Extra: test
Description-Content-Type: text/markdown

# RAJA
![CI](https://github.com/quiltdata/raja/workflows/CI/badge.svg)
![Integration Tests](https://github.com/quiltdata/raja/workflows/Integration%20Tests/badge.svg)
![Coverage](https://codecov.io/gh/quiltdata/raja/branch/main/graph/badge.svg)

**Resource Authorization JWT Authority** - Compile Cedar policies into JWT tokens for deterministic authorization.

## What is RAJA?

RAJA compiles Cedar authorization policies into JWT tokens with explicit scopes. This means:

- Authorization decisions are **deterministic** (same token + request = same result)
- Tokens are **transparent** (you can see exactly what permissions are granted)
- Enforcement is **fast** (simple scope checking, no policy evaluation)

## Quick Start

### Installation

```bash
git clone https://github.com/quiltdata/raja.git
cd raja
uv sync
```

### Deploy to AWS (Control Plane)

```bash
# Deploy infrastructure
poe cdk-deploy --all

# Load Cedar policies
python scripts/load_policies.py

# Compile policies to scopes
export RAJA_API_URL="https://your-api.execute-api.us-east-1.amazonaws.com/prod"
python scripts/invoke_compiler.py
```

### Control Plane UI

After deployment, open the API Gateway URL in your browser. The root path (`/`) renders a
simple admin UI with live data from `/principals`, `/policies`, and `/audit`.

## How It Works

```text
Cedar Policies → Compiler → JWT Scopes → Library Enforcement
```

1. **Write Cedar policies** that define who can do what
2. **Compiler** converts policies into scope strings (e.g., `Document:doc123:read`)
3. **Token Service** issues JWTs containing these scopes
4. **Applications** validate tokens and check scopes locally

## API Endpoints

When deployed to AWS, RAJA provides:

**POST /compile** - Compile Cedar policies into scopes

```json
{}
→ {"message": "Policies compiled successfully", "policies_compiled": 3}
```

**POST /token** - Issue a JWT token

```json
{"principal": "alice"}
→ {"token": "eyJ...", "scopes": ["Document:doc123:read"]}
```

**GET /principals** - List principals and their scopes

```text
→ {"principals": [{"principal": "alice", "scopes": [...]}]}

**GET /policies** - List Cedar policies

```json
→ {"policies": [{"policyId": "..."}]}
```

**GET /audit** - View audit log entries
```

## Local Development

Use the Python library standalone (no AWS required):

```python
from raja import AuthRequest, create_token, enforce

# Create token with scopes
token = create_token(
    subject="alice",
    scopes=["Document:doc123:read"],
    secret="your-secret"
)

# Check authorization
decision = enforce(
    token_str=token,
    request=AuthRequest(resource_type="Document", resource_id="doc123", action="read"),
    secret="your-secret"
)
print(decision.allowed)  # True
```

### Run Tests

```bash
poe test-unit      # Unit tests (no AWS)
poe test           # All tests
poe check-all      # Format, lint, typecheck
```

## Scope Format

Scopes follow the pattern: `{ResourceType}:{ResourceId}:{Action}`

Examples:

- `Document:doc123:read` - Read document doc123
- `Document:*:read` - Read all documents
- `*:*:*` - Full admin access

## Project Structure

```text
raja/
├── src/raja/           # Core Python library
├── lambda_handlers/    # AWS Lambda handlers
├── infra/             # CDK infrastructure
├── policies/          # Sample Cedar policies
└── tests/             # Test suite
```

## Documentation

- **[CLAUDE.md](CLAUDE.md)** - Developer guide and architecture
- **[specs/](specs/)** - Design specifications
- **Module READMEs** - See CLAUDE.md files in subdirectories

## Contributing

See [CLAUDE.md](CLAUDE.md) for development guidelines.

## License

[License information to be added]
