Add runbooks, backup coverage, inventory, roles from groups, Prometheus metrics and event webhooks

- Runbooks: notes per server/integration, shown next to matching alerts
- Backup coverage page across Proxmox and PBS, with a digest section
- Hardware inventory with warranty, power and running cost
- Authentik group to role mapping with preview and safeguards
- /metrics (bearer token) and signed outgoing event webhooks
- Docs: README, DATABASE, NOTIFICATIONS, ROLES and new API.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-17 20:41:00 +02:00
1 parent c36e2092c5
commit c17e9aa140
55 files changed
+7177 -27

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
/**
* Roles from the groups the identity provider says a person is in. An administrator names the groups that mean "admin" and "operator";
* at each sign-in the person's role follows from them. Kept free of the database and the sign-in flow so every rule can be tested exactly.
*/
import type { UserRole } from "../db/schema.js";
export interface SignInRoleSettings {
/** Roles follow the groups. Off, roles are set by hand on the Users page, as they always were. */
roleFromGroups: boolean;
/** The name of the claim that carries the groups ("groups" in Authentik). */
groupsClaim: string;
adminGroups: string[];
operatorGroups: string[];
/** What someone in none of the named groups gets: viewer, or whatever they already have. */
otherwise: "viewer" | "keep";
}
const MAX_GROUPS = 200;
const MAX_GROUP_LENGTH = 200;
/**
* The groups named in a claim, from every place the provider might have put it (the ID token, the user-info answer). Returns null when
* none of them has the claim at all — which is "we weren't told", not "in no groups", and must never be mistaken for it.
*/
export function extractGroups(sources: Record<string, unknown>[], claim: string): string[] | null {
let found = false;
const groups = new Set<string>();
for (const source of sources) {
if (!source || !Object.prototype.hasOwnProperty.call(source, claim)) continue;
const value = source[claim];
if (value === null || value === undefined) continue;
found = true;
const list = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
for (const g of list) {
if (typeof g !== "string") continue;
const name = g.trim().slice(0, MAX_GROUP_LENGTH);
if (name) groups.add(name);
}
}
return found ? [...groups].slice(0, MAX_GROUPS) : null;
}
const norm = (s: string) => s.trim().toLowerCase();
/** The role these groups give: admin if any is an admin group, else operator if any is an operator group, else what `otherwise` says. */
export function roleFromGroups(settings: SignInRoleSettings, groups: string[], current: UserRole): UserRole {
const have = new Set(groups.map(norm));
if (settings.adminGroups.some((g) => have.has(norm(g)))) return "admin";
if (settings.operatorGroups.some((g) => have.has(norm(g)))) return "operator";
return settings.otherwise === "keep" ? current : "viewer";
}
+23 -1
View File
@@ -3,6 +3,8 @@ import * as client from "openid-client";
import { eq } from "drizzle-orm";
import { getOidcConfig } from "./oidc.js";
import { upsertUserFromLogin } from "./users.js";
import { extractGroups } from "./groups.js";
import { getSettings } from "../services/settingsStore.js";
import { env } from "../env.js";
import { db } from "../db/client.js";
import { users } from "../db/schema.js";
@@ -110,15 +112,35 @@ authRouter.get("/callback", signInLimiter, async (req, res, next) => {
let email: string | undefined = typeof claims.email === "string" ? claims.email : undefined;
let name: string | undefined = typeof claims.name === "string" ? claims.name : undefined;
const claimSources: Record<string, unknown>[] = [claims as Record<string, unknown>];
try {
const userinfo = await client.fetchUserInfo(config, tokens.access_token, claims.sub);
email = userinfo.email ?? email;
name = userinfo.name ?? userinfo.preferred_username ?? name;
claimSources.push(userinfo as Record<string, unknown>);
} catch {
// fall back to ID token claims already captured above
}
const { user, created } = await upsertUserFromLogin({ sub: claims.sub, email, name });
// The groups, from wherever the provider put them. Read (and kept for the Users page) whether or not roles follow them, so the
// names can be seen before they are relied on.
const { signIn } = await getSettings();
const groups = extractGroups(claimSources, signIn.groupsClaim);
if (signIn.roleFromGroups && groups === null) {
console.warn(`[auth] roles follow groups, but the sign-in carried no "${signIn.groupsClaim}" claim — roles left as they are`);
}
const { user, created, roleChange } = await upsertUserFromLogin({ sub: claims.sub, email, name, groups });
if (roleChange) {
await recordAudit({
actor: user,
category: "user",
action: roleChange.blocked ? "role_from_groups_blocked" : "role_from_groups",
targetType: "user",
targetId: user.id,
detail: { from: roleChange.from, to: roleChange.to, groups: roleChange.groups, ...(roleChange.blocked ? { reason: "the only administrator" } : {}) },
});
}
// Access to the app is itself something worth being able to look back on: who got an account (and the very first
// one becomes admin), and every sign-in with where it came from.
+44 -6
View File
@@ -1,35 +1,72 @@
import { eq } from "drizzle-orm";
import { and, eq, ne } from "drizzle-orm";
import { db } from "../db/client.js";
import { users } from "../db/schema.js";
import { users, type UserRole } from "../db/schema.js";
import { getSettings } from "../services/settingsStore.js";
import { roleFromGroups } from "./groups.js";
export interface RoleChange {
from: UserRole;
to: UserRole;
groups: string[];
/** The group rules would have taken the last administrator's rights away, so the role was left alone. */
blocked?: boolean;
}
/**
* Called on every successful OIDC login. The very first user ever to sign in
* becomes admin; everyone after defaults to viewer until an admin promotes
* them from the Users page.
* them from the Users page — or, when roles follow groups (Settings → Sign-in),
* until the groups the identity provider reports decide it.
*
* `groups` is what the provider said, or null/undefined when it said nothing about groups at all. That is not "in no groups": with no
* information the role is left exactly as it is, so a wrong claim name can't quietly demote everyone. And the last administrator is
* never demoted by a group rule, whatever the groups say.
*/
export async function upsertUserFromLogin(params: {
sub: string;
email?: string;
name?: string;
}): Promise<{ user: typeof users.$inferSelect; created: boolean }> {
groups?: string[] | null;
}): Promise<{ user: typeof users.$inferSelect; created: boolean; roleChange?: RoleChange }> {
const [existing] = await db.select().from(users).where(eq(users.oidcSub, params.sub)).limit(1);
const now = new Date().toISOString();
const { signIn } = await getSettings();
const mapping = signIn.roleFromGroups && params.groups !== null && params.groups !== undefined;
const groupsJson = params.groups ? JSON.stringify(params.groups) : undefined;
if (existing) {
let role = existing.role;
let roleChange: RoleChange | undefined;
if (mapping) {
const wanted = roleFromGroups(signIn, params.groups!, existing.role);
if (wanted !== existing.role) {
const demotesAdmin = existing.role === "admin" && wanted !== "admin";
const otherAdmin = demotesAdmin ? await db.select({ id: users.id }).from(users).where(and(eq(users.role, "admin"), ne(users.id, existing.id))).limit(1) : [];
if (demotesAdmin && otherAdmin.length === 0) {
roleChange = { from: existing.role, to: wanted, groups: params.groups!, blocked: true };
} else {
role = wanted;
roleChange = { from: existing.role, to: wanted, groups: params.groups! };
}
}
}
const [updated] = await db
.update(users)
.set({
email: params.email ?? existing.email,
name: params.name ?? existing.name,
lastLoginAt: now,
role,
...(groupsJson !== undefined ? { groups: groupsJson } : {}),
})
.where(eq(users.id, existing.id))
.returning();
return { user: updated, created: false };
return { user: updated, created: false, roleChange };
}
const anyUser = await db.select({ id: users.id }).from(users).limit(1);
const role = anyUser.length === 0 ? ("admin" as const) : ("viewer" as const);
// The first person ever is the administrator, so there is always one; after that the groups decide, when they are used, else viewer.
const role: UserRole = anyUser.length === 0 ? "admin" : mapping ? roleFromGroups({ ...signIn, otherwise: "viewer" }, params.groups!, "viewer") : "viewer";
const [created] = await db
.insert(users)
@@ -39,6 +76,7 @@ export async function upsertUserFromLogin(params: {
name: params.name,
role,
lastLoginAt: now,
...(groupsJson !== undefined ? { groups: groupsJson } : {}),
})
.returning();
return { user: created, created: true };