# 🛡️ HSP Guard

**HSP Guard** is a modern OpenID Connect (OIDC) identity provider and access management system for home labs. It provides secure authentication and granular authorization for all your self-hosted services, combining ease of use with enterprise-level control — without any vendor lock-in.

---

## ✨ Features

- **OIDC Provider**: Central login for your home lab apps
- **Admin UI**: Manage apps, users, roles, permissions, and sessions
- **API Tokens**: Issue access tokens with embedded roles and permissions
- **Flexible Authorization**: Support for roles, permissions, and groups (future)
- **App Registration**: Register OAuth/OIDC clients with custom permissions
- **Automatic Permission Sync**: Optionally fetch app permissions from `/.well-known/guard-configuration`
- **User & Admin Sessions**: See and revoke active user/app sessions
- **Pluggable**: Easily integrate new apps and services
- **Audit Logging**: Track actions for security and troubleshooting (planned)

---

## 🚀 Getting Started

### 1. **Run HSP Guard**

You can run HSP Guard via Docker, Docker Compose, or natively (see below).

### 2. **Register Your First App**

1. **Login as admin**
2. Go to **Apps → Register New App**
3. Enter:
   - **Name** of your app
   - **Redirect URIs** (for OIDC/OAuth callbacks)
   - (Optional) **Permissions** (manual or auto-discovered from the app)
4. Save to receive a `client_id` and `client_secret`
5. Configure your app to use these for OIDC login

### 3. **Assign Permissions & Roles**

- Assign **default roles** to new users automatically (configurable)
- Create custom **roles** to bundle permissions (e.g., `FAMILY_MEMBER`)
- Assign users to roles and/or groups for flexible access control

---

## 🏗️ Concepts

### 🔑 **Permissions**
Fine-grained controls for app features (e.g., `music.play`, `dashboard.edit`).  
Can be manually defined or auto-discovered from an app’s `.well-known/guard-configuration` endpoint.

### 🧩 **Roles**
Named bundles of permissions (e.g., `GUEST`, `FAMILY_MEMBER`, `ADMIN`).  
Assign to users/groups for easier management.

### 👥 **Groups**
(Planned) Logical user collections (e.g., “Family”, “Guests”, “Admins”) for batch management of roles/permissions.

### 👤 **Users**
Each user has a unique profile, roles, and group memberships.

---

## 🔗 OIDC/OAuth Integration

**HSP Guard** is a standard-compliant OIDC Provider. Any app supporting OIDC/OAuth can integrate.

- Register app in admin panel to get `client_id` & `client_secret`
- Configure your app’s OIDC integration (see your app’s docs)
- Token claims include `permissions` and `roles` for easy authorization

#### **Example Token Claims**
```json
{
  "sub": "123456",
  "name": "Alex Example",
  "email": "alex@example.com",
  "roles": ["GUEST"],
  "permissions": ["dashboard.view", "music.play"]
}
```

---

## 📡 **App Permission Discovery**

If your app supports permission discovery:
- Expose `/.well-known/guard-configuration` endpoint listing available permissions
- When registering in HSP Guard, auto-fetch and display for approval

#### **Example guard-configuration JSON**
```json
{
  "permissions": [
    "dashboard.view",
    "dashboard.edit",
    "dashboard.admin"
  ]
}
```

---

## 🔄 **User & Admin Sessions**

- List all active sessions (browser, app, device, timestamp)
- Revoke sessions (logout) from user or admin panel

---

## 📦 **Planned Features & Roadmap**

- [ ] **Group Management** for batch assignments
- [ ] **Audit Logging** of all admin/user actions
- [ ] **Permission Expiry** (time-limited access)
- [ ] **Advanced Web UI** (dark mode, mobile)
- [ ] **External Identity Providers** (login with Google, GitHub, etc.)

---

## 🛠️ **Development**

- See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute!
- Pull requests and issues are welcome.

---

## 📝 **License**

MIT — open source, for the home lab community.

---

## 💬 **Feedback**

Open an [issue](https://github.com/yourusername/hsp-guard/issues) or join the discussion!

---