# Recon Ranger (FastAPI)

Local development instructions for running the API on your machine.

## Prerequisites

- Python 3.13+
- Optional: `uv` (recommended because `uv.lock` is included)

## Azure Entra ID Setup

The dashboard at `/` requires login via Azure Entra ID. Assuming you have a **tenant ID**, follow these steps:

### 1. Create an App Registration

1. Go to [Azure Portal](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations**
2. Click **+ New registration**
3. Fill in:
   - **Name**: `Recon Ranger`
   - **Supported account types**: `Accounts in this organizational directory only`
4. Click **Register**

### 2. Configure Redirect URI

1. In your app registration, go to **Authentication** (left sidebar)
2. Click **+ Add a platform**
3. Select **Web**
4. Under **Redirect URIs**, add: `http://127.0.0.1:8000/auth/callback`
5. Check **Access tokens** and **ID tokens** under **Implicit grant and hybrid flows**
6. Click **Configure**

### 3. Create a Client Secret

1. Go to **Certificates & secrets** (left sidebar)
2. Click **+ New client secret**
3. Set **Expires** to `24 months`
4. Click **Add**
5. **Copy the Value** (you won't see it again!) — this is your `AZURE_CLIENT_SECRET`

### 4. Collect Your Credentials

From your app registration **Overview** page, copy:
- **Directory (tenant) ID** → `AZURE_TENANT_ID`
- **Application (client) ID** → `AZURE_CLIENT_ID`
- Client secret value from step 3 → `AZURE_CLIENT_SECRET`

### 5. Generate SESSION_SECRET_KEY

Generate a random 32-byte secret for session encryption:

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Copy the output — this is your `SESSION_SECRET_KEY`.

### 6. Configure Local `.env` File

1. Create a local `.env` file from the template:

```bash
cp .env.example .env
```

2. Fill in your credentials:

```bash
SESSION_SECRET_KEY="<output-from-python-command>"
AZURE_TENANT_ID="<your-tenant-id>"
AZURE_CLIENT_ID="<your-client-id>"
AZURE_CLIENT_SECRET="<your-client-secret>"
```

The app automatically loads `.env` on startup.

## Run Locally (Using uv)

1. Create a virtual environment:

```bash
uv venv
```

2. Activate the virtual environment:

```bash
source .venv/bin/activate
```

3. Install dependencies from lockfile:

```bash
uv sync
```

4. Start the FastAPI app with reload:

```bash
uv run uvicorn app.main:app --reload
```

## Endpoints

- API docs: http://127.0.0.1:8000/api/docs
- OpenAPI schema: http://127.0.0.1:8000/openapi.json