223 lines
11 KiB
Markdown
223 lines
11 KiB
Markdown
# Home-Lab Directory / Inventory — Design Spec
|
||
|
||
Status: **Draft / agreed direction** (no code yet)
|
||
Owner: wmantly
|
||
Last updated: 2026-07-02
|
||
|
||
---
|
||
|
||
## 1. Overview & goals
|
||
|
||
The SSO app manages LDAP groups that gate access across the home lab:
|
||
|
||
- `app_*` — applications (Home Assistant, Gitea, Emby, …)
|
||
- `host_*` — machines (Proxmox nodes, LXC containers, VMs, bare metal)
|
||
|
||
A bootstrap script joins each Debian container to LDAP and grants SSH by group
|
||
membership. Access control works — but the groups are **bare**. In LDAP a group
|
||
(`models/group_ldap.js`) only carries `cn`, `description`, `member`, `owner`.
|
||
There is:
|
||
|
||
- **No metadata** — no URL, IP, FQDN, port, icon, or notes per app/host.
|
||
- **No relationships** — nothing links a **Proxmox host → the container running on
|
||
it → the service the container provides → the LDAP group that gates access**.
|
||
|
||
Consequences:
|
||
|
||
- **Users can't see what they have access to or how to reach it.** Today
|
||
`views/profile.ejs` hardcodes a static "Services" list (Emby, Git, Proxmox…)
|
||
with fixed URLs that are unrelated to the viewer's actual group membership.
|
||
- **CI/CD and service discovery have no source of truth.** Pipelines and tooling
|
||
can't answer "which host runs service X", "what's the IP of `host_ct101`", or
|
||
"which group grants access to this".
|
||
|
||
### Goals
|
||
|
||
1. A machine-readable **discovery API** (build this first) that exposes apps/hosts,
|
||
their metadata, and the infra graph — for CI/CD, dynamic inventory, and dashboards.
|
||
2. Answer, per user, **"what can I access and how do I reach it"** (later dashboard,
|
||
powered by the same API).
|
||
3. Model the **full graph**: Proxmox host ← container/VM ← service/app.
|
||
|
||
### Non-goals (v1)
|
||
|
||
- No write/admin UI yet (management comes in a later phase).
|
||
- No auto-provisioning/sync from Proxmox yet (manual population first).
|
||
- No change to how access is granted — **LDAP remains the access-control truth.**
|
||
|
||
---
|
||
|
||
## 2. Architecture
|
||
|
||
Two stores, one join key.
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ SSO app (this repo) │
|
||
│ │
|
||
Identity │ LDAP ──────────────► access-control truth │
|
||
& access │ (users, app_*/host_* groups, membership) │
|
||
│ │ │
|
||
│ │ join on group cn │
|
||
│ ▼ │
|
||
Inventory │ SQL ──────────────► metadata + graph │
|
||
│ (resources, edges, resource↔group links) │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ /api/discovery/* (read-first API) │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
- **LDAP = access truth.** Who is in `app_homeassistant` / `host_ct101` stays in
|
||
LDAP, unchanged. Read via `Group.list(user.dn)` (`models/group_ldap.js`).
|
||
- **SQL = inventory truth.** Metadata and the host→container→service graph.
|
||
- **Join key = group `cn`.** A SQL resource references the LDAP group(s) that gate
|
||
it by name (`app_*` / `host_*`). "Who can access resource X" is a join:
|
||
LDAP membership ∩ `resource_group`.
|
||
|
||
### Tech choice (to confirm)
|
||
|
||
- **PostgreSQL** recommended (JSONB for flexible metadata, real relational edges).
|
||
**SQLite** is a lighter alternative acceptable for a single-node home lab.
|
||
- Thin query layer: `node-postgres` (`pg`) directly, or `knex` for migrations +
|
||
query building. This is the app's **first SQL dependency** (today it uses LDAP +
|
||
Redis via `model-redis`); the directory is a self-contained module and should not
|
||
disturb the existing stores.
|
||
|
||
---
|
||
|
||
## 3. Data model (full graph)
|
||
|
||
Three tables. Metadata is a JSONB bag so fields can evolve without migrations;
|
||
common query fields can be promoted to columns later.
|
||
|
||
### `resource` — a node in the graph
|
||
| column | type | notes |
|
||
|--------------|-------------|-------|
|
||
| `id` | uuid / pk | |
|
||
| `kind` | enum | `site` \| `host` \| `service` |
|
||
| `name` | text | display name ("Home Assistant", "ct101") |
|
||
| `slug` | text unique | url-safe id used by the API |
|
||
| `description`| text | free text |
|
||
| `metadata` | jsonb | `{ subType, ip, macAddress, address, vmid, port, externalPort, gitRepo, installPath, systemdService, os, kernel, isProduction, isExternalReachable, isPublic }` |
|
||
| `created_at` / `updated_at` | timestamptz | |
|
||
|
||
**Parent Enforcement Rules:**
|
||
- A **Host** MUST have a parent **Site** or **Host**.
|
||
- A **Service** MUST have a parent **Host**.
|
||
- An **OAuth Integration** MUST have a parent **Service**.
|
||
|
||
**LDAP Group Auto-Creation:**
|
||
When a Host or Service is created, the system will automatically create two LDAP groups in the directory (if they do not already exist):
|
||
- `<slug>_access` (for standard user access)
|
||
- `<slug>_admin` (for administrative access)
|
||
Additional groups can still be linked manually.
|
||
|
||
### `resource_edge` — directed relationships (the graph)
|
||
| column | type | notes |
|
||
|--------------|--------|-------|
|
||
| `parent_id` | fk → resource | |
|
||
| `child_id` | fk → resource | |
|
||
| `relation` | enum | `runs_on` \| `hosts` \| `exposes` \| `depends_on` |
|
||
|
||
Represents site←host←service (`hosts`/`runs_on`) and service→service
|
||
(`depends_on`). Directed edges (not a single `parent_id` column) so a node can have
|
||
multiple parents/children and multiple relation types.
|
||
|
||
### `resource_group` — link a resource to the LDAP group(s) that gate it
|
||
| column | type | notes |
|
||
|---------------|--------|-------|
|
||
| `resource_id` | fk → resource | |
|
||
| `group_cn` | text | LDAP group name, `app_*` / `host_*` |
|
||
| `access_level`| enum | `user` \| `admin` \| `owner` |
|
||
|
||
This is the bridge to auth. It lets one resource be gated by several groups
|
||
(e.g. `app_gitea` for users, `host_ct_gitea` for shell/admin).
|
||
|
||
**Naming:** the `app_*` / `host_*` prefix convention is retained in LDAP; in SQL the
|
||
distinction is captured explicitly by `resource.kind` + `resource_group`, so the API
|
||
never has to parse group-name prefixes.
|
||
|
||
### Example
|
||
```
|
||
resource: pve1 (proxmox_node) ── hosts ──▶ ct101 (container) ── exposes ──▶ gitea (service)
|
||
│
|
||
resource_group: gitea ↔ app_gitea (user), ct101 ↔ host_ct101 (user), pve1 ↔ host_pve1 (admin)
|
||
```
|
||
A user in `app_gitea` sees the Gitea service + how to reach it; a user in
|
||
`host_ct101` additionally sees SSH to the container; `host_pve1` sees the node.
|
||
|
||
---
|
||
|
||
## 4. Discovery API (v1 — read-first)
|
||
|
||
JSON. Mounted at `/api/discovery` behind `middleware.auth` (see §5).
|
||
|
||
| method & path | purpose |
|
||
|---------------|---------|
|
||
| `GET /api/discovery/resources?kind=&tag=&group=&parent=` | Filtered list of nodes + metadata. |
|
||
| `GET /api/discovery/resources/:slug` | One node with its edges (parents + children). |
|
||
| `GET /api/discovery/graph[?root=<slug>]` | Whole graph, or the subtree under a root. |
|
||
| `GET /api/discovery/me` | Only the resources the **caller** is entitled to — LDAP membership (`Group.list(user.dn)`) ∩ `resource_group`. Powers the future dashboard and the "what can I access" question. |
|
||
|
||
### CI/CD-friendly output (optional formats, same data)
|
||
- **Ansible dynamic inventory** shape (`?format=ansible`): groups of hosts with
|
||
`ansible_host`/vars pulled from `metadata`.
|
||
- **Dashboard** shape (Homepage/Glance): flat list of services with `href`, `icon`,
|
||
`description`.
|
||
|
||
Write endpoints (POST/PUT/DELETE) are **out of scope for v1**; population is manual
|
||
(SQL seed / migration) until the admin UI phase.
|
||
|
||
---
|
||
|
||
## 5. AuthN / AuthZ
|
||
|
||
- **Interactive users:** existing session auth — `middleware.auth` validating the
|
||
`auth-token` header (an `AuthToken`, `models/token.js`). No change.
|
||
- **CI/CD (machine) access:** scripts and external integrations (like jump hosts) will use the existing `ApiToken` system (Personal Access Tokens) passed in the `Authorization: Bearer sso_...` header. The `ApiToken` inherits the exact LDAP group permissions of the user who created it, seamlessly mapping to existing access controls.
|
||
- **Read visibility (decision to confirm):** either (a) any authenticated user may
|
||
read all resource metadata and only `/me` is filtered, or (b) list endpoints are
|
||
themselves filtered to entitlement. Recommend **(a)** for a home lab — simpler,
|
||
and infra metadata isn't secret — with `/me` as the personalized view.
|
||
- **Management (later):** gate write/admin endpoints behind a new
|
||
`app_sso_directory_admin` LDAP group, mirroring the existing
|
||
`app_sso_oauth_admin` pattern (`routes/oauth_client.js` + `utils/permission.js`).
|
||
|
||
---
|
||
|
||
## 6. Integration points with the existing app
|
||
|
||
- **Replace the hardcoded Services list** in `views/profile.ejs` (lines ~82–126)
|
||
with a render of `GET /api/discovery/me`.
|
||
- **Reuse the group selector** `app.ui.groupSelect` (`public/js/app.js`) for linking
|
||
resources ↔ LDAP groups in the future admin UI — no new group-picker needed.
|
||
- **Join convention:** `resource_group.group_cn` must equal an LDAP group `cn`
|
||
exactly; the discovery layer never invents groups, it only references existing ones.
|
||
- **Reuse `utils/permission.byGroup`** for the admin gate in the management phase.
|
||
|
||
---
|
||
|
||
## 7. Roadmap
|
||
|
||
1. **v1 — Discovery API** (this spec's focus): SQL schema + migrations, read models,
|
||
`/api/discovery/*` endpoints, `ApiToken` for CI/CD.
|
||
2. **v2 — "My Access" dashboard**: swap `profile.ejs`'s static list for `/me`.
|
||
3. **v3 — Admin CRUD UI**: manage resources/edges/group links (reusing `app.ui`
|
||
widgets and the `oauth_clients.ejs` card+modal pattern); gated by
|
||
`app_sso_directory_admin`.
|
||
4. **v4 — Sync from Proxmox** (optional): auto-populate nodes/containers/VMs from the
|
||
Proxmox API so inventory stays current without manual entry.
|
||
|
||
---
|
||
|
||
## 8. Open questions
|
||
|
||
1. **DB engine:** PostgreSQL (recommended) vs SQLite for a single-node lab.
|
||
2. **Population:** manual seed vs Proxmox pull for v1 (spec assumes manual).
|
||
3. **Metadata mirroring:** should any metadata be written back to the LDAP group
|
||
`description` so LDAP-only external consumers see it? **Default: no** — keep LDAP
|
||
for auth, SQL for inventory.
|
||
4. **Read-visibility policy:** confirm option (a) vs (b) in §5.
|
||
5. **Service token scope:** Currently `ApiToken` shares the creator's full permissions. A future enhancement could scope tokens specifically to the Directory API.
|