oauth edit
This commit is contained in:
@@ -0,0 +1,216 @@
|
||||
# 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 | `proxmox_node` \| `container` \| `vm` \| `bare_metal` \| `service` |
|
||||
| `name` | text | display name ("Home Assistant", "ct101") |
|
||||
| `slug` | text unique | url-safe id used by the API |
|
||||
| `description`| text | free text |
|
||||
| `metadata` | jsonb | `{ url, icon, fqdn, ip, port, tags[], … }` |
|
||||
| `created_at` / `updated_at` | timestamptz | |
|
||||
|
||||
### `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 host←container←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:** the app does **not yet** have a long-lived service
|
||||
token — `AuthToken` is session-oriented. **Proposed small addition:** a
|
||||
`ServiceToken` subclass in `models/token.js` (mirrors `AuthToken`/`ImpersonationToken`),
|
||||
long-lived, read-only, passed in the same `auth-token` header. Track as its own
|
||||
task; the discovery API should assume it exists but degrade to normal auth tokens
|
||||
until then.
|
||||
- **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, `ServiceToken` 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:** read-only globally, or per-token resource/kind scoping?
|
||||
Reference in New Issue
Block a user