# 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.